@micha.bigler/ui-core-micha 2.40.0 → 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

@@ -50,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 {

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/ScatterChart.test.jsx

@@ -0,0 +1,234 @@
+// @vitest-environment jsdom
+import React from 'react';
+import i18next from 'i18next';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render } from '@testing-library/react';
+import { I18nextProvider } from 'react-i18next';
+import { ThemeProvider } from '@mui/material/styles';
+
+const scatterSpy = vi.hoisted(() => vi.fn(({ children }) => <div data-testid="mui-scatter">{children}</div>));
+vi.mock('@mui/x-charts/ScatterChart', () => ({ ScatterChart: scatterSpy }));
+vi.mock('@mui/x-charts/hooks', () => ({
+  useXScale: () => (v) => v * 10,
+  useYScale: () => (v) => 100 - v * 10,
+}));
+
+import {
+  ScatterChart,
+  ScatterReferenceCurve,
+  ScatterReferenceLine,
+  scaleBubbleRadius,
+} from '../src/components/charts/ScatterChart';
+import { createAppTheme } from '../src/theme/createAppTheme';
+
+const theme = createAppTheme({ palette: { primary: { main: '#3D5A99' } } });
+const i18n = i18next.createInstance();
+i18n.init({ lng: 'en', resources: { en: { translation: {} } }, interpolation: { escapeValue: false } });
+
+function withProviders(children) {
+  return React.createElement(
+    ThemeProvider,
+    { theme },
+    React.createElement(I18nextProvider, { i18n }, children),
+  );
+}
+
+function renderScatter(props = {}) {
+  return render(withProviders(
+    React.createElement(ScatterChart, {
+      series: [{ id: 's', data: [{ x: 1, y: 1 }] }],
+      ...props,
+    }),
+  ));
+}
+
+// THEME-10 -- the formula the access-gap panel already hand-rolls
+// (`max(3, 10*sqrt(pop/maxPop))`), pinned as a pure function.
+describe('scaleBubbleRadius', () => {
+  it('matches the access-panel formula across the domain', () => {
+    expect(scaleBubbleRadius(0, 100)).toBe(3);
+    expect(scaleBubbleRadius(100, 100)).toBe(10);
+    expect(scaleBubbleRadius(25, 100)).toBeCloseTo(5, 5);
+  });
+
+  it('floors at the minimum radius for a degenerate or non-finite input', () => {
+    expect(scaleBubbleRadius(5, 0)).toBe(3);
+    expect(scaleBubbleRadius(NaN, 100)).toBe(3);
+    expect(scaleBubbleRadius(5, NaN)).toBe(3);
+  });
+});
+
+describe('ScatterChart mark count and colour default (THEME-10)', () => {
+  afterEach(() => { cleanup(); vi.clearAllMocks(); });
+
+  // The failure mode nobody sees: a scatter that silently drops points.
+  it('renders every supplied point, none dropped', () => {
+    renderScatter({ series: [{ id: 's', data: [{ x: 1, y: 1 }, { x: 2, y: 2 }, { x: 3, y: 3 }] }] });
+    expect(scatterSpy.mock.calls.at(-1)[0].series[0].data).toHaveLength(3);
+  });
+
+  it('defaults a single undifferentiated series to the neutral role colour, not a series hue', () => {
+    renderScatter();
+    expect(scatterSpy.mock.calls.at(-1)[0].colors).toEqual([theme.palette.text.secondary]);
+  });
+
+  it('uses the categorical palette, not the neutral tone, once a caller supplies multiple series', () => {
+    renderScatter({
+      series: [
+        { id: 'a', data: [{ x: 1, y: 1 }] },
+        { id: 'b', data: [{ x: 2, y: 2 }] },
+      ],
+    });
+    const { colors } = scatterSpy.mock.calls.at(-1)[0];
+    expect(colors).not.toEqual([theme.palette.text.secondary]);
+    expect(colors.length).toBeGreaterThan(1);
+  });
+
+  it('lets a caller override the palette explicitly (e.g. a family/role register)', () => {
+    renderScatter({ palette: ['#ABCDEF'] });
+    expect(scatterSpy.mock.calls.at(-1)[0].colors).toEqual(['#ABCDEF']);
+  });
+
+  // reviewer/ui_reviewer U3: a single series that sets its OWN colour is not "undifferentiated"
+  // -- the neutral default only applies when nothing else specifies a colour. This pins that
+  // ScatterChart itself never strips or overrides a series' own `.color` (MUI's own resolution
+  // of series.color vs. the colors fallback array is MUI's own contract, out of scope here --
+  // same boundary BarChart.test.jsx already draws for the identical `colors={palette ||
+  // neutralPalette.categorical}` pattern).
+  it('leaves a single series\' own explicit colour untouched and does not treat it as neutral', () => {
+    renderScatter({ series: [{ id: 's', color: '#123456', data: [{ x: 1, y: 1 }] }] });
+    const props = scatterSpy.mock.calls.at(-1)[0];
+    expect(props.series[0].color).toBe('#123456');
+    expect(props.colors).not.toEqual([theme.palette.text.secondary]);
+  });
+});
+
+describe('ScatterChart bubble z-order (THEME-10)', () => {
+  afterEach(() => { cleanup(); vi.clearAllMocks(); });
+
+  it('sorts each series largest-first when sizeAccessor is set, so a small bubble is never hidden under a large one', () => {
+    renderScatter({
+      sizeAccessor: (p) => p.pop,
+      series: [{ id: 's', data: [{ x: 1, y: 1, pop: 10 }, { x: 2, y: 2, pop: 500 }, { x: 3, y: 3, pop: 100 }] }],
+    });
+    const data = scatterSpy.mock.calls.at(-1)[0].series[0].data;
+    expect(data.map((p) => p.pop)).toEqual([500, 100, 10]);
+  });
+
+  it('leaves point order untouched outside bubble mode', () => {
+    const original = [{ x: 1, y: 1 }, { x: 2, y: 2 }];
+    renderScatter({ series: [{ id: 's', data: original }] });
+    expect(scatterSpy.mock.calls.at(-1)[0].series[0].data).toEqual(original);
+  });
+});
+
+describe('ScatterChart per-point marker style (THEME-10)', () => {
+  afterEach(() => { cleanup(); vi.clearAllMocks(); });
+
+  it('renders a hollow marker (fill: none) only for the point getPointStyle marks hollow', () => {
+    renderScatter({
+      getPointStyle: (p) => (p.isStatusQuo ? { hollow: true } : {}),
+      series: [{ id: 's', data: [{ x: 1, y: 1, isStatusQuo: true }, { x: 2, y: 2, isStatusQuo: false }] }],
+    });
+    const Marker = scatterSpy.mock.calls.at(-1)[0].slots.marker;
+    const markerProps = { seriesId: 's', color: '#111', x: 0, y: 0, isHighlighted: false, isFaded: false, size: 5 };
+
+    const hollow = render(React.createElement(Marker, { ...markerProps, dataIndex: 0 }));
+    const filled = render(React.createElement(Marker, { ...markerProps, dataIndex: 1 }));
+
+    expect(hollow.container.querySelector('circle').getAttribute('fill')).toBe('none');
+    expect(filled.container.querySelector('circle').getAttribute('fill')).toBe('#111');
+  });
+
+  it('sizes a bubble marker from sizeAccessor via scaleBubbleRadius, resolved against the POST-sort index', () => {
+    renderScatter({
+      sizeAccessor: (p) => p.pop,
+      series: [{ id: 's', data: [{ x: 1, y: 1, pop: 0 }, { x: 2, y: 2, pop: 100 }] }],
+    });
+    const Marker = scatterSpy.mock.calls.at(-1)[0].slots.marker;
+    const markerProps = { seriesId: 's', color: '#111', x: 0, y: 0, isHighlighted: false, isFaded: false, size: 5 };
+
+    // Data was re-sorted largest-first: index 0 is now pop:100, index 1 is pop:0.
+    const big = render(React.createElement(Marker, { ...markerProps, dataIndex: 0 }));
+    const small = render(React.createElement(Marker, { ...markerProps, dataIndex: 1 }));
+
+    expect(Number(big.container.querySelector('circle').getAttribute('r'))).toBeCloseTo(10, 5);
+    expect(Number(small.container.querySelector('circle').getAttribute('r'))).toBe(3);
+  });
+
+  // Live-render caught regression: bubble sizing must share ONE max across every series (a
+  // single comparable scale, matching the access-gap panel's own
+  // `maxPop = Math.max(1, ...points.map(p => p.population))` over ALL points 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.
+  it('sizes bubbles against ONE chart-wide max across all series, not a max per series', () => {
+    renderScatter({
+      sizeAccessor: (p) => p.pop,
+      series: [
+        { id: 'small-series', data: [{ x: 1, y: 1, pop: 100 }] },
+        { id: 'big-series', data: [{ x: 2, y: 2, pop: 1000 }] },
+      ],
+    });
+    const props = scatterSpy.mock.calls.at(-1)[0];
+    const Marker = props.slots.marker;
+    const markerProps = { color: '#111', x: 0, y: 0, isHighlighted: false, isFaded: false, size: 5 };
+
+    // If sized per-series, "small-series"'s own only point (pop:100) would be its own series
+    // max and render at full radius (10) -- wrongly implying it's as large as big-series's point.
+    const smallSeriesPoint = render(React.createElement(Marker, { ...markerProps, seriesId: 'small-series', dataIndex: 0 }));
+    const bigSeriesPoint = render(React.createElement(Marker, { ...markerProps, seriesId: 'big-series', dataIndex: 0 }));
+
+    const smallR = Number(smallSeriesPoint.container.querySelector('circle').getAttribute('r'));
+    const bigR = Number(bigSeriesPoint.container.querySelector('circle').getAttribute('r'));
+    expect(bigR).toBeCloseTo(10, 5);
+    expect(smallR).toBeCloseTo(10 * Math.sqrt(100 / 1000), 5);
+    expect(smallR).toBeLessThan(bigR);
+  });
+
+  it('renders a square/diamond shape when getPointStyle requests one', () => {
+    renderScatter({
+      getPointStyle: (p) => ({ shape: p.shape }),
+      series: [{ id: 's', data: [{ x: 1, y: 1, shape: 'square' }, { x: 2, y: 2, shape: 'diamond' }] }],
+    });
+    const Marker = scatterSpy.mock.calls.at(-1)[0].slots.marker;
+    const markerProps = { seriesId: 's', color: '#111', x: 0, y: 0, isHighlighted: false, isFaded: false, size: 5 };
+
+    const square = render(React.createElement(Marker, { ...markerProps, dataIndex: 0 }));
+    const diamond = render(React.createElement(Marker, { ...markerProps, dataIndex: 1 }));
+
+    expect(square.container.querySelector('rect')).not.toBeNull();
+    expect(diamond.container.querySelector('polygon')).not.toBeNull();
+  });
+});
+
+describe('ScatterReferenceCurve / ScatterReferenceLine (THEME-10)', () => {
+  it('draws a path through the curve points using the chart\'s own live scale', () => {
+    const { container } = render(React.createElement(ScatterReferenceCurve, {
+      points: [{ x: 0, y: 0 }, { x: 1, y: 1 }],
+      color: '#222',
+    }));
+    expect(container.querySelector('path').getAttribute('d')).toBe('M0,100 L10,90');
+  });
+
+  it('draws a labelled reference line at the given label position', () => {
+    const { container } = render(React.createElement(ScatterReferenceLine, {
+      from: { x: 0, y: 0 },
+      to: { x: 1, y: 1 },
+      label: 'No gap',
+      labelAt: { x: 0.9, y: 0.9 },
+      color: '#222',
+    }));
+    expect(container.querySelector('line')).not.toBeNull();
+    expect(container.textContent).toBe('No gap');
+  });
+
+  it('draws an unlabelled reference line when no label is given', () => {
+    const { container } = render(React.createElement(ScatterReferenceLine, {
+      from: { x: 0, y: 0 },
+      to: { x: 1, y: 1 },
+      color: '#222',
+    }));
+    expect(container.querySelector('line')).not.toBeNull();
+    expect(container.querySelector('text')).toBeNull();
+  });
+});