@pond-ts/charts 0.53.1 → 0.55.0

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

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/Layers.js

@@ -101,6 +101,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,7 +115,7 @@ 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
+            const yTicks = gridY && !(yIsCategory && explicitY === undefined)
                 ? (explicitY ?? gridY.ticks(yCount)).map((t) => gridY(t))
                 : [];
             // On a calendar axis the verticals are the FULL grain populations —