@pond-ts/charts 0.67.0 → 0.69.0

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,8 +1,30 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.67.0",
+  "version": "0.69.0",
   "private": false,
-  "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
+  "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": [
+    "time-series",
+    "timeseries",
+    "typescript",
+    "streaming",
+    "analytics",
+    "react",
+    "charts",
+    "canvas",
+    "visualization",
+    "line-chart",
+    "candlestick",
+    "ohlc",
+    "realtime",
+    "dashboard",
+    "react-timeseries-charts",
+    "pond-ts"
+  ],
+  "homepage": "https://pond-ts.org/docs/charts/",
+  "bugs": {
+    "url": "https://github.com/pond-ts/pond/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,11 +47,12 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "API.md"
+    "API.md",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "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",
+    "prepack": "cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && cp ../../API.md ./API.md && cp ../../docs/agents/USING_POND.md ./AGENTS.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",
@@ -39,8 +62,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.67.0",
-    "pond-ts": "^0.67.0",
+    "@pond-ts/react": "^0.69.0",
+    "pond-ts": "^0.69.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
@@ -50,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",
@@ -63,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"
   }
 }