basalt-ui 1.30.2 → 1.31.0

package/src/charts/primitives/ChartCard.tsx

@@ -12,15 +12,43 @@
  * 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 type { CSSProperties, ReactNode } from 'react'
 import { cx } from '../../common/props'
 import type { BasaltProps, SlotStylesProps } from '../../common/props'
 import { VX } from '../../tokens'
 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 { ChartEmpty, ChartError, ChartPending, resolveChartState } from './ChartPending'
 import type { ChartState } from './ChartPending'
 
+/**
+ * Below this rendered height the header folds its subtitle regardless of width (wave 8's
+ * header-economy law, `docs/CHARTS-SPEC.md` §5) — a short-but-wide card (a KPI-style
+ * chart card) still needs the vertical space back. A `@container basalt-card` SIZE query would be
+ * the natural expression, but `container-type: size` on a box with no explicit height (the common,
+ * non-grid-stretched case) collapses it to 0 — CSS containment requires a definite size in the
+ * contained axis, and a ChartCard's height is ordinarily derived from its content (VERIFIED: making
+ * the root a size container drops `card-chrome.layout.test.ts`'s unstretched short-card fixture to
+ * a 0px box). `useChartSize` (the same measuring primitive `ChartFrame` uses) reads the rendered
+ * height instead, and `data-basalt-card-short` is the CSS hook `widget-header.module.css` reacts to
+ * with the same subtitle-fold declarations as the width query.
+ */
+const CARD_SHORT_HEIGHT = 280
+/**
+ * Hysteresis band on the flag above (`docs/waves/PLAN.md` wave 3, P0-1). `short` folds the header,
+ * which changes the card's OWN measured height by the fold delta — a card whose unfolded height
+ * lands in `[280, 280 + Δ)` is bistable, and the async RO → rAF → debounce → setState → commit path
+ * can sit one reading behind, which turned the bistability into a perpetual flip-flop on the
+ * "Sales by channel" dashboard card (27-52 times per 2s, every viewport). Entering short still
+ * happens below `CARD_SHORT_HEIGHT`; LEAVING it needs `CARD_SHORT_HEIGHT + SHORT_EXIT_SLACK`, sized
+ * to clear the largest fold delta (subtitle line + inset + value row) with headroom.
+ */
+const SHORT_EXIT_SLACK = 24
+
 // Surfaces resolve per theme via CSS vars, so the styles are static (no useMemo/isDark).
 // Depth = `shadow-card` (a whisper shadow + a 1px ring baked into the same value), never a
 // `border` property (docs/DESIGN-SPEC.md §5) — so a ChartCard reads IDENTICALLY to a Mantine
@@ -31,7 +59,16 @@ import type { ChartState } from './ChartPending'
 // `WidgetHeader`'s info bubble (`widget-header.module.css`'s `.infoBubble`, which is where the
 // tooltip this file used to own now lives) opens downward past the header's own box, and must be
 // able to overhang the card edge without being invisibly cut off.
+//
+// The root is a flex column and a `basalt-card` inline-size container (the card's own width drives
+// its header chrome, `docs/CHARTS-SPEC.md` §8): the body takes the row's spare height when a grid stretches
+// the card.
 const cardStyle: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  minHeight: 0,
+  containerType: 'inline-size',
+  containerName: 'basalt-card',
   borderRadius: VX.radiusCard,
   boxShadow: VX.shadowCard,
   backgroundColor: VX.surface.panel,
@@ -45,6 +82,11 @@ const bodyClipStyle: CSSProperties = {
   borderBottomLeftRadius: VX.radiusCard,
   borderBottomRightRadius: VX.radiusCard,
   overflow: 'hidden',
+  flex: '1 1 auto',
+  minHeight: 0,
+  // A column, so a `ChartFrame` inside can grow into the body a stretched grid row hands the card.
+  display: 'flex',
+  flexDirection: 'column',
   padding: '2px var(--vx-space-card-inset-x, 0.8125rem) var(--vx-space-card-inset-y, 0.6875rem)',
 }
 // Card inset = the `cardInsetY`/`cardInsetX` role tokens (vertical / horizontal), the SAME two
@@ -60,6 +102,13 @@ const bodyClipStyle: CSSProperties = {
 const headerWrapStyle: CSSProperties = {
   padding: 'var(--vx-space-card-inset-y, 0.6875rem) var(--vx-space-card-inset-x, 0.8125rem) 4px',
 }
+// A short card (wave 8) trims the header's own top inset — the subtitle line and the wide-tier
+// value/delta row are both already gone by the time `short` is true, so the full card inset reads
+// as dead air rather than rhythm. Bottom stays 4px (unchanged) so the header-to-body seam matches
+// every other ChartCard.
+const headerWrapShortStyle: CSSProperties = {
+  padding: '4px var(--vx-space-card-inset-x, 0.8125rem) 4px',
+}
 
 /**
  * The three boxes a `ChartCard` paints, and therefore the slot set a consumer may class
@@ -143,6 +192,8 @@ export function ChartCard({
   style,
   children,
 }: ChartCardProps) {
+  const [legendSlot, setLegendSlot] = useState<HTMLDivElement | null>(null)
+  const { ref: sizeRef, height: measuredHeight } = useChartSize()
   const resolvedState = resolveChartState({ ...(state !== undefined && { state }) })
   const hasHeader =
     title !== undefined ||
@@ -151,59 +202,101 @@ export function ChartCard({
     actions !== undefined ||
     icon !== undefined ||
     count !== undefined
+  // Hysteresis (P0-1, `SHORT_EXIT_SLACK`'s own doc): which threshold applies depends on the
+  // PREVIOUS committed flag, so a card whose unfolded height sits in the bistable band settles
+  // instead of flip-flopping forever.
+  const short = useHysteresis(
+    (wasShort) =>
+      measuredHeight > 0 &&
+      measuredHeight < (wasShort ? CARD_SHORT_HEIGHT + SHORT_EXIT_SLACK : CARD_SHORT_HEIGHT),
+    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 context = useMemo(
+    () => ({
+      legendSlot,
+      inCard: true,
+      short,
+      claimLegendSlot,
+      releaseLegendSlot,
+      legendSlotVersion,
+    }),
+    [legendSlot, short, claimLegendSlot, releaseLegendSlot, legendSlotVersion],
+  )
 
   return (
-    <div
-      className={cx(classNames?.root, className)}
-      style={{ ...cardStyle, ...style }}
-      {...(resolvedState === 'pending' && { 'aria-busy': 'true' })}
-    >
-      {hasHeader && (
-        <div
-          {...(classNames?.header !== undefined && { className: classNames.header })}
-          style={headerWrapStyle}
-        >
-          <WidgetHeader
-            tier="widget"
-            title={title ?? ''}
-            {...(icon !== undefined && { icon })}
-            {...(subtitle !== undefined && { subtitle })}
-            {...(info !== undefined && { info })}
-            {...(value !== undefined && { value })}
-            {...(delta !== undefined && { delta })}
-            {...(deltaPeriod !== undefined && { deltaPeriod })}
-            {...(deltaPolarity !== undefined && { deltaPolarity })}
-            {...(count !== undefined && { count })}
-            {...(actions !== undefined && {
-              actions: <span data-basalt-tier="widget">{actions}</span>,
-            })}
-          />
-        </div>
-      )}
+    <ChartCardContext.Provider value={context}>
       <div
-        {...(classNames?.body !== undefined && { className: classNames.body })}
-        style={bodyClipStyle}
+        ref={sizeRef}
+        className={cx(classNames?.root, className)}
+        style={{ ...cardStyle, ...style }}
+        {...(resolvedState === 'pending' && { 'aria-busy': 'true' })}
+        {...(short && { 'data-basalt-card-short': '' })}
       >
-        {resolvedState === 'pending' ? (
-          <ChartPending width="100%" height={placeholderHeight} />
-        ) : resolvedState === 'error' ? (
-          <ChartError
-            width="100%"
-            height={placeholderHeight}
-            error={state?.error}
-            action={stateAction}
-          />
-        ) : resolvedState === 'empty' ? (
-          <ChartEmpty
-            width="100%"
-            height={placeholderHeight}
-            {...(typeof state?.empty === 'string' && { label: state.empty })}
-            action={stateAction}
-          />
-        ) : (
-          children
+        {hasHeader && (
+          <div
+            {...(classNames?.header !== undefined && { className: classNames.header })}
+            style={short ? headerWrapShortStyle : headerWrapStyle}
+          >
+            <WidgetHeader
+              tier="widget"
+              title={title ?? ''}
+              {...(icon !== undefined && { icon })}
+              {...(subtitle !== undefined && { subtitle })}
+              {...(info !== undefined && { info })}
+              {...(value !== undefined && { value })}
+              {...(delta !== undefined && { delta })}
+              {...(deltaPeriod !== undefined && { deltaPeriod })}
+              {...(deltaPolarity !== undefined && { deltaPolarity })}
+              {...(count !== undefined && { count })}
+              {...(actions !== undefined && {
+                actions: <span data-basalt-tier="widget">{actions}</span>,
+              })}
+            />
+            <div ref={setLegendSlot} data-basalt-legend-slot="" />
+          </div>
         )}
+        <div
+          {...(classNames?.body !== undefined && { className: classNames.body })}
+          style={bodyClipStyle}
+        >
+          {resolvedState === 'pending' ? (
+            <ChartPending width="100%" height={placeholderHeight} />
+          ) : resolvedState === 'error' ? (
+            <ChartError
+              width="100%"
+              height={placeholderHeight}
+              error={state?.error}
+              action={stateAction}
+            />
+          ) : resolvedState === 'empty' ? (
+            <ChartEmpty
+              width="100%"
+              height={placeholderHeight}
+              {...(typeof state?.empty === 'string' && { label: state.empty })}
+              action={stateAction}
+            />
+          ) : (
+            children
+          )}
+        </div>
       </div>
-    </div>
+    </ChartCardContext.Provider>
   )
 }

package/src/charts/primitives/ChartFrame.tsx

@@ -1,35 +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 { ignoredProp } from '../../common/errors'
-import { useValidateProps } from '../../common/validate'
+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
@@ -38,22 +36,12 @@ export type ChartFrameLegend = {
   /** Default 'bottom'. */
   placement?: LegendPlacement
   /**
-   * Rollup cap at high cardinality: the legend renders this many ENTRIES and folds the remainder
-   * into a `+N more` disclosure chip.
+   * @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.
    *
-   * **It counts entries, not rows** — the name is inherited and now load-bearing across
-   * `ChartTierMetrics.legendMaxRows`, so it is not renamed in a patch. `maxRows: 3` on a 7-entry
-   * legend renders three entries, which is ONE row at any width they fit on. `ChartLegend` slices
-   * (`entries.slice(0, cap)`); nothing here measures rows.
-   *
-   * 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. */
@@ -68,20 +56,32 @@ 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. Passing it WITH `fill` is a wiring mistake, not a fallback — `fill` wins and
+   * 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 — which warns
@@ -136,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 => ({
@@ -219,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) => {
@@ -255,25 +357,91 @@ export function ChartFrame({
     ],
     [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],
+  )
 
-  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 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
@@ -283,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,
@@ -300,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}
@@ -310,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 })}
         />
@@ -317,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' ? (
@@ -339,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>
   )