basalt-ui 1.30.2 → 1.32.0

package/src/charts/cursor/touch-pin.ts

@@ -0,0 +1,138 @@
+/**
+ * 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])
+}

package/src/charts/hooks/use-discrete-cursor.ts

@@ -0,0 +1,335 @@
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
+import type {
+  KeyboardEventHandler,
+  PointerEvent as ReactPointerEvent,
+  PointerEventHandler,
+} from 'react'
+import { useDismissOnOutside, useTouchPin } from '../cursor/touch-pin'
+
+/** A discrete target plus the viewport-space point its tooltip anchors to. */
+export type DiscreteCursorTip<T> = { target: T; anchor: { x: number; y: number } }
+
+type ActiveState = { key: string; anchor: { x: number; y: number } }
+
+export type UseDiscreteCursorResult<T> = {
+  /** The target whose tooltip should render, resolved from whichever mode last set it (hover, a
+   * touch pin, or keyboard focus). `null` when nothing is active. */
+  tip: DiscreteCursorTip<T> | null
+  /** True once a coarse-pointer tap has PINNED `tip` open (survives pointer lift). */
+  isPinned: boolean
+  /** Pointer handlers for one target's shape — spread onto its `<g>`/`<rect>`. Fine pointers
+   * (mouse/pen) hover; a coarse pointer (touch) pins on `pointerdown` instead. */
+  pointerProps: (t: T) => {
+    onPointerEnter: PointerEventHandler<Element>
+    onPointerMove: PointerEventHandler<Element>
+    onPointerDown: PointerEventHandler<Element>
+    onPointerUp: PointerEventHandler<Element>
+    onPointerLeave: PointerEventHandler<Element>
+    onPointerCancel: PointerEventHandler<Element>
+  }
+  /** DOM id for a target's `role="option"` element — also `aria-activedescendant`'s value while
+   * that target is active. Spread `id={optionId(t)}` on the same node that gets `pointerProps`. */
+  optionId: (t: T) => string
+  /** Dismisses a pin and clears keyboard focus. Already wired to Escape and an outside tap while
+   * pinned; call it directly for anything else that should close the tooltip (e.g. data changing
+   * out from under the focused key). */
+  clear: () => void
+  /** Spread on the ONE shared, focusable host (the chart's `<svg>`). */
+  hostProps: {
+    ref: (node: Element | null) => void
+    tabIndex: 0
+    role: 'listbox'
+    'aria-label': string
+    'aria-activedescendant': string | undefined
+    onKeyDown: KeyboardEventHandler<Element>
+    onBlur: () => void
+  }
+}
+
+/**
+ * Keyboard + focus + tap parity for a DISCRETE set of targets (donut slices, heatmap cells) — the
+ * counterpart `HoverOverlay` gives a continuous cartesian domain (`docs/CHARTS-SPEC.md` §4).
+ *
+ * **Role choice**: `listbox`/`option` (WAI-ARIA APG "Listbox"), not `slider`. A cartesian domain is
+ * one continuous value; a donut slice or heatmap cell is a named choice among discrete siblings.
+ * `aria-activedescendant` announces the focused option's id while DOM focus stays on the one host.
+ *
+ * Three input modes converge on one `tip`: hover (fine pointer, ephemeral), a provisional tap that
+ * `pointerup` commits into a pin (a `pointercancel` first — a scroll — clears it), and keyboard
+ * stepping on the one focusable host (`columns` maps Up/Down to a full-row jump for a 2D grid;
+ * Left/Right always step by one). Keyboard focus anchors the tooltip to the host's center — an
+ * accepted simplification; the value still reaches a screen reader via the option's text.
+ */
+export function useDiscreteCursor<T>({
+  targets,
+  getKey,
+  columns,
+  ariaLabel = 'Chart data — use arrow keys to navigate, Escape to dismiss',
+}: {
+  targets: readonly T[]
+  getKey: (t: T) => string
+  /** Row width for a 2D grid — see the Up/Down mapping above. Omit for a 1D ring. */
+  columns?: number
+  /** Accessible name for the shared listbox host. */
+  ariaLabel?: string
+}): UseDiscreteCursorResult<T> {
+  const [active, setActive] = useState<ActiveState | null>(null)
+  const [pinned, setPinned] = useState(false)
+  const hostElRef = useRef<Element | null>(null)
+  const idPrefix = useId()
+
+  // Mirrors `active`/`pinned` so the provisional-press machine below can read the CURRENT committed
+  // value synchronously from an event handler, without either living in a ref of its own.
+  const activeRef = useRef(active)
+  activeRef.current = active
+  const pinnedRef = useRef(pinned)
+  pinnedRef.current = pinned
+
+  // Read through refs so a keypress or an outside tap arriving between renders (the two
+  // `document`-level listeners below) always sees the LATEST list/accessor, not the ones closed
+  // over when the effect was installed — `targets` and `columns` can both change every render (a
+  // filtered dataset, a resize).
+  const targetsRef = useRef(targets)
+  targetsRef.current = targets
+  const getKeyRef = useRef(getKey)
+  getKeyRef.current = getKey
+  const columnsRef = useRef(columns)
+  columnsRef.current = columns
+
+  // `pointermove`/`pointerenter` flood far faster than one `setActive` is worth on a fast scrub
+  // across many targets — coalesced to one commit per animation frame, the same treatment
+  // `useChartCursor`'s own hover path gives its (costlier) nearest-point search. Cancelled on
+  // unmount and in `clear()` — which `onPointerLeave`/`onPointerCancel` below also route through —
+  // so a frame already in flight cannot resurrect a hover the clear just dismissed.
+  const moveFrameRef = useRef<number | null>(null)
+  const pendingActiveRef = useRef<ActiveState | null>(null)
+  useEffect(
+    () => () => {
+      if (moveFrameRef.current !== null) cancelAnimationFrame(moveFrameRef.current)
+    },
+    [],
+  )
+  const scheduleActive = useCallback((next: ActiveState) => {
+    pendingActiveRef.current = next
+    if (moveFrameRef.current !== null) return
+    moveFrameRef.current = requestAnimationFrame(() => {
+      moveFrameRef.current = null
+      setActive(pendingActiveRef.current)
+    })
+  }, [])
+
+  // Cancels a hover frame already in flight and clears what it was about to commit — called by
+  // every SYNCHRONOUS writer of `active` (a touch press, a keyboard step, `clear()` itself) before
+  // it writes. Without this, a `pointermove` scheduled a tick earlier (coalesced onto
+  // `moveFrameRef`/`pendingActiveRef`, per `scheduleActive` above) is still in flight when one of
+  // those writes lands, and the frame fires a moment later and overwrites it right back with the
+  // stale hover target — the keyboard/touch target "reverts" to whatever was last hovered.
+  const cancelPendingFrame = useCallback(() => {
+    if (moveFrameRef.current !== null) {
+      cancelAnimationFrame(moveFrameRef.current)
+      moveFrameRef.current = null
+    }
+    pendingActiveRef.current = null
+  }, [])
+
+  // The provisional-press commit/revert machine (`docs/CHARTS-SPEC.md` §4) — shared with
+  // `useChartCursor`. The committed value IS `active` whenever `pinned` is true — there is no
+  // separate ref to keep in sync, `pinnedRef`/`activeRef` above already mirror both.
+  const touchPin = useTouchPin<ActiveState | null>({
+    getCommitted: () => (pinnedRef.current ? activeRef.current : null),
+    setCommitted: (value) => {
+      setActive(value)
+      setPinned(value !== null)
+    },
+  })
+
+  const clear = useCallback(() => {
+    cancelPendingFrame()
+    touchPin.reset()
+    setActive(null)
+    setPinned(false)
+  }, [touchPin, cancelPendingFrame])
+
+  // Coarse-pointer pin dismissal that can't be expressed as a per-target handler: a tap OUTSIDE
+  // the host, or Escape, from anywhere on the page. A tap landing back INSIDE the host is handled
+  // by the per-target `onPointerDown` in `pointerProps` instead (it MOVES the pin), so this
+  // listener only ever fires for the "elsewhere" case — same shape as `ChartLegend`'s disclosure
+  // dismissal. Shared with `useChartCursor` (`touch-pin.ts`).
+  const isInsideHost = useCallback(
+    (target: Node): boolean => hostElRef.current?.contains(target) === true,
+    [],
+  )
+  useDismissOnOutside({ enabled: pinned, isInside: isInsideHost, onDismiss: clear })
+
+  // Index in `targetsRef`, NOT the key: Heatmap's `cellKey` joins cells with `\u0000`, which would
+  // leak a NUL into a DOM id, and an id has to be a valid DOM token. Resolved by KEY, not reference:
+  // Heatmap builds a fresh `{ row, col, value }` object per cell render, so a reference lookup always
+  // misses. A `Map` built once per `targets` change keeps `optionId` O(1) on the render loop the
+  // touch-scrub path re-runs every frame.
+  const indexByKey = useMemo(() => {
+    const map = new Map<string, number>()
+    targets.forEach((t, i) => map.set(getKeyRef.current(t), i))
+    return map
+  }, [targets])
+  const optionId = useCallback(
+    (t: T): string => `${idPrefix}-${indexByKey.get(getKeyRef.current(t)) ?? -1}`,
+    [idPrefix, indexByKey],
+  )
+
+  // O(1) via `indexByKey` rather than a fresh scan — the same Map `optionId` already builds.
+  const findTarget = (key: string): T | undefined => {
+    const index = indexByKey.get(key)
+    return index === undefined ? undefined : targetsRef.current[index]
+  }
+
+  const pointerProps = (t: T): ReturnType<UseDiscreteCursorResult<T>['pointerProps']> => {
+    const key = getKeyRef.current(t)
+    const showAt = (event: ReactPointerEvent<Element>): void => {
+      scheduleActive({ key, anchor: { x: event.clientX, y: event.clientY } })
+    }
+    // Shared by `onPointerLeave` and `onPointerCancel`: a still-UNCOMMITTED press ending here is the
+    // browser taking the gesture (a scroll) — `touchPin.cancel` restores whatever was COMMITTED
+    // before this press started (or leaves it clear when nothing was), regardless of `pinned`. The
+    // two used to diverge (`onPointerCancel` checked this, `onPointerLeave` didn't), which left a
+    // stale press and a stuck readout on the leave-before-cancel ordering a scroll off a small hit
+    // target commonly produces.
+    const cancelIfUncommitted = (event: ReactPointerEvent<Element>): boolean =>
+      touchPin.cancel(event.pointerId)
+    // `pointerType !== 'mouse'` throughout (never `=== 'touch'`), matching `useChartCursor` —
+    // pen counts as coarse too, so a stylus tap gets the same pin-until-dismiss contract a finger
+    // does, not the fine-pointer hover path.
+    return {
+      onPointerEnter: (event) => {
+        // Guarded on `pinned`, not just pointer type: while a touch tap has pinned a DIFFERENT
+        // target, a stray mouse hover elsewhere (a hybrid touchscreen + mouse device) must not
+        // silently steal `active` out from under the pin — it would leave that new hover's
+        // tooltip stuck on lift, since leave/cancel below still see `pinned` and no-op.
+        if (event.pointerType !== 'mouse' || pinned) return
+        showAt(event)
+      },
+      onPointerMove: (event) => {
+        if (event.pointerType !== 'mouse' || pinned) return
+        showAt(event)
+      },
+      // Only a coarse pointer presses — a fine pointer's `down` is a no-op, it already shows via
+      // enter/move above. The press is PROVISIONAL: it snapshots whatever is committed now (so a
+      // cancel can restore it) BEFORE showing the readout, which only `onPointerUp` commits. On
+      // touch the readout anchors to the HOST's top edge rather than the finger, which would cover
+      // it; a missing host falls back to the pointer.
+      onPointerDown: (event) => {
+        if (event.pointerType === 'mouse') return
+        touchPin.begin(event.pointerId)
+        // A hover frame scheduled just before this press (e.g. a hybrid touch+mouse device) must
+        // not be allowed to land after this — see `cancelPendingFrame`'s own doc.
+        cancelPendingFrame()
+        const rect = hostElRef.current?.getBoundingClientRect()
+        setActive({
+          key,
+          anchor:
+            rect === undefined
+              ? { x: event.clientX, y: event.clientY }
+              : { x: rect.left + rect.width / 2, y: rect.top },
+        })
+      },
+      // A completed tap commits the pin. Only the tracked pointer commits — and only a coarse one:
+      // some browsers assign a touch's `pointerId` the same value (1) mouse pointers use, so a
+      // `pointerType` check keeps an unrelated mouse `pointerup` reusing that id from committing an
+      // abandoned touch press.
+      onPointerUp: (event) => {
+        if (event.pointerType === 'mouse') return
+        if (!touchPin.commit(event.pointerId)) return
+        setPinned(true)
+      },
+      // A still-uncommitted press ending here is the browser taking the gesture (a scroll); clear it
+      // regardless of `pinned`. Otherwise keep the fine-pointer/pinned guard. Routes through the
+      // same `clear()` the outside-tap/Escape dismissal uses (mirrors `useChartCursor`'s own
+      // `onPointerLeave`) rather than a bare `setActive(null)` — a `pointermove` scheduled just
+      // before this event fires is still in flight (coalesced onto `moveFrameRef`/
+      // `pendingActiveRef`), and only `clear()` cancels it. A bare `setActive(null)` left that frame
+      // free to land a tick later and resurrect the tooltip this leave/cancel was meant to dismiss.
+      onPointerLeave: (event) => {
+        if (cancelIfUncommitted(event)) return
+        if (event.pointerType !== 'mouse' || pinned) return
+        clear()
+      },
+      onPointerCancel: (event) => {
+        if (cancelIfUncommitted(event)) return
+        if (event.pointerType !== 'mouse' || pinned) return
+        clear()
+      },
+    }
+  }
+
+  const onKeyDown: KeyboardEventHandler<Element> = (event) => {
+    const list = targetsRef.current
+    if (list.length === 0) return
+    if (event.key === 'Escape') {
+      clear()
+      return
+    }
+    const cols = columnsRef.current
+    let delta = 0
+    switch (event.key) {
+      case 'ArrowRight':
+        delta = 1
+        break
+      case 'ArrowLeft':
+        delta = -1
+        break
+      case 'ArrowDown':
+        delta = cols ?? 1
+        break
+      case 'ArrowUp':
+        delta = -(cols ?? 1)
+        break
+      default:
+        return
+    }
+    event.preventDefault()
+
+    const currentIndex =
+      active === null ? -1 : list.findIndex((t) => getKeyRef.current(t) === active.key)
+    // Mirrors `useChartCursor`'s onKeyDown: no current focus starts one step before/after the
+    // domain edge, so the first arrow press lands on the first or last target.
+    const base = currentIndex === -1 ? (delta > 0 ? -1 : list.length) : currentIndex
+    const nextIndex = Math.min(Math.max(base + delta, 0), list.length - 1)
+    const next = list[nextIndex] as T
+
+    const rect = hostElRef.current?.getBoundingClientRect()
+    const anchor =
+      rect === undefined
+        ? { x: 0, y: 0 }
+        : { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 }
+    // A hover frame scheduled just before this keypress must not be allowed to land after this —
+    // see `cancelPendingFrame`'s own doc.
+    cancelPendingFrame()
+    setActive({ key: getKeyRef.current(next), anchor })
+  }
+
+  const tip: DiscreteCursorTip<T> | null = (() => {
+    if (active === null) return null
+    const target = findTarget(active.key)
+    return target === undefined ? null : { target, anchor: active.anchor }
+  })()
+
+  return {
+    tip,
+    isPinned: pinned,
+    pointerProps,
+    optionId,
+    clear,
+    hostProps: {
+      ref: (node) => {
+        hostElRef.current = node
+      },
+      tabIndex: 0,
+      role: 'listbox',
+      'aria-label': ariaLabel,
+      'aria-activedescendant': tip === null ? undefined : optionId(tip.target),
+      onKeyDown,
+      onBlur: () => {
+        if (!pinned) clear()
+      },
+    },
+  }
+}

package/src/charts/hooks/use-hysteresis.ts

@@ -0,0 +1,26 @@
+import { useLayoutEffect, useRef } from 'react'
+
+/**
+ * A derived value that feeds back into its own next computation — hysteresis, "was X last frame" —
+ * without the anti-pattern of mutating a ref during render (`ChartCard`'s short-card flag, P0-1;
+ * `Donut`'s side/stacked layout, P2-10, both hit the SAME bug independently: a render a concurrent
+ * commit discards must not still poison the next real one's input).
+ *
+ * `compute` is called with the PREVIOUS committed value (never mutated here) and returns this
+ * render's value; the ref only updates in a `useLayoutEffect`, after the value has actually
+ * committed. Internal only — not on any public barrel.
+ *
+ * @example
+ * const short = useHysteresis(
+ *   (wasShort) => measuredHeight > 0 && measuredHeight < (wasShort ? EXIT : ENTER),
+ *   false,
+ * )
+ */
+export function useHysteresis<T>(compute: (previous: T) => T, initial: T): T {
+  const ref = useRef(initial)
+  const value = compute(ref.current)
+  useLayoutEffect(() => {
+    ref.current = value
+  }, [value])
+  return value
+}