docs(19.6.1-05): complete persist relation labels plan

This commit is contained in:
Jakub Zych
2026-10-22 14:43:34 +02:00
parent 51e1a1ea6e
commit 007c68bab2
4 changed files with 476 additions and 24 deletions

View File

@@ -0,0 +1,247 @@
---
phase: 19.6.1-backend-administrators-screen
plan: 05
type: execute
wave: 5
depends_on: ["19.6.1-01", "19.6.1-02", "19.6.1-03", "19.6.1-04"]
files_modified:
- admin/src/components/form/formContext.ts
- admin/src/views/FormView.vue
- admin/src/components/relation/RelationChildModal.vue
- admin/src/components/form/fields/RelationField.vue
- admin/tests/form/RelationField.test.ts
- admin/tests/form/FormView.test.ts
- modules/boardwalk/dist
autonomous: true
gap_closure: true
gap_ids: [G-19.6.1-T2]
requirements: []
estimate:
tokens: 35000
raw_tokens: 35000
tasks: 2
confidence: high
must_haves:
truths:
- "G-19.6.1-T2: After picking a relation option on a tabbed form, switching tabs and coming back still shows that option's name, not String(id)."
- "A remounted RelationField seeds its id→label cache from the form's remembered labels, not only from the server meta.labels captured at load."
- "modules/boardwalk/dist matches a fresh admin build so the embedded SPA used by the local demo carries the fix."
artifacts:
- path: "admin/src/components/form/formContext.ts"
provides: "FORM_REMEMBER_LABEL injection key"
contains: "FORM_REMEMBER_LABEL"
- path: "admin/src/views/FormView.vue"
provides: "FormView persists picked relation labels on the labels ref"
contains: "FORM_REMEMBER_LABEL"
- path: "admin/src/components/form/fields/RelationField.vue"
provides: "choose() remembers the picked option on the form before emit"
contains: "rememberLabel"
- path: "admin/tests/form/FormView.test.ts"
provides: "tab-switch backstop for a picked relation label"
contains: "keeps a picked relation label after switching tabs"
- path: "admin/tests/form/RelationField.test.ts"
provides: "unit backstop: remount with remembered labels shows the name"
contains: "shows a picked label after remount when the form remembered it"
- path: "modules/boardwalk/dist"
provides: "embedded admin build includes the remount-safe labels"
contains: "index.html"
key_links:
- from: "admin/src/components/form/fields/RelationField.vue"
to: "admin/src/components/form/formContext.ts"
via: "choose injects FORM_REMEMBER_LABEL and writes the picked option before update:modelValue"
pattern: "FORM_REMEMBER_LABEL"
- from: "admin/src/views/FormView.vue"
to: "admin/src/components/form/fields/RelationField.vue"
via: "remembered labels flow back as props.labels so remount's watch seeds known"
pattern: "rememberRelationLabel"
prohibitions:
- statement: "Do not keep inactive tab panels mounted with v-show (or otherwise render every tab's fields). That would change trigger hide-tab, ML locale reset, and field mount cost. Persist labels; keep the current one-panel FormGrid."
status: unresolved
verification: grep
- statement: "Do not edit 19.6.1-01/02/03/04-PLAN.md. Do not change cabana Go, pact, phrasebook, YAML screens, or OpenAPI. No new npm dependency."
status: unresolved
verification: grep
- statement: "Framework code, READMEs, docs and tests name no consuming application."
status: unresolved
verification: grep
---
## Phase Goal
ROADMAP Goal (not a user story; MVP mode off): cabana gets WinterCMS's Administrators screens with privilege rules on the server.
This plan's slice (plan 5 of 5, wave 5, gap_closure): close UAT gap G-19.6.1-T2 (test 2, minor). After picking a role (or any relation) on the Administrators form, switching to another tab and back shows the option name, not the raw id. Save already assigned the role; this is labeling only. Ignore CR-01 / WR-03 (closed by plan 04) and IN-01..IN-06.
## Why plan 04 did not close this
Plan 04 `gap_ids` were `[G-19.6.1-1, G-19.6.1-2]` from VERIFICATION.md review findings (CR-01 code-declared role capture, WR-03 contributed Run skip of guardOutranked). The dropdown issue lived only in `19.6.1-UAT.md` ## Gaps, had no `gap_id`, and VERIFICATION.md called it "not a gap-closure item and not a failed must-have". Plan 04 also prohibited SPA changes. `--gaps-only` therefore never selected this truth.
## Spec-less probe fallback
Spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip). Edge row is the UAT diagnosis already on disk.
## Discovery
Level 0: existing RelationField `known` cache, FormView `labels` ref, FormView `panelFields` (active tab only). No new dependency.
## Decisions taken in this plan
- Persist picked labels on the form. Do not v-show inactive tabs.
- New inject `FORM_REMEMBER_LABEL`: `(field: string, option: RelationOption) => void`. FormView and RelationChildModal provide it. RelationField calls it from `choose` when `entry.value !== null` (single and multiple), using `entry.label` and `entry.locked`. A missing provider is a no-op (standalone mount, settings pages without labels).
- FormView helper `rememberRelationLabel` merges the option into `labels.value[field]` by `value` (replace same id, append otherwise). `adopt()` still replaces labels from the server response on load/save.
- RelationField's existing `watch(() => props.labels, remember, { immediate: true })` and `labelOf` stay. Remount seeds `known` from the updated `props.labels`.
- Test names: `keeps a picked relation label after switching tabs` (FormView.test.ts) and `shows a picked label after remount when the form remembered it` (RelationField.test.ts).
## Source coverage (this gap plan)
| Source | Item | Plan | Status |
|---|---|---|---|
| UAT Gaps | G-19.6.1-T2 / test 2 role dropdown id after tab switch | 05 | COVERED |
| VERIFICATION gaps | G-19.6.1-1 / CR-01 | 04 | COVERED (prior) |
| VERIFICATION gaps | G-19.6.1-2 / WR-03 | 04 | COVERED (prior) |
## UI Considerations
No new tokens, colours, or components. The combobox already shows `labelOf(id)`. This plan only keeps that map populated across a tab remount.
| Category | Element | Status | Resolution |
|----------|---------|--------|------------|
| display | Relation single combobox after tab switch | covered | Form remembers the picked `{value,label}`; remount seeds `known` from `props.labels` |
| display | Relation multiple chips after tab switch | covered | same remember path from `choose` |
## Artifacts this phase produces
- `FORM_REMEMBER_LABEL` in `formContext.ts`.
- FormView + RelationChildModal providers; RelationField `choose` write.
- Two vitest names above.
- Rebuilt `modules/boardwalk/dist`.
<objective>
Close G-19.6.1-T2: a picked relation option keeps its name when FormView unmounts the field on a tab switch and remounts it.
Purpose: UAT test 2 labeling. Save is already correct.
Output: inject + two providers + choose() write, two vitest names, rebuilt boardwalk dist. No Go/pact/YAML. Skip git commit (orchestrator commits). Skip STATE.md raw edits.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/19.6.1-backend-administrators-screen/19.6.1-UAT.md
@.planning/phases/19.6.1-backend-administrators-screen/19.6.1-VERIFICATION.md
@.planning/phases/19.6.1-backend-administrators-screen/19.6.1-04-PLAN.md
@.planning/phases/19.6.1-backend-administrators-screen/19.6.1-04-SUMMARY.md
Concurrency and commits: other sessions may touch admin/ or boardwalk/dist. Before each task run `git status --porcelain -- admin modules/boardwalk/dist` and stop if a file this task edits carries someone else's uncommitted change. Stage by explicit path, never `git add -A`; leave STATE.md and state.json alone; no co-author tags. The orchestrator commits after the checker — do not git commit from this plan.
<interfaces>
- RelationField.vue: `known` Record<number,string> seeded by `watch(() => props.labels, remember, { immediate: true })`. `labelOf(id)` is `known[id] ?? String(id)`. `choose(entry)` emits `update:modelValue` (id or null, or appended ids in multiple) and `closeList()`. It does not write back to the parent labels today.
- FormView.vue: `labels` ref assigned in `adopt()` from `record.meta.labels`. `panelFields` filters `tabOf(field) === activeTab`. One FormGrid, so inactive tab fields unmount. `update(name, value)` writes `values` only.
- RelationChildModal.vue: own `labels` ref, `adopt(record, meta)`, FormGrid, same remount if the child form is tabbed.
- formContext.ts: existing injects FORM_VALUES, FORM_PATCH, FIELD_SCOPE, FORM_TRIGGER_NOTES, FORM_FEEDBACK. Add FORM_REMEMBER_LABEL next to FIELD_SCOPE.
- RelationOption: `{ label: string; locked?: boolean; value: number }` (schema.d.ts).
- Fixtures: widgets.form-schema.json has `maker` (relation, default tab) and `serial` (text, tab Details). widgets.record.json has maker 2 / "Bolt & Co". optionsFixture.makerField has Acme Works (1) and Bolt & Co (2). FormView.test.ts already has `tab(wrapper, key)` in the D-21 describe; reuse that helper or a local copy. mountApp + mockApi as existing tests.
- Dist: `npm --prefix admin run build` writes modules/boardwalk/dist; `scripts/check-admin-dist.sh` rebuilds into a temp dir and diffs.
</interfaces>
</context>
<tasks>
<task type="tracer">
<name>Task 1: Persist picked relation labels across FormView tab remount</name>
<precondition>admin/src/components/form/fields/RelationField.vue has choose() and labelOf(); FormView.vue has labels ref, adopt(), panelFields, and a single FormGrid; formContext.ts exports FIELD_SCOPE; admin/tests/form/FormView.test.ts and RelationField.test.ts exist; git status --porcelain -- admin is empty of other sessions' edits.</precondition>
<reversibility rating="reversible">SPA-only inject and label merge; undo is a revert. No API or on-disk format change.</reversibility>
<files>admin/src/components/form/formContext.ts, admin/src/views/FormView.vue, admin/src/components/relation/RelationChildModal.vue, admin/src/components/form/fields/RelationField.vue, admin/tests/form/RelationField.test.ts, admin/tests/form/FormView.test.ts</files>
<read_first>admin/src/components/form/fields/RelationField.vue, admin/src/views/FormView.vue, admin/src/components/relation/RelationChildModal.vue, admin/src/components/form/formContext.ts, admin/src/components/form/FormGrid.vue, admin/tests/form/RelationField.test.ts, admin/tests/form/FormView.test.ts, admin/tests/fixtures/widgets.form-schema.json, admin/tests/fixtures/widgets.options.json, .planning/phases/19.6.1-backend-administrators-screen/19.6.1-UAT.md</read_first>
<action>Close G-19.6.1-T2 in one production-quality slice. Do not v-show inactive tabs. Do not change Go, pact, YAML, or OpenAPI.
formContext.ts: export `FORM_REMEMBER_LABEL` as `InjectionKey&lt;(field: string, option: RelationOption) =&gt; void&gt;` (import RelationOption from api/types). Comment: form hosts persist a picked relation option so a remounted RelationField can seed its id→label cache from props.labels; a host without a provider is a no-op.
FormView.vue: add `rememberRelationLabel(field, option)` that copies `labels.value`, replaces or appends in `labels.value[field]` by option.value, and assigns the new object. provide(FORM_REMEMBER_LABEL, rememberRelationLabel) next to the other form provides. adopt() still overwrites labels from the server.
RelationChildModal.vue: the same helper against its `labels` ref and the same provide, so a tabbed child form does not regress.
RelationField.vue: inject FORM_REMEMBER_LABEL (default undefined). In choose(), when entry.value !== null, call rememberLabel?.(props.field.name, { value: entry.value, label: entry.label, locked: entry.locked || undefined }) before emit('update:modelValue', ...). Empty (null) choice does not remember. Do not change labelOf, remember(rows), or the props.labels watch.
Tests, no consuming-application names:
RelationField.test.ts: `shows a picked label after remount when the form remembered it`. Mount with maker, modelValue 2, labels Bolt &amp; Co only, and provide FORM_REMEMBER_LABEL that records calls into a labels bag. Open the list (mockApi routes as existing), pick Acme Works (value 1). Expect the bag to contain { value: 1, label: 'Acme Works' }. Unmount. Mount again with modelValue 1 and labels from that bag (plus any previous). The combobox value is 'Acme Works', not '1'.
FormView.test.ts: `keeps a picked relation label after switching tabs`. mountApp on /acme/demo/widgets/1 with the widgets form schema (maker on the default tab, serial on Details) and GET maker options from optionsFixture.makerField. Combobox starts as Bolt &amp; Co. Open it, pick Acme Works. Click the Details tab, then the first tab (same tab() pattern as the D-21 describe). The maker combobox value is 'Acme Works', not '1'. Do not assert save.
Existing RelationField and FormView tests stay green, including D-21 hide-tab backstops (those prove we did not switch to v-show of every panel).
</action>
<verify>
<automated>npm --prefix admin run test -- tests/form/RelationField.test.ts tests/form/FormView.test.ts</automated>
<fails_when>non-zero exit, or either new it() name is missing from the run output</fails_when>
<automated>npm --prefix admin run typecheck</automated>
<fails_when>non-zero exit</fails_when>
</verify>
<acceptance_criteria>
- `grep -c 'FORM_REMEMBER_LABEL' admin/src/components/form/formContext.ts` prints at least 1.
- `grep -c 'rememberRelationLabel\|FORM_REMEMBER_LABEL' admin/src/views/FormView.vue` prints at least 2.
- `grep -c 'FORM_REMEMBER_LABEL' admin/src/components/relation/RelationChildModal.vue` prints at least 1.
- `grep -n 'function choose' -A 20 admin/src/components/form/fields/RelationField.vue | grep -c 'rememberLabel'` prints at least 1.
- `grep -c 'v-show' admin/src/views/FormView.vue` prints 0 (do not keep inactive panels mounted).
- `grep -c 'keeps a picked relation label after switching tabs' admin/tests/form/FormView.test.ts` prints 1.
- `grep -c 'shows a picked label after remount when the form remembered it' admin/tests/form/RelationField.test.ts` prints 1.
- `grep -ciE 'fonoteka|plytarium|grzyby|wavepath' admin/src/components/form/formContext.ts admin/src/views/FormView.vue admin/src/components/form/fields/RelationField.vue admin/src/components/relation/RelationChildModal.vue admin/tests/form/RelationField.test.ts admin/tests/form/FormView.test.ts` prints 0 for each file.
</acceptance_criteria>
<done>Picking a relation option, switching tabs, and coming back shows the option name. Proven by the FormView tab-switch test and the RelationField remount test.</done>
</task>
<task type="auto">
<name>Task 2: Rebuild the embedded admin dist</name>
<precondition>Task 1 source is on disk; git status --porcelain -- modules/boardwalk/dist admin/src is only this plan's files or empty; admin/node_modules exists (never run npm ci).</precondition>
<reversibility rating="reversible">Generated embed; undo is a dist revert.</reversibility>
<files>modules/boardwalk/dist</files>
<read_first>scripts/check-admin-dist.sh, admin/package.json</read_first>
<action>Rebuild the committed SPA embed so the local demo binary (go.work → boardwalk) serves the remount-safe labels. Run `npm --prefix admin run build` (vue-tsc then vite into modules/boardwalk/dist with emptyOutDir). Run `scripts/check-admin-dist.sh`. Do not commit (orchestrator commits). Do not touch admin/src in this task.</action>
<verify>
<automated>scripts/check-admin-dist.sh &amp;&amp; go test -short ./modules/boardwalk</automated>
<fails_when>non-zero exit, or check-admin-dist reports stale dist</fails_when>
</verify>
<acceptance_criteria>
- `scripts/check-admin-dist.sh` exits 0 and prints that modules/boardwalk/dist matches a fresh build.
- `test -f modules/boardwalk/dist/index.html` succeeds.
</acceptance_criteria>
<done>The embedded admin build matches the Task 1 SPA, so a `scripts/dev.sh` rebuild of sm-demo-app picks up the fix.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| admin SPA field → form labels ref | Picked option label is display-only; save still posts the id the combobox already emitted |
| options API → remember() | Labels come from the same options payload the administrator already saw |
## STRIDE Threat Register
Threat IDs continue after T-19.6.1-31.
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-19.6.1-32 | Tampering | FORM_REMEMBER_LABEL label string | low | accept | Display only; server still authorizes the posted id. Do not v-html the label (RelationField already interpolates text). |
| T-19.6.1-SC | Tampering | npm/pip/cargo installs | high | mitigate | this plan installs no package |
</threat_model>
<verification>
- After Task 1: `npm --prefix admin run test -- tests/form/RelationField.test.ts tests/form/FormView.test.ts` and `npm --prefix admin run typecheck`.
- After Task 2: `scripts/check-admin-dist.sh` and `go test -short ./modules/boardwalk`.
- Do not run Phase 19.6 fonoteka/user-plugin commands.
</verification>
<success_criteria>
- After picking a relation option on a tabbed form, switching tabs and back shows the option name, not String(id).
- The two named vitest cases exist and pass.
- modules/boardwalk/dist matches a fresh admin build.
- Plans 01-04 are untouched. No Go/pact/YAML change.
</success_criteria>

View File

@@ -0,0 +1,155 @@
---
phase: 19.6.1-backend-administrators-screen
plan: 05
subsystem: ui
tags: [admin-spa, relation-field, form-labels, boardwalk]
requires:
- phase: 19.6.1-01
provides: Administrators and Roles screens compiled from YAML
- phase: 19.6.1-02
provides: privilege ceiling, permission locks, Roles form
- phase: 19.6.1-03
provides: lifecycle tests and phase gate
- phase: 19.6.1-04
provides: CR-01 / WR-03 gap closure
provides:
- FORM_REMEMBER_LABEL inject so form hosts persist a picked relation option
- FormView and RelationChildModal merge picked labels into the labels ref
- RelationField choose() writes the option before emit so a remount seeds known
- Vitest names for remount and tab-switch labeling
- Rebuilt modules/boardwalk/dist matching a fresh admin build
affects: [19.6.1 UAT G-19.6.1-T2, embedded admin SPA]
actuals:
tokens: 2966
tasks: 2
commits: 3
plan_head_before: ba0501c2746e7ea22920701792990537c4729284
plan_head_after: 51e1a1ea6ed3f5e5aa08d07210452bf3e6622f8a
tech-stack:
added: []
patterns:
- "Form hosts persist picked RelationOption rows on the labels ref; remount seeds known from props.labels"
key-files:
created: []
modified:
- admin/src/components/form/formContext.ts
- admin/src/views/FormView.vue
- admin/src/components/relation/RelationChildModal.vue
- admin/src/components/form/fields/RelationField.vue
- admin/tests/form/RelationField.test.ts
- admin/tests/form/FormView.test.ts
- modules/boardwalk/dist
key-decisions:
- "Persist picked relation labels on the form via FORM_REMEMBER_LABEL; keep the one-panel FormGrid (do not v-show inactive tabs)"
patterns-established:
- "A remounted RelationField reads remembered labels from props.labels, not only server meta.labels from load"
requirements-completed: []
coverage:
- id: D1
description: "After picking a relation option on a tabbed form, switching tabs and coming back shows the option name, not String(id)"
verification:
- kind: unit
ref: "admin/tests/form/FormView.test.ts#keeps a picked relation label after switching tabs"
status: pass
- kind: unit
ref: "admin/tests/form/RelationField.test.ts#shows a picked label after remount when the form remembered it"
status: pass
human_judgment: false
- id: D2
description: "modules/boardwalk/dist matches a fresh admin build so the embedded SPA carries the remount-safe labels"
verification:
- kind: other
ref: "scripts/check-admin-dist.sh"
status: pass
- kind: unit
ref: "go test -short ./modules/boardwalk"
status: pass
human_judgment: false
duration: 4min
completed: 2026-10-22
status: complete
---
# Phase 19.6.1 Plan 05: Persist relation labels across tab remount Summary
**Picked relation option names persist across FormView tab remount via FORM_REMEMBER_LABEL**
## Performance
- **Duration:** 4 min
- **Started:** 2026-10-22T12:38:22Z
- **Completed:** 2026-10-22T12:42:52Z
- **Tasks:** 2
- **Files modified:** 7
## Accomplishments
- Form hosts persist a picked relation option on the labels ref so a remounted RelationField seeds its id→label cache from props.labels
- RelationField `choose()` writes `{value,label,locked}` through `FORM_REMEMBER_LABEL` before emit; empty (null) choice does not remember
- Two named vitest cases prove remount and tab-switch labeling; inactive tabs stay unmounted
- Embedded `modules/boardwalk/dist` rebuilt and matched a fresh admin build
## Task Commits
Each task was committed atomically:
1. **Task 1: Persist picked relation labels across FormView tab remount** - `14baafb` (feat)
2. **Task 2: Rebuild the embedded admin dist** - `51e1a1e` (chore)
**Plan metadata:** recorded after this file is committed.
_Note: `git rev-list` from `plan_head_before` to HEAD counted 3 commits because a concurrent `docs(19.7)` commit landed between the two task commits. This plan authored 2 production commits._
## Files Created/Modified
- `admin/src/components/form/formContext.ts` - exports `FORM_REMEMBER_LABEL`
- `admin/src/views/FormView.vue` - `rememberRelationLabel` + provide; `adopt()` still replaces labels from the server
- `admin/src/components/relation/RelationChildModal.vue` - same helper and provide for a tabbed child form
- `admin/src/components/form/fields/RelationField.vue` - `choose()` remembers a non-null option before emit
- `admin/tests/form/RelationField.test.ts` - remount backstop for a remembered label
- `admin/tests/form/FormView.test.ts` - tab-switch backstop for a picked maker label
- `modules/boardwalk/dist` - rebuilt embed (`index-BtP5LUQA.js` replaces `index-D7ALzCHi.js`; editor hash rename)
## Decisions Made
- Persist picked labels on the form via `FORM_REMEMBER_LABEL`. Do not keep inactive tab panels mounted with `v-show`.
## Deviations from Plan
None - plan executed exactly as written.
**Total deviations:** 0 auto-fixed
**Impact on plan:** None.
## Issues Encountered
- A concurrent session committed `d47d618` (`docs(19.7): create phase plans`) between Task 1 and Task 2. Measured `commits:` is 3; this plan's production commits are `14baafb` and `51e1a1e`. Old hashed dist assets were deleted as part of the Vite rebuild (intentional).
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- G-19.6.1-T2 is closed in the SPA and the embedded dist. Phase 19.6.1 plans 01–05 are complete; ready for verify-work / UAT recheck of test 2.
- No blockers. Plans 01–04 were not edited. No Go, pact, YAML, or OpenAPI change.
## Self-Check: PASSED
- FOUND: admin/src/components/form/formContext.ts
- FOUND: admin/src/views/FormView.vue
- FOUND: admin/src/components/relation/RelationChildModal.vue
- FOUND: admin/src/components/form/fields/RelationField.vue
- FOUND: admin/tests/form/RelationField.test.ts
- FOUND: admin/tests/form/FormView.test.ts
- FOUND: modules/boardwalk/dist/index.html
- FOUND: 14baafb
- FOUND: 51e1a1e
---
*Phase: 19.6.1-backend-administrators-screen*
*Completed: 2026-10-22*