@micha.bigler/ui-core-micha 2.33.2 → 2.35.0

package/src/theme/themeCompleteness.js

@@ -1,6 +1,12 @@
 import { createTheme, getContrastRatio as getMuiContrastRatio } from '@mui/material/styles';
 
-import { STATUS_KEYS, TYPOGRAPHY_VARIANTS } from './tokens';
+import {
+  BASELINE_PALETTE,
+  BASELINE_STATIC,
+  STATUS_KEYS,
+  TYPOGRAPHY_VARIANTS,
+} from './tokens';
+import { KIT_COMPONENT_SX_REGISTRY } from './kitSxRegistry';
 
 const MUI_DEFAULT_THEME = createTheme();
 
@@ -366,6 +372,450 @@ export function assertThemeComplete(theme, { exemptions = [] } = {}) {
   return { findings };
 }
 
+const SAME_ROOT_STYLE_OVERRIDE_SLOTS = {
+  MuiAlert: ['standardSuccess', 'standardWarning', 'standardError', 'standardInfo'],
+  MuiButton: ['root', 'contained', 'outlined'],
+  MuiChip: ['root', 'outlined'],
+};
+
+// MUI's sx prop accepts aliases and CSS spacing shorthands that
+// styleOverrides' plain CSS-in-JS objects do not. Each known alias is
+// expanded to the canonical CSS properties it can affect so the
+// disjointness check compares effects, not raw key spellings; a property
+// outside this table expands to itself.
+const SPACING_SHORTHAND_LONGHANDS = {
+  bgcolor: ['backgroundColor'],
+  typography: [
+    'fontFamily',
+    'fontSize',
+    'fontStyle',
+    'fontWeight',
+    'letterSpacing',
+    'lineHeight',
+    'textTransform',
+  ],
+  p: ['paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft'],
+  padding: ['paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft'],
+  px: ['paddingLeft', 'paddingRight'],
+  paddingX: ['paddingLeft', 'paddingRight'],
+  py: ['paddingTop', 'paddingBottom'],
+  paddingY: ['paddingTop', 'paddingBottom'],
+  pt: ['paddingTop'],
+  pr: ['paddingRight'],
+  pb: ['paddingBottom'],
+  pl: ['paddingLeft'],
+  m: ['marginTop', 'marginRight', 'marginBottom', 'marginLeft'],
+  margin: ['marginTop', 'marginRight', 'marginBottom', 'marginLeft'],
+  mx: ['marginLeft', 'marginRight'],
+  marginX: ['marginLeft', 'marginRight'],
+  my: ['marginTop', 'marginBottom'],
+  marginY: ['marginTop', 'marginBottom'],
+  mt: ['marginTop'],
+  mr: ['marginRight'],
+  mb: ['marginBottom'],
+  ml: ['marginLeft'],
+};
+
+function expandShorthandProperty(property) {
+  return SPACING_SHORTHAND_LONGHANDS[property] || [property];
+}
+
+function styleOverrideKeys(componentConfig, slots = ['root']) {
+  const keys = new Set();
+  for (const slot of slots) {
+    const slotStyles = componentConfig?.styleOverrides?.[slot];
+    if (!slotStyles || typeof slotStyles !== 'object' || Array.isArray(slotStyles)) continue;
+    Object.keys(slotStyles).forEach((key) => expandShorthandProperty(key).forEach((longhand) => keys.add(longhand)));
+  }
+  return keys;
+}
+
+/**
+ * Reports top-level property collisions between registered kit sx objects and
+ * the baseline MUI component they target. Known sx aliases are compared by
+ * the CSS properties they affect, not by literal key name.
+ *
+ * This is deliberately a lower bound on shadowing: unknown normalisation gaps
+ * remain. A clean result proves only that the registered top-level key sets
+ * are disjoint; it is not proof that no component can shadow the baseline.
+ */
+export function assertKitSxDisjoint(
+  theme,
+  { registry = KIT_COMPONENT_SX_REGISTRY, 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 entry of registry) {
+    const baselineKeys = styleOverrideKeys(
+      theme?.components?.[entry.muiComponent],
+      entry.slots || SAME_ROOT_STYLE_OVERRIDE_SLOTS[entry.muiComponent],
+    );
+    for (const property of Object.keys(entry.sx || {})) {
+      const surface = `${entry.component}.${entry.muiComponent}.${property}`;
+      const collides = expandShorthandProperty(property).some((longhand) => baselineKeys.has(longhand));
+      if (collides && !validExemptions.has(surface)) {
+        findings.push({
+          surface,
+          reason: `${entry.component} sx shadows ${entry.muiComponent} styleOverrides property "${property}".`,
+        });
+      }
+    }
+  }
+
+  return { findings };
+}
+
+const BASELINE_STYLED_MUI_COMPONENTS = [
+  'Alert',
+  'BottomNavigation',
+  'BottomNavigationAction',
+  'Button',
+  'Card',
+  'Checkbox',
+  'Chip',
+  'Container',
+  'CssBaseline',
+  'Dialog',
+  'Divider',
+  'Drawer',
+  'FilledInput',
+  'FormControlLabel',
+  'IconButton',
+  'Input',
+  'Menu',
+  'OutlinedInput',
+  'Paper',
+  'Select',
+  'TableCell',
+  'TextField',
+  'Tooltip',
+];
+
+function jsxOpeningTag(source, start) {
+  let braces = 0;
+  let quote = null;
+  for (let index = start; index < source.length; index += 1) {
+    const character = source[index];
+    if (quote) {
+      if (character === quote && source[index - 1] !== '\\') quote = null;
+      continue;
+    }
+    if (character === '"' || character === "'" || character === '`') {
+      quote = character;
+    } else if (character === '{') {
+      braces += 1;
+    } else if (character === '}') {
+      braces = Math.max(0, braces - 1);
+    } else if (character === '>' && braces === 0) {
+      return source.slice(start, index + 1);
+    }
+  }
+  return source.slice(start);
+}
+
+function topLevelSxValue(tag) {
+  let braces = 0;
+  let quote = null;
+  for (let index = 0; index < tag.length; index += 1) {
+    const character = tag[index];
+    if (quote) {
+      if (character === quote && tag[index - 1] !== '\\') quote = null;
+      continue;
+    }
+    if (character === '"' || character === "'" || character === '`') {
+      quote = character;
+      continue;
+    }
+    if (braces === 0 && (index === 0 || /\s/.test(tag[index - 1]))) {
+      const attribute = tag.slice(index).match(/^sx\b\s*=\s*/)?.[0];
+      if (attribute) return tag.slice(index + attribute.length);
+    }
+    if (character === '{') braces += 1;
+    if (character === '}') braces = Math.max(0, braces - 1);
+  }
+  return '';
+}
+
+/**
+ * Reports baseline-styled MUI tags that bypass the exported-object convention.
+ * Like assertKitSxDisjoint, this is a documented lower bound: conditional,
+ * array, callback, and otherwise nested sx expressions are not inspected.
+ */
+export function reportKitSxBypasses(sources = [], { registry } = {}) {
+  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 findings = [];
+  const registeredTargets = registry
+    ? registry.reduce((targets, { exportName, muiComponent }) => {
+      if (!exportName || !muiComponent) return targets;
+      if (!targets.has(exportName)) targets.set(exportName, new Set());
+      targets.get(exportName).add(muiComponent);
+      return targets;
+    }, new Map())
+    : null;
+  const componentPattern = BASELINE_STYLED_MUI_COMPONENTS.join('|');
+  const tagPattern = new RegExp(`<(${componentPattern})\\b`, 'g');
+
+  for (const { path, source } of normalized) {
+    const exportedObjects = new Set(
+      [...source.matchAll(/\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*\{/g)]
+        .map((match) => match[1]),
+    );
+
+    for (const match of source.matchAll(tagPattern)) {
+      const tag = jsxOpeningTag(source, match.index);
+      const sxValue = topLevelSxValue(tag);
+      const inline = /^\{\s*\{/.test(sxValue);
+      const identifier = sxValue.match(/^\{\s*([A-Za-z_$][\w$]*)\s*\}/)?.[1];
+      const exported = identifier && exportedObjects.has(identifier);
+      const muiComponent = `Mui${match[1]}`;
+      const unregistered = exported
+        && registeredTargets
+        && !registeredTargets.get(identifier)?.has(muiComponent);
+      if (!inline && (!identifier || (exported && !unregistered))) continue;
+
+      const line = source.slice(0, match.index).split(/\r?\n/).length;
+      findings.push({
+        surface: `${path}:${line}.Mui${match[1]}.sx`,
+        reason: inline
+          ? `${match[1]} uses an inline sx object instead of a top-level exported object.`
+          : unregistered
+            ? `${match[1]} uses exported sx object "${identifier}" without a ${muiComponent} registry entry.`
+            : `${match[1]} uses non-exported sx object "${identifier}".`,
+      });
+    }
+  }
+
+  return { findings };
+}
+
+const BASIC_CSS_COLOUR_NAMES = new Set([
+  'aqua',
+  'black',
+  'blue',
+  'fuchsia',
+  'gray',
+  'green',
+  'grey',
+  'lime',
+  'maroon',
+  'navy',
+  'olive',
+  'purple',
+  'red',
+  'silver',
+  'teal',
+  'white',
+  'yellow',
+]);
+
+const MUI_DEFAULT_NUMERIC_RAMP_NAMES = new Set([
+  'amber',
+  'blue',
+  'bluegrey',
+  'brown',
+  'cyan',
+  'deeporange',
+  'deeppurple',
+  'green',
+  'grey',
+  'indigo',
+  'lightblue',
+  'lightgreen',
+  'lime',
+  'orange',
+  'pink',
+  'purple',
+  'red',
+  'teal',
+  'yellow',
+]);
+
+const HEX_COLOUR_PATTERN = /#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})(?![\da-f])/gi;
+const RGB_COLOUR_PATTERN = /rgba?\(\s*[\d.]+\s*,\s*[\d.]+\s*,\s*[\d.]+(?:\s*,\s*[\d.]+)?\s*\)/gi;
+const NAMED_COLOUR_PATTERN = new RegExp(
+  `\\b(?:${[...BASIC_CSS_COLOUR_NAMES].join('|')})\\b`,
+  'gi',
+);
+const COLOUR_PROPERTY_PATTERN = /\b(?:background(?:Color)?|bgcolor|border(?:Top|Right|Bottom|Left)?(?:Color)?|boxShadow|caretColor|color|fill|fillStyle|outline(?:Color)?|stroke|strokeStyle|textShadow|WebkitTextFillColor)\s*(?::|=)\s*$/;
+
+function colourKey(value) {
+  const colour = parseColour(value);
+  return colour ? `${colour.r},${colour.g},${colour.b},${colour.a}` : null;
+}
+
+function collectBaselineColourKeys(...roots) {
+  const keys = new Set();
+  const visit = (value) => {
+    if (typeof value === 'string') {
+      for (const match of value.matchAll(HEX_COLOUR_PATTERN)) {
+        const key = colourKey(match[0]);
+        if (key) keys.add(key);
+      }
+      for (const match of value.matchAll(RGB_COLOUR_PATTERN)) {
+        const key = colourKey(match[0]);
+        if (key) keys.add(key);
+      }
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach(visit);
+      return;
+    }
+    if (value && typeof value === 'object') Object.values(value).forEach(visit);
+  };
+  roots.forEach(visit);
+  return keys;
+}
+
+function maskComments(source) {
+  const characters = [...source];
+  let quote = null;
+  for (let index = 0; index < characters.length; index += 1) {
+    const character = characters[index];
+    if (quote) {
+      if (character === quote && characters[index - 1] !== '\\') quote = null;
+      continue;
+    }
+    if (character === '"' || character === "'" || character === '`') {
+      quote = character;
+      continue;
+    }
+    if (character === '/' && characters[index + 1] === '/') {
+      for (; index < characters.length && characters[index] !== '\n'; index += 1) {
+        characters[index] = ' ';
+      }
+      index -= 1;
+    } else if (character === '/' && characters[index + 1] === '*') {
+      characters[index] = ' ';
+      characters[index + 1] = ' ';
+      index += 2;
+      while (index < characters.length
+        && !(characters[index] === '*' && characters[index + 1] === '/')) {
+        if (characters[index] !== '\n' && characters[index] !== '\r') characters[index] = ' ';
+        index += 1;
+      }
+      if (index < characters.length) {
+        characters[index] = ' ';
+        characters[index + 1] = ' ';
+        index += 1;
+      }
+    }
+  }
+  return characters.join('');
+}
+
+function maskQrPrintDocument(source, path) {
+  if (!path.replaceAll('\\', '/').endsWith('/QrSignupManager.jsx')) return source;
+  const call = /\bprintWindow\.document\.write\s*\(\s*`/g.exec(source);
+  if (!call) return source;
+  const start = call.index + call[0].lastIndexOf('`');
+  let end = start + 1;
+  while (end < source.length) {
+    if (source[end] === '`' && source[end - 1] !== '\\') break;
+    end += 1;
+  }
+  if (end >= source.length) return source;
+
+  // The generated print document is standalone HTML rendered outside the
+  // React tree, where no application theme is available. Mask the region as
+  // one unit instead of accumulating permanent per-colour exemptions.
+  return source.slice(0, start)
+    + source.slice(start, end + 1).replace(/[^\r\n]/g, ' ')
+    + source.slice(end + 1);
+}
+
+function normalizedSources(sources) {
+  return sources.map((entry, index) =>
+    typeof entry === 'string'
+      ? { path: `source-${index + 1}`, source: entry }
+      : { path: entry.path || `source-${index + 1}`, source: entry.source || '' },
+  );
+}
+
+/**
+ * Reports colour literals in component source that do not come from the
+ * baseline palette, plus report-only uses of MUI's untouched numeric ramps.
+ */
+export function reportOffPaletteColours(
+  sources = [],
+  { palette = BASELINE_PALETTE, baselineStatic = BASELINE_STATIC } = {},
+) {
+  const allowedColours = collectBaselineColourKeys(palette, baselineStatic);
+  const findings = [];
+  const stringPattern = /(["'`])((?:\\.|(?!\1)[\s\S])*)\1/g;
+
+  for (const { path, source } of normalizedSources(sources)) {
+    const normalizedPath = path.replaceAll('\\', '/');
+    if (/(^|\/)src\/theme\//.test(normalizedPath)) continue;
+    const scanSource = maskComments(maskQrPrintDocument(source, normalizedPath));
+
+    for (const match of scanSource.matchAll(stringPattern)) {
+      const value = match[2].trim();
+      const line = source.slice(0, match.index).split(/\r?\n/).length;
+      const surface = `${path}:${line}.colour`;
+
+      for (const hex of value.matchAll(HEX_COLOUR_PATTERN)) {
+        if (!allowedColours.has(colourKey(hex[0]))) {
+          findings.push({
+            surface,
+            reason: `Off-palette hex colour "${hex[0]}" is not derived from the baseline palette.`,
+          });
+        }
+      }
+
+      for (const rgb of value.matchAll(RGB_COLOUR_PATTERN)) {
+        if (!allowedColours.has(colourKey(rgb[0]))) {
+          findings.push({
+            surface,
+            reason: `Off-palette rgb colour "${rgb[0]}" is not derived from the baseline palette.`,
+          });
+        }
+      }
+
+      const before = scanSource.slice(Math.max(0, match.index - 40), match.index);
+      const isColourProperty = COLOUR_PROPERTY_PATTERN.test(before);
+      const numericRamp = value.match(/^([a-z]+)\.(\d+)$/i);
+      if (isColourProperty && !numericRamp) {
+        for (const namedColour of value.matchAll(NAMED_COLOUR_PATTERN)) {
+          findings.push({
+            surface,
+            reason: `Named CSS colour "${namedColour[0]}" bypasses the baseline palette.`,
+          });
+        }
+      }
+
+      if (numericRamp && MUI_DEFAULT_NUMERIC_RAMP_NAMES.has(numericRamp[1].toLowerCase())) {
+        findings.push({
+          surface,
+          reason: `Report only: "${value}" uses MUI's untouched numeric palette ramp, not a baseline token.`,
+        });
+      }
+    }
+  }
+
+  return { findings };
+}
+
 /** Reports adoption signals as numbers; it never changes completeness. */
 export function reportThemeAdoption(sources = []) {
   const normalized = sources.map((entry, index) =>

package/tests/ChartFrame.test.jsx

@@ -154,6 +154,11 @@ describe('ChartFrame', () => {
 
     fireEvent.click(screen.getByRole('button', { name: 'Export PNG' }));
     await vi.waitFor(() => expect(chartExport.exportChartPng).toHaveBeenCalledOnce());
+    expect(chartExport.exportChartPng).toHaveBeenCalledWith(
+      expect.any(HTMLElement),
+      'chart.png',
+      '#fff',
+    );
     await vi.waitFor(() => expect(onExportPng).toHaveBeenCalledOnce());
   });