basalt-ui 1.30.2 → 1.31.0

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
+}

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,