@micha.bigler/ui-core-micha 2.39.1 → 2.41.0

package/dist/components/charts/chartDefaults.js

@@ -7,7 +7,18 @@ export function withGridDefaults(grid) {
 }
 export function withAxisDefaults(axes, label, defaults, tickFontSize) {
     const values = (axes === null || axes === void 0 ? void 0 : axes.length) ? axes : [defaults];
-    return values.map((axis) => (Object.assign(Object.assign(Object.assign({}, defaults), axis), { tickLabelStyle: Object.assign({ fontSize: tickFontSize }, axis.tickLabelStyle), label: axis.label || label })));
+    return values.map((axis, index) => (Object.assign(Object.assign(Object.assign({}, defaults), axis), { tickLabelStyle: Object.assign({ fontSize: tickFontSize }, axis.tickLabelStyle), 
+        // THEME-9: the single `label` argument is the caller's ONE string for
+        // this whole axis family (xAxisLabel/yAxisLabel) -- it may only ever
+        // fall back onto ONE axis. Applying it via .map() to every entry
+        // broadcast the identical label onto every axis in a multi-axis array
+        // (measured live: hram's dual-axis chart carried the same 43-character
+        // label on both y-axes). Only the first entry -- the common single-axis
+        // case is index 0 -- gets the fallback; a caller building a genuine
+        // multi-axis array must label each entry itself (as TimeSeriesChart's
+        // own secondary-axis support already does), exactly like MUI's own
+        // default `position: 'left'` (only the first entry, MUI docs).
+        label: axis.label || (index === 0 ? label : undefined) })));
 }
 function cssLengthToPixels(value) {
     if (typeof value === 'number')
@@ -22,8 +33,37 @@ function cssLengthToPixels(value) {
     return parsed;
 }
 const MUI_LABELLED_X_AXIS_HEIGHT = 45;
-const MUI_CHART_MARGIN_BOTTOM = 20;
+// THEME-11: this used to mirror MUI's own DEFAULT_MARGINS.bottom (20) -- the "resting" bottom
+// margin the rotated-tick path adds its extra height on top of. Now that PACKAGE_DEFAULT_MARGIN
+// below sets the package's own non-rotated bottom to 8, this constant must track THAT value, not
+// MUI's, or a rotated chart would add its extra height to the wrong (too generous) base while
+// every non-rotated chart got trimmed -- an inconsistent baseline between the two paths.
+const MUI_CHART_MARGIN_BOTTOM = 8;
 const AVERAGE_GLYPH_WIDTH_EM = 0.6;
+// 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
+// something different: `left`/`bottom` are pure padding (the tick labels already live inside
+// axisSizeLeft / DEFAULT_AXIS_SIZE_HEIGHT), `top` keeps room for the topmost y-tick label's own
+// ~9px overhang past the plot (it is centred on its gridline, not below it), and `right` stays
+// 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.
+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 (or
+ * the rotated-tick path's own computed `bottom`) 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.
+ */
+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);
@@ -78,6 +118,133 @@ export function spaceForRotatedTicks(xAxis, margin, defaultLineHeight = 1) {
         ? Object.assign(Object.assign({}, margin), { bottom: MUI_CHART_MARGIN_BOTTOM + largestExtraHeight }) : margin;
     return { xAxis: spacedXAxis, margin: spacedMargin };
 }
+// 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 /
+// AXIS_LABEL_DEFAULT_HEIGHT constants and its `useChartDimensions` selector
+// (drawingArea.left = margin.left + axisSizeLeft, i.e. margin and axis size
+// are ADDITIVE, not one containing the other). That flat default is both too
+// generous for short ticks ("0%"/"50%"/"100%") and too stingy for wide ones
+// ("50.0 min"), which is exactly the measured overlap on the Accessibility
+// y-axis. Mirrors spaceForRotatedTicks' existing text-width heuristic below.
+const Y_AXIS_TICK_SIZE = 6;
+const Y_AXIS_TICK_LABEL_GAP = 2;
+const Y_AXIS_LABEL_TICK_GAP = 2;
+// A rotated (90deg) axis-label's line-box "thickness" -- what it costs in
+// WIDTH once rotated -- runs a bit past its raw font size once ascender/
+// descender room is included; matches the ~18px measured live for a 14px
+// label (14 * 1.3 ~= 18).
+const Y_AXIS_LABEL_THICKNESS_FACTOR = 1.3;
+// A small safety margin on the estimate: `spaceForRotatedTicks`'s own risk
+// note applies here too -- a too-tight cut recreates the overlap it was
+// meant to fix, and glyph-width heuristics are approximate by nature.
+const Y_AXIS_WIDTH_SAFETY_FACTOR = 1.1;
+// MUI X-Charts' ChartsYAxisImpl hardcodes the axis-label font at 14px
+// (`additionalProps.style: {...theme.typography.body1, fontSize: 14, ...}`
+// -- fontSize:14 is set AFTER the theme.typography.body1 spread, so it wins
+// regardless of what body1 actually resolves to). Matching that literal
+// constant here -- rather than reading it off `theme.typography.body1` --
+// keeps this sizing correct even if this package's body1 size ever changes;
+// coupling it to body1 was only ever coincidentally right because body1
+// happens to be 14px today.
+const MUI_AXIS_LABEL_FONT_SIZE_PX = 14;
+function longestFormattedTick(values, valueFormatter) {
+    return values.reduce((longest, value) => {
+        let text;
+        try {
+            text = valueFormatter ? String(valueFormatter(value, { location: 'tick' })) : String(value);
+        }
+        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 as the unformatted number would need.
+            text = String(value);
+        }
+        return text.length > longest.length ? text : longest;
+    }, '');
+}
+/**
+ * Sizes a linear y-axis to its actual tick content instead of MUI's flat
+ * default. Only touches axes the caller left unsized (`axis.width == null`)
+ * and only linear/numeric ones -- a categorical axis's ticks are names, not
+ * numbers, and sizing those is not this function's job. Candidate values come
+ * from the axis' own `min`/`max` when the caller set them (as every current
+ * consumer does), falling back to the series actually plotted against this
+ * axis; if neither yields a candidate, the axis is left untouched rather than
+ * guessed at.
+ *
+ * `tickFontSize` is only the FALLBACK -- an axis' own `tickLabelStyle.fontSize`
+ * (set by `withAxisDefaults`, itself overridable per-axis by the caller) is
+ * read first, so a caller-tuned tick font is sized correctly rather than
+ * against the package-wide default. The axis LABEL's font is not a caller
+ * knob at all (`MUI_AXIS_LABEL_FONT_SIZE_PX` -- MUI hardcodes it).
+ *
+ * The series-to-axis match for the fallback deliberately mirrors MUI's own
+ * default-assignment rule, not a naive `undefined === undefined`: a series
+ * with no explicit `yAxisId` is assigned to the FIRST axis in the array
+ * (`yAxisIds[0]` in MUI's own selector), never to "no id". Matching only
+ * `undefined === undefined` left the primary axis of a real dual-axis chart
+ * (id `'primary'`, its series never set `yAxisId`) with zero matched series
+ * and therefore MUI's untouched flat default -- a silent no-op on exactly
+ * the dual-axis case this WO was measured against.
+ */
+export function sizeYAxisForContent(yAxis, series, tickFontSize) {
+    var _a;
+    const fallbackTickFontSizePx = cssLengthToPixels(tickFontSize);
+    const defaultAxisId = (_a = yAxis[0]) === null || _a === void 0 ? void 0 : _a.id;
+    return yAxis.map((axis) => {
+        var _a;
+        if (axis.width != null)
+            return axis;
+        if (axis.scaleType && axis.scaleType !== 'linear')
+            return axis;
+        const tickFontSizePx = cssLengthToPixels((_a = axis.tickLabelStyle) === null || _a === void 0 ? void 0 : _a.fontSize) || fallbackTickFontSizePx;
+        if (tickFontSizePx === 0)
+            return axis;
+        const candidates = [];
+        if (typeof axis.min === 'number')
+            candidates.push(axis.min);
+        if (typeof axis.max === 'number')
+            candidates.push(axis.max);
+        if (candidates.length === 0) {
+            (series || [])
+                .filter((item) => { var _a; return ((_a = item.yAxisId) !== null && _a !== void 0 ? _a : defaultAxisId) === axis.id; })
+                .forEach((item) => (item.data || []).forEach((value) => {
+                if (typeof value === 'number')
+                    candidates.push(value);
+            }));
+        }
+        if (candidates.length === 0)
+            return axis;
+        const longestTick = longestFormattedTick(candidates, axis.valueFormatter);
+        const tickTextWidth = Math.max(tickFontSizePx, longestTick.length * tickFontSizePx * AVERAGE_GLYPH_WIDTH_EM);
+        const labelThickness = axis.label
+            ? Math.ceil(MUI_AXIS_LABEL_FONT_SIZE_PX * Y_AXIS_LABEL_THICKNESS_FACTOR) + Y_AXIS_LABEL_TICK_GAP
+            : 0;
+        const width = Math.ceil((tickTextWidth + Y_AXIS_TICK_SIZE + Y_AXIS_TICK_LABEL_GAP + labelThickness)
+            * Y_AXIS_WIDTH_SAFETY_FACTOR);
+        return Object.assign(Object.assign({}, axis), { width });
+    });
+}
+/**
+ * Locale-correct, unit-free tick numbers as the default -- BarChart set none
+ * at all (raw numbers straight from the domain), and a hand-rolled `Intl`
+ * compact-notation default was measured to be actively wrong: German does
+ * not compact thousands at all (`12'500` stays `12'500`) and Swahili prepends
+ * a word that is WIDER than the raw number (`elfu 12.5`) -- compact notation
+ * does not solve the width problem and worsens it in one locale. Plain
+ * grouped formatting (no `notation: 'compact'`) is safe across all four
+ * locales this package's consumers use. Ticks get a short, rounded form;
+ * tooltip/legend keep full precision -- teaching screens must not round away
+ * a meaningful difference. A caller's own `valueFormatter` always wins (this
+ * is only ever used as a default, per `withAxisDefaults`' `{...defaults,
+ * ...axis}` merge).
+ */
+export function defaultNumericTickFormatter(locale) {
+    return (value, context) => ((context === null || context === void 0 ? void 0 : context.location) === 'tick'
+        ? new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(value)
+        : new Intl.NumberFormat(locale).format(value));
+}
 export function withChartSlotDefaults(slotProps, legendPosition) {
     var _a;
     const position = Object.assign(Object.assign(Object.assign({}, DEFAULT_LEGEND_POSITION), legendPosition), (_a = slotProps === null || slotProps === void 0 ? void 0 : slotProps.legend) === null || _a === void 0 ? void 0 : _a.position);

package/dist/components/charts/palette.js

@@ -17,6 +17,12 @@ export function getNeutralChartPalette(theme) {
         sequential: isDark
             ? [palette.action.disabled, palette.text.secondary, palette.primary.light, palette.primary.main, palette.primary.dark]
             : [palette.action.disabled, palette.divider, palette.text.secondary, palette.primary.light, palette.primary.main],
+        // THEME-10: an undifferentiated mass (e.g. a scatter cloud with no colour
+        // dimension encoded) is ink-neutral, not a series hue -- a KPI identity
+        // colour there implies a meaning the cloud does not carry. `text.secondary`
+        // reads as neutral ink in both palette modes without competing with an
+        // actual categorical/sequential encoding drawn on top of it.
+        neutral: palette.text.secondary,
     };
 }
 /** Resolves the kit's neutral palette from the nearest MUI ThemeProvider. */

package/dist/index.js

@@ -46,6 +46,7 @@ export { ChartFrame } from './components/charts/ChartFrame';
 export { BarChart } from './components/charts/BarChart';
 export { LineChart } from './components/charts/LineChart';
 export { TimeSeriesChart } from './components/charts/TimeSeriesChart';
+export { ScatterChart, ScatterReferenceCurve, ScatterReferenceLine, scaleBubbleRadius, } from './components/charts/ScatterChart';
 export { getNeutralChartPalette, useNeutralChartPalette } from './components/charts/palette';
 export { formatShortTime, formatShortDate, formatShortMonth, formatShortYear, } from './components/charts/chartLabels';
 export { yearTickInterval } from './components/charts/yearTickInterval';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micha.bigler/ui-core-micha",
-  "version": "2.39.1",
+  "version": "2.41.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "repository": {

package/src/components/charts/BarChart.jsx

@@ -1,19 +1,29 @@
 import React from 'react';
 import { Box } from '@mui/material';
 import { useTheme } from '@mui/material/styles';
+import { useTranslation } from 'react-i18next';
 import { BarChart as MuiBarChart } from '@mui/x-charts/BarChart';
 import { useNeutralChartPalette } from './palette';
 import {
   DEFAULT_LEGEND_POSITION,
+  defaultNumericTickFormatter,
+  sizeYAxisForContent,
   spaceForRotatedTicks,
   withAxisDefaults,
   withChartSlotDefaults,
   withGridDefaults,
+  withMarginDefaults,
 } from './chartDefaults';
 
 /**
- * Responsive MUI X-Charts bar preset. xAxisLabel and yAxisLabel (including units) are required.
- * It supplies labelled axes, tooltips, and an automatic multi-series legend.
+ * Responsive MUI X-Charts bar preset. It supplies labelled axes, tooltips,
+ * and an automatic multi-series legend. `xAxisLabel`/`yAxisLabel` are
+ * optional, per DESIGN.md #8a: a categorical axis (BarChart's default x-axis
+ * shape) needs no title by default -- its ticks are names -- and a numeric
+ * axis needs one only unless its unit is already visible in the ticks and
+ * the panel heading already names the quantity. Omitting one never suppresses
+ * a label the caller DID set (`withAxisDefaults` only ever falls back onto
+ * an axis without its own `label`).
  */
 export function BarChart({
   series = [],
@@ -32,10 +42,8 @@ export function BarChart({
   ...chartProps
 }) {
   const theme = useTheme();
+  const { i18n } = useTranslation();
   const neutralPalette = useNeutralChartPalette();
-  if (!xAxisLabel || !yAxisLabel) {
-    throw new Error('BarChart requires xAxisLabel and yAxisLabel.');
-  }
 
   const labelledXAxis = withAxisDefaults(
     xAxis,
@@ -46,7 +54,12 @@ export function BarChart({
   const labelledYAxis = withAxisDefaults(
     yAxis,
     yAxisLabel,
-    { scaleType: 'linear' },
+    { scaleType: 'linear', valueFormatter: defaultNumericTickFormatter(i18n.language) },
+    theme.typography.caption.fontSize,
+  );
+  const sizedYAxis = sizeYAxisForContent(
+    labelledYAxis,
+    series,
     theme.typography.caption.fontSize,
   );
   const rotatedTickSpace = spaceForRotatedTicks(
@@ -61,11 +74,11 @@ export function BarChart({
         {...chartProps}
         series={series}
         xAxis={rotatedTickSpace.xAxis}
-        yAxis={labelledYAxis}
+        yAxis={sizedYAxis}
         colors={palette || neutralPalette.categorical}
         grid={withGridDefaults(grid)}
         hideLegend={hideLegend}
-        margin={rotatedTickSpace.margin}
+        margin={withMarginDefaults(rotatedTickSpace.margin)}
         slotProps={withChartSlotDefaults(slotProps, legendPosition)}
       />
     </Box>

package/src/components/charts/ChartFrame.jsx

@@ -80,7 +80,9 @@ export function ChartFrame({
 
   return (
     <Paper variant={variant} sx={[CHART_FRAME_ROOT_SX, ...callerSx]}>
-      <Box sx={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: 2, mb: 2 }}>
+      {/* THEME-11: mb: 2 -> mb: 1 (16 -> 8px) -- one line item in the estate-wide chart-furniture
+          trim; the controls row below keeps its own mb: 2, not named in that WO's scope. */}
+      <Box sx={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: 2, mb: 1 }}>
         <Box>
           <Typography id={titleId} variant={titleVariant}>{title}</Typography>
           {subtitle && <Typography variant="body2" color="text.secondary">{subtitle}</Typography>}

package/src/components/charts/LineChart.jsx

@@ -1,6 +1,7 @@
 import React from 'react';
 import { Box } from '@mui/material';
 import { useTheme } from '@mui/material/styles';
+import { useTranslation } from 'react-i18next';
 import {
   LineChart as MuiLineChart,
   MarkElement as MuiMarkElement,
@@ -8,10 +9,13 @@ import {
 import { useNeutralChartPalette } from './palette';
 import {
   DEFAULT_LEGEND_POSITION,
+  defaultNumericTickFormatter,
+  sizeYAxisForContent,
   spaceForRotatedTicks,
   withAxisDefaults,
   withChartSlotDefaults,
   withGridDefaults,
+  withMarginDefaults,
 } from './chartDefaults';
 
 // Fixes MUI's hollow `background.paper`-filled marker (MarkElement.js's own
@@ -29,8 +33,14 @@ function FilledMarkElement({ color, style, ...props }) {
 }
 
 /**
- * Responsive MUI X-Charts line preset. xAxisLabel and yAxisLabel (including units) are required.
- * It supplies labelled axes, tooltips, and an automatic multi-series legend.
+ * Responsive MUI X-Charts line preset. It supplies labelled axes, tooltips,
+ * and an automatic multi-series legend. `xAxisLabel`/`yAxisLabel` are
+ * optional, per DESIGN.md #8a: a categorical axis needs no title by default
+ * -- its ticks are names -- and a numeric axis needs one only unless its
+ * unit is already visible in the ticks and the panel heading already names
+ * the quantity. Omitting one never suppresses a label the caller DID set
+ * (`withAxisDefaults` only ever falls back onto an axis without its own
+ * `label`).
  */
 export function LineChart({
   series = [],
@@ -50,10 +60,8 @@ export function LineChart({
   ...chartProps
 }) {
   const theme = useTheme();
+  const { i18n } = useTranslation();
   const neutralPalette = useNeutralChartPalette();
-  if (!xAxisLabel || !yAxisLabel) {
-    throw new Error('LineChart requires xAxisLabel and yAxisLabel.');
-  }
 
   const labelledXAxis = withAxisDefaults(
     xAxis,
@@ -64,19 +72,24 @@ export function LineChart({
   const labelledYAxis = withAxisDefaults(
     yAxis,
     yAxisLabel,
-    { scaleType: 'linear' },
+    { scaleType: 'linear', valueFormatter: defaultNumericTickFormatter(i18n.language) },
     theme.typography.caption.fontSize,
   );
-  const rotatedTickSpace = spaceForRotatedTicks(
-    labelledXAxis,
-    margin,
-    theme.typography.caption.lineHeight,
-  );
   const defaultedSeries = series.map((item) => ({
     showMark: false,
     labelMarkType: 'square',
     ...item,
   }));
+  const sizedYAxis = sizeYAxisForContent(
+    labelledYAxis,
+    defaultedSeries,
+    theme.typography.caption.fontSize,
+  );
+  const rotatedTickSpace = spaceForRotatedTicks(
+    labelledXAxis,
+    margin,
+    theme.typography.caption.lineHeight,
+  );
 
   return (
     <Box data-testid="line-chart-container" sx={{ width: '100%', minHeight, aspectRatio: aspect }}>
@@ -84,11 +97,11 @@ export function LineChart({
         {...chartProps}
         series={defaultedSeries}
         xAxis={rotatedTickSpace.xAxis}
-        yAxis={labelledYAxis}
+        yAxis={sizedYAxis}
         colors={palette || neutralPalette.categorical}
         grid={withGridDefaults(grid)}
         hideLegend={hideLegend}
-        margin={rotatedTickSpace.margin}
+        margin={withMarginDefaults(rotatedTickSpace.margin)}
         slots={{ mark: FilledMarkElement, ...slots }}
         slotProps={withChartSlotDefaults(slotProps, legendPosition)}
       />