basalt-ui 1.41.0 → 2.0.1

package/src/charts/cursor.ts

@@ -0,0 +1,282 @@
+/**
+ * The shared cursor (`docs/V2-SPEC.md` § 9.4). One TanStack `createChartCursor()` per group in a
+ * module map — no provider. Every chart joins `'default'` unless it names a `cursorGroup`.
+ *
+ * CLIENT-ONLY BY CONSTRUCTION. The map is module state, so on a server it would be shared by every
+ * concurrent request. Without `window`, `chartCursor()` is the inert controller (null state, no-op
+ * set/subscribe) and no entry is created. The engine never reads a binding during SSR anyway:
+ * `prerender()` renders the scene, and the binding is consumed by `mountChartRenderer` from a layout
+ * effect. Bindings resolve their controller per call, never at compile time.
+ *
+ * TEARDOWN. A group's entry is refcounted by its live `subscribe` registrations; the last
+ * unsubscribe drops it one microtask later (a host re-binding unsubscribes before it resubscribes,
+ * and must not lose the group's state in between). Only `subscribe` creates an entry: `getState` on
+ * a missing group returns `null` and `setState` on one is a no-op.
+ */
+import { createChartCursor, cursorHost } from '@tanstack/charts/cursor'
+import type { ChartCursorController } from '@tanstack/charts/cursor'
+import { resolveChartFocusStrategy } from '@tanstack/charts/cursor/host'
+import type {
+  ChartCursorBinding,
+  ChartFocusStrategy,
+  ChartValue,
+} from '@tanstack/charts/types/core'
+import type { ChartX, CursorResolution } from './types'
+
+type CursorState = ReturnType<ChartCursorController['getState']>
+
+type Entry = { controller: ChartCursorController; subscribers: number }
+
+const groups = new Map<string, Entry>()
+const facades = new Map<string, ChartCursorController>()
+
+const INERT: ChartCursorController = {
+  getState: () => null,
+  setState: () => {},
+  subscribe: () => () => {},
+}
+
+const isServer = (): boolean => typeof window === 'undefined'
+
+/** Drops `key` a microtask after its entry idles: a host re-binding releases before it re-acquires. */
+function sweepWhenIdle<E extends { subscribers: number }>(
+  map: Map<string, E>,
+  key: string,
+  entry: E,
+): void {
+  queueMicrotask(() => {
+    if (entry.subscribers === 0 && map.get(key) === entry) map.delete(key)
+  })
+}
+
+/** Counts a live subscription; the returned release runs `unsubscribe` once, sweeping at zero. */
+function retain<E extends { subscribers: number }>(
+  map: Map<string, E>,
+  key: string,
+  entry: E,
+  unsubscribe: () => void,
+): () => void {
+  entry.subscribers += 1
+  let live = true
+  return () => {
+    if (!live) return
+    live = false
+    unsubscribe()
+    entry.subscribers -= 1
+    if (entry.subscribers === 0) sweepWhenIdle(map, key, entry)
+  }
+}
+
+function ensure(group: string): Entry {
+  let entry = groups.get(group)
+  if (!entry) {
+    entry = { controller: createChartCursor(), subscribers: 0 }
+    groups.set(group, entry)
+  }
+  return entry
+}
+
+const facade = (group: string): ChartCursorController => ({
+  getState: () => groups.get(group)?.controller.getState() ?? null,
+  // No subscriber, no entry: a write to a group nothing listens to would only leak one.
+  setState: (next) => groups.get(group)?.controller.setState(next),
+  subscribe: (listener) => {
+    const entry = ensure(group)
+    return retain(groups, group, entry, entry.controller.subscribe(listener))
+  },
+})
+
+/**
+ * The cursor controller for a group (default `'default'`), for app-side sync — a map timeline that
+ * follows the charts, or drives them:
+ *
+ * ```ts
+ * const cursor = chartCursor()
+ * const state = useSyncExternalStore(cursor.subscribe, cursor.getState, () => null)
+ * ```
+ *
+ * The same object for the same group, so `useSyncExternalStore` never resubscribes per render. On
+ * the server it is inert.
+ */
+export function chartCursor(group = 'default'): ChartCursorController {
+  if (isServer()) return INERT
+  let controller = facades.get(group)
+  if (!controller) {
+    controller = facade(group)
+    facades.set(group, controller)
+  }
+  return controller
+}
+
+/** Test seam: whether a group currently has an entry. */
+export const hasCursorGroup = (group: string): boolean => groups.has(group)
+
+/**
+ * Which chart published a state, keyed by the state OBJECT: TanStack clears only the exact object a
+ * host published, so a stamp must never change its identity. A programmatic state (an app timeline)
+ * has no owner, so every chart treats it as foreign.
+ */
+const owners = new WeakMap<object, string>()
+
+function stamp(state: CursorState, chartId: string): CursorState {
+  if (state) owners.set(state, chartId)
+  return state
+}
+
+export function isForeign(group: string | undefined, chartId: string): boolean {
+  const state = chartCursor(group).getState()
+  return state !== null && owners.get(state) !== chartId
+}
+
+const valueX = (state: CursorState): ChartValue | undefined =>
+  state?.anchor === 'value' ? state.value.x : undefined
+
+/** Snaps a foreign x value onto this chart's own x values; `null` = no snap (exact). */
+function snapper(
+  keys: readonly ChartX[],
+  mode: CursorResolution,
+): ((x: ChartValue) => ChartValue | undefined) | null {
+  const first = keys[0]
+  if (first === undefined || typeof first === 'string') return null
+  const isDate = first instanceof Date
+  const ts = keys
+    .map((k) => (k instanceof Date ? k.getTime() : (k as number)))
+    .toSorted((a, b) => a - b)
+  return (x) => {
+    // Charts whose x value types differ never sync (the 1.x `DomainKind` partition).
+    if (isDate !== x instanceof Date) return undefined
+    if (!isDate && typeof x !== 'number') return undefined
+    if (mode === 'exact') return x
+    const t = x instanceof Date ? x.getTime() : (x as number)
+    let i = ts.findLastIndex((k) => k <= t)
+    if (
+      mode === 'nearest' &&
+      i < ts.length - 1 &&
+      (i < 0 || (ts[i + 1] as number) - t < t - (ts[i] as number))
+    )
+      i += 1
+    const snapped = ts[Math.max(i, 0)] as number
+    if (snapped === t) return x
+    return isDate ? new Date(snapped) : snapped
+  }
+}
+
+type Snap = { snap: ReturnType<typeof snapper>; memo: WeakMap<object, CursorState> }
+type View = { controller: ChartCursorController; config: Snap; subscribers: number }
+
+/** One stable view per mounted chart: TanStack compares the binding's controller by reference and
+ * re-creates the cursor session when it changes, so a fresh object per compile would reset it on
+ * every re-render. Recompiling only swaps the view's snapping config. */
+const views = new Map<string, View>()
+
+function makeView(
+  group: string | undefined,
+  chartId: string,
+  config: () => Snap,
+  track: (unsubscribe: () => void) => () => void = (unsubscribe) => unsubscribe,
+): ChartCursorController {
+  // Resolved per call, never at build time: a definition compiled during SSR holds no controller.
+  const shared = (): ChartCursorController => chartCursor(group)
+  return {
+    subscribe: (listener) => track(shared().subscribe(listener)),
+    setState: (next) =>
+      shared().setState(
+        typeof next === 'function' ? (prev) => stamp(next(prev), chartId) : stamp(next, chartId),
+      ),
+    getState: () => {
+      const state = shared().getState()
+      const x = valueX(state)
+      const { snap, memo } = config()
+      if (!state || !snap || x === undefined) return state
+      const hit = memo.get(state)
+      if (hit !== undefined) return hit
+      const snapped = snap(x)
+      const next = snapped === x ? state : snappedState(state, snapped)
+      memo.set(state, next)
+      return next
+    },
+  }
+}
+
+/** A foreign value of another x type never shows (`undefined`); otherwise a copy at the snap. */
+function snappedState(state: NonNullable<CursorState>, x: ChartValue | undefined): CursorState {
+  if (x === undefined) return null
+  return { ...state, value: { ...state.value, x } }
+}
+
+/**
+ * Each chart's view of its group's controller. Two jobs:
+ *  - stamp what this chart publishes with its id (ownership, above);
+ *  - snap a foreign value onto THIS chart's x values. TanStack matches a shared value exactly, so a
+ *    weekly chart following a daily one would paint an unsnapped rule. State identity is preserved:
+ *    the same object when no snap is needed, one memoized copy otherwise.
+ *
+ * The view object itself is stable per `group` + `chartId` on the client (see `views`); its entry
+ * is dropped a microtask after its last subscription ends, or after its creation if nothing
+ * subscribed by then.
+ */
+export function chartCursorView(
+  group: string | undefined,
+  chartId: string,
+  keys: readonly ChartX[],
+  mode: CursorResolution,
+): ChartCursorController {
+  const config: Snap = { snap: snapper(keys, mode), memo: new WeakMap() }
+  if (isServer()) return makeView(group, chartId, () => config)
+  const id = `${group ?? 'default'}\u0000${chartId}`
+  const existing = views.get(id)
+  if (existing) {
+    existing.config = config
+    return existing.controller
+  }
+  const view: View = { controller: INERT, config, subscribers: 0 }
+  view.controller = makeView(
+    group,
+    chartId,
+    () => view.config,
+    (unsubscribe) => retain(views, id, view, unsubscribe),
+  )
+  views.set(id, view)
+  // Swept unless subscribed by then — a chart rendering a `state` placeholder compiles a view it
+  // never mounts, and must not leave a permanent entry.
+  sweepWhenIdle(views, id, view)
+  return view.controller
+}
+
+/**
+ * Source-only tooltips. A 1.1.0 host shows a tooltip (and its `role="status"` live region) exactly
+ * when it resolves a focus point, and it resolves a shared cursor's point through the definition's
+ * focus strategy. Wrapping `group-x` so it groups nothing while a FOREIGN state is current leaves a
+ * follower with the crosshair (painted from the cursor presentation, not from focus) and nothing
+ * else.
+ */
+export function sourceOnlyFocus(group: string | undefined, chartId: string): ChartFocusStrategy {
+  const base = resolveChartFocusStrategy<unknown, ChartValue, ChartValue>('group-x')
+  if (!base) throw new Error('[basalt] charts: the group-x focus strategy is missing')
+  return {
+    resolve: (points, context) => base.resolve(points, context),
+    navigation: (points) => base.navigation(points),
+    group: (points, context) => (isForeign(group, chartId) ? [] : base.group(points, context)),
+  }
+}
+
+export function cursorBinding(opts: {
+  group: string | undefined
+  chartId: string
+  keys: readonly ChartX[]
+  mode: CursorResolution
+  /** Activation pins and unpins the cursor — on for a coarse pointer (§ 9.6: tap to pin). */
+  pin: boolean
+}): ChartCursorBinding {
+  return {
+    use: cursorHost,
+    controller: chartCursorView(opts.group, opts.chartId, opts.keys, opts.mode),
+    mode: 'focus',
+    match: 'x',
+    pin: opts.pin,
+  }
+}
+
+/** Test seam: whether a chart's view entry exists. */
+export const hasCursorView = (group: string | undefined, chartId: string): boolean =>
+  views.has(`${group ?? 'default'}\u0000${chartId}`)

package/src/charts/curves.ts

@@ -0,0 +1,111 @@
+/**
+ * `ChartSeries.curve` → TanStack's `ChartCurve` contract. Written here rather than bridged through
+ * `@tanstack/charts/d3/shape`: that bridge takes a `d3-shape` curve factory, and `d3-shape` is not
+ * resolvable from basalt under an isolated linker (the engine depends on it, basalt would have to
+ * add a third peer for five interpolations). The algorithms are d3's own: `monotone` is
+ * `curveMonotoneX` (Steffen), the steps are `curveStep` / `curveStepAfter` / `curveStepBefore`.
+ */
+import type { ChartCurve } from '@tanstack/charts/types/core'
+
+type Point = readonly [number, number]
+
+export type CurveName = 'monotone' | 'linear' | 'step' | 'stepAfter' | 'stepBefore'
+
+const fmt = (n: number): string => String(Math.round(n * 1000) / 1000)
+const at = (p: Point): string => `${fmt(p[0])},${fmt(p[1])}`
+
+function linear(points: readonly Point[]): string {
+  return points.map((p, i) => `${i === 0 ? 'M' : 'L'}${at(p)}`).join('')
+}
+
+/** `t` is where between two samples the value changes: 0 = before, 0.5 = midpoint, 1 = after. */
+function step(points: readonly Point[], t: number): string {
+  const first = points[0]
+  if (!first) return ''
+  let d = `M${at(first)}`
+  for (let i = 1; i < points.length; i++) {
+    const [x0, y0] = points[i - 1] as Point
+    const [x1, y1] = points[i] as Point
+    const xm = x0 * (1 - t) + x1 * t
+    d += `L${fmt(xm)},${fmt(y0)}L${fmt(xm)},${fmt(y1)}`
+    if (xm !== x1) d += `L${at([x1, y1])}`
+  }
+  return d
+}
+
+const sign = (n: number): number => (n < 0 ? -1 : 1)
+
+/** d3's `slope3`: the tangent at an interior point, limited so the curve never overshoots. */
+function interiorTangent(p0: Point, p1: Point, p2: Point): number {
+  const h0 = p1[0] - p0[0]
+  const h1 = p2[0] - p1[0]
+  const s0 = (p1[1] - p0[1]) / (h0 || (h1 < 0 ? -0 : 0))
+  const s1 = (p2[1] - p1[1]) / (h1 || (h0 < 0 ? -0 : 0))
+  const p = (s0 * h1 + s1 * h0) / (h0 + h1)
+  return (sign(s0) + sign(s1)) * Math.min(Math.abs(s0), Math.abs(s1), 0.5 * Math.abs(p)) || 0
+}
+
+/** d3's `slope2`: an end tangent from the one next to it. */
+function endTangent(a: Point, b: Point, t: number): number {
+  const h = b[0] - a[0]
+  return h ? ((3 * (b[1] - a[1])) / h - t) / 2 : t
+}
+
+function monotone(points: readonly Point[]): string {
+  if (points.length < 3) return linear(points)
+  const n = points.length
+  const t: number[] = Array.from({ length: n }, () => 0)
+  for (let i = 1; i < n - 1; i++)
+    t[i] = interiorTangent(points[i - 1] as Point, points[i] as Point, points[i + 1] as Point)
+  t[0] = endTangent(points[0] as Point, points[1] as Point, t[1] as number)
+  t[n - 1] = endTangent(points[n - 2] as Point, points[n - 1] as Point, t[n - 2] as number)
+  let d = `M${at(points[0] as Point)}`
+  for (let i = 1; i < n; i++) {
+    const [x0, y0] = points[i - 1] as Point
+    const [x1, y1] = points[i] as Point
+    const dx = (x1 - x0) / 3
+    const c1: Point = [x0 + dx, y0 + dx * (t[i - 1] as number)]
+    const c2: Point = [x1 - dx, y1 - dx * (t[i] as number)]
+    d += `C${at(c1)},${at(c2)},${at([x1, y1])}`
+  }
+  return d
+}
+
+function pathFor(name: CurveName, points: readonly Point[], reversed: boolean): string {
+  switch (name) {
+    case 'linear':
+      return linear(points)
+    case 'monotone':
+      return monotone(points)
+    case 'step':
+      return step(points, 0.5)
+    // A reversed baseline walks right-to-left, so "after" becomes "before" (d3 flips `t` there).
+    case 'stepAfter':
+      return step(points, reversed ? 0 : 1)
+    case 'stepBefore':
+      return step(points, reversed ? 1 : 0)
+    default:
+      // Exhaustive at compile time; a JS caller's unknown name draws straight segments, never the
+      // name itself as path data.
+      void (name satisfies never)
+      return linear(points)
+  }
+}
+
+const CACHE = new Map<CurveName, ChartCurve>()
+
+/** The engine curve for a series curve name. `linear` maps to the engine's own straight default. */
+export function chartCurve(name: CurveName): ChartCurve {
+  const hit = CACHE.get(name)
+  if (hit) return hit
+  const curve: ChartCurve = {
+    line: (points) => pathFor(name, points, false),
+    area: (top, bottom) => {
+      if (top.length === 0) return ''
+      const back = pathFor(name, bottom.toReversed(), true).replace(/^M/, 'L')
+      return `${pathFor(name, top, false)}${back}Z`
+    },
+  }
+  CACHE.set(name, curve)
+  return curve
+}

package/src/charts/donut.module.css

@@ -0,0 +1,54 @@
+/*
+ * Donut layout, by the donut's own inline size (docs/V2-SPEC.md § 9.6, W10 SSR contract): the legend
+ * stacks under the ring below 480px and sits beside it from 480px. In CSS, so the server HTML is the
+ * hydrated layout. The literal is CONTAINER_CLASSES.regular (`breakpoint-literals.test.ts`).
+ */
+
+.row {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  min-width: 0;
+}
+
+/* The ring is the sized element (its chart box fills it): the stated height per container class
+ * when stacked, a square when beside the legend. One resolution, so a responsive `height` cannot
+ * make the ring and its box disagree. */
+.ring {
+  position: relative;
+  min-width: 0;
+  height: var(--bc-micro);
+}
+
+@container (min-width: 240px) {
+  .ring {
+    height: var(--bc-compact);
+  }
+}
+
+@media (pointer: coarse) {
+  .ring {
+    max-height: 45svh;
+  }
+}
+
+@container (min-width: 480px) {
+  .row {
+    flex-direction: row;
+    align-items: center;
+  }
+
+  /* At most 55% of the row wide, and square. */
+  .ring {
+    flex: 0 0 min(var(--bc-regular), 55cqw);
+    height: auto;
+    max-height: none;
+    aspect-ratio: 1;
+  }
+}
+
+@container (min-width: 800px) {
+  .ring {
+    flex-basis: min(var(--bc-wide), 55cqw);
+  }
+}

package/src/charts/donut.module.css.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly row: string
+  readonly ring: string
+}
+export default classes

package/src/charts/host.tsx

@@ -0,0 +1,60 @@
+/**
+ * The bare engine mount — the ONLY module that imports `@tanstack/charts/react`
+ * (`basalt/chart-host-single`). It knows a compiled definition, a size and an accessible name, and
+ * nothing about legends, placeholders or cards (`docs/V2-SPEC.md` § 9.2).
+ *
+ * The engine is never given a height: it fills a CSS-owned {@link ChartBox} and measures it, so the
+ * box is final in the server HTML and hydration only redraws the svg inside it (W10).
+ */
+import { Chart } from '@tanstack/charts/react'
+import type { CSSProperties, ReactElement } from 'react'
+import type { CartesianDefinition } from './compile'
+import { ChartBox } from './box'
+import type { ChartBoxHeight } from './box'
+import { INITIAL_WIDTH } from './sizing'
+
+export type ChartEngineProps = {
+  definition: CartesianDefinition
+  ariaLabel: string
+  /** The box height: the law when omitted, a number when fixed (see {@link ChartBoxHeight}). */
+  height?: ChartBoxHeight
+  /** Scopes the SVG resources (clip paths, gradients) — the chart's `useId`, sanitized. */
+  idPrefix: string
+  /** `touch-action: pan-y`: a vertical swipe across the chart still scrolls the page. */
+  coarse: boolean
+}
+
+/** `currentColor` is the axis ink. The font is pinned to mono (the 1.x tick look) and inherited by
+ * the svg — TanStack measures guides with the host's computed font. */
+const HOST_STYLE: CSSProperties = {
+  // Overrides the host's own fallback height: the box decides, the engine measures it.
+  height: '100%',
+  color: 'var(--vx-axis)',
+  fontFamily: 'var(--basalt-font-mono)',
+}
+const COARSE_STYLE: CSSProperties = { ...HOST_STYLE, touchAction: 'pan-y' }
+
+export function ChartEngine({
+  definition,
+  ariaLabel,
+  height,
+  idPrefix,
+  coarse,
+}: ChartEngineProps): ReactElement {
+  return (
+    <ChartBox height={height}>
+      <Chart
+        definition={definition}
+        ariaLabel={ariaLabel}
+        initialWidth={INITIAL_WIDTH}
+        idPrefix={idPrefix}
+        className="basalt-chart"
+        style={coarse ? COARSE_STYLE : HOST_STYLE}
+      />
+    </ChartBox>
+  )
+}
+
+/** Scopes the engine's SVG resource ids per chart instance (`useId` output carries colons). */
+export const idPrefixOf = (id: string, prefix = 'chart'): string =>
+  `basalt-${prefix}-${id.replaceAll(/[^\w-]/g, '')}`