@pond-ts/charts 0.56.2 → 0.57.0

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 under a single `v*` tag, so this file covers them all. Pre-1.0: minor bumps may
 include new features and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.56.2...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.57.0...HEAD
+[0.57.0]: https://github.com/pond-ts/pond/compare/v0.56.2...v0.57.0
 [0.56.2]: https://github.com/pond-ts/pond/compare/v0.56.1...v0.56.2
 [0.56.1]: https://github.com/pond-ts/pond/compare/v0.56.0...v0.56.1
 [0.56.0]: https://github.com/pond-ts/pond/compare/v0.55.0...v0.56.0
@@ -59,6 +60,153 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.57.0] — 2026-08-07
+
+### Added
+
+- **charts: `<Zone>` — a shaded y-span annotation.** The fourth annotation
+  mark, and the value-axis counterpart of `<Region>`: a band between two y
+  values, spanning the full plot width. The mark for a **classification of the
+  value axis** — US EPA AQI categories, heart-rate / power zones, SLO bands,
+  control-chart spec limits — where a reading only means something read against
+  a scale.
+
+  ```tsx
+  {
+    AQI_CATEGORIES.map((c) => (
+      <Zone key={c.role} from={c.from} to={c.to} axis="aqi" role={c.role} />
+    ));
+  }
+  ```
+
+  Colour comes from `theme.annotation.roles[role]`, so a zone _set_ styles as
+  one palette in the theme rather than N colours at the call site. Bounds are
+  order-free, clamped to the plot (a band past the axis domain is cut, one
+  fully outside culls), and accept `±Infinity` for genuinely open-ended bands
+  (`to={Infinity}` — AQI's "Hazardous", a `ZoneTime.openEnded` zone), so a
+  whole category table can be rendered and the axis decides what shows.
+
+  Three defaults deliberately **invert** the rest of the annotation family,
+  because a zone spans the full width and a set tiles the row:
+  `selectable={false}` (else every mousemove lights a band and its hit area
+  eats the plot's clicks), `edges={false}` (contiguous sets share every
+  interior boundary — edges-on draws each twice), and no auto-label (the bounds
+  are already legible on the y axis; the useful label is a name). `<Zone>` has
+  no `onChange` — drag-to-edit zones await a consumer.
+
+  Guide: [From a CSV to a banded chart](https://pond-ts.org/docs/how-to-guides/air-quality-bands).
+
+- **charts: `annotation.dash` — an optional dash pattern for the annotation
+  register**, per-register or per-role (`{ color, fillOpacity?, dash? }`), same
+  shape as `LineStyle.dash`. Applies to marker / baseline lines and region /
+  zone boundaries; fills are never dashed. A dashed reference line reads as
+  _placed_ rather than _measured_ — the job the annotation register exists to
+  do, and one colour alone can't always carry.
+
+- **charts: threshold-banded bars** — `<BarChart thresholds={[1, 2]}>` colours
+  one bar **along its length** against a ladder (neutral → warning → alarm), so
+  a long bar shows how far through the ladder it travelled rather than only
+  which band it ended in. Band fills come from the new
+  **`BarStyle.bands`** on the resolved theme role, overridable per chart with
+  **`<BarChart bandColors>`** — breakpoints are data, colour stays in the theme,
+  the same split `colors` already applies to a stack's group fills.
+
+  The shape was previously expressible as N `<BarChart>` layers drawn
+  outermost-first, each clipped to a band, compositing the gradient by
+  overpainting. That produces the same pixels and loses what matters: N layers
+  means N hit targets, N `SelectInfo.mark` identities and N legend rows for
+  something the reader sees as one bar. Banding is **draw-only** — the hit rect
+  is untouched, so a banded bar stays one bar. It also measures **27–49%
+  cheaper** than the layered workaround at 8–400 categories
+  (`scripts/perf-bandbar.mjs`, which interleaves the arms and prints the
+  ratios), and costs nothing when unused.
+
+  Applies to any single-value bar — `series`, `bins`, `categories`, both
+  orientations. Negatives band symmetrically on the magnitude, so a ± diverging
+  scale needs no negative breakpoints. Ignored (with a dev warning) on a
+  multi-group stack, and yields to `binColors` when both are set. Suppresses
+  envelope decimation for the same reason `binColors` does.
+
+- **charts: `<YAxis hide>`** — keep the scale, draw no gutter, reserve no
+  width. A `<YAxis>` does two jobs — it _holds the scale_ (`min`/`max`/`scale`/
+  `pad`) and it _renders a gutter_ — and there was no way to ask for the first
+  without the second. A caller could express "auto domain, no gutter" (omit the
+  axis) or "explicit domain, with a gutter", but not the pairing a fixed-domain
+  chart needs. Omitting the axis is not equivalent: the row supplies an implicit
+  auto-domain axis, which is exactly what must not be given up. `width={0}`
+  isn't either — the labels still draw, over the plot.
+
+  Gridlines are unaffected: they belong to the plot, not the gutter, and
+  `<ChartContainer grid>` already governs them.
+
+- **charts: `<ChartContainer maxBandWidth>` + `bandAlign`** — cap the **slot
+  pitch** on a category x axis and place the resulting block
+  (`'start'` (default) / `'center'` / `'end'`). A band scale otherwise spreads
+  its categories across the full plot width, so three categories in a 900px
+  panel become three 300px bars and thirty become thirty 30px ones — the same
+  chart in the same panel reading as two different charts depending on how many
+  categories the data returned. Fine for a fixed domain; wrong for a **live**
+  one, where bar width becomes a variable that moves on its own and a reader
+  can't compare the chart to itself a minute ago.
+
+  `maxBandWidth` caps the **slot**; `<BarChart gap>` still insets the bar
+  within it — one knob for pitch, one for ink. Omitting `maxBandWidth` is the
+  previous fill behaviour exactly, and a cap too loose to bind degrades back to
+  it rather than clipping. There is deliberately no `bandAlign: 'fill'`: "fill"
+  is what omitting the cap means, and a `fill` alongside a pitch cap would be a
+  contradiction rather than a choice.
+
+  **Vertical / x-axis categories only** — a `orientation="horizontal"`
+  categorical chart puts its categories on the y axis as unit slots, a
+  different mechanism this does not cap.
+
+- **charts: themed emphasis on the category path** — `BarStyle.hover` /
+  `.highlight` now apply to `categories` and horizontal bars, which routed
+  through the transposed stacked draw path and read neither. New
+  `BarStyle.selectedOutline` (the selected bar's stroke, where the default is
+  its own fill) and `BarStyle.emphasisOpacity` (the alpha a live bar pops to,
+  previously hard-coded `1`) make the emphasis tunable rather than fixed.
+
+  The _behaviour_ was defensible; the problem was that the theme accepted
+  values it would not use. `bar.hover` / `.highlight` were typed, settable and
+  documented as the emphasis channel, and silently did nothing on the most
+  common categorical chart, so a theme author set them, saw no change, and
+  could not tell whether they were wrong about the colour or the mechanism.
+  The one genuine exclusion stays and is now the only one: a `binColors` bar
+  keeps its own colour under hover/selection, because swapping a
+  zone-coloured or direction-coloured bar to a single highlight hue erases
+  what the colour encodes.
+
+### Fixed
+
+- **charts: a negative segment in a multi-group stack is no longer silently
+  dropped** ([PND-SIGNSTACK]). Positives stack **up** from the baseline and
+  negatives stack **down** from it — two running totals per bin — so the
+  **signed stacked histogram** (net flow by category, inflow/outflow, buy/sell
+  pressure by venue) renders correctly. `stackValueExtent` grew the matching
+  negative half; both had to move together, since an extent stopping at `0`
+  would clip the segments the draw path now emits.
+
+  **This is a visible behaviour change** for any existing chart feeding
+  negative values into a multi-group stack — but such a chart was previously
+  rendering _wrongly_: the dropped segments did not clamp, warn or throw, every
+  remaining segment stacked up as though they had never been in the data, and a
+  mixed-sign series came out as a confident, wrong, all-positive chart. An
+  all-positive stack is bit-identical to before. Splitting into two layers was
+  not a workaround either — the negative layer was still `G > 1`, so it was
+  dropped too.
+
+### Changed
+
+- **charts (docs): `<BarChart bins>` now states that it selects a _value_
+  axis** ([PND-TICKUNIT]), so a time-bucketed histogram fed through `bins` gets
+  the decimal 1-2-5 tick ladder rather than the duration ladder a clock
+  subdivides by — labelling e.g. 11:40 and 13:20 at a ~100-minute step. The
+  natural reading ("I have pre-binned buckets, so I'll pass `bins`") is exactly
+  what forecloses the time axis, and nothing at the call site said so. The prop
+  docs now point a time-keyed caller at `<BarChart series columns>`, where the
+  clock ticks are native. No behaviour change.
+
 ## [0.56.2] — 2026-08-05
 
 ### Fixed

package/dist/BarChart.d.ts

@@ -26,6 +26,22 @@ import type { DecimateOption } from './decimate.js';
  *   (`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.
+ *
+ *   **`bins` selects a *value* axis, so a time-bucketed histogram fed this way
+ *   gets decimal ticks** ([PND-TICKUNIT]). A `TimeSeries`/`Map` bins on time; a
+ *   `ValueSeries`/`bins`-array bins on a value axis — which means the tick
+ *   ladder is the plain 1-2-5 walk, not the **duration** ladder a clock
+ *   subdivides by (15s and 30s are round durations where 20s and 50s are not).
+ *   A minute-of-day histogram passed as `bins` therefore labels something like
+ *   11:40 and 13:20 — real times at a ~100-minute step — and nothing at the
+ *   call site says why.
+ *
+ *   The natural reading ("I have pre-binned buckets, so I'll pass `bins`") is
+ *   exactly what forecloses the time axis. For a **time-keyed** histogram use
+ *   the series door instead — `<BarChart series columns>` on a time-keyed wide
+ *   series — and the clock ticks are native with no workaround.
+ *   `<ChartContainer origin>` does not rescue it: it relabels a value axis but
+ *   does not re-ladder it.
  * - **`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
@@ -116,6 +132,58 @@ export interface BarChartCommon<S extends SeriesSchema = SeriesSchema, VS extend
      * carry many bars' colours, so every visible bar draws.
      */
     binColors?: readonly (string | undefined)[];
+    /**
+     * **Threshold breakpoints** — colour each bar *along its length* against a
+     * ladder, so a long bar shows how far through the ladder it travelled rather
+     * than only which band it ended in. Breakpoints are **absolute data values**
+     * in the axis's own units — `[1, 2]` means "warning above 1, alarm above 2",
+     * not offsets from wherever the bar happens to rest — and `n` of them make
+     * `n + 1` bands. Each must be finite and greater than zero; anything else is
+     * dropped with a dev warning (the ladder is walked on the magnitude, so a
+     * negative breakpoint is not expressible).
+     *
+     * ```tsx
+     * // neutral to 1, warning 1–2, alarm above 2
+     * <BarChart categories={cats} thresholds={[1, 2]} />
+     * ```
+     *
+     * Band fills come from {@link BarStyle.bands} on the resolved role
+     * (`theme.bar[as] ?? theme.bar.default`), overridden by {@link bandColors}.
+     * Breakpoints are data and live here; colour stays in the theme — the same
+     * split as `colors` over the stack's group fills.
+     *
+     * **A banded bar is still one bar.** It keeps one hit region, one stable
+     * `SelectInfo.mark` and one legend row — which is the whole difference from
+     * the N-overlaid-layers recipe this replaces, where each band was separately
+     * hittable and separately listed. Selection and hover pop the opacity and
+     * keep the band colours (as `binColors` does), outlining in the colour of the
+     * band the value actually reached.
+     *
+     * **Negatives band symmetrically**: the ladder is walked on the magnitude and
+     * re-signed, so a bar hanging below the baseline reads the same ±ladder
+     * without negative breakpoints. Out-of-order entries are sorted (the bands
+     * are defined by their boundaries, so there is no second reading) and
+     * non-finite ones dropped.
+     *
+     * Applies to any **single-value** bar — a `series`/`bins` chart, `categories`,
+     * and both orientations. On a genuine **multi-group stack** it is ignored
+     * with a dev warning: a segment that is already one slice of a total has no
+     * defined banding. Set with `binColors` it also yields (per-bar colour is the
+     * more specific answer) and warns. **Disables envelope decimation** for the
+     * same reason `binColors` does.
+     */
+    thresholds?: readonly number[];
+    /**
+     * Call-site override for the {@link thresholds} band fills — `bandColors[k]`
+     * paints the band above `thresholds[k - 1]`, so a ladder of `n` thresholds
+     * reads `n + 1` entries. Omitted ⇒ {@link BarStyle.bands} from the theme.
+     *
+     * Prefer the theme for anything a design system owns; this is the escape
+     * hatch for a one-off ladder that shouldn't mint a theme role. If neither
+     * source supplies enough entries, the shortfall falls back to the flat fill
+     * and dev-warns rather than silently drawing an unbanded bar.
+     */
+    bandColors?: readonly string[];
     /**
      * Bar growth direction (the histogram orientation). **Default `'vertical'`.**
      *
@@ -220,14 +288,21 @@ export type BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends Valu
  * domain spans zero, or on the axis floor when an explicit `<YAxis min>` sits
  * above zero (see {@link resolveBarBaseline}).
  *
- * **Baseline (stacked).** A stack is **cumulative from value 0** — the segments
- * sum upward from the zero line, so its value axis **must include 0**. The
- * auto-fit guarantees this: {@link stackValueExtent} always returns `[0, maxTotal]`.
- * An explicit `<YAxis min>` **above** 0 is therefore unsupported for a stack — it
- * would hide the bottom of the cumulative column; only the portion above the floor
- * draws (clipped cleanly at the plot floor, as any bar below an explicit floor is).
- * Segment values are assumed **non-negative** (a negative or zero segment is
- * skipped — diverging stacks are out of scope).
+ * **Baseline (stacked).** A stack is **cumulative from value 0** — so its value
+ * axis **must include 0**. The auto-fit guarantees this:
+ * {@link stackValueExtent} returns `[minNegativeTotal, maxPositiveTotal]`, both
+ * seeded at `0`. An explicit `<YAxis min>` **above** 0 is therefore unsupported
+ * for a stack — it would hide the bottom of the cumulative column; only the
+ * portion above the floor draws (clipped cleanly at the plot floor, as any bar
+ * below an explicit floor is).
+ *
+ * **Signed stacks are supported** ([PND-SIGNSTACK]): each bin keeps two running
+ * totals, so positive segments stack **up** from the zero line and negative
+ * ones stack **down** from it — the signed histogram (net flow by category,
+ * inflow/outflow, buy/sell pressure by venue). A **zero** segment is still
+ * skipped, having no extent to draw or hit-test. This changed in the
+ * threshold-banding wave: negative segments were previously dropped outright
+ * and silently, so a mixed-sign series rendered as an all-positive chart.
  *
  * **Interaction (opt-in via `id`).** Hover lights the bar / segment under the
  * cursor (hit-tested by pixel rect, so it works in both orientations); click
@@ -244,6 +319,6 @@ export type BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends Valu
  * </Layers>
  * ```
  */
-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 declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation, ordinal, id, axis, gap, decimate, legend, index, }: BarChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=BarChart.d.ts.map

package/dist/BarChart.js

@@ -1,7 +1,8 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { Interval, ValueSeries } from 'pond-ts';
 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 { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, normalizeThresholds, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
+import { isDev } from './dev.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
@@ -24,14 +25,21 @@ import { useSlotKey } from './use-slot-key.js';
  * domain spans zero, or on the axis floor when an explicit `<YAxis min>` sits
  * above zero (see {@link resolveBarBaseline}).
  *
- * **Baseline (stacked).** A stack is **cumulative from value 0** — the segments
- * sum upward from the zero line, so its value axis **must include 0**. The
- * auto-fit guarantees this: {@link stackValueExtent} always returns `[0, maxTotal]`.
- * An explicit `<YAxis min>` **above** 0 is therefore unsupported for a stack — it
- * would hide the bottom of the cumulative column; only the portion above the floor
- * draws (clipped cleanly at the plot floor, as any bar below an explicit floor is).
- * Segment values are assumed **non-negative** (a negative or zero segment is
- * skipped — diverging stacks are out of scope).
+ * **Baseline (stacked).** A stack is **cumulative from value 0** — so its value
+ * axis **must include 0**. The auto-fit guarantees this:
+ * {@link stackValueExtent} returns `[minNegativeTotal, maxPositiveTotal]`, both
+ * seeded at `0`. An explicit `<YAxis min>` **above** 0 is therefore unsupported
+ * for a stack — it would hide the bottom of the cumulative column; only the
+ * portion above the floor draws (clipped cleanly at the plot floor, as any bar
+ * below an explicit floor is).
+ *
+ * **Signed stacks are supported** ([PND-SIGNSTACK]): each bin keeps two running
+ * totals, so positive segments stack **up** from the zero line and negative
+ * ones stack **down** from it — the signed histogram (net flow by category,
+ * inflow/outflow, buy/sell pressure by venue). A **zero** segment is still
+ * skipped, having no extent to draw or hit-test. This changed in the
+ * threshold-banding wave: negative segments were previously dropped outright
+ * and silently, so a mixed-sign series rendered as an all-positive chart.
  *
  * **Interaction (opt-in via `id`).** Hover lights the bar / segment under the
  * cursor (hit-tested by pixel rect, so it works in both orientations); click
@@ -48,7 +56,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation = 'vertical', ordinal = false, id, axis, gap, decimate = true, legend, index = 0, }) {
+export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation = 'vertical', ordinal = false, id, axis, gap, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BarChart> must be rendered inside a <ChartContainer>');
@@ -232,6 +240,87 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     // 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.
     const stackMinWidth = bar.default.minWidth;
+    // ── Threshold ladder ([PND-BANDBAR2]) ────────────────────────────────────
+    // Resolved once here rather than per bar per frame: normalize the breakpoints
+    // (sort, drop non-finite), then pair them with `bandColors` → the role's
+    // `BarStyle.bands`. Everything that can go wrong with the pairing is a
+    // *silent* wrong-looking chart, so each case dev-warns — this feature exists
+    // because a quietly-unbanded bar was the workaround's failure mode.
+    // Value-compare the two array props rather than relying on their identity.
+    // `thresholds={[1, 2]}` inline is the documented usage and the shape every
+    // story and doc example uses — and a fresh array each render would rebuild
+    // the ladder, hence the layer `entry` below, hence a `registerLayer` call
+    // **every render**. That is a repaint treadmill, not just a noisy warning.
+    // The same value-compare-on-registration reasoning `<YAxis ticks>` already
+    // applies.
+    const thresholdKey = thresholds === undefined ? '' : thresholds.join(',');
+    const bandColorKey = bandColors === undefined ? '' : bandColors.join(',');
+    const bandLadder = useMemo(() => {
+        const steps = normalizeThresholds(thresholds);
+        if (steps === null) {
+            if (isDev && thresholds !== undefined && thresholds.length > 0) {
+                console.warn('<BarChart thresholds>: no usable breakpoints, so no banding was ' +
+                    'applied — each must be finite and greater than zero. Bars draw ' +
+                    'in the flat fill.');
+            }
+            return undefined;
+        }
+        // Some, but not all, entries dropped. Silently banding on a subset of what
+        // the caller wrote is exactly the class of quiet wrongness this feature is
+        // meant to remove, so say so.
+        if (isDev && thresholds !== undefined && steps.length < thresholds.length) {
+            console.warn(`<BarChart thresholds>: dropped ${thresholds.length - steps.length} ` +
+                'breakpoint(s) that were not finite and greater than zero. The ' +
+                'ladder is walked on the magnitude and mirrored onto whichever side ' +
+                'of zero a bar is on, so a negative breakpoint has no meaning; ' +
+                `banding on [${steps.join(', ')}].`);
+        }
+        const want = steps.length + 1;
+        const supplied = bandColors ?? singleStyle.bands;
+        if (supplied === undefined || supplied.length === 0) {
+            if (isDev) {
+                console.warn(`<BarChart thresholds>: ${steps.length} breakpoint(s) need ${want} ` +
+                    'band colours, but neither `bandColors` nor the theme role’s ' +
+                    '`BarStyle.bands` supplies any. Bars draw in the flat fill.');
+            }
+            return undefined;
+        }
+        if (supplied.length < want && isDev) {
+            console.warn(`<BarChart thresholds>: ${steps.length} breakpoint(s) need ${want} ` +
+                `band colours but only ${supplied.length} were supplied; bands ` +
+                'above the last colour fall back to the flat fill.');
+        }
+        // Pad a short ladder with the flat fill so the draw path can index freely.
+        const resolved = supplied.length >= want
+            ? supplied.slice(0, want)
+            : [
+                ...supplied,
+                ...Array.from({ length: want - supplied.length }, () => singleStyle.fill),
+            ];
+        return { thresholds: steps, colors: resolved };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- `thresholdKey` /
+        // `bandColorKey` are the value-compared stand-ins for the array props.
+    }, [thresholdKey, bandColorKey, singleStyle]);
+    // Conflicts between the ladder and the shapes it can't apply to. In an effect
+    // so a re-render doesn't re-log; each fires once per genuinely new pairing.
+    const multiGroup = shape.kind === 'stacked' && shape.ss.groups.length > 1;
+    const hasLadder = bandLadder !== undefined;
+    const hasBinColors = binColors !== undefined;
+    useEffect(() => {
+        if (!isDev || !hasLadder)
+            return;
+        if (hasBinColors) {
+            console.warn('<BarChart>: `thresholds` and `binColors` are both set. They are two ' +
+                'answers to “what colour is this bar”; `binColors` wins as the more ' +
+                'specific one, and the threshold bands are ignored.');
+        }
+        if (multiGroup) {
+            console.warn('<BarChart>: `thresholds` is ignored on a multi-group stack — a ' +
+                'segment that is already one slice of a total has no defined ' +
+                'banding. Threshold bands apply to single-value bars (`series` / ' +
+                '`bins` / `categories`), in either orientation.');
+        }
+    }, [hasLadder, hasBinColors, multiGroup]);
     // Stacked style: per-group fills (colors override → theme role → default),
     // plus the shared opacity / outline from the default bar style. Memoized on the
     // groups + colours so a selection change doesn't rebuild it.
@@ -243,6 +332,17 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
             fills,
             opacity: base.opacity,
             outlineWidth: base.outlineWidth,
+            // [PND-CATEMPH] Forward the themed emphasis so the category / horizontal
+            // path can read the same `fill → hover → highlight` channel every other
+            // bar does, instead of accepting those theme values and ignoring them.
+            highlight: base.highlight,
+            ...(base.hover !== undefined ? { hover: base.hover } : {}),
+            ...(base.selectedOutline !== undefined
+                ? { selectedOutline: base.selectedOutline }
+                : {}),
+            ...(base.emphasisOpacity !== undefined
+                ? { emphasisOpacity: base.emphasisOpacity }
+                : {}),
             ...(binColors !== undefined ? { binFills: binColors } : {}),
         };
     }, [bar, groups, colors, binColors]);
@@ -331,7 +431,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                                 };
                             },
                         }),
-                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors),
+                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors, bandLadder),
                 },
                 axisId: axis,
                 index,
@@ -391,7 +491,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                             };
                         },
                     }),
-                draw: (ctx, xScale, yScale) => drawStacks(ctx, ss, orientation, xScale, yScale, stackStyle, gapPx, stackMinWidth, id, selection, hover),
+                draw: (ctx, xScale, yScale) => drawStacks(ctx, ss, orientation, xScale, yScale, stackStyle, gapPx, stackMinWidth, id, selection, hover, bandLadder),
             },
             axisId: axis,
             index,
@@ -405,6 +505,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         singleStyle,
         stackStyle,
         binColors,
+        bandLadder,
         label,
         id,
         gapPx,

package/dist/ChartContainer.d.ts

@@ -14,6 +14,49 @@ export interface ChartContainerProps {
      * the data — so a tuple stays a time domain on a time chart.
      */
     range?: readonly [number, number] | TimeRange;
+    /**
+     * **Cap the slot pitch** on a **category** x axis, in CSS pixels
+     * ([PND-BANDPACK]). A band scale otherwise spreads its categories across the
+     * full plot width, so three categories in a 900px panel become three 300px
+     * bars and thirty become thirty 30px ones — the same chart in the same panel
+     * reading as two different charts depending on how many categories the data
+     * happened to return.
+     *
+     * That is fine for a static chart with a known domain and wrong for a **live**
+     * one: when the category count moves over a session, bar width becomes a
+     * meaningless variable that moves on its own, and a reader can't compare the
+     * chart to what it looked like a minute ago or to the same chart on another
+     * screen. Capping the pitch keeps bar width constant and comparable, and the
+     * empty space left over is itself information — it shows the set is small.
+     *
+     * Omitted ⇒ slots fill the plot (unchanged). When `n × maxBandWidth` exceeds
+     * the plot, the cap can't bind and the slots fill as before, so this degrades
+     * correctly as categories accumulate. Use {@link bandAlign} to say where the
+     * capped block sits.
+     *
+     * **This caps the slot, not the bar.** `<BarChart gap>` still insets the bar
+     * within its slot, and the two compose — one knob for pitch, one for ink,
+     * neither doing the other's job. (Inverting `gap` against a measured plot
+     * width was the workaround this replaces for the width half; the packing half
+     * had no workaround at all.)
+     *
+     * **Vertical / x-axis categories only.** A `orientation="horizontal"`
+     * categorical chart puts its categories on the **y** axis as unit slots,
+     * which is a different mechanism and is not capped by this.
+     */
+    maxBandWidth?: number;
+    /**
+     * Where the capped category block sits in the plot when {@link maxBandWidth}
+     * binds. **Default `'start'`** — pack from the left, leaving the far side
+     * empty. `'center'` and `'end'` place it otherwise.
+     *
+     * A no-op without `maxBandWidth`, or when the cap doesn't bind: the block
+     * fills the plot and there is no slack to place. (There is deliberately no
+     * `'fill'` member — "fill" is what *omitting* `maxBandWidth` means, and a
+     * `fill` value alongside a pitch cap would be a contradiction rather than a
+     * choice.)
+     */
+    bandAlign?: 'start' | 'center' | 'end';
     /**
      * A **trading-calendar** discontinuity provider — closed-market time
      * (weekends, holidays, overnight, lunch breaks) collapsed. Supply it to turn
@@ -419,5 +462,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom, bounds, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, maxBandWidth, bandAlign, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom, bounds, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map

package/dist/ChartContainer.js

@@ -45,7 +45,7 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
+export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
     // Normalize the `panZoom` mode (boolean shorthand or the three-way string)
     // into the two gesture flags the event surface reads. `true` ⇒ both; `'pan'`
     // ⇒ drag only; `false`/`'none'` ⇒ neither. Zoom implies pan (there is no
@@ -414,7 +414,21 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             // reads by **name** — `cursorFormat` has nothing to format, so the
             // readout channel stays unset.
             const cats = categories ?? [];
-            const s = scaleBand(cats).domain([0, cats.length]).range([0, plotWidth]);
+            // [PND-BANDPACK] Cap the slot pitch, then place the resulting block. With
+            // no cap (or one too loose to bind) `packed === plotWidth` and `offset`
+            // is 0, so the range is `[0, plotWidth]` exactly as before — the whole
+            // feature collapses to the shipped behaviour when unused.
+            const n = cats.length;
+            const pitch = n > 0 ? plotWidth / n : plotWidth;
+            const capped = maxBandWidth !== undefined && maxBandWidth > 0
+                ? Math.min(pitch, maxBandWidth)
+                : pitch;
+            const packed = n > 0 ? capped * n : plotWidth;
+            const slack = Math.max(0, plotWidth - packed);
+            const offset = bandAlign === 'center' ? slack / 2 : bandAlign === 'end' ? slack : 0;
+            const s = scaleBand(cats)
+                .domain([0, n])
+                .range([offset, offset + packed]);
             return {
                 xScale: s,
                 formatTime: (v) => s.label(v),
@@ -555,6 +569,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     }, [
         resolvedKind,
         categories,
+        maxBandWidth,
+        bandAlign,
         d0,
         d1,
         plotWidth,

package/dist/YAxis.d.ts

@@ -106,6 +106,33 @@ export interface YAxisProps {
     boundaryLabels?: boolean;
     /** Gutter width in CSS pixels (default 50). */
     width?: number;
+    /**
+     * **Keep the scale, draw no gutter.** The axis still registers its domain
+     * (`min`/`max`/`scale`/`pad`) and layers still bind to it by `id`, but it
+     * renders nothing and reserves **no width** — the plot gets the space.
+     *
+     * A `<YAxis>` does two jobs: it *holds the scale* and it *renders a gutter*.
+     * Without this there was no way to ask for the first without the second, so a
+     * chart with a **fixed** domain whose scale is already explained by its
+     * chrome (threshold band lines, a legend, a panel header) had two reachable
+     * options and needed a third:
+     *
+     * | | auto domain | explicit domain |
+     * |---|---|---|
+     * | **gutter** | `<YAxis />` | `<YAxis min max />` |
+     * | **no gutter** | omit the axis | ← this prop |
+     *
+     * Omitting the axis is not the same thing: the row then supplies an implicit
+     * auto-domain axis, and the fixed domain is exactly what must not be given
+     * up. `width={0}` is not it either — the labels still draw, now over the
+     * plot.
+     *
+     * **Gridlines are unaffected.** They belong to the plot, not the gutter, and
+     * `<ChartContainer grid>` already controls them — so a hidden axis can still rule
+     * its own gridlines, which is usually what a "the shape matters, the numbers
+     * don't" chart wants. Turn them off there if you want neither.
+     */
+    hide?: boolean;
     /**
      * This axis instance's colour — tick labels and the axis title take it,
      * overriding the theme's `axis.label` / `axis.title.color`. The multi-axis
@@ -128,5 +155,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, scale, min, max, format, ticks, tickCount, pad, boundaryLabels, width, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function YAxis({ id, side, label, scale, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=YAxis.d.ts.map