Codex

How every kanban / workflow-board page is built. The kit is src/components/kanban/ (+ the data-view kit for the shell); the living examples are the CRM deals pipeline (/labs/apps/crm/deals) and the neutral demo (/labs/layout/kanban). Same contract as data-view.md: the kit enforces what it can with defaults, this file records the rest.

Not to be confused with the Dashboard class: a dashboard is a free grid of independent widgets, a kanban is a row of columns with meaning — each column is a workflow state, and moving a card between columns IS a state change on the record.

A kanban page is a data view whose body is a column scroller. The outer Card, the toolbar (search left, module controls, canonical order) and the count semantics all come from the data-view kit unchanged; this law adds only the body grammar — columns, cards, and the drag that mutates state.

const kb = useKanban<StageKey>({ columnOf, onMove });

<DataViewShell>
  <DataViewToolbar search={<DataViewSearch … />} actions={…} />
  <KanbanBody>
    {COLUMNS.map((c) => (
      <KanbanColumn key={c.key} label={c.label} accent={…} count={n}
        aside={fmtMoney(total)} limit={…}
        isOver={kb.overColumn === c.key} {...kb.columnProps(c.key)}
        footer={…}>
        {items.map((it) => (
          <KanbanCard key={it.id} dragging={kb.draggingId === it.id}
            {...kb.cardProps(it.id)}>
            …record content…
          </KanbanCard>
        ))}
      </KanbanColumn>
    ))}
  </KanbanBody>
</DataViewShell>

• A drop is a mutation. useKanban filters same-column drops, so onMove only fires for real state changes — and every one confirms with a toast (the moved card alone can be missed once columns scroll).
• Column headers carry the column's full truth. Count (and value totals where money is involved) live in the header and move with every drag; a drag that changes a header figure by exactly the moved record is the reconciliation rule in motion.
• WIP limits are header state, not decoration. limit renders the count as n / limit, amber at the limit, red over it. No modal, no blocking — the board shows the overload, the team decides.
• An empty column keeps a dashed drop slot. The target never collapses; dashed is the placeholder affordance (the separator grammar's second meaning).
• Drag needs a non-drag twin. HTML5 drag has no keyboard path, so the same state change must be reachable without it — the deal card links to a detail page whose stage stepper moves the deal. A board whose mutations are drag-only is incomplete.
• Filters narrow cards, never columns. Search and filters hide cards; the column skeleton stays put (an empty filtered column shows its drop slot). Hiding a whole workflow state would misreport the pipeline.
• Cards sort by a declared rule inside a column (deals: value, desc) — not by insertion order, which drifts per session. If the module needs manual ordering, that's a different feature and a different law.

1. Columns come from a domain constant (PIPELINE-like: key, label, accent); items carry a column key.
2. Durable state = base data + a moved override map; useKanban gets columnOf + onMove, and onMove writes the override and toasts.
3. Compose the anatomy above; put board-level filters in the DataViewToolbar, summary figures in its right lane.
4. Give every mutation a non-drag twin (usually the detail page).
5. Register the route, extend the feature ledger.

• A second drag implementation (hand-rolled dataTransfer wiring) beside the hook.
• Columns as standard Cards, or an item surface that isn't the record's card.
• A drop that mutates silently, or one that fires on the same column.
• An empty column that collapses to nothing, or is hidden entirely.
• Blocking a drop because a WIP limit is reached (show the red count instead).
• A board whose only route to the state change is the drag itself.