@pond-ts/charts 0.34.1 → 0.36.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.34.1...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.36.0...HEAD
+[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
 [0.33.0]: https://github.com/pjm17971/pond-ts/compare/v0.32.0...v0.33.0
@@ -30,6 +32,55 @@ 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.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`,
+`@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.35.0`).
+
+### Added
+
+- **Charts — per-series line dash (`LineStyle.dash`).** A theme's line style
+  accepts an optional `dash?: readonly number[]` — a px on/off pattern
+  (`[6, 4]` dashed, `[2, 3]` ≈ dotted; omit or `[]` = solid) applied to the
+  series stroke. Lets a theme set a **modeled / forecast** line (e.g. GARCH
+  vol) apart from an observed one at a glance. Distinct from a `GapMode`'s
+  inferred gap-bridge dashing (which marks *missing data*, not the whole
+  line). Additive: existing themes are unaffected; a solid line never touches
+  `setLineDash`. New `Charts/LineChart → LineStyles` story. (#313)
+
 ## [0.34.1] — 2026-07-01
 
 A `pond-ts` core patch: fixes a performance regression introduced in 0.34.0.

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/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/line.js

@@ -69,7 +69,19 @@ export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, ga
     gen(ys);
     ctx.strokeStyle = style.color;
     ctx.lineWidth = style.width;
-    ctx.stroke();
+    // Per-series dash (a modeled/forecast line reads dashed). Applied only when
+    // set — a solid line never touches `setLineDash` — then reset to solid right
+    // after the stroke so it can't leak into the gap-bridge overlay below (which
+    // sets its own dash) or the next layer drawn on this context.
+    const dash = style.dash;
+    if (dash && dash.length > 0) {
+        ctx.setLineDash(dash.slice());
+        ctx.stroke();
+        ctx.setLineDash([]);
+    }
+    else {
+        ctx.stroke();
+    }
     // Overlay bridges for the inferred-gap modes. `dashed` / `step` are faint
     // dashed connectors (gapConnectorOpacity); only `fade` drops to the axis floor.
     if (gaps === 'dashed' || gaps === 'step' || gaps === 'fade') {

package/dist/theme.d.ts

@@ -138,6 +138,15 @@ export interface ChartTheme {
 export interface LineStyle {
     readonly color: string;
     readonly width: number;
+    /**
+     * Optional dash pattern — px on/off lengths (`[6, 4]` = 6 on, 4 off; `[2, 3]`
+     * ≈ dotted). Omit or `[]` for a solid stroke. This is the *series'* own style
+     * — distinct from a {@link GapMode}'s inferred faint gap-bridge dashing (that
+     * marks missing data; this marks the whole line). Use it to set a **modeled**
+     * series (a forecast / smoothed estimate, e.g. GARCH vol) apart from an
+     * observed one at a glance.
+     */
+    readonly dash?: readonly number[];
 }
 /** A resolved band style: fill colour + opacity (0–1) for the variance envelope. */
 export interface BandStyle {

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.34.1",
+  "version": "0.36.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.34.0",
-    "pond-ts": "^0.34.0",
+    "@pond-ts/react": "^0.36.0",
+    "pond-ts": "^0.36.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {