basalt-ui 1.13.0 → 1.15.0

package/src/charts/cursor/store.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test'
+import { createCursorStore, globalCursorStore } from './store'
+
+describe('cursor store', () => {
+  test('notifies subscribers on change', () => {
+    const store = createCursorStore()
+    let calls = 0
+    const unsubscribe = store.subscribe(() => {
+      calls++
+    })
+
+    store.set('2026-08-18', 'chart-a')
+    expect(calls).toBe(1)
+    expect(store.get()).toEqual({ key: '2026-08-18', source: 'chart-a' })
+
+    unsubscribe()
+    store.set('2026-08-19', 'chart-a')
+    expect(calls).toBe(1)
+  })
+
+  test('a redundant set does not notify — a re-hover of the same point costs no render', () => {
+    const store = createCursorStore()
+    let calls = 0
+    store.subscribe(() => {
+      calls++
+    })
+
+    store.set('2026-08-18', 'chart-a')
+    store.set('2026-08-18', 'chart-a')
+    expect(calls).toBe(1)
+  })
+
+  test('clearing returns the stable empty identity', () => {
+    const store = createCursorStore()
+    const before = store.get()
+    store.set('2026-08-18', 'chart-a')
+    store.set(null, null)
+    expect(store.get()).toBe(before)
+  })
+
+  test('scoped stores are independent of the global one', () => {
+    const scoped = createCursorStore()
+    scoped.set('2026-08-18', 'chart-a')
+    expect(globalCursorStore.get().key).toBeNull()
+  })
+})

package/src/charts/cursor/store.ts

@@ -0,0 +1,53 @@
+/**
+ * The shared chart cursor — an external store, not a React context value.
+ *
+ * Sharing used to require a `ChartHoverSync` ancestor, so it was opt-in and silently absent
+ * whenever someone forgot the wrapper. This inverts that: a module-level store means every
+ * chart on the page shares a cursor by default, and `ChartCursorScope` exists to ISOLATE a
+ * subtree (`docs/CHARTS-SPEC.md` §3). Charts with non-overlapping domains never resolve each
+ * other's keys, so "shared by default" cannot produce a false cursor.
+ *
+ * External store rather than context for a second reason: a cursor move re-renders only the
+ * charts subscribed to it, instead of every descendant of a provider whose value object is new
+ * on each pointer frame.
+ */
+
+/** Broadcast cursor position: an opaque domain key plus the chart that owns it. */
+export type CursorState = {
+  /** The hovered x-domain key (a date/category string), or null when nothing is hovered. */
+  key: string | null
+  /** `chartId` of the chart the pointer is actually over — the one that owns the tooltip. */
+  source: string | null
+}
+
+export type CursorStore = {
+  get: () => CursorState
+  set: (key: string | null, source: string | null) => void
+  subscribe: (onChange: () => void) => () => void
+}
+
+/** Stable identity for "nothing hovered" — also the SSR snapshot, so it must never be recreated. */
+export const EMPTY_CURSOR: CursorState = { key: null, source: null }
+
+export function createCursorStore(): CursorStore {
+  let state: CursorState = EMPTY_CURSOR
+  const listeners = new Set<() => void>()
+
+  return {
+    get: () => state,
+    set: (key, source) => {
+      if (state.key === key && state.source === source) return
+      state = key === null && source === null ? EMPTY_CURSOR : { key, source }
+      for (const listener of listeners) listener()
+    },
+    subscribe: (onChange) => {
+      listeners.add(onChange)
+      return () => {
+        listeners.delete(onChange)
+      }
+    },
+  }
+}
+
+/** The default store every chart shares unless a `ChartCursorScope` overrides it. */
+export const globalCursorStore: CursorStore = createCursorStore()

package/src/charts/hooks/useChartCursor.ts

@@ -0,0 +1,163 @@
+import { localPoint } from '@visx/event'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type { KeyboardEvent, PointerEvent } from 'react'
+import { buildDomainIndex, resolveCursorPoint } from '../cursor/resolve'
+import { useCursorState, useCursorStore } from '../cursor/scope'
+
+/** Viewport-space pointer anchor the tooltip positions against. */
+export type CursorAnchor = { x: number; y: number }
+
+export type ChartCursor<T> = {
+  /** The point this chart paints its crosshair + dots at — own hover, or a resolved sibling key. */
+  point: T | null
+  /** True when the pointer is over THIS chart. Only the source chart shows the floating tooltip. */
+  isSource: boolean
+  /** Latest pointer position in viewport coords, or null when not hovered. */
+  anchor: CursorAnchor | null
+  onPointerMove: (event: PointerEvent<SVGRectElement>) => void
+  onPointerLeave: () => void
+  onKeyDown: (event: KeyboardEvent<SVGRectElement>) => void
+  onBlur: () => void
+}
+
+/**
+ * Wires a chart into the ambient cursor store: snaps the pointer to the nearest own point,
+ * broadcasts it, and reads back a sibling's broadcast through domain-aware resolution. Replaces
+ * the removed `useHoverSync` + `useChartTooltip` pair, including their `resolveKey` escape hatch —
+ * resolution is now automatic.
+ *
+ * The tooltip anchor is coalesced through `requestAnimationFrame`, so a fast scrub costs one local
+ * state write per frame instead of one per event. The BROADCAST is not rAF-gated — it is deduped
+ * instead (the store ignores a set that doesn't change the value), so a scrub within one x-bucket
+ * costs nothing while a real bucket change reaches siblings on the same tick rather than a frame
+ * late.
+ */
+export function useChartCursor<T>({
+  data,
+  chartId,
+  getKey,
+  xScale,
+  marginLeft,
+}: {
+  data: readonly T[]
+  chartId: string
+  getKey: (d: T) => string
+  /** Own x scale — maps a domain key to a plot-local x offset. */
+  xScale: (key: string) => number | undefined
+  marginLeft: number
+}): ChartCursor<T> {
+  const store = useCursorStore()
+  const cursor = useCursorState()
+  const [anchor, setAnchor] = useState<CursorAnchor | null>(null)
+
+  // Accessors read through refs so the pointer callbacks stay referentially stable: the natural
+  // call style is an inline arrow, fresh every render, and re-creating these would re-bind the
+  // overlay's listeners on every cursor frame in every sibling chart.
+  const getKeyRef = useRef(getKey)
+  getKeyRef.current = getKey
+  const xScaleRef = useRef(xScale)
+  xScaleRef.current = xScale
+
+  const index = useMemo(() => buildDomainIndex(data, getKeyRef.current), [data])
+
+  const frameRef = useRef<number | null>(null)
+  const pendingRef = useRef<CursorAnchor | null>(null)
+  useEffect(
+    () => () => {
+      if (frameRef.current !== null) cancelAnimationFrame(frameRef.current)
+      // Release the shared cursor if this chart still owns it. Unmounting while hovered (a filter
+      // drops the chart, a tab switches) fires no leave/blur, so the store would keep pointing at
+      // a dead chartId — and any sibling whose domain resolves that stale key would paint a ghost
+      // crosshair with no way to clear it. Same ownership guard as `clear()`.
+      if (store.get().source === chartId) store.set(null, null)
+    },
+    [store, chartId],
+  )
+
+  const scheduleAnchor = useCallback((next: CursorAnchor) => {
+    pendingRef.current = next
+    if (frameRef.current !== null) return
+    frameRef.current = requestAnimationFrame(() => {
+      frameRef.current = null
+      setAnchor(pendingRef.current)
+    })
+  }, [])
+
+  const onPointerMove = useCallback(
+    (event: PointerEvent<SVGRectElement>) => {
+      if (data.length === 0) return
+      // Explicit reference node: `localPoint(event)` resolves it from `event.target`, which is the
+      // overlay rect only while the overlay is genuinely the topmost hit element. Passing
+      // `currentTarget` pins the coordinate space to the overlay regardless of what a kind draws
+      // above it.
+      const local = localPoint(event.currentTarget, event.nativeEvent)
+      if (local === null) return
+      const px = local.x - marginLeft
+
+      let closest = data[0] as T
+      let minDist = Infinity
+      for (const d of data) {
+        const x = xScaleRef.current(getKeyRef.current(d)) ?? 0
+        const dist = Math.abs(x - px)
+        if (dist < minDist) {
+          minDist = dist
+          closest = d
+        }
+      }
+
+      scheduleAnchor({ x: event.clientX, y: event.clientY })
+      store.set(getKeyRef.current(closest), chartId)
+    },
+    [data, marginLeft, chartId, store, scheduleAnchor],
+  )
+
+  const clear = useCallback(() => {
+    if (frameRef.current !== null) {
+      cancelAnimationFrame(frameRef.current)
+      frameRef.current = null
+    }
+    pendingRef.current = null
+    setAnchor(null)
+    // Only clear the SHARED cursor if this chart still owns it: moving fast from chart A to B lets
+    // A's leave fire after B's move, and an unconditional clear would wipe B's cursor.
+    if (store.get().source === chartId) store.set(null, null)
+  }, [store, chartId])
+
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<SVGRectElement>) => {
+      if (data.length === 0) return
+      if (event.key === 'Escape') {
+        clear()
+        return
+      }
+      const delta = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0
+      if (delta === 0) return
+      event.preventDefault()
+
+      const current = store.get().key
+      const currentIndex = data.findIndex((d) => getKeyRef.current(d) === current)
+      const nextIndex = Math.min(
+        Math.max((currentIndex === -1 ? (delta > 0 ? -1 : data.length) : currentIndex) + delta, 0),
+        data.length - 1,
+      )
+      const next = data[nextIndex] as T
+      const rect = event.currentTarget.getBoundingClientRect()
+      const x = xScaleRef.current(getKeyRef.current(next)) ?? 0
+      scheduleAnchor({ x: rect.left + x, y: rect.top })
+      store.set(getKeyRef.current(next), chartId)
+    },
+    [data, store, chartId, clear, scheduleAnchor],
+  )
+
+  const point = cursor.key === null ? null : resolveCursorPoint(index, cursor.key)
+
+  return {
+    point,
+    isSource: cursor.source === chartId,
+    anchor,
+    onPointerMove,
+    onPointerLeave: clear,
+    onKeyDown,
+    onBlur: clear,
+  }
+}

package/src/charts/hooks/useChartSize.ts

@@ -15,12 +15,16 @@ export type UseChartSizeResult = ChartSize & {
  * A thin basalt wrapper over `@visx/responsive`'s `useParentSize` — keeps the
  * `@visx/*` import inside `src/charts/**` per the Mantine-free boundary rule.
  *
+ * Charts do not call this directly — `ChartFrame` (and `CartesianChart` above it) measure for
+ * them, including the legend band. Reach for it when something OUTSIDE the chart system needs a
+ * measured box, e.g. sizing a sparkline to its table cell.
+ *
  * @example
- * function MyChart() {
- *   const { ref, width, height } = useChartSize()
+ * function CellSparkline({ points }: { points: number[] }) {
+ *   const { ref, width } = useChartSize()
  *   return (
- *     <div ref={ref} style={{ width: '100%', height: 240 }}>
- *       {width > 0 && <Bars width={width} height={height} ... />}
+ *     <div ref={ref} style={{ width: '100%', height: 24 }}>
+ *       {width > 0 && <LineSparkline data={points} width={width} height={24} />}
  *     </div>
  *   )
  * }

package/src/charts/index.ts

@@ -2,8 +2,9 @@
  * `./charts` — Mantine-free visx chart system (ZERO `@mantine/*` imports, lint-enforced).
  *
  * Re-exports the framework token layer (so chart consumers have one import surface), the chart
- * theme context, the shared-cursor hover context, the primitives, kinds, sparklines, hooks, utils,
- * and a curated set of raw @visx primitives for bespoke charts.
+ * theme context, the shared cursor (module-level store — charts sync with no provider; see
+ * `docs/CHARTS-SPEC.md` §3), the primitives, kinds, sparklines, hooks, utils, and a curated set of
+ * raw @visx primitives for bespoke charts.
  *
  * The framework ships ONLY generic primitives + framework palette data — no domain series tree
  * (apps rebuild that app-side with `seriesTokens` / `groupTokens` against their own series maps).
@@ -20,15 +21,22 @@ export {
   seriesTokens,
   defineSeries,
   groupTokens,
+  chartMargin,
+  type ChartMargin,
 } from '../tokens'
 
 // ── Design seam type (type-only; erased at runtime — no @mantine value) ─
 export type { SeriesKey } from '../register'
 
-// ── Chart theme + hover context ──────────────────────────────────────────
+// ── Chart theme + shared cursor ──────────────────────────────────────────
 export { VxThemeProvider, useVxTheme, type VxTheme } from './theme'
-export { HoverContext, DEFAULT_NO_OP_SET_HOVER, type HoverCtx } from './hover-context'
-export { ChartHoverSync, type ChartHoverSyncProps } from './hover-sync'
+export { ChartCursorScope, type ChartCursorScopeProps, useCursorState } from './cursor/scope'
+export {
+  createCursorStore,
+  globalCursorStore,
+  type CursorState,
+  type CursorStore,
+} from './cursor/store'
 
 // ── Series descriptor (the legend/tooltip single source of truth) ────────
 export {
@@ -44,8 +52,21 @@ export {
 } from './series'
 
 // ── Primitives ───────────────────────────────────────────────────────────
-export { ResponsiveChart, type ResponsiveChartProps } from './primitives/ResponsiveChart'
-export { ChartFrame, type ChartFrameProps, type ChartFrameLegend } from './primitives/ChartFrame'
+export {
+  CartesianChart,
+  resolveAxisDomain,
+  type CartesianChartProps,
+  type CartesianTooltipConfig,
+  type AxisConfig,
+  type PlotContext,
+} from './primitives/CartesianChart'
+export {
+  ChartFrame,
+  type ChartFrameProps,
+  type ChartFrameLegend,
+  type PlotRect,
+  resolveLegend,
+} from './primitives/ChartFrame'
 export {
   ChartCenter,
   type ChartCenterProps,
@@ -56,25 +77,26 @@ export { Crosshair, SeriesDot } from './primitives/Crosshair'
 export { ChartCard } from './primitives/ChartCard'
 export { ChartLegend, type LegendEntry } from './primitives/ChartLegend'
 export {
-  ChartTooltip,
+  ChartTooltipFloat,
   TooltipHeader,
   TooltipRow,
   TooltipBody,
-  useTooltipStyles,
 } from './primitives/ChartTooltip'
 export { AxisBottomDate, AxisLeftNumeric, AxisRightNumeric } from './primitives/Axes'
 export { HoverOverlay } from './primitives/HoverOverlay'
 export { ZoneRects, type ZoneSpec } from './primitives/ZoneRects'
+export { XZoneRects, type XZoneSpec } from './primitives/XZoneRects'
 export { AreaGradient, areaFillUrl } from './primitives/AreaGradient'
 
 // ── Hooks ────────────────────────────────────────────────────────────────
-export { useChartTooltip, type TooltipState } from './hooks/useChartTooltip'
-export { useHoverSync } from './hooks/useHoverSync'
+export { useChartCursor, type ChartCursor, type CursorAnchor } from './hooks/useChartCursor'
 export { useChartSize, type UseChartSizeResult, type ChartSize } from './hooks/useChartSize'
 
 // ── Utils ────────────────────────────────────────────────────────────────
 export { fmtAxisDate, fmtTooltipDate } from './utils/format'
-export { smartTicks } from './utils/ticks'
+export { smartTicks, smartTicksEvery } from './utils/ticks'
+export { autoMargin, probeAxisLabels, type AutoMarginInput } from './layout/auto-margin'
+export { measureText, maxTextWidth } from './utils/measure-text'
 
 // ── Kind components (owned by a sibling agent under ./kinds) ──────────────
 export {
@@ -83,7 +105,6 @@ export {
   type ZonedLineZone,
   type ZonedLineThreshold,
   type ZonedLineRefLine,
-  type ZonedLineTooltipLabel,
 } from './kinds/ZonedLine'
 
 export {
@@ -93,7 +114,6 @@ export {
   type BarsLine,
   type BarsZone,
   type BarsRefLine,
-  type BarsAxisConfig,
 } from './kinds/Bars'
 
 export { StackedArea, type StackedAreaProps } from './kinds/StackedArea'