kasy-cli 1.19.3 → 1.20.1

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

@@ -1,11 +1,10 @@
 import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
 import 'package:kasy_kit/components/kasy_app_bar.dart';
-import 'package:kasy_kit/core/bottom_menu/bart_inner_paths.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';
 import 'package:kasy_kit/core/widgets/kasy_scroll_behavior.dart';
-import 'package:kasy_kit/features/home/home_components_preview_page.dart';
 import 'package:kasy_kit/features/home/home_components_preview_registry.dart';
 
 /// UI-kit catalog, reachable from the home dashboard.
@@ -66,22 +65,17 @@ class HomeComponentsPage extends StatelessWidget {
                           onTap: () {
                             KasyHaptics.selection(context);
                             if (row.name == 'Design System') {
-                              Navigator.of(context).pushNamed(
-                                bartInnerPath('home', 'design-system'),
-                              );
+                              context.push('/design-system');
                               return;
                             }
-                            final ComponentPreviewDefinition? definition =
-                                getComponentPreviewDefinition(row.name);
-                            if (definition == null) {
+                            // Skip rows without a preview yet (registry returns
+                            // null); otherwise open /components/:name, which the
+                            // router resolves back to this component's preview.
+                            if (getComponentPreviewDefinition(row.name) == null) {
                               return;
                             }
-                            Navigator.of(context).pushNamed(
-                              bartInnerPath('home', 'components-preview'),
-                              arguments: HomeComponentPreviewRouteExtra(
-                                title: definition.title,
-                                variants: definition.variants,
-                              ),
+                            context.push(
+                              '/components/${Uri.encodeComponent(row.name)}',
                             );
                           },
                           child: Padding(
@@ -189,6 +183,7 @@ const Set<String> _kReadyComponents = <String>{
   'TextArea',
   'TextField',
   'Sidebar',
+  'Sidebar Pro',
   'Skeleton',
   'SwipeAction',
   'TextFieldOTP',
@@ -211,6 +206,7 @@ const Set<String> _kWebReadyComponents = <String>{
   'Dialog',
   'Hover',
   'Sidebar',
+  'Sidebar Pro',
   'Skeleton',
   'SwipeAction',
   'TextArea',
@@ -241,6 +237,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/home/home_page.dart

@@ -1,7 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:kasy_kit/components/kasy_app_bar.dart';
-import 'package:kasy_kit/core/bottom_menu/bart_inner_paths.dart';
 import 'package:kasy_kit/core/haptics/kasy_haptics.dart';
 import 'package:kasy_kit/core/states/components/maybe_ask_rating.dart';
 import 'package:kasy_kit/core/states/components/maybe_show_update_bottom_sheet.dart';
@@ -13,7 +13,7 @@ import 'package:kasy_kit/features/notifications/shared/att_permission.dart';
 import 'package:kasy_kit/features/subscription/shared/maybeshow_premium.dart';
 import 'package:kasy_kit/i18n/translations.g.dart';
 
-/// Home hub with dashboard cards; features live under [HomeFeaturesPage].
+/// Home hub with dashboard cards linking to the Features and Components screens.
 class HomePage extends ConsumerWidget {
   const HomePage({super.key});
 
@@ -59,9 +59,10 @@ class HomePage extends ConsumerWidget {
                             gradient: _featuresGradient(context, isDark),
                             onOpen: () {
                               KasyHaptics.medium(context);
-                              Navigator.of(context).pushNamed(
-                                bartInnerPath('home', 'features'),
-                              );
+                              // Top-level go_router route: opens full-screen on the
+                              // root navigator (above the BottomMenu, no bottom bar)
+                              // and pops back to home with the menu intact.
+                              context.push('/features');
                             },
                           );
                           final componentsCard = _DashboardGradientCard(
@@ -74,9 +75,7 @@ class HomePage extends ConsumerWidget {
                             gradient: _componentsGradient(context, isDark),
                             onOpen: () {
                               KasyHaptics.medium(context);
-                              Navigator.of(context).pushNamed(
-                                bartInnerPath('home', 'components'),
-                              );
+                              context.push('/components');
                             },
                           );
                           if (isWide) {