@pond-ts/charts 0.54.0 → 0.56.2

package/dist/BarChart.d.ts

@@ -2,55 +2,86 @@ import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
 import { type BinRecord, type CategoryDatum } from './data.js';
 import { type Orientation } from './bars.js';
+import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import type { DecimateOption } from './decimate.js';
-export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
-    /**
-     * The source series. Provide **exactly one** of `series` or `bins`.
-     *
-     * - A **`TimeSeries`** (interval / timeRange-keyed is the primary form — each
-     *   event's key `[begin, end]` is a bar's x-span; a point-keyed series derives
-     *   its width from neighbour spacing) → single-series bars via `column`, or
-     *   stacked bars from a **wide** series via `columns`.
-     * - A **`ValueSeries`** (`series.byValue('dist')`) bars against its value axis.
-     * - A **`ReadonlyMap<group, TimeSeries>`** — one series per stack group, all on
-     *   the same bin grid, the shape
-     *   `series.partitionBy('host', { groups }).aggregate(seq, m).toMap()` returns.
-     *   Stacked bars, `column` names the shared value column, groups = map order.
-     *
-     * **Live charts:** `series.byValue(…)` / `.toMap()` mint fresh objects each
-     * call, so an inline `series={…}` re-registers this layer every render — on a
-     * frequently re-rendering chart, memoize the projection (`useMemo`).
-     */
-    series?: TimeSeries<S> | ValueSeries<VS> | ReadonlyMap<string, TimeSeries<S>>;
-    /**
-     * `byColumn` **bin records** — `Array<{ start, end, …aggregates }>` from a
-     * value-band aggregation
-     * (`series.byColumn('power', { width: 20 }, { seconds: … })`). The value-axis
-     * alternative to `series`: `column` / `columns` name the aggregate field(s) to
-     * draw. Pair with `ordinal` for a category (band) axis.
-     */
-    bins?: readonly BinRecord[];
-    /**
-     * **Categorical** data — an ordered `{ label, value }[]`, one bar per category
-     * on a first-class **ordinal category x-axis** (the container infers
-     * `xKind:'category'` and builds a band scale over the labels). The transpose
-     * view's "columns on x": each `label` is a category (ticker / account / zone),
-     * `value` its bar height. Provide **exactly one** of `series` / `bins` /
-     * `categories`; `categories` takes no `column`/`columns` and is **vertical only**
-     * (categories on x). Colour per category via `binColors`. (Categorical-axis RFC,
-     * Phase 1.)
-     */
-    categories?: readonly CategoryDatum[];
-    /** Name of the numeric value column for the bar height (single series). Provide
-     *  `column` **or** `columns`, not both. */
-    column?: string;
-    /**
-     * Stacked-segment columns, **bottom → top** — one segment per name. Use with a
-     * **wide** `series` (e.g. `pivotByGroup` output) or with `bins`. Mutually
-     * exclusive with `column`, and invalid with a `Map` series (there the segments
-     * are the map's groups; use `column`).
-     */
-    columns?: readonly string[];
+/**
+ * The **mode union** — the legal (source, columns) combinations, each a
+ * separate member so an illegal mix fails to compile instead of throwing at
+ * render ([PND-CHARTAPI]; the 2026-08 API review's #1 item). Column names are
+ * schema-derived where the source is a series (see `column-names.ts`, which
+ * also explains why a loosely-typed series still accepts any string).
+ *
+ * Members, in the order a reader meets them:
+ *
+ * - **`series` + `column`** — one bar per event. A `TimeSeries`
+ *   (interval/timeRange-keyed draws true spans; a point key derives width
+ *   from neighbour spacing), a `ValueSeries` (`series.byValue('dist')`), or a
+ *   **`ReadonlyMap<group, TimeSeries>`** (the
+ *   `partitionBy(…).aggregate(…).toMap()` shape) — for a `Map`, `column` names
+ *   the shared value column and the map's order is the stack order.
+ * - **`series` + `columns`** — a **wide** series stacked bottom → top (e.g.
+ *   `pivotByGroup` output). Invalid with a `Map` source: there the segments
+ *   *are* the groups, so use `column`.
+ * - **`bins` + `column` / `columns`** — `byColumn` bin records
+ *   (`Array<{ start, end, …aggregates }>`); the names are **aggregate
+ *   fields** of the record, not schema columns, so they stay `string`. Pair
+ *   with `ordinal` for a band axis.
+ * - **`categories`** — an ordered `{ label, value }[]`, one bar per category.
+ *   Takes **no** `column`/`columns` (each datum carries its own value).
+ *   Vertical puts the categories on the ordinal **x** axis (the container's
+ *   band scale); `orientation="horizontal"` puts them on **y** as unit slots
+ *   and the value on x, and a `<YAxis>` with no explicit `ticks` labels one
+ *   per category automatically ([PND-HCAT]).
+ *
+ * **Live charts:** `series.byValue(…)` / `.toMap()` mint fresh objects each
+ * call, so an inline `series={…}` re-registers this layer every render — on a
+ * frequently re-rendering chart, memoize the projection (`useMemo`).
+ */
+type BarChartSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = {
+    series: TimeSeries<S> | ReadonlyMap<string, TimeSeries<S>>;
+    column: NumericColumn<S>;
+    columns?: never;
+    bins?: never;
+    categories?: never;
+} | {
+    series: ValueSeries<VS>;
+    column: ValueNumericColumn<VS>;
+    columns?: never;
+    bins?: never;
+    categories?: never;
+} | {
+    series: TimeSeries<S>;
+    columns: readonly NumericColumn<S>[];
+    column?: never;
+    bins?: never;
+    categories?: never;
+} | {
+    series: ValueSeries<VS>;
+    columns: readonly ValueNumericColumn<VS>[];
+    column?: never;
+    bins?: never;
+    categories?: never;
+} | {
+    bins: readonly BinRecord[];
+    column: string;
+    columns?: never;
+    series?: never;
+    categories?: never;
+} | {
+    bins: readonly BinRecord[];
+    columns: readonly string[];
+    column?: never;
+    series?: never;
+    categories?: never;
+} | {
+    categories: readonly CategoryDatum[];
+    series?: never;
+    bins?: never;
+    column?: never;
+    columns?: never;
+};
+/** The props every {@link BarChartSource} mode shares. */
+export interface BarChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The single series' semantic identifier — what the data _is_. The theme maps
      * it to a {@link BarStyle} (`theme.bar[as] ?? theme.bar.default`). **Single
@@ -91,7 +122,10 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      * - `'vertical'` — bars grow **up** from a value baseline, bins on the **x**
      *   axis (time buckets, value bands). The column / time-histogram look.
      * - `'horizontal'` — bars grow **right**, bins on the **y** axis (a band axis
-     *   like heart-rate zones). Label the bands with `<YAxis ticks={[{ at, label }]}>`.
+     *   like heart-rate zones). Label the bands with `<YAxis ticks={[{ at, label }]}>`
+     *   — or, with `categories`, let the `<YAxis>` derive them ([PND-HCAT]): a
+     *   horizontal categorical chart hands the axis its names and they land one
+     *   per slot, so a funnel / ranking needs no hand-built tick list.
      *
      * A `'horizontal'` chart puts the **value** on the shared x axis, so its
      * container's x-kind is `'value'` — it cannot share a `<ChartContainer>` with
@@ -159,6 +193,14 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      */
     index?: number;
 }
+/**
+ * `<BarChart>`'s props: the shared knobs ({@link BarChartCommon}) plus
+ * **exactly one** legal source shape ({@link BarChartSource}). Mixing sources
+ * (`series` + `bins`) or column forms (`column` + `columns`) is a **compile**
+ * error, and a column name that isn't in the series' schema fails to compile
+ * too — both were runtime throws before [PND-CHARTAPI].
+ */
+export type BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = BarChartCommon<S, VS> & BarChartSource<S, VS>;
 /**
  * A bar / histogram draw layer. In its simplest form, one rectangle per event
  * spanning the key's `[begin, end]` from the axis baseline to a numeric
@@ -203,4 +245,5 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
  * ```
  */
 export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation, ordinal, id, axis, gap, decimate, legend, index, }: BarChartProps<S, VS>): null;
+export {};
 //# sourceMappingURL=BarChart.d.ts.map

package/dist/BarChart.js

@@ -1,6 +1,6 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { Interval, ValueSeries } from 'pond-ts';
-import { barsFromTimeSeries, barsFromValueSeries, categoryStack, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
+import { barsFromTimeSeries, barsFromBins, barsFromValueSeries, categoryStack, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
 import { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
@@ -69,9 +69,6 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         if (column !== undefined || columns !== undefined) {
             throw new Error('<BarChart categories> takes no `column`/`columns` (each datum carries its own value)');
         }
-        if (orientation === 'horizontal') {
-            throw new Error('<BarChart categories> is vertical only (categories on x); horizontal category axes are not yet supported');
-        }
     }
     const isMap = series instanceof Map;
     if (isMap && columns !== undefined) {
@@ -82,7 +79,14 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     }
     // The single series' semantic label (its identity for the readout + selection):
     // the `as` role, else the value column. Used only on the single path.
-    const label = semantic ?? column ?? id ?? 'value';
+    //
+    // [PND-BARSEM] normalizes a ONE-ENTRY `columns` onto that path, and its mark
+    // is the same mark `column` would name — so the lone entry stands in here,
+    // or `columns={['a']}` and `column="a"` would report different `SelectInfo.label`
+    // for the identical bar (found in review of #593).
+    const soleColumn = column ??
+        (columns !== undefined && columns.length === 1 ? columns[0] : undefined);
+    const label = semantic ?? soleColumn ?? id ?? 'value';
     // Build the chart-ready data view. Single-series *vertical* stays on the
     // original BarSeries path (its pixels are unchanged); everything else — any
     // stack, any horizontal — builds a StackedBarSeries (G === 1 for a single
@@ -99,6 +103,17 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
             if (cols === undefined) {
                 throw new Error('<BarChart bins> needs `column` or `columns`');
             }
+            // [PND-BARSEM]: a ONE-column vertical histogram draws the same mark as a
+            // `series`+`column` chart, so it takes the same path — and with it the
+            // whole-slot hit target, the hover colour, the cursor readout and
+            // per-bar decimation. Capabilities follow what is drawn, not which prop
+            // produced it. Horizontal keeps the transposed stacked path.
+            if (cols.length === 1 && orientation !== 'horizontal') {
+                return {
+                    kind: 'single',
+                    bs: barsFromBins(bins, cols[0], { ordinal }),
+                };
+            }
             return { kind: 'stacked', ss: stacksFromBins(bins, cols, { ordinal }) };
         }
         if (isMap) {
@@ -112,6 +127,18 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         }
         const s = series;
         if (columns !== undefined) {
+            // [PND-BARSEM]: a one-entry `columns` is a single series wearing the
+            // stack's clothes — same mark, so the same capabilities (see the `bins`
+            // branch above).
+            if (columns.length === 1 && orientation !== 'horizontal') {
+                const only = columns[0];
+                return {
+                    kind: 'single',
+                    bs: s instanceof ValueSeries
+                        ? barsFromValueSeries(s, only)
+                        : barsFromTimeSeries(s, only),
+                };
+            }
             return { kind: 'stacked', ss: stacksFromColumns(s, columns) };
         }
         if (column === undefined) {
@@ -178,7 +205,29 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     }, [shape, orientation, binAxisKind]);
     const { bar } = container.theme;
     // Single-series style: the `as` role → theme bar style (the single channel).
-    const singleStyle = (semantic !== undefined ? bar[semantic] : undefined) ?? bar.default;
+    //
+    // A shape [PND-BARSEM] normalized onto this path (a one-column `bins`, a
+    // one-entry `columns`) used to resolve its fill through the *stacked*
+    // channel — `colors[group] ?? theme.bar[group] ?? default` — so resolving
+    // only `as` here would silently drop a caller's `colors` map and the
+    // `theme.bar[<column>]` role, changing the bars' colour with no error
+    // (found in review of #593). The column name is that shape's group name, so
+    // the same three-step lookup is applied, `as` still winning when given.
+    const singleStyle = useMemo(() => {
+        const byRole = semantic !== undefined ? bar[semantic] : undefined;
+        if (byRole !== undefined)
+            return byRole;
+        if (soleColumn !== undefined) {
+            const override = colors?.[soleColumn];
+            const byColumn = bar[soleColumn];
+            if (override !== undefined) {
+                return { ...(byColumn ?? bar.default), fill: override };
+            }
+            if (byColumn !== undefined)
+                return byColumn;
+        }
+        return bar.default;
+    }, [bar, semantic, soleColumn, colors]);
     const gapPx = gap ?? bar.default.gap;
     // The stacked path's bar-thickness floor comes from `bar.default` (not the `as`
     // role — `as` is single-series only), matching how `gapPx` sources its default.
@@ -256,7 +305,10 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                         : {
                             hitTest: (px, py, xScale, yScale) => {
                                 const baseline = resolveBarBaseline(yScale);
-                                const hit = barAt(bs, px, py, xScale, yScale, baseline, gapPx, singleStyle.minWidth);
+                                // No `gapPx` — the hit region is the bar's whole slot (its
+                                // interval width, full plot height), not the inset rect the
+                                // gap draws. See barSlotRect.
+                                const hit = barAt(bs, px, py, xScale, yScale, baseline, singleStyle.minWidth);
                                 if (hit === null)
                                     return null;
                                 const [bi, begin, value] = hit;
@@ -302,8 +354,13 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                 ...(binBuckets !== null ? { binIntervals: () => binBuckets } : {}),
                 // A categorical chart hands the container its ordered category names — the
                 // ordinal axis domain the shared band scale + label formatter build on.
+                // Categorical labels go to the axis the categories actually land on:
+                // x for a vertical chart (the container's band scale), y for a
+                // horizontal one, where they label the unit slots ([PND-HCAT]).
                 ...(categoryLabels !== null
-                    ? { xCategories: () => categoryLabels }
+                    ? vertical
+                        ? { xCategories: () => categoryLabels }
+                        : { binCategories: () => categoryLabels }
                     : {}),
                 // No x-scrub flag for a stack / horizontal chart — hover + click read it
                 // out instead (the flag is single-series-vertical only).

package/dist/BarList.d.ts

@@ -0,0 +1,127 @@
+import { type ReactNode } from 'react';
+import type { SeriesSchema, ValueSeriesSchema } from 'pond-ts';
+import { type BarListColumn, type ListCellSpec, type ListMarker, type ListRow, type ListSortDirection } from './list.js';
+import { type ListRowsSource, type ListSeriesSource } from './list-source.js';
+import { type ChartTheme } from './theme.js';
+/** The props both BarList source doors share. */
+export interface BarListCommon<R extends ListRow = ListRow> {
+    /**
+     * The bar lines, **top→bottom within each row** — each names a `values`
+     * entry for its length and optionally a theme role (`as`). Several columns
+     * stack as parallel lines per row (the to-site / from-site pairing), all on
+     * the **one shared scale**, so lengths compare across lines and rows alike.
+     */
+    columns: readonly BarListColumn[];
+    /**
+     * The shared scale's `[min, max]`. **Omitted ⇒ resolved from the data**:
+     * `[min(0, data min), data max]` over every bar column of every row. Set it
+     * to pin the scale across live updates (a re-sorting traffic list whose max
+     * changes every tick) or across sibling lists.
+     *
+     * Bars are **length-encoded from the domain minimum** — the component
+     * assumes non-negative values. A negative value stays in-domain (the auto
+     * fit widens below zero) but draws as a short left-anchored bar, not a
+     * diverging one; diverging bar lists are out of scope (transform upstream,
+     * or use {@link BoxList}, whose marks are positional).
+     */
+    domain?: readonly [number, number];
+    /**
+     * Name of the `values` entry that **ranks the list** — with several bar
+     * columns, this is the decision of which one drives the order. Missing /
+     * non-finite values sort last either direction. **Omitted ⇒ input order**
+     * (the chronological splits case).
+     */
+    sortBy?: string;
+    /** `'desc'` (default — largest on top, the ranked-list convention) or `'asc'`. */
+    sortDirection?: ListSortDirection;
+    /** Full custom comparator — **overrides** `sortBy`/`sortDirection`. */
+    sort?: (a: R, b: R) => number;
+    /** Data cell columns rendered **between the label and the bars**, in order. */
+    before?: readonly ListCellSpec<R>[];
+    /** Data cell columns rendered **after the bars**, in order (a split's
+     *  speed / climb readouts). */
+    after?: readonly ListCellSpec<R>[];
+    /**
+     * A row's expanded detail (any node — a stats grid, a nested chart).
+     * **Providing it adds the chevron column**; expansion is per-row,
+     * uncontrolled, keyed on `row.key` (so it survives a re-sort), seeded by
+     * `defaultExpanded`. Omitted ⇒ no expander UI at all.
+     */
+    renderExpanded?: (row: R) => ReactNode;
+    /** Row keys expanded on first render. */
+    defaultExpanded?: readonly string[];
+    /** Observe a toggle (`expanded` is the row's **new** state). */
+    onExpandToggle?: (key: string, expanded: boolean) => void;
+    /**
+     * The selected row's `key`, marked with an inset edge in the annotation
+     * (marks) register — selection is a user's mark, not data. Consumer-owned
+     * state: pair with `onRowClick`. `null` / omitted ⇒ none.
+     */
+    selected?: string | null;
+    /** Row click (rows show hover + pointer affordances only when provided). */
+    onRowClick?: (row: R) => void;
+    /** Each bar line's height in px. **Omitted ⇒ `8`.** */
+    barHeight?: number;
+    /** Rule between rows (`theme.axis.grid`). **Omitted ⇒ `true`.** */
+    divided?: boolean;
+    /**
+     * Reference **markers** on the shared scale — each draws a dotted vertical
+     * rule through every row (annotation-register ink) with its `label` printed
+     * above the list, centred on the rule. An SLA line, a capacity, the fleet
+     * average. Marker values **join the auto domain fit** (a threshold above
+     * the data max widens the scale); under an explicit `domain` they clamp.
+     */
+    markers?: readonly ListMarker[];
+    /**
+     * The vertical **baseline rule** at the scale origin (the glyph cell's left
+     * edge, the row dividers' `axis.grid` ink). **Omitted ⇒ `false`** — a bar's track
+     * already shows where zero is; opt in when the tracks are visually quiet.
+     * (`<BoxList>` defaults it **on**: its lines float at `lower`, so the shared
+     * origin is what relates rows to each other.)
+     */
+    baseline?: boolean;
+    /** Styling — the same {@link ChartTheme} the canvas charts read; bars
+     *  resolve `theme.bar[as]`. **Omitted ⇒ {@link defaultTheme}.** */
+    theme?: ChartTheme;
+}
+/**
+ * `<BarList>`'s props: the shared knobs ({@link BarListCommon}) plus **exactly
+ * one** source door ([PND-CHARTAPI]). Passing both `rows` and `series`, or
+ * neither, is now a **compile** error rather than a render-time throw.
+ *
+ * The two members differ in their row type on purpose. Through `rows`, a
+ * caller's `R` flows into every callback. Through `series` the rows are read
+ * internally and are plain {@link ListRow}s, so that member pins the callbacks
+ * to `ListRow` — annotating a callback with a custom row type while passing
+ * `series` no longer compiles, where before it silently lied (#590 review).
+ */
+export type BarListProps<R extends ListRow = ListRow, S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = (BarListCommon<R> & ListRowsSource<R>) | (BarListCommon<ListRow> & ListSeriesSource<S, VS>);
+/**
+ * A **ranked bar list** — the DOM sister of `<BarChart orientation="horizontal">`,
+ * for the table-shaped cases: one row per *entity* (interface, split, symbol),
+ * a label cell, one proportional bar line per configured column, optional data
+ * cells before/after, optional per-row expander. react-timeseries-charts'
+ * `HorizontalBarChart`, reconceived as what it always was: a table.
+ *
+ * **Standalone** — no `<ChartContainer>`; there is no time axis here. It takes
+ * a `theme` directly and renders a plain `<table>` (label cells can be links,
+ * cells align by table layout, the expander is a `colSpan` row).
+ *
+ * - **One shared scale.** Every bar of every row maps through one
+ *   `[min, max]` (see `domain`), because cross-row comparison is the point.
+ * - **Gaps.** A missing / non-numeric value renders an empty track and sorts
+ *   last — absence reads as absence, never as zero-drawn-long.
+ * - **Sorting.** `sortBy` + `sortDirection` for the common case, `sort` for
+ *   anything else, input order otherwise.
+ *
+ * ```tsx
+ * <BarList
+ *   rows={listRowsFromTimeSeries(splits, { label: (i) => `${i + 1}` })}
+ *   columns={[{ column: 'speed' }]}
+ *   after={[{ key: 'speed', align: 'right', render: (r) => fmtMph(r.values.speed) }]}
+ *   renderExpanded={(r) => <SplitDetail row={r} />}
+ * />
+ * ```
+ */
+export declare function BarList<R extends ListRow = ListRow, S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>(props: BarListProps<R, S, VS>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=BarList.d.ts.map

package/dist/BarList.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { ValueSeries } from 'pond-ts';
+import { listFraction, listRowsFromTimeSeries, listRowsFromValueSeries, resolveListDomain, sortListRows, } from './list.js';
+import { isSeriesSource, } from './list-source.js';
+import { ListTable } from './ListTable.js';
+import { defaultTheme } from './theme.js';
+/**
+ * A **ranked bar list** — the DOM sister of `<BarChart orientation="horizontal">`,
+ * for the table-shaped cases: one row per *entity* (interface, split, symbol),
+ * a label cell, one proportional bar line per configured column, optional data
+ * cells before/after, optional per-row expander. react-timeseries-charts'
+ * `HorizontalBarChart`, reconceived as what it always was: a table.
+ *
+ * **Standalone** — no `<ChartContainer>`; there is no time axis here. It takes
+ * a `theme` directly and renders a plain `<table>` (label cells can be links,
+ * cells align by table layout, the expander is a `colSpan` row).
+ *
+ * - **One shared scale.** Every bar of every row maps through one
+ *   `[min, max]` (see `domain`), because cross-row comparison is the point.
+ * - **Gaps.** A missing / non-numeric value renders an empty track and sorts
+ *   last — absence reads as absence, never as zero-drawn-long.
+ * - **Sorting.** `sortBy` + `sortDirection` for the common case, `sort` for
+ *   anything else, input order otherwise.
+ *
+ * ```tsx
+ * <BarList
+ *   rows={listRowsFromTimeSeries(splits, { label: (i) => `${i + 1}` })}
+ *   columns={[{ column: 'speed' }]}
+ *   after={[{ key: 'speed', align: 'right', render: (r) => fmtMph(r.values.speed) }]}
+ *   renderExpanded={(r) => <SplitDetail row={r} />}
+ * />
+ * ```
+ */
+export function BarList(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 = 8, divided, baseline, 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('<BarList>: provide exactly one of `rows` (records) or `series` (one row per event)');
+    }
+    // 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.map((c) => c.column), 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: "bar", 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) => {
+                const style = theme.bar[col.as ?? 'default'] ?? theme.bar.default;
+                const frac = listFraction(row.values[col.column], scale);
+                return (_jsxs("div", { "data-list-track": col.column, style: {
+                        position: 'relative',
+                        height: barHeight,
+                        margin: '3px 0',
+                        borderRadius: barHeight / 2,
+                        overflow: 'hidden',
+                    }, children: [_jsx("div", { style: {
+                                position: 'absolute',
+                                inset: 0,
+                                background: style.fill,
+                                opacity: 0.15,
+                            } }), frac !== null && frac > 0 && (_jsx("div", { "data-list-bar": col.column, style: {
+                                position: 'absolute',
+                                top: 0,
+                                bottom: 0,
+                                left: 0,
+                                width: `${frac * 100}%`,
+                                background: style.fill,
+                                opacity: style.opacity,
+                                borderRadius: barHeight / 2,
+                            } }))] }, `${ci} ${col.column}`));
+            }) })) }));
+}
+//# sourceMappingURL=BarList.js.map

package/dist/BoxList.d.ts

@@ -0,0 +1,108 @@
+import { type ReactNode } from 'react';
+import type { SeriesSchema, ValueSeriesSchema } from 'pond-ts';
+import { type BoxListColumn, type ListCellSpec, type ListMarker, type ListRow, type ListSortDirection } from './list.js';
+import { type ListRowsSource, type ListSeriesSource } from './list-source.js';
+import { type ChartTheme } from './theme.js';
+/** The props both BoxList source doors share. */
+export interface BoxListCommon<R extends ListRow = ListRow> {
+    /**
+     * The box lines, **top→bottom within each row** — each names the `values`
+     * entries for its five-number summary (`lower`/`upper` required; `q1`+`q3`
+     * both-or-neither; `median` optional — the `<BoxPlot>` vocabulary), plus an
+     * optional current-value tick (`value`) with an inline `format`ted label.
+     * All lines share the **one scale** so distributions compare across the
+     * whole list.
+     */
+    columns: readonly BoxListColumn[];
+    /**
+     * The shared scale's `[min, max]`. **Omitted ⇒ resolved from the data**
+     * over every box's `lower`/`upper`/`value`: `[min(0, data min), data max]`.
+     */
+    domain?: readonly [number, number];
+    /**
+     * Name of the `values` entry that ranks the list. The box columns are
+     * plain `values` names, so any stat sorts — the current value
+     * (`sortBy="in_now"`), a p95, a median — with no stat-picking rule to
+     * remember. Missing sorts last. **Omitted ⇒ input order.**
+     */
+    sortBy?: string;
+    /** `'desc'` (default) or `'asc'`. */
+    sortDirection?: ListSortDirection;
+    /** Full custom comparator — **overrides** `sortBy`/`sortDirection`. */
+    sort?: (a: R, b: R) => number;
+    /** Data cell columns between the label and the boxes. */
+    before?: readonly ListCellSpec<R>[];
+    /** Data cell columns after the boxes. */
+    after?: readonly ListCellSpec<R>[];
+    /** A row's expanded detail; providing it adds the chevron column (see
+     *  `BarListProps.renderExpanded`). */
+    renderExpanded?: (row: R) => ReactNode;
+    /** Row keys expanded on first render. */
+    defaultExpanded?: readonly string[];
+    /** Observe a toggle (`expanded` is the row's new state). */
+    onExpandToggle?: (key: string, expanded: boolean) => void;
+    /** The selected row's `key` (inset accent edge). Pair with `onRowClick`. */
+    selected?: string | null;
+    /** Row click (also gates the hover affordance). */
+    onRowClick?: (row: R) => void;
+    /** Each box line's height in px. **Omitted ⇒ `10`.** */
+    barHeight?: number;
+    /** Rule between rows. **Omitted ⇒ `true`.** */
+    divided?: boolean;
+    /**
+     * Reference **markers** on the shared scale — a dotted vertical rule
+     * through every row with the `label` printed above the list (see
+     * `BarListProps.markers`; identical semantics, including joining the auto
+     * domain fit).
+     */
+    markers?: readonly ListMarker[];
+    /**
+     * The vertical **baseline rule** at the scale origin (the glyph cell's left
+     * edge, the row dividers' `axis.grid` ink). **Omitted ⇒ `true`** — box lines float
+     * at their `lower` quantile, so the shared origin is what lets the eye
+     * relate rows to each other. Pass `false` to drop it.
+     */
+    baseline?: boolean;
+    /** Styling — boxes resolve `theme.box[as]`. **Omitted ⇒ {@link defaultTheme}.** */
+    theme?: ChartTheme;
+}
+/**
+ * `<BoxList>`'s props: the shared knobs ({@link BoxListCommon}) plus **exactly
+ * one** source door ([PND-CHARTAPI]). Passing both `rows` and `series`, or
+ * neither, is now a **compile** error rather than a render-time throw.
+ *
+ * The two members differ in their row type on purpose. Through `rows`, a
+ * caller's `R` flows into every callback. Through `series` the rows are read
+ * internally and are plain {@link ListRow}s, so that member pins the callbacks
+ * to `ListRow` — annotating a callback with a custom row type while passing
+ * `series` no longer compiles, where before it silently lied (#590 review).
+ */
+export type BoxListProps<R extends ListRow = ListRow, S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = (BoxListCommon<R> & ListRowsSource<R>) | (BoxListCommon<ListRow> & ListSeriesSource<S, VS>);
+/**
+ * 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 declare function BoxList<R extends ListRow = ListRow, S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>(props: BoxListProps<R, S, VS>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=BoxList.d.ts.map