kasy-cli 1.19.1 → 1.20.0

package/templates/firebase/lib/core/widgets/kasy_hover.dart

@@ -7,18 +7,33 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:kasy_kit/core/haptics/haptic_feedback_notifier.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
 
-/// Universal hover/press wrapper — works on any widget shape.
+/// Universal hover/press wrapper — works on any widget shape, any platform.
 ///
-/// Native: animated background fill on press + haptic (no Material ripple).
-/// The pressed state lasts at least [_kMinPressDuration] so it is visible
-/// even on quick taps.
+/// **Press feedback:** animated background fill + optional haptic. No Material
+/// ripple. The pressed state persists for at least [_kMinPressDuration] so
+/// it is always visible, even on quick taps.
 ///
-/// Web: pointer cursor + subtle background on hover, slightly darker on press.
+/// **Hover feedback:** subtle overlay on pointer-capable devices (web,
+/// desktop, trackpad). Has no visible effect on touch-only devices.
+///
+/// **Cursor:** [SystemMouseCursors.click] is set automatically on all
+/// platforms that support pointer input.
+///
+/// ### Customising colours
+///
+/// - [pressColor] — tint base for the press overlay (defaults to
+///   `onSurface`). Pass the surface accent colour (e.g. `primary`) to avoid
+///   a mismatched gray cast on tinted backgrounds.
+///
+/// - [hoverColor] — exact solid background colour shown while the pointer is
+///   over the widget. When set, **replaces** the default semi-transparent
+///   overlay with a solid fill. Use this on navigation items where hover and
+///   selected states must look identical (same bg, bolder text/icon in the
+///   child widget signals selection). When null, falls back to a subtle
+///   [pressColor]-tinted overlay.
 ///
 /// Contrast with [KasyPressableDepth]: this component uses a background fill
-/// while [KasyPressableDepth] uses a scale animation. Use this one for
-/// surfaces that already have their own shape (list rows, cards, menu items,
-/// custom buttons); use [KasyPressableDepth] when you want a "push-in" feel.
+/// while [KasyPressableDepth] uses a scale/depth animation.
 class KasyHover extends ConsumerStatefulWidget {
   const KasyHover({
     super.key,
@@ -29,6 +44,7 @@ class KasyHover extends ConsumerStatefulWidget {
     this.margin,
     this.semanticLabel,
     this.hapticEnabled = true,
+    this.hoverColor,
     this.pressColor,
   });
 
@@ -51,15 +67,24 @@ class KasyHover extends ConsumerStatefulWidget {
   /// Haptic on tap (automatically ignored on web).
   final bool hapticEnabled;
 
-  /// Tint color for the hover/press overlay.
+  /// Exact background colour used while the pointer hovers over the widget.
+  ///
+  /// When non-null, this solid colour replaces the default semi-transparent
+  /// overlay during hover. Ideal for navigation items: pass the same colour
+  /// used for the selected state so hover and active look identical — the
+  /// child widget is responsible for rendering the selected indicator (e.g.
+  /// bolder text, accent icon colour).
+  ///
+  /// When null, a subtle [pressColor]-tinted overlay is used instead.
+  final Color? hoverColor;
+
+  /// Tint base for the press overlay.
   ///
   /// When null, falls back to [ColorScheme.onSurface] — a neutral dark/light
   /// overlay suited for plain surfaces.
   ///
-  /// Pass the surface's accent color (e.g. [KasyColors.primary]) when the
-  /// background is already tinted so the feedback stays on-palette and avoids
-  /// a mismatched gray cast (e.g. a primary-tinted button should deepen with
-  /// primary, not darken with neutral gray).
+  /// Pass the surface's accent colour (e.g. [KasyColors.primary]) when the
+  /// background is already tinted so the feedback stays on-palette.
   final Color? pressColor;
 
   @override
@@ -85,7 +110,21 @@ class _KasyHoverState extends ConsumerState<KasyHover> {
     final bool isDark = Theme.of(context).brightness == Brightness.dark;
     final Color base = widget.pressColor ?? context.colors.onSurface;
     if (_pressed) return base.withValues(alpha: isDark ? 0.04 : 0.10);
-    if (_hovered) return base.withValues(alpha: isDark ? 0.02 : 0.06);
+    if (_hovered) {
+      // Solid hover colour — used for nav items where hover must exactly
+      // match the selected background.
+      if (widget.hoverColor != null) return widget.hoverColor!;
+      return base.withValues(alpha: isDark ? 0.02 : 0.06);
+    }
+    // IMPORTANT: when hoverColor is set, the resting state must be the same
+    // colour at alpha=0 (not Colors.transparent = 0x00000000 black).
+    // AnimatedContainer lerps between the two values — lerping from black-
+    // transparent to a light solid colour passes through dark intermediates,
+    // causing a visible flash. Lerping from the same hue at alpha=0 to
+    // alpha=1 only changes opacity → no dark artefact.
+    if (widget.hoverColor != null) {
+      return widget.hoverColor!.withValues(alpha: 0);
+    }
     return Colors.transparent;
   }
 
@@ -136,19 +175,21 @@ class _KasyHoverState extends ConsumerState<KasyHover> {
       child: content,
     );
 
-    if (kIsWeb) {
-      interactive = MouseRegion(
-        cursor: SystemMouseCursors.click,
-        onEnter: (_) => setState(() => _hovered = true),
-        onExit: (_) {
-          setState(() {
-            _hovered = false;
-            _pressed = false;
-          });
-        },
-        child: interactive,
-      );
-    }
+    // MouseRegion is active on all platforms:
+    // - Web / desktop / trackpad: fires onEnter/onExit for real hover effects.
+    // - Touch-only (iOS/Android): pointer events never fire, zero overhead.
+    // The click cursor is also set universally so desktop feels native.
+    interactive = MouseRegion(
+      cursor: SystemMouseCursors.click,
+      onEnter: (_) => setState(() => _hovered = true),
+      onExit: (_) {
+        setState(() {
+          _hovered = false;
+          _pressed = false;
+        });
+      },
+      child: interactive,
+    );
 
     if (widget.semanticLabel != null) {
       interactive = Semantics(

package/templates/firebase/lib/features/home/home_components_page.dart

@@ -189,6 +189,7 @@ const Set<String> _kReadyComponents = <String>{
   'TextArea',
   'TextField',
   'Sidebar',
+  'Sidebar Pro',
   'Skeleton',
   'SwipeAction',
   'TextFieldOTP',
@@ -211,6 +212,7 @@ const Set<String> _kWebReadyComponents = <String>{
   'Dialog',
   'Hover',
   'Sidebar',
+  'Sidebar Pro',
   'Skeleton',
   'SwipeAction',
   'TextArea',
@@ -241,6 +243,7 @@ const List<_CatalogRow> _kCatalog = [
   _CatalogRow('Dialog'),
   _CatalogRow('Hover'),
   _CatalogRow('Sidebar'),
+  _CatalogRow('Sidebar Pro'),
   _CatalogRow('Skeleton'),
   _CatalogRow('SwipeAction'),
   _CatalogRow('TextArea'),

package/templates/firebase/lib/features/home/home_components_preview_registry.dart

@@ -1,7 +1,9 @@
 import 'package:bart/bart/bart_model.dart';
+import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:kasy_kit/components/components.dart';
+import 'package:kasy_kit/components/kasy_sidebar_pro.dart';
 import 'package:kasy_kit/core/haptics/kasy_haptics.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
 import 'package:kasy_kit/core/widgets/kasy_hover.dart';
@@ -243,10 +245,6 @@ ComponentPreviewDefinition? getComponentPreviewDefinition(
             label: 'Range selection',
             builder: _buildDatePickerRange,
           ),
-          ComponentPreviewVariant(
-            label: 'Multi-month',
-            builder: _buildDatePickerMultiMonth,
-          ),
           ComponentPreviewVariant(
             label: 'Date formats',
             builder: _buildDatePickerFormats,
@@ -259,6 +257,13 @@ ComponentPreviewDefinition? getComponentPreviewDefinition(
             label: 'Field states',
             builder: _buildDatePickerFieldStates,
           ),
+          // Multi-month last — it's a desktop-only opt-in layout and the
+          // preview itself falls back to an explainer card on mobile, so
+          // keeping it at the end avoids burying the main use cases.
+          ComponentPreviewVariant(
+            label: 'Multi-month',
+            builder: _buildDatePickerMultiMonth,
+          ),
         ],
       );
     case 'Dialog':
@@ -512,6 +517,20 @@ ComponentPreviewDefinition? getComponentPreviewDefinition(
           ),
         ],
       );
+    case 'Sidebar Pro':
+      return const ComponentPreviewDefinition(
+        title: 'Sidebar Pro',
+        variants: [
+          ComponentPreviewVariant(
+            label: 'Expanded',
+            builder: _buildSidebarProExpanded,
+          ),
+          ComponentPreviewVariant(
+            label: 'Collapsed',
+            builder: _buildSidebarProCollapsed,
+          ),
+        ],
+      );
     case 'Skeleton':
       return const ComponentPreviewDefinition(
         title: 'Skeleton',
@@ -684,6 +703,91 @@ class _SidebarPreviewState extends State<_SidebarPreview> {
 }
 
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Sidebar Pro — interactive preview
+// ─────────────────────────────────────────────────────────────────────────────
+
+Widget _buildSidebarProExpanded(BuildContext context) =>
+    const _SidebarProPreview(initiallyCollapsed: false);
+
+Widget _buildSidebarProCollapsed(BuildContext context) =>
+    const _SidebarProPreview(initiallyCollapsed: true);
+
+class _SidebarProPreview extends StatelessWidget {
+  const _SidebarProPreview({required this.initiallyCollapsed});
+
+  final bool initiallyCollapsed;
+
+  void _open(BuildContext context, {required bool fromEnd}) {
+    showGeneralDialog<void>(
+      context: context,
+      barrierDismissible: true,
+      barrierLabel: 'Dismiss',
+      barrierColor: Colors.black.withValues(alpha: 0.42),
+      transitionDuration: const Duration(milliseconds: 290),
+      pageBuilder: (ctx, anim, secAnim) => Align(
+        alignment: fromEnd ? Alignment.centerRight : Alignment.centerLeft,
+        child: SizedBox(
+          height: double.infinity,
+          child: KasySidebarPro(
+            initiallyCollapsed: initiallyCollapsed,
+            side: fromEnd
+                ? KasySidebarProSide.right
+                : KasySidebarProSide.left,
+          ),
+        ),
+      ),
+      transitionBuilder: (ctx, anim, secAnim, child) {
+        final curved = CurvedAnimation(
+          parent: anim,
+          curve: Curves.easeOutCubic,
+        );
+        return SlideTransition(
+          position: Tween<Offset>(
+            begin: Offset(fromEnd ? 1.0 : -1.0, 0),
+            end: Offset.zero,
+          ).animate(curved),
+          child: FadeTransition(
+            opacity: Tween<double>(begin: 0.85, end: 1.0).animate(curved),
+            child: child,
+          ),
+        );
+      },
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        Padding(
+          padding: const EdgeInsets.symmetric(horizontal: KasySpacing.md),
+          child: _previewIntrinsicLaunch(
+            KasyButton(
+              label: 'Open Left',
+              variant: KasyButtonVariant.soft,
+              onPressed: () => _open(context, fromEnd: false),
+            ),
+          ),
+        ),
+        const SizedBox(height: KasySpacing.sm),
+        Padding(
+          padding: const EdgeInsets.symmetric(horizontal: KasySpacing.md),
+          child: _previewIntrinsicLaunch(
+            KasyButton(
+              label: 'Open Right',
+              variant: KasyButtonVariant.soft,
+              onPressed: () => _open(context, fromEnd: true),
+            ),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // ─────────────────────────────────────────────────────────────────────────────
 // Tabs — interactive demos
@@ -2626,29 +2730,18 @@ Widget _buildTextFieldCharacterLimit(BuildContext context) {
 }
 
 Widget _buildTextFieldVariantsVariant(BuildContext context) {
-  final TextStyle labelStyle =
-      context.textTheme.labelSmall?.copyWith(
-        color: context.colors.muted,
-        letterSpacing: 1.2,
-        fontWeight: FontWeight.w700,
-      ) ??
-      const TextStyle();
-  return Column(
+  return const Column(
     mainAxisSize: MainAxisSize.min,
     crossAxisAlignment: CrossAxisAlignment.stretch,
     children: [
-      Text('PRIMARY', style: labelStyle),
-      const SizedBox(height: KasySpacing.sm),
-      const KasyTextField(
+      KasyTextField(
         label: 'Primary Variant',
         hint: 'Primary style input',
         description: 'Default variant with primary styling',
         contentType: KasyTextFieldContentType.email,
       ),
-      const SizedBox(height: KasySpacing.lg),
-      Text('SECONDARY', style: labelStyle),
-      const SizedBox(height: KasySpacing.sm),
-      const KasyTextField(
+      SizedBox(height: KasySpacing.lg),
+      KasyTextField(
         label: 'Secondary Variant',
         hint: 'Secondary style input',
         description: 'Secondary variant for surfaces',
@@ -2660,39 +2753,26 @@ Widget _buildTextFieldVariantsVariant(BuildContext context) {
 }
 
 Widget _buildTextFieldStates(BuildContext context) {
-  final TextStyle labelStyle =
-      context.textTheme.labelSmall?.copyWith(
-        color: context.colors.muted,
-        letterSpacing: 1.2,
-        fontWeight: FontWeight.w700,
-      ) ??
-      const TextStyle();
-  return Column(
+  return const Column(
     mainAxisSize: MainAxisSize.min,
     crossAxisAlignment: CrossAxisAlignment.stretch,
     children: [
-      Text('DEFAULT', style: labelStyle),
-      const SizedBox(height: KasySpacing.sm),
-      const KasyTextField(
+      KasyTextField(
         label: 'Default State',
         hint: 'Enter your email',
         description: 'Normal input state',
         contentType: KasyTextFieldContentType.email,
       ),
-      const SizedBox(height: KasySpacing.lg),
-      Text('DISABLED', style: labelStyle),
-      const SizedBox(height: KasySpacing.sm),
-      const KasyTextField(
+      SizedBox(height: KasySpacing.lg),
+      KasyTextField(
         label: 'Disabled State',
         hint: 'Read only value',
         description: 'TextField is disabled and cannot be edited',
         enabled: false,
         contentType: KasyTextFieldContentType.email,
       ),
-      const SizedBox(height: KasySpacing.lg),
-      Text('INVALID', style: labelStyle),
-      const SizedBox(height: KasySpacing.sm),
-      const KasyTextField(
+      SizedBox(height: KasySpacing.lg),
+      KasyTextField(
         label: 'Invalid State',
         hint: 'Enter your email',
         errorText: 'Please enter a valid email address',
@@ -2720,29 +2800,18 @@ Widget _buildTextAreaWithLabelDescription(BuildContext context) {
 }
 
 Widget _buildTextAreaStates(BuildContext context) {
-  final TextStyle labelStyle =
-      context.textTheme.labelSmall?.copyWith(
-        color: context.colors.muted,
-        letterSpacing: 1.2,
-        fontWeight: FontWeight.w700,
-      ) ??
-      const TextStyle();
-  return Column(
+  return const Column(
     mainAxisSize: MainAxisSize.min,
     crossAxisAlignment: CrossAxisAlignment.stretch,
     children: [
-      Text('DISABLED', style: labelStyle),
-      const SizedBox(height: KasySpacing.sm),
-      const KasyTextArea(
+      KasyTextArea(
         label: 'Disabled State',
         hint: 'Read only value',
         description: 'Text area is disabled and cannot be edited',
         enabled: false,
       ),
-      const SizedBox(height: KasySpacing.lg),
-      Text('INVALID', style: labelStyle),
-      const SizedBox(height: KasySpacing.sm),
-      const KasyTextArea(
+      SizedBox(height: KasySpacing.lg),
+      KasyTextArea(
         label: 'Invalid State',
         hint: 'Enter your message',
         isInvalid: true,
@@ -4859,19 +4928,10 @@ class _TextFieldWithIconContentState extends State<_TextFieldWithIconContent> {
 
   @override
   Widget build(BuildContext context) {
-    final TextStyle labelStyle =
-        context.textTheme.labelSmall?.copyWith(
-          color: context.colors.muted,
-          letterSpacing: 1.2,
-          fontWeight: FontWeight.w700,
-        ) ??
-        const TextStyle();
     return Column(
       mainAxisSize: MainAxisSize.min,
       crossAxisAlignment: CrossAxisAlignment.stretch,
       children: [
-        Text('PHONE', style: labelStyle),
-        const SizedBox(height: KasySpacing.sm),
         const KasyTextField(
           label: 'Phone',
           hint: '5550000000',
@@ -4879,16 +4939,12 @@ class _TextFieldWithIconContentState extends State<_TextFieldWithIconContent> {
           contentType: KasyTextFieldContentType.phone,
         ),
         const SizedBox(height: KasySpacing.lg),
-        Text('PASSWORD', style: labelStyle),
-        const SizedBox(height: KasySpacing.sm),
         const KasyTextField(
           label: 'Password',
           hint: 'Enter your password',
           contentType: KasyTextFieldContentType.password,
         ),
         const SizedBox(height: KasySpacing.lg),
-        Text('MESSAGE', style: labelStyle),
-        const SizedBox(height: KasySpacing.sm),
         KasyTextField(
           controller: _messageController,
           label: 'Message',
@@ -8693,6 +8749,13 @@ class _DatePickerMultiMonthPreview extends StatefulWidget {
       _DatePickerMultiMonthPreviewState();
 }
 
+// Breakpoints for the multi-month preview. Below the 2-month threshold the
+// preview shows an explanation card instead of the calendars — picking dates
+// across 2 or 3 grids only makes sense on canvases wide enough to lay them
+// out side by side.
+const double _kMultiMonthMinWidth2 = 620;
+const double _kMultiMonthMinWidth3 = 920;
+
 class _DatePickerMultiMonthPreviewState
     extends State<_DatePickerMultiMonthPreview> {
   KasyDateRange? _stay;
@@ -8700,24 +8763,38 @@ class _DatePickerMultiMonthPreviewState
 
   @override
   Widget build(BuildContext context) {
+    // Multi-month is a desktop/wide-tablet pattern. On native iOS/Android and
+    // narrow web viewports we don't have horizontal room to lay 2–3 month
+    // grids side by side, so the preview shows a notice instead.
+    final double width = MediaQuery.sizeOf(context).width;
+    final bool fitsTwoMonths = kIsWeb && width >= _kMultiMonthMinWidth2;
+    final bool fitsThreeMonths = kIsWeb && width >= _kMultiMonthMinWidth3;
+
+    if (!fitsTwoMonths) {
+      return _MultiMonthUnavailableNotice();
+    }
+
     final KasyDatePickerLocale locale = _datePickerLocaleForApp(context);
     return Column(
       mainAxisSize: MainAxisSize.min,
       crossAxisAlignment: CrossAxisAlignment.stretch,
       children: [
-        // 3-month layout combined with range selection — the classic
-        // Airbnb / Booking desktop pattern for picking a stay.
-        KasyDatePicker(
-          label: '3 months  +  range',
-          placeholder: 'Check-in  ->  Check-out',
-          description: 'Pass monthsToShow: 3 to opt in. Best on wide canvases.',
-          selectionMode: KasyDateSelectionMode.range,
-          range: _stay,
-          onRangeChanged: (r) => setState(() => _stay = r),
-          monthsToShow: 3,
-          locale: locale,
-        ),
-        const SizedBox(height: KasySpacing.lg),
+        if (fitsThreeMonths) ...[
+          // 3-month layout combined with range selection — the classic
+          // Airbnb / Booking desktop pattern for picking a stay.
+          KasyDatePicker(
+            label: '3 months  +  range',
+            placeholder: 'Check-in  ->  Check-out',
+            description:
+                'Pass monthsToShow: 3 to opt in. Best on wide canvases.',
+            selectionMode: KasyDateSelectionMode.range,
+            range: _stay,
+            onRangeChanged: (r) => setState(() => _stay = r),
+            monthsToShow: 3,
+            locale: locale,
+          ),
+          const SizedBox(height: KasySpacing.lg),
+        ],
         // 2-month layout in single-date mode — useful when there's enough
         // horizontal room but you still want one tap to commit.
         KasyDatePicker(
@@ -8733,6 +8810,52 @@ class _DatePickerMultiMonthPreviewState
   }
 }
 
+/// Friendly placeholder shown when the multi-month preview is opened on a
+/// viewport too narrow for the layout (native mobile, narrow web). Surfacing
+/// this instead of hiding the variant keeps the design-system docs honest:
+/// the feature exists, it just isn't appropriate on small canvases.
+class _MultiMonthUnavailableNotice extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    final KasyColors c = context.colors;
+    return Container(
+      padding: const EdgeInsets.all(KasySpacing.lg),
+      decoration: BoxDecoration(
+        color: c.avatarFallbackFill,
+        borderRadius: BorderRadius.circular(KasyRadius.md),
+      ),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          Row(
+            children: [
+              Icon(KasyIcons.info, size: 18, color: c.primary),
+              const SizedBox(width: KasySpacing.sm),
+              Text(
+                'Multi-month works best on wide screens',
+                style: context.textTheme.labelLarge?.copyWith(
+                  fontWeight: FontWeight.w700,
+                  color: c.onSurface,
+                ),
+              ),
+            ],
+          ),
+          const SizedBox(height: KasySpacing.sm),
+          Text(
+            'The 2 and 3-month layouts need room to render side by side, so '
+            'they are previewed only on web at tablet width or larger. On '
+            'mobile breakpoints and native iOS/Android the picker stays at '
+            'a single month — opt in by passing monthsToShow: 2 or 3 from '
+            'your own desktop screens.',
+            style: context.textTheme.bodyMedium?.copyWith(color: c.muted),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // DatePicker — Variants (filled, no backdrop, no suffix, no focus border)
 // ─────────────────────────────────────────────────────────────────────────────