@micha.bigler/ui-core-micha 2.40.0 → 2.41.1

package/package.json

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

package/src/auth/apiClient.jsx

@@ -32,16 +32,36 @@ const CONSUMER_PUBLIC_PATHS = new Set();
  * Register an additional public path so a 401 on that route does not auto-redirect
  * to `/login`. Typical use: a public landing on `/` in an otherwise authenticated app.
  *
+ * Accepts a `string` (matched like the builtins: exact for "/", prefix otherwise) or
+ * a `RegExp` (AUTH-5) for consumers whose public area includes a dynamic segment —
+ * e.g. `/<slug>`, `/<slug>/team` — that no finite set of string prefixes can describe.
+ *
+ * A `RegExp` is tested via `.test()` against `window.location.pathname` ONLY — never
+ * against the query string or fragment. Anchor it (`^…$`): this library does not add
+ * anchors for you, and an unanchored pattern like `/team` also matches `/admin/team`,
+ * silently suppressing the redirect somewhere it's still needed. That failure is
+ * invisible until someone opens the over-matched page anonymously and lands on a
+ * blank error instead of `/login` — so test the non-matching direction too, not just
+ * the intended match.
+ *
  * MUST be called before the AuthProvider mounts (i.e. before `ReactDOM.render`).
  * Calling it later won't help the bootstrap probe which fires on AuthProvider mount.
  */
 export function addPublicPath(path) {
   if (typeof path === "string" && path) {
     CONSUMER_PUBLIC_PATHS.add(path);
+  } else if (path instanceof RegExp) {
+    CONSUMER_PUBLIC_PATHS.add(path);
   }
 }
 
-/** Remove a consumer-added public path. Library-internal paths are protected. */
+/**
+ * Remove a consumer-added public path. Library-internal paths are protected.
+ *
+ * For a `RegExp` entry, removal is by object identity (`Set.delete` uses SameValueZero
+ * equality) — pass the exact same `RegExp` instance `addPublicPath` was given, not a
+ * new literal that merely looks the same. Two `/^\/team$/` literals are not equal.
+ */
 export function removePublicPath(path) {
   CONSUMER_PUBLIC_PATHS.delete(path);
 }
@@ -50,10 +70,19 @@ function isPublicSitePath(pathname) {
   return pathname === "/sites" || pathname.startsWith("/sites/");
 }
 
-// Match rule: an entry of exactly "/" requires strict equality (avoids matching
-// every path with startsWith). Other entries keep the looser prefix match so
-// dynamic routes like /invite/:uid/:token still work.
+// Match rule: a RegExp entry is tested against pathname only (AUTH-5). A string entry
+// of exactly "/" requires strict equality (avoids matching every path with
+// startsWith); other string entries keep the looser prefix match so dynamic routes
+// like /invite/:uid/:token still work.
 function matchesPublicPath(pathname, entry) {
+  if (entry instanceof RegExp) {
+    // `g`/`y` flags make `.test()` stateful (`lastIndex` advances on match), which would
+    // make the same pathname alternate matched/unmatched across calls to this
+    // long-lived, module-scoped RegExp — a redirect that only fires every other time.
+    // Reset before every test so a consumer's flags can't leak state across calls.
+    entry.lastIndex = 0;
+    return entry.test(pathname);
+  }
   if (entry === "/") return pathname === "/";
   return pathname.startsWith(entry);
 }

package/src/components/charts/BarChart.jsx

@@ -12,6 +12,7 @@ import {
   withAxisDefaults,
   withChartSlotDefaults,
   withGridDefaults,
+  withMarginDefaults,
 } from './chartDefaults';
 
 /**
@@ -77,7 +78,7 @@ export function BarChart({
         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

@@ -15,6 +15,7 @@ import {
   withAxisDefaults,
   withChartSlotDefaults,
   withGridDefaults,
+  withMarginDefaults,
 } from './chartDefaults';
 
 // Fixes MUI's hollow `background.paper`-filled marker (MarkElement.js's own
@@ -100,7 +101,7 @@ export function LineChart({
         colors={palette || neutralPalette.categorical}
         grid={withGridDefaults(grid)}
         hideLegend={hideLegend}
-        margin={rotatedTickSpace.margin}
+        margin={withMarginDefaults(rotatedTickSpace.margin)}
         slots={{ mark: FilledMarkElement, ...slots }}
         slotProps={withChartSlotDefaults(slotProps, legendPosition)}
       />

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,