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

package/dist/components/charts/chartDefaults.js

@@ -1,3 +1,14 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 export const DEFAULT_LEGEND_POSITION = {
     vertical: 'bottom',
     horizontal: 'start',
@@ -33,7 +44,85 @@ function cssLengthToPixels(value) {
     return parsed;
 }
 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 (_a) {
+        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
@@ -43,78 +132,18 @@ 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 Object.assign(Object.assign({}, PACKAGE_DEFAULT_MARGIN), explicit);
-}
-function formattedTickText(axis, value) {
-    if (!axis.valueFormatter)
-        return String(value);
-    try {
-        return String(axis.valueFormatter(value, { location: 'tick' }));
-    }
-    catch (_a) {
-        // 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) {
-    var _a, _b, _c;
-    const angle = Number((_a = axis.tickLabelStyle) === null || _a === void 0 ? void 0 : _a.angle) || 0;
-    if (angle === 0)
-        return null;
-    const fontSize = cssLengthToPixels((_b = axis.tickLabelStyle) === null || _b === void 0 ? void 0 : _b.fontSize);
-    if (fontSize === 0)
-        return null;
-    const lineHeight = Number((_c = axis.tickLabelStyle) === null || _c === void 0 ? void 0 : _c.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 Object.assign(Object.assign({}, 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
 // -- confirmed against @mui/x-charts' own DEFAULT_AXIS_SIZE_WIDTH /
@@ -242,56 +271,207 @@ export function defaultNumericTickFormatter(locale) {
         ? new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(value)
         : 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 === null || axis === void 0 ? void 0 : 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 };
+function resolveXAxisGeometry(axis, xLabelsMode, defaultLineHeight, measureTextWidth, fallbackTickFontSize) {
+    var _a, _b, _c;
+    if (!xAxisHasVisibleTicks(axis))
+        return { tickBand: 0, angle: 0 };
+    const fontSize = cssLengthToPixels((_a = axis === null || axis === void 0 ? void 0 : axis.tickLabelStyle) === null || _a === void 0 ? void 0 : _a.fontSize) || cssLengthToPixels(fallbackTickFontSize);
+    const longestLabel = xAxisTickContentText(axis) || '';
+    const dataCount = Array.isArray(axis === null || axis === void 0 ? void 0 : axis.data) ? axis.data.length : 0;
+    let angle = 0;
+    if (xLabelsMode === 'angled') {
+        angle = Number((_b = axis === null || axis === void 0 ? void 0 : axis.tickLabelStyle) === null || _b === void 0 ? void 0 : _b.angle) || -45;
     }
-    if (aspect != null) {
-        return { wrapperMinHeight: minHeight, chartHeight: undefined };
+    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((_c = axis === null || axis === void 0 ? void 0 : axis.tickLabelStyle) === null || _c === void 0 ? void 0 : _c.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:
+ *
+ *   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.
  *
- * 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.
+ * `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 warnOnHeightMismatch(componentName, { minHeight, height }, { heightWins = true } = {}) {
-    if (process.env.NODE_ENV === 'production')
-        return;
-    if (minHeight == null || height == null || minHeight === height)
+export function resolveChartLayout({ size = 'standard', height, xAxis, yAxis, series = [], xLabels = 'auto', hideLegend = false, legendPosition = DEFAULT_LEGEND_POSITION, tickFontSize, spacing, defaultLineHeight = 1, measureTextWidth, containerWidth, } = {}) {
+    var _a, _b, _c;
+    const chartHeight = resolveChartHeightPx(size, height, spacing);
+    const xAxisList = (xAxis === null || xAxis === void 0 ? void 0 : xAxis.length) ? xAxis : [{}];
+    const primaryXAxis = xAxisList[0];
+    const { tickBand: xAxisBand, angle } = resolveXAxisGeometry(primaryXAxis, xLabels, defaultLineHeight, measureTextWidth, tickFontSize);
+    const xTitleBand = (primaryXAxis === null || primaryXAxis === void 0 ? void 0 : 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 = (_a = legendPosition === null || legendPosition === void 0 ? void 0 : legendPosition.vertical) !== null && _a !== void 0 ? _a : 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 === null || yAxis === void 0 ? void 0 : yAxis.length) ? yAxis : [{}], series, tickFontSize);
+    const yAxisBand = (_c = (_b = sizedYAxis[0]) === null || _b === void 0 ? void 0 : _b.width) !== null && _c !== void 0 ? _c : 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 _a = axisEntry.tickLabelStyle || {}, { angle: _callerAngle } = _a, restTickLabelStyle = __rest(_a, ["angle"]);
+        return Object.assign(Object.assign({}, axisEntry), { height: xAxisBand + xTitleBand, tickLabelStyle: Object.assign(Object.assign({}, 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: Object.assign({ 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 assertRemovedChartProp(componentName, propName, value, replacement) {
+    if (value === undefined || process.env.NODE_ENV === 'production')
         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);
+    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}`);
 }
 export function withChartSlotDefaults(slotProps, legendPosition) {
     var _a;

package/docs/CHART-LAYOUT.md

@@ -0,0 +1,129 @@
+# Chart layout model (UCM-CHART-12)
+
+One function, `resolveChartLayout` (`src/components/charts/chartDefaults.js`), owns the geometry
+of every chart preset (`BarChart`, `LineChart`, `ScatterChart`, and indirectly `TimeSeriesChart`,
+which wraps `BarChart`). It replaces `resolveChartHeight`, `spaceForRotatedTicks`, and
+`warnOnHeightMismatch` — all three deleted in this version. This is a **breaking major (`3.0.0`)**.
+
+## The model
+
+Every reserved band is derived from the content it holds and collapses to zero when that content
+is empty. Consumers express intent, never pixels.
+
+```
+chartHeight === plotHeight + xAxisBand + xTitleBand + legendBand
+```
+
+- `xAxisBand` — the tick row. Zero when the axis has no visible tick content (an empty `data`
+  array, or every formatted tick is a blank string). Non-zero otherwise: a flat baseline for
+  horizontal labels, or a measured/estimated projection for rotated ones (same measurement
+  mechanism as before — a real DOM measurement when available, a per-glyph estimate otherwise).
+  The flat baseline (25px) and the title addition (20px) are MUI X-Charts' own
+  `DEFAULT_AXIS_SIZE_HEIGHT`/`AXIS_LABEL_DEFAULT_HEIGHT` constants, not a re-estimate — the plain
+  unrotated/untitled case renders pixel-identical to before this WO, even though the resolver now
+  sets `axis.height` explicitly where MUI used to fill it in implicitly.
+- `xTitleBand` — the axis title. Zero unless the x-axis carries a `label`.
+- `legendBand` — one row for the legend. Zero when `hideLegend` is set.
+- `plotHeight` is the residual: `chartHeight` minus the three bands above.
+
+Width follows the same shape (`yAxisBand + plotWidth + rightPad`), but the presets stay
+responsive — they never fix a pixel width — so `plotWidth`/`containerWidth` are only meaningful
+when a caller explicitly supplies `containerWidth` (tests, or the browser-level check); the
+presets themselves never pass it.
+
+## Removed props, and their replacement
+
+| Removed prop | Replacement | Why |
+|---|---|---|
+| `minHeight` | `size` (see below) | A floor was a *card* concern, not a chart one — `ChartFrame` still has its own `minHeight`, unchanged. |
+| `aspect` | `size` | One size source, system-wide (operator decision). A chart's height no longer tracks its width. |
+| `margin` | *(none)* | The model owns margins completely — spacing between a chart and its neighbours is the card's job. |
+| `xAxisAngle` / a caller-set `tickLabelStyle.angle` | `xLabels: "auto" \| "horizontal" \| "angled"` | Under `"auto"` the model decides from the tick count and label length whether rotation is needed — a consumer no longer states a rotation and separately pays for its geometry. |
+
+Passing a removed prop throws in development (`assertRemovedChartProp`), naming the replacement.
+It is inert in production — a shared package must not crash a consumer's page over a layout prop.
+This is deliberate, not a silent ignore: every call site that still passes `minHeight`/`aspect`/
+`margin` will see it immediately in dev.
+
+## `size` — before / after
+
+```diff
+- <BarChart minHeight={320} series={series} />
++ <BarChart size="standard" series={series} />
+```
+
+```diff
+- <BarChart aspect={1.8} minHeight={280} series={series} />
++ <BarChart size="tall" series={series} />
+```
+
+Tokens resolve through the theme's spacing scale (`theme.spacing`, MUI's 8px unit):
+
+| Token | Spacing units | Height |
+|---|---|---|
+| `compact` | 30 | 240px |
+| `standard` | 40 | 320px |
+| `tall` | 50 | 400px |
+
+`standard` is pinned to the exact number every current consumer already renders at today
+(`TimeSeriesChart`'s old `CHART_HEIGHT = 320`) — this migration does not silently redraw an
+existing default-sized chart. `height` (a raw px number) survives as a **documented escape** for a
+justified special case; prefer `size`.
+
+**Four call sites lose responsive height with `aspect` gone**: `hram/AccessGapScatterPanel.jsx`
+and three in `fitness-monitor/BodyHistoryPage.jsx` (its `960/380` ratios were a design decision,
+not an accident — operator accepted this trade 2026-08-22). Each converts to a size token as a
+named, visible decision in its own migration WO — charts still reflow horizontally (`width: 100%`
+on the wrapper), only the height stops tracking width.
+
+## `xLabels` — before / after
+
+```diff
+- <BarChart xAxis={[{ data: wardNames, tickLabelStyle: { angle: -45 } }]} />
++ <BarChart xAxis={[{ data: wardNames }]} xLabels="angled" />
+```
+
+```diff
+- <BarChart xAxis={[{ data: months }]} />   {/* horizontal by default, unrotated */}
++ <BarChart xAxis={[{ data: months }]} xLabels="auto" />   {/* the new default; equivalent here */}
+```
+
+`"auto"` (the default) is a **heuristic**, not a true fit computation — the presets stay
+responsive, so the resolver has no real container width to measure against before render. It
+rotates when there are more than 6 categories *and* the longest formatted label is longer than 4
+characters; otherwise it stays horizontal. `"horizontal"` always stays flat; `"angled"` always
+rotates (at the caller's own `tickLabelStyle.angle`, or -45° if unset). Verify a specific chart's
+real rendered fit with the browser-level check described below — a unit test cannot see real
+container width or real font metrics either.
+
+## `margin` — no replacement
+
+There is no margin prop any more. Spacing between a chart card and its neighbours is the card's
+job (a wrapping `Box`/`Stack`'s own `gap`/`p`), not the chart's.
+
+```diff
+- <Chart series={series} margin={{ left: 220 }} />   {/* hand-tuned gutter for a long label */}
++ <Box sx={{ pl: '220px' }}>
++   <Chart series={series} />
++ </Box>
+```
+
+If the extra space was compensating for a wide y-axis label the resolver now sizes itself
+(`sizeYAxisForContent`), try dropping the override entirely first — the model may already reserve
+the right amount.
+
+## What stays unchanged
+
+- `ChartFrame`'s own `minHeight`/`height`/`aspect` — it is a whole-card floor (title, toolbar,
+  chart, legend, footnotes, export links), not a single chart's size, and was never in scope here
+  (`UCM-CHART-9` established this distinction).
+- Palettes, series colours, tooltips, legend content, interaction.
+- `sizeYAxisForContent` (y-axis width from tick content) — reused unchanged inside the resolver.
+
+## Verifying a migrated chart
+
+The invariant is arithmetic, but only against **real rendered geometry** — jsdom cannot measure
+SVG text (`getComputedTextLength` is unimplemented there), so the unit suite injects a stubbed
+measurement. Before shipping a chart that leans on rotated or auto-detected labels, render it in
+a real browser at a realistic width and confirm no tick label is clipped and no band is reserved
+with nothing in it (the Access-scatter defect this WO exists to close).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micha.bigler/ui-core-micha",
-  "version": "2.42.2",
+  "version": "3.0.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "sideEffects": [