@pond-ts/charts 0.68.0 → 0.70.0

package/dist/tradingAxis.fixture.d.ts

@@ -50,6 +50,25 @@ export declare function ticks(sessions: Session[], stepMs: number): TimeSeries<t
  *  pen-up. (Plain {@link ticks} walks continuously across sessions, so close ≈
  *  next open and the break is invisible — this is the fixture that shows it.) */
 export declare function gappingTicks(sessions: Session[], stepMs: number): TimeSeries<typeof tickSchema>;
+export declare const envelopeSchema: readonly [{
+    readonly name: "time";
+    readonly kind: "time";
+}, {
+    readonly name: "price";
+    readonly kind: "number";
+}, {
+    readonly name: "lo";
+    readonly kind: "number";
+}, {
+    readonly name: "hi";
+    readonly kind: "number";
+}];
+/** {@link gappingTicks} plus a `lo` / `hi` envelope around the price (a slowly
+ *  breathing spread), so a `<BandChart>` on the trading axis shows the same
+ *  overnight jump the line does: connected, the fill runs a near-vertical sliver
+ *  from one session's close to the next open; with `sessionBreaks` it ends at
+ *  the close and re-starts at the open. */
+export declare function gappingEnvelope(sessions: Session[], stepMs: number): TimeSeries<typeof envelopeSchema>;
 export declare const OHLC: {
     readonly open: {
         readonly from: "price";

package/dist/tradingAxis.fixture.js

@@ -195,6 +195,30 @@ export function gappingTicks(sessions, stepMs) {
     });
     return new TimeSeries({ name: 'ticks', schema: tickSchema, rows });
 }
+export const envelopeSchema = [
+    { name: 'time', kind: 'time' },
+    { name: 'price', kind: 'number' },
+    { name: 'lo', kind: 'number' },
+    { name: 'hi', kind: 'number' },
+];
+/** {@link gappingTicks} plus a `lo` / `hi` envelope around the price (a slowly
+ *  breathing spread), so a `<BandChart>` on the trading axis shows the same
+ *  overnight jump the line does: connected, the fill runs a near-vertical sliver
+ *  from one session's close to the next open; with `sessionBreaks` it ends at
+ *  the close and re-starts at the open. */
+export function gappingEnvelope(sessions, stepMs) {
+    const rows = [];
+    let i = 0;
+    sessions.forEach((s, si) => {
+        const base = 100 + si * 6; // each session gaps ~6 above the last
+        for (let t = s.open; t < s.close; t += stepMs, i++) {
+            const price = base + 4 * Math.sin(i / 18) + 1.5 * Math.sin(i / 3.5);
+            const spread = 1.5 + 0.8 * Math.sin(i / 40);
+            rows.push([t, price, price - spread, price + spread]);
+        }
+    });
+    return new TimeSeries({ name: 'envelope', schema: envelopeSchema, rows });
+}
 export const OHLC = {
     open: { from: 'price', using: 'first' },
     high: { from: 'price', using: 'max' },

package/dist/tradingTimeScale.d.ts

@@ -1,4 +1,15 @@
 import { type TickGranularity, type TimeGrain } from './tickLadder.js';
+/** Zone options shared by {@link scaleTradingTime} and {@link identityProvider}. */
+export interface ScaleTimeZoneOptions {
+    /**
+     * The IANA zone the axis's calendar runs in — ticks on that zone's
+     * midnights / Mondays / month starts, labels and readouts reading in it.
+     * **Omitted ⇒ the runtime's local zone** (the browser's), exactly as before
+     * the option existed. Any id `Intl` knows (`'UTC'`, `'Europe/Berlin'`, …);
+     * an unknown id throws `RangeError`.
+     */
+    timeZone?: string | undefined;
+}
 /**
  * The structural discontinuity-provider surface `scaleTradingTime` consumes to
  * collapse closed-market time. Charts declares this **shape** itself and never
@@ -29,6 +40,15 @@ export interface DiscontinuityProvider {
      * `TradingCalendar.discontinuities()` provider supplies it.)
      */
     boundaries?(from: number, to: number): number[];
+    /**
+     * Optional: the same provider with its calendar in another zone. Only a
+     * provider whose gap topology *depends* on a zone needs it — the identity
+     * provider, whose "sessions" are calendar days and therefore move with the
+     * zone; a trading calendar's session opens are instants and do not. Used by
+     * {@link TradingTimeScale.withTimeZone} so a second `<XAxis timeZone>` can
+     * re-derive its day anchors in its own zone.
+     */
+    withTimeZone?(timeZone: string | undefined): DiscontinuityProvider;
 }
 /**
  * The high-level counterpart to a bare {@link DiscontinuityProvider}: anything
@@ -45,6 +65,14 @@ export interface TradingCalendarLike {
     discontinuities(options?: {
         spacing?: 'proportional' | 'uniform';
     }): DiscontinuityProvider;
+    /**
+     * Optional: the exchange's IANA zone. When present and the container has no
+     * explicit `timeZone`, the axis renders in it — ticks on exchange-local day
+     * starts, labels and readouts in exchange time — instead of the viewer's
+     * zone. A `@pond-ts/financial` `TradingCalendar` built `fromRules` carries
+     * its rules' zone here.
+     */
+    readonly timeZone?: string | undefined;
 }
 /**
  * A d3-scale-shaped time scale whose pixel mapping runs through **trading time**
@@ -198,22 +226,35 @@ export interface TradingTimeScale {
     range(): [number, number];
     range(next: readonly [number, number]): TradingTimeScale;
     copy(): TradingTimeScale;
+    /**
+     * The same pixel mapping (provider, domain, range) with its **calendar in
+     * another zone** — `undefined` for runtime-local. The scale's own zone is
+     * unchanged; this is how a second `<XAxis timeZone>` strip ticks and labels
+     * in its own zone over the container's shared x mapping. A provider that
+     * exposes {@link DiscontinuityProvider.withTimeZone} re-derives its day
+     * anchors; any other keeps its instants (a trading calendar's session opens
+     * are zone-independent).
+     */
+    withTimeZone(timeZone: string | undefined): TradingTimeScale;
+    /** The IANA zone this scale's calendar runs in; `undefined` = runtime-local. */
+    timeZone(): string | undefined;
 }
 export { coarsenCalendar } 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
+ * time, and every midnight (in `timeZone`, default runtime-local) is a
+ * "session open". Backing a plain
  * continuous time axis with `scaleTradingTime(identityProvider())` runs it
  * through the same logical tick ladder as a trading-calendar axis — calendar
  * days are the day anchors, so a year of data ticks on month starts and an
  * afternoon ticks on clock-aligned hours, instead of d3's mixed multi-scale
  * default.
  */
-export declare function identityProvider(): DiscontinuityProvider;
+export declare function identityProvider(options?: ScaleTimeZoneOptions): DiscontinuityProvider;
 /**
  * Build a {@link TradingTimeScale} over the given discontinuity `provider`.
  * Configure like a d3 scale: `scaleTradingTime(provider).domain([t0, t1]).range([0, width])`.
  */
-export declare function scaleTradingTime(provider: DiscontinuityProvider): TradingTimeScale;
+export declare function scaleTradingTime(provider: DiscontinuityProvider, options?: ScaleTimeZoneOptions): TradingTimeScale;
 //# sourceMappingURL=tradingTimeScale.d.ts.map

package/dist/tradingTimeScale.js

@@ -1,34 +1,84 @@
-import { scaleTime } from 'd3-scale';
-import { bandFormatFor, bandGrainFor, bandNext, bandShaded, bandStartOf, boundaryFormatFor, boundaryGrainFor, boundaryTicks, buildGridLevels, buildTicks, coarseUnitOf, flatBaseFormatFor, flatFormats, majorFormatFor, nominalStepMs, readoutFormatFor, } from './tickLadder.js';
+import { scaleTime, scaleUtc } from 'd3-scale';
+import { utcFormat } from 'd3-time-format';
+import { TimeZone } from 'pond-ts';
+import { bandFormatFor, bandGrainFor, bandNext, bandShaded, bandStartOf, boundaryFormatFor, boundaryGrainFor, boundaryTicks, buildGridLevels, buildTicks, coarseUnitOf, flatBaseFormatFor, flatFormats, majorFormatFor, nominalStepMs, readoutFormatFor, tickCalendarFor, } from './tickLadder.js';
+/**
+ * The d3 time-specifier formatter for a zone. Local (no zone) is d3's own
+ * `timeFormat` through the scale, untouched. A named zone formats a
+ * **civil-shifted** date — the instant moved by the zone's offset and then
+ * read in UTC — so every `%Y %m %d %H %M %S %a %b %p …` directive reads in the
+ * zone for free; `%Z` / `%z`, which the shift would render `UTC` / `+0000`,
+ * are substituted per instant from the zone itself. The two directives that
+ * print the *instant* rather than a wall-clock field — `%s` (epoch seconds)
+ * and `%Q` (epoch ms) — read the shifted instant, i.e. offset by the zone;
+ * they have no meaning on a zoned axis.
+ */
+function zonedFormatter(zone, specifier) {
+    // Tokenise so an escaped percent (`%%`) is never read as the start of a
+    // directive: `'%%Z'` is a literal `%Z`, not the zone name.
+    const tokens = specifier.match(/%%|%[Zz]|[^%]+|%/g) ?? [];
+    const hasZoneName = tokens.some((tok) => tok === '%Z' || tok === '%z');
+    if (!hasZoneName) {
+        const f = utcFormat(specifier);
+        return (d) => {
+            const t = +d;
+            return f(new Date(t + zone.offsetAt(t)));
+        };
+    }
+    const cache = new Map();
+    return (d) => {
+        const t = +d;
+        const offset = zone.offsetAt(t);
+        const sign = offset < 0 ? '-' : '+';
+        const abs = Math.abs(offset) / 60_000;
+        const hh = String(Math.floor(abs / 60)).padStart(2, '0');
+        const mm = String(abs % 60).padStart(2, '0');
+        const resolved = tokens
+            .map((tok) => tok === '%Z'
+            ? zone.abbreviation(t).replace(/%/g, '%%')
+            : tok === '%z'
+                ? `${sign}${hh}${mm}`
+                : tok)
+            .join('');
+        let f = cache.get(resolved);
+        if (f === undefined) {
+            f = utcFormat(resolved);
+            cache.set(resolved, f);
+        }
+        return f(new Date(t + offset));
+    };
+}
 // 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';
 /**
  * The trivial gap-free {@link DiscontinuityProvider}: live time **is** wall
- * time, and every local midnight is a "session open". Backing a plain
+ * time, and every midnight (in `timeZone`, default runtime-local) is a
+ * "session open". Backing a plain
  * continuous time axis with `scaleTradingTime(identityProvider())` runs it
  * through the same logical tick ladder as a trading-calendar axis — calendar
  * days are the day anchors, so a year of data ticks on month starts and an
  * afternoon ticks on clock-aligned hours, instead of d3's mixed multi-scale
  * default.
  */
-export function identityProvider() {
+export function identityProvider(options = {}) {
+    const cal = tickCalendarFor(options.timeZone);
     const self = {
         clampUp: (t) => t,
         clampDown: (t) => t,
         distance: (from, to) => to - from,
         offset: (v, amount) => v + amount,
         copy: () => self,
+        withTimeZone: (timeZone) => identityProvider({ timeZone }),
         boundaries: (from, to) => {
             const out = [];
-            const d = new Date(from);
-            // First local midnight strictly after `from`; step by calendar day (not
-            // 24h) so DST transitions stay on midnight.
-            let cur = new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1);
-            while (cur.getTime() < to) {
-                if (cur.getTime() > from)
-                    out.push(cur.getTime());
-                cur = new Date(cur.getFullYear(), cur.getMonth(), cur.getDate() + 1);
+            // First midnight (in the zone) strictly after `from`; step by calendar
+            // day (not 24h) so DST transitions stay on midnight.
+            let cur = cal.nextDay(from);
+            while (cur < to) {
+                if (cur > from)
+                    out.push(cur);
+                cur = cal.nextDay(cur);
             }
             return out;
         },
@@ -39,11 +89,31 @@ export function identityProvider() {
  * Build a {@link TradingTimeScale} over the given discontinuity `provider`.
  * Configure like a d3 scale: `scaleTradingTime(provider).domain([t0, t1]).range([0, width])`.
  */
-export function scaleTradingTime(provider) {
+export function scaleTradingTime(provider, options = {}) {
     let domain = [0, 1];
     let range = [0, 1];
-    // A private d3 time scale, kept in sync with the domain, purely for tickFormat.
+    const zone = options.timeZone === undefined ? undefined : TimeZone.of(options.timeZone);
+    const cal = tickCalendarFor(zone?.id);
+    // A private d3 time scale purely for formatting. Local: d3's own `timeFormat`
+    // (and its multi-scale default) untouched. Zoned: the same specifiers on a
+    // civil-shifted date via `utcFormat`, and a `scaleUtc` multi-scale default
+    // on the shifted date so the fallback picks its unit in the zone too.
     const base = scaleTime();
+    const baseUtc = zone === undefined ? undefined : scaleUtc();
+    const fmt = (count, specifier) => {
+        if (zone === undefined) {
+            return specifier === undefined
+                ? base.tickFormat(count)
+                : base.tickFormat(count, specifier);
+        }
+        if (specifier !== undefined)
+            return zonedFormatter(zone, specifier);
+        const def = baseUtc.tickFormat(count);
+        return (d) => {
+            const t = +d;
+            return def(new Date(t + zone.offsetAt(t)));
+        };
+    };
     const totalLive = () => provider.distance(domain[0], domain[1]);
     const scale = ((value) => {
         const live = totalLive();
@@ -86,7 +156,7 @@ export function scaleTradingTime(provider) {
         if (laddered?.key !== key) {
             laddered = {
                 key,
-                value: buildTicks(provider, sessionOpens(), domain[1], count),
+                value: buildTicks(provider, sessionOpens(), domain[1], count, cal),
             };
         }
         return laddered.value;
@@ -110,8 +180,8 @@ export function scaleTradingTime(provider) {
     };
     scale.tickFormat = (count = 10, specifier) => {
         if (specifier !== undefined)
-            return base.tickFormat(count, specifier);
-        const defFmt = base.tickFormat(count);
+            return fmt(count, specifier);
+        const defFmt = fmt(count);
         if (!hasCalendar())
             return defFmt; // no calendar → d3 multi-scale default
         // Anchor labels at the grain {@link ticks} chose — one uniform format per
@@ -122,7 +192,7 @@ export function scaleTradingTime(provider) {
         // the dividers drawn at these instants agree.
         const { ticks, granularity } = resolved(count);
         const anchors = new Set(ticks);
-        const anchorFmt = base.tickFormat(count, majorFormatFor(granularity));
+        const anchorFmt = fmt(count, majorFormatFor(granularity));
         return (d) => (anchors.has(+d) ? anchorFmt(d) : defFmt(d));
     };
     scale.tickBoundaries = (count = 10) => {
@@ -132,10 +202,10 @@ export function scaleTradingTime(provider) {
         const bg = boundaryGrainFor(granularity);
         if (bg === undefined)
             return () => undefined;
-        const fmt = base.tickFormat(count, boundaryFormatFor(bg));
+        const bfmt = fmt(count, boundaryFormatFor(bg));
         const labelled = new Map();
-        for (const t of boundaryTicks(ticks, granularity, domain[0])) {
-            labelled.set(t, fmt(new Date(t)));
+        for (const t of boundaryTicks(ticks, granularity, domain[0], cal)) {
+            labelled.set(t, bfmt(new Date(t)));
         }
         return (value) => labelled.get(value);
     };
@@ -144,7 +214,7 @@ export function scaleTradingTime(provider) {
         // 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);
+        const defFmt = fmt(count);
         if (!hasCalendar())
             return (value) => defFmt(new Date(value));
         const { ticks, granularity } = resolved(count);
@@ -153,13 +223,13 @@ export function scaleTradingTime(provider) {
         // 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));
+        const specs = flatFormats(ticks, granularity, provider.clampDown(domain[0] - 1), cal);
         // 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);
+                f = fmt(count, spec);
                 bySpec.set(spec, f);
             }
             return f;
@@ -173,20 +243,20 @@ export function scaleTradingTime(provider) {
         // 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);
+        const defFmt = fmt(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));
+        const terse = fmt(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);
+        const defFmt = fmt(count);
         if (!hasCalendar())
             return (value) => defFmt(new Date(value));
-        const fmt = base.tickFormat(count, readoutFormatFor(resolved(count).granularity));
-        return (value) => fmt(new Date(value));
+        const rfmt = fmt(count, readoutFormatFor(resolved(count).granularity));
+        return (value) => rfmt(new Date(value));
     };
     scale.grain = (count = 10) => hasCalendar() ? coarseUnitOf(resolved(count).granularity) : 'day';
     scale.bands = (count = 10) => {
@@ -196,7 +266,7 @@ export function scaleTradingTime(provider) {
         const bg = bandGrainFor(granularity);
         if (bg === undefined)
             return []; // year grain — nothing coarser to band
-        const fmt = base.tickFormat(count, bandFormatFor(bg));
+        const bandFmt = fmt(count, bandFormatFor(bg));
         const tickSet = new Set(ticks);
         // A band's raw calendar start is a date, not necessarily a LIVE instant —
         // a month or day beginning on a collapsed weekend/holiday clamps onto the
@@ -207,13 +277,13 @@ export function scaleTradingTime(provider) {
         // can be resolved as one group rather than emitting (and then trying to
         // retract) a label per member.
         const candidates = [];
-        let s = bandStartOf(domain[0], bg);
+        let s = bandStartOf(domain[0], bg, cal);
         // 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.
         for (let i = 0; i < 100_000 && s < domain[1]; i++) {
             candidates.push({ s, live: provider.clampUp(s) });
-            s = bandNext(s, bg);
+            s = bandNext(s, bg, cal);
         }
         const out = [];
         for (let i = 0; i < candidates.length;) {
@@ -249,9 +319,9 @@ export function scaleTradingTime(provider) {
                 // Formatted from the representative's own RAW start, not the
                 // clamped one — a genuinely-live rep reads its own date; a
                 // gap-only run's rep reads whichever raw date it fell back to.
-                label: fmt(new Date(rep.s)),
+                label: bandFmt(new Date(rep.s)),
                 showLabel: !collides,
-                shaded: bandShaded(rep.s, bg),
+                shaded: bandShaded(rep.s, bg, cal),
             });
             i = j;
         }
@@ -264,8 +334,7 @@ export function scaleTradingTime(provider) {
         const bg = boundaryGrainFor(granularity);
         if (bg === undefined)
             return undefined;
-        const fmt = base.tickFormat(count, boundaryFormatFor(bg));
-        return fmt(new Date(domain[0]));
+        return fmt(count, boundaryFormatFor(bg))(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. */
@@ -282,7 +351,7 @@ export function scaleTradingTime(provider) {
         if (gridMemo?.key !== key) {
             gridMemo = {
                 key,
-                value: buildGridLevels(provider, sessionOpens(), domain[1], cap)
+                value: buildGridLevels(provider, sessionOpens(), domain[1], cap, cal)
                     .map((l) => ({
                     granularity: l.granularity,
                     // The first open is the domain start itself — a window edge, not
@@ -312,7 +381,13 @@ export function scaleTradingTime(provider) {
         return scale;
     }
     scale.range = rangeFn;
-    scale.copy = () => scaleTradingTime(provider.copy()).domain(domain).range(range);
+    scale.copy = () => scaleTradingTime(provider.copy(), options).domain(domain).range(range);
+    scale.withTimeZone = (timeZone) => scaleTradingTime(provider.withTimeZone?.(timeZone) ?? provider.copy(), {
+        timeZone,
+    })
+        .domain(domain)
+        .range(range);
+    scale.timeZone = () => zone?.id;
     return scale;
 }
 //# sourceMappingURL=tradingTimeScale.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.68.0",
+  "version": "0.70.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first React time-series charts for pond-ts: line, area, band, bar, scatter, box, candlestick, with cursors, selection and annotations",
   "keywords": [
@@ -62,8 +62,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.68.0",
-    "pond-ts": "^0.68.0",
+    "@pond-ts/react": "^0.70.0",
+    "pond-ts": "^0.70.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
@@ -73,6 +73,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/d3-scale": "^4.0.9",
     "@types/d3-shape": "^3.1.8",
+    "@types/d3-time-format": "^4.0.3",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.2.3",
     "happy-dom": "^20.9.0",
@@ -86,6 +87,7 @@
   },
   "dependencies": {
     "d3-scale": "^4.0.2",
-    "d3-shape": "^3.2.0"
+    "d3-shape": "^3.2.0",
+    "d3-time-format": "^4.1.0"
   }
 }