goodwe-addon/goodwe_controller/DECISIONS/UX-13-one-layout-table.md

UX-13 — one layout table, and why UI code may now name an option key

Status: DECIDED 2026-09-27 (owner approved the UX-13 design and mockup). Card 6ab979852f3eca02fb40f69e. Amends UX-02 §3.1. Design note and mockup: goodwe-session/UX-13-design.md, UX-13-mockup.html.

1. What UX-02 said, and why it no longer fits

UX-02 built the configuration panel from the Supervisor's schema, so app/configui.py contains "no option key, no label and no rule", and test_selfconfig.py part 5 checks that the page script names no key. That kept a second copy of the option surface from drifting, and it is why the panel is a flat list of fields in schema order.

UX-13 needs things a schema cannot say: groups and sub-groups, a slider in kW for a value stored in W, a picker for an entity, a field shown only for one meter source, locked measured values, a Simple view and a setup wizard. It also needs page fields that are not options at all: one inverter card that is stored as six flat keys, solar rows that become pv_entity or pv_entities, a contract and two prices that become static_profile JSON, and a region that becomes the levies figure. None of that can be read off the schema, so some code has to name option keys.

2. The decision

Option keys may appear in UI code in exactly two files:

• app/uilayout.py, the layout table: screen → group → part → field, with control, unit, display scale, step, entity kind, when it is shown, whether it is on the Simple view or a wizard step, and whether it applies now or after a restart. Every option in config.yaml is a field, DERIVED or HIDDEN, exactly once.
• app/uimodel.py, the derivations the table names: options_to_ui() and ui_to_options(). It may name only the keys it writes.

What UX-02 made authoritative stays authoritative:

• Ranges come from the schema (uilayout.range_of()); the table writes none. A unit holds no digit.
• Labels and help come from translations/*.yaml by key. Page-only fields, group titles and choices are in app/ui_text/*.json, held to STYLE by test_messages.py.
• Rules stay in validate.py. It gains a warning tier (validate.Note, "warn" or "info") for the page. A note never blocks a save, and passing the notes list does not change the refusals returned.
• The stored blob is still the one truth. The page model carries the stored values of every derived key (keep). A derivation whose page fields are unchanged writes those values back untouched, so a blob the page cannot express survives a save of another field.

3. How it is held

• test_uilayout.py fails when config.yaml gains an option, or an inverter field, that the table does not place. It also checks that uimodel.py names only the keys it writes and that web.py and haentities.py name none.
• test_uimodel.py round-trips options → page model → JSON → options for every validator call the suite made at 652097a (scenarios/ux13/), the TEST-23 option files and config.yaml's defaults. All must be identical.
• tools/ux13_validator_calls.py compare runs those calls through the old and new validator. At P0: 261 calls, 158 refused, no refusal changed.
• test_selfconfig.py part 5 still checks the old page script; P1 moves the page into app/static/ and the same check applies there.
• P2: the Installer view (app/static/settings.js) draws from app/uipage.py, which serialises the table and names no key itself (test_uilayout part 5, test_settings part 2). The view posts its page model to the existing /config/validate and /config/save, which turn it into options with ui_to_options() before the shipped validator runs. No route was added.
• P4: the setup wizard draws the same model by each field's wizard step. Its tables (KETTLE, SHADOW) are in uilayout.py, and its live checks are rules, so they are in validate.py (setup_checks). settings.js still names no key. See UX-13-setup-wizard.
• P5: the page words are in app/ui_text/en.json and nl.json, one key set, loaded by app/uitext.py with an English fallback per key. The page picks Dutch when the browser's language is nl, as the classic page does. Home's sentences moved from homeview.py into home_words, so /status?lang=nl builds them in Dutch. Status rows, banners, hints and validator sentences (messages.py, validate.py) stay English: they are shared with notifications, the log and the start refusal. test_ui_text.py checks both files against STYLE.md and each other, using the rules in tools/style_rules.py, which it shares with test_messages.py.
• P5: "Other time windows" is a list editor (ui.periods, control period_list). uimodel._periods_json() builds static_profile and names the first bad time, empty price, overlap or gap. Its tiling rule matches static_tariff._check_tiling. A stored profile whose days the editor has no choice for (for example "mon,wed") is still kept as stored and edited in the Configuration tab. Supervisor 2026.08.0's AppOptions accepted all 133 wizard blobs, 17 of them with time windows (tools/ux13_wizard_blobs.py --supervisor, run offline on 2026-09-28).
• P3: Settings, Simple draws the fields the table marks simple, with an optional note under each (words in settings.simple.note), plus the batteries' switches and modes. Those are store state set through the existing /action values, not options, so the table places no key for them. The Batteries screen's Now, Today and Why lines are built in homeview.py from what the add-on knows this cycle; the plan per mode is OPT-11 P3/P4, so until then Today says "Not planned yet" when no block is planned for the battery (test_batteries_screen.py).

4. What this costs

The table is a second place that knows the option surface, which UX-02 set out to avoid. The cost is bounded by the coverage test: an option added to config.yaml and not placed here fails CI, rather than silently missing from the page. Changing a key's type or range needs no change here.