basalt-ui 1.30.2 → 1.32.0

package/src/charts/kinds/BandStrip.tsx

@@ -8,21 +8,15 @@ import type { ChartMargin } from '../../tokens'
 import type { CursorResolution } from '../cursor/resolve'
 import { useBandPlot } from '../hooks/useBandPlot'
 import type { BandFold, BandTooltipConfig } from '../hooks/useBandPlot'
-import { AxisBottomDate } from '../primitives/Axes'
 import { ChartFrame, resolveLegend } from '../primitives/ChartFrame'
 import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
-import {
-  ChartTooltipFloat,
-  TooltipBody,
-  TooltipHeader,
-  TooltipRow,
-} from '../primitives/ChartTooltip'
+import { TooltipRow } from '../primitives/ChartTooltip'
 import { Crosshair } from '../primitives/Crosshair'
 import { HatchPattern, hatchFill, hatchSizeFor } from '../primitives/HatchPattern'
-import { HoverOverlay } from '../primitives/HoverOverlay'
 import type { ChartState } from '../primitives/ChartPending'
 import type { ChartLegendConfig, SeriesStyle } from '../series'
 import { fmtAxisDate } from '../utils/format'
+import { BandAxisOverlay, BandTooltip, clampFraction } from './band-chrome'
 import { isDev } from '../../common/is-dev'
 
 /**
@@ -256,7 +250,7 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
     ...(tooltip !== undefined && { tooltip }),
   })
 
-  const { bands, margin, plotWidth, scale, cursor, point, crosshairX, step, bandWidth } = band
+  const { bands, margin, plotWidth, point, crosshairX, step, bandWidth } = band
   const stripHeight = Math.max(plot.height - margin.top - margin.bottom, 1)
   const hatchId = `${chartId}-band-absent`
   if (absentState !== undefined && !styleByKey.has(absentState)) {
@@ -351,13 +345,17 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
 
   if (plotWidth <= 0 || bands.length === 0) return null
 
-  const cfg = tooltip === false ? undefined : tooltip
-  const badge = cfg?.label === undefined || point === null ? null : cfg.label(point)
   const row = point === null ? null : deriveBandRow(getBand(point), styleByKey, hidden, point)
 
   return (
     <>
-      <svg ref={band.svgRef} width={plot.width} height={plot.height}>
+      <svg
+        ref={band.svgRef}
+        width={plot.width}
+        height={plot.height}
+        // `touch-action` on the plot `<svg>`: Chrome ignores it on the overlay `<rect>` (`R2C-2`).
+        style={{ touchAction: 'pan-y' }}
+      >
         <defs>
           <HatchPattern
             id={hatchId}
@@ -377,65 +375,31 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
 
           {crosshairX !== null && <Crosshair x={crosshairX} top={0} bottom={stripHeight} />}
 
-          <AxisBottomDate
-            top={stripHeight}
-            scale={scale}
-            tickValues={band.tickValues}
-            tickFormat={(v) => formatX(String(v))}
-          />
-
-          <HoverOverlay
-            width={plotWidth}
+          <BandAxisOverlay
+            band={band}
             height={stripHeight}
-            onMove={cursor.onPointerMove}
-            onLeave={cursor.onPointerLeave}
-            onKeyDown={cursor.onKeyDown}
-            onBlur={cursor.onBlur}
-            valueMax={Math.max(bands.length - 1, 0)}
-            {...(point !== null && {
-              valueNow: bands.indexOf(point),
-              valueText: formatX(getX(point)),
-            })}
-            {...(ariaLabel !== undefined && { ariaLabel })}
+            getX={getX}
+            formatX={formatX}
+            ariaLabel={ariaLabel}
           />
         </Group>
       </svg>
 
-      {band.showTooltip && point !== null && (
-        <ChartTooltipFloat anchor={band.tooltipAnchor} ariaLive={band.ariaLive}>
-          <TooltipHeader
-            date={getX(point)}
-            {...(cfg?.formatHeader !== undefined && {
-              format: (key: string) => cfg.formatHeader?.(key, point) ?? key,
-            })}
-            {...(badge !== null && { label: badge.text, labelColor: badge.color })}
+      <BandTooltip band={band} tooltip={tooltip} getX={getX} hidden={hidden}>
+        {row !== null && (
+          <TooltipRow
+            color={row.color}
+            label={row.label}
+            value={row.value}
+            shape={row.shape}
+            dashed={row.dashed}
           />
-          <TooltipBody>
-            {cfg?.prependRows?.(point, { hidden })}
-            {row !== null && (
-              <TooltipRow
-                color={row.color}
-                label={row.label}
-                value={row.value}
-                shape={row.shape}
-                dashed={row.dashed}
-              />
-            )}
-            {cfg?.extraRows?.(point, { hidden })}
-          </TooltipBody>
-        </ChartTooltipFloat>
-      )}
+        )}
+      </BandTooltip>
     </>
   )
 }
 
-/** A 0..1 share. Non-finite (a 0/0 fold count) reads as "nothing is absent" — the conservative
- * end, since the alternative is a band that does not render at all. */
-function clampFraction(value: number | undefined): number {
-  if (value === undefined || !Number.isFinite(value)) return 0
-  return Math.min(Math.max(value, 0), 1)
-}
-
 /**
  * The strip's one derived row: the hovered band's STATE, named and formatted by its own `series`
  * entry. A strip cannot show a row for a state it does not draw, and cannot name a state the

package/src/charts/kinds/Donut.tsx

@@ -1,7 +1,10 @@
 import { Group } from '@visx/group'
 import { Pie } from '@visx/shape'
-import { memo, useMemo, useState } from 'react'
-import type { PointerEvent, ReactNode } from 'react'
+import { memo, useMemo } from 'react'
+import type { ReactNode } from 'react'
+import { useChartSize } from '../hooks/useChartSize'
+import { useDiscreteCursor } from '../hooks/use-discrete-cursor'
+import { useHysteresis } from '../hooks/use-hysteresis'
 import { assertRequiredProps } from '../../common/validate'
 import type { BasaltProps } from '../../common/props'
 import { ChartTooltipFloat, TooltipBody, TooltipRow } from '../primitives/ChartTooltip'
@@ -9,6 +12,15 @@ import { ChartFrame } from '../primitives/ChartFrame'
 import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { ChartState } from '../primitives/ChartPending'
 import { VX } from '../../tokens'
+import { resolveContainerClass } from '../../tokens/size-classes'
+import { resolveFrameHeight } from '../primitives/chart-frame-layout'
+import {
+  foldOther,
+  resolveDonutLayout,
+  resolveDonutRadius,
+  resolveOtherKey,
+  sharePercent,
+} from './donut-layout'
 import type { SeriesStyle } from '../series'
 import type { SeriesKey } from '../../register'
 
@@ -64,14 +76,22 @@ export type DonutProps<K extends string = SeriesKey> = BasaltProps & {
   state?: ChartState
 }
 
+const identityLabel = (key: string): string => key
+
 /**
  * Radial slice-share chart with a punched-out center label. Composes `ChartFrame` for a
  * categorical legend derived from the slices (one `SeriesStyle` per slice, `mark: 'bar'`) so the
- * legend can never drift from what's plotted — legend-hidden slices drop out of the ring, the
- * center total, and the tooltip's "Share" row together (`docs/CHARTS-SPEC.md` §5). No crosshair —
- * meaningless for a radial layout. Hover stays local to the pie (dimming siblings on hover) rather
+ * legend can never drift from what's plotted — legend-hidden slices drop out of the ring and the
+ * tooltip together, while every share is taken of ALL slices so the legend and the tooltip never
+ * disagree (`docs/CHARTS-SPEC.md` §5). No crosshair — meaningless for a radial layout. Hover stays local to the pie (dimming siblings on hover) rather
  * than joining the shared cursor: a date-keyed cursor has no counterpart on a donut, and cross-kind
  * category sync (donut ↔ bar, via a generalized key) is a distinct, deliberately deferred feature.
+ * Tap-to-pin, keyboard stepping and focus over the slice ring come from `useDiscreteCursor`
+ * (`docs/CHARTS-SPEC.md` §4, Tooltip), the discrete counterpart of `HoverOverlay`.
+ *
+ * Layout law (`docs/CHARTS-SPEC.md` §5, Legend): frame W/H > 1.5 puts the legend beside the ring
+ * with value and %, the ring capped at `min(h, 0.55w)`; `micro`/`compact` stack the full legend
+ * under the ring, never rolled up. 7 or more slices fold the smallest into a neutral "Other".
  */
 function DonutInner<K extends string = SeriesKey>(props: DonutProps<K>) {
   // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
@@ -82,7 +102,8 @@ function DonutInner<K extends string = SeriesKey>(props: DonutProps<K>) {
     data,
     height,
     colorForKey,
-    seriesLabel = (k) => k,
+    formatValue,
+    seriesLabel = identityLabel,
     ariaLabel,
     isPending,
     state,
@@ -90,44 +111,118 @@ function DonutInner<K extends string = SeriesKey>(props: DonutProps<K>) {
     style,
   } = props
 
-  const series: SeriesStyle[] = data.map((d) => ({
-    key: d.key,
-    label: seriesLabel(d.key),
-    color: colorForKey(d.key),
-    mark: 'bar',
-  }))
+  // The legend side depends on the frame's own measured box, which only exists inside
+  // `ChartFrame` — so measure the wrapper (same width) one level up. A stated height is used as
+  // is; the measured one moves with the legend's placement, so an unstated height gets hysteresis.
+  const { ref, width: frameW, height: measuredH } = useChartSize()
+  const containerClass = resolveContainerClass(frameW)
+  const frameH = height === undefined ? measuredH : resolveFrameHeight(height, containerClass)
+  const side = useHysteresis(
+    (wasSide) =>
+      resolveDonutLayout({
+        frameW,
+        frameH,
+        containerClass,
+        wasSide: height === undefined && wasSide,
+      }).side,
+    false,
+  )
+
+  const slices = useMemo(() => {
+    const { kept, other } = foldOther(data)
+    const out: Slice[] = kept.map((d) => ({
+      key: d.key,
+      label: seriesLabel(d.key),
+      color: colorForKey(d.key),
+      value: d.value,
+    }))
+    if (other !== null)
+      out.push({
+        key: resolveOtherKey(kept.map((d) => d.key)),
+        label: 'Other',
+        color: VX.neutral,
+        value: other,
+      })
+    return out
+  }, [data, seriesLabel, colorForKey])
+
+  // One denominator for the side legend and the tooltip: every slice, hidden or not.
+  const total = useMemo(() => slices.reduce((sum, d) => sum + d.value, 0), [slices])
+  const series = useMemo<SeriesStyle[]>(
+    () =>
+      slices.map((d) => ({
+        key: d.key,
+        label: side
+          ? `${d.label} · ${formatValue(d.value)} · ${sharePercent(d.value, total)}%`
+          : d.label,
+        color: d.color,
+        mark: 'bar',
+      })),
+    [slices, side, formatValue, total],
+  )
 
   return (
-    <ChartFrame
-      series={series}
-      {...(height !== undefined && { height })}
-      {...(ariaLabel !== undefined && { ariaLabel })}
-      {...(isPending !== undefined && { isPending })}
-      {...(state !== undefined && { state })}
+    <div
+      ref={ref}
       {...(className !== undefined && { className })}
-      {...(style !== undefined && { style })}
+      style={{ display: 'flex', flexDirection: 'column', flex: '1 1 auto', minHeight: 0, ...style }}
     >
-      {(plot) => <DonutPlot {...props} plot={plot} />}
-    </ChartFrame>
+      <ChartFrame
+        series={series}
+        // Never roll the legend up: the full list is the donut's only key. Side legends read as a
+        // column. `headerSlot: false` (P1-4) keeps it under/beside the ring even inside a
+        // `ChartCard` with a header slot free — a Donut's legend IS its key, so it must never
+        // shrink to unlabelled header dots.
+        legend={{ placement: side ? 'right' : 'bottom', maxRows: series.length, headerSlot: false }}
+        {...(height !== undefined && { height })}
+        {...(ariaLabel !== undefined && { ariaLabel })}
+        {...(isPending !== undefined && { isPending })}
+        {...(state !== undefined && { state })}
+      >
+        {(plot) => (
+          <DonutPlot
+            slices={slices}
+            total={total}
+            side={side}
+            frameW={frameW}
+            plot={plot}
+            formatValue={formatValue}
+            {...(props.centerLabel !== undefined && { centerLabel: props.centerLabel })}
+            {...(props.centerSubLabel !== undefined && { centerSubLabel: props.centerSubLabel })}
+            {...(props.centerContent !== undefined && { centerContent: props.centerContent })}
+            {...(props.innerRatio !== undefined && { innerRatio: props.innerRatio })}
+            {...(props.padAngle !== undefined && { padAngle: props.padAngle })}
+          />
+        )}
+      </ChartFrame>
+    </div>
   )
 }
 
-type DonutPlotProps<K extends string = SeriesKey> = DonutProps<K> & {
+type Slice = { key: string; label: string; color: string; value: number }
+
+type DonutPlotProps = Pick<
+  DonutProps,
+  'formatValue' | 'centerLabel' | 'centerSubLabel' | 'centerContent' | 'innerRatio' | 'padAngle'
+> & {
   plot: { width: number; height: number; hidden: ReadonlySet<string> }
+  slices: Slice[]
+  /** Sum of ALL slices (hidden included) — the one denominator for every share. */
+  total: number
+  side: boolean
+  frameW: number
 }
 
-/** A hovered slice plus the viewport anchor `ChartTooltipFloat` positions against. */
-type DonutTip<K extends string> = { key: K; value: number; anchor: { x: number; y: number } }
-
 /** The measured plot — split from {@link DonutInner} so it only draws once `ChartFrame` has
  * resolved a non-empty plot rect (radius/center depend on the measured size). */
-function DonutPlot<K extends string = SeriesKey>(props: DonutPlotProps<K>) {
+function DonutPlot(props: DonutPlotProps) {
   const {
-    data,
+    slices,
+    total,
     plot,
-    colorForKey,
+    side,
+    frameW,
     formatValue,
-    seriesLabel = (k) => k,
     centerLabel,
     centerSubLabel,
     centerContent,
@@ -136,28 +231,28 @@ function DonutPlot<K extends string = SeriesKey>(props: DonutPlotProps<K>) {
   } = props
   const { width, height, hidden } = plot
 
-  const [tip, setTip] = useState<DonutTip<K> | null>(null)
-  const hoveredKey = tip?.key ?? null
+  const visibleData = useMemo(() => slices.filter((d) => !hidden.has(d.key)), [slices, hidden])
 
-  const visibleData = useMemo(() => data.filter((d) => !hidden.has(d.key)), [data, hidden])
+  // One ring, one shared keyboard host: `useDiscreteCursor` gives arrow-key stepping through the
+  // VISIBLE slices (a hidden legend entry is not a reachable target either), plus tap-to-pin on
+  // touch. Left/Right and Up/Down are equivalent (no `columns` — a ring has no 2D shape).
+  const cursor = useDiscreteCursor<Slice>({
+    targets: visibleData,
+    getKey: (d) => d.key,
+    ariaLabel: 'Donut slices — use arrow keys to select, Escape to dismiss',
+  })
+  const activeKey = cursor.tip?.target.key ?? null
 
-  const radius = Math.min(width, height) / 2 - 4
+  const radius = resolveDonutRadius({ plotW: width, plotH: height, frameW, side })
   const innerRadius = radius * innerRatio
   const centerX = width / 2
   const centerY = height / 2
 
-  const total = useMemo(() => visibleData.reduce((sum, d) => sum + d.value, 0), [visibleData])
-
-  const show = (d: DonutDatum<K>, event: PointerEvent<SVGGElement>) => {
-    setTip({ key: d.key, value: d.value, anchor: { x: event.clientX, y: event.clientY } })
-  }
-  const hide = () => setTip(null)
-
   return (
     <div style={{ position: 'relative' }}>
-      <svg width={width} height={height}>
+      <svg width={width} height={height} {...cursor.hostProps}>
         <Group left={centerX} top={centerY}>
-          <Pie<DonutDatum<K>>
+          <Pie<Slice>
             data={visibleData}
             pieValue={(d) => d.value}
             pieSortValues={() => 0}
@@ -172,26 +267,22 @@ function DonutPlot<K extends string = SeriesKey>(props: DonutPlotProps<K>) {
                 return (
                   <g
                     key={key}
-                    onPointerEnter={(event) => {
-                      show(arc.data, event)
-                    }}
-                    onPointerMove={(event) => {
-                      show(arc.data, event)
-                    }}
-                    onPointerLeave={() => {
-                      hide()
-                    }}
-                    onPointerCancel={() => {
-                      hide()
-                    }}
+                    id={cursor.optionId(arc.data)}
+                    // An SVG `<g>` has no `<option>` counterpart — `useDiscreteCursor`'s
+                    // listbox/option pair (see its JSDoc) is a role over an arbitrary shape.
+                    // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role
+                    role="option"
+                    aria-selected={activeKey === key}
+                    aria-label={`${arc.data.label}: ${formatValue(arc.data.value)}, ${sharePercent(arc.data.value, total)}%`}
+                    {...cursor.pointerProps(arc.data)}
                     style={{ cursor: 'pointer' }}
                   >
                     <path
                       d={pie.path(arc) || ''}
-                      fill={colorForKey(key)}
+                      fill={arc.data.color}
                       stroke={VX.surface.panel}
                       strokeWidth={1.5}
-                      opacity={hoveredKey === null || hoveredKey === key ? 1 : 0.4}
+                      opacity={activeKey === null || activeKey === key ? 1 : 0.4}
                     />
                   </g>
                 )
@@ -244,19 +335,19 @@ function DonutPlot<K extends string = SeriesKey>(props: DonutPlotProps<K>) {
         </div>
       )}
 
-      {tip !== null && (
-        <ChartTooltipFloat anchor={tip.anchor}>
+      {cursor.tip !== null && (
+        <ChartTooltipFloat anchor={cursor.tip.anchor}>
           <TooltipBody>
             <TooltipRow
-              color={colorForKey(tip.key)}
-              label={seriesLabel(tip.key)}
-              value={formatValue(tip.value)}
+              color={cursor.tip.target.color}
+              label={cursor.tip.target.label}
+              value={formatValue(cursor.tip.target.value)}
               shape="bar"
             />
             <TooltipRow
               color={VX.grid}
               label="Share"
-              value={`${total > 0 ? Math.round((tip.value / total) * 100) : 0}%`}
+              value={`${sharePercent(cursor.tip.target.value, total)}%`}
               shape="bar"
             />
           </TooltipBody>

package/src/charts/kinds/DualPanel.tsx

@@ -13,11 +13,12 @@ import {
   TooltipBody,
   TooltipHeader,
   TooltipRow,
+  TooltipRows,
 } from '../primitives/ChartTooltip'
 import { ChartFrame, resolveLegend } from '../primitives/ChartFrame'
 import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import { Crosshair, SeriesDot } from '../primitives/Crosshair'
-import { HoverOverlay } from '../primitives/HoverOverlay'
+import { cursorSliderProps, HoverOverlay } from '../primitives/HoverOverlay'
 import { ZoneRects } from '../primitives/ZoneRects'
 import type { ZoneSpec } from '../primitives/ZoneRects'
 import type { ChartState } from '../primitives/ChartPending'
@@ -336,12 +337,16 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
     [bottomDomain, bottomH, useNiceBottom],
   )
 
+  // ONE `<svg>` wraps both panes below, so it doubles as the tap-outside boundary
+  // (`docs/CHARTS-SPEC.md` §4, Tooltip) for the single cursor they share.
+  const svgRef = useRef<SVGSVGElement>(null)
   const cursor = useChartCursor<T>({
     data,
     chartId,
     getKey: getX,
     xScale,
     marginLeft: margin.left,
+    boundaryRef: svgRef,
     ...(cursorResolution !== undefined && { resolution: cursorResolution }),
   })
 
@@ -477,7 +482,6 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
     [visibleSeries, lineValid, xScale, topYScale, getX],
   )
 
-  const svgRef = useRef<SVGSVGElement>(null)
   const point = cursor.point
   const sx = point !== null ? (xScale(getX(point)) ?? 0) : 0
   const syncedBar = point !== null ? getBar(point) : null
@@ -485,10 +489,12 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
   // Same seam as `CartesianChart`: this chart renders its tooltip as the cursor SOURCE (always) or,
   // opted in via `onFollow`, as a FOLLOWER. A follower has no pointer under it, so it is always
   // positioned via the anchored (crosshair) path — `cursor.anchor` stays null on a chart nobody is
-  // hovering, so following it here would render nothing.
+  // hovering, so following it here would render nothing. `DualPanel` has no `follow` prop to
+  // override the default, so touch (spec §5) anchors unconditionally, same as an unset `follow`
+  // elsewhere.
   const isFollowerRender = !cursor.isSource && onFollow === true
   const showTooltip = point !== null && (cursor.isSource || isFollowerRender)
-  const anchorX = isFollowerRender && point !== null ? sx : null
+  const anchorX = (isFollowerRender || cursor.isTouch) && point !== null ? sx : null
   const svgRect = anchorX === null ? undefined : svgRef.current?.getBoundingClientRect()
   const tooltipAnchor =
     svgRect === undefined || anchorX === null
@@ -497,7 +503,13 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
 
   return (
     <>
-      <svg ref={svgRef} width={plot.width} height={plot.height}>
+      <svg
+        ref={svgRef}
+        width={plot.width}
+        height={plot.height}
+        // `touch-action` on the plot `<svg>`: Chrome ignores it on the overlay `<rect>` (`R2C-2`).
+        style={{ touchAction: 'pan-y' }}
+      >
         {/* Top pane: line series + fill-between + zones + ref lines. */}
         <Group left={margin.left} top={margin.top}>
           <GridRows scale={topYScale} width={xMax} stroke={VX.grid} numTicks={4} />
@@ -584,16 +596,7 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
           <HoverOverlay
             width={xMax}
             height={topH + PANE_GAP}
-            onMove={cursor.onPointerMove}
-            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 })}
+            {...cursorSliderProps({ cursor, data, getX, formatX, ariaLabel })}
           />
         </Group>
 
@@ -648,6 +651,8 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
             width={xMax}
             height={bottomH + margin.bottom}
             onMove={cursor.onPointerMove}
+            onDown={cursor.onPointerDown}
+            onUp={cursor.onPointerUp}
             onLeave={cursor.onPointerLeave}
           />
         </Group>
@@ -673,17 +678,7 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
             })()}
           />
           <TooltipBody>
-            {deriveTooltipRows(visibleSeries, point, formatTop).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 })}
-              />
-            ))}
+            <TooltipRows rows={deriveTooltipRows(visibleSeries, point, formatTop)} />
             {barVisible &&
               (() => {
                 const v = getBar(point)