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

package/src/components/charts/ScatterChart.jsx

@@ -0,0 +1,277 @@
+import React, { useMemo } from 'react';
+import { Box } from '@mui/material';
+import { useTheme } from '@mui/material/styles';
+import { useTranslation } from 'react-i18next';
+import { ScatterChart as MuiScatterChart } from '@mui/x-charts/ScatterChart';
+import { useXScale, useYScale } from '@mui/x-charts/hooks';
+import { useNeutralChartPalette } from './palette';
+import {
+  DEFAULT_LEGEND_POSITION,
+  defaultNumericTickFormatter,
+  sizeYAxisForContent,
+  withAxisDefaults,
+  withChartSlotDefaults,
+  withGridDefaults,
+} from './chartDefaults';
+
+// Small enough that hram's largest cloud (~300 points, the tested magnitude -- state it, don't
+// imply it scales past that) doesn't fuse into a solid mass at the default (non-bubble) size.
+const DEFAULT_MARKER_RADIUS = 5;
+const BUBBLE_MIN_RADIUS = 3;
+const BUBBLE_RADIUS_SCALE = 10;
+
+/**
+ * value -> radius, `max(3, 10 * sqrt(value / maxValue))` -- the formula the access-gap panel
+ * already hand-rolls (THEME-10 scope 5). Exported so a consumer can size a legend swatch or a
+ * standalone marker the same way the chart does.
+ */
+export function scaleBubbleRadius(value, maxValue, { minRadius = BUBBLE_MIN_RADIUS, scale = BUBBLE_RADIUS_SCALE } = {}) {
+  if (!Number.isFinite(value) || !Number.isFinite(maxValue) || maxValue <= 0) return minRadius;
+  return Math.max(minRadius, scale * Math.sqrt(Math.max(0, value) / maxValue));
+}
+
+// A custom MUI marker slot -- the only way to vary radius/colour/shape PER POINT: MUI's own
+// Scatter passes a single `markerSize` per whole series (confirmed against
+// @mui/x-charts/ScatterChart/Scatter.js -- `size: series.markerSize`, never derived from a
+// point's own `z`), so bubble sizing and per-point overrides (a hollow status-quo marker, a
+// continuous-scale colour) can only be expressed by replacing the marker itself.
+function makeMarkerSlot(seriesById, { sizeAccessor, chartMax, getPointStyle }) {
+  return function PresetScatterMarker({
+    seriesId, dataIndex, color, x, y, isHighlighted, isFaded, size, onClick, ...rest
+  }) {
+    const point = seriesById[seriesId]?.data?.[dataIndex];
+    const style = point && getPointStyle ? (getPointStyle(point, { seriesId, dataIndex }) || {}) : {};
+    const radius = style.radius
+      ?? (sizeAccessor && point ? scaleBubbleRadius(sizeAccessor(point), chartMax) : size);
+    const r = (isHighlighted ? 1.15 : 1) * radius;
+    const fill = style.hollow ? 'none' : (style.color ?? color);
+    const stroke = style.color ?? color;
+    const shared = {
+      onClick,
+      opacity: isFaded ? 0.3 : 1,
+      stroke,
+      strokeWidth: style.hollow ? 2 : (style.strokeWidth ?? 1),
+      style: { cursor: onClick ? 'pointer' : 'unset' },
+      ...rest,
+    };
+    if (style.shape === 'square') {
+      return <rect x={x - r} y={y - r} width={r * 2} height={r * 2} fill={fill} {...shared} />;
+    }
+    if (style.shape === 'diamond') {
+      return <polygon points={`${x},${y - r} ${x + r},${y} ${x},${y + r} ${x - r},${y}`} fill={fill} {...shared} />;
+    }
+    return <circle cx={x} cy={y} r={r} fill={fill} {...shared} />;
+  };
+}
+
+/**
+ * A computed curve (allocation's Pareto envelope) drawn inside the chart's own live coordinate
+ * space. Render as a `ScatterChart` child -- `useXScale`/`useYScale` only resolve inside the
+ * chart's own context, so this can never drift into a second, hand-rolled pixel mapping the way
+ * the hand-drawn panels this preset replaces each built their own.
+ */
+export function ScatterReferenceCurve({ points, color, dashed, strokeWidth = 2 }) {
+  const xScale = useXScale();
+  const yScale = useYScale();
+  if (!points || points.length < 2) return null;
+  const d = points.map((p, i) => `${i === 0 ? 'M' : 'L'}${xScale(p.x)},${yScale(p.y)}`).join(' ');
+  return <path d={d} fill="none" stroke={color} strokeWidth={strokeWidth} strokeDasharray={dashed ? '6 3' : undefined} />;
+}
+
+/**
+ * A straight reference line with an optional inline label -- the access panel's labelled y=x
+ * "no gap" diagonal, or optimization's dashed threshold line. Same live-scale rule as
+ * `ScatterReferenceCurve`.
+ */
+export function ScatterReferenceLine({
+  from, to, color, dashed, strokeWidth = 1.5, label, labelAt, labelAngle = 0,
+}) {
+  const xScale = useXScale();
+  const yScale = useYScale();
+  const labelX = labelAt ? xScale(labelAt.x) : null;
+  const labelY = labelAt ? yScale(labelAt.y) : null;
+  return (
+    <g>
+      <line
+        x1={xScale(from.x)}
+        y1={yScale(from.y)}
+        x2={xScale(to.x)}
+        y2={yScale(to.y)}
+        stroke={color}
+        strokeWidth={strokeWidth}
+        strokeDasharray={dashed ? '5 3' : undefined}
+      />
+      {label && labelAt && (
+        <text
+          x={labelX}
+          y={labelY}
+          fontSize={10}
+          fill={color}
+          textAnchor="start"
+          transform={labelAngle ? `rotate(${labelAngle}, ${labelX}, ${labelY})` : undefined}
+        >
+          {label}
+        </text>
+      )}
+    </g>
+  );
+}
+
+/**
+ * Responsive MUI X-Charts scatter preset, drawn from three real consumers (THEME-10): a
+ * continuously-coloured cost/outcome cloud with an envelope curve and marked points
+ * (allocation performance), a bubble cloud with a labelled y=x reference diagonal and
+ * categorical per-point colouring (access gap), and a cloud with a dashed reference line and a
+ * hollow status-quo marker (optimization results). Reuses BarChart/LineChart's own axis
+ * machinery (THEME-9) rather than sizing its own -- a scatter axis is a numeric axis like any
+ * other, and a preset that re-derives axis sizing would re-open exactly what THEME-9 closed.
+ *
+ * `series` follows MUI's own scatter shape (`{id, label, data: [{x,y,z?,id?}], color?}`).
+ * Multiple series render as a categorical cloud with a discrete legend, one colour per series
+ * -- draw those colours from the app's own family/role register via `palette`; this package
+ * does not invent one. A single series with no explicit `color` renders as one neutral mass:
+ * undifferentiated data encodes no dimension, so it gets the role register's neutral tone
+ * (`palette.js`'s `neutral`), never a series/KPI identity hue.
+ *
+ * `sizeAccessor(point) => number` turns on bubble mode: marker radius follows
+ * `scaleBubbleRadius`, and every series' points are drawn largest-first so a small bubble is
+ * never hidden under a large one -- the z-order is the whole correctness of a bubble chart, not
+ * a decoration.
+ *
+ * `getPointStyle(point, {seriesId, dataIndex}) => {hollow?, color?, shape?, radius?,
+ * strokeWidth?}` marks individual points -- a status-quo point drawn hollow against filled
+ * candidates (allocation, optimization), a `'square'` shape for a source category the data
+ * itself marks (allocation's "targeted" points), or a per-point colour from a continuous scale
+ * the caller computed (this package does not ship a continuous colour-scale/legend component;
+ * the caller already owns that logic and only needs a way to apply the resolved colour per
+ * point, which this is it). Read the `point` object itself, not `dataIndex`, to correlate a
+ * style back to your own data -- in bubble mode (`sizeAccessor` set) `dataIndex` indexes the
+ * chart's internal z-ordered copy of your series, not your original array's order.
+ *
+ * Reference geometry (a computed curve, a straight line, either with an optional label) is
+ * composed as `children` using `ScatterReferenceCurve`/`ScatterReferenceLine` above.
+ *
+ * Tested magnitude: a few hundred marks (hram's largest cloud is ~300 points). Not verified,
+ * and not implied to hold, at thousands+.
+ *
+ * THEME-10 was commissioned before its requirement set closed -- a forthcoming "paired point"
+ * shape (optimization's MILP-vs-simulated pair, two marks joined by a connector) is named but
+ * explicitly NOT built here. Nothing below assumes a datum produces exactly one mark: a point
+ * object may carry arbitrary extra fields beyond `{x,y,z,id}` (as `getPointStyle`'s own status-
+ * quo/bubble-radius usage already does), `getPointStyle`/`sizeAccessor` key off that datum, not
+ * off a fixed mark count, and reference geometry is composed via `children`, not baked into the
+ * per-point contract. A pair variant can therefore layer on later -- extra series entries plus a
+ * connector drawn through `children` -- without reshaping `series` or either callback's contract.
+ */
+export function ScatterChart({
+  series = [],
+  xAxisLabel,
+  yAxisLabel,
+  xAxis,
+  yAxis,
+  palette,
+  minHeight,
+  aspect,
+  grid,
+  hideLegend = series.length <= 1,
+  legendPosition = DEFAULT_LEGEND_POSITION,
+  margin,
+  sizeAccessor,
+  getPointStyle,
+  markerSize = DEFAULT_MARKER_RADIUS,
+  slotProps,
+  children,
+  ...chartProps
+}) {
+  const theme = useTheme();
+  const { i18n } = useTranslation();
+  const neutralPalette = useNeutralChartPalette();
+
+  const labelledXAxis = withAxisDefaults(
+    xAxis,
+    xAxisLabel,
+    { scaleType: 'linear', valueFormatter: defaultNumericTickFormatter(i18n.language) },
+    theme.typography.caption.fontSize,
+  );
+  const labelledYAxis = withAxisDefaults(
+    yAxis,
+    yAxisLabel,
+    { 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.
+  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 isNeutral = series.length <= 1 && !series[0]?.color;
+  const resolvedPalette = palette || (isNeutral ? [neutralPalette.neutral] : neutralPalette.categorical);
+
+  // A single chart-wide max, NOT one per series: population (or whatever sizeAccessor reads) is
+  // one comparable scale across the whole cloud (matches the access-gap panel's own
+  // `maxPop = Math.max(1, ...points.map(p => p.population))`, computed over every point
+  // regardless of division/settlement) -- a per-series max would let each series' own largest
+  // point always render at full radius, making cross-series bubble size meaningless.
+  const chartMax = useMemo(() => {
+    if (!sizeAccessor) return 1;
+    return Math.max(
+      1,
+      ...series.flatMap((item) => (item.data || []).map((point) => sizeAccessor(point))).filter(Number.isFinite),
+    );
+  }, [series, sizeAccessor]);
+
+  // THEME-10 scope 5: explicit z-order -- largest bubbles drawn first so smaller ones are never
+  // hidden underneath (SVG paints later elements on top). A no-op outside bubble mode.
+  const orderedSeries = useMemo(() => (
+    sizeAccessor
+      ? series.map((item) => ({
+        ...item,
+        data: [...(item.data || [])].sort((a, b) => sizeAccessor(b) - sizeAccessor(a)),
+      }))
+      : series
+  ), [series, sizeAccessor]);
+
+  // The marker's `dataIndex` refers to a position in whatever was actually handed to MUI --
+  // `orderedSeries` (post z-order sort), not the caller's original `series` -- so the lookup
+  // table the marker closes over must be built from that SAME array, or a sorted bubble series
+  // would resolve every point's style/radius against the wrong (pre-sort) index.
+  const orderedSeriesById = useMemo(
+    () => Object.fromEntries(orderedSeries.map((item) => [item.id, item])),
+    [orderedSeries],
+  );
+  const markerSlot = useMemo(
+    () => makeMarkerSlot(orderedSeriesById, { sizeAccessor, chartMax, getPointStyle }),
+    [orderedSeriesById, sizeAccessor, chartMax, getPointStyle],
+  );
+
+  return (
+    <Box data-testid="scatter-chart-container" sx={{ width: '100%', minHeight, aspectRatio: aspect }}>
+      <MuiScatterChart
+        {...chartProps}
+        series={orderedSeries.map((item) => ({ markerSize, ...item }))}
+        xAxis={labelledXAxis}
+        yAxis={sizedYAxis}
+        colors={resolvedPalette}
+        grid={withGridDefaults(grid)}
+        hideLegend={hideLegend}
+        margin={margin}
+        slots={{ marker: markerSlot }}
+        slotProps={withChartSlotDefaults(slotProps, legendPosition)}
+      >
+        {children}
+      </MuiScatterChart>
+    </Box>
+  );
+}

package/src/components/charts/chartDefaults.js

@@ -9,7 +9,7 @@ export function withGridDefaults(grid) {
 
 export function withAxisDefaults(axes, label, defaults, tickFontSize) {
   const values = axes?.length ? axes : [defaults];
-  return values.map((axis) => ({
+  return values.map((axis, index) => ({
     // `defaults.scaleType` (and any other scale-defining default) must
     // survive even when the caller passes their OWN xAxis/yAxis array --
     // confirmed live in the dev harness: a caller-supplied axis with `data`
@@ -25,7 +25,17 @@ export function withAxisDefaults(axes, label, defaults, tickFontSize) {
       fontSize: tickFontSize,
       ...axis.tickLabelStyle,
     },
-    label: axis.label || label,
+    // 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),
   }));
 }
 
@@ -40,9 +50,40 @@ function cssLengthToPixels(value) {
 }
 
 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 { ...PACKAGE_DEFAULT_MARGIN, ...explicit };
+}
+
 function formattedTickText(axis, value) {
   if (!axis.valueFormatter) return String(value);
   try {
@@ -100,6 +141,136 @@ export function spaceForRotatedTicks(xAxis, margin, defaultLineHeight = 1) {
   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 {
+      // 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) {
+  const fallbackTickFontSizePx = cssLengthToPixels(tickFontSize);
+  const defaultAxisId = yAxis[0]?.id;
+  return yAxis.map((axis) => {
+    if (axis.width != null) return axis;
+    if (axis.scaleType && axis.scaleType !== 'linear') return axis;
+
+    const tickFontSizePx = cssLengthToPixels(axis.tickLabelStyle?.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) => (item.yAxisId ?? 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 { ...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?.location === 'tick'
+    ? new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(value)
+    : new Intl.NumberFormat(locale).format(value));
+}
+
 export function withChartSlotDefaults(slotProps, legendPosition) {
   const position = {
     ...DEFAULT_LEGEND_POSITION,

package/src/components/charts/palette.js

@@ -18,6 +18,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,
   };
 }
 

package/src/index.js

@@ -71,6 +71,12 @@ 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,

package/tests/BarChart.test.jsx

@@ -50,9 +50,25 @@ describe('BarChart preset', () => {
     expect(chartSpy.mock.calls.at(-1)[0].colors).toEqual(['var(--application-chart-colour)']);
   });
 
-  it('requires labels for both axes', () => {
-    expect(() => render(
-      <ThemeProvider theme={createTheme()}><BarChart series={[]} xAxisLabel="Year" /></ThemeProvider>,
-    )).toThrow('BarChart requires xAxisLabel and yAxisLabel.');
+  // THEME-9: DESIGN.md #8a makes an axis title the caller's per-axis
+  // decision (categorical axes default to none) -- a hard "both required"
+  // throw made that default unachievable through this preset. Omitting a
+  // label now renders no title for that axis rather than crashing.
+  it('renders without a title on an axis whose label was omitted', () => {
+    render(
+      <ThemeProvider theme={createTheme()}><BarChart series={[{ data: [1] }]} xAxisLabel="Year" /></ThemeProvider>,
+    );
+    const props = chartSpy.mock.calls.at(-1)[0];
+    expect(props.xAxis[0].label).toBe('Year');
+    expect(props.yAxis[0].label).toBeUndefined();
+  });
+
+  it('renders with no title on either axis when both labels are omitted', () => {
+    render(
+      <ThemeProvider theme={createTheme()}><BarChart series={[{ data: [1] }]} /></ThemeProvider>,
+    );
+    const props = chartSpy.mock.calls.at(-1)[0];
+    expect(props.xAxis[0].label).toBeUndefined();
+    expect(props.yAxis[0].label).toBeUndefined();
   });
 });