@pond-ts/charts 0.68.0 → 0.69.0

package/dist/tickLadder.js

@@ -1,3 +1,4 @@
+import { TimeZone } from 'pond-ts';
 /** Collapse a {@link TickGranularity} to its coarse {@link TimeGrain} unit. */
 export function coarseUnitOf(g) {
     if (g.startsWith('second'))
@@ -32,43 +33,131 @@ const SUB_DAY_GRAINS = [
 function isSubDay(g) {
     return g !== 'day' && SUB_DAY_GRAINS.some((r) => r.g === g);
 }
+/** The runtime-local calendar — `Date`'s local accessors, exactly as the
+ *  ladder computed before it had a zone. The default {@link TickCalendar}. */
+export const localTickCalendar = {
+    startOfDay: (t) => {
+        const d = new Date(t);
+        return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+    },
+    nextDay: (t) => {
+        const d = new Date(t);
+        return new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime();
+    },
+    startOfWeek: (t) => {
+        const d = new Date(t);
+        const dow = (d.getDay() + 6) % 7; // 0 = Monday
+        // Local midnight of this week's Monday (Date normalizes a negative date).
+        return new Date(d.getFullYear(), d.getMonth(), d.getDate() - dow).getTime();
+    },
+    parts: (t) => {
+        const d = new Date(t);
+        return { year: d.getFullYear(), month: d.getMonth() + 1, day: d.getDate() };
+    },
+    monthStart: (year, month) => new Date(year, month - 1, 1).getTime(),
+    daysInMonth: (year, month) => new Date(year, month, 0).getDate(),
+    nextAligned: (t, stepMs) => {
+        const d = new Date(t);
+        const midnight = new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+        return midnight + Math.ceil((t - midnight) / stepMs) * stepMs;
+    },
+    nextAnchor: (t, stepMs) => t + stepMs,
+};
+/** A {@link TickCalendar} for an IANA zone, on core's `TimeZone`. */
+export function zonedTickCalendar(zone) {
+    const monthStart = (year, month) => {
+        // Normalise an overflowed month the way the Date constructor does.
+        const total = year * 12 + (month - 1);
+        const y = Math.floor(total / 12);
+        const m = total - y * 12 + 1;
+        return zone.instant({ year: y, month: m, day: 1 });
+    };
+    return {
+        startOfDay: (t) => zone.startOf('day', t),
+        nextDay: (t) => zone.next('day', t),
+        startOfWeek: (t) => zone.startOf('week', t),
+        parts: (t) => {
+            const p = zone.parts(t);
+            return { year: p.year, month: p.month, day: p.day };
+        },
+        monthStart,
+        daysInMonth: (year, month) => Math.round((monthStart(year, month + 1) - monthStart(year, month)) / DAY_MS),
+        nextAligned: zonedNextAligned,
+        nextAnchor: (t, stepMs) => zonedNextAligned(t + 1, stepMs),
+    };
+    function zonedNextAligned(t, stepMs) {
+        {
+            const p = zone.parts(t);
+            const sinceMidnight = ((p.hour * 60 + p.minute) * 60 + p.second) * 1000 + p.millisecond;
+            // Walk wall-clock multiples of the step until one resolves at or after
+            // `t`: a repeated hour (fall-back) can resolve a wall time to its
+            // earlier reading, which sits before a `t` in the later one.
+            for (let k = Math.ceil(sinceMidnight / stepMs);; k += 1) {
+                const target = k * stepMs;
+                if (target >= DAY_MS)
+                    return zone.next('day', t);
+                const hour = Math.floor(target / HOUR_MS);
+                const minute = Math.floor((target - hour * HOUR_MS) / MIN_MS);
+                const second = Math.floor((target % MIN_MS) / SEC_MS);
+                const millisecond = target % SEC_MS;
+                const at = zone.instant({
+                    year: p.year,
+                    month: p.month,
+                    day: p.day,
+                    hour,
+                    minute,
+                    second,
+                    millisecond,
+                });
+                if (at >= t)
+                    return at;
+            }
+        }
+    }
+}
+/** Resolve an optional IANA id to the calendar the ladder should use: the
+ *  runtime-local calendar when `timeZone` is undefined, else the zone's. */
+export function tickCalendarFor(timeZone) {
+    return timeZone === undefined
+        ? localTickCalendar
+        : zonedTickCalendar(TimeZone.of(timeZone));
+}
 /**
- * The local-time bucket key for `t` at grain `g` — two instants in the same
- * day / week / month / quarter / year share a key. Local time (not UTC) so it
- * agrees with the local `scaleTime` label formatter; the exchange's own time
- * zone is unknown to the scale (the deferred refinement), and a session open
- * sits well inside its local day, so runtime-local grouping matches the
- * exchange day in every ordinary case. Hour grains are never bucketed (each
- * anchor is its own tick), so they key by identity.
+ * The calendar bucket key for `t` at grain `g` — two instants in the same
+ * day / week / month / quarter / year share a key. Computed in `cal`'s zone
+ * (runtime-local by default) so it agrees with the label formatter for the
+ * same zone; a trading axis passes its exchange zone so the grain buckets by
+ * the exchange day rather than the viewer's. Hour grains are never bucketed
+ * (each anchor is its own tick), so they key by identity.
  */
-export function bucketKey(t, g) {
+export function bucketKey(t, g, cal = localTickCalendar) {
     if (isSubDay(g))
         return t;
-    const d = new Date(t);
     switch (g) {
         case 'day':
-            return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
-        case 'week': {
-            const dow = (d.getDay() + 6) % 7; // 0 = Monday
-            // Local midnight of this week's Monday (Date normalizes a negative date).
-            return new Date(d.getFullYear(), d.getMonth(), d.getDate() - dow).getTime();
+            return cal.startOfDay(t);
+        case 'week':
+            return cal.startOfWeek(t);
+        case 'month': {
+            const p = cal.parts(t);
+            return p.year * 12 + (p.month - 1);
+        }
+        case 'quarter': {
+            const p = cal.parts(t);
+            return p.year * 4 + Math.floor((p.month - 1) / 3);
         }
-        case 'month':
-            return d.getFullYear() * 12 + d.getMonth();
-        case 'quarter':
-            return d.getFullYear() * 4 + Math.floor(d.getMonth() / 3);
         case 'year':
-            return d.getFullYear();
+            return cal.parts(t).year;
         default:
             return t;
     }
 }
 /** The first instant of each distinct `g`-bucket in the ascending list `opens`. */
-function firstOfEachBucket(opens, g) {
+function firstOfEachBucket(opens, g, cal) {
     const out = [];
     let prev;
     for (const t of opens) {
-        const k = bucketKey(t, g);
+        const k = bucketKey(t, g, cal);
         if (k !== prev) {
             out.push(t);
             prev = k;
@@ -84,10 +173,6 @@ const COARSENING_LADDER = [
 /** Nominal days per month — the band gate: the session-stride band applies
  *  while a nominal month still affords ≥ 2 marks at the span-derived budget. */
 const DAYS_PER_MONTH = 30.44;
-/** Days in the local month containing `d`. */
-function daysInLocalMonth(d) {
-    return new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate();
-}
 /**
  * Whether index `i` marks in a month of `n` sessions/days at stride `k`. Two
  * regimes, split on `m = floor(n / k)` — the whole stride-intervals the month
@@ -134,15 +219,15 @@ function monthMark(i, k, n) {
  * first open has no known predecessor and marks only on its own exact day — a
  * snapped edge mark would appear/disappear with the pan phase.)
  */
-function subdivideMonthsByDay(opens, gapDays) {
+function subdivideMonthsByDay(opens, gapDays, cal) {
     const k = Math.max(2, Math.ceil(gapDays - 1e-9));
     const out = [];
     let prev = null;
     for (const t of opens) {
-        const d = new Date(t);
-        const month = d.getFullYear() * 12 + d.getMonth();
-        const dom = d.getDate();
-        const monthLen = daysInLocalMonth(d);
+        const p = cal.parts(t);
+        const month = p.year * 12 + (p.month - 1);
+        const dom = p.day;
+        const monthLen = cal.daysInMonth(p.year, p.month);
         // Scan window: same month → since the previous open's date; the first
         // open of a new month → from day 1 (a weekend month-start snaps here);
         // the window's first open → its own exact day only (see doc above).
@@ -193,12 +278,13 @@ function subdivideMonthsByDay(opens, gapDays) {
  * never report it — is detected by live-time flow and indexed 0, keeping the
  * world-start month pinned.
  */
-function subdivideMonthsBySession(opens, gapDays, provider) {
+function subdivideMonthsBySession(opens, gapDays, provider, cal) {
     const monthKeyOf = (t) => {
-        const d = new Date(t);
-        return d.getFullYear() * 12 + d.getMonth();
+        const p = cal.parts(t);
+        return p.year * 12 + (p.month - 1);
     };
-    const monthStartOf = (key) => new Date(Math.floor(key / 12), key % 12, 1).getTime();
+    const monthStartOf = (key) => cal.monthStart(Math.floor(key / 12), (key % 12) + 1);
+    const dayOf = (t) => cal.parts(t).day;
     const strideOf = (count, extentDays) => Math.max(2, Math.ceil((gapDays * count) / Math.max(1, extentDays) - 1e-9));
     // Full-month roster: session count + the per-month stride its calendar-day
     // extent affords. Cached per call; ≤ (visible months + 1) provider queries,
@@ -211,9 +297,7 @@ function subdivideMonthsBySession(opens, gapDays, provider) {
             const count = Math.max(1, sessions.length);
             const extentDays = sessions.length === 0
                 ? 0
-                : new Date(sessions[sessions.length - 1]).getDate() -
-                    new Date(sessions[0]).getDate() +
-                    1;
+                : dayOf(sessions[sessions.length - 1]) - dayOf(sessions[0]) + 1;
             r = { count, stride: strideOf(count, extentDays) };
             rosters.set(key, r);
         }
@@ -236,13 +320,11 @@ function subdivideMonthsBySession(opens, gapDays, provider) {
             // roster, detected by live-time flow — it is the month's session 0.
             const worldStart = !exact && pre === 0 && provider.distance(t, t + MIN_MS) > 0;
             const count = Math.max(1, sessions.length + (worldStart ? 1 : 0));
-            const rosterFirstDom = sessions.length > 0 ? new Date(sessions[0]).getDate() : 31;
+            const rosterFirstDom = sessions.length > 0 ? dayOf(sessions[0]) : 31;
             const firstDom = worldStart
-                ? Math.min(new Date(t).getDate(), rosterFirstDom)
+                ? Math.min(dayOf(t), rosterFirstDom)
                 : rosterFirstDom;
-            const lastDom = sessions.length > 0
-                ? new Date(sessions[sessions.length - 1]).getDate()
-                : new Date(t).getDate();
+            const lastDom = sessions.length > 0 ? dayOf(sessions[sessions.length - 1]) : dayOf(t);
             const stride = strideOf(count, lastDom - firstDom + 1);
             rosters.set(key, { count, stride });
             if ((exact || worldStart) && monthMark(pre, stride, count)) {
@@ -301,7 +383,7 @@ function subdivideMonthsBySession(opens, gapDays, provider) {
  * This is the day-and-coarser half of the ladder; {@link buildTicks} adds the
  * sub-day rungs.
  */
-export function coarsenCalendar(opens, count, spanDays, provider) {
+export function coarsenCalendar(opens, count, spanDays, provider, cal = localTickCalendar) {
     if (opens.length <= count)
         return { ticks: [...opens], granularity: 'day' };
     // Per-month uniform session stride. Band-gated to spans where a nominal
@@ -313,18 +395,18 @@ export function coarsenCalendar(opens, count, spanDays, provider) {
     const gapDays = (spanDays ?? openSpanDays) / count;
     if (dailyDense && DAYS_PER_MONTH / gapDays >= 2) {
         const ticks = provider?.boundaries !== undefined
-            ? subdivideMonthsBySession(opens, gapDays, provider)
-            : subdivideMonthsByDay(opens, gapDays);
+            ? subdivideMonthsBySession(opens, gapDays, provider, cal)
+            : subdivideMonthsByDay(opens, gapDays, cal);
         if (ticks.length > 0)
             return { ticks, granularity: 'day' };
     }
     for (const g of COARSENING_LADDER) {
-        const ticks = firstOfEachBucket(opens, g);
+        const ticks = firstOfEachBucket(opens, g, cal);
         if (ticks.length <= count)
             return { ticks, granularity: g };
     }
     // Coarser than yearly isn't a calendar grain — decimate the year starts.
-    const yearly = firstOfEachBucket(opens, 'year');
+    const yearly = firstOfEachBucket(opens, 'year', cal);
     const step = Math.ceil(yearly.length / count);
     return {
         ticks: yearly.filter((_, i) => i % step === 0),
@@ -350,7 +432,7 @@ export function coarsenCalendar(opens, count, spanDays, provider) {
  * the live-span estimate first (like {@link buildTicks}) and skipped when they
  * add no anchor beyond the session opens themselves (that is the day level).
  */
-export function buildGridLevels(provider, opens, domainEnd, cap) {
+export function buildGridLevels(provider, opens, domainEnd, cap, cal = localTickCalendar) {
     const out = [];
     if (cap < 1 || opens.length === 0)
         return out;
@@ -359,7 +441,7 @@ export function buildGridLevels(provider, opens, domainEnd, cap) {
         if (opens.length + Math.floor(liveSpan / step) > cap)
             continue;
         const budget = cap + opens.length + 4;
-        const anchors = stepAnchors(provider, opens, domainEnd, step, budget);
+        const anchors = stepAnchors(provider, opens, domainEnd, step, budget, cal);
         if (anchors.length > budget)
             continue;
         if (anchors.length > opens.length) {
@@ -370,7 +452,7 @@ export function buildGridLevels(provider, opens, domainEnd, cap) {
         out.push({ granularity: 'day', values: [...opens] });
     }
     for (const g of COARSENING_LADDER) {
-        const values = firstOfEachBucket(opens, g);
+        const values = firstOfEachBucket(opens, g, cal);
         if (values.length <= cap)
             out.push({ granularity: g, values });
     }
@@ -407,52 +489,41 @@ export function nominalStepMs(g) {
 /**
  * Whether `t` sits exactly on a calendar instant of grain `g` — a local
  * midnight at day grain, a month / quarter / year start, a clock-aligned
- * step multiple (relative to `t`'s own local midnight, the same convention
- * as {@link nextAligned}) on the sub-day rungs. The window-edge genuineness
+ * step multiple (relative to `t`'s own midnight, the calendar's
+ * `nextAligned` convention) on the sub-day rungs. The window-edge genuineness
  * test in {@link buildTicks} — the only way a **continuous** axis's edge tick
  * survives, since a gap-free provider has no dead time to probe.
  *
- * The sub-day test shares {@link nextAligned}'s **fixed-elapsed-ms** rung
+ * The sub-day test shares the local calendar's **fixed-elapsed-ms** rung
  * convention **by design** — so an edge tick is judged aligned iff it is one
  * of the instants {@link stepAnchors} would actually generate. On the two DST
  * transition days a wall-clock `03:00` is then *not* "aligned" to `hour3`
  * (only 2h elapsed since midnight) while `04:00` is — the same drift the
- * anchors themselves take, and the already-deferred exchange-tz grain
- * refinement (see `nextAligned`), not a fresh inconsistency. It only decides
+ * anchors themselves take (a zoned calendar aligns to the wall clock instead),
+ * not a fresh inconsistency. It only decides
  * whether the *window-edge* tick is kept on those days — nil practical impact
  * (Codex review, #479).
  */
-function alignedToGrain(t, g) {
-    const d = new Date(t);
-    const midnight = new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+function alignedToGrain(t, g, cal) {
+    const midnight = cal.startOfDay(t);
     const sub = SUB_DAY_GRAINS.find((r) => r.g === g);
     if (sub !== undefined)
-        return (t - midnight) % sub.step === 0;
+        return cal.nextAligned(t, sub.step) === t;
     if (t !== midnight)
         return false;
+    const p = cal.parts(t);
     switch (g) {
         case 'month':
-            return d.getDate() === 1;
+            return p.day === 1;
         case 'quarter':
-            return d.getDate() === 1 && d.getMonth() % 3 === 0;
+            return p.day === 1 && (p.month - 1) % 3 === 0;
         case 'year':
-            return d.getDate() === 1 && d.getMonth() === 0;
+            return p.day === 1 && p.month === 1;
         default:
             // 'day' (and the unreachable 'week' — there is no week rung).
             return true;
     }
 }
-/** The first clock-aligned `stepMs` multiple at or after `t`, relative to `t`'s
- *  own local midnight — so a 3-hour step lands on 00:00 / 03:00 / 06:00 local,
- *  whatever the session open was. Fixed-ms stepping from midnight, so on a DST
- *  transition day the later anchors drift off the wall-clock grid by the shift
- *  (labels stay truthful — they format the real instant); exchange-tz grain is
- *  the already-deferred refinement. */
-function nextAligned(t, stepMs) {
-    const d = new Date(t);
-    const midnight = new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
-    return midnight + Math.ceil((t - midnight) / stepMs) * stepMs;
-}
 /**
  * The sub-day anchors at `stepMs`: each session open, plus each clock-aligned
  * step instant strictly inside that session's **live** span. (The caller may
@@ -462,13 +533,16 @@ function nextAligned(t, stepMs) {
  * new provider surface is needed. Bails once `cap` is exceeded (the caller
  * only needs to know the grain doesn't fit).
  */
-function stepAnchors(provider, opens, domainEnd, stepMs, cap) {
+function stepAnchors(provider, opens, domainEnd, stepMs, cap, cal) {
     const out = [];
     for (let i = 0; i < opens.length; i++) {
         const open = opens[i];
         const end = i + 1 < opens.length ? opens[i + 1] : domainEnd;
         out.push(open);
-        for (let t = nextAligned(open + 1, stepMs); t < end; t += stepMs) {
+        // Stepping is the calendar's: local is `t + stepMs` (the pre-seam loop,
+        // so a session spanning a DST midnight ticks exactly as before), zoned
+        // re-aligns each anchor to the wall clock across a DST jump.
+        for (let t = cal.nextAligned(open + 1, stepMs); t < end; t = cal.nextAnchor(t, stepMs)) {
             if (provider.offset(open, provider.distance(open, t)) === t) {
                 out.push(t);
                 if (out.length > cap)
@@ -488,7 +562,7 @@ function stepAnchors(provider, opens, domainEnd, stepMs, cap) {
  * themselves fit — a year of daily sessions never wastes time generating hour
  * anchors.
  */
-export function buildTicks(provider, opens, domainEnd, cap) {
+export function buildTicks(provider, opens, domainEnd, cap, cal = localTickCalendar) {
     const result = (() => {
         if (opens.length <= cap) {
             // Pick the clock rung from the **live-span estimate**, not the
@@ -515,7 +589,7 @@ export function buildTicks(provider, opens, domainEnd, cap) {
                 // phase ticks), try the coarser rungs, whose smaller estimates
                 // leave the budget room to finish.
                 const budget = cap + opens.length + 4;
-                const ticks = stepAnchors(provider, opens, domainEnd, step, budget);
+                const ticks = stepAnchors(provider, opens, domainEnd, step, budget, cal);
                 if (ticks.length > budget)
                     continue;
                 // A clock rung must earn its labels: if it adds no intraday anchor
@@ -534,7 +608,7 @@ export function buildTicks(provider, opens, domainEnd, cap) {
         // put instead of reshuffling when the enumerated open count wobbles ±1.
         // The provider routes the day band to session-index space (screen-even
         // marks; see subdivideMonthsBySession).
-        return coarsenCalendar(opens, cap, (domainEnd - opens[0]) / DAY_MS, provider);
+        return coarsenCalendar(opens, cap, (domainEnd - opens[0]) / DAY_MS, provider, cal);
     })();
     // Round anchors to integer milliseconds: a pan/zoom domain comes from
     // `scale.invert(pixel)` and is fractional, and a fractional anchor breaks
@@ -564,7 +638,7 @@ export function buildTicks(provider, opens, domainEnd, cap) {
         const edge = t[0];
         const genuine = provider.distance(edge, edge + 1) > 0 && // live (a dead edge never ticks)
             (provider.distance(edge - 1, edge) === 0 || // a session open, or…
-                alignedToGrain(edge, result.granularity)); // …exactly on the grain
+                alignedToGrain(edge, result.granularity, cal)); // …exactly on the grain
         if (!genuine)
             t.shift();
     }
@@ -716,42 +790,41 @@ export function bandFormatFor(g) {
  * same-shade day-bands side by side on a gappy calendar. A rare, cosmetic
  * consequence of keeping the shade fixed to the date rather than the slot.
  */
-export function bandShaded(t, g) {
-    const d = new Date(t);
+export function bandShaded(t, g, cal = localTickCalendar) {
+    const p = cal.parts(t);
     let index;
     switch (g) {
         case 'day':
-            // UTC of the local Y/M/D — an integer calendar-day count, DST-immune.
-            index = Math.floor(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()) / 86_400_000);
+            // UTC of the calendar Y/M/D — an integer calendar-day count, DST-immune.
+            index = Math.floor(Date.UTC(p.year, p.month - 1, p.day) / 86_400_000);
             break;
         case 'month':
-            index = d.getFullYear() * 12 + d.getMonth();
+            index = p.year * 12 + (p.month - 1);
             break;
         default: // year
-            index = d.getFullYear();
+            index = p.year;
     }
     return ((index % 2) + 2) % 2 === 1;
 }
-/** The local-time start of the band grain `g` containing `t` (the band's left
- *  edge): local midnight, month start, or Jan 1. Through the Date ctor so DST
- *  and month/year overflow normalize correctly. */
-export function bandStartOf(t, g) {
-    const d = new Date(t);
+/** The start of the band grain `g` containing `t` (the band's left edge) in
+ *  `cal`'s zone: midnight, month start, or Jan 1. */
+export function bandStartOf(t, g, cal = localTickCalendar) {
     if (g === 'day')
-        return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+        return cal.startOfDay(t);
+    const p = cal.parts(t);
     if (g === 'month')
-        return new Date(d.getFullYear(), d.getMonth(), 1).getTime();
-    return new Date(d.getFullYear(), 0, 1).getTime(); // year
+        return cal.monthStart(p.year, p.month);
+    return cal.monthStart(p.year, 1); // year
 }
 /** The start of the band grain `g` **after** the one containing `t` — the next
- *  local midnight / month start / Jan 1. */
-export function bandNext(t, g) {
-    const d = new Date(t);
+ *  midnight / month start / Jan 1 in `cal`'s zone. */
+export function bandNext(t, g, cal = localTickCalendar) {
     if (g === 'day')
-        return new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime();
+        return cal.nextDay(t);
+    const p = cal.parts(t);
     if (g === 'month')
-        return new Date(d.getFullYear(), d.getMonth() + 1, 1).getTime();
-    return new Date(d.getFullYear() + 1, 0, 1).getTime(); // year
+        return cal.monthStart(p.year, p.month + 1);
+    return cal.monthStart(p.year + 1, 1); // year
 }
 /**
  * Which of `ticks` (at grain `granularity`) carry a boundary label: every tick
@@ -763,7 +836,7 @@ export function bandNext(t, g) {
  * tick-to-tick on a live sliding window). Empty when the grain has no
  * boundary row (year grain).
  */
-export function boundaryTicks(ticks, granularity, domainStart) {
+export function boundaryTicks(ticks, granularity, domainStart, cal = localTickCalendar) {
     const bg = boundaryGrainFor(granularity);
     if (bg === undefined)
         return [];
@@ -773,9 +846,9 @@ export function boundaryTicks(ticks, granularity, domainStart) {
     // window whose cramped 23:55 lead was dropped still marks 00:00 as the
     // day turn); a first tick in the same period is not (no tick-hopping
     // context on a live window).
-    let prev = domainStart !== undefined ? bucketKey(domainStart, bg) : undefined;
+    let prev = domainStart !== undefined ? bucketKey(domainStart, bg, cal) : undefined;
     for (const t of ticks) {
-        const k = bucketKey(t, bg);
+        const k = bucketKey(t, bg, cal);
         if (prev !== undefined && k !== prev)
             out.push(t);
         prev = k;
@@ -865,7 +938,7 @@ function flatPromotionFormatFor(level) {
  * opening at May 1 midnight reads `May 16 …`, not `1 16 …`). Without
  * `domainStart` the first tick is never promoted.
  */
-export function flatFormats(ticks, granularity, domainStart) {
+export function flatFormats(ticks, granularity, domainStart, cal = localTickCalendar) {
     const base = flatBaseFormatFor(granularity);
     const levels = flatPromotionLevels(granularity);
     // Last-seen bucket per level; seeded from just before the domain start so a
@@ -874,13 +947,13 @@ export function flatFormats(ticks, granularity, domainStart) {
     const prev = new Map();
     if (domainStart !== undefined) {
         for (const L of levels)
-            prev.set(L, bucketKey(domainStart - 1, L));
+            prev.set(L, bucketKey(domainStart - 1, L, cal));
     }
     return ticks.map((t) => {
         let spec = base;
         let promoted = false;
         for (const L of levels) {
-            const k = bucketKey(t, L);
+            const k = bucketKey(t, L, cal);
             // Coarsest changed level wins; still update every level's bucket so a
             // year turn (which also turns the month/day) leaves them all current.
             if (!promoted && prev.has(L) && prev.get(L) !== k) {

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