@pond-ts/charts 0.46.0 → 0.48.0

package/dist/tickLadder.d.ts

@@ -13,10 +13,27 @@ import type { DiscontinuityProvider } from './tradingTimeScale.js';
  * label doesn't carry (hours → the date, days/weeks → the month, months →
  * the year). The axis renders that as a second label row, once per boundary
  * crossing, so a month row reads `Dec Jan Feb …` with `2026` appearing exactly
- * where the year turns.
+ * where the year turns — the **stacked** date style.
+ *
+ * The **flat** date style (the default, the TradingView look) drops the second
+ * row: each tick that *opens* a coarser calendar period is relabelled **inline**
+ * to that period — the year at a year turn, the month at a month turn, the date
+ * at a day turn under an intraday grain — while every other tick keeps a terse
+ * base label (bare day-of-month, month abbrev, clock time). {@link flatFormats}
+ * computes the per-tick format specifiers for that single row.
  */
 /** The calendar grain a run of tick anchors is bucketed to. */
 export type TickGranularity = 'second1' | 'second5' | 'second15' | 'second30' | 'minute1' | 'minute5' | 'minute15' | 'minute30' | 'hour1' | 'hour3' | 'hour6' | 'hour12' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/**
+ * The **coarse calendar unit** of a resolved grain — the public grain a
+ * `cursorFormat` callback branches on, with the internal 1/5/15/30 strides
+ * collapsed to their unit (`hour1|3|6|12` → `hour`). Stable across zoom steps
+ * within a unit, so a consumer's `grain === 'hour'` check doesn't churn as the
+ * stride changes.
+ */
+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 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
@@ -28,32 +45,86 @@ export type TickGranularity = 'second1' | 'second5' | 'second15' | 'second30' |
  */
 export declare function bucketKey(t: number, g: TickGranularity): number;
 /**
- * Thin an ascending run of **session opens** down to about `count` axis ticks by
- * **calendar grain** — the trading-terminal habit of labelling week / month /
- * year starts rather than an arbitrary every-nth session. Picks the finest grain
- * on the ladder (day → week → month → quarter → year) that yields at most
- * `count` buckets and returns the first open in each; beyond yearly it decimates
- * every-nth so the axis never crowds. Exported so the container can draw session
- * dividers at the same instants the axis labels.
+ * Thin an ascending run of **session opens** down to about `count` axis ticks.
+ * Picks the finest rung: every session → **per-month uniform session stride**
+ * (still day grain, month starts pinned) → month → quarter → year; beyond
+ * yearly it decimates every-nth so the axis never crowds. Exported so the
+ * container can draw session dividers at the same instants the axis labels.
  *
- * `count` is a **cap**, not a target: grains jump by 4–12× up the ladder, so a
- * small fixed count over-coarsens long spans (a mid-year-anchored 12-month daily
- * run spans 6 quarter buckets — capped at 5 it collapses to year grain, 2
- * ticks). Callers size the cap to the room the labels have — the container
- * derives it from plot width — rather than passing a small constant.
+ * The day band thins each month to a **uniform session stride** — the month's
+ * first session, then every `k`-th session, truncated so the gap to the next
+ * month start stays ≥ `k` (slack at the month end, never a cramped tick
+ * before the month label). The decoded-and-validated TradingView algorithm:
+ * with a `provider` the stride runs in **session-index space**
+ * ({@link subdivideMonthsBySession}) — marks an equal number of bars apart,
+ * evenly spaced pixels on a collapsed axis, no weekend snapping; without one
+ * it falls back to day-of-month space ({@link subdivideMonthsByDay}).
+ * Zooming steps the stride through the integers (…4 → 3 → 2 → 1), a ~one-bar
+ * density change that re-labels some interior marks; month / year starts stay
+ * pinned at every zoom, and pans never reshuffle anything (the stride derives
+ * from the span, the indices from the calendar). Schemes tried and rejected
+ * on the way here: a global even day-stride (can't pin month starts — the
+ * `Feb` label drifted with zoom), `round(i·L/div)` division (beats against
+ * the month length), and dyadic midpoint halving (perfect zoom-nesting, but
+ * 2× density jumps and ±1-day wobble inside non-power months; the owner's
+ * TradingView captures showed uniform strides re-labelling on zoom reads
+ * calmer than either wobble). There is deliberately no week rung: a
+ * Monday-anchored week can't pin month starts either, so the day band owns
+ * everything between every-session and month grain.
+ *
+ * `count` is a **cap**, not a target: coarser grains jump by 3–4× (month →
+ * quarter → year), so a small fixed count over-coarsens long spans. Callers
+ * size the cap to the room the labels have — the container derives it from plot
+ * width — rather than passing a small constant. `spanDays` is the domain's
+ * calendar-day span from the caller (stable at a fixed zoom); absent (a direct
+ * call), it falls back to the opens' own span.
  *
  * 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): {
+export declare function coarsenCalendar(opens: readonly number[], count: number, spanDays?: number, provider?: DiscontinuityProvider): {
     ticks: number[];
     granularity: TickGranularity;
 };
+/**
+ * The **grid populations** behind {@link buildTicks}' labels: every ladder rung
+ * that fits `cap` lines, each carrying its FULL anchor population — every
+ * aligned clock instant, every session open, every month / quarter / year
+ * start — finest rung first. The axis *labels* are a thinned subset of one
+ * rung; the grid is the calendar structure itself, so the container draws
+ * every anchor of each returned level and fades a level's lines by their pixel
+ * spacing (a crowding level dissolves while the coarser ones persist — the
+ * map-style hierarchical grid). Levels **nest** (a month start is a session
+ * open; an aligned hour sits inside its session; there is no week rung), so a
+ * consumer de-duplicates shared anchors coarsest-first and each line draws
+ * once, at its coarsest membership's (widest-spaced, so strongest) alpha.
+ *
+ * `cap` is the max lines per level — the caller derives it from plot width ÷
+ * the fade-out spacing, so a level too dense to be visible at all is simply
+ * absent rather than enumerated and thrown away. Sub-day rungs are gated on
+ * 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<{
+    granularity: TickGranularity;
+    values: number[];
+}>;
+/**
+ * The **nominal wall-clock step** of grain `g` in ms — the calendar time one
+ * grid cell of that grain covers (a day is a day whether or not its weekend
+ * neighbours are drawn; a month is ~30.44 days). This is what the grid's
+ * density fade keys off: `width × step / wallSpan` is a grain's spacing on a
+ * gap-free axis, and using it (rather than the measured on-screen gaps) makes
+ * the fade **mode-invariant** — collapsing weekends draws fewer day lines at
+ * the *same* strength, instead of wider-spaced lines that jump to full
+ * opacity at the same zoom.
+ */
+export declare function nominalStepMs(g: TickGranularity): number;
 /**
  * The full-ladder grain selection: given the provider, the domain, and the
  * width-derived `cap`, walk the clock rungs (1s … 30s, 1m … 30m, 1h … 12h)
- * then day → week → month → quarter → year (then decimate) and return the
- * first rung that fits.
+ * then day (thinned by a per-month uniform session stride) → month → quarter → year
+ * (then decimate) and return the first rung that fits.
  * `opens` are the session-open anchors (`[domain start, ...boundaries]`) the
  * caller already has. Sub-day rungs are only reachable when the opens
  * themselves fit — a year of daily sessions never wastes time generating hour
@@ -78,6 +149,46 @@ export declare function majorFormatFor(g: TickGranularity): string;
  *  everything else. Never repeat a unit the first row already shows
  *  (`Jan 2026` under a `Jan 05` tick reads as noise). */
 export declare function boundaryFormatFor(g: TickGranularity): string;
+/** The **band grain** under `g`-grain ticks (the segmented stacked second row):
+ *  the next coarser unit — sub-day → day, day/week → month, month/quarter →
+ *  year, year → none. */
+export declare function bandGrainFor(g: TickGranularity): TickGranularity | undefined;
+/**
+ * d3 specifier for the **cursor / marker readout** at grain `g` — a hovered
+ * instant formatted at the axis's own granularity, never finer. A day-or-coarser
+ * axis reads a **date** (no time-of-day), so a daily bar at a foreign-tz
+ * midnight can't render as `02 AM`; a sub-day axis reads date **+** clock. This
+ * is the grain-aware default that replaces d3's multi-scale default for the
+ * readout (a `cursorFormat` override, when given, wins over it). Unambiguous by
+ * design — the readout carries the year / date the terse tick labels omit.
+ */
+export declare function readoutFormatFor(g: TickGranularity): string;
+/** d3 specifier for a **band** label at band grain `g`: the date for a day band
+ *  (`Jan 12`), the full month for a month band (`January`), the year for a year
+ *  band (`2031`). Left-aligned in the band by the renderer. */
+export declare function bandFormatFor(g: TickGranularity): string;
+/**
+ * The **zebra parity** of the band starting at `t` (band grain `g`) — `true`
+ * when the band is shaded. A stable, pan/zoom-invariant flag derived from the
+ * band's own calendar identity: the year number, the months-since-epoch, or
+ * the **UTC**-day index (UTC so a DST shift never flips a band's shade). Odd
+ * index → shaded, matching the reference frames (2031 / 2033 grey).
+ *
+ * Parity is **absolute** (per calendar period), not per-visible-position — the
+ * price of pan-stability. Calendar-consecutive bands always differ, and
+ * collapsed **weekends** stay clean (Fri→Mon is a 3-index step, odd), but a
+ * lone skipped weekday — a single **holiday**, a 2-index step — can place two
+ * 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;
+/** 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;
 /**
  * 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
@@ -89,4 +200,33 @@ export declare function boundaryFormatFor(g: TickGranularity): string;
  * boundary row (year grain).
  */
 export declare function boundaryTicks(ticks: readonly number[], granularity: TickGranularity, domainStart?: number): 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
+ * grain, a bare day-of-month for day / week (`5`, not `Jan 5` — the month rides
+ * the promoted month-start tick), the month abbrev for month / quarter, the
+ * year for year. Terser than {@link majorFormatFor} (which carries the month on
+ * every day tick) because the flat row leans on inline promotions for context.
+ */
+export declare function flatBaseFormatFor(g: TickGranularity): string;
+/**
+ * The **flat** (single-row) label format specifier for each tick, parallel to
+ * `ticks` (already at grain `granularity`). Each tick shows the coarsest
+ * calendar period it *opens* — a year / month / date promotion — and its terse
+ * {@link flatBaseFormatFor} label otherwise, so the one row reads
+ * `… 30 31 Feb 2 3 …` with `Feb` where the month turns and the year where it
+ * turns. A tick "opens" level L when its L-bucket differs from the previous
+ * tick's; the coarsest changed level wins (a Jan-1 tick promotes to the year,
+ * not the month).
+ *
+ * `domainStart` seeds the walk (like {@link boundaryTicks}): the first tick is
+ * promoted only if it crosses a period relative to the instant just *before*
+ * the domain's left edge — so a window opening mid-month doesn't falsely
+ * promote its first tick (and a live sliding window doesn't flicker the
+ * leftmost label), while a domain starting *exactly* on a boundary still
+ * promotes the boundary tick (it truly is the period's first instant: a window
+ * 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[];
 //# sourceMappingURL=tickLadder.d.ts.map