Differentiate between focused and hovered states on FTappable & fix misc. calendar bugs

CONTRIBUTING.md

@@ -1,5 +1,16 @@
 # Contributing to Forui
 
+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.
+
+Doing so saves time and effort by identifying potential problems early in the development process.
+
 ## Design Guidelines
 
 ### Be agnostic about state management

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,15 @@ to transition between pages.
 
 ```dart
 FCalendar(
-  controller: FCalendarSingleRangeController(),
+  controller: FCalendarValueController(
+    initialSelection: DateTime.utc(2024, 9, 13),
+    selectable: (date) => allowedDates.contains(date),
+  ),
   start: DateTime.utc(2024),
   end: DateTime.utc(2030),
   today: DateTime.utc(2024, 7, 14),
-  initalType = FCalendarPickerType.yearMonth,
-  initialDate = DateTime.utc(2024, 9, 12),
-  enabled: (date) => allowed.contains(date),
+  initialType = FCalendarPickerType.yearMonth,
+  initialMonth = DateTime.utc(2024, 9),
   onMonthChange: (date) => print(date),
   onPress: (date) => print(date),
   onLongPress: (date) => print(date),
@@ -58,34 +63,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)},
+          selectable: (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,8 +2,30 @@
 
 ### Additions
 * Add `FAvatar`
+* **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:** Move `FCalendar.enabled` to `FCalendarController.canSelect(...)`.
+
+* **Breaking:** Rename `FCalendarController.contains(...)` to `FCalendarController.selected(...)`.
+* **Breaking:** Rename `FCalendarController.onPress(...)` to `FCalendarController.select(...)`.
+
+* **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
 
@@ -25,16 +47,19 @@
 ### Fixes
 * Fix broken images in README.md (yet again).
 
+
 ## 0.2.0+2
 
 ### Fixes
 * Fix broken images in README.md.
 
+
 ## 0.2.0+1
 
 ### Fixes
 * Fix broken images in README.md.
 
+
 ## 0.2.0
 
 ### Additions
@@ -58,6 +83,7 @@
 * **Breaking** `FButton.prefixIcon` and `FButton.suffixIcon` have been renamed to `FButton.prefix` and `FButton.suffix`.
 * Fix padding inconsistencies in `FCard` and `FDialog`.
 
+
 ## 0.1.0
 
 * Initial release! 🚀

forui/example/lib/example.dart

@@ -1,5 +1,7 @@
 import 'package:flutter/material.dart';
 
+import 'package:forui/forui.dart';
+
 class Example extends StatefulWidget {
   const Example({super.key});
 
@@ -14,5 +16,14 @@ class _ExampleState extends State<Example> {
   }
 
   @override
-  Widget build(BuildContext context) => const Placeholder();
+  Widget build(BuildContext context) => Column(
+        children: [
+          FCalendar(
+            controller: FCalendarValueController(),
+            initialType: FCalendarPickerType.yearMonth,
+            start: DateTime.utc(2000),
+            end: DateTime.utc(2030),
+          ),
+        ],
+      );
 }

forui/example/lib/main.dart

@@ -32,7 +32,7 @@ class _ApplicationState extends State<Application> {
                 ),
               ],
             ),
-            content: const Example(),
+            content: child!,
             footer: FBottomNavigationBar(
               index: index,
               onChange: (index) => setState(() => this.index = index),

forui/lib/src/foundation/tappable.dart

@@ -1,11 +1,16 @@
 import 'package:flutter/foundation.dart';
+import 'package:flutter/services.dart';
 import 'package:flutter/widgets.dart';
 
 import 'package:meta/meta.dart';
 
+// TODO: Remove redundant comment when flutter fixes its lint issue.
+///
+@internal
+typedef FTappableState = ({bool focused, bool hovered});
+
 @internal
 class FTappable extends StatefulWidget {
-  final bool enabled;
   final String? semanticLabel;
   final bool selected;
   final bool excludeSemantics;
@@ -14,7 +19,7 @@ class FTappable extends StatefulWidget {
   final ValueChanged<bool>? onFocusChange;
   final VoidCallback? onPress;
   final VoidCallback? onLongPress;
-  final ValueWidgetBuilder<bool> builder;
+  final ValueWidgetBuilder<FTappableState> builder;
   final Widget? child;
 
   factory FTappable.animated({
@@ -26,7 +31,7 @@ class FTappable extends StatefulWidget {
     ValueChanged<bool>? onFocusChange,
     VoidCallback? onPress,
     VoidCallback? onLongPress,
-    ValueWidgetBuilder<bool>? builder,
+    ValueWidgetBuilder<FTappableState>? builder,
     Widget? child,
     Key? key,
   }) = _AnimatedTappable;
@@ -40,12 +45,13 @@ class FTappable extends StatefulWidget {
     this.onFocusChange,
     this.onPress,
     this.onLongPress,
-    ValueWidgetBuilder<bool>? builder,
+    ValueWidgetBuilder<FTappableState>? builder,
     this.child,
     super.key,
   })  : assert(builder != null || child != null, 'Either builder or child must be provided.'),
-        builder = builder ?? ((_, __, child) => child!),
-        enabled = onPress != null || onLongPress != null;
+        builder = builder ?? ((_, __, child) => child!);
+
+  bool get enabled => onPress != null || onLongPress != null;
 
   @override
   State<FTappable> createState() => _FTappableState();
@@ -80,33 +86,51 @@ class _FTappableState extends State<FTappable> with SingleTickerProviderStateMix
   bool _hovered = false;
 
   @override
-  Widget build(BuildContext context) => Semantics(
-        enabled: widget.enabled,
-        label: widget.semanticLabel,
-        container: true,
-        button: true,
-        selected: widget.selected,
-        excludeSemantics: widget.excludeSemantics,
-        child: Focus(
-          autofocus: widget.autofocus,
-          focusNode: widget.focusNode,
-          onFocusChange: (focused) {
-            setState(() => _focused = focused);
-            widget.onFocusChange?.call(focused);
-          },
-          child: MouseRegion(
-            cursor: widget.enabled ? SystemMouseCursors.click : MouseCursor.defer,
-            onEnter: (_) => setState(() => _hovered = true),
-            onExit: (_) => setState(() => _hovered = false),
-            child: _child,
-          ),
+  Widget build(BuildContext context) {
+    final tappable = Semantics(
+      enabled: widget.enabled,
+      label: widget.semanticLabel,
+      container: true,
+      button: true,
+      selected: widget.selected,
+      excludeSemantics: widget.excludeSemantics,
+      child: Focus(
+        autofocus: widget.autofocus,
+        focusNode: widget.focusNode,
+        onFocusChange: (focused) {
+          setState(() => _focused = focused);
+          widget.onFocusChange?.call(focused);
+        },
+        child: MouseRegion(
+          cursor: widget.enabled ? SystemMouseCursors.click : MouseCursor.defer,
+          onEnter: (_) => setState(() => _hovered = true),
+          onExit: (_) => setState(() => _hovered = false),
+          child: _child,
         ),
-      );
+      ),
+    );
+
+    if (widget.onPress == null) {
+      return tappable;
+    }
+
+    return Shortcuts(
+      shortcuts: const {
+        SingleActivator(LogicalKeyboardKey.enter): ActivateIntent(),
+      },
+      child: Actions(
+        actions: {
+          ActivateIntent: CallbackAction<ActivateIntent>(onInvoke: (_) => widget.onPress!()),
+        },
+        child: tappable,
+      ),
+    );
+  }
 
   Widget get _child => GestureDetector(
         onTap: widget.onPress,
         onLongPress: widget.onLongPress,
-        child: widget.builder(context, _focused || _hovered, widget.child),
+        child: widget.builder(context, (focused: _focused, hovered: _hovered), widget.child),
       );
 }
 
@@ -156,7 +180,7 @@ class _AnimatedTappableState extends _FTappableState {
                   _controller.forward();
                 },
           onLongPress: widget.onLongPress,
-          child: widget.builder(context, _focused || _hovered, widget.child),
+          child: widget.builder(context, (focused: _focused, hovered: _hovered), widget.child),
         ),
       );