@pond-ts/charts 0.59.0 → 0.61.0

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/CategoryAxis.d.ts

@@ -7,10 +7,14 @@ import { type XAxisProps } from './XAxis.js';
  * formatter). Kept as the familiar name for categorical charts, mirroring
  * {@link TimeAxis}. Forwards every {@link XAxisProps} (`label`, `side`, …).
  *
- * A high-cardinality axis (many categories) thins + truncates its labels to stay
- * legible (categorical-axis RFC, Phase 1). The labels **come from the data** (the
- * `categories` list), so a d3 `format` prop does not apply here (it can't name a
- * category); customize a label by changing the `categories` datum's `label`.
+ * A crowded axis thins + truncates its labels to stay legible — triggered by
+ * **measured geometry** (rendered label width vs. band pitch), not category
+ * count, so few-but-wide labels fit as reliably as many short ones
+ * ([PND-CATFIT]; categorical-axis RFC, Phase 1). Truncation is from the
+ * middle (`EDGE01…EQT`), keeping both the prefix and the distinguishing tail.
+ * The labels **come from the data** (the `categories` list), so a d3 `format`
+ * prop does not apply here (it can't name a category); customize a label by
+ * changing the `categories` datum's `label`.
  */
 export declare function CategoryAxis(props?: XAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=CategoryAxis.d.ts.map

package/dist/CategoryAxis.js

@@ -8,10 +8,14 @@ import { XAxis } from './XAxis.js';
  * formatter). Kept as the familiar name for categorical charts, mirroring
  * {@link TimeAxis}. Forwards every {@link XAxisProps} (`label`, `side`, …).
  *
- * A high-cardinality axis (many categories) thins + truncates its labels to stay
- * legible (categorical-axis RFC, Phase 1). The labels **come from the data** (the
- * `categories` list), so a d3 `format` prop does not apply here (it can't name a
- * category); customize a label by changing the `categories` datum's `label`.
+ * A crowded axis thins + truncates its labels to stay legible — triggered by
+ * **measured geometry** (rendered label width vs. band pitch), not category
+ * count, so few-but-wide labels fit as reliably as many short ones
+ * ([PND-CATFIT]; categorical-axis RFC, Phase 1). Truncation is from the
+ * middle (`EDGE01…EQT`), keeping both the prefix and the distinguishing tail.
+ * The labels **come from the data** (the `categories` list), so a d3 `format`
+ * prop does not apply here (it can't name a category); customize a label by
+ * changing the `categories` datum's `label`.
  */
 export function CategoryAxis(props = {}) {
     return _jsx(XAxis, { ...props });

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

package/dist/ChartContainer.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
-import { scaleLinear } from 'd3-scale';
+import { scaleLinear, scaleLog, scaleSymlog } from 'd3-scale';
 import { identityProvider, scaleTradingTime, } from './tradingTimeScale.js';
 import { scaleBand } from './bandScale.js';
 import { scaleElapsed } from './elapsed.js';
@@ -52,8 +52,75 @@ function normalizeRange(range) {
  * 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 function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor: cursorProp, cursorSequence: cursorSequenceProp, onRegionSelect, regionSelectModifier, cursorTime: cursorTimeProp, crosshairSnap: crosshairSnapProp, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat: cursorFormatProp, origin, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
+export function ChartContainer(props) {
+    const { width } = props;
+    // The measure pass is a *different component* rather than a branch inside
+    // the resolved one, because the resolved container may not render at all
+    // until a width exists — and ~60 hooks cannot be conditional. Choosing the
+    // component by the prop's kind (number vs auto) means flipping a container
+    // between fixed and auto remounts it; that is a layout change, and a
+    // remount is the honest response to one.
+    if (typeof width === 'number') {
+        return _jsx(ResolvedChartContainer, { ...props, width: width });
+    }
+    return _jsx(AutoWidthContainer, { ...props });
+}
+/**
+ * The `width="auto"` half: render a plain full-width box, measure it, and
+ * mount the chart at that pixel width.
+ *
+ * Three details, each of which the shipped
+ * [responsive-width recipe](https://pond-ts.github.io/pond/docs/recipes/responsive-width)
+ * had to spell out for consumers and which now hold by construction:
+ *
+ * 1. **`useLayoutEffect`, so the first real width lands before paint** — no
+ *    flash of the empty box.
+ * 2. **Measure synchronously on mount, then let `ResizeObserver` take over.**
+ *    RO's own first callback is not guaranteed to fire promptly in every
+ *    browser; relying on it alone can leave a chart that never mounts.
+ * 3. **The measured box is plain.** No padding, no border — so
+ *    `getBoundingClientRect().width` is the content width, and the chart can
+ *    never overflow its own measurement. A caller who wants a bordered frame
+ *    puts it on a wrapper *outside* the container.
+ */
+function AutoWidthContainer(props) {
+    const boxRef = useRef(null);
+    const [measured, setMeasured] = useState(0);
+    useLayoutEffect(() => {
+        const el = boxRef.current;
+        if (el === null)
+            return;
+        const measure = () => setMeasured((prev) => {
+            const next = Math.round(el.getBoundingClientRect().width);
+            // **Latch the last non-zero width.** A box measures 0 whenever it is
+            // not laid out — most often because an ancestor went `display: none`
+            // (a tab switch, a collapsed accordion), which is a *hidden* chart,
+            // not a resized one. Writing that 0 through would unmount the resolved
+            // container and discard everything it owns: pan/zoom position,
+            // selection, hover, and every layer's memoized draw state, all
+            // rebuilt on the way back. Keeping the stale width holds the chart
+            // mounted through the hide, and the next real measurement corrects it.
+            return next > 0 ? next : prev;
+        });
+        measure();
+        // Guarded rather than assumed: a non-browser render target (SSR, an older
+        // test DOM) has no ResizeObserver, and a chart that measured once is a far
+        // better failure than one that throws on mount.
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const ro = new ResizeObserver(measure);
+        ro.observe(el);
+        return () => ro.disconnect();
+    }, []);
+    return (_jsx("div", { ref: boxRef, style: { width: '100%' }, children: measured > 0 && _jsx(ResolvedChartContainer, { ...props, width: measured }) }));
+}
+/** {@link ChartContainer} with its width resolved to a concrete pixel number. */
+function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidth, bandAlign = 'start', width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor: cursorProp, cursorSequence: cursorSequenceProp, onRegionSelect, regionSelectModifier, cursorTime: cursorTimeProp, crosshairSnap: crosshairSnapProp, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat: cursorFormatProp, origin, theme, discontinuities, calendar, spacing, xScale: xScaleKind = 'linear', grid = true, sessionDividers = 'none', children, }) {
     // ── Legacy cursor props (deprecated) ───────────────────────────────────────
     // The string surface keeps working for one minor: the resolved mode is
     // synthesized into the equivalent mounted preset below (`<LegacyCursor>`),
@@ -61,6 +128,19 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
     // *explicitly* set (never on the defaults). Mounted cursor components in the
     // same scope override the shim. See docs/rfcs/interaction.md §9 / A4.4.
     const cursor = cursorProp ?? DEFAULT_CURSOR_MODE;
+    // [PND-IGNITECAT] The declared slot list, normalized to `null` when absent
+    // and held by **content** identity. An inline `categories={['a', 'b']}` is a
+    // fresh array every render; keying the kind/scale memos off the raw prop
+    // would rebuild the band scale — and therefore repaint every row — on every
+    // parent render, which is the shape of bug the `<Legend>` items array hit.
+    //
+    // JSON, not `join` — a separator collides (`['a b','c']` and `['a','b c']`
+    // join identically), and a category label containing a space is not a
+    // hypothetical for venue or instrument names.
+    const categoriesKey = categoriesProp === undefined ? null : JSON.stringify(categoriesProp);
+    const declaredCategories = useMemo(() => categoriesProp === undefined ? null : [...categoriesProp], 
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- content identity
+    [categoriesKey]);
     const cursorTime = cursorTimeProp ?? false;
     const crosshairSnap = crosshairSnapProp ?? true;
     const warnedLegacyRef = useRef(false);
@@ -347,6 +427,39 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
     // — a mix is a hard error. Defaults to `'time'` until a layer registers (the
     // two-pass: register → re-resolve → rescale).
     const resolvedKind = useMemo(() => {
+        // [PND-IGNITECAT] A container-level `categories` *declares* the ordinal
+        // axis rather than inferring it, which is what lets a non-category layer
+        // join one. A value-keyed layer is compatible by construction: the band
+        // scale's domain is numeric (`[0, n]`, slot `i` at `[i, i+1]`) with a
+        // linear pixel mapping, so a ValueSeries keyed on slot coordinates already
+        // lands where the bars do. A time-keyed layer is not — a timestamp has no
+        // slot — so that stays the hard error a mixed kind always was.
+        if (declaredCategories !== null) {
+            for (const s of sources.values()) {
+                if (s.xKind === 'time') {
+                    throw new Error(`ChartContainer: a time-keyed layer cannot plot on a category ` +
+                        `axis. This container declares \`categories\`, so its x axis is ` +
+                        `ordinal slots — key the layer to a ValueSeries on slot ` +
+                        `coordinates instead (slot i's centre is i + 0.5).`);
+                }
+                // No guard here for a **horizontal categorical `<BarChart>`**, whose x
+                // is bar *length* rather than a coordinate and which therefore draws
+                // nonsense on an ordinal x. One was written and removed: it tested
+                // `binCategories`, and that is the generic "**my y** is ordinal"
+                // channel — a *vertical* heat map sets it too (`HeatMap.tsx:361`, its
+                // rows), so the guard rejected a `ValueSeries` grid with named columns
+                // on x. That is a legitimate and wanted layout, not a contradiction:
+                // ordinal rows and ordinal columns is simply a 2-D grid.
+                //
+                // The framing was the error. There is no contradiction to detect,
+                // because nothing on a layer source distinguishes "my x is a
+                // coordinate" from "my x is a magnitude", and inventing a flag to
+                // carry that for one guard buys a false sense of coverage — every
+                // *other* misuse of the value-layer allowance stays silent regardless.
+                // The hazard is documented on the prop instead ([PND-IGNITECAT]).
+            }
+            return 'category';
+        }
         let kind;
         for (const s of sources.values()) {
             if (kind === undefined)
@@ -354,31 +467,44 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
             else if (kind !== s.xKind) {
                 throw new Error(`ChartContainer: rows mix x-axis kinds ('${kind}' and '${s.xKind}'). ` +
                     `A container has one shared x axis — every row must plot the same ` +
-                    `kind (all time-keyed, all value-keyed, or all category).`);
+                    `kind (all time-keyed, all value-keyed, or all category). ` +
+                    `To put value-keyed layers on an ordinal axis, declare the slots ` +
+                    `on the container: <ChartContainer categories={[…]}>.`);
             }
         }
         return kind ?? 'time';
-    }, [sources]);
+    }, [sources, declaredCategories]);
     // A `'category'` container's ordered category names — the ordinal axis domain.
     // Every category layer must agree on the same list (a mix is an error, like the
     // kind), so the shared band scale has one authoritative slot order. `null` when
     // no category layer has registered (or the kind isn't category).
+    //
+    // [PND-IGNITECAT] The container's own `categories` prop, when given, is the
+    // authority: layer-derived lists are then *validated* against it rather than
+    // being the source. Reconciling both directions in one pass keeps a single
+    // error message for a disagreement, whichever side is wrong.
     const categories = useMemo(() => {
-        let cats = null;
+        const same = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+        let cats = declaredCategories;
         for (const s of sources.values()) {
             const c = s.xCategories?.() ?? null;
             if (c === null)
                 continue;
             if (cats === null)
                 cats = c;
-            else if (cats.length !== c.length || cats.some((v, i) => v !== c[i])) {
-                throw new Error(`ChartContainer: category rows disagree on the axis categories. ` +
-                    `Every category layer in one container must share the same ordered ` +
-                    `column set (got [${cats.join(', ')}] and [${c.join(', ')}]).`);
+            else if (!same(cats, c)) {
+                throw new Error(declaredCategories !== null
+                    ? `ChartContainer: a category layer's columns disagree with the ` +
+                        `container's \`categories\`. The container's list is ` +
+                        `authoritative, so they must match in order (container ` +
+                        `[${declaredCategories.join(', ')}], layer [${c.join(', ')}]).`
+                    : `ChartContainer: category rows disagree on the axis categories. ` +
+                        `Every category layer in one container must share the same ordered ` +
+                        `column set (got [${cats.join(', ')}] and [${c.join(', ')}]).`);
             }
         }
         return cats;
-    }, [sources]);
+    }, [sources, declaredCategories]);
     // Auto-fit extent — the union of the layers' x extents — used as the domain
     // when no explicit `range` is given. (Same source registry as the kind; the
     // two-pass register→resolve applies.)
@@ -801,7 +927,30 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
             };
         }
         if (resolvedKind === 'value') {
-            const s = scaleLinear().domain([d0, d1]).range([0, plotWidth]);
+            // `scaleLog` / `scaleSymlog` share d3's continuous-scale surface — the
+            // call signature, `invert`, `ticks`, `domain`, `range` — so nothing
+            // downstream branches on which one this is. That is the whole of log
+            // support at the scale layer; the work is in the arithmetic that reads
+            // the domain (see `ViewportOptions`) and in the tick ladder.
+            //
+            // A log scale cannot represent a non-positive domain, and silently
+            // clamping would invent a view the caller did not ask for. So fall back
+            // to linear and say so, matching how `<YAxis scale="log">` behaves.
+            const wantsLog = xScaleKind !== 'linear';
+            const logUsable = xScaleKind === 'symlog' || (d0 > 0 && d1 > 0);
+            if (isDev && wantsLog && !logUsable) {
+                console.warn(`<ChartContainer xScale="log">: the x domain [${d0}, ${d1}] includes ` +
+                    'zero or a negative value, which a log scale cannot represent. ' +
+                    'Falling back to a linear x axis — use xScale="symlog" for data ' +
+                    'that crosses zero.');
+            }
+            const s = (!wantsLog || !logUsable
+                ? scaleLinear()
+                : xScaleKind === 'symlog'
+                    ? scaleSymlog()
+                    : scaleLog())
+                .domain([d0, d1])
+                .range([0, plotWidth]);
             if (elapsedOrigin !== undefined) {
                 // Offset (elapsed) value axis: same pixels, ticks anchored at the
                 // origin, labels reading `v - origin`. A `timeFormat` / `cursorFormat`
@@ -1019,6 +1168,34 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         const values = Array.from(sources.values()).flatMap((s) => s.sampleAt(time));
         cb({ time, values });
     }, [cursorX, xScale, sources, plotWidth]);
+    // Structural, not `xScaleKind !== 'linear'`: a log scale asked for over a
+    // non-positive domain falls back to linear above, and the gestures must see
+    // what was actually built rather than what was requested. `base()` exists on
+    // d3's log scales and on no other continuous scale — the same test the y side
+    // already uses in `yticks.ts`.
+    // Both probes, because d3 splits them: `base()` is on `scaleLog` and
+    // `constant()` on `scaleSymlog` — the same pair `tickValues` tests.
+    // `xScale` shapes the VALUE axis only — a logarithmic time axis is
+    // meaningless and a category axis has its own band spacing. Saying so out
+    // loud rather than ignoring the prop: a request that quietly does nothing is
+    // the failure mode `panZoom2D` shipped with, where a mode named two axes and
+    // silently moved one.
+    // `sources.size > 0` because `resolvedKind` falls back to 'time' until the
+    // layers have registered — without the guard this fires once on every mount,
+    // including the valid ones.
+    if (isDev &&
+        xScaleKind !== 'linear' &&
+        sources.size > 0 &&
+        resolvedKind !== 'value') {
+        console.warn(`<ChartContainer xScale="${xScaleKind}">: ignored on a ${resolvedKind} ` +
+            'x axis — it applies to a value axis only. A `TimeSeries` gives a time ' +
+            'axis; key the data on the quantity itself (a `ValueSeries`) to get a ' +
+            'value axis you can scale.');
+    }
+    const xIsLog = ((s) => {
+        const probe = s;
+        return (typeof probe.base === 'function' || typeof probe.constant === 'function');
+    })(xScale);
     // Pack overlapping top-flag labels (markers + regions) into stacked lanes so
     // close-in-x labels don't collide; chips read their lane back off the frame.
     const labelLanes = useMemo(() => computeLabelLanes(annotations, (v) => xScale(v), draggingKey, plotWidth), [annotations, xScale, draggingKey]);
@@ -1112,6 +1289,7 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         zoomEnabled,
         minDuration,
         applyRange,
+        xIsLog,
         zoomX,
         zoomY,
         panX,
@@ -1191,6 +1369,7 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         zoomEnabled,
         minDuration,
         applyRange,
+        xIsLog,
         zoomX,
         zoomY,
         panX,

package/dist/ChartRow.js

@@ -453,6 +453,7 @@ export function ChartRow({ height, cursor, children }) {
     }, [effectiveAxes]);
     const frame = useMemo(() => ({
         height,
+        topInset: topHeader,
         cursor,
         isFirstRow,
         rowKey,
@@ -470,6 +471,7 @@ export function ChartRow({ height, cursor, children }) {
         layers: layerList,
     }), [
         height,
+        topHeader,
         cursor,
         isFirstRow,
         rowKey,