kasy-cli 1.39.1 → 1.40.0

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

@@ -0,0 +1,267 @@
+import 'package:flutter/material.dart';
+import 'package:kasy_kit/core/theme/theme.dart';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KasyPopover — desktop-native counterpart to a mobile menu bottom sheet.
+//
+// Instead of dimming the whole screen and dropping a centered card (what a
+// bottom sheet "adapted" to desktop does), a popover opens right next to the
+// control the user clicked, like a native desktop menu. Position is computed
+// from the trigger's render box — no LayerLink wiring at the call site — so any
+// `onTap` that still has the trigger's BuildContext can anchor one. It flips
+// above the trigger when there's no room below, clamps to the viewport, and
+// dismisses on tap-outside / Esc.
+//
+// Used by [showKasyMenuSheet] (see kasy_bottom_sheet.dart) as the desktop form
+// of a menu sheet; callers normally go through that, not this directly.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Horizontal anchoring of the popover panel relative to its trigger.
+enum KasyPopoverAlign {
+  /// Panel's left edge aligns with the trigger's left edge.
+  start,
+
+  /// Panel's right edge aligns with the trigger's right edge (menus that hang
+  /// off a right-aligned value, e.g. a settings row).
+  end,
+
+  /// Panel is centered horizontally on the trigger.
+  center,
+}
+
+/// Side of the trigger the popover opens toward. Each side flips to its opposite
+/// when there isn't room (e.g. [bottom] flips to top near the screen edge).
+enum KasyPopoverPlacement { bottom, top, left, right }
+
+const double _kPopoverDefaultWidth = 220;
+const double _kPopoverGap = 6;
+const double _kViewportMargin = 8;
+
+// Below this much room on the chosen side we consider flipping to the opposite.
+const double _kFlipThreshold = 220;
+
+/// Presents [builder] as a floating panel anchored to the widget that owns
+/// [anchorContext] (the control the user clicked). The content is wrapped in a
+/// [KasyPopoverSurface] automatically, so [builder] returns the bare menu body.
+///
+/// [placement] picks the side it opens toward (default below the trigger);
+/// [align] sets cross-axis alignment for top/bottom placements. Pop the panel
+/// with a value (`Navigator.pop(context, value)`) to return it through the
+/// future, mirroring [showModalBottomSheet].
+Future<T?> showKasyPopover<T>({
+  required BuildContext anchorContext,
+  required WidgetBuilder builder,
+  KasyPopoverAlign align = KasyPopoverAlign.start,
+  KasyPopoverPlacement placement = KasyPopoverPlacement.bottom,
+  double width = _kPopoverDefaultWidth,
+  double gap = _kPopoverGap,
+}) {
+  // Snapshot the trigger geometry at open time (global coords). A transient menu
+  // doesn't need to follow scroll — tap-outside closes it.
+  final RenderBox? anchorBox = anchorContext.findRenderObject() as RenderBox?;
+  final Size viewport = MediaQuery.sizeOf(anchorContext);
+  final Offset anchorTopLeft =
+      anchorBox?.localToGlobal(Offset.zero) ??
+      Offset(viewport.width / 2, viewport.height / 2);
+  final Size anchorSize = anchorBox?.size ?? Size.zero;
+
+  return showGeneralDialog<T>(
+    context: anchorContext,
+    barrierDismissible: true,
+    barrierLabel: MaterialLocalizations.of(
+      anchorContext,
+    ).modalBarrierDismissLabel,
+    // No scrim: a desktop popover keeps the page visible behind it.
+    barrierColor: Colors.transparent,
+    transitionDuration: const Duration(milliseconds: 160),
+    pageBuilder: (ctx, animation, _) => _KasyPopoverLayout(
+      anchorTopLeft: anchorTopLeft,
+      anchorSize: anchorSize,
+      width: width,
+      gap: gap,
+      align: align,
+      placement: placement,
+      animation: animation,
+      child: Builder(builder: builder),
+    ),
+    transitionBuilder: (_, _, _, child) => child,
+  );
+}
+
+/// Positions and animates the popover panel over a full-screen, transparent
+/// layer. Resolves [placement] (flipping to the opposite side when room is
+/// tight) and clamps the panel within the viewport.
+class _KasyPopoverLayout extends StatelessWidget {
+  final Offset anchorTopLeft;
+  final Size anchorSize;
+  final double width;
+  final double gap;
+  final KasyPopoverAlign align;
+  final KasyPopoverPlacement placement;
+  final Animation<double> animation;
+  final Widget child;
+
+  const _KasyPopoverLayout({
+    required this.anchorTopLeft,
+    required this.anchorSize,
+    required this.width,
+    required this.gap,
+    required this.align,
+    required this.placement,
+    required this.animation,
+    required this.child,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final Size viewport = MediaQuery.sizeOf(context);
+    final EdgeInsets safe = MediaQuery.viewPaddingOf(context);
+    final double anchorRight = anchorTopLeft.dx + anchorSize.width;
+    final double anchorBottom = anchorTopLeft.dy + anchorSize.height;
+
+    final double spaceBelow = viewport.height - safe.bottom - anchorBottom;
+    final double spaceAbove = anchorTopLeft.dy - safe.top;
+    final double spaceRight = viewport.width - _kViewportMargin - anchorRight;
+    final double spaceLeft = anchorTopLeft.dx - _kViewportMargin;
+
+    // Resolve the effective side, flipping to the opposite when too tight.
+    final KasyPopoverPlacement side = switch (placement) {
+      KasyPopoverPlacement.bottom =>
+        spaceBelow < _kFlipThreshold && spaceAbove > spaceBelow
+            ? KasyPopoverPlacement.top
+            : KasyPopoverPlacement.bottom,
+      KasyPopoverPlacement.top =>
+        spaceAbove < _kFlipThreshold && spaceBelow > spaceAbove
+            ? KasyPopoverPlacement.bottom
+            : KasyPopoverPlacement.top,
+      KasyPopoverPlacement.right =>
+        spaceRight < width + gap && spaceLeft > spaceRight
+            ? KasyPopoverPlacement.left
+            : KasyPopoverPlacement.right,
+      KasyPopoverPlacement.left =>
+        spaceLeft < width + gap && spaceRight > spaceLeft
+            ? KasyPopoverPlacement.right
+            : KasyPopoverPlacement.left,
+    };
+
+    double? left;
+    double? top;
+    double? right;
+    double? bottom;
+    double maxHeight;
+    Alignment scaleAlign;
+
+    final bool vertical =
+        side == KasyPopoverPlacement.bottom || side == KasyPopoverPlacement.top;
+    if (vertical) {
+      left = switch (align) {
+        KasyPopoverAlign.start => anchorTopLeft.dx,
+        KasyPopoverAlign.end => anchorRight - width,
+        KasyPopoverAlign.center =>
+          anchorTopLeft.dx + (anchorSize.width - width) / 2,
+      }.clamp(_kViewportMargin, viewport.width - width - _kViewportMargin);
+      if (side == KasyPopoverPlacement.bottom) {
+        top = anchorBottom + gap;
+        maxHeight = spaceBelow - gap - _kViewportMargin;
+        scaleAlign = Alignment.topCenter;
+      } else {
+        bottom = viewport.height - (anchorTopLeft.dy - gap);
+        maxHeight = spaceAbove - gap - _kViewportMargin;
+        scaleAlign = Alignment.bottomCenter;
+      }
+    } else {
+      // Left / right: align the panel's top with the trigger, clamped so it
+      // never runs past the bottom edge.
+      top = anchorTopLeft.dy.clamp(
+        safe.top + _kViewportMargin,
+        viewport.height - safe.bottom - _kViewportMargin,
+      );
+      maxHeight = viewport.height - safe.bottom - top - _kViewportMargin;
+      if (side == KasyPopoverPlacement.right) {
+        left = anchorRight + gap;
+        scaleAlign = Alignment.centerLeft;
+      } else {
+        right = viewport.width - (anchorTopLeft.dx - gap);
+        scaleAlign = Alignment.centerRight;
+      }
+    }
+
+    final CurvedAnimation curved = CurvedAnimation(
+      parent: animation,
+      curve: Curves.easeOutCubic,
+      reverseCurve: Curves.easeIn,
+    );
+
+    return Stack(
+      children: [
+        Positioned(
+          left: left,
+          top: top,
+          right: right,
+          bottom: bottom,
+          child: FadeTransition(
+            opacity: curved,
+            child: ScaleTransition(
+              scale: Tween<double>(begin: 0.96, end: 1.0).animate(curved),
+              alignment: scaleAlign,
+              child: KasyPopoverSurface(
+                width: width,
+                maxHeight: maxHeight.clamp(0, viewport.height),
+                child: child,
+              ),
+            ),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+/// Floating surface chrome for popover content: design-system surface tone,
+/// fully-rounded corners, hairline border and elevation shadow, with an internal
+/// scroll so tall menus never overflow. Mirrors the dropdown panel look.
+class KasyPopoverSurface extends StatelessWidget {
+  final Widget child;
+  final double width;
+  final double maxHeight;
+
+  const KasyPopoverSurface({
+    super.key,
+    required this.child,
+    this.width = _kPopoverDefaultWidth,
+    this.maxHeight = double.infinity,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final BorderRadius radius = BorderRadius.circular(KasyRadius.xl);
+    return Material(
+      type: MaterialType.transparency,
+      child: Container(
+        width: width,
+        constraints: BoxConstraints(maxHeight: maxHeight),
+        decoration: BoxDecoration(
+          color: context.colors.surface,
+          borderRadius: radius,
+          border: Border.all(
+            color: context.colors.outline.withValues(alpha: 0.22),
+          ),
+          boxShadow: [
+            KasyShadows.component(
+              context,
+              blurRadius: 24,
+              spreadRadius: -2,
+              offset: const Offset(0, 10),
+            ),
+          ],
+        ),
+        child: ClipRRect(
+          borderRadius: radius,
+          child: SingleChildScrollView(
+            child: child,
+          ),
+        ),
+      ),
+    );
+  }
+}

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

@@ -393,6 +393,12 @@ class _KasySidebarState extends State<KasySidebar> {
   /// Viewport width below which the sidebar auto-collapses (tablet breakpoint).
   static const double _kBreakpoint = 1024.0;
 
+  /// Phone breakpoint. Below this the sidebar is always an overlay (drawer or
+  /// full-screen preview), so the logo gets its mobile placement (nudged down,
+  /// band trimmed). Above it the inline rail keeps its divider aligned with the
+  /// page app bar / web header.
+  static const double _kMobileBreakpoint = 768.0;
+
 
   /// True when wired to Bart's navigation (real, tappable screens).
   bool get _connected =>
@@ -982,18 +988,22 @@ class _KasySidebarState extends State<KasySidebar> {
     // border: the web header (68) on desktop, but the shorter KasyAppBar on
     // tablet (medium), where the page keeps its own app bar instead of the
     // header. Without this the line breaks between the rail and the app bar.
-    final bool isCompact = MediaQuery.sizeOf(context).width < _kBreakpoint;
-    // The drawer trims a little off the band so there's less dead space below the
-    // wordmark before the divider (the drawer is an overlay, so its divider has
-    // no app-bar line to stay aligned with).
+    final double viewportWidth = MediaQuery.sizeOf(context).width;
+    final bool isCompact = viewportWidth < _kBreakpoint;
+    // On phones the sidebar is always an overlay (drawer or full-screen preview),
+    // never the inline rail beside a page app bar — so mobile positioning is a
+    // sidebar default keyed off the phone breakpoint, not isDrawer.
+    final bool isMobile = viewportWidth < _kMobileBreakpoint;
+    // Mobile trims a little off the band so there's less dead space below the
+    // wordmark before the divider; the overlay has no app-bar line to align with.
     final double bandHeight = !isCompact
         ? _kTopBandHeight
-        : kasyAppBarBodyTopOverlap(context) - (widget.isDrawer ? 26.0 : 0.0);
-    // In the mobile drawer the band starts right under the status bar notch, so
-    // nudge the wordmark down a touch to breathe. Restricted to the drawer (an
-    // overlay) so the inline rail keeps its divider aligned with the app bar /
-    // web header on tablet and desktop.
-    final double logoTopInset = widget.isDrawer ? 20.0 : 0.0;
+        : kasyAppBarBodyTopOverlap(context) - (isMobile ? 26.0 : 0.0);
+    // On mobile the band starts right under the status bar notch, so nudge the
+    // brand (and the collapsed toggle, which shares this band) down to breathe.
+    // Tablet/desktop keep it centred so the rail's divider stays aligned with the
+    // app bar / web header.
+    final double logoTopInset = isMobile ? 44.0 : 0.0;
     // The collapse toggle is available on every breakpoint so any config can be
     // switched thin↔wide — except a drawer, which is a dismissible overlay you
     // close whole rather than collapse in place.

package/templates/firebase/lib/core/navigation/kasy_route_observer.dart

@@ -0,0 +1,8 @@
+import 'package:flutter/widgets.dart';
+
+/// Shared route observer on the root navigator so screens can react to being
+/// revealed again after a route pushed on top of them pops, via
+/// [RouteAware.didPopNext]. Register it in the router's `observers` list and
+/// subscribe a [RouteAware] state to it.
+final RouteObserver<ModalRoute<dynamic>> kasyRouteObserver =
+    RouteObserver<ModalRoute<dynamic>>();

package/templates/firebase/lib/core/theme/texts.dart

@@ -184,6 +184,31 @@ class KasyTextTheme extends ThemeExtension<KasyTextTheme> {
   /// Caption, hint, version label, footnote. 12 / w400.
   TextStyle get caption => bodySmall;
 
+  // --- Overlay & component roles -----------------------------------------
+  // The harmonic ladder for surfaces and components: an OVERLAY (a full
+  // decision surface — dialog, bottom sheet) carries the largest title (20); an
+  // inline COMPONENT header (alert, accordion) sits a step below (16) so it
+  // reads as a header WITHIN the component, not a screen section; supporting
+  // text everywhere is 14. These are deliberately STABLE across breakpoints —
+  // only page/hero headings scale (Material/Apple model). Route every
+  // dialog/sheet/alert/accordion through these so titles never drift per
+  // component.
+
+  /// Title of a modal/overlay surface (dialog, bottom sheet, OTP sheet).
+  /// 20 / w600 — the largest title tier, for full decision surfaces.
+  TextStyle get overlayTitle => titleLarge;
+
+  /// Header of an inline component (alert, accordion). 16 / w600 — content
+  /// emphasis, one clear step below an overlay/section title and above body, so
+  /// a compact card never wears a screen-section-sized title.
+  TextStyle get componentTitle =>
+      bodyLarge.copyWith(fontWeight: FontWeight.w600);
+
+  /// Supporting text / description inside an overlay or component (the message
+  /// under a dialog/sheet/alert title, an accordion body). 14 / w400. Apply the
+  /// muted colour and any line-height at the call site.
+  TextStyle get supportingText => bodyMedium;
+
   /// Builds the full text theme for a given [device].
   ///
   /// Each slot resolves its size from the responsive [KasyTypeScale] ramp at the

package/templates/firebase/lib/features/home/home_components_page.dart

@@ -2,6 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
 import 'package:kasy_kit/components/kasy_app_bar.dart';
 import 'package:kasy_kit/core/haptics/kasy_haptics.dart';
+import 'package:kasy_kit/core/navigation/kasy_route_observer.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
 import 'package:kasy_kit/core/widgets/kasy_hover.dart';
 import 'package:kasy_kit/core/widgets/kasy_scroll_behavior.dart';
@@ -46,18 +47,34 @@ class HomeComponentsCatalog extends StatefulWidget {
   State<HomeComponentsCatalog> createState() => _HomeComponentsCatalogState();
 }
 
-class _HomeComponentsCatalogState extends State<HomeComponentsCatalog> {
+class _HomeComponentsCatalogState extends State<HomeComponentsCatalog>
+    with RouteAware {
   final TextEditingController _searchCtrl = TextEditingController();
   String _query = '';
 
+  @override
+  void didChangeDependencies() {
+    super.didChangeDependencies();
+    final ModalRoute<dynamic>? route = ModalRoute.of(context);
+    if (route != null) {
+      kasyRouteObserver.subscribe(this, route);
+    }
+  }
+
   @override
   void dispose() {
+    kasyRouteObserver.unsubscribe(this);
     _searchCtrl.dispose();
     super.dispose();
   }
 
-  /// Reset the filter when leaving for a component, so coming back shows the
-  /// full catalog instead of the stale search term.
+  /// When a pushed preview pops back to the catalog, reset the filter so the
+  /// list shows the full catalog instead of the stale search term. Backed up by
+  /// the navigation future's [_clearSearch] for the admin-embedded case, whose
+  /// nested navigator the root observer does not see.
+  @override
+  void didPopNext() => _clearSearch();
+
   void _clearSearch() {
     if (!mounted) return;
     if (_query.isEmpty && _searchCtrl.text.isEmpty) return;
@@ -325,6 +342,7 @@ const Set<String> _kReadyComponents = <String>{
   'Dialog',
   'DropDown',
   'Hover',
+  'Menu',
   'Tabs',
   'TextArea',
   'TextField',
@@ -352,6 +370,7 @@ const Set<String> _kWebReadyComponents = <String>{
   'Dialog',
   'DropDown',
   'Hover',
+  'Menu',
   'Sidebar',
   'Skeleton',
   'Status Tag',
@@ -384,6 +403,7 @@ const List<_CatalogRow> _kCatalog = [
   _CatalogRow('Dialog'),
   _CatalogRow('DropDown'),
   _CatalogRow('Hover'),
+  _CatalogRow('Menu'),
   _CatalogRow('Sidebar'),
   _CatalogRow('Skeleton'),
   _CatalogRow('Status Tag'),
@@ -412,7 +432,6 @@ const List<_CatalogRow> _kCatalog = [
   _CatalogRow('LineChart'),
   _CatalogRow('LinkButton'),
   _CatalogRow('ListGroup'),
-  _CatalogRow('Menu'),
   _CatalogRow('NumberField'),
   _CatalogRow('NumberStepper'),
   _CatalogRow('NumberValue'),