@pond-ts/charts 0.54.0 → 0.56.2

package/dist/BoxList.js

@@ -0,0 +1,125 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { ValueSeries } from 'pond-ts';
+import { listFraction, listRowsFromTimeSeries, listRowsFromValueSeries, resolveListDomain, sortListRows, validateBoxListColumn, } from './list.js';
+import { isSeriesSource, } from './list-source.js';
+import { ListTable, listInk } from './ListTable.js';
+import { defaultTheme } from './theme.js';
+/**
+ * A **distribution row list** — {@link BarList}'s sister, drawing a horizontal
+ * five-number box per configured column instead of a value bar: the light
+ * `lower→upper` range band, the stronger `q1→q3` body, the `median` line, and
+ * an optional **current-value tick** with a printed label (the esnet
+ * traffic-by-interface look: where traffic *ranges* vs where it *is now*).
+ *
+ * Same table contract as {@link BarList} (standalone, cells, sort, expander,
+ * one shared scale, gap-aware), same quantile vocabulary as the canvas
+ * `<BoxPlot>` (`lower`/`q1`/`median`/`q3`/`upper`, both-or-neither body,
+ * quantiles **pre-computed upstream** — `series.reduce` facts; the chart never
+ * computes them).
+ *
+ * ```tsx
+ * <BoxList
+ *   rows={ifaceRows}
+ *   columns={[
+ *     { lower: 'in_p5', q1: 'in_p25', median: 'in_p50', q3: 'in_p75',
+ *       upper: 'in_p95', value: 'in_now', format: fmtBps },
+ *     { lower: 'out_p5', q1: 'out_p25', median: 'out_p50', q3: 'out_p75',
+ *       upper: 'out_p95', value: 'out_now', format: fmtBps, as: 'secondary' },
+ *   ]}
+ *   sortBy="in_now"
+ * />
+ * ```
+ */
+export function BoxList(props) {
+    // One normalized view of the union — `isSeriesSource` is the runtime
+    // narrowing; the doors are mutually exclusive by construction now.
+    const source = props;
+    const { rows, series, label, columns, domain, sortBy, sortDirection = 'desc', sort, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, markers, barHeight = 10, divided, baseline = true, theme = defaultTheme, } = source;
+    // A runtime guard for JS consumers and `any`-typed call sites — the
+    // props union makes both branches unreachable from typed TS, but a
+    // silently-ignored source prop is a worse failure than a throw.
+    if (isSeriesSource(props) === (rows !== undefined)) {
+        throw new Error('<BoxList>: provide exactly one of `rows` (records) or `series` (one row per event)');
+    }
+    for (const col of columns)
+        validateBoxListColumn(col);
+    // The series door reads internally — starting from a pond series there is
+    // no shaping step (with `series`, R stays the default ListRow).
+    const allRows = useMemo(() => rows ??
+        (series instanceof ValueSeries
+            ? listRowsFromValueSeries(series, label !== undefined ? { label } : {})
+            : listRowsFromTimeSeries(series, label !== undefined ? { label } : {})), [rows, series, label]);
+    const sorted = useMemo(() => sortListRows(allRows, sortBy, sortDirection, sort), [allRows, sortBy, sortDirection, sort]);
+    const scale = useMemo(() => resolveListDomain(allRows, columns.flatMap((c) => c.value !== undefined
+        ? [c.lower, c.upper, c.value]
+        : [c.lower, c.upper]), domain, markers?.map((m) => m.value)), [allRows, columns, domain, markers]);
+    const resolvedMarkers = useMemo(() => markers?.map((m) => ({
+        frac: listFraction(m.value, scale),
+        ...(m.label !== undefined ? { label: m.label } : {}),
+    })), [markers, scale]);
+    return (_jsx(ListTable, { rows: sorted, kind: "box", markers: resolvedMarkers, before: before, after: after, renderExpanded: renderExpanded, defaultExpanded: defaultExpanded, onExpandToggle: onExpandToggle, selected: selected, onRowClick: onRowClick, divided: divided, baseline: baseline, theme: theme, renderGlyphs: (row) => (_jsx(_Fragment, { children: columns.map((col, ci) => (_jsx(BoxLine
+            // Index-qualified so two lines over the same quantile names
+            // (say, styled differently) never collide.
+            , { row: row, col: col, scale: scale, height: barHeight, style: theme.box[col.as ?? 'default'] ?? theme.box.default, ink: listInk(theme), fontSize: theme.font.size }, `${ci} ${col.lower} ${col.upper}`))) })) }));
+}
+/** One horizontal box line: range band → body → median → current tick + label. */
+function BoxLine({ row, col, scale, height, style, ink, fontSize, }) {
+    const at = (name) => name === undefined ? null : listFraction(row.values[name], scale);
+    const lo = at(col.lower);
+    const hi = at(col.upper);
+    const q1 = at(col.q1);
+    const q3 = at(col.q3);
+    const med = at(col.median);
+    const tick = at(col.value);
+    const raw = col.value !== undefined ? row.values[col.value] : undefined;
+    const label = col.format !== undefined && typeof raw === 'number' && Number.isFinite(raw)
+        ? col.format(raw)
+        : null;
+    const pct = (f) => `${f * 100}%`;
+    // The row keeps its slot height even when everything is missing — a gap
+    // reads as an empty line, not a collapsed row.
+    return (_jsxs("div", { "data-list-boxline": "", style: { position: 'relative', height: height + 4, margin: '2px 0' }, children: [lo !== null && hi !== null && (_jsx("div", { "data-list-range": "", style: {
+                    position: 'absolute',
+                    top: 2,
+                    bottom: 2,
+                    left: pct(lo),
+                    width: pct(Math.max(hi - lo, 0)),
+                    background: style.whisker,
+                    opacity: 0.55,
+                    borderRadius: height / 2,
+                } })), q1 !== null && q3 !== null && (_jsx("div", { "data-list-body": "", style: {
+                    position: 'absolute',
+                    top: 2,
+                    bottom: 2,
+                    left: pct(q1),
+                    width: pct(Math.max(q3 - q1, 0)),
+                    background: style.fill,
+                    opacity: Math.min(style.fillOpacity * 2, 1),
+                    borderRadius: 1,
+                } })), med !== null && (_jsx("div", { "data-list-median": "", style: {
+                    position: 'absolute',
+                    top: 2,
+                    bottom: 2,
+                    left: `calc(${pct(med)} - ${style.medianWidth / 2}px)`,
+                    width: style.medianWidth,
+                    background: style.median,
+                } })), tick !== null && (_jsxs(_Fragment, { children: [_jsx("div", { "data-list-tick": "", style: {
+                            position: 'absolute',
+                            top: 0,
+                            bottom: 0,
+                            left: `calc(${pct(tick)} - 1.5px)`,
+                            width: 3,
+                            background: style.stroke,
+                            borderRadius: 1,
+                        } }), label !== null && (_jsx("span", { "data-list-value": "", style: {
+                            position: 'absolute',
+                            left: `calc(${pct(tick)} + 8px)`,
+                            top: '50%',
+                            transform: 'translateY(-50%)',
+                            whiteSpace: 'nowrap',
+                            fontSize: fontSize + 1,
+                            color: ink,
+                        }, children: label }))] }))] }));
+}
+//# sourceMappingURL=BoxList.js.map

package/dist/BoxPlot.d.ts

@@ -1,37 +1,9 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import { type BoxShape } from './box.js';
 import type { DecimateOption } from './decimate.js';
-export interface BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
-    /**
-     * The source series. A `TimeSeries` plots against the time axis; a `ValueSeries`
-     * (`series.byValue('strike')`, or `ValueSeries.fromColumns` for natively
-     * value-keyed data — a per-strike IV distribution) against its value axis — the
-     * container infers which from the data, no axis-type prop (mirrors `<LineChart>`
-     * / `<ScatterChart>`). The box x-span is the key's `[begin, end)` for an
-     * interval-keyed `TimeSeries`, else synthesized from neighbour spacing (a
-     * point-keyed `TimeSeries`, or a `ValueSeries`) so the box keeps real width.
-     */
-    series: TimeSeries<S> | ValueSeries<VS>;
-    /** Name of the numeric column for the lower whisker end (e.g. `p5` / `min`).
-     *  **Required** — with `upper` it's the whisker reach. */
-    lower: string;
-    /**
-     * Name of the numeric column for the box bottom — first quartile (e.g. `p25`).
-     * **Optional:** omit `q1` **and** `q3` together for a **range-only** box — a
-     * whisker-only `lower→upper` segment, no body (a bid→ask IV mark). Giving just
-     * one of `q1`/`q3` throws.
-     */
-    q1?: string;
-    /** Name of the numeric column for the median line (e.g. `p50`). **Optional** —
-     *  omit for no centre line (independent of the box body). */
-    median?: string;
-    /** Name of the numeric column for the box top — third quartile (e.g. `p75`).
-     *  **Optional** — omit with `q1` for a range-only box (see `q1`). */
-    q3?: string;
-    /** Name of the numeric column for the upper whisker end (e.g. `p95` / `max`).
-     *  **Required** — with `lower` it's the whisker reach. */
-    upper: string;
+export interface BoxPlotCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The box series' semantic identifier — what the spread _is_ (e.g. `latency`).
      * The theme maps it to a {@link BoxStyle} (`theme.box[as] ?? theme.box.default`
@@ -122,6 +94,66 @@ export interface BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends
      */
     index?: number;
 }
+/**
+ * BoxPlot's source + column props, a **union over the series kind** so the
+ * column names are checked against the schema that was actually passed
+ * ([PND-CHARTAPI]). A single member carrying `NumericColumn<S> |
+ * ValueNumericColumn<VS>` would silently widen to `string`: only one of the
+ * two generics is ever inferred, and the other falls back (measured in
+ * `spikes/charts-type-seam/`). Loosely-typed series still accept any name.
+ */
+type BoxPlotSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = {
+    /**
+     * The source series. **Live charts:** `series.byValue(…)` mints a
+     * *fresh* projection each call, so an inline `series={s.byValue('d')}`
+     * re-registers this layer every render — on a frequently re-rendering
+     * (e.g. scrub-driven) chart, memoize the projection (`useMemo`) so the
+     * layer isn't rebuilt each frame.
+     */
+    series: TimeSeries<S>;
+    /** Lower whisker end (e.g. `p5` / `min`). **Required** — with `upper`
+     *  it is the whisker reach. */
+    lower: NumericColumn<S>;
+    /**
+     * Box bottom — first quartile (e.g. `p25`). **Optional:** omit `q1`
+     * **and** `q3` together for a **range-only** box (a whisker-only
+     * `lower→upper` segment, no body — a bid→ask IV mark). Giving just one
+     * of the pair throws.
+     */
+    q1?: NumericColumn<S>;
+    /** Median line (e.g. `p50`). **Optional** — omit for no centre line
+     *  (independent of the box body). */
+    median?: NumericColumn<S>;
+    /** Box top — third quartile (e.g. `p75`). **Optional** — omit with `q1`
+     *  for a range-only box. */
+    q3?: NumericColumn<S>;
+    /** Upper whisker end (e.g. `p95` / `max`). **Required** — with `lower`
+     *  it is the whisker reach. */
+    upper: NumericColumn<S>;
+} | {
+    series: ValueSeries<VS>;
+    /** Lower whisker end (e.g. `p5` / `min`). **Required** — with `upper`
+     *  it is the whisker reach. */
+    lower: ValueNumericColumn<VS>;
+    /**
+     * Box bottom — first quartile (e.g. `p25`). **Optional:** omit `q1`
+     * **and** `q3` together for a **range-only** box (a whisker-only
+     * `lower→upper` segment, no body — a bid→ask IV mark). Giving just one
+     * of the pair throws.
+     */
+    q1?: ValueNumericColumn<VS>;
+    /** Median line (e.g. `p50`). **Optional** — omit for no centre line
+     *  (independent of the box body). */
+    median?: ValueNumericColumn<VS>;
+    /** Box top — third quartile (e.g. `p75`). **Optional** — omit with `q1`
+     *  for a range-only box. */
+    q3?: ValueNumericColumn<VS>;
+    /** Upper whisker end (e.g. `p95` / `max`). **Required** — with `lower`
+     *  it is the whisker reach. */
+    upper: ValueNumericColumn<VS>;
+};
+/** `<BoxPlot>`'s props: the shared knobs plus one series-kind source shape. */
+export type BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = BoxPlotCommon<S, VS> & BoxPlotSource<S, VS>;
 /**
  * A discrete box-and-whisker draw layer — the bar-chart analog of the variance
  * band. Reads **pre-computed quantile columns** of `series` (typically a
@@ -154,4 +186,5 @@ export interface BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends
  * ```
  */
 export declare function BoxPlot<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, q1, median, q3, upper, as: semantic, axis, gap, shape, showMedian, offset, capWidth, id, decimate, legend, index, }: BoxPlotProps<S, VS>): null;
+export {};
 //# sourceMappingURL=BoxPlot.d.ts.map

package/dist/Candlestick.d.ts

@@ -1,4 +1,5 @@
 import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import type { NumericColumn } from './column-names.js';
 import type { DecimateOption } from './decimate.js';
 import { type CandleVariant, type ColorBy } from './ohlc.js';
 export interface CandlestickProps<S extends SeriesSchema> {
@@ -12,13 +13,13 @@ export interface CandlestickProps<S extends SeriesSchema> {
      */
     series: TimeSeries<S>;
     /** Opening-price column. **Omitted ⇒ `'open'`.** */
-    open?: string;
+    open?: NumericColumn<S>;
     /** Session-high column. **Omitted ⇒ `'high'`.** */
-    high?: string;
+    high?: NumericColumn<S>;
     /** Session-low column. **Omitted ⇒ `'low'`.** */
-    low?: string;
+    low?: NumericColumn<S>;
     /** Closing-price column. **Omitted ⇒ `'close'`.** */
-    close?: string;
+    close?: NumericColumn<S>;
     /**
      * The series' semantic identifier — what the data _is_ (e.g. a ticker). The
      * theme maps it to a {@link CandleStyle} (`theme.candle[as] ??

package/dist/ChartRow.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
-import { scaleLinear } from 'd3-scale';
-import { resolveYDomain } from './domain.js';
+import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { scaleLinear, scaleLog } from 'd3-scale';
+import { isDev } from './dev.js';
+import { logAxisWarning, needsExtents, resolveYDomain } from './domain.js';
 import { resolveAxisFormat } from './format.js';
 import { resolveYTickCount } from './yticks.js';
 import { placeAxisSlots } from './slots.js';
@@ -39,6 +40,7 @@ function axisSpecEqual(a, b) {
     return (a.id === b.id &&
         a.side === b.side &&
         a.width === b.width &&
+        a.scale === b.scale &&
         // Object.is (not ===) so a degenerate NaN bound compares equal to itself and
         // doesn't re-register every render.
         Object.is(a.min, b.min) &&
@@ -171,6 +173,7 @@ export function ChartRow({ height, cursor, children }) {
                 id: IMPLICIT_AXIS_ID,
                 side: 'left',
                 width: 0,
+                scale: 'linear',
                 min: undefined,
                 max: undefined,
                 pad: 0,
@@ -222,20 +225,68 @@ export function ChartRow({ height, cursor, children }) {
     const yScales = useMemo(() => {
         const map = new Map();
         for (const ax of effectiveAxes) {
-            const extents = ax.min === undefined || ax.max === undefined
+            const extents = needsExtents(ax)
                 ? layerList
                     .filter((entry) => (entry.axisId ?? defaultAxisId) === ax.id)
                     .map((entry) => entry.layer.yExtent())
                 : [];
-            const [lo, hi] = resolveYDomain(ax.min, ax.max, extents, ax.pad);
+            const [lo, hi] = resolveYDomain(ax.min, ax.max, extents, ax.pad, ax.scale);
             // Reserve a header band at the top when any axis draws a `'top'` title,
             // so the title clears the top tick + plot (the whole row shifts down
             // uniformly, keeping stacked axes aligned). No top titles ⇒ range top 0,
             // so nothing changes for existing charts.
-            map.set(ax.id, scaleLinear().domain([lo, hi]).range([height, topHeader]));
+            // `scaleLog` and `scaleLinear` share the call/ticks/tickFormat/invert
+            // surface every consumer uses (see `YScale`), so choosing between them
+            // here is the whole of log support — no draw layer branches on it.
+            const base = ax.scale === 'log' ? scaleLog() : scaleLinear();
+            map.set(ax.id, base.domain([lo, hi]).range([height, topHeader]));
         }
         return map;
     }, [effectiveAxes, layerList, height, defaultAxisId, topHeader]);
+    // Dev-mode diagnostics for a `scale="log"` axis (see `logAxisWarning`). Three
+    // things about *where* this sits are load-bearing, each of them a bug the
+    // first version shipped:
+    //
+    //  - **An effect, not the scale memo.** Warning from inside `useMemo` is a
+    //    side effect in a function React may call speculatively — and does call
+    //    twice under StrictMode.
+    //  - **Deduplicated by message, in a ref.** The comment on the original said
+    //    "warn once per offending axis" and nothing implemented it, so a live
+    //    chart re-warned on every appended sample. Keying on the message (not a
+    //    bare "already warned" flag) still reports a *different* complaint if the
+    //    data changes shape.
+    //  - **`height` is not a dependency.** It is one for the scales, which is why
+    //    the warning must not ride along: a drag-resize would otherwise emit a
+    //    line per animation frame.
+    //
+    // Gated on `isDev` **and** on some axis actually being logarithmic, so a
+    // production build and every linear chart skip the extent walk entirely.
+    const warnedRef = useRef(new Map());
+    useEffect(() => {
+        if (!isDev || !effectiveAxes.some((ax) => ax.scale === 'log'))
+            return;
+        const warned = warnedRef.current;
+        for (const ax of effectiveAxes) {
+            // A linear axis in the same row has nothing to say and must not pay the
+            // O(points) walk below just because a sibling is logarithmic.
+            if (ax.scale !== 'log')
+                continue;
+            // Always walk the extents here, even for a fully-explicit domain the
+            // scale memo skips them for: data that cannot be drawn is worth saying so
+            // about whether or not it happened to constrain the bounds — and the
+            // both-explicit axis was exactly the case the first version stayed silent
+            // about.
+            const message = logAxisWarning(ax, layerList
+                .filter((entry) => (entry.axisId ?? defaultAxisId) === ax.id)
+                .map((entry) => entry.layer.yExtent()));
+            if (message === null)
+                warned.delete(ax.id);
+            else if (warned.get(ax.id) !== message) {
+                warned.set(ax.id, message);
+                console.warn(message);
+            }
+        }
+    }, [effectiveAxes, layerList, defaultAxisId]);
     // Resolved auto-tick count per axis — explicit `<YAxis tickCount>` else
     // height-derived (see resolveYTickCount). The single source the `<YAxis>`
     // labels, the readout formatter (below), and the `Layers` gridlines all read,

package/dist/Layers.js

@@ -5,6 +5,7 @@ import { drawGrid, drawDividers, dividerAlphas, thinPixels } from './grid.js';
 import { cursorParts, bandRect, regionSpan } from './tracker.js';
 import { resolveSelection } from './select.js';
 import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
+import { yTickValues } from './yticks.js';
 import { flagChipStyle, flagChipX, axisPillX, axisPillStyle } from './chip.js';
 import { ContainerContext, CursorContext, LayersContext, RowContext, } from './context.js';
 /** Fallback **y**-gridline tick count, used only before the row publishes its
@@ -101,6 +102,13 @@ export function Layers({ children }) {
         // A category axis draws no vertical gridlines — a line through each bar
         // centre reads as noise; the bars are the structure.
         const xTickVals = container.xKind === 'category' ? [] : xScale.ticks(xTickCount);
+        // The same rule on the other axis: a **horizontal** categorical chart
+        // ([PND-HCAT]) puts its categories on y, where the `<YAxis>` labels slot
+        // *centres* while d3's auto ticks fall on slot *boundaries* — so drawing
+        // them would both mismatch the labels and stripe each bar. Suppressed,
+        // exactly as the categorical x axis already is.
+        const yIsCategory = layers.some((e) => (e.axisId ?? defaultAxisId) === defaultAxisId &&
+            (e.layer.binCategories?.() ?? null) !== null);
         // The reference grid — behind the data, opt-out via `grid={false}` for
         // a clean backdrop (session dividers below stay independent of it).
         if (container.grid) {
@@ -108,8 +116,8 @@ export function Layers({ children }) {
             // single source, height-derived or an explicit `<YAxis tickCount>`), so
             // a gridline sits under every `<YAxis>` label and no more.
             const yCount = tickCounts.get(defaultAxisId) ?? GRID_TICKS;
-            const yTicks = gridY
-                ? (explicitY ?? gridY.ticks(yCount)).map((t) => gridY(t))
+            const yTicks = gridY && !(yIsCategory && explicitY === undefined)
+                ? (explicitY ?? yTickValues(gridY, yCount)).map((t) => gridY(t))
                 : [];
             // On a calendar axis the verticals are the FULL grain populations —
             // every day in the month, every month in the year, every aligned
@@ -260,6 +268,18 @@ export function Layers({ children }) {
         // a full replot per mousemove.
         container.timeRange,
         container.reportDrawStats,
+        // Read inside `draw`, so they have to invalidate it. Omitting `grid` meant
+        // toggling `<ChartContainer grid>` changed nothing until some *other*
+        // dep moved — pan the plot a pixel and the gridlines you switched off
+        // finally vanished. All primitives, so no per-frame identity churn.
+        container.grid,
+        container.sessionDividers,
+        container.xKind,
+        // `container.theme` is read too. It is deliberately NOT listed: it is the
+        // caller's prop and an inline object literal would rebuild `draw` every
+        // render (a full replot per frame). The values `draw` actually takes from
+        // it — `background`, `gridColor`, `gridDash` — are extracted above and
+        // listed individually, so a theme swap still invalidates.
         row.rowKey,
     ]);
     // Interaction overlay: the cursor marks live on a DOM/SVG overlay above the

package/dist/LineChart.d.ts

@@ -1,34 +1,10 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import type { DecimateOption } from './decimate.js';
 import { type Curve } from './curve.js';
 import { type GapMode } from './gaps.js';
-export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
-    /**
-     * The source series. A `TimeSeries` plots against the time axis; a
-     * `ValueSeries` (`series.byValue('cumDist')`) against its value axis — the
-     * container infers which from the data, no axis-type prop. Either way the key
-     * / axis column supplies x and `column` supplies y.
-     *
-     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
-     * passing `series={s.byValue('dist')}` inline re-registers this layer every
-     * render — on a frequently re-rendering (e.g. scrub-driven) chart, memoize the
-     * projection (`useMemo`) so the layer isn't rebuilt each frame.
-     */
-    series: TimeSeries<S> | ValueSeries<VS>;
-    /** Name of the numeric value column to plot. */
-    column: string;
-    /**
-     * Optional column to **read out** at the cursor instead of the plotted
-     * `column`. The layer still plots `column`; each tracker sample additionally
-     * carries this column's value as {@link TrackerSample.readout}, so an
-     * off-chart readout can show the **source** value while the line draws a
-     * derived one — a smoothed / transformed / normalized plot with a raw-value
-     * readout (estela plots pace-space + Gaussian-smoothed, reads the native m/s).
-     * The plotted `value` (hence the in-chart cursor dot) is unchanged.
-     * **Omitted ⇒ no readout channel** (`readout` is `undefined` on the sample).
-     */
-    readout?: string;
+export interface LineChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The series' semantic identifier — what the data _is_ / how it should read
      * (e.g. `heartrate`, `power`, or a role name like `foam`). The theme maps it
@@ -99,6 +75,32 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      */
     index?: number;
 }
+/**
+ * LineChart's source + column props, a **union over the series kind** so the
+ * column names are checked against the schema that was actually passed
+ * ([PND-CHARTAPI]). A single member carrying `NumericColumn<S> |
+ * ValueNumericColumn<VS>` would silently widen to `string`: only one of the
+ * two generics is ever inferred, and the other falls back (measured in
+ * `spikes/charts-type-seam/`). Loosely-typed series still accept any name.
+ */
+type LineChartSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = {
+    /**
+     * The source series. **Live charts:** `series.byValue(…)` mints a
+     * *fresh* projection each call, so an inline `series={s.byValue('d')}`
+     * re-registers this layer every render — on a frequently re-rendering
+     * (e.g. scrub-driven) chart, memoize the projection (`useMemo`) so the
+     * layer isn't rebuilt each frame.
+     */
+    series: TimeSeries<S>;
+    column: NumericColumn<S>;
+    readout?: NumericColumn<S>;
+} | {
+    series: ValueSeries<VS>;
+    column: ValueNumericColumn<VS>;
+    readout?: ValueNumericColumn<VS>;
+};
+/** `<LineChart>`'s props: the shared knobs plus one series-kind source shape. */
+export type LineChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = LineChartCommon<S, VS> & LineChartSource<S, VS>;
 /**
  * A line draw layer. Reads `column` from `series` into a {@link ChartSeries}
  * (columnar, gaps as NaN), registers itself into the enclosing {@link Layers}
@@ -106,4 +108,5 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * it. The line breaks at gaps rather than spanning them.
  */
 export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, curve, gaps, sessionBreaks, decimate, legend, index, }: LineChartProps<S, VS>): null;
+export {};
 //# sourceMappingURL=LineChart.d.ts.map

package/dist/ListTable.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @internal The shared row-table shell behind {@link BarList} / {@link BoxList}.
+ *
+ * Renders a real `<table>` — the point of the list family is table semantics
+ * (label cells that can be links, aligned data cells, a `colSpan` detail row
+ * for the expander, screen-reader-legible rows), which a canvas plot can't
+ * carry and which hand-rolled flex rows re-implement badly (per-row cell
+ * alignment is exactly what table layout solves). The glyph cell takes
+ * `width: 100%` so it absorbs the free width; every text cell shrinks to fit.
+ *
+ * Not exported from the package: the public surface is the two sisters, so the
+ * shared shell can evolve without a compatibility contract.
+ */
+import { type ReactNode } from 'react';
+import type { ListCellSpec, ListRow } from './list.js';
+import type { ChartTheme } from './theme.js';
+export interface ListTableProps<R extends ListRow> {
+    /** Rows in display order (the caller sorts). */
+    readonly rows: readonly R[];
+    /** Which sister is rendering — stamped as `data-list` for styling/tests. */
+    readonly kind: 'bar' | 'box';
+    /** The glyph cell's content for one row (the bar / box lines). */
+    readonly renderGlyphs: (row: R) => ReactNode;
+    readonly before?: readonly ListCellSpec<R>[] | undefined;
+    readonly after?: readonly ListCellSpec<R>[] | undefined;
+    readonly renderExpanded?: ((row: R) => ReactNode) | undefined;
+    readonly defaultExpanded?: readonly string[] | undefined;
+    readonly onExpandToggle?: ((key: string, expanded: boolean) => void) | undefined;
+    readonly selected?: string | null | undefined;
+    readonly onRowClick?: ((row: R) => void) | undefined;
+    readonly divided?: boolean | undefined;
+    /** Draw the vertical **baseline rule** at the scale origin (the glyph
+     *  cell's left edge) — the shared reference the eye aligns rows against. */
+    readonly baseline?: boolean | undefined;
+    /**
+     * Reference markers, **pre-resolved to track fractions** by the caller (the
+     * shell knows pixels, not the scale): each draws a dotted vertical rule
+     * through every row's glyph area, plus a label strip above the list when
+     * any carries a `label`. A `null` fraction (out-of-scale gap) is skipped.
+     */
+    readonly markers?: ReadonlyArray<{
+        readonly frac: number | null;
+        readonly label?: string;
+    }> | undefined;
+    readonly theme: ChartTheme;
+}
+/** The shared text ink: the band-label tone when the theme has one (stronger
+ *  than tick labels — these cells are primary content), else the tick ink. */
+export declare function listInk(theme: ChartTheme): string;
+export declare function ListTable<R extends ListRow>({ rows, kind, renderGlyphs, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, divided, baseline, markers, theme, }: ListTableProps<R>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ListTable.d.ts.map