120 lines
7.2 KiB
Markdown
120 lines
7.2 KiB
Markdown
# Object Detail Readability — Design
|
|
|
|
**Date:** 2026-06-07
|
|
**Status:** Approved (brainstorming) — ready for implementation planning.
|
|
**Issue:** #45.
|
|
|
|
## Context
|
|
|
|
`web/src/objects/object-detail.tsx` renders flexible field values with
|
|
`typeof value === "object" ? JSON.stringify(value) : String(value)`. Since term/authority
|
|
values are stored as **UUID strings** and `localized_text` as a `{lang: text}` **object**,
|
|
the result is: term/authority fields show a **raw UUID**, and `localized_text` shows
|
|
**`{"sv":"…"}`** JSON. Flexible fields also render in `Object.entries` (insertion) order,
|
|
ungrouped, and empty core fields vanish (layout shifts per object). This is the worst
|
|
readability defect in the screen curators read most — now more visible since the detail moved
|
|
into the new pane/drawer (#44).
|
|
|
|
The resolution machinery already exists: `useTerms(vocabulary_id)` / `useAuthorities(kind)`
|
|
and `labelText(labels, lang)` (`web/src/lib/labels.ts`) — the object form/combobox use them.
|
|
`FieldDefinitionView` carries `data_type`, `vocabulary_id`, `authority_kind`, `group`, and
|
|
`labels`.
|
|
|
|
### Decisions (from brainstorming)
|
|
1. **Client-side resolution**, reusing `useTerms`/`useAuthorities` + `labelText` (no backend
|
|
change; react-query dedups repeated vocabularies/kinds). Backend-resolved labels were
|
|
rejected for now (more work; the client machinery exists). PDF export (#39) may revisit
|
|
server-side resolution later.
|
|
2. **Scope = detail readability bundle:** value resolution + grouping/order + small polish
|
|
(date formatting, empty-core placeholders, an actions toolbar). **Excluded:** export/PDF
|
|
(#39), the object form's grouping (left to the form work / #46), backend resolution.
|
|
|
|
## Components
|
|
|
|
### `FlexibleFieldValue` (new, in `object-detail.tsx` or a sibling file)
|
|
Rendered once per flexible field — so the term/authority hooks satisfy the rules of hooks
|
|
(one hook call per component instance, not a loop). Props: `{ def: FieldDefinitionView,
|
|
value: unknown, lang: string }`. Switches on `def.data_type`:
|
|
- **`term`**: `const { data: terms } = useTerms(def.vocabulary_id)`; find `terms?.find(t => t.id === value)`; show `labelText(term.labels, lang)`.
|
|
- **`authority`**: `const { data: authorities } = useAuthorities(def.authority_kind)`; same.
|
|
- **`localized_text`**: `value` is `Record<string, string>`; show `value[lang] ?? value.en ?? Object.values(value)[0] ?? "—"`.
|
|
- **`date`**: `Intl.DateTimeFormat(i18n.language, { dateStyle: "medium" }).format(new Date(value))` — a bare date, **no `timeZone`** (would shift a date-only value).
|
|
- **`boolean`**: `value ? t("common.yes") : t("common.no")`.
|
|
- **`integer` / `text` / default**: `String(value)`.
|
|
|
|
**Fallbacks:**
|
|
- Term/authority value present but not found in the loaded set (deleted ref) → render the raw
|
|
id in muted text with a `t("objects.unknownRef")` ("(unknown)") suffix.
|
|
- Terms/authorities still loading → a muted placeholder (e.g. the id faintly, or "…").
|
|
- Empty/absent value → "—".
|
|
- `def` missing for a stored key (field definition deleted) → fall back to `String(value)` (or
|
|
the raw value) muted.
|
|
|
|
react-query keys: `["terms", vocabularyId]` / `["authorities", kind]` are shared, so N term
|
|
fields in one vocabulary cause **one** fetch (often already cached from the table/combobox).
|
|
|
|
### Detail layout changes (`object-detail.tsx`)
|
|
- **Header → actions toolbar:** left = `object_name` (`<h2>`) + `VisibilityBadge`; right =
|
|
a toolbar with **Edit** (a real `Button` linking to `/objects/:id/edit` — use `Link` +
|
|
`buttonVariants` like the table's New button, since the Base UI `Button` has no `asChild`)
|
|
and **Delete** (the existing `DeleteObjectDialog`). `PublishControl` stays below the fields.
|
|
- **Core fields render always** with a muted "—" when empty (object number, count, brief
|
|
description, current location, current owner, recorder, recording date) — stable layout.
|
|
Update the local `Field` component to show "—" instead of returning `null`. (`recording_date`
|
|
formatted as a locale date.)
|
|
- **Flexible fields grouped + ordered:** iterate `definitions` (stable API order); for each
|
|
definition whose key exists in `object.fields` with a non-null value, render
|
|
`<FlexibleFieldValue>` under a subheading for its `def.group` (null group → an "Other" /
|
|
ungrouped section rendered last). No more `Object.entries`/`JSON.stringify`.
|
|
|
|
## Data flow
|
|
`useObject(id)` + `useFieldDefinitions()` (already loaded) → group definitions by
|
|
`group` (stable order) → for each present flexible field, `FlexibleFieldValue` resolves the
|
|
display via the type-appropriate hook (`useTerms`/`useAuthorities`, react-query-cached) or
|
|
inline (localized/date/boolean/text). Core fields render directly with placeholders.
|
|
|
|
## Error handling / edges
|
|
- Deleted term/authority (id not resolvable) → muted id + "(unknown)"; never a crash or raw
|
|
JSON.
|
|
- `localized_text` with no active-language entry → English → first → "—".
|
|
- Invalid date string → fall back to the raw string (guard `Number.isNaN(date.getTime())`).
|
|
- Object with no flexible values → no flexible section (only core fields).
|
|
- A stored key with no matching definition → render the raw value muted (don't drop silently
|
|
into `JSON.stringify`).
|
|
|
|
## Testing
|
|
**Vitest + RTL + MSW** (extend `web/src/test/fixtures.ts` — it already has `fieldDefinitions`
|
|
with term/authority/localized_text/date/boolean defs, `materialTerms`, `personAuthorities`):
|
|
- A `term` field renders the term's active-locale label (not the UUID); `authority` likewise;
|
|
`localized_text` renders the active-language string (not JSON); `date` is locale-formatted;
|
|
`boolean` → yes/no.
|
|
- A term value whose id isn't in the vocabulary → muted id + "(unknown)" fallback.
|
|
- Flexible fields render **grouped** with group subheadings, in definition order.
|
|
- An empty core field shows "—".
|
|
- The Edit action links to `/objects/:id/edit`; Delete dialog present.
|
|
- Component test for `FlexibleFieldValue` covering each `data_type` + the unknown-ref fallback.
|
|
|
|
**Storybook** (per the standing preference): `FlexibleFieldValue.stories.tsx` — Term /
|
|
Authority / LocalizedText / Date / Boolean / UnknownRef variants (MSW from the preview, or
|
|
pass pre-seeded query data). Mirror the established story format.
|
|
|
|
## Acceptance criteria
|
|
1. Term and authority flexible fields display their active-locale **label** (not a UUID);
|
|
`localized_text` shows the active-language string (not JSON); date/boolean/integer/text
|
|
render readably.
|
|
2. A deleted/unknown term/authority ref degrades to a muted id + "(unknown)", never raw JSON
|
|
or a crash.
|
|
3. Flexible fields are **grouped by `def.group`** in stable definition order; empty core fields
|
|
show "—".
|
|
4. The detail header is an actions toolbar (Edit as a Button + Delete); `recording_date` is
|
|
locale-formatted.
|
|
5. A `FlexibleFieldValue` Storybook story exists; en/sv parity for new keys (`common.yes`,
|
|
`common.no`, `objects.unknownRef`); `pnpm typecheck`/`lint`/`test`/`build` green;
|
|
`check:size` within budget; no codename; no `any`/`eslint-disable`.
|
|
|
|
## Out of scope → follow-ups
|
|
- **Export / PDF** of a record (#39).
|
|
- The **object form's** flexible-field grouping/order (the form still renders flat) — left to
|
|
the form work (#46) or a small follow-up.
|
|
- **Backend-resolved labels** (would help PDF export #39 and avoid client N+1 at large scale).
|