@pond-ts/charts 0.54.0 → 0.56.2

package/dist/domain.js

@@ -1,4 +1,4 @@
-import { scaleLinear } from 'd3-scale';
+import { scaleLinear, scaleLog } from 'd3-scale';
 /**
  * Resolve a y-axis `[lo, hi]` domain from its explicit bounds and the extents of
  * the layers linked to it. An `undefined` bound auto-fits the data: with no
@@ -20,8 +20,17 @@ import { scaleLinear } from 'd3-scale';
  * `pad × span` on each side — headroom without hand-computing bounds, useful to
  * lift a tight **explicit** domain off the plot edges. Applied last, to whatever
  * domain was resolved (explicit or auto); `0` is a no-op.
+ *
+ * `scale` selects the spacing. `'log'` delegates to {@link resolveLogDomain},
+ * which applies **every policy above** — verbatim explicit bounds, an auto-fit
+ * side that moves rather than a caller's bound being discarded, `.nice()` on a
+ * fully auto-fit domain — and differs only where a log axis forces it to: a
+ * non-positive bound has no position and is refused, and `pad` is a fraction of
+ * the *decades* spanned rather than of the difference.
  */
-export function resolveYDomain(min, max, extents, pad = 0) {
+export function resolveYDomain(min, max, extents, pad = 0, scale = 'linear') {
+    if (scale === 'log')
+        return resolveLogDomain(min, max, extents, pad);
     const result = resolveBase(min, max, extents);
     if (pad) {
         const [lo, hi] = result;
@@ -30,6 +39,190 @@ export function resolveYDomain(min, max, extents, pad = 0) {
     }
     return result;
 }
+/** Smallest positive value a log domain will fall back to when the data offers
+ *  nothing positive at all. Arbitrary but finite — a log scale has no natural
+ *  zero to anchor on, and `[0, 1]` (the linear empty-data domain) has no
+ *  position for its own low end: `scaleLog().domain([0, 1])(x)` is `NaN` for
+ *  every `x`, which poisons every coordinate drawn against it. */
+const LOG_EMPTY_LO = 1;
+const LOG_EMPTY_HI = 10;
+/**
+ * The log analog of {@link resolveBase} + padding.
+ *
+ * The **policy** is deliberately identical to linear's, so `scale="log"` changes
+ * how a domain is spaced and not what the props mean:
+ *
+ * - **Two explicit bounds are verbatim** (an inverted pair is a deliberate axis
+ *   flip; we don't second-guess it).
+ * - **A partial explicit bound is never discarded.** When one side is explicit
+ *   and the resolved domain would invert, the **auto-fit** side moves — exactly
+ *   as {@link resolveBase} does. (This inverted the caller's policy until the
+ *   log-axis review: `resolveLogDomain(undefined, 100, [[1000, 2000]])` returned
+ *   `[1000, 10000]`, silently throwing away the requested `max` and putting the
+ *   axis three decades from where it was asked to be.)
+ * - **A fully auto-fit domain is `.nice()`d**, the promise {@link resolveYDomain}
+ *   already documents. `scaleLog().nice()` extends to whole powers of ten, so
+ *   the extremes get headroom instead of sitting clipped against the plot edge
+ *   and the decade ticks land on the domain bounds.
+ *
+ * Two things differ from linear, and both are consequences of the same fact —
+ * that a log axis has no position for zero:
+ *
+ * - **Non-positive bounds are unusable.** Auto-fit takes the smallest
+ *   *positive* extent rather than the smallest, so one zero sample doesn't
+ *   collapse the axis; an explicit non-positive `min`/`max` is ignored in
+ *   favour of the data (a caller asking for `min={0}` on a log axis has asked
+ *   for `NaN` — see {@link logAxisWarning} — which we will not hand to a scale).
+ *   A bound refused this way is treated as *absent* from here on, so the side
+ *   that survives is still honoured as an explicit bound.
+ * - **Padding is multiplicative.** `pad` is a *fraction of the domain*, and on
+ *   a log axis the domain's span is a ratio, not a difference. Padding
+ *   additively would add a constant number of bytes to a decade — invisible at
+ *   the top, enormous at the bottom. Applying it in log space adds the same
+ *   *fraction of a decade* at both ends, which is what the linear behaviour
+ *   looks like to the eye. (The expression is sign-correct on a flipped domain
+ *   for the same reason linear's is: `log10(hi/lo)` goes negative, so both ends
+ *   still move outward.)
+ */
+function resolveLogDomain(min, max, extents, pad) {
+    // A non-positive explicit bound is refused, and from here on is simply absent
+    // — so `max={1e6}` with a refused `min={0}` still behaves as "explicit top,
+    // auto-fit floor" rather than falling into the both-explicit branch.
+    const explicitLo = min !== undefined && min > 0 ? min : undefined;
+    const explicitHi = max !== undefined && max > 0 ? max : undefined;
+    const [lo, hi] = resolveLogBase(explicitLo, explicitHi, extents);
+    if (!pad)
+        return [lo, hi];
+    // A fraction of the *decades* spanned, added at each end.
+    const decades = Math.log10(hi / lo) * pad;
+    return [lo / 10 ** decades, hi * 10 ** decades];
+}
+/** {@link resolveLogDomain} minus the padding — the domain itself. */
+function resolveLogBase(explicitLo, explicitHi, extents) {
+    // Both bounds explicit (and positive): trust them verbatim, matching
+    // `resolveBase` — including an intentional flip.
+    if (explicitLo !== undefined && explicitHi !== undefined) {
+        return [explicitLo, explicitHi];
+    }
+    let dataLo = Infinity;
+    let dataHi = -Infinity;
+    for (const e of extents) {
+        if (!e)
+            continue;
+        // The low end walks both ends of the extent: a series whose min is 0 or
+        // negative can still have a positive max, and that max is the only
+        // positive floor it can offer.
+        if (e[0] > 0 && e[0] < dataLo)
+            dataLo = e[0];
+        else if (e[1] > 0 && e[1] < dataLo)
+            dataLo = e[1];
+        if (e[1] > dataHi)
+            dataHi = e[1];
+    }
+    if (dataLo === Infinity || !(dataHi > 0)) {
+        // Nothing positive to fit — the log counterpart of linear's `[0, 1]`.
+        dataLo = LOG_EMPTY_LO;
+        dataHi = LOG_EMPTY_HI;
+    }
+    else if (dataLo === dataHi) {
+        // Flat — give it room, so a constant line sits mid-row rather than on an
+        // edge (linear's ±1, expressed as a ratio: half a decade each way).
+        dataLo /= 10 ** 0.5;
+        dataHi *= 10 ** 0.5;
+    }
+    let lo = explicitLo ?? dataLo;
+    let hi = explicitHi ?? dataHi;
+    // A partial explicit bound can sit at or past the auto-fit other side. Keep
+    // the axis ascending by moving the *auto-fit* side — never discard the
+    // caller's explicit bound. Exactly one side is explicit here: both-explicit
+    // returned early, and a both-auto domain can't invert after the guards above.
+    if (lo >= hi) {
+        if (explicitLo === undefined)
+            lo = hi / 10; // hi is explicit → preserve it
+        else
+            hi = lo * 10; // lo is explicit → preserve it
+    }
+    // Fully auto-fit → round out to whole powers of ten, for headroom and so the
+    // decade ticks reach the domain bounds. A partial/full explicit bound is left
+    // exact, exactly as `resolveBase` leaves it.
+    if (explicitLo === undefined && explicitHi === undefined) {
+        return scaleLog().domain([lo, hi]).nice().domain();
+    }
+    return [lo, hi];
+}
+/**
+ * Does resolving this axis's domain need its layers' extents walked?
+ * `yExtent()` is O(points) per layer, so the caller only pays it when a side
+ * actually auto-fits.
+ *
+ * A log axis **refuses a non-positive bound** ({@link resolveLogDomain}), which
+ * means such a bound is not a bound: that side auto-fits and needs the data. The
+ * naive `min === undefined || max === undefined` test misses this, and the miss
+ * is silent — `<YAxis scale="log" min={0} max={1e6}>` looked fully explicit, so
+ * no extents were gathered, so the refused floor fell back to the empty-data
+ * placeholder instead of the data's own floor. (`resolveLogDomain`'s unit tests
+ * passed throughout: they hand it the extents directly, which is precisely what
+ * the component was not doing.)
+ */
+export function needsExtents(axis) {
+    if (axis.scale === 'log') {
+        return (!(axis.min !== undefined && axis.min > 0) ||
+            !(axis.max !== undefined && axis.max > 0));
+    }
+    return axis.min === undefined || axis.max === undefined;
+}
+/**
+ * The dev-mode complaint a `scale="log"` axis has about its own bounds and the
+ * data linked to it, or `null` when it has none. Pure, so the policy is unit
+ * tested directly rather than through a rendered console spy.
+ *
+ * **Every case here is unambiguous**, which is the whole design constraint. The
+ * previous version warned whenever a linked extent reached zero, and that fires
+ * on *every* `BarChart` — `barExtent` always widens its low end to `0` so a bar
+ * can reach its baseline, whether or not the data goes anywhere near it. So the
+ * `WithBars` story warned, on strictly positive data, with text asserting
+ * something false about it. A dev warning that cries wolf gets muted, and then
+ * the real ones are lost too.
+ *
+ * The cost of that precision is the one genuinely ambiguous shape: an extent of
+ * exactly `[0, hi]`, which is what a line touching zero *and* a bar layer on
+ * positive data both report. It is not warned about. That case is no longer
+ * silent, though — a sample with no position on the axis now renders as a
+ * **gap** rather than being bridged straight over, so the picture itself says
+ * the data is missing there.
+ */
+export function logAxisWarning(axis, extents) {
+    if (axis.scale !== 'log')
+        return null;
+    const reasons = [];
+    // `!(x > 0)` rather than `x <= 0` so a NaN bound is caught too — it is refused
+    // by the same rule and is just as invisible.
+    if (axis.min !== undefined && !(axis.min > 0)) {
+        reasons.push(`min={${axis.min}} was ignored (it is not a positive number)`);
+    }
+    if (axis.max !== undefined && !(axis.max > 0)) {
+        reasons.push(`max={${axis.max}} was ignored (it is not a positive number)`);
+    }
+    const present = extents.filter((e) => e !== null);
+    if (present.some((e) => e[0] < 0)) {
+        reasons.push('data linked to this axis includes negative values');
+    }
+    // Independent of the above, not an `else`: an axis whose data is *entirely*
+    // non-positive is both negative-valued and undrawable, and the second fact is
+    // the one that explains the empty plot.
+    if (present.length > 0 && !present.some((e) => e[1] > 0)) {
+        // There is data, and none of it is positive — the whole axis is a fallback
+        // domain and nothing will be drawn against it.
+        reasons.push(`no data linked to this axis is positive, so the domain fell back to ` +
+            `[${LOG_EMPTY_LO}, ${LOG_EMPTY_HI}]`);
+    }
+    if (reasons.length === 0)
+        return null;
+    return (`<YAxis id="${axis.id}" scale="log">: ${reasons.join('; ')}. ` +
+        'A log scale has no position for zero or negative numbers (d3 maps them ' +
+        'to NaN), so such values are refused as bounds and are not drawn. Filter ' +
+        'them out, or use the default linear scale.');
+}
 function resolveBase(min, max, extents) {
     // Both bounds explicit: trust them verbatim (allows an intentional flip).
     if (min !== undefined && max !== undefined)

package/dist/format.d.ts

@@ -45,6 +45,9 @@ export type CursorFormat = string | ((value: number, ctx: {
  *  optional specifier. A d3 `ScaleLinear` / `ScaleTime` satisfies it. */
 interface Tickable {
     tickFormat(count: number, specifier?: string): (value: number) => string;
+    /** Present on d3's `scaleLog` and on no other continuous scale. */
+    base?: () => number;
+    domain?: () => number[];
 }
 /**
  * Resolve an {@link AxisFormat} (or `undefined`) to a `(value) => string`
@@ -55,6 +58,23 @@ interface Tickable {
  * - a **specifier string** → `scale.tickFormat(count, specifier)` — d3 applies
  *   the specifier, so the readout matches ticks formatted the same way;
  * - **`undefined`** → `scale.tickFormat(count)` — the scale's default.
+ *
+ * **A log scale is formatted through a linear one over the same domain.**
+ * `scaleLog.tickFormat` is not a value formatter — it is a *tick* formatter,
+ * and it deliberately returns `''` for anything it doesn't consider a
+ * significant tick:
+ *
+ * ```
+ * scaleLog().domain([1.9e10, 2.6e17]).tickFormat(6, '.3s')(1.97e17) === ''
+ * ```
+ *
+ * That is correct for axis labels (it is how a log axis thins them) and
+ * catastrophic for the cursor readout, `YAxisIndicator` and `Baseline` chips,
+ * which share this formatter and ask it about arbitrary values — they would
+ * render blank for almost every real number. A linear scale's `tickFormat`
+ * applies the specifier to whatever it is handed, which is what every consumer
+ * of this function actually wants; the axis's own tick *thinning* is handled by
+ * `yTickValues`, not here.
  */
 export declare function resolveAxisFormat(scale: Tickable, count: number, format: AxisFormat | undefined): (value: number) => string;
 /** The slice of a d3 **time** scale {@link resolveTimeFormat} needs. A d3

package/dist/format.js

@@ -1,11 +1,4 @@
-/**
- * Axis value formatting — the single formatter shared by an axis's tick labels
- * and the cursor readout, so a value reads the same in both places (the readout
- * "matches the axes"). d3-style: a format **specifier string** (e.g. `'.0%'`,
- * `',.2f'`) is applied through the scale's own `tickFormat` (the same path d3
- * uses for the ticks), a **function** is used verbatim, and `undefined` falls
- * back to the scale's default `tickFormat`.
- */
+import { scaleLinear } from 'd3-scale';
 /**
  * Resolve an {@link AxisFormat} (or `undefined`) to a `(value) => string`
  * formatter, given the `scale` it formats against and the axis `count` (so the
@@ -15,13 +8,33 @@
  * - a **specifier string** → `scale.tickFormat(count, specifier)` — d3 applies
  *   the specifier, so the readout matches ticks formatted the same way;
  * - **`undefined`** → `scale.tickFormat(count)` — the scale's default.
+ *
+ * **A log scale is formatted through a linear one over the same domain.**
+ * `scaleLog.tickFormat` is not a value formatter — it is a *tick* formatter,
+ * and it deliberately returns `''` for anything it doesn't consider a
+ * significant tick:
+ *
+ * ```
+ * scaleLog().domain([1.9e10, 2.6e17]).tickFormat(6, '.3s')(1.97e17) === ''
+ * ```
+ *
+ * That is correct for axis labels (it is how a log axis thins them) and
+ * catastrophic for the cursor readout, `YAxisIndicator` and `Baseline` chips,
+ * which share this formatter and ask it about arbitrary values — they would
+ * render blank for almost every real number. A linear scale's `tickFormat`
+ * applies the specifier to whatever it is handed, which is what every consumer
+ * of this function actually wants; the axis's own tick *thinning* is handled by
+ * `yTickValues`, not here.
  */
 export function resolveAxisFormat(scale, count, format) {
     if (typeof format === 'function')
         return format;
+    const source = typeof scale.base === 'function' && typeof scale.domain === 'function'
+        ? scaleLinear().domain(scale.domain())
+        : scale;
     return format !== undefined
-        ? scale.tickFormat(count, format)
-        : scale.tickFormat(count);
+        ? source.tickFormat(count, format)
+        : source.tickFormat(count);
 }
 /**
  * The time analog of {@link resolveAxisFormat} — resolve an {@link AxisFormat}

package/dist/gaps.d.ts

@@ -72,6 +72,39 @@ export interface GapEdge {
     /** Pixel y of the next-good sample (`toIndex`). */
     readonly toY: number;
 }
+/**
+ * Return `values` with every entry that has **no position on `scale`** replaced
+ * by `NaN` — i.e. converted into the gap signal the rest of this module, the
+ * `.defined` predicates, and the affine draw loops already speak. Returns the
+ * input array itself (no copy) when nothing needs gapping, which is the
+ * overwhelmingly common case.
+ *
+ * **Why the raw value is not the right test.** Every gap check in this package
+ * asks `Number.isFinite(value)`, and `0` is finite — so on a **log** axis a zero
+ * sample sailed through as real data, d3 emitted `lineTo(x, NaN)` for it, and
+ * the canvas spec says a path op with a non-finite coordinate is *dropped*. Not
+ * drawn as a break: dropped. The pen stays where it was, the next point draws
+ * from there, and the two neighbours of the missing sample join with a straight
+ * line — a bridge over absent data, which is the one thing
+ * `docs/rfcs/charts.md` trap #2 exists to prevent, arrived at silently by a
+ * chart that had asked for the honest `'empty'` mode.
+ *
+ * Testing the **scaled** coordinate instead is both the honest answer and the
+ * general one: it needs no knowledge of which scale kind is in play, and any
+ * future scale with a restricted domain (`sqrt`, `pow` with a fractional
+ * exponent) inherits it. Normalizing to `NaN` here rather than special-casing
+ * three `.defined` predicates means the gap *modes* keep working too — a
+ * `'dashed'` connector spans it, `'none'` interpolates across it, `'fade'`
+ * drops to the floor at it — instead of the value being invisible to
+ * {@link collectGapEdges} and {@link bridgeGaps}, which read the values directly.
+ *
+ * **Costs nothing on a linear axis.** An affine scale ({@link affineOf}) maps
+ * every finite value to a finite pixel by construction, so there is nothing to
+ * find and the walk is skipped outright. That is also exactly the condition
+ * under which the callers take their affine fast path, so the O(N) probe only
+ * ever runs where the draw was already on the d3-scale path.
+ */
+export declare function gapUnscalable(values: Float64Array, length: number, scale: Scale): Float64Array;
 /**
  * Return a copy of `values` with **interior** gaps (NaN runs that have a finite
  * sample on each side) linearly interpolated across, for the `none` mode — so d3

package/dist/gaps.js

@@ -1,3 +1,4 @@
+import { affineOf } from './affine.js';
 /** The default gap mode — break at the gap, leave a hole (today's behavior). */
 export const DEFAULT_GAP_MODE = 'empty';
 /**
@@ -6,6 +7,54 @@ export const DEFAULT_GAP_MODE = 'empty';
  * inferred bridge reads as secondary to measured data.
  */
 export const DEFAULT_GAP_CONNECTOR_OPACITY = 0.5;
+/**
+ * Return `values` with every entry that has **no position on `scale`** replaced
+ * by `NaN` — i.e. converted into the gap signal the rest of this module, the
+ * `.defined` predicates, and the affine draw loops already speak. Returns the
+ * input array itself (no copy) when nothing needs gapping, which is the
+ * overwhelmingly common case.
+ *
+ * **Why the raw value is not the right test.** Every gap check in this package
+ * asks `Number.isFinite(value)`, and `0` is finite — so on a **log** axis a zero
+ * sample sailed through as real data, d3 emitted `lineTo(x, NaN)` for it, and
+ * the canvas spec says a path op with a non-finite coordinate is *dropped*. Not
+ * drawn as a break: dropped. The pen stays where it was, the next point draws
+ * from there, and the two neighbours of the missing sample join with a straight
+ * line — a bridge over absent data, which is the one thing
+ * `docs/rfcs/charts.md` trap #2 exists to prevent, arrived at silently by a
+ * chart that had asked for the honest `'empty'` mode.
+ *
+ * Testing the **scaled** coordinate instead is both the honest answer and the
+ * general one: it needs no knowledge of which scale kind is in play, and any
+ * future scale with a restricted domain (`sqrt`, `pow` with a fractional
+ * exponent) inherits it. Normalizing to `NaN` here rather than special-casing
+ * three `.defined` predicates means the gap *modes* keep working too — a
+ * `'dashed'` connector spans it, `'none'` interpolates across it, `'fade'`
+ * drops to the floor at it — instead of the value being invisible to
+ * {@link collectGapEdges} and {@link bridgeGaps}, which read the values directly.
+ *
+ * **Costs nothing on a linear axis.** An affine scale ({@link affineOf}) maps
+ * every finite value to a finite pixel by construction, so there is nothing to
+ * find and the walk is skipped outright. That is also exactly the condition
+ * under which the callers take their affine fast path, so the O(N) probe only
+ * ever runs where the draw was already on the d3-scale path.
+ */
+export function gapUnscalable(values, length, scale) {
+    if (affineOf(scale) !== null)
+        return values;
+    let out = null;
+    for (let i = 0; i < length; i += 1) {
+        const v = values[i];
+        if (!Number.isFinite(v) || Number.isFinite(scale(v)))
+            continue;
+        // Copy lazily — a log axis whose data never touches zero (the normal case)
+        // pays a scan and no allocation.
+        if (out === null)
+            out = values.slice();
+        out[i] = NaN;
+    }
+    return out ?? values;
+}
 /**
  * Return a copy of `values` with **interior** gaps (NaN runs that have a finite
  * sample on each side) linearly interpolated across, for the `none` mode — so d3

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

@@ -2,7 +2,7 @@ import { line as d3line, curveLinear } from 'd3-shape';
 import { cullChartSeries } from './culling.js';
 import { decimateM4Cached } from './decimate.js';
 import { affineOf } from './affine.js';
-import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
+import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, gapUnscalable, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 /** Shared empty boundary list — passed to `sessionRuns` when a decimated series
  *  already carries its session breaks as baked-in `NaN` points. */
 const EMPTY_BOUNDARIES = [];
@@ -131,6 +131,15 @@ export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, ga
     else {
         cs = cullChartSeries(source, xScale);
     }
+    // Normalize any value with **no position on the y scale** (a zero or negative
+    // sample on a log axis) into the ordinary NaN gap signal, so every consumer
+    // below — the `.defined` break, `bridgeGaps`, `collectGapEdges` — treats it as
+    // the absence it is instead of emitting a dropped `lineTo(x, NaN)` that
+    // silently bridges its neighbours. A no-op on an affine (linear) y scale; see
+    // {@link gapUnscalable}.
+    const scaledY = gapUnscalable(cs.y, cs.length, yScale);
+    if (scaledY !== cs.y)
+        cs = { ...cs, y: scaledY };
     // Split into independent index runs at each boundary; no boundary inside the
     // data ⇒ one run over the whole series (the hot path — no slicing, so the draw
     // is byte-identical to the pre-boundary single pass). When the series was

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