@pond-ts/charts 0.44.1 → 0.46.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 tag, so this file covers them all. Pre-1.0: minor bumps may include new features
 and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.44.1...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.46.0...HEAD
+[0.46.0]: https://github.com/pjm17971/pond-ts/compare/v0.45.0...v0.46.0
+[0.45.0]: https://github.com/pjm17971/pond-ts/compare/v0.44.1...v0.45.0
 [0.44.1]: https://github.com/pjm17971/pond-ts/compare/v0.44.0...v0.44.1
 [0.44.0]: https://github.com/pjm17971/pond-ts/compare/v0.43.0...v0.44.0
 [0.43.0]: https://github.com/pjm17971/pond-ts/compare/v0.42.0...v0.43.0
@@ -43,6 +45,146 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.46.0] — 2026-07-14
+
+### Changed
+
+- **charts:** the boundary (second-row) axis label's **context** now pins to
+  the plot's left edge instead of riding the first tick: it shows the period
+  the *domain start* is in, and a crossing label sliding toward the edge
+  pushes it off (the sticky-header behavior). On a live sliding window the
+  old first-tick anchoring made `Jan 01` hop tick-to-tick as ticks scrolled
+  out; pinned, it stays put until the period actually changes. Crossing
+  labels (day/year turns) still ride their ticks — including a first tick
+  whose period differs from the domain start's. `TradingTimeScale` gains
+  `boundaryContext(count)`; `tickBoundaries` now labels crossings only.
+
+### Fixed
+
+- **charts:** a live (sliding-window) time axis no longer flickers between two
+  tick grains: the clock-rung choice now derives from the window's live span
+  (constant while sliding) instead of the enumerated anchor count, which
+  oscillates ±1 with the window's phase and flipped the grain for single
+  frames whenever it sat exactly at the width-derived cap.
+
+### Added
+
+- **charts:** **dual x-axes** — two tick layouts on one shared scale. A second
+  `<XAxis>` stacks by declaration order (above/below the plot, either side,
+  same side twice); the new **`transform`** prop (`{ to, from }`, exported
+  `AxisTransform`) relabels an axis into a derived unit: strike ↔ moneyness on
+  a top axis, or a nonlinear BS-delta strip under a std-moneyness chart. Ticks
+  are nice derived-unit values chosen by a pixel-aware multi-resolution fill
+  (1-2-5 steps, coarsest first, admitted where they keep room), so a span the
+  transform compresses gets coarse ticks and a stretched span picks up finer
+  ones — and a label-honesty filter drops any tick whose formatted label would
+  lie about its position. Gridlines stay on the container's primary ticks; the
+  cursor pill on a transformed axis reads in the derived unit. Stories under
+  `Charts/Axes/DualX`. Each `<XAxis>` **and `<YAxis>`** also takes a
+  per-instance **`color`** (labels, tick marks, rule, title) — the lever that
+  distinguishes stacked x strips (a blue delta strip under a grey primary) and
+  colours a y axis to match its series (the dual-axis convention).
+
+### Fixed
+
+- **charts:** annotation label chips now clip to the plot: a marker whose pole
+  pans off-plot no longer leaves its chip floating in the axis gutter, and a
+  partially visible region's chip clamps to the plot's left edge (culled only
+  when the region is entirely out of view). The lines/fills were already
+  SVG-clipped — only the DOM chips escaped.
+
+## [0.45.0] — 2026-07-14
+
+### Added
+
+- **charts:** the time axis now walks a **logical tick ladder** — clock/calendar
+  units (1s…30s, 1m…30m, 1H…12H, day / week / month / quarter / year), picking
+  the finest grain that fits the width-derived cap — and renders **two-tier labels**:
+  a first row at the tick grain (`14:00`, `Feb 02`, `Feb`, `2026`) plus a
+  **boundary row** carrying the coarser context the first row omits (the date
+  under clock ticks, the year under day/week/month ticks — never a unit the
+  first row already shows), shown once under
+  the first tick of each new period. Hour anchors are generated in **live**
+  trading time, so none lands in a collapsed gap, an early close, or a lunch
+  break. `TradingTimeScale` gains `tickBoundaries(count)`; a cramped leading
+  partial-period anchor (the `"Jun 23Jul 07"` pile-up) is dropped. Systematic
+  story matrix under `Charts/TimeAxisTicks`.
+- **financial:** the rest of the first study batch — `rollingStdev`,
+  `rollingMin`, `rollingMax`, `rollingPercentile` (linear interpolation),
+  `zScore` (rolling), `envelope` (MA ± percent, `maType` sma/ema), and
+  `percentChange` (n-bar rate of change). Same shape as the others — `column` /
+  `output` (or `prefix`) on every one, bar-count periods, length-preserving
+  warm-up — and each has a fluent method (`bars.zScore({ period: 20 })`) and a
+  **pandas oracle** case (values cross-validated bar-for-bar). This completes the
+  #449 first batch.
+- **financial:** opt-in **fluent studies** via `import '@pond-ts/financial/fluent'`
+  — mounts `sma` / `ema` / `bollinger` as chainable `TimeSeries` methods so
+  composition reads like the core operators beside it:
+  `bars.sma({ period: 20 }).ema({ period: 12 }).bollinger({ period: 20 })`.
+  Opt-in by import (the default entry leaves `TimeSeries` untouched, so a
+  non-financial series never sees `.sma()`); the methods are exactly the
+  standalone functions bound to `this`, fully typed (each appends its column to
+  the schema). Same prototype-augmentation pattern core uses for column methods.
+- **financial:** `@pond-ts/financial` gains its first **studies** — `sma`, `ema`,
+  and `bollinger` (Bollinger Bands®) — pure functions that append a column (or a
+  `${prefix}Middle/Upper/Lower` family) to a bar series. Every study takes a
+  `column` source (default `'close'`) and an `output` name, so a study runs over
+  any numeric column including another study's output; periods are **bar counts**
+  (on core's count window, gap-correct); warm-up rows are `undefined`
+  (length-preserving). Plus the `OhlcvColumns` contract + `DEFAULT_OHLCV`. (Core
+  `AppendColumn` is now exported so study return types name their appended
+  column.)
+- **core:** `smooth(col, 'ema', …)` gains the financial **`span`** rate
+  convention (`α = 2/(span+1)`, e.g. `{ span: 12 }` for a 12-period EMA) as an
+  alternative to `alpha` (exactly one required), and a length-preserving
+  **`minSamples`** warm-up that emits `undefined` for the first `N` present
+  values while **keeping the row count** — mirroring `rolling`'s `minSamples`,
+  the one warm-up convention studies use so a smoothed line aligns on its
+  source's time axis. (The existing `warmup` option is unchanged — it still
+  *drops* the head rows; `minSamples` is the length-preserving counterpart.)
+- **core:** `TimeSeries.rolling` accepts a **count-based** window —
+  `rolling({ count: N }, mapping, opts?)` reduces the last / next / centered
+  `N` _rows_ (bars) by position instead of a time span. Unlike a duration
+  window, an N-bar window stays correct across session gaps (weekends,
+  overnight) where `N` bars do not equal `N × barSize` of time — the load-
+  bearing primitive for financial N-bar studies (SMA-20, Bollinger-20, rolling
+  stdev). Honours `alignment` and `minSamples` exactly like a duration window
+  (`minSamples: N` gives the conventional first-`N-1`-rows-`undefined` warmup);
+  per-row output only (not supported with a sequence). Same amortized-O(1)-per-
+  row sweep as the duration path.
+- **charts:** `<LineChart sessionBreaks>` breaks the line at each trading-axis
+  discontinuity (a session / day / lunch close→open) instead of connecting the
+  prior close straight to the next open across the collapsed gap. For intraday
+  data on a `discontinuities` / `calendar` axis this gives the terminal look —
+  the line ends at the close and re-starts at the open, so one session's price
+  doesn't visually flow into the next. It's a **scale** break (driven by the
+  axis's collapsed gaps), orthogonal to `gaps` (a **data** break, a NaN run) —
+  set both independently. Default `false`; a no-op on a continuous axis or a
+  provider without `boundaries`. New `Charts/TradingTimeAxis/SessionBreaks`
+  story (connected vs broken) + `sessionRuns` / `gappingTicks` helpers.
+
+### Changed
+
+- **charts:** a **plain continuous time axis** now runs the same ladder as a
+  trading-calendar axis (via an internal gap-free identity provider) instead of
+  d3's multi-scale default — so a year of daily data ticks cleanly on month
+  starts (`Jul Aug … Jun` + the year underneath) rather than mixed
+  `"Jun 23" / "Sep" / "Dec"` labels, and its tick count is now width-derived
+  like the trading axis's. Month/quarter-grain anchor labels are now bare
+  months (`Feb`, was `Feb 02`) with the year on the boundary row;
+  `coarsenCalendar`'s finest granularity is renamed `'session'` → `'day'`.
+
+### Fixed
+
+- **core:** `TimeSeries.withColumn` now appends an **optional** column
+  (`required: false`) rather than a required one. It already accepted
+  `(number | undefined)[]`, but marking the column required meant a later
+  strict-intake rebuild (`smooth`, any row reconstruction) threw on the gaps —
+  so a column with a warm-up (a rolling study fed into an EMA, e.g.
+  `ema(sma(bars, …), …)`) crashed. The appended column's type is now
+  `number | undefined`, matching `smooth`'s optional append. (`OptionalNumberColumn`
+  is exported for the widened return type.)
+
 ## [0.44.1] — 2026-07-13
 
 A `@pond-ts/charts` patch: fixes trading-time axis tick density. `pond-ts`,

package/dist/ChartContainer.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
-import { scaleLinear, scaleTime } from 'd3-scale';
-import { scaleTradingTime, } from './tradingTimeScale.js';
+import { scaleLinear } from 'd3-scale';
+import { identityProvider, scaleTradingTime, } from './tradingTimeScale.js';
 import { scaleBand } from './bandScale.js';
 import { Sequence } from 'pond-ts';
 import { ContainerContext, } from './context.js';
@@ -335,10 +335,11 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     // The shared x-side tick count — labels, x gridlines, session dividers, and
     // `formatTime` all pass this one value, so they derive from the same instants
     // (the alignment previously held by three hardcoded constants agreeing).
-    // Trading axis: width-derived, since the trading scale's `count` caps its
-    // calendar buckets rather than targeting a tick total; floored at 2 so a
-    // pre-layout zero width still requests a drawable tick set.
-    const xTickCount = xDiscontinuities !== undefined
+    // Time axis (trading or plain — both run the logical tick ladder):
+    // width-derived, since the ladder's `count` caps its calendar buckets rather
+    // than targeting a tick total; floored at 2 so a pre-layout zero width still
+    // requests a drawable tick set. Value/category axes keep the d3 target count.
+    const xTickCount = resolvedKind === 'time'
         ? Math.max(2, Math.floor(plotWidth / TRADING_TICK_PX))
         : TIME_TICK_COUNT;
     const { xScale, formatTime } = useMemo(() => {
@@ -373,7 +374,15 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
                 formatTime: resolveTimeFormat(s, xTickCount, timeFormat),
             };
         }
-        const s = scaleTime().domain([d0, d1]).range([0, plotWidth]);
+        // Plain continuous time axis: the same trading-time scale over the
+        // gap-free identity provider, so it runs the same logical tick ladder
+        // (month starts over a year, clock-aligned hours over an afternoon) —
+        // never d3's mixed multi-scale default. Interactions stay on continuous
+        // time math: the frame's `discontinuities` remains undefined, and identity
+        // distance/offset are plain subtraction/addition anyway.
+        const s = scaleTradingTime(identityProvider())
+            .domain([d0, d1])
+            .range([0, plotWidth]);
         return {
             xScale: s,
             formatTime: resolveTimeFormat(s, xTickCount, timeFormat),
@@ -461,7 +470,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     }, [cursorX, xScale, sources, plotWidth]);
     // Pack overlapping top-flag labels (markers + regions) into stacked lanes so
     // close-in-x labels don't collide; chips read their lane back off the frame.
-    const labelLanes = useMemo(() => computeLabelLanes(annotations, (v) => xScale(v), draggingKey), [annotations, xScale, draggingKey]);
+    const labelLanes = useMemo(() => computeLabelLanes(annotations, (v) => xScale(v), draggingKey, plotWidth), [annotations, xScale, draggingKey]);
     const frame = useMemo(() => ({
         timeRange: [d0, d1],
         width,
@@ -499,6 +508,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         onHoverAnnotation,
         onEditAnnotation,
         formatTime,
+        xFormatCustom: timeFormat !== undefined,
         xTickCount,
         registerTrackerSource,
         unregisterTrackerSource,
@@ -553,6 +563,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         onHoverAnnotation,
         onEditAnnotation,
         formatTime,
+        timeFormat,
         xTickCount,
         registerTrackerSource,
         unregisterTrackerSource,

package/dist/LineChart.d.ts

@@ -49,6 +49,20 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * `gap.connectorOpacity`.)
      */
     gaps?: GapMode;
+    /**
+     * Break the line at each **trading-axis discontinuity** (a session / day /
+     * lunch close→open) when the container renders on a trading-time axis (a
+     * `discontinuities` / `calendar` provider). **Omitted ⇒ `false`**: the line
+     * connects the last pre-close point straight to the next open across the
+     * collapsed gap (the near-vertical connector). `true` ends the line at the
+     * close and re-starts it at the open — the intraday look, where a session's
+     * price shouldn't visually flow into the next.
+     *
+     * This is a **scale** break (driven by the axis's collapsed gaps), orthogonal
+     * to {@link gaps} (a **data** break, a NaN run) — set both independently. A
+     * no-op on a continuous axis (no provider) or a provider without `boundaries`.
+     */
+    sessionBreaks?: boolean;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -61,5 +75,5 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * (scaling against its `axis`), and renders nothing to the DOM — the row draws
  * it. The line breaks at gaps rather than spanning them.
  */
-export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, curve, gaps, index, }: LineChartProps<S, VS>): null;
+export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, curve, gaps, sessionBreaks, index, }: LineChartProps<S, VS>): null;
 //# sourceMappingURL=LineChart.d.ts.map

package/dist/LineChart.js

@@ -6,13 +6,16 @@ import { resolveCurve } from './curve.js';
 import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 import { ContainerContext, LayersContext } from './context.js';
 import { useSlotKey } from './use-slot-key.js';
+/** Stable empty boundary list — so `sessionBreaks={false}` keeps a referentially
+ *  constant array and the layer entry isn't rebuilt every render. */
+const NO_BREAKS = [];
 /**
  * A line draw layer. Reads `column` from `series` into a {@link ChartSeries}
  * (columnar, gaps as NaN), registers itself into the enclosing {@link Layers}
  * (scaling against its `axis`), and renders nothing to the DOM — the row draws
  * it. The line breaks at gaps rather than spanning them.
  */
-export function LineChart({ series, column, as: semantic, axis, curve, gaps = DEFAULT_GAP_MODE, index = 0, }) {
+export function LineChart({ series, column, as: semantic, axis, curve, gaps = DEFAULT_GAP_MODE, sessionBreaks = false, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<LineChart> must be rendered inside a <ChartContainer>');
@@ -33,6 +36,17 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
     // Faintness of the inferred dashed connectors (dashed / step) — theme-level,
     // falling back to the shared default so a theme without it still renders faint.
     const gapConnectorOpacity = container.theme.gap?.connectorOpacity ?? DEFAULT_GAP_CONNECTOR_OPACITY;
+    // Trading-axis session breaks: the collapse instants inside this series' span
+    // (session/day/lunch opens the axis skips). Data instants, not pixels — so the
+    // set is view-independent (pan/zoom reuse it). Only computed when opted in and
+    // the container carries a boundary-reporting discontinuity provider.
+    const sessionBreakInstants = useMemo(() => {
+        const provider = container.discontinuities;
+        if (!sessionBreaks || provider?.boundaries === undefined || cs.length < 2) {
+            return NO_BREAKS;
+        }
+        return provider.boundaries(cs.x[0], cs.x[cs.length - 1]);
+    }, [sessionBreaks, container.discontinuities, cs]);
     const entry = useMemo(() => ({
         layer: {
             yExtent: () => yExtent(cs),
@@ -67,7 +81,7 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
                     ? [{ x: e.begin(), value: v, color: style.color, label }]
                     : [];
             },
-            draw: (ctx, xScale, yScale) => drawLine(ctx, cs, xScale, yScale, style, curveFactory, gaps, gapConnectorOpacity),
+            draw: (ctx, xScale, yScale) => drawLine(ctx, cs, xScale, yScale, style, curveFactory, gaps, gapConnectorOpacity, sessionBreakInstants),
         },
         axisId: axis,
         index,
@@ -80,6 +94,7 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
         curveFactory,
         gaps,
         gapConnectorOpacity,
+        sessionBreakInstants,
         axis,
         index,
     ]);

package/dist/XAxis.d.ts

@@ -1,3 +1,4 @@
+import { type AxisTransform } from './derivedTicks.js';
 import { type AxisFormat } from './format.js';
 export interface XAxisProps {
     /**
@@ -24,6 +25,31 @@ export interface XAxisProps {
         readonly at: number;
         readonly label: string;
     }>;
+    /**
+     * Relabel this axis into a **derived unit on the same scale** — a second
+     * tick layout, not a second scale (the pixel mapping never changes). E.g. a
+     * BS-delta strip under a std-moneyness chart (`transform={{ to: sigmaToDelta,
+     * from: deltaToSigma }}`) or a moneyness axis over a strike chart
+     * (`transform={{ to: (k) => k / spot, from: (m) => m * spot }}`). `to`/`from`
+     * are monotonic inverses (either direction); they may be **nonlinear** —
+     * ticks are nice derived-unit values at mixed 1-2-5 step sizes, admitted
+     * wherever they keep pixel room, so a span the transform compresses gets
+     * coarser ticks and a span it stretches gets finer ones. `format` (or the
+     * d3 number default) formats the derived values; the cursor pill and marker
+     * indicators on this axis read in the derived unit too. Ignored on a
+     * category axis; explicit {@link ticks} win. Typically used on a second
+     * `<XAxis>` stacked with the primary one — declaration order places the
+     * strips; gridlines stay on the container's own (primary) ticks.
+     */
+    transform?: AxisTransform;
+    /**
+     * This axis instance's colour — tick marks, labels, the plot-facing rule,
+     * and the `label` title all take it, overriding the theme's `axis.label` /
+     * `axis.grid` / `axis.title.color`. The lever that distinguishes stacked
+     * dual axes (a blue derived-unit strip under a grey primary). Cursor and
+     * marker pills keep their own colours. Omit for the theme's axis colours.
+     */
+    color?: string;
     /**
      * Horizontal placement of each tick label relative to its tick.
      * - **`'center'` (default)** — every label centred on its tick. Note the
@@ -48,5 +74,5 @@ export interface XAxisProps {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export declare function XAxis({ format, label, side, height, ticks: customTicks, align, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=XAxis.d.ts.map

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,6 +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;
+/** 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
@@ -47,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', } = {}) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
@@ -67,19 +75,37 @@ 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';
+    // 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;
     // 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);
+    // 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.
+    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);
     // 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
@@ -126,12 +152,62 @@ 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;
+    // 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),
-        }));
+        : derived !== null
+            ? honestDerived()
+            : xScale.ticks(xTickCount).map((d) => ({
+                x: xScale(d),
+                label: fmt(+d),
+                boundary: boundaryOf?.(+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
@@ -143,7 +219,34 @@ 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;
     const stripHeight = (height ?? TICK_STRIP + (label ? LABEL_STRIP : 0)) +
+        (hasBoundary ? BOUNDARY_STRIP : 0) +
         maxPillLane * PILL_LANE_H;
     return (_jsxs("div", { style: {
             position: 'relative',
@@ -151,10 +254,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;
@@ -178,15 +281,29 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                                 [onTop ? 'bottom' : 'top']: 0,
                                 width: '1px',
                                 height: `${tickHeight}px`,
-                                background: theme.axis.grid,
+                                background: color ?? theme.axis.grid,
                             } }), _jsx("div", { style: {
                                 position: 'absolute',
                                 left: `${labelLeft}px`,
                                 [onTop ? 'bottom' : 'top']: `${labelOffset}px`,
                                 transform: labelTransform,
                                 whiteSpace: 'nowrap',
-                            }, children: t.label })] }, `${t.x}-${i}`));
-            }), label !== undefined && (_jsx("div", { style: {
+                            }, 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: {
+                    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: {
                     position: 'absolute',
                     left: 0,
                     width: '100%',
@@ -194,7 +311,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: {