@micha.bigler/ui-core-micha 2.42.3 → 3.0.1

package/src/components/charts/BarChart.jsx

@@ -1,4 +1,4 @@
-import React, { useEffect } from 'react';
+import React from 'react';
 import { Box } from '@mui/material';
 import { useTheme } from '@mui/material/styles';
 import { useTranslation } from 'react-i18next';
@@ -6,15 +6,12 @@ import { BarChart as MuiBarChart } from '@mui/x-charts/BarChart';
 import { useNeutralChartPalette } from './palette';
 import {
   DEFAULT_LEGEND_POSITION,
+  assertRemovedChartProp,
   defaultNumericTickFormatter,
-  resolveChartHeight,
-  sizeYAxisForContent,
-  spaceForRotatedTicks,
-  warnOnHeightMismatch,
+  resolveChartLayout,
   withAxisDefaults,
   withChartSlotDefaults,
   withGridDefaults,
-  withMarginDefaults,
 } from './chartDefaults';
 
 /**
@@ -27,10 +24,9 @@ import {
  * a label the caller DID set (`withAxisDefaults` only ever falls back onto
  * an axis without its own `label`).
  *
- * `minHeight` (CHART-8): a floor under an `aspect`-derived responsive height when `aspect` is
- * set and `height` is not; otherwise (no `height`, no `aspect`) it sizes the chart itself. Once
- * `height` is set, `height` sizes the chart and the wrapper never reserves more than that, even
- * if `minHeight` is also passed and larger.
+ * `size` (UCM-CHART-12): `"compact" | "standard" | "tall"`, resolved through the theme's
+ * spacing scale by `resolveChartLayout`. `height` (px) is the documented escape for a justified
+ * special case -- prefer `size`. `minHeight`/`aspect`/`margin` are gone (see docs/CHART-LAYOUT.md).
  */
 export function BarChart({
   series = [],
@@ -39,13 +35,15 @@ export function BarChart({
   xAxis,
   yAxis,
   palette,
-  minHeight,
+  size = 'standard',
   height,
+  minHeight,
   aspect,
+  margin,
+  xLabels = 'auto',
   grid,
   hideLegend = series.length <= 1,
   legendPosition = DEFAULT_LEGEND_POSITION,
-  margin,
   slotProps,
   ...chartProps
 }) {
@@ -53,8 +51,9 @@ export function BarChart({
   const { i18n } = useTranslation();
   const neutralPalette = useNeutralChartPalette();
 
-  useEffect(() => warnOnHeightMismatch('BarChart', { minHeight, height }), [minHeight, height]);
-  const { wrapperMinHeight, chartHeight } = resolveChartHeight({ minHeight, height, aspect });
+  assertRemovedChartProp('BarChart', 'minHeight', minHeight, 'Use size="compact" | "standard" | "tall", or height for the documented escape.');
+  assertRemovedChartProp('BarChart', 'aspect', aspect, 'Removed with no replacement -- pick a size token; the chart no longer tracks width.');
+  assertRemovedChartProp('BarChart', 'margin', margin, 'Removed -- the layout model owns margins completely.');
 
   const labelledXAxis = withAxisDefaults(
     xAxis,
@@ -68,29 +67,33 @@ export function BarChart({
     { scaleType: 'linear', valueFormatter: defaultNumericTickFormatter(i18n.language) },
     theme.typography.caption.fontSize,
   );
-  const sizedYAxis = sizeYAxisForContent(
-    labelledYAxis,
+  const layout = resolveChartLayout({
+    size,
+    height,
+    xAxis: labelledXAxis,
+    yAxis: labelledYAxis,
     series,
-    theme.typography.caption.fontSize,
-  );
-  const rotatedTickSpace = spaceForRotatedTicks(
-    labelledXAxis,
-    margin,
-    theme.typography.caption.lineHeight,
-  );
+    xLabels,
+    hideLegend,
+    legendPosition,
+    slotProps,
+    tickFontSize: theme.typography.caption.fontSize,
+    spacing: theme.spacing,
+    defaultLineHeight: theme.typography.caption.lineHeight,
+  });
 
   return (
-    <Box data-testid="bar-chart-container" sx={{ width: '100%', minHeight: wrapperMinHeight, aspectRatio: aspect }}>
+    <Box data-testid="bar-chart-container" sx={layout.sx}>
       <MuiBarChart
         {...chartProps}
-        height={chartHeight}
+        height={layout.chartHeight}
         series={series}
-        xAxis={rotatedTickSpace.xAxis}
-        yAxis={sizedYAxis}
+        xAxis={layout.xAxis}
+        yAxis={layout.yAxis}
         colors={palette || neutralPalette.categorical}
         grid={withGridDefaults(grid)}
         hideLegend={hideLegend}
-        margin={withMarginDefaults(rotatedTickSpace.margin)}
+        margin={layout.margin}
         slotProps={withChartSlotDefaults(slotProps, legendPosition)}
       />
     </Box>

package/src/components/charts/ChartFrame.jsx

@@ -11,19 +11,38 @@ import {
 import { useTranslation } from 'react-i18next';
 import { useTheme } from '@mui/material/styles';
 import { exportChartPng, exportChartSvg } from './exportChart';
-import { warnOnHeightMismatch } from './chartDefaults';
 
 export const CHART_FRAME_ROOT_SX = { p: 2 };
 export const CHART_FRAME_ALERT_SX = { mt: 2 };
 
+/**
+ * UCM-CHART-12: `warnOnHeightMismatch` (the shared helper this note used to call into
+ * `chartDefaults`) was deleted along with `resolveChartHeight` -- both belonged to the
+ * `{minHeight, height, aspect}` trio the four chart presets used to accept, which that WO
+ * replaced with `resolveChartLayout`'s `size`/`height` model. `ChartFrame` keeps its OWN
+ * `minHeight`/`height`/`aspect` props unchanged (CHART-9: it is a card floor, not a chart size),
+ * so it keeps this note too -- same text, same condition, just no longer routed through the
+ * now-deleted shared function.
+ */
+function warnOnChartFrameHeightMismatch(minHeight, height) {
+  if (process.env.NODE_ENV === 'production') return;
+  if (minHeight == null || height == null || minHeight === height) return;
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[ui-core-micha] <ChartFrame> received both minHeight={${minHeight}} and height={${height}}; `
+    + 'they disagree; height is ignored here and minHeight keeps sizing the wrapper as a floor. '
+    + 'Pass only minHeight, or drop height if it was meant to size the whole card.',
+  );
+}
+
 /**
  * Chart-type-agnostic chart scaffolding. Children may be an X-Charts primitive or a bespoke SVG.
  *
  * `minHeight` (CHART-9): always just a floor on the content box, which holds a whole card --
  * title, toolbar, chart, legend, footnotes, export links -- not a single chart. `height` is never
- * applied to the box (unlike the four chart presets, whose box holds exactly one chart and do use
- * `resolveChartHeight`'s `height`/`aspect` resolution); it is only compared against `minHeight` for
- * `warnOnHeightMismatch`'s dev-mode note.
+ * applied to the box (unlike the four chart presets, whose box holds exactly one chart and use
+ * `resolveChartLayout`'s `size`/`height` resolution); it is only compared against `minHeight` for
+ * this component's own dev-mode mismatch note.
  */
 export function ChartFrame({
   title,
@@ -60,7 +79,7 @@ export function ChartFrame({
   const callerSx = Array.isArray(sx) ? sx : [sx];
 
   useEffect(
-    () => warnOnHeightMismatch('ChartFrame', { minHeight, height }, { heightWins: false }),
+    () => warnOnChartFrameHeightMismatch(minHeight, height),
     [minHeight, height],
   );
 

package/src/components/charts/LineChart.jsx

@@ -1,4 +1,4 @@
-import React, { useEffect } from 'react';
+import React from 'react';
 import { Box } from '@mui/material';
 import { useTheme } from '@mui/material/styles';
 import { useTranslation } from 'react-i18next';
@@ -9,15 +9,12 @@ import {
 import { useNeutralChartPalette } from './palette';
 import {
   DEFAULT_LEGEND_POSITION,
+  assertRemovedChartProp,
   defaultNumericTickFormatter,
-  resolveChartHeight,
-  sizeYAxisForContent,
-  spaceForRotatedTicks,
-  warnOnHeightMismatch,
+  resolveChartLayout,
   withAxisDefaults,
   withChartSlotDefaults,
   withGridDefaults,
-  withMarginDefaults,
 } from './chartDefaults';
 
 // Fixes MUI's hollow `background.paper`-filled marker (MarkElement.js's own
@@ -44,10 +41,9 @@ function FilledMarkElement({ color, style, ...props }) {
  * (`withAxisDefaults` only ever falls back onto an axis without its own
  * `label`).
  *
- * `minHeight` (CHART-8): a floor under an `aspect`-derived responsive height when `aspect` is
- * set and `height` is not; otherwise (no `height`, no `aspect`) it sizes the chart itself. Once
- * `height` is set, `height` sizes the chart and the wrapper never reserves more than that, even
- * if `minHeight` is also passed and larger.
+ * `size` (UCM-CHART-12): `"compact" | "standard" | "tall"`, resolved through the theme's
+ * spacing scale by `resolveChartLayout`. `height` (px) is the documented escape for a justified
+ * special case -- prefer `size`. `minHeight`/`aspect`/`margin` are gone (see docs/CHART-LAYOUT.md).
  */
 export function LineChart({
   series = [],
@@ -56,13 +52,15 @@ export function LineChart({
   xAxis,
   yAxis,
   palette,
-  minHeight,
+  size = 'standard',
   height,
+  minHeight,
   aspect,
+  margin,
+  xLabels = 'auto',
   grid,
   hideLegend = series.length <= 1,
   legendPosition = DEFAULT_LEGEND_POSITION,
-  margin,
   slots,
   slotProps,
   ...chartProps
@@ -71,8 +69,9 @@ export function LineChart({
   const { i18n } = useTranslation();
   const neutralPalette = useNeutralChartPalette();
 
-  useEffect(() => warnOnHeightMismatch('LineChart', { minHeight, height }), [minHeight, height]);
-  const { wrapperMinHeight, chartHeight } = resolveChartHeight({ minHeight, height, aspect });
+  assertRemovedChartProp('LineChart', 'minHeight', minHeight, 'Use size="compact" | "standard" | "tall", or height for the documented escape.');
+  assertRemovedChartProp('LineChart', 'aspect', aspect, 'Removed with no replacement -- pick a size token; the chart no longer tracks width.');
+  assertRemovedChartProp('LineChart', 'margin', margin, 'Removed -- the layout model owns margins completely.');
 
   const labelledXAxis = withAxisDefaults(
     xAxis,
@@ -91,29 +90,33 @@ export function LineChart({
     labelMarkType: 'square',
     ...item,
   }));
-  const sizedYAxis = sizeYAxisForContent(
-    labelledYAxis,
-    defaultedSeries,
-    theme.typography.caption.fontSize,
-  );
-  const rotatedTickSpace = spaceForRotatedTicks(
-    labelledXAxis,
-    margin,
-    theme.typography.caption.lineHeight,
-  );
+  const layout = resolveChartLayout({
+    size,
+    height,
+    xAxis: labelledXAxis,
+    yAxis: labelledYAxis,
+    series: defaultedSeries,
+    xLabels,
+    hideLegend,
+    legendPosition,
+    slotProps,
+    tickFontSize: theme.typography.caption.fontSize,
+    spacing: theme.spacing,
+    defaultLineHeight: theme.typography.caption.lineHeight,
+  });
 
   return (
-    <Box data-testid="line-chart-container" sx={{ width: '100%', minHeight: wrapperMinHeight, aspectRatio: aspect }}>
+    <Box data-testid="line-chart-container" sx={layout.sx}>
       <MuiLineChart
         {...chartProps}
-        height={chartHeight}
+        height={layout.chartHeight}
         series={defaultedSeries}
-        xAxis={rotatedTickSpace.xAxis}
-        yAxis={sizedYAxis}
+        xAxis={layout.xAxis}
+        yAxis={layout.yAxis}
         colors={palette || neutralPalette.categorical}
         grid={withGridDefaults(grid)}
         hideLegend={hideLegend}
-        margin={withMarginDefaults(rotatedTickSpace.margin)}
+        margin={layout.margin}
         slots={{ mark: FilledMarkElement, ...slots }}
         slotProps={withChartSlotDefaults(slotProps, legendPosition)}
       />

package/src/components/charts/ScatterChart.jsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useMemo } from 'react';
+import React, { useMemo } from 'react';
 import { Box } from '@mui/material';
 import { useTheme } from '@mui/material/styles';
 import { useTranslation } from 'react-i18next';
@@ -7,10 +7,9 @@ import { useXScale, useYScale } from '@mui/x-charts/hooks';
 import { useNeutralChartPalette } from './palette';
 import {
   DEFAULT_LEGEND_POSITION,
+  assertRemovedChartProp,
   defaultNumericTickFormatter,
-  resolveChartHeight,
-  sizeYAxisForContent,
-  warnOnHeightMismatch,
+  resolveChartLayout,
   withAxisDefaults,
   withChartSlotDefaults,
   withGridDefaults,
@@ -153,10 +152,9 @@ export function ScatterReferenceLine({
  * Reference geometry (a computed curve, a straight line, either with an optional label) is
  * composed as `children` using `ScatterReferenceCurve`/`ScatterReferenceLine` above.
  *
- * `minHeight` (CHART-8): a floor under an `aspect`-derived responsive height when `aspect` is
- * set and `height` is not; otherwise (no `height`, no `aspect`) it sizes the chart itself. Once
- * `height` is set, `height` sizes the chart and the wrapper never reserves more than that, even
- * if `minHeight` is also passed and larger.
+ * `size` (UCM-CHART-12): `"compact" | "standard" | "tall"`, resolved through the theme's
+ * spacing scale by `resolveChartLayout`. `height` (px) is the documented escape for a justified
+ * special case -- prefer `size`. `minHeight`/`aspect`/`margin` are gone (see docs/CHART-LAYOUT.md).
  *
  * Tested magnitude: a few hundred marks (hram's largest cloud is ~300 points). Not verified,
  * and not implied to hold, at thousands+.
@@ -177,13 +175,15 @@ export function ScatterChart({
   xAxis,
   yAxis,
   palette,
-  minHeight,
+  size = 'standard',
   height,
+  minHeight,
   aspect,
+  margin,
+  xLabels = 'auto',
   grid,
   hideLegend = series.length <= 1,
   legendPosition = DEFAULT_LEGEND_POSITION,
-  margin,
   sizeAccessor,
   getPointStyle,
   markerSize = DEFAULT_MARKER_RADIUS,
@@ -195,8 +195,9 @@ export function ScatterChart({
   const { i18n } = useTranslation();
   const neutralPalette = useNeutralChartPalette();
 
-  useEffect(() => warnOnHeightMismatch('ScatterChart', { minHeight, height }), [minHeight, height]);
-  const { wrapperMinHeight, chartHeight } = resolveChartHeight({ minHeight, height, aspect });
+  assertRemovedChartProp('ScatterChart', 'minHeight', minHeight, 'Use size="compact" | "standard" | "tall", or height for the documented escape.');
+  assertRemovedChartProp('ScatterChart', 'aspect', aspect, 'Removed with no replacement -- pick a size token; the chart no longer tracks width.');
+  assertRemovedChartProp('ScatterChart', 'margin', margin, 'Removed -- the layout model owns margins completely.');
 
   const labelledXAxis = withAxisDefaults(
     xAxis,
@@ -210,22 +211,30 @@ export function ScatterChart({
     { scaleType: 'linear', valueFormatter: defaultNumericTickFormatter(i18n.language) },
     theme.typography.caption.fontSize,
   );
-  // Only the Y axis is width-sized (sizeYAxisForContent reserves horizontal space for a
-  // vertical axis's ticks+label) -- a scatter's numeric X axis needs no analogous treatment
-  // beyond what MUI already sizes for a horizontal tick row.
-  //
-  // sizeYAxisForContent's series-data fallback (used when the caller sets no axis min/max)
-  // expects `series[i].data` to be a plain array of numbers -- true for BarChart/LineChart, but
-  // a scatter's data is `{x,y,z,id}` points, so `typeof value === 'number'` never matched and
-  // the fallback silently found zero candidates (reviewer finding, live-caught: it "looked fine"
-  // only because the untested case happened to fall back to MUI's flat default at a magnitude
-  // that didn't visibly overlap). Adapt AT THIS CALL SITE, not inside the shared helper --
-  // BarChart/LineChart's own contract must not change for this.
+  // `resolveChartLayout`'s own y-axis sizing (via `sizeYAxisForContent`) expects `series[i].data`
+  // to be a plain array of numbers -- true for BarChart/LineChart, but a scatter's data is
+  // `{x,y,z,id}` points. Adapt AT THIS CALL SITE, not inside the shared resolver -- BarChart/
+  // LineChart's own contract must not change for this (reviewer finding, live-caught under
+  // THEME-10: the untested case silently found zero candidates and fell back to MUI's flat
+  // default at a magnitude that didn't visibly overlap).
   const yValueSeries = useMemo(
     () => series.map((item) => ({ ...item, data: (item.data || []).map((point) => point?.y) })),
     [series],
   );
-  const sizedYAxis = sizeYAxisForContent(labelledYAxis, yValueSeries, theme.typography.caption.fontSize);
+  const layout = resolveChartLayout({
+    size,
+    height,
+    xAxis: labelledXAxis,
+    yAxis: labelledYAxis,
+    series: yValueSeries,
+    xLabels,
+    hideLegend,
+    legendPosition,
+    slotProps,
+    tickFontSize: theme.typography.caption.fontSize,
+    spacing: theme.spacing,
+    defaultLineHeight: theme.typography.caption.lineHeight,
+  });
 
   const isNeutral = series.length <= 1 && !series[0]?.color;
   const resolvedPalette = palette || (isNeutral ? [neutralPalette.neutral] : neutralPalette.categorical);
@@ -268,17 +277,17 @@ export function ScatterChart({
   );
 
   return (
-    <Box data-testid="scatter-chart-container" sx={{ width: '100%', minHeight: wrapperMinHeight, aspectRatio: aspect }}>
+    <Box data-testid="scatter-chart-container" sx={layout.sx}>
       <MuiScatterChart
         {...chartProps}
-        height={chartHeight}
+        height={layout.chartHeight}
         series={orderedSeries.map((item) => ({ markerSize, ...item }))}
-        xAxis={labelledXAxis}
-        yAxis={sizedYAxis}
+        xAxis={layout.xAxis}
+        yAxis={layout.yAxis}
         colors={resolvedPalette}
         grid={withGridDefaults(grid)}
         hideLegend={hideLegend}
-        margin={margin}
+        margin={layout.margin}
         slots={{ marker: markerSlot }}
         slotProps={withChartSlotDefaults(slotProps, legendPosition)}
       >

package/src/components/charts/TimeSeriesChart.jsx

@@ -30,6 +30,11 @@ import { useNeutralChartPalette } from './palette';
 // zero-height chart in the first place (CHART-4). Do not "fix" this back
 // to a responsive/aspect-ratio height without re-verifying the underlying
 // MUI measurement bug is actually resolved.
+//
+// UCM-CHART-12: `CHART_HEIGHT` (320) is the number `"standard"` (BarChart's new `size` token) was
+// deliberately pinned to, specifically so this preset's own default did not silently move under
+// this migration -- still used here as ChartFrame's own `minHeight` floor (a card concern,
+// unaffected by CHART-12), and the inner BarChart now takes `size="standard"` instead of `height`.
 const CHART_HEIGHT = 320;
 
 // Dynamic sx factories are outside the registry's documented top-level-object
@@ -283,7 +288,7 @@ export function TimeSeriesChart({
             ...(hasSecondaryAxis && series.axis === 'secondary' ? { yAxisId: 'secondary' } : {}),
           }))}
           palette={visiblePalette}
-          height={CHART_HEIGHT}
+          size="standard"
           hideLegend={seriesConfig.length > 0}
           skipAnimation={skipAnimation}
         />