@pond-ts/charts 0.46.0 → 0.48.0

package/dist/XAxis.js

@@ -9,8 +9,8 @@ import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
 const TICK_STRIP = 22;
 /** Extra height reserved for an axis `label` line. */
 const LABEL_STRIP = 16;
-/** Extra height reserved for the boundary (second) label row. */
-const BOUNDARY_STRIP = 15;
+/** Extra height reserved for the stacked **band** (second) row. */
+const BAND_STRIP = 20;
 /** Minimum pixel gap between derived-unit (`transform`) ticks — the room a
  *  short numeric label needs plus breathing space, in the spirit of the
  *  ladder's per-tick budget (a hair tighter: derived labels are short). */
@@ -55,7 +55,7 @@ function thinCategoryLabels(ticks, plotWidth, fontSize) {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', } = {}) {
+export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', dateStyle = 'flat', } = {}) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
@@ -90,12 +90,59 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
             return resolveAxisFormat(scaleLinear().domain(u), xTickCount, format);
         })()
         : null;
-    // Tick formatter: an explicit `format` is resolved against the axis kind
-    // (a time specifier through the time scale, a number specifier through the
-    // value scale); otherwise the container's shared formatter — the one the
+    // Whether this axis draws **ladder-derived** date context (flat promotions or
+    // the stacked boundary row). Only a ladder-driven time scale supplies it;
+    // explicit `ticks`, an explicit axis `format`, and a container-level
+    // `timeFormat` all opt out (a custom format owns the whole label, and custom
+    // ticks have no grain).
+    const laddered = xKind === 'time' &&
+        customTicks === undefined &&
+        transform === undefined &&
+        format === undefined &&
+        !container.xFormatCustom &&
+        'tickBoundaries' in xScale;
+    // The flat-style single-row label formatter — the coarsest calendar period
+    // each tick opens promoted inline, terse base labels otherwise (the
+    // TradingView default `dateStyle`). Replaces the shared `formatTime` for the
+    // tick labels; a non-tick instant (the cursor pill) still reads a full
+    // timestamp through it. `undefined` for the stacked style / a custom format.
+    const flatFmt = laddered && dateStyle === 'flat' && 'flatFormat' in xScale
+        ? xScale.flatFormat(xTickCount)
+        : undefined;
+    // The **stacked** date style renders a segmented **band** row (the coarser
+    // calendar period as zebra-shaded cells with left-aligned labels + dividers)
+    // beneath a terse top row, with the band-turn tick emphasized. The top row
+    // reads `baseFormat` (the grain's bare unit, no inline promotion — the
+    // context lives in the band), and `bands` are the segments.
+    const stacked = laddered && dateStyle === 'stacked' && 'bands' in xScale;
+    // The terse base label (the grain's bare unit, no promotion): the stacked
+    // top row, and — in flat — the yardstick for detecting which ticks were
+    // *promoted* to a coarser period, so those can be emphasized to match the
+    // stacked band turns (a period boundary reads the same in both styles).
+    const baseFmt = laddered && 'baseFormat' in xScale
+        ? xScale.baseFormat(xTickCount)
+        : undefined;
+    const bands = stacked ? xScale.bands(xTickCount) : [];
+    // Pixel positions where a band **divider** is drawn — the interior band
+    // starts (a start at/left of the plot edge maps to px ≤ 0 and draws no
+    // divider). A top-row tick landing on one is the band turn: it renders bold
+    // and in the divider colour, so tick + divider read as one continuous
+    // boundary line. Matched by **pixel**, not by instant, because on a trading
+    // axis the turn tick is the session OPEN sitting at the collapsed-midnight
+    // seam — the same pixel as the midnight band-start, but a different instant.
+    const dividerXs = new Set(bands
+        .map((b) => xScale(b.start))
+        .filter((px) => px > 0) // same threshold the band border uses (startPx > 0)
+        .map((px) => Math.round(px)));
+    // Tick / readout formatter: an explicit `format` is resolved against the axis
+    // kind (a time specifier through the time scale, a number specifier through
+    // the value scale); otherwise the container's shared formatter — the one the
     // cursor readout uses, so a tick and the cursor read identically. On a
     // transformed axis every readout (cursor pill, marker indicator) speaks the
-    // **derived unit** — the axis's own language.
+    // **derived unit** — the axis's own language. NOTE: the flat date style
+    // applies *only* to the rendered tick labels (`tickFmt` below), never to this
+    // `fmt` — the cursor pill and marker indicators keep reading a full timestamp
+    // rather than a terse/promoted axis label.
     const fmt = transform !== undefined && uFmt !== null && xKind !== 'category'
         ? (v) => uFmt(transform.to(v))
         : // A category axis labels by name (the container's `formatTime` = the band
@@ -106,6 +153,11 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                 : xKind === 'time'
                     ? resolveTimeFormat(xScale, xTickCount, format)
                     : resolveAxisFormat(xScale, xTickCount, format);
+    // The formatter for the rendered **tick labels** specifically: flat-style
+    // promoted labels, stacked-style terse base labels, else the shared `fmt`.
+    // Split from `fmt` so an axis's terse tick labels never leak into the cursor /
+    // marker readouts, which stay full timestamps.
+    const tickFmt = flatFmt ?? (stacked ? baseFmt : undefined) ?? fmt;
     // Marker annotations that opted into an axis indicator (`<Marker indicator>`)
     // pin their **time** to this shared x-axis — a pill at `at`, in the annotation
     // colour, reading like a tick. An indicator always shows the axis coordinate
@@ -152,28 +204,10 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
         markerLanes.set(t.id, lane);
     }
     const maxPillLane = Math.max(0, pillLaneEnds.length - 1);
-    // The boundary (second) label row — the coarser calendar unit the first-row
-    // label omits (the year under day / week / month ticks, the date under
-    // clock ticks), placed under the first tick of each new
-    // period. Only a ladder-driven time scale supplies it; explicit `ticks`, an
-    // explicit axis `format`, and a container-level `timeFormat` all opt out (a
-    // custom format owns the whole label, and custom ticks have no grain).
-    const boundaryOf = xKind === 'time' &&
-        customTicks === undefined &&
-        transform === undefined &&
-        format === undefined &&
-        !container.xFormatCustom &&
-        'tickBoundaries' in xScale
-        ? xScale.tickBoundaries(xTickCount)
-        : undefined;
-    // The pinned left-edge **context** label — what period the domain starts in
-    // (`Jan 01` over an intraday axis, the year over a month axis). A property
-    // of the domain, not of any tick: anchoring it to the first tick made it
-    // hop tick-to-tick on a live sliding window. Crossing labels ride their
-    // ticks and **push it off** the left edge as they approach (below).
-    const boundaryContext = boundaryOf !== undefined && 'boundaryContext' in xScale
-        ? xScale.boundaryContext(xTickCount)
-        : undefined;
+    // (The `'stacked'` date style's coarser context is the segmented **band**
+    // row — `bands`, computed above — not a per-tick boundary label. The old
+    // ride-a-tick boundary row + pinned context are retired; the scale still
+    // exposes `tickBoundaries` / `boundaryContext` for any external consumer.)
     // Derived ticks pass a **label-honesty filter**: the fill can descend below
     // the format's resolution (a delta tick at u = 0.498 renders as "+0.50" under
     // `+.2f` — a lie about its position), so a tick survives only when its
@@ -205,8 +239,17 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
             ? honestDerived()
             : xScale.ticks(xTickCount).map((d) => ({
                 x: xScale(d),
-                label: fmt(+d),
-                boundary: boundaryOf?.(+d),
+                label: tickFmt(+d),
+                // A **period turn** renders emphasized (bold), consistently across
+                // styles: in stacked, a tick on a band divider (matched by pixel);
+                // in flat, a tick whose label was *promoted* to a coarser period
+                // (its flat label differs from the terse base) — the same boundaries,
+                // so `Feb` / `2026` read as strong in flat just as the band turns do.
+                bold: stacked
+                    ? dividerXs.has(Math.round(xScale(d)))
+                    : flatFmt !== undefined &&
+                        baseFmt !== undefined &&
+                        flatFmt(+d) !== baseFmt(+d),
             }));
     // A category axis ticks once per category; thin + truncate its labels when they
     // crowd (an explicit `customTicks` axis keeps its labels verbatim).
@@ -219,34 +262,19 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     const pillOffset = align === 'right' ? 2 : 6;
     // Per-lane vertical step for stacked pills; grow the strip to fit the stack.
     const PILL_LANE_H = theme.font.size + 6;
-    // Any boundary label in view grows the strip by one row (like pill lanes do).
-    const hasBoundary = boundaryContext !== undefined ||
-        placed.some((t) => t.boundary !== undefined);
-    // The pinned context anchors at the plot's left edge (the y-axis line) with
-    // the SAME alignment as the tick labels — centred on it in `center` mode
-    // (exactly where a first-tick label at x=0 sat, half into the gutter by the
-    // same documented rule), left-anchored in `auto`, beside the line in
-    // `right`. As the leftmost crossing label slides toward the edge it would
-    // collide, so the context CULLS once the crossing label's left edge reaches
-    // the context's right edge (plus a gap) — no overlap, and nothing slides
-    // loose into the gutter. Widths from the same rough glyph metric the pills
-    // use; the crossing's label is centred on its tick.
-    const charW = theme.font.size * 0.62;
-    const contextWidth = (boundaryContext?.length ?? 0) * charW;
-    const contextRight = align === 'center'
-        ? contextWidth / 2
-        : align === 'right'
-            ? 4 + contextWidth
-            : contextWidth;
-    const firstCrossing = placed.find((t) => t.boundary !== undefined);
-    const crossingLeft = firstCrossing
-        ? align === 'right'
-            ? firstCrossing.x + 4
-            : firstCrossing.x - (firstCrossing.boundary.length * charW) / 2
-        : Infinity;
-    const showContext = boundaryContext !== undefined && crossingLeft > contextRight + 6;
+    // The stacked **band** row grows the strip by one band-height row (like pill
+    // lanes do). Only when the stacked style actually has bands (not at year
+    // grain / on a non-ladder axis).
+    const hasBands = stacked && bands.length > 0;
+    // Band-row colours (themeable via `theme.axis.band`): the zebra shade fill,
+    // the turn divider, and the label ink. A per-axis `color` override wins for
+    // divider + label (the fill stays the band's own shade).
+    const bandTheme = theme.axis.band;
+    const bandFill = bandTheme?.fill ?? theme.chip?.background ?? 'rgba(0,0,0,0.04)';
+    const bandDivider = color ?? bandTheme?.divider ?? theme.axis.grid;
+    const bandLabelColor = color ?? bandTheme?.label ?? theme.axis.title?.color ?? theme.axis.label;
     const stripHeight = (height ?? TICK_STRIP + (label ? LABEL_STRIP : 0)) +
-        (hasBoundary ? BOUNDARY_STRIP : 0) +
+        (hasBands ? BAND_STRIP : 0) +
         maxPillLane * PILL_LANE_H;
     return (_jsxs("div", { style: {
             position: 'relative',
@@ -271,8 +299,18 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                         : align === 'auto' && isLast
                             ? 'translateX(-100%)'
                             : 'translateX(-50%)';
-                // `right` drops a longer tick alongside the label; others keep the 4px stub.
-                const tickHeight = align === 'right' ? theme.font.size + 4 : 4;
+                // Stacked band mode: every tick runs the full tick-row height to *meet*
+                // the inter-row rule, so the boundary reads as one line continuing into
+                // the band divider below. `right` drops a longer tick beside the label;
+                // otherwise a 4px stub.
+                const tickHeight = hasBands
+                    ? stripHeight - BAND_STRIP
+                    : align === 'right'
+                        ? theme.font.size + 4
+                        : 4;
+                // The band-turn tick takes the divider colour so tick + divider read as
+                // one continuous boundary; minor ticks stay the faint grid colour.
+                const tickColor = hasBands && t.bold ? bandDivider : (color ?? theme.axis.grid);
                 const labelLeft = align === 'right' ? t.x + 4 : t.x;
                 const labelOffset = align === 'right' ? 2 : 6;
                 return (_jsxs(Fragment, { children: [_jsx("div", { style: {
@@ -281,29 +319,55 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                                 [onTop ? 'bottom' : 'top']: 0,
                                 width: '1px',
                                 height: `${tickHeight}px`,
-                                background: color ?? theme.axis.grid,
+                                background: tickColor,
                             } }), _jsx("div", { style: {
                                 position: 'absolute',
                                 left: `${labelLeft}px`,
                                 [onTop ? 'bottom' : 'top']: `${labelOffset}px`,
                                 transform: labelTransform,
                                 whiteSpace: 'nowrap',
-                            }, children: t.label }), t.boundary !== undefined && (_jsx("div", { "data-boundary-label": true, style: {
-                                position: 'absolute',
-                                left: `${labelLeft}px`,
-                                [onTop ? 'bottom' : 'top']: `${labelOffset + theme.font.size + 3}px`,
-                                transform: labelTransform,
-                                whiteSpace: 'nowrap',
-                                opacity: 0.75,
-                            }, children: t.boundary }))] }, `${t.x}-${i}`));
-            }), showContext && (_jsx("div", { "data-boundary-label": true, "data-boundary-context": true, style: {
+                                // Stacked band style bolds the tick sitting on a band turn
+                                // (the day/month/year start) — the emphasized boundary tick.
+                                fontWeight: t.bold ? 700 : undefined,
+                            }, children: t.label })] }, `${t.x}-${i}`));
+            }), hasBands && (_jsx("div", { style: {
                     position: 'absolute',
-                    left: `${align === 'right' ? 4 : 0}px`,
-                    [onTop ? 'bottom' : 'top']: `${(align === 'right' ? 2 : 6) + theme.font.size + 3}px`,
-                    transform: align === 'center' ? 'translateX(-50%)' : 'none',
-                    whiteSpace: 'nowrap',
-                    opacity: 0.75,
-                }, children: boundaryContext })), label !== undefined && (_jsx("div", { style: {
+                    left: 0,
+                    width: `${plotWidth}px`,
+                    [onTop ? 'top' : 'bottom']: 0,
+                    height: `${BAND_STRIP}px`,
+                    // The rule between the terse tick row and the band row.
+                    [onTop ? 'borderBottom' : 'borderTop']: `1px solid ${color ?? theme.axis.grid}`,
+                    overflow: 'hidden',
+                }, children: bands.map((b, i) => {
+                    // Each band spans [its start, the next band's start) in pixels,
+                    // clamped to the plot. The first (partial) band starts off-screen
+                    // left, so its label pins at x=0; interior bands carry a divider
+                    // at their start. Shaded bands paint the zebra fill.
+                    const startPx = xScale(b.start);
+                    const left = Math.max(0, startPx);
+                    const nextPx = i + 1 < bands.length ? xScale(bands[i + 1].start) : plotWidth;
+                    const width = Math.max(0, Math.min(plotWidth, nextPx) - left);
+                    if (width <= 0)
+                        return null;
+                    return (_jsx("div", { "data-band-label": true, style: {
+                            position: 'absolute',
+                            left: `${left}px`,
+                            top: 0,
+                            bottom: 0,
+                            width: `${width}px`,
+                            boxSizing: 'border-box',
+                            background: b.shaded ? bandFill : 'transparent',
+                            borderLeft: startPx > 0 ? `1px solid ${bandDivider}` : 'none',
+                            display: 'flex',
+                            alignItems: 'center',
+                            paddingLeft: '8px',
+                            color: bandLabelColor,
+                            fontWeight: 600,
+                            whiteSpace: 'nowrap',
+                            overflow: 'hidden',
+                        }, children: b.label }, b.start));
+                }) })), label !== undefined && (_jsx("div", { style: {
                     position: 'absolute',
                     left: 0,
                     width: '100%',

package/dist/context.d.ts

@@ -203,6 +203,14 @@ export interface ContainerFrame {
      * rather than raw wall-clock ms.
      */
     readonly discontinuities?: DiscontinuityProvider | undefined;
+    /** Draw the reference gridlines behind the data (default `true`; the
+     *  container's `grid` prop). Session dividers are independent of this. */
+    readonly grid: boolean;
+    /** Where session dividers draw on a trading axis: `'none'` (the default —
+     *  the hierarchical grid already marks calendar structure), `'all'` (every
+     *  session boundary in view — the TradingView separator look), or
+     *  `'labeled'` (only under labelled collapse points). */
+    readonly sessionDividers: 'labeled' | 'all' | 'none';
     /**
      * The resolved kind of the shared x scale — `'time'` (a `scaleTime`),
      * `'value'` (a `scaleLinear`), or `'category'` (a {@link ScaleBand}: an ordinal

package/dist/format.d.ts

@@ -6,12 +6,32 @@
  * uses for the ticks), a **function** is used verbatim, and `undefined` falls
  * back to the scale's default `tickFormat`.
  */
+import type { TimeGrain } from './tickLadder.js';
 /**
  * How to format an axis's values — a d3 [format specifier]
  * (https://github.com/d3/d3-format#locale_format) string, or a custom
  * `(value) => string` function. Omit for the scale's d3 default.
  */
 export type AxisFormat = string | ((value: number) => string);
+/**
+ * How to format the **cursor / marker readout** on a time axis
+ * ({@link ChartContainerProps.cursorFormat}). Either:
+ *
+ * - a d3 time specifier **string** (e.g. `'%b %-d'`) applied uniformly at every
+ *   zoom; or
+ * - a **function** `(epochMs, ctx) => string`, where `ctx.grain` is the axis's
+ *   resolved coarse {@link TimeGrain} (`year` … `second`) and `ctx.defaultText`
+ *   is the library's grain-aware default readout for that instant — so a
+ *   consumer can branch on the zoom level (`grain === 'year' ? … : …`) and
+ *   pass `defaultText` through for the grains they don't want to override.
+ *
+ * The library hands you the grain because it already resolved it — you never
+ * re-derive it from the range.
+ */
+export type CursorFormat = string | ((epochMs: number, ctx: {
+    readonly grain: TimeGrain;
+    readonly defaultText: string;
+}) => string);
 /** The slice of a d3 scale {@link resolveAxisFormat} needs — `tickFormat` with an
  *  optional specifier. A d3 `ScaleLinear` / `ScaleTime` satisfies it. */
 interface Tickable {

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

@@ -31,7 +31,7 @@ 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';
+export type { AxisFormat, CursorFormat } from './format.js';
 export { LineChart } from './LineChart.js';
 export type { LineChartProps } from './LineChart.js';
 export { BandChart } from './BandChart.js';
@@ -48,7 +48,7 @@ export { Candlestick } from './Candlestick.js';
 export type { CandlestickProps } from './Candlestick.js';
 export type { CandleVariant, ColorBy } from './ohlc.js';
 export { scaleTradingTime } from './tradingTimeScale.js';
-export type { TradingTimeScale, DiscontinuityProvider, } from './tradingTimeScale.js';
+export type { TradingTimeScale, DiscontinuityProvider, TimeGrain, } from './tradingTimeScale.js';
 export { scaleBand } from './bandScale.js';
 export type { ScaleBand } from './bandScale.js';
 export { Region, Baseline, Marker } from './annotations.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',