@pond-ts/charts 0.54.0 → 0.55.0

package/dist/bars.d.ts

@@ -50,8 +50,10 @@ export declare function resolveBarBaseline(yScale: Scale): number;
  * from {@link barSpanPx} (the key's `[begin, end]`, inset by `gapPx`, floored at
  * `minWidthPx`); the y-span runs between the value and the `baseline` pixel,
  * normalized so a value above *or* below the baseline both yield an ascending
- * rect. Shared by {@link drawBars} and {@link barAt} so the drawn rect and the
- * hit rect are the same geometry.
+ * rect. This is the **ink** — what {@link drawBars} paints. Hit-testing uses
+ * {@link barSlotRect} instead (the bar's whole slot), so the drawn rect and the
+ * hit region are deliberately *not* the same geometry: the `gapPx` inset
+ * separates columns visually without carving a dead channel out of the target.
  */
 export declare function barRect(cs: BarSeries, i: number, xScale: Scale, yScale: Scale, baseline: number, gapPx: number, minWidthPx: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
 /**
@@ -75,9 +77,12 @@ export interface BarMark {
  * no-id layer passes `undefined` and never matches — plus the bar's identity,
  * see {@link barMatches}) draws in the style's `highlight` colour **and
  * outlined**, so a click reads back on the canvas; a bar matching `hovered`
- * draws in `highlight` **without** the outline (a lighter "this bar is live" on
- * pointer-over); all others use the flat `fill`. `globalAlpha` carries the fill
- * opacity and is restored so it doesn't leak into later layers.
+ * draws **without** the outline (a lighter "this bar is live" on pointer-over)
+ * in the style's optional `hover` colour, or in `highlight` when the theme
+ * doesn't set one; all others use the flat `fill`. Either live state fills at
+ * **full opacity** — the resting `opacity` applies to resting bars only, and is
+ * restored so it doesn't leak into later layers. A bar that is both selected
+ * and hovered reads as **selected**.
  *
  * **Which identity.** A selection carrying a `mark` matches against the series'
  * stable per-bar name ({@link BarSeries.marks} — the sample's own axis key,
@@ -94,11 +99,12 @@ export interface BarMark {
  * (an `undefined` entry falls back to the flat `fill`). This is the
  * direction-coloured financial volume row (rising / falling) and the
  * value-band case on a time axis. Highlight follows {@link drawStacks}'s
- * binFills convention rather than the flat path's: the bar **keeps its own
- * colour** under hover / selection — the highlight pops `globalAlpha` to 1
- * (and outlines the selection in the bar's own fill) — so a red / green bar
- * stays red / green while live, instead of swapping to the single
- * `highlight` colour and losing its meaning.
+ * binFills convention: the bar **keeps its own colour** under hover /
+ * selection — the highlight pops `globalAlpha` to 1 (and outlines the
+ * selection in the bar's own fill) — so a red / green bar stays red / green
+ * while live, instead of swapping to the single `highlight` colour and losing
+ * its meaning. (Both paths now pop to 1; what still differs is the *colour* —
+ * the flat path swaps to `highlight`, this one keeps `binFills[i]`.)
  *
  * **M4 column decimation ([PND-MARKDEC]):** once the *visible* bars are denser
  * than ~2 per device pixel, they overplot into a solid silhouette, so
@@ -129,19 +135,68 @@ export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, x
  * cheap and allocation-free).
  */
 export declare function barIndexAtTime(cs: BarSeries, time: number): number;
+/**
+ * The pixel rect of bar `i`'s **slot** — the region that *belongs* to the bar,
+ * as opposed to the ink {@link barRect} puts on the canvas. It spans the key's
+ * full `[begin, end]` in x (**no `gapPx` inset**) and the **whole plot height**
+ * in y. `null` for a gap (non-finite value), which owns no slot to select.
+ *
+ * The distinction is the point: a bar *is* the full width of its interval, and
+ * the drawing gap is a display affordance so adjacent columns read as discrete.
+ * Hit-testing the drawn rect made that affordance interactive — the gap became
+ * a dead channel you could point at and select nothing, and the empty plot
+ * space above a short bar likewise. Slots tile the axis, so every x inside the
+ * data range belongs to exactly one bar, which is what a column chart's hover
+ * should feel like and what {@link barIndexAtTime} (the x-scrub cursor) has
+ * always done.
+ *
+ * The plot's y extent is read from the `yScale`'s own domain, the same
+ * localized shape {@link resolveBarBaseline} uses. When it isn't readable (a
+ * bare test stub with no `.domain()`), this falls back to {@link barRect}'s
+ * value→baseline span, so a scale-less caller keeps the old behaviour rather
+ * than getting an unbounded hit region.
+ *
+ * `minWidthPx` still floors the span, so a lone point-keyed bar (zero-width
+ * key) stays selectable.
+ *
+ * **Two consequences worth knowing before you compose with it.**
+ *
+ * 1. **It reaches across the whole plot height, so it can shadow layers below
+ *    it.** `resolveSelection` returns the topmost hit, so a `<BarChart>`
+ *    declared *after* a `<ScatterChart>` / `<BoxPlot>` / another `<BarChart>`
+ *    in the same row now claims every hit inside its x-range, at any y — where
+ *    the drawn-rect target only claimed the bar's own ink. Declare a bar layer
+ *    **below** the marks you want to stay clickable (which is also the usual
+ *    z-order for bars-as-context). No shipped story composes that way, so this
+ *    is latent rather than a live regression.
+ * 2. **Only the single-series vertical path uses it.** A stacked, `bins`,
+ *    `categories` or horizontal `<BarChart>` hit-tests through
+ *    {@link stackAt}, which still targets the drawn segment — a stack has to,
+ *    since segments share a bin's x-range and only y tells them apart. So
+ *    `<BarChart>` has two hit models; this is the one for a plain bar.
+ */
+export declare function barSlotRect(cs: BarSeries, i: number, xScale: Scale, yScale: Scale, baseline: number, minWidthPx: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
 /**
  * Hit-test plot-pixel `(px, py)` against `cs`'s bars — the **first** bar whose
- * rect contains the point, or `null`. The geometry is {@link barRect}, so the
- * hit rect is exactly the drawn rect (same `baseline`/`gapPx`/`minWidth`). The
- * returned tuple is `[index, begin, value]` for the chart to assemble a
- * `SelectInfo` (it owns the colour + label); keeping this layer free of the
- * theme keeps it unit-testable without a `ChartTheme`.
+ * **slot** contains the point, or `null`. The geometry is {@link barSlotRect}:
+ * the bar's full interval width and the full plot height, *not* the drawn rect.
+ * Pointing at the gap between two columns, or above a short one, selects the
+ * bar whose slot you are in. The returned tuple is `[index, begin, value]` for
+ * the chart to assemble a `SelectInfo` (it owns the colour + label); keeping
+ * this layer free of the theme keeps it unit-testable without a `ChartTheme`.
+ *
+ * **Shared edges.** Contiguous bars meet exactly (`end[i] === begin[i+1]`) once
+ * the gap is gone, and both ends are inclusive, so a point landing precisely on
+ * the boundary matches **the left bar** — first match wins, the same rule
+ * {@link barIndexAtTime} documents, so hover and the x-scrub cursor agree.
+ *
+ * A **gap** bar (non-finite value) owns no slot and is skipped, so hovering
+ * where the data is missing selects nothing rather than a `NaN`.
  *
  * O(N) over the events (no spatial index — bar counts are view-scale, hundreds
- * not millions; click is a rare event). Bars don't overlap in x for a sorted
- * series, so "first match" is unambiguous in practice.
+ * not millions; click is a rare event).
  */
-export declare function barAt(cs: BarSeries, px: number, py: number, xScale: Scale, yScale: Scale, baseline: number, gapPx: number, minWidthPx: number): [index: number, begin: number, value: number] | null;
+export declare function barAt(cs: BarSeries, px: number, py: number, xScale: Scale, yScale: Scale, baseline: number, minWidthPx: number): [index: number, begin: number, value: number] | null;
 /**
  * A resolved per-group stack style: `fills` aligned index-for-index to
  * {@link StackedBarSeries.groups} (segment `g` uses `fills[g]`), plus the shared

package/dist/bars.js

@@ -67,8 +67,10 @@ export function resolveBarBaseline(yScale) {
  * from {@link barSpanPx} (the key's `[begin, end]`, inset by `gapPx`, floored at
  * `minWidthPx`); the y-span runs between the value and the `baseline` pixel,
  * normalized so a value above *or* below the baseline both yield an ascending
- * rect. Shared by {@link drawBars} and {@link barAt} so the drawn rect and the
- * hit rect are the same geometry.
+ * rect. This is the **ink** — what {@link drawBars} paints. Hit-testing uses
+ * {@link barSlotRect} instead (the bar's whole slot), so the drawn rect and the
+ * hit region are deliberately *not* the same geometry: the `gapPx` inset
+ * separates columns visually without carving a dead channel out of the target.
  */
 export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
     const v = cs.y[i];
@@ -114,9 +116,12 @@ function barMatches(m, seriesId, stable, begin) {
  * no-id layer passes `undefined` and never matches — plus the bar's identity,
  * see {@link barMatches}) draws in the style's `highlight` colour **and
  * outlined**, so a click reads back on the canvas; a bar matching `hovered`
- * draws in `highlight` **without** the outline (a lighter "this bar is live" on
- * pointer-over); all others use the flat `fill`. `globalAlpha` carries the fill
- * opacity and is restored so it doesn't leak into later layers.
+ * draws **without** the outline (a lighter "this bar is live" on pointer-over)
+ * in the style's optional `hover` colour, or in `highlight` when the theme
+ * doesn't set one; all others use the flat `fill`. Either live state fills at
+ * **full opacity** — the resting `opacity` applies to resting bars only, and is
+ * restored so it doesn't leak into later layers. A bar that is both selected
+ * and hovered reads as **selected**.
  *
  * **Which identity.** A selection carrying a `mark` matches against the series'
  * stable per-bar name ({@link BarSeries.marks} — the sample's own axis key,
@@ -133,11 +138,12 @@ function barMatches(m, seriesId, stable, begin) {
  * (an `undefined` entry falls back to the flat `fill`). This is the
  * direction-coloured financial volume row (rising / falling) and the
  * value-band case on a time axis. Highlight follows {@link drawStacks}'s
- * binFills convention rather than the flat path's: the bar **keeps its own
- * colour** under hover / selection — the highlight pops `globalAlpha` to 1
- * (and outlines the selection in the bar's own fill) — so a red / green bar
- * stays red / green while live, instead of swapping to the single
- * `highlight` colour and losing its meaning.
+ * binFills convention: the bar **keeps its own colour** under hover /
+ * selection — the highlight pops `globalAlpha` to 1 (and outlines the
+ * selection in the bar's own fill) — so a red / green bar stays red / green
+ * while live, instead of swapping to the single `highlight` colour and losing
+ * its meaning. (Both paths now pop to 1; what still differs is the *colour* —
+ * the flat path swaps to `highlight`, this one keeps `binFills[i]`.)
  *
  * **M4 column decimation ([PND-MARKDEC]):** once the *visible* bars are denser
  * than ~2 per device pixel, they overplot into a solid silhouette, so
@@ -210,10 +216,10 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
         // Match by the series `id` **and** the bar's identity — its stable `mark`
         // when the selection carries one, else the sample `key` (begin) — so two
         // series sharing a timestamp don't both light up (a no-id, non-selectable
-        // layer passes `seriesId === undefined` and never matches). Both the
-        // committed selection and the transient hover use the `highlight` fill; only
-        // the selection adds the outline, so hover reads as a lighter "this bar is
-        // live" and select as the committed pick.
+        // layer passes `seriesId === undefined` and never matches). The selection
+        // takes `highlight` + the outline; the hover takes `hover` when the theme
+        // sets one and `highlight` otherwise, always without the outline — so hover
+        // reads as a lighter "this bar is live" and select as the committed pick.
         const stable = marks?.[i];
         const selected = barMatches(selection, seriesId, stable, cs.begin[i]);
         const isHovered = barMatches(hovered, seriesId, stable, cs.begin[i]);
@@ -233,17 +239,33 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
             }
             continue;
         }
-        ctx.fillStyle = selected || isHovered ? style.highlight : style.fill;
+        // A hovered / selected bar pops to full opacity, as the binFills branch
+        // above and `drawStacks` both do — without this the highlight *fill* drew
+        // at the resting `style.opacity`, so on an alpha'd theme a hovered bar
+        // (which has no outline) barely changed at all, and a selected one read
+        // only by its outline (#576).
+        ctx.globalAlpha = selected || isHovered ? 1 : style.opacity;
+        // Three-step emphasis when the theme opts in with `hover`: rest → hover →
+        // selected. Selection outranks hover on a bar that is both (as the outline
+        // already did). With no `hover` colour this is the shipped two-step —
+        // `highlight` for either state (see BarStyle.hover).
+        ctx.fillStyle = selected
+            ? style.highlight
+            : isHovered
+                ? (style.hover ?? style.highlight)
+                : style.fill;
         ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
         drawn += 1;
         if (selected) {
-            // The selected bar gets an outline so it reads at full strength over the
-            // (alpha'd) fills. Stroke at full opacity (reset within the save bracket).
-            ctx.globalAlpha = 1;
+            // The selected bar's outline. Already at alpha 1 from the fill above —
+            // which also means it no longer separates select from hover the way it
+            // used to: the stroke is `highlight` over a now-`highlight`, now-alpha-1
+            // fill, so only the half-stroke falling outside the rect reads. A theme
+            // that needs the two states clearly apart sets `BarStyle.hover` (#577);
+            // the outline is the shape cue, not the whole signal.
             ctx.lineWidth = style.outlineWidth;
             ctx.strokeStyle = style.highlight;
             ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
-            ctx.globalAlpha = style.opacity;
         }
     }
     ctx.restore();
@@ -269,21 +291,90 @@ export function barIndexAtTime(cs, time) {
     }
     return -1;
 }
+/**
+ * The pixel rect of bar `i`'s **slot** — the region that *belongs* to the bar,
+ * as opposed to the ink {@link barRect} puts on the canvas. It spans the key's
+ * full `[begin, end]` in x (**no `gapPx` inset**) and the **whole plot height**
+ * in y. `null` for a gap (non-finite value), which owns no slot to select.
+ *
+ * The distinction is the point: a bar *is* the full width of its interval, and
+ * the drawing gap is a display affordance so adjacent columns read as discrete.
+ * Hit-testing the drawn rect made that affordance interactive — the gap became
+ * a dead channel you could point at and select nothing, and the empty plot
+ * space above a short bar likewise. Slots tile the axis, so every x inside the
+ * data range belongs to exactly one bar, which is what a column chart's hover
+ * should feel like and what {@link barIndexAtTime} (the x-scrub cursor) has
+ * always done.
+ *
+ * The plot's y extent is read from the `yScale`'s own domain, the same
+ * localized shape {@link resolveBarBaseline} uses. When it isn't readable (a
+ * bare test stub with no `.domain()`), this falls back to {@link barRect}'s
+ * value→baseline span, so a scale-less caller keeps the old behaviour rather
+ * than getting an unbounded hit region.
+ *
+ * `minWidthPx` still floors the span, so a lone point-keyed bar (zero-width
+ * key) stays selectable.
+ *
+ * **Two consequences worth knowing before you compose with it.**
+ *
+ * 1. **It reaches across the whole plot height, so it can shadow layers below
+ *    it.** `resolveSelection` returns the topmost hit, so a `<BarChart>`
+ *    declared *after* a `<ScatterChart>` / `<BoxPlot>` / another `<BarChart>`
+ *    in the same row now claims every hit inside its x-range, at any y — where
+ *    the drawn-rect target only claimed the bar's own ink. Declare a bar layer
+ *    **below** the marks you want to stay clickable (which is also the usual
+ *    z-order for bars-as-context). No shipped story composes that way, so this
+ *    is latent rather than a live regression.
+ * 2. **Only the single-series vertical path uses it.** A stacked, `bins`,
+ *    `categories` or horizontal `<BarChart>` hit-tests through
+ *    {@link stackAt}, which still targets the drawn segment — a stack has to,
+ *    since segments share a bin's x-range and only y tells them apart. So
+ *    `<BarChart>` has two hit models; this is the one for a plain bar.
+ */
+export function barSlotRect(cs, i, xScale, yScale, baseline, minWidthPx) {
+    const v = cs.y[i];
+    if (!Number.isFinite(v))
+        return null;
+    // Gap-free: the slot is the key's own span.
+    const [x0, x1] = barSpanPx(cs.begin[i], cs.end[i], xScale, 0, minWidthPx);
+    const d = yScale.domain?.();
+    // `< 2`, not `=== 0`: a one-element domain would make both endpoints the same
+    // value, collapsing the slot to zero height and making the bar unhittable —
+    // worse than the fallback it was meant to skip. (`resolveBarBaseline`'s
+    // `=== 0` is fine because it clamps against min/max of the same endpoints.)
+    if (!d || d.length < 2) {
+        // No usable domain (a bare test stub): keep the drawn rect's y span.
+        const yValue = yScale(v);
+        const yBase = yScale(baseline);
+        return [x0, x1, Math.min(yValue, yBase), Math.max(yValue, yBase)];
+    }
+    const yA = yScale(d[0]);
+    const yB = yScale(d[d.length - 1]);
+    return [x0, x1, Math.min(yA, yB), Math.max(yA, yB)];
+}
 /**
  * Hit-test plot-pixel `(px, py)` against `cs`'s bars — the **first** bar whose
- * rect contains the point, or `null`. The geometry is {@link barRect}, so the
- * hit rect is exactly the drawn rect (same `baseline`/`gapPx`/`minWidth`). The
- * returned tuple is `[index, begin, value]` for the chart to assemble a
- * `SelectInfo` (it owns the colour + label); keeping this layer free of the
- * theme keeps it unit-testable without a `ChartTheme`.
+ * **slot** contains the point, or `null`. The geometry is {@link barSlotRect}:
+ * the bar's full interval width and the full plot height, *not* the drawn rect.
+ * Pointing at the gap between two columns, or above a short one, selects the
+ * bar whose slot you are in. The returned tuple is `[index, begin, value]` for
+ * the chart to assemble a `SelectInfo` (it owns the colour + label); keeping
+ * this layer free of the theme keeps it unit-testable without a `ChartTheme`.
+ *
+ * **Shared edges.** Contiguous bars meet exactly (`end[i] === begin[i+1]`) once
+ * the gap is gone, and both ends are inclusive, so a point landing precisely on
+ * the boundary matches **the left bar** — first match wins, the same rule
+ * {@link barIndexAtTime} documents, so hover and the x-scrub cursor agree.
+ *
+ * A **gap** bar (non-finite value) owns no slot and is skipped, so hovering
+ * where the data is missing selects nothing rather than a `NaN`.
  *
  * O(N) over the events (no spatial index — bar counts are view-scale, hundreds
- * not millions; click is a rare event). Bars don't overlap in x for a sorted
- * series, so "first match" is unambiguous in practice.
+ * not millions; click is a rare event).
  */
-export function barAt(cs, px, py, xScale, yScale, baseline, gapPx, minWidthPx) {
+export function barAt(cs, px, py, xScale, yScale, baseline, minWidthPx) {
     for (let i = 0; i < cs.length; i += 1) {
-        const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx);
+        const rect = barSlotRect(cs, i, xScale, yScale, baseline, minWidthPx);
         if (rect === null)
             continue;
         const [x0, x1, yTop, yBottom] = rect;

package/dist/column-names.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Schema-derived column-name types for the draw layers' column props —
+ * [PND-CHARTAPI]'s foundation.
+ *
+ * The 2026-08 API review's finding: the layers are generic over the schema,
+ * but their column props are bare `string`, so `<LineChart series={cpu}
+ * column="cpuu" />` compiles and fails at runtime — out of character for a
+ * library whose core exports `NumericColumnNameForSchema<S>`. These aliases
+ * close that gap in one place; **no prop position should reference core's
+ * helper directly.**
+ *
+ * ## Why the `never` guard is load-bearing
+ *
+ * `NumericColumnNameForSchema<SeriesSchema>` resolves to **`never`** — an
+ * unparameterized schema names no columns. Constraining a prop to it
+ * directly would therefore make `column` accept *nothing at all* for every
+ * consumer holding a loosely-typed series: a helper returning
+ * `TimeSeries<SeriesSchema>`, a React prop typed that way, or a component's
+ * own defaulted `S`. That is a large, silent breakage class — and one this
+ * repo's own suite cannot see, because its fixtures use `as const` schemas
+ * throughout (measured in `spikes/charts-type-seam/REPORT.md`, finding 5).
+ *
+ * So each alias falls back to `string` when the derived union is empty:
+ * a **narrow** schema gets precise names and a one-line error on a typo, a
+ * **loose** one keeps compiling exactly as before. The bracketed
+ * `[T] extends [never]` form is required — a bare `T extends never`
+ * distributes over unions and answers the wrong question.
+ */
+import type { NumericColumnNameForSchema, SeriesSchema, ValueColumnsForSchema, ValueSeriesSchema } from 'pond-ts';
+/**
+ * A **numeric** value column of `S` — the constraint for every prop naming a
+ * column the layer reads as a number (a line's `column`, a band's
+ * `lower`/`upper`, a box's quantiles, an OHLC price).
+ *
+ * The test is **"is the schema loose?"**, not "did it yield no numeric
+ * columns" — those are different questions with different right answers, and
+ * conflating them was a real bug. A schema that names columns but has no
+ * numeric one (all-string) should reject *every* name, because there is
+ * genuinely nothing numeric to plot; only an **unparameterized** schema, whose
+ * column names are unbounded, should fall back to `string`. `string extends
+ * AnyColumn<S>` distinguishes them: it is true only when the name union is
+ * open.
+ */
+export type NumericColumn<S extends SeriesSchema> = string extends AnyColumn<S> ? string : NumericColumnNameForSchema<S>;
+/**
+ * **Any** value column name of `S`, of any kind — the looseness probe for
+ * {@link NumericColumn}. On an unparameterized schema this is `string` (an
+ * open union), which is exactly what distinguishes "cannot check" from
+ * "checked, and nothing matches". Internal: no prop is typed with it, so it
+ * stays off the public surface until one is.
+ */
+type AnyColumn<S extends SeriesSchema> = ValueColumnsForSchema<S>[number]['name'];
+/**
+ * The `ValueSeries` sibling of {@link NumericColumn} — a different schema type
+ * family, so it needs its own derivation; the loose-schema rule is identical.
+ *
+ * **Layers do not union the two.** A prop typed `NumericColumn<S> |
+ * ValueNumericColumn<VS>` is inert: only one of the two generics is ever
+ * inferred at a call site, so the other falls back to `string` and widens the
+ * union away. Each layer's props are instead a union **per series kind**, so
+ * the names check against the schema that was actually passed. Measured in
+ * `spikes/charts-type-seam/REPORT.md`.
+ */
+export type ValueNumericColumn<VS extends ValueSeriesSchema> = string extends VS[number]['name'] ? string : NumericColumnNameForValueSchema<VS>;
+/**
+ * Names of `'number'`-kind value columns on a `ValueSeries` schema. Core
+ * exports the `TimeSeries` equivalent but not this one; derived locally
+ * rather than widening core's surface for a charts-only need.
+ */
+type NumericColumnNameForValueSchema<VS extends ValueSeriesSchema> = Extract<VS[number], {
+    readonly kind: 'number';
+}>['name'];
+export {};
+//# sourceMappingURL=column-names.d.ts.map

package/dist/column-names.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=column-names.js.map

package/dist/context.d.ts

@@ -541,6 +541,17 @@ export interface RowLayer {
      * must agree on this list (a mix is an error), the same way {@link xKind} must.
      */
     xCategories?(): readonly string[] | null;
+    /**
+     * A **horizontal** categorical source's ordered category names — the same
+     * list {@link xCategories} carries for a vertical one, but for the axis it
+     * lands on when the bars grow right: the **y** axis ([PND-HCAT]).
+     *
+     * The y axis stays a linear scale over the layer's unit slots (`[i, i+1]`),
+     * so this only supplies *labels*: a `<YAxis>` in the row with no explicit
+     * `ticks` derives one tick per category at the slot centre (`i + 0.5`).
+     * That hand-built tick list was the friction the gallery funnel documented.
+     */
+    binCategories?(): readonly string[] | null;
     /**
      * A bar/histogram layer's bar `[begin, end)` spans, as pond `Interval`s — the
      * **region cursor's snap buckets**. When present (and no `cursorSequence` is
@@ -642,6 +653,17 @@ export interface TrackerSource {
     xExtent(): readonly [number, number] | null;
     /** A `'category'` source's ordered category names (see {@link RowLayer.xCategories}). */
     xCategories?(): readonly string[] | null;
+    /**
+     * A **horizontal** categorical source's ordered category names — the same
+     * list {@link xCategories} carries for a vertical one, but for the axis it
+     * lands on when the bars grow right: the **y** axis ([PND-HCAT]).
+     *
+     * The y axis stays a linear scale over the layer's unit slots (`[i, i+1]`),
+     * so this only supplies *labels*: a `<YAxis>` in the row with no explicit
+     * `ticks` derives one tick per category at the slot centre (`i + 0.5`).
+     * That hand-built tick list was the friction the gallery funnel documented.
+     */
+    binCategories?(): readonly string[] | null;
     /** A bar/histogram source's bar `[begin, end)` spans (see {@link RowLayer.binIntervals}). */
     binIntervals?(): readonly Interval[] | null;
 }

package/dist/data.d.ts

@@ -447,6 +447,25 @@ export interface StacksFromBinsOptions {
      */
     readonly ordinal?: boolean;
 }
+/**
+ * Build a {@link BarSeries} from **`byColumn` bin records** — the single-series
+ * sibling of {@link stacksFromBins}, for a histogram drawing **one** aggregate
+ * field.
+ *
+ * Why it exists ([PND-BARSEM]): a one-column histogram *is* a single-series
+ * bar chart — same mark, same geometry — but routing it through the stacked
+ * reader made its capabilities depend on which prop produced it (whole-slot
+ * hit-testing, the hover colour, the cursor readout and per-bar decimation all
+ * live on the single path). Reading it as a `BarSeries` lets the chart decide
+ * by what it *draws* rather than by how it was fed.
+ *
+ * `column` names the aggregate field; slots are the bins' numeric
+ * `[start, end]` edges, or uniform unit slots under `{ ordinal: true }` —
+ * identical to {@link stacksFromBins}. A missing / non-finite aggregate reads
+ * as a gap (`NaN`), and each bar carries its slot index as a stable
+ * {@link BarSeries.marks} identity (bin records have no key of their own).
+ */
+export declare function barsFromBins(bins: readonly BinRecord[], column: string, options?: StacksFromBinsOptions): BarSeries;
 /**
  * Build a {@link StackedBarSeries} from **`byColumn` bin records** — the array of
  * `{ start, end, …aggregates }` a value-band aggregation returns

package/dist/data.js

@@ -535,6 +535,52 @@ export function stacksFromColumns(series, columns) {
     }
     return { begin, end, groups: columns, values, length: n };
 }
+/**
+ * Build a {@link BarSeries} from **`byColumn` bin records** — the single-series
+ * sibling of {@link stacksFromBins}, for a histogram drawing **one** aggregate
+ * field.
+ *
+ * Why it exists ([PND-BARSEM]): a one-column histogram *is* a single-series
+ * bar chart — same mark, same geometry — but routing it through the stacked
+ * reader made its capabilities depend on which prop produced it (whole-slot
+ * hit-testing, the hover colour, the cursor readout and per-bar decimation all
+ * live on the single path). Reading it as a `BarSeries` lets the chart decide
+ * by what it *draws* rather than by how it was fed.
+ *
+ * `column` names the aggregate field; slots are the bins' numeric
+ * `[start, end]` edges, or uniform unit slots under `{ ordinal: true }` —
+ * identical to {@link stacksFromBins}. A missing / non-finite aggregate reads
+ * as a gap (`NaN`), and each bar carries its slot index as a stable
+ * {@link BarSeries.marks} identity (bin records have no key of their own).
+ */
+export function barsFromBins(bins, column, options = {}) {
+    const n = bins.length;
+    const begin = new Float64Array(n);
+    const end = new Float64Array(n);
+    const y = new Float64Array(n);
+    // The bin's own **start value** is its identity — the same axis-key
+    // convention every other reader uses, and stable under `ordinal` (which only
+    // changes the drawn slot, not which bin a row is). A slot *index* would be
+    // positional and would renumber if the bin set changed. Materialized through
+    // the shared lazy getter, so a non-interactive layer never pays for the
+    // strings (see {@link BarSeries.marks}).
+    const keys = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
+        const bin = bins[i];
+        if (options.ordinal) {
+            begin[i] = i;
+            end[i] = i + 1;
+        }
+        else {
+            begin[i] = bin.start;
+            end[i] = bin.end;
+        }
+        keys[i] = bin.start;
+        const v = bin[column];
+        y[i] = typeof v === 'number' && Number.isFinite(v) ? v : NaN;
+    }
+    return withKeyMarks({ begin, end, y, length: n }, keys);
+}
 /**
  * Build a {@link StackedBarSeries} from **`byColumn` bin records** — the array of
  * `{ start, end, …aggregates }` a value-band aggregation returns

package/dist/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';