kasy-cli 1.31.14 → 1.34.0

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

@@ -552,11 +552,13 @@ class _KasyDatePickerState extends State<KasyDatePicker>
   // Key on the trigger field — used to measure its width when opening the popover.
   final GlobalKey _fieldKey = GlobalKey();
 
-  // Focus node owned by the trigger field. We want focus so the
-  // KasyTextField paints its focus border while the calendar is open — but
-  // the underlying TextField runs in readOnly mode, so no soft keyboard
-  // appears even when focused.
-  final FocusNode _fieldFocusNode = FocusNode();
+  // Drives the trigger's "active" (focused-look) border while the calendar or
+  // overlay is open. We deliberately do NOT focus the field for this: real
+  // focus would (a) light the wrapping KasyFocusRing's keyboard ring on a mouse
+  // click — a second outline — and (b) get stolen by the overlay after a
+  // moment, dropping the border. KasyTextField.forceFocusBorder paints it from
+  // this flag instead, so it stays put for as long as the calendar is open.
+  bool _triggerActive = false;
 
   // Controller backing the trigger KasyTextField — text mirrors the formatted
   // date (or stays empty so the hint renders).
@@ -639,7 +641,6 @@ class _KasyDatePickerState extends State<KasyDatePicker>
   @override
   void dispose() {
     _displayController.dispose();
-    _fieldFocusNode.dispose();
     _animCtrl.dispose();
     super.dispose();
   }
@@ -741,11 +742,12 @@ class _KasyDatePickerState extends State<KasyDatePicker>
 
     _portalController.show();
     _animCtrl.forward();
-    // Focus so the trigger field paints its focus border while the calendar
-    // is open (only when focusBorder is enabled — otherwise we skip to avoid
-    // the field announcing focus to assistive tech for no visual reason).
-    if (widget.focusBorder) _fieldFocusNode.requestFocus();
-    setState(() => _isOpen = true);
+    // Paint the trigger's "active" border while the calendar is open — driven
+    // by state, not real focus (see _triggerActive).
+    setState(() {
+      _isOpen = true;
+      _triggerActive = true;
+    });
   }
 
   void _close() {
@@ -765,7 +767,7 @@ class _KasyDatePickerState extends State<KasyDatePicker>
         _pendingPopoverRange = null;
         widget.onRangeChanged?.call(pendingRange);
       }
-      _fieldFocusNode.unfocus();
+      setState(() => _triggerActive = false);
     });
     setState(() => _isOpen = false);
   }
@@ -830,7 +832,7 @@ class _KasyDatePickerState extends State<KasyDatePicker>
     // endpoint right away).
     DateTime dialogViewMonth = _viewMonth;
     KasyDateRange? dialogRange = _effectiveRange;
-    if (widget.focusBorder) _fieldFocusNode.requestFocus();
+    setState(() => _triggerActive = true);
 
     showKasyDialog<void>(
       context: context,
@@ -904,12 +906,12 @@ class _KasyDatePickerState extends State<KasyDatePicker>
         },
       ),
     ).whenComplete(() {
-      if (mounted) _fieldFocusNode.unfocus();
+      if (mounted) setState(() => _triggerActive = false);
     });
   }
 
   void _openBottomSheet() {
-    if (widget.focusBorder) _fieldFocusNode.requestFocus();
+    setState(() => _triggerActive = true);
     showKasyBottomSheet<void>(
       context: context,
       isScrollControlled: true,
@@ -925,7 +927,7 @@ class _KasyDatePickerState extends State<KasyDatePicker>
         monthsToShow: widget.monthsToShow,
       ),
     ).whenComplete(() {
-      if (mounted) _fieldFocusNode.unfocus();
+      if (mounted) setState(() => _triggerActive = false);
     });
   }
 
@@ -1050,15 +1052,18 @@ class _KasyDatePickerState extends State<KasyDatePicker>
                   child: KasyTextField(
                     key: _fieldKey,
                     controller: _displayController,
-                    focusNode: _fieldFocusNode,
                     readOnly: true,
                     enabled: widget.enabled,
                     hint: _resolvedPlaceholder,
                     isInvalid: hasInvalidState,
                     variant: widget.variant,
                     focusBorder: widget.focusBorder,
-                    // No caret, no selection handles, no "blue text" when the
-                    // trigger is focused while the calendar is open — keeps the
+                    // "Active" border while the calendar is open — painted from
+                    // state, not real focus, so it never doubles the wrapping
+                    // KasyFocusRing's keyboard ring on click and never gets
+                    // dropped when the overlay steals focus.
+                    forceFocusBorder: widget.focusBorder && _triggerActive,
+                    // No caret, no selection handles, no "blue text" — keeps the
                     // field reading as a button, not an editable input.
                     enableInteractiveSelection: false,
                     suffix: widget.showSuffix
@@ -1691,7 +1696,7 @@ class _CalendarNavRow extends StatelessWidget {
             viewMode == _CalendarViewMode.month
                 ? KasyIcons.chevronRight
                 : KasyIcons.chevronDown,
-            size: 18,
+            size: KasyIconSize.md,
             weight: 700,
             color: c.primary,
           ),
@@ -1766,7 +1771,7 @@ class _NavArrowButton extends StatelessWidget {
       child: Center(
         child: Icon(
           icon,
-          size: 20,
+          size: KasyIconSize.lg,
           weight: 700,
           color: disabled ? c.muted.withValues(alpha: 0.45) : c.primary,
         ),

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

@@ -144,7 +144,7 @@ class KasyDialog extends StatelessWidget {
                 padding: const EdgeInsets.all(6),
                 minimumSize: const Size(40, 40),
               ),
-              icon: const Icon(KasyIcons.close, size: 19),
+              icon: const Icon(KasyIcons.close, size: KasyIconSize.md),
             ),
           );
       }
@@ -449,7 +449,7 @@ class _DialogIconBubble extends StatelessWidget {
       width: _size,
       height: _size,
       decoration: BoxDecoration(color: p.background, shape: BoxShape.circle),
-      child: Icon(icon, size: 20, color: p.foreground),
+      child: Icon(icon, size: KasyIconSize.lg, color: p.foreground),
     );
   }
 

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

@@ -0,0 +1,114 @@
+import 'package:flutter/material.dart';
+import 'package:kasy_kit/components/kasy_card.dart';
+import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/page_background.dart';
+
+/// Canonical screen scaffold. A new page that uses it inherits the internal
+/// screen contract for free: the page background, a centred content column
+/// capped at [maxContentWidth], the page gutter, scroll handling, and
+/// (optionally) a [KasyCard] wrapper — all from design-system tokens.
+///
+/// Opt-in by design: it is a thin convenience over [Scaffold] (it forwards the
+/// same `appBar`, `floatingActionButton`, `bottomNavigationBar` slots), not a
+/// cage. Screens that need bespoke chrome can keep using [Scaffold] directly —
+/// nothing here is forced, and any value is overridable.
+///
+/// ```dart
+/// KasyScreen(
+///   appBar: KasyAppBar.root(title: 'Settings'),
+///   card: true,
+///   child: Column(children: [...]),
+/// )
+/// ```
+class KasyScreen extends StatelessWidget {
+  const KasyScreen({
+    super.key,
+    required this.child,
+    this.appBar,
+    this.scrollable = true,
+    this.maxContentWidth = 600,
+    this.padding,
+    this.card = false,
+    this.backgroundColor,
+    this.resizeToAvoidBottomInset,
+    this.floatingActionButton,
+    this.bottomNavigationBar,
+  });
+
+  /// Page content.
+  final Widget child;
+
+  /// Optional top bar. Same slot as [Scaffold.appBar]; pass any
+  /// [PreferredSizeWidget].
+  final PreferredSizeWidget? appBar;
+
+  /// Wrap the content in a scroll view (default true). Set false for screens
+  /// that manage their own scrolling (e.g. a full-bleed list).
+  final bool scrollable;
+
+  /// Max width of the content column on wide screens. The internal-screen
+  /// contract is ~600; content is centred within the available width so it does
+  /// not stretch edge-to-edge on web/desktop.
+  final double maxContentWidth;
+
+  /// Padding around the content. Defaults to the horizontal page gutter plus
+  /// vertical breathing room.
+  final EdgeInsetsGeometry? padding;
+
+  /// Wrap the content in an elevated [KasyCard] (radius 16), matching the Home
+  /// reference look.
+  final bool card;
+
+  /// Page background. Defaults to the theme background token.
+  final Color? backgroundColor;
+
+  /// Forwarded to [Scaffold.resizeToAvoidBottomInset].
+  final bool? resizeToAvoidBottomInset;
+
+  /// Forwarded to [Scaffold.floatingActionButton].
+  final Widget? floatingActionButton;
+
+  /// Forwarded to [Scaffold.bottomNavigationBar].
+  final Widget? bottomNavigationBar;
+
+  @override
+  Widget build(BuildContext context) {
+    final EdgeInsetsGeometry resolvedPadding = padding ??
+        const EdgeInsets.symmetric(
+          horizontal: KasySpacing.pageHorizontalGutter,
+          vertical: KasySpacing.lg,
+        );
+
+    Widget content = ConstrainedBox(
+      constraints: BoxConstraints(maxWidth: maxContentWidth),
+      child: card ? KasyCard(child: child) : child,
+    );
+
+    content = Align(
+      alignment: Alignment.topCenter,
+      child: Padding(padding: resolvedPadding, child: content),
+    );
+
+    if (scrollable) {
+      content = SingleChildScrollView(
+        physics: const ClampingScrollPhysics(),
+        keyboardDismissBehavior: ScrollViewKeyboardDismissBehavior.onDrag,
+        child: content,
+      );
+    }
+
+    return Scaffold(
+      backgroundColor: backgroundColor ?? context.colors.background,
+      resizeToAvoidBottomInset: resizeToAvoidBottomInset,
+      appBar: appBar,
+      floatingActionButton: floatingActionButton,
+      bottomNavigationBar: bottomNavigationBar,
+      body: Background(
+        bgColor: backgroundColor,
+        // top:false when an app bar is present — Scaffold already insets the
+        // body below it, so SafeArea only needs to guard the bottom/sides.
+        child: SafeArea(top: appBar == null, child: content),
+      ),
+    );
+  }
+}

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

@@ -1227,7 +1227,7 @@ class _ProHoverPopupIconState extends State<_ProHoverPopupIcon> {
                 color: widget.iconBg,
                 borderRadius: BorderRadius.circular(_kItemRadius),
               ),
-              child: Icon(widget.icon, size: 20, color: widget.iconColor),
+              child: Icon(widget.icon, size: KasyIconSize.lg, color: widget.iconColor),
             ),
           ),
         ),
@@ -1365,7 +1365,7 @@ class _ProTooltipIconState extends State<_ProTooltipIcon> {
                 color: widget.iconBg,
                 borderRadius: BorderRadius.circular(_kItemRadius),
               ),
-              child: Icon(widget.icon, size: 20, color: widget.iconColor),
+              child: Icon(widget.icon, size: KasyIconSize.lg, color: widget.iconColor),
             ),
           ),
         ),

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

@@ -486,7 +486,7 @@ class _PrimaryTabState extends State<_PrimaryTab> {
             opacity: disabled ? 0.4 : 1.0,
             child: Icon(
               item.icon,
-              size: 16,
+              size: KasyIconSize.sm,
               color: fg,
             ),
           )
@@ -628,7 +628,7 @@ class _SecondaryTabState extends State<_SecondaryTab> {
                   opacity: disabled ? 0.4 : 1.0,
                   child: Icon(
                     item.icon,
-                    size: 16,
+                    size: KasyIconSize.sm,
                     color: fg,
                   ),
                 ),

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

@@ -1,6 +1,8 @@
 import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
+import 'package:kasy_kit/components/kasy_text_field.dart'
+    show KasyTextFieldVariant;
 import 'package:kasy_kit/core/theme/theme.dart';
 
 /// Kasy Design System — multi-line text area.
@@ -31,6 +33,11 @@ class KasyTextArea extends StatefulWidget {
   final int? maxLines;
   final int? maxLength;
 
+  /// Visual treatment — same set as [KasyTextField] (primary / secondary /
+  /// flat / embedded). [flat] is the surface fill with a hairline border and
+  /// NO shadow. Defaults to [primary].
+  final KasyTextFieldVariant variant;
+
   const KasyTextArea({
     super.key,
     this.controller,
@@ -53,6 +60,7 @@ class KasyTextArea extends StatefulWidget {
     this.minLines = 4,
     this.maxLines = 8,
     this.maxLength,
+    this.variant = KasyTextFieldVariant.primary,
   });
 
   @override
@@ -129,6 +137,10 @@ class _KasyTextAreaState extends State<KasyTextArea> {
   @override
   Widget build(BuildContext context) {
     final bool isDisabled = !widget.enabled;
+    final bool isSecondary = widget.variant == KasyTextFieldVariant.secondary;
+    final bool isEmbedded = widget.variant == KasyTextFieldVariant.embedded;
+    final bool isFlat = widget.variant == KasyTextFieldVariant.flat;
+    final bool showShadow = widget.variant == KasyTextFieldVariant.primary;
     final bool hasInvalidState = widget.isInvalid || widget.errorText != null;
     final bool useForm = widget.validator != null || widget.onSaved != null;
 
@@ -156,12 +168,24 @@ class _KasyTextAreaState extends State<KasyTextArea> {
     final Color resolvedFocusedBorderColor = hasInvalidState
         ? context.colors.error
         : focusedBorderColor;
-    final Color enabledBorderColor = KasyShadows.inputFieldRestingBorder(context);
+    final Color enabledBorderColor = isFlat
+        ? KasyShadows.inputFieldFlatBorder(context)
+        : KasyShadows.inputFieldRestingBorder(context);
     final Color restingBorderColor = hasInvalidState
         ? context.colors.error
         : enabledBorderColor;
-    final double restingBorderWidth = hasInvalidState ? 1.3 : 1;
-    final Color surfaceColor = context.colors.surface;
+    final double restingBorderWidth = isEmbedded
+        ? 0
+        : hasInvalidState
+            ? 1.3
+            : 1;
+    final Color surfaceColor = isEmbedded
+        ? Colors.transparent
+        : isSecondary
+            ? (context.isDark
+                ? const Color(0xFF272729)
+                : const Color(0xFFF0F0F2))
+            : context.colors.surface;
     final Color fieldFillColor = isDisabled
         ? surfaceColor.withValues(alpha: context.isDark ? 0.9 : 0.94)
         : surfaceColor;
@@ -348,9 +372,17 @@ class _KasyTextAreaState extends State<KasyTextArea> {
         DecoratedBox(
           decoration: BoxDecoration(
             borderRadius: fieldRadius,
-            boxShadow: [fieldShadow],
+            boxShadow: showShadow ? [fieldShadow] : null,
+          ),
+          // Force standard visual density so the area renders identically on
+          // web/desktop and mobile (Flutter's adaptive density is compact on
+          // web and would otherwise shrink line spacing). Mirrors KasyTextField.
+          child: Theme(
+            data: Theme.of(context).copyWith(
+              visualDensity: VisualDensity.standard,
+            ),
+            child: innerField,
           ),
-          child: innerField,
         ),
         if (hasHelperText || hasCounter) ...[
           const SizedBox(height: KasySpacing.xs),

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

@@ -3,7 +3,12 @@ import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
 
-enum KasyTextFieldVariant { primary, secondary, embedded }
+/// Visual treatments for [KasyTextField]:
+/// - [primary]   filled (surface) + hairline border + soft shadow
+/// - [secondary] elevated fill (contrasts on a surface/card) + border, no shadow
+/// - [flat]      primary's surface fill + border, but NO shadow (e.g. header search)
+/// - [embedded]  transparent, no border, no shadow
+enum KasyTextFieldVariant { primary, secondary, embedded, flat }
 
 enum KasyTextFieldContentType { text, email, password, phone }
 
@@ -18,7 +23,13 @@ class KasyTextField extends StatefulWidget {
   static const double adjacentFieldSpacing = KasySpacing.md;
   static const double iconSlotExtent = 38;
   static const double iconGlyphSize = 17;
-  static const double webSingleLineVerticalPadding = 16;
+
+  /// Canonical resting height for a single-line field. Drives the field's
+  /// vertical content padding (what the filled/bordered box actually wraps), so
+  /// changing this value grows or shrinks the visible box on every platform.
+  /// Matches the medium [KasyButton] height (45) so fields, the DatePicker
+  /// trigger and the primary action all share one control height.
+  static const double singleLineHeight = 41;
 
   final TextEditingController? controller;
   final FocusNode? focusNode;
@@ -57,9 +68,10 @@ class KasyTextField extends StatefulWidget {
   final Widget? labelTrailing;
 
   /// Override for the field's vertical/horizontal padding. When null, the
-  /// design-system default is used (`KasySpacing.md` horizontal, `10`
-  /// vertical on mobile / `webSingleLineVerticalPadding` on web). Pass a
-  /// smaller value to make the field render shorter.
+  /// design-system default is used (`KasySpacing.md` horizontal; single-line
+  /// fields use 0 vertical and take their height from the [singleLineHeight]
+  /// SizedBox, multi-line uses `13`). Passing a custom value opts the field out
+  /// of the fixed single-line height (e.g. the compact header search).
   final EdgeInsetsGeometry? contentPadding;
 
   /// Override for the field's drop shadow. When null, the design-system
@@ -74,6 +86,14 @@ class KasyTextField extends StatefulWidget {
   /// affordance would feel noisy.
   final bool focusBorder;
 
+  /// When true, paints the focused (primary) border even though the field holds
+  /// no real focus. Composite controls like [KasyDatePicker] use this to show
+  /// the trigger as "active" while their overlay is open WITHOUT taking focus —
+  /// taking real focus would double up with the wrapper's keyboard focus ring
+  /// (a second outline on mouse click) and can be stolen by the overlay after a
+  /// moment. No effect on the embedded variant.
+  final bool forceFocusBorder;
+
   /// Forwards to [TextField.enableInteractiveSelection]. When false, the
   /// field renders no caret, suppresses text-selection gestures, and stops
   /// showing the I-beam cursor on web/desktop — handy for read-only triggers
@@ -117,6 +137,7 @@ class KasyTextField extends StatefulWidget {
     this.contentPadding,
     this.boxShadow,
     this.focusBorder = true,
+    this.forceFocusBorder = false,
     this.enableInteractiveSelection = true,
   });
 
@@ -239,6 +260,7 @@ class _KasyTextFieldState extends State<KasyTextField> {
         widget.variant == KasyTextFieldVariant.secondary;
     final bool isEmbeddedVariant =
         widget.variant == KasyTextFieldVariant.embedded;
+    final bool isFlatVariant = widget.variant == KasyTextFieldVariant.flat;
     // (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.)
@@ -265,6 +287,24 @@ class _KasyTextFieldState extends State<KasyTextField> {
     final bool resolvedObscureText = isPassword
         ? !_passwordVisible
         : widget.obscureText;
+    // Single-line fields with the default padding get a fixed canonical height
+    // so they match the medium KasyButton and render identically on every
+    // platform. Multi-line fields (minLines set, or maxLines > 1) keep growing
+    // with their content; callers that pass a custom [contentPadding] (e.g. the
+    // compact header search) are opting into their own height, so the lock is
+    // skipped for them.
+    final bool isSingleLineField =
+        widget.contentPadding == null &&
+        widget.minLines == null &&
+        (resolvedObscureText || (widget.maxLines ?? 1) == 1);
+    // Height of the filled/bordered box = single-line text height + 2× vertical
+    // padding. So to hit [singleLineHeight] we back out the padding from it
+    // (subtract one text line, halve). This is the only lever that actually
+    // stretches the visible box — constraints/SizedBox just pad around it.
+    const double singleLineTextHeight = 19;
+    final double singleLineVerticalPadding =
+        ((KasyTextField.singleLineHeight - singleLineTextHeight) / 2)
+            .clamp(0.0, 60.0);
     final Iterable<String>? resolvedAutofillHints =
         widget.autofillHints ?? _defaultAutofillHints(widget.contentType);
     final TextInputType? resolvedKeyboardType =
@@ -320,7 +360,7 @@ class _KasyTextFieldState extends State<KasyTextField> {
     // platform — removed the previous `!kIsWeb` guard so web matches mobile
     // and the KasyDatePicker trigger.
     final bool shouldShowShadow =
-        !isSecondaryVariant && !isEmbeddedVariant;
+        !isSecondaryVariant && !isEmbeddedVariant && !isFlatVariant;
     final BoxShadow resolvedShadow = BoxShadow(
       color: const Color(0xFF000000).withValues(
         alpha: context.isDark ? 0.28 : 0.11,
@@ -336,9 +376,9 @@ class _KasyTextFieldState extends State<KasyTextField> {
     final Color resolvedFocusedBorderColor = hasInvalidState
         ? context.colors.error
         : focusedBorderColor;
-    final Color enabledBorderColor = KasyShadows.inputFieldRestingBorder(
-      context,
-    );
+    final Color enabledBorderColor = isFlatVariant
+        ? KasyShadows.inputFieldFlatBorder(context)
+        : KasyShadows.inputFieldRestingBorder(context);
     final Color restingBorderColor = hasInvalidState
         ? context.colors.error
         : enabledBorderColor;
@@ -351,14 +391,22 @@ class _KasyTextFieldState extends State<KasyTextField> {
       borderRadius: fieldRadius,
       borderSide: BorderSide.none,
     );
+    // When forceFocusBorder is set, the always-visible (resting) border adopts
+    // the focused look — so a composite trigger reads as "active" without the
+    // field ever holding real focus.
     final InputBorder resolvedEnabledBorder = isEmbeddedVariant
         ? embeddedBorder
         : OutlineInputBorder(
             borderRadius: fieldRadius,
-            borderSide: BorderSide(
-              color: restingBorderColor,
-              width: restingBorderWidth,
-            ),
+            borderSide: widget.forceFocusBorder
+                ? BorderSide(
+                    color: resolvedFocusedBorderColor,
+                    width: focusedBorderWidth,
+                  )
+                : BorderSide(
+                    color: restingBorderColor,
+                    width: restingBorderWidth,
+                  ),
           );
     // When focusBorder is disabled, the focused state collapses to the
     // resting border so the field never grows that bright outline. Error
@@ -462,10 +510,12 @@ class _KasyTextFieldState extends State<KasyTextField> {
               width: KasyTextField.iconSlotExtent,
               height: KasyTextField.iconSlotExtent,
             ),
+      // Single-line height comes from this vertical padding (derived from
+      // singleLineHeight); multi-line keeps a fixed comfortable padding.
       contentPadding: widget.contentPadding ??
           EdgeInsets.symmetric(
             horizontal: isEmbeddedVariant ? 0 : KasySpacing.md,
-            vertical: 13,
+            vertical: isSingleLineField ? singleLineVerticalPadding : 13,
           ),
       fillColor: fieldFillColor,
       filled: !isEmbeddedVariant,
@@ -548,8 +598,19 @@ class _KasyTextFieldState extends State<KasyTextField> {
       child: Semantics(
         textField: true,
         enabled: widget.enabled,
-        label: widget.semanticLabel ?? widget.label ?? widget.hint ?? 'Input',
-        child: innerField,
+        label:
+            widget.semanticLabel ?? widget.label ?? widget.hint ?? 'Text field',
+        // Force standard visual density so the field renders at the same height
+        // on web/desktop as on mobile (Flutter's adaptive density is compact on
+        // web and would otherwise shave ~4px). The height itself comes from the
+        // vertical contentPadding below — that's what the filled/bordered box
+        // wraps, so it grows/shrinks the box you actually see.
+        child: Theme(
+          data: Theme.of(context).copyWith(
+            visualDensity: VisualDensity.standard,
+          ),
+          child: innerField,
+        ),
       ),
     );
     final Widget? labelTrailing = widget.labelTrailing;