basalt-ui 1.41.0 → 2.0.0

package/src/charts/cursor/resolve.ts

@@ -1,198 +0,0 @@
-/**
- * Domain-aware resolution of a BROADCAST cursor key against a chart's own points.
- *
- * The layer this replaced matched keys byte-for-byte, so two charts shared a cursor only if they emitted identical
- * strings. A chart that folded its domain to fit a narrow viewport stopped owning most of the keys
- * its siblings broadcast, and the shared crosshair then landed on roughly one hover in three with
- * no rule a reader could infer — patched per chart by a manual `resolveKey`. Resolving on the
- * PARSED domain instead makes that automatic (`docs/CHARTS-SPEC.md` §3).
- */
-
-/** Numeric-string test — shared by `parseKey` and `classifyDomain` so a key can never be numeric
- * to one and not the other. */
-function isNumericString(key: string): boolean {
-  return /^[-+]?\d*\.?\d+$/.test(key) && Number.isFinite(Number(key))
-}
-
-/** `Date.parse`-able test — shared by `parseKey` and `classifyDomain`, same reason. */
-function isDateParseableString(key: string): boolean {
-  return !Number.isNaN(Date.parse(key))
-}
-
-/**
- * A key as a comparable number: numeric-looking strings as numbers, everything else as a date.
- * Neither (a plain category like "Direct") → null, which degrades to exact-match only — correct,
- * since "nearest category" is meaningless.
- */
-export function parseKey(key: string): number | null {
-  if (isNumericString(key)) return Number(key)
-  return isDateParseableString(key) ? Date.parse(key) : null
-}
-
-/** The x-domain families the shared cursor partitions on, derived from a chart's own keys — never
- * a prop, never `ChartCursorScope`. A chart's kind is stamped on every broadcast it makes, and a
- * receiving chart ignores any broadcast whose kind differs from its own — so a category chart can
- * never be mistaken for a time chart just because both domains happen to parse. */
-export type DomainKind = 'time' | 'linear' | 'band'
-
-/**
- * Classify a domain by the SAME parse precedence `parseKey` applies to each key, so a domain can
- * never be classified one way and resolved another:
- *
- * - empty domain → `'band'` (nothing to share).
- * - every key numeric (same test `parseKey` tries first) → `'linear'`.
- * - otherwise every key `Date.parse`-able (same test `parseKey` falls back to) → `'time'`.
- * - otherwise → `'band'` (categories, or a mixed domain).
- *
- * Ordering matters and mirrors `parseKey` exactly: a domain of bare years like `"2026"` is numeric
- * FIRST, so it classifies `'linear'`, not `'time'`, even though every value is also a valid date.
- */
-export function classifyDomain(keys: readonly string[]): DomainKind {
-  if (keys.length === 0) return 'band'
-  if (keys.every(isNumericString)) return 'linear'
-  if (keys.every(isDateParseableString)) return 'time'
-  return 'band'
-}
-
-/**
- * How a foreign key maps onto a chart's own points.
- *
- * `'nearest'` (default) treats every key as a POINT — the foreign key resolves to whichever own
- * point sits closest to it. Correct when a chart's x-domain is a set of instants.
- *
- * `'leading'` treats every key as the LEADING EDGE of a bucket covering `[key, nextKey)` — the
- * foreign key resolves to the LAST own key `<=` it. Use this when a chart's keys are bucket
- * starts (a weekly series keyed by the Monday of each week, a monthly series keyed by the 1st):
- * under `'nearest'`, a target landing in the back half of a bucket resolves to the FOLLOWING
- * bucket instead of the one it's actually inside, and the shared crosshair lands one column off
- * for every back-half hover.
- *
- * The two modes differ at the DOMAIN EDGES too, and deliberately: `'nearest'` tolerates one step
- * past each end (the target is an instant, so the closest point is still a defensible answer),
- * while `'leading'` bounds strictly to `[first, last + step)` — outside that range no bucket
- * CONTAINS the key, and answering with the nearest one would paint a crosshair on a bucket that
- * provably excludes it.
- */
-export type CursorResolution = 'nearest' | 'leading'
-
-export type DomainIndex<T> = {
-  byKey: Map<string, T>
-  /** Parsed positions, ascending. Empty when the domain isn't parseable. */
-  values: number[]
-  /** Points parallel to `values`. */
-  points: T[]
-  /** Median spacing — the tolerance within which a foreign key still resolves. */
-  step: number
-  /** The resolution strategy this index was built for. */
-  resolution: CursorResolution
-}
-
-/** Build the lookup structure once per `data` identity. */
-export function buildDomainIndex<T>(
-  data: readonly T[],
-  getKey: (d: T) => string,
-  resolution: CursorResolution = 'nearest',
-): DomainIndex<T> {
-  const byKey = new Map<string, T>()
-  const parsed: { value: number; point: T }[] = []
-  let parseable = true
-
-  for (const d of data) {
-    byKey.set(getKey(d), d)
-    if (!parseable) continue
-    const value = parseKey(getKey(d))
-    if (value === null) parseable = false
-    else parsed.push({ value, point: d })
-  }
-
-  // Under two parseable points there is no step to reason about, so nearest-match would be
-  // unbounded — fall back to exact match.
-  if (!parseable || parsed.length < 2) {
-    return { byKey, values: [], points: [], step: 0, resolution }
-  }
-
-  parsed.sort((a, b) => a.value - b.value)
-  const values = parsed.map((p) => p.value)
-  const points = parsed.map((p) => p.point)
-
-  const diffs: number[] = []
-  for (let i = 1; i < values.length; i++) {
-    diffs.push((values[i] as number) - (values[i - 1] as number))
-  }
-  diffs.sort((a, b) => a - b)
-
-  return { byKey, values, points, step: diffs[Math.floor(diffs.length / 2)] ?? 0, resolution }
-}
-
-/** `'leading'` resolution: the last own position `<= target`. The caller has already rejected
- * anything outside `[first, last + step)`, so a containing bucket is guaranteed to exist. */
-function resolveLeading<T>(index: DomainIndex<T>, target: number): T {
-  let lo = 0
-  let hi = index.values.length - 1
-  let result = 0
-  while (lo <= hi) {
-    const mid = (lo + hi) >> 1
-    if ((index.values[mid] as number) <= target) {
-      result = mid
-      lo = mid + 1
-    } else {
-      hi = mid - 1
-    }
-  }
-  return index.points[result] as T
-}
-
-/**
- * The own point a broadcast `key` maps to: exact match first, else — per `index.resolution` — the
- * nearest parsed position or the last position at/before the target, both within one domain step.
- * Out of range → null, so charts over unrelated domains never paint a cursor for each other —
- * which is what makes "shared by default" safe. A categorical (unparseable) domain falls back to
- * exact-match-only in BOTH resolutions, since "nearest"/"leading" over a category is meaningless.
- */
-export function resolveCursorPoint<T>(
-  index: DomainIndex<T>,
-  key: string,
-  resolution: CursorResolution = index.resolution,
-): T | null {
-  const exact = index.byKey.get(key)
-  if (exact !== undefined) return exact
-
-  const target = parseKey(key)
-  if (target === null || index.values.length === 0) return null
-
-  const first = index.values[0] as number
-  const last = index.values[index.values.length - 1] as number
-
-  if (resolution === 'leading') {
-    // Containment, NOT tolerance. A bucket keyed `k` covers `[k, nextKey)`, so a target before the
-    // first key sits in no bucket at all, and `last + step` is the first instant past the final
-    // one. Borrowing `'nearest'`'s symmetric ±step window here would snap a pre-domain target onto
-    // the first bucket and a post-domain one onto the last — painting a crosshair on a bucket that
-    // provably does not contain the hovered key, which is the exact lie this mode exists to remove.
-    if (target < first || target >= last + index.step) return null
-    return resolveLeading(index, target)
-  }
-
-  if (target < first - index.step || target > last + index.step) return null
-
-  let lo = 0
-  let hi = index.values.length - 1
-  while (lo < hi) {
-    const mid = (lo + hi) >> 1
-    if ((index.values[mid] as number) < target) lo = mid + 1
-    else hi = mid
-  }
-
-  let best = lo
-  let bestDist = Math.abs((index.values[lo] as number) - target)
-  if (lo > 0) {
-    const prevDist = Math.abs((index.values[lo - 1] as number) - target)
-    // `<=`, not `<`: a key landing exactly between two own points belongs to the EARLIER one —
-    // the folded bucket that swallowed it starts there, so ties resolve backwards, consistently.
-    if (prevDist <= bestDist) {
-      best = lo - 1
-      bestDist = prevDist
-    }
-  }
-  return bestDist <= index.step ? (index.points[best] as T) : null
-}

package/src/charts/cursor/scope.tsx

@@ -1,35 +0,0 @@
-import { createContext, useContext, useMemo, useSyncExternalStore } from 'react'
-import type { ReactNode } from 'react'
-import type { CursorState, CursorStore } from './store'
-import { createCursorStore, EMPTY_CURSOR, globalCursorStore } from './store'
-
-const CursorStoreContext = createContext<CursorStore>(globalCursorStore)
-
-export type ChartCursorScopeProps = {
-  children: ReactNode
-}
-
-/**
- * ISOLATES its subtree onto a private cursor store — the inverse of the removed `ChartHoverSync`, which
- * had to be mounted to enable sharing at all. Charts share a cursor by default now, AND the shared
- * cursor partitions automatically by x-domain kind (`DomainKind`, derived from each chart's own
- * data in `useChartCursor`) — a categorical chart never follows a date chart just because both
- * happen to be on the page, with nothing to configure. `ChartCursorScope` is no longer the tool for
- * that case. What it is still for: isolating two charts that share the same domain KIND but are
- * semantically unrelated — two different tenants' date ranges rendered side by side on one page.
- */
-export function ChartCursorScope({ children }: ChartCursorScopeProps) {
-  const store = useMemo(() => createCursorStore(), [])
-  return <CursorStoreContext.Provider value={store}>{children}</CursorStoreContext.Provider>
-}
-
-/** The cursor store this chart belongs to — the nearest `ChartCursorScope`, else the global one. */
-export function useCursorStore(): CursorStore {
-  return useContext(CursorStoreContext)
-}
-
-/** Subscribe to the ambient cursor. Re-renders only on an actual cursor change. */
-export function useCursorState(): CursorState {
-  const store = useCursorStore()
-  return useSyncExternalStore(store.subscribe, store.get, () => EMPTY_CURSOR)
-}

package/src/charts/cursor/store.ts

@@ -1,58 +0,0 @@
-/**
- * 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.
- */
-
-import type { DomainKind } from './resolve'
-
-/** 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
-  /** The broadcaster's own x-domain kind. `null` only in the empty state — the store itself does
-   * not police this, it just carries it; the partition is enforced by the reading hook. */
-  kind: DomainKind | null
-}
-
-export type CursorStore = {
-  get: () => CursorState
-  set: (key: string | null, source: string | null, kind?: DomainKind | 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, kind: null }
-
-export function createCursorStore(): CursorStore {
-  let state: CursorState = EMPTY_CURSOR
-  const listeners = new Set<() => void>()
-
-  return {
-    get: () => state,
-    set: (key, source, kind = null) => {
-      if (state.key === key && state.source === source && state.kind === kind) return
-      state = key === null && source === null ? EMPTY_CURSOR : { key, source, kind }
-      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/cursor/touch-pin.ts

@@ -1,138 +0,0 @@
-/**
- * Two small pieces shared by every touch-pinned surface in the chart layer — extracted so
- * `useChartCursor`/`useDiscreteCursor`/`ChartLegend`'s disclosure cannot drift apart on the same
- * contract (round 2's carried-forward gap: each had its own hand-rolled copy).
- */
-import { useCallback, useEffect, useMemo, useRef } from 'react'
-
-/**
- * Outside-tap / Escape / scroll (optionally resize) dismissal for a pinned/open floating element.
- * Capture-phase `pointerdown` so a descendant that stops propagation on its own handler can't leave
- * the dismissal stuck.
- */
-export function useDismissOnOutside({
-  enabled,
-  isInside,
-  onDismiss,
-  dismissOnResize = false,
-  scrollExemptInside = false,
-}: {
-  enabled: boolean
-  /** A tap (or, with `scrollExemptInside`, a scroll) landing where this returns true doesn't
-   * dismiss. Omit to treat every tap as outside. */
-  isInside?: (target: Node) => boolean
-  onDismiss: () => void
-  /** Also dismiss on a window `resize` — `ChartLegend`'s disclosure needs this, the touch-pinned
-   * cursors don't (their host doesn't reflow independently of the chart it's pinned to). */
-  dismissOnResize?: boolean
-  /** Exempts a scroll whose target is `isInside` — `ChartLegend`'s own scrollable panel needs this
-   * (`overflowY: auto`), the cursor hooks don't (a chart has no internal scroller to protect). */
-  scrollExemptInside?: boolean
-}): void {
-  useEffect(() => {
-    if (!enabled) return
-    const onPointerDown = (event: PointerEvent) => {
-      if (event.target instanceof Node && isInside?.(event.target) === true) return
-      onDismiss()
-    }
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') onDismiss()
-    }
-    const onScroll = (event: Event) => {
-      if (scrollExemptInside && event.target instanceof Node && isInside?.(event.target) === true) {
-        return
-      }
-      onDismiss()
-    }
-    document.addEventListener('pointerdown', onPointerDown, true)
-    document.addEventListener('keydown', onKeyDown)
-    document.addEventListener('scroll', onScroll, true)
-    if (dismissOnResize) window.addEventListener('resize', onDismiss)
-    return () => {
-      document.removeEventListener('pointerdown', onPointerDown, true)
-      document.removeEventListener('keydown', onKeyDown)
-      document.removeEventListener('scroll', onScroll, true)
-      if (dismissOnResize) window.removeEventListener('resize', onDismiss)
-    }
-  }, [enabled, isInside, onDismiss, dismissOnResize, scrollExemptInside])
-}
-
-export type TouchPin = {
-  /** `onPointerDown` for a coarse press: snapshots whatever is currently committed (via
-   * `getCommitted`) so a later `cancel` can restore exactly that, then tracks `pointerId`. */
-  begin: (pointerId: number) => void
-  /** `onPointerUp` for the tracked pointer: the press is now committed — nothing left to revert. */
-  commit: (pointerId: number) => boolean
-  /** `onPointerCancel`/`onPointerLeave` for the tracked pointer: the browser took the gesture (a
-   * scroll) before the press committed — restores the pre-press value via `setCommitted`, or
-   * leaves it clear when nothing was committed before. Returns whether this pointer was tracked. */
-  cancel: (pointerId: number) => boolean
-  /** Hard reset — no restore, just drop any in-flight press bookkeeping (an explicit `clear()`, e.g.
-   * Escape or an outside tap, is about to overwrite the value directly anyway). */
-  reset: () => void
-}
-
-/**
- * Provisional-press state machine shared by `useChartCursor`/`useDiscreteCursor`: a coarse press
- * shows a value immediately (PROVISIONAL, not yet committed) — `commit` on `pointerup` leaves it in
- * place, `cancel` on `pointercancel`/`pointerleave` (a scroll winning the gesture) restores whatever
- * was committed before this press started, rather than dropping it. This is what keeps a previously
- * COMMITTED pin alive through a second tap that gets cancelled instead of completed.
- */
-export function useTouchPin<V>({
-  getCommitted,
-  setCommitted,
-}: {
-  /** Reads the value currently committed — snapshotted on `begin`, restored on `cancel`. */
-  getCommitted: () => V
-  setCommitted: (value: V) => void
-}): TouchPin {
-  const pressRef = useRef<number | null>(null)
-  const backupRef = useRef<V | undefined>(undefined)
-  // Whether `backupRef` holds a real snapshot — `backupRef.current !== undefined` used to stand in
-  // for this, which silently dropped a genuinely committed `undefined` (a caller's `V` can legally
-  // include it): `cancel` would restore nothing at all instead of restoring "nothing was pinned".
-  const hasBackupRef = useRef(false)
-  const getCommittedRef = useRef(getCommitted)
-  getCommittedRef.current = getCommitted
-  const setCommittedRef = useRef(setCommitted)
-  setCommittedRef.current = setCommitted
-
-  const begin = useCallback((pointerId: number) => {
-    backupRef.current = getCommittedRef.current()
-    hasBackupRef.current = true
-    pressRef.current = pointerId
-  }, [])
-
-  const commit = useCallback((pointerId: number): boolean => {
-    if (pressRef.current !== pointerId) return false
-    pressRef.current = null
-    backupRef.current = undefined
-    hasBackupRef.current = false
-    return true
-  }, [])
-
-  const cancel = useCallback((pointerId: number): boolean => {
-    if (pressRef.current !== pointerId) return false
-    pressRef.current = null
-    const backup = backupRef.current
-    const hasBackup = hasBackupRef.current
-    backupRef.current = undefined
-    hasBackupRef.current = false
-    if (hasBackup) setCommittedRef.current(backup as V)
-    return true
-  }, [])
-
-  const reset = useCallback(() => {
-    pressRef.current = null
-    backupRef.current = undefined
-    hasBackupRef.current = false
-  }, [])
-
-  // Stable identity: `begin`/`commit`/`cancel`/`reset` are themselves already stable (empty-dep
-  // `useCallback`s), but the returned OBJECT wrapping them was a fresh literal every render — a
-  // consumer's own effect depending on the whole `TouchPin` (or a `useDismissOnOutside` closing
-  // over one of these) would re-subscribe on every render for no reason. Memoizing on the four
-  // (stable) functions costs nothing and makes the wrapper's identity match theirs.
-  return useMemo(() => ({ begin, commit, cancel, reset }), [begin, commit, cancel, reset])
-}