kasy-cli 1.19.3 → 1.20.0

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,
                     ),