Codex

How every table / card-list page in this repo is built. The kit lives in src/components/data-view/; the living example is /labs/layout/data-view. This document is the contract between the two: the kit enforces what it can with component defaults, and this file records the rules that live in judgement.

Ten data-view modules were built here by hand before the kit existed. They converged on the same anatomy — and still drifted: two different count predicates, four different "which direction does a fresh sort start in" semantics, three Reset behaviours, and ten byte-similar copies of the options panel. A written convention decays one copy-paste at a time; a component whose defaults are the rules cannot. So the canonical order below is not a style guide to follow — it is what DataViewToolbar and ViewOptionsPanel render, and deviating requires visibly opting out.

<DataViewShell>
  <KpiStrip>…</KpiStrip>                      {/* optional */}
  <DataViewToolbar search={…} filters={…} count={…} clear={…} actions={…} options={…} />
  <DataViewChips chips={…} />                 {/* only while a panel filter narrows */}
  <ScopeTabs items={…} value={…} onChange={…} />   {/* optional */}
  <DataViewBody>…grid | table | empty…</DataViewBody>
  <DataViewPagination … />                    {/* only when paginated */}
</DataViewShell>

The page above the shell owns the single <h1> (PageHeader). The shell has no title of its own — one page, one heading; the card repeating the page title was removed deliberately (f96dfc5) and must not come back.

Every condition that narrows the set is placed by how often it is used, and every place a narrowing is shown carries its own undo. Those two rules are the whole design; the table below is what they produce.

Sort, layout and column visibility are not filters — they never narrow the set — and always live in the panel. A condition lives in exactly one home; promoting a filter to the toolbar removes it from the panel in the same change.

The clear belongs to the state, not to the control. Wherever a narrowing condition is visible, one click next to it puts that condition back to its neutral value ("All teams", an empty query). A control at its neutral value shows no ✕ — an ✕ on "All teams" is noise, and its absence is what tells the reader nothing is filtered there.

• One undo per narrowing, one Clear filters per view. With a single condition narrowing, its own ✕ is the clear — a "Clear filters" beside it is the same action twice, so it appears only from two conditions up. When the view has toolbar filters it closes the filter lane, after the count (DataViewClearFilters in the clear slot) — the count is the result, the clear is its remedy, and beside the last filter it would read as clearing only the toolbar when it also clears the chips below. Otherwise it closes the chip row (DataViewChips onClearAll); never both. Its count includes the search query (active), because a query plus one filter is two narrowings.
• A crowded toolbar may give its filters a row. When module actions leave the toolbar no room, the frequent filters may take their own region directly beneath it (a dashed seam, like any region). They are still DataViewFilters, and the view's Clear filters then closes that row — still counting the search above it. The row exists for room, not emphasis: a toolbar with space keeps its filters in the filters slot.
• Clear filters is not Reset. Clear filters puts search, toolbar filters and panel filters back to neutral and leaves the view alone — scope tab, sort, layout, columns. The panel's Reset restores the factory defaults of everything the panel holds. Two different moves, two different places.
• A toolbar filter is one control with one value. The filled trigger is the signal, the ✕ is the undo, the popup is the only editor — the same contract a removable filter pill keeps (+ Field pills that turn into Field: value ⊗ once set), worn by a select so a high-frequency filter stays one click away instead of behind "Add filter". The ✕ is a sibling laid over the trigger, never a child of it (a button inside a button is invalid, and would open the popup on its way to clearing).
• A chip only removes. Editing a panel filter happens in the panel; a chip that opens an editor is a second editor of one value.
• A filter-miss empty carries no action (feedback law): the undo controls are already on screen next to the conditions that caused it.
• The count is announced. DataViewCount is a polite live region, so a narrowing that changes the result reaches a screen reader as well as the eye.

An app screen with several views (Support, Content, Observability, the operations apps) has two layers of conditions, and they never clear each other.

• Same parts, same undo. A band condition is a DataViewSearch or a DataViewFilter like any other — filled with its own ✕ while it narrows, nothing at neutral.
• Never across layers. The band decides which slice of data the reader is looking at in every view; a button inside one view that wipes it would change the other views behind the reader's back. Likewise a band clear leaves each view's own conditions alone.
• A view's count is measured inside the screen's scope. Its total is the set the band leaves; the view's own conditions narrow from there (n / N).
• A lens is not a filter. A control with no neutral value — an observation window, a reporting period, a currency — chooses what the reader looks through, it does not hide part of a result. It stays a plain select: no fill, no ✕, not counted, never cleared.
• A filter may open narrowed. When a default narrows (Observability opens on production), the filter opens filled with its ✕ showing, so what the view hides is visible from the first paint; its ✕ and Clear filters go to neutral ("All environments"), not back to the default.
• Conditions that arrive by link (a stock cell opening the ledger for one item) have no control on the receiving page, so they are echoed as chips there, exactly like panel filters, and count toward its Clear filters.

• A card is a feature boundary. One feature = one standard Card (the shell provides it — a data view must never render bare on the page background). A page with several features shows several cards; never merge two features into one card or split one feature across two.
• Solid lines belong to card edges only. The card's own border/ring is the one solid line a feature gets. The bigger the semantic break, the heavier the divider — and nothing inside a card breaks harder than the card itself.
• Between regions inside a card: low-contrast dashed (border-b border-dashed). Toolbar, tabs, KPI strip, footer — every seam within the feature is dashed, which keeps it visually quieter than the card edge.
• Inside a region: no lines. Spacing and type size do the layering.
• Dashed also keeps its two content-level meanings — derived-commentary footnotes and placeholder/add-slot affordances. All three dashed uses agree on the grammar: dashed = subdivision or annotation within a feature, solid = the feature's outer structure.

const { view, patch, reset, page, setPage } = useDataView<ViewState>({
  id: "integrations",   // localStorage key — omit to disable persistence
  defaults: DEFAULT_VIEW,
  version: 1,           // bump when ViewState changes shape
});

• Each module keeps its view-state.ts: the ViewState type, DEFAULT_VIEW, LAYOUT_OPTIONS, SORT_OPTIONS, PAGE_SIZE. Those are module facts; the machine that runs them is the hook.
• Everything the panel edits goes in ViewState — layout, sort, filters, visibility — so persistence and Reset cover it automatically. The page number stays outside (a return visit starts on page 1) and search stays outside (a stored query is a trap: the user forgets it and thinks data lost).
• SortOption carries defaultAsc: names start ascending, numbers and dates start descending. toggleSort reads it; never hand-roll the else-branch.
• reset() restores defaults, clears the page, and removes the stored copy in one move. Wire the panel's Reset to it and nothing else.
• The page goes back to 1 whenever the SET changes — a new query, a filter, a sort, a different page size. Clamping the render is not enough: the state still holds page 3, so loosening the filter later jumps the user somewhere they never navigated to. Do both — the clamp catches the path you forgot to wire, the reset is the part the user feels. Edits that do NOT change the set (layout, a visibility toggle) leave the page where it is; jumping to page 1 because someone toggled grid/list is its own small betrayal.
• Selection is page-scoped, the count is not. A header select-all checkbox covers the rows on screen — ticking one that reaches rows the user cannot see builds a selection they cannot find to undo. Selections themselves survive paging, and the toolbar's count is what makes that visible.

List is the default layout. A module earns a Grid layout only when all three hold:

1. items have a visual subject (logo, cover, colour identity);
2. the fields a reader needs fit on a card (≤ 4 key figures);
3. the primary task is browsing, not cross-row comparison.

Finance-style many-column data fails 2 and 3 — give it List only, and put the column effort into good SortHeads. The card-list family passes (it exists to showcase cards); new pages must justify themselves against this list, not inherit the habit.

Exactly two moves, both built in: the ScopeTabs thumb slides between pills (spring 400/32), and AnimatedGrid items scale in/out at 180ms ease-out when a filter changes. Don't add a third to a data view — the data is the show.

1. {name}-data.ts — deterministic mock data (no Math.random, no new Date()).
2. view-state.ts — ViewState, DEFAULT_VIEW, LAYOUT_OPTIONS, SORT_OPTIONS (with defaultAsc), PAGE_SIZE if paginated.
3. Gallery component: useDataView + comparators + the anatomy skeleton above.
4. Filters: place each condition by frequency (see Filters) — high-frequency ones as DataViewFilters in the toolbar's filters slot, the rest in the panel with a DataViewChips row echoing them, one DataViewClearFilters in the toolbar's clear slot counting every narrowing condition.
5. Panel: fill ViewOptionsPanel's slots (layout / sort / filters / toggles), wire onReset={reset}. A control the vocabulary lacks composes inside an OptionRow — never fork the panel.
6. Page: PageHeader (title + description + actions) + PageContainer + the shell. No second heading anywhere in the card.
7. Register the route in nav-data.ts and add/extend the feature-ledger entry.

• A local copy of ViewOptionsPanel, SortHead, KpiStrip, pagination, or the empty state. The kit exists; extend it there.
• The same filter surfaced twice (toolbar ToggleGroup and a panel row).
• A chip that edits its value, or a chip echoing an always-visible control.
• An ✕ on a control at its neutral value, or a narrowing toolbar filter with no ✕ (reading it back to "All" through the popup is two steps and a search).
• A "Clear filters" shown for a single narrowing condition, or two of them in one view; a Clear filters that also resets sort, layout or the scope tab.
• A Clear filters that crosses layers (a view clearing the screen's scope, or the band clearing a view's conditions), or an ✕ on a lens.
• A filter placed among a toolbar's actions instead of its filter lane, or a linked-in condition shown as a sentence with a "Show all" link instead of a chip.
• A centred pager that enumerates every page number.
• A data view rendered without its outer Card, or two features in one card.
• A solid region separator inside a card, or any separator inside a region.
• A second heading inside the shell repeating the page title.
• Persisting the page number or the search query.
• Hardcoded layoutId strings on tab thumbs (collisions across instances).