From 31f495fc189230a839329236db0da9a7d0f0a804 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Tue, 10 Nov 2026 21:53:35 +0000 Subject: [PATCH] Add adaptive popup helpers: anchored choice menus and details dialogs Phase 2b.1 of docs/plans/floating-windows.md. showAppChoiceMenu is a menu panel anchored to its button on a wide app and a bottom sheet on a phone; showAppDetails is a dialog or a bottom sheet. Both are on the root navigator, and the app's width decides, so content in a narrow floating window still gets desktop popups. The probe window exercises both. --- app/lib/ui/adaptive/app_popups.dart | 207 ++++++++++++++++++ app/notes/floating-windows.md | 10 + .../shell/windows/window_layering_test.dart | 23 ++ app/test/ui/adaptive/app_popups_test.dart | 154 +++++++++++++ app/tool/capture/window_probe.dart | 29 +++ 5 files changed, 423 insertions(+) create mode 100644 app/lib/ui/adaptive/app_popups.dart create mode 100644 app/test/ui/adaptive/app_popups_test.dart diff --git a/app/lib/ui/adaptive/app_popups.dart b/app/lib/ui/adaptive/app_popups.dart new file mode 100644 index 00000000..94ce6695 --- /dev/null +++ b/app/lib/ui/adaptive/app_popups.dart @@ -0,0 +1,207 @@ +import 'package:flutter/material.dart'; + +import '../motion/motion.dart'; + +/// The narrowest app that gets desktop popups: the width where a list shows +/// beside its open item (`kListDetailMinWidth`). +const double kDesktopPopupMinWidth = 600; + +/// Whether popups here are desktop ones (a menu anchored to its button, a +/// dialog) rather than a phone's bottom sheets. It is the app's width that +/// decides, not the surface asking: content in a narrow floating window on a +/// wide app still gets menus and dialogs. +bool usesDesktopPopups(BuildContext context) { + final root = Navigator.maybeOf(context, rootNavigator: true)?.context; + return MediaQuery.sizeOf(root ?? context).width >= kDesktopPopupMinWidth; +} + +/// Shows a short list of choices (a mode, a sort order, a pane to add, a +/// row's actions) built by [builder]. +/// +/// On a wide app it is a menu panel anchored to [anchor] (the button that +/// opened it): below it, or above when there is no room, kept inside the app. +/// On a phone it is a bottom sheet. Either way it is on the root navigator, +/// so it is above every floating window. Escape, Back or a press outside +/// closes it; the content closes it with `Navigator.of(context).pop(value)`. +Future showAppChoiceMenu( + BuildContext anchor, { + required WidgetBuilder builder, + double width = 320, + String? semanticLabel, +}) { + final navigator = Navigator.of(anchor, rootNavigator: true); + if (!usesDesktopPopups(anchor)) { + return showModalBottomSheet( + context: anchor, + useRootNavigator: true, + showDragHandle: true, + isScrollControlled: true, + useSafeArea: true, + builder: builder, + ); + } + final box = anchor.findRenderObject()! as RenderBox; + final overlay = navigator.overlay!.context.findRenderObject()! as RenderBox; + final rect = box.localToGlobal(Offset.zero, ancestor: overlay) & box.size; + return navigator.push( + _AnchoredMenuRoute( + anchor: rect, + width: width, + builder: builder, + label: semanticLabel ?? 'Menu', + themes: InheritedTheme.capture(from: anchor, to: navigator.context), + duration: Motion.of(anchor, Motion.quick), + ), + ); +} + +/// Shows richer content (a chat's details, a file's details) built by +/// [builder]: a dialog on a wide app, a bottom sheet on a phone, on the root +/// navigator either way. +Future showAppDetails( + BuildContext context, { + required WidgetBuilder builder, + double maxWidth = 560, +}) { + if (!usesDesktopPopups(context)) { + return showModalBottomSheet( + context: context, + useRootNavigator: true, + showDragHandle: true, + isScrollControlled: true, + useSafeArea: true, + builder: builder, + ); + } + return showDialog( + context: context, + useRootNavigator: true, + builder: (dialog) => Dialog( + clipBehavior: Clip.antiAlias, + child: ConstrainedBox( + constraints: BoxConstraints( + maxWidth: maxWidth, + maxHeight: MediaQuery.sizeOf(dialog).height * 0.85, + ), + child: Padding( + padding: const EdgeInsets.only(top: 16), + child: builder(dialog), + ), + ), + ), + ); +} + +class _AnchoredMenuRoute extends PopupRoute { + _AnchoredMenuRoute({ + required this.anchor, + required this.width, + required this.builder, + required this.label, + required this.themes, + required this.duration, + }); + + final Rect anchor; + final double width; + final WidgetBuilder builder; + final String label; + final CapturedThemes themes; + final Duration duration; + + @override + Color? get barrierColor => null; + @override + bool get barrierDismissible => true; + @override + String? get barrierLabel => 'Dismiss'; + @override + Duration get transitionDuration => duration; + + @override + Widget buildPage( + BuildContext context, + Animation animation, + Animation secondaryAnimation, + ) { + final colors = Theme.of(context).colorScheme; + return SafeArea( + child: CustomSingleChildLayout( + delegate: _AnchoredMenuLayout(anchor, width), + child: FadeTransition( + opacity: CurvedAnimation(parent: animation, curve: Motion.curve), + child: Semantics( + scopesRoute: true, + namesRoute: true, + explicitChildNodes: true, + label: label, + child: Material( + key: const ValueKey('app-choice-menu'), + elevation: 3, + // A step above a window's own surface, so the panel reads + // as raised when it opens over one. + color: colors.surfaceContainerHigh, + surfaceTintColor: Colors.transparent, + borderRadius: BorderRadius.circular(12), + clipBehavior: Clip.antiAlias, + child: Padding( + padding: const EdgeInsets.symmetric(vertical: 8), + child: themes.wrap(Builder(builder: builder)), + ), + ), + ), + ), + ), + ); + } +} + +/// Places the panel below its anchor, aligned to the anchor's leading edge, +/// or above it when it fits better there, and always inside the app. +class _AnchoredMenuLayout extends SingleChildLayoutDelegate { + _AnchoredMenuLayout(this.anchor, this.width); + + final Rect anchor; + final double width; + + static const double margin = 8; + static const double gap = 4; + + @override + BoxConstraints getConstraintsForChild(BoxConstraints constraints) { + final available = constraints.biggest; + final below = available.height - anchor.bottom - gap - margin; + final above = anchor.top - gap - margin; + final height = (below >= 240 || below >= above ? below : above).clamp( + 0.0, + available.height - 2 * margin, + ); + final maxWidth = (available.width - 2 * margin).clamp(0.0, double.infinity); + return BoxConstraints( + minWidth: width.clamp(0.0, maxWidth), + maxWidth: width.clamp(0.0, maxWidth), + maxHeight: height, + ); + } + + @override + Offset getPositionForChild(Size size, Size childSize) { + final below = size.height - anchor.bottom - gap - margin; + final fitsBelow = childSize.height <= below; + final top = fitsBelow + ? anchor.bottom + gap + : (anchor.top - gap - childSize.height).clamp( + margin, + size.height - margin - childSize.height, + ); + final left = anchor.left.clamp( + margin, + (size.width - margin - childSize.width).clamp(margin, double.infinity), + ); + return Offset(left, top); + } + + @override + bool shouldRelayout(_AnchoredMenuLayout oldDelegate) => + oldDelegate.anchor != anchor || oldDelegate.width != width; +} diff --git a/app/notes/floating-windows.md b/app/notes/floating-windows.md index 954a7ea3..1af69a1d 100644 --- a/app/notes/floating-windows.md +++ b/app/notes/floating-windows.md @@ -53,3 +53,13 @@ floating chats (`notes/chat-floating-pane.md`); the terminal moves in Phase 3. hover, SnackBar, pushed page and Back, raise, move, maximise, minimise. - Not captured in the browser: the text-selection menu (the kit has no right-click); covered by the layering test only. + +## Desktop popups (Phase 2b) + +`ui/adaptive/app_popups.dart`: `showAppChoiceMenu` (a short list of choices: +a menu panel anchored to its button on a wide app, a bottom sheet on a phone) +and `showAppDetails` (richer content: a dialog, or a bottom sheet on a phone). +Both are on the root navigator, so they are above every window, and the app's +width decides (`usesDesktopPopups`), not the surface asking: content in a +narrow window on a wide app still gets menus and dialogs. The probe window has +`choice` and `details` buttons for captures. diff --git a/app/test/shell/windows/window_layering_test.dart b/app/test/shell/windows/window_layering_test.dart index a0371596..ff2dbac5 100644 --- a/app/test/shell/windows/window_layering_test.dart +++ b/app/test/shell/windows/window_layering_test.dart @@ -79,6 +79,29 @@ void main() { ); }); + testWidgets('app choice menu and details dialog', (tester) async { + await open(tester, destination); + final button = tester.getRect(find.byKey(const ValueKey('a-choice'))); + await tester.tap(find.byKey(const ValueKey('a-choice'))); + await tester.pumpAndSettle(); + // A menu at its button, not a sheet, though the window is narrow. + expect(find.byType(BottomSheet), findsNothing); + expect(find.text('Choice two').hitTestable(), findsOneWidget); + final menu = tester.getRect( + find.byKey(const ValueKey('app-choice-menu')), + ); + expect((menu.top - button.bottom).abs(), lessThan(40)); + expect(menu.left, button.left); + await tester.tap(find.text('Choice two')); + await tester.pumpAndSettle(); + expect(picked(tester, 'a'), 'Choice two'); + + await tester.tap(find.byKey(const ValueKey('a-details'))); + await tester.pumpAndSettle(); + expect(find.byType(Dialog), findsOneWidget); + expect(find.text('Details body').hitTestable(), findsOneWidget); + }); + testWidgets('MenuAnchor', (tester) async { await open(tester, destination); await tester.tap(find.byKey(const ValueKey('a-anchor'))); diff --git a/app/test/ui/adaptive/app_popups_test.dart b/app/test/ui/adaptive/app_popups_test.dart new file mode 100644 index 00000000..a5251716 --- /dev/null +++ b/app/test/ui/adaptive/app_popups_test.dart @@ -0,0 +1,154 @@ +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/ui/adaptive/app_popups.dart'; + +Widget _app({Alignment alignment = Alignment.topLeft, List? picked}) => + MaterialApp( + home: Scaffold( + body: Align( + alignment: alignment, + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + Builder( + builder: (anchor) => TextButton( + onPressed: () async { + final value = await showAppChoiceMenu( + anchor, + builder: (menu) => Column( + mainAxisSize: MainAxisSize.min, + children: [ + for (final choice in const ['One', 'Two', 'Three']) + ListTile( + title: Text(choice), + onTap: () => Navigator.of(menu).pop(choice), + ), + ], + ), + ); + picked?.add('$value'); + }, + child: const Text('Open menu'), + ), + ), + Builder( + builder: (context) => TextButton( + onPressed: () => showAppDetails( + context, + builder: (_) => const Text('Details body'), + ), + child: const Text('Open details'), + ), + ), + ], + ), + ), + ), + ); + +void _size(WidgetTester tester, Size size) { + tester.view.physicalSize = size; + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.reset); +} + +final _menu = find.byKey(const ValueKey('app-choice-menu')); + +void main() { + testWidgets('wide: a menu anchored below its button, closed by a choice, ' + 'Escape or a press outside', (tester) async { + _size(tester, const Size(1280, 800)); + final picked = []; + await tester.pumpWidget(_app(picked: picked)); + final button = tester.getRect(find.text('Open menu')); + await tester.tap(find.text('Open menu')); + await tester.pumpAndSettle(); + expect(find.byType(BottomSheet), findsNothing); + final menu = tester.getRect(_menu); + expect(menu.width, 320); + expect(menu.top, greaterThanOrEqualTo(button.bottom)); + expect(menu.top - button.bottom, lessThan(40)); + expect(menu.left, greaterThanOrEqualTo(8)); + await tester.tap(find.text('Two')); + await tester.pumpAndSettle(); + expect(picked, ['Two']); + expect(_menu, findsNothing); + + await tester.tap(find.text('Open menu')); + await tester.pumpAndSettle(); + await tester.sendKeyEvent(LogicalKeyboardKey.escape); + await tester.pumpAndSettle(); + expect(_menu, findsNothing); + + await tester.tap(find.text('Open menu')); + await tester.pumpAndSettle(); + await tester.tapAt(const Offset(1200, 700)); + await tester.pumpAndSettle(); + expect(_menu, findsNothing); + expect(picked, ['Two', 'null', 'null']); + }); + + testWidgets('wide: near the bottom right the menu opens above, inside the ' + 'app', (tester) async { + _size(tester, const Size(1280, 800)); + await tester.pumpWidget(_app(alignment: Alignment.bottomRight)); + final button = tester.getRect(find.text('Open menu')); + await tester.tap(find.text('Open menu')); + await tester.pumpAndSettle(); + final menu = tester.getRect(_menu); + expect(menu.bottom, lessThanOrEqualTo(button.top)); + expect(menu.right, lessThanOrEqualTo(1280 - 8)); + expect(menu.top, greaterThanOrEqualTo(8)); + }); + + testWidgets('wide: details are a dialog', (tester) async { + _size(tester, const Size(1280, 800)); + await tester.pumpWidget(_app()); + await tester.tap(find.text('Open details')); + await tester.pumpAndSettle(); + expect(find.byType(Dialog), findsOneWidget); + expect(find.byType(BottomSheet), findsNothing); + expect(tester.getSize(find.byType(Dialog)).width, lessThanOrEqualTo(1280)); + expect(find.text('Details body'), findsOneWidget); + }); + + testWidgets('phone: both are bottom sheets', (tester) async { + _size(tester, const Size(430, 900)); + final picked = []; + await tester.pumpWidget(_app(picked: picked)); + await tester.tap(find.text('Open menu')); + await tester.pumpAndSettle(); + expect(find.byType(BottomSheet), findsOneWidget); + expect(_menu, findsNothing); + await tester.tap(find.text('Three')); + await tester.pumpAndSettle(); + expect(picked, ['Three']); + await tester.tap(find.text('Open details')); + await tester.pumpAndSettle(); + expect(find.byType(BottomSheet), findsOneWidget); + expect(find.byType(Dialog), findsNothing); + }); + + testWidgets('the app decides, not a narrow surface inside it', ( + tester, + ) async { + _size(tester, const Size(1280, 800)); + late BuildContext inner; + await tester.pumpWidget( + MaterialApp( + home: MediaQuery( + data: const MediaQueryData(size: Size(360, 400)), + child: Builder( + builder: (context) { + inner = context; + return const SizedBox(); + }, + ), + ), + ), + ); + expect(MediaQuery.sizeOf(inner).width, 360); + expect(usesDesktopPopups(inner), isTrue); + }); +} diff --git a/app/tool/capture/window_probe.dart b/app/tool/capture/window_probe.dart index 03b63c8b..ec2c7f34 100644 --- a/app/tool/capture/window_probe.dart +++ b/app/tool/capture/window_probe.dart @@ -1,4 +1,5 @@ import 'package:flutter/material.dart'; +import 'package:pipelines_app/ui/adaptive/app_popups.dart'; import 'package:pipelines_app/shell/windows/window_entry.dart'; import 'package:pipelines_app/shell/windows/window_kind.dart'; import 'package:pipelines_app/shell/windows/window_manager.dart'; @@ -88,6 +89,34 @@ class ProbeContentState extends State { ), ), ), + Builder( + builder: (anchor) => _button('choice', () async { + final value = await showAppChoiceMenu( + anchor, + builder: (menu) => Column( + mainAxisSize: MainAxisSize.min, + children: [ + for (final choice in const ['Choice one', 'Choice two']) + ListTile( + title: Text(choice), + onTap: () => Navigator.of(menu).pop(choice), + ), + ], + ), + ); + if (mounted && value != null) setState(() => picked = value); + }), + ), + _button( + 'details', + () => showAppDetails( + context, + builder: (_) => const Padding( + padding: EdgeInsets.fromLTRB(24, 8, 24, 24), + child: Text('Details body'), + ), + ), + ), _button( 'dialog', () => showDialog(