basalt-ui 1.31.0 → 1.32.1

package/src/charts/primitives/ChartCard.tsx

@@ -12,7 +12,7 @@
  * The header renders only when at least one of title/info/value/actions/icon/count is set — ending
  * the `''`-as-hidden-header sentinel a consumer used to reach for otherwise.
  */
-import { useCallback, useMemo, useRef, useState } from 'react'
+import { useMemo, useReducer, useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
 import { cx } from '../../common/props'
 import type { BasaltProps, SlotStylesProps } from '../../common/props'
@@ -21,7 +21,7 @@ import { WidgetHeader } from '../../dashboard/widget-header'
 import type { DeltaPolarity } from '../../dashboard/delta-badge'
 import { useChartSize } from '../hooks/useChartSize'
 import { useHysteresis } from '../hooks/use-hysteresis'
-import { ChartCardContext } from './chart-card-context'
+import { ChartCardContext, legendSlotReducer } from './chart-card-context'
 import { ChartEmpty, ChartError, ChartPending, resolveChartState } from './ChartPending'
 import type { ChartState } from './ChartPending'
 
@@ -212,32 +212,10 @@ export function ChartCard({
     false,
   )
 
-  const legendOwnerRef = useRef<string | null>(null)
-  // Bumped on every release so a previously-denied sibling's claim effect (keyed on the context
-  // value it reads, see `chart-card-context.ts`) re-runs and gets a chance to re-claim the slot the
-  // owner just gave up — without it a frame told "no" once stayed denied even after the owner
-  // unmounted.
-  const [legendSlotVersion, setLegendSlotVersion] = useState(0)
-  const claimLegendSlot = useCallback((id: string) => {
-    if (legendOwnerRef.current === null) legendOwnerRef.current = id
-    return legendOwnerRef.current === id
-  }, [])
-  const releaseLegendSlot = useCallback((id: string) => {
-    if (legendOwnerRef.current === id) {
-      legendOwnerRef.current = null
-      setLegendSlotVersion((v) => v + 1)
-    }
-  }, [])
+  const [legendClaimants, dispatchLegendSlot] = useReducer(legendSlotReducer, [])
   const context = useMemo(
-    () => ({
-      legendSlot,
-      inCard: true,
-      short,
-      claimLegendSlot,
-      releaseLegendSlot,
-      legendSlotVersion,
-    }),
-    [legendSlot, short, claimLegendSlot, releaseLegendSlot, legendSlotVersion],
+    () => ({ legendSlot, inCard: true, short, legendClaimants, dispatchLegendSlot }),
+    [legendSlot, short, legendClaimants],
   )
 
   return (

package/src/charts/primitives/ChartFrame.tsx

@@ -1,5 +1,5 @@
 import type { CSSProperties, ReactNode } from 'react'
-import { useCallback, useContext, useId, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { useCallback, useContext, useId, useLayoutEffect, useMemo, useState } from 'react'
 import { createPortal } from 'react-dom'
 import type { BasaltProps } from '../../common/props'
 import {
@@ -228,93 +228,55 @@ export function ChartFrame({
     inCard,
     legendSlot,
     short: cardShort,
-    claimLegendSlot,
-    releaseLegendSlot,
-    legendSlotVersion,
+    legendClaimants,
+    dispatchLegendSlot,
   } = useContext(ChartCardContext)
   const frameId = useId()
-  const [ownsSlot, setOwnsSlot] = useState(false)
   const [slotSeedW, setSlotSeedW] = useState(0)
-  // Mirrors `ownsSlot` synchronously so the retry effect below can read "do I currently own the
-  // slot" without waiting a render for the state to catch up — see the two effects' own doc.
-  const ownsSlotRef = useRef(false)
   const placement = legend === false ? 'bottom' : (legend.placement ?? 'bottom')
   const vertical = placement === 'left' || placement === 'right'
   // `Donut` sets `headerSlot: false` (P1-4) — it never wants the slot, so it must never CLAIM it
   // either, or it would silently deny a sibling frame in the same card that does want it. A
   // vertical (left/right) legend never portals into the header either (`inHeader` below requires
   // `!vertical`), so it must not claim the slot from a sibling that could actually use it.
-  const wantsHeaderSlot = legend !== false && legend.headerSlot !== false && !vertical
+  const wantsHeaderSlot =
+    legendSlot !== null && legend !== false && legend.headerSlot !== false && !vertical
   // Every non-null state replaces the plot, and all three suppress the legend for one reason: a
-  // legend naming a series with nothing to point at is its own small lie. Computed here (ahead of
-  // the claim effect below) only because that effect's own dev warning needs it.
+  // legend naming a series with nothing to point at is its own small lie.
   const resolvedState = resolveChartState({ ...(state !== undefined && { state }), isPending })
   const legendVisible = legend !== false && resolvedState === null
-  // The card's header slot is observed like the frame is: its width is what a header legend fits.
-  // Only the frame that CLAIMS the slot (first to mount, P2-9) observes it or seeds its width — a
-  // second frame in the same card never measures a slot it will not portal into. The contention
-  // warning is reported HERE, from the deterministic `owns` this effect just computed, rather than
-  // as a separate reactive check on `ownsSlot` state — that state takes one extra render to catch up
-  // with the claim, and a passive effect reacting to the interim (stale) value warned about frames
-  // that went on to win the claim one render later.
-  // One claim attempt, shared by the owner effect below (real identity changes) and the
-  // denied-frame retry effect further down (a sibling's release). Reads `legendVisible` at CALL
-  // time through the closure, not through a dependency array of its own effect, so the two callers
-  // stay free to key on whatever triggers each of them.
-  const tryClaim = useCallback((): boolean => {
-    if (legendSlot === null || !wantsHeaderSlot) return false
-    const owns = claimLegendSlot(frameId)
-    ownsSlotRef.current = owns
-    setOwnsSlot(owns)
-    if (!owns) {
-      setSlotSeedW(0)
-      if (legendVisible) reportOnce('ChartFrame', legendSlotContention('ChartFrame'))
-      return false
-    }
-    // Seeded synchronously (P2-8) so the very first commit already knows the slot's real width,
-    // instead of assuming 0 until the ResizeObserver's first (asynchronous) callback — which is
-    // what let a header legend paint once in the band before jumping to the header on every mount.
+  // Ownership is DERIVED from the card's claimant queue (`legendSlotReducer`), never mirrored here:
+  // the first frame to claim owns the slot, a later one is denied until everything ahead of it
+  // releases, and each frame's only job is to claim while it wants the slot and release on the way
+  // out (P2-9).
+  //
+  // Denied means THIS frame's own claim is in the queue and is not its head — never "someone else
+  // owns it" read before this frame has claimed. A new frame's first render can still see an
+  // owner that is unmounting in the same commit (a tab switch, a different `useId`); that is a
+  // hand-off, and warning off that stale head reported contention for a frame about to own it.
+  const ownsSlot = wantsHeaderSlot && legendClaimants[0] === frameId
+  const slotDenied = wantsHeaderSlot && !ownsSlot && legendClaimants.includes(frameId)
+  useLayoutEffect(() => {
+    if (!wantsHeaderSlot) return undefined
+    dispatchLegendSlot({ type: 'claim', id: frameId })
+    return () => dispatchLegendSlot({ type: 'release', id: frameId })
+  }, [wantsHeaderSlot, frameId, dispatchLegendSlot])
+  useLayoutEffect(() => {
+    if (slotDenied && legendVisible) reportOnce('ChartFrame', legendSlotContention('ChartFrame'))
+  }, [slotDenied, legendVisible])
+  // Only the owner observes the slot — its width is what a header legend fits. Seeded synchronously
+  // (P2-8) so the first paint already knows the slot's real width, instead of assuming 0 until the
+  // ResizeObserver's first (asynchronous) callback — which is what let a header legend paint once in
+  // the band before jumping to the header on every mount.
+  useLayoutEffect(() => {
+    if (!ownsSlot || legendSlot === null) return undefined
     setSlotSeedW(legendSlot.getBoundingClientRect().width)
     slotRef(legendSlot)
-    return true
-  }, [legendSlot, wantsHeaderSlot, legendVisible, frameId, claimLegendSlot, slotRef])
-
-  // Releases the slot only if THIS frame currently owns it, read live off `ownsSlotRef` at
-  // cleanup time rather than a snapshot closed over when the effect ran — so it correctly releases
-  // whichever effect (this one's own claim, or the retry effect's) most recently won it.
-  const releaseIfOwned = useCallback(() => {
-    if (!ownsSlotRef.current) return
-    ownsSlotRef.current = false
-    releaseLegendSlot(frameId)
-    slotRef(null)
-  }, [releaseLegendSlot, frameId, slotRef])
-
-  // The OWNER effect: claims/releases only on a real identity change (the slot itself, whether this
-  // frame even wants one, or a remount) — never on `legendSlotVersion`. A prior version keyed this
-  // effect on `legendSlotVersion` too, so the owner's own cleanup (which unconditionally released)
-  // bumped the version, which re-ran this very effect, which released again — an infinite
-  // release → bump → re-run loop that surfaced as "Maximum update depth exceeded" under StrictMode
-  // replay or a `legendVisible` flip. Only a DENIED frame reacts to the version now (below).
-  useLayoutEffect(() => {
-    if (legendSlot === null || !wantsHeaderSlot) {
-      setOwnsSlot(false)
+    return () => {
+      slotRef(null)
       setSlotSeedW(0)
-      return undefined
     }
-    tryClaim()
-    return releaseIfOwned
-  }, [legendSlot, wantsHeaderSlot, tryClaim, releaseIfOwned])
-
-  // The DENIED-frame retry: fires only when the slot's ownership changes elsewhere
-  // (`legendSlotVersion` bumps on a release). A frame that already owns the slot short-circuits via
-  // `ownsSlotRef` — this effect never releases what it claims; the owner effect's `releaseIfOwned`
-  // cleanup (keyed on stable identity, not on this version) is the one place release happens, for
-  // whichever frame currently holds the slot.
-  useLayoutEffect(() => {
-    if (ownsSlotRef.current) return
-    tryClaim()
-    // oxlint-disable-next-line react-hooks/exhaustive-deps
-  }, [legendSlotVersion])
+  }, [ownsSlot, legendSlot, slotRef])
   const viewportClass = useSizeClass()
   // No `BasaltProvider` (a charts-only consumer) means no viewport hint: the unmeasured first frame
   // resolves to the regular (desktop) class, not phone chrome.
@@ -368,7 +330,7 @@ export function ChartFrame({
             'legend.maxRows',
             'nothing (the legend fits by measured width)',
             '1.32.0',
-            'Overflow folds into an `All N` disclosure; an explicit value still wins this release.',
+            `Its UNIT changed from rows to entries: \`maxRows: ${legend.maxRows}\` is now read as a cap of ${legend.maxRows} legend ENTRIES (not rows), with the rest folded into an \`All N\` disclosure. An explicit value still wins this release.`,
           )
         : null,
     [legend, legendItems.length],
@@ -380,7 +342,7 @@ export function ChartFrame({
   // Memoized on scalars (the legend by its keys+labels) so `ChartTierProvider`'s value is stable
   // across renders that change nothing. No slot, not the owner, or not measured yet → `slotW` 0 →
   // a band. `slotSeedW` (P2-8) covers the gap before the ResizeObserver's own first callback.
-  const slotW = legendSlot === null || !ownsSlot ? 0 : Math.max(slotMeasuredW, slotSeedW)
+  const slotW = ownsSlot ? Math.max(slotMeasuredW, slotSeedW) : 0
   const groups = legend !== false && legend.groups === true
   // Role and note both feed the resolver (`orderEntries`'s grouping, `legendEntryWidth`'s measured
   // fit), so a change to either — a series moving `role`, a note appearing/disappearing — has to
@@ -414,8 +376,7 @@ export function ChartFrame({
   const fit = layout.legend.mode === 'dots' || layout.legend.mode === 'chips' ? layout.legend : null
   const legendMode = fit?.mode
   const showLegend = legendVisible && fit !== null
-  const inHeader =
-    showLegend && !vertical && legendSlot !== null && ownsSlot && fit?.where === 'header'
+  const inHeader = showLegend && ownsSlot && fit?.where === 'header'
   const sideLegendWidth = showLegend && vertical ? legendW : 0
   const topBottomLegendHeight = showLegend && !vertical && !inHeader ? legendH : 0
 

package/src/charts/primitives/ChartLegend.tsx

@@ -1,12 +1,10 @@
 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 { DOTS_HIT_GAP, LEGEND_DOT_SIZE, LEGEND_ROW_GAP, orderEntries } from './chart-frame-layout'
 import { useChartMetrics, useCoarsePointer } from './chart-tier'
+import { LegendDisclosure, useLegendDisclosure } from './legend-disclosure'
 
 export type LegendEntry = {
   key: string
@@ -57,55 +55,6 @@ const LEGEND_ITEM_BUTTON: CSSProperties = {
 /** Stable empty set — a fresh `new Set()` default would be a new identity on every render. */
 const NO_HIDDEN: ReadonlySet<string> = new Set()
 
-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,
-}
-
-/** A popover never collapses below one usable row, however little room the chip leaves. */
-const DISCLOSURE_MIN_HEIGHT = 96
-
-/** 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, dots: boolean): CSSProperties {
   const vertical = placement === 'left' || placement === 'right'
   const gap = dots ? DOTS_HIT_GAP : VX.legendGap
@@ -365,71 +314,7 @@ export function ChartLegend({
 }) {
   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 { open, panelId, openFrom, close, panel } = useLegendDisclosure(coarse)
 
   const handleEnter = (key: string) => onHighlight?.(key)
   const handleLeave = () => onHighlight?.(null)
@@ -476,7 +361,7 @@ export function ChartLegend({
           textDecoration: hidden.has(item.key) ? 'line-through' : 'none',
         }}
         {...(isDotTrigger
-          ? { onClick: (e: MouseEvent<HTMLButtonElement>) => openDisclosure(e.currentTarget) }
+          ? { onClick: (e: MouseEvent<HTMLButtonElement>) => openFrom(e.currentTarget) }
           : onToggle !== undefined && { onClick: () => onToggle(item.key) })}
         onMouseEnter={() => handleEnter(item.key)}
         onMouseLeave={handleLeave}
@@ -514,7 +399,7 @@ export function ChartLegend({
         aria-expanded={open}
         aria-haspopup="dialog"
         aria-controls={panelId}
-        onClick={(e) => (open ? setDisclosure(null) : openDisclosure(e.currentTarget))}
+        onClick={(e) => (open ? close() : openFrom(e.currentTarget))}
         style={{ ...LEGEND_ITEM_BUTTON, cursor: 'pointer', textDecoration: 'underline' }}
       >
         {`All ${entries.length}`}
@@ -528,41 +413,9 @@ export function ChartLegend({
       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,
-        )}
+      <LegendDisclosure {...panel} fontSize={tier.legendFontSize}>
+        {entries.map((item) => entryButton(item, true))}
+      </LegendDisclosure>
     </div>
   )
 }

package/src/charts/primitives/ChartTooltip.tsx

@@ -2,6 +2,7 @@ import type { CSSProperties, ReactNode } from 'react'
 import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react'
 import { createPortal } from 'react-dom'
 import { VX } from '../../tokens'
+import type { TooltipRowData } from '../series'
 import { fmtTooltipDate } from '../utils/format'
 import { useChartMetrics } from './chart-tier'
 
@@ -136,6 +137,21 @@ export function TooltipRow({
   )
 }
 
+/** The derived rows (`deriveTooltipRows`), one {@link TooltipRow} each. */
+export function TooltipRows({ rows }: { rows: readonly TooltipRowData[] }) {
+  return rows.map((row) => (
+    <TooltipRow
+      key={row.key}
+      color={row.color}
+      label={row.label}
+      value={row.value}
+      shape={row.shape}
+      dashed={row.dashed}
+      {...(row.strokeWidth !== undefined && { strokeWidth: row.strokeWidth })}
+    />
+  ))
+}
+
 export function TooltipBody({ children }: { children: ReactNode }) {
   return <div style={{ padding: '5px 0' }}>{children}</div>
 }

package/src/charts/primitives/HoverOverlay.tsx

@@ -1,6 +1,30 @@
 import type { FocusEventHandler, KeyboardEventHandler, PointerEventHandler } from 'react'
+import type { ChartCursor } from '../hooks/useChartCursor'
 import styles from './HoverOverlay.module.css'
 
+/** Props of {@link HoverOverlay}. */
+export type HoverOverlayProps = {
+  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>
+  onBlur?: FocusEventHandler<SVGRectElement>
+  ariaLabel?: string
+  /** Index of the focused point — announced as the slider position. */
+  valueNow?: number
+  /** Last index of the domain. */
+  valueMax?: number
+  /** Human-readable label for the focused point (the formatted x key). */
+  valueText?: string
+}
+
 /**
  * Transparent <rect> that captures pointer events (mouse + touch + pen) for tooltip + crosshair
  * sync.
@@ -21,27 +45,7 @@ export function HoverOverlay({
   valueNow,
   valueMax,
   valueText,
-}: {
-  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>
-  onBlur?: FocusEventHandler<SVGRectElement>
-  ariaLabel?: string
-  /** Index of the focused point — announced as the slider position. */
-  valueNow?: number
-  /** Last index of the domain. */
-  valueMax?: number
-  /** Human-readable label for the focused point (the formatted x key). */
-  valueText?: string
-}) {
+}: HoverOverlayProps) {
   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
@@ -75,3 +79,30 @@ export function HoverOverlay({
     />
   )
 }
+
+/**
+ * Everything a FOCUSABLE overlay over indexed data takes besides its rect: the cursor's pointer and
+ * keyboard handlers plus the slider label/position. `CartesianChart`, `DualPanel`'s top pane and
+ * the banded kinds all wire it identically, so it is stated once.
+ */
+export function cursorSliderProps<T>(input: {
+  cursor: ChartCursor<T>
+  data: readonly T[]
+  getX: (d: T) => string
+  formatX: (key: string) => string
+  ariaLabel: string | undefined
+}): Omit<HoverOverlayProps, 'width' | 'height'> {
+  const { cursor, data, getX, formatX, ariaLabel } = input
+  const { point } = cursor
+  return {
+    onMove: cursor.onPointerMove,
+    onDown: cursor.onPointerDown,
+    onUp: cursor.onPointerUp,
+    onLeave: cursor.onPointerLeave,
+    onKeyDown: cursor.onKeyDown,
+    onBlur: cursor.onBlur,
+    valueMax: Math.max(data.length - 1, 0),
+    ...(point !== null && { valueNow: data.indexOf(point), valueText: formatX(getX(point)) }),
+    ...(ariaLabel !== undefined && { ariaLabel }),
+  }
+}

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

@@ -1,4 +1,23 @@
 import { createContext } from 'react'
+import type { Dispatch } from 'react'
+
+/** One frame claiming or releasing the card's header legend slot. */
+export type LegendSlotAction = { type: 'claim' | 'release'; id: string }
+
+/**
+ * The ONE owner of the legend-slot protocol (`docs/waves/PLAN.md` wave 3, P2-9): claimants in claim
+ * order, and the head owns the slot. A later claimant is denied simply by not being the head, and
+ * it takes over the moment everything ahead of it releases — no retry signal, no ownership mirrored
+ * in a ref. Returns the same array on a no-op so a repeated claim/release never re-renders the card.
+ */
+export function legendSlotReducer(
+  claimants: readonly string[],
+  { type, id }: LegendSlotAction,
+): readonly string[] {
+  const held = claimants.includes(id)
+  if (type === 'claim') return held ? claimants : [...claimants, id]
+  return held ? claimants.filter((c) => c !== id) : claimants
+}
 
 /**
  * `ChartCard`'s internal context: `inCard` (a frame inside a card treats its computed height as a
@@ -9,29 +28,19 @@ import { createContext } from 'react'
  * '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.
+ * `legendClaimants` is {@link legendSlotReducer}'s queue (its head owns the slot) and
+ * `dispatchLegendSlot` feeds it. Outside any card there is no slot, so nothing ever claims.
  */
 export const ChartCardContext = createContext<{
   legendSlot: HTMLDivElement | null
   inCard: boolean
   short: boolean
-  claimLegendSlot: (id: string) => boolean
-  releaseLegendSlot: (id: string) => void
-  legendSlotVersion: number
+  legendClaimants: readonly string[]
+  dispatchLegendSlot: Dispatch<LegendSlotAction>
 }>({
   legendSlot: null,
   inCard: false,
   short: false,
-  claimLegendSlot: () => true,
-  releaseLegendSlot: () => {},
-  legendSlotVersion: 0,
+  legendClaimants: [],
+  dispatchLegendSlot: () => {},
 })