@pond-ts/charts 0.68.0 → 0.69.0

package/dist/XAxis.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useContext, useRef } from 'react';
+import { Fragment, useContext, useMemo, useRef } from 'react';
 import { scaleLinear } from 'd3-scale';
+import { TimeZone } from 'pond-ts';
 import { derivedTicks } from './derivedTicks.js';
 import { ContainerContext, CursorContext, } from './context.js';
 import { tickValues } from './yticks.js';
@@ -166,7 +167,7 @@ export function thinCategoryLabels(ticks, slot, plotWidth, fontSize, fontFamily)
  * plot's own drag, including `bounds` / `minDuration` and the trading calendar.
  * A category axis has no continuous domain and stays inert.
  */
-export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', dateStyle = 'flat', onMouseEvent, } = {}) {
+export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', dateStyle = 'flat', timeZone, onMouseEvent, } = {}) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
@@ -175,7 +176,38 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     // `xTickCount` is the container's shared x-side count — the same value the x
     // gridlines and `formatTime` use, so labels and grid stay on the same instants
     // (width-derived on a trading-time axis).
-    const { xScale, plotWidth, leftGutter, theme, formatTime, xKind, xTickCount, } = container;
+    const { xScale: containerScale, plotWidth, leftGutter, theme, formatTime: containerFormatTime, xKind, xTickCount, } = container;
+    // A per-strip zone: the container's shared scale re-derived with its
+    // calendar in `timeZone` — identical pixel mapping, so every `xScale(v)`
+    // below lands where the plot puts it, but ticks / labels / bands / this
+    // strip's pills come from this zone's ladder. Canonicalised (and validated)
+    // so an unknown id throws by name and `'utc'` / `'UTC'` memoize as one.
+    const zonedScale = useMemo(() => {
+        if (timeZone === undefined ||
+            xKind !== 'time' ||
+            !('withTimeZone' in containerScale)) {
+            return undefined;
+        }
+        const id = TimeZone.of(timeZone).id;
+        const s = containerScale;
+        return s.timeZone() === id ? undefined : s.withTimeZone(id);
+    }, [containerScale, timeZone, xKind]);
+    const xScale = zonedScale ?? containerScale;
+    // The label formatter this strip falls back to when no explicit `format`
+    // shapes it. The container's `formatTime` was resolved in the container's
+    // zone; a zoned strip needs the same channel in its own — the grain-aware
+    // default, or the container's `timeFormat` specifier re-resolved (a
+    // function `timeFormat` receives epoch ms and is used verbatim either way).
+    const formatTime = useMemo(() => {
+        if (zonedScale === undefined)
+            return containerFormatTime;
+        const custom = container.timeFormat;
+        if (typeof custom === 'function')
+            return custom;
+        return custom === undefined
+            ? zonedScale.readoutFormat(xTickCount)
+            : resolveTimeFormat(zonedScale, xTickCount, custom);
+    }, [zonedScale, containerFormatTime, container.timeFormat, xTickCount]);
     // The cursor's x-axis slot: did the mounted cursor in effect register one
     // (`renderXAxis` — the crosshair's time pill)? While hovering, that is the
     // **hovered row's** effective cursor — so a per-row override reaches this

package/dist/context.d.ts

@@ -270,6 +270,20 @@ export interface ContainerFrame {
      * tick labels) without moving them.
      */
     readonly formatReadout?: ((value: number) => string) | undefined;
+    /**
+     * The IANA zone the time axis renders in — the container's resolved
+     * `timeZone` (explicit prop, else the calendar's), canonical id; `undefined`
+     * when the axis is in the runtime's local zone. For a consumer's own
+     * formatter (`timeFormat` / `cursorFormat` functions receive epoch ms) to
+     * read the same zone the ticks do.
+     */
+    readonly timeZone: string | undefined;
+    /**
+     * The container's raw `timeFormat` prop, for a strip that must re-resolve it
+     * in another zone (`<XAxis timeZone>`): a specifier string is re-resolved
+     * against that strip's zoned scale, a function is used verbatim.
+     */
+    readonly timeFormat: AxisFormat | undefined;
     /** Whether an explicit container `timeFormat` shaped {@link formatTime}. The
      *  x axis suppresses its boundary (second) label row when it's set — a
      *  custom format owns the whole label, so the ladder mustn't second-line it. */

package/dist/index.d.ts

@@ -68,8 +68,8 @@ export type { ChartLegend, LegendRow, LegendItem } from './useChartLegend.js';
 export { useChartFrame } from './useChartFrame.js';
 export type { ChartFrame, ChartFrameRow, ChartBands, ChartBand, } from './useChartFrame.js';
 export type { ChartXScale } from './context.js';
-export { scaleTradingTime } from './tradingTimeScale.js';
-export type { TradingTimeScale, DiscontinuityProvider, TimeGrain, } from './tradingTimeScale.js';
+export { scaleTradingTime, identityProvider } from './tradingTimeScale.js';
+export type { TradingTimeScale, DiscontinuityProvider, TradingCalendarLike, ScaleTimeZoneOptions, TimeGrain, } from './tradingTimeScale.js';
 export { scaleBand } from './bandScale.js';
 export type { ScaleBand } from './bandScale.js';
 export { Region, Baseline, Marker, Zone } from './annotations.js';

package/dist/index.js

@@ -58,7 +58,7 @@ export { useChartLegend } from './useChartLegend.js';
 // by mirroring the library's own gutter arithmetic — a duplicate that drifts
 // silently the moment the library changes how a gutter is sized.
 export { useChartFrame } from './useChartFrame.js';
-export { scaleTradingTime } from './tradingTimeScale.js';
+export { scaleTradingTime, identityProvider } from './tradingTimeScale.js';
 // The ordinal category (band) scale — the transpose view's "columns on x" axis.
 export { scaleBand } from './bandScale.js';
 // Annotations — user-authored marks in the turquoise register (distinct from the

package/dist/tickLadder.d.ts

@@ -1,3 +1,4 @@
+import { TimeZone } from 'pond-ts';
 import type { DiscontinuityProvider } from './tradingTimeScale.js';
 /**
  * The logical tick ladder — grain selection for a time axis. Ticks sit on real
@@ -34,16 +35,62 @@ export type TickGranularity = 'second1' | 'second5' | 'second15' | 'second30' |
 export type TimeGrain = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
 /** Collapse a {@link TickGranularity} to its coarse {@link TimeGrain} unit. */
 export declare function coarseUnitOf(g: TickGranularity): TimeGrain;
+/** The calendar operations the tick ladder needs. Months are `1…12`. */
+export interface TickCalendar {
+    /** Midnight of the day containing `t`. */
+    startOfDay(t: number): number;
+    /** Midnight of the day after the one containing `t`. */
+    nextDay(t: number): number;
+    /** Midnight of the Monday of the week containing `t`. */
+    startOfWeek(t: number): number;
+    /** The civil date of `t`. */
+    parts(t: number): {
+        year: number;
+        month: number;
+        day: number;
+    };
+    /** Midnight of the first of `month` (`1…12`; `13` carries into the next year, `0` into the previous). */
+    monthStart(year: number, month: number): number;
+    /** Days in `month` of `year`. */
+    daysInMonth(year: number, month: number): number;
+    /**
+     * The first clock-aligned `stepMs` multiple at or after `t`, counted from
+     * `t`'s own midnight — 00:00 / 03:00 / 06:00 … for a 3 h step. The local
+     * calendar steps **fixed milliseconds** from midnight (so on a DST day the
+     * later anchors drift off the wall clock by the shift, until the next
+     * midnight re-anchors — the pre-seam behaviour, kept); a zoned calendar
+     * aligns to the **wall clock**, so 6 h anchors read 00 / 06 / 12 / 18 on
+     * both sides of the jump, with one short or long gap at the transition.
+     * Always `>= t`.
+     */
+    nextAligned(t: number, stepMs: number): number;
+    /**
+     * The anchor after an aligned anchor `t` at `stepMs`. The local calendar
+     * steps `t + stepMs` — fixed elapsed milliseconds, the pre-seam loop
+     * verbatim, which is what keeps a session that spans a DST midnight (a
+     * futures 18:00 → 17:00 session) ticking exactly as it did. A zoned
+     * calendar re-aligns through {@link nextAligned} so the anchors stay on
+     * the wall clock across the jump.
+     */
+    nextAnchor(t: number, stepMs: number): number;
+}
+/** The runtime-local calendar — `Date`'s local accessors, exactly as the
+ *  ladder computed before it had a zone. The default {@link TickCalendar}. */
+export declare const localTickCalendar: TickCalendar;
+/** A {@link TickCalendar} for an IANA zone, on core's `TimeZone`. */
+export declare function zonedTickCalendar(zone: TimeZone): TickCalendar;
+/** 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 declare function tickCalendarFor(timeZone: string | undefined): TickCalendar;
 /**
- * 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 declare function bucketKey(t: number, g: TickGranularity): number;
+export declare function bucketKey(t: number, g: TickGranularity, cal?: TickCalendar): number;
 /**
  * Thin an ascending run of **session opens** down to about `count` axis ticks.
  * Picks the finest rung: every session → **per-month uniform session stride**
@@ -82,7 +129,7 @@ export declare function bucketKey(t: number, g: TickGranularity): number;
  * This is the day-and-coarser half of the ladder; {@link buildTicks} adds the
  * sub-day rungs.
  */
-export declare function coarsenCalendar(opens: readonly number[], count: number, spanDays?: number, provider?: DiscontinuityProvider): {
+export declare function coarsenCalendar(opens: readonly number[], count: number, spanDays?: number, provider?: DiscontinuityProvider, cal?: TickCalendar): {
     ticks: number[];
     granularity: TickGranularity;
 };
@@ -105,7 +152,7 @@ export declare function coarsenCalendar(opens: readonly number[], count: number,
  * 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 declare function buildGridLevels(provider: DiscontinuityProvider, opens: readonly number[], domainEnd: number, cap: number): Array<{
+export declare function buildGridLevels(provider: DiscontinuityProvider, opens: readonly number[], domainEnd: number, cap: number, cal?: TickCalendar): Array<{
     granularity: TickGranularity;
     values: number[];
 }>;
@@ -130,7 +177,7 @@ export declare function nominalStepMs(g: TickGranularity): number;
  * themselves fit — a year of daily sessions never wastes time generating hour
  * anchors.
  */
-export declare function buildTicks(provider: DiscontinuityProvider, opens: readonly number[], domainEnd: number, cap: number): {
+export declare function buildTicks(provider: DiscontinuityProvider, opens: readonly number[], domainEnd: number, cap: number, cal?: TickCalendar): {
     ticks: number[];
     granularity: TickGranularity;
 };
@@ -181,14 +228,13 @@ export declare function bandFormatFor(g: TickGranularity): string;
  * 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 declare function bandShaded(t: number, g: TickGranularity): boolean;
-/** 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 declare function bandStartOf(t: number, g: TickGranularity): number;
+export declare function bandShaded(t: number, g: TickGranularity, cal?: TickCalendar): boolean;
+/** 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 declare function bandStartOf(t: number, g: TickGranularity, cal?: TickCalendar): number;
 /** The start of the band grain `g` **after** the one containing `t` — the next
- *  local midnight / month start / Jan 1. */
-export declare function bandNext(t: number, g: TickGranularity): number;
+ *  midnight / month start / Jan 1 in `cal`'s zone. */
+export declare function bandNext(t: number, g: TickGranularity, cal?: TickCalendar): number;
 /**
  * Which of `ticks` (at grain `granularity`) carry a boundary label: every tick
  * whose boundary-grain bucket differs from the previous tick's — i.e. a
@@ -199,7 +245,7 @@ export declare function bandNext(t: number, g: TickGranularity): number;
  * tick-to-tick on a live sliding window). Empty when the grain has no
  * boundary row (year grain).
  */
-export declare function boundaryTicks(ticks: readonly number[], granularity: TickGranularity, domainStart?: number): number[];
+export declare function boundaryTicks(ticks: readonly number[], granularity: TickGranularity, domainStart?: number, cal?: TickCalendar): number[];
 /**
  * The terse **base** (non-promoted) flat label format for grain `g` — the label
  * a tick carries when it opens no coarser period: the clock time for a sub-day
@@ -228,5 +274,5 @@ export declare function flatBaseFormatFor(g: TickGranularity): string;
  * opening at May 1 midnight reads `May 16 …`, not `1 16 …`). Without
  * `domainStart` the first tick is never promoted.
  */
-export declare function flatFormats(ticks: readonly number[], granularity: TickGranularity, domainStart?: number): string[];
+export declare function flatFormats(ticks: readonly number[], granularity: TickGranularity, domainStart?: number, cal?: TickCalendar): string[];
 //# sourceMappingURL=tickLadder.d.ts.map