basalt-ui 1.30.2 → 1.31.0

package/src/charts/primitives/ChartLegend.tsx

@@ -1,9 +1,12 @@
-import type { CSSProperties, FocusEvent, MouseEvent, ReactNode } from 'react'
-import { useState } from 'react'
+import type { CSSProperties, MouseEvent, ReactNode } from 'react'
+import { useCallback, useEffect, useId, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
 import type { BasaltProps } from '../../common/props'
 import { alpha, VX } from '../../tokens'
+import { useDismissOnOutside } from '../cursor/touch-pin'
 import type { SeriesRole, LegendPlacement } from '../series'
-import { useChartTierMetrics } from './chart-tier'
+import { DOTS_HIT_GAP, LEGEND_DOT_SIZE, LEGEND_ROW_GAP, orderEntries } from './chart-frame-layout'
+import { useChartMetrics, useCoarsePointer } from './chart-tier'
 
 export type LegendEntry = {
   key: string
@@ -51,43 +54,77 @@ const LEGEND_ITEM_BUTTON: CSSProperties = {
   textAlign: 'inherit',
 }
 
-const GROUP_ORDER: SeriesRole[] = ['series', 'overlay', 'reference']
-
 /** Stable empty set — a fresh `new Set()` default would be a new identity on every render. */
 const NO_HIDDEN: ReadonlySet<string> = new Set()
 
-const roleOf = (item: LegendEntry): SeriesRole => item.role ?? 'series'
+const DISCLOSURE_PANEL: CSSProperties = {
+  position: 'fixed',
+  zIndex: VX.zIndexFloating,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: LEGEND_ROW_GAP,
+  // theme-allow raw-scroll-container — a fixed floating panel of one legend, not app chrome
+  overflowY: 'auto',
+  // `<dialog open>` brings UA chrome (centring margin, border, fit-content box) this resets.
+  margin: 0,
+  border: 'none',
+  width: 'auto',
+  height: 'auto',
+  padding: 10,
+  boxSizing: 'border-box',
+  backgroundColor: VX.surface.overlay,
+  boxShadow: VX.shadowOverlay,
+  color: VX.muted,
+  borderRadius: VX.radiusCard,
+}
 
-/** Order entries series → overlay → reference and record where a divider belongs. */
-function orderEntries(
-  items: LegendEntry[],
-  groups: boolean,
-): { entries: LegendEntry[]; dividerAfter: Set<number> } {
-  if (!groups) return { entries: items, dividerAfter: new Set() }
+/** A popover never collapses below one usable row, however little room the chip leaves. */
+const DISCLOSURE_MIN_HEIGHT = 96
 
-  const dividerAfter = new Set<number>()
-  const entries: LegendEntry[] = []
-  const nonEmptyGroups = GROUP_ORDER.map((role) =>
-    items.filter((item) => roleOf(item) === role),
-  ).filter((group) => group.length > 0)
-  nonEmptyGroups.forEach((group, i) => {
-    entries.push(...group)
-    if (i < nonEmptyGroups.length - 1) dividerAfter.add(entries.length - 1)
-  })
-  return { entries, dividerAfter }
+/** A popover hangs off its chip (flipping above when there is no room below); a sheet is docked. */
+function disclosurePlacement(chip: DOMRect, coarse: boolean): CSSProperties {
+  if (coarse) {
+    return {
+      left: 0,
+      right: 0,
+      bottom: 0,
+      maxHeight: '60dvh',
+      borderBottomLeftRadius: 0,
+      borderBottomRightRadius: 0,
+      padding: '12px 16px calc(12px + env(safe-area-inset-bottom, 0px))',
+    }
+  }
+  const below = window.innerHeight - chip.bottom
+  const left = Math.max(8, Math.min(chip.left, window.innerWidth - 248))
+  const base = { left, right: 'auto', minWidth: 200, maxWidth: 'calc(100vw - 16px)' }
+  return below >= 200 || below >= chip.top
+    ? { ...base, top: chip.bottom + 4, maxHeight: Math.max(below - 12, DISCLOSURE_MIN_HEIGHT) }
+    : {
+        ...base,
+        bottom: window.innerHeight - chip.top + 4,
+        maxHeight: Math.max(chip.top - 12, DISCLOSURE_MIN_HEIGHT),
+      }
 }
 
-function wrapperStyle(placement: LegendPlacement, fontSize: number): CSSProperties {
+function wrapperStyle(placement: LegendPlacement, fontSize: number, dots: boolean): CSSProperties {
   const vertical = placement === 'left' || placement === 'right'
+  const gap = dots ? DOTS_HIT_GAP : VX.legendGap
   return {
     display: 'flex',
     flexDirection: vertical ? 'column' : 'row',
     flexWrap: vertical ? 'nowrap' : 'wrap',
     alignItems: vertical ? 'flex-start' : 'center',
-    justifyContent: vertical ? 'flex-start' : 'center',
-    columnGap: VX.legendGap,
-    rowGap: VX.legendGap,
-    padding: '8px 0 2px',
+    justifyContent: 'flex-start',
+    columnGap: gap,
+    // Always the tight row gap (R2C-9): the wider dots COLUMN gap is a hit-overlap cap, not
+    // breathing room between wrapped rows — a dots-mode header legend is 1 row by law
+    // (`LEGEND_ROWS.header` in `chart-layout.ts`) anyway, so this only ever shows in the band.
+    rowGap: LEGEND_ROW_GAP,
+    // Caps each entry's `[data-basalt-hit]` overlay at the real inter-entry gap (styles.css).
+    ...({ '--vx-hit-gap': `${gap}px` } as CSSProperties),
+    // A dots-mode row has no text baseline to breathe around — the header-fold law (wave 8) is
+    // the reason this row exists at all, so it gets the same tight treatment.
+    padding: dots ? '4px 0 2px' : '8px 0 2px',
     fontSize,
     color: VX.muted,
   }
@@ -205,6 +242,27 @@ const LEGEND_CHILD_STYLE: CSSProperties = {
   opacity: 0.75,
 }
 
+/**
+ * The whole entry collapses to its color, in 'dots' mode (`docs/CHARTS-SPEC.md` §5: a short or
+ * `compact`-container header has no room for a text label per entry) — a plain 8px circle
+ * regardless of the series' own shape, since a two-tone `split`/`splitLine` swatch cannot express
+ * two colors in one dot. The name survives via the button's own `aria-label`; sighted users get
+ * color-coded identity only, same trade the `compact` container class already made for the y axis.
+ */
+function LegendDot({ item }: { item: LegendEntry }) {
+  return (
+    <span
+      style={{
+        width: LEGEND_DOT_SIZE,
+        height: LEGEND_DOT_SIZE,
+        borderRadius: '50%', // theme-allow raw-surface — a circle shape, not a surface corner
+        backgroundColor: item.color,
+        flexShrink: 0,
+      }}
+    />
+  )
+}
+
 /** Compact swatch for a folded child entry — smaller than {@link LegendSwatch}, line/bar only
  * (folded companions are simple line or bar series; `split`/`splitLine` never fold). */
 function LegendChildSwatch({ item }: { item: LegendEntry }) {
@@ -256,24 +314,19 @@ function LegendChild({ item }: { item: LegendEntry }) {
  * static legends without hover interactivity. `chartId` namespaces `split` clipPath ids so two
  * legends on the same page never collide. `groups` renders series → hairline divider → overlay →
  * reference bands instead of one flat smear. `maxRows` caps the number of rendered ENTRIES and
- * rolls the remainder into a `+N more` chip — it is an entry count, not a row count, in spite of
- * the name (`entries.slice(0, cap)` below is the whole of it, and `ChartFrame` measures rows for a
- * different purpose in `legendEntryCap`). The name is inherited and reaches the public
- * `ChartTierMetrics.legendMaxRows`, so it stays until a minor can rename both.
+ * rolls the remainder into an `All N` disclosure chip — it is an entry count, not a row count, in
+ * spite of the name (`entries.slice(0, cap)` below is the whole of it). `ChartFrame` derives the
+ * cap from the measured fit (`resolveChartLayout().legend`); a caller-stated value wins.
  *
  * `onToggle` makes an entry a real toggle: clicking it hides the series in the plot, the tooltip,
  * and the auto y-domain together (`ChartFrame` owns the `hidden` set — see `docs/CHARTS-SPEC.md`
- * §5).
+ * §5). A hidden entry is announced via `aria-pressed`.
  *
- * The label font and the DEFAULT entry cap both track the ambient chart tier (§8): inside a
- * phone-width `ChartFrame` the legend drops one type step and rolls up past two entries. An
- * explicit `maxRows` always wins. Omit it for a static legend; a hidden entry is announced via `aria-pressed`.
- *
- * **The rollup is a disclosure, not a label.** A cap of two leaves six of eight plotted colours
- * unnamed, and a `+6 more` that is a `<span>` gives a phone reader no way to learn them — a
- * categorical encoding the chart draws and refuses to decode. The chip is a `<button>` carrying
- * `aria-expanded`: expanded, every entry renders, the legend band grows, and `ChartFrame`'s
- * observer re-flows the frame around it (the plot keeps `VX.minPlotHeight`).
+ * **The rollup is a disclosure, not a label.** `All N` is a `<button>` carrying `aria-expanded`
+ * that opens EVERY entry, toggles included, in a popover under the chip on a fine pointer and a
+ * bottom sheet on a coarse one. Both are fixed-position and portalled, so opening one never grows
+ * the legend band or moves the plot. Escape, an outside press, a scroll or a resize closes it, and
+ * focus returns to the chip on every close.
  */
 export function ChartLegend({
   items,
@@ -285,6 +338,7 @@ export function ChartLegend({
   placement = 'bottom',
   groups = false,
   maxRows,
+  mode = 'chips',
   className,
   style,
 }: BasaltProps & {
@@ -299,40 +353,119 @@ export function ChartLegend({
   placement?: LegendPlacement
   groups?: boolean
   maxRows?: number
+  /**
+   * `'dots'` collapses every VISIBLE entry to a plain color dot with no label (the name still
+   * reaches assistive tech via `aria-label`) — `resolveChartLayout`'s header-slot legend forces
+   * this for a short `ChartCard` (wave 11, `docs/CHARTS-SPEC.md` §5) so the legend band's height and
+   * width both shrink before it eats plot space. The `All N` disclosure panel is unaffected: it
+   * always shows the full swatch + label, `mode` only governs the inline row. Default `'chips'`
+   * (today's swatch + label rendering) for every other caller.
+   */
+  mode?: 'dots' | 'chips'
 }) {
-  const tier = useChartTierMetrics()
-  const [expanded, setExpanded] = useState(false)
-  const handleEnter = (e: MouseEvent<HTMLButtonElement> | FocusEvent<HTMLButtonElement>) => {
-    const key = e.currentTarget.dataset['legendKey']
-    if (key !== undefined) onHighlight?.(key)
+  const tier = useChartMetrics()
+  const coarse = useCoarsePointer()
+  const [disclosure, setDisclosure] = useState<CSSProperties | null>(null)
+  // Whichever button opened the panel — the `All N` chip, or (dots mode) any entry — so focus
+  // returns to where the user actually tapped, not to a fixed chip that might not exist.
+  const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const panelRef = useRef<HTMLDialogElement>(null)
+  const open = disclosure !== null
+
+  const panelId = useId()
+  const wasOpen = useRef(false)
+
+  const openDisclosure = (trigger: HTMLButtonElement) => {
+    triggerRef.current = trigger
+    setDisclosure(disclosurePlacement(trigger.getBoundingClientRect(), coarse))
   }
+
+  // Focus moves into the panel on open and back to the trigger on EVERY close path.
+  useEffect(() => {
+    if (open) panelRef.current?.focus()
+    else if (wasOpen.current) triggerRef.current?.focus()
+    wasOpen.current = open
+  }, [open])
+
+  // The panel is fixed to where the trigger WAS — a scroll outside it (any scroller, hence capture)
+  // or a resize leaves it hanging off nothing; the panel's own scroll is not one. Shared with the
+  // chart cursors' own outside-dismiss (`useChartCursor`/`useDiscreteCursor`, see `touch-pin.ts`).
+  const isInsidePanel = useCallback(
+    (target: Node): boolean =>
+      panelRef.current?.contains(target) === true || triggerRef.current?.contains(target) === true,
+    [],
+  )
+  useDismissOnOutside({
+    enabled: open,
+    isInside: isInsidePanel,
+    onDismiss: () => setDisclosure(null),
+    dismissOnResize: true,
+    scrollExemptInside: true,
+  })
+
+  // The coarse sheet claims `aria-modal` (below), which is a claim that Tab cannot leave it — a
+  // native `<dialog open>` (no `showModal()`) does not enforce that on its own (B14). Wrap Tab at
+  // the panel's own first/last focusable rather than the fine popover, which is dismissed by an
+  // outside click/Escape just as easily and never claimed to be modal in the first place.
+  useEffect(() => {
+    if (!open || !coarse) return
+    const panel = panelRef.current
+    if (panel === null) return
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return
+      const focusable = panel.querySelectorAll<HTMLElement>(
+        'button, [tabindex]:not([tabindex="-1"])',
+      )
+      const first = focusable[0]
+      const last = focusable[focusable.length - 1]
+      if (first === undefined || last === undefined) return
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+    panel.addEventListener('keydown', onKeyDown)
+    return () => panel.removeEventListener('keydown', onKeyDown)
+  }, [open, coarse])
+
+  const handleEnter = (key: string) => onHighlight?.(key)
   const handleLeave = () => onHighlight?.(null)
-  const handleToggle = (e: MouseEvent<HTMLButtonElement>) => {
-    const key = e.currentTarget.dataset['legendKey']
-    if (key !== undefined) onToggle?.(key)
-  }
 
   const idPrefix = chartId ? `${chartId}-` : ''
   const vertical = placement === 'left' || placement === 'right'
   const { entries, dividerAfter } = orderEntries(items, groups)
-  const cap = maxRows ?? tier.legendMaxRows
-  const rolledUp = cap === undefined ? 0 : Math.max(entries.length - cap, 0)
-  const visible = rolledUp > 0 && !expanded ? entries.slice(0, cap) : entries
+  const rolledUp = maxRows === undefined ? 0 : Math.max(entries.length - maxRows, 0)
+  const visible = rolledUp > 0 ? entries.slice(0, maxRows) : entries
 
-  const nodes: ReactNode[] = []
-  visible.forEach((item, i) => {
-    nodes.push(
+  // The disclosure panel is a second copy of the same entries: it gets its own id namespace and
+  // no `data-legend-key`, so a page query for the band's entries never finds the panel's twins.
+  const entryButton = (item: LegendEntry, inPanel = false): ReactNode => {
+    // A dots-mode entry names nothing on its own face — its whole point is the color — so a tap
+    // opens the same All-N sheet the overflow chip does, rather than silently hiding a series the
+    // reader was trying to identify (R2C-8: "what is this?" used to toggle it off instead). Gated
+    // on `mode` alone: with `legend.toggle: false` (no `onToggle`) a dots entry still has no OTHER
+    // way to name itself, so it still needs the title + disclosure — `onToggle !== undefined` used
+    // to suppress both just because toggling happened to be off.
+    const isDotTrigger = !inPanel && mode === 'dots'
+    return (
       <button
         key={item.key}
         type="button"
-        data-legend-key={item.key}
+        data-basalt-hit
+        {...(!inPanel && { 'data-legend-key': item.key })}
         // The note is the whole point for a series that is invisible in the plot, so it has to
         // reach a screen reader too — an explicit aria-label would otherwise replace it.
         aria-label={item.note ? `${item.label} — ${item.note}` : item.label}
-        {...(onToggle !== undefined && { 'aria-pressed': !hidden.has(item.key) })}
+        {...(isDotTrigger && { title: item.label, 'aria-haspopup': 'dialog' as const })}
+        {...(isDotTrigger
+          ? { 'aria-expanded': open, 'aria-controls': panelId }
+          : onToggle !== undefined && { 'aria-pressed': !hidden.has(item.key) })}
         style={{
           ...LEGEND_ITEM_BUTTON,
-          cursor: onToggle === undefined ? 'default' : 'pointer',
+          cursor: onToggle === undefined && !isDotTrigger ? 'default' : 'pointer',
           // Toggled-off wins over hover-dimming: a hidden series must read as hidden even while
           // it is the one being hovered.
           opacity: hidden.has(item.key)
@@ -342,20 +475,33 @@ export function ChartLegend({
               : 0.3,
           textDecoration: hidden.has(item.key) ? 'line-through' : 'none',
         }}
-        {...(onToggle !== undefined && { onClick: handleToggle })}
-        onMouseEnter={handleEnter}
+        {...(isDotTrigger
+          ? { onClick: (e: MouseEvent<HTMLButtonElement>) => openDisclosure(e.currentTarget) }
+          : onToggle !== undefined && { onClick: () => onToggle(item.key) })}
+        onMouseEnter={() => handleEnter(item.key)}
         onMouseLeave={handleLeave}
-        onFocus={handleEnter}
+        onFocus={() => handleEnter(item.key)}
         onBlur={handleLeave}
       >
-        <LegendSwatch item={item} idPrefix={idPrefix} />
-        <span>{item.label}</span>
-        {item.note ? <span style={LEGEND_NOTE_STYLE}>{item.note}</span> : null}
-        {item.children?.map((child) => (
-          <LegendChild key={child.key} item={child} />
-        ))}
-      </button>,
+        {!inPanel && mode === 'dots' ? (
+          <LegendDot item={item} />
+        ) : (
+          <>
+            <LegendSwatch item={item} idPrefix={inPanel ? `${idPrefix}disclosure-` : idPrefix} />
+            <span>{item.label}</span>
+            {item.note ? <span style={LEGEND_NOTE_STYLE}>{item.note}</span> : null}
+            {item.children?.map((child) => (
+              <LegendChild key={child.key} item={child} />
+            ))}
+          </>
+        )}
+      </button>
     )
+  }
+
+  const nodes: ReactNode[] = []
+  visible.forEach((item, i) => {
+    nodes.push(entryButton(item))
     if (dividerAfter.has(i))
       nodes.push(<LegendDivider key={`divider-${item.key}`} columnLayout={vertical} />)
   })
@@ -364,11 +510,14 @@ export function ChartLegend({
       <button
         key="legend-more"
         type="button"
-        aria-expanded={expanded}
-        onClick={() => setExpanded((prev) => !prev)}
+        data-basalt-hit
+        aria-expanded={open}
+        aria-haspopup="dialog"
+        aria-controls={panelId}
+        onClick={(e) => (open ? setDisclosure(null) : openDisclosure(e.currentTarget))}
         style={{ ...LEGEND_ITEM_BUTTON, cursor: 'pointer', textDecoration: 'underline' }}
       >
-        {expanded ? 'Show less' : `+${rolledUp} more`}
+        {`All ${entries.length}`}
       </button>,
     )
   }
@@ -376,9 +525,44 @@ export function ChartLegend({
   return (
     <div
       {...(className !== undefined && { className })}
-      style={{ ...wrapperStyle(placement, tier.legendFontSize), ...style }}
+      style={{ ...wrapperStyle(placement, tier.legendFontSize, mode === 'dots'), ...style }}
     >
       {nodes}
+      {open &&
+        createPortal(
+          <>
+            {coarse && (
+              <div
+                aria-hidden
+                onPointerDown={(e) => {
+                  e.stopPropagation()
+                  setDisclosure(null)
+                }}
+                style={{
+                  position: 'fixed',
+                  inset: 0,
+                  // One below the panel it sits behind — still `VX.zIndexFloating`-derived, never a
+                  // second unrelated literal (B14).
+                  zIndex: VX.zIndexFloating - 1,
+                  backgroundColor: alpha(VX.neutral, 0.35),
+                }}
+              />
+            )}
+            <dialog
+              ref={panelRef}
+              id={panelId}
+              open
+              tabIndex={-1}
+              aria-label="Legend"
+              {...(coarse && { 'aria-modal': true })}
+              data-basalt-legend-disclosure={coarse ? 'sheet' : 'popover'}
+              style={{ ...DISCLOSURE_PANEL, fontSize: tier.legendFontSize, ...disclosure }}
+            >
+              {entries.map((item) => entryButton(item, true))}
+            </dialog>
+          </>,
+          document.body,
+        )}
     </div>
   )
 }

package/src/charts/primitives/ChartTooltip.tsx

@@ -3,7 +3,7 @@ import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react'
 import { createPortal } from 'react-dom'
 import { VX } from '../../tokens'
 import { fmtTooltipDate } from '../utils/format'
-import { useChartTierMetrics } from './chart-tier'
+import { useChartMetrics } from './chart-tier'
 
 // Panel bg + shadow-card, radius 8 (docs/DESIGN-SPEC.md §5's "Tooltip/popover/menu" idiom) — the
 // same depth-via-shadow treatment as ChartCard, never a `border` property. Surfaces resolve per
@@ -11,7 +11,7 @@ import { useChartTierMetrics } from './chart-tier'
 const TOOLTIP_STYLES: CSSProperties = {
   position: 'fixed',
   pointerEvents: 'none',
-  zIndex: 9999,
+  zIndex: VX.zIndexFloating,
   backgroundColor: VX.surface.panel,
   borderRadius: 'var(--vx-radius-floating)',
   padding: '0',
@@ -191,7 +191,7 @@ export function ChartTooltipFloat({
   const ref = useRef<HTMLDivElement>(null)
   const [box, setBox] = useState<{ width: number; height: number } | null>(null)
   const isClient = useIsClient()
-  const { tooltipMinWidth } = useChartTierMetrics()
+  const { tooltipMinWidth } = useChartMetrics()
 
   useLayoutEffect(() => {
     const el = ref.current
@@ -215,6 +215,11 @@ export function ChartTooltipFloat({
   const vw = window.innerWidth
   const vh = window.innerHeight
 
+  // An anchor outside the viewport means the chart that owns it has scrolled off-screen. Clamping
+  // would paint a follower's box over unrelated chrome (the bottom nav — `R2C-3`); render nothing
+  // instead.
+  if (anchor.y < 0 || anchor.y > vh) return null
+
   const flipsLeft = anchor.x + TOOLTIP_GAP + width + VIEWPORT_MARGIN > vw
   const left = flipsLeft
     ? Math.max(VIEWPORT_MARGIN, anchor.x - TOOLTIP_GAP - width)

package/src/charts/primitives/Crosshair.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react'
 import { VX } from '../../tokens'
-import { useChartTierMetrics } from './chart-tier'
+import { useChartMetrics } from './chart-tier'
 
 /**
  * The shared vertical hover crosshair — one implementation for what used to be five hand-rolled
@@ -38,6 +38,6 @@ export function SeriesDot({
   color: string
   r?: number
 }): ReactNode {
-  const { dotR } = useChartTierMetrics()
+  const { dotR } = useChartMetrics()
   return <circle cx={cx} cy={cy} r={r ?? dotR} fill={color} stroke={VX.dotStroke} strokeWidth={2} />
 }

package/src/charts/primitives/HoverOverlay.module.css

@@ -0,0 +1,13 @@
+/*
+ * `HoverOverlay` — the transparent plot rect every cartesian kind scrubs through. A tap focuses it
+ * on pointerdown, so the UA's own outline would ring the whole plot on every phone tap (`R2C-15`);
+ * keyboard focus keeps a VX accent inset instead.
+ */
+.overlay {
+  outline: none;
+}
+
+.overlay:focus-visible {
+  outline: 1px solid var(--vx-accent);
+  outline-offset: -1px;
+}

package/src/charts/primitives/HoverOverlay.module.css.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Typed CSS-module declaration — named string props, so dot access stays verbatim under the
+ * package's strict flags.
+ */
+declare const classes: {
+  readonly overlay: string
+}
+export default classes

package/src/charts/primitives/HoverOverlay.tsx

@@ -1,4 +1,5 @@
 import type { FocusEventHandler, KeyboardEventHandler, PointerEventHandler } from 'react'
+import styles from './HoverOverlay.module.css'
 
 /**
  * Transparent <rect> that captures pointer events (mouse + touch + pen) for tooltip + crosshair
@@ -11,6 +12,8 @@ export function HoverOverlay({
   width,
   height,
   onMove,
+  onDown,
+  onUp,
   onLeave,
   onKeyDown,
   onBlur,
@@ -22,6 +25,11 @@ export function HoverOverlay({
   width: number
   height: number
   onMove: PointerEventHandler<SVGRectElement>
+  /** Coarse-pointer tap: resolves + shows the tooltip immediately, with no preceding `pointermove`
+   * (`docs/CHARTS-SPEC.md` §4, Tooltip). The press is provisional; `onUp` commits it. */
+  onDown?: PointerEventHandler<SVGRectElement>
+  /** Commits the provisional touch press so the pin survives the lift. */
+  onUp?: PointerEventHandler<SVGRectElement>
   onLeave: PointerEventHandler<SVGRectElement>
   /** Present = the overlay is focusable and scrubs on ←/→. */
   onKeyDown?: KeyboardEventHandler<SVGRectElement>
@@ -35,7 +43,12 @@ export function HoverOverlay({
   valueText?: string
 }) {
   return (
+    // `touch-action: pan-y` lives on the plot's `<svg>` (each kind's own), NOT here: Chrome ignores
+    // `touch-action` on an SVG child `<rect>`, so the browser claims a horizontal pan and cancels
+    // the pointer (`R2C-2`). The `overlay` class owns the focus ring: no UA outline on tap, a VX
+    // accent inset under `:focus-visible` (`R2C-15`).
     <rect
+      className={styles.overlay}
       width={width}
       height={height}
       fill="transparent"
@@ -54,11 +67,9 @@ export function HoverOverlay({
         onKeyDown,
         ...(onBlur !== undefined && { onBlur }),
       })}
-      // `pan-y`, not `none`: `none` would turn a full-width chart into a scroll dead zone on a
-      // phone. `pan-y` lets vertical page scroll pass through while a horizontal drag still
-      // reaches this overlay to scrub the chart.
-      style={{ touchAction: 'pan-y' }}
       onPointerMove={onMove}
+      {...(onDown !== undefined && { onPointerDown: onDown })}
+      {...(onUp !== undefined && { onPointerUp: onUp })}
       onPointerLeave={onLeave}
       onPointerCancel={onLeave}
     />

package/src/charts/primitives/chart-card-context.ts

@@ -0,0 +1,37 @@
+import { createContext } from 'react'
+
+/**
+ * `ChartCard`'s internal context: `inCard` (a frame inside a card treats its computed height as a
+ * MINIMUM and grows into the card body), the legend slot — the empty header-row box a chart will portal its legend into
+ * (`docs/CHARTS-SPEC.md` §5, Legend), so a card has one chrome band, not two — and `short`, the same
+ * `measuredHeight < CARD_SHORT_HEIGHT` flag `ChartCard` already computes for the header-fold law
+ * (`data-basalt-card-short`), threaded through so `ChartFrame` can fold its header-slot legend to
+ * 'dots' before it eats the plot floor (`docs/CHARTS-SPEC.md` §5, wave 11). `null`/`false` until the slot
+ * mounts, and outside any card. Deliberately not exported from any barrel.
+ *
+ * `claimLegendSlot`/`releaseLegendSlot` arbitrate the slot when a card hosts more than one
+ * `ChartFrame` (`docs/waves/PLAN.md` wave 3, P2-9): the first frame to claim an id keeps it for as
+ * long as it holds it, every later claimant is told no and falls back to its own band legend
+ * instead of a second frame silently portalling into the same node. Outside any card there is no
+ * slot to contend for, so the default always grants the claim.
+ *
+ * `legendSlotVersion` bumps every time the owner releases the slot (round 3's carried gap): a
+ * denied frame's claim attempt runs once, in its own mount effect, so with no signal that the slot
+ * freed up it would sit denied forever even after the owning frame unmounts. Frames read it only to
+ * put it in a dependency array — the effect re-running is the entire point, not the number itself.
+ */
+export const ChartCardContext = createContext<{
+  legendSlot: HTMLDivElement | null
+  inCard: boolean
+  short: boolean
+  claimLegendSlot: (id: string) => boolean
+  releaseLegendSlot: (id: string) => void
+  legendSlotVersion: number
+}>({
+  legendSlot: null,
+  inCard: false,
+  short: false,
+  claimLegendSlot: () => true,
+  releaseLegendSlot: () => {},
+  legendSlotVersion: 0,
+})