@pond-ts/charts 0.53.1 → 0.55.0

package/dist/AreaChart.d.ts

@@ -1,22 +1,10 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import type { DecimateOption } from './decimate.js';
 import { type Curve } from './curve.js';
 import { type GapMode } from './gaps.js';
-export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
-    /**
-     * The source series. A `TimeSeries` fills against the time axis; a
-     * `ValueSeries` (`series.byValue('dist')`) against its value axis — the
-     * container infers which from the data, no axis-type prop (mirrors
-     * `<LineChart>`). Either way `column` names the numeric value to fill from.
-     *
-     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
-     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
-     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
-     */
-    series: TimeSeries<S> | ValueSeries<VS>;
-    /** Name of the numeric value column to fill from. */
-    column: string;
+export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The series' semantic identifier — what the data _is_ / how it should read
      * (e.g. `elevation`, or a signed-traffic role like `in` / `out`). The theme
@@ -88,6 +76,32 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      */
     index?: number;
 }
+/**
+ * AreaChart'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 AreaChartSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = {
+    /**
+     * The source series. **Live charts:** `series.byValue(…)` mints a
+     * *fresh* projection each call, so an inline `series={s.byValue('d')}`
+     * re-registers this layer every render — on a frequently re-rendering
+     * (e.g. scrub-driven) chart, memoize the projection (`useMemo`) so the
+     * layer isn't rebuilt each frame.
+     */
+    series: TimeSeries<S>;
+    column: NumericColumn<S>;
+    readout?: NumericColumn<S>;
+} | {
+    series: ValueSeries<VS>;
+    column: ValueNumericColumn<VS>;
+    readout?: ValueNumericColumn<VS>;
+};
+/** `<AreaChart>`'s props: the shared knobs plus one series-kind source shape. */
+export type AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = AreaChartCommon<S, VS> & AreaChartSource<S, VS>;
 /**
  * An area draw layer: fills between a value `column` and a `baseline`, with a
  * graded (gradient) shade — opaque at the line, transparent at the baseline —
@@ -108,5 +122,6 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * </Layers>
  * ```
  */
-export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
+export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
+export {};
 //# sourceMappingURL=AreaChart.d.ts.map

package/dist/AreaChart.js

@@ -1,6 +1,6 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { ValueSeries } from 'pond-ts';
-import { fromTimeSeries, fromValueSeries } from './data.js';
+import { assertNumericColumn, fromTimeSeries, fromValueSeries, } from './data.js';
 import { areaExtent, drawArea } from './area.js';
 import { resolveCurve } from './curve.js';
 import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
@@ -36,7 +36,7 @@ function domainFloor(yScale) {
  * </Layers>
  * ```
  */
-export function AreaChart({ series, column, as: semantic, axis, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, legend, index = 0, }) {
+export function AreaChart({ series, column, readout, as: semantic, axis, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<AreaChart> must be rendered inside a <ChartContainer>');
@@ -48,6 +48,22 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
     const cs = useMemo(() => series instanceof ValueSeries
         ? fromValueSeries(series, column)
         : fromTimeSeries(series, column), [series, column]);
+    // Readout column values for a value-axis series (time path reads it off the
+    // event) — the tracker reports it alongside the plotted fill so an off-chart
+    // readout can show a source value. See AreaChartProps.readout.
+    //
+    // The time path buffers nothing (it has an event, not an index), so it
+    // validates the name here instead, so a mistyped `readout` fails the same way
+    // on both axis kinds rather than throwing on one and silently doing nothing
+    // on the other. Mirrors `<LineChart>`.
+    const readoutY = useMemo(() => {
+        if (readout === undefined)
+            return undefined;
+        if (series instanceof ValueSeries)
+            return fromValueSeries(series, readout).y;
+        assertNumericColumn(series, readout);
+        return undefined;
+    }, [series, readout]);
     // Styling: semantic identifier → theme area style. The single styling channel.
     const { area } = container.theme;
     const style = (semantic !== undefined ? area[semantic] : undefined) ?? area.default;
@@ -77,8 +93,19 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
                     if (i < 0)
                         return [];
                     const v = cs.y[i];
+                    const rv = readoutY?.[i];
                     return Number.isFinite(v)
-                        ? [{ x: cs.x[i], value: v, color: style.color, label }]
+                        ? [
+                            {
+                                x: cs.x[i],
+                                value: v,
+                                color: style.color,
+                                label,
+                                ...(rv !== undefined && Number.isFinite(rv)
+                                    ? { readout: rv }
+                                    : {}),
+                            },
+                        ]
                         : [];
                 }
                 const e = series.nearest(x);
@@ -87,11 +114,23 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
                 // get() wants a literal key; column is a runtime string. Cast the
                 // *event* (not the method — that would detach `this`) to a
                 // string-keyed get; runtime-safe read + guard.
-                const v = e.get(column);
+                const ev = e;
+                const v = ev.get(column);
+                const rv = readout !== undefined ? ev.get(readout) : undefined;
                 // The readout dot rides the value line (not the baseline), coloured by
                 // the outline stroke. A gap yields no readout (like the fill).
                 return typeof v === 'number' && Number.isFinite(v)
-                    ? [{ x: e.begin(), value: v, color: style.color, label }]
+                    ? [
+                        {
+                            x: e.begin(),
+                            value: v,
+                            color: style.color,
+                            label,
+                            ...(typeof rv === 'number' && Number.isFinite(rv)
+                                ? { readout: rv }
+                                : {}),
+                        },
+                    ]
                     : [];
             },
             draw: (ctx, xScale, yScale) => drawArea(ctx, cs, xScale, yScale, style, 
@@ -106,6 +145,8 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
         cs,
         series,
         column,
+        readout,
+        readoutY,
         style,
         label,
         baseline,

package/dist/BandChart.d.ts

@@ -1,24 +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 Curve } from './curve.js';
 import type { DecimateOption } from './decimate.js';
-export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
-    /**
-     * The source series. A `TimeSeries` fills the envelope against the time axis;
-     * a `ValueSeries` (`series.byValue('dist')`) against its value axis — the
-     * container infers which from the data, no axis-type prop (mirrors
-     * `<LineChart>` / `<AreaChart>`). Either way `lower`/`upper` name the numeric
-     * edge columns.
-     *
-     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
-     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
-     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
-     */
-    series: TimeSeries<S> | ValueSeries<VS>;
-    /** Name of the numeric column for the band's lower edge (e.g. `p25`). */
-    lower: string;
-    /** Name of the numeric column for the band's upper edge (e.g. `p75`). */
-    upper: string;
+export interface BandChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The band's semantic identifier — what the spread _is_ (e.g. `outer` for a
      * p5/p95 envelope, `inner` for p25/p75). The theme maps it to a
@@ -64,6 +49,32 @@ export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      */
     index?: number;
 }
+/**
+ * BandChart'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 BandChartSource<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: NumericColumn<S>;
+    upper: NumericColumn<S>;
+} | {
+    series: ValueSeries<VS>;
+    lower: ValueNumericColumn<VS>;
+    upper: ValueNumericColumn<VS>;
+};
+/** `<BandChart>`'s props: the shared knobs plus one series-kind source shape. */
+export type BandChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = BandChartCommon<S, VS> & BandChartSource<S, VS>;
 /**
  * A variance-band draw layer: fills the envelope between the `lower` and `upper`
  * columns of `series` (typically `rollingByColumn` percentiles), gap-aware, and
@@ -82,4 +93,5 @@ export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * ```
  */
 export declare function BandChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, upper, as: semantic, axis, curve, decimate, legend, index, }: BandChartProps<S, VS>): null;
+export {};
 //# sourceMappingURL=BandChart.d.ts.map

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
@@ -68,14 +99,21 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      */
     colors?: Readonly<Record<string, string>>;
     /**
-     * **Per-bin** colours for a single-series band chart — `binColors[i]` fills
-     * bar `i` (aligned to the bins / bands in order), overriding the `as`/theme
-     * fill. This is the way to colour heart-rate / power **zones** or value bands
-     * each their own colour (the `colors` map above is per-**group**, for stacks).
-     * An `undefined`/short entry falls back to the theme fill. Meant for a
-     * single-series chart (`column` + `bins`, or a horizontal single series); on a
+     * **Per-bar** colours for a single-series chart — `binColors[i]` fills bar
+     * `i` (aligned to the bars / bins in order), overriding the `as`/theme fill.
+     * This is the way to colour heart-rate / power **zones** or value bands each
+     * their own colour, and the **direction-coloured financial volume row** — a
+     * time-axis `series` derives `binColors` from its own data (rising / falling
+     * off open vs close) so volume bars read green / red under the candles (the
+     * `colors` map above is per-**group**, for stacks). An `undefined`/short
+     * entry falls back to the theme fill. Works on any **single-series** shape —
+     * a time / value `series` (vertical or horizontal) or `bins`; on a
      * multi-group stack it would tint every segment of a bin alike, so it's not
-     * the tool there.
+     * the tool there. A per-bar-coloured bar keeps its own colour under hover /
+     * selection (the highlight pops opacity instead of swapping the fill), and
+     * the hover / click readout reports the bar's own colour. **Disables the
+     * dense-bar envelope decimation** (see `decimate`) — an envelope rect can't
+     * carry many bars' colours, so every visible bar draws.
      */
     binColors?: readonly (string | undefined)[];
     /**
@@ -84,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
@@ -130,7 +171,9 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      * at that density (a perf knob, not a style); interaction still reads the source
      * bars. Pass `false` to always draw every bar, or `{ threshold }` to tune the
      * samples-per-pixel factor. **No-op for a stacked / multi-group histogram** (the
-     * categorical case is low-count; only the single-series path decimates).
+     * categorical case is low-count; only the single-series path decimates) — and
+     * **no-op when `binColors` is set** (an envelope rect would repaint its bars
+     * one flat colour; a per-bar-coloured layer draws every visible bar).
      */
     decimate?: DecimateOption;
     /**
@@ -150,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
@@ -194,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.
@@ -244,7 +293,9 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                             {
                                 x: (bs.begin[i] + bs.end[i]) / 2,
                                 value: v,
-                                color: singleStyle.fill,
+                                // A per-bar colour wins over the flat fill, so the readout
+                                // pill reads the bar's own colour (as the stacked path does).
+                                color: binColors?.[i] ?? singleStyle.fill,
                                 label,
                             },
                         ];
@@ -254,20 +305,33 @@ 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 [, begin, value] = hit;
+                                const [bi, begin, value] = hit;
+                                // The bar's stable `mark` (its own axis key) rides the
+                                // selection, so the highlight match and a controlled echo key
+                                // on the *sample* rather than on the `begin` edge — which on a
+                                // point-keyed series is derived geometry, not the sample's key
+                                // (see BarSeries.marks). `bi` is the exact bar index from the
+                                // hit, as the stacked path uses it.
+                                const stableMark = bs.marks?.[bi];
                                 return {
                                     id,
                                     key: begin,
                                     value,
-                                    color: singleStyle.fill,
+                                    // The bar's own colour when per-bar coloured (stacked-path
+                                    // parity: the readout pill matches the pixels).
+                                    color: binColors?.[bi] ?? singleStyle.fill,
                                     label,
+                                    ...(stableMark !== undefined ? { mark: stableMark } : {}),
                                 };
                             },
                         }),
-                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate),
+                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors),
                 },
                 axisId: axis,
                 index,
@@ -290,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).
@@ -335,6 +404,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         orientation,
         singleStyle,
         stackStyle,
+        binColors,
         label,
         id,
         gapPx,