The Documents Register drawer — the whole truth behind one row

🛰️ Satellite — why a drawer, not a page

The stakes: a litigator triaging a 400-document matter cannot afford a full page navigation to inspect one file and lose her place in the register. The naive fix — a route per document — detonates on contact with the workflow: it unmounts the register, drops the slice/sort/scroll she built, and turns "check this one thing" into a round trip. WHY a drawer: it is an overlay on the same surface — the register stays mounted underneath, the row that opened it stays selected, and closing the drawer returns her to exactly where she was. The detail is additive, never a context switch.

And WHY the timeline matters specifically: in legal work provenance is the product. "When did this become evidence, who (or which agent) moved it there, and did anything fail?" is not metadata trivia — it is the chain of custody. The timeline surfaces document_status_events as a human-readable trail so that truth is one click from any row.

✈️ Airplane — the shape of the change

One sustained analogy: the drawer is a case file jacket. The register is the cabinet; each row is a labelled tab. Pull a tab and the jacket opens to show the same facts in full — the cover (names + format), the index card (properties), the routing slip (custody timeline), and a copy slot (download). Nothing about the cabinet changes while a jacket is open.

🔬 Microscopic — the seams that carry the truth

The view-model reuses the row, it does not re-derive it

DocumentDetail extends RegisterDocument. Every Mode-1 column the table already mapped (names, format, size, status, flags) is reused as-is; the drawer only layers on the two fields the table does not show — the AI summary and the uploader. WHY extend rather than re-fetch: one source of truth for what a document is, so the drawer and the row can never disagree.

Mode discipline — nullable, never hidden

PRD v2: Mode-2 / AI fields stay nullable until EPIC-009 fills them. A still-processing document shows "processing…" for its name/summary and "—" for the unclassified properties rather than dropping the rows. WHY render the empty truth: the first real run is a brand-new firm with an unprocessed corpus — the drawer must read honestly there, not only when fixtures carry happy data.

The timeline reads document_status_events via src/gen

// gateway.ts — trust boundary (HR-21 / ADR-061)
const upstream = await gatewayResponse<unknown>(`/documents/${docId}/status-events`);
return assertContract(documentStatusEventListResponseSchema, upstream.data, { … });

// container — generated TanStack hook → /api/internal proxy → functions
const events = useAppListDocumentStatusEvents(docId, undefined, { query: { enabled: open } });
<DocumentStatusTimeline entries={toStatusTimeline(events.data)} … />

Firm tenancy is enforced upstream: gatewayResponse attaches the caller's Clerk bearer and pramaan-functions scopes every row by firm membership — a document outside the firm 404s, never another firm's custody trail.

One-sentence recall

Click a row → a jacket opens over the same cabinet showing the full record and the custody timeline, with Mode-2 blanks rendered as honest "processing…/—".

Acceptance criteria

• ✓ Opens on row click; full record (both names, AI summary, type, derived filing type/state, tags, proceeding, uploaded-by, pages/size, download).
• ✓ Status timeline from document_status_events (FN-STATUSEVENTS via src/gen).
• ✓ Storybook stories for each leaf component (story before live wiring).
• ✓ i18n: all copy via next-intl, keys in both en.json and hi.json (parity verified).
• ✓ Design tokens only — no inline hex/rgb/hsl; semantic tokens reused from the register.
• ✓ a11y: keyboard-operable sheet, focus-visible controls, ARIA on the timeline + status.
• ✓ Empty / zero states: empty timeline, loading, fetch error, Mode-1 processing.
• ✓ Tenancy: firm-scoped server-side; assertContract at the trust boundary (HR-21).

Files changed

17 file(s), +1015 / -0 lines