@pond-ts/charts 0.57.0 → 0.59.0

package/dist/ChartRow.d.ts

@@ -3,8 +3,15 @@ import { type CursorMode } from './context.js';
 export interface ChartRowProps {
     /** Row height in CSS pixels. */
     height: number;
-    /** Cursor presentation for this row, overriding the container's default
-     *  ({@link ChartContainerProps.cursor}). Omit to inherit. See {@link CursorMode}. */
+    /**
+     * Cursor presentation for this row, overriding the container's default
+     * ({@link ChartContainerProps.cursor}). Omit to inherit. See {@link CursorMode}.
+     *
+     * @deprecated Mount a cursor component **inside the row** instead
+     * (`<ChartRow><CrosshairCursor /> …</ChartRow>`) — the per-row override with
+     * the same nearest-mount-wins semantics. Works for one more minor; a mounted
+     * cursor in the row overrides this prop.
+     */
     cursor?: CursorMode;
     children?: ReactNode;
 }

package/dist/ChartRow.js

@@ -1,14 +1,51 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
-import { scaleLinear, scaleLog } from 'd3-scale';
+import { Children, Fragment, isValidElement, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+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';
 import { resolveAxisFormat } from './format.js';
 import { resolveYTickCount } from './yticks.js';
 import { placeAxisSlots } from './slots.js';
 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) —
@@ -41,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) &&
@@ -104,6 +145,18 @@ export function ChartRow({ height, cursor, children }) {
     const { registerRow } = container;
     useEffect(() => registerRow(rowKey), [registerRow, rowKey]);
     const isFirstRow = container.firstRowKey === rowKey;
+    // Deprecation notice for the legacy `cursor` prop (dev, once per row): the
+    // per-row override is now a cursor component mounted inside the row. The
+    // prop keeps working via the shim rendered below.
+    const warnedCursorRef = useRef(false);
+    useEffect(() => {
+        if (!isDev || cursor === undefined || warnedCursorRef.current)
+            return;
+        warnedCursorRef.current = true;
+        console.warn(`[pond-charts] <ChartRow cursor="${cursor}"> is deprecated (it keeps ` +
+            'working this minor, removed next) — mount the cursor component ' +
+            'inside the row instead (docs/rfcs/interaction.md §9).');
+    }, [cursor]);
     // Keyed by a stable per-instance id (Map preserves insertion order; setting an
     // existing key updates in place). So a re-register on a prop change keeps the
     // entry's slot — the axis-default (first axis) and layer z-order stay stable
@@ -222,6 +275,7 @@ export function ChartRow({ height, cursor, children }) {
     // One y-scale per axis. A layer counts toward an axis when its (late-resolved)
     // axis id matches; `resolveYDomain` handles the auto-fit + empty/flat/inverted
     // edges. yExtent() is O(points), so only walk the layers when a bound auto-fits.
+    const { k: yk, ty: yty } = container.yTransform;
     const yScales = useMemo(() => {
         const map = new Map();
         for (const ax of effectiveAxes) {
@@ -238,11 +292,37 @@ 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();
-            map.set(ax.id, base.domain([lo, hi]).range([height, topHeader]));
+            // `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
+            // zoom by the same factor — which is what fixes the aspect ratio. But it is
+            // applied by narrowing the **domain** to the window that transform makes
+            // visible, not by stretching the range.
+            //
+            // That distinction is not cosmetic. Stretching the range leaves the tick
+            // generator working on the FULL domain, so ticks outside the view get
+            // clamped onto the plot edge and pile up — 350 and 400 printed on top of
+            // each other in the first cut. Narrowing the domain means ticks, padding
+            // and every downstream reader see an ordinary axis over the visible
+            // window, and none of them need to know a transform exists.
+            if (yk !== 1 || yty !== 0) {
+                const at = (px) => +s.invert((px - yty) / yk);
+                s.domain([at(height), at(topHeader)]);
+            }
+            map.set(ax.id, s);
         }
         return map;
-    }, [effectiveAxes, layerList, height, defaultAxisId, topHeader]);
+    }, [effectiveAxes, layerList, height, defaultAxisId, topHeader, yk, yty]);
     // Dev-mode diagnostics for a `scale="log"` axis (see `logAxisWarning`). Three
     // things about *where* this sits are load-bearing, each of them a bug the
     // first version shipped:
@@ -287,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,
@@ -369,9 +489,14 @@ export function ChartRow({ height, cursor, children }) {
     // Inject each direct child's JSX position so axes register their declaration
     // order (the default-axis source). `<Layers>` receives an index too (harmless
     // — it's not an axis) and injects its own into the draw layers.
-    const indexedChildren = Children.map(children, (child, index) => isValidElement(child)
-        ? cloneElement(child, { index })
-        : child);
+    //
+    // A fragment child costs more here than it does in `<Layers>`: the axes
+    // inside it lose the index *and* the `child.type === YAxis` sort below cannot
+    // see through it, so they fall into `plotEls` and render in the middle of the
+    // row instead of in a gutter. Hence the same warning on both.
+    const indexedChildren = useIndexedChildren(children, '<ChartRow>', 'the axes inside it lose their declaration order (the default-axis pick ' +
+        'and slot order within a side) and are placed in the plot rather than a ' +
+        'gutter, because the side sort cannot see through a fragment');
     // Place axes by their `side`, not by JSX author position — so a `side="right"`
     // axis always renders right of the plot (and a left axis left), **consistent
     // with the side-based gutter reservation above**. (Author position only
@@ -383,20 +508,57 @@ export function ChartRow({ height, cursor, children }) {
     const leftAxisEls = [];
     const plotEls = [];
     const rightAxisEls = [];
+    let axisInsideWrapper = false;
     for (const child of indexedChildren ?? []) {
         if (isValidElement(child) && child.type === YAxis) {
             const side = child.props.side ?? 'left';
             (side === 'right' ? rightAxisEls : leftAxisEls).push(child);
         }
         else {
+            // A `<Selector>`/`<MultiSelector>` is a legitimate row child now that it
+            // wraps its scope (RFC A10.1) — but it must wrap the row's `<Layers>`,
+            // NOT its axes: the sort above matches on `child.type`, so an axis
+            // nested inside any wrapper is invisible to it and lands in the plot
+            // column. The fragment warning cannot catch this one (a selector is a
+            // real element, not a fragment), and the failure is silent, so look one
+            // level down for the mistake the docs could invite.
+            // A fragment is skipped here: `useIndexedChildren` already warns about
+            // it and names the same gutter consequence, so checking it too would
+            // print two warnings for one mistake.
+            if (isDev &&
+                isValidElement(child) &&
+                child.type !== Fragment &&
+                !axisInsideWrapper) {
+                const nested = child.props.children;
+                if (nested !== undefined) {
+                    for (const g of Children.toArray(nested)) {
+                        if (isValidElement(g) && g.type === YAxis) {
+                            axisInsideWrapper = true;
+                            break;
+                        }
+                    }
+                }
+            }
             plotEls.push(child);
         }
     }
-    return (_jsx(RowContext.Provider, { value: frame, children: _jsxs("div", { style: {
-                display: 'flex',
-                flexDirection: 'row',
-                width: `${container.width}px`,
-                height: `${height}px`,
-            }, children: [leftPad > 0 && _jsx("div", { style: { flex: `0 0 ${leftPad}px` } }), leftAxisEls, plotEls, rightAxisEls, rightPad > 0 && _jsx("div", { style: { flex: `0 0 ${rightPad}px` } })] }) }));
+    const warnedAxisWrapperRef = useRef(false);
+    useEffect(() => {
+        if (!isDev || !axisInsideWrapper || warnedAxisWrapperRef.current)
+            return;
+        warnedAxisWrapperRef.current = true;
+        console.warn('[pond-charts] a <YAxis> is nested inside another element in this ' +
+            '<ChartRow>, so it renders in the plot column instead of a gutter — ' +
+            '<ChartRow> places axes by matching its own children, and cannot see ' +
+            'through a wrapper. A row-scoped <Selector>/<MultiSelector> should ' +
+            "wrap the row's <Layers>, leaving each <YAxis> a direct child of the " +
+            '<ChartRow>.');
+    }, [axisInsideWrapper]);
+    return (_jsxs(RowContext.Provider, { value: frame, children: [cursor !== undefined && (_jsx(LegacyCursor, { mode: cursor, showTime: container.cursorTime, snap: container.crosshairSnap })), _jsxs("div", { style: {
+                    display: 'flex',
+                    flexDirection: 'row',
+                    width: `${container.width}px`,
+                    height: `${height}px`,
+                }, children: [leftPad > 0 && _jsx("div", { style: { flex: `0 0 ${leftPad}px` } }), leftAxisEls, plotEls, rightAxisEls, rightPad > 0 && _jsx("div", { style: { flex: `0 0 ${rightPad}px` } })] })] }));
 }
 //# sourceMappingURL=ChartRow.js.map

package/dist/HeatMap.d.ts

@@ -0,0 +1,176 @@
+import { ValueSeries } from 'pond-ts';
+import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import type { DecimateOption } from './decimate.js';
+import type { Orientation } from './bars.js';
+import { type HeatNoData, type HeatScale } from './heat.js';
+export interface HeatMapProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
+    /**
+     * The source series. A **`TimeSeries`** puts time intervals on x, a
+     * **`ValueSeries`** puts value intervals on x — inferred, no axis-kind prop,
+     * the same rule `<BarChart>` uses.
+     *
+     * Because the cell spans are the ordinary bin spans, the whole of pond's
+     * binning machinery applies unchanged: `aggregate` over a trading calendar
+     * with sessions, `Sequence.calendar` day/week/month buckets, `byColumn` value
+     * bands. The heat map inherits all of it by having no opinion about x.
+     */
+    series: TimeSeries<S> | ValueSeries<VS>;
+    /**
+     * The numeric columns forming the **rows**, bottom → top — one row per
+     * column. Give one column for a single-row **stripe**; a stripe is just
+     * `columns.length === 1`, drawn by the same path.
+     *
+     * The y dimension must be columns, which is the layer's one real constraint.
+     * A month-of-year grid means a column per month; a per-city grid means a
+     * column per city (`pivotByGroup`'s long→wide output, or `partitionBy`
+     * reshaped). That keeps the second dimension in the data model, where pond's
+     * own reshaping operators can produce it, rather than inventing a
+     * chart-level pivot.
+     *
+     * Row `0` is at the **bottom**, matching the band-axis convention; reverse
+     * the list to read top-down.
+     */
+    columns: readonly string[];
+    /**
+     * The colour ramp, low → high. The value domain splits into `colors.length`
+     * equal bands and a cell takes its band's colour (see {@link bandedColor}).
+     * A diverging ramp is just a ramp whose middle is pale.
+     */
+    colors: readonly string[];
+    /**
+     * Pin the colour domain as `[lo, hi]`. **Omitted ⇒ the finite extent across
+     * the whole grid**, so every row is read against one scale and rows are
+     * comparable to each other.
+     *
+     * Pin it when two charts must be read against each other, or when the window
+     * is a slice of a longer record and the colours should not re-mean themselves
+     * as it moves — a colour scale has no tick labels to reveal that it moved.
+     */
+    domain?: readonly [number, number];
+    /**
+     * Which axis carries the **bins**. `'vertical'` (the default) puts them on
+     * **x** with the columns as rows down y; `'horizontal'` transposes — bins run
+     * down **y** and the columns become the categories along x.
+     *
+     * The transpose is cheaper here than for `<BarChart>`, because a heat map has
+     * two *position* axes and no value axis: nothing has to change which scale it
+     * is measured against, only which one is horizontal on the canvas.
+     *
+     * Reach for `'horizontal'` when the binned dimension is the long one and the
+     * columns are few — a gene-expression matrix (thousands of gene buckets, a
+     * handful of samples) is the canonical case, and it is the orientation that
+     * literature draws. Note that the bins still come from the **key** axis, so
+     * the genes must be the series' rows and the samples its columns; the
+     * ordinary binning operators (`byColumn`, `aggregate`) then bucket them.
+     */
+    orientation?: Orientation;
+    /** Semantic identifier — picks geometry defaults off `theme.bar[as]`. */
+    as?: string;
+    /** Which `<YAxis>` (by `id`) this layer scales against. */
+    axis?: string;
+    /** Px inset around each cell. **Omitted ⇒ `0`**, tiling flush. */
+    gap?: number;
+    /**
+     * How value maps onto the ramp's bands. **Omitted ⇒ `'linear'`** — equal-width
+     * bands across the domain.
+     *
+     * `'log'` gives equal-*ratio* bands, which is what a quantity spanning orders
+     * of magnitude needs. US measles incidence runs from ~2,900 per 100k before
+     * the vaccine to under 1 after it; linear banding over eight colours puts
+     * everything below ~360 into a single band — the entire post-1965 record,
+     * which is the half of that chart carrying the finding.
+     *
+     * Bands on `log1p` of the offset from the domain's floor, so a value **at**
+     * the floor is a real band rather than `-Infinity`. Zero is the case that
+     * needs it: an incidence grid is mostly zeros once a disease is eliminated,
+     * and those cells are the point.
+     */
+    scale?: HeatScale;
+    /**
+     * How a cell with no value is drawn. **Omitted ⇒ `'blank'`** — nothing is
+     * painted and the background shows through, which is right when a hole simply
+     * means "outside the record".
+     *
+     * `'hatch'` draws diagonal lines in the theme's grid colour. Reach for it when
+     * *missing* and *low* would otherwise be indistinguishable — on a pale ramp
+     * "draw nothing" reads as the bottom of the scale, so a state with no
+     * surveillance yet looks exactly like a state reporting zero cases. No ramp
+     * colour can be mistaken for hatching, which is why it is the convention.
+     *
+     * Suppressed while decimated: an aggregated cell is not a hole.
+     */
+    noData?: HeatNoData;
+    /**
+     * Viewport decimation — **on by default**, and a perf knob rather than a
+     * rendering-style one.
+     *
+     * Once the visible cells are denser than ~2 per device pixel they overlap and
+     * overpaint each other, so what you see is already one cell per column picked
+     * by draw order. Decimation replaces that with the **mean** per pixel column
+     * — what the overdrawn picture resolves to at that size — from `O(W·G)` rects
+     * instead of `O(V·G)`. A 20,000-bin grid over an 800px plot goes from ~48ms
+     * to a fraction of it.
+     *
+     * `{ threshold }` moves the cells-per-pixel gate (default `2`). `false` draws
+     * every visible cell — reach for it if you are screenshotting at a device
+     * pixel ratio the gate can't see, not to "keep the data honest": undecimated
+     * at this density is the less honest picture.
+     *
+     * While decimated, per-cell selection and hover outlines are suppressed (a
+     * sub-pixel ring isn't visible anyway) and interaction still reads the source
+     * grid.
+     */
+    decimate?: DecimateOption;
+    /**
+     * Stable identity — **gates selection + hover**, as every layer's does. Both
+     * channels are sets, and **every** cell a member names outlines (bin `key` —
+     * or the stable per-bin `mark` — plus the row `label`), so a multi-cell pin or
+     * a drag-sweep hover lights all of it. A cell in both reads as selected.
+     */
+    id?: string;
+    /** @internal Declaration position, injected by `Layers`. Do not set. */
+    index?: number;
+}
+/**
+ * A **heat-map draw layer**: a grid of cells, bins along x and the series'
+ * columns down y, colour carrying the aggregate ([PND-HEATMAP]).
+ *
+ * ```tsx
+ * // A stripe — one column.
+ * <HeatMap series={hourly} columns={['count']} colors={ramp} id="load" />
+ *
+ * // A grid — one column per row.
+ * <HeatMap series={byCity} columns={['London', 'Paris', 'Berlin']} colors={ramp} />
+ * ```
+ *
+ * **No reader of its own.** It builds on `stacksFromColumns`, whose output is
+ * already a heat map's data shape — bin spans, named rows, a row-major value
+ * grid. That covers all four shapes pond can express today (`TimeSeries` or
+ * `ValueSeries` × one column or many), and the stripe is simply `G === 1`, so
+ * there is one draw path rather than two.
+ *
+ * **The readout is the point.** A cell carries its value, so hover and click
+ * report it and the readout pill takes the cell's own colour. The bar-based
+ * workaround this replaces cannot: its bars are a constant-height column
+ * carrying no value, so the number has to be looked up out-of-band.
+ *
+ * **Styling.** Colour is data and comes from `colors`, not the theme. Geometry
+ * and the selected-cell treatment are borrowed from
+ * `theme.bar[as] ?? theme.bar.default` rather than a new `theme.heat` slot:
+ * `ChartTheme`'s slots are required, so adding one is breaking for every custom
+ * theme, and the M5 "theme tokens optional-with-default" gate has to land
+ * first. Borrowing defers that decision instead of pre-empting it.
+ *
+ * **Pair it with `<ChartContainer cursor="none">`.** The container's default is
+ * the shared vertical line, and on a grid that is a *second, weaker* cursor
+ * competing with the one that already works: the cell under the pointer takes an
+ * outline, which says both axes at once. The line says only x, and a heat map's
+ * x position is rarely the question. The pointer's own crosshair shape plus the
+ * cell outline is the whole affordance.
+ *
+ * **Not built:** a grouped two-level x axis, and cell value labels. The former
+ * is axis work that would serve bars equally; the latter is small and
+ * independent.
+ */
+export declare function HeatMap<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, columns, colors, domain, orientation, as: semantic, axis, gap, scale, noData, decimate, id, index, }: HeatMapProps<S, VS>): null;
+//# sourceMappingURL=HeatMap.d.ts.map