basalt-ui 1.30.2 → 1.31.0

package/src/charts/hooks/useChartCursor.ts

@@ -1,9 +1,11 @@
 import { localPoint } from '@visx/event'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import type { KeyboardEvent, PointerEvent } 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 }
@@ -15,23 +17,45 @@ export type ChartCursor<T> = {
   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
-  onPointerLeave: () => 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. Replaces
- * the removed `useHoverSync` + `useChartTooltip` pair, including their `resolveKey` escape hatch —
- * resolution is now automatic.
+ * 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.
  *
- * 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.
+ * 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,
@@ -40,6 +64,7 @@ export function useChartCursor<T>({
   xScale,
   marginLeft,
   resolution = 'nearest',
+  boundaryRef,
 }: {
   data: readonly T[]
   chartId: string
@@ -53,10 +78,38 @@ export function useChartCursor<T>({
    * 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
@@ -76,9 +129,18 @@ export function useChartCursor<T>({
 
   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
@@ -97,17 +159,29 @@ export function useChartCursor<T>({
     })
   }, [])
 
-  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
+  // 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) {
@@ -118,11 +192,79 @@ export function useChartCursor<T>({
           closest = d
         }
       }
-
-      scheduleAnchor({ x: event.clientX, y: event.clientY })
+      setIsTouch(pointerType !== 'mouse')
+      scheduleAnchor(anchor)
       store.set(getKeyRef.current(closest), chartId, kind)
     },
-    [data, marginLeft, chartId, store, scheduleAnchor, 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(() => {
@@ -130,12 +272,35 @@ export function useChartCursor<T>({
       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])
+  }, [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>) => {
@@ -169,13 +334,33 @@ export function useChartCursor<T>({
   // 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: cursor.source === chartId,
+    isSource,
     anchor,
+    isTouch,
     onPointerMove,
-    onPointerLeave: clear,
+    onPointerDown,
+    onPointerUp,
+    onPointerLeave,
     onKeyDown,
     onBlur: clear,
   }

package/src/charts/index.ts

@@ -84,14 +84,6 @@ export {
   type ResolvedChartState,
   resolveChartState,
 } from './primitives/ChartPending'
-export {
-  useChartTier,
-  useChartTierMetrics,
-  chartTierMetrics,
-  resolveChartTier,
-  type ChartTier,
-  type ChartTierMetrics,
-} from './primitives/chart-tier'
 export { Crosshair, SeriesDot } from './primitives/Crosshair'
 export { HatchPattern, hatchFill, hatchSizeFor } from './primitives/HatchPattern'
 export { ChartCard, type ChartCardProps, type ChartCardSlot } from './primitives/ChartCard'

package/src/charts/kinds/BandStrip.tsx

@@ -357,7 +357,13 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
 
   return (
     <>
-      <svg ref={band.svgRef} width={plot.width} height={plot.height}>
+      <svg
+        ref={band.svgRef}
+        width={plot.width}
+        height={plot.height}
+        // `touch-action` on the plot `<svg>`: Chrome ignores it on the overlay `<rect>` (`R2C-2`).
+        style={{ touchAction: 'pan-y' }}
+      >
         <defs>
           <HatchPattern
             id={hatchId}
@@ -382,12 +388,16 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
             scale={scale}
             tickValues={band.tickValues}
             tickFormat={(v) => formatX(String(v))}
+            anchorTerminals={band.xAnchorTerminals}
+            {...(band.xWrapWidth !== undefined && { wrapWidth: band.xWrapWidth })}
           />
 
           <HoverOverlay
             width={plotWidth}
             height={stripHeight}
             onMove={cursor.onPointerMove}
+            onDown={cursor.onPointerDown}
+            onUp={cursor.onPointerUp}
             onLeave={cursor.onPointerLeave}
             onKeyDown={cursor.onKeyDown}
             onBlur={cursor.onBlur}