The Documents Register view-state engine

🛰️ Satellite — why a pure engine at all

The naive build wires grouping, slicing, and counting straight into the table component: rows.filter(...).sort(...), then a reduce in the JSX. It renders. It also rots — the moment a second surface needs the same grouping (a saved-view preview, a slice navigator, a footer total), the logic is trapped in one component's render and gets copy-pasted, and the only way to test "does a tag-grouped document appear in every group?" is to mount a DOM and read cells. The PRD's testing decision is explicit: assert the render model — groups, counts, totals, ordering — with no DOM-internals. So the engine has to be a plain function with plain data in and plain data out. WHY: if the brains are pure, the test is a value comparison and the table is just a renderer.

✈️ Airplane — the shape of the thing

One function, one pipeline:

buildRegisterModel(rows: RegisterDocument[], view: ViewState): RegisterModel

The engine is locale-blind and React-blind on purpose. It emits message keys (e.g. the untagged sentinel), raw data values, and numbers; the leaf components localize and format. That keeps the engine trivially unit-testable and keeps i18n where it belongs.

🔬 Microscope — the two details that earn the engine

1. Multi-membership grouping (the AC's "key case")

A document tagged Financial, Vega, Board must appear under all three tag groups — "a doc appears under every group it belongs to" (PRD). So a scalar field (document type) buckets a row once; a multi field (tags) buckets it once per value, and a value-less row falls into a localized sentinel bucket (untagged, unclassified, unfiled, …) that sorts after the real values.

const { values, sentinel } = fieldMembership(doc, groupBy);
const targets = sentinel ? [sentinelBucket] : values.map(valueBucket);
for (const target of targets) bucket(target).rows.push(doc);

The consequence the tests pin: group membership counts sum above the corpus size (a doc is counted in each group it joins), yet visibleCount — the distinct rows — is unchanged. Both numbers are true at once, and the engine reports both.

2. Mode-1 truth — nullable AI columns, not absent ones

Today the documents pipeline is Mode-1: deterministic fields (filename, size, status, format) are real; the AI fields (clean name, document type, tags, filing) are filled later by EPIC-009. The wire DTO (DocumentListItem in src/gen) carries only the Mode-1 fields. The trap is to model only what the wire has and bolt the AI columns on later — which forks the type. Instead the RegisterDocument row is the full shape with every AI field nullable, and the adapter maps a Mode-1 DTO with those fields set to null/[]. The row component reads the null and renders a live "processing…" label or a skeleton — the empty first-run state is the designed state, not an afterthought.

What shipped

Engine — src/lib/documents/register/ (pure)

Tests 40 passing

• view-state.test.ts — columns, ungrouped, single- & multi-membership grouping, slicing (value + sentinel), slice aggregation order, sorting (numeric / text / tiebreak), field-sum, hierarchy nesting, and every empty state.
• saved-view.test.ts — wire ↔ view-state round-trip, defensive drop of unknown keys, null field-sum.
• adapter.test.ts — MIME → format and Mode-1 field nulling.

Leaf components — src/components/documents/register/ (Storybook-first)

Each is a pure renderer over the engine's output, storied before any live wiring (this Story does not touch a route).

House rules honored

• Mode discipline — every AI column is nullable and renders processing/empty in Mode 1; nothing here fills them (that is EPIC-009).
• i18n — all user-facing copy resolves via next-intl under the new DocumentsRegister namespace, added to both en.json and hi.json. The engine carries keys, never display strings.
• Design tokens — no hex/rgb/hsl literals; semantic tokens only, status hues reserved for status.
• a11y — checkboxes, sort buttons, the column-menu trigger, fold carets, and slice rows are real buttons with labels, aria-pressed / aria-sort / aria-expanded.
• Contracts (HR-22) — the adapter and saved-view mapping consume generated src/gen types only; no hand-written wire mirrors, and pnpm codegen was not run (owned by the codegen-sync PR).

Verify green

pnpm typecheck   # clean
pnpm lint        # clean (1 pre-existing unrelated warning)
pnpm test        # 562 passed (40 new)
pnpm build       # success
pnpm storybook:build  # success

Observability (ADR-124): this slice adds no executable workflow boundary, route, job, or external call — it is a pure client engine + presentational leaves — so it is instrumentation-exempt; spans land when the live register page and its data fetch are wired in a later Story.

Files changed

30 file(s), +3016 / -0 lines