diff --git a/docs/specifications/ephemeral_window.md b/docs/specifications/ephemeral_window.md index 5442a8ed..b75a61c7 100644 --- a/docs/specifications/ephemeral_window.md +++ b/docs/specifications/ephemeral_window.md @@ -23,7 +23,11 @@ by `EphemeralWindowWidget`. only raises an existing window, or a failed launch — stays readable here instead of becoming a blank card. - **Opened** — once a meta window is attributed, `EphemeralWindowWidget` renders - it (`WindowWidget`) maximized. + it (`WindowWidget`) maximized and hands it the keyboard: focus moves to the + window's surface node, so keys the client handles (`Enter`, `Space`, `Escape`, + `Tab`, directions) fall through to it instead of being consumed by the + overview's search pane. While the surface has not been matched yet, the + placeholder holds the keyboard for the same reason. - **Closed** — closing the native window removes the window. Closing while no native window is owned (the waiting case above) removes the window directly and cancels its pending launch (`systemctl --user stop` on the tracked diff --git a/docs/specifications/navigation.md b/docs/specifications/navigation.md index c5ff5b16..d838d630 100644 --- a/docs/specifications/navigation.md +++ b/docs/specifications/navigation.md @@ -140,7 +140,12 @@ focused context's ancestry**. The `ActivateIntent` handler is therefore registered only by the search pane (`SearchEngine`) and the result lists, so `Enter` acts there but is ignored — and forwarded to the focused client — everywhere else, and never steals `Enter` from a focused client surface or an -unrelated text field. `DismissIntent` is registered by the overview, so +unrelated text field. A client surface that owns the keyboard (`SurfaceFocus`) +shadows activation, dismissal and traversal keys with an action that does not +consume them, so they fall through to the client; the overview hands the +keyboard to an ephemeral window's surface when it is displayed, so `Enter` +reaches the application rather than the search pane that launched it. +`DismissIntent` is registered by the overview, so `Escape` hides it, but a dialog or menu opened above it consumes the key first. `Super+Tab` is registered above both overview panes, so it keeps acting no matter which part of the overview holds focus. diff --git a/docs/specifications/overview.md b/docs/specifications/overview.md index 7481e391..62aac388 100644 --- a/docs/specifications/overview.md +++ b/docs/specifications/overview.md @@ -14,8 +14,9 @@ displayed content and `Overview.selectedContent` resolves it (falling back to the Helm when stale). Opening the overview keeps the current selection and `show(windowId)` opens it to a specific window (used when bringing a window into view). Each tab shows its icon and a label — `Helm`, the window's application -name, or the file name. The content cross-fades when the selection changes, and -only the selected button is tinted — unselected buttons use a low surface. +name, or the file name. Selecting a window's tab displays it and hands it the +keyboard. The content cross-fades when the selection changes, and only the +selected button is tinted — unselected buttons use a low surface. Selecting a file in the Files mode opens or reuses a **preview tab** and displays it: @@ -72,6 +73,15 @@ between the panes and the same direction keys then walk the Helm's controls, switches and notification list. Focus drives the semantic focus, so the selection is what assistive technology follows. +A displayed ephemeral window owns the keyboard: launching an application hands +focus to its surface as soon as it is mapped (the launch placeholder holds it +until then), and clicking the window or selecting its panel tab hands it back. +The surface's `SurfaceFocus` lets `Enter`, `Space`, `Escape`, `Tab` and the +direction keys fall through to the client, so they act in the application +instead of the overview — without the hand-off the search pane keeps the Flutter +focus and `Enter` would launch another instance. Use the `Super` chords to move +the keyboard back to the search pane to keep launching. + The navigation applies to all three modes: `Super+W`/`Super+S` move through the mode's results and `Enter` activates them — a file opens with its handler, an application is launched as an ephemeral window, and a settings row is activated. diff --git a/src/shell/lib/overview/widget/overview_content.dart b/src/shell/lib/overview/widget/overview_content.dart index 418c6744..bdb10e3f 100644 --- a/src/shell/lib/overview/widget/overview_content.dart +++ b/src/shell/lib/overview/widget/overview_content.dart @@ -19,7 +19,21 @@ class OverviewContentPane extends HookConsumerWidget { overviewStateProvider(screenId).select((state) => state.selectedContent), ); - final node = useFocusNode(); + final node = useFocusNode(debugLabel: 'OverviewWindowFocus'); + + // Selecting a window's tab hands it the keyboard. `selectContent` is a + // no-op when that window is already the displayed content (the common + // re-click): nothing remounts, so the window widget's own focus hand-off + // never runs and the keyboard would stay where it was (e.g. the search + // field), where `Enter` would launch another instance. + void selectContent(OverviewContent content) { + ref + .read(overviewStateProvider(screenId).notifier) + .selectContent(content.contentId); + if (content is WindowOverviewContent) { + node.requestFocus(); + } + } // Directional navigation inside the content pane (the Helm's controls, a // preview, an embedded window) uses the framework's directional focus: @@ -45,7 +59,7 @@ class OverviewContentPane extends HookConsumerWidget { padding: const EdgeInsets.all(16), child: Column( children: [ - const _OverviewContentPanel(), + _OverviewContentPanel(onSelect: selectContent), const SizedBox(height: 16), Expanded( child: AnimatedSwitcher( @@ -72,7 +86,12 @@ class OverviewContentPane extends HookConsumerWidget { } class _OverviewContentPanel extends HookConsumerWidget { - const _OverviewContentPanel(); + const _OverviewContentPanel({required this.onSelect}); + + /// Selects a content; the pane uses it to also hand a selected window the + /// keyboard. + final ValueChanged onSelect; + @override Widget build(BuildContext context, WidgetRef ref) { final screenId = CurrentScreenId.of(context); @@ -106,7 +125,7 @@ class _OverviewContentPanel extends HookConsumerWidget { OverviewContentTab( content: content, isSelected: content.contentId == selectedContentId, - onSelect: () => notifier.selectContent(content.contentId), + onSelect: () => onSelect(content), onClose: () => notifier.closeContent(content.contentId), ), ], diff --git a/src/shell/lib/window/widget/ephemeral_window.dart b/src/shell/lib/window/widget/ephemeral_window.dart index 40a701d4..4304493c 100644 --- a/src/shell/lib/window/widget/ephemeral_window.dart +++ b/src/shell/lib/window/widget/ephemeral_window.dart @@ -1,3 +1,4 @@ +import 'package:flutter_hooks/flutter_hooks.dart'; import 'package:hooks_riverpod/hooks_riverpod.dart'; import 'package:material_ui/material_ui.dart'; import 'package:shell/application/widget/logs_viewer.dart'; @@ -27,38 +28,67 @@ class EphemeralWindowWidget extends HookConsumerWidget { final metaWindowId = window.metaWindowId; final fileChooser = ref.watch(fileChooserForWindowProvider(windowId)); - if (metaWindowId != null) { - return Stack( - fit: StackFit.expand, - children: [ - WindowWidget( - metaWindowId: metaWindowId, - focusNode: focusNode, - dialogMetaWindowList: ref - .watch(dialogSetForWindowProvider(window.windowId)) - .map((element) { - return ref - .read(dialogWindowStateProvider(element)) - .metaWindowId; - }) - .toList(), - ), - // The trusted file chooser renders inside the window container, - // attached to the window that asked for it (like a native dialog). - if (fileChooser != null) FileChooserModal(request: fileChooser), - ], - ); - } - // No native window yet: an ephemeral launch may never produce one (a - // single-instance app that only raises its existing window, a launch that - // fails). Show the execution logs in a dark terminal container so the tile - // is never a blank, unclosable card while it waits for its surface. - return _EphemeralLaunchView( - pid: window.pid, - onClose: () => ref - .read(ephemeralWindowStateProvider(windowId).notifier) - .closeWindow(), + // While the launch has no surface, the window owns a placeholder focus + // target; once the surface exists, the keyboard goes to the surface node. + // Handing the keyboard over is what makes the reported bug go away: the + // surface wraps itself in `SurfaceFocus`, which lets `Enter`/`Space`/ + // `Escape` and the direction keys fall through to the client, while the + // placeholder has no actions at all, so those keys are not consumed by the + // overview's search pane either. Without the hand-off the search pane keeps + // the Flutter focus and its `ActivateIntent` fires, launching another + // instance instead of reaching the focused client. + final waitingFocusNode = useFocusNode(debugLabel: 'EphemeralWindowWaiting'); + final activeFocusNode = metaWindowId == null ? waitingFocusNode : focusNode; + useEffect(() { + activeFocusNode.requestFocus(); + return null; + }, [metaWindowId]); + + final content = metaWindowId != null + ? Stack( + fit: StackFit.expand, + children: [ + WindowWidget( + metaWindowId: metaWindowId, + focusNode: focusNode, + dialogMetaWindowList: ref + .watch(dialogSetForWindowProvider(window.windowId)) + .map((element) { + return ref + .read(dialogWindowStateProvider(element)) + .metaWindowId; + }) + .toList(), + ), + // The trusted file chooser renders inside the window container, + // attached to the window that asked for it (native-dialog like). + if (fileChooser != null) FileChooserModal(request: fileChooser), + ], + ) + : Focus( + // No native window yet: an ephemeral launch may never produce one + // (a single-instance app that only raises its existing window, a + // launch that fails). Show the execution logs in a dark terminal + // container so the tile is never a blank, unclosable card while it + // waits for its surface. + focusNode: waitingFocusNode, + child: _EphemeralLaunchView( + pid: window.pid, + onClose: () => ref + .read(ephemeralWindowStateProvider(windowId).notifier) + .closeWindow(), + ), + ); + + // Clicking into the window hands it the keyboard as well. The compositor + // already activates the client on pointer down + // (`ActivateSurfaceOnPointerDown`); this keeps the Flutter focus in step, + // so a click after the launch is what `Enter`/`Space` follow. + return Listener( + behavior: HitTestBehavior.translucent, + onPointerDown: (_) => activeFocusNode.requestFocus(), + child: content, ); } } diff --git a/src/shell/test/ephemeral_window_focus_test.dart b/src/shell/test/ephemeral_window_focus_test.dart new file mode 100644 index 00000000..88f44343 --- /dev/null +++ b/src/shell/test/ephemeral_window_focus_test.dart @@ -0,0 +1,312 @@ +import 'package:fast_immutable_collections/fast_immutable_collections.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:freedesktop_desktop_entry/freedesktop_desktop_entry.dart'; +import 'package:hooks_riverpod/hooks_riverpod.dart'; +import 'package:material_ui/material_ui.dart'; +import 'package:shell/application/provider/localized_desktop_entries.dart'; +import 'package:shell/l10n/l10n.dart'; +import 'package:shell/meta_window/model/meta_window.serializable.dart'; +import 'package:shell/meta_window/provider/meta_window_state.dart'; +import 'package:shell/monitor/widget/current_screen_id.dart'; +import 'package:shell/overview/model/overview.dart'; +import 'package:shell/overview/model/overview_content.dart'; +import 'package:shell/overview/provider/overview_state.dart'; +import 'package:shell/overview/widget/overview_content.dart'; +import 'package:shell/overview/widget/overview_content_tab.dart'; +import 'package:shell/platform/model/event/platform_event.serializable.dart'; +import 'package:shell/platform/model/request/platform_request.dart'; +import 'package:shell/platform/provider/platform_manager.dart'; +import 'package:shell/screen/model/screen.serializable.dart'; +import 'package:shell/screen/widget/current_screen_id.dart'; +import 'package:shell/wayland/model/wl_surface.dart'; +import 'package:shell/wayland/provider/wl_surface_state.dart'; +import 'package:shell/window/model/ephemeral_window.dart'; +import 'package:shell/window/model/window_id.serializable.dart'; +import 'package:shell/window/model/window_properties.serializable.dart'; +import 'package:shell/window/provider/ephemeral_window_state.dart'; +import 'package:shell/window/widget/ephemeral_window.dart'; + +const _windowId = EphemeralWindowId('e1'); +const _metaWindowId = 'window-1'; +const _surfaceId = 0; +const _surfaceSize = Size(1000, 800); +const _screenId = 'screen-1'; + +/// An ephemeral window whose launch has not produced a native surface yet. +class _WaitingWindowState extends EphemeralWindowState { + @override + EphemeralWindow build(EphemeralWindowId windowId) => EphemeralWindow( + windowId: windowId, + properties: const WindowProperties(appId: 'org.example.App'), + screenId: 'screen-1', + ); +} + +/// An ephemeral window whose native surface has been matched. +class _DisplayedWindowState extends EphemeralWindowState { + @override + EphemeralWindow build(EphemeralWindowId windowId) => EphemeralWindow( + windowId: windowId, + properties: const WindowProperties(appId: 'org.example.App'), + screenId: 'screen-1', + metaWindowId: _metaWindowId, + ); +} + +/// An overview whose displayed content is [_windowId]. +class _SelectedWindowOverviewState extends OverviewState { + @override + Overview build(ScreenId screenId) { + const content = OverviewContent.window(_windowId); + return Overview( + screenId: screenId, + contentList: [content].lock, + isDisplayed: true, + selectedContentId: content.contentId, + ); + } +} + +class _FakeMetaWindowState extends MetaWindowState { + @override + MetaWindow build(String id) => const MetaWindow( + id: _metaWindowId, + pid: 1, + mapped: true, + surfaceId: _surfaceId, + needDecoration: false, + gameModeActivated: false, + scaleRatio: 1, + geometry: Rect.fromLTWH(0, 0, 1000, 800), + ); +} + +class _FakeSurfaceState extends WlSurfaceState { + @override + WlSurface build(int surfaceId) => WlSurface( + surfaceId: _surfaceId, + role: SurfaceRole.xdgToplevel, + texture: const SurfaceTexture(id: 1, size: _surfaceSize), + scale: 1, + subsurfacesBelow: IList(), + subsurfacesAbove: IList(), + inputRegion: Rect.zero, + ); +} + +/// Swallows the activation requests the window makes when it takes focus, so +/// the test does not need a platform channel. +class _FakePlatformManager extends PlatformManager { + @override + Stream build() => const Stream.empty(); + + @override + Future request(PlatformRequest request) async {} +} + +/// Resolves no desktop entry, so a window tab falls back to its title. +class _FakeLocalizedDesktopEntryForId extends LocalizedDesktopEntryForId { + @override + Future build(String appId) async => null; +} + +/// The two focus nodes the test watches: the stand-in search pane, and the +/// node handed to the ephemeral window. +typedef _FocusNodes = ({FocusNode search, FocusNode window}); + +void main() { + Future<_FocusNodes> pumpWindow( + WidgetTester tester, { + required EphemeralWindowState Function() windowState, + required bool displayed, + }) async { + final nodes = ( + search: FocusNode(debugLabel: 'search'), + window: FocusNode(debugLabel: 'window'), + ); + addTearDown(nodes.search.dispose); + addTearDown(nodes.window.dispose); + tester.view + ..devicePixelRatio = 1.0 + ..physicalSize = const Size(1000, 800); + addTearDown(tester.view.reset); + + await tester.pumpWidget( + ProviderScope( + overrides: [ + platformManagerProvider.overrideWith(_FakePlatformManager.new), + ephemeralWindowStateProvider(_windowId).overrideWith(windowState), + if (displayed) ...[ + metaWindowStateProvider( + _metaWindowId, + ).overrideWith(_FakeMetaWindowState.new), + wlSurfaceStateProvider( + _surfaceId, + ).overrideWith(_FakeSurfaceState.new), + ], + ], + child: MaterialApp( + home: CurrentMonitorName( + name: 'M1', + child: Column( + children: [ + // Stands in for the overview's search pane, which autofocuses + // and keeps the keyboard until the window is shown. + Focus( + focusNode: nodes.search, + autofocus: true, + child: const SizedBox(), + ), + Expanded( + child: EphemeralWindowWidget( + windowId: _windowId, + focusNode: nodes.window, + ), + ), + ], + ), + ), + ), + ), + ); + + // Let the autofocus and the widget's focus hand-off settle. (Not + // `pumpAndSettle`: the waiting placeholder shows an indeterminate + // progress indicator, which never settles.) + await tester.pump(); + await tester.pump(); + return nodes; + } + + testWidgets( + 'the waiting placeholder takes the keyboard while there is no surface', + (tester) async { + final nodes = await pumpWindow( + tester, + windowState: _WaitingWindowState.new, + displayed: false, + ); + + expect( + nodes.search.hasFocus, + isFalse, + reason: 'the search pane must not keep Enter while the app launches', + ); + expect( + nodes.window.hasFocus, + isFalse, + reason: 'there is no surface node yet', + ); + }, + ); + + testWidgets('the surface takes the keyboard once the window is matched', ( + tester, + ) async { + final nodes = await pumpWindow( + tester, + windowState: _DisplayedWindowState.new, + displayed: true, + ); + + expect( + nodes.window.hasFocus, + isTrue, + reason: 'the client surface owns the keyboard so Enter reaches it', + ); + expect(nodes.search.hasFocus, isFalse); + }); + + testWidgets('clicking the window hands it the keyboard', (tester) async { + final nodes = await pumpWindow( + tester, + windowState: _DisplayedWindowState.new, + displayed: true, + ); + + // Move the keyboard back to the search pane first. + nodes.search.requestFocus(); + await tester.pump(); + expect(nodes.search.hasFocus, isTrue); + + await tester.tap(find.byType(EphemeralWindowWidget)); + await tester.pump(); + + expect(nodes.window.hasFocus, isTrue); + expect(nodes.search.hasFocus, isFalse); + }); + + testWidgets('selecting the displayed window tab hands it the keyboard', ( + tester, + ) async { + final otherFocus = FocusNode(debugLabel: 'other'); + addTearDown(otherFocus.dispose); + tester.view + ..devicePixelRatio = 1.0 + ..physicalSize = const Size(1000, 800); + addTearDown(tester.view.reset); + + await tester.pumpWidget( + ProviderScope( + overrides: [ + platformManagerProvider.overrideWith(_FakePlatformManager.new), + overviewStateProvider( + _screenId, + ).overrideWith(_SelectedWindowOverviewState.new), + ephemeralWindowStateProvider( + _windowId, + ).overrideWith(_DisplayedWindowState.new), + metaWindowStateProvider( + _metaWindowId, + ).overrideWith(_FakeMetaWindowState.new), + wlSurfaceStateProvider( + _surfaceId, + ).overrideWith(_FakeSurfaceState.new), + localizedDesktopEntryForIdProvider( + 'org.example.App', + ).overrideWith(_FakeLocalizedDesktopEntryForId.new), + ], + child: MaterialApp( + localizationsDelegates: AppLocalizations.localizationsDelegates, + supportedLocales: AppLocalizations.supportedLocales, + home: CurrentScreenId( + screenId: _screenId, + child: CurrentMonitorName( + name: 'M1', + child: Column( + children: [ + Focus(focusNode: otherFocus, child: const SizedBox()), + const Expanded(child: OverviewContentPane()), + ], + ), + ), + ), + ), + ), + ); + + // The displayed window auto-focuses. + await tester.pump(); + await tester.pump(); + expect( + FocusManager.instance.primaryFocus?.debugLabel, + 'OverviewWindowFocus', + ); + + // Move the keyboard away, then re-select the already-displayed window's + // tab: `selectContent` changes nothing, so only the tab's focus hand-off + // can bring the keyboard back. + otherFocus.requestFocus(); + await tester.pump(); + expect(otherFocus.hasFocus, isTrue); + + await tester.tap(find.byType(OverviewContentTab).last); + await tester.pump(); + + expect( + FocusManager.instance.primaryFocus?.debugLabel, + 'OverviewWindowFocus', + reason: 'the tab hands the displayed window the keyboard', + ); + }); +}