@pond-ts/charts 0.53.1 → 0.55.0

package/dist/context.d.ts

@@ -541,6 +541,17 @@ export interface RowLayer {
      * must agree on this list (a mix is an error), the same way {@link xKind} must.
      */
     xCategories?(): readonly string[] | null;
+    /**
+     * A **horizontal** categorical source's ordered category names — the same
+     * list {@link xCategories} carries for a vertical one, but for the axis it
+     * lands on when the bars grow right: the **y** axis ([PND-HCAT]).
+     *
+     * The y axis stays a linear scale over the layer's unit slots (`[i, i+1]`),
+     * so this only supplies *labels*: a `<YAxis>` in the row with no explicit
+     * `ticks` derives one tick per category at the slot centre (`i + 0.5`).
+     * That hand-built tick list was the friction the gallery funnel documented.
+     */
+    binCategories?(): readonly string[] | null;
     /**
      * A bar/histogram layer's bar `[begin, end)` spans, as pond `Interval`s — the
      * **region cursor's snap buckets**. When present (and no `cursorSequence` is
@@ -601,6 +612,15 @@ export interface TrackerSample {
      *  quote) emits `"<as> <role>"` composites (`iv lower`, `SPY high`) when its
      *  `as` is set, else the raw column / role word. */
     readonly label: string;
+    /**
+     * Optional **source value for the off-chart readout**, when the layer plots a
+     * *derived* column but a `readout` column names the raw value (see
+     * `LineChart`/`AreaChart` `readout`). `value` stays the plotted number — so
+     * the in-chart cursor dot is unchanged — while an off-chart consumer shows
+     * `readout ?? value`. `undefined` when the layer has no `readout` column (the
+     * common case: the plotted value *is* the value to show).
+     */
+    readonly readout?: number;
 }
 /** One line of a {@link CursorFlag} — a labelled, coloured value. */
 export interface CursorFlagLine {
@@ -633,6 +653,17 @@ export interface TrackerSource {
     xExtent(): readonly [number, number] | null;
     /** A `'category'` source's ordered category names (see {@link RowLayer.xCategories}). */
     xCategories?(): readonly string[] | null;
+    /**
+     * A **horizontal** categorical source's ordered category names — the same
+     * list {@link xCategories} carries for a vertical one, but for the axis it
+     * lands on when the bars grow right: the **y** axis ([PND-HCAT]).
+     *
+     * The y axis stays a linear scale over the layer's unit slots (`[i, i+1]`),
+     * so this only supplies *labels*: a `<YAxis>` in the row with no explicit
+     * `ticks` derives one tick per category at the slot centre (`i + 0.5`).
+     * That hand-built tick list was the friction the gallery funnel documented.
+     */
+    binCategories?(): readonly string[] | null;
     /** A bar/histogram source's bar `[begin, end)` spans (see {@link RowLayer.binIntervals}). */
     binIntervals?(): readonly Interval[] | null;
 }
@@ -667,13 +698,25 @@ export interface SelectInfo {
     /** Display label (`as` ?? column ?? id) — labels the selection in a readout. */
     readonly label: string;
     /**
-     * An optional **stable per-mark identity within the layer** — a *category's
-     * column name* on the categorical axis, where every bar shares the layer's
-     * `id` but each column needs its own stable handle. When present, the
-     * highlight match + controlled `selected` echo key on `(id, mark)` instead of
-     * the sample `key`, so a pinned selection survives a column reorder / data
-     * update (the slot index is not stable; the column name is). `undefined` for
-     * marks whose sample `key` is already their identity (a time / value bar).
+     * An optional **stable per-mark identity within the layer** — every mark
+     * shares the layer's `id`, so this is the handle that picks one *within* it.
+     * When a selection carries it, the highlight match + controlled `selected`
+     * echo key on `(id, mark)` instead of the sample `key`, so a pin survives a
+     * reorder / data update that renumbers the slot.
+     *
+     * Two layers report one today:
+     *
+     * - A **categorical** bar reports its *column name* — the slot index is not
+     *   stable across a reorder, the name is.
+     * - A **single-series** bar (`<BarChart series column>`) reports its own axis
+     *   key, stringified. On a **point-keyed** series the sample `key` is *not*
+     *   its identity: the bar span is synthesized from neighbour spacing, so
+     *   `key` is a derived edge (`t - halfGap`) rather than the sample's own
+     *   time. See `BarSeries.marks`.
+     *
+     * `undefined` for every other mark (scatter, box, candle), whose sample `key`
+     * *is* its identity. A selection without a `mark` still matches on `key`
+     * everywhere — the mark is an additional channel, not a replacement.
      */
     readonly mark?: string;
 }

package/dist/data.d.ts

@@ -121,6 +121,35 @@ export interface BarSeries {
     readonly end: Float64Array;
     readonly y: Float64Array;
     readonly length: number;
+    /**
+     * Optional **stable per-bar identity** — `marks[i]` names bar `i`. The
+     * single-series sibling of {@link StackedBarSeries.marks}: when present, the
+     * draw / hit-test / selection can key on this name instead of the bar's
+     * `begin` **edge**.
+     *
+     * The readers ({@link barsFromTimeSeries} / {@link barsFromValueSeries}) fill
+     * it with the **sample's own axis key** — `String(key[i])`, the timestamp or
+     * axis value the row is keyed on. That is the identity a caller already
+     * owns, and for a **point-keyed** series it is *not* `begin[i]`: there the
+     * span is synthesized, so `begin[i]` is a derived edge (`key - prevGap/2`,
+     * see {@link neighbourSpans}) and pinning a selection by key meant
+     * re-deriving the neighbour spacing. `undefined` on a hand-built view.
+     *
+     * Built **lazily** on first read and then memoized (~9 ms per 100k bars, on
+     * top of a ~0.8 ms reader). Who pays, precisely:
+     *
+     * - A **non-interactive** layer (no `id`, so no `hitTest`) never reads them.
+     * - An **interactive** one hit-tests on every *pointer move*, and that echo
+     *   reads the hovered bar's mark — so the first move that lands on a bar
+     *   materializes the array, once per data identity, on the input path
+     *   (11.1 ms vs 1.7 ms for a warm 100k-bar hover).
+     *
+     * So this is not free for an interactive chart; it is bounded and paid once,
+     * where an eager array would cost every chart on every data update. At
+     * realistic bar counts it is under a millisecond either way. See
+     * `scripts/perf-barmarks.mjs`.
+     */
+    readonly marks?: readonly string[];
 }
 /**
  * A chart-ready view of a **stacked / histogram** bar series — the multi-segment
@@ -156,6 +185,27 @@ export interface StackedBarSeries {
      */
     readonly marks?: readonly string[];
 }
+/**
+ * Assert `column` names an existing **numeric** column of `series`, returning
+ * it. The single source of the reader's two errors, so a caller that reads a
+ * column **per event** rather than buffering it — the time-axis `readout` path
+ * in `LineChart` / `AreaChart` — rejects a bad name identically to one that
+ * materializes. Without it a mistyped `readout` throws on a `ValueSeries` (via
+ * {@link readValueColumn}) but silently produced no readout on a `TimeSeries`,
+ * where the per-event `get()` just returns `undefined`.
+ *
+ * The `undefined` guard is runtime-necessary even though it reads as dead code:
+ * `column()` returns `undefined` for an unknown name at runtime, but core's
+ * public overload currently types the result as non-`undefined` (see F-3 in the
+ * M1 friction note). Keep it — the "throws on unknown column" tests exercise it.
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export declare function assertNumericColumn<S extends SeriesSchema>(series: TimeSeries<S>, column: string): {
+    kind: string;
+    read(i: number): number | undefined;
+};
 /**
  * The quantile column names a {@link boxFromTimeSeries} / {@link boxFromValueSeries}
  * reads. `lower`/`upper` (the whisker reach) are required; `q1`/`q3` (the box
@@ -306,6 +356,10 @@ export declare function ohlcFromTimeSeries<S extends SeriesSchema>(series: TimeS
  * interval-keyed series (e.g. an `aggregate`/`window` rollup) draws its true
  * bucket spans. Detected by `keyColumn().kind === 'time'`.
  *
+ * Each bar also carries its **own key** as a stable {@link BarSeries.marks}
+ * identity, so a selection can be pinned on the sample rather than on the span
+ * this derived for it.
+ *
  * @throws RangeError if `column` does not exist.
  * @throws TypeError if `column` is not a numeric column.
  */
@@ -326,6 +380,10 @@ export declare function barsFromTimeSeries<S extends SeriesSchema>(series: TimeS
  * (a slight drift from a true segment edge — fine for the bar look; key an
  * interval/timeRange `TimeSeries` instead if exact edges matter).
  *
+ * Each bar also carries its **axis value** as a stable {@link BarSeries.marks}
+ * identity — the centre it is drawn around, not the derived edge — so a
+ * selection can be pinned without re-deriving the neighbour spacing.
+ *
  * @throws RangeError if `column` does not exist.
  * @throws TypeError if `column` is not a numeric column.
  */
@@ -389,6 +447,25 @@ export interface StacksFromBinsOptions {
      */
     readonly ordinal?: boolean;
 }
+/**
+ * Build a {@link BarSeries} from **`byColumn` bin records** — the single-series
+ * sibling of {@link stacksFromBins}, for a histogram drawing **one** aggregate
+ * field.
+ *
+ * Why it exists ([PND-BARSEM]): a one-column histogram *is* a single-series
+ * bar chart — same mark, same geometry — but routing it through the stacked
+ * reader made its capabilities depend on which prop produced it (whole-slot
+ * hit-testing, the hover colour, the cursor readout and per-bar decimation all
+ * live on the single path). Reading it as a `BarSeries` lets the chart decide
+ * by what it *draws* rather than by how it was fed.
+ *
+ * `column` names the aggregate field; slots are the bins' numeric
+ * `[start, end]` edges, or uniform unit slots under `{ ordinal: true }` —
+ * identical to {@link stacksFromBins}. A missing / non-finite aggregate reads
+ * as a gap (`NaN`), and each bar carries its slot index as a stable
+ * {@link BarSeries.marks} identity (bin records have no key of their own).
+ */
+export declare function barsFromBins(bins: readonly BinRecord[], column: string, options?: StacksFromBinsOptions): BarSeries;
 /**
  * Build a {@link StackedBarSeries} from **`byColumn` bin records** — the array of
  * `{ start, end, …aggregates }` a value-band aggregation returns

package/dist/data.js

@@ -1,4 +1,31 @@
 import { ValueSeries } from 'pond-ts';
+/**
+ * Assert `column` names an existing **numeric** column of `series`, returning
+ * it. The single source of the reader's two errors, so a caller that reads a
+ * column **per event** rather than buffering it — the time-axis `readout` path
+ * in `LineChart` / `AreaChart` — rejects a bad name identically to one that
+ * materializes. Without it a mistyped `readout` throws on a `ValueSeries` (via
+ * {@link readValueColumn}) but silently produced no readout on a `TimeSeries`,
+ * where the per-event `get()` just returns `undefined`.
+ *
+ * The `undefined` guard is runtime-necessary even though it reads as dead code:
+ * `column()` returns `undefined` for an unknown name at runtime, but core's
+ * public overload currently types the result as non-`undefined` (see F-3 in the
+ * M1 friction note). Keep it — the "throws on unknown column" tests exercise it.
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export function assertNumericColumn(series, column) {
+    const col = series.column(column);
+    if (col === undefined) {
+        throw new RangeError(`unknown column '${column}'`);
+    }
+    if (col.kind !== 'number') {
+        throw new TypeError(`column '${column}' must be numeric (got '${col.kind}')`);
+    }
+    return col;
+}
 /**
  * Read a numeric column into a `Float64Array`, missing cells as `NaN`.
  *
@@ -15,17 +42,7 @@ import { ValueSeries } from 'pond-ts';
  * @throws TypeError if `column` is not a numeric column.
  */
 function readNumericColumn(series, column) {
-    // Runtime-necessary even though it reads as dead code: `column()` returns
-    // `undefined` for an unknown name at runtime, but core's public overload
-    // currently types the result as non-`undefined` (see F-3 in the M1 friction
-    // note). Keep the guard — the "throws on unknown column" test exercises it.
-    const col = series.column(column);
-    if (col === undefined) {
-        throw new RangeError(`unknown column '${column}'`);
-    }
-    if (col.kind !== 'number') {
-        throw new TypeError(`column '${column}' must be numeric (got '${col.kind}')`);
-    }
+    const col = assertNumericColumn(series, column);
     const length = series.length;
     const out = new Float64Array(length);
     for (let i = 0; i < length; i += 1) {
@@ -302,6 +319,43 @@ function neighbourSpans(axis, n) {
     }
     return { begin, end };
 }
+/**
+ * Attach the lazy stable per-bar identity to a bar view — see
+ * {@link BarSeries.marks}. `keys` is the **sample's own** axis buffer (the key
+ * column's `begin` for a `TimeSeries`, `axisValues()` for a `ValueSeries`), not
+ * the possibly-derived bar span, and must already be trimmed to `bars.length`.
+ *
+ * The strings are built on first read and then memoized. That is why this is a
+ * getter rather than an eager array: 100k bars is ~9 ms of string allocation on
+ * top of a ~0.8 ms reader, and eager would charge it to every chart on every
+ * data update, for a channel a non-interactive one never uses at all. An
+ * interactive chart *does* pay it, once per data identity, on its first hover
+ * over a bar — see {@link BarSeries.marks}. `scripts/perf-barmarks.mjs` pins
+ * both halves.
+ *
+ * The getter is deliberately **enumerable**, so a `{...bs}` spread carries the
+ * marks through (materializing them) rather than silently dropping them — a
+ * perf surprise beats a correctness one. Nothing in the package spreads a
+ * `BarSeries` today; this is for outside callers. If one ever appears **in the
+ * draw path**, it would force materialization on every frame — but
+ * `perf-barmarks.mjs`'s `marks untouched` row is measured on exactly that, so
+ * it would show up as a reader regression rather than pass silently.
+ */
+function withKeyMarks(bars, keys) {
+    let marks;
+    return {
+        ...bars,
+        get marks() {
+            if (marks === undefined) {
+                const out = new Array(bars.length);
+                for (let i = 0; i < bars.length; i += 1)
+                    out[i] = String(keys[i]);
+                marks = out;
+            }
+            return marks;
+        },
+    };
+}
 /**
  * Build a {@link BarSeries} from a pond `TimeSeries` — one bar per event, the
  * key's `[begin, end]` as the x-span and `column` as the height.
@@ -320,6 +374,10 @@ function neighbourSpans(axis, n) {
  * interval-keyed series (e.g. an `aggregate`/`window` rollup) draws its true
  * bucket spans. Detected by `keyColumn().kind === 'time'`.
  *
+ * Each bar also carries its **own key** as a stable {@link BarSeries.marks}
+ * identity, so a selection can be pinned on the sample rather than on the span
+ * this derived for it.
+ *
  * @throws RangeError if `column` does not exist.
  * @throws TypeError if `column` is not a numeric column.
  */
@@ -327,15 +385,15 @@ export function barsFromTimeSeries(series, column) {
     const y = readNumericColumn(series, column);
     const n = series.length;
     const kind = series.keyColumn().kind;
-    if (kind !== 'time') {
-        // Interval / timeRange: the key's own endpoints are the bar span.
-        const { begin, end } = keyBeginEnd(series);
-        return { begin, end, y, length: n };
-    }
-    // Point key (begin === end): synthesize a span from neighbour spacing so the
-    // bars have width (see neighbourSpans).
-    const { begin, end } = neighbourSpans(series.keyColumn().begin, n);
-    return { begin, end, y, length: n };
+    // Interval / timeRange: the key's own endpoints are the bar span. Point key
+    // (begin === end): synthesize a span from neighbour spacing so the bars have
+    // width (see neighbourSpans).
+    const { begin, end } = kind !== 'time'
+        ? keyBeginEnd(series)
+        : neighbourSpans(series.keyColumn().begin, n);
+    // The marks key on the event's own timestamp — which for a point key is the
+    // bar's *centre*, not the `begin` edge derived above (see BarSeries.marks).
+    return withKeyMarks({ begin, end, y, length: n }, timeAxis(series));
 }
 /**
  * Build a {@link BarSeries} from a pond `ValueSeries` — the value-axis sibling
@@ -353,6 +411,10 @@ export function barsFromTimeSeries(series, column) {
  * (a slight drift from a true segment edge — fine for the bar look; key an
  * interval/timeRange `TimeSeries` instead if exact edges matter).
  *
+ * Each bar also carries its **axis value** as a stable {@link BarSeries.marks}
+ * identity — the centre it is drawn around, not the derived edge — so a
+ * selection can be pinned without re-deriving the neighbour spacing.
+ *
  * @throws RangeError if `column` does not exist.
  * @throws TypeError if `column` is not a numeric column.
  */
@@ -361,8 +423,9 @@ export function barsFromValueSeries(series, column) {
     const n = series.length;
     // axisValues() is the monotonic key buffer (zero-copy); neighbourSpans reads it
     // and allocates fresh span buffers (never mutates the source).
-    const { begin, end } = neighbourSpans(series.axisValues(), n);
-    return { begin, end, y, length: n };
+    const axis = series.axisValues();
+    const { begin, end } = neighbourSpans(axis, n);
+    return withKeyMarks({ begin, end, y, length: n }, axis);
 }
 /**
  * The per-bin `[begin, end]` slots for a `TimeSeries`, key-shape aware — the same
@@ -472,6 +535,52 @@ export function stacksFromColumns(series, columns) {
     }
     return { begin, end, groups: columns, values, length: n };
 }
+/**
+ * Build a {@link BarSeries} from **`byColumn` bin records** — the single-series
+ * sibling of {@link stacksFromBins}, for a histogram drawing **one** aggregate
+ * field.
+ *
+ * Why it exists ([PND-BARSEM]): a one-column histogram *is* a single-series
+ * bar chart — same mark, same geometry — but routing it through the stacked
+ * reader made its capabilities depend on which prop produced it (whole-slot
+ * hit-testing, the hover colour, the cursor readout and per-bar decimation all
+ * live on the single path). Reading it as a `BarSeries` lets the chart decide
+ * by what it *draws* rather than by how it was fed.
+ *
+ * `column` names the aggregate field; slots are the bins' numeric
+ * `[start, end]` edges, or uniform unit slots under `{ ordinal: true }` —
+ * identical to {@link stacksFromBins}. A missing / non-finite aggregate reads
+ * as a gap (`NaN`), and each bar carries its slot index as a stable
+ * {@link BarSeries.marks} identity (bin records have no key of their own).
+ */
+export function barsFromBins(bins, column, options = {}) {
+    const n = bins.length;
+    const begin = new Float64Array(n);
+    const end = new Float64Array(n);
+    const y = new Float64Array(n);
+    // The bin's own **start value** is its identity — the same axis-key
+    // convention every other reader uses, and stable under `ordinal` (which only
+    // changes the drawn slot, not which bin a row is). A slot *index* would be
+    // positional and would renumber if the bin set changed. Materialized through
+    // the shared lazy getter, so a non-interactive layer never pays for the
+    // strings (see {@link BarSeries.marks}).
+    const keys = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
+        const bin = bins[i];
+        if (options.ordinal) {
+            begin[i] = i;
+            end[i] = i + 1;
+        }
+        else {
+            begin[i] = bin.start;
+            end[i] = bin.end;
+        }
+        keys[i] = bin.start;
+        const v = bin[column];
+        y[i] = typeof v === 'number' && Number.isFinite(v) ? v : NaN;
+    }
+    return withKeyMarks({ begin, end, y, length: n }, keys);
+}
 /**
  * Build a {@link StackedBarSeries} from **`byColumn` bin records** — the array of
  * `{ start, end, …aggregates }` a value-band aggregation returns

package/dist/decimate.js

@@ -636,11 +636,11 @@ export function decimateBars(cs, xScale, ctx, baseline, k = 2, visibleCount = cs
 export function decimateScatter(cs, xScale, yScale, cellPx, vStart = 0, vEnd = cs.length) {
     const cell = cellPx > 0 ? cellPx : 1;
     // Affine fast path ([PND-AFFINE]) for the per-point pixel mapping the sweep
-    // needs — an inline `k·v + b` over the typed arrays instead of a d3-scale
-    // closure per point (each axis independently; a non-affine axis, e.g. a
-    // real-gap trading x, falls back to the exact scale call). Without this the
-    // sweep would re-introduce the per-point d3-scale cost the line/area paths
-    // shed, making the decimation's own cost dominate.
+    // needs — an inline rebased `(v − v0)·k + p0` over the typed arrays instead
+    // of a d3-scale closure per point (each axis independently; a non-affine
+    // axis, e.g. a real-gap trading x, falls back to the exact scale call).
+    // Without this the sweep would re-introduce the per-point d3-scale cost the
+    // line/area paths shed, making the decimation's own cost dominate.
     const ax = affineOf(xScale);
     const ay = affineOf(yScale);
     const outX = [];
@@ -652,13 +652,13 @@ export function decimateScatter(cs, xScale, yScale, cellPx, vStart = 0, vEnd = c
         if (!Number.isFinite(y))
             continue; // gap — no mark
         const xv = cs.x[i];
-        const px = ax !== null ? ax.k * xv + ax.b : xScale(xv);
+        const px = ax !== null ? (xv - ax.v0) * ax.k + ax.p0 : xScale(xv);
         const col = Math.floor(px / cell);
         if (col !== curCol) {
             rows.clear();
             curCol = col;
         }
-        const py = ay !== null ? ay.k * y + ay.b : yScale(y);
+        const py = ay !== null ? (y - ay.v0) * ay.k + ay.p0 : yScale(y);
         const row = Math.floor(py / cell);
         if (!rows.has(row)) {
             rows.add(row);

package/dist/index.d.ts

@@ -2,19 +2,19 @@
  * `@pond-ts/charts` — the visualization end of pond.
  *
  * Canvas-rendered, streaming-first time-series charts with a
- * react-timeseries-charts-style declarative layout. The architecture (hard
- * layers: adapter → typed-array store → decimator → canvas renderer → React
- * shell) is documented in the charts RFC at `docs/rfcs/charts.md`; the
- * milestone plan lives in `PLAN.md`. (A Path2D path cache was explored and
- * deferred — it doesn't help the pan case, which re-decimates every frame; see
- * the [PND-DECIM] floor decision.)
+ * react-timeseries-charts-style declarative layout: compose
+ * `<ChartContainer>` → `<ChartRow>` → `<Layers>` → draw layers
+ * (line/area/band/scatter/bar/box/candle), plus the standalone DOM row lists
+ * ({@link BarList} / {@link BoxList}). **The data contract is the pond series
+ * itself** — every layer takes a `TimeSeries` / `ValueSeries` (or a
+ * partition `Map`, `byColumn` bins, category records) directly and shapes
+ * internally; an adapter you must call when starting from a series is an API
+ * failure (`docs/notes/charts-api-review-2026-08.md`). The exported `from*`
+ * view builders are **interop escape hatches** for non-pond data only.
  *
- * **M1 — rendering spine.** The layout shell + the first draw layer:
- * `<ChartContainer>` (time axis) → `<ChartRow>` (y-axis + canvas) →
- * `<LineChart>` (a gap-aware line), fed from a pond `TimeSeries` via
- * {@link fromTimeSeries}. Axes, themes, the variance band, and interactions
- * land in M2–M4. {@link Canvas} is the low-level DPR-aware primitive the rows
- * sit on.
+ * Architecture (typed-array store → decimator → canvas renderer → React
+ * shell): `docs/rfcs/charts.md`; roadmap: `PLAN.md`. {@link Canvas} is the
+ * low-level DPR-aware primitive the rows sit on.
  *
  * @packageDocumentation
  */
@@ -49,6 +49,12 @@ export type { BarChartProps } from './BarChart.js';
 export { Candlestick } from './Candlestick.js';
 export type { CandlestickProps } from './Candlestick.js';
 export type { CandleVariant, ColorBy } from './ohlc.js';
+export { BarList } from './BarList.js';
+export type { BarListProps } from './BarList.js';
+export { BoxList } from './BoxList.js';
+export type { BoxListProps } from './BoxList.js';
+export { listRowsFromTimeSeries, listRowsFromValueSeries } from './list.js';
+export type { ListRow, ListValue, ListCellSpec, ListMarker, ListSortDirection, ListRowsOptions, BarListColumn, BoxListColumn, } from './list.js';
 export { Legend } from './Legend.js';
 export type { LegendProps, LegendPlacement } from './Legend.js';
 export type { SwatchSpec, LegendItemInput } from './swatch.js';
@@ -63,7 +69,7 @@ export type { RegionProps, BaselineProps, MarkerProps } from './annotations.js';
 export type { AnnotationKind, CreateSpec } from './context.js';
 export { YAxisIndicator, createLiveValue } from './indicators.js';
 export type { YAxisIndicatorProps, LiveValue } from './indicators.js';
-export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries, stacksFromGroups, stacksFromColumns, stacksFromBins, categoryStack, transposeRow, } from './data.js';
+export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, barsFromBins, ohlcFromTimeSeries, stacksFromGroups, stacksFromColumns, stacksFromBins, categoryStack, transposeRow, } from './data.js';
 export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, OhlcSeries, OhlcColumns, StackedBarSeries, BinRecord, StacksFromBinsOptions, CategoryDatum, RowAt, TransposeRowOptions, } from './data.js';
 export type { Orientation } from './bars.js';
 export type { RadiusEncoding, ColorEncoding } from './encoding.js';

package/dist/index.js

@@ -2,19 +2,19 @@
  * `@pond-ts/charts` — the visualization end of pond.
  *
  * Canvas-rendered, streaming-first time-series charts with a
- * react-timeseries-charts-style declarative layout. The architecture (hard
- * layers: adapter → typed-array store → decimator → canvas renderer → React
- * shell) is documented in the charts RFC at `docs/rfcs/charts.md`; the
- * milestone plan lives in `PLAN.md`. (A Path2D path cache was explored and
- * deferred — it doesn't help the pan case, which re-decimates every frame; see
- * the [PND-DECIM] floor decision.)
+ * react-timeseries-charts-style declarative layout: compose
+ * `<ChartContainer>` → `<ChartRow>` → `<Layers>` → draw layers
+ * (line/area/band/scatter/bar/box/candle), plus the standalone DOM row lists
+ * ({@link BarList} / {@link BoxList}). **The data contract is the pond series
+ * itself** — every layer takes a `TimeSeries` / `ValueSeries` (or a
+ * partition `Map`, `byColumn` bins, category records) directly and shapes
+ * internally; an adapter you must call when starting from a series is an API
+ * failure (`docs/notes/charts-api-review-2026-08.md`). The exported `from*`
+ * view builders are **interop escape hatches** for non-pond data only.
  *
- * **M1 — rendering spine.** The layout shell + the first draw layer:
- * `<ChartContainer>` (time axis) → `<ChartRow>` (y-axis + canvas) →
- * `<LineChart>` (a gap-aware line), fed from a pond `TimeSeries` via
- * {@link fromTimeSeries}. Axes, themes, the variance band, and interactions
- * land in M2–M4. {@link Canvas} is the low-level DPR-aware primitive the rows
- * sit on.
+ * Architecture (typed-array store → decimator → canvas renderer → React
+ * shell): `docs/rfcs/charts.md`; roadmap: `PLAN.md`. {@link Canvas} is the
+ * low-level DPR-aware primitive the rows sit on.
  *
  * @packageDocumentation
  */
@@ -33,6 +33,14 @@ export { ScatterChart } from './ScatterChart.js';
 export { BoxPlot } from './BoxPlot.js';
 export { BarChart } from './BarChart.js';
 export { Candlestick } from './Candlestick.js';
+// The list family — DOM-rendered *ranked row lists* (the react-timeseries-charts
+// `HorizontalBarChart` shape, reconceived as a table): one row per entity, a
+// proportional bar / five-number box line per configured column, data cells,
+// custom sort, per-row expander. Standalone — no <ChartContainer> (the in-plot
+// horizontal bars remain `<BarChart orientation="horizontal">`).
+export { BarList } from './BarList.js';
+export { BoxList } from './BoxList.js';
+export { listRowsFromTimeSeries, listRowsFromValueSeries } from './list.js';
 // The series key: rows enumerate the registered layers' resolved styles.
 export { Legend } from './Legend.js';
 // The headless legend — the same rows + hover/select sync as data, for
@@ -48,7 +56,7 @@ export { Region, Baseline, Marker } from './annotations.js';
 // Axis indicators — a value pill pinned to an axis edge (the ChartIQ live tag).
 // `createLiveValue` is the high-frequency, isolated-repaint update path.
 export { YAxisIndicator, createLiveValue } from './indicators.js';
-export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries, 
+export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, barsFromBins, ohlcFromTimeSeries, 
 // Stacked / histogram readers — assemble a StackedBarSeries from pond's own
 // aggregation output: a Map of grouped series, a wide series, or byColumn bins.
 stacksFromGroups, stacksFromColumns, stacksFromBins, 

package/dist/line.js

@@ -26,8 +26,8 @@ export function strokeAffinePolyline(ctx, xs, ys, ax, ay) {
             penDown = false;
             continue;
         }
-        const px = ax.k * xs[j] + ax.b;
-        const py = ay.k * v + ay.b;
+        const px = (xs[j] - ax.v0) * ax.k + ax.p0;
+        const py = (v - ay.v0) * ay.k + ay.p0;
         if (penDown)
             ctx.lineTo(px, py);
         else {

package/dist/list-source.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The list family's **source union** — `rows` XOR `series`, shared by
+ * {@link BarList} and {@link BoxList} ([PND-CHARTAPI]).
+ *
+ * Two things this fixes, both flagged on #590's review and deferred to here
+ * so one union pattern serves the layers and the lists alike:
+ *
+ * 1. **The doors were both optional**, so `<BarList columns={…} />` with
+ *    neither source, and `rows` + `series` together, type-checked and threw at
+ *    render. Now each is a compile error.
+ * 2. **The generic row type could lie.** `R` is inferred from the *callbacks*
+ *    (`sort`, cell `render`, `renderExpanded`, `onRowClick`), so merely
+ *    annotating one of them while passing `series` inferred a custom `R` that
+ *    the series door cannot honour — it produces plain {@link ListRow}s. The
+ *    series member pins `R` to `ListRow`, so the annotation now fails to
+ *    compile instead of lying at runtime.
+ */
+import type { ReactNode } from 'react';
+import type { SeriesSchema, TimeSeries, ValueSeries, ValueSeriesSchema } from 'pond-ts';
+import type { ListRow, ListRowsOptions } from './list.js';
+/**
+ * The **record door**: entity rows built by hand or from partition facts.
+ * `R` may extend {@link ListRow} with extra fields, which then flow into
+ * every callback fully typed.
+ */
+export interface ListRowsSource<R extends ListRow> {
+    readonly rows: readonly R[];
+    readonly series?: never;
+    readonly label?: never;
+}
+/**
+ * The **series door**: one row per event, read internally — starting from a
+ * pond series there is no shaping step. Rows are plain {@link ListRow}s (the
+ * reader cannot know a caller's custom row shape), so this member does not
+ * carry `R`.
+ */
+export interface ListSeriesSource<S extends SeriesSchema, VS extends ValueSeriesSchema> {
+    readonly series: TimeSeries<S> | ValueSeries<VS>;
+    readonly rows?: never;
+    /**
+     * The built-in label cell per row — from the row's ordinal and its axis key
+     * (epoch ms / axis value). **Omitted ⇒ the stringified key renders.**
+     */
+    readonly label?: ListRowsOptions['label'];
+}
+/** `rows` XOR `series` — exactly one door, enforced at compile time. */
+export type ListSource<R extends ListRow, S extends SeriesSchema, VS extends ValueSeriesSchema> = ListRowsSource<R> | ListSeriesSource<S, VS>;
+/**
+ * The row type a given source yields: a caller's `R` through the record door,
+ * plain {@link ListRow} through the series door. Callback props resolve
+ * against this, which is what stops the series door from claiming a custom
+ * row shape it cannot produce.
+ */
+export type RowOf<Src> = Src extends {
+    rows: readonly (infer T)[];
+} ? T extends ListRow ? T : ListRow : ListRow;
+/** Narrowing helper for the components' runtime read of the union. */
+export declare function isSeriesSource<R extends ListRow, S extends SeriesSchema, VS extends ValueSeriesSchema>(src: ListSource<R, S, VS>): src is ListSeriesSource<S, VS>;
+/** Re-exported for the components' prop docs. */
+export type ListLabel = (i: number, key: number) => ReactNode;
+//# sourceMappingURL=list-source.d.ts.map

package/dist/list-source.js

@@ -0,0 +1,5 @@
+/** Narrowing helper for the components' runtime read of the union. */
+export function isSeriesSource(src) {
+    return src.series !== undefined;
+}
+//# sourceMappingURL=list-source.js.map