76 lines
5.8 KiB
Markdown
76 lines
5.8 KiB
Markdown
# Panama Settings Design
|
|
|
|
## Purpose
|
|
|
|
Panama Settings is the native control center for the Panama Hyprland desktop. It gives Gabriel one polished, understandable place to inspect the current desktop and change Panama-owned behavior without editing Lua, QML, JSON, or systemd units by hand.
|
|
|
|
The approved visual direction is **Luminous System Settings**: an Apple-like two-pane settings window, rendered with Panama's restrained Prism glass and Tokyo Night Moon palette. It is a real application window, not a transient layer-shell popover.
|
|
|
|
## Product boundaries
|
|
|
|
Panama Settings owns settings whose source of truth is Panama, Quickshell, or Hyprland. The first release includes:
|
|
|
|
- Home summary with the active display, current desktop profile, Night Light, notification/focus state, and startup-service health.
|
|
- Appearance controls for clock format and bar vitals.
|
|
- Display policy for game-aware HDR, content-aware VRR, direct scanout, and Night Light.
|
|
- Desktop controls for dock auto-hide and timing.
|
|
- A searchable, read-only shortcut reference generated from the established Panama mental model.
|
|
- Sound entry points that reuse Panama's live PipeWire controls.
|
|
- Notification, Do Not Disturb, and focus-duration controls.
|
|
- Startup/service health for Nextcloud, RustDesk, KDE Connect, Hyprpaper, Hypridle, and Vicinae, with safe open/restart actions where appropriate.
|
|
- An About page with the running Hyprland, Quickshell, and Panama identity.
|
|
|
|
Hardware configuration, user accounts, printers, online accounts, and other services owned by Fedora or GNOME remain delegated to GNOME Settings. Panama Settings labels those handoffs and launches the relevant GNOME panel with a one-process `XDG_CURRENT_DESKTOP=GNOME` override. GNOME Settings remains installed and searchable in Vicinae.
|
|
|
|
Screen Intelligence remains a separate subsystem with its own capture, recognition, and result lifecycle. Once that subsystem is installed, Settings exposes its real readiness and privacy page rather than duplicating the feature or presenting inactive controls.
|
|
|
|
## Interaction model
|
|
|
|
`Super+I` opens or raises Panama Settings. The shell also exposes a typed `settings` IPC target with `open`, `toggle`, `close`, and `page(name)` operations. A desktop entry makes Panama Settings searchable in Vicinae alongside GNOME Settings.
|
|
|
|
The sidebar is always visible at desktop sizes and contains a search field, category groups, and a quiet system-status footer. Search filters categories and setting labels rather than becoming a command palette.
|
|
|
|
The content pane uses a stable header, restrained cards, and rows with labels, concise explanations, and controls aligned to the trailing edge. Changes apply immediately. There is no global Save button.
|
|
|
|
## State and architecture
|
|
|
|
`config/DesktopPreferences.qml` persists user choices to `Quickshell.stateDir + "/panama-settings.json"` through `FileView` and `JsonAdapter`. Existing consumers continue reading `Settings.qml`; dynamic values in that singleton bind to `DesktopPreferences`, preserving one public configuration surface.
|
|
|
|
`services/SystemSettings.qml` is the machine boundary. It reads current monitor and service state, invokes allow-listed Hyprland runtime settings, opens GNOME panels, and reports command failures. UI components never construct arbitrary shell commands.
|
|
|
|
The display policy values are persisted and re-applied when the shell starts:
|
|
|
|
- Game-aware HDR maps to `render:cm_auto_hdr` with values `0` or `1`.
|
|
- VRR maps to `misc:vrr` with values `0` or `3`.
|
|
- Direct scanout maps to `render:direct_scanout` with values `0` or `2`.
|
|
|
|
Full-time desktop HDR is informational in this release because it can break screenshots, OBS, Sunshine, and lock-screen capture on the current Hyprland build. It must not be exposed as an unsafe one-click toggle without a tested automatic rollback path.
|
|
|
|
`services/ShellState.qml` owns whether the window is open and the requested page. `modules/settings/SettingsWindow.qml` owns the normal application toplevel, which participates in Hyprland's active tiling layout. Presentation components under `modules/settings/` call only public preference or service methods.
|
|
|
|
## Visual language
|
|
|
|
- Tokyo Night Moon is the only palette.
|
|
- A faint blue-to-orchid Prism hairline marks the selected category and major surfaces; orchid never appears as a standalone accent.
|
|
- The window is dense enough to feel professional but leaves generous breathing room around page headers and section groups.
|
|
- Typography uses Adwaita Sans for interface text and VictorMono Nerd Font only for version strings, dimensions, and key chords.
|
|
- Motion is event-driven and short. No pulse, shimmer, animated gradient, or idle repaint loop is allowed.
|
|
- Enabled states use the primary blue, warnings use amber, and destructive/error states use red only when there is an actual problem.
|
|
|
|
## Failure handling
|
|
|
|
- A malformed or absent preferences file falls back to shipped defaults.
|
|
- A failed `hyprctl` write restores the previous preference value and surfaces a quiet inline error.
|
|
- Missing optional applications or services are shown as unavailable, never as a shell error or empty card.
|
|
- Service refreshes are bounded and user-triggerable; no polling loop runs continuously.
|
|
- Closing Panama Settings only hides the window. It does not terminate Quickshell or alter another overlay.
|
|
|
|
## Verification
|
|
|
|
- Exercise preferences through a disposable Quickshell state directory and prove values survive a shell restart.
|
|
- Verify each display policy emits only its allow-listed numeric `hyprctl keyword` command.
|
|
- Verify `Super+I`, IPC open/close/page routing, and the searchable desktop entry.
|
|
- Construct every Settings page without QML warnings.
|
|
- Exercise live monitor refresh, Night Light, DND, audio controls, service refresh, and GNOME handoffs.
|
|
- Restart the live shell, inspect logs, and capture Home, Displays, Desktop, and Services pages for visual review.
|