@micha.bigler/ui-core-micha 2.42.2 → 3.0.0

package/src/components/charts/chartDefaults.js

@@ -50,8 +50,86 @@ function cssLengthToPixels(value) {
 }
 
 const MUI_LABELLED_X_AXIS_HEIGHT = 45;
+// Still used by `sizeYAxisForContent` (THEME-9, y-axis width) below -- unrelated to CHART-11,
+// which only replaces how the ROTATED x-axis path (`rotatedTickMetrics`) estimates width.
 const AVERAGE_GLYPH_WIDTH_EM = 0.6;
 
+// CHART-11: per-character width table (em units), the ESTIMATE fallback used only when no DOM is
+// available to actually measure a tick label's rendered extent (SSR, or a test environment where
+// `measureTickTextWidthPx` returns null -- jsdom does not implement real SVG text layout). A
+// single flat multiplier (the pre-CHART-11 constant, `AVERAGE_GLYPH_WIDTH_EM = 0.6`) systematically
+// overestimated real ward-name-shaped strings: they mix spaces, apostrophes and narrow lowercase
+// letters ("Mang'ula", "Msolwa Station") with a few wide/uppercase ones, and a flat multiplier
+// prices every character at the wide end. Three tiers, not a full per-glyph font metrics table --
+// proportionate to "an estimate", not a replacement for real measurement.
+const NARROW_GLYPH_WIDTH_EM = 0.28; // i l j I ' . , : ; ! | and space
+const WIDE_GLYPH_WIDTH_EM = 0.78; // uppercase (except I), plus lowercase m/w
+const DEFAULT_GLYPH_WIDTH_EM = 0.52; // everything else -- most lowercase letters and digits
+const NARROW_GLYPH_CHARS = new Set(["i", "l", "j", "I", "'", ".", ",", ":", ";", "!", "|", " "]);
+const WIDE_GLYPH_CHARS = new Set(["m", "w"]);
+
+function glyphWidthEm(char) {
+  if (NARROW_GLYPH_CHARS.has(char)) return NARROW_GLYPH_WIDTH_EM;
+  if (WIDE_GLYPH_CHARS.has(char) || (char >= 'A' && char <= 'Z')) return WIDE_GLYPH_WIDTH_EM;
+  return DEFAULT_GLYPH_WIDTH_EM;
+}
+
+/**
+ * CHART-11 ESTIMATE fallback (declared explicitly, not dressed up as a measurement): sums a
+ * per-character width table instead of applying one flat multiplier to the whole string. Only
+ * reached when `measureTickTextWidthPx` returns null.
+ */
+function estimateTextWidthPx(text, fontSizePx) {
+  let widthEm = 0;
+  for (const char of text) widthEm += glyphWidthEm(char);
+  return widthEm * fontSizePx;
+}
+
+let hiddenMeasurementTextNode;
+
+function getHiddenMeasurementTextNode() {
+  if (typeof document === 'undefined') return null;
+  if (hiddenMeasurementTextNode && hiddenMeasurementTextNode.isConnected) {
+    return hiddenMeasurementTextNode;
+  }
+  const svgNS = 'http://www.w3.org/2000/svg';
+  const svg = document.createElementNS(svgNS, 'svg');
+  svg.setAttribute('aria-hidden', 'true');
+  svg.style.position = 'absolute';
+  svg.style.width = '0';
+  svg.style.height = '0';
+  svg.style.overflow = 'hidden';
+  svg.style.pointerEvents = 'none';
+  const text = document.createElementNS(svgNS, 'text');
+  svg.appendChild(text);
+  (document.body || document.documentElement).appendChild(svg);
+  hiddenMeasurementTextNode = text;
+  return text;
+}
+
+/**
+ * CHART-11: measures a tick label's real rendered width via a transient, invisible, shared SVG
+ * `<text>` node -- the same element type MUI's own axis ticks render as, so glyph metrics match
+ * whatever font actually cascades to it (this package has no access to the consumer's theme font
+ * at this call site; the transient node inherits the page's own cascade, same as a real tick
+ * would). Returns `null` (never throws) when no DOM is available (SSR) or when
+ * `getComputedTextLength` is unsupported/unreliable there (jsdom does not implement real SVG text
+ * layout) -- callers fall back to `estimateTextWidthPx` in that case, and tests inject their own
+ * stub via `spaceForRotatedTicks`'s optional `measureTextWidth` parameter for determinism.
+ */
+function measureTickTextWidthPx(text, fontSizePx) {
+  try {
+    const node = getHiddenMeasurementTextNode();
+    if (!node) return null;
+    node.setAttribute('font-size', String(fontSizePx));
+    node.textContent = text;
+    const length = node.getComputedTextLength();
+    return Number.isFinite(length) && length > 0 ? length : null;
+  } catch {
+    return null;
+  }
+}
+
 // THEME-11: this package never formed an opinion on chart margins, so every chart fell back to
 // MUI's own DEFAULT_MARGINS (20px on all four sides) -- measured live (hram's KPI cards) as 167
 // of a 270px-tall chart being furniture. Per-side, not a uniform trim, because each side is for
@@ -61,79 +139,19 @@ const AVERAGE_GLYPH_WIDTH_EM = 0.6;
 // less trimmed than `left` because a LINEAR x-axis's last tick label sits AT the edge and
 // overhangs by about half its width (~13px at caption size) -- a band axis wouldn't need it, but
 // making this conditional on scale type would be inferred behaviour with no named consumer.
+//
+// UCM-CHART-12 Rule 3: no caller-supplied `margin` exists any more (the model owns spacing
+// completely, `resolveChartLayout` builds the final margin object directly) -- this is now only
+// the base every side starts from before `resolveChartLayout` adds the legend band to one side.
 export const PACKAGE_DEFAULT_MARGIN = {
   top: 10, bottom: 8, left: 8, right: 16,
 };
 
-/**
- * Applies the package's own margin default, per side -- a caller's own value on any side always
- * wins on that side; only an UNSET side gets the package default. A caller passing `{ left: 60 }`
- * therefore keeps that 60 on the left and gets the package defaults on the other three sides,
- * never MUI's wider ones. CHART-10: this applies identically whether or not the x-axis carries
- * rotated labels -- `spaceForRotatedTicks` no longer computes a `bottom` of its own.
- */
-export function withMarginDefaults(margin) {
-  const explicit = typeof margin === 'number'
-    ? { top: margin, bottom: margin, left: margin, right: margin }
-    : margin;
-  return { ...PACKAGE_DEFAULT_MARGIN, ...explicit };
-}
-
-function formattedTickText(axis, value) {
-  if (!axis.valueFormatter) return String(value);
-  try {
-    return String(axis.valueFormatter(value, { location: 'tick' }));
-  } catch {
-    // Some formatters require MUI's complete scale context. Falling back to
-    // the raw value is conservative: it reserves at least as much space.
-    return String(value);
-  }
-}
-
-function rotatedTickMetrics(axis, defaultLineHeight) {
-  const angle = Number(axis.tickLabelStyle?.angle) || 0;
-  if (angle === 0) return null;
-
-  const fontSize = cssLengthToPixels(axis.tickLabelStyle?.fontSize);
-  if (fontSize === 0) return null;
-
-  const lineHeight = Number(axis.tickLabelStyle?.lineHeight) || defaultLineHeight;
-  const longestLabel = (axis.data || []).reduce((longest, value) => {
-    const text = formattedTickText(axis, value);
-    return text.length > longest.length ? text : longest;
-  }, '');
-  const textWidth = Math.max(fontSize, longestLabel.length * fontSize * AVERAGE_GLYPH_WIDTH_EM);
-  const radians = (angle * Math.PI) / 180;
-  const projectedHeight = Math.abs(Math.cos(radians)) * fontSize * lineHeight
-    + Math.abs(Math.sin(radians)) * textWidth;
-  const extraHeight = Math.max(1, Math.ceil(projectedHeight - fontSize));
-
-  return { extraHeight };
-}
-
-/**
- * CHART-10: rotated labels project both their line box and text width vertically, and X-Charts
- * uses `xAxis.height` -- not `margin.bottom` -- to size the band that actually CONTAINS them.
- * `margin.bottom` only separates that axis band from the SVG edge; it plays no part in whether a
- * label fits. Measured live (hram, 2026-08-22, real data): once `axis.height` carries the
- * allowance, the rendered tick labels sit fully INSIDE the axis band with nothing below them --
- * `margin.bottom` growing by the same allowance on top was reserving space nothing ever used, up
- * to 130px (38% of a 340px card) on long rotated labels. Only `axis.height` grows here now;
- * `margin` is returned untouched (whatever the caller passed, or didn't) so `withMarginDefaults`
- * downstream applies the package's ordinary bottom default in every case, rotated or not -- a
- * caller-set `margin.bottom` was never touched by this function even before this fix, and still
- * isn't.
- */
-export function spaceForRotatedTicks(xAxis, margin, defaultLineHeight = 1) {
-  const spacedXAxis = xAxis.map((axis) => {
-    const metrics = rotatedTickMetrics(axis, defaultLineHeight);
-    if (!metrics) return axis;
-    if (axis.height != null) return axis;
-    return { ...axis, height: MUI_LABELLED_X_AXIS_HEIGHT + metrics.extraHeight };
-  });
-
-  return { xAxis: spacedXAxis, margin };
-}
+// CHART-11: small clearance between the rotated text block's own projected extent and the
+// bottom of the axis's reserved band -- the same order of magnitude as the package's own
+// PACKAGE_DEFAULT_MARGIN breathing-room, applied here for the same reason (a hard 0px gap reads
+// as clipped even when nothing is actually cut off).
+const ROTATED_TICK_CLEARANCE_PX = 8;
 
 // THEME-9: MUI X-Charts' own default y-axis width is a flat 45px (ticks) +
 // 20px (label, if present) = 65px regardless of what the ticks actually say
@@ -265,56 +283,247 @@ export function defaultNumericTickFormatter(locale) {
     : new Intl.NumberFormat(locale).format(value));
 }
 
+// UCM-CHART-12: named size tokens, resolved through the theme's 8px spacing unit
+// (`src/theme/tokens.js`'s `spacing: 8`). `standard` is pinned to the pre-existing deployed
+// default (`TimeSeriesChart`'s old `CHART_HEIGHT = 320`) so this migration does not also
+// silently redraw every already-shipped default-sized chart; `compact`/`tall` are proportional.
+// Documented plainly in `docs/CHART-LAYOUT.md` -- these are visible product decisions, not
+// internal plumbing.
+export const CHART_SIZE_SPACING_UNITS = { compact: 30, standard: 40, tall: 50 };
+
+// UCM-CHART-12 Rule 2: every band is its own measured content, or zero -- no band is ever a
+// constant taken on faith. These two ARE constants, but only for the "content is present" case;
+// each one collapses to 0 the moment its content is absent (`resolveXAxisGeometry`,
+// `resolveChartLayout` below).
+//
+// ui_reviewer finding U1: before this WO, a plain (unrotated, untitled) axis got NO explicit
+// `axis.height` at all -- MUI computed its own default internally. This resolver now always sets
+// `axis.height` explicitly (Rule 1: nothing outside the resolver does chart arithmetic), which
+// looked like a silent behaviour change until checked against MUI's own source
+// (`@mui/x-charts/constants`): `DEFAULT_AXIS_SIZE_HEIGHT = 25` and `AXIS_LABEL_DEFAULT_HEIGHT =
+// 20` -- i.e. `TICK_BAND_BASE_PX`/`AXIS_TITLE_BAND_PX` below are not an approximation, they are
+// MUI's own constants, confirmed pixel-for-pixel. Making them explicit changes nothing about what
+// renders for that common case; `TICK_BAND_BASE_PX + AXIS_TITLE_BAND_PX` = 45 is also exactly the
+// pre-CHART-12 `MUI_LABELLED_X_AXIS_HEIGHT`, decomposed into the two bands Rule 2 requires instead
+// of one opaque "labelled axis height" figure.
+const TICK_BAND_BASE_PX = 25;
+const AXIS_TITLE_BAND_PX = MUI_LABELLED_X_AXIS_HEIGHT - TICK_BAND_BASE_PX;
+// One row of legend chips + gap -- MUI does not reserve this space itself (confirmed: nothing in
+// this package's pre-CHART-12 margin/axis math ever accounted for the legend), so a visible
+// legend growing the SVG uncounted was the sixth defect this WO's Rule 2 also closes.
+const LEGEND_BAND_PX = 32;
+
+// UCM-CHART-12 `xLabels: "auto"`: with no real container-width measurement available before
+// render (the presets stay responsive -- MUI measures actual width via ResizeObserver, which this
+// pure function cannot see), "auto" is a documented HEURISTIC, not a true fit computation: rotate
+// once there are enough categories AND the longest one is long enough that a horizontal row would
+// plausibly collide. The mandatory browser-level check (WO Part C) is what actually verifies fit
+// against real rendered geometry; this only picks a reasonable default ahead of that.
+const AUTO_ROTATE_TICK_COUNT = 6;
+const AUTO_ROTATE_LABEL_CHARS = 4;
+
+function xAxisTickContentText(axis) {
+  const data = axis?.data;
+  if (!Array.isArray(data)) return null; // no data array -- can't tell (e.g. a numeric scale); assume content
+  return longestFormattedTick(data, axis.valueFormatter);
+}
+
+// The Access-scatter case (WO Part A): an axis whose tick labels are all blank/absent must
+// collapse its reserved band to zero, not keep the package's floor. `null` (no data array at
+// all -- a linear numeric axis, whose ticks come from the scale, not a caller-supplied list)
+// is treated as "assume content", since there is nothing here to measure as empty.
+function xAxisHasVisibleTicks(axis) {
+  const text = xAxisTickContentText(axis);
+  return text === null || text.length > 0;
+}
+
 /**
- * CHART-8: resolves the `{minHeight, height, aspect}` trio these presets accept into what the
- * wrapper reserves and what height (if any) sizes the chart itself. Three-way, not two-way --
- * `aspect` changes the answer:
- *  - `height` set -> it sizes the chart; the wrapper never reserves more than that (a caller-set
- *    `minHeight` larger than `height` is capped here, closing the dead-space gap this WO exists
- *    to fix -- equal values, or no `minHeight` at all, pass through unchanged).
- *  - no `height`, `aspect` set -> unchanged from before this WO: the wrapper's own `aspectRatio`
- *    derives its height from its width, and `minHeight` stays exactly what its name says, a floor
- *    stopping it collapsing on a narrow viewport. Do not give the chart a fixed height here --
- *    that would remove the responsive behaviour four live call sites rely on.
- *  - no `height`, no `aspect` -> `minHeight` sizes the chart itself. There is no other sizing
- *    information to go on, and a caller in this shape meant the chart to have that height, not
- *    merely a wrapper floor around an unsized chart.
+ * UCM-CHART-12: decides the x-axis tick band's height and rotation angle. Replaces CHART-10/11's
+ * `spaceForRotatedTicks`/`rotatedTickMetrics` -- same measured-text-width mechanism
+ * (`measureTickTextWidthPx`, with `estimateTextWidthPx` as the no-DOM fallback and
+ * `measureTextWidth` as the test injection point), but now driven by `xLabels`
+ * ("auto"|"horizontal"|"angled") instead of a caller-supplied `tickLabelStyle.angle`, and
+ * returning 0 outright when the axis has no visible tick content (Rule 2).
  */
-export function resolveChartHeight({ minHeight, height, aspect }) {
-  if (height != null) {
-    const wrapperMinHeight = minHeight != null && minHeight > height ? height : minHeight;
-    return { wrapperMinHeight, chartHeight: height };
-  }
-  if (aspect != null) {
-    return { wrapperMinHeight: minHeight, chartHeight: undefined };
+function resolveXAxisGeometry(axis, xLabelsMode, defaultLineHeight, measureTextWidth, fallbackTickFontSize) {
+  if (!xAxisHasVisibleTicks(axis)) return { tickBand: 0, angle: 0 };
+
+  const fontSize = cssLengthToPixels(axis?.tickLabelStyle?.fontSize) || cssLengthToPixels(fallbackTickFontSize);
+  const longestLabel = xAxisTickContentText(axis) || '';
+  const dataCount = Array.isArray(axis?.data) ? axis.data.length : 0;
+
+  let angle = 0;
+  if (xLabelsMode === 'angled') {
+    angle = Number(axis?.tickLabelStyle?.angle) || -45;
+  } else if (xLabelsMode === 'auto') {
+    const needsRotation = dataCount > AUTO_ROTATE_TICK_COUNT && longestLabel.length > AUTO_ROTATE_LABEL_CHARS;
+    angle = needsRotation ? -45 : 0;
+  } // "horizontal" always stays at angle 0
+
+  if (angle === 0) return { tickBand: TICK_BAND_BASE_PX, angle: 0 };
+  // Rotation is a visual instruction independent of whether a font size is knowable here -- an
+  // "angled" axis still rotates even when `fontSize` can't be resolved (no theme fallback given),
+  // it just can't project a tighter band than the floor without one.
+  if (fontSize === 0) return { tickBand: TICK_BAND_BASE_PX, angle };
+
+  const lineHeight = Number(axis?.tickLabelStyle?.lineHeight) || defaultLineHeight;
+  const measure = measureTextWidth || measureTickTextWidthPx;
+  const measuredWidth = measure(longestLabel, fontSize);
+  const textWidth = Math.max(
+    fontSize,
+    Number.isFinite(measuredWidth) && measuredWidth > 0
+      ? measuredWidth
+      : estimateTextWidthPx(longestLabel, fontSize),
+  );
+  const radians = (angle * Math.PI) / 180;
+  const projectedHeight = Math.abs(Math.cos(radians)) * fontSize * lineHeight
+    + Math.abs(Math.sin(radians)) * textWidth;
+  const tickBand = Math.max(TICK_BAND_BASE_PX, Math.ceil(projectedHeight) + ROTATED_TICK_CLEARANCE_PX);
+  return { tickBand, angle };
+}
+
+function resolveChartHeightPx(size, height, spacing) {
+  if (height != null) return height;
+  const units = CHART_SIZE_SPACING_UNITS[size];
+  if (units == null) {
+    throw new Error(
+      `[ui-core-micha] Unknown chart size="${size}". Use "compact" | "standard" | "tall", `
+      + 'or pass height (in px) for the documented escape.',
+    );
   }
-  return { wrapperMinHeight: minHeight, chartHeight: minHeight };
+  // MUI's `theme.spacing(n)` returns a CSS length STRING ("240px"), not a number -- the chart
+  // height feeds straight into MUI X-Charts' own numeric `height` prop, so it must be unwrapped
+  // back to a px number via the same `cssLengthToPixels` the rest of this file already uses.
+  return typeof spacing === 'function' ? cssLengthToPixels(spacing(units)) : units * 8;
 }
 
 /**
- * CHART-8: dev-only warning when a caller passes both `minHeight` and `height` and they disagree
- * -- the incoherent pair this WO closes. Not a throw: a shared package throwing on a prop
- * combination in production would break a consumer's page over a layout nit. Silent on the
- * equal-value majority and on the legitimate `minHeight` + `aspect` (no `height`) combination.
+ * UCM-CHART-12: the one function that owns a chart's geometry (Rule 1-3), replacing
+ * `resolveChartHeight` + `spaceForRotatedTicks` + `warnOnHeightMismatch`. Returns the COMPLETE
+ * geometry a preset needs -- wrapper `sx`, chart height, margins, and both resolved axis arrays --
+ * plus the named `bands` the composition invariant is asserted against:
  *
- * CHART-9: `heightWins` distinguishes the two shapes this fires from. The four chart presets
- * (default, `heightWins: true`) DO apply `resolveChartHeight`'s `height` to their box, so the
- * original "height wins" wording is accurate there. `ChartFrame` (`heightWins: false`) never
- * applies `height` to its box at all -- `minHeight` always keeps reserving the floor -- so it gets
- * its own accurate wording instead of reusing the presets' story.
+ *   chartHeight === bands.plotHeight + bands.xAxisBand + bands.xTitleBand + bands.legendBand
+ *   containerWidth === bands.yAxisBand + bands.plotWidth + bands.rightPad   (when `containerWidth` is given)
+ *
+ * `plotHeight`/`plotWidth` are the RESIDUAL of `chartHeight`/`containerWidth` minus the OTHER
+ * fields this function itself returns (`margin.top/bottom`, `xAxis[0].height`, `yAxisBand`) --
+ * by construction, summing them back up can never fail to balance, so that arithmetic identity
+ * ALONE proves nothing about a `UCM-CHART-10`-shaped bug (a term double-counted between
+ * `xAxis.height` and `margin.bottom`). What actually catches that class of bug is asserting each
+ * individual band lands in exactly one place downstream, independently of the others:
+ * `xAxis[0].height === xAxisBand + xTitleBand` (nothing else may also carry the tick/title
+ * allowance) and `margin.top + margin.bottom - PACKAGE_DEFAULT_MARGIN.top -
+ * PACKAGE_DEFAULT_MARGIN.bottom === legendBand` (the ONLY thing margin grows for, over its own
+ * package baseline, is the legend). The test suite asserts both forms side by side.
+ *
+ * `plotHeight` deliberately does NOT subtract the base `PACKAGE_DEFAULT_MARGIN` breathing room --
+ * that margin is intentional spacing around the plot (THEME-11), not one of the three itemized
+ * "furniture" bands (tick/title/legend) this WO exists to zero out, so it is treated as part of
+ * "the rest of the chart", the same as `plotHeight` itself.
+ *
+ * `containerWidth` is optional and only meaningful for tests / the browser-level check -- the
+ * presets themselves stay responsive (no explicit width) and never pass it.
+ */
+export function resolveChartLayout({
+  size = 'standard',
+  height,
+  xAxis,
+  yAxis,
+  series = [],
+  xLabels = 'auto',
+  hideLegend = false,
+  legendPosition = DEFAULT_LEGEND_POSITION,
+  tickFontSize,
+  spacing,
+  defaultLineHeight = 1,
+  measureTextWidth,
+  containerWidth,
+} = {}) {
+  const chartHeight = resolveChartHeightPx(size, height, spacing);
+
+  const xAxisList = xAxis?.length ? xAxis : [{}];
+  const primaryXAxis = xAxisList[0];
+  const { tickBand: xAxisBand, angle } = resolveXAxisGeometry(
+    primaryXAxis, xLabels, defaultLineHeight, measureTextWidth, tickFontSize,
+  );
+  const xTitleBand = primaryXAxis?.label ? AXIS_TITLE_BAND_PX : 0;
+
+  // A `vertical: 'middle'` legend renders on the SIDE (consuming width, not height) -- reviewer
+  // finding: only branching on 'top' vs. not-'top' always reserved the legend band vertically,
+  // over-reserving height and under-reserving width for a side-placed legend. This WO's width
+  // invariant does not itemize a legend-width band, so a side legend simply gets none of the
+  // height reservation here rather than a wrong one -- consistent with the WO's own text ("0 when
+  // legend is off or horizontal").
+  const legendVertical = legendPosition?.vertical ?? DEFAULT_LEGEND_POSITION.vertical;
+  const legendIsSidePlaced = legendVertical === 'middle';
+  const legendHeightBand = hideLegend || legendIsSidePlaced ? 0 : LEGEND_BAND_PX;
+  const legendOnTop = legendHeightBand > 0 && legendVertical === 'top';
+
+  const sizedYAxis = sizeYAxisForContent(yAxis?.length ? yAxis : [{}], series, tickFontSize);
+  const yAxisBand = sizedYAxis[0]?.width ?? 0;
+  const rightPad = PACKAGE_DEFAULT_MARGIN.right;
+
+  const resolvedXAxis = xAxisList.map((axisEntry, index) => {
+    if (index !== 0 || axisEntry.height != null) return axisEntry;
+    // `xLabels` is the SOLE source of truth for rotation (Rule 3) -- `angle` is always written
+    // explicitly here, even when 0, rather than only overriding a truthy value. Leaving a stale
+    // caller-supplied `tickLabelStyle.angle` in place when `xLabels` resolved to no rotation would
+    // let MUI still render a rotated label whose band this resolver reserved as if it were flat --
+    // exactly the space/render mismatch this WO exists to close, just inverted (under-reservation
+    // instead of CHART-10's over-reservation).
+    const { angle: _callerAngle, ...restTickLabelStyle } = axisEntry.tickLabelStyle || {};
+    return {
+      ...axisEntry,
+      height: xAxisBand + xTitleBand,
+      tickLabelStyle: { ...restTickLabelStyle, angle },
+    };
+  });
+
+  const margin = {
+    top: PACKAGE_DEFAULT_MARGIN.top + (legendOnTop ? legendHeightBand : 0),
+    bottom: PACKAGE_DEFAULT_MARGIN.bottom + (legendOnTop ? 0 : legendHeightBand),
+    left: PACKAGE_DEFAULT_MARGIN.left,
+    right: rightPad,
+  };
+
+  // `plotHeight`/`plotWidth`: the residual of `chartHeight`/`containerWidth` minus the three named
+  // furniture bands (see this function's own docblock for why this alone does not prove the
+  // absence of a double-counted term, and what does).
+  const plotHeight = chartHeight - xAxisBand - xTitleBand - legendHeightBand;
+  const plotWidth = containerWidth != null ? containerWidth - yAxisBand - rightPad : undefined;
+
+  return {
+    chartHeight,
+    sx: { width: '100%', height: chartHeight },
+    margin,
+    xAxis: resolvedXAxis,
+    yAxis: sizedYAxis,
+    bands: {
+      plotHeight,
+      xAxisBand,
+      xTitleBand,
+      legendBand: legendHeightBand,
+      yAxisBand,
+      rightPad,
+      ...(containerWidth != null ? { plotWidth, containerWidth } : {}),
+    },
+  };
+}
+
+/**
+ * UCM-CHART-12 Rule 1/3: `minHeight`, `aspect`, and `margin` are gone from the four chart presets
+ * -- the model owns sizing and spacing completely. Passing one is a dev-mode error naming its
+ * replacement (never a silent ignore, so the 38 existing call sites this breaks get a clear
+ * migration path instead of a layout that quietly stops matching what the prop says) -- gated on
+ * `NODE_ENV !== 'production'` like the deleted `warnOnHeightMismatch` was, so a shared package
+ * cannot crash a consumer's production page over a layout prop; loud in dev, inert in prod.
  */
-export function warnOnHeightMismatch(componentName, { minHeight, height }, { heightWins = true } = {}) {
-  if (process.env.NODE_ENV === 'production') return;
-  if (minHeight == null || height == null || minHeight === height) return;
-  const resolution = heightWins
-    ? 'they disagree, so height wins and the wrapper no longer reserves the extra space below the '
-      + 'chart. Pass only height, or drop minHeight if it should just track 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.';
-  // eslint-disable-next-line no-console
-  console.warn(
-    `[ui-core-micha] <${componentName}> received both minHeight={${minHeight}} and height={${height}}; `
-    + resolution,
+export function assertRemovedChartProp(componentName, propName, value, replacement) {
+  if (value === undefined || process.env.NODE_ENV === 'production') return;
+  throw new Error(
+    `[ui-core-micha] <${componentName}> no longer accepts "${propName}" (removed in UCM-CHART-12, `
+    + `v3.0.0 -- see docs/CHART-LAYOUT.md). ${replacement}`,
   );
 }
 

package/tests/BarChart.test.jsx

@@ -20,7 +20,7 @@ function renderChart(props) {
 describe('BarChart preset', () => {
   afterEach(cleanup);
 
-  it('passes both axis labels, tooltip, responsive sizing, and hides a single-series legend', () => {
+  it('passes both axis labels, tooltip, the default "standard" height, and hides a single-series legend', () => {
     renderChart({ series: [{ data: [1, 2] }] });
     const props = chartSpy.mock.calls[0][0];
 
@@ -31,7 +31,10 @@ describe('BarChart preset', () => {
       legend: { position: { vertical: 'bottom', horizontal: 'start' } },
     });
     expect(props.hideLegend).toBe(true);
-    expect(screen.getByTestId('bar-chart-container').getAttribute('style') || '').not.toContain('px');
+    // UCM-CHART-12: size defaults to "standard" (320px, the historical default) -- the wrapper
+    // always carries an explicit height now, width stays responsive.
+    expect(props.height).toBe(320);
+    expect(window.getComputedStyle(screen.getByTestId('bar-chart-container')).height).toBe('320px');
   });
 
   it.each([
@@ -72,51 +75,36 @@ describe('BarChart preset', () => {
     expect(props.yAxis[0].label).toBeUndefined();
   });
 
-  // CHART-8: minHeight/height/aspect resolution, wired through the actual component.
-  describe('minHeight/height resolution (CHART-8)', () => {
-    it('sizes the chart from minHeight alone when neither height nor aspect is set', () => {
-      renderChart({ series: [{ data: [1] }], minHeight: 300 });
-      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(300);
-      expect(window.getComputedStyle(screen.getByTestId('bar-chart-container')).minHeight).toBe('300px');
+  // UCM-CHART-12: `size`/`height` resolution, wired through the actual component. Replaces the
+  // deleted `minHeight`/`aspect` CHART-8 trio -- see the removed-prop assertions below for the
+  // migration side of this.
+  describe('size/height resolution (UCM-CHART-12)', () => {
+    it.each([
+      ['compact', 240],
+      ['standard', 320],
+      ['tall', 400],
+    ])('resolves size="%s" to %ipx, on both the chart height and the wrapper', (size, px) => {
+      renderChart({ series: [{ data: [1] }], size });
+      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(px);
+      expect(window.getComputedStyle(screen.getByTestId('bar-chart-container')).height).toBe(`${px}px`);
     });
 
-    it('leaves minHeight as a floor and gives the chart no fixed height when aspect is set (no height)', () => {
-      renderChart({ series: [{ data: [1] }], minHeight: 320, aspect: 1.8 });
-      expect(chartSpy.mock.calls.at(-1)[0].height).toBeUndefined();
-      const style = window.getComputedStyle(screen.getByTestId('bar-chart-container'));
-      expect(style.minHeight).toBe('320px');
-      expect(style.aspectRatio).toBe('1.8 / 1');
+    it('lets height override size entirely, as the documented escape', () => {
+      renderChart({ series: [{ data: [1] }], size: 'tall', height: 280 });
+      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(280);
+      expect(window.getComputedStyle(screen.getByTestId('bar-chart-container')).height).toBe('280px');
     });
 
-    it('caps the wrapper at height when minHeight is larger, closing the dead-space gap', () => {
-      renderChart({ series: [{ data: [1] }], minHeight: 420, height: 380 });
-      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(380);
-      expect(window.getComputedStyle(screen.getByTestId('bar-chart-container')).minHeight).toBe('380px');
+    it('throws in dev when a caller still passes minHeight, naming the replacement', () => {
+      expect(() => renderChart({ series: [{ data: [1] }], minHeight: 300 })).toThrow(/size=.*standard.*tall/);
     });
 
-    it('is byte-identical when minHeight equals height', () => {
-      renderChart({ series: [{ data: [1] }], minHeight: 320, height: 320 });
-      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(320);
-      expect(window.getComputedStyle(screen.getByTestId('bar-chart-container')).minHeight).toBe('320px');
+    it('throws in dev when a caller still passes aspect, naming the removal', () => {
+      expect(() => renderChart({ series: [{ data: [1] }], aspect: 1.8 })).toThrow(/aspect/);
     });
 
-    it('is unchanged when height is passed alone', () => {
-      renderChart({ series: [{ data: [1] }], height: 280 });
-      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(280);
-      expect(window.getComputedStyle(screen.getByTestId('bar-chart-container')).minHeight).toBe('auto');
-    });
-
-    it('warns only on the disagreeing pair, naming both values, and not on the aspect combination', () => {
-      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-      renderChart({ series: [{ data: [1] }], minHeight: 420, height: 380 });
-      expect(warn).toHaveBeenCalledOnce();
-      expect(warn.mock.calls[0][0]).toContain('420');
-      expect(warn.mock.calls[0][0]).toContain('380');
-      warn.mockClear();
-
-      renderChart({ series: [{ data: [1] }], minHeight: 320, aspect: 1.8 });
-      expect(warn).not.toHaveBeenCalled();
-      warn.mockRestore();
+    it('throws in dev when a caller still passes margin, naming the removal', () => {
+      expect(() => renderChart({ series: [{ data: [1] }], margin: { top: 1 } })).toThrow(/margin/);
     });
   });
 });

package/tests/LineChart.test.jsx

@@ -34,8 +34,9 @@ describe('LineChart preset', () => {
     });
   });
 
-  // CHART-8: minHeight/height/aspect resolution, wired through the actual component.
-  describe('minHeight/height resolution (CHART-8)', () => {
+  // UCM-CHART-12: `size`/`height` resolution, wired through the actual component. Replaces the
+  // deleted `minHeight`/`aspect` CHART-8 trio.
+  describe('size/height resolution (UCM-CHART-12)', () => {
     function renderLine(props) {
       return render(
         <ThemeProvider theme={createTheme()}>
@@ -46,36 +47,32 @@ describe('LineChart preset', () => {
 
     afterEach(cleanup);
 
-    it('sizes the chart from minHeight alone when neither height nor aspect is set', () => {
-      renderLine({ minHeight: 300 });
-      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(300);
-      expect(window.getComputedStyle(screen.getByTestId('line-chart-container')).minHeight).toBe('300px');
+    it.each([
+      ['compact', 240],
+      ['standard', 320],
+      ['tall', 400],
+    ])('resolves size="%s" to %ipx, on both the chart height and the wrapper', (size, px) => {
+      renderLine({ size });
+      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(px);
+      expect(window.getComputedStyle(screen.getByTestId('line-chart-container')).height).toBe(`${px}px`);
     });
 
-    it('leaves minHeight as a floor and gives the chart no fixed height when aspect is set (no height)', () => {
-      renderLine({ minHeight: 320, aspect: 1.8 });
-      expect(chartSpy.mock.calls.at(-1)[0].height).toBeUndefined();
-      const style = window.getComputedStyle(screen.getByTestId('line-chart-container'));
-      expect(style.minHeight).toBe('320px');
-      expect(style.aspectRatio).toBe('1.8 / 1');
+    it('lets height override size entirely, as the documented escape', () => {
+      renderLine({ size: 'compact', height: 280 });
+      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(280);
+      expect(window.getComputedStyle(screen.getByTestId('line-chart-container')).height).toBe('280px');
     });
 
-    it('caps the wrapper at height when minHeight is larger, closing the dead-space gap', () => {
-      renderLine({ minHeight: 420, height: 380 });
-      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(380);
-      expect(window.getComputedStyle(screen.getByTestId('line-chart-container')).minHeight).toBe('380px');
+    it('throws in dev when a caller still passes minHeight, naming the replacement', () => {
+      expect(() => renderLine({ minHeight: 300 })).toThrow(/size=.*standard.*tall/);
     });
 
-    it('is byte-identical when minHeight equals height', () => {
-      renderLine({ minHeight: 320, height: 320 });
-      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(320);
-      expect(window.getComputedStyle(screen.getByTestId('line-chart-container')).minHeight).toBe('320px');
+    it('throws in dev when a caller still passes aspect, naming the removal', () => {
+      expect(() => renderLine({ aspect: 1.8 })).toThrow(/aspect/);
     });
 
-    it('is unchanged when height is passed alone', () => {
-      renderLine({ height: 280 });
-      expect(chartSpy.mock.calls.at(-1)[0].height).toBe(280);
-      expect(window.getComputedStyle(screen.getByTestId('line-chart-container')).minHeight).toBe('auto');
+    it('throws in dev when a caller still passes margin, naming the removal', () => {
+      expect(() => renderLine({ margin: { top: 1 } })).toThrow(/margin/);
     });
   });
 });