basalt-ui 1.30.1 → 1.31.0

package/src/charts/primitives/ChartFrame.tsx

@@ -1,33 +1,33 @@
 import type { CSSProperties, ReactNode } from 'react'
-import { useCallback, useState } from 'react'
+import { useCallback, useContext, useId, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
 import type { BasaltProps } from '../../common/props'
+import {
+  deprecatedProp,
+  ignoredProp,
+  legendSlotContention,
+  plotBelowFloor,
+} from '../../common/errors'
+import { reportOnce, useValidateProps } from '../../common/validate'
+import { SizeClassHintContext, useSizeClass } from '../../shell/use-size-class'
 import { VX } from '../../tokens'
 import { useChartSize } from '../hooks/useChartSize'
 import { deriveLegend } from '../series'
 import type { ChartLegendConfig, LegendPlacement, SeriesStyle } from '../series'
-import {
-  resolveChartTier,
-  resolveFrameHeight,
-  resolveLegendRollup,
-  resolvePlotRect,
-} from './chart-frame-layout'
+import { ChartCardContext } from './chart-card-context'
+import { resolveChartLayout, resolveFrameClass } from './chart-layout'
+import { resolveFrameHeight, resolveLegendRollup, resolvePlotRect } from './chart-frame-layout'
 import type { ResponsiveChartHeight } from './chart-frame-layout'
-import { ChartTierProvider } from './chart-tier'
+import { ChartTierProvider, useCoarsePointer, useViewportHeight } from './chart-tier'
 import { ChartLegend } from './ChartLegend'
 import { ChartEmpty, ChartError, ChartPending, resolveChartState } from './ChartPending'
 import type { ChartState } from './ChartPending'
 
 /** Re-exported for `ChartFrame.test.tsx` and any other consumer that previously reached these
  * through `ChartFrame` — the layout math itself lives in `./chart-frame-layout` (pure, DOM-free). */
-export {
-  legendEntryCap,
-  resolveLegendRollup,
-  resolvePlotRect,
-  resolveChartTier,
-} from './chart-frame-layout'
+export { legendEntryCap, resolveLegendRollup, resolvePlotRect } from './chart-frame-layout'
 export type { ResponsiveChartHeight } from './chart-frame-layout'
 
-const DEFAULT_HEIGHT = 240
 const DEFAULT_MIN_WIDTH = 200
 
 /** Legend configuration for {@link ChartFrame}. Omit entirely (or pass `{}`) for the default
@@ -36,16 +36,12 @@ export type ChartFrameLegend = {
   /** Default 'bottom'. */
   placement?: LegendPlacement
   /**
-   * Wrap cap → "+N more" rollup at high cardinality.
+   * @deprecated Removed in 1.32.0 — the legend now fits by measured width every time and folds
+   * overflow into an `All N` disclosure (`docs/CHARTS-SPEC.md` §8); drop the prop.
    *
-   * An explicit value WINS OUTRIGHT — over the phone tier's two-row default (`chartTierMetrics`)
-   * AND over a `fill` frame's measured fit (`legendEntryCap`). 1.30.0 fixed only the first half:
-   * the fit still ran `Math.min(fitted, caller)` on top, so meteo's 7-entry meteogram legend in a
-   * 150px docked row rendered 2 entries at `maxRows` 3, 6 AND 99 — five series drawn in colours
-   * nothing named. Both losers are DEFAULTS (the tier's, and `VX.minPlotHeight`); this is the one
-   * number a caller stated, so under `fill` the PLOT yields the height instead
-   * ({@link resolvePlotRect}'s `legendWins`). State a number too large for the box and the plot
-   * gets what is left — visible, and yours.
+   * Until then an explicit value still WINS OUTRIGHT over the measured fit, and it counts ENTRIES,
+   * not rows: `maxRows: 3` on a 7-entry legend renders three entries. Under `fill` the PLOT yields
+   * the height ({@link resolvePlotRect}'s `legendWins`).
    */
   maxRows?: number
   /** Visually separate role: series | overlay | reference. */
@@ -60,22 +56,36 @@ export type ChartFrameLegend = {
    * plot, the tooltip, and the auto domain together (`docs/CHARTS-SPEC.md` §5).
    */
   toggle?: boolean
+  /**
+   * Internal escape hatch for a kind that never wants its legend portalled into a `ChartCard`
+   * header, whatever the placement — `Donut` sets this (`docs/waves/PLAN.md` wave 3, P1-4): its
+   * side/bottom legend is the ring's only key, so it must stay under or beside the ring rather than
+   * follow every other frame's default of claiming an available header slot. `false` keeps the
+   * legend in its own band regardless of `placement`; omitted (default) behaves as today. Not
+   * something a consumer composing a kind's own `legend` prop can reach — kinds compose `ChartFrame`
+   * directly to set it.
+   */
+  headerSlot?: boolean
 }
 
 export type ChartFrameProps = BasaltProps & {
   /** Series identity — drives the derived legend. Pass the SAME array the kind draws + tooltips from. */
   series: readonly SeriesStyle[]
   /**
-   * Height in pixels, or one per size step. Used when neither `aspectRatio` nor `fill` is set.
-   * Default 240.
+   * Height in pixels, or one per container step. Used when neither `aspectRatio` nor `fill` is set.
+   * Default: derived from the measured width and container class (`resolveChartLayout`). Inside a
+   * `ChartCard` the resulting height is a MINIMUM — the frame grows into a taller card body. Passing it WITH `fill` is a wiring mistake, not a fallback — `fill` wins and
+   * this is never read, which now warns once in dev (`common/errors.ts`' `ignoredProp`).
    *
-   * `{ base: 180, md: 260 }` is the declarative escape from a page of fixed-height charts: the
-   * steps are compared against the frame's own MEASURED width, not the viewport, so a chart squeezed
-   * by a `PageAside` gets the short height on a desktop too. A plain number is unchanged and stays
-   * supported ({@link resolveFrameHeight}).
+   * `{ base: 180, wide: 260 }` is the declarative escape from a page of fixed-height charts: the
+   * `regular`/`wide` steps are compared against the frame's own MEASURED width, not the viewport,
+   * so a chart squeezed by a `PageAside` gets the short height on a desktop too. A plain number is
+   * an override and stays supported ({@link resolveFrameHeight}); one that leaves the plot under
+   * `VX.minPlotHeight` warns once in dev.
    */
   height?: number | ResponsiveChartHeight
-  /** height = Math.round(containerWidth / aspectRatio). Ignored when `fill` is set. */
+  /** height = Math.round(containerWidth / aspectRatio). Ignored when `fill` is set — which warns
+   * once in dev, for the same reason `height` does. */
   aspectRatio?: number
   /** Fill the parent flex/grid cell's measured height instead of a fixed/derived one. */
   fill?: boolean
@@ -126,6 +136,10 @@ export type PlotRect = {
   width: number
   height: number
   hidden: ReadonlySet<string>
+  /** Whether THIS frame's legend is currently portalled into a `ChartCard` header slot — a chart
+   * composing `ChartFrame` (e.g. `CartesianChart`'s end labels, R2C-10) reads this to skip a
+   * band-legend-only affordance once the header already names every series for free. */
+  legendInHeader: boolean
 }
 
 const outerStyle = (fill: boolean, vertical: boolean): CSSProperties => ({
@@ -209,6 +223,104 @@ export function ChartFrame({
 }: ChartFrameProps): ReactNode {
   const { ref: containerRef, width: containerW, height: containerH } = useChartSize()
   const { ref: legendRef, width: legendW, height: legendH } = useChartSize()
+  const { ref: slotRef, width: slotMeasuredW } = useChartSize()
+  const {
+    inCard,
+    legendSlot,
+    short: cardShort,
+    claimLegendSlot,
+    releaseLegendSlot,
+    legendSlotVersion,
+  } = 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
+  // 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.
+  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.
+    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)
+      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])
+  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.
+  const sizeClass = useContext(SizeClassHintContext) === undefined ? 'medium' : viewportClass
+  const coarse = useCoarsePointer()
+  const viewportH = useViewportHeight()
   const [hidden, setHidden] = useState<ReadonlySet<string>>(() => new Set())
 
   const toggleKey = useCallback((key: string) => {
@@ -220,24 +332,116 @@ export function ChartFrame({
     })
   }, [])
 
-  const placement = legend === false ? 'bottom' : (legend.placement ?? 'bottom')
-  const vertical = placement === 'left' || placement === 'right'
-  // 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.
-  const resolvedState = resolveChartState({ ...(state !== undefined && { state }), isPending })
-  const legendVisible = legend !== false && resolvedState === null
-  const tier = resolveChartTier(containerW)
+  // The three sizing props are mutually exclusive and `fill` wins, silently — the type cannot say
+  // so without a union prop, which is a bigger change than a patch carries. Warn instead: a
+  // consumer passed `height` alongside `fill` for the life of a file and kept eight height
+  // constants (and a whole `compact` branch) that never moved a pixel, with nothing from tsc,
+  // oxlint or check-theme saying a word.
+  useValidateProps(
+    'ChartFrame',
+    () => [
+      fill && height !== undefined
+        ? ignoredProp(
+            'ChartFrame',
+            'height',
+            "`fill` is set — a fill frame takes its parent cell's measured height. Pass one or the other.",
+          )
+        : null,
+      fill && aspectRatio !== undefined
+        ? ignoredProp(
+            'ChartFrame',
+            'aspectRatio',
+            "`fill` is set — a fill frame takes its parent cell's measured height. Pass one or the other.",
+          )
+        : null,
+    ],
+    [fill, height, aspectRatio],
+  )
+  const legendItems = legend === false ? [] : deriveLegend(series)
+  useValidateProps(
+    'ChartFrame',
+    () =>
+      // A cap covering every entry rolls nothing up — it is how `Donut` states "never roll up".
+      legend !== false && legend.maxRows !== undefined && legend.maxRows < legendItems.length
+        ? deprecatedProp(
+            '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.',
+          )
+        : null,
+    [legend, legendItems.length],
+  )
+  const statedHeight =
+    height === undefined
+      ? undefined
+      : resolveFrameHeight(height, resolveFrameClass({ frameW: containerW, sizeClass }))
+  // 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 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
+  // invalidate this memo exactly like a key or label change does; keying on key+label alone missed
+  // both and served a stale layout until something else happened to change first.
+  const legendKey = legendItems
+    .map((item) => `${item.key}\u0000${item.label}\u0000${item.role ?? ''}\u0000${item.note ?? ''}`)
+    .join('\u0001')
+  const layout = useMemo(
+    () =>
+      resolveChartLayout({
+        frameW: containerW,
+        slotW,
+        viewportH,
+        legendItems,
+        sizeClass,
+        coarse,
+        cardShort,
+        groups,
+        ...(statedHeight !== undefined && { override: { height: statedHeight } }),
+      }),
+    // `legendItems` is a fresh array per render; `legendKey` is its identity.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    [containerW, slotW, viewportH, legendKey, sizeClass, coarse, cardShort, groups, statedHeight],
+  )
+
+  // The resolver gates every placement: none at micro, else the card's header slot when there is
+  // one AND this frame owns it (P2-9) — `slotW` is already 0 for a non-owner or a `headerSlot:
+  // false` kind (P1-4), so `fit.where` already reads 'band' for both; `ownsSlot` here is only the
+  // (harmless) belt to that suspenders.
+  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 sideLegendWidth = showLegend && vertical ? legendW : 0
+  const topBottomLegendHeight = showLegend && !vertical && !inHeader ? legendH : 0
 
+  const computedHeight =
+    aspectRatio !== undefined ? Math.round(containerW / aspectRatio) : layout.height
+  // In a card the computed height is a floor: a stretched grid row hands the body more, and the
+  // frame (flex 1 in the body) takes it. Never below what the legend band plus the plot floor need.
+  const grows = inCard && !fill
   const resolvedHeight = fill
     ? containerH
-    : aspectRatio !== undefined
-      ? Math.round(containerW / aspectRatio)
-      : resolveFrameHeight(height ?? DEFAULT_HEIGHT, containerW)
+    : grows
+      ? Math.max(computedHeight, containerH)
+      : computedHeight
+  const cardMinHeight = Math.max(computedHeight, VX.minPlotHeight + topBottomLegendHeight)
 
-  const sideLegendWidth = legendVisible && vertical ? legendW : 0
-  const topBottomLegendHeight = legendVisible && !vertical ? legendH : 0
-
-  const legendItems = legend === false ? [] : deriveLegend(series)
+  useValidateProps(
+    'ChartFrame',
+    () =>
+      typeof height === 'number' &&
+      !fill &&
+      aspectRatio === undefined &&
+      height - topBottomLegendHeight < VX.minPlotHeight
+        ? plotBelowFloor('ChartFrame', height, VX.minPlotHeight)
+        : null,
+    [height, fill, aspectRatio, topBottomLegendHeight],
+  )
   const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1)
 
   // The cap, and who pays for it — one pure decision ({@link resolveLegendRollup} states the three
@@ -247,8 +451,8 @@ export function ChartFrame({
   // plot pays for. Top/bottom only: a side legend costs width, not height.
   const { maxRows, legendWins } = resolveLegendRollup({
     ...(legend !== false && legend.maxRows !== undefined && { statedMaxRows: legend.maxRows }),
-    tier,
-    fillBand: legendVisible && fill && !vertical,
+    ...(!vertical && fit !== null && fit.overflow > 0 && { fittedMaxRows: fit.visible }),
+    fillBand: showLegend && fill && !inHeader && !vertical,
     items: legendItems,
     containerW,
     available: resolvedHeight - VX.minPlotHeight,
@@ -264,7 +468,7 @@ export function ChartFrame({
   })
 
   const legendNode =
-    legend === false || resolvedState !== null ? null : (
+    legend === false || resolvedState !== null || !showLegend ? null : (
       <div ref={legendRef} style={legendWrapperStyle(vertical)}>
         <ChartLegend
           items={legendItems}
@@ -274,6 +478,7 @@ export function ChartFrame({
           {...(chartId !== undefined && { chartId })}
           {...(legend.groups !== undefined && { groups: legend.groups })}
           {...(maxRows !== undefined && { maxRows })}
+          {...(legendMode !== undefined && { mode: legendMode })}
           {...(legend.highlighted !== undefined && { highlighted: legend.highlighted })}
           {...(legend.onHighlight !== undefined && { onHighlight: legend.onHighlight })}
         />
@@ -281,15 +486,26 @@ export function ChartFrame({
     )
 
   return (
-    <ChartTierProvider tier={tier}>
+    <ChartTierProvider containerClass={layout.containerClass}>
       <div
         ref={containerRef}
         {...(className !== undefined && { className })}
-        style={{ ...outerStyle(fill, vertical), ...style }}
+        style={{
+          ...outerStyle(fill, vertical),
+          ...(grows && { flex: '1 1 0', minHeight: cardMinHeight }),
+          ...style,
+        }}
         {...(ariaLabel !== undefined && { role: 'group', 'aria-label': ariaLabel })}
         {...(resolvedState === 'pending' && { 'aria-busy': 'true' })}
       >
-        {legendNode !== null && (placement === 'top' || placement === 'left') && legendNode}
+        {inHeader &&
+          legendNode !== null &&
+          legendSlot !== null &&
+          createPortal(legendNode, legendSlot)}
+        {!inHeader &&
+          legendNode !== null &&
+          (placement === 'top' || placement === 'left') &&
+          legendNode}
         {plot.width > 0 &&
           plot.height > 0 &&
           (resolvedState === 'pending' ? (
@@ -303,9 +519,12 @@ export function ChartFrame({
               {...(typeof state?.empty === 'string' && { label: state.empty })}
             />
           ) : (
-            children({ ...plot, hidden })
+            children({ ...plot, hidden, legendInHeader: inHeader })
           ))}
-        {legendNode !== null && (placement === 'bottom' || placement === 'right') && legendNode}
+        {!inHeader &&
+          legendNode !== null &&
+          (placement === 'bottom' || placement === 'right') &&
+          legendNode}
       </div>
     </ChartTierProvider>
   )