@pond-ts/charts 0.45.0 → 0.47.0

package/dist/XAxis.js

@@ -1,5 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useContext } from 'react';
+import { scaleLinear } from 'd3-scale';
+import { derivedTicks } from './derivedTicks.js';
 import { ContainerContext } from './context.js';
 import { axisPillStyle } from './chip.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
@@ -7,8 +9,12 @@ 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). */
+const TRANSFORM_TICK_PX = 48;
 /**
  * Thin + truncate a **category** axis's labels so a dense axis stays legible: keep
  * every `stride`-th label (so a kept label has room), and ellipsize one that still
@@ -49,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, 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>');
@@ -69,19 +75,89 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
         cursorX <= plotWidth;
     const cursorColor = theme.cursor ?? theme.axis.label;
     const annotationColor = theme.annotation?.color ?? '#0d9488';
-    // 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
-    // cursor readout uses, so a tick and the cursor read identically.
-    const fmt = 
-    // A category axis labels by name (the container's `formatTime` = the band
-    // scale's label lookup); a d3 number/time `format` can't name a category, so
-    // it's ignored here (customize the labels in the `categories` data instead).
-    format === undefined || xKind === 'category'
-        ? formatTime
-        : xKind === 'time'
-            ? resolveTimeFormat(xScale, xTickCount, format)
-            : resolveAxisFormat(xScale, xTickCount, format);
+    // Derived-unit (`transform`) layout: nice ticks in the derived unit at
+    // mixed step sizes, admitted where they keep pixel room (see derivedTicks).
+    // Explicit `ticks` win; a category axis has no numeric unit to derive from.
+    const derived = transform !== undefined && xKind !== 'category' && customTicks === undefined
+        ? derivedTicks(transform, xScale.domain(), (v) => xScale(v), plotWidth, TRANSFORM_TICK_PX)
+        : null;
+    // Formatter for derived-unit values — `format` resolved against a u-space
+    // linear scale (so `'+.2f'` and the d3 number default both work).
+    const uFmt = transform !== undefined && xKind !== 'category'
+        ? (() => {
+            const [d0, d1] = xScale.domain();
+            const u = [transform.to(d0), transform.to(d1)].sort((a, b) => a - b);
+            return resolveAxisFormat(scaleLinear().domain(u), xTickCount, format);
+        })()
+        : null;
+    // 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. 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
+            // scale's label lookup); a d3 number/time `format` can't name a category, so
+            // it's ignored here (customize the labels in the `categories` data instead).
+            format === undefined || xKind === 'category'
+                ? formatTime
+                : 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
@@ -128,26 +204,53 @@ 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 &&
-        format === undefined &&
-        !container.xFormatCustom &&
-        'tickBoundaries' in xScale
-        ? xScale.tickBoundaries(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
+    // formatted label parses back to a value that maps to (±1px of) the tick's
+    // own pixel. This also caps density at the format's precision and drops
+    // would-be duplicate labels. Non-numeric labels (a custom format function)
+    // are trusted as-is.
+    const honestDerived = () => {
+        const out = [];
+        const seen = new Set();
+        for (const t of derived) {
+            const text = uFmt(t.u);
+            if (seen.has(text))
+                continue;
+            const back = parseFloat(text.replace(/\u2212/g, '-').replace(/,/g, ''));
+            if (Number.isFinite(back)) {
+                const bx = xScale(transform.from(back));
+                if (!Number.isFinite(bx) || Math.abs(bx - t.x) > 1)
+                    continue;
+            }
+            seen.add(text);
+            out.push({ x: t.x, label: text });
+        }
+        return out;
+    };
     const rawTicks = customTicks
         ? customTicks.map((t) => ({ x: xScale(t.at), label: t.label }))
-        : xScale.ticks(xTickCount).map((d) => ({
-            x: xScale(d),
-            label: fmt(+d),
-            boundary: boundaryOf?.(+d),
-        }));
+        : derived !== null
+            ? honestDerived()
+            : xScale.ticks(xTickCount).map((d) => ({
+                x: xScale(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).
     const placed = xKind === 'category' && customTicks === undefined && rawTicks.length > 1
@@ -159,10 +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 = placed.some((t) => t.boundary !== undefined);
+    // 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',
@@ -170,10 +282,10 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
             width: `${plotWidth}px`,
             height: `${stripHeight}px`,
             // The plot-facing edge carries the rule; a top axis rules its bottom.
-            [onTop ? 'borderBottom' : 'borderTop']: `1px solid ${theme.axis.grid}`,
+            [onTop ? 'borderBottom' : 'borderTop']: `1px solid ${color ?? theme.axis.grid}`,
             fontFamily: theme.font.family,
             fontSize: `${theme.font.size}px`,
-            color: theme.axis.label,
+            color: color ?? theme.axis.label,
         }, children: [placed.map((t, i) => {
                 const isFirst = i === 0;
                 const isLast = i === placed.length - 1;
@@ -187,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: {
@@ -197,22 +319,55 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                                 [onTop ? 'bottom' : 'top']: 0,
                                 width: '1px',
                                 height: `${tickHeight}px`,
-                                background: 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}`));
-            }), label !== undefined && (_jsx("div", { 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: 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%',
@@ -220,7 +375,7 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                     [onTop ? 'top' : 'bottom']: 0,
                     // Themeable axis-title text (shared with the rotated y-axis title).
                     fontSize: `${theme.axis.title?.size ?? theme.font.size + 1}px`,
-                    color: theme.axis.title?.color ?? theme.axis.label,
+                    color: color ?? theme.axis.title?.color ?? theme.axis.label,
                     opacity: theme.axis.title?.opacity ?? 0.85,
                     whiteSpace: 'nowrap',
                 }, children: label })), markerTags.map((t) => {

package/dist/YAxis.d.ts

@@ -70,6 +70,14 @@ export interface YAxisProps {
     boundaryLabels?: boolean;
     /** Gutter width in CSS pixels (default 50). */
     width?: number;
+    /**
+     * This axis instance's colour — tick labels and the axis title take it,
+     * overriding the theme's `axis.label` / `axis.title.color`. The multi-axis
+     * convention of colouring each y axis to match its series (`color`
+     * matching the layer's) — busy, but standard. Omit for the theme's axis
+     * colours. Presentation-only: it never re-registers the axis.
+     */
+    color?: string;
     /**
      * @internal Declaration position among the row's children, injected by
      * `ChartRow` so the first-declared axis stays the default. Do not set.
@@ -84,5 +92,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, min, max, format, ticks, pad, boundaryLabels, width, labelPlacement, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function YAxis({ id, side, label, min, max, format, ticks, pad, boundaryLabels, width, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -13,7 +13,7 @@ const TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', index = 0, }) {
+export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', color, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -76,7 +76,7 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad =
                 height: `${row.height}px`,
                 fontFamily: theme.font.family,
                 fontSize: `${theme.font.size}px`,
-                color: theme.axis.label,
+                color: color ?? theme.axis.label,
             }, children: [yScale &&
                     tickList.map(({ value, label }, i) => {
                         // Drop just the top & bottom labels when boundary labels are off
@@ -102,7 +102,7 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad =
                         // labels' alignment, rather than floating at the outer gutter edge.
                         [side === 'left' ? 'right' : 'left']: '4px',
                         fontSize: `${theme.axis.title?.size ?? theme.font.size + 1}px`,
-                        color: theme.axis.title?.color ?? theme.axis.label,
+                        color: color ?? theme.axis.title?.color ?? theme.axis.label,
                         opacity: theme.axis.title?.opacity ?? 0.85,
                         whiteSpace: 'nowrap',
                         pointerEvents: 'none',
@@ -116,7 +116,7 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad =
                         alignItems: 'center',
                         justifyContent: 'center',
                         fontSize: `${theme.axis.title?.size ?? theme.font.size + 1}px`,
-                        color: theme.axis.title?.color ?? theme.axis.label,
+                        color: color ?? theme.axis.title?.color ?? theme.axis.label,
                         opacity: theme.axis.title?.opacity ?? 0.85,
                         pointerEvents: 'none',
                     }, children: _jsx("span", { style: {

package/dist/annotations.d.ts

@@ -15,7 +15,7 @@ import { type AnnotationSpec, type ContainerFrame, type LabelPlacement } from '.
  *   the next free lane. The `draggingKey` is excluded (pinned to lane 0, its own
  *   label) so the static labels hold their lanes as it crosses them.
  */
-export declare function computeLabelLanes(annotations: readonly AnnotationSpec[], toPixel: (axisX: number) => number, draggingKey?: symbol | null): Map<symbol, LabelPlacement>;
+export declare function computeLabelLanes(annotations: readonly AnnotationSpec[], toPixel: (axisX: number) => number, draggingKey?: symbol | null, plotWidth?: number): Map<symbol, LabelPlacement>;
 /**
  * Snap a dragged plot-pixel `px` to the nearest **guideline** within
  * {@link SNAP_PX} — another annotation's x, **or** a trading-axis **disjoint

package/dist/annotations.js

@@ -169,7 +169,7 @@ const labelWidth = (text) => text.length * LABEL_CHAR_W + LABEL_PAD;
  *   the next free lane. The `draggingKey` is excluded (pinned to lane 0, its own
  *   label) so the static labels hold their lanes as it crosses them.
  */
-export function computeLabelLanes(annotations, toPixel, draggingKey) {
+export function computeLabelLanes(annotations, toPixel, draggingKey, plotWidth) {
     const out = new Map();
     const byRow = new Map();
     for (const a of annotations) {
@@ -195,22 +195,33 @@ export function computeLabelLanes(annotations, toPixel, draggingKey) {
                     markerGroups.set(a.xs[0], [a]);
             }
             else {
+                // Lane-pack at the position the chip will *render*: a region panned
+                // half off-plot renders clamped to the plot's left edge, and a fully
+                // off-plot region's chip is culled — so it must not hold a lane.
                 const ax = a.kind === 'region' ? Math.min(a.xs[0], a.xs[1]) : a.xs[0];
+                const bx = a.kind === 'region' ? Math.max(a.xs[0], a.xs[1]) : a.xs[0];
+                const rawLeft = toPixel(ax);
+                if (plotWidth !== undefined && (rawLeft > plotWidth || toPixel(bx) < 0))
+                    continue;
                 flags.push({
                     rep: a.key,
                     members: [a.key],
-                    left: toPixel(ax),
+                    left: plotWidth === undefined ? rawLeft : Math.max(rawLeft, 0),
                     width: labelWidth(a.label),
                     label: a.label,
                 });
             }
         }
         for (const [x, group] of markerGroups) {
+            // A culled off-plot marker chip must not hold a lane either.
+            const px = toPixel(x);
+            if (plotWidth !== undefined && (px < 0 || px > plotWidth))
+                continue;
             const label = group.map((g) => g.label).join(', ');
             flags.push({
                 rep: group[0].key,
                 members: group.map((g) => g.key),
-                left: toPixel(x),
+                left: px,
                 width: labelWidth(label),
                 label,
             });
@@ -473,7 +484,7 @@ export function Marker({ at, label, id, selected = false, selectable = true, hov
     // into a lower lane doesn't leave line poking above it. No label ⇒ full height.
     const staffTop = text ? FLAG_TOP + lane * LANE_H : 0;
     return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("line", { x1: x, y1: staffTop, x2: x, y2: h, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: x, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })), selectable && (_jsx(DragArea, { x: x - HIT_PAD, y: 0, w: 2 * HIT_PAD, h: h, cursor: editing ? 'ew-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (px) => onChange?.(snapToGuides(container, selfKey, px) ??
-                            +container.xScale.invert(px)) }))] }), chipLabel && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+                            +container.xScale.invert(px)) }))] }), chipLabel && x >= 0 && x <= container.plotWidth && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
                     top: `${FLAG_TOP + lane * LANE_H}px`,
                     ...flagChipX(x, container.plotWidth),
                 }, children: chipLabel }))] }));
@@ -618,9 +629,9 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
                                             +container.xScale.invert(px), edgeRef.current ?? to)) }), _jsx(DragArea, { x: xb - EDGE_GRAB / 2, y: 0, w: EDGE_GRAB, h: h, cursor: "ew-resize", editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDragStart: () => {
                                             edgeRef.current = from; // the fixed pivot = the near edge
                                         }, onDrag: (px) => onChange?.(orderRegion(snapToGuides(container, selfKey, px) ??
-                                            +container.xScale.invert(px), edgeRef.current ?? from)) })] }))] }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+                                            +container.xScale.invert(px), edgeRef.current ?? from)) })] }))] }))] }), text && left <= container.plotWidth && left + spanW >= 0 && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
                     top: `${FLAG_TOP + lane * LANE_H}px`,
-                    ...flagChipX(left, container.plotWidth),
+                    ...flagChipX(Math.max(left, 0), container.plotWidth),
                 }, children: text }))] }));
 }
 //# sourceMappingURL=annotations.js.map

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/derivedTicks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tick layout for a **derived-unit axis** — a second labeling of the same
+ * scale (`<XAxis transform>`): strike relabelled as moneyness, std-moneyness
+ * relabelled as BS delta. The transform may be nonlinear, which stretches or
+ * compresses the derived unit across the pixel range — so a single uniform
+ * step can't work (uniform delta ticks pile up mid-axis and leave the
+ * stretched wings empty). Instead: a **pixel-aware multi-resolution fill** —
+ * walk nice step sizes (the 1-2-5 ladder) coarsest→finest, admitting each
+ * candidate tick wherever it keeps `minPx` of room from every tick already
+ * placed. A compressed span ends up with coarse ticks, a stretched span picks
+ * up finer ones (the reference look: `0.10`-step deltas mid-axis, `0.45 /
+ * 0.49` out in the wings). A linear transform degenerates to ordinary
+ * evenly-spaced nice ticks through the same code path.
+ */
+/** A derived-unit transform: `to`/`from` are monotonic inverses (either
+ *  direction — a decreasing transform is fine); they may be nonlinear. */
+export interface AxisTransform {
+    /** Axis value → derived unit (e.g. strike → moneyness). */
+    to(value: number): number;
+    /** Derived unit → axis value (inverse of {@link to}). */
+    from(unit: number): number;
+}
+/** One derived tick: its value in the derived unit and its plot pixel. */
+export interface DerivedTick {
+    readonly u: number;
+    readonly x: number;
+}
+/**
+ * Compute the derived-unit ticks: nice values in `transform.to`-space at
+ * mixed 1-2-5 step sizes, greedily admitted coarsest-first wherever the
+ * mapped pixel keeps `minPx` from every tick already placed (and stays inside
+ * `[0, plotWidth]`). Returns ticks sorted by pixel. Pure — unit-testable
+ * without a DOM.
+ */
+export declare function derivedTicks(transform: AxisTransform, domain: readonly [number, number], toPixel: (value: number) => number, plotWidth: number, minPx: number): DerivedTick[];
+//# sourceMappingURL=derivedTicks.d.ts.map

package/dist/derivedTicks.js

@@ -0,0 +1,92 @@
+/**
+ * Tick layout for a **derived-unit axis** — a second labeling of the same
+ * scale (`<XAxis transform>`): strike relabelled as moneyness, std-moneyness
+ * relabelled as BS delta. The transform may be nonlinear, which stretches or
+ * compresses the derived unit across the pixel range — so a single uniform
+ * step can't work (uniform delta ticks pile up mid-axis and leave the
+ * stretched wings empty). Instead: a **pixel-aware multi-resolution fill** —
+ * walk nice step sizes (the 1-2-5 ladder) coarsest→finest, admitting each
+ * candidate tick wherever it keeps `minPx` of room from every tick already
+ * placed. A compressed span ends up with coarse ticks, a stretched span picks
+ * up finer ones (the reference look: `0.10`-step deltas mid-axis, `0.45 /
+ * 0.49` out in the wings). A linear transform degenerates to ordinary
+ * evenly-spaced nice ticks through the same code path.
+ */
+/** The largest 1-2-5 nice step ≤ `span` (so the coarsest level yields at
+ *  least one interval across the domain). */
+function firstStep(span) {
+    const pow = 10 ** Math.floor(Math.log10(span));
+    for (const m of [5, 2, 1]) {
+        if (m * pow <= span)
+            return m * pow;
+    }
+    return pow / 2; // span < pow can't happen (pow ≤ span), belt-and-braces
+}
+/** The next step down the 1-2-5 ladder: 5→2→1→0.5→0.2→0.1… */
+function nextFiner(step) {
+    const pow = 10 ** Math.floor(Math.log10(step));
+    const m = Math.round(step / pow);
+    if (m === 5)
+        return 2 * pow;
+    if (m === 2)
+        return pow;
+    return pow / 2;
+}
+/** Per-level enumeration cap — a backstop against a pathological transform
+ *  requesting a step so fine the candidate walk explodes. Generous: the
+ *  reference delta axis enumerates ~100 candidates at its finest level. */
+const MAX_CANDIDATES = 4000;
+/**
+ * Compute the derived-unit ticks: nice values in `transform.to`-space at
+ * mixed 1-2-5 step sizes, greedily admitted coarsest-first wherever the
+ * mapped pixel keeps `minPx` from every tick already placed (and stays inside
+ * `[0, plotWidth]`). Returns ticks sorted by pixel. Pure — unit-testable
+ * without a DOM.
+ */
+export function derivedTicks(transform, domain, toPixel, plotWidth, minPx) {
+    const ua = transform.to(domain[0]);
+    const ub = transform.to(domain[1]);
+    const u0 = Math.min(ua, ub);
+    const u1 = Math.max(ua, ub);
+    if (!Number.isFinite(u0) ||
+        !Number.isFinite(u1) ||
+        u1 <= u0 ||
+        !(plotWidth > 0)) {
+        return [];
+    }
+    const kept = [];
+    const fits = (x) => x >= 0 && x <= plotWidth && kept.every((k) => Math.abs(k.x - x) >= minPx);
+    // More ticks than the plot has room for can never be admitted.
+    const maxTicks = Math.ceil(plotWidth / minPx) + 2;
+    let step = firstStep(u1 - u0);
+    // An empty level does NOT end the walk: under a nonlinear transform a
+    // pixel-wide gap can have a tiny u-span (the delta wings — no 0.1-grid
+    // value lands in [0.4, 0.4987], but 0.45 on the 0.05 grid does), so finer
+    // levels may fill where a coarser one placed nothing. Several *consecutive*
+    // empty levels mean the remaining gaps' u-spans are being outrun faster
+    // than the ladder descends — give up then (plus the enumeration backstop).
+    let emptyLevels = 0;
+    for (let level = 0; level < 24 && kept.length < maxTicks; level++) {
+        const i0 = Math.ceil(u0 / step - 1e-9);
+        const i1 = Math.floor(u1 / step + 1e-9);
+        if (i1 - i0 > MAX_CANDIDATES)
+            break;
+        let added = 0;
+        for (let i = i0; i <= i1 && kept.length < maxTicks; i++) {
+            // Clean the float (0.3, not 0.30000000000000004) — the raw `u` reaches
+            // a caller-supplied format function, so it must be presentable.
+            const u = Number((i * step).toPrecision(12));
+            const x = toPixel(transform.from(u));
+            if (Number.isFinite(x) && fits(x)) {
+                kept.push({ u, x });
+                added += 1;
+            }
+        }
+        emptyLevels = added === 0 && level > 0 ? emptyLevels + 1 : 0;
+        if (emptyLevels >= 3)
+            break;
+        step = nextFiner(step);
+    }
+    return kept.sort((a, b) => a.x - b.x);
+}
+//# sourceMappingURL=derivedTicks.js.map