kasy-cli 1.37.1 → 1.39.0

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

@@ -0,0 +1,584 @@
+import 'package:flutter/material.dart';
+import 'package:kasy_kit/components/kasy_text_field.dart';
+import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_focus_ring.dart';
+import 'package:kasy_kit/core/widgets/kasy_hover.dart';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KasyDropDown — design-system single-select dropdown (HeroUI "Select").
+//
+// Two parts, mirroring the Figma spec:
+//   • Trigger  — reuses [KasyTextField] in read-only mode, so it inherits the
+//                kit input look (label, placeholder, border, shadow, focus
+//                affordance). Shows the selected option or a placeholder, plus
+//                a chevron that flips while open.
+//   • Dropdown — a floating panel anchored to the trigger via [OverlayPortal]
+//                (not a Material PopupMenu). The popover lives under the app's
+//                Overlay, so it inherits the real light/dark theme — fixing the
+//                classic "white menu in dark mode" of raw PopupMenuButton. Opens
+//                downward by default, or upward when there isn't room below.
+//
+// Usage:
+//   KasyDropDown<String>(
+//     label: 'State',
+//     hint: 'Select one',
+//     showRequiredIndicator: true,
+//     value: selected,
+//     items: const [
+//       KasyDropDownItem(value: 'fl', label: 'Florida'),
+//       KasyDropDownItem(value: 'tx', label: 'Texas'),
+//     ],
+//     onChanged: (v) => setState(() => selected = v),
+//   )
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// One selectable option in a [KasyDropDown].
+class KasyDropDownItem<T> {
+  const KasyDropDownItem({
+    required this.value,
+    required this.label,
+    this.icon,
+    this.subtitle,
+    this.enabled = true,
+  });
+
+  /// The value reported through [KasyDropDown.onChanged] when this option is
+  /// picked. Must be unique within the list.
+  final T value;
+
+  /// Primary text shown for the option (and in the trigger once selected).
+  final String label;
+
+  /// Optional leading icon, rendered before the label.
+  final IconData? icon;
+
+  /// Optional secondary line below the label (muted).
+  final String? subtitle;
+
+  /// When false, the option is dimmed and not selectable.
+  final bool enabled;
+}
+
+/// Design-system single-select dropdown. See file header for the anatomy.
+class KasyDropDown<T> extends StatefulWidget {
+  const KasyDropDown({
+    super.key,
+    required this.items,
+    required this.onChanged,
+    this.value,
+    this.label,
+    this.hint,
+    this.showRequiredIndicator = false,
+    this.description,
+    this.errorText,
+    this.isInvalid = false,
+    this.enabled = true,
+    this.leadingIcon,
+    this.variant = KasyTextFieldVariant.primary,
+    this.focusBorder = true,
+    this.showSelectedCheck = true,
+    this.maxPanelHeight = 280,
+    this.semanticLabel,
+  });
+
+  /// The options to choose from.
+  final List<KasyDropDownItem<T>> items;
+
+  /// Called with the picked value. Pass null to render a read-only dropdown.
+  final ValueChanged<T>? onChanged;
+
+  /// Currently selected value (matched against [KasyDropDownItem.value]).
+  final T? value;
+
+  /// Label rendered above the trigger.
+  final String? label;
+
+  /// Placeholder shown in the trigger while nothing is selected.
+  final String? hint;
+
+  /// Shows a danger `*` after the [label].
+  final bool showRequiredIndicator;
+
+  /// Helper text rendered below the trigger (hidden when [errorText] is set).
+  final String? description;
+
+  /// Error text rendered below the trigger; also flips the field to invalid.
+  final String? errorText;
+
+  /// Forces the invalid (danger) styling even without [errorText].
+  final bool isInvalid;
+
+  /// When false, the trigger is dimmed and won't open.
+  final bool enabled;
+
+  /// Optional leading icon shown inside the trigger.
+  final IconData? leadingIcon;
+
+  /// Trigger fill style — mirrors [KasyTextField.variant].
+  final KasyTextFieldVariant variant;
+
+  /// Whether the trigger paints the primary "active" border while open.
+  final bool focusBorder;
+
+  /// Whether the selected option shows a trailing check in the panel.
+  final bool showSelectedCheck;
+
+  /// Maximum height of the dropdown panel before it scrolls internally.
+  final double maxPanelHeight;
+
+  /// Accessibility label for the trigger (falls back to [label]/[hint]).
+  final String? semanticLabel;
+
+  @override
+  State<KasyDropDown<T>> createState() => _KasyDropDownState<T>();
+}
+
+class _KasyDropDownState<T> extends State<KasyDropDown<T>>
+    with SingleTickerProviderStateMixin {
+  final LayerLink _layerLink = LayerLink();
+  final OverlayPortalController _portalController = OverlayPortalController();
+
+  // Groups the trigger + panel for TapRegion so a tap inside either is "inside".
+  final Object _tapGroupId = Object();
+
+  // Measures the trigger width when opening so the panel matches it.
+  final GlobalKey _fieldKey = GlobalKey();
+
+  // Trigger text mirrors the selected label (empty → hint renders).
+  late final TextEditingController _displayController;
+
+  late final AnimationController _animCtrl;
+  late final Animation<double> _fadeAnim;
+  late final Animation<double> _scaleAnim;
+
+  bool _isOpen = false;
+
+  // Drives the trigger's "active" border while the panel is open — from state,
+  // not real focus (see KasyDatePicker for the rationale).
+  bool _triggerActive = false;
+
+  // Trigger width + open direction, read at open time.
+  double _panelWidth = 256;
+  bool _openUp = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _displayController = TextEditingController(text: _selectedLabel());
+    _animCtrl = AnimationController(
+      vsync: this,
+      duration: const Duration(milliseconds: 160),
+    );
+    _fadeAnim = CurvedAnimation(parent: _animCtrl, curve: Curves.easeOut);
+    _scaleAnim = Tween<double>(begin: 0.96, end: 1.0).animate(
+      CurvedAnimation(parent: _animCtrl, curve: Curves.easeOut),
+    );
+  }
+
+  @override
+  void didUpdateWidget(covariant KasyDropDown<T> oldWidget) {
+    super.didUpdateWidget(oldWidget);
+    // Keep the trigger text in sync when the selection or items change upstream.
+    if (oldWidget.value != widget.value || oldWidget.items != widget.items) {
+      _displayController.text = _selectedLabel();
+    }
+  }
+
+  @override
+  void dispose() {
+    _animCtrl.dispose();
+    _displayController.dispose();
+    super.dispose();
+  }
+
+  KasyDropDownItem<T>? get _selectedItem {
+    for (final item in widget.items) {
+      if (item.value == widget.value) return item;
+    }
+    return null;
+  }
+
+  String _selectedLabel() => _selectedItem?.label ?? '';
+
+  void _toggle() {
+    if (!widget.enabled || widget.items.isEmpty) return;
+    if (_isOpen) {
+      _close();
+    } else {
+      _open();
+    }
+  }
+
+  void _open() {
+    final RenderBox? fieldBox =
+        _fieldKey.currentContext?.findRenderObject() as RenderBox?;
+    _panelWidth = fieldBox?.size.width ?? 256;
+
+    // Estimate the panel height so we can flip up when there's no room below.
+    final double estimatedHeight = _estimatedPanelHeight();
+    bool openUp = false;
+    if (fieldBox != null) {
+      final Offset fieldTopLeft = fieldBox.localToGlobal(Offset.zero);
+      final Size viewport = MediaQuery.sizeOf(context);
+      final EdgeInsets safe = MediaQuery.viewPaddingOf(context);
+      final double fieldBottom = fieldTopLeft.dy + fieldBox.size.height;
+      final double spaceBelow = viewport.height - safe.bottom - fieldBottom;
+      final double spaceAbove = fieldTopLeft.dy - safe.top;
+      if (spaceBelow < estimatedHeight + 8 && spaceAbove > spaceBelow) {
+        openUp = true;
+      }
+    }
+    _openUp = openUp;
+
+    _portalController.show();
+    _animCtrl.forward();
+    setState(() {
+      _isOpen = true;
+      _triggerActive = true;
+    });
+  }
+
+  void _close() {
+    _animCtrl.reverse().then((_) {
+      if (!mounted) return;
+      _portalController.hide();
+      setState(() => _triggerActive = false);
+    });
+    setState(() => _isOpen = false);
+  }
+
+  void _select(KasyDropDownItem<T> item) {
+    if (!item.enabled) return;
+    widget.onChanged?.call(item.value);
+    _close();
+  }
+
+  // Roughly: item rows (36 each) + panel padding, capped at maxPanelHeight.
+  double _estimatedPanelHeight() {
+    const double rowHeight = 38;
+    const double panelPadding = KasySpacing.xs * 2;
+    final double raw = widget.items.length * rowHeight + panelPadding;
+    return raw.clamp(0, widget.maxPanelHeight);
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return TapRegion(
+      groupId: _tapGroupId,
+      child: OverlayPortal(
+        controller: _portalController,
+        overlayChildBuilder: _buildOverlay,
+        child: _buildTrigger(context),
+      ),
+    );
+  }
+
+  // ── Trigger ────────────────────────────────────────────────────────────────
+  Widget _buildTrigger(BuildContext context) {
+    final KasyColors c = context.colors;
+    final bool isDisabled = !widget.enabled;
+    final bool hasErrorText =
+        widget.errorText != null && widget.errorText!.isNotEmpty;
+    final bool hasInvalidState = widget.isInvalid || hasErrorText;
+    final String? footerText =
+        hasErrorText ? widget.errorText : widget.description;
+    final Color labelColor = hasInvalidState ? c.error : c.fieldLabel;
+
+    Color dimDisabled(Color base, {double alpha = 0.55}) {
+      if (!isDisabled) return base;
+      return Color.alphaBlend(base.withValues(alpha: alpha), c.surface);
+    }
+
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        if (widget.label != null && widget.label!.trim().isNotEmpty) ...[
+          Padding(
+            padding: const EdgeInsets.only(left: KasySpacing.sm - 2),
+            child: Row(
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                Text(
+                  widget.label!,
+                  style: context.textTheme.bodyMedium?.copyWith(
+                    color: dimDisabled(labelColor),
+                    fontWeight: FontWeight.w500,
+                  ),
+                ),
+                if (widget.showRequiredIndicator)
+                  Text(
+                    ' *',
+                    style: context.textTheme.bodyMedium?.copyWith(
+                      color: c.error,
+                      fontWeight: FontWeight.w500,
+                    ),
+                  ),
+              ],
+            ),
+          ),
+          const SizedBox(height: KasySpacing.xs),
+        ],
+        // Only this rectangle is the popover anchor — label and footer are
+        // siblings so they don't shift the panel's open position.
+        CompositedTransformTarget(
+          link: _layerLink,
+          child: MouseRegion(
+            cursor: widget.enabled
+                ? SystemMouseCursors.click
+                : SystemMouseCursors.basic,
+            child: KasyFocusRing(
+              onActivate: _toggle,
+              borderRadius: BorderRadius.circular(KasyRadius.md),
+              child: GestureDetector(
+                behavior: HitTestBehavior.opaque,
+                onTap: _toggle,
+                child: IgnorePointer(
+                  child: KasyTextField(
+                    key: _fieldKey,
+                    controller: _displayController,
+                    readOnly: true,
+                    enabled: widget.enabled,
+                    hint: widget.hint,
+                    isInvalid: hasInvalidState,
+                    variant: widget.variant,
+                    focusBorder: widget.focusBorder,
+                    forceFocusBorder: widget.focusBorder && _triggerActive,
+                    enableInteractiveSelection: false,
+                    semanticLabel:
+                        widget.semanticLabel ?? widget.label ?? widget.hint,
+                    prefix: widget.leadingIcon == null
+                        ? null
+                        : Icon(widget.leadingIcon, size: KasyIconSize.sm),
+                    suffix: AnimatedRotation(
+                      turns: _isOpen ? 0.5 : 0.0,
+                      duration: const Duration(milliseconds: 160),
+                      child: const Icon(KasyIcons.chevronDown),
+                    ),
+                  ),
+                ),
+              ),
+            ),
+          ),
+        ),
+        if (footerText != null && footerText.isNotEmpty) ...[
+          const SizedBox(height: KasySpacing.xs),
+          Padding(
+            padding: const EdgeInsets.symmetric(horizontal: KasySpacing.sm - 2),
+            child: Text(
+              footerText,
+              style: context.textTheme.bodySmall?.copyWith(
+                color: hasErrorText ? c.error : c.muted,
+              ),
+            ),
+          ),
+        ],
+      ],
+    );
+  }
+
+  // ── Dropdown panel (popover) ─────────────────────────────────────────────────
+  Widget _buildOverlay(BuildContext context) {
+    return TapRegion(
+      groupId: _tapGroupId,
+      onTapOutside: (_) => _close(),
+      child: Stack(
+        children: [
+          CompositedTransformFollower(
+            link: _layerLink,
+            targetAnchor:
+                _openUp ? Alignment.topLeft : Alignment.bottomLeft,
+            followerAnchor:
+                _openUp ? Alignment.bottomLeft : Alignment.topLeft,
+            // 6px gap between trigger and panel.
+            offset: _openUp ? const Offset(0, -6) : const Offset(0, 6),
+            child: FadeTransition(
+              opacity: _fadeAnim,
+              child: ScaleTransition(
+                scale: _scaleAnim,
+                alignment:
+                    _openUp ? Alignment.bottomCenter : Alignment.topCenter,
+                child: _DropDownPanel<T>(
+                  width: _panelWidth,
+                  maxHeight: widget.maxPanelHeight,
+                  items: widget.items,
+                  selectedValue: widget.value,
+                  showSelectedCheck: widget.showSelectedCheck,
+                  onSelected: _select,
+                ),
+              ),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// _DropDownPanel — the floating list surface
+// ─────────────────────────────────────────────────────────────────────────────
+
+class _DropDownPanel<T> extends StatelessWidget {
+  const _DropDownPanel({
+    required this.width,
+    required this.maxHeight,
+    required this.items,
+    required this.selectedValue,
+    required this.showSelectedCheck,
+    required this.onSelected,
+  });
+
+  final double width;
+  final double maxHeight;
+  final List<KasyDropDownItem<T>> items;
+  final T? selectedValue;
+  final bool showSelectedCheck;
+  final ValueChanged<KasyDropDownItem<T>> onSelected;
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyColors c = context.colors;
+
+    return Material(
+      type: MaterialType.transparency,
+      child: Container(
+        width: width,
+        constraints: BoxConstraints(maxHeight: maxHeight),
+        padding: const EdgeInsets.all(KasySpacing.xs),
+        decoration: BoxDecoration(
+          color: c.surface,
+          borderRadius: BorderRadius.circular(KasyRadius.xl),
+          border: Border.all(color: c.outline.withValues(alpha: 0.5)),
+          boxShadow: [
+            BoxShadow(
+              color: Colors.black.withValues(alpha: context.isDark ? 0.45 : 0.12),
+              blurRadius: 28,
+              offset: const Offset(0, 14),
+            ),
+            BoxShadow(
+              color: Colors.black.withValues(alpha: context.isDark ? 0.30 : 0.06),
+              blurRadius: 8,
+              offset: const Offset(0, 2),
+            ),
+          ],
+        ),
+        child: ClipRRect(
+          borderRadius: BorderRadius.circular(KasyRadius.xl - KasySpacing.xs),
+          child: SingleChildScrollView(
+            child: Column(
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                for (final item in items)
+                  _DropDownTile<T>(
+                    item: item,
+                    selected: item.value == selectedValue,
+                    showSelectedCheck: showSelectedCheck,
+                    onTap: () => onSelected(item),
+                  ),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// _DropDownTile — a single option row
+// ─────────────────────────────────────────────────────────────────────────────
+
+class _DropDownTile<T> extends StatelessWidget {
+  const _DropDownTile({
+    required this.item,
+    required this.selected,
+    required this.showSelectedCheck,
+    required this.onTap,
+  });
+
+  final KasyDropDownItem<T> item;
+  final bool selected;
+  final bool showSelectedCheck;
+  final VoidCallback onTap;
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyColors c = context.colors;
+    final bool isDisabled = !item.enabled;
+    final Color foreground = selected ? c.primary : c.onSurface;
+    final Color resolved = isDisabled
+        ? Color.alphaBlend(foreground.withValues(alpha: 0.45), c.surface)
+        : foreground;
+
+    final Widget row = Row(
+      children: [
+        if (item.icon != null) ...[
+          Icon(
+            item.icon,
+            size: KasyIconSize.sm,
+            color: isDisabled
+                ? Color.alphaBlend(c.muted.withValues(alpha: 0.5), c.surface)
+                : (selected ? c.primary : c.muted),
+          ),
+          const SizedBox(width: KasySpacing.smd),
+        ],
+        Expanded(
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              Text(
+                item.label,
+                maxLines: 1,
+                overflow: TextOverflow.ellipsis,
+                style: context.textTheme.bodyMedium?.copyWith(
+                  color: resolved,
+                  fontWeight: selected ? FontWeight.w600 : FontWeight.w500,
+                ),
+              ),
+              if (item.subtitle != null && item.subtitle!.isNotEmpty)
+                Text(
+                  item.subtitle!,
+                  maxLines: 1,
+                  overflow: TextOverflow.ellipsis,
+                  style: context.textTheme.bodySmall?.copyWith(color: c.muted),
+                ),
+            ],
+          ),
+        ),
+        if (selected && showSelectedCheck) ...[
+          const SizedBox(width: KasySpacing.smd),
+          Icon(KasyIcons.check, size: KasyIconSize.sm, color: c.primary),
+        ],
+      ],
+    );
+
+    if (isDisabled) {
+      return Padding(
+        padding: const EdgeInsets.symmetric(
+          horizontal: KasySpacing.smd,
+          vertical: 6,
+        ),
+        child: row,
+      );
+    }
+
+    return KasyHover(
+      onTap: onTap,
+      focusable: true,
+      semanticLabel: item.label,
+      borderRadius: BorderRadius.circular(KasyRadius.rounded2_5xl),
+      hoverColor: selected ? c.accentSoft : c.surfaceSecondary,
+      pressColor: c.primary,
+      padding: const EdgeInsets.symmetric(
+        horizontal: KasySpacing.smd,
+        vertical: 6,
+      ),
+      child: ConstrainedBox(
+        constraints: const BoxConstraints(minHeight: 24),
+        child: Align(alignment: Alignment.centerLeft, child: row),
+      ),
+    );
+  }
+}