@pond-ts/charts 0.58.0 → 0.60.0

package/dist/viewport.js

@@ -70,8 +70,26 @@ function roundRange(lo, hi) {
  * is snapped to whole milliseconds ({@link roundRange}) — `dt` comes from a pixel
  * delta through `xScale.invert()`, so it is fractional by construction.
  */
-export function panRange(range, dt) {
-    return roundRange(range[0] + dt, range[1] + dt);
+export function panRange(range, dt, options = {}) {
+    const { log = false, snap = !log } = options;
+    if (log) {
+        // On a log axis a pixel drag is a RATIO, not an offset. `dt` arrives as a
+        // domain delta from `xScale.invert`, which on a log scale is meaningless as
+        // an addend: adding 100s near the 1s end walks off the plot, and near the
+        // 3h end barely moves. Convert it to the fraction of the visible decades it
+        // represents and shift by that instead, so a drag of N pixels moves the
+        // same visual distance wherever it starts.
+        const [lo, hi] = range;
+        if (!(lo > 0) || !(hi > lo))
+            return [lo, hi];
+        const span = hi - lo;
+        const f = span > 0 ? dt / span : 0; // fraction of the window dragged
+        const k = Math.exp(Math.log(hi / lo) * f); // …as a ratio over the decades
+        return [lo * k, hi * k];
+    }
+    const lo = range[0] + dt;
+    const hi = range[1] + dt;
+    return snap ? roundRange(lo, hi) : [lo, hi];
 }
 /**
  * Zoom `range` around `pivot` (ms) by `factor` — `< 1` zooms in, `> 1` out, with
@@ -85,15 +103,44 @@ export function panRange(range, dt) {
  * lands on the 1 ms floor the snap guarantees, which is the finest view this
  * model has.
  */
-export function zoomRange(range, pivot, factor, minDuration = 1) {
+export function zoomRange(range, pivot, factor, minDuration = 1, options = {}) {
+    const { log = false, snap = !log } = options;
+    if (log) {
+        // The same arithmetic, done in log space — which is where a log axis is
+        // linear. Zooming a log domain multiplicatively is what keeps the pivot
+        // under the cursor; doing it additively (as the linear branch does) drags
+        // the value under the pointer sideways, which is the one thing zoom must
+        // never do.
+        //
+        // `minDuration` is read as a minimum RATIO between the ends rather than a
+        // minimum difference, because a span on a log axis is a number of decades.
+        const [lo0, hi0] = range;
+        if (!(lo0 > 0) || !(hi0 > lo0) || !(pivot > 0))
+            return [lo0, hi0];
+        const L = Math.log(lo0);
+        const H = Math.log(hi0);
+        const P = Math.min(H, Math.max(L, Math.log(pivot)));
+        let l = P - (P - L) * factor;
+        let h = P + (H - P) * factor;
+        const floor = Math.log(Math.max(minDuration, 1 + 1e-9)); // ratio → decades
+        if (h - l < floor) {
+            const frac = H - L > 0 ? (P - L) / (H - L) : 0.5;
+            l = P - floor * frac;
+            h = P + floor * (1 - frac);
+        }
+        return [Math.exp(l), Math.exp(h)];
+    }
     const lo = pivot - (pivot - range[0]) * factor;
     const hi = pivot + (range[1] - pivot) * factor;
-    if (hi - lo >= minDuration)
-        return roundRange(lo, hi);
+    if (hi - lo >= minDuration) {
+        return snap ? roundRange(lo, hi) : [lo, hi];
+    }
     // Floor reached: hold the pivot's fractional position, set span = minDuration.
     const span = range[1] - range[0];
     const frac = span > 0 ? (pivot - range[0]) / span : 0.5;
-    return roundRange(pivot - minDuration * frac, pivot + minDuration * (1 - frac));
+    const flo = pivot - minDuration * frac;
+    const fhi = pivot + minDuration * (1 - frac);
+    return snap ? roundRange(flo, fhi) : [flo, fhi];
 }
 /**
  * Pan a range on a **trading-time** axis: shift both endpoints by the same

package/dist/yticks.d.ts

@@ -23,6 +23,9 @@ interface TickableScale {
     domain(): number[];
     /** Present on d3's `scaleLog` and on no other continuous scale. */
     base?: () => number;
+    /** Present on d3's `scaleSymlog` and on no other continuous scale — the
+     *  linear window's half-width, i.e. the knee ([PND-SYMLOG]). */
+    constant?: () => number;
 }
 /**
  * The y tick **values** a `<YAxis>`'s labels and the row's gridlines draw —
@@ -54,11 +57,15 @@ interface TickableScale {
  * d3's within-decade selection (2,3,…9 × 10ⁿ) is the right answer and is well
  * behaved — so that case defers to the scale.
  *
+ * Used by **both** axes. Nothing in here was ever y-specific — it detects log
+ * and symlog structurally and defers to the scale for everything else — and
+ * `<ChartContainer xScale="log">` made that concrete ([PND-XLOG]).
+ *
  * Log detection is structural: `base()` exists on `scaleLog` and on no other
  * continuous scale. The alternative is threading the axis kind down to the
  * gridline site, which has no `AxisSpec` in scope — the same localized-shape
  * approach `resolveBarBaseline` takes to read `.domain()`.
  */
-export declare function yTickValues(scale: TickableScale, count: number): number[];
+export declare function tickValues(scale: TickableScale, count: number): number[];
 export {};
 //# sourceMappingURL=yticks.d.ts.map

package/dist/yticks.js

@@ -55,12 +55,18 @@ export function resolveYTickCount(height, explicit) {
  * d3's within-decade selection (2,3,…9 × 10ⁿ) is the right answer and is well
  * behaved — so that case defers to the scale.
  *
+ * Used by **both** axes. Nothing in here was ever y-specific — it detects log
+ * and symlog structurally and defers to the scale for everything else — and
+ * `<ChartContainer xScale="log">` made that concrete ([PND-XLOG]).
+ *
  * Log detection is structural: `base()` exists on `scaleLog` and on no other
  * continuous scale. The alternative is threading the axis kind down to the
  * gridline site, which has no `AxisSpec` in scope — the same localized-shape
  * approach `resolveBarBaseline` takes to read `.domain()`.
  */
-export function yTickValues(scale, count) {
+export function tickValues(scale, count) {
+    if (typeof scale.constant === 'function')
+        return symlogTickValues(scale, count);
     if (typeof scale.base !== 'function')
         return scale.ticks(count);
     const domain = scale.domain();
@@ -80,4 +86,106 @@ export function yTickValues(scale, count) {
         out.push(10 ** e);
     return out;
 }
+/**
+ * Tick values for a **symlog** axis — linear through zero, logarithmic beyond
+ * ([PND-SYMLOG]).
+ *
+ * **This is the feature, not a refinement of it.** d3's `scaleSymlog` supplies
+ * the transform but its `ticks()` is `linearish` — evenly spaced in *value*. On
+ * a ±1M domain with a 20k knee that yields `-1M, -500k, 0, 500k, 1M`: **nothing
+ * at all below the knee**, which is the region a symlog axis exists to reveal.
+ * The mapping does spread that region generously (0→250px, 20k→294px,
+ * 100k→364px on a 500px range), so such a chart is readable-but-unlabelled —
+ * confidently gridded on the one part of the scale that isn't the point. Owning
+ * the ladder is therefore inseparable from owning the transform.
+ *
+ * The ladder, and why each piece is there:
+ *
+ * - **Zero, always.** It is the axis's centre of symmetry and the one value a
+ *   symlog scale is chosen to keep visible.
+ * - **The knee, ±`constant`.** Where the reading changes from linear to
+ *   logarithmic. Unlabelled, a reader has no way to know which régime a given
+ *   gap belongs to, and the same pixel distance means different things either
+ *   side of it.
+ * - **Decades beyond the knee, mirrored.** What a log plot is conventionally
+ *   gridded on, thinned by the same "every `k`th power of ten" rule the log path
+ *   above uses, so it degrades predictably as the row shrinks instead of
+ *   exploding.
+ * - **Bounds are NOT labelled.** A data-derived bound is rarely round, so
+ *   printing it puts an arbitrary number next to a decade — the noise a log grid
+ *   exists to avoid.
+ *
+ * Below one decade of span past the knee there is nothing to grid
+ * logarithmically, so it defers to `scale.ticks(count)` — which is linear, and
+ * correct, because inside the knee symlog *is* linear.
+ *
+ * **Clip first, then thin — never the other way round.** A pan/zoom (or explicit
+ * bounds) can leave a window that contains *none* of the ideal ladder:
+ * `[510_000, 990_000]` with a 19_800 knee excludes zero, both knees, and its one
+ * candidate decade, so an order that thinned a symmetric ladder and clipped
+ * afterwards handed **`[]`** to the labels and the gridlines — an axis with no
+ * ticks at all, which reads as a rendering failure rather than as a scale. The
+ * budget is likewise spent on what *survives* the domain, not on an ideal
+ * two-sided ladder, so an asymmetric window is not thinned as if it were twice
+ * its size. If nothing survives, the linear ticks are the honest answer.
+ *
+ * Detection is structural, matching the log path's use of `base()`: `constant()`
+ * exists on `scaleSymlog` and on no other continuous scale.
+ */
+function symlogTickValues(scale, count) {
+    const domain = scale.domain();
+    const lo = Math.min(domain[0], domain[domain.length - 1]);
+    const hi = Math.max(domain[0], domain[domain.length - 1]);
+    const knee = Math.abs(scale.constant?.() ?? 1);
+    const maxAbs = Math.max(Math.abs(lo), Math.abs(hi));
+    // Finiteness is checked, not assumed: an explicit `max={Infinity}` reaches here
+    // intact, and `floor(log10(Infinity))` is `Infinity` — which made the decade
+    // loop's `e += step` a no-op and hung the render in a `for` that could never
+    // end. d3's own linear ticks return `[]` on such a domain, so deferring is both
+    // safe and the truthful answer for a domain with no finite extent.
+    if (!Number.isFinite(lo) || !Number.isFinite(hi) || !Number.isFinite(knee))
+        return scale.ticks(count);
+    if (!(knee > 0) || !(maxAbs > knee) || !(hi > lo))
+        return scale.ticks(count);
+    // The ladder starts at the first decade **at least half a decade above the
+    // knee** (`× √10`), not merely above it. `ceil(log10(knee))` alone puts a
+    // decade arbitrarily close to the knee tick whenever the knee lands just under
+    // a power of ten — a data-derived `maxAbs` of 4.95e6 gives a 99k knee and a
+    // 100k decade, two ticks a few pixels apart whose labels round to the *same
+    // string*. Since the knee itself is always drawn, dropping that decade loses
+    // no information; a chart that prints one number twice at two positions is
+    // reporting something false about the scale.
+    const firstExp = Math.ceil(Math.log10(knee) + 0.5);
+    const lastExp = Math.floor(Math.log10(maxAbs));
+    const inDomain = (v) => v >= lo && v <= hi;
+    // Zero and ±knee are the fixed part of the ladder — kept whole, never thinned,
+    // because they are what distinguishes a symlog axis from a log one.
+    const fixed = [0, knee, -knee].filter(inDomain);
+    // Every decade past the knee that the domain actually contains, in ascending
+    // magnitude, each carrying whichever of ±10^e survived.
+    const rungs = [];
+    for (let e = firstExp; e <= lastExp; e += 1) {
+        const pair = [10 ** e, -(10 ** e)].filter(inDomain);
+        if (pair.length > 0)
+            rungs.push(pair);
+    }
+    // No rung survives ⇒ there is no logarithmic region to grid, so the linear
+    // ticks are the answer — the same reasoning as the knee-swallows-the-domain
+    // guard above, and the case that used to produce an empty axis. Note this also
+    // covers a window sitting *between* the knee and the first decade.
+    if (rungs.length === 0)
+        return scale.ticks(count);
+    // Thin the SURVIVING rungs to what is left of the budget after the fixed
+    // ticks. Stepping by magnitude keeps a rung's ± pair together, so the grid
+    // stays symmetric wherever the domain is.
+    const budget = Math.max(2, count);
+    const total = rungs.reduce((n, pair) => n + pair.length, 0);
+    const room = Math.max(1, budget - fixed.length);
+    const step = Math.max(1, Math.ceil(total / room));
+    const out = new Set(fixed);
+    for (let i = 0; i < rungs.length; i += step)
+        for (const v of rungs[i])
+            out.add(v);
+    return [...out].sort((a, b) => a - b);
+}
 //# sourceMappingURL=yticks.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -24,11 +24,12 @@
   },
   "files": [
     "dist",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "API.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepack": "cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && npm run build && cp cjs-fallback.cjs dist/cjs-fallback.cjs && find dist -name '*.map' -delete",
+    "prepack": "cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && cp ../../API.md ./API.md && npm run build && cp cjs-fallback.cjs dist/cjs-fallback.cjs && find dist -name '*.map' -delete",
     "test": "npm run test:type && npm run test:runtime",
     "test:type": "tsc -p tsconfig.types.json",
     "test:runtime": "vitest run",
@@ -38,8 +39,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.58.0",
-    "pond-ts": "^0.58.0",
+    "@pond-ts/react": "^0.60.0",
+    "pond-ts": "^0.60.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {