@pond-ts/charts 0.58.0 → 0.60.0

package/dist/range.d.ts

@@ -10,6 +10,19 @@
  * A span that the gap would invert (narrower than `minWidthPx` after the inset)
  * collapses to a `minWidthPx` mark centred in the slot, so a too-thin bucket
  * stays visible and the bar never flips inside-out.
+ *
+ * `maxWidthPx` caps the **ink** and is applied *after* the inset, centred in the
+ * slot ([PND-BARWIDTH]). It is the missing half of the width vocabulary: `gapPx`
+ * is a *relative* inset, so on its own bar width is always `slot - gap` and
+ * fattens with the slot. Two independent sizes — slots spreading to fill the
+ * plot, ink pinned to N px — is what makes a measure comparable **between**
+ * panes, since a bar that widens with its pane reads as a different weight of
+ * the same thing. Expressing that with the relative knob alone requires
+ * predicting the slot width and back-solving the gap, which re-derives this
+ * function's arithmetic in consumer code.
+ *
+ * `minWidthPx` still wins: a cap below the floor yields the floor, so the two
+ * bounds can never invert the rect.
  */
-export declare function barSpanPx(beginMs: number, endMs: number, xScale: (value: number) => number, gapPx?: number, minWidthPx?: number): [number, number];
+export declare function barSpanPx(beginMs: number, endMs: number, xScale: (value: number) => number, gapPx?: number, minWidthPx?: number, maxWidthPx?: number): [number, number];
 //# sourceMappingURL=range.d.ts.map

package/dist/range.js

@@ -10,15 +10,36 @@
  * A span that the gap would invert (narrower than `minWidthPx` after the inset)
  * collapses to a `minWidthPx` mark centred in the slot, so a too-thin bucket
  * stays visible and the bar never flips inside-out.
+ *
+ * `maxWidthPx` caps the **ink** and is applied *after* the inset, centred in the
+ * slot ([PND-BARWIDTH]). It is the missing half of the width vocabulary: `gapPx`
+ * is a *relative* inset, so on its own bar width is always `slot - gap` and
+ * fattens with the slot. Two independent sizes — slots spreading to fill the
+ * plot, ink pinned to N px — is what makes a measure comparable **between**
+ * panes, since a bar that widens with its pane reads as a different weight of
+ * the same thing. Expressing that with the relative knob alone requires
+ * predicting the slot width and back-solving the gap, which re-derives this
+ * function's arithmetic in consumer code.
+ *
+ * `minWidthPx` still wins: a cap below the floor yields the floor, so the two
+ * bounds can never invert the rect.
  */
-export function barSpanPx(beginMs, endMs, xScale, gapPx = 0, minWidthPx = 1) {
+export function barSpanPx(beginMs, endMs, xScale, gapPx = 0, minWidthPx = 1, maxWidthPx) {
     const a = xScale(beginMs);
     const b = xScale(endMs);
     const lo = Math.min(a, b);
     const hi = Math.max(a, b);
     const inset = gapPx / 2;
-    const x0 = lo + inset;
-    const x1 = hi - inset;
+    let x0 = lo + inset;
+    let x1 = hi - inset;
+    // The cap reads on the INSET span, not the raw slot, so `gap` keeps its
+    // meaning as the minimum breathing room: a bar is never wider than the gap
+    // allows, and never wider than the cap, whichever binds first.
+    if (maxWidthPx !== undefined && maxWidthPx > 0 && x1 - x0 > maxWidthPx) {
+        const mid = (lo + hi) / 2;
+        x0 = mid - maxWidthPx / 2;
+        x1 = mid + maxWidthPx / 2;
+    }
     if (x1 - x0 >= minWidthPx)
         return [x0, x1];
     const mid = (lo + hi) / 2;

package/dist/theme.d.ts

@@ -296,10 +296,14 @@ export interface ChartTheme {
      *
      * So the two values here are the ones with no canvas counterpart: the row
      * **band** tints. Everything else resolves from tokens that already exist
-     * and are per-metric where they should be — a selected fill takes
-     * {@link BarStyle.highlight}, a dimmed one {@link BarStyle.dimmed} — so a
-     * consumer who themes their bars gets a coherent list without theming it
-     * twice.
+     * and are per-metric where they should be — a selected glyph fill takes
+     * `bar[as].highlight` and a dimmed one `bar[as].dimmed` — so a consumer who
+     * themes their bars gets a coherent list without theming it twice.
+     *
+     * **To be unambiguous, because this reads as a list of fields on this
+     * block:** `highlight` / `dimmed` are **`BarStyle`** tokens, resolved through
+     * `theme.bar[as]`. They are not fields of `theme.list` and there is no
+     * `list.dimmed` — this register carries exactly the five values below.
      *
      * **The rail is deliberately NOT per-metric.** There is one rail per row
      * and a row may carry several metrics, so it cannot resolve through
@@ -716,6 +720,28 @@ export interface AreaStyle {
     /** Ink for a swept window's emphasised portion (edge + fill).
      *  **Omitted ⇒ the area keeps its own colours and only strengthens.** */
     readonly spanColor?: string;
+    /**
+     * The **threshold-band ladder** — ordered fills for an area coloured *along
+     * its height* against `<AreaChart thresholds>`: `bands[0]` up to the first
+     * threshold, `bands[1]` between the first and second, and so on. A ladder of
+     * `n` thresholds reads `n + 1` entries. The fill **and** the outline take
+     * the band hues (one hard-stop gradient in pixel space), and the grade to
+     * transparent is dropped: the fade encoded distance-from-the-baseline, which
+     * is exactly what the ladder now states discretely — two encodings of one
+     * thing would fight.
+     *
+     * Lives on `AreaStyle` for {@link BarStyle.bands}' reason: `theme.area` is a
+     * semantic **map**, so a top-level key would collide with a role of that
+     * name — and per-role is the more useful shape (`area.default.bands` and a
+     * capacity role's ladder can differ).
+     *
+     * **Overridden by `<AreaChart bandColors>`** at the call site. If neither
+     * resolves enough entries for the ladder, the shortfall falls back to the
+     * flat {@link fill} and (in dev) warns — the same contract as the bar
+     * ladder, because a silently-unbanded chart is the failure mode the feature
+     * exists to remove.
+     */
+    readonly bands?: readonly string[];
 }
 /**
  * A resolved bar style: the flat `fill` (scaled by `opacity`, 0–1) plus the
@@ -730,6 +756,28 @@ export interface BarStyle {
     readonly highlight: string;
     readonly gap: number;
     readonly minWidth: number;
+    /**
+     * Cap on a bar's **ink** width in px, applied after the `gap` inset and
+     * centred in the slot ([PND-BARWIDTH]). **Omitted ⇒ uncapped** — a bar is
+     * `slot - gap` wide, as it always was.
+     *
+     * It is the missing half of the width vocabulary, and the reason it cannot be
+     * spelled with `gap` alone: `gap` is a *relative* inset, so bar width tracks
+     * the slot and fattens as the plot widens. A **fixed** ink width is what makes
+     * a measure comparable *between* panes — bars that widen with their pane read
+     * as different weights of the same thing. Wanting both (slots spreading to
+     * fill, ink pinned) needs two independent knobs; with one, a consumer has to
+     * predict the slot width and back-solve the gap, re-deriving pond's own layout
+     * arithmetic in their code.
+     *
+     * Pairs with `<ChartContainer maxBandWidth>`, which caps the **slot**: that
+     * one decides how far the bars spread, this one how wide the ink is inside
+     * whatever slot results. `minWidth` still wins if the two would invert.
+     *
+     * `<BarChart maxBarWidth>` overrides this per layer, the same relationship
+     * `gap` has.
+     */
+    readonly maxWidth?: number;
     readonly outlineWidth: number;
     /**
      * Optional distinct **hover** fill, so a bar can read a three-step emphasis —
@@ -757,6 +805,11 @@ export interface BarStyle {
      *   both states so a red/green volume bar keeps its meaning while live —
      *   the one *design* exclusion rather than a path consequence.
      *
+     * **Scope note: that `binColors` exclusion is about the LIVE states only.**
+     * It does not carry over to {@link dimmed}, which *replaces* a per-bar fill
+     * on an unselected bar — see that token, which spells out the asymmetry and
+     * why emphasis preserves a per-bar colour while recession suppresses it.
+     *
      * The **decimated** dense-bar pass also draws the flat fill only, as it
      * already did for `highlight`.
      */
@@ -859,6 +912,29 @@ export interface BarStyle {
      * component, and drifted immediately — one consumer had three charts using
      * `color-mix` at 22%, 28% and 30% for the same concept, in the same week, for
      * no reason. One theme value fixes that permanently.
+     *
+     * **It OVERRIDES a per-bar fill, unlike the live states.** This is the one
+     * place `dimmed` and {@link hover} deliberately disagree, and the asymmetry
+     * is easy to read the wrong way round:
+     *
+     * - **{@link binColors} / {@link binFills}:** an unselected bar paints
+     *   `dimmed`, discarding its own colour. (Hover and selection do the
+     *   opposite — they keep the per-bar colour and pop the alpha, so a
+     *   red/green volume bar stays red/green while live.)
+     * - **{@link bands} / thresholds:** an unselected banded bar draws **flat**
+     *   in `dimmed`, discarding the ladder entirely rather than dimming each
+     *   band.
+     * - **A multi-group stack** resolves per group through
+     *   {@link StackStyle.dimmedFills} first, falling back to this flat value —
+     *   a stack dimmed to one colour stops reading as a stack.
+     *
+     * The rule behind all three: a per-bar or per-band colour encodes *what the
+     * value is*, and a receded bar's whole job is to stop competing over that.
+     * Emphasis preserves meaning; recession suppresses it. So a chart that keeps
+     * `binColors` or `thresholds` for reasons unrelated to selection still gets
+     * a visible de-emphasis for free, and does **not** need to dim inside its own
+     * colour arrays. (Asked by a consumer who reasonably generalized `hover`'s
+     * `binColors` exclusion to this token; the exclusion is live-states-only.)
      */
     readonly dimmed?: string;
 }

package/dist/theme.js

@@ -78,6 +78,9 @@ export const defaultTheme = {
             selectedFillOpacity: 0.55,
             dimmedOpacity: 0.32,
             spanColor: '#3F5BE0',
+            // The same ok → warning → alarm ladder `bar.default.bands` carries, so a
+            // banded area and a banded bar over one dataset read as one system.
+            bands: ['#2A9D8F', '#e8a13c', '#d64545'],
         },
         in: { color: '#0284c7', width: 1.5, fill: '#0284c7', fillOpacity: 0.3 },
         out: { color: '#e8836b', width: 1.5, fill: '#e8836b', fillOpacity: 0.3 },

package/dist/use-band-ladder.d.ts

@@ -0,0 +1,30 @@
+import { type BandLadder } from './bars.js';
+/**
+ * Resolve a component's `thresholds` / `bandColors` props against its theme
+ * role's band ramp into a {@link BandLadder} — or `undefined` when there is no
+ * usable ladder, so the caller keeps its flat path.
+ *
+ * Extracted from `<BarChart>`'s [PND-BANDBAR2] block verbatim when
+ * `<AreaChart thresholds>` arrived ([PND-BANDAREA]): the resolution rules and
+ * every dev warning are one contract across banded marks, differing only in
+ * the component named by the warning text.
+ *
+ * Resolved once here rather than per mark per frame: normalize the breakpoints
+ * (sort, drop non-finite / non-positive), then pair them with `bandColors` →
+ * the role's `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 mark was the workaround's failure mode.
+ *
+ * The two array props are **value-compared** rather than identity-compared:
+ * `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 caller's layer entry, 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>` applies.
+ *
+ * A short colour supply pads with `styleFill` (the role's flat fill) so the
+ * draw path can index freely; `undefined` comes back only when there are no
+ * usable breakpoints or no colours at all.
+ */
+export declare function useBandLadder(component: 'BarChart' | 'AreaChart', thresholds: readonly number[] | undefined, bandColors: readonly string[] | undefined, styleBands: readonly string[] | undefined, styleFill: string): BandLadder | undefined;
+//# sourceMappingURL=use-band-ladder.d.ts.map

package/dist/use-band-ladder.js

@@ -0,0 +1,81 @@
+import { useMemo } from 'react';
+import { normalizeThresholds } from './bars.js';
+import { isDev } from './dev.js';
+/**
+ * Resolve a component's `thresholds` / `bandColors` props against its theme
+ * role's band ramp into a {@link BandLadder} — or `undefined` when there is no
+ * usable ladder, so the caller keeps its flat path.
+ *
+ * Extracted from `<BarChart>`'s [PND-BANDBAR2] block verbatim when
+ * `<AreaChart thresholds>` arrived ([PND-BANDAREA]): the resolution rules and
+ * every dev warning are one contract across banded marks, differing only in
+ * the component named by the warning text.
+ *
+ * Resolved once here rather than per mark per frame: normalize the breakpoints
+ * (sort, drop non-finite / non-positive), then pair them with `bandColors` →
+ * the role's `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 mark was the workaround's failure mode.
+ *
+ * The two array props are **value-compared** rather than identity-compared:
+ * `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 caller's layer entry, 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>` applies.
+ *
+ * A short colour supply pads with `styleFill` (the role's flat fill) so the
+ * draw path can index freely; `undefined` comes back only when there are no
+ * usable breakpoints or no colours at all.
+ */
+export function useBandLadder(component, thresholds, bandColors, styleBands, styleFill) {
+    const thresholdKey = thresholds === undefined ? '' : thresholds.join(',');
+    const bandColorKey = bandColors === undefined ? '' : bandColors.join(',');
+    return useMemo(() => {
+        const steps = normalizeThresholds(thresholds);
+        if (steps === null) {
+            if (isDev && thresholds !== undefined && thresholds.length > 0) {
+                console.warn(`<${component} thresholds>: no usable breakpoints, so no banding ` +
+                    'was applied — each must be finite and greater than zero. The ' +
+                    'chart draws 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(`<${component} 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 the value is on, so a negative breakpoint has no meaning; ` +
+                `banding on [${steps.join(', ')}].`);
+        }
+        const want = steps.length + 1;
+        const supplied = bandColors ?? styleBands;
+        if (supplied === undefined || supplied.length === 0) {
+            if (isDev) {
+                console.warn(`<${component} thresholds>: ${steps.length} breakpoint(s) need ` +
+                    `${want} band colours, but neither \`bandColors\` nor the theme ` +
+                    `role’s \`bands\` supplies any. The chart draws in the flat fill.`);
+            }
+            return undefined;
+        }
+        if (supplied.length < want && isDev) {
+            console.warn(`<${component} 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 }, () => styleFill),
+            ];
+        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.
+    }, [component, thresholdKey, bandColorKey, styleBands, styleFill]);
+}
+//# sourceMappingURL=use-band-ladder.js.map

package/dist/useChartFrame.d.ts

@@ -0,0 +1,122 @@
+import { type ChartXScale, type YScale } from './context.js';
+/**
+ * One ordinal slot on a category axis — its pixel span within the plot, its
+ * centre (where a mark is drawn and a tick is labelled), and its name.
+ *
+ * `x0`/`x1`/`center` are **plot-relative** (`0 … plot.width`); add
+ * {@link ChartFrame.plot}`.x` for container-relative DOM placement.
+ */
+export interface ChartBand {
+    /** The slot's left edge in px. */
+    readonly x0: number;
+    /** The slot's right edge in px. `x1 - x0` is {@link ChartBands.pitch}. */
+    readonly x1: number;
+    /** The slot's centre in px — where a bar centres and a tick labels. */
+    readonly center: number;
+    /** The category name at this slot. */
+    readonly label: string;
+}
+/**
+ * The ordinal slot geometry of a `'category'` x axis — `null` on a `'time'`
+ * or `'value'` axis, which has no slots.
+ *
+ * **The pitch is not `plot.width / count`.** `<ChartContainer maxBandWidth>`
+ * caps it and `bandAlign` places the resulting narrower block within the
+ * plot, so the packed band run can be inset from both plot edges. Reading
+ * `pitch` and `at(i)` rather than recomputing is the difference between
+ * chrome that tracks that packing and chrome that ignores it.
+ */
+export interface ChartBands {
+    /** Number of slots — the category count. */
+    readonly count: number;
+    /** One slot's width in px (the pitch; slots are contiguous and equal). */
+    readonly pitch: number;
+    /** The ordered category names, index-aligned with the slots. */
+    readonly labels: readonly string[];
+    /** The slot at `index`, or `null` when `index` is not a real slot. */
+    at(index: number): ChartBand | null;
+}
+/**
+ * The **row-scoped** half of the frame: y geometry and the row's value
+ * scales. `null` on {@link ChartFrame.row} when the hook is called outside a
+ * `<ChartRow>`.
+ */
+export interface ChartFrameRow {
+    /**
+     * The plot's top inset within the row's box in px — the band reserved by a
+     * `labelPlacement="top"` axis title, `0` when no axis draws one. An overlay
+     * that ignores it sits under the title.
+     */
+    readonly topInset: number;
+    /**
+     * The plot's drawable height in px, below {@link topInset}. The row's own
+     * `height` prop is `topInset + height`, and the y-scales' pixel range is
+     * `[topInset + height, topInset]` (inverted — pixels grow downward).
+     */
+    readonly height: number;
+    /**
+     * One value→pixel scale per `<YAxis id>`, each mapping into
+     * `[topInset + height, topInset]`. A row with no explicit `<YAxis>` has one
+     * entry under the implicit default id.
+     */
+    readonly yScales: ReadonlyMap<string, YScale>;
+    /** Which gutter each axis id sits in — so chrome hugs the right edge. */
+    readonly axisSides: ReadonlyMap<string, 'left' | 'right'>;
+}
+/** The resolved geometry of a chart, as published by {@link useChartFrame}. */
+export interface ChartFrame {
+    /**
+     * The plot's **x** geometry in px, relative to the container's own box:
+     * `x` is the left gutter (where the plot starts) and `width` is the plot's
+     * width after both gutters. Shared by every row.
+     */
+    readonly plot: {
+        readonly x: number;
+        readonly width: number;
+    };
+    /**
+     * The reserved axis gutters in px — how far the plot is inset on each side.
+     * `left` equals {@link plot}`.x`; both are published because chrome above
+     * the plot pads by `left` while chrome sized to the container subtracts
+     * both.
+     */
+    readonly gutters: {
+        readonly left: number;
+        readonly right: number;
+    };
+    /**
+     * The shared x→pixel scale, mapping into `[0, plot.width]`. Callable
+     * (`value → px`) with `invert` / `ticks` / `tickFormat`, whichever kind the
+     * container resolved (see {@link ChartXScale}).
+     *
+     * **Not the same thing as `<ChartContainer xScale>`**, which is a string
+     * naming how a *value* axis spaces itself (`'linear' | 'log' | 'symlog'`).
+     * This is the built scale object that choice — along with the data's kind,
+     * `origin`, `discontinuities` and `categories` — resolves to.
+     */
+    readonly xScale: ChartXScale;
+    /**
+     * Which **kind** of x axis resolved: `'time'`, `'value'` or `'category'`.
+     * `'category'` is exactly when {@link bands} is non-null.
+     *
+     * Distinct from `<ChartContainer xScale>` again: that picks the spacing
+     * *within* a value axis, this says whether the axis is a value axis at all.
+     */
+    readonly xKind: 'time' | 'value' | 'category';
+    /** Ordinal slot geometry on a `'category'` axis; `null` otherwise. */
+    readonly bands: ChartBands | null;
+    /** Row-scoped y geometry — `null` outside a `<ChartRow>`. */
+    readonly row: ChartFrameRow | null;
+}
+/**
+ * Read the container's resolved plot geometry — the plot rect, the axis
+ * gutters, the shared x scale, the row's y scales, and (on a category axis)
+ * the ordinal slot edges. See the module docblock for the x/y split, the
+ * placement-scoped `row` half, and which box each pixel value is relative to.
+ *
+ * Must be called under a `<ChartContainer>`; throws otherwise. To render the
+ * markup *outside* the chart's box, portal it out (`createPortal`) — context
+ * flows through portals.
+ */
+export declare function useChartFrame(): ChartFrame;
+//# sourceMappingURL=useChartFrame.d.ts.map

package/dist/useChartFrame.js

@@ -0,0 +1,155 @@
+/**
+ * `useChartFrame()` — **the resolved plot geometry, published**.
+ *
+ * A consumer whose chrome has to line up with the plot (a per-slot header
+ * table above it, a column summary strip below it, a card pinned over one
+ * band, a colour ramp keyed to the plot's own scale) needs the numbers the
+ * container already resolved: where the plot starts, how wide it is, and the
+ * scales that map data to pixels inside it. Before this hook none of that was
+ * reachable, so consumers re-derived it — pin every axis gutter to a fixed
+ * width so it stops depending on label content, measure the outer box,
+ * subtract, and re-implement the band packing.
+ *
+ * **That duplicate is not merely verbose, it is wrong over time.** It holds
+ * only until the library changes how a gutter is sized or how bands are
+ * packed, at which point the consumer's chrome slides out of alignment with
+ * the plot it labels — with no type error and no failing test. Reading the
+ * frame converts a silent drift hazard into a version-checked API.
+ *
+ * ## The x / y split is the library's own
+ *
+ * The shape mirrors the architecture rather than flattening it: **the
+ * container owns x** (one shared scale, so every row's plot left-aligns under
+ * one time axis) and **rows own y** (row-local data, one scale per axis id).
+ * So {@link ChartFrame.plot} carries x only, and y lives on
+ * {@link ChartFrame.row} — which is `null` when the hook is called outside a
+ * `<ChartRow>`.
+ *
+ * That `null` is the point. The common case (a header strip above the plot,
+ * a sibling of the rows) genuinely has no y geometry, and the alternative —
+ * reporting `height: 0` — is the same silent-misalignment failure this hook
+ * exists to remove. A consumer that needs y must be inside a row, and the
+ * type says so.
+ *
+ * ## Scope follows placement
+ *
+ * Exactly as {@link useChartLegend} does: at the container level you get the
+ * shared x frame and `row: null`; inside a `<ChartRow>` you additionally get
+ * that row's y scales. No prop selects the scope — placement does.
+ *
+ * ## Pixel origins
+ *
+ * Two different boxes, because the DOM has two:
+ *
+ * - `plot.x` / `plot.width` are relative to the **container's** box, so a
+ *   `<div>` sibling of the rows pads by `plot.x` to align.
+ * - `xScale(v)` and `bands.at(i)` are relative to the **plot**, i.e. `0 …
+ *   plot.width` — the coordinate system the canvas draws in. Add `plot.x` to
+ *   place DOM chrome in container space.
+ * - `row.topInset` / `row.height` are relative to the **row's** box.
+ *
+ * @example Align a per-slot header strip above a categorical plot
+ * ```tsx
+ * function SlotHeader() {
+ *   const { plot, bands } = useChartFrame();
+ *   if (bands === null) return null;
+ *   return (
+ *     <div style={{ position: 'relative', height: 22, marginLeft: plot.x, width: plot.width }}>
+ *       {bands.labels.map((label, i) => {
+ *         const b = bands.at(i)!;
+ *         return (
+ *           <div key={label} style={{ position: 'absolute', left: b.x0, width: b.x1 - b.x0 }}>
+ *             {label}
+ *           </div>
+ *         );
+ *       })}
+ *     </div>
+ *   );
+ * }
+ *
+ * <ChartContainer categories={tickers} width="auto">
+ *   <SlotHeader />
+ *   <ChartRow height={200}>…</ChartRow>
+ * </ChartContainer>
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { useContext, useMemo } from 'react';
+import { ContainerContext, RowContext, } from './context.js';
+/** Whether the container resolved an ordinal scale (which alone carries `label`). */
+function asBandScale(scale, kind) {
+    return kind === 'category' ? scale : null;
+}
+/**
+ * Read the container's resolved plot geometry — the plot rect, the axis
+ * gutters, the shared x scale, the row's y scales, and (on a category axis)
+ * the ordinal slot edges. See the module docblock for the x/y split, the
+ * placement-scoped `row` half, and which box each pixel value is relative to.
+ *
+ * Must be called under a `<ChartContainer>`; throws otherwise. To render the
+ * markup *outside* the chart's box, portal it out (`createPortal`) — context
+ * flows through portals.
+ */
+export function useChartFrame() {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('useChartFrame() must be used inside a <ChartContainer>');
+    }
+    const row = useContext(RowContext);
+    const { leftGutter, rightGutter, plotWidth, xScale, xKind } = container;
+    const bands = useMemo(() => {
+        const band = asBandScale(xScale, xKind);
+        if (band === null)
+            return null;
+        // The slot count is the scale's own domain width, not the label count:
+        // `scaleBand` is built with `domain([0, n])` from the container's resolved
+        // category list, so the domain is the authority on geometry (the labels
+        // ride alongside for naming). They agree today; reading the domain means
+        // they cannot disagree here if that ever stops being true.
+        const [d0, d1] = band.domain();
+        const count = Math.max(0, Math.round(d1 - d0));
+        const pitch = band.step();
+        // Slot `i` is the domain value `d0 + i`; the container always sets
+        // `domain([0, n])` so `d0` is 0 today, but every read goes through it so
+        // an offset domain could never silently shift the labels off the slots.
+        const labels = [];
+        for (let i = 0; i < count; i++)
+            labels.push(band.label(d0 + i + 0.5));
+        return {
+            count,
+            pitch,
+            labels,
+            at(index) {
+                if (!Number.isInteger(index) || index < 0 || index >= count) {
+                    return null;
+                }
+                return {
+                    x0: band(d0 + index),
+                    x1: band(d0 + index + 1),
+                    center: band(d0 + index + 0.5),
+                    label: labels[index] ?? '',
+                };
+            },
+        };
+    }, [xScale, xKind]);
+    const rowHalf = useMemo(() => {
+        if (row === null)
+            return null;
+        return {
+            topInset: row.topInset,
+            height: Math.max(0, row.height - row.topInset),
+            yScales: row.yScales,
+            axisSides: row.axisSides,
+        };
+    }, [row]);
+    return useMemo(() => ({
+        plot: { x: leftGutter, width: plotWidth },
+        gutters: { left: leftGutter, right: rightGutter },
+        xScale,
+        xKind,
+        bands,
+        row: rowHalf,
+    }), [leftGutter, rightGutter, plotWidth, xScale, xKind, bands, rowHalf]);
+}
+//# sourceMappingURL=useChartFrame.js.map

package/dist/useChartLegend.d.ts

@@ -32,6 +32,14 @@ export interface ChartLegend {
      * inset from the chart box on each side. A custom legend laid out above /
      * below the chart pads by `gutters.left` (and `gutters.right`) to align
      * with the plot instead of the y-axis column.
+     *
+     * The same two numbers {@link useChartFrame} publishes as
+     * `ChartFrame.gutters`, kept here so a legend needs one hook rather than
+     * two. **Reach for `useChartFrame()` instead** when the chrome is not a
+     * legend, or when aligning needs more than the gutters — the plot width,
+     * the x scale, the per-slot band edges, or a row's y scales. This field
+     * predates that hook and is the reason it exists: the geometry was
+     * published for exactly one consumer, on a hook named for something else.
      */
     readonly gutters: {
         readonly left: number;

package/dist/viewport.d.ts

@@ -24,13 +24,46 @@ export type TimeRange = readonly [number, number];
  * range untouched) so a mis-specified extent can't collapse the view.
  */
 export declare function clampToBounds(range: TimeRange, bounds: TimeRange): [number, number];
+/**
+ * How a viewport gesture should treat the domain it is moving.
+ *
+ * Both flags exist because {@link roundRange} was written for a **millisecond**
+ * axis and silently assumed every axis was one.
+ */
+export interface ViewportOptions {
+    /**
+     * Snap the result to whole integers. **Default `true`** — right for a time
+     * axis, where a fractional domain is meaningless and the 1 ms floor is the
+     * finest real view.
+     *
+     * Pass `false` on a **value** axis, where the units are not milliseconds and
+     * the fractions are the data: a power–duration curve over `[0.5, 10800]`
+     * seconds would otherwise snap its floor to `0`, and a `[0.001, 1]` domain
+     * would collapse to `[0, 1]`.
+     *
+     * The axis kind is a caller's fact, not something to infer from magnitude — a
+     * 0.2 ms span and a 0.2-unit value span are indistinguishable by size, and
+     * guessing breaks whichever one you guessed against.
+     */
+    readonly snap?: boolean;
+    /**
+     * Do the arithmetic in **log space**, where a log axis is linear. Implies
+     * `snap: false`.
+     *
+     * Without it a log axis zooms additively, which drags the value under the
+     * cursor sideways — the one thing zoom must never do — and pans by an offset,
+     * so a drag near the low end walks off the plot while the same drag near the
+     * high end barely moves.
+     */
+    readonly log?: boolean;
+}
 /**
  * Shift a range by `dt` ms (drag-pan). The caller signs `dt` from the gesture —
  * dragging the plot right reveals earlier data, i.e. a negative `dt`. The result
  * is snapped to whole milliseconds ({@link roundRange}) — `dt` comes from a pixel
  * delta through `xScale.invert()`, so it is fractional by construction.
  */
-export declare function panRange(range: TimeRange, dt: number): [number, number];
+export declare function panRange(range: TimeRange, dt: number, options?: ViewportOptions): [number, number];
 /**
  * Zoom `range` around `pivot` (ms) by `factor` — `< 1` zooms in, `> 1` out, with
  * the pivot held fixed (the time under the cursor stays put). Clamped so the
@@ -43,7 +76,7 @@ export declare function panRange(range: TimeRange, dt: number): [number, number]
  * lands on the 1 ms floor the snap guarantees, which is the finest view this
  * model has.
  */
-export declare function zoomRange(range: TimeRange, pivot: number, factor: number, minDuration?: number): [number, number];
+export declare function zoomRange(range: TimeRange, pivot: number, factor: number, minDuration?: number, options?: ViewportOptions): [number, number];
 /**
  * The slice of a discontinuity provider the trading-time viewport math needs —
  * a structural subset of the charts `DiscontinuityProvider` (so `viewport.ts`