@pond-ts/charts 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
 them all. Pre-1.0: minor bumps may include new features and type-level changes;
 patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.39.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.40.0...HEAD
+[0.40.0]: https://github.com/pjm17971/pond-ts/compare/v0.39.0...v0.40.0
 [0.39.0]: https://github.com/pjm17971/pond-ts/compare/v0.38.0...v0.39.0
 [0.38.0]: https://github.com/pjm17971/pond-ts/compare/v0.37.0...v0.38.0
 [0.37.0]: https://github.com/pjm17971/pond-ts/compare/v0.36.0...v0.37.0
@@ -37,21 +38,34 @@ patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.40.0] — 2026-07-05
+
+A **core + charts** release from the estela `DataChart`-port friction wave.
+`@pond-ts/react` and `@pond-ts/fit` carry no code changes — republished in
+lock-step (peer ranges widen to `^0.40.0`).
+
+### Added
+
+- `pond-ts`: **`TimeSeries.fromColumns({ sort })`** — an opt-in `sort?: boolean`
+  (default `false`) that stable-sorts a columnar payload by key before
+  construction, the columnar counterpart of `fromJSON`'s `sort`. The default path
+  is unchanged: a decreasing key still throws (a backwards key on the trusted fast
+  door is a corruption signal, not silently accepted), and the `Float64Array`
+  zero-copy adoption is preserved when `sort` is unset. (#344)
+- `@pond-ts/charts`: **controlled bar hover** — `<ChartContainer hovered
+onHover>`, the transient-hover analog of the existing `selected` / `onSelect`
+  pair, keyed by the same `SelectInfo`. Pin a lit `<BarChart>` bar from a legend
+  or list row (`hovered`), or mirror a bar-originated hover out-of-band
+  (`onHover`); omit both for today's uncontrolled behavior. (#343)
+
 ### Fixed
 
-- **Charts — click-to-select an annotation now works while `panZoom` is on.** A
-  _selectable but non-editable_ `<Region>` / `<Marker>` (one with no `onChange`)
-  lets its press bubble to the plot so a drag can pan _through_ it. The plot
-  captured the pointer on press to start the pan, and the browser then retargeted
-  the resulting `click` onto the plot (Pointer Events spec: a captured pointer's
-  compatibility mouse events fire on the capture target) — silently dropping the
-  mark's `onSelectAnnotation`. The plot now **defers** its pan pointer-capture
-  until the pointer actually moves past the drag slop, so a click (no drag) leaves
-  the pointer on the mark and its select fires, while a press-drag still pans
-  through and the tracker still hides once the pan commits. Resolves the
-  browser-dependent finding deferred from #308; adds
-  `e2e/annotations-panzoom.spec.ts`, the first real-pointer-event behavior e2e for
-  the annotation layer. (#309)
+- `@pond-ts/charts`: **axis and layer registration are value-equality-guarded** —
+  a fresh-but-value-equal `ticks` / `format` / `byValue()`-projected `series`
+  reference no longer re-registers the axis/layer, fixing a "Maximum update depth
+  exceeded" loop on frequently re-rendering (scrub-driven) charts. The layer and
+  axis docs gain a memoize note for `format` / `series` (an inline `format`
+  closure still must be hoisted — a closure can't be value-compared). (#342)
 
 ## [0.39.0] — 2026-07-03
 
@@ -89,6 +103,19 @@ carry no code changes — republished in lock-step (peer ranges widen to `^0.39.
 
 - `@pond-ts/charts`: the crosshair x-axis pill and marker pills read the axis's
   own formatter (a value-axis / off-boundary time no longer shows a raw number).
+- **Charts — click-to-select an annotation now works while `panZoom` is on.** A
+  _selectable but non-editable_ `<Region>` / `<Marker>` (one with no `onChange`)
+  lets its press bubble to the plot so a drag can pan _through_ it. The plot
+  captured the pointer on press to start the pan, and the browser then retargeted
+  the resulting `click` onto the plot (Pointer Events spec: a captured pointer's
+  compatibility mouse events fire on the capture target) — silently dropping the
+  mark's `onSelectAnnotation`. The plot now **defers** its pan pointer-capture
+  until the pointer actually moves past the drag slop, so a click (no drag) leaves
+  the pointer on the mark and its select fires, while a press-drag still pans
+  through and the tracker still hides once the pan commits. Resolves the
+  browser-dependent finding deferred from #308; adds
+  `e2e/annotations-panzoom.spec.ts`, the first real-pointer-event behavior e2e for
+  the annotation layer. (#309)
 
 ## [0.38.0] — 2026-07-03
 

package/dist/AreaChart.d.ts

@@ -8,6 +8,10 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * `ValueSeries` (`series.byValue('dist')`) against its value axis — the
      * container infers which from the data, no axis-type prop (mirrors
      * `<LineChart>`). Either way `column` names the numeric value to fill from.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
+     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column to fill from. */

package/dist/BandChart.d.ts

@@ -8,6 +8,10 @@ export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * container infers which from the data, no axis-type prop (mirrors
      * `<LineChart>` / `<AreaChart>`). Either way `lower`/`upper` name the numeric
      * edge columns.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
+     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric column for the band's lower edge (e.g. `p25`). */

package/dist/BarChart.d.ts

@@ -10,6 +10,10 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      * the same neighbour-spacing span applies (see {@link barsFromValueSeries}); the
      * container infers the x-kind from the data, no axis-type prop (mirrors the
      * other layers).
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
+     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column for the bar height. */
@@ -63,6 +67,12 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
  * readout reads the same bar you click, even across a wide bucket (they differ
  * only by the `gap` inset, where the pixel rect is narrower than the span).
  *
+ * Both channels are also **controllable from outside** the chart via the
+ * container: `selected`/`onSelect` (committed) and `hovered`/`onHover` (transient)
+ * — pass either to pin the lit/selected bar from a legend or list row, and read
+ * the callback to mirror a bar-originated hover/click out-of-band. Symmetric pair,
+ * keyed by the same {@link SelectInfo} identity.
+ *
  * **Value axis** — bars also scale on a value axis when fed a `ValueSeries`
  * (`series.byValue('dist')`): estela's distance-domain splits/laps, one bar per
  * segment over a monotonic axis. A `ValueSeries` is point-keyed, so the span is

package/dist/BarChart.js

@@ -26,6 +26,12 @@ import { useSlotKey } from './use-slot-key.js';
  * readout reads the same bar you click, even across a wide bucket (they differ
  * only by the `gap` inset, where the pixel rect is narrower than the span).
  *
+ * Both channels are also **controllable from outside** the chart via the
+ * container: `selected`/`onSelect` (committed) and `hovered`/`onHover` (transient)
+ * — pass either to pin the lit/selected bar from a legend or list row, and read
+ * the callback to mirror a bar-originated hover/click out-of-band. Symmetric pair,
+ * keyed by the same {@link SelectInfo} identity.
+ *
  * **Value axis** — bars also scale on a value axis when fed a `ValueSeries`
  * (`series.byValue('dist')`): estela's distance-domain splits/laps, one bar per
  * segment over a monotonic axis. A `ValueSeries` is point-keyed, so the span is

package/dist/ChartContainer.d.ts

@@ -57,6 +57,31 @@ export interface ChartContainerProps {
      * works in both controlled and uncontrolled mode.
      */
     onSelect?: (hit: SelectInfo | null) => void;
+    /**
+     * Controlled hover-highlight — the transiently lit mark (echo the `onHover` arg
+     * back), or `null`. **Omitted ⇒ uncontrolled** (the pointer over a selectable
+     * layer manages it internally). The hover analog of {@link selected}: pass it to
+     * **pin** a lit mark from outside the chart (e.g. hovering a legend / list row
+     * lights the matching {@link BarChart} bar). Only layers with a hover-highlight
+     * (currently `BarChart`) render it; keyed by the same {@link SelectInfo} identity
+     * as selection.
+     */
+    hovered?: SelectInfo | null;
+    /**
+     * Fires when the pointer enters a selectable layer's mark (the hit mark) or
+     * leaves every mark (`null`) — the hover analog of {@link onSelect}. Notification
+     * only (works controlled or uncontrolled), and **deduped**: it fires on a mark
+     * transition, not on every pointer move. Wire it to mirror hover out-of-band
+     * (e.g. a list row ↔ the bar), pairing with {@link hovered} to sync both ways.
+     * (The annotation counterpart is {@link onHoverAnnotation}.)
+     *
+     * **Dedup key:** by the mark's `key` + `label` only (not `value`/`color`). So on
+     * a live chart where a bar's value changes while the cursor stays on it, this
+     * won't re-fire — read the current value from your series, not the last
+     * `onHover` payload. (Matches the internal hover-highlight, which repaints on
+     * key transitions.)
+     */
+    onHover?: (hit: SelectInfo | null) => void;
     /**
      * Enable pan/zoom: drag the plot to pan the time range, wheel to zoom around
      * the cursor. **Default off** — so it doesn't capture drag/scroll unless asked.
@@ -155,5 +180,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map

package/dist/ChartContainer.js

@@ -31,7 +31,7 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, children, }) {
+export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, children, }) {
     // The explicit base domain from `range` (a tuple or a TimeRange). `undefined`
     // ⇒ auto-fit (resolved from the layers below). Pan/zoom seeds from it; `seed`
     // is the placeholder while auto-fitting.
@@ -175,18 +175,36 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             setInternalSelected(hit);
     }, []);
     // Hover-highlight: the transient mark under the pointer (distinct from the
-    // committed selection). Deduped by key+label so the data canvas repaints only
-    // when the hovered mark changes — not on every pointer move (the move itself
-    // just slides the SVG cursor, which never touches the data canvas).
-    const [hovered, setHoveredState] = useState(null);
+    // committed selection). Controlled (`hovered` prop) or uncontrolled (internal),
+    // mirroring selection; `onHover` notifies in both modes. Deduped by key+label
+    // so it fires — and the data canvas repaints — only when the hovered mark
+    // changes, not on every pointer move (the move itself just slides the SVG
+    // cursor, which never touches the data canvas).
+    const [internalHovered, setInternalHovered] = useState(null);
+    const controlledHover = hovered !== undefined;
+    const hoveredValue = controlledHover ? (hovered ?? null) : internalHovered;
+    const onHoverRef = useRef(onHover);
+    const controlledHoverRef = useRef(controlledHover);
+    // The last mark we reported — so the callback dedups across pointer moves even
+    // in controlled mode, where there's no internal state to compare against.
+    const lastHoverRef = useRef(null);
+    useLayoutEffect(() => {
+        onHoverRef.current = onHover;
+        controlledHoverRef.current = controlledHover;
+    });
     const setHovered = useCallback((hit) => {
-        setHoveredState((prev) => prev === hit ||
+        const prev = lastHoverRef.current;
+        const same = prev === hit ||
             (prev !== null &&
                 hit !== null &&
                 prev.key === hit.key &&
-                prev.label === hit.label)
-            ? prev
-            : hit);
+                prev.label === hit.label);
+        if (same)
+            return;
+        lastHoverRef.current = hit;
+        onHoverRef.current?.(hit);
+        if (!controlledHoverRef.current)
+            setInternalHovered(hit);
     }, []);
     // Rows report their per-slot gutter widths; we reserve each slot's max.
     const [gutters, setGutters] = useState([]);
@@ -284,7 +302,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         setDragging,
         selected: selectedValue,
         select,
-        hovered,
+        hovered: hoveredValue,
         setHovered,
         cursor,
         cursorTime,
@@ -329,7 +347,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         setDragging,
         selectedValue,
         select,
-        hovered,
+        hoveredValue,
         setHovered,
         cursor,
         cursorTime,

package/dist/ChartRow.js

@@ -9,6 +9,62 @@ import { YAxis } from './YAxis.js';
 import { ContainerContext, RowContext, } from './context.js';
 /** 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) —
+ *  so a *fresh* `ticks={[…]}` array whose contents are unchanged doesn't count as
+ *  a new spec (see {@link axisSpecEqual}). */
+function numberArraysEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1)
+        if (!Object.is(a[i], b[i]))
+            return false;
+    return true;
+}
+/**
+ * Value-equality for two {@link AxisSpec}s — the registration guard's compare
+ * (see `registerAxis`). Every field is a plain value except `format`, which may
+ * be a `(value) => string` closure: those are compared by **reference**
+ * (`Object.is`), so a stable/hoisted formatter (or a string specifier) is equal
+ * across renders but a *fresh inline function* is not — the one case a structural
+ * guard provably can't collapse, hence the `<YAxis format>` memoize note. A
+ * fresh-but-value-equal `ticks` array (the common live-chart footgun) compares
+ * equal element-wise and no-ops.
+ */
+function axisSpecEqual(a, b) {
+    return (a.id === b.id &&
+        a.side === b.side &&
+        a.width === b.width &&
+        // 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) &&
+        Object.is(a.max, b.max) &&
+        a.pad === b.pad &&
+        a.labelPlacement === b.labelPlacement &&
+        a.index === b.index &&
+        Object.is(a.format, b.format) &&
+        numberArraysEqual(a.tickValues, b.tickValues));
+}
+/**
+ * Value-equality for two {@link LayerEntry}s — **defensive, not load-bearing.**
+ * The axis guard (`axisSpecEqual`) is what breaks the update-depth loop; this is
+ * belt-and-suspenders for the layer setter. Note that under the current draw-layer
+ * structure it *won't* actually fire: every layer builds `layer` inside the same
+ * `useMemo` as `entry`, so the register effect only runs when `entry` is fresh —
+ * and a fresh `entry` always carries a fresh `layer`, so `a.layer === b.layer` is
+ * never true when the guard runs (it falls through to a normal register). It would
+ * only bite if a future layer memoized `layer` separately from `entry` (or the
+ * `Layers` registry ref changed under a stable entry). A fresh `series` projection
+ * (`byValue()` mints one each call) rebuilds the memo → a new `layer` and
+ * legitimately re-registers; that's a consumer-side memoize (see the `series` note
+ * on the draw-layer components), not something the setter can value-compare.
+ */
+function layerEntryEqual(a, b) {
+    return a.layer === b.layer && a.axisId === b.axisId && a.index === b.index;
+}
 /** Axis tick count for the per-axis formatter — matches `<YAxis>`'s tick count
  *  so the readout formatter is calibrated exactly as the labels are. */
 const AXIS_TICK_COUNT = 5;
@@ -52,8 +108,19 @@ export function ChartRow({ height, cursor, children }) {
     // min/max or series change silently rebind axes / reorder the z-stack.)
     const [axes, setAxes] = useState(() => new Map());
     const [layers, setLayers] = useState(() => new Map());
+    // Registration is idempotent under value-equality: a `<YAxis>` re-fires its
+    // register effect whenever its `spec` memo yields a fresh object — which an
+    // inline `ticks={[]}` / `format` or a re-rendered parent does every render. If
+    // the spec is *value*-equal to the stored one, skip the `setState` entirely so
+    // it can't spin `register → setState → re-render → register` into React's
+    // "Maximum update depth exceeded" on a scrub-heavy chart (F-charts-axis-reregister).
     const registerAxis = useCallback((key, spec) => {
-        setAxes((m) => new Map(m).set(key, spec));
+        setAxes((m) => {
+            const prev = m.get(key);
+            if (prev !== undefined && axisSpecEqual(prev, spec))
+                return m;
+            return new Map(m).set(key, spec);
+        });
     }, []);
     const unregisterAxis = useCallback((key) => {
         setAxes((m) => {
@@ -64,8 +131,17 @@ export function ChartRow({ height, cursor, children }) {
             return next;
         });
     }, []);
+    // Same value-equality guard as `registerAxis`: a re-register carrying the same
+    // `layer` object (stable while the draw layer's inputs are) + `axisId`/`index`
+    // no-ops rather than churning state. (A fresh `series` projection rebuilds the
+    // layer and legitimately re-registers — see `layerEntryEqual`.)
     const registerLayer = useCallback((key, entry) => {
-        setLayers((m) => new Map(m).set(key, entry));
+        setLayers((m) => {
+            const prev = m.get(key);
+            if (prev !== undefined && layerEntryEqual(prev, entry))
+                return m;
+            return new Map(m).set(key, entry);
+        });
     }, []);
     const unregisterLayer = useCallback((key) => {
         setLayers((m) => {

package/dist/LineChart.d.ts

@@ -8,6 +8,11 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * `ValueSeries` (`series.byValue('cumDist')`) against its value axis — the
      * container infers which from the data, no axis-type prop. Either way the key
      * / axis column supplies x and `column` supplies y.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * passing `series={s.byValue('dist')}` inline re-registers this layer every
+     * render — on a frequently re-rendering (e.g. scrub-driven) chart, memoize the
+     * projection (`useMemo`) so the layer isn't rebuilt each frame.
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column to plot. */

package/dist/YAxis.d.ts

@@ -36,6 +36,12 @@ export interface YAxisProps {
      * function. Omit for the scale's d3 default — which is calibrated to the tick
      * step, so a between-ticks readout rounds to tick precision; pass a specifier
      * (e.g. `',.2f'`) when you want finer readout precision. See {@link AxisFormat}.
+     *
+     * **Live charts:** a string specifier is value-compared, so an inline
+     * `format='.0%'` is safe every render. An inline `format={(v) => …}` **function**
+     * is a fresh reference each render — the one axis prop a structural guard can't
+     * value-compare — so on a frequently re-rendering (e.g. scrub-driven) chart,
+     * hoist it or wrap it in `useCallback`, or it re-registers the axis each frame.
      */
     format?: AxisFormat;
     /**
@@ -45,9 +51,10 @@ export interface YAxisProps {
      * lever for a non-uniform axis like pace, where the caller chooses round-pace
      * positions and their own `m:ss` labels (`{ at: -300, label: '5:00' }`). `at`
      * values outside `[min, max]` extrapolate off-plot (the scale does not clamp).
-     * Pass `[]` to draw none. For a live / animating chart, **memoize the array** —
-     * an inline `ticks={[…]}` is a fresh reference each render and re-registers the
-     * axis (like `format`; harmless for a static chart).
+     * Pass `[]` to draw none. The array is **value-compared on registration**, so an
+     * inline `ticks={[…]}` (or `ticks={[]}`) with unchanged contents no longer
+     * re-registers the axis — only genuinely changed tick positions do. (An inline
+     * `format` *function* still needs hoisting; see `format`.)
      */
     ticks?: ReadonlyArray<{
         readonly at: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.39.0",
-    "pond-ts": "^0.39.0",
+    "@pond-ts/react": "^0.40.0",
+    "pond-ts": "^0.40.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {