@pond-ts/charts 0.59.0 → 0.60.0

package/dist/useChartFrame.js

@@ -0,0 +1,155 @@
+/**
+ * `useChartFrame()` — **the resolved plot geometry, published**.
+ *
+ * A consumer whose chrome has to line up with the plot (a per-slot header
+ * table above it, a column summary strip below it, a card pinned over one
+ * band, a colour ramp keyed to the plot's own scale) needs the numbers the
+ * container already resolved: where the plot starts, how wide it is, and the
+ * scales that map data to pixels inside it. Before this hook none of that was
+ * reachable, so consumers re-derived it — pin every axis gutter to a fixed
+ * width so it stops depending on label content, measure the outer box,
+ * subtract, and re-implement the band packing.
+ *
+ * **That duplicate is not merely verbose, it is wrong over time.** It holds
+ * only until the library changes how a gutter is sized or how bands are
+ * packed, at which point the consumer's chrome slides out of alignment with
+ * the plot it labels — with no type error and no failing test. Reading the
+ * frame converts a silent drift hazard into a version-checked API.
+ *
+ * ## The x / y split is the library's own
+ *
+ * The shape mirrors the architecture rather than flattening it: **the
+ * container owns x** (one shared scale, so every row's plot left-aligns under
+ * one time axis) and **rows own y** (row-local data, one scale per axis id).
+ * So {@link ChartFrame.plot} carries x only, and y lives on
+ * {@link ChartFrame.row} — which is `null` when the hook is called outside a
+ * `<ChartRow>`.
+ *
+ * That `null` is the point. The common case (a header strip above the plot,
+ * a sibling of the rows) genuinely has no y geometry, and the alternative —
+ * reporting `height: 0` — is the same silent-misalignment failure this hook
+ * exists to remove. A consumer that needs y must be inside a row, and the
+ * type says so.
+ *
+ * ## Scope follows placement
+ *
+ * Exactly as {@link useChartLegend} does: at the container level you get the
+ * shared x frame and `row: null`; inside a `<ChartRow>` you additionally get
+ * that row's y scales. No prop selects the scope — placement does.
+ *
+ * ## Pixel origins
+ *
+ * Two different boxes, because the DOM has two:
+ *
+ * - `plot.x` / `plot.width` are relative to the **container's** box, so a
+ *   `<div>` sibling of the rows pads by `plot.x` to align.
+ * - `xScale(v)` and `bands.at(i)` are relative to the **plot**, i.e. `0 …
+ *   plot.width` — the coordinate system the canvas draws in. Add `plot.x` to
+ *   place DOM chrome in container space.
+ * - `row.topInset` / `row.height` are relative to the **row's** box.
+ *
+ * @example Align a per-slot header strip above a categorical plot
+ * ```tsx
+ * function SlotHeader() {
+ *   const { plot, bands } = useChartFrame();
+ *   if (bands === null) return null;
+ *   return (
+ *     <div style={{ position: 'relative', height: 22, marginLeft: plot.x, width: plot.width }}>
+ *       {bands.labels.map((label, i) => {
+ *         const b = bands.at(i)!;
+ *         return (
+ *           <div key={label} style={{ position: 'absolute', left: b.x0, width: b.x1 - b.x0 }}>
+ *             {label}
+ *           </div>
+ *         );
+ *       })}
+ *     </div>
+ *   );
+ * }
+ *
+ * <ChartContainer categories={tickers} width="auto">
+ *   <SlotHeader />
+ *   <ChartRow height={200}>…</ChartRow>
+ * </ChartContainer>
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { useContext, useMemo } from 'react';
+import { ContainerContext, RowContext, } from './context.js';
+/** Whether the container resolved an ordinal scale (which alone carries `label`). */
+function asBandScale(scale, kind) {
+    return kind === 'category' ? scale : null;
+}
+/**
+ * Read the container's resolved plot geometry — the plot rect, the axis
+ * gutters, the shared x scale, the row's y scales, and (on a category axis)
+ * the ordinal slot edges. See the module docblock for the x/y split, the
+ * placement-scoped `row` half, and which box each pixel value is relative to.
+ *
+ * Must be called under a `<ChartContainer>`; throws otherwise. To render the
+ * markup *outside* the chart's box, portal it out (`createPortal`) — context
+ * flows through portals.
+ */
+export function useChartFrame() {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('useChartFrame() must be used inside a <ChartContainer>');
+    }
+    const row = useContext(RowContext);
+    const { leftGutter, rightGutter, plotWidth, xScale, xKind } = container;
+    const bands = useMemo(() => {
+        const band = asBandScale(xScale, xKind);
+        if (band === null)
+            return null;
+        // The slot count is the scale's own domain width, not the label count:
+        // `scaleBand` is built with `domain([0, n])` from the container's resolved
+        // category list, so the domain is the authority on geometry (the labels
+        // ride alongside for naming). They agree today; reading the domain means
+        // they cannot disagree here if that ever stops being true.
+        const [d0, d1] = band.domain();
+        const count = Math.max(0, Math.round(d1 - d0));
+        const pitch = band.step();
+        // Slot `i` is the domain value `d0 + i`; the container always sets
+        // `domain([0, n])` so `d0` is 0 today, but every read goes through it so
+        // an offset domain could never silently shift the labels off the slots.
+        const labels = [];
+        for (let i = 0; i < count; i++)
+            labels.push(band.label(d0 + i + 0.5));
+        return {
+            count,
+            pitch,
+            labels,
+            at(index) {
+                if (!Number.isInteger(index) || index < 0 || index >= count) {
+                    return null;
+                }
+                return {
+                    x0: band(d0 + index),
+                    x1: band(d0 + index + 1),
+                    center: band(d0 + index + 0.5),
+                    label: labels[index] ?? '',
+                };
+            },
+        };
+    }, [xScale, xKind]);
+    const rowHalf = useMemo(() => {
+        if (row === null)
+            return null;
+        return {
+            topInset: row.topInset,
+            height: Math.max(0, row.height - row.topInset),
+            yScales: row.yScales,
+            axisSides: row.axisSides,
+        };
+    }, [row]);
+    return useMemo(() => ({
+        plot: { x: leftGutter, width: plotWidth },
+        gutters: { left: leftGutter, right: rightGutter },
+        xScale,
+        xKind,
+        bands,
+        row: rowHalf,
+    }), [leftGutter, rightGutter, plotWidth, xScale, xKind, bands, rowHalf]);
+}
+//# sourceMappingURL=useChartFrame.js.map

package/dist/useChartLegend.d.ts

@@ -32,6 +32,14 @@ export interface ChartLegend {
      * inset from the chart box on each side. A custom legend laid out above /
      * below the chart pads by `gutters.left` (and `gutters.right`) to align
      * with the plot instead of the y-axis column.
+     *
+     * The same two numbers {@link useChartFrame} publishes as
+     * `ChartFrame.gutters`, kept here so a legend needs one hook rather than
+     * two. **Reach for `useChartFrame()` instead** when the chrome is not a
+     * legend, or when aligning needs more than the gutters — the plot width,
+     * the x scale, the per-slot band edges, or a row's y scales. This field
+     * predates that hook and is the reason it exists: the geometry was
+     * published for exactly one consumer, on a hook named for something else.
      */
     readonly gutters: {
         readonly left: number;

package/dist/viewport.d.ts

@@ -24,13 +24,46 @@ export type TimeRange = readonly [number, number];
  * range untouched) so a mis-specified extent can't collapse the view.
  */
 export declare function clampToBounds(range: TimeRange, bounds: TimeRange): [number, number];
+/**
+ * How a viewport gesture should treat the domain it is moving.
+ *
+ * Both flags exist because {@link roundRange} was written for a **millisecond**
+ * axis and silently assumed every axis was one.
+ */
+export interface ViewportOptions {
+    /**
+     * Snap the result to whole integers. **Default `true`** — right for a time
+     * axis, where a fractional domain is meaningless and the 1 ms floor is the
+     * finest real view.
+     *
+     * Pass `false` on a **value** axis, where the units are not milliseconds and
+     * the fractions are the data: a power–duration curve over `[0.5, 10800]`
+     * seconds would otherwise snap its floor to `0`, and a `[0.001, 1]` domain
+     * would collapse to `[0, 1]`.
+     *
+     * The axis kind is a caller's fact, not something to infer from magnitude — a
+     * 0.2 ms span and a 0.2-unit value span are indistinguishable by size, and
+     * guessing breaks whichever one you guessed against.
+     */
+    readonly snap?: boolean;
+    /**
+     * Do the arithmetic in **log space**, where a log axis is linear. Implies
+     * `snap: false`.
+     *
+     * Without it a log axis zooms additively, which drags the value under the
+     * cursor sideways — the one thing zoom must never do — and pans by an offset,
+     * so a drag near the low end walks off the plot while the same drag near the
+     * high end barely moves.
+     */
+    readonly log?: boolean;
+}
 /**
  * Shift a range by `dt` ms (drag-pan). The caller signs `dt` from the gesture —
  * dragging the plot right reveals earlier data, i.e. a negative `dt`. The result
  * is snapped to whole milliseconds ({@link roundRange}) — `dt` comes from a pixel
  * delta through `xScale.invert()`, so it is fractional by construction.
  */
-export declare function panRange(range: TimeRange, dt: number): [number, number];
+export declare function panRange(range: TimeRange, dt: number, options?: ViewportOptions): [number, number];
 /**
  * Zoom `range` around `pivot` (ms) by `factor` — `< 1` zooms in, `> 1` out, with
  * the pivot held fixed (the time under the cursor stays put). Clamped so the
@@ -43,7 +76,7 @@ export declare function panRange(range: TimeRange, dt: number): [number, number]
  * lands on the 1 ms floor the snap guarantees, which is the finest view this
  * model has.
  */
-export declare function zoomRange(range: TimeRange, pivot: number, factor: number, minDuration?: number): [number, number];
+export declare function zoomRange(range: TimeRange, pivot: number, factor: number, minDuration?: number, options?: ViewportOptions): [number, number];
 /**
  * The slice of a discontinuity provider the trading-time viewport math needs —
  * a structural subset of the charts `DiscontinuityProvider` (so `viewport.ts`

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

@@ -57,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,16 @@ 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')

package/package.json

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