@pond-ts/charts 0.58.0 → 0.60.0

package/dist/BarChart.js

@@ -1,8 +1,9 @@
 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, normalizeThresholds, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
+import { barsFromTimeSeries, barsFromBins, barsFromValueSeries, categoryStack, categoryStacks, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
+import { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
 import { spansForLayer } from './span.js';
+import { useBandLadder } from './use-band-ladder.js';
 import { isDev } from './dev.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { sweep1D } from './sweep.js';
@@ -60,7 +61,7 @@ const EMPTY_MARKS = [];
  * </Layers>
  * ```
  */
-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, }) {
+export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation = 'vertical', ordinal = false, id, axis, gap, maxBarWidth, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BarChart> must be rendered inside a <ChartContainer>');
@@ -78,8 +79,11 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         throw new Error('<BarChart> needs exactly one of `series`, `bins`, or `categories`');
     }
     if (categories !== undefined) {
-        if (column !== undefined || columns !== undefined) {
-            throw new Error('<BarChart categories> takes no `column`/`columns` (each datum carries its own value)');
+        if (column !== undefined) {
+            throw new Error('<BarChart categories> takes no `column` — a single-value datum carries its own `value`, and a stacked one names its groups with `columns`');
+        }
+        if (columns !== undefined && columns.length === 0) {
+            throw new Error('<BarChart categories> with `columns` needs at least one group name');
         }
     }
     const isMap = series instanceof Map;
@@ -105,10 +109,21 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     // horizontal bar) so one oriented draw path covers it.
     const shape = useMemo(() => {
         if (categories !== undefined) {
-            // Categorical row-read: one unit-slot bar per category (G === 1), drawn on
-            // the container's band scale. The reused stacked geometry — only the axis
+            // Categorical row-read: one unit-slot bar per category, drawn on the
+            // container's band scale. The reused stacked geometry — only the axis
             // (band scale + labels) is new.
-            return { kind: 'stacked', ss: categoryStack(categories) };
+            //
+            // With `columns` it is a real multi-group stack ([PND-CATSTACK]): same
+            // slots, same `marks`, `G > 1`. Because `marks` is indexed by BIN, one
+            // selection entry naming `(id, mark)` matches every segment of a bar —
+            // which is the property that made the hand-composed workaround's
+            // "recedes from the waist up" bug inexpressible here.
+            return {
+                kind: 'stacked',
+                ss: columns !== undefined
+                    ? categoryStacks(categories, columns)
+                    : categoryStack(categories),
+            };
         }
         if (bins !== undefined) {
             const cols = columns ?? (column !== undefined ? [column] : undefined);
@@ -250,67 +265,24 @@ 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;
+    // Same sourcing as `gapPx`: the prop wins, else the theme token, else
+    // uncapped ([PND-BARWIDTH]). `bar.default` rather than the `as` role for the
+    // stacked ceiling, for the reason above.
+    const maxWidthPx = maxBarWidth ?? bar.default.maxWidth;
+    // The single-series draw takes a `BarStyle` straight from the theme, so the
+    // prop override is applied by shadowing the token — same relationship `gap`
+    // has, and with the prop absent the role's own `maxWidth` (if any) already
+    // rides along untouched. Only the INK path gets this: `barSlotRect` (the hit
+    // region) stays the whole slot, so a narrow capped bar keeps a full-width
+    // target — the deliberate ink/hit split `gapPx` already relies on.
+    const singleDrawStyle = useMemo(() => maxBarWidth !== undefined
+        ? { ...singleStyle, maxWidth: maxBarWidth }
+        : singleStyle, [singleStyle, maxBarWidth]);
     // ── 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]);
+    // Breakpoints normalized + paired with `bandColors` → the role's
+    // `BarStyle.bands` in the shared {@link useBandLadder} (one contract with
+    // `<AreaChart thresholds>`, including every dev warning).
+    const bandLadder = useBandLadder('BarChart', thresholds, bandColors, singleStyle.bands, singleStyle.fill);
     // 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;
@@ -351,11 +323,38 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
             (ramp !== undefined ? at(ramp, i) : base.fill));
         // A ramp entry the call site overrode is no longer the ramp's colour, so
         // its receded counterpart would be wrong — the whole ramp only means
-        // anything when it is the ramp that painted it.
+        // anything when it is the ramp that painted it. This gates the *derived*
+        // companions (`dimmedFills` / `hoverFills`), which need a counterpart per
+        // group and cannot invent one for an arbitrary call-site colour.
         const ramped = ramp !== undefined && colors === undefined;
+        // `groupColored` derives nothing — it only says "a selected segment keeps
+        // its own fill rather than taking the flat `highlight`", because the colour
+        // is meaning-carrying.
+        //
+        // So the condition is exactly **"do the fills actually differ"**, read off
+        // the resolved `fills` rather than inferred from anything upstream of them.
+        // Both cheaper inferences are wrong, and each was shipped in turn:
+        //
+        //  - Gating on `ramped` (the ramp painted it) meant a stack with `colors`
+        //    collapsed BOTH segments of a selected bar to one `highlight` blue —
+        //    losing the segment distinction exactly where the reader is looking. A
+        //    call site naming its groups' colours is *more* deliberate than a
+        //    fallback ramp, not less. Found building [PND-CATSTACK].
+        //  - Gating on `groups.length > 1` (my fix for that) is wrong in the other
+        //    direction: a multi-group stack under a theme with **no** group ramp, no
+        //    `colors` and no per-group roles resolves every fill to `base.fill`, so
+        //    claiming the colour carries meaning suppresses the highlight and leaves
+        //    *nothing* — selection becomes invisible. `estelaTheme` is exactly that
+        //    theme, and it ships. Found by Layer-2 review, which is the only way it
+        //    could have been: every story and test renders `defaultTheme`, whose ramp
+        //    makes the two gates indistinguishable.
+        //
+        // Reading `fills` also handles the degenerate `colors` map that assigns one
+        // colour to every group: nothing is distinguished, so the highlight applies.
+        const groupColoured = new Set(fills).size > 1;
         return {
             fills,
-            ...(ramped ? { groupColored: true } : {}),
+            ...(groupColoured ? { groupColored: true } : {}),
             ...(ramped && rampDim !== undefined
                 ? {
                     dimmedFills: (groups ?? []).map((_g, i) => at(rampDim, i)),
@@ -380,9 +379,10 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                 ? { emphasisOpacity: base.emphasisOpacity }
                 : {}),
             ...(base.dimmed !== undefined ? { dimmed: base.dimmed } : {}),
+            ...(maxWidthPx !== undefined ? { maxWidth: maxWidthPx } : {}),
             ...(binColors !== undefined ? { binFills: binColors } : {}),
         };
-    }, [bar, groups, colors, binColors]);
+    }, [bar, groups, colors, binColors, maxWidthPx]);
     // The current selection / hover, narrowed to the identity the highlight match
     // needs. For a stack that's (id, key, label = group); the single path uses just
     // (id, key). Read here so a change re-registers the layer → the canvas repaints.
@@ -525,7 +525,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, bandLadder, layerSpans),
+                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleDrawStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors, bandLadder, layerSpans),
                 },
                 axisId: axis,
                 index,
@@ -563,7 +563,20 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                     ? {}
                     : {
                         hitTest: (px, py, xScale, yScale) => {
-                            const hit = stackAt(ss, px, py, orientation, xScale, yScale, gapPx, stackMinWidth);
+                            // The cap reaches the hit rect ONLY for a real stack, where the
+                            // rect is what resolves *which segment* was hit and so must be
+                            // the drawn one. A single-series chart has one segment per slot
+                            // and nothing to disambiguate, so narrowing its target buys
+                            // nothing and costs clickability.
+                            //
+                            // This path serves single-series **horizontal** charts as well as
+                            // stacks (see the branch comment above), which is how the prop's
+                            // documented guarantee — "a single-series bar hit-tests its whole
+                            // slot" — was true only of vertical ones. Found by Layer-2 review;
+                            // the fix is to make the guarantee orientation-independent rather
+                            // than to narrow the claim, since the reason for the split is
+                            // segment disambiguation and that is a property of the *stack*.
+                            const hit = stackAt(ss, px, py, orientation, xScale, yScale, gapPx, stackMinWidth, ss.groups.length > 1 ? maxWidthPx : undefined);
                             if (hit === null)
                                 return null;
                             const [bi, g, begin, name, value] = hit;
@@ -656,6 +669,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         categoryLabels,
         orientation,
         singleStyle,
+        singleDrawStyle,
         stackStyle,
         binColors,
         bandLadder,
@@ -664,6 +678,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         gapPx,
         decimate,
         stackMinWidth,
+        maxWidthPx,
         selection,
         hover,
         layerSpans,

package/dist/BarList.d.ts

@@ -69,6 +69,28 @@ export interface BarListCommon<R extends ListRow = ListRow> {
     selected?: string | readonly string[] | null;
     /** Row click (rows show the pointer affordance only when provided). */
     onRowClick?: (row: R) => void;
+    /**
+     * Per-**row** bar colour, `barColors[i]` aligned to the rows in order — the
+     * list's `<BarChart binColors>` ([#650]). An `undefined` or short entry falls
+     * back to the column's `as` / theme fill, so a partial list is legal.
+     *
+     * For the case `binColors` was built for and a list could not do: a zone
+     * table where each row's bar carries its own step of a ramp (Z1 deep → Z7
+     * pale). Without it a `BarListColumn`'s single `as` paints every row the same
+     * colour, and the ramp has to move onto the label — putting it on the wrong
+     * element, since the bar is the natural carrier of a magnitude.
+     *
+     * **The fill becomes load-bearing, so its state treatment stands down.** A
+     * per-row-coloured bar keeps its own colour while selected or hovered, and
+     * the live state is carried by the band and rail that already say it. This is
+     * the same rule the multi-metric case follows for the same reason — see the
+     * comment beside the fill resolution — and the same one `binColors` follows
+     * on the canvas: recolouring a bar that means something would trade a
+     * distinction the reader needs for one they already have.
+     *
+     * [#650]: https://github.com/pond-ts/pond/issues/650
+     */
+    barColors?: readonly (string | undefined)[];
     /**
      * **Plural select** — the list's answer to `<MultiSelector>`, and how a user
      * produces a multi-row {@link selected}.

package/dist/BarList.js

@@ -36,7 +36,7 @@ export function BarList(props) {
     // One normalized view of the union — `isSeriesSource` is the runtime
     // narrowing; the doors are mutually exclusive by construction now.
     const source = props;
-    const { rows, series, label, columns, domain, sortBy, sortDirection = 'desc', sort, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, onRowSelect, hovered, onHover, markers, barHeight = 8, divided, baseline, theme = defaultTheme, } = source;
+    const { rows, series, label, columns, domain, sortBy, sortDirection = 'desc', sort, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, onRowSelect, barColors, hovered, onHover, markers, barHeight = 8, divided, baseline, theme = defaultTheme, } = source;
     // A runtime guard for JS consumers and `any`-typed call sites — the
     // props union makes both branches unreachable from typed TS, but a
     // silently-ignored source prop is a worse failure than a throw.
@@ -49,6 +49,21 @@ export function BarList(props) {
         (series instanceof ValueSeries
             ? listRowsFromValueSeries(series, label !== undefined ? { label } : {})
             : listRowsFromTimeSeries(series, label !== undefined ? { label } : {})), [rows, series, label]);
+    // Keyed by row, not indexed by render position. `barColors` aligns to the
+    // rows the caller passed — but the table renders `sorted`, so an index would
+    // silently repaint the ramp onto the wrong rows the moment `sortBy` is set.
+    // The key survives any reordering.
+    const barColorOf = useMemo(() => {
+        if (barColors === undefined)
+            return null;
+        const m = new Map();
+        allRows.forEach((r, i) => {
+            const c = barColors[i];
+            if (c !== undefined)
+                m.set(r.key, c);
+        });
+        return m;
+    }, [barColors, allRows]);
     const sorted = useMemo(() => sortListRows(allRows, sortBy, sortDirection, sort), [allRows, sortBy, sortDirection, sort]);
     const scale = useMemo(() => resolveListDomain(allRows, columns.map((c) => c.column), domain, markers?.map((m) => m.value)), [allRows, columns, domain, markers]);
     const resolvedMarkers = useMemo(() => markers?.map((m) => ({
@@ -68,17 +83,35 @@ export function BarList(props) {
                 // Which is also why nothing below may be the *only* signal: strip
                 // this block and a selected row still reads as selected.
                 const soleMetric = columns.length === 1;
-                const fill = state.selected && soleMetric
-                    ? style.highlight
-                    : state.dimmed
-                        ? (style.dimmed ?? style.fill)
-                        : style.fill;
+                // A per-row colour makes the fill mean something, which puts it in
+                // exactly the position a multi-metric row's fill is already in: the
+                // state treatment stands down rather than trading a distinction the
+                // reader needs for one the band and rail already give them. Same
+                // rule `binColors` follows on the canvas.
+                const own = barColorOf?.get(row.key);
+                const fill = own !== undefined
+                    ? own
+                    : state.selected && soleMetric
+                        ? style.highlight
+                        : state.dimmed
+                            ? (style.dimmed ?? style.fill)
+                            : style.fill;
                 // A `dimmed` token carries its own alpha (`rgba(…,0.32)`), so
                 // multiplying `opacity` on top of it would dim twice. Fall back to
                 // the raw 0.32 only when the theme names no dimmed colour.
-                const fillOpacity = state.dimmed && style.dimmed === undefined
-                    ? style.opacity * 0.32
-                    : style.opacity;
+                // Opacity is where a coloured bar shows its state, since its hue
+                // is spoken for. A `dimmed` THEME token carries its own alpha so
+                // multiplying on top would dim twice — but that token is not in
+                // play for a per-row colour, so the raw 0.32 applies there too.
+                const fillOpacity = own !== undefined
+                    ? state.dimmed
+                        ? style.opacity * 0.32
+                        : state.selected
+                            ? 1
+                            : style.opacity
+                    : state.dimmed && style.dimmed === undefined
+                        ? style.opacity * 0.32
+                        : style.opacity;
                 return (_jsxs("div", { "data-list-track": col.column, style: {
                         position: 'relative',
                         height: barHeight,

package/dist/ChartContainer.d.ts

@@ -14,6 +14,108 @@ export interface ChartContainerProps {
      * the data — so a tuple stays a time domain on a time chart.
      */
     range?: readonly [number, number] | TimeRange;
+    /**
+     * **Make the x axis ordinal at the container level** — one equal-width slot
+     * per name, in this order ([PND-IGNITECAT]).
+     *
+     * Note this is a list of **names** (`string[]`), unlike `<BarChart
+     * categories>`, which takes `{ label, value }` data. The container names the
+     * slots; the bar layer fills them.
+     *
+     * Until this prop, the band scale was reachable only *through a layer*:
+     * `<BarChart categories>` (and a **horizontal** heat map) reported
+     * `xKind: 'category'`,
+     * every other layer reported `'time'` or `'value'`, and the container throws
+     * on a mix — so **a line, a point or an envelope over categorical bars was
+     * not expressible at all**. The workaround was to key every layer to a
+     * synthetic integer index and hand-supply the tick labels, which forfeits two
+     * features the ordinal axis already implements: `<XAxis>` label thinning
+     * (gated on a category axis with no custom ticks) and the
+     * {@link maxBandWidth} / {@link bandAlign} slot packing.
+     *
+     * Declaring the categories here inverts that. The container owns the ordinal
+     * domain, so **any value-keyed layer can live on it** and both of those
+     * features keep working.
+     *
+     * ## Keying a layer to the slots
+     *
+     * The band scale's domain is **numeric** — slot `i` occupies `[i, i+1]`, so
+     * its **centre is `i + 0.5`**. Key a `ValueSeries` there and the mark lands
+     * on the slot centre, which is also where `<XAxis>` puts the tick:
+     *
+     * ```tsx
+     * const line = ValueSeries.from(
+     *   tickers.map((t, i) => ({ x: i + 0.5, target: t.target })),
+     *   { key: 'x' },
+     * );
+     *
+     * <ChartContainer categories={tickers.map((t) => t.label)} width="auto">
+     *   <ChartRow height={220}>
+     *     <YAxis id="v" />
+     *     <Layers>
+     *       <BarChart categories={bars} />
+     *       <LineChart series={line} column="target" axis="v" />
+     *     </Layers>
+     *   </ChartRow>
+     * </ChartContainer>;
+     * ```
+     *
+     * ## What still errors
+     *
+     * - **A time-keyed layer.** A `TimeSeries` has no slot to sit in; mixing one
+     *   into an ordinal container is a hard error, as a mixed x-kind always was.
+     * - **A category layer that disagrees.** `<BarChart categories>` in an
+     *   ordinal container must name the same list in the same order — this prop
+     *   is authoritative, and a silent mismatch would draw bars under the wrong
+     *   labels.
+     * ## What declaring it costs
+     *
+     * Setting this makes the x axis ordinal, and two container capabilities are
+     * defined only on a continuous x. Both were already true of an *inferred*
+     * category axis; they are stated here because this prop lets you opt a
+     * previously-continuous container into them:
+     *
+     * - **x pan and zoom stop.** `panZoom` keeps working on **y** (`panY` /
+     *   `zoomY`), but the x half is gated off — sliding between named slots is
+     *   not a gesture the axis has a meaning for.
+     * - **{@link range} stops applying to x.** The domain is `[0, n]`, derived
+     *   from the slot count, so an x range is a no-op rather than an error.
+     *   Show a subset by passing fewer categories.
+     * - **{@link xScale} stops applying.** `'log'` / `'symlog'` describe how a
+     *   *continuous* x spaces its values; ordinal slots are evenly spaced by
+     *   definition, so the kind is ignored (as it already is on a time axis).
+     *
+     * ## The hazard this cannot catch
+     *
+     * **A value-keyed layer is taken at its word.** Anything reporting `'value'`
+     * is read as slot coordinates, so a layer whose x means something *else*
+     * will draw — in the wrong place, silently. The sharpest instance is a
+     * **horizontal categorical `<BarChart>`**: its x is bar *length*, not a
+     * coordinate, so on an ordinal x it plots magnitudes as slot positions.
+     * Don't mix one into an ordinal container.
+     *
+     * This is documented rather than enforced, and the reason is worth keeping:
+     * a guard was written for it, testing `binCategories`. That is the generic
+     * "my **y** is ordinal" channel, and a *vertical* heat map sets it too — so
+     * the guard rejected a `ValueSeries` grid with named columns on x, which is
+     * a wanted layout (ordinal rows plus ordinal columns is just a 2-D grid),
+     * with an error naming a `<BarChart>` that wasn't in the tree. Nothing on a
+     * layer source distinguishes "my x is a coordinate" from "my x is a
+     * magnitude", so there is no contradiction to detect — and a flag invented
+     * to carry it would buy a false sense of coverage while every other misuse
+     * stayed silent.
+     *
+     * ## One more edge
+     *
+     * **`categories={[]}` is an ordinal axis with no slots yet**, not a fallback
+     * to time. That is the useful reading for a loading state: the kind stays
+     * put when the data arrives, instead of flipping and rebuilding every scale
+     * mid-session.
+     *
+     * Omit for the inferred behaviour: a container with only category layers
+     * still resolves its slots from them, exactly as before.
+     */
+    categories?: readonly string[];
     /**
      * **Cap the slot pitch** on a **category** x axis, in CSS pixels
      * ([PND-BANDPACK]). A band scale otherwise spreads its categories across the
@@ -99,6 +201,38 @@ export interface ChartContainerProps {
      * carries its own metric).
      */
     spacing?: 'proportional' | 'uniform';
+    /**
+     * How the **value** x axis maps data to pixels. **Omitted ⇒ `'linear'`.**
+     *
+     * `'log'` for a quantity spanning orders of magnitude — a power–duration
+     * curve is watts against 1s · 5s · 1m · 20m · 3h, which is unreadable on a
+     * linear x. `'symlog'` is the same but linear through zero, for data that
+     * crosses it.
+     *
+     * **Ignored on a time or category axis**, which have their own spacing rules.
+     *
+     * **Why this lives on the container and not on `<XAxis scale>`,** which is
+     * where `<YAxis scale>`'s mirror would put it: **the rows are stacked
+     * vertically, so a given pixel column has to mean the same x in every one of
+     * them** — otherwise the stack doesn't line up and a cursor at one pixel
+     * reads a different value per row. The x scale and its domain are therefore
+     * *shared by requirement*, not by convention, and a shared thing is declared
+     * once by the thing that contains them. `<YAxis>` is the opposite for the
+     * same reason: each row carries its own quantity, so its scale **must** be
+     * per-row, which is why `min` / `max` / `pad` / `scale` belong to the axis.
+     *
+     * That gives the test for what belongs here rather than on `<XAxis>`: **does
+     * it define the mapping or the domain?** `origin`, `spacing`, `calendar` and
+     * the viewport props all do, and sit here for the same reason. Every
+     * `<XAxis>` prop (`format`, `label`, `side`, `ticks`, `align`, …) does not —
+     * they style a scale the axis only draws, and putting a scale-defining prop
+     * among them would mean a registration round-trip to the component that
+     * already owns it.
+     *
+     * (Had `<XAxis>` been mandatory in the declaration, the props would more
+     * naturally have lived there and x would mirror y — see [PND-XLOG].)
+     */
+    xScale?: 'linear' | 'log' | 'symlog';
     /**
      * Draw the reference gridlines behind the data. On a calendar (time) axis
      * the verticals are the **full grain populations** — every day / month /
@@ -124,8 +258,42 @@ export interface ChartContainerProps {
      * separators-on-a-clean-plot look.
      */
     sessionDividers?: 'labeled' | 'all' | 'none';
-    /** Total width in CSS pixels (plot + axis gutters). */
-    width: number;
+    /**
+     * Total width in CSS pixels (plot + axis gutters), or **`'auto'` to fill the
+     * available width** — which is also what an omitted `width` means.
+     *
+     * The canvas renderer needs real pixels to lay out ticks and slots before it
+     * draws, so `'auto'` does not hand the canvas a percentage: the container
+     * renders a plain full-width box, measures it with a `ResizeObserver`, and
+     * mounts the chart at that pixel width, re-rendering as the box resizes.
+     * **Nothing paints until a real width exists** — a zero-width chart is
+     * degenerate, not empty — so an auto container renders an empty box for the
+     * first layout pass.
+     *
+     * This is the [responsive-width recipe](https://pond-ts.github.io/pond/docs/recipes/responsive-width)
+     * moved inside the library, and it closes that recipe's sharpest edge by
+     * construction: the measured box is one the library owns, so it can never be
+     * the caller's padded or bordered box (whose border-box width overflows the
+     * chart by exactly the padding). Style your own wrapper *around* the
+     * container as freely as you like.
+     *
+     * **The parent needs a definite width.** `'auto'` measures a `width: 100%`
+     * box, so a parent whose own width comes from its *content* — a float, an
+     * `inline-block`, a grid `auto` track, a flex child without `min-width: 0` —
+     * measures 0, and the chart is the content that would have given it a width.
+     * That is a standing deadlock, not a slow start: the chart stays blank with
+     * no error. Give the parent a width, a `flex` basis, or `min-width: 0`, or
+     * pass a number.
+     *
+     * A container hidden by an ancestor's `display: none` is fine — it keeps the
+     * last width it measured and stays mounted, so a tab switch does not discard
+     * pan/zoom position, selection or hover.
+     *
+     * Pass a number whenever the width is already known — a fixed-size panel, a
+     * print layout, a test. It skips the measure pass and paints on the first
+     * render.
+     */
+    width?: number | 'auto';
     /** Vertical space between rows in CSS pixels (not under the axis). Default 0. */
     rowGap?: number;
     /**
@@ -449,6 +617,10 @@ export interface ChartContainerProps {
  * the shared time `xScale`. It renders its rows (separated by `rowGap`) then one
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
+ *
+ * A `width` in pixels renders straight through; `'auto'` (or an omitted
+ * `width`) measures the available width first — see {@link
+ * ChartContainerProps.width} and {@link AutoWidthContainer}.
  */
-export declare function ChartContainer({ range, maxBandWidth, bandAlign, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, panZoom, bounds, onTimeRangeChange, minDuration, cursor: cursorProp, cursorSequence: cursorSequenceProp, onRegionSelect, regionSelectModifier, cursorTime: cursorTimeProp, crosshairSnap: crosshairSnapProp, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat: cursorFormatProp, origin, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer(props: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map