From f1eb6a9ba5f9d47c2309ca53cea72790608f4421 Mon Sep 17 00:00:00 2001
From: Anders Olsson <anders.e.olsson@gmail.com>
Date: Mon, 8 Jun 2026 19:52:35 +0200
Subject: [PATCH] docs(specs): unify vocabulary + authority CRUD (#64)

---
 .../2026-06-08-unify-record-crud-design.md    | 182 ++++++++++++++++++
 1 file changed, 182 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-08-unify-record-crud-design.md

diff --git a/docs/superpowers/specs/2026-06-08-unify-record-crud-design.md b/docs/superpowers/specs/2026-06-08-unify-record-crud-design.md
new file mode 100644
index 0000000..edfa23f
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-08-unify-record-crud-design.md
@@ -0,0 +1,182 @@
+# Unify Vocabulary + Authority CRUD — Design
+
+**Date:** 2026-06-08
+**Status:** Approved (brainstorming) — ready for implementation planning.
+**Issue:** #64 (the duplicated Vocabulary-terms + Authorities CRUD surfaces).
+
+## Context
+
+The Vocabulary-terms and Authorities admin surfaces are two copies of one feature ("a labelled record
+with an optional external URI: filterable list + inline-edit rows + create form"). The duplication spans
+four files and ~280 lines:
+
+- `vocab/term-row.tsx` and `authorities/authority-row.tsx` are byte-for-byte twins except: the mutation
+  hooks (`useUpdateTerm`/`useDeleteTerm` vs `useUpdateAuthority`/`useDeleteAuthority`), the record type
+  (`TermView` vs `AuthorityView`), the URI-input id prefix (`term-uri-` / `auth-uri-`), the mutate-arg
+  shape (`{ vocabularyId, termId, … }` vs `{ id, kind, … }`), and the delete-confirm i18n key.
+- `authorities/authorities-page.tsx` and `vocab/vocabulary-terms.tsx` share the filter input, the
+  4-state list (loading→skeleton / error / empty / no-matches / rows), and the create form
+  (`LabelEditor` + URI input + `labels.some()` validation + `MutationError` + submit). They differ in the
+  i18n keys, the create-form heading, and (authorities only) the kind-tabs `<nav>` + `PageTitle` +
+  `Navigate` guard.
+
+A fix to inline-edit behaviour must currently be made in two places and silently drifts. (These files
+already share `LabelEditor`, `ExternalUriLink`, `DeleteConfirmDialog`, and `MutationError`.)
+
+`vocabulary-list.tsx` (vocabularies are `key`-based, not labelled records) and the `objects` RHF surface
+are intentionally **not** unified — different shapes.
+
+### Decisions (from brainstorming)
+Full unification — three shared components in `src/components/`, with `TermRow`/`AuthorityRow` and the
+two pages reduced to thin adapters. All variance is pushed into props; no generics on the row (the adapter
+owns the mutate-arg shape). Behavior-preserving — existing tests are the guard.
+
+## Components
+
+### `components/labelled-record-row.tsx` (new) — `LabelledRecordRow`
+Owns `editing` / `labels` / `uri` state. Renders the display row (`labelText` + `ExternalUriLink` + Edit
+button + `DeleteConfirmDialog`) or the edit view (`LabelEditor` + URI `<Input>` + Save/Cancel +
+`MutationError`).
+```ts
+type RecordLike = { id: string; labels: LabelView[]; external_uri: string | null };
+
+function LabelledRecordRow(props: {
+  record: RecordLike;
+  lang: string;
+  deleteConfirmKey: string;                                  // i18n key for the confirm prompt
+  savePending: boolean;                                      // update.isPending
+  saveError: unknown;                                        // update.error
+  onEditOpen: () => void;                                    // adapter calls update.reset()
+  onSave: (labels: LabelInput[], uri: string | null, done: () => void) => void;
+  onDelete: () => Promise<void>;
+}): JSX.Element;
+```
+- Edit button onClick: `onEditOpen(); setLabels(record.labels as LabelInput[]); setUri(record.external_uri ?? ""); setEditing(true);` (preserves the #63 reset-on-edit-open behaviour).
+- Save: `onSave(labels, uri.trim() || null, () => setEditing(false))`; Save disabled while `savePending`;
+  `<MutationError error={saveError} />` below the buttons.
+- The URI input id uses `useId()` (replaces the `term-uri-${id}` / `auth-uri-${id}` scheme).
+- `record.labels` is `LabelView[]`; cast to `LabelInput[]` for `LabelEditor` (same cast the current rows do).
+
+### `components/labelled-record-create-form.tsx` (new) — `LabelledRecordCreateForm`
+Owns its own `labels` / `uri` / `requiredError` state. Renders `heading` + `LabelEditor` + URI `<Input>`
+(id via `useId()`) + the `form.required` validation alert + `<MutationError error={error} />` + submit.
+```ts
+function LabelledRecordCreateForm(props: {
+  heading: ReactNode;
+  submitLabel: string;
+  pending: boolean;                                          // create.isPending
+  error: unknown;                                            // create.error
+  onCreate: (labels: LabelInput[], uri: string | null, reset: () => void) => void;
+}): JSX.Element;
+```
+- Submit: `if (!labels.some((l) => l.label)) { setRequiredError(true); return; } setRequiredError(false);
+  onCreate(labels, uri.trim() || null, () => { setLabels([]); setUri(""); });`
+- Submit button disabled while `pending`.
+
+### `components/filtered-record-list.tsx` (new) — `FilteredRecordList<T>`
+Owns the `filter` state. Renders the filter `<Input>` **always**, then (loading → `<ListSkeleton>` else the
+`<ul>`), so the filter stays visible during load (matches current behaviour).
+```ts
+function FilteredRecordList<T extends { id: string; labels: LabelView[] }>(props: {
+  records: T[] | undefined;
+  lang: string;
+  isLoading: boolean;
+  isError: boolean;
+  loadErrorText: string;
+  emptyText: string;
+  renderRow: (record: T) => ReactNode;
+}): JSX.Element;
+```
+- `const q = filter.trim().toLowerCase(); const rows = [...(records ?? [])].filter((r) => !q ||
+  labelText(r.labels, lang).toLowerCase().includes(q)).sort(byLabel(lang));`
+- List states (preserving the current logic exactly): `isError` → `loadErrorText`; `!isError &&
+  records?.length === 0` → `emptyText`; `!isError && records && records.length > 0 && rows.length === 0`
+  → `t("common.noMatches")`; else `rows.map(renderRow)`.
+- Filter input uses `aria-label={t("common.filter")}` + `placeholder={t("common.filter")}` (unchanged).
+
+### Adapters
+
+**`vocab/term-row.tsx`** keeps its public API `<TermRow vocabularyId term lang />` (its #63 test stays
+valid). Body:
+```tsx
+const update = useUpdateTerm();
+const del = useDeleteTerm();
+return (
+  <LabelledRecordRow
+    record={term}
+    lang={lang}
+    deleteConfirmKey="actions.confirmDeleteTerm"
+    savePending={update.isPending}
+    saveError={update.error}
+    onEditOpen={() => update.reset()}
+    onSave={(labels, uri, done) =>
+      update.mutate({ vocabularyId, termId: term.id, external_uri: uri, labels }, { onSuccess: done })}
+    onDelete={() => del.mutateAsync({ vocabularyId, termId: term.id })}
+  />
+);
+```
+**`authorities/authority-row.tsx`** keeps `<AuthorityRow authority kind lang />`; analogous with
+`useUpdateAuthority`/`useDeleteAuthority`, `deleteConfirmKey="actions.confirmDeleteAuthority"`, save arg
+`{ id: authority.id, kind, external_uri: uri, labels }`, delete `{ id: authority.id, kind }`.
+
+**`authorities/authorities-page.tsx`** keeps the `PageTitle`, kind `<nav>`, `Navigate` guard, breadcrumb,
+and `useDocumentTitle`. Replaces the inline filter/list with `<FilteredRecordList records={authorities}
+lang={lang} isLoading={isLoading} isError={isError} loadErrorText={t("authorities.loadError")}
+emptyText={t("authorities.empty")} renderRow={(a) => <AuthorityRow authority={a} kind={currentKind}
+lang={lang} />} />`, and the inline form with `<LabelledRecordCreateForm heading={`${t("authorities.new")} ·
+${t(\`authorities.${currentKind}\`)}`} submitLabel={t("authorities.create")} pending={create.isPending}
+error={create.error} onCreate={(labels, uri, reset) => create.mutate({ kind, external_uri: uri, labels },
+{ onSuccess: reset })} />`. (Drops the now-unused local `labels`/`uri`/`error`/`filter` state and the
+`onCreate` handler.)
+
+**`vocab/vocabulary-terms.tsx`** keeps its `vocab.terms` caption + breadcrumb. Uses `<FilteredRecordList
+records={terms} … loadErrorText={t("vocab.loadError")} emptyText={t("vocab.noTerms")} renderRow={(term) =>
+<TermRow vocabularyId={id} term={term} lang={lang} />} />` and `<LabelledRecordCreateForm
+heading={t("vocab.addTerm")} submitLabel={t("vocab.addTerm")} pending={addTerm.isPending}
+error={addTerm.error} onCreate={(labels, uri, reset) => addTerm.mutate({ vocabularyId: id, external_uri:
+uri, labels }, { onSuccess: reset })} />`.
+
+## Data flow
+No change to the query/mutation layer. Each page owns its data hooks + the page-specific chrome (nav,
+headings, breadcrumb) and hands records + render callbacks to the shared list, mutate callbacks to the
+shared create form, and per-row mutate callbacks (via the row adapters) to the shared row.
+
+## Error handling / edges
+- Inline save errors and create errors still render via `<MutationError>` (status-aware, from #63),
+  unchanged.
+- The `form.required` validation (empty labels) stays in the create form.
+- Reset-on-edit-open (`update.reset()`) preserved so a stale save error doesn't linger.
+- The empty-vs-no-matches distinction is computed from the **raw** `records` length (empty) vs the
+  **filtered** `rows` length (no matches), exactly as today.
+- `useId()` keeps URI-input ids unique across simultaneously-mounted rows/forms.
+
+## Testing
+- **Behavior guard:** existing tests stay green unchanged — `vocab/term-row.test.tsx`,
+  `authorities/authorities.test.tsx` (page filter/create/list), `vocab/vocabularies.test.tsx`
+  (out-of-scope list, must not break). Same public component APIs + DOM.
+- **New focused tests** for the three components:
+  - `labelled-record-row.test.tsx`: display → click Edit → Save calls `onSave` and closes on `done`; a
+    failed save (passing `saveError`) shows the inline error and the row stays editable; Delete invokes
+    `onDelete`.
+  - `labelled-record-create-form.test.tsx`: submit with empty labels shows `form.required` and does NOT
+    call `onCreate`; a valid submit calls `onCreate` and the `reset` clears the inputs.
+  - `filtered-record-list.test.tsx`: typing in the filter narrows the rendered rows; `records=[]` →
+    `emptyText`; non-empty records + non-matching filter → `common.noMatches`; `isError` → `loadErrorText`;
+    `isLoading` → skeleton.
+- **Gate:** `typecheck`/`lint`/`test`/`build`/`check:size`/`check:colors` green; no new i18n keys; en/sv
+  parity unaffected; no codename; no new dependency. `check:size` should not grow (net code reduction).
+
+## Acceptance criteria
+1. `LabelledRecordRow`, `LabelledRecordCreateForm`, `FilteredRecordList<T>` exist in `src/components/` with
+   the prop shapes above; `TermRow`/`AuthorityRow` and the two pages are adapters over them.
+2. `term-row.tsx` + `authority-row.tsx` no longer duplicate the row body; `authorities-page.tsx` +
+   `vocabulary-terms.tsx` no longer duplicate the filter/list/create-form body.
+3. All existing tests pass unchanged; the three new components have focused tests.
+4. No behavior change: inline edit/save/delete, create + validation, filtering, the 4 list states, the
+   authorities kind-nav, and breadcrumbs all work as before.
+5. `typecheck`/`lint`/`test`/`build`/`check:colors` green; `check:size` reported (not increased); no new
+   i18n keys; no codename; no new dependency.
+
+## Out of scope → follow-ups
+- `vocabulary-list.tsx` (key-based vocabularies) and the `objects` table/detail/RHF surface.
+- A field-definition "position"/ordering concept; server-side filtering for large vocabularies (#43).