Codex

How every detail page — the screen one row of a data view opens into — is built, and the peek it opens into first. The kit is src/components/detail/ (+ PageHeader's eyebrow slot and the dashboard's StatTile for figures); the living examples are the deal detail (/labs/apps/crm/deals/[id]), the filing review (/labs/card-list/financial-statements/[id]), and the tasks board's peek (/labs/apps/tasks/board). Same contract as data-view.md: the kit enforces what it can with defaults, this file records the rest.

A detail page answers three questions in fixed order: which record is this (identity band), how is it doing (figure strip), everything else (feature cards + fact rail). The two pages that predated this kit had already agreed on that order and then drifted on every particular — one used a breadcrumb, one a bare arrow; one rebuilt the header band by hand, one drew a plain row; two figure-tile recipes, two fact-row styles. The kit makes the agreement structural.

In yPulse, opening a record defaults to a side panel. Works and Matrix are the references: the operator keeps the list in place while inspecting one record, checking its modules, making a small edit, and moving to the next. This profile takes precedence over the compact triage peek rules below; it does not change the yBlocks examples' existing navigation.

• Preserve the list context. Opening, switching and closing a panel keep filters, sorting, pagination and scroll position. Highlight the selected row; previous / next follow the visible view's own ordering. On close, restore focus to the initiating row when it still exists.
• The panel may contain the full record. Group related information into named sections or tabs: overview, metrics, history, configuration. Load expensive modules on demand and show loading, empty and error states in the affected module. A longer history alone does not require another page.
• Fit the available space. Desktop panels leave the list interactive; an overlay may preserve the table's geometry. A non-modal Sheet is valid here. On narrow screens, use a full-width modal detail surface with an accessible title, a visible close control and correct focus handling.
• Selection belongs in the URL. A shared link or refresh must reopen the selected record. Existing standalone detail URLs may redirect to the list with that selection. yPulse's current usePeek replaces the query entry when opening, switching and closing; browser Back is not a panel-close control. Closing is explicit (close button or Escape).
• One detail implementation. A panel does not require a second detail page or an obligatory “view details” link. If a dedicated workspace is justified, give it an explicit entry action and share the record modules and mutations. Preserve a return path to the originating list context.

The identity, status, action scope, figure reconciliation and mutation feedback laws below still apply. The 22rem width, mandatory page link and content restrictions below apply specifically to the compact triage peek.

The page is not the only way to open a record, and the second way is not a smaller page — it answers a different question.

Triage asks the second question once per row, and paying a navigation for it destroys the very thing being triaged. So a list-shaped view opens the peek, the peek links to the page, and the cut between them is width: the moment a reading needs room or completeness — a full event log, a sub-task table, a dependency list as rows, a figure strip — it belongs to the page. A peek that kept growing would end up being the record, and then the list beside it is permanently half-width for no gain.

Not every view wants one. Peek where the loop is scan → judge → next (list, table, board, my-work); go straight to the page where a click means trace this back (a calendar cell, a feed entry, an aggregate).

<PeekLayout peek={selected ? <TaskPeek … /> : null}>
  <DataViewShell>…the list…</DataViewShell>
</PeekLayout>

• The URL is the state. Selection lives in a search param via usePeek, never useState — deep-link safety (below) is not waived because the surface is small. replace, not push: a triage queue must not bury the page the user arrived from under twenty history entries.
• Non-modal, or it isn't a peek. The loop is open, judge, click the next one; a surface that must be dismissed first has taken the loop away. This is why Sheet is wrong here — it is a modal dialog, and modality is the one property this surface must not have.
• Peek and page agree. Same status chip, same vocabulary, same mutation. A fact that reads differently in the two is a bug in one of them.

<DetailHeader
  backHref="/labs/apps/crm/deals" backLabel="Deals"
  title={deal.name}
  status={<StageChip … />}
  meta={deal.company}
  chips={<><MetaChip … /><MetaChip … /></>}
  pager={<DetailPager prevHref=… nextHref=… position="3 / 12" />}
  actions={<><Button variant="outline">…</Button><Button>…</Button></>}
/>
<PageContainer>
  <DetailBody rail={<FactCard title="Details"><FactRow …/></FactCard>}>
    <FigureStrip>
      <StatTile label="VALUE" value={…} />
      …
    </FigureStrip>
    …feature cards…
  </DetailBody>
</PageContainer>

• State is identity. The record's status chip pins to the title (status slot), not to a corner of some card. When an action changes the state (Mark won, Approve), the chip is where the change must show.
• Actions are record-level or they don't belong in the header. The header's cluster holds actions on the whole record (Save, Export, Mark won); an action on one fragment (revert one edited cell) lives next to that fragment.
• Figures reconcile. Every figure in the strip derives from the same module the feature cards render; a figure that can disagree with the card explaining it is a bug, not a shortcut.
• Deep-link safe. The page must work when opened cold: breadcrumb (not history-dependent back), prerendered params where the dataset is static, notFound() for unknown ids.
• Mutations toast. Stage moves, saves, exports — every state change confirms via sonner, since the changed chip alone can be missed.

1. Route it <list>/[id] beside its list; generateStaticParams over the dataset, notFound() on a miss.
2. Compose DetailHeader — breadcrumb to the list, status chip, meta line, MetaChips, DetailPager over the same ordered dataset the list renders.
3. Body: FigureStrip of StatTiles first, then one standard Card per feature; facts into the rail as FactCards.
4. Wire actions with toasts; check the status chip reflects every state an action can produce.

• A hand-built identity band (border-b bg-card + container) instead of DetailHeader — that's a second PageHeader.
• A bare back-arrow as the only return path.
• A second <h1> inside the body repeating the record name.
• Figure tiles hand-rolled per page (rounded-xl border bg-card p-*) — that's StatTile.
• Solid separators between fact rows, or a fact list re-implemented as an ad-hoc flex stack per page.
• Record actions scattered into body cards when they act on the whole record.
• A peek in local state — unshareable, dead on refresh, and the one detail surface that breaks the deep-link law.
• A peek built on Sheet, or any surface that must be dismissed before the next row can be clicked.
• A peek that grew a history log, a nested table or a figure strip. That is the page, rendered at 22rem.
• A second ordering hand-written for the peek's prev / next instead of the one the list already renders.