basalt-ui 1.27.0 → 1.29.0

package/dist/charts/primitives/ChartCard.js

@@ -1,6 +1,8 @@
 import { jsx, jsxs } from "react/jsx-runtime";
+import { cx } from "../../common/props.js";
 import { VX } from "../../tokens/index.js";
-import { WidgetHeader } from "../../widget-header/index.js";
+import { WidgetHeader } from "../../dashboard/widget-header.js";
+import { ChartEmpty, ChartError, ChartPending, resolveChartState } from "./ChartPending.js";
 const cardStyle = {
   borderRadius: VX.radiusCard,
   boxShadow: VX.shadowCard,
@@ -28,31 +30,78 @@ function ChartCard({
   value,
   delta,
   deltaPeriod,
+  deltaPolarity,
   count,
   actions,
+  state,
+  placeholderHeight = 240,
+  stateAction,
+  className,
+  classNames,
+  style,
   children
 }) {
+  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("div", { style: cardStyle, children: [
-    hasHeader && /* @__PURE__ */ jsx("div", { 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 },
-        ...count !== void 0 && { count },
-        ...actions !== void 0 && {
-          actions: /* @__PURE__ */ jsx("span", { "data-basalt-tier": "widget", children: actions })
-        }
-      }
-    ) }),
-    /* @__PURE__ */ jsx("div", { style: bodyClipStyle, children })
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cx(classNames?.root, className),
+      style: { ...cardStyle, ...style },
+      ...resolvedState === "pending" && { "aria-busy": "true" },
+      children: [
+        hasHeader && /* @__PURE__ */ jsx(
+          "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 })
+                }
+              }
+            )
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            ...classNames?.body !== void 0 && { className: classNames.body },
+            style: bodyClipStyle,
+            children: resolvedState === "pending" ? /* @__PURE__ */ jsx(ChartPending, { width: "100%", height: placeholderHeight }) : resolvedState === "error" ? /* @__PURE__ */ jsx(
+              ChartError,
+              {
+                width: "100%",
+                height: placeholderHeight,
+                error: state?.error,
+                action: stateAction
+              }
+            ) : resolvedState === "empty" ? /* @__PURE__ */ jsx(
+              ChartEmpty,
+              {
+                width: "100%",
+                height: placeholderHeight,
+                ...typeof state?.empty === "string" && { label: state.empty },
+                action: stateAction
+              }
+            ) : children
+          }
+        )
+      ]
+    }
+  );
 }
 export {
   ChartCard

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

@@ -1,5 +1,10 @@
 import type { ReactNode } from 'react';
+import type { BasaltProps } from '../../common/props.js';
 import type { ChartLegendConfig, LegendPlacement, SeriesStyle } from '../series.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, resolvePlotRect, resolveChartTier } 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. */
 export type ChartFrameLegend = {
@@ -20,7 +25,7 @@ export type ChartFrameLegend = {
      */
     toggle?: boolean;
 };
-export type ChartFrameProps = {
+export type ChartFrameProps = BasaltProps & {
     /** Series identity — drives the derived legend. Pass the SAME array the kind draws + tooltips from. */
     series: readonly SeriesStyle[];
     /** Fixed height in pixels. Used when neither `aspectRatio` nor `fill` is set. Default 240. */
@@ -40,8 +45,19 @@ export type ChartFrameProps = {
      * three-state "nothing to draw" rationale) over the full plot rect in place of `children`,
      * suppresses the legend entirely (a legend naming a series with nothing yet to point at is its
      * own small lie), and marks the outer container `aria-busy="true"`.
+     *
+     * An alias for `state={{ pending: true }}` and staying that way — it predates {@link ChartState}
+     * and every kind forwards it.
      */
     isPending?: boolean;
+    /**
+     * The three "nothing to draw" states in one prop — the shape a query result already has. Wins
+     * over `isPending`, which stays a supported alias for `state={{ pending: true }}`. Precedence is
+     * pending → error → empty ({@link resolveChartState}); each renders its own placeholder over the
+     * full plot rect in place of `children` and suppresses the legend, and only `pending` marks the
+     * container `aria-busy`.
+     */
+    state?: ChartState;
     /**
      * Accessible text alternative for the chart, applied as `aria-label` (+ `role="group"`) on the
      * outer container so screen readers announce something other than an unlabeled graphic. Every
@@ -77,8 +93,16 @@ export type ChartFrameLegendHover = {
  * is the one merge every kind performs: consumer `placement`/`groups`/`maxRows` (or the defaults)
  * plus the kind's `highlighted`/`onHighlight`, which a consumer may not set directly.
  * `config === false` disables the legend regardless of `hover` (the sparkline escape).
+ *
+ * A single-entry legend is pure noise — it only ever restates the chart's own title ("— BTC
+ * price" under a chart already titled "BTC price"), costs a legend row of vertical space, and its
+ * one toggle can blank the whole plot. So when `seriesCount` is passed, is `<= 1`, AND the caller
+ * passed no explicit config (`undefined` — NOT `{}`, which is a deliberate opt-in), the legend is
+ * suppressed automatically. `config === undefined` is the load-bearing check: a kind that composes
+ * `ChartFrame` directly without threading `seriesCount` through (e.g. `DualPanel`) simply omits
+ * the third argument and keeps today's behaviour.
  */
-export declare function resolveLegend(config: ChartLegendConfig | false | undefined, hover?: ChartFrameLegendHover): ChartFrameLegend | false;
+export declare function resolveLegend(config: ChartLegendConfig | false | undefined, hover?: ChartFrameLegendHover, seriesCount?: number): ChartFrameLegend | false;
 /**
  * The measuring, legend-owning shell every non-sparkline chart composes. Supersedes
  * `ResponsiveChart`'s job and adds the two things it lacked: it observes height (via
@@ -86,10 +110,12 @@ export declare function resolveLegend(config: ChartLegendConfig | false | undefi
  * rect via a second, independent `useChartSize` on the legend's own wrapper div. The legend
  * `<div>` wraps (`ChartLegend`'s `flexWrap`), so its measured band grows as entries wrap and the
  * plot shrinks accordingly — the plot can never overlap the legend because the legend's measured
- * band is always subtracted first.
+ * band is always subtracted first. It also can never shrink to nothing: {@link resolvePlotRect}
+ * floors it at `VX.minPlotHeight` and the frame grows, or under `fill` the legend rolls up
+ * ({@link legendEntryCap}).
  *
  * Layout-only: it does not know lines from bars (that stays in the kind), so it is not a
  * Recharts god-component. Render the child only when the resolved plot rect is non-empty.
  */
-export declare function ChartFrame({ series, height, aspectRatio, fill, minWidth, chartId, legend, ariaLabel, isPending, children, }: ChartFrameProps): ReactNode;
+export declare function ChartFrame({ series, height, aspectRatio, fill, minWidth, chartId, legend, ariaLabel, isPending, state, className, style, children, }: ChartFrameProps): ReactNode;
 //# sourceMappingURL=ChartFrame.d.ts.map

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;AAIrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAOhF;0EAC0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,uDAAuD;IACvD,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;IAC5B,uGAAuG;IACvG,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IAC9B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,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;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;;;;;;;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;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,KAAK,CAAC,EAAE,qBAAqB,GAC5B,gBAAgB,GAAG,KAAK,CAS1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,MAAM,EACN,WAAW,EACX,IAAY,EACZ,QAA4B,EAC5B,OAAO,EACP,MAAW,EACX,SAAS,EACT,SAAiB,EACjB,QAAQ,GACT,EAAE,eAAe,GAAG,SAAS,CAsE7B"}
+{"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;AAIrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAUhF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEhD;qGACqG;AACrG,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAKxF;0EAC0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,uDAAuD;IACvD,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,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,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,CAmH7B"}

package/dist/charts/primitives/ChartFrame.js

@@ -1,9 +1,18 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useCallback, useState } from "react";
+import { VX } from "../../tokens/index.js";
 import { useChartSize } from "../hooks/useChartSize.js";
 import { deriveLegend } from "../series.js";
+import {
+  chartTierMetrics,
+  legendEntryCap,
+  resolveChartTier,
+  resolvePlotRect
+} from "./chart-frame-layout.js";
+import { ChartTierProvider } from "./chart-tier.js";
 import { ChartLegend } from "./ChartLegend.js";
-import { ChartPending } from "./ChartPending.js";
+import { ChartEmpty, ChartError, ChartPending, resolveChartState } from "./ChartPending.js";
+import { legendEntryCap as legendEntryCap2, resolvePlotRect as resolvePlotRect2, resolveChartTier as resolveChartTier2 } from "./chart-frame-layout.js";
 const DEFAULT_HEIGHT = 240;
 const DEFAULT_MIN_WIDTH = 200;
 const outerStyle = (fill, vertical) => ({
@@ -16,8 +25,9 @@ const legendWrapperStyle = (vertical) => ({
   flexShrink: 0,
   width: vertical ? void 0 : "100%"
 });
-function resolveLegend(config, hover) {
+function resolveLegend(config, hover, seriesCount) {
   if (config === false) return false;
+  if (config === void 0 && seriesCount !== void 0 && seriesCount <= 1) return false;
   return {
     placement: config?.placement ?? "bottom",
     ...config?.groups !== void 0 && { groups: config.groups },
@@ -36,6 +46,9 @@ function ChartFrame({
   legend = {},
   ariaLabel,
   isPending = false,
+  state,
+  className,
+  style,
   children
 }) {
   const { ref: containerRef, width: containerW, height: containerH } = useChartSize();
@@ -51,17 +64,30 @@ function ChartFrame({
   }, []);
   const placement = legend === false ? "bottom" : legend.placement ?? "bottom";
   const vertical = placement === "left" || placement === "right";
-  const legendVisible = legend !== false && !isPending;
+  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) : height ?? DEFAULT_HEIGHT;
   const sideLegendWidth = legendVisible && vertical ? legendW : 0;
   const topBottomLegendHeight = legendVisible && !vertical ? legendH : 0;
-  const plot = {
-    width: Math.max(containerW - sideLegendWidth, minWidth),
-    height: resolvedHeight - topBottomLegendHeight
-  };
+  const plot = resolvePlotRect({
+    containerW,
+    resolvedHeight,
+    minWidth,
+    sideLegendWidth,
+    topBottomLegendHeight
+  });
   const legendItems = legend === false ? [] : deriveLegend(series);
   const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1);
-  const legendNode = legend === false || isPending ? null : /* @__PURE__ */ jsx("div", { ref: legendRef, style: legendWrapperStyle(vertical), children: /* @__PURE__ */ jsx(
+  const tierMaxRows = chartTierMetrics(tier).legendMaxRows;
+  const callerMaxRows = legend === false ? void 0 : legend.maxRows === void 0 ? tierMaxRows : tierMaxRows === void 0 ? legend.maxRows : Math.min(legend.maxRows, tierMaxRows);
+  const maxRows = legend === false ? void 0 : fill && !vertical ? legendEntryCap({
+    items: legendItems,
+    containerW,
+    available: resolvedHeight - VX.minPlotHeight,
+    ...callerMaxRows !== void 0 && { callerMaxRows }
+  }) : callerMaxRows;
+  const legendNode = legend === false || resolvedState !== null ? null : /* @__PURE__ */ jsx("div", { ref: legendRef, style: legendWrapperStyle(vertical), children: /* @__PURE__ */ jsx(
     ChartLegend,
     {
       items: legendItems,
@@ -70,27 +96,38 @@ function ChartFrame({
       ...togglable && { onToggle: toggleKey },
       ...chartId !== void 0 && { chartId },
       ...legend.groups !== void 0 && { groups: legend.groups },
-      ...legend.maxRows !== void 0 && { maxRows: legend.maxRows },
+      ...maxRows !== void 0 && { maxRows },
       ...legend.highlighted !== void 0 && { highlighted: legend.highlighted },
       ...legend.onHighlight !== void 0 && { onHighlight: legend.onHighlight }
     }
   ) });
-  return /* @__PURE__ */ jsxs(
+  return /* @__PURE__ */ jsx(ChartTierProvider, { tier, children: /* @__PURE__ */ jsxs(
     "div",
     {
       ref: containerRef,
-      style: outerStyle(fill, vertical),
+      ...className !== void 0 && { className },
+      style: { ...outerStyle(fill, vertical), ...style },
       ...ariaLabel !== void 0 && { role: "group", "aria-label": ariaLabel },
-      ...isPending && { "aria-busy": "true" },
+      ...resolvedState === "pending" && { "aria-busy": "true" },
       children: [
         legendNode !== null && (placement === "top" || placement === "left") && legendNode,
-        plot.width > 0 && plot.height > 0 && (isPending ? /* @__PURE__ */ jsx(ChartPending, { width: plot.width, height: plot.height }) : children({ ...plot, hidden })),
+        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,
+          {
+            width: plot.width,
+            height: plot.height,
+            ...typeof state?.empty === "string" && { label: state.empty }
+          }
+        ) : children({ ...plot, hidden })),
         legendNode !== null && (placement === "bottom" || placement === "right") && legendNode
       ]
     }
-  );
+  ) });
 }
 export {
   ChartFrame,
-  resolveLegend
+  legendEntryCap2 as legendEntryCap,
+  resolveChartTier2 as resolveChartTier,
+  resolveLegend,
+  resolvePlotRect2 as resolvePlotRect
 };

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

@@ -1,3 +1,4 @@
+import type { BasaltProps } from '../../common/props.js';
 import type { SeriesRole, LegendPlacement } from '../series.js';
 export type LegendEntry = {
     key: string;
@@ -32,9 +33,19 @@ export type LegendEntry = {
  *
  * `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). Omit it for a static legend; a hidden entry is announced via `aria-pressed`.
+ * §5).
+ *
+ * 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`).
  */
-export declare function ChartLegend({ items, highlighted, onHighlight, hidden, onToggle, chartId, placement, groups, maxRows, }: {
+export declare function ChartLegend({ items, highlighted, onHighlight, hidden, onToggle, chartId, placement, groups, maxRows, className, style, }: BasaltProps & {
     items: LegendEntry[];
     highlighted?: string | null;
     onHighlight?: (key: string | null) => void;

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,UAAU,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAE5D,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;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,WAAkB,EAClB,WAAW,EACX,MAAkB,EAClB,QAAQ,EACR,OAAY,EACZ,SAAoB,EACpB,MAAc,EACd,OAAO,GACR,EAAE;IACD,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,+BAmEA"}
+{"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;;;;;;;;;;;;;;;;;;;;;GAqBG;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"}

package/dist/charts/primitives/ChartLegend.js

@@ -1,5 +1,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import { VX, alpha } from "../../tokens/index.js";
+import { useState } from "react";
+import { alpha, VX } from "../../tokens/index.js";
+import { useChartTierMetrics } from "./chart-tier.js";
 const LEGEND_ITEM_BASE = {
   display: "flex",
   alignItems: "center",
@@ -34,7 +36,7 @@ function orderEntries(items, groups) {
   });
   return { entries, dividerAfter };
 }
-function wrapperStyle(placement) {
+function wrapperStyle(placement, fontSize) {
   const vertical = placement === "left" || placement === "right";
   return {
     display: "flex",
@@ -45,7 +47,7 @@ function wrapperStyle(placement) {
     columnGap: VX.legendGap,
     rowGap: VX.legendGap,
     padding: "8px 0 2px",
-    fontSize: VX.legendFontSize,
+    fontSize,
     color: VX.muted
   };
 }
@@ -190,8 +192,12 @@ function ChartLegend({
   chartId = "",
   placement = "bottom",
   groups = false,
-  maxRows
+  maxRows,
+  className,
+  style
 }) {
+  const tier = useChartTierMetrics();
+  const [expanded, setExpanded] = useState(false);
   const handleEnter = (e) => {
     const key = e.currentTarget.dataset["legendKey"];
     if (key !== void 0) onHighlight?.(key);
@@ -204,8 +210,9 @@ function ChartLegend({
   const idPrefix = chartId ? `${chartId}-` : "";
   const vertical = placement === "left" || placement === "right";
   const { entries, dividerAfter } = orderEntries(items, groups);
-  const visible = maxRows !== void 0 && maxRows < entries.length ? entries.slice(0, maxRows) : entries;
-  const hiddenCount = entries.length - visible.length;
+  const cap = maxRows ?? tier.legendMaxRows;
+  const rolledUp = cap === void 0 ? 0 : Math.max(entries.length - cap, 0);
+  const visible = rolledUp > 0 && !expanded ? entries.slice(0, cap) : entries;
   const nodes = [];
   visible.forEach((item, i) => {
     nodes.push(
@@ -242,16 +249,29 @@ function ChartLegend({
     if (dividerAfter.has(i))
       nodes.push(/* @__PURE__ */ jsx(LegendDivider, { columnLayout: vertical }, `divider-${item.key}`));
   });
-  if (hiddenCount > 0) {
+  if (rolledUp > 0) {
     nodes.push(
-      /* @__PURE__ */ jsxs("span", { style: LEGEND_ITEM_BASE, children: [
-        "+",
-        hiddenCount,
-        " more"
-      ] }, "legend-more")
+      /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          "aria-expanded": expanded,
+          onClick: () => setExpanded((prev) => !prev),
+          style: { ...LEGEND_ITEM_BUTTON, cursor: "pointer", textDecoration: "underline" },
+          children: expanded ? "Show less" : `+${rolledUp} more`
+        },
+        "legend-more"
+      )
     );
   }
-  return /* @__PURE__ */ jsx("div", { style: wrapperStyle(placement), children: nodes });
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ...className !== void 0 && { className },
+      style: { ...wrapperStyle(placement, tier.legendFontSize), ...style },
+      children: nodes
+    }
+  );
 }
 export {
   ChartLegend

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

@@ -1,6 +1,9 @@
 import type { ReactNode } from 'react';
-export type ChartCenterProps = {
-    width: number;
+import type { BasaltProps } from '../../common/props.js';
+export type ChartCenterProps = BasaltProps & {
+    /** A block body (a title-less pending `ChartCard`, a non-`ChartFrame` body) has no measured
+     * plot width to reserve — `'100%'` fills its container instead of a pixel figure. */
+    width: number | string;
     height: number;
     children: ReactNode;
 };
@@ -10,9 +13,9 @@ export type ChartCenterProps = {
  * there was previously nothing to reach for when a chart file needed to center something. Not a
  * general layout system — width, height, children, nothing else.
  */
-export declare function ChartCenter({ width, height, children }: ChartCenterProps): ReactNode;
-export type ChartPendingProps = {
-    width: number;
+export declare function ChartCenter({ width, height, className, style, children, }: ChartCenterProps): ReactNode;
+export type ChartPendingProps = BasaltProps & {
+    width: number | string;
     height: number;
     /** Default `'Loading…'`. */
     label?: string;
@@ -29,6 +32,82 @@ export type ChartPendingProps = {
  * measurement — no axes, no gridlines, no hatching, no data marks — just a faint, static, centered
  * label. No animation: the package's motion doctrine bans looping/pulsing idle motion, so a static
  * reserved box is the correct answer here, not a compromise.
+ *
+ * The label is `role="status"` (polite), so a screen reader hears the chart resolve through all
+ * three states rather than only its failure: `ChartError` was `role="alert"` and its two siblings
+ * were silent, which announced the one outcome and swallowed the other two. Polite, not assertive —
+ * a loading placeholder must not interrupt what the reader is already being told.
+ */
+export declare function ChartPending({ width, height, label, className, style, }: ChartPendingProps): ReactNode;
+/**
+ * The three "nothing to draw" states a chart can be in, in ONE prop — the shape a
+ * `@tanstack/react-query` result (or anything derived from one) already has.
+ *
+ * It exists because the answer that already existed, `dashboard/QueryState`, renders Mantine and
+ * therefore cannot be reached from `./charts` at all (the Mantine-free boundary). A chart consumer
+ * without that import was left writing the four-way branch by hand, which is the exact bug
+ * `QueryState` was built for: the shape suggests `empty` and a 500 renders "No data".
+ *
+ * Precedence is fixed and is the whole product: **pending → error → empty**. A refetch that is
+ * both in flight and carrying a stale error is pending, not failed; a query that errored has no
+ * standing to claim its result was empty.
+ */
+export type ChartState = {
+    /** The query has not resolved yet. Wins over every other flag. */
+    pending?: boolean;
+    /** Truthy = the query failed. Any thrown value; an `Error`'s `message` is used as the label. */
+    error?: unknown;
+    /**
+     * The query resolved and there is genuinely nothing to plot. `true`, or the empty label
+     * itself — a string is truthy AND the copy `ChartEmpty` paints, so a consumer with its own
+     * "No data" wording never needs a ternary around the placeholder.
+     */
+    empty?: boolean | string;
+};
+/** Which placeholder {@link ChartState} resolves to, or `null` to draw the chart. */
+export type ResolvedChartState = 'pending' | 'error' | 'empty' | null;
+/**
+ * Resolve {@link ChartState} (plus the older standalone `isPending` flag, which stays a supported
+ * alias) into the ONE placeholder to render. Pure and exported so a hand-composed plot applies the
+ * same precedence rather than re-deriving it.
+ */
+export declare function resolveChartState(input: {
+    state?: ChartState;
+    isPending?: boolean;
+}): ResolvedChartState;
+export type ChartEmptyProps = BasaltProps & {
+    width: number | string;
+    height: number;
+    /** Default `'No data'`. */
+    label?: string;
+    /** Optional affordance under the label — a "clear filters" button, a range reset. Rendered as
+     * given: this layer is Mantine-free, so the caller owns whatever it puts here. */
+    action?: ReactNode;
+};
+/**
+ * Measured and EMPTY — the query resolved and there is nothing to plot. Distinct from
+ * {@link ChartPending} ("not asked yet") and from a hatched absence ("watched, measured nothing"):
+ * collapsing any of the three into another is the honesty bug this trio exists to prevent.
+ *
+ * Same footprint discipline as `ChartPending`: it reserves the plot rect and draws nothing that
+ * could be read as a measurement — no axes, no gridlines, no marks. Announced `role="status"`
+ * (polite) like `ChartPending`, so the resolution is heard; only `ChartError` is an `alert`.
+ */
+export declare function ChartEmpty({ width, height, label, action, className, style, }: ChartEmptyProps): ReactNode;
+export type ChartErrorProps = BasaltProps & {
+    width: number | string;
+    height: number;
+    /** Overrides the text outright. Omitted, an `Error`'s own `message` is used, else
+     * `'Could not load chart'` — a failure never borrows the empty state's copy. */
+    label?: string;
+    /** The thrown value, used for the default label. */
+    error?: unknown;
+    /** Optional affordance under the label — typically a retry. */
+    action?: ReactNode;
+};
+/**
+ * Measured and FAILED. The branch a hand-written chart switch reliably gets wrong — a 500 rendered
+ * as "No data" is a positive claim that the server answered and had nothing, which it did not.
  */
-export declare function ChartPending({ width, height, label }: ChartPendingProps): ReactNode;
+export declare function ChartError({ width, height, label, error, action, className, style, }: ChartErrorProps): ReactNode;
 //# sourceMappingURL=ChartPending.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ChartPending.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartPending.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAGrD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAUD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,gBAAgB,GAAG,SAAS,CAEpF;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAkB,EAAE,EAAE,iBAAiB,GAAG,SAAS,CAMhG"}
+{"version":3,"file":"ChartPending.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartPending.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAGrD,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG;IAC3C;yFACqF;IACrF,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAUD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,GACT,EAAE,gBAAgB,GAAG,SAAS,CAS9B;AAED,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG;IAC5C,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAOD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,MAAM,EACN,KAAkB,EAClB,SAAS,EACT,KAAK,GACN,EAAE,iBAAiB,GAAG,SAAS,CAkB/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gGAAgG;IAChG,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CACzB,CAAA;AAED,qFAAqF;AACrF,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,IAAI,CAAA;AAErE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,GAAG,kBAAkB,CAMrB;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;sFACkF;IAClF,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AASD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,MAAM,EACN,KAAiB,EACjB,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,eAAe,GAAG,SAAS,CAgB7B;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd;oFACgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,+DAA+D;IAC/D,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAWD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,MAAM,EACN,KAAK,EACL,KAAK,EACL,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,eAAe,GAAG,SAAS,CAc7B"}