basalt-ui 1.41.0 → 2.0.0

package/src/charts/hooks/useChartCursor.ts

@@ -1,367 +0,0 @@
-import { localPoint } from '@visx/event'
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import type { KeyboardEvent, PointerEvent, RefObject } from 'react'
-import type { CursorResolution } from '../cursor/resolve'
-import { buildDomainIndex, classifyDomain, resolveCursorPoint } from '../cursor/resolve'
-import { useCursorState, useCursorStore } from '../cursor/scope'
-import type { CursorState } from '../cursor/store'
-import { useDismissOnOutside, useTouchPin } from '../cursor/touch-pin'
-
-/** 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
-  /**
-   * True when the interaction that most recently placed THIS chart's cursor had
-   * `event.pointerType !== 'mouse'` (touch or pen). Callers fold it into the anchored-tooltip
-   * condition (`tooltip.follow` defaulting to `false` on touch, docs/CHARTS-SPEC.md §4) — a follower's own
-   * anchoring is unaffected, since a follower is never the one whose pointer set this flag.
-   */
-  isTouch: boolean
-  onPointerMove: (event: PointerEvent<SVGRectElement>) => void
-  /** Coarse-pointer equivalent of hover: resolves the nearest point and shows the tooltip
-   * immediately, with no preceding `pointermove` — a plain tap otherwise fires only
-   * `pointerdown`/`pointerup`. The press is PROVISIONAL: it shows the tooltip but does not commit a
-   * pin, which only `onPointerUp` does. Also what MOVES an existing touch pin to a new tap elsewhere
-   * in the same chart (fine pointers ignore it; `onPointerMove` already covers hover for them). */
-  onPointerDown: (event: PointerEvent<SVGRectElement>) => void
-  /** Commits the provisional touch press — the same `pointerId` as the matching `onPointerDown` —
-   * so the pin survives the lift. A `pointerup` for any other pointer is ignored. */
-  onPointerUp: (event: PointerEvent<SVGRectElement>) => void
-  /** `pointerleave`/`pointercancel`, sharing one handler. A still-UNCOMMITTED touch press cancelled
-   * here is the browser taking the gesture (a scroll) and clears; once committed, touch no-ops so a
-   * stray `pointercancel` cannot undo the pin. A fine pointer always clears. */
-  onPointerLeave: (event: PointerEvent<SVGRectElement>) => 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 — automatic,
- * no `resolveKey` escape hatch.
- *
- * The tooltip anchor is coalesced through `requestAnimationFrame` (one local write per frame on a
- * fast scrub); the BROADCAST is deduped instead, so a within-bucket scrub costs nothing and a real
- * bucket change reaches siblings on the same tick.
- *
- * Touch model (`docs/CHARTS-SPEC.md` §4): a fine pointer keeps hovering. A coarse pointer
- * (`onPointerDown`) resolves and shows the tooltip immediately, drag-scrubs via `onPointerMove`,
- * and COMMITS a pin on `onPointerUp` — `onPointerLeave` (also wired to `pointercancel`) no-ops once
- * committed. A press the browser turns into a scroll clears instead. The pin moves on a fresh tap,
- * clears on a `document` tap outside `boundaryRef`, on any scroll, or on Escape.
- */
-export function useChartCursor<T>({
-  data,
-  chartId,
-  getKey,
-  xScale,
-  marginLeft,
-  resolution = 'nearest',
-  boundaryRef,
-}: {
-  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
-  /**
-   * How a sibling's broadcast key resolves against this chart's own points. Default `'nearest'`
-   * (point domains). Pass `'leading'` when `getKey` returns a bucket's leading edge (a weekly
-   * series keyed by its Monday, a monthly series keyed by its 1st) — see {@link CursorResolution}.
-   */
-  resolution?: CursorResolution
-  /**
-   * Element a touch tap OUTSIDE dismisses the pin against (`docs/CHARTS-SPEC.md` §4). One
-   * capture-phase `document` `pointerdown` listener clears the pin when the target falls outside
-   * this ref — added on pinning, removed on unpin/unmount. Omit to skip outside-dismiss (a tap
-   * elsewhere in the chart and Escape still work); never throws for a missing ref.
-   */
-  boundaryRef?: RefObject<Element | null>
-}): ChartCursor<T> {
-  const store = useCursorStore()
-  const cursor = useCursorState()
-  const [anchor, setAnchor] = useState<CursorAnchor | null>(null)
-  // Whether the interaction that most recently placed THIS chart's cursor was coarse (touch/pen).
-  // Branched per EVENT (`event.pointerType`), never a static media query — a hybrid device can
-  // carry both inputs, and a media query can't tell which one just fired.
-  const [isTouch, setIsTouch] = useState(false)
-  // Whether THIS chart currently holds a COMMITTED touch/pen pin — deliberately separate from
-  // `isTouch` above, which a subsequent fine-pointer move resets to `false` (that IS the bug this
-  // guards against) and which `clear()` never touches. Set on a successful `onPointerUp` commit,
-  // cleared by `clear()` OR by losing source ownership — mirrors `useDiscreteCursor`'s `pinned`
-  // state, kept as a ref here since nothing needs to re-render off it directly.
-  const pinnedRef = useRef(false)
-  // A SIBLING chart stealing the shared cursor source (its own touch tap) never calls THIS chart's
-  // `clear()` — nothing here observes that tap directly. Left unguarded, `pinnedRef` stayed `true`
-  // forever once set, so a later mouse hover on this chart — after it legitimately re-claims
-  // `source` — read a stale pin and froze the crosshair (`resolveNearestAt`'s
-  // `pointerType === 'mouse' && pinnedRef.current && store.get().source === chartId` guard blocking
-  // a hover that was never actually still pinned). Reset the moment this chart is no longer the
-  // cursor's source — the one signal that unambiguously means whatever touch pin this chart held
-  // is gone, stolen or not.
-  useEffect(() => {
-    if (cursor.source !== chartId) pinnedRef.current = false
-  }, [cursor.source, chartId])
-
-  // 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, resolution),
-    [data, resolution],
-  )
-  // Mirrors `index`'s memo shape (deps built off `data`, reading the accessor through a ref) —
-  // `resolution` is left out because `kind` never reads it, and `exhaustive-deps` enforces that.
-  const kind = useMemo(() => classifyDomain(data.map((d) => getKeyRef.current(d))), [data])
-
-  const frameRef = useRef<number | null>(null)
-  const pendingRef = useRef<CursorAnchor | null>(null)
-  // `pointermove` floods far faster than one nearest-point search is worth — an untethered scrub
-  // can fire dozens of native events between paints. `moveFrameRef`/`pendingMoveRef` coalesce the
-  // O(n) search itself (not just the anchor, which `frameRef`/`pendingRef` already batch) to one
-  // per animation frame — see `onPointerMove` below.
-  const moveFrameRef = useRef<number | null>(null)
-  const pendingMoveRef = useRef<{ px: number; anchor: CursorAnchor; pointerType: string } | null>(
-    null,
-  )
-  useEffect(
-    () => () => {
-      if (frameRef.current !== null) cancelAnimationFrame(frameRef.current)
-      if (moveFrameRef.current !== null) cancelAnimationFrame(moveFrameRef.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, 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)
-    })
-  }, [])
-
-  // The provisional-press commit/revert machine (`docs/CHARTS-SPEC.md` §4) — shared with
-  // `useDiscreteCursor`. `getCommitted` snapshots the STORE's current value (not this chart's own
-  // `point`), because the shared cursor is page-wide: a committed pin can belong to a different
-  // chart than the one now taking a second, cancelled press.
-  const touchPin = useTouchPin<CursorState>({
-    getCommitted: () => store.get(),
-    setCommitted: (v) => store.set(v.key, v.source, v.kind),
-  })
-
-  // The nearest-point search plus the broadcast — shared by the immediate (tap) and throttled
-  // (move) resolve paths below, so they cannot drift apart. `px` is the plot-local x, already run
-  // through `localPoint` by the caller: a `requestAnimationFrame` boundary has no business holding
-  // a live `PointerEvent`, only the plain numbers it already read out of one.
-  const resolveNearestAt = useCallback(
-    (px: number, anchor: CursorAnchor, pointerType: string) => {
-      if (data.length === 0) return
-      // A committed touch/pen pin must not be silently overridden by a fine-pointer hover on a
-      // hybrid device (a touchscreen laptop with a mouse/trackpad) — mirrors `useDiscreteCursor`'s
-      // `pinned` guard on its own hover path. Gated on `store.get().source` (not the reactive
-      // `isSource` derived later in this hook) so a pin a SIBLING chart has since stolen no longer
-      // blocks this chart's own mouse hover just because this chart's stale `pinnedRef` is still
-      // true.
-      if (pointerType === 'mouse' && pinnedRef.current && store.get().source === chartId) return
-      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
-        }
-      }
-      setIsTouch(pointerType !== 'mouse')
-      scheduleAnchor(anchor)
-      store.set(getKeyRef.current(closest), chartId, kind)
-    },
-    [data, chartId, store, scheduleAnchor, kind],
-  )
-
-  // 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 localX = useCallback(
-    (event: PointerEvent<SVGRectElement>): number | null => {
-      const local = localPoint(event.currentTarget, event.nativeEvent)
-      return local === null ? null : local.x - marginLeft
-    },
-    [marginLeft],
-  )
-
-  // A tap resolves immediately — one discrete event, not a flood, so it needs no throttle.
-  const resolveImmediate = useCallback(
-    (event: PointerEvent<SVGRectElement>) => {
-      const px = localX(event)
-      if (px === null) return
-      resolveNearestAt(px, { x: event.clientX, y: event.clientY }, event.pointerType)
-    },
-    [localX, resolveNearestAt],
-  )
-
-  const onPointerMove = useCallback(
-    (event: PointerEvent<SVGRectElement>) => {
-      const px = localX(event)
-      if (px === null) return
-      pendingMoveRef.current = {
-        px,
-        anchor: { x: event.clientX, y: event.clientY },
-        pointerType: event.pointerType,
-      }
-      if (moveFrameRef.current !== null) return
-      moveFrameRef.current = requestAnimationFrame(() => {
-        moveFrameRef.current = null
-        const pending = pendingMoveRef.current
-        pendingMoveRef.current = null
-        if (pending !== null) resolveNearestAt(pending.px, pending.anchor, pending.pointerType)
-      })
-    },
-    [localX, resolveNearestAt],
-  )
-
-  // A tap fires `pointerdown` + `pointerup` with no `pointermove` in between, so hover's resolve
-  // path never runs for it — this is what makes a tap show anything at all. It also MOVES an
-  // existing touch pin: a fresh `pointerdown` elsewhere in the chart re-resolves and re-broadcasts
-  // exactly like the first one, with nothing extra to wire.
-  const onPointerDown = useCallback(
-    (event: PointerEvent<SVGRectElement>) => {
-      // A coarse press is PROVISIONAL: snapshot whatever is committed now (so a cancel can restore
-      // it) BEFORE the resolve below overwrites the store. A fine pointer never begins a press —
-      // its hover path has no pin to protect.
-      if (event.pointerType !== 'mouse') touchPin.begin(event.pointerId)
-      resolveImmediate(event)
-    },
-    [resolveImmediate, touchPin],
-  )
-  // A completed tap: the pin is now committed, so `onPointerLeave`'s touch no-op keeps it past the
-  // lift. Only the tracked pointer commits — a stray `pointerup` is ignored. `pointerType ===
-  // 'mouse'` is checked FIRST and unconditionally: some browsers alias a touch's `pointerId` to the
-  // same value (1) a mouse pointer uses, so without this an unrelated mouse `pointerup` could commit
-  // an abandoned touch press it never tracked (mirrors `useDiscreteCursor`'s identical guard).
-  const onPointerUp = useCallback(
-    (event: PointerEvent<SVGRectElement>) => {
-      if (event.pointerType === 'mouse') return
-      if (touchPin.commit(event.pointerId)) pinnedRef.current = true
-    },
-    [touchPin],
-  )
-
-  const clear = useCallback(() => {
-    if (frameRef.current !== null) {
-      cancelAnimationFrame(frameRef.current)
-      frameRef.current = null
-    }
-    if (moveFrameRef.current !== null) {
-      cancelAnimationFrame(moveFrameRef.current)
-      moveFrameRef.current = null
-    }
-    pendingRef.current = null
-    pendingMoveRef.current = null
-    touchPin.reset()
-    pinnedRef.current = false
-    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, null)
-  }, [store, chartId, touchPin])
-
-  // `pointerleave`/`pointercancel` share this one handler (`HoverOverlay` wires both to `onLeave`).
-  // A still-uncommitted touch press cancelled here is the browser taking the gesture (a scroll):
-  // `touchPin.cancel` restores whatever pin was committed before this press started (or leaves it
-  // clear when nothing was), rather than dropping a pin this press never owned. Once COMMITTED by
-  // touch it is a no-op — a stray `pointercancel` must not undo the pin the tap was meant to set.
-  // Escape's `clear()` in `onKeyDown` bypasses this guard entirely, by design: it is the one
-  // dismissal that must work regardless of pointer type.
-  const onPointerLeave = useCallback(
-    (event: PointerEvent<SVGRectElement>) => {
-      if (touchPin.cancel(event.pointerId)) return
-      if (isTouch) return
-      clear()
-    },
-    [isTouch, clear, touchPin],
-  )
-
-  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, kind)
-    },
-    [data, store, chartId, clear, scheduleAnchor, kind],
-  )
-
-  // A broadcast from a domain of a DIFFERENT kind is filtered out here, before resolution is even
-  // attempted — a category chart never resolves a date chart's key just because both happen to
-  // parse. `isSource` is unaffected: it compares `chartId`, not `kind`, and a chart's own broadcast
-  // always carries its own kind by construction.
-  const point =
-    cursor.key === null || cursor.kind !== kind ? null : resolveCursorPoint(index, cursor.key)
-  const isSource = cursor.source === chartId
-
-  // Tap-outside dismissal (spec §5): while THIS chart is both pinned by touch and still the cursor's
-  // source, a capture-phase `document` `pointerdown`/`scroll`/`keydown` (shared with
-  // `useDiscreteCursor`, see `touch-pin.ts`) clears it the moment the event target falls outside
-  // `boundaryRef`. Gating on `isSource` (not `isTouch` alone) means the listener follows the pin —
-  // a sibling chart stealing the source on its own touch tap detaches this one instead of leaving a
-  // second stale listener alive.
-  const isInsideBoundary = useCallback(
-    (target: Node): boolean => boundaryRef?.current?.contains(target) === true,
-    [boundaryRef],
-  )
-  useDismissOnOutside({
-    enabled: isTouch && isSource && boundaryRef !== undefined,
-    isInside: isInsideBoundary,
-    onDismiss: clear,
-  })
-
-  return {
-    point,
-    isSource,
-    anchor,
-    isTouch,
-    onPointerMove,
-    onPointerDown,
-    onPointerUp,
-    onPointerLeave,
-    onKeyDown,
-    onBlur: clear,
-  }
-}

package/src/charts/hooks/useChartSize.ts

@@ -1,35 +0,0 @@
-import { useParentSize } from '@visx/responsive'
-
-export type ChartSize = {
-  width: number
-  height: number
-}
-
-export type UseChartSizeResult = ChartSize & {
-  /** Attach to the container element to measure its dimensions. */
-  ref: (node: HTMLDivElement | null) => void
-}
-
-/**
- * Measures the width and height of a container element via a ResizeObserver.
- * 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 CellSparkline({ points }: { points: number[] }) {
- *   const { ref, width } = useChartSize()
- *   return (
- *     <div ref={ref} style={{ width: '100%', height: 24 }}>
- *       {width > 0 && <LineSparkline data={points} width={width} height={24} />}
- *     </div>
- *   )
- * }
- */
-export function useChartSize(debounceMs = 0): UseChartSizeResult {
-  const { parentRef, width, height } = useParentSize({ debounceTime: debounceMs })
-  return { ref: parentRef, width, height }
-}