@micha.bigler/ui-core-micha 2.29.2 → 2.31.0

package/src/components/charts/chartLabels.js

@@ -0,0 +1,36 @@
+// Short, granularity-aware x-axis tick labels.
+//
+// Not a style choice -- MUI X-Charts has a known, unfixed bug (mui-x#18768,
+// duplicate of #18399): when the measured space for a tick label gets
+// tight, its ellipsize() logic doesn't truncate the text, it collapses it
+// to an empty string (the <tspan> stays in the DOM with no content). It
+// only reproduces with long label text ("08/05, 10:00 AM"-style, ~16
+// characters) combined with this app's actual font metrics (DM Sans) --
+// short labels like "05.08." or "10:00" leave enough margin that the bug
+// never triggers. Same fix already proven in jg-ferien's ActivitySection.
+
+// `locale` defaults to "de-CH" only as a fallback for callers that don't
+// pass the app's active i18n language (found in review: an earlier version
+// hardcoded "de-CH" always, showing German month names to en/fr users).
+
+export function formatShortTime(date, locale = 'de-CH') {
+  // hour12 forced false regardless of locale -- an English 12-hour label
+  // ("10:00 AM") is exactly the longer style that triggered the original
+  // collapse bug; staying short is the point, not locale fidelity here.
+  return date.toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit', hour12: false });
+}
+
+export function formatShortDate(date, locale = 'de-CH') {
+  return date.toLocaleDateString(locale, { day: '2-digit', month: '2-digit' });
+}
+
+export function formatShortMonth(date, locale = 'de-CH') {
+  return date.toLocaleDateString(locale, { month: 'short', year: '2-digit' });
+}
+
+// "All" spans years -- day/month labels repeat (e.g. every "01.04." shows up
+// once per year) and read as meaningless noise; a bare year number is the
+// only granularity dense multi-year history can show cleanly.
+export function formatShortYear(date, locale = 'de-CH') {
+  return date.toLocaleDateString(locale, { year: 'numeric' });
+}

package/src/components/charts/palette.js

@@ -7,11 +7,14 @@ import { useTheme } from '@mui/material/styles';
 export function getNeutralChartPalette(theme) {
   const palette = theme.palette;
   const isDark = palette.mode === 'dark';
+  const dataSeries = palette.dataSeries?.categorical;
 
   return {
-    categorical: isDark
-      ? [palette.primary.light, palette.secondary.light, palette.info.light, palette.success.light, palette.warning.light]
-      : [palette.primary.main, palette.secondary.main, palette.info.main, palette.success.main, palette.warning.main],
+    categorical: Array.isArray(dataSeries) && dataSeries.length > 0
+      ? [...dataSeries]
+      : isDark
+        ? [palette.primary.light, palette.secondary.light, palette.info.light, palette.success.light, palette.warning.light]
+        : [palette.primary.main, palette.secondary.main, palette.info.main, palette.success.main, palette.warning.main],
     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],

package/src/components/charts/yearTickInterval.js

@@ -0,0 +1,7 @@
+/** Return one January tick for every calendar year represented in dates. */
+export function yearTickInterval(dates) {
+  const years = new Set(dates.map((date) => date.getFullYear()));
+  return [...years]
+    .sort((first, second) => first - second)
+    .map((year) => new Date(year, 0, 1));
+}

package/src/index.js

@@ -1,5 +1,14 @@
 // index.js (Entry Point deiner Library)
 
+// --- 0. Theme ---
+export {
+  createAppTheme,
+  assertThemeComplete,
+  calculateContrastRatio,
+  reportThemeAdoption,
+  THEME_COMPLETENESS_SURFACES,
+} from './theme';
+
 // --- 1. Auth Context (Essentiell für den Wrapper) ---
 export { AuthContext, AuthProvider } from './auth/AuthContext';
 export { UserMenu } from './auth/UserMenu';
@@ -46,6 +55,13 @@ export { BarChart } from './components/charts/BarChart';
 export { LineChart } from './components/charts/LineChart';
 export { TimeSeriesChart } from './components/charts/TimeSeriesChart';
 export { getNeutralChartPalette, useNeutralChartPalette } from './components/charts/palette';
+export {
+  formatShortTime,
+  formatShortDate,
+  formatShortMonth,
+  formatShortYear,
+} from './components/charts/chartLabels';
+export { yearTickInterval } from './components/charts/yearTickInterval';
 export {
   formatPercentage,
   formatCompact,

package/src/theme/createAppTheme.js

@@ -0,0 +1,212 @@
+import '@fontsource/dm-sans/400.css';
+import '@fontsource/dm-sans/500.css';
+import '@fontsource/dm-sans/600.css';
+
+import { createTheme, darken, getContrastRatio } from '@mui/material/styles';
+
+import {
+  BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS,
+  BASELINE_PALETTE,
+  BASELINE_STATIC,
+  MOTION,
+} from './tokens';
+
+function findFunction(value, path) {
+  if (typeof value === 'function') return path;
+  if (!value || typeof value !== 'object') return null;
+
+  for (const [key, child] of Object.entries(value)) {
+    const found = findFunction(child, `${path}.${key}`);
+    if (found) return found;
+  }
+  return null;
+}
+
+function validateStyleOverrides(components = {}) {
+  for (const [componentName, component] of Object.entries(components)) {
+    if (!component?.styleOverrides) continue;
+    const slot = findFunction(
+      component.styleOverrides,
+      `components.${componentName}.styleOverrides`,
+    );
+    if (slot) {
+      throw new TypeError(
+        `createAppTheme: ${slot} must be an object, not a function. ` +
+          'Use object styleOverrides and MUI variants for prop- or state-dependent styles.',
+      );
+    }
+  }
+}
+
+function clearsContrast(colour, surfaces) {
+  return surfaces.every((surface) => getContrastRatio(colour, surface) >= 3);
+}
+
+// Darkened until it clears 3:1 against BOTH '#FFFFFF' and background.default
+// -- the exact two surfaces assertThemeComplete's contrastFindings checks --
+// so deriving against background.paper alone (which need not be white for an
+// app that overrides it) could pass here and still fail there.
+function deriveFocusColour(primary, surfaces) {
+  let focus = primary;
+  for (let coefficient = 0.05; !clearsContrast(focus, surfaces); coefficient += 0.05) {
+    focus = darken(primary, Math.min(coefficient, 0.9));
+    if (coefficient >= 0.9) break;
+  }
+  return focus;
+}
+
+function createPaletteAwareComponents(palette) {
+  const stateTransition = `border-color ${MOTION.duration.fast}ms ${MOTION.easing.state}, color ${MOTION.duration.fast}ms ${MOTION.easing.state}, background-color ${MOTION.duration.fast}ms ${MOTION.easing.state}`;
+  const autofill = {
+    '&:-webkit-autofill': {
+      WebkitBoxShadow: `0 0 0 100px ${palette.background.paper} inset`,
+      WebkitTextFillColor: palette.ink.primary,
+      caretColor: palette.ink.primary,
+    },
+    '&:autofill': {
+      boxShadow: `0 0 0 100px ${palette.background.paper} inset`,
+      WebkitTextFillColor: palette.ink.primary,
+      caretColor: palette.ink.primary,
+    },
+  };
+  const alertStyles = Object.fromEntries(
+    ['success', 'warning', 'error', 'info'].map((status) => [
+      `standard${status[0].toUpperCase()}${status.slice(1)}`,
+      {
+        color: palette[status].text,
+        backgroundColor: palette[status].bg,
+        '& .MuiAlert-icon': { color: palette[status].text },
+      },
+    ]),
+  );
+
+  return {
+    MuiButton: {
+      styleOverrides: {
+        root: { transition: stateTransition },
+        outlined: {
+          borderColor: palette.controlBorder.main,
+          '&:hover': { borderColor: palette.controlBorder.hover },
+        },
+      },
+    },
+    MuiDivider: {
+      styleOverrides: { root: { borderColor: palette.divider } },
+    },
+    MuiCheckbox: {
+      styleOverrides: {
+        root: {
+          color: palette.controlBorder.main,
+          transition: stateTransition,
+          '&:hover': { color: palette.controlBorder.hover },
+          '&.Mui-checked': { color: palette.primary.main },
+          '&.MuiCheckbox-indeterminate': { color: palette.primary.main },
+          '&.Mui-error': { color: palette.controlBorder.error },
+        },
+      },
+    },
+    MuiPaper: {
+      styleOverrides: { root: { borderColor: palette.divider } },
+    },
+    MuiCard: {
+      styleOverrides: { root: { borderColor: palette.divider } },
+    },
+    MuiChip: {
+      styleOverrides: {
+        outlined: { borderColor: palette.controlBorder.main },
+      },
+    },
+    MuiOutlinedInput: {
+      styleOverrides: {
+        root: {
+          transition: stateTransition,
+          '& .MuiOutlinedInput-notchedOutline': {
+            borderColor: palette.controlBorder.main,
+          },
+          '&:hover .MuiOutlinedInput-notchedOutline': {
+            borderColor: palette.controlBorder.hover,
+          },
+          '&.Mui-focused .MuiOutlinedInput-notchedOutline': {
+            borderColor: palette.controlBorder.focus,
+            borderWidth: 2,
+          },
+          '&.Mui-error .MuiOutlinedInput-notchedOutline': {
+            borderColor: palette.controlBorder.error,
+          },
+        },
+        input: autofill,
+      },
+    },
+    MuiFilledInput: {
+      styleOverrides: { input: autofill },
+    },
+    MuiInput: {
+      styleOverrides: { input: autofill },
+    },
+    MuiAlert: {
+      styleOverrides: alertStyles,
+    },
+  };
+}
+
+/**
+ * Builds the shared application theme while leaving app identity in primary
+ * and fontFamily. Palette resolution happens before palette-aware component
+ * objects are created, so runtime app/site overrides cannot leave stale values.
+ */
+export function createAppTheme(appConfig = {}) {
+  if (!appConfig?.palette?.primary) {
+    throw new TypeError('createAppTheme: appConfig.palette.primary is required.');
+  }
+  validateStyleOverrides(appConfig.components);
+
+  const paletteTheme = createTheme(
+    { palette: appConfig.palette },
+    { palette: BASELINE_PALETTE },
+    { palette: appConfig.palette },
+  );
+  const finalPalette = paletteTheme.palette;
+  const computedPalette = {
+    controlBorder: {
+      ...finalPalette.controlBorder,
+      focus: deriveFocusColour(finalPalette.primary.main, [
+        '#FFFFFF',
+        finalPalette.background.default,
+      ]),
+    },
+  };
+  const resolvedPalette = { ...finalPalette, ...computedPalette };
+  const fontFamily = appConfig.typography?.fontFamily || BASELINE_STATIC.typography.fontFamily;
+
+  return createTheme(
+    {
+      ...BASELINE_STATIC,
+      typography: {
+        ...BASELINE_STATIC.typography,
+        fontFamily,
+      },
+      fontLoading: {
+        ...BASELINE_STATIC.fontLoading,
+        weights: [...BASELINE_STATIC.fontLoading.weights],
+      },
+      palette: resolvedPalette,
+      themeCompleteness: {
+        baseline: true,
+        exemptions: BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS.map((exemption) => ({
+          ...exemption,
+        })),
+      },
+    },
+    {
+      components: createPaletteAwareComponents(resolvedPalette),
+    },
+    appConfig,
+    {
+      palette: {
+        dataSeries: {
+          categorical: [...resolvedPalette.dataSeries.categorical],
+        },
+      },
+    },
+  );
+}

package/src/theme/index.js

@@ -0,0 +1,14 @@
+export { createAppTheme } from './createAppTheme';
+export {
+  assertThemeComplete,
+  calculateContrastRatio,
+  reportThemeAdoption,
+  THEME_COMPLETENESS_SURFACES,
+} from './themeCompleteness';
+export {
+  formatShortTime,
+  formatShortDate,
+  formatShortMonth,
+  formatShortYear,
+} from '../components/charts/chartLabels';
+export { yearTickInterval } from '../components/charts/yearTickInterval';

package/src/theme/themeCompleteness.js

@@ -0,0 +1,355 @@
+import { createTheme, getContrastRatio as getMuiContrastRatio } from '@mui/material/styles';
+
+import { STATUS_KEYS, TYPOGRAPHY_VARIANTS } from './tokens';
+
+const MUI_DEFAULT_THEME = createTheme();
+
+function getPath(value, path) {
+  return path.split('.').reduce((current, key) => current?.[key], value);
+}
+
+function sameValue(left, right) {
+  if (left === right) return true;
+  if (left === undefined || right === undefined) return false;
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+const pathSurface = (surface, path = surface) => ({
+  surface,
+  get: (theme) => getPath(theme, path),
+});
+
+const keyedSurface = (surface, get) => ({ surface, get });
+
+const STATUS_SURFACES = STATUS_KEYS.flatMap((status) =>
+  ['text', 'fill', 'fillText', 'bg'].map((token) =>
+    pathSurface(`palette.${status}.${token}`),
+  ),
+);
+
+const TYPOGRAPHY_SURFACES = TYPOGRAPHY_VARIANTS.flatMap((variant) =>
+  ['fontSize', 'fontWeight', 'lineHeight', 'letterSpacing'].map((token) =>
+    pathSurface(`typography.${variant}.${token}`),
+  ),
+);
+
+const componentPath = (component, path) =>
+  pathSurface(`components.${component}.${path}`);
+
+const componentKeyLeaf = (component, path, key, leaf) => keyedSurface(
+  `components.${component}.${path}.${key}.${leaf}`,
+  (theme) => getPath(theme, `components.${component}.${path}`)?.[key]?.[leaf],
+);
+
+const COMPONENT_SURFACES = [
+  keyedSurface(
+    'components.MuiCssBaseline.reduced-motion.transitionDuration',
+    (theme) => theme.components?.MuiCssBaseline?.styleOverrides
+      ?.['@media (prefers-reduced-motion: reduce)']
+      ?.['*, *::before, *::after']?.transitionDuration,
+  ),
+  componentPath('MuiButton', 'defaultProps.disableElevation'),
+  componentPath('MuiButton', 'styleOverrides.root.minHeight'),
+  componentPath('MuiButton', 'styleOverrides.root.borderRadius'),
+  componentPath('MuiButton', 'styleOverrides.root.textTransform'),
+  componentKeyLeaf('MuiButton', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minHeight'),
+  componentKeyLeaf('MuiButton', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minWidth'),
+  componentPath('MuiButton', 'styleOverrides.contained.boxShadow'),
+  componentPath('MuiButton', 'styleOverrides.outlined.borderColor'),
+  componentPath('MuiTableCell', 'styleOverrides.root.padding'),
+  componentPath('MuiIconButton', 'styleOverrides.root.minHeight'),
+  componentPath('MuiIconButton', 'styleOverrides.root.minWidth'),
+  componentKeyLeaf('MuiIconButton', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minHeight'),
+  componentKeyLeaf('MuiIconButton', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minWidth'),
+  componentPath('MuiDivider', 'styleOverrides.root.borderColor'),
+  componentPath('MuiTooltip', 'styleOverrides.tooltip.boxShadow'),
+  componentPath('MuiTooltip', 'styleOverrides.tooltip.transitionDuration'),
+  componentPath('MuiTooltip', 'defaultProps.slotProps.transition.timeout.enter'),
+  componentPath('MuiTooltip', 'defaultProps.slotProps.transition.timeout.exit'),
+  componentPath('MuiSelect', 'defaultProps.variant'),
+  componentPath('MuiSelect', 'styleOverrides.select.minHeight'),
+  componentKeyLeaf('MuiSelect', 'styleOverrides.select', '@media (any-pointer: coarse)', 'minHeight'),
+  componentPath('MuiCheckbox', 'styleOverrides.root.color'),
+  componentKeyLeaf('MuiCheckbox', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minHeight'),
+  componentKeyLeaf('MuiCheckbox', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minWidth'),
+  componentPath('MuiFormControlLabel', 'styleOverrides.root.minHeight'),
+  componentKeyLeaf('MuiFormControlLabel', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minHeight'),
+  componentKeyLeaf('MuiFormControlLabel', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minWidth'),
+  componentPath('MuiFormControlLabel', 'styleOverrides.label.fontSize'),
+  componentPath('MuiContainer', 'styleOverrides.root.paddingLeft'),
+  componentPath('MuiContainer', 'styleOverrides.root.paddingRight'),
+  componentKeyLeaf('MuiContainer', 'styleOverrides.root', '@media (min-width:1200px)', 'paddingLeft'),
+  componentKeyLeaf('MuiContainer', 'styleOverrides.root', '@media (min-width:1200px)', 'paddingRight'),
+  componentPath('MuiPaper', 'defaultProps.elevation'),
+  componentPath('MuiPaper', 'defaultProps.variant'),
+  componentPath('MuiPaper', 'styleOverrides.root.borderRadius'),
+  componentPath('MuiPaper', 'styleOverrides.root.boxShadow'),
+  componentPath('MuiCard', 'defaultProps.elevation'),
+  componentPath('MuiCard', 'defaultProps.variant'),
+  componentPath('MuiCard', 'styleOverrides.root.borderRadius'),
+  componentPath('MuiCard', 'styleOverrides.root.boxShadow'),
+  componentPath('MuiChip', 'styleOverrides.root.height'),
+  componentPath('MuiChip', 'styleOverrides.root.borderRadius'),
+  componentPath('MuiChip', 'styleOverrides.root.fontSize'),
+  keyedSurface(
+    'components.MuiChip.styleOverrides.root.coarse-hit-area.inset',
+    (theme) => theme.components?.MuiChip?.styleOverrides?.root
+      ?.['@media (any-pointer: coarse)']?.['&::after']?.inset,
+  ),
+  componentPath('MuiTextField', 'defaultProps.variant'),
+  componentPath('MuiTextField', 'styleOverrides.root.minHeight'),
+  componentKeyLeaf('MuiTextField', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minHeight'),
+  componentKeyLeaf('MuiTextField', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minWidth'),
+  componentPath('MuiOutlinedInput', 'styleOverrides.root.minHeight'),
+  componentPath('MuiOutlinedInput', 'styleOverrides.root.borderRadius'),
+  keyedSurface(
+    'components.MuiOutlinedInput.variants.non-multiline-height',
+    (theme) => theme.components?.MuiOutlinedInput?.variants
+      ?.find(({ props }) => props?.multiline === false)?.style?.height,
+  ),
+  componentKeyLeaf('MuiOutlinedInput', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minHeight'),
+  componentKeyLeaf('MuiOutlinedInput', 'styleOverrides.root', '@media (any-pointer: coarse)', 'minWidth'),
+  componentKeyLeaf('MuiOutlinedInput', 'styleOverrides.root', '& .MuiOutlinedInput-notchedOutline', 'borderColor'),
+  componentKeyLeaf('MuiOutlinedInput', 'styleOverrides.root', '&:hover .MuiOutlinedInput-notchedOutline', 'borderColor'),
+  componentKeyLeaf('MuiOutlinedInput', 'styleOverrides.root', '&.Mui-focused .MuiOutlinedInput-notchedOutline', 'borderColor'),
+  componentKeyLeaf('MuiOutlinedInput', 'styleOverrides.root', '&.Mui-error .MuiOutlinedInput-notchedOutline', 'borderColor'),
+  componentPath('MuiDialog', 'defaultProps.transitionDuration.enter'),
+  componentPath('MuiDialog', 'defaultProps.transitionDuration.exit'),
+  componentPath('MuiDialog', 'styleOverrides.paper.borderRadius'),
+  componentPath('MuiDialog', 'styleOverrides.paper.boxShadow'),
+  componentPath('MuiDrawer', 'styleOverrides.paper.boxShadow'),
+  componentPath('MuiMenu', 'styleOverrides.paper.boxShadow'),
+  ...['success', 'warning', 'error', 'info'].flatMap((status) => {
+    const slot = `standard${status[0].toUpperCase()}${status.slice(1)}`;
+    return [
+      componentPath('MuiAlert', `styleOverrides.${slot}.color`),
+      componentPath('MuiAlert', `styleOverrides.${slot}.backgroundColor`),
+      componentKeyLeaf('MuiAlert', `styleOverrides.${slot}`, '& .MuiAlert-icon', 'color'),
+    ];
+  }),
+  ...['MuiOutlinedInput', 'MuiFilledInput', 'MuiInput'].flatMap((component) => [
+    componentKeyLeaf(component, 'styleOverrides.input', '&:-webkit-autofill', 'WebkitBoxShadow'),
+    componentKeyLeaf(component, 'styleOverrides.input', '&:-webkit-autofill', 'WebkitTextFillColor'),
+    componentKeyLeaf(component, 'styleOverrides.input', '&:autofill', 'boxShadow'),
+    componentKeyLeaf(component, 'styleOverrides.input', '&:autofill', 'WebkitTextFillColor'),
+  ]),
+];
+
+/** The versioned surface inventory used by every adopting application. */
+export const THEME_COMPLETENESS_SURFACES = [
+  pathSurface('palette.primary.main'),
+  ...STATUS_SURFACES,
+  pathSurface('palette.ink.primary'),
+  pathSurface('palette.ink.secondary'),
+  pathSurface('palette.ink.muted'),
+  pathSurface('palette.background.default'),
+  pathSurface('palette.background.paper'),
+  pathSurface('palette.divider'),
+  pathSurface('palette.controlBorder.main'),
+  pathSurface('palette.controlBorder.hover'),
+  pathSurface('palette.controlBorder.focus'),
+  pathSurface('palette.controlBorder.error'),
+  pathSurface('palette.dataSeries.categorical'),
+  pathSurface('radius.control'),
+  pathSurface('radius.card'),
+  pathSurface('typography.fontFamily'),
+  ...TYPOGRAPHY_SURFACES,
+  pathSurface('shape.borderRadius'),
+  {
+    surface: 'spacing.unit',
+    get: (theme) => (typeof theme.spacing === 'function' ? theme.spacing(1) : undefined),
+  },
+  pathSurface('breakpoints.values'),
+  pathSurface('shadow.rest'),
+  pathSurface('shadow.overlay'),
+  pathSurface('motion.duration.fast'),
+  pathSurface('motion.duration.base'),
+  pathSurface('motion.duration.overlayEnter'),
+  pathSurface('motion.duration.overlayExit'),
+  pathSurface('motion.duration.chart'),
+  pathSurface('motion.easing.enter'),
+  pathSurface('motion.easing.exit'),
+  pathSurface('motion.easing.state'),
+  pathSurface('motion.reduced'),
+  pathSurface('fontLoading.family'),
+  pathSurface('fontLoading.weights'),
+  ...COMPONENT_SURFACES,
+];
+
+function parseColour(colour) {
+  if (typeof colour !== 'string') return null;
+  const value = colour.trim();
+  if (value.startsWith('#')) {
+    const hex = value.slice(1);
+    const expanded = hex.length === 3
+      ? hex.split('').map((part) => part + part).join('')
+      : hex;
+    if (!/^[\da-f]{6}([\da-f]{2})?$/i.test(expanded)) return null;
+    return {
+      r: parseInt(expanded.slice(0, 2), 16),
+      g: parseInt(expanded.slice(2, 4), 16),
+      b: parseInt(expanded.slice(4, 6), 16),
+      a: expanded.length === 8 ? parseInt(expanded.slice(6, 8), 16) / 255 : 1,
+    };
+  }
+
+  const match = value.match(/^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)(?:\s*,\s*([\d.]+))?\s*\)$/i);
+  if (!match) return null;
+  return {
+    r: Number(match[1]),
+    g: Number(match[2]),
+    b: Number(match[3]),
+    a: match[4] === undefined ? 1 : Number(match[4]),
+  };
+}
+
+function composite(foreground, background) {
+  const alpha = foreground.a + background.a * (1 - foreground.a);
+  if (alpha === 0) return { r: 0, g: 0, b: 0, a: 0 };
+  return {
+    r: (foreground.r * foreground.a + background.r * background.a * (1 - foreground.a)) / alpha,
+    g: (foreground.g * foreground.a + background.g * background.a * (1 - foreground.a)) / alpha,
+    b: (foreground.b * foreground.a + background.b * background.a * (1 - foreground.a)) / alpha,
+    a: alpha,
+  };
+}
+
+function luminance(colour) {
+  const channels = [colour.r, colour.g, colour.b].map((channel) => {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  });
+  return channels[0] * 0.2126 + channels[1] * 0.7152 + channels[2] * 0.0722;
+}
+
+/** Calculates WCAG contrast, including alpha compositing over the background. */
+export function calculateContrastRatio(foreground, background) {
+  const foregroundColour = parseColour(foreground);
+  const backgroundColour = parseColour(background);
+  if (!foregroundColour || !backgroundColour) {
+    try {
+      const ratio = getMuiContrastRatio(foreground, background);
+      return Number.isFinite(ratio) ? ratio : Number.NaN;
+    } catch {
+      return Number.NaN;
+    }
+  }
+
+  const opaqueBackground = backgroundColour.a < 1
+    ? composite(backgroundColour, { r: 255, g: 255, b: 255, a: 1 })
+    : backgroundColour;
+  const opaqueForeground = foregroundColour.a < 1
+    ? composite(foregroundColour, opaqueBackground)
+    : foregroundColour;
+  const light = Math.max(luminance(opaqueForeground), luminance(opaqueBackground));
+  const dark = Math.min(luminance(opaqueForeground), luminance(opaqueBackground));
+  return (light + 0.05) / (dark + 0.05);
+}
+
+function contrastFindings(theme) {
+  const findings = [];
+  for (const status of STATUS_KEYS) {
+    const tokens = theme.palette?.[status];
+    if (!tokens) continue;
+    const textRatio = calculateContrastRatio(tokens.text, tokens.bg);
+    if (!Number.isFinite(textRatio) || textRatio < 4.5) {
+      findings.push({
+        surface: `contrast.${status}.text-on-bg`,
+        reason: Number.isFinite(textRatio)
+          ? `Expected at least 4.5:1; received ${textRatio.toFixed(2)}:1.`
+          : 'Contrast could not be calculated from the declared colours.',
+      });
+    }
+    const fillRatio = calculateContrastRatio(tokens.fillText, tokens.fill);
+    if (!Number.isFinite(fillRatio) || fillRatio < 4.5) {
+      findings.push({
+        surface: `contrast.${status}.fillText-on-fill`,
+        reason: Number.isFinite(fillRatio)
+          ? `Expected at least 4.5:1; received ${fillRatio.toFixed(2)}:1.`
+          : 'Contrast could not be calculated from the declared colours.',
+      });
+    }
+  }
+
+  const backgrounds = {
+    white: '#FFFFFF',
+    page: theme.palette?.background?.default,
+  };
+  for (const state of ['main', 'hover', 'focus', 'error']) {
+    const colour = theme.palette?.controlBorder?.[state];
+    if (!colour) continue;
+    for (const [surface, background] of Object.entries(backgrounds)) {
+      const ratio = calculateContrastRatio(colour, background);
+      if (!Number.isFinite(ratio) || ratio < 3) {
+        findings.push({
+          surface: `contrast.controlBorder.${state}-on-${surface}`,
+          reason: Number.isFinite(ratio)
+            ? `Expected at least 3:1; received ${ratio.toFixed(2)}:1.`
+            : 'Contrast could not be calculated from the declared colours.',
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Returns completeness findings. Adopting applications make this a hard CI
+ * assertion in their own suite; non-adopters may call it for reporting only.
+ */
+export function assertThemeComplete(theme, { exemptions = [] } = {}) {
+  const declaredExemptions = [
+    ...(theme?.themeCompleteness?.exemptions || []),
+    ...exemptions,
+  ];
+  const validExemptions = new Set();
+  const findings = [];
+
+  for (const exemption of declaredExemptions) {
+    if (!exemption?.surface || !exemption?.reason?.trim()) {
+      findings.push({
+        surface: `exemption.${exemption?.surface || 'unknown'}`,
+        reason: 'A completeness exemption must name a surface and include a reason.',
+      });
+      continue;
+    }
+    validExemptions.add(exemption.surface);
+  }
+
+  for (const descriptor of THEME_COMPLETENESS_SURFACES) {
+    const value = descriptor.get(theme);
+    const defaultValue = descriptor.get(MUI_DEFAULT_THEME);
+    if ((value === undefined || sameValue(value, defaultValue)) && !validExemptions.has(descriptor.surface)) {
+      findings.push({
+        surface: descriptor.surface,
+        reason: value === undefined
+          ? 'The surface is not deliberately defined.'
+          : 'The surface still equals MUI\'s untouched default.',
+      });
+    }
+  }
+
+  findings.push(...contrastFindings(theme));
+  return { findings };
+}
+
+/** Reports adoption signals as numbers; it never changes completeness. */
+export function reportThemeAdoption(sources = []) {
+  const normalized = sources.map((entry, index) =>
+    typeof entry === 'string'
+      ? { path: `source-${index + 1}`, source: entry }
+      : { path: entry.path || `source-${index + 1}`, source: entry.source || '' },
+  );
+  const themeBypassPaths = normalized
+    .filter(({ source }) => /\bcreateTheme\s*\(/.test(source) && !/\bcreateAppTheme\s*\(/.test(source))
+    .map(({ path }) => path);
+  const inlineHexCount = normalized.reduce(
+    (count, { source }) => count + (source.match(/#[\da-f]{3,8}\b/gi)?.length || 0),
+    0,
+  );
+  return {
+    inlineHexCount,
+    themeBypassPathCount: themeBypassPaths.length,
+    themeBypassPaths,
+  };
+}