basalt-ui 1.31.0 → 1.32.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: () => {},
 })

package/src/charts/primitives/chart-frame-layout.ts

@@ -286,38 +286,46 @@ const legendEntryWidth = (item: LegendEntry): number =>
   )
 
 /**
- * The greedy chip-width wrap {@link entriesWithinRows} runs — split out so
- * {@link entriesWithinChipRows} can run it a second time against a narrower, reserve-adjusted
- * width without duplicating the wrap arithmetic. `allowZero` (default false) drops the "the first
- * entry always fits" guarantee a bare row-fit needs (a raw width-vs-0 check is meaningless
- * otherwise): without it, the SAME entry the caller is about to also draw an `All N` chip beside
- * would always be counted as fitting even when the two together provably don't.
+ * The ONE greedy wrap every legend fit runs — the same wrap the flex container performs, measured
+ * rather than assumed. Each item costs `widthOf(item)` (plus `gap` after the row's first) and
+ * `extraAfter(i)` more once placed (a group divider is its own flex item). `allowZero` (default
+ * false) drops the "the first entry always fits" guarantee a bare row-fit needs: a reserved pass
+ * (the `All N` chip already took its room) must be able to answer 0, or the SAME entry the caller
+ * is about to draw the chip beside would always count as fitting even when the two provably don't.
  */
-function fitChipRows(
-  items: readonly LegendEntry[],
-  width: number,
-  rows: number,
-  allowZero = false,
+function fitGreedyRows<T>(
+  items: readonly T[],
+  fit: {
+    widthOf: (item: T) => number
+    gap: number
+    width: number
+    rows: number
+    allowZero?: boolean
+    extraAfter?: (index: number) => number
+  },
 ): number {
   let row = 1
   let x = 0
   let fitted = 0
-  for (const item of items) {
-    const w = legendEntryWidth(item)
-    const next = x === 0 ? w : x + VX.legendGap + w
-    if (x === 0 && allowZero && next > width) return 0
-    if (next > width && x > 0) {
+  for (const [i, item] of items.entries()) {
+    const w = fit.widthOf(item)
+    const next = x === 0 ? w : x + fit.gap + w
+    if (x === 0 && fit.allowZero === true && next > fit.width) return 0
+    if (next > fit.width && x > 0) {
       row += 1
-      if (row > rows) return fitted
+      if (row > fit.rows) return fitted
       x = w
     } else {
       x = next
     }
     fitted += 1
+    x += fit.extraAfter?.(i) ?? 0
   }
   return fitted
 }
 
+const chipFit = { widthOf: legendEntryWidth, gap: VX.legendGap }
+
 /** How many of `items` fit in `rows` wrapped rows of `width` — the same greedy wrap the flex
  * container performs, measured rather than assumed (`docs/CHARTS-SPEC.md` §1). */
 export function entriesWithinRows(
@@ -325,7 +333,7 @@ export function entriesWithinRows(
   width: number,
   rows: number,
 ): number {
-  return fitChipRows(items, width, rows)
+  return fitGreedyRows(items, { ...chipFit, width, rows })
 }
 
 /**
@@ -342,44 +350,15 @@ export function entriesWithinChipRows(
   rows: number,
 ): number {
   const total = items.length
-  const fittedNoReserve = fitChipRows(items, width, rows)
+  const fittedNoReserve = entriesWithinRows(items, width, rows)
   if (fittedNoReserve >= total) return fittedNoReserve
   const reserve = measureText(`All ${total}`, VX.legendFontSize) + VX.legendGap
-  return fitChipRows(items, Math.max(width - reserve, 0), rows, true)
-}
-
-/** The greedy dot-pitch wrap `entriesWithinDotRows` runs twice — once optimistically, once against
- * a width that already gave up the `All N` chip's room. A group divider is its own flex item, so it
- * costs one more pitch before the next dot. `allowZero` (default false) mirrors {@link fitChipRows}'s
- * own flag: without it the first dot always counts as fitted regardless of `width`, which is wrong
- * for the reserved pass once reserving has left no usable room at all. */
-function fitDotRows(
-  items: readonly LegendEntry[],
-  width: number,
-  rows: number,
-  dividerAfter: ReadonlySet<number>,
-  allowZero = false,
-): number {
-  let row = 1
-  let x = 0
-  let fitted = 0
-  for (let i = 0; i < items.length; i += 1) {
-    // `DOT_PITCH` already IS one dot's full footprint (its own size plus the gap to a neighbour,
-    // `LEGEND_DOT_SIZE + DOTS_HIT_GAP`) — adding `LEGEND_DOT_SIZE` again here double-counted every
-    // dot after the row's first, wrapping a legend to `All N` well before it actually overflowed.
-    const next = x === 0 ? LEGEND_DOT_SIZE : x + DOT_PITCH
-    if (x === 0 && allowZero && next > width) return 0
-    if (next > width && x > 0) {
-      row += 1
-      if (row > rows) return fitted
-      x = LEGEND_DOT_SIZE
-    } else {
-      x = next
-    }
-    fitted += 1
-    if (dividerAfter.has(i)) x += DOT_PITCH
-  }
-  return fitted
+  return fitGreedyRows(items, {
+    ...chipFit,
+    width: Math.max(width - reserve, 0),
+    rows,
+    allowZero: true,
+  })
 }
 
 /**
@@ -398,11 +377,20 @@ export function entriesWithinDotRows(
   rows: number,
   dividerAfter: ReadonlySet<number> = new Set(),
 ): number {
+  // A dot is `LEGEND_DOT_SIZE` wide and `DOT_PITCH` already IS its full footprint (size plus the
+  // gap to a neighbour) — so the gap is the pitch LESS the dot; adding the dot again double-counted
+  // every dot after the row's first and wrapped to `All N` well before it overflowed.
+  const dotFit = {
+    widthOf: () => LEGEND_DOT_SIZE,
+    gap: DOT_PITCH - LEGEND_DOT_SIZE,
+    rows,
+    extraAfter: (i: number) => (dividerAfter.has(i) ? DOT_PITCH : 0),
+  }
   const total = items.length
-  const fittedNoReserve = fitDotRows(items, width, rows, dividerAfter)
+  const fittedNoReserve = fitGreedyRows(items, { ...dotFit, width })
   if (fittedNoReserve >= total) return fittedNoReserve
   const reserve = measureText(`All ${total}`, VX.legendFontSize) + DOT_PITCH
-  return fitDotRows(items, Math.max(width - reserve, 0), rows, dividerAfter, true)
+  return fitGreedyRows(items, { ...dotFit, width: Math.max(width - reserve, 0), allowZero: true })
 }
 
 /**