kasy-cli 1.19.3 → 1.20.1

package/templates/firebase/lib/components/kasy_tabs.dart

@@ -7,15 +7,24 @@ import 'package:kasy_kit/core/theme/theme.dart';
 
 /// Data model for a single tab item.
 class KasyTabItem {
+  /// Visible text. Leave empty for an icon-only tab (requires [icon]).
   final String label;
   final IconData? icon;
   final bool enabled;
 
+  /// Accessibility label read by screen readers. Falls back to [label] when
+  /// not provided; required (in spirit) for icon-only tabs, which have no text.
+  final String? semanticLabel;
+
   const KasyTabItem({
-    required this.label,
+    this.label = '',
     this.icon,
     this.enabled = true,
-  });
+    this.semanticLabel,
+  }) : assert(
+          label != '' || icon != null,
+          'KasyTabItem needs a label, an icon, or both.',
+        );
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -190,27 +199,41 @@ class _KasyTabsState extends State<KasyTabs> {
     }
   }
 
-  /// Scrolls the [SingleChildScrollView] so the selected tab is fully visible.
+  /// Scrolls the inner [SingleChildScrollView] so the selected tab is visible.
   ///
-  /// First/last tab snap to the scroll extremes so the container's outer
-  /// padding (and the pill that extends 4px beyond tab edges) is never clipped.
+  /// Only the component's OWN horizontal controller is moved — never an
+  /// ancestor scrollable. (Using [Scrollable.ensureVisible] here would bubble
+  /// up and scroll the enclosing page vertically, e.g. nudging the Settings
+  /// list down when picking a middle tab.) First/last tab snap to the scroll
+  /// extremes so the container padding and the 4px pill overflow aren't clipped.
   void _ensureSelectedVisible(int index) {
+    if (!_scrollController.hasClients) return;
+
+    final ScrollPosition position = _scrollController.position;
+    final double min = position.minScrollExtent;
+    final double max = position.maxScrollExtent;
+    // No horizontal overflow: leave every scroll position untouched.
+    if (max <= min) return;
+
     const Duration duration = Duration(milliseconds: 250);
     const Curve curve = Curves.easeInOut;
     final int lastIndex = widget.items.length - 1;
 
-    if (_scrollController.hasClients &&
-        (index == 0 || index == lastIndex)) {
-      final double target = index == 0
-          ? _scrollController.position.minScrollExtent
-          : _scrollController.position.maxScrollExtent;
-      _scrollController.animateTo(target, duration: duration, curve: curve);
-      return;
+    final double target;
+    if (index == 0) {
+      target = min;
+    } else if (index == lastIndex) {
+      target = max;
+    } else {
+      // Centre the selected tab in the viewport. Measured geometry is relative
+      // to the inner Stack, which sits 8px in from the scrollable content edge
+      // (the tabsContent horizontal padding).
+      const double horizontalPadding = 8;
+      final double tabCentre =
+          horizontalPadding + _indicatorLeft + _indicatorWidth / 2;
+      target = (tabCentre - position.viewportDimension / 2).clamp(min, max);
     }
-
-    final BuildContext? ctx = _keys[index].currentContext;
-    if (ctx == null) return;
-    Scrollable.ensureVisible(ctx, duration: duration, curve: curve);
+    _scrollController.animateTo(target, duration: duration, curve: curve);
   }
 
   @override
@@ -397,7 +420,31 @@ class _KasyTabsState extends State<KasyTabs> {
 // Internal tab widgets
 // ─────────────────────────────────────────────────────────────────────────────
 
-class _PrimaryTab extends StatelessWidget {
+/// Adds a pointer (click) cursor and reports hover changes on web/desktop.
+/// Disabled tabs keep the default cursor and never report hover.
+class _TabHoverRegion extends StatelessWidget {
+  const _TabHoverRegion({
+    required this.enabled,
+    required this.onHover,
+    required this.child,
+  });
+
+  final bool enabled;
+  final ValueChanged<bool> onHover;
+  final Widget child;
+
+  @override
+  Widget build(BuildContext context) {
+    return MouseRegion(
+      cursor: enabled ? SystemMouseCursors.click : MouseCursor.defer,
+      onEnter: enabled ? (_) => onHover(true) : null,
+      onExit: enabled ? (_) => onHover(false) : null,
+      child: child,
+    );
+  }
+}
+
+class _PrimaryTab extends StatefulWidget {
   const _PrimaryTab({
     super.key,
     required this.item,
@@ -411,12 +458,27 @@ class _PrimaryTab extends StatelessWidget {
   final bool expand;
   final VoidCallback? onTap;
 
+  @override
+  State<_PrimaryTab> createState() => _PrimaryTabState();
+}
+
+class _PrimaryTabState extends State<_PrimaryTab> {
+  bool _hovered = false;
+
   Widget _tabContent(BuildContext context) {
     final KasyColors c = context.colors;
+    final KasyTabItem item = widget.item;
+    final bool selected = widget.selected;
     final bool disabled = !item.enabled;
-    // Fill mode with icons uses a vertical (Column) layout per Figma spec:
-    // icon stacked above label, 12px all-sides padding, 12px font size.
-    final bool verticalLayout = expand && item.icon != null;
+    final bool hasLabel = item.label.isNotEmpty;
+    final bool iconOnly = item.icon != null && !hasLabel;
+    // Fill mode with a label + icon uses a vertical (Column) layout per Figma
+    // spec: icon stacked above label, 12px all-sides padding, 12px font size.
+    final bool verticalLayout = widget.expand && item.icon != null && hasLabel;
+
+    // On web/desktop, hovering an inactive tab lifts its foreground toward the
+    // selected color so it reads as interactive (mobile keeps the flat look).
+    final Color fg = (selected || _hovered) ? c.onSurface : c.muted;
 
     final Widget iconWidget = item.icon != null
         ? Opacity(
@@ -424,7 +486,7 @@ class _PrimaryTab extends StatelessWidget {
             child: Icon(
               item.icon,
               size: 16,
-              color: selected ? c.onSurface : c.muted,
+              color: fg,
             ),
           )
         : const SizedBox.shrink();
@@ -437,15 +499,15 @@ class _PrimaryTab extends StatelessWidget {
         // Use labelLarge as defined in the Kasy theme (14px/w600).
         // No fontWeight override — the theme token is the source of truth.
         style: context.textTheme.labelLarge?.copyWith(
-          color: selected ? c.onSurface : c.muted,
+          color: fg,
           // Fill+icon layout uses 12px (text-xs) — per Figma spec.
           fontSize: verticalLayout ? 12 : null,
         ),
       ),
     );
 
-    return GestureDetector(
-      onTap: onTap,
+    final Widget gesture = GestureDetector(
+      onTap: widget.onTap,
       behavior: HitTestBehavior.opaque,
       child: Padding(
         padding: verticalLayout
@@ -467,25 +529,42 @@ class _PrimaryTab extends StatelessWidget {
                 mainAxisSize: MainAxisSize.min,
                 mainAxisAlignment: MainAxisAlignment.center,
                 children: [
-                  if (item.icon != null) ...[
-                    iconWidget,
+                  if (item.icon != null) iconWidget,
+                  if (item.icon != null && hasLabel)
                     const SizedBox(width: 6),
-                  ],
-                  labelWidget,
+                  if (hasLabel) labelWidget,
                 ],
               ),
       ),
     );
+
+    final Widget hoverable = _TabHoverRegion(
+      enabled: !disabled,
+      onHover: (value) => setState(() => _hovered = value),
+      child: gesture,
+    );
+
+    // Icon-only tabs carry no text, so expose the selection state and a label
+    // to screen readers explicitly (labelled tabs are described by their Text).
+    if (iconOnly) {
+      return Semantics(
+        button: true,
+        selected: selected,
+        label: item.semanticLabel,
+        child: hoverable,
+      );
+    }
+    return hoverable;
   }
 
   @override
   Widget build(BuildContext context) {
     final Widget inner = _tabContent(context);
-    return expand ? Expanded(child: inner) : inner;
+    return widget.expand ? Expanded(child: inner) : inner;
   }
 }
 
-class _SecondaryTab extends StatelessWidget {
+class _SecondaryTab extends StatefulWidget {
   const _SecondaryTab({
     super.key,
     required this.item,
@@ -499,12 +578,27 @@ class _SecondaryTab extends StatelessWidget {
   final bool expand;
   final VoidCallback? onTap;
 
+  @override
+  State<_SecondaryTab> createState() => _SecondaryTabState();
+}
+
+class _SecondaryTabState extends State<_SecondaryTab> {
+  bool _hovered = false;
+
   Widget _tabContent(BuildContext context) {
     final KasyColors c = context.colors;
+    final KasyTabItem item = widget.item;
+    final bool selected = widget.selected;
     final bool disabled = !item.enabled;
+    final bool hasLabel = item.label.isNotEmpty;
+    final bool iconOnly = item.icon != null && !hasLabel;
+
+    // On web/desktop, hovering an inactive tab lifts its foreground toward the
+    // selected color so it reads as interactive (mobile keeps the flat look).
+    final Color fg = (selected || _hovered) ? c.onSurface : c.muted;
 
-    return GestureDetector(
-      onTap: onTap,
+    final Widget gesture = GestureDetector(
+      onTap: widget.onTap,
       behavior: HitTestBehavior.opaque,
       child: Padding(
         // top:4 bottom:6 horizontal:12 — per Figma spec.
@@ -525,30 +619,49 @@ class _SecondaryTab extends StatelessWidget {
                 child: Icon(
                   item.icon,
                   size: 16,
-                  color: selected ? c.onSurface : c.muted,
+                  color: fg,
                 ),
               ),
-              const SizedBox(width: 6),
+              if (hasLabel) const SizedBox(width: 6),
             ],
-            Opacity(
-              opacity: disabled ? 0.4 : 1.0,
-              child: Text(
-                item.label,
-                // Use labelLarge as defined in the Kasy theme (14px/w600).
-                style: context.textTheme.labelLarge?.copyWith(
-                  color: selected ? c.onSurface : c.muted,
+            if (hasLabel)
+              Opacity(
+                opacity: disabled ? 0.4 : 1.0,
+                child: Text(
+                  item.label,
+                  // Use labelLarge as defined in the Kasy theme (14px/w600).
+                  style: context.textTheme.labelLarge?.copyWith(
+                    color: fg,
+                  ),
                 ),
               ),
-            ),
           ],
         ),
       ),
     );
+
+    final Widget hoverable = _TabHoverRegion(
+      enabled: !disabled,
+      onHover: (value) => setState(() => _hovered = value),
+      child: gesture,
+    );
+
+    // Icon-only tabs carry no text, so expose the selection state and a label
+    // to screen readers explicitly (labelled tabs are described by their Text).
+    if (iconOnly) {
+      return Semantics(
+        button: true,
+        selected: selected,
+        label: item.semanticLabel,
+        child: hoverable,
+      );
+    }
+    return hoverable;
   }
 
   @override
   Widget build(BuildContext context) {
     final Widget inner = _tabContent(context);
-    return expand ? Expanded(child: inner) : inner;
+    return widget.expand ? Expanded(child: inner) : inner;
   }
 }

package/templates/firebase/lib/components/kasy_text_field.dart

@@ -241,9 +241,20 @@ class _KasyTextFieldState extends State<KasyTextField> {
     // (No more web-specific padding — the field now uses the same vertical
     // padding on every platform so primary/web TextFields render at the same
     // height as mobile and as the KasyDatePicker trigger.)
-    const double disabledTextOpacity = 0.56;
-    const double disabledLabelOpacity = 0.46;
-    const double disabledDescriptionOpacity = 0.34;
+
+    // ── Disabled state: opaque "softened" colors, NOT transparency. ────────
+    // Kit-wide rule (see KasyButton): keep the original hue but render it
+    // weaker by alpha-blending toward the surface — never use raw opacity,
+    // which would leak whatever sits behind the widget. [dimDisabled] takes
+    // any base color and returns an opaque, softer version of it (or the
+    // color itself when the field is enabled). The [alpha] parameter
+    // controls how much of the original color is kept: higher = stronger
+    // (closer to the original), lower = softer (closer to the surface).
+    final Color blendSurface = context.colors.surface;
+    Color dimDisabled(Color base, {double alpha = 0.46}) {
+      if (!isDisabled) return base;
+      return Color.alphaBlend(base.withValues(alpha: alpha), blendSurface);
+    }
     final bool isPassword =
         widget.contentType == KasyTextFieldContentType.password;
     final bool isEmail = widget.contentType == KasyTextFieldContentType.email;
@@ -289,16 +300,18 @@ class _KasyTextFieldState extends State<KasyTextField> {
     final TextStyle labelStyle = labelBaseStyle.copyWith(
       color: hasInvalidState
           ? context.colors.error
-          : (labelBaseStyle.color ?? context.colors.fieldLabel).withValues(
-              alpha: isDisabled ? disabledLabelOpacity : 1,
+          : dimDisabled(
+              labelBaseStyle.color ?? context.colors.fieldLabel,
+              alpha: 0.55,
             ),
     );
     final TextStyle descriptionStyle =
         (hasInvalidState ? errorBaseStyle : helperBaseStyle).copyWith(
           color: hasInvalidState
               ? context.colors.error
-              : (helperBaseStyle.color ?? context.colors.muted).withValues(
-                  alpha: isDisabled ? disabledDescriptionOpacity : 1,
+              : dimDisabled(
+                  helperBaseStyle.color ?? context.colors.muted,
+                  alpha: 0.45,
                 ),
         );
     final BorderRadius fieldRadius = BorderRadius.circular(KasyRadius.md);
@@ -372,19 +385,17 @@ class _KasyTextFieldState extends State<KasyTextField> {
         ? surfaceColor.withValues(alpha: context.isDark ? 0.9 : 0.94)
         : surfaceColor;
     // Affix icon tint matches the kit's helper-icon tone (0.62) when the
-    // field is enabled, and fades down with the same disabled curve used by
-    // the rest of the field so prefix/suffix don't stay "alive" while
-    // everything else dims.
-    final double affixAlpha = isDisabled
-        ? 0.62 * disabledTextOpacity
-        : 0.62;
+    // field is enabled. When disabled, dimDisabled blends that base color
+    // toward the surface — the icon stays opaque, just less saturated.
+    final Color affixBase = context.colors.onSurface.withValues(alpha: 0.62);
+    final Color affixColor = dimDisabled(affixBase);
     final Widget? resolvedPrefix = widget.prefix == null
         ? null
         : Center(
             child: IconTheme.merge(
               data: IconThemeData(
                 size: KasyTextField.iconGlyphSize,
-                color: context.colors.onSurface.withValues(alpha: affixAlpha),
+                color: affixColor,
               ),
               child: widget.prefix!,
             ),
@@ -395,7 +406,7 @@ class _KasyTextFieldState extends State<KasyTextField> {
             child: IconTheme.merge(
               data: IconThemeData(
                 size: KasyTextField.iconGlyphSize,
-                color: context.colors.onSurface.withValues(alpha: affixAlpha),
+                color: affixColor,
               ),
               child: widget.suffix!,
             ),
@@ -419,24 +430,15 @@ class _KasyTextFieldState extends State<KasyTextField> {
                       child: Icon(
                         _passwordVisible ? KasyIcons.eyeOff : KasyIcons.eye,
                         size: KasyTextField.iconGlyphSize,
-                        color: context.colors.onSurface.withValues(
-                          alpha: widget.enabled ? 0.62 : disabledTextOpacity,
-                        ),
+                        color: affixColor,
                       ),
                     ),
                   ),
                 ),
               )
             : null);
-    // Resolved text color for the value rendered inside the field. We bake
-    // the disabled fade directly into the color (rather than relying on the
-    // Material TextField's own disabled handling) so the disabled state is
-    // visually identical across native, web and DatePicker contexts. Without
-    // this explicit color, Material would render the value at full opacity
-    // because [style] takes precedence over the framework's disabled fade.
-    final Color fieldTextColor = isDisabled
-        ? context.colors.onSurface.withValues(alpha: disabledTextOpacity)
-        : context.colors.onSurface;
+
+    final Color fieldTextColor = dimDisabled(context.colors.onSurface);
     final TextStyle fieldTextStyle =
         context.textTheme.bodyLarge?.copyWith(
           color: fieldTextColor,
@@ -502,11 +504,11 @@ class _KasyTextFieldState extends State<KasyTextField> {
               ),
             ),
       hintStyle: hintBaseStyle.copyWith(
-        // Match the disabled description fade so the placeholder dims along
-        // with the rest of the field (the previous 0.42 read as "kind of
-        // greyed out" rather than disabled).
-        color: (hintBaseStyle.color ?? context.colors.muted).withValues(
-          alpha: isDisabled ? disabledDescriptionOpacity : 1,
+        // Placeholder dims along with the field via the kit-wide softened
+        // color rule (opaque blend toward the surface, not raw opacity).
+        color: dimDisabled(
+          hintBaseStyle.color ?? context.colors.muted,
+          alpha: 0.55,
         ),
       ),
     );
@@ -618,8 +620,9 @@ class _KasyTextFieldState extends State<KasyTextField> {
                   Text(
                     '${_effectiveController.text.length}/${widget.maxLength}',
                     style: context.textTheme.bodySmall?.copyWith(
-                      color: context.colors.onSurface.withValues(
-                        alpha: isDisabled ? disabledDescriptionOpacity : 0.54,
+                      color: dimDisabled(
+                        context.colors.onSurface.withValues(alpha: 0.54),
+                        alpha: 0.55,
                       ),
                       fontWeight: FontWeight.w500,
                     ),

package/templates/firebase/lib/core/bottom_menu/bottom_menu.dart

@@ -1,96 +1,30 @@
 import 'package:bart/bart.dart' as bart;
-import 'package:bart/bart/bart_bottombar_actions.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
+import 'package:kasy_kit/components/kasy_sidebar_pro.dart';
 import 'package:kasy_kit/core/bottom_menu/bottom_router.dart';
 import 'package:kasy_kit/core/bottom_menu/kasy_bottom_bar_factory.dart';
-import 'package:kasy_kit/core/sidebar/kasy_sidebar.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
 import 'package:kasy_kit/core/widgets/responsive_layout.dart';
 
 /// Bottom navigation host powered by Bart (https://pub.dev/packages/bart).
 ///
-/// Bart stores its bottom-bar visibility inside a [ValueNotifier] created in
-/// the [bart.BartScaffold] constructor. Because [ResponsiveLayout] recreates
-/// one of three [bart.BartScaffold]s on every rebuild (breakpoint change,
-/// theme toggle, device-preview resize), that notifier resets to its initial
-/// value and a previously-hidden bar can come back wrong — or, when returning
-/// from a native overlay (FaceID, photo picker, permission dialog), Bart's
-/// internal state ends up out of sync with the visible route.
-///
-/// This widget owns visibility end-to-end so feature pages never need to
-/// touch it. The rules are simple:
-///   * Bottom-bar tab (1 path segment) → bar visible.
-///   * Inner route (multi-segment, or [bart.BartMenuRoute.showBottomBar] =
-///     false) → bar hidden.
-///
-/// Sync points: [onRouteChanged], post-frame after every [build] (catches
-/// scaffold rebuilds), and [didChangeAppLifecycleState] on resume.
-class BottomMenu extends StatefulWidget {
+/// [ResponsiveLayout] swaps between three [bart.BartScaffold]s (small / medium /
+/// large) based on width. The bottom bar shows on every tab; detail screens
+/// (Features, Components, …) are pushed on the root navigator from the pages
+/// themselves, so they cover this menu and there's nothing to toggle here.
+class BottomMenu extends StatelessWidget {
   final String? initialRoute;
 
   const BottomMenu({super.key, this.initialRoute});
 
-  @override
-  State<BottomMenu> createState() => _BottomMenuState();
-}
-
-class _BottomMenuState extends State<BottomMenu>
-    with WidgetsBindingObserver, BartNotifier {
-  String? _currentRoutePath;
-
-  @override
-  void initState() {
-    super.initState();
-    WidgetsBinding.instance.addObserver(this);
-    _currentRoutePath = _resolveInitialRoute(widget.initialRoute);
-  }
-
-  @override
-  void dispose() {
-    WidgetsBinding.instance.removeObserver(this);
-    super.dispose();
-  }
-
-  @override
-  void didChangeAppLifecycleState(AppLifecycleState state) {
-    super.didChangeAppLifecycleState(state);
-    if (state == AppLifecycleState.resumed) {
-      _scheduleSync();
-    }
-  }
-
-  void _onRouteChanged(bart.BartMenuRoute route) {
-    _currentRoutePath = route.path;
-    _scheduleSync();
-  }
-
-  void _scheduleSync() {
-    WidgetsBinding.instance.addPostFrameCallback((_) {
-      if (!mounted) return;
-      _applyVisibility();
-    });
-  }
-
-  void _applyVisibility() {
-    if (_shouldShowBottomBar(_currentRoutePath)) {
-      showBottomBar(context);
-    } else {
-      hideBottomBar(context);
-    }
-  }
-
   @override
   Widget build(BuildContext context) {
-    // Re-assert visibility after every rebuild: the Bart scaffold underneath
-    // may have been freshly instantiated (see class doc).
-    _scheduleSync();
-
-    final String? resolvedInitialRoute = _resolveInitialRoute(
-      widget.initialRoute,
+    final String? resolvedInitialRoute = _resolveInitialRoute(initialRoute);
+    final bool showBottomBarOnStart = _shouldShowBottomBarOnStart(
+      resolvedInitialRoute,
     );
-    final bool showBottomBarOnStart = _shouldShowBottomBar(resolvedInitialRoute);
     final scaffoldOptions = bart.ScaffoldOptions(
       backgroundColor: context.colors.background,
     );
@@ -107,9 +41,8 @@ class _BottomMenuState extends State<BottomMenu>
           initialRoute: resolvedInitialRoute,
           showBottomBarOnStart: showBottomBarOnStart,
           scaffoldOptions: scaffoldOptions,
-          onRouteChanged: _onRouteChanged,
         ),
-        // medium (768–1024 px): icon-only collapsed rail
+        // medium (768–1024 px): KasySidebarPro auto-collapses at this width
         medium: bart.BartScaffold(
           routesBuilder: subRoutes,
           bottomBar: kasyPaddedSurfaceBottomBar(),
@@ -117,9 +50,8 @@ class _BottomMenuState extends State<BottomMenu>
           showBottomBarOnStart: showBottomBarOnStart,
           scaffoldOptions: scaffoldOptions,
           sideBarOptions: bart.CustomSideBarOptions(
-            sideBarBuilder: kasySidebarCollapsedBuilder,
+            sideBarBuilder: (routes, onTap, current) => const KasySidebarPro(),
           ),
-          onRouteChanged: _onRouteChanged,
         ),
         // large (1024 px+): full expanded sidebar
         large: bart.BartScaffold(
@@ -129,9 +61,8 @@ class _BottomMenuState extends State<BottomMenu>
           showBottomBarOnStart: showBottomBarOnStart,
           scaffoldOptions: scaffoldOptions,
           sideBarOptions: bart.CustomSideBarOptions(
-            sideBarBuilder: kasySidebarBuilder,
+            sideBarBuilder: (routes, onTap, current) => const KasySidebarPro(),
           ),
-          onRouteChanged: _onRouteChanged,
         ),
       ),
     );
@@ -170,7 +101,7 @@ class _BottomMenuState extends State<BottomMenu>
     return path;
   }
 
-  bool _shouldShowBottomBar(String? route) {
+  bool _shouldShowBottomBarOnStart(String? route) {
     if (route == null) {
       return true;
     }