Collection View

A collection the user can look at more than one way from a single schema — Table today, Board tomorrow, a custom gallery next — where grouping, selection and write-back must mean the same thing in every view (a task tracker with a list and a Kanban, a records surface with a spreadsheet-style grid and a status board, an admin resource with a table and a status board). Reach for it when the switch, the shared group-by, or the drag-is-a-mutation write-back is the point. Use useCollectionView alone when you want the derived data without garn's markup.

CollectionView is one data source, many looks — the meta-component that makes a table, the sortable Board, and views you write yourself feel like one product: switch from Table to Board and it's the same records, the same grouping, just a different shape. The intelligence lives below a seam. A typed field schema feeds a pure, memoized filter → sort → group → ViewData pipeline (useCollectionView); each renderer is a thin adapter that consumes the normalized ViewData and writes back only through ViewApi. That one rule — renderers never touch raw records, they mutate through the api — is what lets Table and Board share a single group-by, keeps a view-agnostic selection (a Set of record ids) alive across a switch, and makes a consumer-defined renderer a first-class citizen: a renderer is data ({ id, kind, requires, supports, render }), not a hardcoded branch, so you add a view without forking the core. It is generic over the record type, controlled or uncontrolled per axis (activeView / config / selection), and treats loading / empty / error as first-class pipeline states rather than afterthoughts.

The defining move is the write-back contract: on Board a drag across columns is a field mutation — the card's group-by value becomes the target column's value (onFieldValueChange), not a reorder. Row order is deliberately outside the engine: the pipeline buckets, it does not order, so onReorder reports a group-relative index and your records array owns the resulting order. Today it covers the schema + group-by pipeline proven through Table AND Board, plus the registry, the write-back, and the async-state slots. Filter, multi-sort, search, a built-in Switcher shell, and the List/Calendar adapters come later.

Author the schema first. CollectionField<T> (id, type, label, accessor, groupable?, options?, format?) is the linchpin — one schema drives the config UI and the pipeline. Declare options on a select group-by field so group order is fixed and an empty group stays alive (without it, dragging the last card out of a Board column deletes the column). format renders a field's cell in every renderer, so a status reads as the same chip in Table and Board.

Own the write-back. onFieldValueChange applies a mutation to your source of truth; onReorder reports a position (row order lives in your records array — move the record there or the drop snaps back). Both are typed void | Promise<void> so an optimistic layer can land later without a signature change.

Give it a stable identity and a name. A required getRowId (idempotent, never an index) keys selection, drag and React. Set aria-label / aria-labelledby on the root — it is handed to the active renderer, not the wrapper.

Compose the state slots when you want rich ones. Omit children and the root renders the active view directly; pass CollectionView.Loading / .Empty / .Error (with .View) to compose an empty message or a spinner. The slots self-gate on status — you don't branch on it yourself.

Reach past the markup with the hook. useCollectionView returns the derived ViewData with no garn markup — drive your own switcher, a KPI row, or a server render from the same engine.