houseplan-card/docs/design/600-settings-dialogs/IMPLEMENTATION-GUIDE.md

# Implementation guide: settings dialogs redesign (for the implementing Claude session)

Read this before touching code. It tells you where the four dialogs live in `Matysh/houseplan-card`, what the prototype in `reference/` means, which prototype control maps to which product state key, and what you must not change.

Verified against dev `9683a59` (v1.76.0, 2026-09-18). Re-check line numbers with `grep`; they drift.

## 0. Ground rules

1. **UI only, no global code changes.** Only the markup and styles of the four dialogs change. Every product state key, config key, resolver, save path, permission check and side effect stays exactly as it is. A new control must write the same value to the same key the old control wrote. If a visual decision in the prototype needs a behaviour change, do not improvise and do not ask the repository owner: read `OPEN-POINTS.md` (known cases with proposed defaults) and **ask JB in the chat** before implementing that dialog; keep current behaviour meanwhile.
2. **Process.** `AGENTS.md` Rule #1: product code changes only when the issue carries `S5-ready`, `S6-in-progress` or `S7-code-review` (`gh issue view <NN> --repo Matysh/houseplan-card --json labels`). Branch `issue/<NN>-settings-dialogs`. Commit trailers `Issue: #<NN>` and `User-Visible: yes`. Changelog entries in `docs/CHANGELOG.md` and `docs/CHANGELOG.ru.md` in the same commit. Class D paths (`dist/**`, `custom_components/houseplan/frontend/**`) only via `npm run bundle:sync`.
3. **Prototype JS is a design reference, not code to port.** Read `reference/*.js` to learn the markup, class names, states and copy; do not copy localStorage, demo data, the gallery shell or `room-fill.js` into the product.
4. **Priority when they disagree:** `SPEC.md` > existing House Plan contracts (data, safety, a11y, hp-dialog, touch) > prototype visuals > prototype implementation details.

## 1. Where things are in the product

| Surface | Renderer | State | Styles | Notes |
|---|---|---|---|---|
| Space settings (edit/create) | `src/houseplan-editor-runtime.ts` `_renderSpaceDialog()` (~13614) | `SpaceDialogState` in `src/space-dialog.ts`; `host._spaceDialog` | `src/styles/dialogs.styles.ts` (`.srcrow`, `.dispsection`, `.rhint`, `.colorrow`, `.areasel`, `.namein`, `.helpfieldlabel`) | `hp-dialog data-kind="space" wide`; create mode has import progress and Skip; `switchSpacePlanSource` / `touchSpaceDisplay` guard `displayTouched` |
| Space display section in onboarding | `src/houseplan-onboarding-runtime.ts` (~700–780) | same keys | same | duplicates Display + Room card rows; must get the same controls |
| General settings | `_renderSettingsDialog()` (~10340) + `_renderColorRow()` (~10090) | `host._settingsDialog` `{ colors, glowRadius, bgColor, northDeg, bgMode, sunRays, sunRayOrigin, showRoomTooltip, zigbeeTopology, radarShowLive, busy }` | same | `data-kind="settings"`; Zigbee block is `src/hp-zigbee-topology-settings.ts`; sun rays select in `src/sun-settings-view.ts`; compass `host._renderCompass()` in `houseplan-card.ts` (~10658); `_openBackupExport`, `_pickBackupImport`, `_openAlignDialog`, undo buttons |
| Room settings (edit/create) | `_renderRoomDialog()` (~13987), `_renderRoomSource()` (~13941) | `host._nameSel`, `_areaSel`, `_roomFill` ('' \| none \| lqi \| light \| temp \| custom), `_roomCustomFill`, `_roomTempMin/_roomTempMax` (strings), `_roomTempSrc/_roomHumSrc` ('' = average), `_roomSrcOpen/_roomSrcFilter`, `_roomNameScale/_roomLabelScale` (fractions) | same, `hp-dialog.roomdialog` block | `data-kind="room" wide`; temperature bounds in `src/room-temperature-controls.ts` (`roomTemperatureControls`), parsing in `space-dialog.ts` (`roomTempThresholdDraft`) |
| Device on the plan | `_renderMarkerDialog()` (~12887) + radar/vacuum sections | `host._markerDialog` (keys listed in §5) | same (`.markerlightgroup`, `.markerradios`, `.markerhelpfield`, `.ctrlchips`, `.dropbtn`, `.droppanel`, `.candlist`, `.habindingbanner`) | `data-kind="marker"`; preview `src/hp-device-preview.ts`; `*Touched` / `original*` flags drive save semantics |
| Help tooltip | `src/hp-help.ts`, used via `this._help('<i18n key>.help')` | – | own | keep as is; only its placement changes |
| Colour field today | `src/hp-color-opacity.ts` (`hp-color-opacity`, event `hp-color-opacity-change` `{color, opacity}`) | – | own | new inline field replaces it in the four dialogs only |
| Dialog shell | `src/hp-dialog.ts` (`wide` = `--hp-dialog-wide-width`, 500px) | – | own | scope width/badge changes to `:host([data-kind="…"])` |
| Bool / range inputs | `_boolInput()` (~10067, `ha-switch` fallback checkbox), `_rangeInput()` (`ha-slider`) | – | – | keep using them inside the new rows |
| i18n | `src/i18n/{en,ru,de,fr}.json`, topology strings in `src/i18n/topology/*.json`, support strings in `src/i18n/support/*.json` | – | – | parity tests reject missing keys; placeholders are a contract |
| Tests | `test/space-dialog.test.mjs`, `test/hp-dialog-contract.test.mjs`, room/space/marker unit tests; `demo/smoke_*.mjs` | – | – | `grep -l "_spaceDialog\|_settingsDialog\|_markerDialog\|roomdialog" demo/*.mjs test/*.mjs` |

## 2. Build order (suggested)

1. **Primitives first**, in one new module pair (names are a proposal): `src/settings-form-view.ts` (lit template helpers) and `src/styles/settings-form.styles.ts` (scoped under `hp-dialog[data-kind="space"], [data-kind="settings"], [data-kind="room"], [data-kind="marker"]`). Take sizes and colours from `reference/styles.css`, map colours to HA theme variables (§3). Primitives: `card(title, help?, body)`, `subsection(title, help?)`, `settingRow(icon, title, description?, help?, control)`, `compactRow(icon, title, control)`, `segmented(name, options, value, onChange, disabled?)`, `valueTiles(items)`, `colorTiles(items)`, `colorField(...)`, `chips(items, onRemove)`, `sourceButton + sourcePanel`, `footer(left, status, right)`.
2. **Colour field component** (`hp-color-field` or `compact` mode of `hp-color-opacity`): swatch = `<input type="color">`, hex text, optional opacity number (0–100 in UI, fraction in state), optional Reset. Emits the same `{color, opacity}` shape. Fallback to a hex text input when `input[type=color]` degrades.
3. **Space dialog** (edit + create + onboarding). Smallest surface, validates the primitives.
4. **General settings**, including restyling `hp-zigbee-topology-settings` and `sun-settings-view`.
5. **Room settings** (edit + create queue).
6. **Device on the plan** (largest; keep every conditional branch, §5).
7. Smokes and unit tests, i18n for four locales, changelogs, docs, `docs/design/<NN>-settings-dialogs/` with the reference and `ACCEPTANCE.md` (paired screenshots).

Gates to run before review: `npm run typecheck`, `npm test`, `npm run gate:small`, `npm run bundle:budget`, i18n parity tests, `npm run bundle:sync` for class D.

## 3. Prototype → product token mapping

| Prototype | Product |
|---|---|
| accent `#4a9ec6`, active text `#398fb8` | `var(--primary-color)` (text: same, or `color-mix` darkened for contrast on light theme) |
| active fill `#f3f9fc`, active border `#b7d5e4` | `color-mix(in srgb, var(--primary-color) 10%, var(--card-background-color))` and 30% |
| card background `#fff`, form canvas `#f6f6f6`, plate `#fafafa` | `var(--card-background-color)`, `var(--secondary-background-color)`, mix of the two |
| line `#ddd`, `#e5e5e5` | `var(--divider-color)` |
| ink `#202124`, muted `#666` / `#777`, hint `#8a949b` | `var(--primary-text-color)`, `var(--secondary-text-color)` |
| danger `#db543d` | `var(--error-color)` |
| Roboto 14 px body, 16 px h3, 20 px h2 | HA font family; keep 14/16/20 px or HA equivalents, never below 14 px body |
| radii 15 (dialog) / 11 (card) / 8 (buttons, tiles) / 7 (fields) | keep |
| 44 px controls, 40 px compact rows, 72 px value tiles, 32 px help button | keep |

Dark theme: every colour comes from the token set; the swatch shows the resolved colour without a checkerboard.

## 4. Control mapping per dialog

Value contracts. Any deviation is a bug.

### 4.1 Space settings (`SpaceDialogState`) — see `docs/FIELD-MAP-space.md` for the full table

| Prototype control | Key | Value written | Today |
|---|---|---|---|
| Space name text | `title` | string | `.namein` |
| Grid cell size number + unit | `cellCm`, `cellCmInput`, `cellCmTouched` | via `strictNumber` + `gridCellFieldToCm` (imperial kept) | `#space-cell-cm` |
| Floor plan choice cards | `source` | `'draw' \| 'file'` via `switchSpacePlanSource` | radios `plansrc` |
| Upload / Browse uploaded | `planFile`, `planUrl`, `pickSaved`, `saved*` | unchanged handlers | `_pickPlanFile`, `_toggleServerPlans` |
| Always show room borders row | `showBorders` | via `touchSpaceDisplay` | `_boolInput` |
| Zero-thickness walls segment | `zeroWallStyle` | `'dashed' \| 'solid'` | select |
| Border & name color field | `roomColor`, `roomOpacity` | hex, 0–100 | `hp-color-opacity` |
| Room fill segment | `fillMode` | `SPACE_FILL_UI_MODES` value | radios `fillmode` |
| Fill color field + Reset | `customFill` | `{c, a}` or `null` | `hp-color-opacity` + Reset |
| Comfort range | `tempMin`, `tempMax` | numbers via `strictNumber` | `.tempin` |
| Visible layers compact rows | `hideDecor`, `hideOpenings` (**UI inverted**), `showLqi` | booleans | `_boolInput` |
| Show room names row | `showNames` | via `touchSpaceDisplay` | `_boolInput` |
| Values on the card tiles | `labelTemp`, `labelHum`, `labelLqi`, `labelLight` | booleans; disabled when `!showNames`, values kept | `_boolInput` |
| Room-card font size slider + number + Reset | `cardFontScale` | fraction (UI shows %) | `_rangeInput` |
| Plan background segment | `bgMode` | `null \| 'static' \| 'daynight'` | select |
| Background color field + Reset | `bgColor` | hex or `null` | `hp-color-opacity` + Inherit button |
| Sunlight radios | `sunRays` | `null \| true \| false` | select |
| North select + degrees + compass | `northDeg` | `null` or 0–359 int; inherited value from `northDegOf(settings, {})` | number input with placeholder |
| Light-source glow row | `glowEnabled` | boolean | `_boolInput` |
| Footer Copy / Delete / Skip / Cancel / Save | – | `openSpaceCopyDialog`, `_deleteSpace`, `_skipImport`, `_saveSpaceDialog` unchanged | – |

Removed from the UI (no state change): card preview `_renderCardPreview` under the font slider; `rhint` paragraphs (text moves to `?`).

### 4.2 General settings (`host._settingsDialog`)

| Prototype control | Key | Value written | Today |
|---|---|---|---|
| Display rows | `showRoomTooltip`, `radarShowLive` | booleans | `_boolInput` |
| Zigbee links card | `zigbeeTopology` | unchanged object; `savedEnabled` from `zigbeeTopologySettingsOf(host._settings).enabled` gates provider buttons | `hp-zigbee-topology-settings` |
| Colour tiles (8 fills + 2 glow) | `colors.<key>` | `{c, a}`; UI % ↔ fraction | `_renderColorRow` |
| Glow radius | `glowRadius` | number > 0 via `strictNumber`; unit `gs.unit_m` / `gs.unit_ft` | `#gs-glow-radius` |
| Wall fill plate | `colors.wall_fill` | `{c, a}` | `_renderColorRow` |
| Plan background segment | `bgMode` | `'static' \| 'daynight'` (no null here) | select |
| Background around the plan field + Reset | `bgColor` | hex or `null` (`gs.bg_default`) | `hp-color-opacity` + button |
| North field + Clear + compass | `northDeg` | `null` or 0–359 int | input + `gs.north_clear` |
| Sunlight through windows row | `sunRays` | boolean | `_boolInput` |
| Sun rays segment | `sunRayOrigin` | `'inner' \| 'outer'` via `renderSunRayOriginSelect` callback | select |
| Data card buttons | – | `_openBackupExport`, `_pickBackupImport`, `_openAlignDialog`, `_undoPlanOptimization` unchanged; `_canEdit` gate kept | – |
| Reset to defaults | whole draft | same reset object as today's `gs.reset` button | – |

Keep `gs.sun_missing` callout when `sunStateOf(hass)` is falsy.

### 4.3 Room settings (host fields)

| Prototype control | Field | Value written | Today |
|---|---|---|---|
| Display name | `_nameSel` | string; name auto-filled from area when empty (unchanged) | `.namein` |
| Home Assistant area select | `_areaSel` | area id or '' | `.areasel` |
| "As the space" toggle | `_roomFill` | on → `''`; off → the current space fill mode as starting value (see OPEN-POINTS Q4) | first radio |
| Fill segment | `_roomFill` | `ROOM_FILL_MODES` value; non-custom clears `_roomCustomFill` (unchanged) | radios `rfill` |
| Fill color field + Reset | `_roomCustomFill` | `{c, a}` or `null` (Reset) | `hp-color-opacity` |
| Comfort range | `_roomTempMin`, `_roomTempMax` | raw strings; shown when effective fill is `temp` (`roomTemperatureControls`) | `roomtemprange` |
| Source segment + picker | `_roomTempSrc`, `_roomHumSrc`, `_roomSrcOpen`, `_roomSrcFilter` | '' or `device:…` / `entity:…` from `_roomSrcCandidates()` | `_renderRoomSource` |
| Font sizes | `_roomNameScale`, `_roomLabelScale` | fractions (UI %) | `_rangeInput` |
| Footer | – | `_roomDialogCancel`, `_saveRoomEdit`, `_saveRoom`, `_keepClosedAsPartitions` unchanged; Save disabled by the same `tempValid` / name / `canSaveNew` rules | – |

Removed from the UI: `_renderCardPreview` at the bottom.

### 4.4 Device on the plan (`host._markerDialog`)

| Prototype control | Key(s) | Notes |
|---|---|---|
| Name | `name` | – |
| Binding segment | `bindingMode` (`'virtual' \| 'ha'`) | – |
| Binding picker (button + inline panel + search + Show entities checkbox) | `binding`, `bindingOpen`, `bindingFilter`, `showEntities` | candidates from the existing list builder; `marker.binding_disabled` state kept |
| Room select | `room`, `roomTouched` | options `marker.room_auto` / `marker.room_choose` + rooms |
| Tap action select | `tapAction`, `tapActionTouched`, `tapHintAnnouncement` | keep the announcement text (Target / Now) as the hint |
| Entity to toggle select | `toggleEntity`, `toggleEntityTouched` | conditional, unchanged |
| What to run picker | `tapTarget`, `runFilter` | conditional (`tap.run`), unchanged |
| Ask for confirmation row | `tapConfirm` | hidden for `tap.none` (OPEN-POINTS Q8) |
| Controls other light sources (chips + search list) | `controls`, `controlsFilter` | existing `ctrlchips` semantics |
| Include the device temperature in the room | `useClimateTemp` | conditional (`climrow`), keep as a row |
| Light source segment | `lightRole`, `lightRoleTouched` | Auto label shows `marker.light_role_auto_yes/no` as hint |
| Leading light entity select | `lightEntity`, `lightEntityTouched` | conditional, unchanged |
| Glow mode segment, colour field, brightness slider | `glowMode`, `glowColor`, `glowBrightness`, `glowColorDrafted`, `glowBrightnessDrafted`, `glowTouched` | disabled states and messages (`glow_disabled_*`, `glow_passive_hint`) unchanged |
| Glow radius | `glowRadius` | empty = general radius |
| Icon field + clear + Pin | `icon`, `autoIcon` | `marker.icon_auto`, `marker.icon_pin_auto` |
| Display select + hint | `display` | `display.*` options; `marker.display_hint_*`; `marker.static_alarm_warning` |
| Activity pulse colour / size | `rippleColor`, `rippleSize` | conditional on display mode |
| Value source select | `valueSource`, `valueSourceTouched` | conditional on value display modes |
| Value badge toggle, source, position | `valueBadgeEnabled`, `valueBadgeSource`, `valueBadgePosition`, `valueBadgeTouched` | warnings `value_badge_static / _missing / _duplicate / _empty` |
| Display preview | – | `hp-device-preview` with its Now / Example controls, inside the tinted block |
| Icon size / rotation | `size`, `angle` | two sliders + numbers |
| Model, Link, Description, Manuals | `model`, `link`, `description`, `pdfs` | Attach via the existing file input; chips with remove |
| Additional actions: presence radar, vacuum | `radar*`, `_renderRadarSection`, `_renderVacSection` | same conditions, restyled |
| Banners | `habindingbanner`, `ha_registry_limited`, Open in HA | callouts in Basics |
| Footer | `hideFromPlan`, delete, cancel, save | `_toggleMarkerDialogVisibility`, `_deleteMarker`, `_saveMarker`, same disabled conditions |

## 5. Things the prototype does not show (implement anyway, same style)

Space create mode (import progress, Skip); onboarding Display section; General `gs.sun_missing`, undo buttons, `_canEdit` gating; Room create queue (`room.queue_progress`, Keep as walls) and `canSaveNew`; Device: Entity to toggle, What to run, Include the device temperature, Leading light entity, Value source, static alarm warning, binding banners, radar and vacuum sections, `bindingOpen` disabled state, Show button when hidden. Use `settingRow` / `selectField` / `callout` primitives; do not leave them in the old markup.

## 6. Verification checklist for the PR

- [ ] For each dialog: open, change every control once, save, diff the stored config against a run on `dev` with the same actions (byte-identical).
- [ ] Inverted layers: stored `hide_decor: true` renders Decorative layer OFF; toggling ON stores `false`.
- [ ] Space: `displayTouched` survives source switches in create mode; onboarding writes the same keys.
- [ ] Room: `''` vs mode, `null` custom fill until edited, empty temperature strings inherit.
- [ ] Device: every `*Touched` flag flips only when the user changes that control; `original*` restored on cancel.
- [ ] All `?` open the same text keys as before; no `rhint` text lost (grep the removed keys, each must be used by a `?` or intentionally deleted with a note).
- [ ] 320 / 390 / 560 / 200% text / RU / DE / FR / dark theme captures.
- [ ] Paired screenshots vs `screenshots/*.png` in `docs/design/<NN>-settings-dialogs/ACCEPTANCE.md`.