basalt-ui 1.30.2 → 1.31.0

package/dist/charts/primitives/ChartCard.js

@@ -1,9 +1,20 @@
 import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef, useState } from "react";
 import { cx } from "../../common/props.js";
 import { VX } from "../../tokens/index.js";
 import { WidgetHeader } from "../../dashboard/widget-header.js";
+import { useChartSize } from "../hooks/useChartSize.js";
+import { useHysteresis } from "../hooks/use-hysteresis.js";
+import { ChartCardContext } from "./chart-card-context.js";
 import { ChartEmpty, ChartError, ChartPending, resolveChartState } from "./ChartPending.js";
+const CARD_SHORT_HEIGHT = 280;
+const SHORT_EXIT_SLACK = 24;
 const cardStyle = {
+  display: "flex",
+  flexDirection: "column",
+  minHeight: 0,
+  containerType: "inline-size",
+  containerName: "basalt-card",
   borderRadius: VX.radiusCard,
   boxShadow: VX.shadowCard,
   backgroundColor: VX.surface.panel
@@ -17,11 +28,19 @@ const bodyClipStyle = {
   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)"
 };
 const headerWrapStyle = {
   padding: "var(--vx-space-card-inset-y, 0.6875rem) var(--vx-space-card-inset-x, 0.8125rem) 4px"
 };
+const headerWrapShortStyle = {
+  padding: "4px var(--vx-space-card-inset-x, 0.8125rem) 4px"
+};
 function ChartCard({
   title,
   icon,
@@ -41,38 +60,72 @@ function ChartCard({
   style,
   children
 }) {
+  const [legendSlot, setLegendSlot] = useState(null);
+  const { ref: sizeRef, height: measuredHeight } = useChartSize();
   const resolvedState = resolveChartState({ ...state !== void 0 && { state } });
   const hasHeader = title !== void 0 || info !== void 0 || value !== void 0 || actions !== void 0 || icon !== void 0 || count !== void 0;
-  return /* @__PURE__ */ jsxs(
+  const short = useHysteresis(
+    (wasShort) => measuredHeight > 0 && measuredHeight < (wasShort ? CARD_SHORT_HEIGHT + SHORT_EXIT_SLACK : CARD_SHORT_HEIGHT),
+    false
+  );
+  const legendOwnerRef = useRef(null);
+  const [legendSlotVersion, setLegendSlotVersion] = useState(0);
+  const claimLegendSlot = useCallback((id) => {
+    if (legendOwnerRef.current === null) legendOwnerRef.current = id;
+    return legendOwnerRef.current === id;
+  }, []);
+  const releaseLegendSlot = useCallback((id) => {
+    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 /* @__PURE__ */ jsx(ChartCardContext.Provider, { value: context, children: /* @__PURE__ */ jsxs(
     "div",
     {
+      ref: sizeRef,
       className: cx(classNames?.root, className),
       style: { ...cardStyle, ...style },
       ...resolvedState === "pending" && { "aria-busy": "true" },
+      ...short && { "data-basalt-card-short": "" },
       children: [
-        hasHeader && /* @__PURE__ */ jsx(
+        hasHeader && /* @__PURE__ */ jsxs(
           "div",
           {
             ...classNames?.header !== void 0 && { className: classNames.header },
-            style: headerWrapStyle,
-            children: /* @__PURE__ */ jsx(
-              WidgetHeader,
-              {
-                tier: "widget",
-                title: title ?? "",
-                ...icon !== void 0 && { icon },
-                ...subtitle !== void 0 && { subtitle },
-                ...info !== void 0 && { info },
-                ...value !== void 0 && { value },
-                ...delta !== void 0 && { delta },
-                ...deltaPeriod !== void 0 && { deltaPeriod },
-                ...deltaPolarity !== void 0 && { deltaPolarity },
-                ...count !== void 0 && { count },
-                ...actions !== void 0 && {
-                  actions: /* @__PURE__ */ jsx("span", { "data-basalt-tier": "widget", children: actions })
+            style: short ? headerWrapShortStyle : headerWrapStyle,
+            children: [
+              /* @__PURE__ */ jsx(
+                WidgetHeader,
+                {
+                  tier: "widget",
+                  title: title ?? "",
+                  ...icon !== void 0 && { icon },
+                  ...subtitle !== void 0 && { subtitle },
+                  ...info !== void 0 && { info },
+                  ...value !== void 0 && { value },
+                  ...delta !== void 0 && { delta },
+                  ...deltaPeriod !== void 0 && { deltaPeriod },
+                  ...deltaPolarity !== void 0 && { deltaPolarity },
+                  ...count !== void 0 && { count },
+                  ...actions !== void 0 && {
+                    actions: /* @__PURE__ */ jsx("span", { "data-basalt-tier": "widget", children: actions })
+                  }
                 }
-              }
-            )
+              ),
+              /* @__PURE__ */ jsx("div", { ref: setLegendSlot, "data-basalt-legend-slot": "" })
+            ]
           }
         ),
         /* @__PURE__ */ jsx(
@@ -101,7 +154,7 @@ function ChartCard({
         )
       ]
     }
-  );
+  ) });
 }
 export {
   ChartCard

package/dist/charts/primitives/ChartFrame.d.ts

@@ -5,7 +5,7 @@ import type { ResponsiveChartHeight } from './chart-frame-layout.js';
 import type { ChartState } from './ChartPending.js';
 /** 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.js';
+export { legendEntryCap, resolveLegendRollup, resolvePlotRect } from './chart-frame-layout.js';
 export type { ResponsiveChartHeight } from './chart-frame-layout.js';
 /** Legend configuration for {@link ChartFrame}. Omit entirely (or pass `{}`) for the default
  * bottom-placed legend; pass `false` only for the sparkline exemption. */
@@ -13,22 +13,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. */
@@ -43,19 +33,31 @@ 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
@@ -109,6 +111,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;
 };
 /** A kind's own hover-dim wiring, merged into the resolved `ChartFrameLegend`. Kinds without
  * per-series highlight state (single-series `ZonedLine`, `DualPanel`) omit this. */

package/dist/charts/primitives/ChartFrame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartFrame.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartFrame.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAMrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAOhF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAIjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEhD;qGACqG;AACrG,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,gBAAgB,GACjB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAKjE;0EAC0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC1C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C,uGAAuG;IACvG,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IAC9B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,qBAAqB,CAAA;IACvC;yDACqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uFAAuF;IACvF,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAA;IACjC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;oDACgD;IAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,SAAS,CAAA;CACxC,CAAA;AAED,0FAA0F;AAC1F,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAC5B,CAAA;AAcD;oFACoF;AACpF,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,KAAK,CAAC,EAAE,qBAAqB,EAC7B,WAAW,CAAC,EAAE,MAAM,GACnB,gBAAgB,GAAG,KAAK,CAU1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,MAAM,EACN,WAAW,EACX,IAAY,EACZ,QAA4B,EAC5B,OAAO,EACP,MAAW,EACX,SAAS,EACT,SAAiB,EACjB,KAAK,EACL,SAAS,EACT,KAAK,EACL,QAAQ,GACT,EAAE,eAAe,GAAG,SAAS,CAiI7B"}
+{"version":3,"file":"ChartFrame.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartFrame.tsx"],"names":[],"mappings":"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"}

package/dist/charts/primitives/ChartFrame.js

@@ -1,26 +1,24 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import { useCallback, useState } from "react";
-import { ignoredProp } from "../../common/errors.js";
-import { useValidateProps } from "../../common/validate.js";
+import { useCallback, useContext, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import {
+  deprecatedProp,
+  ignoredProp,
+  legendSlotContention,
+  plotBelowFloor
+} from "../../common/errors.js";
+import { reportOnce, useValidateProps } from "../../common/validate.js";
+import { SizeClassHintContext, useSizeClass } from "../../shell/use-size-class.js";
 import { VX } from "../../tokens/index.js";
 import { useChartSize } from "../hooks/useChartSize.js";
 import { deriveLegend } from "../series.js";
-import {
-  resolveChartTier,
-  resolveFrameHeight,
-  resolveLegendRollup,
-  resolvePlotRect
-} from "./chart-frame-layout.js";
-import { ChartTierProvider } from "./chart-tier.js";
+import { ChartCardContext } from "./chart-card-context.js";
+import { resolveChartLayout, resolveFrameClass } from "./chart-layout.js";
+import { resolveFrameHeight, resolveLegendRollup, resolvePlotRect } from "./chart-frame-layout.js";
+import { ChartTierProvider, useCoarsePointer, useViewportHeight } from "./chart-tier.js";
 import { ChartLegend } from "./ChartLegend.js";
 import { ChartEmpty, ChartError, ChartPending, resolveChartState } from "./ChartPending.js";
-import {
-  legendEntryCap,
-  resolveLegendRollup as resolveLegendRollup2,
-  resolvePlotRect as resolvePlotRect2,
-  resolveChartTier as resolveChartTier2
-} from "./chart-frame-layout.js";
-const DEFAULT_HEIGHT = 240;
+import { legendEntryCap, resolveLegendRollup as resolveLegendRollup2, resolvePlotRect as resolvePlotRect2 } from "./chart-frame-layout.js";
 const DEFAULT_MIN_WIDTH = 200;
 const outerStyle = (fill, vertical) => ({
   width: "100%",
@@ -60,6 +58,61 @@ function ChartFrame({
 }) {
   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);
+  const ownsSlotRef = useRef(false);
+  const placement = legend === false ? "bottom" : legend.placement ?? "bottom";
+  const vertical = placement === "left" || placement === "right";
+  const wantsHeaderSlot = legend !== false && legend.headerSlot !== false && !vertical;
+  const resolvedState = resolveChartState({ ...state !== void 0 && { state }, isPending });
+  const legendVisible = legend !== false && resolvedState === null;
+  const tryClaim = useCallback(() => {
+    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;
+    }
+    setSlotSeedW(legendSlot.getBoundingClientRect().width);
+    slotRef(legendSlot);
+    return true;
+  }, [legendSlot, wantsHeaderSlot, legendVisible, frameId, claimLegendSlot, slotRef]);
+  const releaseIfOwned = useCallback(() => {
+    if (!ownsSlotRef.current) return;
+    ownsSlotRef.current = false;
+    releaseLegendSlot(frameId);
+    slotRef(null);
+  }, [releaseLegendSlot, frameId, slotRef]);
+  useLayoutEffect(() => {
+    if (legendSlot === null || !wantsHeaderSlot) {
+      setOwnsSlot(false);
+      setSlotSeedW(0);
+      return void 0;
+    }
+    tryClaim();
+    return releaseIfOwned;
+  }, [legendSlot, wantsHeaderSlot, tryClaim, releaseIfOwned]);
+  useLayoutEffect(() => {
+    if (ownsSlotRef.current) return;
+    tryClaim();
+  }, [legendSlotVersion]);
+  const viewportClass = useSizeClass();
+  const sizeClass = useContext(SizeClassHintContext) === void 0 ? "medium" : viewportClass;
+  const coarse = useCoarsePointer();
+  const viewportH = useViewportHeight();
   const [hidden, setHidden] = useState(() => /* @__PURE__ */ new Set());
   const toggleKey = useCallback((key) => {
     setHidden((prev) => {
@@ -85,20 +138,61 @@ function ChartFrame({
     ],
     [fill, height, aspectRatio]
   );
-  const placement = legend === false ? "bottom" : legend.placement ?? "bottom";
-  const vertical = placement === "left" || placement === "right";
-  const resolvedState = resolveChartState({ ...state !== void 0 && { state }, isPending });
-  const legendVisible = legend !== false && resolvedState === null;
-  const tier = resolveChartTier(containerW);
-  const resolvedHeight = fill ? containerH : aspectRatio !== void 0 ? Math.round(containerW / aspectRatio) : resolveFrameHeight(height ?? DEFAULT_HEIGHT, containerW);
-  const sideLegendWidth = legendVisible && vertical ? legendW : 0;
-  const topBottomLegendHeight = legendVisible && !vertical ? legendH : 0;
   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 !== void 0 && 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 === void 0 ? void 0 : resolveFrameHeight(height, resolveFrameClass({ frameW: containerW, sizeClass }));
+  const slotW = legendSlot === null || !ownsSlot ? 0 : Math.max(slotMeasuredW, slotSeedW);
+  const groups = legend !== false && legend.groups === true;
+  const legendKey = legendItems.map((item) => `${item.key}\0${item.label}\0${item.role ?? ""}\0${item.note ?? ""}`).join("
");
+  const layout = useMemo(
+    () => resolveChartLayout({
+      frameW: containerW,
+      slotW,
+      viewportH,
+      legendItems,
+      sizeClass,
+      coarse,
+      cardShort,
+      groups,
+      ...statedHeight !== void 0 && { 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 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 !== void 0 ? Math.round(containerW / aspectRatio) : layout.height;
+  const grows = inCard && !fill;
+  const resolvedHeight = fill ? containerH : grows ? Math.max(computedHeight, containerH) : computedHeight;
+  const cardMinHeight = Math.max(computedHeight, VX.minPlotHeight + topBottomLegendHeight);
+  useValidateProps(
+    "ChartFrame",
+    () => typeof height === "number" && !fill && aspectRatio === void 0 && height - topBottomLegendHeight < VX.minPlotHeight ? plotBelowFloor("ChartFrame", height, VX.minPlotHeight) : null,
+    [height, fill, aspectRatio, topBottomLegendHeight]
+  );
   const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1);
   const { maxRows, legendWins } = resolveLegendRollup({
     ...legend !== false && legend.maxRows !== void 0 && { 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
@@ -111,7 +205,7 @@ function ChartFrame({
     topBottomLegendHeight,
     ...legendWins && { legendWins }
   });
-  const legendNode = legend === false || resolvedState !== null ? null : /* @__PURE__ */ jsx("div", { ref: legendRef, style: legendWrapperStyle(vertical), children: /* @__PURE__ */ jsx(
+  const legendNode = legend === false || resolvedState !== null || !showLegend ? null : /* @__PURE__ */ jsx("div", { ref: legendRef, style: legendWrapperStyle(vertical), children: /* @__PURE__ */ jsx(
     ChartLegend,
     {
       items: legendItems,
@@ -121,20 +215,26 @@ function ChartFrame({
       ...chartId !== void 0 && { chartId },
       ...legend.groups !== void 0 && { groups: legend.groups },
       ...maxRows !== void 0 && { maxRows },
+      ...legendMode !== void 0 && { mode: legendMode },
       ...legend.highlighted !== void 0 && { highlighted: legend.highlighted },
       ...legend.onHighlight !== void 0 && { onHighlight: legend.onHighlight }
     }
   ) });
-  return /* @__PURE__ */ jsx(ChartTierProvider, { tier, children: /* @__PURE__ */ jsxs(
+  return /* @__PURE__ */ jsx(ChartTierProvider, { containerClass: layout.containerClass, children: /* @__PURE__ */ jsxs(
     "div",
     {
       ref: containerRef,
       ...className !== void 0 && { className },
-      style: { ...outerStyle(fill, vertical), ...style },
+      style: {
+        ...outerStyle(fill, vertical),
+        ...grows && { flex: "1 1 0", minHeight: cardMinHeight },
+        ...style
+      },
       ...ariaLabel !== void 0 && { role: "group", "aria-label": ariaLabel },
       ...resolvedState === "pending" && { "aria-busy": "true" },
       children: [
-        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" ? /* @__PURE__ */ jsx(ChartPending, { width: plot.width, height: plot.height }) : resolvedState === "error" ? /* @__PURE__ */ jsx(ChartError, { width: plot.width, height: plot.height, error: state?.error }) : resolvedState === "empty" ? /* @__PURE__ */ jsx(
           ChartEmpty,
           {
@@ -142,8 +242,8 @@ function ChartFrame({
             height: plot.height,
             ...typeof state?.empty === "string" && { label: state.empty }
           }
-        ) : children({ ...plot, hidden })),
-        legendNode !== null && (placement === "bottom" || placement === "right") && legendNode
+        ) : children({ ...plot, hidden, legendInHeader: inHeader })),
+        !inHeader && legendNode !== null && (placement === "bottom" || placement === "right") && legendNode
       ]
     }
   ) });
@@ -151,7 +251,6 @@ function ChartFrame({
 export {
   ChartFrame,
   legendEntryCap,
-  resolveChartTier2 as resolveChartTier,
   resolveLegend,
   resolveLegendRollup2 as resolveLegendRollup,
   resolvePlotRect2 as resolvePlotRect

package/dist/charts/primitives/ChartLegend.d.ts

@@ -28,26 +28,21 @@ export type LegendEntry = {
  * static legends without hover interactivity. `chartId` namespaces `split` clipPath ids so two
  * legends on the same page never collide. `groups` renders series → hairline divider → overlay →
  * reference bands instead of one flat smear. `maxRows` caps the number of rendered ENTRIES and
- * rolls the remainder into a `+N more` chip — it is an entry count, not a row count, in spite of
- * the name (`entries.slice(0, cap)` below is the whole of it, and `ChartFrame` measures rows for a
- * different purpose in `legendEntryCap`). The name is inherited and reaches the public
- * `ChartTierMetrics.legendMaxRows`, so it stays until a minor can rename both.
+ * rolls the remainder into an `All N` disclosure chip — it is an entry count, not a row count, in
+ * spite of the name (`entries.slice(0, cap)` below is the whole of it). `ChartFrame` derives the
+ * cap from the measured fit (`resolveChartLayout().legend`); a caller-stated value wins.
  *
  * `onToggle` makes an entry a real toggle: clicking it hides the series in the plot, the tooltip,
  * and the auto y-domain together (`ChartFrame` owns the `hidden` set — see `docs/CHARTS-SPEC.md`
- * §5).
+ * §5). A hidden entry is announced via `aria-pressed`.
  *
- * The label font and the DEFAULT entry cap both track the ambient chart tier (§8): inside a
- * phone-width `ChartFrame` the legend drops one type step and rolls up past two entries. An
- * explicit `maxRows` always wins. Omit it for a static legend; a hidden entry is announced via `aria-pressed`.
- *
- * **The rollup is a disclosure, not a label.** A cap of two leaves six of eight plotted colours
- * unnamed, and a `+6 more` that is a `<span>` gives a phone reader no way to learn them — a
- * categorical encoding the chart draws and refuses to decode. The chip is a `<button>` carrying
- * `aria-expanded`: expanded, every entry renders, the legend band grows, and `ChartFrame`'s
- * observer re-flows the frame around it (the plot keeps `VX.minPlotHeight`).
+ * **The rollup is a disclosure, not a label.** `All N` is a `<button>` carrying `aria-expanded`
+ * that opens EVERY entry, toggles included, in a popover under the chip on a fine pointer and a
+ * bottom sheet on a coarse one. Both are fixed-position and portalled, so opening one never grows
+ * the legend band or moves the plot. Escape, an outside press, a scroll or a resize closes it, and
+ * focus returns to the chip on every close.
  */
-export declare function ChartLegend({ items, highlighted, onHighlight, hidden, onToggle, chartId, placement, groups, maxRows, className, style, }: BasaltProps & {
+export declare function ChartLegend({ items, highlighted, onHighlight, hidden, onToggle, chartId, placement, groups, maxRows, mode, className, style, }: BasaltProps & {
     items: LegendEntry[];
     highlighted?: string | null;
     onHighlight?: (key: string | null) => void;
@@ -59,5 +54,14 @@ export declare function ChartLegend({ items, highlighted, onHighlight, hidden, o
     placement?: LegendPlacement;
     groups?: boolean;
     maxRows?: number;
+    /**
+     * `'dots'` collapses every VISIBLE entry to a plain color dot with no label (the name still
+     * reaches assistive tech via `aria-label`) — `resolveChartLayout`'s header-slot legend forces
+     * this for a short `ChartCard` (wave 11, `docs/CHARTS-SPEC.md` §5) so the legend band's height and
+     * width both shrink before it eats plot space. The `All N` disclosure panel is unaffected: it
+     * always shows the full swatch + label, `mode` only governs the inline row. Default `'chips'`
+     * (today's swatch + label rendering) for every other caller.
+     */
+    mode?: 'dots' | 'chips';
 }): import("react").JSX.Element;
 //# sourceMappingURL=ChartLegend.d.ts.map

package/dist/charts/primitives/ChartLegend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartLegend.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartLegend.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAG5D,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,WAAW,CAAA;IAC9C,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kGAAkG;IAClG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;0EACsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mFAAmF;IACnF,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB;iFAC6E;IAC7E,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;IACxB;gCAC4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAgOD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,WAAkB,EAClB,WAAW,EACX,MAAkB,EAClB,QAAQ,EACR,OAAY,EACZ,SAAoB,EACpB,MAAc,EACd,OAAO,EACP,SAAS,EACT,KAAK,GACN,EAAE,WAAW,GAAG;IACf,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC1C,kCAAkC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,+BAkFA"}
+{"version":3,"file":"ChartLegend.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartLegend.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAGrD,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAI5D,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,WAAW,CAAA;IAC9C,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kGAAkG;IAClG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;0EACsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mFAAmF;IACnF,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB;iFAC6E;IAC7E,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;IACxB;gCAC4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAuRD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,WAAkB,EAClB,WAAW,EACX,MAAkB,EAClB,QAAQ,EACR,OAAY,EACZ,SAAoB,EACpB,MAAc,EACd,OAAO,EACP,IAAc,EACd,SAAS,EACT,KAAK,GACN,EAAE,WAAW,GAAG;IACf,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC1C,kCAAkC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACxB,+BA2MA"}