kasy-cli 1.39.1 → 1.40.0

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

@@ -0,0 +1,902 @@
+import 'package:flutter/material.dart';
+import 'package:kasy_kit/components/kasy_bottom_sheet.dart';
+import 'package:kasy_kit/components/kasy_popover.dart';
+import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_hover.dart';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KasyMenu — design-system action menu (HeroUI "Dropdown" / Menu).
+//
+// A list of contextual actions presented in a floating panel. Mirrors the
+// HeroUI Menu anatomy and reuses the visual language of [KasyDropDown] (panel
+// radius, item radius, 14px medium labels, selected check, "Danger zone"
+// grouping) so the kit stays consistent.
+//
+// Anatomy:
+//   • KasyMenuItem    — one actionable row: prefix icon (or selection check),
+//                       title, optional description, optional suffix (keyboard
+//                       shortcut / submenu chevron / custom), tone (initial |
+//                       danger), selected / disabled states, optional submenu.
+//   • KasyMenuSection — a group of items with an optional muted label; sections
+//                       are separated by a divider (e.g. "Actions"/"Danger zone").
+//   • KasyMenu        — the chrome-less panel that stacks sections. The floating
+//                       surface (border, shadow, scroll) is supplied by the
+//                       presenter, so the menu never double-draws a card.
+//
+// Present it with [showKasyMenu]. By default the presentation adapts to the
+// platform (popover on desktop, bottom sheet on mobile), but it can be forced
+// either way with [KasyMenuPresentation]. Items can close the menu on tap or
+// stay open ([closeOnSelect]).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Visual type of a [KasyMenuItem] (HeroUI: Initial | Danger).
+enum KasyMenuItemTone {
+  /// Default neutral action.
+  initial,
+
+  /// Destructive / irreversible action (delete, remove) — rendered in the error
+  /// color. Use sparingly, in its own ("Danger zone") [KasyMenuSection].
+  danger,
+}
+
+/// Row density. [compact] matches the HeroUI desktop spec (36px rows, 14px
+/// labels, 16px icons); [comfortable] enlarges rows for touch on mobile.
+enum KasyMenuDensity { compact, comfortable }
+
+/// Selection indicator a [KasyMenuSection] draws for its selected items.
+enum KasyMenuSelectionMode {
+  /// Plain action items — no selection indicator.
+  none,
+
+  /// One choice at a time — the selected item shows a filled radio dot.
+  single,
+
+  /// Several choices at once — each selected item shows a check.
+  multiple,
+}
+
+/// How [showKasyMenu] presents the menu.
+enum KasyMenuPresentation {
+  /// Popover anchored to the trigger on desktop, bottom sheet on mobile.
+  auto,
+
+  /// Always a popover anchored to the trigger (both platforms).
+  popover,
+
+  /// Always a bottom sheet sliding up from the bottom (both platforms).
+  bottomSheet,
+}
+
+/// One actionable row in a [KasyMenu].
+class KasyMenuItem {
+  /// Main action label (required).
+  final String title;
+
+  /// Optional supporting line beneath the title (muted).
+  final String? description;
+
+  /// Optional leading icon (HeroUI "Prefix"). Omitted on selectable items, where
+  /// the prefix slot shows a check for the selected row instead.
+  final IconData? icon;
+
+  /// Optional keyboard shortcut shown as a trailing chip (HeroUI "Kbd"), e.g.
+  /// '⌘ B'. Ignored when [trailing] or [submenu] is set.
+  final String? shortcut;
+
+  /// Optional custom trailing widget (HeroUI "Suffix"). Overrides [shortcut].
+  final Widget? trailing;
+
+  /// Initial (neutral) or danger (destructive) styling.
+  final KasyMenuItemTone tone;
+
+  /// Marks the row as the current selection (primary label + leading check).
+  final bool selected;
+
+  /// When false the row is dimmed and not tappable.
+  final bool enabled;
+
+  /// When set, the row opens a nested menu instead of acting; a trailing chevron
+  /// is shown. Opens as a side popover on desktop, a nested sheet on mobile.
+  final List<KasyMenuSection>? submenu;
+
+  /// Whether tapping this row closes the menu. Null inherits the menu-level
+  /// [KasyMenu.closeOnSelect]. Set false for toggles that keep the menu open.
+  final bool? closeOnSelect;
+
+  /// Invoked when the row is tapped (after the menu closes, if it closes).
+  final VoidCallback? onTap;
+
+  const KasyMenuItem({
+    required this.title,
+    this.description,
+    this.icon,
+    this.shortcut,
+    this.trailing,
+    this.tone = KasyMenuItemTone.initial,
+    this.selected = false,
+    this.enabled = true,
+    this.submenu,
+    this.closeOnSelect,
+    this.onTap,
+  });
+}
+
+/// A labelled group of [KasyMenuItem]s. Sections are divided from each other so
+/// destructive actions can sit in their own ("Danger zone") group.
+class KasyMenuSection {
+  /// Optional muted group header (HeroUI "Groups", e.g. "Actions").
+  final String? label;
+
+  /// Selection indicator for this group's selected items (check vs radio dot).
+  final KasyMenuSelectionMode selectionMode;
+  final List<KasyMenuItem> items;
+
+  const KasyMenuSection({
+    this.label,
+    this.selectionMode = KasyMenuSelectionMode.none,
+    required this.items,
+  });
+}
+
+/// The chrome-less menu panel: stacks [sections] with group labels and dividers.
+/// Wrap it in a floating surface to display (the presenters do this for you).
+class KasyMenu extends StatelessWidget {
+  final List<KasyMenuSection> sections;
+  final KasyMenuDensity density;
+
+  /// Whether tapping a row closes the menu by default (rows can override).
+  final bool closeOnSelect;
+
+  /// How to dismiss the menu when a row closes it. [KasyMenuAnchor] passes its
+  /// own close (it lives in an overlay, not a route); when null the menu assumes
+  /// it's a route and pops the navigator (the [showKasyMenu] popover / sheet).
+  final VoidCallback? onClose;
+
+  /// Shared [TapRegion] group of the presenter. A submenu flyout joins this
+  /// group so tapping inside it counts as "inside" the menu and never dismisses
+  /// the parent. Null for a route-based menu (the route's barrier handles taps).
+  final Object? tapGroupId;
+
+  const KasyMenu({
+    super.key,
+    required this.sections,
+    this.density = KasyMenuDensity.compact,
+    this.closeOnSelect = true,
+    this.onClose,
+    this.tapGroupId,
+  });
+
+  /// Convenience for a single ungrouped menu.
+  factory KasyMenu.items(
+    List<KasyMenuItem> items, {
+    Key? key,
+    KasyMenuDensity density = KasyMenuDensity.compact,
+    bool closeOnSelect = true,
+    VoidCallback? onClose,
+    Object? tapGroupId,
+  }) =>
+      KasyMenu(
+        key: key,
+        sections: [KasyMenuSection(items: items)],
+        density: density,
+        closeOnSelect: closeOnSelect,
+        onClose: onClose,
+        tapGroupId: tapGroupId,
+      );
+
+  @override
+  Widget build(BuildContext context) {
+    final bool compact = density == KasyMenuDensity.compact;
+    final List<Widget> children = [];
+
+    for (int s = 0; s < sections.length; s++) {
+      final KasyMenuSection section = sections[s];
+      // Reserve the prefix slot for every row in the group when any row carries
+      // an icon or a selection indicator, so labels stay aligned (HeroUI).
+      final bool reserveLeading =
+          section.selectionMode != KasyMenuSelectionMode.none ||
+          section.items.any((i) => i.icon != null || i.selected);
+      if (s > 0) children.add(_MenuDivider());
+      final String? label = section.label;
+      if (label != null && label.trim().isNotEmpty) {
+        children.add(_MenuGroupLabel(label: label, compact: compact));
+      }
+      for (final KasyMenuItem item in section.items) {
+        children.add(
+          _MenuItemRow(
+            item: item,
+            compact: compact,
+            reserveLeading: reserveLeading,
+            selectionMode: section.selectionMode,
+            menuCloseOnSelect: closeOnSelect,
+            onClose: onClose,
+            tapGroupId: tapGroupId,
+          ),
+        );
+      }
+    }
+
+    return Padding(
+      // HeroUI: 4px panel inset so a hovered row's rounded fill never touches
+      // the panel edge.
+      padding: const EdgeInsets.all(KasySpacing.xs),
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        crossAxisAlignment: CrossAxisAlignment.stretch,
+        children: children,
+      ),
+    );
+  }
+}
+
+/// Presents [sections] as a [KasyMenu].
+///
+/// [presentation] picks the form. The default — [KasyMenuPresentation.popover] —
+/// shows a floating menu anchored to [anchorContext] on every platform (mobile
+/// and desktop). Opt into [bottomSheet] to slide it up from the bottom instead,
+/// or [auto] to adapt per platform (popover on desktop, bottom sheet on mobile).
+/// [closeOnSelect] is the default for whether tapping a row dismisses the menu.
+Future<T?> showKasyMenu<T>({
+  required BuildContext context,
+  required List<KasyMenuSection> sections,
+  BuildContext? anchorContext,
+  KasyPopoverAlign desktopAlign = KasyPopoverAlign.start,
+  KasyPopoverPlacement placement = KasyPopoverPlacement.bottom,
+  double desktopWidth = 240,
+  KasyMenuPresentation presentation = KasyMenuPresentation.popover,
+  bool closeOnSelect = true,
+}) {
+  final bool asPopover = switch (presentation) {
+    KasyMenuPresentation.auto => kasySheetUsesDialog(context),
+    KasyMenuPresentation.popover => true,
+    KasyMenuPresentation.bottomSheet => false,
+  };
+
+  if (asPopover) {
+    return showKasyPopover<T>(
+      anchorContext: anchorContext ?? context,
+      align: desktopAlign,
+      placement: placement,
+      width: desktopWidth,
+      builder: (_) => KasyMenu(sections: sections, closeOnSelect: closeOnSelect),
+    );
+  }
+
+  final bool dark = Theme.of(context).brightness == Brightness.dark;
+  return showModalBottomSheet<T>(
+    context: context,
+    useRootNavigator: true,
+    backgroundColor: Colors.transparent,
+    barrierColor: Colors.black.withValues(alpha: dark ? 0.6 : 0.45),
+    // Same compact, elegant menu — only the container changes (sheet vs popover).
+    // The bottom sheet must NOT enlarge the rows.
+    builder: (_) => KasySheetSurface(
+      child: KasyMenu(sections: sections, closeOnSelect: closeOnSelect),
+    ),
+  );
+}
+
+/// Declarative trigger that opens a [KasyMenu] glued to itself.
+///
+/// The panel is centered on the trigger and hangs just below it, flipping to
+/// hang above when there isn't room. It rides a [LayerLink] +
+/// [CompositedTransformFollower] hosted by an [OverlayPortal] (the [KasyDropDown]
+/// mechanism): the panel is pinned to the trigger at the compositor level, so it
+/// stays glued even under an ancestor that scales or offsets the subtree (the
+/// device-preview frame, an animated page), and the framework owns the overlay's
+/// lifecycle so there's no manual entry juggling to corrupt the element tree.
+///
+/// [builder] renders the trigger and receives an `open` callback to wire to its
+/// tap. Set [presentation] to [KasyMenuPresentation.bottomSheet] to slide the
+/// menu up from the bottom instead of anchoring it.
+class KasyMenuAnchor extends StatefulWidget {
+  final List<KasyMenuSection> sections;
+
+  /// Builds the trigger; call `open` to show the menu.
+  final Widget Function(BuildContext context, VoidCallback open) builder;
+  final double width;
+  final bool closeOnSelect;
+  final KasyMenuPresentation presentation;
+
+  const KasyMenuAnchor({
+    super.key,
+    required this.sections,
+    required this.builder,
+    this.width = 240,
+    this.closeOnSelect = true,
+    this.presentation = KasyMenuPresentation.popover,
+  });
+
+  @override
+  State<KasyMenuAnchor> createState() => _KasyMenuAnchorState();
+}
+
+class _KasyMenuAnchorState extends State<KasyMenuAnchor>
+    with SingleTickerProviderStateMixin {
+  // LayerLink glues the panel to the trigger at the compositor level, so it
+  // can't drift even under the device-preview frame's scale/offset. OverlayPortal
+  // hosts the panel declaratively — the framework owns its element lifecycle, so
+  // there's no manual insert/remove that can corrupt the element tree.
+  final LayerLink _link = LayerLink();
+  final OverlayPortalController _portal = OverlayPortalController();
+  // Groups trigger + panel so a tap on either counts as "inside" for TapRegion.
+  final Object _tapGroupId = Object();
+
+  late final AnimationController _anim;
+  late final Animation<double> _fade;
+  late final Animation<double> _scale;
+
+  // Whether the panel hangs above the trigger (no room below), set at open time.
+  bool _openUp = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _anim = AnimationController(
+      vsync: this,
+      duration: const Duration(milliseconds: 160),
+    );
+    _fade = CurvedAnimation(parent: _anim, curve: Curves.easeOut);
+    _scale = Tween<double>(begin: 0.96, end: 1.0).animate(
+      CurvedAnimation(parent: _anim, curve: Curves.easeOutCubic),
+    );
+  }
+
+  @override
+  void dispose() {
+    _anim.dispose();
+    super.dispose();
+  }
+
+  void _open() {
+    if (widget.presentation == KasyMenuPresentation.bottomSheet) {
+      _openSheet();
+      return;
+    }
+    setState(() => _openUp = _resolveOpenUp());
+    _portal.show();
+    _anim.forward(from: 0);
+  }
+
+  // Decide the open direction only. Position is handled by the LayerLink, so a
+  // slightly-off estimate just flips the menu — it always stays glued. Measured
+  // in the overlay's space (where the panel draws) to stay consistent.
+  bool _resolveOpenUp() {
+    final RenderBox? box = context.findRenderObject() as RenderBox?;
+    final RenderBox? overlayBox =
+        Overlay.of(context).context.findRenderObject() as RenderBox?;
+    if (box == null || overlayBox == null) return false;
+    final Offset topLeft = box.localToGlobal(Offset.zero, ancestor: overlayBox);
+    final double spaceBelow =
+        overlayBox.size.height - (topLeft.dy + box.size.height);
+    final double spaceAbove = topLeft.dy;
+    return spaceBelow < _estimatedHeight() + 8 && spaceAbove > spaceBelow;
+  }
+
+  Future<void> _openSheet() {
+    final bool dark = Theme.of(context).brightness == Brightness.dark;
+    return showModalBottomSheet<void>(
+      context: context,
+      useRootNavigator: true,
+      backgroundColor: Colors.transparent,
+      barrierColor: Colors.black.withValues(alpha: dark ? 0.6 : 0.45),
+      builder: (_) => KasySheetSurface(
+        child: KasyMenu(
+          sections: widget.sections,
+          closeOnSelect: widget.closeOnSelect,
+        ),
+      ),
+    );
+  }
+
+  void _close() {
+    _anim.reverse().then((_) {
+      if (mounted) _portal.hide();
+    });
+  }
+
+  // Rough panel height (rows + labels + dividers + padding), enough to decide
+  // the flip — the real layout still clamps to the viewport.
+  double _estimatedHeight() {
+    double h = KasySpacing.xs * 2;
+    for (int s = 0; s < widget.sections.length; s++) {
+      final KasyMenuSection section = widget.sections[s];
+      if (s > 0) h += 17;
+      final String? label = section.label;
+      if (label != null && label.trim().isNotEmpty) h += 28;
+      for (final KasyMenuItem item in section.items) {
+        final bool hasDesc =
+            item.description != null && item.description!.isNotEmpty;
+        h += hasDesc ? 52 : 40;
+      }
+    }
+    return h;
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return TapRegion(
+      groupId: _tapGroupId,
+      child: OverlayPortal(
+        controller: _portal,
+        overlayChildBuilder: _buildOverlay,
+        child: CompositedTransformTarget(
+          link: _link,
+          child: widget.builder(context, _open),
+        ),
+      ),
+    );
+  }
+
+  Widget _buildOverlay(BuildContext context) {
+    // Center the panel on the trigger (bottom-center → top-center), or flip to
+    // hang above. The LayerLink does the positioning; we only pick the anchors.
+    final Alignment target = _openUp
+        ? Alignment.topCenter
+        : Alignment.bottomCenter;
+    final Alignment follower = _openUp
+        ? Alignment.bottomCenter
+        : Alignment.topCenter;
+    final Offset offset = _openUp ? const Offset(0, -6) : const Offset(0, 6);
+    final Size viewport = MediaQuery.sizeOf(context);
+
+    return TapRegion(
+      groupId: _tapGroupId,
+      onTapOutside: (_) => _close(),
+      child: Stack(
+        children: [
+          CompositedTransformFollower(
+            link: _link,
+            targetAnchor: target,
+            followerAnchor: follower,
+            offset: offset,
+            child: FadeTransition(
+              opacity: _fade,
+              child: ScaleTransition(
+                scale: _scale,
+                alignment: follower,
+                child: KasyPopoverSurface(
+                  width: widget.width,
+                  maxHeight: viewport.height * 0.8,
+                  child: KasyMenu(
+                    sections: widget.sections,
+                    closeOnSelect: widget.closeOnSelect,
+                    onClose: _close,
+                    tapGroupId: _tapGroupId,
+                  ),
+                ),
+              ),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+// ── Internals ────────────────────────────────────────────────────────────────
+
+/// Side a submenu flyout opens toward, or [none] when neither side has room (the
+/// row then presents its submenu as a sheet instead of a clipped flyout).
+enum _FlyoutSide { left, right, none }
+
+class _MenuGroupLabel extends StatelessWidget {
+  final String label;
+  final bool compact;
+
+  const _MenuGroupLabel({required this.label, required this.compact});
+
+  @override
+  Widget build(BuildContext context) {
+    return Padding(
+      // HeroUI: pt 10 / pb 4 / px 12 for group headers.
+      padding: EdgeInsets.fromLTRB(
+        KasySpacing.smd,
+        compact ? 10 : KasySpacing.smd,
+        KasySpacing.smd,
+        KasySpacing.xs,
+      ),
+      child: Align(
+        alignment: Alignment.centerLeft,
+        child: Text(
+          label,
+          style: context.textTheme.bodySmall?.copyWith(
+            color: context.colors.muted,
+            fontWeight: FontWeight.w500,
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+class _MenuDivider extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Padding(
+      padding: const EdgeInsets.symmetric(
+        horizontal: KasySpacing.smd,
+        vertical: KasySpacing.xs,
+      ),
+      child: Container(
+        height: 1,
+        color: context.colors.onSurface.withValues(alpha: 0.08),
+      ),
+    );
+  }
+}
+
+/// Trailing keyboard shortcut (HeroUI "Kbd", light variant). No filled pill —
+/// just the muted command glyphs, as the Figma menu uses.
+class _MenuShortcut extends StatelessWidget {
+  final String label;
+  final bool compact;
+
+  const _MenuShortcut({required this.label, required this.compact});
+
+  @override
+  Widget build(BuildContext context) {
+    return Text(
+      label,
+      style:
+          (compact ? context.textTheme.bodyMedium : context.textTheme.bodyLarge)
+              ?.copyWith(
+        color: context.colors.muted,
+        fontWeight: FontWeight.w500,
+      ),
+    );
+  }
+}
+
+class _MenuItemRow extends StatefulWidget {
+  final KasyMenuItem item;
+  final bool compact;
+  final bool reserveLeading;
+  final KasyMenuSelectionMode selectionMode;
+  final bool menuCloseOnSelect;
+  final VoidCallback? onClose;
+
+  /// Shared [TapRegion] group (from the presenter), so this row's submenu flyout
+  /// is "inside" the menu and doesn't dismiss the parent when tapped.
+  final Object? tapGroupId;
+
+  const _MenuItemRow({
+    required this.item,
+    required this.compact,
+    required this.reserveLeading,
+    required this.selectionMode,
+    required this.menuCloseOnSelect,
+    this.onClose,
+    this.tapGroupId,
+  });
+
+  @override
+  State<_MenuItemRow> createState() => _MenuItemRowState();
+}
+
+class _MenuItemRowState extends State<_MenuItemRow>
+    with SingleTickerProviderStateMixin {
+  // Submenu flyout machinery — created only when the row has a submenu. It rides
+  // the same LayerLink + OverlayPortal mechanism as [KasyMenuAnchor] so the
+  // nested menu stays glued to this row (compositor level) and opens to its
+  // side, like a desktop cascade, even inside the scaled device-preview frame.
+  static const double _submenuWidth = 224;
+  final LayerLink _link = LayerLink();
+  final OverlayPortalController _portal = OverlayPortalController();
+  AnimationController? _anim;
+  // Assigned in initState only for submenu rows; read only from the submenu
+  // overlay, which exists solely on that path.
+  late final Animation<double> _fade;
+  late final Animation<double> _scale;
+
+  // Whether the flyout opens to the left of the row (no room on the right).
+  bool _openLeft = false;
+
+  bool get _hasSubmenu => widget.item.submenu != null;
+
+  @override
+  void initState() {
+    super.initState();
+    if (_hasSubmenu) {
+      _anim = AnimationController(
+        vsync: this,
+        duration: const Duration(milliseconds: 150),
+      );
+      _fade = CurvedAnimation(parent: _anim!, curve: Curves.easeOut);
+      _scale = Tween<double>(begin: 0.96, end: 1.0).animate(
+        CurvedAnimation(parent: _anim!, curve: Curves.easeOutCubic),
+      );
+    }
+  }
+
+  @override
+  void dispose() {
+    _anim?.dispose();
+    super.dispose();
+  }
+
+  void _openSubmenu() {
+    final _FlyoutSide side = _resolveSide();
+    if (side == _FlyoutSide.none) {
+      // No room for a side cascade (narrow phone): a 224px panel won't fit
+      // beside the menu, so present the nested menu as a sheet instead of a
+      // flyout clipped off-screen. The cascade still shows on wider layouts.
+      _openSubmenuSheet();
+      return;
+    }
+    setState(() => _openLeft = side == _FlyoutSide.left);
+    _portal.show();
+    _anim!.forward(from: 0);
+  }
+
+  void _closeSubmenu() {
+    _anim!.reverse().then((_) {
+      if (mounted) _portal.hide();
+    });
+  }
+
+  Future<void> _openSubmenuSheet() {
+    final bool dark = Theme.of(context).brightness == Brightness.dark;
+    return showModalBottomSheet<void>(
+      context: context,
+      useRootNavigator: true,
+      backgroundColor: Colors.transparent,
+      barrierColor: Colors.black.withValues(alpha: dark ? 0.6 : 0.45),
+      builder: (_) => KasySheetSurface(
+        child: KasyMenu(
+          sections: widget.item.submenu!,
+          closeOnSelect: widget.menuCloseOnSelect,
+          // A row that closes the menu pops this sheet, then bubbles the close
+          // up so the parent chain dismisses too.
+          onClose: () {
+            Navigator.of(context, rootNavigator: true).pop();
+            _bubbleClose();
+          },
+        ),
+      ),
+    );
+  }
+
+  // Pick the side with room for the flyout, or [none] when neither fits (the
+  // caller then falls back to a sheet). Position is the LayerLink's job — this
+  // only decides the side, measured in the overlay's space.
+  _FlyoutSide _resolveSide() {
+    final RenderBox? box = context.findRenderObject() as RenderBox?;
+    final RenderBox? overlayBox =
+        Overlay.of(context).context.findRenderObject() as RenderBox?;
+    if (box == null || overlayBox == null) return _FlyoutSide.right;
+    final Offset topLeft = box.localToGlobal(Offset.zero, ancestor: overlayBox);
+    final double spaceRight =
+        overlayBox.size.width - (topLeft.dx + box.size.width);
+    final double spaceLeft = topLeft.dx;
+    const double needed = _submenuWidth + 12;
+    if (spaceRight >= needed) return _FlyoutSide.right;
+    if (spaceLeft >= needed) return _FlyoutSide.left;
+    return _FlyoutSide.none;
+  }
+
+  void _handleTap() {
+    if (_hasSubmenu) {
+      if (_portal.isShowing) {
+        _closeSubmenu();
+      } else {
+        _openSubmenu();
+      }
+      return;
+    }
+    // Close first (mirrors the call-site ordering that avoids a Navigator lock
+    // when the action triggers a rebuild), then run the action. An overlay-based
+    // menu ([KasyMenuAnchor]) supplies onClose; a route-based one pops itself.
+    final bool close = widget.item.closeOnSelect ?? widget.menuCloseOnSelect;
+    if (close) {
+      _bubbleClose();
+    }
+    widget.item.onTap?.call();
+  }
+
+  // Dismiss the whole menu chain. Overlay-based menus pass an onClose; a
+  // route-based menu pops the navigator itself.
+  void _bubbleClose() {
+    if (widget.onClose != null) {
+      widget.onClose!();
+    } else {
+      Navigator.of(context, rootNavigator: true).pop();
+    }
+  }
+
+  // Given to the submenu: when one of its rows closes the menu, fold the flyout
+  // away and bubble the close up so the entire chain dismisses together.
+  void _closeChain() {
+    if (_portal.isShowing) _closeSubmenu();
+    _bubbleClose();
+  }
+
+  Widget _buildSubmenuOverlay(BuildContext context) {
+    // Anchor the flyout to this row's side: right edge → left edge (or mirrored
+    // when flipped). Nudge up by the panel inset so the first submenu row lines
+    // up with the tapped row. The LayerLink does the positioning.
+    final Alignment target = _openLeft ? Alignment.topLeft : Alignment.topRight;
+    final Alignment follower =
+        _openLeft ? Alignment.topRight : Alignment.topLeft;
+    final Offset offset = _openLeft
+        ? const Offset(-KasySpacing.xs, -KasySpacing.xs)
+        : const Offset(KasySpacing.xs, -KasySpacing.xs);
+    final Size viewport = MediaQuery.sizeOf(context);
+
+    return TapRegion(
+      groupId: widget.tapGroupId,
+      onTapOutside: (_) => _closeSubmenu(),
+      child: Stack(
+        children: [
+          CompositedTransformFollower(
+            link: _link,
+            targetAnchor: target,
+            followerAnchor: follower,
+            offset: offset,
+            child: FadeTransition(
+              opacity: _fade,
+              child: ScaleTransition(
+                scale: _scale,
+                alignment: follower,
+                child: KasyPopoverSurface(
+                  width: _submenuWidth,
+                  maxHeight: viewport.height * 0.8,
+                  child: KasyMenu(
+                    sections: widget.item.submenu!,
+                    closeOnSelect: widget.menuCloseOnSelect,
+                    onClose: _closeChain,
+                    tapGroupId: widget.tapGroupId,
+                  ),
+                ),
+              ),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyMenuItem item = widget.item;
+    final bool compact = widget.compact;
+    final KasyMenuSelectionMode selectionMode = widget.selectionMode;
+    final KasyColors c = context.colors;
+    final bool disabled = !item.enabled;
+    final bool danger = item.tone == KasyMenuItemTone.danger;
+
+    final Color baseColor = danger ? c.error : c.onSurface;
+    final Color fg = item.selected ? c.primary : baseColor;
+    final Color resolvedFg = disabled
+        ? Color.alphaBlend(fg.withValues(alpha: 0.45), c.surface)
+        : fg;
+    final Color leadColor = item.selected
+        ? c.primary
+        : (danger ? c.error : c.muted);
+    final Color resolvedLead = disabled
+        ? Color.alphaBlend(leadColor.withValues(alpha: 0.45), c.surface)
+        : leadColor;
+
+    final double iconSize = compact ? KasyIconSize.sm : KasyIconSize.lg;
+    final double iconGap = compact ? KasySpacing.smd : KasySpacing.sm;
+    final EdgeInsets itemPadding = EdgeInsets.symmetric(
+      horizontal: KasySpacing.smd,
+      vertical: compact ? 6 : KasySpacing.smd,
+    );
+
+    final TextStyle? titleStyle =
+        (compact ? context.textTheme.bodyMedium : context.textTheme.bodyLarge)
+            ?.copyWith(
+      color: resolvedFg,
+      fontWeight: item.selected ? FontWeight.w600 : FontWeight.w500,
+    );
+
+    // Prefix slot: an icon, a selection indicator (check for multi-select, a
+    // filled dot for single-select), or reserved empty space so the group's
+    // labels stay aligned.
+    Widget? leading;
+    if (item.icon != null) {
+      leading = Icon(item.icon, size: iconSize, color: resolvedLead);
+    } else if (item.selected) {
+      leading = selectionMode == KasyMenuSelectionMode.single
+          ? SizedBox(
+              width: iconSize,
+              height: iconSize,
+              child: Center(
+                child: Container(
+                  width: 7,
+                  height: 7,
+                  decoration: BoxDecoration(
+                    color: c.primary,
+                    shape: BoxShape.circle,
+                  ),
+                ),
+              ),
+            )
+          : Icon(KasyIcons.check, size: iconSize, color: c.primary);
+    } else if (widget.reserveLeading) {
+      leading = SizedBox(width: iconSize);
+    }
+
+    // Suffix slot: submenu chevron, custom trailing, or a shortcut chip.
+    Widget? trailing;
+    if (item.submenu != null) {
+      trailing = Icon(
+        KasyIcons.chevronRight,
+        size: KasyIconSize.sm,
+        color: resolvedLead,
+      );
+    } else if (item.trailing != null) {
+      trailing = item.trailing;
+    } else if (item.shortcut != null) {
+      trailing = _MenuShortcut(label: item.shortcut!, compact: compact);
+    }
+
+    final bool hasDescription =
+        item.description != null && item.description!.isNotEmpty;
+    // With a description the row is two lines; align the icon and shortcut to the
+    // title line (a 2px nudge centers a 16px glyph on the 20px title), as the
+    // HeroUI menu does. Single-line rows stay vertically centered.
+    Widget alignToTitle(Widget w) => hasDescription
+        ? Padding(padding: const EdgeInsets.only(top: 2), child: w)
+        : w;
+
+    final Widget row = Row(
+      crossAxisAlignment: hasDescription
+          ? CrossAxisAlignment.start
+          : CrossAxisAlignment.center,
+      children: [
+        if (leading != null) ...[
+          alignToTitle(leading),
+          SizedBox(width: iconGap),
+        ],
+        Expanded(
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              Text(item.title, style: titleStyle),
+              if (hasDescription)
+                Text(
+                  item.description!,
+                  style: context.textTheme.bodySmall?.copyWith(color: c.muted),
+                ),
+            ],
+          ),
+        ),
+        if (trailing != null) ...[
+          SizedBox(width: iconGap),
+          alignToTitle(trailing),
+        ],
+      ],
+    );
+
+    if (disabled) {
+      return Padding(padding: itemPadding, child: row);
+    }
+
+    final Widget hover = KasyHover(
+      onTap: _handleTap,
+      focusable: true,
+      semanticLabel: item.title,
+      focusGapColor: c.surface,
+      borderRadius: BorderRadius.circular(KasyRadius.rounded2_5xl),
+      hoverColor: item.selected ? c.accentSoft : c.surfaceSecondary,
+      pressColor: danger ? c.error : c.primary,
+      padding: itemPadding,
+      child: ConstrainedBox(
+        constraints: BoxConstraints(minHeight: compact ? 24 : 32),
+        child: Align(alignment: Alignment.centerLeft, child: row),
+      ),
+    );
+
+    // A plain row needs no overlay machinery. A submenu row hosts its flyout
+    // through an OverlayPortal and links the panel to itself for side anchoring.
+    if (!_hasSubmenu) return hover;
+    return OverlayPortal(
+      controller: _portal,
+      overlayChildBuilder: _buildSubmenuOverlay,
+      child: CompositedTransformTarget(link: _link, child: hover),
+    );
+  }
+}