basalt-ui 1.31.0 → 1.32.0

package/src/charts/kinds/band-chrome.tsx

@@ -0,0 +1,91 @@
+import type { ReactNode } from 'react'
+import type { BandPlot, BandTooltipConfig } from '../hooks/useBandPlot'
+import { AxisBottomDate } from '../primitives/Axes'
+import { ChartTooltipFloat, TooltipBody, TooltipHeader } from '../primitives/ChartTooltip'
+import { cursorSliderProps, HoverOverlay } from '../primitives/HoverOverlay'
+
+/**
+ * The chrome `BandStrip` and `MirroredBars` share around their own marks — the slot axis, the
+ * keyboard/pointer overlay and the tooltip shell — so the two `useBandPlot` kinds cannot drift in
+ * any of them. Internal; neither is exported from a barrel.
+ *
+ * theme-allow-file hand-rolled-plot — the slot axis and overlay of the two declared banded
+ * exceptions (`BandStrip`, `MirroredBars`), which carry the same waiver for the same reason.
+ */
+
+/** 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. */
+export function clampFraction(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return 0
+  return Math.min(Math.max(value, 0), 1)
+}
+
+/** The slot axis under a `height`-tall band row, plus the hover/keyboard overlay over it. */
+export function BandAxisOverlay<T>({
+  band,
+  height,
+  getX,
+  formatX,
+  ariaLabel,
+}: {
+  band: BandPlot<T>
+  height: number
+  getX: (d: T) => string
+  formatX: (key: string) => string
+  ariaLabel: string | undefined
+}) {
+  return (
+    <>
+      <AxisBottomDate
+        top={height}
+        scale={band.scale}
+        tickValues={band.tickValues}
+        tickFormat={(v) => formatX(String(v))}
+        anchorTerminals={band.xAnchorTerminals}
+        {...(band.xWrapWidth !== undefined && { wrapWidth: band.xWrapWidth })}
+      />
+      <HoverOverlay
+        width={band.plotWidth}
+        height={height}
+        {...cursorSliderProps({ cursor: band.cursor, data: band.bands, getX, formatX, ariaLabel })}
+      />
+    </>
+  )
+}
+
+/** The tooltip shell: header (+ badge), the consumer's prepended rows, the kind's own derived
+ * `children` rows, the consumer's extra rows. Renders nothing off-hover or with `tooltip: false`. */
+export function BandTooltip<T>({
+  band,
+  tooltip,
+  getX,
+  hidden,
+  children,
+}: {
+  band: BandPlot<T>
+  tooltip: BandTooltipConfig<T> | false | undefined
+  getX: (d: T) => string
+  hidden: ReadonlySet<string>
+  children: ReactNode
+}) {
+  const { point } = band
+  if (!band.showTooltip || point === null) return null
+  const cfg = tooltip === false ? undefined : tooltip
+  const badge = cfg?.label === undefined ? null : cfg.label(point)
+  return (
+    <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 })}
+      />
+      <TooltipBody>
+        {cfg?.prependRows?.(point, { hidden })}
+        {children}
+        {cfg?.extraRows?.(point, { hidden })}
+      </TooltipBody>
+    </ChartTooltipFloat>
+  )
+}

package/src/charts/primitives/CartesianChart.tsx

@@ -32,9 +32,9 @@ import {
 } from './chart-layout'
 import { useChartContainerClass, useChartMetrics } from './chart-tier'
 import type { ChartState } from './ChartPending'
-import { ChartTooltipFloat, TooltipBody, TooltipHeader, TooltipRow } from './ChartTooltip'
+import { ChartTooltipFloat, TooltipBody, TooltipHeader, TooltipRows } from './ChartTooltip'
 import { Crosshair, SeriesDot } from './Crosshair'
-import { HoverOverlay } from './HoverOverlay'
+import { cursorSliderProps, HoverOverlay } from './HoverOverlay'
 import { XZoneRects } from './XZoneRects'
 import type { XZoneSpec } from './XZoneRects'
 import { ZoneRects } from './ZoneRects'
@@ -405,46 +405,51 @@ function buildYScale<T>(
 }
 
 /**
- * `tickLabelPx`'s resolver, split out of a two-deep ternary: a 45° label projects wider than its
- * flat glyph box, so it measures through {@link rotatedXLabelPx} instead of the flat/wrapped
- * numbers every other rotation uses; a wrapped flat label (`wrapWidth` set) uses ITS width, an
- * unwrapped one the plain flat width. `rotate === 90` falls through to the flat/wrapped branch
- * unchanged — `wrapWidth` is only ever set for `rotate === 0` (see its own definition), so a 90°
- * axis always resolves to `flatLabelPx` here, matching the pre-split behaviour exactly.
+ * The x-axis margin ladder, as one pure decision. The flat (unrotated) margin is what every case
+ * resolves to except a rotated or wrapped axis, and it is what the rotation decision itself is
+ * measured against — deciding needs an `xMax`, and `xMax` needs a margin, so the flat pass breaks
+ * the loop. An explicit `xLabelRotate` always wins — including `0`, the documented "never rotate"
+ * opt-out; unset, only a categorical (band) axis wraps, and rotates only when even wrapped it
+ * doesn't fit (`planXLabels`) — a time or number domain only thins.
+ *
+ * Per rotation: 45° reuses its pre-measured margin and measures its tick room through
+ * {@link rotatedXLabelPx} (a rotated label projects wider than its glyph box); 90° measures fresh
+ * (one line box wide, so the flat label room governs its thinning); a wrapped flat axis re-measures
+ * for its extra line(s) and thins by the wrapped width.
  */
-function resolveTickLabelPx(input: {
-  rotate: 0 | 45 | 90
-  wrapWidth: number | undefined
-  xLabels: string[]
-  axisFont: number
+function resolveXAxisLayout(input: {
+  marginInput: AutoMarginInput
+  flatMargin: ChartMargin
+  rotated45Margin: ChartMargin
   flatLabelPx: number
-  wrappedLabelPx: number
-}): number {
-  const { rotate, wrapWidth, xLabels, axisFont, flatLabelPx, wrappedLabelPx } = input
-  if (rotate === 45) return rotatedXLabelPx(xLabels, axisFont)
-  return wrapWidth === undefined ? flatLabelPx : wrappedLabelPx
-}
-
-/**
- * `baseMargin`'s resolver, split out of the same two-deep ternary: an unrotated, unwrapped axis
- * keeps the already-measured flat margin; wrapping re-measures for the extra line(s)
- * (`bottomLines`); a 45° rotation reuses its own pre-measured margin ({@link rotated45Margin}); a
- * 90° one measures fresh (no pre-measured twin exists for it, unlike 45°).
- */
-function resolveBaseMargin(input: {
+  xLabels: string[]
+  fontPx: number
+  plotWidth: number
+  categorical: boolean
+  xLabelRotate: 0 | 45 | 90 | undefined
+}): {
+  baseMargin: ChartMargin
   rotate: 0 | 45 | 90
   wrapWidth: number | undefined
-  flatMargin: ChartMargin
-  rotated45Margin: ChartMargin
-  marginInput: AutoMarginInput
-  xPlanLines: number
-}): ChartMargin {
-  const { rotate, wrapWidth, flatMargin, rotated45Margin, marginInput, xPlanLines } = input
-  if (rotate === 45) return rotated45Margin
-  if (rotate === 90) return autoMargin({ ...marginInput, rotate })
-  return wrapWidth === undefined
-    ? flatMargin
-    : autoMargin({ ...marginInput, bottomLines: xPlanLines })
+  tickLabelPx: number
+} {
+  const { marginInput, flatMargin, rotated45Margin, flatLabelPx, xLabels, fontPx, categorical } =
+    input
+  const flatXMax = Math.max(input.plotWidth - flatMargin.left - flatMargin.right, 0)
+  const xPlan = planXLabels({ labels: xLabels, plotWidth: flatXMax, fontPx, categorical })
+  const rotate = input.xLabelRotate ?? (categorical ? xPlan.rotate : 0)
+  if (rotate === 45) {
+    const tickLabelPx = rotatedXLabelPx(xLabels, fontPx)
+    return { baseMargin: rotated45Margin, rotate, wrapWidth: undefined, tickLabelPx }
+  }
+  if (rotate === 90) {
+    const baseMargin = autoMargin({ ...marginInput, rotate })
+    return { baseMargin, rotate, wrapWidth: undefined, tickLabelPx: flatLabelPx }
+  }
+  if (!xPlan.wrap)
+    return { baseMargin: flatMargin, rotate, wrapWidth: undefined, tickLabelPx: flatLabelPx }
+  const baseMargin = autoMargin({ ...marginInput, bottomLines: xPlan.lines })
+  return { baseMargin, rotate, wrapWidth: xPlan.wrapPx, tickLabelPx: xPlan.labelPx }
 }
 
 /**
@@ -665,16 +670,16 @@ function CartesianPlot<T>({
   // the actual law: only a band (category) domain wraps or rotates; time and number domains thin.
   const categorical = tight && classifyDomain(keys) === 'band'
 
-  /** The horizontal room one x tick label needs: the widest string that could be painted, plus
-   * breathing space to its neighbour. Feeds `smartTicks`, which otherwise thinned the axis by a
-   * constant that knew nothing about the label. Measured at the tick font the axis will actually
-   * paint, which the tier moves (`docs/CHARTS-SPEC.md` §8). */
-  const xLabelPx = useMemo(() => xLabelPxFor(xLabels, tier.axisFont), [xLabels, tier.axisFont])
+  // The room one flat x tick label needs at the tick font the axis will actually paint
+  // (`docs/CHARTS-SPEC.md` §8) — keyed on the labels and font alone, so a y-label or margin change
+  // never re-measures every x label.
+  const flatLabelPx = useMemo(() => xLabelPxFor(xLabels, tier.axisFont), [xLabels, tier.axisFont])
 
-  /** Everything `autoMargin` measures except the rotation — shared by all three passes below so a
-   * measured label can never differ between the one that DECIDES and the one that PAINTS. */
-  const marginInput = useMemo(
-    () => ({
+  // Everything `autoMargin` measures except the rotation, measured once for every pass so a label
+  // can never differ between the one that DECIDES and the one that PAINTS — plus the 45° margin (a
+  // rotated label reaches into the left gutter).
+  const measured = useMemo(() => {
+    const marginInput: AutoMarginInput = {
       left: yPlacement === 'outside' ? leftLabels : [],
       right: rightLabels,
       bottom: xLabels,
@@ -684,61 +689,34 @@ function CartesianPlot<T>({
       floor: resolveMarginFloor(yPlacement, tier.margin),
       anchorTerminals: tight,
       ...(marginOverride !== undefined && { override: marginOverride }),
-    }),
-    [
-      leftLabels,
-      rightLabels,
-      xLabels,
-      tier.axisFont,
-      tier.margin,
-      marginOverride,
-      tight,
-      yPlacement,
-    ],
-  )
-
-  /** The margin an UNROTATED axis resolves to. It is the final margin in every case except an
-   * auto-rotated phone axis, and it is what the rotation decision itself is measured against —
-   * deciding needs an `xMax`, and `xMax` needs a margin, so the unrotated pass breaks the loop. */
-  const flatMargin = useMemo(() => autoMargin(marginInput), [marginInput])
-
-  /** And the margin a 45° axis would resolve to — the OTHER half of the decision, needed only for
-   * a categorical (band) domain that still overflows once wrapped (`planXLabels`'s own rotate
-   * case). A rotated label reaches into the left gutter, so rotating spends plot width. */
-  const rotated45Margin = useMemo(() => autoMargin({ ...marginInput, rotate: 45 }), [marginInput])
-
-  // An explicit `xLabelRotate` always wins — including `0`, which is the documented "never rotate"
-  // opt-out. Only an unset one falls through to the domain-driven default: a categorical (band)
-  // axis wraps before it rotates, and rotates only when even wrapped it doesn't fit
-  // (`planXLabels`). A time or number domain never wraps or rotates — it only thins.
-  const flatXMax = Math.max(plot.width - flatMargin.left - flatMargin.right, 0)
-  const xPlan = useMemo(
-    () => planXLabels({ labels: xLabels, plotWidth: flatXMax, fontPx: tier.axisFont, categorical }),
-    [xLabels, flatXMax, tier.axisFont, categorical],
-  )
-  const rotate = xLabelRotate ?? (categorical ? xPlan.rotate : 0)
-  const wrapWidth = rotate === 0 && xPlan.wrap ? xPlan.wrapPx : undefined
-  // A 90° label is one line box wide, so the constant floor governs it; a 45° one projects wider.
-  const tickLabelPx = resolveTickLabelPx({
-    rotate,
-    wrapWidth,
+    }
+    return {
+      marginInput,
+      flatMargin: autoMargin(marginInput),
+      rotated45Margin: autoMargin({ ...marginInput, rotate: 45 }),
+    }
+  }, [
+    leftLabels,
+    rightLabels,
     xLabels,
-    axisFont: tier.axisFont,
-    flatLabelPx: xLabelPx,
-    wrappedLabelPx: xPlan.labelPx,
-  })
-
-  const baseMargin = useMemo(
+    tier.axisFont,
+    tier.margin,
+    marginOverride,
+    tight,
+    yPlacement,
+  ])
+  const { baseMargin, rotate, wrapWidth, tickLabelPx } = useMemo(
     () =>
-      resolveBaseMargin({
-        rotate,
-        wrapWidth,
-        flatMargin,
-        rotated45Margin,
-        marginInput,
-        xPlanLines: xPlan.lines,
+      resolveXAxisLayout({
+        ...measured,
+        flatLabelPx,
+        xLabels,
+        fontPx: tier.axisFont,
+        plotWidth: plot.width,
+        categorical,
+        xLabelRotate,
       }),
-    [flatMargin, rotated45Margin, marginInput, rotate, wrapWidth, xPlan.lines],
+    [measured, flatLabelPx, xLabels, tier.axisFont, plot.width, categorical, xLabelRotate],
   )
 
   // End-of-line labels are planned FIRST, against the base margin: the right gutter is reserved
@@ -998,18 +976,7 @@ function CartesianPlot<T>({
           <HoverOverlay
             width={xMax}
             height={yMax}
-            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 })}
+            {...cursorSliderProps({ cursor: cursor, data: data, getX, formatX, ariaLabel })}
           />
         </Group>
       </svg>
@@ -1025,17 +992,7 @@ function CartesianPlot<T>({
           />
           <TooltipBody>
             {tooltipCfg?.prependRows?.(point, { visible, hidden })}
-            {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 })}
-              />
-            ))}
+            <TooltipRows rows={rows} />
             {tooltipCfg?.extraRows?.(point, { visible, hidden })}
           </TooltipBody>
         </ChartTooltipFloat>

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