repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs: design shared popup controls

fad7c10b045672a90f571bf47715ca090deb3c75

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

quickshell/nuguland/docs/super/specs/2026-07-11-popup-controls-design.md

Added
new file mode 100644
1 +# popup controls design
3 +## goal
5 +Fix the reported Nuguland popup bugs and converge every popup on one reusable control language.
7 +References: media, noko, launcher. Selected visual direction: HIG-style cards — calm desktop controls with explicit hover, press, focus, selected, and disabled states.
9 +## scope
11 +- Fix notification DND and toast clearing.
12 +- Fix network button feedback and missing Wi-Fi data.
13 +- Add tray card right-click/middle-click behavior and richer available tray metadata.
14 +- Remove stray launcher bottom line and audio card left-line artifacts.
15 +- Add reusable QML controls for popup frame, sections, cards, buttons/toggles, separators, and text fields.
16 +- Migrate every popup to shared controls where the popup contains the corresponding UI role: connectivity, audio, tray, notifications, clipboard, power, brightness, media, noko, launcher, clock, system, and remaining registered popouts.
18 +No lockscreen/bar redesign. No new dependencies. No palette redesign.
20 +## HIG rules
22 +- One primary action per local decision.
23 +- Buttons must show hover, pressed, disabled, and selected/toggled states.
24 +- Cards are larger clickable targets with visible status and optional secondary details.
25 +- Use spacing and common regions for grouping; avoid divider lines unless they separate unrelated sections.
26 +- Do not use color alone: include text, shape, or icon state.
27 +- Keep all UI labels lowercase.
29 +## shared controls
31 +New small QML files in the same directory:
33 +- `PopupSurface.qml`: rounded popup frame, padding, background, optional border. `PopoutHost` uses this as its single frame; individual panels do not nest another surface.
34 +- `PopupSection.qml`: title row plus body slot.
35 +- `PopupCard.qml`: reusable rounded card with active/revealed/attention/destructive roles and hover/press feedback.
36 +- `PopupButton.qml`: button/toggle pill with role, checked, hover, press, disabled states.
37 +- `PopupDivider.qml`: subtle separator used sparingly.
38 +- `PopupTextField.qml`: shared password/text input container.
40 +These controls wrap existing `NuguText` and `Theme`; they do not introduce business logic.
42 +## behavior fixes
44 +### notifications
46 +`toggleDnd()` must suppress future non-critical toasts and immediately clear current non-critical toasts. Critical toasts still bypass DND. The existing `SUPER+ESC` niri binding must route to `notificationsDismissToasts()` and clear every active toast, including critical toasts, without deleting notification history.
48 +### network
50 +Keep iwd as the authoritative read/write path. Diagnose and fix the empty-row failure in its managed-object/ordered-network refresh before adding another backend. Quickshell Networking may supply connectivity status only; it must not create a second Wi-Fi row model or write path. Buttons use `PopupButton` for visible hover/press feedback.
52 +### tray
54 +Use documented SystemTrayItem data: title, tooltipTitle, tooltipDescription, icon, status, category, hasMenu, onlyMenu. Card left click activates or displays menu when item is only-menu. Right click displays native menu when available. Middle click calls secondaryActivate. Cards become wider/taller with tooltip/status/category metadata.
56 +### stray lines
58 +Remove decorative hard accent lines that read as rendering artifacts: launcher bottom stripe, audio left accent strips on rounded cards. Active cards should use border/fill/state, not exposed edge slivers.
60 +## migration strategy
62 +Start with shared controls and bug fixes. Then migrate every registered popup, replacing duplicated controls when their role matches a shared component. Bespoke data visualization may remain bespoke. Service APIs stay unchanged except for the explicit notification and tray routes above.
64 +## tests
66 +- Add a failing pure-JS test first for each network shaping defect, then fix it.
67 +- Extend the existing notification QML self-test before changing DND/toast behavior; exercise it through the existing IPC route.
68 +- Add no test-only production QML behavior.
69 +- Run targeted tests with `just test <stem>`, all JS tests with `just test`, format with `just fmt`, then run the zero-warning gate with `just lint`.
71 +## acceptance
73 +- DND visibly changes state, removes current non-critical toasts, and suppresses later non-critical toasts.
74 +- `SUPER+ESC` removes all visible toasts while history remains.
75 +- Connected Wi-Fi and scan rows render when iwd reports them; scan/toggle/action controls visibly react to hover and press.
76 +- Tray cards show all nonempty documented metadata; left/right/middle clicks follow the routes above.
77 +- Launcher has no bottom stripe; audio cards have no left accent sliver.
78 +- Every registered popup uses the shared surface and shared controls for matching roles.
79 +- `just test` and `just lint` pass without warnings.