biggus-dickus/docs/superpowers/specs/2026-06-04-fields-management-design.md

Fields Management — Design

Date: 2026-06-04 Status: Approved (brainstorming) — ready for implementation planning.

Context

Milestones 1–5 (merged to main at 2d0b76a) delivered the SPA foundation, object authoring, publishing, vocabulary/authority management, and search. The app shell has one disabled nav stub left: Fields. This milestone enables it — managing the flexible field definitions that form the catalogue's extensible schema (the fields the M2 object authoring form renders beyond the fixed core columns).

Like Search (M5), this is not a pure-frontend milestone. GET /api/admin/field-definitions exists (read-only), and the db layer has db::fields::create_field_definition, but there is no HTTP write route. So Fields is a combined backend + frontend slice.

After this milestone, every nav item is live — zero stubs.

Decisions (settled during brainstorming)

• Combined backend + frontend, create + list only. Expose POST /api/admin/field-definitions over the existing db::fields::create_field_definition; build the list + create UI. New field definitions are purely additive (they only add optional schema), so create is safe and useful standalone. Edit/delete is deferred — it needs new db functions and a referential-integrity policy (a field definition drives existing object data; the same concern as issue #30). File a follow-up when this lands.
• Two-pane layout (consistent with Objects/Vocabularies): grouped list of existing definitions on the left, a persistent create form on the right. No per-item detail view or :id route (definitions are create+list only and identified by key).
• Create endpoint capability = EditCatalogue (matches other catalogue writes; the existing GET uses ViewInternal).
• Ungrouped fields render under a localized "Other" heading.

Backend contract (to build)

Domain (already present — reuse, no change)

FieldType (crates/domain/src/field_definition.rs) is a discriminated union: Text | LocalizedText | Integer | Date | Boolean | Term { vocabulary_id } | Authority { kind: Option<AuthorityKind> }.

• FieldType::from_parts(data_type: &str, vocabulary_id: Option<VocabularyId>, authority_kind: Option<AuthorityKind>) -> Option<FieldType> reconstructs the type from the three stored columns and returns None for any inconsistent combination — a scalar carrying a binding, a term without a vocabulary (or with an authority kind), an authority carrying a vocabulary. This is the single validation chokepoint the handler reuses.
• NewFieldDefinition { key, field_type, required, group_key: Option<String>, labels: Vec<LocalizedLabel> }.
• db::fields::create_field_definition(conn: &mut PgConnection, new: &NewFieldDefinition) -> Result<FieldDefinitionId, sqlx::Error> (multi-statement — must be passed a transaction connection &mut *tx).

api crate — new write handler

POST /api/admin/field-definitions, capability EditCatalogue. Request body:

NewFieldDefinitionRequest {
  key: String,
  data_type: String,                 // text|localized_text|integer|date|boolean|term|authority
  vocabulary_id: Option<String>,     // required iff data_type == "term"
  authority_kind: Option<String>,    // person|organisation|place; only for "authority" (optional)
  required: bool,
  group: Option<String>,
  labels: Vec<LabelInput>,           // { lang, label } — reuse the existing LabelInput schema
}

Handler logic:

1. Parse vocabulary_id (if present) to VocabularyId (→ 400 on malformed UUID) and authority_kind (if present) to AuthorityKind by matching person|organisation|place (→ 400 otherwise).
2. FieldType::from_parts(&data_type, vocabulary_id, authority_kind) → None ⇒ 422 (covers "term without vocabulary", "authority with vocabulary", unknown type, stray binding on a scalar — all in one check).
3. Build NewFieldDefinition, run create_field_definition inside a transaction, commit.
4. On a unique-violation (duplicate key, Postgres SQLSTATE 23505) ⇒ 409; other db errors ⇒ 500.
5. Return 201 { key } (a small CreatedField { key } view).

Register in crates/api/src/openapi.rs (path + the NewFieldDefinitionRequest and CreatedField schemas). The route is added to the admin router (likely a new crates/api/src/admin_fields.rs, or alongside the existing field-definition GET in admin_objects.rs — implementer's call, following the module that already owns list_field_definitions).

Typed client

Regenerate web/src/api/schema.d.ts (run the server against the test infra + pnpm gen:api) so the path, NewFieldDefinitionRequest, and CreatedField appear.

Frontend architecture

Routes & navigation

/fields → FieldsPage (FieldList left, FieldForm right) — no nested :id route

Added under the protected AppShell. In app-shell.tsx, Fields becomes the last active NavLink; DISABLED_NAV becomes empty (the disabled-button block renders nothing / is removed). All nav items are now live.

Components / files

web/src/fields/
  fields-page.tsx     two-pane grid (FieldList left, FieldForm right)
  field-list.tsx      useFieldDefinitions, grouped by `group` (ungrouped → "Other"); rows
                      show localized label + key + data_type badge + required marker; with
                      loading / empty / error states
  field-form.tsx      the create form (key, LabelEditor sv/en, type Select, conditional
                      Vocabulary/authority-kind, group, required) → useCreateFieldDefinition
web/src/api/queries.ts   + useCreateFieldDefinition (POST; invalidates ["field-definitions"])
web/src/app.tsx          + the /fields route
web/src/shell/app-shell.tsx  enable Fields NavLink; DISABLED_NAV = []
web/src/i18n/{en,sv}.json    + fields.* namespace

FieldForm — the discriminated-union create form

• key — text Input (machine identifier).
• Labels — the shared LabelEditor (sv/en; EN required), reused from M4.
• type — Select over the 7 data types.
• Conditional: when type=term, reveal a Vocabulary Select populated from useVocabularies (reused); when type=authority, reveal an authority-kind Select (Any / Person / Organisation / Place). All other types show no extra config.
• group — optional text Input.
• required — Checkbox.
• Submit → useCreateFieldDefinition → on success invalidate ["field-definitions"] and clear the form.

Data layer

useCreateFieldDefinition() → POST /api/admin/field-definitions with the request body; invalidates ["field-definitions"]. useFieldDefinitions() and useVocabularies() already exist and are reused.

Data flow

useFieldDefinitions is the same cached query the M2 object authoring form consumes. Creating a field definition and invalidating ["field-definitions"] makes the new field appear both in the Fields list and immediately as an available field in the object editor. That shared-cache effect is the milestone's main payoff.

Validation & error handling

• Client: key non-empty (trimmed); EN label required (the LabelEditor guard); if type=term, a vocabulary must be chosen — all block submit with inline messages.
• Backend (source of truth): key uniqueness (409) and type/binding consistency (422), surfaced as a form-level form.rejected alert.
• The list has loading / empty / error states (reuse the M1 list-state patterns).

Testing

Backend (crates/api/tests/)

• POST creates a scalar field (e.g. integer) → 201; a term field with a valid vocabulary_id → 201; term without vocabulary_id → 422; duplicate key → 409; unauthenticated → 401. (Mirror the existing admin test harness — seed an editor, login, oneshot requests.)

Frontend (Vitest + RTL + MSW, onUnhandledRequest:"error")

• New MSW handler POST /api/admin/field-definitions (+ a fieldDefinitions GET fixture with at least one grouped and one ungrouped entry).
• Tests: list renders, grouped (incl. the "Other" group); creating a text field posts the expected body and clears the form; selecting Term reveals the vocabulary picker and blocks submit until one is chosen; the EN-required guard blocks submit; create invalidates ["field-definitions"]; the Fields nav item is an enabled link (and no disabled nav buttons remain).

Project constraints

• en/sv i18n key parity (authority-kind labels reuse existing authorities.*).
• No any / eslint-disable / @ts-ignore. Codename ban.
• Bundle ≤150 KB gz (current headroom ~5 KB; lazy-load /fields with React.lazy + Suspense — as M2 did for the object forms — if it pushes over, then re-verify).

Acceptance criteria

1. POST /api/admin/field-definitions creates definitions of all representative types, reuses FieldType::from_parts for consistency validation (term/authority), is EditCatalogue-gated, returns 409 on duplicate key and 422 on inconsistent type/config.
2. The Fields nav item is enabled and routes to /fields; the grouped list renders; the create form shows the conditional type config (vocabulary for term, kind for authority).
3. A newly created field appears in the Fields list and in the M2 object authoring form (shared ["field-definitions"] invalidation).
4. EN-required and term-needs-vocabulary client validation; backend 409/422 surfaced as a form-level error.
5. Web + backend CI green (cargo test; web typecheck/lint/test/build, bundle ≤150 KB gz); en/sv parity.
6. After this milestone, the app shell has no disabled nav stubs.

Out of scope / follow-ups

• Edit/delete field definitions — needs new db::fields update/delete functions and a referential-integrity policy (block/handle deleting a field that objects reference, or that is required). File a backend follow-up when this milestone lands.
• Per-field validation rules (min/max, length, regex) — already tracked as #11.
• Field reordering and group management (renaming/reordering groups).
• Changing a field's key or type after creation (immutable for now).