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.
This commit is contained in:
2026-11-10 21:53:35 +00:00
parent f0aadbe4e3
commit 31f495fc18
5 changed files with 423 additions and 0 deletions
+207
View File
@@ -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<T?> showAppChoiceMenu<T>(
BuildContext anchor, {
required WidgetBuilder builder,
double width = 320,
String? semanticLabel,
}) {
final navigator = Navigator.of(anchor, rootNavigator: true);
if (!usesDesktopPopups(anchor)) {
return showModalBottomSheet<T>(
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<T>(
_AnchoredMenuRoute<T>(
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<T?> showAppDetails<T>(
BuildContext context, {
required WidgetBuilder builder,
double maxWidth = 560,
}) {
if (!usesDesktopPopups(context)) {
return showModalBottomSheet<T>(
context: context,
useRootNavigator: true,
showDragHandle: true,
isScrollControlled: true,
useSafeArea: true,
builder: builder,
);
}
return showDialog<T>(
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<T> extends PopupRoute<T> {
_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<double> animation,
Animation<double> 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;
}
+10
View File
@@ -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.
@@ -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')));
+154
View File
@@ -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<String>? picked}) =>
MaterialApp(
home: Scaffold(
body: Align(
alignment: alignment,
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
Builder(
builder: (anchor) => TextButton(
onPressed: () async {
final value = await showAppChoiceMenu<String>(
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<void>(
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 = <String>[];
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 = <String>[];
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);
});
}
+29
View File
@@ -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<ProbeContent> {
),
),
),
Builder(
builder: (anchor) => _button('choice', () async {
final value = await showAppChoiceMenu<String>(
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<void>(
context,
builder: (_) => const Padding(
padding: EdgeInsets.fromLTRB(24, 8, 24, 24),
child: Text('Details body'),
),
),
),
_button(
'dialog',
() => showDialog<void>(