basalt-ui 1.30.0 → 1.30.2

package/dist/common/errors.js

@@ -17,6 +17,9 @@ function deprecatedProp(component, oldProp, newProp, removeIn) {
     `prop "${oldProp}" is deprecated \u2014 use "${newProp}" instead. "${oldProp}" is removed in ${removeIn}.`
   );
 }
+function ignoredProp(component, prop, because) {
+  return message(component, `prop "${prop}" is ignored because ${because}`);
+}
 function missingLayer(component, layer, remedy) {
   return message(component, `needs ${layer}, which is not available \u2014 ${remedy}.`);
 }
@@ -57,6 +60,7 @@ export {
   deprecatedProp,
   duplicateMount,
   errorStatus,
+  ignoredProp,
   missingLayer,
   oneOf,
   requiredProp,

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.30.0
+# basalt-ui v1.30.2
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.30.0
+Version: 1.30.2
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.30.0",
+  "version": "1.30.2",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/charts/index.ts

@@ -67,6 +67,7 @@ export {
   ChartFrame,
   type ChartFrameProps,
   type ChartFrameLegend,
+  type ResponsiveChartHeight,
   type PlotRect,
   resolveLegend,
 } from './primitives/ChartFrame'

package/src/charts/kinds/BandStrip.tsx

@@ -10,6 +10,7 @@ import { useBandPlot } from '../hooks/useBandPlot'
 import type { BandFold, BandTooltipConfig } from '../hooks/useBandPlot'
 import { AxisBottomDate } from '../primitives/Axes'
 import { ChartFrame, resolveLegend } from '../primitives/ChartFrame'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import {
   ChartTooltipFloat,
   TooltipBody,
@@ -94,9 +95,10 @@ export type BandStripProps<T> = BasaltProps & {
   series: readonly BandStripSeries<T>[]
   /** Which state each datum is in. */
   getBand: (d: T) => BandSpan
-  /** Fixed height in px, forwarded to `ChartFrame`. The band row gets whatever the measured
-   * margins and the measured legend band leave. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`), forwarded to `ChartFrame`.
+   * The band row gets whatever the measured margins and legend band leave. Default 240.
+   * `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   /** Fill the parent flex/grid cell's measured height instead of a fixed one. */
   fill?: boolean
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */

package/src/charts/kinds/Bars.tsx

@@ -7,6 +7,7 @@ import { VX } from '../../tokens'
 import type { ChartMargin } from '../../tokens'
 import { CartesianChart } from '../primitives/CartesianChart'
 import type { AxisConfig, CartesianTooltipConfig, PlotContext } from '../primitives/CartesianChart'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { ZoneSpec } from '../primitives/ZoneRects'
 import type { ChartState } from '../primitives/ChartPending'
 import { curveFor, LINE_OVERLAY_STROKE_WIDTH } from '../series'
@@ -65,8 +66,9 @@ export type BarsRefLine = {
 
 export type BarsProps<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
   /** Generic value accessor — given a data point and a bar/line key, returns the value or null. */

package/src/charts/kinds/Donut.tsx

@@ -6,6 +6,7 @@ import { assertRequiredProps } from '../../common/validate'
 import type { BasaltProps } from '../../common/props'
 import { ChartTooltipFloat, TooltipBody, TooltipRow } from '../primitives/ChartTooltip'
 import { ChartFrame } from '../primitives/ChartFrame'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { ChartState } from '../primitives/ChartPending'
 import { VX } from '../../tokens'
 import type { SeriesStyle } from '../series'
@@ -20,8 +21,9 @@ export type DonutDatum<K extends string = SeriesKey> = { key: K; value: number }
 
 export type DonutProps<K extends string = SeriesKey> = BasaltProps & {
   data: DonutDatum<K>[]
-  /** Fixed height in pixels, forwarded to the internal `ChartFrame`. 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
   colorForKey: (key: K) => string
   formatValue: (v: number) => string
   seriesLabel?: (key: string) => string

package/src/charts/kinds/DualPanel.tsx

@@ -15,6 +15,7 @@ import {
   TooltipRow,
 } from '../primitives/ChartTooltip'
 import { ChartFrame, resolveLegend } from '../primitives/ChartFrame'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import { Crosshair, SeriesDot } from '../primitives/Crosshair'
 import { HoverOverlay } from '../primitives/HoverOverlay'
 import { ZoneRects } from '../primitives/ZoneRects'
@@ -31,8 +32,9 @@ import { smartTicks, xLabelPxFor } from '../utils/ticks'
 
 export type DualPanelProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels, forwarded to the internal `ChartFrame`. 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
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM) — same default `CartesianChart` uses,

package/src/charts/kinds/Heatmap.tsx

@@ -10,6 +10,7 @@ import {
   TooltipRow,
 } from '../primitives/ChartTooltip'
 import { ChartFrame } from '../primitives/ChartFrame'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import { useChartTierMetrics } from '../primitives/chart-tier'
 import type { ChartState } from '../primitives/ChartPending'
 import { maxTextWidth } from '../utils/measure-text'
@@ -24,8 +25,10 @@ type HeatmapTip = HeatmapCell & { anchor: { x: number; y: number } }
 
 export type HeatmapProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels. Used when neither `aspectRatio` nor `fill` is set. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Used when neither
+   * `aspectRatio` nor `fill` is set. Default 240. `ChartFrameProps.height` owns the law —
+   * steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   /** height = Math.round(containerWidth / aspectRatio). Ignored when `fill` is set. */
   aspectRatio?: number
   /** Fill the parent flex/grid cell's measured height instead of a fixed/derived one. */

package/src/charts/kinds/MirroredBars.tsx

@@ -12,6 +12,7 @@ import type { BandFold, BandTooltipConfig } from '../hooks/useBandPlot'
 import { probeAxisLabels } from '../layout/auto-margin'
 import { AxisBottomDate, AxisLeftNumeric } from '../primitives/Axes'
 import { ChartFrame, resolveLegend } from '../primitives/ChartFrame'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import {
   ChartTooltipFloat,
   TooltipBody,
@@ -79,8 +80,9 @@ export type MirroredBarsProps<T> = BasaltProps & {
   /** Per-datum bar opacity — a real but qualified measurement (a short bucket, a partial interval)
    * drawn dimmer. Default 1. */
   getBarOpacity?: (d: T) => number
-  /** Fixed height in px, forwarded to `ChartFrame`. 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
   fill?: boolean
   formatX?: (key: string) => string
   xTickValues?: (keys: readonly string[], plotWidth: number) => readonly string[]

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

@@ -1,15 +1,16 @@
 import type { CSSProperties, ReactNode } from 'react'
 import { useCallback, useState } from 'react'
 import type { BasaltProps } from '../../common/props'
+import { ignoredProp } from '../../common/errors'
+import { useValidateProps } from '../../common/validate'
 import { VX } from '../../tokens'
 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 +21,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
@@ -32,15 +38,22 @@ export type ChartFrameLegend = {
   /** Default 'bottom'. */
   placement?: LegendPlacement
   /**
-   * Wrap cap → "+N more" rollup at high cardinality.
+   * Rollup cap at high cardinality: the legend renders this many ENTRIES and folds the remainder
+   * into a `+N more` disclosure chip.
    *
-   * 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}).
+   * **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.
    */
   maxRows?: number
   /** Visually separate role: series | overlay | reference. */
@@ -62,7 +75,8 @@ export type ChartFrameProps = BasaltProps & {
   series: readonly SeriesStyle[]
   /**
    * Height in pixels, or one per size step. Used when neither `aspectRatio` nor `fill` is set.
-   * Default 240.
+   * Default 240. 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
@@ -70,7 +84,8 @@ export type ChartFrameProps = BasaltProps & {
    * supported ({@link resolveFrameHeight}).
    */
   height?: number | ResponsiveChartHeight
-  /** height = Math.round(containerWidth / aspectRatio). Ignored when `fill` is set. */
+  /** height = Math.round(containerWidth / aspectRatio). Ignored when `fill` is set — which warns
+   * once in dev, for the same reason `height` does. */
   aspectRatio?: number
   /** Fill the parent flex/grid cell's measured height instead of a fixed/derived one. */
   fill?: boolean
@@ -215,6 +230,32 @@ export function ChartFrame({
     })
   }, [])
 
+  // The three sizing props are mutually exclusive and `fill` wins, silently — the type cannot say
+  // so without a union prop, which is a bigger change than a patch carries. Warn instead: a
+  // consumer passed `height` alongside `fill` for the life of a file and kept eight height
+  // constants (and a whole `compact` branch) that never moved a pixel, with nothing from tsc,
+  // oxlint or check-theme saying a word.
+  useValidateProps(
+    'ChartFrame',
+    () => [
+      fill && height !== undefined
+        ? ignoredProp(
+            'ChartFrame',
+            'height',
+            "`fill` is set — a fill frame takes its parent cell's measured height. Pass one or the other.",
+          )
+        : null,
+      fill && aspectRatio !== undefined
+        ? ignoredProp(
+            'ChartFrame',
+            'aspectRatio',
+            "`fill` is set — a fill frame takes its parent cell's measured height. Pass one or the other.",
+          )
+        : null,
+    ],
+    [fill, height, aspectRatio],
+  )
+
   const 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
@@ -232,38 +273,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/ChartLegend.tsx

@@ -255,9 +255,11 @@ function LegendChild({ item }: { item: LegendEntry }) {
  * Shared legend for all non-sparkline charts. `highlighted`/`onHighlight` are optional — omit for
  * 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 (row-accurate wrap measurement is `ChartFrame`'s job —
- * this is an entry-count cap, a deliberate simplification until that primitive lands).
+ * 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.
  *
  * `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`