kasy-cli 1.19.3 → 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

@@ -3,6 +3,7 @@ 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';
@@ -244,10 +245,6 @@ ComponentPreviewDefinition? getComponentPreviewDefinition(
             label: 'Range selection',
             builder: _buildDatePickerRange,
           ),
-          ComponentPreviewVariant(
-            label: 'Multi-month',
-            builder: _buildDatePickerMultiMonth,
-          ),
           ComponentPreviewVariant(
             label: 'Date formats',
             builder: _buildDatePickerFormats,
@@ -260,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':
@@ -513,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',
@@ -685,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
@@ -2627,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',
@@ -2661,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',
@@ -2721,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,
@@ -4860,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',
@@ -4880,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',

package/templates/firebase/lib/features/settings/settings_page.dart

@@ -429,171 +429,52 @@ class HapticFeedbackSwitcher extends ConsumerWidget {
 class ThemeSwitcher extends StatelessWidget {
   const ThemeSwitcher({super.key});
 
-  IconData _iconFor(ThemeMode mode) {
-    switch (mode) {
-      case ThemeMode.system:
-        return KasyIcons.phoneAndroid;
-      case ThemeMode.dark:
-        return KasyIcons.darkMode;
-      case ThemeMode.light:
-        return KasyIcons.lightMode;
-    }
-  }
+  // Tab order mirrors the trailing pill: system, light, dark.
+  static const List<ThemeMode> _modes = <ThemeMode>[
+    ThemeMode.system,
+    ThemeMode.light,
+    ThemeMode.dark,
+  ];
 
   @override
   Widget build(BuildContext context) {
     final tr = context.t.settings;
     final theme = ThemeProvider.of(context);
-    final options = <({ThemeMode mode, IconData icon, String label})>[
-      (
-        mode: ThemeMode.system,
-        icon: KasyIcons.phoneAndroid,
-        label: tr.theme_option_system,
+    final items = <KasyTabItem>[
+      KasyTabItem(
+        icon: KasyIcons.monitor,
+        semanticLabel: tr.theme_option_system,
       ),
-      (
-        mode: ThemeMode.light,
+      KasyTabItem(
         icon: KasyIcons.lightMode,
-        label: tr.theme_option_light,
+        semanticLabel: tr.theme_option_light,
       ),
-      (
-        mode: ThemeMode.dark,
+      KasyTabItem(
         icon: KasyIcons.darkMode,
-        label: tr.theme_option_dark,
+        semanticLabel: tr.theme_option_dark,
       ),
     ];
     return Padding(
       padding: const EdgeInsets.symmetric(vertical: KasySpacing.sm),
-      child: Column(
-        crossAxisAlignment: CrossAxisAlignment.stretch,
-        children: [
-          Row(
-            children: [
-              Icon(
-                _iconFor(theme.mode),
-                size: 21,
-                color: context.colors.onSurface,
-              ),
-              const SizedBox(width: KasySpacing.sm),
-              Expanded(
-                child: Text(
-                  tr.theme_title,
-                  style: context.textTheme.titleMedium?.copyWith(
-                    color: context.colors.onSurface,
-                  ),
-                ),
-              ),
-            ],
-          ),
-          const SizedBox(height: KasySpacing.sm),
-          _ThemeModeSegmented(
-            current: theme.mode,
-            options: options,
-            onChanged: theme.setMode,
-          ),
-        ],
-      ),
-    );
-  }
-}
-
-class _ThemeModeSegmented extends StatelessWidget {
-  const _ThemeModeSegmented({
-    required this.current,
-    required this.options,
-    required this.onChanged,
-  });
-
-  final ThemeMode current;
-  final List<({ThemeMode mode, IconData icon, String label})> options;
-  final ValueChanged<ThemeMode> onChanged;
-
-  @override
-  Widget build(BuildContext context) {
-    final trackColor = context.colors.onSurface.withValues(alpha: 0.06);
-    return Container(
-      padding: const EdgeInsets.all(3),
-      decoration: BoxDecoration(
-        color: trackColor,
-        borderRadius: BorderRadius.circular(10),
-      ),
       child: Row(
         children: [
-          for (final opt in options)
-            Expanded(
-              child: _ThemeModeSegment(
-                icon: opt.icon,
-                label: opt.label,
-                selected: current == opt.mode,
-                onTap: () => onChanged(opt.mode),
+          Icon(KasyIcons.palette, size: 21, color: context.colors.onSurface),
+          const SizedBox(width: KasySpacing.sm),
+          Expanded(
+            child: Text(
+              tr.theme_title,
+              style: context.textTheme.titleMedium?.copyWith(
+                color: context.colors.onSurface,
               ),
             ),
-        ],
-      ),
-    );
-  }
-}
-
-class _ThemeModeSegment extends StatelessWidget {
-  const _ThemeModeSegment({
-    required this.icon,
-    required this.label,
-    required this.selected,
-    required this.onTap,
-  });
-
-  final IconData icon;
-  final String label;
-  final bool selected;
-  final VoidCallback onTap;
-
-  @override
-  Widget build(BuildContext context) {
-    final selectedBg = context.colors.surface;
-    final selectedFg = context.colors.onSurface;
-    final unselectedFg = context.colors.muted;
-    return Semantics(
-      button: true,
-      selected: selected,
-      label: label,
-      child: GestureDetector(
-        onTap: onTap,
-        behavior: HitTestBehavior.opaque,
-        child: AnimatedContainer(
-          duration: const Duration(milliseconds: 160),
-          curve: Curves.easeOut,
-          padding: const EdgeInsets.symmetric(vertical: 8),
-          decoration: BoxDecoration(
-            color: selected ? selectedBg : Colors.transparent,
-            borderRadius: BorderRadius.circular(8),
-            boxShadow: selected
-                ? [
-                    BoxShadow(
-                      color: Colors.black.withValues(alpha: 0.06),
-                      blurRadius: 4,
-                      offset: const Offset(0, 1),
-                    ),
-                  ]
-                : const [],
           ),
-          child: Column(
-            mainAxisSize: MainAxisSize.min,
-            children: [
-              Icon(
-                icon,
-                size: 18,
-                color: selected ? selectedFg : unselectedFg,
-              ),
-              const SizedBox(height: 2),
-              Text(
-                label,
-                style: context.textTheme.labelSmall?.copyWith(
-                  color: selected ? selectedFg : unselectedFg,
-                  fontWeight: selected ? FontWeight.w600 : FontWeight.w500,
-                ),
-              ),
-            ],
+          const SizedBox(width: KasySpacing.sm),
+          KasyTabs.items(
+            items: items,
+            selectedIndex: _modes.indexOf(theme.mode),
+            onTabSelected: (i) => theme.setMode(_modes[i]),
           ),
-        ),
+        ],
       ),
     );
   }