basalt-ui 1.30.0 → 1.30.1

package/src/charts/kinds/MultiLine.tsx

@@ -6,6 +6,7 @@ import type { BasaltProps } from '../../common/props'
 import type { CursorResolution } from '../cursor/resolve'
 import type { CartesianTooltipConfig, AxisConfig, PlotContext } from '../primitives/CartesianChart'
 import { CartesianChart } from '../primitives/CartesianChart'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { XZoneSpec } from '../primitives/XZoneRects'
 import type { ZoneSpec } from '../primitives/ZoneRects'
 import type { ChartState } from '../primitives/ChartPending'
@@ -15,8 +16,9 @@ import { VX } from '../../tokens'
 
 export type MultiLineProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   chartId: string
   /** Extracts the x-axis category (date string) from a data point. */
   getX: (d: T) => string

package/src/charts/kinds/StackedArea.tsx

@@ -5,6 +5,7 @@ import type { BasaltProps } from '../../common/props'
 import type { CursorResolution } from '../cursor/resolve'
 import { CartesianChart } from '../primitives/CartesianChart'
 import type { AxisConfig, PlotContext } from '../primitives/CartesianChart'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { ChartState } from '../primitives/ChartPending'
 import { curveFor } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
@@ -12,8 +13,9 @@ import { isDev } from '../../common/is-dev'
 
 export type StackedAreaProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   chartId: string
   getX: (d: T) => string
   /** The stacked bands, bottom to top — the single source of truth for color, legend, and tooltip

package/src/charts/kinds/ZonedLine.tsx

@@ -7,6 +7,7 @@ import type { CursorResolution } from '../cursor/resolve'
 import { AreaGradient, areaFillUrl } from '../primitives/AreaGradient'
 import type { CartesianTooltipConfig, AxisConfig, PlotContext } from '../primitives/CartesianChart'
 import { CartesianChart } from '../primitives/CartesianChart'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { XZoneSpec } from '../primitives/XZoneRects'
 import type { ZoneSpec } from '../primitives/ZoneRects'
 import type { ChartState } from '../primitives/ChartPending'
@@ -31,8 +32,9 @@ export type ZonedLineRefLine = {
 
 export type ZonedLineProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   chartId: string
   /** Extracts the x-axis category (date string) from a data point. */
   getX: (d: T) => string

package/src/charts/primitives/CartesianChart.tsx

@@ -17,6 +17,7 @@ import { fmtAxisDate } from '../utils/format'
 import { autoXLabelRotate, smartTicks, smartTicksEvery, xLabelPxFor } from '../utils/ticks'
 import { AxisBottomDate, AxisLeftNumeric, AxisRightNumeric } from './Axes'
 import { ChartFrame, resolveLegend } from './ChartFrame'
+import type { ResponsiveChartHeight } from './ChartFrame'
 import { useChartTierMetrics } from './chart-tier'
 import type { ChartState } from './ChartPending'
 import { ChartTooltipFloat, TooltipBody, TooltipHeader, TooltipRow } from './ChartTooltip'
@@ -209,7 +210,9 @@ export type CartesianChartProps<T> = BasaltProps & {
   /** X-range bands (time windows), drawn behind the marks. */
   xZones?: XZoneSpec[]
   refLines?: { value: number; color: string; dashed?: boolean; axis?: 'left' | 'right' }[]
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   aspectRatio?: number
   fill?: boolean
   legend?: ChartLegendConfig | false

package/src/charts/primitives/ChartFrame.tsx

@@ -6,10 +6,9 @@ import { useChartSize } from '../hooks/useChartSize'
 import { deriveLegend } from '../series'
 import type { ChartLegendConfig, LegendPlacement, SeriesStyle } from '../series'
 import {
-  legendEntryCap,
   resolveChartTier,
   resolveFrameHeight,
-  resolveLegendMaxRows,
+  resolveLegendRollup,
   resolvePlotRect,
 } from './chart-frame-layout'
 import type { ResponsiveChartHeight } from './chart-frame-layout'
@@ -20,7 +19,12 @@ 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, resolvePlotRect, resolveChartTier } from './chart-frame-layout'
+export {
+  legendEntryCap,
+  resolveLegendRollup,
+  resolvePlotRect,
+  resolveChartTier,
+} from './chart-frame-layout'
 export type { ResponsiveChartHeight } from './chart-frame-layout'
 
 const DEFAULT_HEIGHT = 240
@@ -34,13 +38,14 @@ export type ChartFrameLegend = {
   /**
    * Wrap cap → "+N more" rollup at high cardinality.
    *
-   * An explicit value WINS OUTRIGHT — including over the phone tier's own two-row default
-   * (`chartTierMetrics`). It used to be `Math.min`'d against the tier, which made the documented
-   * per-chart opt-out ("opt back out with an explicit `legend.maxRows`") false in the one direction
-   * anybody needs it: a consumer's 380px inspector panel is "a phone" on a 1440px desktop, and a
-   * six-series legend rolled up to `+4 more` with no way to say no. Under `fill` the measured
-   * entry cap can still roll up FURTHER — that is a floor on the plot, not a tier default
-   * ({@link legendEntryCap}).
+   * 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.
    */
   maxRows?: number
   /** Visually separate role: series | overlay | reference. */
@@ -232,38 +237,32 @@ export function ChartFrame({
   const sideLegendWidth = legendVisible && vertical ? legendW : 0
   const topBottomLegendHeight = legendVisible && !vertical ? legendH : 0
 
+  const legendItems = legend === false ? [] : deriveLegend(series)
+  const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1)
+
+  // The cap, and who pays for it — one pure decision ({@link resolveLegendRollup} states the three
+  // cases and why the composition, not either half, is what shipped broken). A fixed-height frame
+  // grows around its legend; a `fill` one cannot, so its legend rolls up to the measured fit
+  // instead of eating the plot — unless the caller stated a number, which nothing trims and the
+  // 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,
+    items: legendItems,
+    containerW,
+    available: resolvedHeight - VX.minPlotHeight,
+  })
+
   const plot = resolvePlotRect({
     containerW,
     resolvedHeight,
     minWidth,
     sideLegendWidth,
     topBottomLegendHeight,
+    ...(legendWins && { legendWins }),
   })
 
-  const legendItems = legend === false ? [] : deriveLegend(series)
-  const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1)
-
-  // A fixed-height frame grows around its legend; a `fill` one cannot, so its legend rolls up
-  // instead of eating the plot (see `legendEntryCap`). Top/bottom only — a side legend costs
-  // width, not height.
-  // The resolved cap — the caller's if they named one, else the tier's DEFAULT, never both
-  // `Math.min`'d (`resolveLegendMaxRows` owns that law and says why) — enters the fill measurement
-  // as the upper bound, so a phone-width `fill` frame can only ever roll up further, never less.
-  const callerMaxRows =
-    legend === false ? undefined : resolveLegendMaxRows({ callerMaxRows: legend.maxRows, tier })
-
-  const maxRows =
-    legend === false
-      ? undefined
-      : fill && !vertical
-        ? legendEntryCap({
-            items: legendItems,
-            containerW,
-            available: resolvedHeight - VX.minPlotHeight,
-            ...(callerMaxRows !== undefined && { callerMaxRows }),
-          })
-        : callerMaxRows
-
   const legendNode =
     legend === false || resolvedState !== null ? null : (
       <div ref={legendRef} style={legendWrapperStyle(vertical)}>

package/src/charts/primitives/chart-frame-layout.ts

@@ -137,7 +137,7 @@ export type ChartTierMetrics = {
   /** Floating tooltip `minWidth`, px. */
   tooltipMinWidth: number
   /** Default entry cap on the legend, or `undefined` for no default cap. An explicit
-   * `legend.maxRows` still wins as the upper bound. */
+   * `legend.maxRows` replaces it outright ({@link resolveLegendMaxRows}). */
   legendMaxRows: number | undefined
   /** Per-side margin FLOORS (`VX.margin` is a floor, never a ceiling — §1). */
   margin: ChartMargin
@@ -186,9 +186,14 @@ export function chartTierMetrics(tier: ChartTier): ChartTierMetrics {
  * panel on a 1440px desktop is "a phone", so a six-series legend rolled up to two rows + `+4 more`
  * with no way to say no. `margin` and `xLabelRotate` always had that escape; the legend did not.
  *
- * A `fill` frame's measured {@link legendEntryCap} still applies ON TOP of whatever wins here — it
- * is a floor on the PLOT, not a tier default, so a chart that would otherwise render no plot at all
- * still rolls up.
+ * The measured {@link legendEntryCap} a `fill` frame applies is NOT a second ceiling on top of
+ * this: it resolves an ABSENT cap only. 1.30.0 ran it over the caller's number as well
+ * (`Math.min(fitted, caller)`), which made "wins outright" false again in the one place it was
+ * needed — meteo measured a 7-entry legend pinned to 2 entries at `maxRows` 3, 6 AND 99, with 5
+ * series drawn in colours the legend refused to name. The fit is not physics either: it derives
+ * from `VX.minPlotHeight`, which is a framework DEFAULT about the plot. Two defaults do not
+ * outvote the one number a caller stated, so the PLOT yields the height instead
+ * ({@link resolvePlotRect}'s `legendWins`) — visibly, in the frame the caller sized.
  */
 export function resolveLegendMaxRows(input: {
   callerMaxRows?: number | undefined
@@ -197,6 +202,48 @@ export function resolveLegendMaxRows(input: {
   return input.callerMaxRows ?? chartTierMetrics(input.tier).legendMaxRows
 }
 
+/**
+ * The whole legend-cap decision in one place: which cap `ChartLegend` gets, and whether the plot
+ * pays for it.
+ *
+ * It lives here rather than inline in `ChartFrame` because the COMPOSITION is what broke. 1.30.0
+ * had both halves right on their own — {@link resolveLegendMaxRows} honoured a stated cap,
+ * {@link legendEntryCap} measured a fit — and then ran the second over the first, which no test
+ * could see because neither pure function was wrong and the frame that combined them needs a
+ * `ResizeObserver` to test. Now the combination is a pure function too.
+ *
+ * Three cases, in order:
+ * 1. The caller STATED a number → it is the cap, and on a `fill` band the plot yields
+ *    (`legendWins`). Nothing measured or defaulted trims it.
+ * 2. No `fill` band → the tier's default (or none), because the frame simply grows.
+ * 3. A `fill` band with nothing stated → the measured fit, bounded by the tier's default.
+ */
+export function resolveLegendRollup(input: {
+  /** The caller's own `legend.maxRows`. */
+  statedMaxRows?: number | undefined
+  tier: ChartTier
+  /** A visible top/bottom legend on a `fill` frame — the one shape whose box cannot grow. */
+  fillBand: boolean
+  items: readonly LegendEntry[]
+  containerW: number
+  /** Frame height the legend may consume — `resolvedHeight - VX.minPlotHeight`. */
+  available: number
+}): { maxRows: number | undefined; legendWins: boolean } {
+  const { statedMaxRows, tier, fillBand, items, containerW, available } = input
+  if (statedMaxRows !== undefined) return { maxRows: statedMaxRows, legendWins: fillBand }
+  const tierMaxRows = resolveLegendMaxRows({ callerMaxRows: undefined, tier })
+  if (!fillBand) return { maxRows: tierMaxRows, legendWins: false }
+  return {
+    maxRows: legendEntryCap({
+      items,
+      containerW,
+      available,
+      ...(tierMaxRows !== undefined && { defaultMaxRows: tierMaxRows }),
+    }),
+    legendWins: false,
+  }
+}
+
 /**
  * Resolve the plot rect from the measured box and the measured legend band. Pure and exported so
  * the two floors below are testable without a `ResizeObserver`.
@@ -211,9 +258,11 @@ export function resolveLegendMaxRows(input: {
  *   `height={240}` toward zero and the body stopped rendering entirely. The plot stops at
  *   `VX.minPlotHeight` and the frame's own box grows by the difference instead — it is a flex
  *   column with `height: auto`, so that growth is automatic. Under `fill` the box CANNOT grow, so
- *   the legend is capped instead ({@link legendEntryCap}). An unmeasured box (`resolvedHeight <=
- *   0`, i.e. a `fill` frame before its first measurement) stays at 0 and renders nothing, exactly
- *   as before — the floor must never invent a height for a box nobody has measured.
+ *   the legend is capped instead ({@link legendEntryCap}) — UNLESS the caller stated
+ *   `legend.maxRows`, which is `legendWins`: there the floor itself yields, because a floor is a
+ *   default and the caller's number is not. An unmeasured box (`resolvedHeight <= 0`, i.e. a
+ *   `fill` frame before its first measurement) stays at 0 and renders nothing, exactly as before —
+ *   the floor must never invent a height for a box nobody has measured.
  */
 export function resolvePlotRect(input: {
   containerW: number
@@ -221,12 +270,28 @@ export function resolvePlotRect(input: {
   minWidth: number
   sideLegendWidth: number
   topBottomLegendHeight: number
+  /**
+   * The caller stated `legend.maxRows` on a `fill` frame, so the legend takes the rows it asked
+   * for and the plot takes what is left — `VX.minPlotHeight` stops being a floor. Without this the
+   * honoured cap would push the frame's content PAST its own cell (the plot holds 120px, the legend
+   * band adds its own) and paint over whatever sits below it; with it, the cost of the caller's
+   * number lands where they can see it. Spend the whole box on legend rows and there is no plot
+   * left to draw — that is their arithmetic, made visible rather than silently rolled up.
+   */
+  legendWins?: boolean
 }): { width: number; height: number } {
-  const { containerW, resolvedHeight, minWidth, sideLegendWidth, topBottomLegendHeight } = input
+  const {
+    containerW,
+    resolvedHeight,
+    minWidth,
+    sideLegendWidth,
+    topBottomLegendHeight,
+    legendWins = false,
+  } = input
+  const plotFloor = legendWins ? 0 : VX.minPlotHeight
   return {
     width: containerW === 0 ? minWidth : Math.max(containerW - sideLegendWidth, 1),
-    height:
-      resolvedHeight <= 0 ? 0 : Math.max(resolvedHeight - topBottomLegendHeight, VX.minPlotHeight),
+    height: resolvedHeight <= 0 ? 0 : Math.max(resolvedHeight - topBottomLegendHeight, plotFloor),
   }
 }
 
@@ -272,17 +337,25 @@ function entriesWithinRows(items: readonly LegendEntry[], width: number, rows: n
  * MEASURING the labels, not from assuming one entry per row — otherwise a five-entry legend that
  * fits on one line would roll up to `+2 more` in every 240px cell, moving rendering for charts
  * that never had the bug. Returns `undefined` when the whole legend already fits.
+ *
+ * This resolves an ABSENT cap. A caller who stated `legend.maxRows` never reaches here at all —
+ * `ChartFrame` routes around it — because `Math.min`-ing a stated number against this one made the
+ * documented escape inert in exactly the narrow `fill` panel it exists for
+ * ({@link resolveLegendMaxRows}).
  */
 export function legendEntryCap(input: {
   items: readonly LegendEntry[]
   containerW: number
   /** Frame height the legend may consume — `resolvedHeight - VX.minPlotHeight`. */
   available: number
-  /** An explicit caller cap always wins as the upper bound. */
-  callerMaxRows?: number
+  /**
+   * The cap that applies when nothing explicit was stated — today only the tier's own default
+   * ({@link chartTierMetrics}). Two defaults contending: the smaller wins.
+   */
+  defaultMaxRows?: number
 }): number | undefined {
-  const { items, containerW, available, callerMaxRows } = input
-  if (containerW <= 0 || items.length === 0) return callerMaxRows
+  const { items, containerW, available, defaultMaxRows } = input
+  if (containerW <= 0 || items.length === 0) return defaultMaxRows
   const rows = Math.max(
     1,
     Math.floor((available - LEGEND_PAD_Y + VX.legendGap) / (LEGEND_LINE_H + VX.legendGap)),
@@ -291,8 +364,8 @@ export function legendEntryCap(input: {
     legendBandHeight(rows) <= available &&
     entriesWithinRows(items, containerW, rows) >= items.length
   ) {
-    return callerMaxRows
+    return defaultMaxRows
   }
   const fitted = Math.max(1, entriesWithinRows(items, containerW, rows))
-  return callerMaxRows === undefined ? fitted : Math.min(fitted, callerMaxRows)
+  return defaultMaxRows === undefined ? fitted : Math.min(fitted, defaultMaxRows)
 }