66 lines
5.4 KiB
Markdown
66 lines
5.4 KiB
Markdown
# Focus Glass and Continuum Overview Design
|
|
|
|
## Outcome
|
|
|
|
Panama gains a polished focus-session surface and a GNOME-like workspace overview. The focus surface uses the selected Signal Glass visual language, keeps Command Deck's useful controls, and treats its associated Hyprland workspace as a first-class destination. The overview uses the selected Continuum layout: a workspace filmstrip above a large, spatially familiar active-workspace preview.
|
|
|
|
## Focus session behavior
|
|
|
|
- A focus session starts with Panama's configurable default duration of 45 minutes and binds to the currently focused positive-numbered Hyprland workspace.
|
|
- Starting a session enables Do Not Disturb and Caffeine. Panama remembers their prior values and restores them when the session ends.
|
|
- The session uses a wall-clock deadline rather than decrementing persistent state every second. It therefore survives a Quickshell reload without losing time.
|
|
- Pause stores the exact remaining duration. Resume creates a new deadline from that stored duration.
|
|
- The session completes automatically at zero and posts a normal desktop notification through the existing Panama notification server.
|
|
- End deliberately terminates the session and restores the prior DND and Caffeine values.
|
|
- Only one focus session exists at a time. Starting again replaces the old session with a fresh session on the current workspace.
|
|
|
|
## Signal Glass surface
|
|
|
|
- The main capsule is a top-centred blurred glass surface below the bar, carrying Panama's Prism edge, Tokyo Night Moon palette, and event-driven open/close motion.
|
|
- Its primary row shows the focus icon, workspace label, remaining time, and whether DND and Caffeine are being held.
|
|
- Clicking the primary row activates the bound workspace and dismisses the capsule without ending the session.
|
|
- The action row contains Pause or Resume, Workspace, and End.
|
|
- Workspace opens the Continuum overview with the session's bound workspace selected.
|
|
- A labelled close button hides the capsule while the session continues.
|
|
- While a session exists, a compact bar indicator remains visible. Clicking it reopens the capsule, so dismissal never makes the running session undiscoverable.
|
|
- No focus UI animates while idle. The only periodic update is the once-per-second remaining-time text while a session is running and not paused.
|
|
|
|
## Discoverability and controls
|
|
|
|
- Quick Settings includes a full-width Focus row. When idle it starts a 45-minute session on the current workspace. When active it shows the remaining time and opens the capsule.
|
|
- `SUPER+SHIFT+F` performs the same start-or-show action.
|
|
- A `focus` Quickshell IPC target exposes `start`, `reveal`, `pause`, `workspace`, `overview`, and `end` for launcher integration and diagnostics.
|
|
|
|
## Continuum overview
|
|
|
|
- The overview keeps the existing full-screen dimmed and blurred layer, Escape behavior, outside-click dismissal, one-shot window captures, and dynamic-workspace support.
|
|
- A horizontally scrollable workspace filmstrip occupies the top of the surface. It contains every positive-numbered workspace plus the trailing new-workspace affordance.
|
|
- The focused or requested workspace is rendered as a large preview below the filmstrip. Clicking one of its windows activates that window and closes the overview.
|
|
- Selecting a workspace in the filmstrip activates it while keeping the overview open, matching GNOME's spatial workflow. Scrolling over the filmstrip moves left or right through workspaces.
|
|
- Opening from the focus capsule initially selects the session workspace and marks it with a subtle focus-session badge.
|
|
- A search field filters windows across all positive workspaces by title or application id. Selecting a result activates its workspace and window, then closes the overview.
|
|
- The overview IPC target can open directly into a search query, enabling deterministic diagnostics and future launcher actions without synthesizing keyboard input.
|
|
|
|
## State and boundaries
|
|
|
|
- `services/FocusSession.qml` owns session timing, persistence, DND and Caffeine coordination, and workspace activation. Visual modules only call its public functions and render its properties.
|
|
- `services/ShellState.qml` remains the owner of mutually exclusive overlays and gains only the requested overview workspace id.
|
|
- `modules/focus/` owns the capsule and bar indicator.
|
|
- `modules/overview/` owns the Continuum presentation and window search.
|
|
- Persistent state is stored atomically through Quickshell `FileView` and `JsonAdapter` under `Quickshell.stateDir`; no daemon or new package is required.
|
|
|
|
## Failure handling
|
|
|
|
- If the persisted workspace no longer exists, direct activation falls back to Hyprland's workspace dispatcher using the stored positive id.
|
|
- A malformed or absent state file falls back to an inactive session with no user-visible error.
|
|
- If the shell reloads after the deadline, the session is completed during restoration and its managed DND and Caffeine state is released.
|
|
- Search and workspace lists tolerate transient null Hyprland objects while IPC state refreshes.
|
|
|
|
## Verification
|
|
|
|
- Validate the focus state machine with a standalone Quickshell harness using a very short session.
|
|
- Validate every QML component constructs without warnings against Quickshell 0.3.0.
|
|
- Exercise start, pause, resume, dismiss, reopen, workspace activation, overview targeting, automatic completion, and manual end through live IPC.
|
|
- Reload the daily-driver shell and inspect its logs for QML errors.
|
|
- Capture the capsule, compact indicator, Continuum overview, and search state for visual review.
|