basalt-ui 1.30.2 → 1.32.0

package/src/charts/hooks/useBandPlot.ts

@@ -20,7 +20,13 @@ import type { ReactNode, RefObject } from 'react'
 import type { ChartMargin } from '../../tokens'
 import type { CursorResolution } from '../cursor/resolve'
 import { autoMargin } from '../layout/auto-margin'
-import { useChartTierMetrics } from '../primitives/chart-tier'
+import {
+  isTightClass,
+  planXLabels,
+  resolveMarginFloor,
+  resolveYPlacement,
+} from '../primitives/chart-layout'
+import { useChartContainerClass, useChartMetrics } from '../primitives/chart-tier'
 import { maxTextWidth } from '../utils/measure-text'
 import { smartTicks, xLabelPxFor } from '../utils/ticks'
 import { useChartCursor } from './useChartCursor'
@@ -150,6 +156,13 @@ export type BandPlot<T> = {
   /** Drawn width of one band — the pitch minus a 1px separator, floored at 1. */
   bandWidth: number
   tickValues: string[]
+  /** Where the left axis paints: inside the plot (compact), not at all (micro), else outside. An
+   * explicit `margin.left` keeps it outside. Same law as `CartesianChart`. */
+  yPlacement: 'outside' | 'inside' | 'none'
+  /** Terminal x labels anchor inward (compact/micro). */
+  xAnchorTerminals: boolean
+  /** Width to wrap x labels to; undefined when they do not wrap. */
+  xWrapWidth: number | undefined
   svgRef: RefObject<SVGSVGElement | null>
   tooltipAnchor: CursorAnchor | null
   showTooltip: boolean
@@ -181,18 +194,44 @@ export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
   // two things `CartesianChart` reads off it: the tick font its gutters are MEASURED at (the same
   // one `AxisBottomDate` paints — measured labels must be the painted labels, §1) and the tightened
   // margin FLOORS (`docs/CHARTS-SPEC.md` §8).
-  const tier = useChartTierMetrics()
+  const tier = useChartMetrics()
+  const containerClass = useChartContainerClass()
+  const tight = isTightClass(containerClass)
 
   const hasLeftAxis = leftLabels !== undefined && leftLabels.length > 0
+  // Ladder step 5: inside labels reserve no gutter. An explicit `margin.left` keeps them outside.
+  const yPlacement = resolveYPlacement(containerClass, {
+    hasLeftAxis,
+    marginOverrideLeft: marginOverride?.left,
+  })
   const xLabelsAll = useMemo(() => data.map((d) => formatX(getX(d))), [data, getX, formatX])
 
+  // Ladder step 4 (wrap; a band axis cannot rotate, so it thins instead). Sized from the token
+  // floors because the real gutters depend on the wrapped line count. A band chart's x labels are
+  // always categorical by construction (one slot per datum) — no whitespace heuristic needed.
+  const xPlan = useMemo(
+    () =>
+      planXLabels({
+        labels: xLabelsAll,
+        plotWidth: width - tier.margin.left - tier.margin.right,
+        fontPx: tier.axisFont,
+        categorical: tight,
+      }),
+    [xLabelsAll, width, tier.margin, tier.axisFont, tight],
+  )
+  const xWrapWidth = xPlan.wrap ? xPlan.wrapPx : undefined
+
   // ── Pass 1: gutters, from the labels that will actually be painted ──────────────────────────
   const margin = useMemo<ChartMargin>(() => {
     const measured = autoMargin({
-      ...(leftLabels !== undefined && { left: leftLabels }),
+      ...(leftLabels !== undefined && { left: yPlacement === 'outside' ? leftLabels : [] }),
       bottom: xLabelsAll,
       fontPx: tier.axisFont,
-      floor: tier.margin,
+      // An inside-placed left axis paints IN the plot, so the outside label-width floor is dead
+      // space there — same law as `CartesianChart`'s `marginInput.floor`.
+      floor: resolveMarginFloor(yPlacement, tier.margin),
+      anchorTerminals: tight,
+      bottomLines: xPlan.lines,
       ...(marginOverride !== undefined && { override: marginOverride }),
     })
     if (marginOverride?.left !== undefined && marginOverride.right !== undefined) return measured
@@ -201,24 +240,38 @@ export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
     // A band axis puts its FIRST tick on the plot's left edge, so the left gutter needs the same
     // half-label law `autoMargin` already applies on the right. `autoMargin` cannot know that —
     // its left law measures a left AXIS, which a band plot may not have.
-    const left = hasLeftAxis ? measured.left : Math.max(measured.left, halfXLabel)
+    const left = hasLeftAxis || tight ? measured.left : Math.max(measured.left, halfXLabel)
     return {
       ...measured,
       ...(marginOverride?.left === undefined && {
-        left: hasLeftAxis
-          ? left
-          : capTerminalGutter(left, width, TERMINAL_GUTTER_MAX_FRACTION.left, tier.margin.left),
+        left:
+          hasLeftAxis || tight
+            ? left
+            : capTerminalGutter(left, width, TERMINAL_GUTTER_MAX_FRACTION.left, tier.margin.left),
       }),
       ...(marginOverride?.right === undefined && {
-        right: capTerminalGutter(
-          measured.right,
-          width,
-          TERMINAL_GUTTER_MAX_FRACTION.right,
-          tier.margin.right,
-        ),
+        right: tight
+          ? measured.right
+          : capTerminalGutter(
+              measured.right,
+              width,
+              TERMINAL_GUTTER_MAX_FRACTION.right,
+              tier.margin.right,
+            ),
       }),
     }
-  }, [leftLabels, xLabelsAll, marginOverride, hasLeftAxis, width, tier.axisFont, tier.margin])
+  }, [
+    leftLabels,
+    xLabelsAll,
+    marginOverride,
+    hasLeftAxis,
+    width,
+    tier.axisFont,
+    tier.margin,
+    tight,
+    yPlacement,
+    xPlan.lines,
+  ])
 
   const plotWidth = Math.max(width - margin.left - margin.right, 0)
 
@@ -249,12 +302,17 @@ export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
     [scale],
   )
 
+  const svgRef = useRef<SVGSVGElement>(null)
   const cursor = useChartCursor<T>({
     data: bands,
     chartId,
     getKey: getX,
     xScale: bandCenter,
     marginLeft: margin.left,
+    // Both callers (`BandStrip`, `MirroredBars`) mount exactly one `<svg ref={band.svgRef}>`, so
+    // it doubles as the tap-outside boundary (`docs/CHARTS-SPEC.md` §4, Tooltip) with no separate
+    // passthrough option — reusing the ref this hook already returns, not a new one.
+    boundaryRef: svgRef,
     ...(cursorResolution !== undefined && { resolution: cursorResolution }),
   })
 
@@ -262,20 +320,19 @@ export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
   // same measured-spacing law `CartesianChart` applies (`docs/CHARTS-SPEC.md` §1). `keys` (not
   // `xLabelsAll`) because ticks are chosen from the post-fold key list.
   const xLabelPx = useMemo(
-    () => xLabelPxFor(keys.map(formatX), tier.axisFont),
-    [keys, formatX, tier.axisFont],
+    () =>
+      xWrapWidth === undefined ? xLabelPxFor(keys.map(formatX), tier.axisFont) : xPlan.labelPx,
+    [keys, formatX, tier.axisFont, xWrapWidth, xPlan.labelPx],
   )
 
-  const tickValues = useMemo(
-    () => [
-      ...(xTickValues === undefined
-        ? smartTicks(keys, plotWidth, xLabelPx)
-        : xTickValues(keys, plotWidth)),
-    ],
-    [keys, plotWidth, xTickValues, xLabelPx],
-  )
+  const tickValues = useMemo(() => {
+    if (xTickValues !== undefined) return [...xTickValues(keys, plotWidth)]
+    // Micro: the two terminals only.
+    if (containerClass === 'micro')
+      return keys.length > 1 ? [keys[0]!, keys[keys.length - 1]!] : [...keys]
+    return [...smartTicks(keys, plotWidth, xLabelPx, tight)]
+  }, [keys, plotWidth, xTickValues, xLabelPx, containerClass, tight])
 
-  const svgRef = useRef<SVGSVGElement>(null)
   const point = cursor.point
   const crosshairX = point === null ? null : (bandCenter(getX(point)) ?? null)
 
@@ -284,7 +341,10 @@ export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
   // no pointer under it, so it is always positioned via the anchored (crosshair) path.
   const isFollowerRender = !cursor.isSource && cfg?.onFollow === true
   const showTooltip = tooltip !== false && point !== null && (cursor.isSource || isFollowerRender)
-  const useAnchored = cfg?.follow === false || isFollowerRender
+  // An unset `follow` also anchors on touch (spec §5) — same law as `CartesianChart`'s
+  // `useAnchoredPosition`; an EXPLICIT `follow` always wins over that default.
+  const useAnchored =
+    cfg?.follow === false || (cfg?.follow === undefined && cursor.isTouch) || isFollowerRender
   const anchorX = useAnchored ? crosshairX : null
   const svgRect = anchorX === null ? undefined : svgRef.current?.getBoundingClientRect()
   const tooltipAnchor =
@@ -307,6 +367,9 @@ export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
     step,
     bandWidth,
     tickValues,
+    yPlacement,
+    xAnchorTerminals: tight,
+    xWrapWidth,
     svgRef,
     tooltipAnchor,
     showTooltip,

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'