@pond-ts/charts 0.57.0 → 0.58.0

package/dist/HeatMap.js

@@ -0,0 +1,344 @@
+import { useContext, useEffect, useMemo } from 'react';
+import { ValueSeries } from 'pond-ts';
+import { stacksFromColumns } from './data.js';
+import { bandedColor, drawHeat, heatAt, heatValueExtent, } from './heat.js';
+import { spansForLayer } from './span.js';
+import { ContainerContext, LayersContext, } from './context.js';
+import { useSlotKey } from './use-slot-key.js';
+import { sweep2D } from './sweep.js';
+/** Stable identity for "nothing in this set" — the resting case, so the layer
+ *  doesn't rebuild its `entry` (and the canvas doesn't repaint) merely because
+ *  the container handed out a fresh empty array. */
+const NO_MARKS = [];
+/**
+ * The cell identity of every member of `set` — the layer `id`, the bin `key`
+ * (or the stable per-bin `mark` where the series carries one) and the row
+ * `label`, which is the whole of what {@link drawHeat} matches on.
+ *
+ * Deliberately **not** filtered to this layer's own `id` — the draw matches on
+ * it anyway, and gates its per-bin scan on whether either set names this layer
+ * at all, so a component-side filter would buy nothing and add a second place
+ * the id rule lives. What this *does* drop is the `SelectInfo` presentation
+ * fields (`value`, `color`), which the draw has no business reading.
+ */
+function marksOf(set) {
+    if (set.length === 0)
+        return NO_MARKS;
+    return set.map((m) => ({
+        id: m.id,
+        key: m.key,
+        label: m.label,
+        ...(m.mark !== undefined ? { mark: m.mark } : {}),
+    }));
+}
+/**
+ * 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 function HeatMap({ series, columns, colors, domain, orientation = 'vertical', as: semantic, axis, gap = 0, scale = 'linear', noData = 'blank', decimate = true, id, index = 0, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<HeatMap> must be rendered inside a <ChartContainer>');
+    }
+    const layers = useContext(LayersContext);
+    if (layers === null) {
+        throw new Error('<HeatMap> must be rendered inside a <Layers>');
+    }
+    if (columns.length === 0) {
+        throw new Error('<HeatMap> needs at least one column (one row per column)');
+    }
+    // `columns`, `colors` and `domain` are **array** props, and the natural way to
+    // write every one of them is a fresh array per render — a JSX literal, a
+    // `.map()`, or a theme hook like the docs site's `useSequentialRamp()`. Keyed
+    // by identity they would rebuild the layer `entry` every render, hence a
+    // `registerLayer` every render: a repaint treadmill, not a noisy warning. So
+    // memoize on **content**, exactly as `<BarChart thresholds>` does. The joiner
+    // is NUL rather than a comma because a column name may contain a comma, and
+    // `['a,b']` must not key the same as `['a', 'b']`.
+    const columnsKey = columns.join('\u0000');
+    const colorsKey = colors.join('\u0000');
+    const domainKey = domain === undefined ? '' : `${domain[0]}\u0000${domain[1]}`;
+    const ss = useMemo(() => stacksFromColumns(series, columns), [series, columnsKey]);
+    const { bar } = container.theme;
+    const base = (semantic !== undefined ? bar[semantic] : undefined) ?? bar.default;
+    // The geometry comes from the BAR slot (a cell is a bar's slot with colour
+    // instead of height); the interaction states come from `theme.heat`, which
+    // exists because a bar's fill is free and a cell's fill is the datum — see
+    // `HeatStates`. Absent, the pre-states treatment is unchanged.
+    const heatStates = container.theme.heat;
+    const states = (semantic !== undefined ? heatStates?.[semantic] : undefined) ??
+        heatStates?.default;
+    const style = useMemo(() => ({
+        opacity: base.opacity,
+        highlight: base.highlight,
+        outlineWidth: base.outlineWidth,
+        gap,
+        minWidth: base.minWidth,
+        gridColor: container.theme.axis.grid,
+        ...(states !== undefined ? { states } : {}),
+    }), [base, gap, container.theme.axis.grid, states]);
+    // One colour domain across the whole grid, so rows are comparable.
+    const [lo, hi] = useMemo(() => domain ?? heatValueExtent(ss) ?? [0, 1], [domainKey, ss]);
+    const G = ss.groups.length;
+    const vertical = orientation === 'vertical';
+    // Colour is a function of the **value**, which is the layer's whole model —
+    // so the closure takes one. It also lets a decimated pixel column, which has
+    // no source `(b, g)`, be coloured by the same ramp.
+    const colorOf = useMemo(() => (value) => bandedColor(value, colors, lo, hi, scale), [colorsKey, lo, hi, scale]);
+    const selected = container.selected;
+    const hoveredMark = container.hovered;
+    // Both channels are **sets** — `selected` since [PND-MULTISEL], `hovered`
+    // since RFC A4.3 — and both reach `drawHeat` whole, which lights every cell a
+    // member names. Narrowed here only from `SelectInfo` down to the cell identity
+    // (`id` + `key`/`mark` + row `label`), so `heat.ts` stays free of the
+    // selection's presentation fields exactly as it is free of the theme.
+    const selection = useMemo(() => marksOf(selected), [selected]);
+    const hover = useMemo(() => marksOf(hoveredMark), [hoveredMark]);
+    // The selection's span entries, narrowed to this layer (interaction RFC
+    // A5.2). A heat map's labels vary per cell (the row names — the ordinal
+    // second dimension a span addresses via `rows`, RFC A5.3), so no label is
+    // passed and the `rows` channel rides through for `drawHeat` to test per
+    // cell. Reference-stable when empty, like the mark memos above.
+    const layerSpans = useMemo(() => spansForLayer(container.selectedSpans, id), [container.selectedSpans, id]);
+    const entry = useMemo(() => ({
+        layer: {
+            as: semantic,
+            // Inferred, exactly as BarChart does it — no axis-kind prop.
+            // Horizontal moves the bins to y, so x becomes the categories the
+            // columns name — which is the container's `'category'` kind, exactly as
+            // a categorical `<BarChart>` reports it.
+            xKind: vertical
+                ? series instanceof ValueSeries
+                    ? 'value'
+                    : 'time'
+                : 'category',
+            xExtent: () => vertical
+                ? ss.length === 0
+                    ? null
+                    : [ss.begin[0], ss.end[ss.length - 1]]
+                : [0, G],
+            yExtent: () => vertical
+                ? [0, G]
+                : ss.length === 0
+                    ? null
+                    : [ss.begin[0], ss.end[ss.length - 1]],
+            // Unit slots, one per column, labelled at each centre — on whichever
+            // axis they landed. `binCategories` is the y-axis channel and
+            // `xCategories` the x-axis one ([PND-HCAT]).
+            ...(vertical
+                ? { binCategories: () => ss.groups }
+                : { xCategories: () => ss.groups }),
+            // The x-scrub tracker samples along x, which is the bin axis only when
+            // vertical. A horizontal grid answers through `onHover` / `onSelect`
+            // instead, which resolve both axes — the same split the 2-D readout
+            // already forced.
+            sampleAt: (x) => {
+                if (!vertical)
+                    return [];
+                // Every row's value at the cursor — the whole column of the grid,
+                // which is what an off-chart readout wants from a heat map.
+                for (let b = 0; b < ss.length; b += 1) {
+                    if (x < ss.begin[b] || x > ss.end[b])
+                        continue;
+                    const out = [];
+                    for (let g = 0; g < G; g += 1) {
+                        const v = ss.values[b * G + g];
+                        if (!Number.isFinite(v))
+                            continue;
+                        out.push({
+                            x: (ss.begin[b] + ss.end[b]) / 2,
+                            // `value` is where the cursor *draws* — `yScale(value)` — so
+                            // it must be a y coordinate, and for a cell that is its row's
+                            // centre, not its number. The number rides `readout`, which
+                            // an off-chart consumer shows as `readout ?? value`. Without
+                            // the split the dot would be placed at `yScale(anomaly)` on a
+                            // unit-slot axis and land outside the plot entirely.
+                            value: g + 0.5,
+                            readout: v,
+                            color: colorOf(v) ?? style.highlight,
+                            label: ss.groups[g],
+                        });
+                    }
+                    return out;
+                }
+                return [];
+            },
+            ...(id === undefined
+                ? {}
+                : {
+                    hitTest: (px, py, xScale, yScale) => {
+                        const hit = heatAt(ss, px, py, xScale, yScale, style.gap, style.minWidth, orientation);
+                        if (hit === null)
+                            return null;
+                        const [b, g, begin, name, value] = hit;
+                        const mark = ss.marks?.[b];
+                        return {
+                            id,
+                            key: begin,
+                            value,
+                            color: colorOf(value) ?? style.highlight,
+                            label: name,
+                            ...(mark !== undefined ? { mark } : {}),
+                        };
+                    },
+                    /**
+                     * The **snapped rect** ([PND-INTERACT2D]). Both dimensions snap:
+                     * x to whole bin columns (`sweep2D`'s cut, as every column mark
+                     * does) and y **outward to whole row slots** — a vertical heat
+                     * map's rows own the unit intervals `[g, g+1)` of its value axis
+                     * (see `yExtent`), so a window is floored and ceiled onto them.
+                     *
+                     * Snapping both is what makes the selection a contiguous
+                     * rectangle of cells, which in turn is why the region can carry
+                     * **one** perimeter rather than a border per cell.
+                     */
+                    // A cell owns a position, not a column: the sweep is a rect, and
+                    // the resting cursor is the small crosshair rather than a band.
+                    //
+                    // Gated on exactly what `beginSweep` gates on. `sweepsRect` is
+                    // read at REST, where there is no session to ask, so declaring
+                    // it unconditionally made a HORIZONTAL heat map suppress its
+                    // row's cursor and paint a resting `+` for a rect gesture that
+                    // can never start — `beginSweep` returns `null` there.
+                    sweepsRect: vertical && ss.length > 0 && G > 0,
+                    beginSweep: () => {
+                        if (!vertical || ss.length === 0 || G === 0)
+                            return null;
+                        /** The window's covering row-slot run, snapped outward. */
+                        const rowRun = (y0, y1) => {
+                            const g0 = Math.max(0, Math.floor(y0));
+                            const g1 = Math.min(G, Math.ceil(y1));
+                            return [g0, g1 > g0 ? g1 : g0];
+                        };
+                        return sweep2D({
+                            id,
+                            begin: ss.begin,
+                            end: ss.end,
+                            length: ss.length,
+                            spanFrom: 'bins',
+                            materialize: (lo, hi, y0, y1) => {
+                                const [g0, g1] = rowRun(y0, y1);
+                                const out = [];
+                                for (let b = lo; b < hi; b += 1) {
+                                    const mark = ss.marks?.[b];
+                                    for (let g = g0; g < g1; g += 1) {
+                                        const v = ss.values[b * G + g];
+                                        // A gap cell draws nothing and owns no membership —
+                                        // the rule `hitTest` already applies.
+                                        if (!Number.isFinite(v))
+                                            continue;
+                                        out.push({
+                                            id,
+                                            key: ss.begin[b],
+                                            value: v,
+                                            color: colorOf(v) ?? style.highlight,
+                                            label: ss.groups[g],
+                                            ...(mark !== undefined ? { mark } : {}),
+                                        });
+                                    }
+                                }
+                                return out;
+                            },
+                            // The brush draws THIS, not the pointer rectangle: the cut
+                            // snaps to whole bins and whole rows, so a raw rect would
+                            // promise a different set than the release delivers — and
+                            // it disagrees most visibly at the moment the user is
+                            // deciding where to let go.
+                            snap: (lo, hi, y0, y1) => {
+                                const [g0, g1] = rowRun(y0, y1);
+                                return g1 > g0
+                                    ? { x: [ss.begin[lo], ss.end[hi - 1]], y: [g0, g1] }
+                                    : null;
+                            },
+                            // `rows` names the rows rather than numbering slots, so a
+                            // committed selection survives a row reorder (RFC A5.3).
+                            channels: (_hits, y0, y1) => {
+                                const [g0, g1] = rowRun(y0, y1);
+                                return { rows: ss.groups.slice(g0, g1) };
+                            },
+                        });
+                    },
+                }),
+            draw: (ctx, xScale, yScale) => drawHeat(ctx, ss, xScale, yScale, style, colorOf, id, 
+            // Both sets whole. Passing `selection[0]` here quietly showed one
+            // outline for a three-cell selection — the memos above were plural
+            // long before the draw was.
+            selection, hover, decimate, orientation, noData, layerSpans),
+        },
+        axisId: axis,
+        index,
+    }), [
+        ss,
+        G,
+        style,
+        colorOf,
+        decimate,
+        orientation,
+        noData,
+        vertical,
+        semantic,
+        series,
+        id,
+        axis,
+        index,
+        selection,
+        hover,
+        layerSpans,
+    ]);
+    const slot = useSlotKey();
+    useEffect(() => () => layers.unregisterLayer(slot), [layers, slot]);
+    useEffect(() => {
+        layers.registerLayer(slot, entry);
+    }, [layers, slot, entry]);
+    const { registerTrackerSource, unregisterTrackerSource } = container;
+    useEffect(() => () => unregisterTrackerSource(slot), [unregisterTrackerSource, slot]);
+    useEffect(() => {
+        registerTrackerSource(slot, entry.layer);
+    }, [registerTrackerSource, slot, entry.layer]);
+    const { registerSelectable, unregisterSelectable } = container;
+    useEffect(() => {
+        if (id === undefined)
+            return;
+        registerSelectable(slot);
+        return () => unregisterSelectable(slot);
+    }, [registerSelectable, unregisterSelectable, slot, id]);
+    return null;
+}
+//# sourceMappingURL=HeatMap.js.map

package/dist/Layers.d.ts

@@ -16,7 +16,11 @@ export interface LayersProps {
  * others slots into place, not onto the top), and each layer keeps a stable,
  * id-keyed slot so a series/style update holds its position (no jump to the
  * front — the trap that bites live charts). Draw layers must be **direct
- * children** of `<Layers>` for the index to reach them.
+ * children** of `<Layers>` for the index to reach them — to group them
+ * conditionally, return a **keyed array**, not a `<>…</>`: a fragment takes no
+ * props, so the index stops there and the layers inside it all register at 0
+ * (dev warns about this, because a stable sort makes the resulting tie look
+ * correct until mount order and declaration order disagree).
  */
 export declare function Layers({ children }: LayersProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=Layers.d.ts.map