@pond-ts/charts 0.46.0 → 0.48.0

package/dist/tradingTimeScale.d.ts

@@ -1,3 +1,4 @@
+import { type TickGranularity, type TimeGrain } from './tickLadder.js';
 /**
  * The structural discontinuity-provider surface `scaleTradingTime` consumes to
  * collapse closed-market time. Charts declares this **shape** itself and never
@@ -16,10 +17,16 @@ export interface DiscontinuityProvider {
     offset(value: number, amount: number): number;
     copy(): DiscontinuityProvider;
     /**
-     * Optional: the domain positions of collapsed gaps strictly inside `(from,
-     * to)` — session/day opens where closed time was removed. The container draws
-     * a **session divider** at each; a provider that omits it just collapses the
-     * axis silently. (A `TradingCalendar.discontinuities()` provider supplies it.)
+     * Optional: the **session roster** strictly inside `(from, to)` — each
+     * session/day open, in ascending order. Consumed two ways: the tick ladder
+     * and the calendar grid treat every entry as a **date anchor** (so a
+     * provider whose sessions are contiguous — the gap-free identity provider,
+     * a full-day-sessions demo — still reports every open); the container's
+     * **session dividers** draw only at the entries that are true collapse
+     * *seams* (removed time immediately precedes them — detected via
+     * {@link distance}), which on a real exchange calendar is all of them.
+     * A provider that omits this just collapses the axis silently. (A
+     * `TradingCalendar.discontinuities()` provider supplies it.)
      */
     boundaries?(from: number, to: number): number[];
 }
@@ -47,14 +54,18 @@ export interface TradingCalendarLike {
  * wherever the container's `xScale` goes.
  *
  * Ticks are **calendar-aware** when the provider enumerates its gaps: `.ticks`
- * walks the logical ladder (hour1 → hour3 → hour6 → hour12 → day → week →
- * month → quarter → year) and returns the finest rung that fits `count`, and
+ * walks the logical ladder (hour1 → hour3 → hour6 → hour12 → day → month →
+ * quarter → year; the day rung also thins by per-month midpoint subdivision before
+ * month grain) and returns the finest rung that fits `count`, and
  * `.tickFormat` labels each anchor at that grain (`%H:%M` for hours, `%b %d`
  * for days/weeks, `%b` for months/quarters, `%Y` for years) while formatting
- * any other instant (the cursor readout) with the d3 multi-scale default. The
+ * any other instant with the d3 multi-scale default (the cursor readout uses
+ * `.readoutFormat`, a grain-aware date/clock format, not this). The
  * coarser context a label drops lives on `.tickBoundaries` — the second-row
- * boundary labels (the date over a clock axis, the year over a day / week /
- * month axis), one per boundary crossing plus the first tick.
+ * boundary labels of the **stacked** date style (the date over a clock axis,
+ * the year over a day / week / month axis), one per boundary crossing plus the
+ * first tick. `.flatFormat` is the **flat** (default) alternative: that context
+ * promoted inline into a single row, the TradingView look.
  * Without a provider `boundaries` method it falls back to interior even-spaced
  * time ticks.
  *
@@ -81,6 +92,18 @@ export interface TradingTimeScale {
      * axis rather than riding a tick; year-grain ticks have no second row.
      */
     tickBoundaries(count?: number): (value: number) => string | undefined;
+    /**
+     * **Flat**-style single-row labels: the coarsest calendar unit each tick
+     * opens (year / month / date) promoted **inline** into the one row, its terse
+     * base label (bare day-of-month, month abbrev, clock time) otherwise — the
+     * TradingView default axis, the alternative to the two-row {@link tickFormat}
+     * + {@link tickBoundaries} stack. Same grain selection as {@link ticks} at the
+     * same `count`, so the labels sit on the tick instants. A non-tick value
+     * formats with the d3 multi-scale default, like {@link tickFormat}; the
+     * cursor readout itself uses {@link readoutFormat} (grain-aware), so ticks
+     * read terse while the crosshair reads an unambiguous date/clock.
+     */
+    flatFormat(count?: number): (value: number) => string;
     /**
      * The boundary-row label for the **domain start** — the reader's left-edge
      * context (`Jan 01` over an intraday axis, the year over a month axis),
@@ -89,6 +112,77 @@ export interface TradingTimeScale {
      * from tick to tick. `undefined` when the grain has no boundary row.
      */
     boundaryContext(count?: number): string | undefined;
+    /**
+     * The **grid populations** — one level per ladder rung that fits the plot,
+     * finest first, each carrying its FULL anchor population in the domain
+     * (every aligned clock instant / session open / month / quarter / year
+     * start, strictly after the domain start — the window's left edge is not a
+     * calendar boundary). Where {@link ticks} thins one rung down to *labels*,
+     * these are the calendar structure the labels sit on: the container draws
+     * every anchor and fades each level as a unit by its `spacing`, so a
+     * crowding level dissolves while the coarser ones persist (the map-style
+     * hierarchical grid). Levels nest — de-duplicate coarsest-first.
+     *
+     * `spacing` is the level's **nominal** spacing in px — `width × the grain's
+     * wall-clock step / the domain's wall span` — i.e. its spacing on a gap-free
+     * axis. Keying the fade off calendar density rather than the measured
+     * on-screen gaps makes the look **mode-invariant**: collapsing weekends
+     * draws fewer day lines at the same strength, instead of wider-spaced day
+     * lines that jump to full opacity at the same zoom.
+     *
+     * `minGapPx` is the spacing at which a level's lines have fully faded; a
+     * level denser than that is omitted outright. Empty without a calendar
+     * (a provider that can't enumerate `boundaries`).
+     */
+    gridLevels(minGapPx?: number): Array<{
+        granularity: TickGranularity;
+        values: number[];
+        spacing: number;
+    }>;
+    /**
+     * The **terse base** label for each tick — the grain's bare unit with **no**
+     * inline promotion (`14:00`, `12`, `Feb`, `2026`), the top row of the
+     * **stacked band** date style. Same anchor set as {@link ticks}; a non-tick
+     * instant (the cursor) falls through to the d3 multi-scale default. This is
+     * `flatFormat` without the promotions — the coarser context lives in the
+     * band row ({@link bands}) instead of inline.
+     */
+    baseFormat(count?: number): (value: number) => string;
+    /**
+     * The **cursor / marker readout** formatter — a hovered instant formatted at
+     * the axis's own grain, never finer (a day-or-coarser axis reads a **date**,
+     * so a daily bar at a foreign-tz midnight never renders as a time-of-day like
+     * `02 AM`; a sub-day axis reads date **+** clock). This is the grain-aware
+     * default the crosshair pill, marker indicators, and annotation auto-labels
+     * use — replacing d3's multi-scale default, which showed local time-of-day
+     * for any off-local-midnight instant. A container `cursorFormat` overrides it.
+     */
+    readoutFormat(count?: number): (value: number) => string;
+    /**
+     * The axis's resolved **coarse grain** ({@link TimeGrain}) at `count` — the
+     * unit the ticks currently sit on (`year` … `second`), strides collapsed. A
+     * `cursorFormat` callback receives this so it can branch on the zoom level
+     * (return a year when zoomed out, a clock when zoomed in) without
+     * re-deriving the ladder the axis already ran.
+     */
+    grain(count?: number): TimeGrain;
+    /**
+     * The **date bands** — the segmented second row of the stacked style. One
+     * entry per next-coarser calendar period touching the domain (day bands
+     * under intraday ticks, month bands under day ticks, year bands under
+     * month/quarter ticks), each `{ start, label, shaded }`: the period's start
+     * instant (the first band's `start` may precede the domain — its label pins
+     * at the left edge), the left-aligned label, and a stable zebra `shaded`
+     * flag keyed to the band's calendar identity (pan/zoom-invariant). The
+     * renderer draws a divider at each interior `start`, fills shaded bands, and
+     * emphasizes the top-row tick sitting at each `start`. Empty at year grain
+     * (nothing coarser to band) and without a calendar provider.
+     */
+    bands(count?: number): Array<{
+        start: number;
+        label: string;
+        shaded: boolean;
+    }>;
     domain(): [number, number];
     domain(next: readonly [number, number]): TradingTimeScale;
     range(): [number, number];
@@ -96,7 +190,7 @@ export interface TradingTimeScale {
     copy(): TradingTimeScale;
 }
 export { coarsenCalendar } from './tickLadder.js';
-export type { TickGranularity } from './tickLadder.js';
+export type { TickGranularity, TimeGrain } from './tickLadder.js';
 /**
  * The trivial gap-free {@link DiscontinuityProvider}: live time **is** wall
  * time, and every local midnight is a "session open". Backing a plain

package/dist/tradingTimeScale.js

@@ -1,5 +1,5 @@
 import { scaleTime } from 'd3-scale';
-import { boundaryFormatFor, boundaryGrainFor, boundaryTicks, buildTicks, majorFormatFor, } from './tickLadder.js';
+import { bandFormatFor, bandGrainFor, bandNext, bandShaded, bandStartOf, boundaryFormatFor, boundaryGrainFor, boundaryTicks, buildGridLevels, buildTicks, coarseUnitOf, flatBaseFormatFor, flatFormats, majorFormatFor, nominalStepMs, readoutFormatFor, } from './tickLadder.js';
 // Grain selection lives in `tickLadder.ts` (the full hour1…year ladder plus
 // the boundary-row helpers); re-exported here so existing imports keep working.
 export { coarsenCalendar } from './tickLadder.js';
@@ -58,10 +58,19 @@ export function scaleTradingTime(provider) {
         return provider.offset(domain[0], frac * totalLive());
     };
     /** The session-open instants in the domain — the first session's open (the
-     *  left edge) plus each collapsed-gap boundary — the axis's date anchors. */
+     *  left edge) plus each collapsed-gap boundary — the axis's date anchors.
+     *  Memoized per domain: both the label ladder ({@link resolved}) and the
+     *  grid populations ({@link TradingTimeScale.gridLevels}) walk these every
+     *  frame of a pan, and on a wide continuous domain the enumeration (one
+     *  Date per day) is the expensive part. */
+    let opensMemo = null;
     const sessionOpens = () => {
-        const bounds = provider.boundaries?.(domain[0], domain[1]) ?? [];
-        return [domain[0], ...bounds];
+        const key = `${domain[0]}:${domain[1]}`;
+        if (opensMemo?.key !== key) {
+            const bounds = provider.boundaries?.(domain[0], domain[1]) ?? [];
+            opensMemo = { key, value: [domain[0], ...bounds] };
+        }
+        return opensMemo.value;
     };
     /** Whether the provider has calendar structure to ladder on. Without a
      *  `boundaries` method there are no anchors — the even-spacing fallback. */
@@ -130,6 +139,78 @@ export function scaleTradingTime(provider) {
         }
         return (value) => labelled.get(value);
     };
+    scale.flatFormat = (count = 10) => {
+        // A non-tick instant always uses the d3 multi-scale default — same as
+        // tickFormat. (The cursor readout doesn't route through here; it uses
+        // readoutFormat, grain-aware.) Without a calendar there are no ladder
+        // anchors, so every value falls through to the default.
+        const defFmt = base.tickFormat(count);
+        if (!hasCalendar())
+            return (value) => defFmt(new Date(value));
+        const { ticks, granularity } = resolved(count);
+        // Seed the promotion walk from the previous **live** instant before the
+        // domain start (clampDown; identity on a continuous axis): a domain that
+        // opens exactly on a month's first session then promotes that tick to the
+        // month (`apr 8 14 …`, not `1 8 14 …`) — the previous session was in
+        // March — while a mid-session start still suppresses the false promotion.
+        const specs = flatFormats(ticks, granularity, provider.clampDown(domain[0] - 1));
+        // One d3 formatter per distinct specifier; most ticks share the base one.
+        const bySpec = new Map();
+        const fmtFor = (spec) => {
+            let f = bySpec.get(spec);
+            if (f === undefined) {
+                f = base.tickFormat(count, spec);
+                bySpec.set(spec, f);
+            }
+            return f;
+        };
+        const labelled = new Map();
+        ticks.forEach((t, i) => labelled.set(t, fmtFor(specs[i])(new Date(t))));
+        return (value) => labelled.get(value) ?? defFmt(new Date(value));
+    };
+    scale.baseFormat = (count = 10) => {
+        // The terse top row of the stacked band style: the grain's bare unit, no
+        // inline promotion (that context lives in the band row). Anchors get the
+        // grain's flat base format; a non-tick instant (the cursor) reads the d3
+        // multi-scale default, so the crosshair still shows a full timestamp.
+        const defFmt = base.tickFormat(count);
+        if (!hasCalendar())
+            return (value) => defFmt(new Date(value));
+        const { ticks, granularity } = resolved(count);
+        const anchors = new Set(ticks);
+        const terse = base.tickFormat(count, flatBaseFormatFor(granularity));
+        return (value) => anchors.has(value) ? terse(new Date(value)) : defFmt(new Date(value));
+    };
+    scale.readoutFormat = (count = 10) => {
+        const defFmt = base.tickFormat(count);
+        if (!hasCalendar())
+            return (value) => defFmt(new Date(value));
+        const fmt = base.tickFormat(count, readoutFormatFor(resolved(count).granularity));
+        return (value) => fmt(new Date(value));
+    };
+    scale.grain = (count = 10) => hasCalendar() ? coarseUnitOf(resolved(count).granularity) : 'day';
+    scale.bands = (count = 10) => {
+        if (!hasCalendar())
+            return [];
+        const bg = bandGrainFor(resolved(count).granularity);
+        if (bg === undefined)
+            return []; // year grain — nothing coarser to band
+        const fmt = base.tickFormat(count, bandFormatFor(bg));
+        const out = [];
+        // First band starts at (or before) the domain start — the partial left
+        // band whose label the renderer pins at x=0; step to each next period
+        // start still inside the domain. Bounded loop as a runaway guard.
+        let s = bandStartOf(domain[0], bg);
+        for (let i = 0; i < 100_000 && s < domain[1]; i++) {
+            out.push({
+                start: s,
+                label: fmt(new Date(s)),
+                shaded: bandShaded(s, bg),
+            });
+            s = bandNext(s, bg);
+        }
+        return out;
+    };
     scale.boundaryContext = (count = 10) => {
         if (!hasCalendar())
             return undefined;
@@ -140,6 +221,37 @@ export function scaleTradingTime(provider) {
         const fmt = base.tickFormat(count, boundaryFormatFor(bg));
         return fmt(new Date(domain[0]));
     };
+    /** Memoized like {@link resolved}: the draw pass asks once per frame, and
+     *  the populations only change with the domain / width / fade floor. */
+    let gridMemo = null;
+    scale.gridLevels = (minGapPx = 4) => {
+        if (!hasCalendar())
+            return [];
+        const width = Math.abs(range[1] - range[0]);
+        const wallSpan = domain[1] - domain[0];
+        if (wallSpan <= 0 || width <= 0)
+            return [];
+        const cap = Math.max(1, Math.floor(width / Math.max(1, minGapPx)));
+        const key = `${domain[0]}:${domain[1]}:${width}:${minGapPx}`;
+        if (gridMemo?.key !== key) {
+            gridMemo = {
+                key,
+                value: buildGridLevels(provider, sessionOpens(), domain[1], cap)
+                    .map((l) => ({
+                    granularity: l.granularity,
+                    // The first open is the domain start itself — a window edge, not
+                    // a boundary (and mid-period in general). Grid lines are the
+                    // strictly-interior anchors.
+                    values: l.values.filter((v) => v > domain[0]),
+                    // Nominal (gap-free) spacing — the fade metric; see the
+                    // interface doc for why it isn't the measured on-screen gap.
+                    spacing: (width * nominalStepMs(l.granularity)) / wallSpan,
+                }))
+                    .filter((l) => l.values.length > 0 && l.spacing > minGapPx),
+            };
+        }
+        return gridMemo.value;
+    };
     function domainFn(next) {
         if (next === undefined)
             return [domain[0], domain[1]];

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pjm17971/pond-ts.git",
+    "url": "git+https://github.com/pond-ts/pond.git",
     "directory": "packages/charts"
   },
   "type": "module",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.46.0",
-    "pond-ts": "^0.46.0",
+    "@pond-ts/react": "^0.48.0",
+    "pond-ts": "^0.48.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {