@pond-ts/charts 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
 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.35.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.37.0...HEAD
+[0.37.0]: https://github.com/pjm17971/pond-ts/compare/v0.36.0...v0.37.0
+[0.36.0]: https://github.com/pjm17971/pond-ts/compare/v0.35.0...v0.36.0
 [0.35.0]: https://github.com/pjm17971/pond-ts/compare/v0.34.1...v0.35.0
 [0.34.1]: https://github.com/pjm17971/pond-ts/compare/v0.34.0...v0.34.1
 [0.34.0]: https://github.com/pjm17971/pond-ts/compare/v0.33.0...v0.34.0
@@ -31,6 +33,70 @@ patch bumps are strictly additive.
 [0.19.0]: https://github.com/pjm17971/pond-ts/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/pjm17971/pond-ts/compare/v0.17.1...v0.18.0
 
+## [0.37.0] — 2026-07-02
+
+A `@pond-ts/charts` release: the axis wave — label, tick, and domain controls
+driven by the Tidal terminal's friction. `pond-ts`, `@pond-ts/react`, and
+`@pond-ts/fit` carry no code changes — republished in lock-step (peer ranges
+widen to `^0.37.0`).
+
+### Added
+
+- **Charts — axis title typography (`theme.axis.title`).** The rotated y-axis
+  title now renders a touch larger than the ticks by default and is fully
+  themeable (`{ color, size, opacity }`, shared with the x-axis label). (#318)
+- **Charts — `YAxis labelPlacement`.** `'rotated'` (default) or `'top'` — a
+  horizontal title above the axis, aligned to the axis line, in a reserved
+  header band that clears the top tick. (#318, #320)
+- **Charts — `XAxis align`.** `'center'` (**new default**), `'auto'` (previous
+  behaviour: centred but first/last end-anchored), or `'right'` (label beside an
+  extended tick). (#318)
+- **Charts — `YAxis pad`.** Fractional headroom added to each side of the
+  resolved domain (`0` default) — lifts a tight domain off the plot edges
+  without hand-computing bounds. (#319)
+- **Charts — `YAxis boundaryLabels`.** `false` drops the top & bottom tick
+  numbers (gridlines stay) for stacked layouts where the edge labels crowd. (#319)
+- **Charts — new `Charts/Axes` Storybook gallery** covering the above. (#318)
+
+### Changed
+
+- **Charts — domain-extreme y-tick labels now clamp inside the row** instead of
+  half-overflowing the top/bottom edge (resolves Tidal friction F-charts-6). (#319)
+- **Charts — `XAxis` tick-label default is now `'center'`** (was the
+  end-anchored `'auto'`). Pass `align="auto"` for the old behaviour. (#318)
+
+## [0.36.0] — 2026-07-02
+
+A `@pond-ts/charts` release: a CSS-custom-property → theme bridge so a canvas
+chart can follow a design system's tokens and dark/light toggle. `pond-ts`,
+`@pond-ts/react`, and `@pond-ts/fit` carry no code changes — republished in
+lock-step (their `pond-ts` / `@pond-ts/react` peer ranges widen to `^0.36.0`).
+
+### Added
+
+- **Charts — `cssVarTheme(base, resolve, opts?)`.** Builds a `ChartTheme` by
+  overlaying CSS custom properties onto a base theme: a typed `resolve`
+  receives a `readVar` and returns only the slots to override. An unresolved
+  var keeps the base value (a missing token never blanks a colour). DOM-only by
+  design; safe under SSR / worker (returns the base + any literal fallbacks).
+  The typed `ChartTheme` stays the single styling channel — this generates it
+  from CSS rather than adding a second one. (#315)
+- **Charts — `useChartTheme(base, resolve, opts?)`.** Wraps `cssVarTheme` and
+  re-resolves on a `data-theme` / `class` change (a `MutationObserver` on the
+  root, configurable via `{ target, attributes }`), so a chart follows
+  dark/light with the page — no `mode` prop threaded through. Returns a new
+  theme reference only when the resolved theme actually changed (the repaint
+  signal `ChartContainer` keys on), so an unrelated attribute toggle doesn't
+  repaint. Lives in `@pond-ts/charts` (not `@pond-ts/react`) to keep the
+  package graph acyclic. (#315)
+- **Docs — charts recipes.** [Theming charts](https://pjm17971.github.io/pond-ts/docs/recipes/theming)
+  (the `ChartTheme` model, semantic identifiers, per-series dash, the CSS-var
+  bridge), [Using @pond-ts/charts](https://pjm17971.github.io/pond-ts/docs/recipes/using-charts)
+  (install, the Storybook `react-docgen` gotcha, the repaint contract,
+  in-dev consumption), and
+  [Resizable multi-panel layout](https://pjm17971.github.io/pond-ts/docs/recipes/resizable-panels).
+  (#314, #315, #316)
+
 ## [0.35.0] — 2026-07-02
 
 A `@pond-ts/charts` release: per-series line dash patterns. `pond-ts`,

package/dist/ChartRow.js

@@ -12,6 +12,10 @@ const IMPLICIT_AXIS_ID = '__default__';
 /** Axis tick count for the per-axis formatter — matches `<YAxis>`'s tick count
  *  so the readout formatter is calibrated exactly as the labels are. */
 const AXIS_TICK_COUNT = 5;
+/** Vertical band (px) reserved above the plot for a `labelPlacement="top"` axis
+ *  title, so it clears the top tick + plotted data. Sized for the default title
+ *  (~`font.size + 1`); a much larger themed title may want more room. */
+const TOP_LABEL_HEADER = 16;
 /**
  * A horizontal band sharing the container's time axis. `ChartRow` owns the
  * **horizontal layout** (axes left/right around a `<Layers>` plot area) and
@@ -91,6 +95,8 @@ export function ChartRow({ height, cursor, children }) {
                 width: 0,
                 min: undefined,
                 max: undefined,
+                pad: 0,
+                labelPlacement: 'rotated',
                 format: undefined,
                 tickValues: undefined,
                 index: 0,
@@ -126,6 +132,11 @@ export function ChartRow({ height, cursor, children }) {
     const containerLeftSlots = container.leftSlots;
     const containerRightSlots = container.rightSlots;
     const { axisSlots, leftPad, rightPad } = useMemo(() => placeAxisSlots(leftAxes, rightAxes, containerLeftSlots, containerRightSlots), [leftAxes, rightAxes, containerLeftSlots, containerRightSlots]);
+    // Header band reserved at the top of the plot when any axis draws a `'top'`
+    // title — the scale range then starts below it (see below).
+    const topHeader = effectiveAxes.some((ax) => ax.labelPlacement === 'top')
+        ? TOP_LABEL_HEADER
+        : 0;
     // One y-scale per axis. A layer counts toward an axis when its (late-resolved)
     // axis id matches; `resolveYDomain` handles the auto-fit + empty/flat/inverted
     // edges. yExtent() is O(points), so only walk the layers when a bound auto-fits.
@@ -137,11 +148,15 @@ export function ChartRow({ height, cursor, children }) {
                     .filter((entry) => (entry.axisId ?? defaultAxisId) === ax.id)
                     .map((entry) => entry.layer.yExtent())
                 : [];
-            const [lo, hi] = resolveYDomain(ax.min, ax.max, extents);
-            map.set(ax.id, scaleLinear().domain([lo, hi]).range([height, 0]));
+            const [lo, hi] = resolveYDomain(ax.min, ax.max, extents, ax.pad);
+            // Reserve a header band at the top when any axis draws a `'top'` title,
+            // so the title clears the top tick + plot (the whole row shifts down
+            // uniformly, keeping stacked axes aligned). No top titles ⇒ range top 0,
+            // so nothing changes for existing charts.
+            map.set(ax.id, scaleLinear().domain([lo, hi]).range([height, topHeader]));
         }
         return map;
-    }, [effectiveAxes, layerList, height, defaultAxisId]);
+    }, [effectiveAxes, layerList, height, defaultAxisId, topHeader]);
     // A value formatter per axis (its `format` resolved against its scale) — shared
     // by the axis tick labels and the cursor readout so a value reads the same.
     const formats = useMemo(() => {

package/dist/XAxis.d.ts

@@ -24,6 +24,19 @@ export interface XAxisProps {
         readonly at: number;
         readonly label: string;
     }>;
+    /**
+     * Horizontal placement of each tick label relative to its tick.
+     * - **`'center'` (default)** — every label centred on its tick. Note the
+     *   first/last labels can then extend past the plot edges (the strip doesn't
+     *   clip), so a wide first label may reach into the left y-axis gutter; use
+     *   `'auto'` if that crowds.
+     * - `'auto'` — centred, but the first label left-anchors and the last
+     *   right-anchors so the edge labels stay inside the plot (the old default).
+     * - `'right'` — the label sits to the **right** of an extended tick that
+     *   drops from the axis line (label beside the tick, not under it) — useful
+     *   for dense or wide labels that would collide when centred.
+     */
+    align?: 'auto' | 'center' | 'right';
 }
 /**
  * The shared **x axis**, a sibling of {@link YAxis} for the horizontal axis. A
@@ -35,5 +48,5 @@ export interface XAxisProps {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export declare function XAxis({ format, label, side, height, ticks: customTicks, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function XAxis({ format, label, side, height, ticks: customTicks, align, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=XAxis.d.ts.map

package/dist/XAxis.js

@@ -17,7 +17,7 @@ const TICK_COUNT = 5;
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, } = {}) {
+export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, align = 'center', } = {}) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
@@ -51,23 +51,33 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
             fontSize: `${theme.font.size}px`,
             color: theme.axis.label,
         }, children: [placed.map((t, i) => {
-                // End-align the edge labels so they stay within [0, plotWidth].
-                const labelTransform = i === 0
+                const isFirst = i === 0;
+                const isLast = i === placed.length - 1;
+                // `center`: every label centred on its tick. `auto`: centred, but the
+                // edge labels end-align so they stay within [0, plotWidth]. `right`:
+                // label left-anchored just past an extended tick (beside, not under).
+                const labelTransform = align === 'right'
                     ? 'none'
-                    : i === placed.length - 1
-                        ? 'translateX(-100%)'
-                        : 'translateX(-50%)';
+                    : align === 'auto' && isFirst
+                        ? 'none'
+                        : 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;
+                const labelLeft = align === 'right' ? t.x + 4 : t.x;
+                const labelOffset = align === 'right' ? 2 : 6;
                 return (_jsxs(Fragment, { children: [_jsx("div", { style: {
                                 position: 'absolute',
                                 left: `${t.x}px`,
                                 [onTop ? 'bottom' : 'top']: 0,
                                 width: '1px',
-                                height: '4px',
+                                height: `${tickHeight}px`,
                                 background: theme.axis.grid,
                             } }), _jsx("div", { style: {
                                 position: 'absolute',
-                                left: `${t.x}px`,
-                                [onTop ? 'bottom' : 'top']: '6px',
+                                left: `${labelLeft}px`,
+                                [onTop ? 'bottom' : 'top']: `${labelOffset}px`,
                                 transform: labelTransform,
                                 whiteSpace: 'nowrap',
                             }, children: t.label })] }, `${t.x}-${i}`));
@@ -77,7 +87,10 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                     width: '100%',
                     textAlign: 'center',
                     [onTop ? 'top' : 'bottom']: 0,
-                    opacity: 0.7,
+                    // 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,
+                    opacity: theme.axis.title?.opacity ?? 0.85,
                     whiteSpace: 'nowrap',
                 }, children: label }))] }));
 }

package/dist/YAxis.d.ts

@@ -11,9 +11,25 @@ export interface YAxisProps {
     side?: 'left' | 'right';
     /** Display label / unit (e.g. `bpm`); defaults to `id`. */
     label?: string;
+    /**
+     * How the axis title (`label`) is drawn:
+     * - **`'rotated'` (default)** — a thin vertical strip down the outer edge
+     *   (the standard y-axis convention; fits long labels in a narrow gutter).
+     * - `'top'` — horizontal, at the top of the axis, aligned to its side. Reads
+     *   better for short unit labels; keep it terse and pair it with a domain
+     *   that has headroom (auto-fit / padded) so it doesn't crowd the top tick.
+     */
+    labelPlacement?: 'rotated' | 'top';
     /** Explicit domain bounds; omit to auto-fit the charts linked to this axis. */
     min?: number;
     max?: number;
+    /**
+     * Fractional headroom added to each side of the resolved domain — `0` (the
+     * default) means none. Lifts a tight domain off the plot edges without
+     * hand-computing bounds (e.g. `pad={0.05}` adds 5% of the span top & bottom).
+     * Applies to an explicit `[min, max]` or an auto-fit domain.
+     */
+    pad?: number;
     /**
      * Value formatting for the tick labels (and the cursor readout, which matches):
      * a d3 format specifier string (e.g. `'.0%'`, `',.2f'`) or a `(value) => string`
@@ -37,6 +53,14 @@ export interface YAxisProps {
         readonly at: number;
         readonly label: string;
     }>;
+    /**
+     * Render the tick labels at the domain extremes (the top & bottom ticks)?
+     * **Default `true`.** `false` drops just those two numbers — the gridlines
+     * stay — for when the min/max labels crowd a stacked row's edges and you'd
+     * rather omit them than keep them. (Extreme labels are otherwise clamped to
+     * stay inside the row, never overflowing the edge.)
+     */
+    boundaryLabels?: boolean;
     /** Gutter width in CSS pixels (default 50). */
     width?: number;
     /**
@@ -53,5 +77,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, width, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function YAxis({ id, side, label, min, max, format, ticks, pad, boundaryLabels, width, labelPlacement, 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, width = DEFAULT_WIDTH, index = 0, }) {
+export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -28,10 +28,12 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, width
         width,
         min,
         max,
+        pad,
+        labelPlacement,
         format,
         tickValues: ticks?.map((t) => t.at),
         index,
-    }), [id, side, width, min, max, format, ticks, index]);
+    }), [id, side, width, min, max, pad, labelPlacement, format, ticks, index]);
     // A stable per-instance slot (see useSlotKey) keeps this axis in a fixed
     // registry position, so a min/max/side change updates in place rather than
     // re-appending (which would move the first axis behind a later one and
@@ -76,27 +78,50 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, width
                 fontSize: `${theme.font.size}px`,
                 color: theme.axis.label,
             }, children: [yScale &&
-                    tickList.map(({ value, label }) => (_jsx("div", { style: {
-                            position: 'absolute',
-                            top: `${yScale(value)}px`,
-                            [side === 'left' ? 'right' : 'left']: '4px',
-                            transform: 'translateY(-50%)',
-                            whiteSpace: 'nowrap',
-                        }, children: label }, value))), _jsx("div", { style: {
+                    tickList.map(({ value, label }, i) => {
+                        // Drop just the top & bottom labels when boundary labels are off
+                        // (gridlines are drawn separately, so they stay).
+                        if (!boundaryLabels && (i === 0 || i === tickList.length - 1))
+                            return null;
+                        // Clamp the label's centre so a domain-extreme label stays inside
+                        // the row instead of half-overflowing the top/bottom edge (and
+                        // colliding across a splitter in a stacked layout) — F-charts-6.
+                        const half = theme.font.size / 2 + 1;
+                        const top = Math.max(half, Math.min(row.height - half, yScale(value)));
+                        return (_jsx("div", { style: {
+                                position: 'absolute',
+                                top: `${top}px`,
+                                [side === 'left' ? 'right' : 'left']: '4px',
+                                transform: 'translateY(-50%)',
+                                whiteSpace: 'nowrap',
+                            }, children: label }, value));
+                    }), labelPlacement === 'top' ? (_jsx("div", { style: {
+                        position: 'absolute',
+                        top: 0,
+                        // Align to the axis line (the plot-facing edge), matching the tick
+                        // 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,
+                        opacity: theme.axis.title?.opacity ?? 0.85,
+                        whiteSpace: 'nowrap',
+                        pointerEvents: 'none',
+                    }, children: label ?? id })) : (_jsx("div", { style: {
                         position: 'absolute',
                         [side === 'left' ? 'left' : 'right']: '1px',
                         top: 0,
                         bottom: 0,
-                        width: `${theme.font.size + 2}px`,
+                        width: `${(theme.axis.title?.size ?? theme.font.size + 1) + 3}px`,
                         display: 'flex',
                         alignItems: 'center',
                         justifyContent: 'center',
-                        fontSize: `${theme.font.size - 1}px`,
-                        opacity: 0.7,
+                        fontSize: `${theme.axis.title?.size ?? theme.font.size + 1}px`,
+                        color: theme.axis.title?.color ?? theme.axis.label,
+                        opacity: theme.axis.title?.opacity ?? 0.85,
                         pointerEvents: 'none',
                     }, children: _jsx("span", { style: {
                             whiteSpace: 'nowrap',
                             transform: `rotate(${side === 'left' ? -90 : 90}deg)`,
-                        }, children: label ?? id }) })] }) }));
+                        }, children: label ?? id }) }))] }) }));
 }
 //# sourceMappingURL=YAxis.js.map

package/dist/context.d.ts

@@ -396,6 +396,10 @@ export interface AxisSpec {
     /** Explicit domain bounds, or `undefined` to auto-fit linked layers. */
     readonly min: number | undefined;
     readonly max: number | undefined;
+    /** Fractional headroom added to each side of the resolved domain (`0` = none). */
+    readonly pad: number;
+    /** Title placement; `'top'` makes the row reserve a header band above the plot. */
+    readonly labelPlacement: 'rotated' | 'top';
     /** Value formatting for the tick labels + the cursor readout ({@link AxisFormat}),
      *  or `undefined` for the scale's d3 default. */
     readonly format: AxisFormat | undefined;

package/dist/css-theme.d.ts

@@ -0,0 +1,50 @@
+import type { ChartTheme } from './theme.js';
+/**
+ * A deep-partial of {@link ChartTheme} — every leaf optional, arrays kept whole
+ * (so `axis.gridDash` / `annotation.depth` replace rather than merge
+ * element-wise). The shape a {@link cssVarTheme} resolver returns: name only the
+ * slots you're driving from CSS, everything else falls through to the base.
+ */
+export type ChartThemeOverrides = DeepPartial<ChartTheme>;
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]> | undefined;
+} : T;
+/**
+ * Reads a CSS custom property's computed value. Returns the trimmed value, or
+ * `fallback` when the property is empty / unset / there's no DOM (SSR, worker).
+ * `undefined` from a resolver leaf means "leave the base theme's value" — so a
+ * missing var never blanks a colour.
+ */
+export type VarReader = (name: string, fallback?: string) => string | undefined;
+/**
+ * Build a {@link ChartTheme} by overlaying CSS-custom-property values onto a
+ * `base` theme — the adapter that lets a chart track a design system's tokens
+ * (and its dark/light toggle) without hand-mirroring hex values.
+ *
+ * `resolve` receives a {@link VarReader} and returns only the slots to override
+ * (a {@link ChartThemeOverrides}); the result is `base` deep-merged with them.
+ * The typed `ChartTheme` stays the one styling channel — this **generates** it
+ * from CSS, it doesn't add a second one.
+ *
+ * ```ts
+ * const theme = cssVarTheme(defaultTheme, (v) => ({
+ *   line: { default: { color: v('--td-primary') }, secondary: { color: v('--td-secondary') } },
+ *   axis: { label: v('--td-text-3'), grid: v('--td-hairline') },
+ *   cursor: v('--td-text-3'),
+ *   font: { family: v('--td-font-mono') },
+ * }));
+ * ```
+ *
+ * **DOM-only, by design.** It reads `getComputedStyle` off `opts.element` (or
+ * `document.documentElement`). With no DOM — SSR, an OffscreenCanvas worker —
+ * every `readVar` returns its fallback (or `undefined`, kept from `base`), so
+ * the call is safe and returns the base theme (plus any literal fallbacks). For
+ * a live chart that follows a theme toggle, use {@link useChartTheme}, which
+ * wraps this and re-resolves on a `data-theme` change — don't call `cssVarTheme`
+ * per frame (`getComputedStyle` is a layout read).
+ */
+export declare function cssVarTheme(base: ChartTheme, resolve: (readVar: VarReader) => ChartThemeOverrides, opts?: {
+    element?: Element;
+}): ChartTheme;
+export {};
+//# sourceMappingURL=css-theme.d.ts.map

package/dist/css-theme.js

@@ -0,0 +1,72 @@
+/**
+ * Build a {@link ChartTheme} by overlaying CSS-custom-property values onto a
+ * `base` theme — the adapter that lets a chart track a design system's tokens
+ * (and its dark/light toggle) without hand-mirroring hex values.
+ *
+ * `resolve` receives a {@link VarReader} and returns only the slots to override
+ * (a {@link ChartThemeOverrides}); the result is `base` deep-merged with them.
+ * The typed `ChartTheme` stays the one styling channel — this **generates** it
+ * from CSS, it doesn't add a second one.
+ *
+ * ```ts
+ * const theme = cssVarTheme(defaultTheme, (v) => ({
+ *   line: { default: { color: v('--td-primary') }, secondary: { color: v('--td-secondary') } },
+ *   axis: { label: v('--td-text-3'), grid: v('--td-hairline') },
+ *   cursor: v('--td-text-3'),
+ *   font: { family: v('--td-font-mono') },
+ * }));
+ * ```
+ *
+ * **DOM-only, by design.** It reads `getComputedStyle` off `opts.element` (or
+ * `document.documentElement`). With no DOM — SSR, an OffscreenCanvas worker —
+ * every `readVar` returns its fallback (or `undefined`, kept from `base`), so
+ * the call is safe and returns the base theme (plus any literal fallbacks). For
+ * a live chart that follows a theme toggle, use {@link useChartTheme}, which
+ * wraps this and re-resolves on a `data-theme` change — don't call `cssVarTheme`
+ * per frame (`getComputedStyle` is a layout read).
+ */
+export function cssVarTheme(base, resolve, opts) {
+    const el = opts?.element ??
+        (typeof document !== 'undefined' ? document.documentElement : undefined);
+    const style = el && typeof getComputedStyle === 'function'
+        ? getComputedStyle(el)
+        : undefined;
+    const readVar = (name, fallback) => {
+        const raw = style?.getPropertyValue(name).trim();
+        return raw ? raw : fallback;
+    };
+    return deepMerge(base, resolve(readVar));
+}
+/**
+ * Deep-merge `partial` over `base`: recurse into plain objects, replace at
+ * leaves and arrays, and **skip `undefined`** in `partial` (so an unresolved
+ * var keeps the base value). Never mutates `base`; each merged object level is
+ * freshly spread, and untouched subtrees are shared by reference (safe — a
+ * `ChartTheme` is read-only).
+ */
+function deepMerge(base, partial) {
+    if (partial === undefined)
+        return base;
+    if (base === null ||
+        typeof base !== 'object' ||
+        Array.isArray(base) ||
+        Array.isArray(partial) ||
+        typeof partial !== 'object' ||
+        partial === null) {
+        // Leaf, array (replace whole), or a partial that introduces a value where
+        // the base had none — the partial wins.
+        return partial;
+    }
+    const out = { ...base };
+    for (const key of Object.keys(partial)) {
+        // Never let a resolver's key rewrite the prototype chain.
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+            continue;
+        const pv = partial[key];
+        if (pv === undefined)
+            continue;
+        out[key] = deepMerge(base[key], pv);
+    }
+    return out;
+}
+//# sourceMappingURL=css-theme.js.map

package/dist/domain.d.ts

@@ -14,6 +14,11 @@
  * can otherwise invert it (e.g. `min=5` with no data would naively give
  * `[5, 1]`). Two explicit bounds are returned as-is (an inverted explicit domain
  * is a deliberate axis flip; we don't second-guess it).
+ *
+ * `pad` (fractional, default `0`) expands the resolved domain outward by
+ * `pad × span` on each side — headroom without hand-computing bounds, useful to
+ * lift a tight **explicit** domain off the plot edges. Applied last, to whatever
+ * domain was resolved (explicit or auto); `0` is a no-op.
  */
-export declare function resolveYDomain(min: number | undefined, max: number | undefined, extents: Iterable<readonly [number, number] | null>): [number, number];
+export declare function resolveYDomain(min: number | undefined, max: number | undefined, extents: Iterable<readonly [number, number] | null>, pad?: number): [number, number];
 //# sourceMappingURL=domain.d.ts.map

package/dist/domain.js

@@ -15,8 +15,22 @@ import { scaleLinear } from 'd3-scale';
  * can otherwise invert it (e.g. `min=5` with no data would naively give
  * `[5, 1]`). Two explicit bounds are returned as-is (an inverted explicit domain
  * is a deliberate axis flip; we don't second-guess it).
+ *
+ * `pad` (fractional, default `0`) expands the resolved domain outward by
+ * `pad × span` on each side — headroom without hand-computing bounds, useful to
+ * lift a tight **explicit** domain off the plot edges. Applied last, to whatever
+ * domain was resolved (explicit or auto); `0` is a no-op.
  */
-export function resolveYDomain(min, max, extents) {
+export function resolveYDomain(min, max, extents, pad = 0) {
+    const result = resolveBase(min, max, extents);
+    if (pad) {
+        const [lo, hi] = result;
+        const p = pad * (hi - lo);
+        return [lo - p, hi + p];
+    }
+    return result;
+}
+function resolveBase(min, max, extents) {
     // Both bounds explicit: trust them verbatim (allows an intentional flip).
     if (min !== undefined && max !== undefined)
         return [min, max];

package/dist/index.d.ts

@@ -52,5 +52,9 @@ export type { Curve } from './curve.js';
 export type { GapMode } from './gaps.js';
 export { defaultTheme, estelaTheme } from './theme.js';
 export type { ChartTheme, LineStyle, BandStyle, AreaStyle, ScatterStyle, BoxStyle, BarStyle, } from './theme.js';
+export { cssVarTheme } from './css-theme.js';
+export type { ChartThemeOverrides, VarReader } from './css-theme.js';
+export { useChartTheme } from './useChartTheme.js';
+export type { UseChartThemeOptions } from './useChartTheme.js';
 export type { CursorMode, TrackerInfo, TrackerSample, SelectInfo, } from './context.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -34,4 +34,9 @@ export { BarChart } from './BarChart.js';
 export { Region, Baseline, Marker } from './annotations.js';
 export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, } from './data.js';
 export { defaultTheme, estelaTheme } from './theme.js';
+// CSS-custom-property → ChartTheme bridge: build a theme from a design system's
+// tokens (`cssVarTheme`), and a hook that re-resolves it on a `data-theme`
+// toggle so a canvas chart follows dark/light (`useChartTheme`).
+export { cssVarTheme } from './css-theme.js';
+export { useChartTheme } from './useChartTheme.js';
 //# sourceMappingURL=index.js.map

package/dist/theme.d.ts

@@ -88,6 +88,17 @@ export interface ChartTheme {
         readonly grid: string;
         /** Gridline dash pattern (px on/off pairs); `[]` for solid. */
         readonly gridDash: readonly number[];
+        /**
+         * 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
+         * field to fall back: `color` → `label`, `size` → `font.size + 1` (a touch
+         * larger than the ticks so the rotated strip reads), `opacity` → `0.85`.
+         */
+        readonly title?: {
+            readonly color?: string;
+            readonly size?: number;
+            readonly opacity?: number;
+        };
     };
     /** Label / tick typography. One source for axes + chrome. */
     readonly font: {

package/dist/useChartTheme.d.ts

@@ -0,0 +1,50 @@
+import { type ChartThemeOverrides, type VarReader } from './css-theme.js';
+import type { ChartTheme } from './theme.js';
+/** Options for {@link useChartTheme}. */
+export interface UseChartThemeOptions {
+    /**
+     * Element whose CSS custom properties are read and whose attribute changes
+     * are watched. **Default `document.documentElement`** (`<html>`) — the usual
+     * home of a `data-theme` toggle. Pass a scoped element to theme one subtree.
+     */
+    target?: Element;
+    /**
+     * Attributes that, when they change on `target`, trigger a re-resolve.
+     * **Default `['data-theme', 'class']`** — the two common dark/light switches.
+     */
+    attributes?: readonly string[];
+}
+/**
+ * Live {@link ChartTheme} bound to CSS custom properties: resolves `resolve`
+ * against the DOM (via {@link cssVarTheme}) and **re-resolves whenever the
+ * theme toggle flips** — a `MutationObserver` watches `target`'s
+ * `data-theme` / `class`, so `<ChartContainer theme={useChartTheme(...)} />`
+ * follows dark/light with no `mode` prop threaded through and no hand-ordered
+ * attribute-then-read dance.
+ *
+ * When the resolved theme changes it returns a **new** reference, which is the
+ * repaint signal — `ChartContainer` redraws when handed a new `theme`. A
+ * watched mutation that doesn't change the resolved values (e.g. an app
+ * toggling an unrelated `class` on `<html>`) returns the *same* reference, so
+ * it doesn't repaint. Resolution runs on mount and on watched-attribute changes
+ * only — never per frame — so the `getComputedStyle` read stays cheap.
+ *
+ * ```tsx
+ * const theme = useChartTheme(defaultTheme, (v) => ({
+ *   line: { default: { color: v('--td-primary') } },
+ *   axis: { label: v('--td-text-3'), grid: v('--td-hairline') },
+ * }));
+ * return <ChartContainer width={w} theme={theme}>…</ChartContainer>;
+ * ```
+ *
+ * `base` and `resolve` are read fresh on every resolve (held in refs), so
+ * inline literals are fine — they don't need memoizing and don't re-subscribe
+ * the observer. **But** because a resolve only fires on mount + a watched
+ * mutation, changing `base`/`resolve` alone won't re-resolve until the next
+ * toggle; if you need to swap them and re-resolve immediately, change `target`
+ * / `attributes` (which re-subscribes) or remount. SSR-safe: the first value
+ * resolves with no DOM (returns `base` + any literal fallbacks); the client
+ * re-resolves on mount.
+ */
+export declare function useChartTheme(base: ChartTheme, resolve: (readVar: VarReader) => ChartThemeOverrides, opts?: UseChartThemeOptions): ChartTheme;
+//# sourceMappingURL=useChartTheme.d.ts.map

package/dist/useChartTheme.js

@@ -0,0 +1,79 @@
+import { useEffect, useRef, useState } from 'react';
+import { cssVarTheme, } from './css-theme.js';
+/**
+ * Live {@link ChartTheme} bound to CSS custom properties: resolves `resolve`
+ * against the DOM (via {@link cssVarTheme}) and **re-resolves whenever the
+ * theme toggle flips** — a `MutationObserver` watches `target`'s
+ * `data-theme` / `class`, so `<ChartContainer theme={useChartTheme(...)} />`
+ * follows dark/light with no `mode` prop threaded through and no hand-ordered
+ * attribute-then-read dance.
+ *
+ * When the resolved theme changes it returns a **new** reference, which is the
+ * repaint signal — `ChartContainer` redraws when handed a new `theme`. A
+ * watched mutation that doesn't change the resolved values (e.g. an app
+ * toggling an unrelated `class` on `<html>`) returns the *same* reference, so
+ * it doesn't repaint. Resolution runs on mount and on watched-attribute changes
+ * only — never per frame — so the `getComputedStyle` read stays cheap.
+ *
+ * ```tsx
+ * const theme = useChartTheme(defaultTheme, (v) => ({
+ *   line: { default: { color: v('--td-primary') } },
+ *   axis: { label: v('--td-text-3'), grid: v('--td-hairline') },
+ * }));
+ * return <ChartContainer width={w} theme={theme}>…</ChartContainer>;
+ * ```
+ *
+ * `base` and `resolve` are read fresh on every resolve (held in refs), so
+ * inline literals are fine — they don't need memoizing and don't re-subscribe
+ * the observer. **But** because a resolve only fires on mount + a watched
+ * mutation, changing `base`/`resolve` alone won't re-resolve until the next
+ * toggle; if you need to swap them and re-resolve immediately, change `target`
+ * / `attributes` (which re-subscribes) or remount. SSR-safe: the first value
+ * resolves with no DOM (returns `base` + any literal fallbacks); the client
+ * re-resolves on mount.
+ */
+export function useChartTheme(base, resolve, opts) {
+    const baseRef = useRef(base);
+    baseRef.current = base;
+    const resolveRef = useRef(resolve);
+    resolveRef.current = resolve;
+    const target = opts?.target;
+    // Stable key for the effect dep so an inline `attributes` array doesn't
+    // re-subscribe every render.
+    const attrKey = (opts?.attributes ?? ['data-theme', 'class']).join(',');
+    const compute = () => cssVarTheme(baseRef.current, resolveRef.current, target ? { element: target } : undefined);
+    const [theme, setTheme] = useState(compute);
+    // Re-resolve, but only push a new reference when the resolved theme actually
+    // changed — so a watched-but-unrelated mutation (e.g. an app toggling a
+    // scroll-lock `class` on `<html>`) doesn't force a repaint. Identical values
+    // ⇒ return the previous reference ⇒ React bails out.
+    const resolveAndApply = () => {
+        const next = compute();
+        setTheme((prev) => (themesEqual(prev, next) ? prev : next));
+    };
+    useEffect(() => {
+        const el = target ??
+            (typeof document !== 'undefined' ? document.documentElement : undefined);
+        if (!el || typeof MutationObserver === 'undefined')
+            return;
+        // Re-resolve on mount: the SSR/first value was computed without a DOM.
+        resolveAndApply();
+        const observer = new MutationObserver(resolveAndApply);
+        observer.observe(el, {
+            attributes: true,
+            attributeFilter: attrKey.split(','),
+        });
+        return () => observer.disconnect();
+        // `resolveAndApply` closes over stable refs; re-subscribe only on
+        // target/attr change.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [target, attrKey]);
+    return theme;
+}
+/** Value-equality for two resolved themes. A `ChartTheme` is a plain tree of
+ *  strings / numbers / small arrays (no functions, stable key order), so a
+ *  JSON compare is correct and cheap at the mount/toggle cadence this runs at. */
+function themesEqual(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+//# sourceMappingURL=useChartTheme.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.35.0",
-    "pond-ts": "^0.35.0",
+    "@pond-ts/react": "^0.37.0",
+    "pond-ts": "^0.37.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {