@nurix/etna 0.20.36 → 0.20.38

package/data/harnesses/code/skills/design/components/charts.md

@@ -2,75 +2,153 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Three tiers, all consuming the canonical `ChartSeries[]` / `ChartPoint` data contract (re-exported from `@nurix/components/charts`) and resolving color through tokens — no chart takes hex literals as its primary color path.
+Components: Spark, Chart, ChartErrorCard, StatusTimeline, plus the chart kernel helpers
 
-- **Tier 0 — marks only:** `spark`
-- **Tier 1 — inline charts:** `bar-graph`, `line-graph`, `pie-graph`, `progress-bar`, `sparkline`, plus the standalone families `funnel`, `gauge`, `heatmap`, `radar`, `ring`; shared chrome in `chart-primitives`
-- **Tier 2 — composable dashboard shells:** the `charts` subpath (visx-based)
+Four entry points, all resolving colour through the `--chart-*` tokens — no chart takes a hex literal as its colour path:
 
-> The old `chart` subpath (a dead recharts wrapper) was removed with the 2026-07 chart adoption — it no longer exists; the `charts` family below replaced it.
+- **Tier 0 — marks only:** `Spark` (`element/spark`) — an axis-less inline trend.
+- **Tier 1 — spec-native charts:** `Chart` (`block/chart`) — one component rendering fourteen families from a serializable `{ config, theme?, data? }` spec.
+- **Status strip:** `StatusTimeline` (`compound/status-timeline`) — one stacked bar per day, no axis; not a bar chart.
+- **Kernel:** `lib/chart-kernel` (+ `/arc`, `/colors`, `/line`) — the data contract, colour policy, formatters and geometry, for a bespoke mark neither `Chart` nor `Spark` draws.
 
 ## Spark
 
-Tier-0 inline mark — no axes, no chrome. Import from `@nurix/components/element/spark`.
+Tier-0 trend mark for a stat card or a caption — no axes, no legend, no tooltip, never a tab stop. Import from `@nurix/components/element/spark`. Install the `spark` peer family first: `@mantine/charts @mantine/core recharts`, plus `@mantine/hooks` (which `@mantine/core` peers on); no `MantineProvider` or Mantine stylesheet is needed.
 
-**Props:** `series` (`ChartSeries[]` or plain `number[]`), `type` [line|bar|pie], `filled`, `fillOpacity`, `strokeWidth` (line), `gap` (bar), `width`, `height`, `useTokens` (default false: self-contained oklch; true: `--chart-N` tokens)
+**Props:** `values` (`(number | null)[]` — a `null` is a gap, never a zero), `family` [line|area|bar|pie] (default `line`), `width` / `height` (default `100`×`30` px; a class such as `w-full` overrides the width), `color` (any CSS colour, default `currentColor`), `strokeWidth` (line and area, default `1.5`), `gap` (bar, default `2`), `colors` (pie, per slice; default the `--chart-N` palette), `animate` (default `false`), `label`
+
+- The props are a union on `family`: `strokeWidth` on bar, `gap` on line or area, `colors` off pie, and `width` or `color` on pie are type errors. A pie is a `height`×`height` square.
+- It paints in `currentColor`, so a muted caption gives a muted spark; pass `color="var(--chart-1)"` for a token colour.
+- It is `aria-hidden` until `label` names it (then `role="img"`) — a trend beside its number is decorative; a spark standing alone wants a label.
+- A table's sparkline column is `block/table`'s `TableSparkline`, never a hand-embedded `Spark`.
 
 ```tsx
-<Spark series={[4, 6, 5, 9, 7, 12]} type="line" filled width={96} height={24} />
+<Spark values={[4, 6, null, 9, 7, 12]} family="area" color="var(--chart-1)" className="w-full" />
 ```
 
-## Inline charts
+## Chart
+
+The spec-native chart. Import `Chart` from `@nurix/components/block/chart`. Install the `charts` and `animated-number` peer families first: `@visx/curve @visx/event @visx/grid @visx/group @visx/heatmap @visx/pattern @visx/responsive @visx/scale @visx/shape d3-array @number-flow/react`.
+
+**Props:** `config` (what the chart means — `version`, `family`, `title`, `format`, `overlays`, `encode`, and `x` on cartesian families), `theme` (how it is presented — `context`, `motion`, `color`, `chrome`, `interaction`, `labels`), `data` (typed by `config.family`), `loading`, `onHoverChange`, `onRangeChange`, `pinnedIndex` / `defaultPinnedIndex` / `onPinnedIndexChange`, `onValidationIssue`, `replayNonce` (bump to replay enter motion), plus `ref`, `className` and any div prop, landing on the one root in every state.
+
+- **Validation is internal and always on** — `withDefaultVersion` → `migrateSpec` → `validateChartSpec` → `diagnoseChart` → `normalize` on every render. An invalid spec never throws and never renders blank: it renders `ChartErrorCard` (`errors`, `labels`) naming the first violation's JSON Pointer. Warnings render the chart and report through `onValidationIssue`, once per distinct set.
+- **`version` is `CURRENT_VERSION` (2).** A stored spec carries its own `version`; only the JSX boundary defaults a missing one. `migrateSpec` walks a spec forward only, so a spec newer than the installed renderer is rejected, never downgraded.
+- **Every colour field takes a token slot, never a literal:** `chart-1`…`chart-5` (categorical, wrapping after five), `chart-positive`, `chart-negative`, `chart-diverging-mid`, `chart-scale-01`…`chart-scale-05`. `theme.color.palette` reorders the five categorical slots; an explicit series `color` wins over it.
+- **Size comes from the parent.** `Chart` sets only `w-full`. The `cell`/`card` backend stretches into its parent's box; the `dashboard` backend renders nothing until it measures a non-zero ancestor — an unsized parent is a silently empty chart either way.
+- **Emit-loop pre-flight:** `validateChartSpec(spec)` returns `{ ok, value | errors }`; `diagnoseChart(spec)` returns `{ errors, warnings }` over the data values (log scale over non-positive values, a palette wrap, date-like x on a category axis) — treat both as blocking before storing an artifact. `explainSpec(spec)` reports which default supplied each resolved value. `normalize` and `withDefaultVersion` are exported beside them.
+
+### Context
+
+`theme.context` is `cell`, `card` or `dashboard`; it picks density defaults, the capability envelope and the backend. An omitted context resolves from the host — `cell` inside a `data-mode="inline"` or `data-density="compact"` ancestor, otherwise `card`. **A host never implies `dashboard`**, so a dashboard-only family needs `theme: { context: "dashboard" }` or it fails validation with the recorded reason.
 
-Import via `@nurix/components/<subpath>`; each ships a matching skeleton.
+| Context | Chrome | Interaction | Motion (`auto`) | Families admitted |
+| --- | --- | --- | --- | --- |
+| `cell` | none | hover off unless turned on | none, whatever the request | line, area, bar, pie, progress, ring, gauge, stat |
+| `card` | value labels and legend, off by default | hover on, pin off | enter | line, area, bar, pie, progress, ring, gauge, stat |
+| `dashboard` | grid horizontal and both axes on; value labels and legend admissible | hover with a crosshair; `range` opt-in | full | line, area, bar, composed, scatter, funnel, heatmap-calendar, heatmap-matrix, radar |
 
-- `bar-graph` — `BarGraph`, `BarGraphSkeleton`
-- `line-graph` — `LineGraph`, `LineGraphSkeleton` (re-exports `ChartSeries`)
-- `pie-graph` — `PieGraph`, `PieGraphSkeleton` (variants pie|half-pie|doughnut|half-doughnut; doughnut variants take a `center` prop that auto-fits content in the hole)
-- `progress-bar` — `ProgressBar`, `ProgressBarSkeleton` (segmented multi-series bars; distinct from the `progress` subpath's shadcn Progress primitive)
-- `sparkline` — `Sparkline` (legacy; prefer `Spark` for new work)
+### Families and their data
 
-## Standalone chart families
+`config.family` is a closed enum, and each family takes exactly one data class. The cartesian families (`line`, `area`, `bar`, `composed`) require `x: { type: "time" | "category" | "linear", grain? }`; `scatter` requires `x: { type: "linear" | "log" | "time", grain? }`. `grain` is `hour`, `day`, `week`, `month`, `quarter` or `year`. `encode` is the one family-shaped key; an unknown key is a rejection naming the legal keys. Shared knobs keep one shape: `sort` is `"none" | "asc" | "desc"` or `{ by, order }`, `stack` is `"none" | "stacked" | "percent"`, `diverging` is `{ baseline?, positiveColor?, negativeColor? }`.
 
-Each on its own subpath with tooltip/legend/skeleton companions and full types:
+Series data is `{ series: [{ id, label, points: [{ x, y, size? }], color? }] }` — `y` may be `null`, `id` is unique and stable, series order is stacking and draw order.
 
-- `funnel` — `Funnel` (+ `FunnelTooltip`, `FunnelLegend`, `FunnelSkeleton`): ordered stage bands. **Props:** `data: FunnelData`, `orientation`, `variant` (default `halo`), `sort` (`asc` renders a pyramid), `showPercentage`/`showValues`/`showLabels`, `showDrop` (inter-stage drop-off annotation), `showTooltip`, `percentBasis` (default `first`), `color`, `layers`
-- `gauge` — `Gauge`, `Bullet`, `GaugeSkeleton`: value on a [min,max] scale. **Props:** `orientation` (arc or horizontal notch track), `value` (null renders the empty state), `min`/`max`, `zones` (threshold color bands), `target` (tick marker), `ticks`, `showTicks`/`showValues`, `valueFormat`, `centerContent` (arc only), `totalNotches`
-- `heatmap` — `Heatmap`, `HeatmapSkeleton`, `HeatmapLegend`, `HeatmapTooltip`, `HeatmapXAxis`/`HeatmapYAxis`/`HeatmapSeparator`: calendar contribution grid. **Props:** `data: HeatmapColumn[]`, `xDomain`, `layout` [fluid|fill], `binSize`, `gap`, `cornerRadius`, `levelColors` (defaults to the `--chart-scale-*` tokens)
-- `heatmap` (same subpath) — `MatrixHeatmap`, `MatrixHeatmapSkeleton`, `MatrixHeatmapLegend`, `MatrixHeatmapTooltip`: x-by-y cell matrix (`MatrixHeatmapData` dense or cell list), quantized onto the token ramp
-- `radar` — `Radar`, `RadarSkeleton`: series polygons over spider axes. **Props:** `data` (`RadarSeries[]` or `ChartSeries[]`), `metrics` (ordered axes; derived when omitted), `levels`, `scaling` [independent|shared] (default `independent` — honest mixed-unit rendering), `maxValue`, `nullMode` [zero|gap], `colors`, `size`
-- `ring` — `Ring`, `RingSkeleton`: concentric segmented progress. **Props:** `data: RingDatum[]` (innermost first), `strokeWidth`, `ringGap`, `startAngle`/`endAngle`, `lineCap`, `trackColor`, `animated`, `interactive`, `size`
+- **`line`** — multi-series lines. `encode`: `curve` [linear|smooth|step|stepAfter|stepBefore], `nulls` [gap|bridge] (default `gap`), `markers`, `diverging`, `endpointLabels`.
+- **`area`** — filled series. `encode`: `curve`, `nulls` [gap|bridge], `markers`, `diverging`, `stack`, `band: { lower, upper }` (series ids drawing a range band).
+- **`bar`** — grouped or stacked bars. `encode`: `mode` [categorical|histogram|pareto], `stack`, `horizontal`, `sort` (by `value`, `label` or a series id), `diverging`, `bins`, `binWidth`. **Histogram:** `mode: "histogram"` bins each point's raw `y` samples, so already-binned counts are binned again; `stack` and `sort` are rejected. **Pareto:** fixed descending with a cumulative-percent line; `sort` is rejected.
+- **`composed`** (dashboard) — mixed marks over one shared scale pair. `encode.series` maps each series id to `{ mark: "line" | "area" | "bar", axis?: "left" | "right" }`, at most two y axes.
+- **`scatter`** (dashboard) — x/y point field. `encode`: `yScale` [linear|log], `bubble` (reads `size`), `colorByValue`, `trend` (least-squares line), `quadrant: { x?, y?, shade? }`.
+- **`radar`** (dashboard) — series polygons over spider axes; spokes are the points' categorical `x`. `encode`: `scaling` [independent|shared], `maxValue`, `nulls` [gap|zero] (default `gap`).
+- **`pie`** (cell, card) — data `{ parts: [{ label, value, color? }] }`. `encode`: `donut`, `half`, `sort`, `maxSlices`, `otherThreshold`, `otherLabel` (Other sorts last), `minAngle`, `center` [total|none].
+- **`progress`** (cell, card) — stacked horizontal segments from `parts`, left to right; no `encode` keys; the goal tick is a `target` overlay.
+- **`funnel`** (dashboard) — ordered stage bands from `parts`, top-down. `encode`: `variant` [halo|solid] (`halo` draws concentric rings at ramping opacity), `colorMode` [single|ramp|categorical], `sort` (`asc` renders a pyramid), `showValue`, `showPercent`, `showDrop`.
+- **`gauge`** (cell, card) — data `{ value, min, max }`, the domain required. `encode`: `shape` [arc|linear|bullet], `fill` [solid|gradient|scale]. Threshold bands are `zone` overlays and the goal tick a `target` overlay — `shape: "bullet"` with zones and a target is the bullet chart. Hover is unavailable (one always-visible scalar).
+- **`ring`** (cell, card) — concentric value-vs-max rings. Data `{ rings: [{ label, value, max, color? }] }`, innermost first. `encode`: `endAngle` (narrow it for an arc-gauge look).
+- **`heatmap-calendar`** (dashboard) — contribution grid. Data `{ cells: [{ date, value }] }` with ISO dates. `encode`: `weekStartDay` (0–6), `levels`, `hideGhostCells`.
+- **`heatmap-matrix`** (dashboard) — x-by-y cell matrix on the token ramp. Data `{ cells: [{ x, y, value }] }`. `encode`: `colorScaleType` [sequential|diverging], `divergingMidpoint`, `nulls` [empty|zero|hatch] (default `empty`), `xOrder` / `yOrder` (`none`, `asc`, `desc`, `{ by, order }` or an explicit list), `aggregate` [sum|mean|max|min|count], `highlight` [none|cell|cross], `showValues`.
+- **`stat`** (cell, card) — a KPI. Data `{ value, delta?, history? }` (`history` is points). `encode.visual: { family: "line" | "bar" | "pie" | "gauge" | "ring" | "progress" }` draws a cell-scale mini-chart from stat's own data. A KPI laid out as a page unit is `Stat` (`element/stat`, see [layout](layout.md)).
 
-## Chart chrome primitives
+```tsx
+import { Chart } from "@nurix/components/block/chart";
+
+<Chart
+  config={{
+    version: 2,
+    family: "line",
+    title: "Revenue",
+    x: { type: "time", grain: "month" },
+    format: { y: { kind: "currency", currency: "USD", compact: true } },
+    encode: { curve: "smooth" },
+    overlays: [{ type: "line", y: 50000, label: "Target", color: "chart-negative" }],
+  }}
+  theme={{ context: "dashboard", chrome: { legend: "bottom" } }}
+  data={{ series: [{ id: "rev", label: "Revenue", points: [{ x: "2026-01-01", y: 42000 }, { x: "2026-02-01", y: 51000 }] }] }}
+/>
+
+<Chart
+  config={{
+    version: 2,
+    family: "gauge",
+    title: "Quota",
+    encode: { shape: "bullet" },
+    overlays: [{ type: "zone", from: 0, to: 60, color: "chart-scale-01" }, { type: "target", value: 80 }],
+  }}
+  data={{ value: 72, min: 0, max: 100 }}
+/>
+```
+
+### Chrome, interaction, overlays and labels
 
-`@nurix/components/chart-primitives` — shared tier-1 chrome: `ChartEmpty` (empty state), `ChartHoverCard` (tooltip surface; `ChartHoverCardRow`), `ChartLegend` (`ChartLegendItem`, `ChartLegendPosition`).
+The shared chart chrome — legend, tooltip, empty and error states — is set by the spec, never composed as children.
 
-## Dashboard charts (`charts` subpath)
+- **`theme.chrome`:** `grid` [none|horizontal|both], `xAxis` / `yAxis` / `yAxisRight` (`{ ticks, tickMode, format, largeNumbers, orientation }` or `false`), `legend` [none|right|bottom|inline], `valueLabels` (`true` or `{ position: "inside" | "outside", endpointOnly, total }`), `background` (a plot-area pattern). `legend` and `valueLabels` are illegal at `cell`; grid, axes and `background` are dashboard-only.
+- **`theme.interaction`:** `hover`, `pin`, `range` [none|xband|box]. `pin` is legal on bar, pie, scatter, funnel and both heatmaps; `xband` on line, area, bar and composed; `box` on scatter only. Not every handler reaches the host from every renderer — dashboard hover reaches `onHoverChange` only from the two heatmaps, pin reaches `onPinnedIndexChange` only from `funnel`, and no renderer emits `onRangeChange`.
+- **`config.overlays`:** `zone` (`from`, `to`, `color`, `label`), `target` (`value`), `line` (`x` or `y`), `dot` (`{ x, y }` or `{ resolve: "max" | "min" | "average", seriesId }`), `annotation` (`x`, `text`, `variant` [point|event]), `projection` (`seriesId`, `horizon`). Each is legal only on the families its envelope lists — `zone` on the cartesian families, scatter and gauge; `target` on line, area, bar, composed, gauge, progress and ring; `projection` on line and area.
+- **`config.format`:** `x`, `y`, `value` channels, each `{ kind: "compact" | "int" | "percent" | "currency" | "unit" | "date", … }` with optional `prefix` / `suffix`.
+- **`theme.motion`:** [none|enter|full|auto] (default `auto`, resolved by context).
+- **`theme.labels`:** every string the chart writes — `empty` ("No data"), `invalid`, `invalidName`, `more`, `didYouMean`, `total`, `loading`, `retry`.
 
-Composable visx-based shells — a shell provides scales/context, marks draw data ink, chrome and overlays compose as children. All from `@nurix/components/charts`.
+## StatusTimeline
 
-**Shells:** `AreaChart`, `BarChart` (`BarOrientation`), `LineChart`, `ScatterChart`, `ComposedChart` — plus standalone loading shells `AreaChartLoading`, `BarChartLoading`, `LineChartLoading`
+An uptime/status strip: one stacked bar per day with a shared day card on hover, focus or pin. No axis — a quantitative time series is `Chart`, a single percentage is `element/progress`. Import `StatusTimeline` and `formatDateRange` from `@nurix/components/compound/status-timeline`.
 
-**Recipes & transforms:** `Bullet`, `Histogram` (+ `computeHistogramBins`, `binsToRows`), `ParetoLine` (+ `computeParetoRows`), `BarSort`, `BarStackMode`
+**Props:** `data: StatusTimelineData[]`, `title` (a muted caption that also names the strip), `height` (px, default `50`), `spacing` [none|sm|md|lg] (default `sm`), `roundedCorners` [none|top|all] (default `top`), `isNormalized` (default `true`), `hasTrack`, `animate` (default `false`), `locale`, `labels`, `loading`, `emptyState`, `renderBar(segment, index, { day, total })`, `renderCard`, `renderEvent`, `render`
 
-**Marks:** `Area`, `RangeArea`, `Bar`, `Line` (`DivergingConfig`), `Scatter`, `SeriesBar`, `SeriesMarkers`, `ValueLabels`; curve factories `curveLinear`, `curveMonotoneX`, `curveNatural`, `curveStep`, `curveStepAfter`, `curveStepBefore` (pass to a mark's `curve` prop — never import `@visx/curve` directly)
+- One record per day: `{ day, summary?, bar: [{ intent, height }], card: [{ intent, value }], events: [{ id, name, type, from, to }] }`. `day` is an ISO date read in local time; `summary` is the card's muted header line; event `type` is `incident`, `report` or `maintenance`.
+- `isNormalized` reads `bar[].height` as a percentage of 100 per day — pass raw counts with `isNormalized={false}`, or every bar mis-fills.
+- Colour comes from `intent` (`neutral`, `info`, `success`, `warning`, `danger`) and the `--intent-*` tokens; retint by redeclaring the tokens, never a per-strip colour map.
+- `loading` renders the skeleton; there is no separate skeleton member.
+- `formatDateRange(from?, to?, { locale, labels })` formats an event's range, collapsing a same-day range.
 
-**Chrome:** `XAxis`, `YAxis`, `BarXAxis`, `BarYAxis`, `Grid`, `Background` (pattern presets), `PatternArea`, `PatternCircles`/`PatternHexagons`/`PatternLines`/`PatternWaves`
+```tsx
+<StatusTimeline
+  title="API uptime"
+  data={[{
+    day: "2026-08-07",
+    summary: "1,204 requests",
+    bar: [{ intent: "success", height: 92 }, { intent: "warning", height: 8 }],
+    card: [{ intent: "success", value: "92%" }, { intent: "warning", value: "8%" }],
+    events: [],
+  }]}
+/>
+```
 
-**Tooltip & legend:** composable subsystems re-exported whole (`./tooltip`, `./legend` internals)
+## Chart kernel
 
-**Overlays:** `ReferenceLine`, `ReferenceArea`, `ReferenceDot`, `Annotation` (`AnnotationVariant`), `ProjectionLine`, `ProfitLossLine` + `ProfitLossLegend`, `ChartBrush`
+The coherence-bearing subset of the chart core, for bespoke visualization code that must match the `Chart` system. Reach for it only for a mark neither `Chart` nor `Spark` draws; needing decimation, scatter geometry, thresholds or interaction scheduling is the signal to use a chart family — those stay unpublished.
 
-**Data contract:** `ChartPoint`, `ChartSeries`, `isChartSeriesArray`, `seriesToRows`
+- **`lib/chart-kernel`:** the data contract types `ChartSeries` (`{ id, label, points, color? }`), `ChartPoint` (`{ x, y }`), `ChartSlice`, `ColorableSeries`; the colour policy `resolveSeriesColors(series, { useTokens })` / `resolveSeriesColor(index, explicitColor?, { useTokens })`; `buildColorScale(min, max, kind)` (`sequential` by default over `--chart-scale-01..05`, or `diverging` over `--chart-negative` / `--chart-diverging-mid` / `--chart-positive`); the formatters `formatCompactNumber`, `formatPercent(ratio, precision)`, `intFmt`, `shortDateFmt`, `weekdayDateFmt`, `monthLongFmt`, `monthShortFmt`, `weekdayLongFmt`, `hmsTimeFmt`; and `isChartDataEmpty(series)`.
+- **`lib/chart-kernel/colors`:** `resolveSeriesColors`, `resolveSeriesColor` at a narrower entry.
+- **`lib/chart-kernel/arc`:** `computeSliceAngles(values, startAngle, totalAngle)`, `arcCentroid`, `buildArcPath({ cx, cy, innerRadius, outerRadius, startAngle, endAngle, padAngle?, cornerRadius? })` (wedge and ring paths), `isFullArc(startAngle, endAngle)`.
+- **`lib/chart-kernel/line`:** `resolveLineDomain(values)`, `createLineScales(config)`, `buildPolylinePoints`, `buildAreaPoints`, `buildLinePath(points, scales, curve, connectNulls)`, `buildAreaPath`, `buildBandAreaPath` — `curve` is `linear`, `smooth`, `step`, `stepAfter` or `stepBefore`.
+- Colour resolves explicit override → `var(--chart-1..5)` → self-contained `oklch` fallbacks; pass `{ useTokens: false }` only for a shell with no theme wiring, or the marks stop re-branding with the host stylesheet.
+- The formatter singletons are fixed to `en-US` at module scope and never follow the runtime locale — a localized axis builds its own `Intl` instance.
 
 ```tsx
-import { LineChart, Line, XAxis, YAxis, Grid, ReferenceLine } from "@nurix/components/charts";
-
-<LineChart series={revenue}>
-  <Grid />
-  <XAxis />
-  <YAxis />
-  <Line curve={curveMonotoneX} />
-  <ReferenceLine y={target} label="Target" />
-</LineChart>
+import { resolveSeriesColors } from "@nurix/components/lib/chart-kernel";
+import { computeSliceAngles, buildArcPath } from "@nurix/components/lib/chart-kernel/arc";
+
+const colors = resolveSeriesColors(slices);
+const angles = computeSliceAngles(slices.map((s) => s.value), 0, Math.PI * 2);
 ```

package/data/harnesses/code/skills/design/components/collections.md

@@ -2,52 +2,59 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
+Components: Table, UiTable, List, Tree, FieldGrid, AnchoredScroller, Composer, MicInput, StreamingCursor, Marker
+
+Each imports from its own subpath as one namespace, with its parts as dotted members, e.g. `import { UiTable } from "@nurix/components/block/ui-table"` then `UiTable.Row`, `UiTable.Cell`. `Table` is the exception: a single generic root whose cell renderers stay flat named exports.
+
 ## Table
 
-Data table with sorting, pagination, and row selection. Zero-config `<Table data columns />` renders bare; selection, sorting, pagination, and resize are opt-in via `tableConfig`.
+Server-driven data table on a TanStack engine (`block/table`). Zero-config `<Table data columns />` renders bare; selection, sorting, pagination, resize and the grid keyboard model are opt-in via `tableConfig`. Install its two optional peer families first — `table` (`@tanstack/react-table`) and `spark` (`@mantine/charts @mantine/core recharts`, for the lazily loaded sparkline cell); a missing peer fails at the bundler with the package named.
 
 **Props:**
 
-- `data` - Array of row objects (must have `id` field)
+- `data` - Array of row objects (each must have an `id` string)
 - `columns` - Array of `ColumnDefinition` objects
-- `columnOrder` - Optional column order (defaults to column definition order)
-- `pagination` - `{ current, size, total, onChange }`
-- `sorting` - `{ columns, direction, onChange }` (max 3 sort columns)
+- `columnOrder` - Composite column ids in display order (defaults to column definition order)
+- `pagination` - `{ current, size, total, onChange }` — controlled and 1-indexed; slice `data` to the current page yourself
+- `sorting` - `{ columns, direction, onChange }` (max 3 sort columns) — `columns` takes composite ids
 - `onSelect` - Callback with selected row IDs
-- `onCellChange` - Write-back from `editable` cells: `({ rowId, columnId, slug, value }) => void` (data stays consumer-controlled)
+- `onCellChange` - Write-back from `editable` cells: `({ rowId, columnId, slug, value }) => void`; fires only on a real commit (a blur that typed nothing emits nothing), and the table never mutates `data`
 - `loading` - Show loading skeleton
-- `tableConfig` - Optional; `{ preset, rowSelection, sort, pagination, header, density, columnBorders, tableBorders, resize, autoHeight }`
+- `error` - `{ message, onRetry? }` — a failed fetch renders in place of the rows; wins over `loading`, which wins over the empty body
+- `tableConfig` - Optional; `{ preset, rowSelection, sort, pagination, header, density, columnBorders, tableBorders, resize, autoHeight, gridAria }`
+
+`density` is [compact|comfortable|spacious]; `columnBorders`/`tableBorders` are [none|all]. `preset: "classic"` sets a tinted short header row, comfortable density, the pagination footer and `tableBorders: "all"` in one key, and explicit keys override it. The pagination footer is opt-in (`pagination: true`); `gridAria` adds `role="grid"` with roving-tabindex arrow navigation.
 
-`preset: "classic"` restores the legacy look in one key; `resize` gates column drag handles; the pagination footer is opt-in (`pagination: true`).
+**Composite ids.** `sorting.columns` and `columnOrder` take `getColumnId()`'s `${slug}_${component}` id — `name_text` for a `slug: "name"`, `type: "text"` column. A bare `"name"` silently matches no column.
 
 ```tsx
 <Table
-  data={users}
+  data={pageRows}
   columns={columns}
   pagination={{ current: 1, size: 10, total: 100, onChange: setPagination }}
-  sorting={{ columns: ["name"], direction: "asc", onChange: setSorting }}
+  sorting={{ columns: ["name_text"], direction: "asc", onChange: setSorting }}
   onSelect={setSelectedIds}
-  tableConfig={{ rowSelection: true, resize: true }}
+  tableConfig={{ rowSelection: true, pagination: true, resize: true }}
 />
 ```
 
 ## ColumnDefinition
 
-Define table columns using the `defineColumn()` helper.
+Define table columns with the `defineColumn()` helper, which fills `component` from `type`, `hidden: false`, and empty `metadata`/`display`.
 
 **Fields:**
 
-- `slug` - Field key in data object
+- `slug` - Field key in the row object
 - `label` - Column header text
 - `type` - Data type: `text`, `number`, `boolean`, `date`, `enum`, `user`
-- `component` - Renderer (defaults from `type`): `text`, `number`, `boolean`, `date`, `select`, `multiselect`, `slider`, `rating`, `status`, `priority`, `assignee`, `sparkline`, `date-range`
+- `component` - Renderer (defaults from `type`: `enum` → `select`, `user` → `assignee`, otherwise the type string): `text`, `number`, `boolean`, `date`, `date-range`, `select`, `multiselect`, `slider`, `rating`, `status`, `priority`, `assignee`, `sparkline`
 - `hidden` - Hide column
 - `editable` - Activate the interactive widget; columns render the read-only display variant by default
 - `metadata` - Component-specific options (see table below)
-- `display` - `{ width, sortable }` (width optional — columns are fluid when unset)
-- `cell` - Custom render function `(row) => ReactNode`
+- `display` - `{ width, sortable }` (width optional — columns are fluid when unset; `sortable` defaults to true except for `boolean` and `user`)
+- `cell` - Custom render function `(row) => ReactNode`; wins over `component`
 
-For full control, pass your own `cell()` or import a renderer from `@nurix/components/block/table` (`StatusPill`, `SelectCell`, etc.) as an escape hatch.
+For full control, pass your own `cell()` and compose a renderer imported from `@nurix/components/block/table` — `EditableText`, `EditableNumber`, `EditableDate`, `EditableDateRange`, `BooleanCell`, `SliderCell`, `RatingCell`, `SelectCell`, `StatusCell`, `PriorityCell`, `AssigneeChip`, `MultiSelectCell`, `TableSparkline`. Each is a flat export so a consumer pays only for the renderers it imports.
 
 ### Metadata options by component
 
@@ -67,13 +74,13 @@ For full control, pass your own `cell()` or import a renderer from `@nurix/compo
 import { defineColumn } from "@nurix/components/block/table";
 
 const columns = [
-  defineColumn({
+  defineColumn<Row>({
     slug: "name",
     label: "Name",
     type: "text",
     editable: true,
   }),
-  defineColumn({
+  defineColumn<Row>({
     slug: "status",
     label: "Status",
     type: "enum",
@@ -82,14 +89,14 @@ const columns = [
       options: [{ value: "active", label: "Active", color: "#22c55e" }],
     },
   }),
-  defineColumn({
+  defineColumn<Row>({
     slug: "progress",
     label: "Progress",
     type: "number",
     component: "slider",
     metadata: { min: 0, max: 100 },
   }),
-  defineColumn({
+  defineColumn<Row>({
     slug: "createdAt",
     label: "Created",
     type: "date",
@@ -98,35 +105,196 @@ const columns = [
 ];
 ```
 
-## PageHeader
+## UiTable
+
+Bare native-table parts (`block/ui-table`) for markup you write yourself — no data model, no sort, no edit machinery. Reach for `Table` the moment the data needs sorting, editable cells or a `defineColumn` column set.
+
+**Sub-components:** `UiTable.Header`, `UiTable.Body`, `UiTable.Footer`, `UiTable.Head`, `UiTable.Row`, `UiTable.Cell`, `UiTable.Caption`
+
+- The root renders a `data-slot="table-container"` scroll wrapper around the `<table>`; `className` on `UiTable` styles the `<table>`, not the wrapper.
+- Mark a selected row with `data-selected` on `UiTable.Row` (paints on the accent; `data-state="selected"` paints nothing). Body rows take the hover wash; header and footer rows stay still.
+- No built-in loading, empty or error row — it renders exactly the rows it is given.
+
+```tsx
+<UiTable>
+  <UiTable.Header>
+    <UiTable.Row><UiTable.Head>Invoice</UiTable.Head></UiTable.Row>
+  </UiTable.Header>
+  <UiTable.Body>
+    <UiTable.Row><UiTable.Cell>INV001</UiTable.Cell></UiTable.Row>
+  </UiTable.Body>
+</UiTable>
+```
+
+## List
+
+Keyed collection whose rows you draw (`block/list`) — `item.id` is the React key, the selection key, the expand key and what row motion tracks. Rows with typed columns are `Table`; a chat transcript is `AnchoredScroller`. Activity feeds, record history, notification inboxes and card grids are `List` with a recipe.
+
+**Sub-components:** `List.Toolbar`, `List.Pagination` (the parts List renders from `toolbar` and `pagination`), `List.ItemErrorBoundary` (wraps every row: a render throw becomes a compact error state while the other rows stand)
+
+**Props:** `data`, `renderItem(item, index, { isExpanded, onToggle, view })`, `toolbar` (`{ search: { placeholder, keys }, filters: [{ key, label, options, multiple }], showExpandControls, actions }`), `pagination` (`{ current, size, total, onChange }` — when present, the parent has already filtered, sorted and paged), `expandedIds`/`defaultExpandedIds`/`onExpandedIdsChange` (`string[] | "all"`), `searchValue`/`defaultSearchValue`/`onSearchValueChange`, `filters`/`defaultFilters`/`onFiltersChange`, `onSelect`, `groupBy(item) → { key, label }` (a `Marker` separator before each run), `live` (holds rows arriving above the viewport behind an "N new" pill — keep `data` newest-first), `onLoadMore` + `hasMore` + `loadingMore`, `view` [list|card], `onItemActivate(id)`, `onItemError(error, id)`, `loading`, `error` (`{ message, onRetry? }`), `emptyState`, `labels`, `config` (`{ selection, density, dividers, animation: { type: slide|fade|scale|none }, expandable, pageSizeOptions, cardColumns }`)
+
+- No virtualization: every item in `data` renders, so page an unbounded collection with `onLoadMore` or `pagination`.
+- `expandedIds`, `searchValue` and `filters` go controlled the moment the prop is passed — `expandedIds={[]}` locks expansion closed unless `onExpandedIdsChange` drives it.
+
+```tsx
+<List
+  data={events}
+  renderItem={(event) => <FeedRow event={event} />}
+  groupBy={(event) => ({ key: dayKey(event), label: dayLabel(event) })}
+  toolbar={{ search: { keys: ["title"] }, filters: [{ key: "type", label: "Type", options }] }}
+  onLoadMore={loadOlder}
+  hasMore={hasMore}
+  loadingMore={isLoading}
+/>
+```
+
+## Tree
+
+Hierarchy built from flat records that name their parent (`block/tree`); `useTree` is exported beside it for fully custom markup.
 
-Config-driven page masthead with an optional stat ledger — router-agnostic (the consumer owns navigation). Import from `@nurix/components/block/page-header`.
+**Sub-components:** `Tree.Item`, `Tree.ItemLabel` (returned from `renderItem` when a row needs its own props or `render` element).
 
-**Props:** `title`, `eyebrow` (breadcrumb segments — strings or linked `Crumb`s; last is the current page), `description`, `statusSlot`, `actions`, `stats` (`Stat[]` ledger), `back` (`BackLink`), `onBack`, `onNavigate` (fired with a crumb's/stat's `href`), `statsAlign` [left|right], `tall`
+**Props:** `data`, `getParentId` (`null` for a top-level record), `isItemFolder`, `isItemDisabled`, `renderItem`, `selectionMode` [none|single|multiple], `selectedIds`/`defaultSelectedIds`/`onSelectedIdsChange`, `expandedIds`/`defaultExpandedIds` (an id list or `"all"`; default `[]`)/`onExpandedIdsChange`, `onItemActivate`
+
+- Keep the accessor functions stable — the rows re-flatten whenever `data` or an accessor changes identity. Records whose parent id names no record never render.
 
 ```tsx
-<PageHeader
-  title="Q3 Pipeline"
-  eyebrow={["Sales", "Pipelines"]}
-  actions={<Button size="sm">Export</Button>}
-  stats={[{ label: "Open deals", value: "142" }, { label: "Won", value: "$1.2M" }]}
+<Tree
+  aria-label="Files"
+  data={records}
+  getParentId={getParentId}
+  selectionMode="single"
+  onItemActivate={openFile}
+  renderItem={(item) => item.getItemData().name}
 />
 ```
 
+## FieldGrid
+
+One record's fields, column-driven and editable in place (`compound/field-grid`) — the description list. Skip it for one labelled form field (`compound/cell`) and for many records (`Table`).
+
+**Props:** `columns` (`FieldColumn[]`), `data` (the one record), `onDataChange(slug, value)`, `arrangement` [grid|strip] (default `grid`, the responsive labelled `<dl>`; `strip` is the compact icon-and-value band), `columnsPerRow` (grid only, 1–9, default 6), `labels` (`{ empty, on, off }`)
+
+**FieldColumn:** `id`, `slug`, `label`, `type` [text|number|boolean|date|slider|rating|enum|status|priority|assignee|avatar|avatarGroup|chip|timer], `options` (`[{ value, label, color, icon }]`), `readOnly`, `placeholder`, `min`/`max`/`step`, `format` (Intl number options), `colSpan`, `icon` (a Lucide icon, or `true` to pick one from `type` then `slug`), `validate(value)` (a returned message refuses the commit), `cell(value, record)` (wins over `type`)
+
+- Editing is opt-in twice: a column is read-only unless it sets `readOnly: false` **and** the grid received `onDataChange`. Each editor commits once (Enter or blur for text, the pick for options, the release for a slider).
+- The grid is naked — the strip's band chrome goes on the call site.
+
+```tsx
+<FieldGrid
+  arrangement="strip"
+  data={deal}
+  onDataChange={(slug, value) => updateDeal(deal.id, { [slug]: value })}
+  className="border-y bg-muted/30 px-5 py-3"
+  columns={[
+    { id: "stage", slug: "stage", label: "Stage", type: "status", options: stages, readOnly: false, icon: true },
+    { id: "amount", slug: "amount", label: "Amount", type: "number", format: { style: "currency", currency: "USD" } },
+  ]}
+/>
+```
+
+## Page and record headers
+
+No page-header block ships: compose the masthead at the call site. A title row and actions sit on a `Row`; a KPI ledger is several `Stat` (`element/stat`) on a `Row` beneath it, documented in [typography](typography.md); a record's labelled fields are `FieldGrid` with `arrangement="strip"`.
+
 ## Conversation surfaces
 
-Chat/AI message chrome; import each from its kebab-case subpath.
+Chat and message-thread chrome; import each from its own subpath.
+
+### AnchoredScroller
+
+Scroll region that sticks to the newest message and offers a jump control once the reader scrolls away (`block/anchored-scroller`). Install its optional peer family `anchored-scroller` (`@shadcn/react`) first. A plain scrollable region with no stick-to-bottom behavior is `element/scroll-area`.
+
+**Sub-components:** `AnchoredScroller.Provider`, `AnchoredScroller.Viewport`, `AnchoredScroller.Content`, `AnchoredScroller.Item`, `AnchoredScroller.Button`; hooks `useAnchoredScroller`, `useAnchoredScrollerScrollable`, `useAnchoredScrollerVisibility`
+
+**Props:** Provider — `shouldAutoScroll`, `defaultScrollPosition`; root — `labels` (`{ region, scrollToEnd, scrollToStart }`); Viewport — `shouldPreserveScrollOnPrepend` (default `true`); Item — `itemId`, `isScrollAnchor`; Button — `direction` [start|end] (default `end`), plus `Button`'s `variant`, `size`, `isIconOnly`
+
+- The hooks read the scroll store only from components rendered under `AnchoredScroller.Provider`.
+- Give every Item an `itemId` — `scrollToItem`, `visibleItemIds` and `currentAnchorId` key off it.
+
+```tsx
+<AnchoredScroller.Provider shouldAutoScroll defaultScrollPosition="end">
+  <AnchoredScroller labels={{ region: "Support thread" }}>
+    <AnchoredScroller.Viewport>
+      <AnchoredScroller.Content>
+        {messages.map((m) => (
+          <AnchoredScroller.Item key={m.id} itemId={m.id} isScrollAnchor={m.isTurnStart}>{renderMessage(m)}</AnchoredScroller.Item>
+        ))}
+      </AnchoredScroller.Content>
+    </AnchoredScroller.Viewport>
+    <AnchoredScroller.Button direction="end" />
+  </AnchoredScroller>
+</AnchoredScroller.Provider>
+```
+
+### Composer
+
+Chat message composer: textarea, attachments, a footer of controls and a send (`@nurix/components/block/composer`, plus `useStagedFiles`, `composerNoticeVariants`).
+
+**Props:** `onSubmit`, `onFilesDropped`, `reason` (blocks every send path and fills the Notice), `loading`, `accept`, `labels`
+
+**Sub-components:** `Composer.Header`, `Composer.Attachments`, `Composer.Textarea` (`onEnterSubmit`, `maxRows`), `Composer.Footer` (`start`, `end`), `Composer.Attach` (`onSelect`, `multiple`), `Composer.Send`, `Composer.Notice` (`intent` [neutral|danger])
+
+Enter submits (Shift+Enter is a newline) except while `reason` or `loading` holds the send. Render `Composer.Notice` unconditionally so a later reason announces. `useStagedFiles({ maxFiles })` returns `{ files, stage, remove, clear }`.
+
+```tsx
+<Composer onSubmit={send} onFilesDropped={stage} reason={closed ? "The window is closed." : undefined}>
+  <Composer.Attachments>{files.map(renderChip)}</Composer.Attachments>
+  <Composer.Textarea value={draft} onValueChange={setDraft} />
+  <Composer.Footer start={<Composer.Attach onSelect={stage} />} end={<Composer.Send disabled={!draft.trim()} />} />
+  <Composer.Notice />
+</Composer>
+```
+
+### MicInput
+
+Microphone toggle with a live level meter, as a latch over the caller's engine or over a built-in recorder (`@nurix/components/compound/mic-input`, plus `useMicInputState`, `useMicRecorder`; recorder mode needs the optional peer `react-voice-visualizer`).
+
+**Props:** `pressed`, `onPressedChange`, `onValueCommitted` (latch mode) or `recorder` (from `useMicRecorder()`), `status` [idle|listening|processing|error], `waveform` [true|false|"always"], `onError`, `labels`
+
+**Sub-components:** `MicInput.Trigger` (`size` [sm|default|lg]), `MicInput.Meter` (`variant` [static|history], `deviceId`)
+
+A denied microphone surfaces only through `onError` (meter) or `recorder.error`. A composer's voice button is a `Button` in `Composer.Footer`.
+
+```tsx
+<MicInput pressed={isRecording} onPressedChange={toggle} status={status}>
+  <MicInput.Meter variant="history" />
+  <MicInput.Trigger size="sm" />
+</MicInput>
+```
+
+### StreamingCursor
+
+The blinking caret at the tail of a live stream (`effect/streaming-cursor`); inline, `h-[1lh]`, `aria-hidden`, blink shipped in the library stylesheet. Change the element with `render` (no `as` or `asChild`). Before the first token, show `element/loader`; inside a code block, set `compound/code-block`'s `isStreaming` prop instead.
+
+```tsx
+<p>{streamedText}{isStreaming && <StreamingCursor className="ml-0.5" />}</p>
+```
+
+### Marker
+
+Muted full-width row for out-of-band thread content — a date divider or a system event (`element/marker`). It is not a notification badge; an unread dot on an avatar is `Avatar.Badge`.
+
+**Sub-components:** `Marker.Icon` (`aria-hidden` — put any meaning in the content text), `Marker.Content`; also `markerVariants`
+
+**Props:** `variant` [default|separator|border] (`separator` flanks centered content with hairlines; `border` underlines the row), `render` (non-interactive elements only — an action goes inside `Marker.Content` as a `Link` or `Button`)
+
+```tsx
+<Marker variant="separator">
+  <Marker.Content>Today</Marker.Content>
+</Marker>
+```
 
-- `message` — docs-style message rows: `MessageGroup`, `Message`, `MessageAvatar`, `MessageHeader`, `MessageContent`, `MessageFooter`, `MessageStatus` (`status` [sending|sent|failed…] with icon + `data-status`)
-- `message-scroller` — pinned-to-bottom scroll container for feeds: `MessageScrollerProvider`, `MessageScroller`, `MessageScrollerViewport`, `MessageScrollerContent`, `MessageScrollerItem`, `MessageScrollerButton` (jump-to-latest); hooks `useMessageScroller`, `useMessageScrollerScrollable`, `useMessageScrollerVisibility`
-- `bubble` — chat-bubble rows: `BubbleGroup`, `Bubble`, `BubbleContent`, `BubbleReactions`
-- `attachment` — file chips for composer/thread: `Attachment` (+ `AttachmentGroup`, `AttachmentMedia`, `AttachmentContent`, `AttachmentTitle`, `AttachmentDescription`, `AttachmentActions`, `AttachmentAction`, `AttachmentTrigger`); `size` [default|sm], dashed border in idle state, `data-[state=error]` styling
-- `marker` — inline annotation row in a stream: `Marker`, `MarkerIcon`, `MarkerContent`; `variant` [default|separator|border]
+## Fallback-only concepts
 
-## Other Collections
+No nurix primitive — build each from its plain-spec fallback in [index.md](index.md):
 
-- `activity-timeline` — `GanttChart`: D3-based activity timeline (`Task`, `TaskStatus`, `ViewMode`, `GanttChartProps` types; `DEFAULT_STATUS_COLORS`, `getTaskDuration` helpers)
-- `changes-list` — `ChangesList`: grouped change-history feed (`ChangeItem`, `EntityConfig`, `OperationConfig`, `GroupBy` types)
-- `header` — `Header`: config-driven page header taking a single `config: HeaderConfig` (breadcrumbs, profile, status bar, grid, actions sections); sub-components `HeaderBreadcrumbs`, `HeaderActions`, `HeaderSection`, `HeaderCell`
-- `list` — `List`: data list with `ListToolbar`, `ListPagination`, `ListItemErrorBoundary`
-- `ui-table` — `UiTable`, `UiTableHeader`, `UiTableBody`, `UiTableFooter`, `UiTableHead`, `UiTableRow`, `UiTableCell`, `UiTableCaption`: bare HTML-table primitives; prefer `Table`
+- `gantt-timeline`
+- `chat-bubble`
+- `json-viewer`
+- `virtualized-list`
+- `kanban-board`
+- `event-calendar`
+- `filter-toolbar`
+- `vertical-timeline`