@pond-ts/charts 0.58.0 → 0.60.0

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

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, Fragment, isValidElement, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
-import { scaleLinear, scaleLog } from 'd3-scale';
+import { scaleLinear, scaleLog, scaleSymlog } from 'd3-scale';
 import { isDev } from './dev.js';
 import { useIndexedChildren } from './child-index.js';
 import { logAxisWarning, needsExtents, resolveYDomain } from './domain.js';
@@ -11,6 +11,41 @@ import { useSlotKey } from './use-slot-key.js';
 import { LegacyCursor } from './cursors.js';
 import { YAxis } from './YAxis.js';
 import { ContainerContext, RowContext, } from './context.js';
+/**
+ * `scale="symlog"`'s default linear window — the knee at **2% of the domain's
+ * largest magnitude** ([PND-SYMLOG]). Chosen because it is what the reporting
+ * consumer's own transform used (`maxAbs / 50`), and confirmed with them as
+ * generalizing: every caller they had passed the data's own max-abs, and none
+ * had a case for an absolute constant.
+ */
+const DEFAULT_LINEAR_WINDOW = 0.02;
+/**
+ * `scaleSymlog`'s `constant` (the linear window's half-width in data units) for
+ * an axis's domain-relative {@link YAxisProps.linearWindow} ([PND-SYMLOG]).
+ *
+ * **The clamp is the point.** d3's symlog transform is
+ * `sign(x)·log1p(|x / constant|)`, so a `constant` of `0` — or of
+ * `Number.MIN_VALUE`, which the first version of this "clamped" to — divides
+ * every sample by ~zero, and `(∞ − ∞) / (∞ − ∞)` makes **every mapped pixel
+ * `NaN`**: a blank plot, `NaN` gridline coordinates, no error. That is strictly
+ * worse than the mistake it was guarding, so an unusable fraction (non-finite,
+ * `<= 0`, or `> 1`) falls back to the **default** and dev-warns (see the
+ * `linearWindow` diagnostics below) rather than being nudged to a value that
+ * technically satisfies `> 0`.
+ *
+ * A degenerate all-zero domain has no magnitude to take a fraction *of*, so the
+ * knee falls back to `1`; the axis is linear across it either way.
+ */
+function symlogConstant(linearWindow, lo, hi) {
+    const usable = linearWindow !== undefined &&
+        Number.isFinite(linearWindow) &&
+        linearWindow > 0 &&
+        linearWindow <= 1;
+    const fraction = usable ? linearWindow : DEFAULT_LINEAR_WINDOW;
+    const maxAbs = Math.max(Math.abs(lo), Math.abs(hi));
+    const knee = fraction * maxAbs;
+    return Number.isFinite(knee) && knee > 0 ? knee : 1;
+}
 /** Sentinel id for the implicit axis a row gets when no `<YAxis>` is declared. */
 const IMPLICIT_AXIS_ID = '__default__';
 /** Element-wise compare of two optional number arrays (an axis's tick values) —
@@ -43,6 +78,10 @@ function axisSpecEqual(a, b) {
         a.side === b.side &&
         a.width === b.width &&
         a.scale === b.scale &&
+        // Easy to forget when adding a scale-shaping field, and the failure is
+        // silent: an axis whose `linearWindow` alone changed would be discarded by
+        // the guard and keep drawing with the previous knee.
+        a.linearWindow === b.linearWindow &&
         // Object.is (not ===) so a degenerate NaN bound compares equal to itself and
         // doesn't re-register every render.
         Object.is(a.min, b.min) &&
@@ -253,7 +292,16 @@ export function ChartRow({ height, cursor, children }) {
             // `scaleLog` and `scaleLinear` share the call/ticks/tickFormat/invert
             // surface every consumer uses (see `YScale`), so choosing between them
             // here is the whole of log support — no draw layer branches on it.
-            const base = ax.scale === 'log' ? scaleLog() : scaleLinear();
+            // `scaleSymlog` shares the same call/ticks/tickFormat/invert surface, so
+            // as with log, choosing it here is the whole of symlog support — no draw
+            // layer branches on it. Its `constant` (the linear window's half-width) is
+            // resolved from the axis's DOMAIN-RELATIVE fraction: absolute would need
+            // recomputing whenever the domain moved ([PND-SYMLOG]).
+            const base = ax.scale === 'log'
+                ? scaleLog()
+                : ax.scale === 'symlog'
+                    ? scaleSymlog().constant(symlogConstant(ax.linearWindow, lo, hi))
+                    : scaleLinear();
             const s = base.domain([lo, hi]).range([height, topHeader]);
             // 2-D pan/zoom is carried as a **pixel** transform (`k`, `ty`) so one
             // gesture serves every axis in the row whatever its units, and all of them
@@ -319,6 +367,46 @@ export function ChartRow({ height, cursor, children }) {
             }
         }
     }, [effectiveAxes, layerList, defaultAxisId]);
+    // Dev-mode diagnostics for `linearWindow` ([PND-SYMLOG]). Both cases it covers
+    // are *silent* otherwise, which is the whole reason it exists: a
+    // `linearWindow` on a linear or log axis is read by nothing, and a fraction
+    // outside `(0, 1]` is unusable as a knee (see `symlogConstant`), so the axis
+    // silently draws with the **default** window instead of the one asked for.
+    // Neither throws and neither looks broken — it just isn't the scale the call
+    // site asked for.
+    //
+    // Same shape as the log diagnostics above: an effect rather than the memo, and
+    // deduped in `warnedRef` under a suffixed key so it cannot collide with the
+    // log message stored under the bare axis id.
+    useEffect(() => {
+        if (!isDev)
+            return;
+        const warned = warnedRef.current;
+        for (const ax of effectiveAxes) {
+            const key = `${ax.id}:linearWindow`;
+            const w = ax.linearWindow;
+            let message = null;
+            if (w !== undefined && ax.scale !== 'symlog') {
+                message =
+                    `<YAxis id="${ax.id}"> sets linearWindow=${w} but scale is ` +
+                        `"${ax.scale}" — linearWindow only applies to scale="symlog" and is ` +
+                        `ignored here.`;
+            }
+            else if (w !== undefined && (!Number.isFinite(w) || w <= 0 || w > 1)) {
+                message =
+                    `<YAxis id="${ax.id}"> has linearWindow=${w}, outside (0, 1] — the ` +
+                        `axis is drawing with the default ${DEFAULT_LINEAR_WINDOW} instead. ` +
+                        `It is a fraction of the domain's largest magnitude, so 0.02 means ` +
+                        `"linear through 2% of the domain".`;
+            }
+            if (message === null)
+                warned.delete(key);
+            else if (warned.get(key) !== message) {
+                warned.set(key, message);
+                console.warn(message);
+            }
+        }
+    }, [effectiveAxes]);
     // Resolved auto-tick count per axis — explicit `<YAxis tickCount>` else
     // height-derived (see resolveYTickCount). The single source the `<YAxis>`
     // labels, the readout formatter (below), and the `Layers` gridlines all read,
@@ -365,6 +453,7 @@ export function ChartRow({ height, cursor, children }) {
     }, [effectiveAxes]);
     const frame = useMemo(() => ({
         height,
+        topInset: topHeader,
         cursor,
         isFirstRow,
         rowKey,
@@ -382,6 +471,7 @@ export function ChartRow({ height, cursor, children }) {
         layers: layerList,
     }), [
         height,
+        topHeader,
         cursor,
         isFirstRow,
         rowKey,

package/dist/Layers.js

@@ -9,7 +9,8 @@ import { resolveSelection } from './select.js';
 import { isDev } from './dev.js';
 import { useIndexedChildren } from './child-index.js';
 import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
-import { yTickValues } from './yticks.js';
+// Aliased: `tickValues` is already a local map of per-axis explicit ticks.
+import { tickValues as axisTickValues } from './yticks.js';
 import { ContainerContext, CursorContext, LayersContext, RowContext, } from './context.js';
 /** Fallback **y**-gridline tick count, used only before the row publishes its
  *  resolved `tickCounts` (pre-registration). Normally the gridlines read the
@@ -240,7 +241,7 @@ export function Layers({ children }) {
             // a gridline sits under every `<YAxis>` label and no more.
             const yCount = tickCounts.get(defaultAxisId) ?? GRID_TICKS;
             const yTicks = gridY && !(yIsCategory && explicitY === undefined)
-                ? (explicitY ?? yTickValues(gridY, yCount)).map((t) => gridY(t))
+                ? (explicitY ?? axisTickValues(gridY, yCount)).map((t) => gridY(t))
                 : [];
             // On a calendar axis the verticals are the FULL grain populations —
             // every day in the month, every month in the year, every aligned
@@ -1078,7 +1079,13 @@ export function Layers({ children }) {
             else {
                 const span = drag.startRange[1] - drag.startRange[0];
                 const dt = c.plotWidth > 0 ? -dx * (span / c.plotWidth) : 0;
-                c.applyRange(panRange(drag.startRange, dt));
+                // A log x pans by ratio, not by offset — see `ViewportOptions`.
+                // `snap` follows: whole-millisecond snapping is a time-axis rule and
+                // wrong for any value axis, log or not.
+                c.applyRange(panRange(drag.startRange, dt, {
+                    log: c.xIsLog,
+                    snap: c.xKind === 'time',
+                }));
             }
             return; // tracker suppressed during a pan
         }
@@ -1467,7 +1474,10 @@ export function Layers({ children }) {
                     // the minimum visible *trading* time (ms of open-market time)
                     // rather than wall-clock ms — the sensible meaning for this axis.
                     zoomRangeTrading(c.timeRange, pivot, f, c.discontinuities, c.minDuration)
-                : zoomRange(c.timeRange, pivot, f, c.minDuration);
+                : zoomRange(c.timeRange, pivot, f, c.minDuration, {
+                    log: c.xIsLog,
+                    snap: c.xKind === 'time',
+                });
             // ── The aspect lock has to be NEGOTIATED, not asserted ────────────────
             // Both axes zooming by "the same factor" only holds the ratio while both
             // can actually take that factor. Each has its own limit — y cannot zoom

package/dist/XAxis.js

@@ -3,6 +3,7 @@ import { Fragment, useContext } from 'react';
 import { scaleLinear } from 'd3-scale';
 import { derivedTicks } from './derivedTicks.js';
 import { ContainerContext, CursorContext, } from './context.js';
+import { tickValues } from './yticks.js';
 import { xAxisCursorEntries } from './cursors.js';
 import { axisPillStyle } from './chip.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
@@ -261,20 +262,24 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
         ? customTicks.map((t) => ({ x: xScale(t.at), label: t.label }))
         : derived !== null
             ? honestDerived()
-            : xScale.ticks(xTickCount).map((d) => ({
-                x: xScale(d),
-                label: tickFmt(+d),
-                // A **period turn** renders emphasized (bold), consistently across
-                // styles: in stacked, a tick on a band divider (matched by pixel);
-                // in flat, a tick whose label was *promoted* to a coarser period
-                // (its flat label differs from the terse base) — the same boundaries,
-                // so `Feb` / `2026` read as strong in flat just as the band turns do.
-                bold: stacked
-                    ? dividerXs.has(Math.round(xScale(d)))
-                    : flatFmt !== undefined &&
-                        baseFmt !== undefined &&
-                        flatFmt(+d) !== baseFmt(+d),
-            }));
+            : // `tickValues`, not `xScale.ticks` — d3's raw `scaleLog.ticks()` is
+                // nearly a step function (see `yticks.ts`), so a log x needs the same
+                // decade ladder the y axis already builds. For a time or linear scale
+                // it defers to `scale.ticks(count)`, so this is a no-op there.
+                tickValues(xScale, xTickCount).map((d) => ({
+                    x: xScale(d),
+                    label: tickFmt(+d),
+                    // A **period turn** renders emphasized (bold), consistently across
+                    // styles: in stacked, a tick on a band divider (matched by pixel);
+                    // in flat, a tick whose label was *promoted* to a coarser period
+                    // (its flat label differs from the terse base) — the same boundaries,
+                    // so `Feb` / `2026` read as strong in flat just as the band turns do.
+                    bold: stacked
+                        ? dividerXs.has(Math.round(xScale(d)))
+                        : flatFmt !== undefined &&
+                            baseFmt !== undefined &&
+                            flatFmt(+d) !== baseFmt(+d),
+                }));
     // A category axis ticks once per category; thin + truncate its labels when they
     // crowd (an explicit `customTicks` axis keeps its labels verbatim).
     const placed = xKind === 'category' && customTicks === undefined && rawTicks.length > 1

package/dist/YAxis.d.ts

@@ -46,8 +46,64 @@ export interface YAxisProps {
      *
      * A dev-mode warning fires for the cases that are unambiguously a mistake: a
      * refused bound, negative data, or an axis with no positive data at all.
+     *
+     * `'symlog'` is **linear through zero, logarithmic beyond** — for data that
+     * spans orders of magnitude *on both sides of zero*, which `'log'` cannot
+     * express at all (it admits no zero and no negatives). The linear window is
+     * {@link linearWindow}. Because it admits zero, it resolves its domain on the
+     * ordinary **linear** path: no positive-only bound refusal, no rounding out to
+     * decades, no gapping of non-positive samples.
+     *
+     * **The axis owns tick placement, and that is the substance of the feature.**
+     * d3's symlog supplies the transform but ticks it *linearly*, which on a ±1M
+     * domain with a 20k knee labels nothing below the knee — the exact region the
+     * scale was chosen to reveal. pond grids it on zero, the knee (±`linearWindow ×
+     * maxAbs`) and mirrored decades beyond, thinned by the same rule the log axis
+     * uses. See `yticks.ts`.
+     *
+     * **The curve is `log1p`, not piecewise — read this before replacing a
+     * hand-rolled one.** "Linear through zero, logarithmic beyond" describes how the
+     * axis *reads*, not two joined segments: `scaleSymlog` is the single smooth
+     * `sign(x) · log1p(|x / knee|)`, so there is no exact boundary at which one law
+     * stops and the other starts. A common hand-rolled curve *is* piecewise —
+     * exactly linear below the knee, `log10` above — and the two are the same family
+     * with materially different shape. Swapping one for the other, a reporting
+     * consumer measured small values landing at **roughly half** their former height
+     * (a ±9M domain: 283k went from 0.44 to 0.24 of the half-plot above the zero
+     * line), while order, the dominance of the tail, and a several-fold lift over a
+     * linear axis all held — the chart still says the same thing, but it does not
+     * say it identically.
+     *
+     * **No `linearWindow` recovers a piecewise shape.** The same consumer tried: a
+     * smaller window fits the large values while overshooting the small ones about
+     * 2×, because the difference is the curve, not the knee. If you need the
+     * piecewise curve exactly, you need your own transform — which is the thing this
+     * scale exists to let you delete, so weigh that before reaching for it.
+     */
+    scale?: 'linear' | 'log' | 'symlog';
+    /**
+     * `scale="symlog"`'s **linear window**, as a fraction of the domain's largest
+     * magnitude. **Default `0.02`** — the knee sits at 2% of `maxAbs`, so a ±1M
+     * domain is linear through ±20k and logarithmic beyond. Ignored on any other
+     * scale.
+     *
+     * **Domain-relative, not absolute** (d3's own `constant` is absolute). A chart
+     * that re-keys to the largest magnitude on every update would otherwise need
+     * the constant recomputed each tick, and would drift silently the moment
+     * someone forgot — the fraction survives a domain change with no call-site
+     * arithmetic at all.
+     *
+     * Precisely: a fraction of the **resolved domain before any pan/zoom** — the
+     * one the axis's `min`/`max`/`pad`/auto-fit produce. A 2-D gesture is carried
+     * as a *pixel* transform and the knee is deliberately **not** recomputed from
+     * the zoomed window, so zooming moves the plot without moving the boundary
+     * between the two régimes underneath it. (Recomputing would make the same
+     * datum linear at one zoom level and logarithmic at the next.)
+     *
+     * A value outside `(0, 1]` cannot be a knee; the axis draws with the default
+     * instead and dev-warns which window is in force.
      */
-    scale?: 'linear' | 'log';
+    linearWindow?: number;
     /** Explicit domain bounds; omit to auto-fit the charts linked to this axis. */
     min?: number;
     max?: number;
@@ -155,5 +211,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, scale, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function YAxis({ id, side, label, scale, linearWindow, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -3,7 +3,7 @@ import { useContext, useEffect, useMemo } from 'react';
 import { ContainerContext, RowContext } from './context.js';
 import { resolveAxisFormat } from './format.js';
 import { useSlotKey } from './use-slot-key.js';
-import { yTickValues } from './yticks.js';
+import { tickValues } from './yticks.js';
 const DEFAULT_WIDTH = 50;
 /** Fallback tick count before the row has published its resolved count (the
  *  first render, pre-registration). The row's height-derived value takes over
@@ -17,7 +17,7 @@ const DEFAULT_TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, index = 0, }) {
+export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow, min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -35,6 +35,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
         // and layers still bind to it, which is the whole point of the prop.
         width: hide ? 0 : width,
         scale,
+        linearWindow,
         min,
         max,
         pad,
@@ -49,6 +50,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
         width,
         hide,
         scale,
+        linearWindow,
         min,
         max,
         pad,
@@ -112,7 +114,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
         ? ticks.map((t) => ({ value: t.at, label: t.label }))
         : layerCategories !== null
             ? layerCategories.map((label, i) => ({ value: i + 0.5, label }))
-            : (yScale ? yTickValues(yScale, count) : []).map((t) => ({
+            : (yScale ? tickValues(yScale, count) : []).map((t) => ({
                 value: t,
                 label: fmt(t),
             }));