@pond-ts/charts 0.45.0 → 0.47.0

package/dist/grid.d.ts

@@ -1,13 +1,21 @@
 /**
  * Stroke the plot's gridlines: a vertical line at each `xTicks` pixel and a
- * horizontal line at each `yTicks` pixel, faint and dashed. Drawn behind the
- * data layers from the same tick positions the axes label, so grid and labels
- * line up. `+0.5` aligns each 1px stroke to the device grid for a crisp line.
+ * horizontal line at each `yTicks` pixel, faint and dashed. On a calendar
+ * axis the verticals are the **full grain populations** (every day / month /
+ * aligned hour in view — see `TradingTimeScale.gridLevels`), not just the
+ * labelled ticks. `+0.5` aligns each 1px stroke to the device grid for a
+ * crisp line.
+ *
+ * `xAlphas` (parallel to `xTicks`) fades individual verticals — the
+ * hierarchical density falloff: a crowding grain's lines dim toward invisible
+ * while coarser grains hold full strength. Full-alpha lines (and all the
+ * horizontals) batch into one path; only the fading remainder pays a
+ * per-line stroke. A near-zero alpha is skipped.
  *
  * `save`/`restore` brackets the dash + stroke state so it doesn't leak into the
  * data layers that draw next.
  */
-export declare function drawGrid(ctx: CanvasRenderingContext2D, xTicks: readonly number[], yTicks: readonly number[], width: number, height: number, color: string, dash: readonly number[]): void;
+export declare function drawGrid(ctx: CanvasRenderingContext2D, xTicks: readonly number[], yTicks: readonly number[], width: number, height: number, color: string, dash: readonly number[], xAlphas?: readonly number[]): void;
 /**
  * Greedily thin an **ascending** list of pixel positions so no two kept lines
  * are closer than `minGap` px — keeps the axis from crowding when collapse
@@ -20,6 +28,25 @@ export declare function thinPixels(xs: readonly number[], minGap: number): numbe
  * the plot height. Drawn a touch stronger than the dashed gridlines (solid, so a
  * session/day boundary reads as structural, not just another tick) at the
  * discontinuity provider's collapse points (see `DiscontinuityProvider.boundaries`).
+ *
+ * `alphas` (parallel to `xs`) fades individual lines — used by the `'all'`
+ * session-divider mode so crowding lines dim smoothly toward invisible instead
+ * of popping in/out with a hard density cutoff. Omitted ⇒ every line at full
+ * opacity in a single path (the fast default). A near-zero alpha is skipped.
+ */
+export declare function drawDividers(ctx: CanvasRenderingContext2D, xs: readonly number[], height: number, color: string, alphas?: readonly number[]): void;
+/**
+ * Per-line opacity for {@link drawDividers} in `'all'` mode: each line keys off
+ * the gap to its nearest neighbour — full at `fullPx`+, **zero** at `gonePx`
+ * and below, a quadratic ramp between. So as a zoom-out crowds the session
+ * lines they dim toward a clean plot — no hard drop that pops on pan.
+ *
+ * The curve must fall **superlinearly** in the gap: the veil a reader sees is
+ * `alpha × density = alpha / gap`, so the earlier linear ramp (`alpha = gap/f`)
+ * cancelled the density growth exactly and pinned a constant gray wash over the
+ * whole plot no matter how far out you zoomed. Quadratic-to-a-floor makes the
+ * wash itself → 0 as lines converge: alpha `t²` with
+ * `t = (gap − gonePx) / (fullPx − gonePx)`. `xs` ascending.
  */
-export declare function drawDividers(ctx: CanvasRenderingContext2D, xs: readonly number[], height: number, color: string): void;
+export declare function dividerAlphas(xs: readonly number[], gonePx: number, fullPx: number): number[];
 //# sourceMappingURL=grid.d.ts.map

package/dist/grid.js

@@ -1,20 +1,30 @@
 /**
  * Stroke the plot's gridlines: a vertical line at each `xTicks` pixel and a
- * horizontal line at each `yTicks` pixel, faint and dashed. Drawn behind the
- * data layers from the same tick positions the axes label, so grid and labels
- * line up. `+0.5` aligns each 1px stroke to the device grid for a crisp line.
+ * horizontal line at each `yTicks` pixel, faint and dashed. On a calendar
+ * axis the verticals are the **full grain populations** (every day / month /
+ * aligned hour in view — see `TradingTimeScale.gridLevels`), not just the
+ * labelled ticks. `+0.5` aligns each 1px stroke to the device grid for a
+ * crisp line.
+ *
+ * `xAlphas` (parallel to `xTicks`) fades individual verticals — the
+ * hierarchical density falloff: a crowding grain's lines dim toward invisible
+ * while coarser grains hold full strength. Full-alpha lines (and all the
+ * horizontals) batch into one path; only the fading remainder pays a
+ * per-line stroke. A near-zero alpha is skipped.
  *
  * `save`/`restore` brackets the dash + stroke state so it doesn't leak into the
  * data layers that draw next.
  */
-export function drawGrid(ctx, xTicks, yTicks, width, height, color, dash) {
+export function drawGrid(ctx, xTicks, yTicks, width, height, color, dash, xAlphas) {
     ctx.save();
     ctx.strokeStyle = color;
     ctx.lineWidth = 1;
     ctx.setLineDash([...dash]);
     ctx.beginPath();
-    for (const x of xTicks) {
-        const px = Math.round(x) + 0.5;
+    for (let i = 0; i < xTicks.length; i++) {
+        if (xAlphas !== undefined && (xAlphas[i] ?? 1) < 1)
+            continue;
+        const px = Math.round(xTicks[i]) + 0.5;
         ctx.moveTo(px, 0);
         ctx.lineTo(px, height);
     }
@@ -24,6 +34,19 @@ export function drawGrid(ctx, xTicks, yTicks, width, height, color, dash) {
         ctx.lineTo(width, py);
     }
     ctx.stroke();
+    if (xAlphas !== undefined) {
+        for (let i = 0; i < xTicks.length; i++) {
+            const a = xAlphas[i] ?? 1;
+            if (a >= 1 || a <= 0.02)
+                continue;
+            ctx.globalAlpha = a;
+            const px = Math.round(xTicks[i]) + 0.5;
+            ctx.beginPath();
+            ctx.moveTo(px, 0);
+            ctx.lineTo(px, height);
+            ctx.stroke();
+        }
+    }
     ctx.restore();
 }
 /**
@@ -45,21 +68,66 @@ export function thinPixels(xs, minGap) {
  * the plot height. Drawn a touch stronger than the dashed gridlines (solid, so a
  * session/day boundary reads as structural, not just another tick) at the
  * discontinuity provider's collapse points (see `DiscontinuityProvider.boundaries`).
+ *
+ * `alphas` (parallel to `xs`) fades individual lines — used by the `'all'`
+ * session-divider mode so crowding lines dim smoothly toward invisible instead
+ * of popping in/out with a hard density cutoff. Omitted ⇒ every line at full
+ * opacity in a single path (the fast default). A near-zero alpha is skipped.
  */
-export function drawDividers(ctx, xs, height, color) {
+export function drawDividers(ctx, xs, height, color, alphas) {
     if (xs.length === 0)
         return;
     ctx.save();
     ctx.strokeStyle = color;
     ctx.lineWidth = 1;
     ctx.setLineDash([]);
-    ctx.beginPath();
-    for (const x of xs) {
-        const px = Math.round(x) + 0.5;
-        ctx.moveTo(px, 0);
-        ctx.lineTo(px, height);
+    if (alphas === undefined) {
+        ctx.beginPath();
+        for (const x of xs) {
+            const px = Math.round(x) + 0.5;
+            ctx.moveTo(px, 0);
+            ctx.lineTo(px, height);
+        }
+        ctx.stroke();
+    }
+    else {
+        // Per-line opacity → each line is its own path (globalAlpha can't vary
+        // within one stroke). Dividers draw at base opacity 1 (nothing sets it
+        // before this pass), so set the line alpha directly; `restore` resets it.
+        for (let i = 0; i < xs.length; i++) {
+            const a = alphas[i] ?? 1;
+            if (a <= 0.02)
+                continue;
+            ctx.globalAlpha = a;
+            const px = Math.round(xs[i]) + 0.5;
+            ctx.beginPath();
+            ctx.moveTo(px, 0);
+            ctx.lineTo(px, height);
+            ctx.stroke();
+        }
     }
-    ctx.stroke();
     ctx.restore();
 }
+/**
+ * Per-line opacity for {@link drawDividers} in `'all'` mode: each line keys off
+ * the gap to its nearest neighbour — full at `fullPx`+, **zero** at `gonePx`
+ * and below, a quadratic ramp between. So as a zoom-out crowds the session
+ * lines they dim toward a clean plot — no hard drop that pops on pan.
+ *
+ * The curve must fall **superlinearly** in the gap: the veil a reader sees is
+ * `alpha × density = alpha / gap`, so the earlier linear ramp (`alpha = gap/f`)
+ * cancelled the density growth exactly and pinned a constant gray wash over the
+ * whole plot no matter how far out you zoomed. Quadratic-to-a-floor makes the
+ * wash itself → 0 as lines converge: alpha `t²` with
+ * `t = (gap − gonePx) / (fullPx − gonePx)`. `xs` ascending.
+ */
+export function dividerAlphas(xs, gonePx, fullPx) {
+    return xs.map((x, i) => {
+        const left = i > 0 ? x - xs[i - 1] : Infinity;
+        const right = i < xs.length - 1 ? xs[i + 1] - x : Infinity;
+        const gap = Math.min(left, right);
+        const t = Math.max(0, Math.min(1, (gap - gonePx) / (fullPx - gonePx)));
+        return t * t;
+    });
+}
 //# sourceMappingURL=grid.js.map

package/dist/index.d.ts

@@ -28,6 +28,7 @@ export { YAxis } from './YAxis.js';
 export type { YAxisProps } from './YAxis.js';
 export { XAxis } from './XAxis.js';
 export type { XAxisProps } from './XAxis.js';
+export type { AxisTransform } from './derivedTicks.js';
 export { TimeAxis } from './TimeAxis.js';
 export { CategoryAxis } from './CategoryAxis.js';
 export type { AxisFormat } from './format.js';

package/dist/theme.d.ts

@@ -111,6 +111,19 @@ export interface ChartTheme {
          * boundary reads as structural.
          */
         readonly sessionDivider?: string;
+        /**
+         * The stacked date style's **band** row (the segmented second row: zebra
+         * date/month/year cells with left-aligned labels + dividers). `fill` is the
+         * shaded (odd-parity) cell background — "could be a background color" per
+         * the design; `divider` the turn line (falls back to {@link grid}); `label`
+         * the band-label ink (falls back to {@link title}.color → {@link label}).
+         * Optional; the whole band row is stacked-only.
+         */
+        readonly band?: {
+            readonly fill: string;
+            readonly divider?: string;
+            readonly label?: string;
+        };
         /**
          * Typography for the axis **title** — the rotated y-axis unit strip and the
          * x-axis label (distinct from the per-tick `label` colour above). Omit a

package/dist/theme.js

@@ -112,6 +112,11 @@ export const defaultTheme = {
         grid: '#e2e8f0',
         gridDash: [2, 2],
         sessionDivider: '#cbd5e1', // slate-300 — a step stronger than the gridlines
+        band: {
+            fill: '#f8fafc', // slate-50 — the zebra shade on the stacked band row
+            divider: '#cbd5e1', // slate-300 turn line
+            label: '#334155', // slate-700 ink for band labels
+        },
     },
     font: {
         family: 'system-ui, -apple-system, sans-serif',

package/dist/tickLadder.d.ts

@@ -13,7 +13,14 @@ 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';
@@ -28,32 +35,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.
+ *
+ * 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: 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.
+ * `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,12 +139,74 @@ 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 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;
 /**
- * Which of `ticks` (at grain `granularity`) carry a boundary label: the first
- * tick always (the reader needs context immediately), then every tick whose
- * boundary-grain bucket differs from the previous tick's — i.e. the first tick
- * of each new day / year. Returns the boundary-flagged tick values;
- * empty when the grain has no boundary row (year grain).
+ * 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
+ * **crossing**, the first tick of a new day / year. The first tick is *not*
+ * automatically flagged: the reader's left-edge context is the pinned
+ * {@link TradingTimeScale.boundaryContext} label (a property of the domain
+ * start, not of any tick — anchoring it to the first tick made it hop
+ * 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[];
+/**
+ * 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 boundaryTicks(ticks: readonly number[], granularity: TickGranularity): number[];
+export declare function flatFormats(ticks: readonly number[], granularity: TickGranularity, domainStart?: number): string[];
 //# sourceMappingURL=tickLadder.d.ts.map