#+TITLE: Desktop-Settings Dropdown Panel
#+AUTHOR: Craig Jennings
#+DATE: 2026-07-02
#+TODO: TODO | DONE
#+TODO: DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED

* DRAFT Desktop-Settings Dropdown Panel
:PROPERTIES:
:ID:       d6bb1e73-ec90-4327-85ee-bfa762da5bce
:END:
- 2026-07-04 Sat @ 12:36:56 -0500 — retrofitted by spec-sort; status set to DRAFT (evidence-based, human-confirmed)

* DRAFT Status
:PROPERTIES:
:ID:       fb7eec22-a214-4568-82c4-903612f4832f
:END:
- [2026-07-04 Sat] DRAFT — all four decisions resolved by Craig (dim + airplane collapse into the panel, touchpad + caffeine stay on the bar; Super+Shift+G keybind; code in dotfiles settings/ beside net/; 5% brightness floor). The four collapse/keybind/location/floor decisions are closed; one open scoping question remains ("few other things" — see Decisions) before a spec-review can flip it READY.
- [2026-07-03 Fri] DRAFT update — from the waybar/panel-family design
  discussion: adopt the instrument-console faceplate aesthetic net + bt
  shipped (lamps, engraved sections, console keys, machined plate), not just
  the raw palette; add the audio panel as a sibling in the panel family;
  cross-reference the shared faceplate CSS. Toggle-consolidation scope (the
  "few other things") still open — see the Decisions section.
- [2026-07-02 Thu] DRAFT — initial spec from the todo.org task "Desktop-settings
  dropdown panel" (2026-06-24 review), updated for the Blueprint/GTK4 pipeline
  the net panel stood up 2026-07-01.

* Metadata

| Field  | Value                                        |
|--------+----------------------------------------------|
| Status | draft                                        |
|--------+----------------------------------------------|
| Owner  | Craig Jennings                               |
|--------+----------------------------------------------|
| Repo   | dotfiles                                     |
|--------+----------------------------------------------|
| Kin    | net panel (architecture donor), theme studio |
|        | audio panel (sibling), bt panel (aesthetic)  |
|--------+----------------------------------------------|

* Problem

Desktop toggles are scattered: dim, caffeine/idle, touchpad/mouse, airplane
mode each own a bar module and a keybind; brightness and keyboard-backlight
have keybinds but no visible control or level readout. The bar is running out
of glanceable width (hence the collapse arrows), and sliders can't live in
waybar at all. One settings dropdown — a gear glyph opening a small panel —
gathers them.

* Goals

1. One panel with every desktop toggle + slider: auto-dim, idle/caffeine,
   touchpad, mouse, airplane (laptop-only), screen brightness, keyboard
   backlight.
2. Conditional rows appear only when the hardware/context applies (mouse
   present, trackpad present, battery present) — reuse the detection the
   airplane/touchpad indicators already do.
3. Every control reflects live state and verifies its action took (the net
   panel's verify-everything contract).
4. Bar stays the quick layer: which standalone indicators survive is a
   decision below.

* Design sketch

** Architecture — clone the net panel's proven stack

- GTK4 + gtk4-layer-shell, Blueprint .blp sources compiled to committed .ui
  (=make ui=; dev-only build dependency, fresh clones run without the
  compiler).
- Humble-object split: a GTK-free PanelModel presenter (unit-tested to 100%
  like the net PanelModel) + thin composite-widget pages. Backing actions in
  a GTK-free settings.py that shells out to brightnessctl / hyprctl / the
  existing toggle scripts, TDD'd with fake binaries like every dotfiles
  suite.
- One gated AT-SPI smoke (the run-panel-smoke.sh pattern), no bespoke
  headless widget suite.
- Instrument-console faceplate aesthetic, consistent with net + bt + audio:
  the machined gradient plate, glowing status lamps, engraved section labels,
  physical console keys for the toggles, and (where a level applies) needle
  gauges. Load the shared instrument-console palette/faceplate CSS asset all
  the family panels use — factor it once, don't duplicate (feeds the
  theme-studio task later).

** Controls and their backings

| Control            | Backing                                      |
|--------------------+----------------------------------------------|
| Auto-dim toggle    | hyprctl decoration:dim_inactive (dim-toggle) |
|--------------------+----------------------------------------------|
| Idle / caffeine    | hypridle start/stop (caffeine-toggle)        |
|--------------------+----------------------------------------------|
| Touchpad toggle    | toggle-touchpad + touchpad-state file        |
|--------------------+----------------------------------------------|
| Mouse toggle       | same mechanism, mouse-state file             |
|--------------------+----------------------------------------------|
| Airplane mode      | airplane-mode script (laptop-only row)       |
|--------------------+----------------------------------------------|
| Screen brightness  | brightnessctl (backlight class), slider + %  |
|--------------------+----------------------------------------------|
| Keyboard backlight | brightnessctl (kbd_backlight class), slider  |
|--------------------+----------------------------------------------|

Slider changes apply live (throttled) and read back the actual level after
apply — verify-everything. Toggles re-read their source of truth after
firing, same as the bar indicators do, and the bar modules get their refresh
signals so both surfaces agree.

** Open/close behavior

Gear glyph module on the bar right cluster; click toggles the panel
(layer-shell anchored under the bar, right-aligned). Focus-out auto-hide +
Close button, matching the net panel. Keybind: Super+Shift+G (decision B).

* Decisions (Craig)

** DONE Which standalone bar indicators collapse into the panel?
CLOSED: [2026-07-04 Sat]
Resolved (Craig, 2026-07-04): touchpad and caffeine stay on the bar (glanceable state); auto-dim and airplane move into the panel (panel-only, freeing bar width). The airplane Super+Shift+A toggle keybind stays as the quick lane — only its bar indicator collapses in.

** DONE Keybind for the panel?
CLOSED: [2026-07-04 Sat]
Resolved (Craig, 2026-07-04): Super+Shift+G (gear), for parity with the other panels' fast path.

** DONE Where does the code live?
CLOSED: [2026-07-04 Sat]
Resolved (Craig, 2026-07-04): dotfiles =settings/= sibling to =net/= (same src-layout, tests in tests/settings/), sharing the palette css. The net panel is the architecture donor; the old in-tree pocketbook-style note is out.

** DONE Slider granularity and floor
CLOSED: [2026-07-04 Sat]
Resolved (Craig, 2026-07-04): 5% floor on the brightness slider, so a dark-room drag can't black the screen out and lock you out. brightnessctl's 0-100% range clamps to a 5% minimum.

** TODO What are the "few other things" beyond the toggles?
The 2026-07-03 discussion named consolidating the toggle buttons "and a few
other things" into this panel, but the extras weren't enumerated. Current
control list (above): auto-dim, idle/caffeine, touchpad, mouse, airplane,
screen brightness, keyboard backlight. Candidates raised or adjacent —
confirm which belong here vs the audio panel vs the bar: night-light / color
temperature, a theme/dupre-vs-hudson switch (theme-studio kin), volume or a
master-mute mirror (or leave all audio to the audio panel), a
notifications/do-not-disturb toggle (dunst), lock/suspend actions. Craig to
name the set.

*** 2026-07-04 Sat — Craig's input (roam capture): the set includes a wallpaper manager
Confirmed the panel gathers the mouse/trackpad toggle, a no-sleep (idle-inhibit) toggle, and the auto-dim toggle, and adds a *wallpaper manager* (this is where the displaced waypaper functionality lands — see the media/keybind change that freed Super+Shift+P). The wallpaper manager needs its own depth:
- take a number of directories to look in;
- switch the wallpaper with the change persisting across sessions;
- switch between two pictures at sunup / sundown (a day/night pair).
That last one implies a sun-time source (a lat/long or a sunrise/sunset lookup). The wallpaper manager is sizable enough it may want its own sub-spec rather than a single panel row; decide during the spec-review whether it's a row that opens a sub-view or a separate panel. Remaining "few other things" candidates above (night-light, theme switch, DND, lock/suspend) still await Craig's yes/no.

* Implementation phases

1. settings.py backings (brightness get/set, kbd backlight, toggle
   state readers) — pure engine, TDD with fake brightnessctl/hyprctl.
2. PanelModel presenter (rows, conditional visibility, verify-after-apply
   semantics) — unit-tested, no GTK.
3. Blueprint UI + gear bar module + open/close wiring; palette css factored
   to a shared asset; AT-SPI smoke.
4. Bar-module consolidation per decision A: drop the dim and airplane bar
   modules (now panel-only), keep touchpad and caffeine on the bar, wire the
   refresh signals so bar and panel agree, and bind Super+Shift+G.