Ops

CONTRIBUTING.md

@@ -1,12 +1,15 @@
 # Contributing to Forui
 
-Before submitting a Pull Request (PR), please create an issue to discuss the proposed changes. This helps to:
+Before starting work on a pull request, please check if a similar issue already exists, or create one to discuss the 
+proposed changes.
+
+This helps to:
 
 * Ensure that the proposed changes align with the project's goals and direction.
 * Avoid duplicate efforts by informing other contributors about ongoing work.
 * Provide a platform for maintainers and the community to offer feedback and suggestions.
 
-Creating an issue first can save time and effort by identifying potential problems early in the development process.
+Doing so saves time and effort by identifying potential problems early in the development process.
 
 ## Design Guidelines
 

docs/pages/docs/calendar.mdx

@@ -4,8 +4,11 @@ import { Widget } from "../../components/widget";
 # Calendar
 A date field component that allows users to enter and edit date.
 
-The calendar pages are designed to be navigable through swipe gestures on mobile platforms, allowing left and right swipes
-to transition between pages.
+The calendar pages are designed to be navigable through swipe gestures on mobile platforms, allowing left and right
+swipes to transition between pages.
+
+A [FCalendarController](https://pub.dev/documentation/forui/latest/forui.widgets/FCalendarController-class.html) is used
+to customize the date selection behavior.
 
 <Tabs items={['Preview', 'Code']}>
     <Tabs.Tab>
@@ -14,7 +17,7 @@ to transition between pages.
     <Tabs.Tab>
         ```dart
         FCalendar(
-          controller: FCalendarSingleRangeController(),
+          controller: FCalendarValueController(initialSelection: selected),
           start: DateTime.utc(2000),
           end: DateTime.utc(2030),
         );
@@ -28,13 +31,16 @@ to transition between pages.
 
 ```dart
 FCalendar(
-  controller: FCalendarSingleRangeController(),
+  controller: FCalendarValueController(
+    initialSelection: DateTime.utc(2024, 9, 13),
+    canSelect: (date) => true,
+  ),
   start: DateTime.utc(2024),
   end: DateTime.utc(2030),
   today: DateTime.utc(2024, 7, 14),
-  initalType = FCalendarPickerType.yearMonth,
+  initialType = FCalendarPickerType.yearMonth,
   initialDate = DateTime.utc(2024, 9, 12),
-  enabled: (date) => allowed.contains(date),
+  enabled:
   onMonthChange: (date) => print(date),
   onPress: (date) => print(date),
   onLongPress: (date) => print(date),
@@ -58,34 +64,59 @@ FCalendar(
     </Tabs.Tab>
 </Tabs>
 
-### Multiple Dates
+### Multiple Dates with Initial Selections
 <Tabs items={['Preview', 'Code']}>
     <Tabs.Tab>
         <Widget name='calendar' variant='multi-value' query={{}} height={500}/>
     </Tabs.Tab>
     <Tabs.Tab>
         ```dart
         FCalendar(
-          controller: FCalendarMultiValueController(),
+          controller: FCalendarMultiValueController(
+            initialSelections: {DateTime.utc(2024, 7, 17), DateTime.utc(2024, 7, 20)},
+          ),
           start: DateTime.utc(2000),
+          today: DateTime.utc(2024, 7, 15),
           end: DateTime.utc(2030),
         );
         ```
     </Tabs.Tab>
 </Tabs>
 
-### Single Range
+### Unselectable Dates
+<Tabs items={['Preview', 'Code']}>
+    <Tabs.Tab>
+        <Widget name='calendar' variant='unselectable' query={{}} height={500}/>
+    </Tabs.Tab>
+      ```dart
+      FCalendar(
+        controller: FCalendarMultiValueController(
+          initialSelections: {DateTime.utc(2024, 7, 17), DateTime.utc(2024, 7, 20)},
+          canSelect: (date) => !{DateTime.utc(2024, 7, 18), DateTime.utc(2024, 7, 19)}.contains(date),
+        ),
+        start: DateTime.utc(2000),
+        today: DateTime.utc(2024, 7, 15),
+        end: DateTime.utc(2030),
+      );
+      ```
+    </Tabs.Tab>
+</Tabs>
+
+### Range Selection with Initial Range
 <Tabs items={['Preview', 'Code']}>
     <Tabs.Tab>
-        <Widget name='calendar' variant='single-range' query={{}} height={500}/>
+        <Widget name='calendar' variant='range' query={{}} height={500}/>
     </Tabs.Tab>
     <Tabs.Tab>
         ```dart
         FCalendar(
-          controller: FCalendarSingleRangeController(),
+          controller: FCalendarRangeController(
+            initialSelection: (DateTime.utc(2024, 7, 17), DateTime.utc(2024, 7, 20)),
+          ),
           start: DateTime.utc(2000),
+          today: DateTime.utc(2024, 7, 15),
           end: DateTime.utc(2030),
-        )
+        );
         ```
     </Tabs.Tab>
 </Tabs>

forui/CHANGELOG.md

@@ -2,18 +2,28 @@
 
 ### Additions
 * Add `FAvatar`
-* **Breaking** Add `FCalendarEntryStyle.focusedBorderColor`
+* **Breaking:** Add `FCalendarEntryStyle.focusedBorderColor`. This only affects users that customized `FCalendarEntryStyle`.
 * Add `FResizable`
 
 ### Changes
 * Change number of years displayed per page in `FCalendar` from 12 to 15.
-* **Breaking** Rename `FCalendarEntryStyle.focusedBackgroundColor` to `FCalendarEntryStyle.hoveredBackgroundColor`.
-* **Breaking** Rename `FCalendarEntryStyle.focusedTextStyle` to `FCalendarEntryStyle.hoveredTextStyle`.
+* **Breaking:** Move `FCalendar.enabled` to `FCalendarController.canSelect(...)`.
+
+* **Breaking:** Rename `FCalendarEntryStyle.focusedBackgroundColor` to `FCalendarEntryStyle.hoveredBackgroundColor`.
+  This only affects users that customized `FCalendarEntryStyle`.
+
+* **Breaking:** Rename `FCalendarEntryStyle.focusedTextStyle` to `FCalendarEntryStyle.hoveredTextStyle`.
+  This only affects users that customized `FCalendarEntryStyle`.
+
+* **Breaking:** Rename `FCalendarSingleValueController` to `FCalendarValueController`.
+
+* **Breaking:** Rename `FCalendarSingleRangeController` to `FCalendarRangeController`.
 
 ### Fixes
 * Fix `FCalendar` dates not being toggleable using `Enter` key.
 * Fix `FCalendar` dates sometimes not being navigable using arrow keys.
 
+
 ## 0.3.0
 
 ### Additions

forui/example/lib/example.dart

@@ -17,12 +17,9 @@ class _ExampleState extends State<Example> {
   @override
   Widget build(BuildContext context) => Column(
     children: [
-      // Material(
-      //   child: CalendarDatePicker(initialDate: DateTime.now(), firstDate: DateTime.utc(2000),
-      //     lastDate: DateTime.utc(2030), onDateChanged: (DateTime value) {  },),
-      // ),
       FCalendar(
-        controller: FCalendarSingleValueController(),
+        controller: FCalendarValueController(),
+        initialType: FCalendarPickerType.yearMonth,
         start: DateTime.utc(2000),
         end: DateTime.utc(2030),
       ),

forui/lib/src/widgets/calendar/calendar.dart

@@ -21,12 +21,14 @@ export 'year_month_picker.dart' show FCalendarYearMonthPickerStyle;
 /// The calendar pages are designed to be navigable through swipe gestures on mobile Android, iOS & iPadOS, allowing
 /// left and right swipes to transition between pages.
 ///
+/// All [DateTime]s are in UTC timezone. A [FCalendarController] is used to customize the date selection behavior.
+/// [DateTime]s outside [start] and [end] are unselectable regardless of the [FCalendarController] used.
+///
 /// See:
 /// * https://forui.dev/docs/calendar for working examples.
-/// * [FCalendarDayStyle] for customizing a card's appearance.
+/// *  for customizing a calendar's date selection behavior.
+/// * [FCalendarDayStyle] for customizing a calendar's appearance.
 class FCalendar extends StatelessWidget {
-  static bool _true(DateTime _) => true;
-
   /// The style. Defaults to [FThemeData.calendarStyle].
   final FCalendarStyle? style;
 
@@ -48,11 +50,6 @@ class FCalendar extends StatelessWidget {
   /// The current date. It is truncated to the nearest date. Defaults to the [DateTime.now].
   final DateTime today;
 
-  /// A predicate that determines if a date can be selected. It may be called more than once for a single date.
-  ///
-  /// Defaults to returning true for all dates.
-  final Predicate<DateTime> enabled;
-
   /// A callback for when the displayed month changes.
   final ValueChanged<DateTime>? onMonthChange;
 
@@ -61,29 +58,29 @@ class FCalendar extends StatelessWidget {
 
   /// A callback for when a date in a [FCalendarPickerType.day] picker is long pressed.
   final ValueChanged<DateTime>? onLongPress;
+
   final ValueNotifier<FCalendarPickerType> _type;
   final ValueNotifier<LocalDate> _month;
 
   /// Creates a [FCalendar].
   ///
-  /// [initialDate] defaults to [today]. It is truncated to the nearest date.
+  /// [initialMonth] defaults to [today]. It is truncated to the nearest date.
   FCalendar({
     required this.controller,
     required this.start,
     required this.end,
     this.style,
-    this.enabled = _true,
     this.onMonthChange,
     this.onPress,
     this.onLongPress,
     FCalendarPickerType initialType = FCalendarPickerType.day,
     DateTime? today,
-    DateTime? initialDate,
+    DateTime? initialMonth,
     super.key,
   })  : assert(start.toLocalDate() < end.toLocalDate(), 'end date must be greater than start date'),
         today = today ?? DateTime.now(),
         _type = ValueNotifier(initialType),
-        _month = ValueNotifier((initialDate ?? today ?? DateTime.now()).toLocalDate().truncate(to: DateUnit.months));
+        _month = ValueNotifier((initialMonth ?? today ?? DateTime.now()).toLocalDate().truncate(to: DateUnit.months));
 
   @override
   Widget build(BuildContext context) {
@@ -115,15 +112,15 @@ class FCalendar extends StatelessWidget {
                       end: end.toLocalDate(),
                       today: today.toLocalDate(),
                       initial: _month.value,
-                      enabled: (date) => enabled(date.toNative()),
+                      selectable: (date) => controller.canSelect(date.toNative()),
                       selected: (date) => controller.contains(date.toNative()),
                       onMonthChange: (date) {
                         _month.value = date;
                         onMonthChange?.call(date.toNative());
                       },
                       onPress: (date) {
                         final native = date.toNative();
-                        controller.onPress(native);
+                        controller.select(native);
                         onPress?.call(native);
                       },
                       onLongPress: (date) => onLongPress?.call(date.toNative()),
@@ -157,7 +154,6 @@ class FCalendar extends StatelessWidget {
       ..add(DiagnosticsProperty('start', start))
       ..add(DiagnosticsProperty('end', end))
       ..add(DiagnosticsProperty('today', today))
-      ..add(DiagnosticsProperty('enabled', enabled))
       ..add(DiagnosticsProperty('onMonthChange', onMonthChange))
       ..add(DiagnosticsProperty('onPress', onPress))
       ..add(DiagnosticsProperty('onLongPress', onLongPress));