pond-ts 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/batch/time-series.d.ts

@@ -112,7 +112,19 @@ export declare class TimeSeries<S extends SeriesSchema> {
      * the fast path): the resulting series' columns alias the caller's buffers.
      * Mutating an adopted buffer after construction mutates the series. Pass a
      * fresh buffer (e.g. straight off a decode) if this matters; `number[]`
-     * columns are always copied.
+     * columns are always copied. (**`sort` disables the adoption** — a reorder
+     * needs its own buffers, so every column is copied when sorting.)
+     *
+     * **Ordering.** Keys must be **non-decreasing** — bisect-based operators (crop,
+     * `atTime`, range queries) rely on it — so an out-of-order columnar input
+     * throws by default (a backwards key on the *trusted* fast door is a corruption
+     * signal, not something to silently accept). Pass **`sort: true`** to sort the
+     * rows by key before construction instead — the columnar analog of
+     * {@link TimeSeries.fromJSON}'s `sort`, paying `O(n log n)` + a copy only when
+     * asked. The sort is **stable**, so rows sharing a key keep their input order.
+     * (To flatten a genuine backwards blip to a plateau — a different, lossy choice
+     * — clamp the key column yourself before ingest; the library won't mutate data
+     * for you.)
      *
      * **v1 scope:** a `time`-kind key + `number` value columns (the market-data /
      * chart wire case). Other key kinds (`interval` / `timeRange`) and non-numeric
@@ -120,12 +132,20 @@ export declare class TimeSeries<S extends SeriesSchema> {
      *
      * @throws ValidationError on a missing column, a length mismatch, an
      *   unsupported kind, a non-finite timestamp key, or an out-of-order
-     *   (decreasing) timestamp — keys must be non-decreasing, same as `fromJSON`.
+     *   (decreasing) timestamp when `sort` is not set — keys must be non-decreasing,
+     *   same as `fromJSON`.
      */
     static fromColumns<S extends SeriesSchema>(input: {
         name: string;
         schema: S;
         columns: Record<string, ReadonlyArray<number | null | undefined> | Float64Array>;
+        /**
+         * Sort the rows by key before construction (off by default), for a columnar
+         * payload whose rows aren't guaranteed ordered — the counterpart of
+         * `fromJSON`'s `sort`. Stable; disables the `Float64Array` zero-copy adoption
+         * (columns are reordered into fresh buffers).
+         */
+        sort?: boolean;
     }): TimeSeries<S>;
     /**
      * Example: `TimeSeries.fromEvents(events, { schema, name })`.

package/dist/batch/time-series.js

@@ -511,7 +511,19 @@ export class TimeSeries {
      * the fast path): the resulting series' columns alias the caller's buffers.
      * Mutating an adopted buffer after construction mutates the series. Pass a
      * fresh buffer (e.g. straight off a decode) if this matters; `number[]`
-     * columns are always copied.
+     * columns are always copied. (**`sort` disables the adoption** — a reorder
+     * needs its own buffers, so every column is copied when sorting.)
+     *
+     * **Ordering.** Keys must be **non-decreasing** — bisect-based operators (crop,
+     * `atTime`, range queries) rely on it — so an out-of-order columnar input
+     * throws by default (a backwards key on the *trusted* fast door is a corruption
+     * signal, not something to silently accept). Pass **`sort: true`** to sort the
+     * rows by key before construction instead — the columnar analog of
+     * {@link TimeSeries.fromJSON}'s `sort`, paying `O(n log n)` + a copy only when
+     * asked. The sort is **stable**, so rows sharing a key keep their input order.
+     * (To flatten a genuine backwards blip to a plateau — a different, lossy choice
+     * — clamp the key column yourself before ingest; the library won't mutate data
+     * for you.)
      *
      * **v1 scope:** a `time`-kind key + `number` value columns (the market-data /
      * chart wire case). Other key kinds (`interval` / `timeRange`) and non-numeric
@@ -519,10 +531,11 @@ export class TimeSeries {
      *
      * @throws ValidationError on a missing column, a length mismatch, an
      *   unsupported kind, a non-finite timestamp key, or an out-of-order
-     *   (decreasing) timestamp — keys must be non-decreasing, same as `fromJSON`.
+     *   (decreasing) timestamp when `sort` is not set — keys must be non-decreasing,
+     *   same as `fromJSON`.
      */
     static fromColumns(input) {
-        const { name, schema, columns } = input;
+        const { name, schema, columns, sort = false } = input;
         // Key column (schema[0]). v1: point-in-time (`time`) keys only.
         const keyDef = schema[0];
         if (keyDef === undefined) {
@@ -540,18 +553,38 @@ export class TimeSeries {
         // generic iterable-protocol path even for a plain array, ~15-20x slower
         // than a preallocated-buffer copy at 100k-element scale — measured, not
         // theoretical (see the pond-columnar-ingest spike's ingest regression).
-        let begin;
+        let rawBegin;
         if (keyRaw instanceof Float64Array) {
-            begin = keyRaw;
+            rawBegin = keyRaw;
         }
         else {
-            begin = new Float64Array(keyRaw.length);
+            rawBegin = new Float64Array(keyRaw.length);
             for (let j = 0; j < keyRaw.length; j += 1) {
                 const v = keyRaw[j];
-                begin[j] = v == null ? NaN : Number(v);
+                rawBegin[j] = v == null ? NaN : Number(v);
             }
         }
-        const count = begin.length;
+        const count = rawBegin.length;
+        // `sort: true` — reorder every column by ascending key before construction.
+        // Compute the row permutation once (a stable sort of the index array; V8's
+        // Array.sort is stable, so equal keys keep input order, matching fromJSON's
+        // stable intake), then remap the key + each value column through it below.
+        // `order` stays null on the (default) trusted fast path, so no allocation /
+        // copy is paid unless asked. A non-finite key is left for `TimeKeyColumn` to
+        // reject — sorting can't make it valid.
+        let begin;
+        let order = null;
+        if (sort) {
+            const idx = Array.from({ length: count }, (_, i) => i);
+            idx.sort((a, b) => rawBegin[a] - rawBegin[b]);
+            order = Uint32Array.from(idx);
+            begin = new Float64Array(count);
+            for (let j = 0; j < count; j += 1)
+                begin[j] = rawBegin[order[j]];
+        }
+        else {
+            begin = rawBegin;
+        }
         // Throws on any non-finite timestamp.
         const keys = new TimeKeyColumn(begin, count);
         // Enforce the non-decreasing-key invariant that `fromJSON`'s
@@ -560,11 +593,13 @@ export class TimeSeries {
         // bisect-based operators (crop, `atTime`, range queries) rely on it, so an
         // unsorted columnar input must fail loudly here rather than build a silently
         // broken series. One O(N) scan over already-finite values — negligible next
-        // to decode.
+        // to decode. (When `sort` is set the keys are now non-decreasing, so this is
+        // a cheap post-condition check rather than a rejection.)
         for (let j = 1; j < count; j += 1) {
             if (begin[j] < begin[j - 1]) {
                 throw new ValidationError(`fromColumns: key column '${keyDef.name}' is out of order at index ${j} ` +
-                    `(${begin[j]} < ${begin[j - 1]}) — timestamps must be non-decreasing; pre-sort the columns`);
+                    `(${begin[j]} < ${begin[j - 1]}) — timestamps must be non-decreasing; ` +
+                    `pass { sort: true } or pre-sort the columns`);
             }
         }
         // Value columns — packed directly (missing-aware) from the arrays.
@@ -594,7 +629,23 @@ export class TimeSeries {
             // Manual loop, not `Float64Array.from(arr, mapFn)` — see the key-column
             // comment above; the cost applies identically here.
             let values;
-            if (raw instanceof Float64Array) {
+            if (order !== null) {
+                // Sorting: reorder into a fresh buffer through the key permutation (no
+                // zero-copy adoption — the rows are being moved). Same missing rule
+                // (`null`/`undefined` → NaN) applied while remapping.
+                values = new Float64Array(count);
+                if (raw instanceof Float64Array) {
+                    for (let j = 0; j < count; j += 1)
+                        values[j] = raw[order[j]];
+                }
+                else {
+                    for (let j = 0; j < count; j += 1) {
+                        const v = raw[order[j]];
+                        values[j] = v == null ? NaN : v;
+                    }
+                }
+            }
+            else if (raw instanceof Float64Array) {
                 values = raw;
             }
             else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pond-ts",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "TypeScript-first time series primitives",
   "license": "MIT",
   "repository": {