basalt-ui 1.30.2 → 1.32.0

package/src/charts/primitives/ChartLegend.tsx

@@ -1,9 +1,10 @@
-import type { CSSProperties, FocusEvent, MouseEvent, ReactNode } from 'react'
-import { useState } from 'react'
+import type { CSSProperties, MouseEvent, ReactNode } from 'react'
 import type { BasaltProps } from '../../common/props'
 import { alpha, VX } from '../../tokens'
 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'
+import { LegendDisclosure, useLegendDisclosure } from './legend-disclosure'
 
 export type LegendEntry = {
   key: string
@@ -51,43 +52,28 @@ 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'
-
-/** 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() }
-
-  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 }
-}
-
-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 +191,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 +263,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 +287,7 @@ export function ChartLegend({
   placement = 'bottom',
   groups = false,
   maxRows,
+  mode = 'chips',
   className,
   style,
 }: BasaltProps & {
@@ -299,40 +302,55 @@ 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 { open, panelId, openFrom, close, panel } = useLegendDisclosure(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 +360,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>) => openFrom(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 +395,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 ? close() : openFrom(e.currentTarget))}
         style={{ ...LEGEND_ITEM_BUTTON, cursor: 'pointer', textDecoration: 'underline' }}
       >
-        {expanded ? 'Show less' : `+${rolledUp} more`}
+        {`All ${entries.length}`}
       </button>,
     )
   }
@@ -376,9 +410,12 @@ export function ChartLegend({
   return (
     <div
       {...(className !== undefined && { className })}
-      style={{ ...wrapperStyle(placement, tier.legendFontSize), ...style }}
+      style={{ ...wrapperStyle(placement, tier.legendFontSize, mode === 'dots'), ...style }}
     >
       {nodes}
+      <LegendDisclosure {...panel} fontSize={tier.legendFontSize}>
+        {entries.map((item) => entryButton(item, true))}
+      </LegendDisclosure>
     </div>
   )
 }

package/src/charts/primitives/ChartTooltip.tsx

@@ -2,8 +2,9 @@ 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 { 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 +12,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',
@@ -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>
 }
@@ -191,7 +207,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 +231,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,29 @@
 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
@@ -11,6 +36,8 @@ export function HoverOverlay({
   width,
   height,
   onMove,
+  onDown,
+  onUp,
   onLeave,
   onKeyDown,
   onBlur,
@@ -18,24 +45,14 @@ export function HoverOverlay({
   valueNow,
   valueMax,
   valueText,
-}: {
-  width: number
-  height: number
-  onMove: 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
+    // 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,13 +71,38 @@ 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}
     />
   )
 }
+
+/**
+ * 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

@@ -0,0 +1,46 @@
+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
+ * 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.
+ *
+ * `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
+  legendClaimants: readonly string[]
+  dispatchLegendSlot: Dispatch<LegendSlotAction>
+}>({
+  legendSlot: null,
+  inCard: false,
+  short: false,
+  legendClaimants: [],
+  dispatchLegendSlot: () => {},
+})