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

package/src/theme/themeCompleteness.js

@@ -1,6 +1,11 @@
 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();
@@ -373,18 +378,28 @@ const SAME_ROOT_STYLE_OVERRIDE_SLOTS = {
   MuiChip: ['root', 'outlined'],
 };
 
-// MUI's sx prop accepts CSS spacing shorthands (`py`, `px`, `pt`, ...) that
-// styleOverrides' plain CSS-in-JS objects do not -- a baseline `padding`
-// default and a component's own `sx={{ py: 1 }}` collide on the vertical
-// axis even though the two key strings never match literally. Each key is
-// expanded to the canonical longhand properties it can affect so the
-// disjointness check compares axes, not raw key spellings; a property
+// 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'],
@@ -392,7 +407,9 @@ const SPACING_SHORTHAND_LONGHANDS = {
   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'],
@@ -415,14 +432,12 @@ function styleOverrideKeys(componentConfig, slots = ['root']) {
 
 /**
  * Reports top-level property collisions between registered kit sx objects and
- * the baseline MUI component they target. Spacing shorthands (`py`/`px`/...)
- * are compared by the longhand axis they affect, not by literal key name --
- * see `SPACING_SHORTHAND_LONGHANDS`.
+ * 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: conditional sx, nested sx,
- * callback results, and nested selector properties are not inspected. A clean
- * result therefore proves only that the registered top-level key sets are
- * disjoint; it is not proof that no component can shadow the baseline.
+ * 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,
@@ -593,6 +608,214 @@ export function reportKitSxBypasses(sources = [], { registry } = {}) {
   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());
   });
 

package/tests/themeCompleteness.test.js

@@ -10,15 +10,17 @@ import {
   calculateContrastRatio,
   createAppTheme,
   KIT_COMPONENT_SX_REGISTRY,
+  reportOffPaletteColours,
   reportKitSxBypasses,
   THEME_COMPLETENESS_SURFACES,
 } from '../src/theme';
+import { BASELINE_PALETTE } from '../src/theme/tokens';
 
-function jsxSources(directory) {
+function sourceFiles(directory) {
   return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
     const entryPath = path.join(directory, entry.name);
-    if (entry.isDirectory()) return jsxSources(entryPath);
-    if (!entry.name.endsWith('.jsx')) return [];
+    if (entry.isDirectory()) return sourceFiles(entryPath);
+    if (!/\.jsx?$/.test(entry.name)) return [];
     return [{ path: path.relative(process.cwd(), entryPath), source: fs.readFileSync(entryPath, 'utf8') }];
   });
 }
@@ -209,6 +211,27 @@ describe('kit sx disjointness', () => {
     expect(bottomNavActionResult.findings).toEqual([]);
   });
 
+  it('normalises bgcolor against a backgroundColor baseline default', () => {
+    const result = assertKitSxDisjoint({
+      components: {
+        MuiPaper: {
+          styleOverrides: { root: { backgroundColor: '#FFFFFF' } },
+        },
+      },
+    }, {
+      registry: [{
+        component: 'FixturePaper',
+        muiComponent: 'MuiPaper',
+        sx: { bgcolor: '#FFFFFF' },
+      }],
+    });
+
+    expect(result.findings).toEqual([{
+      surface: 'FixturePaper.MuiPaper.bgcolor',
+      reason: expect.stringMatching(/FixturePaper.*MuiPaper.*bgcolor/),
+    }]);
+  });
+
   it('keeps every registered kit sx object disjoint from the baseline', () => {
     expect(KIT_COMPONENT_SX_REGISTRY.length).toBeGreaterThan(2);
     expect(assertKitSxDisjoint(theme, {
@@ -290,7 +313,7 @@ describe('kit sx disjointness', () => {
 
   it('does not let current kit source bypass the exported-object convention', () => {
     expect(reportKitSxBypasses(
-      jsxSources(path.resolve('src')),
+      sourceFiles(path.resolve('src')),
       { registry: KIT_COMPONENT_SX_REGISTRY },
     ).findings).toEqual([]);
   });
@@ -353,3 +376,132 @@ describe('kit sx disjointness', () => {
     ]);
   });
 });
+
+describe('off-palette colour reporting', () => {
+  it('flags an unknown hex literal and accepts a baseline palette value', () => {
+    const result = reportOffPaletteColours([
+      { path: 'Unknown.jsx', source: "const sx = { bgcolor: '#123456' };" },
+      { path: 'Baseline.jsx', source: "const sx = { bgcolor: '#F4F5F6' };" },
+      { path: 'Token.jsx', source: "const sx = { bgcolor: 'background.subtle' };" },
+    ]);
+
+    expect(result.findings).toEqual([{
+      surface: 'Unknown.jsx:1.colour',
+      reason: expect.stringMatching(/#123456.*baseline palette/i),
+    }]);
+  });
+
+  it('flags a named CSS colour used by sx', () => {
+    const result = reportOffPaletteColours([{
+      path: 'Named.jsx',
+      source: "const sx = { bgcolor: 'white' };",
+    }]);
+
+    expect(result.findings).toEqual([{
+      surface: 'Named.jsx:1.colour',
+      reason: expect.stringMatching(/named CSS colour.*white.*baseline palette/i),
+    }]);
+  });
+
+  it('flags rgba literals and named Canvas fill colours', () => {
+    const result = reportOffPaletteColours([
+      {
+        path: 'Border.jsx',
+        source: "const sx = { border: '1px solid rgba(0,0,0,0.2)' };",
+      },
+      {
+        path: 'exportChart.js',
+        source: "context.fillStyle = 'white';",
+      },
+      {
+        path: 'NamedBorder.jsx',
+        source: "const sx = { border: '1px solid white', boxShadow: '0 0 1px black' };",
+      },
+    ]);
+
+    expect(result.findings).toEqual([
+      {
+        surface: 'Border.jsx:1.colour',
+        reason: expect.stringMatching(/rgba\(0,0,0,0\.2\).*baseline palette/i),
+      },
+      {
+        surface: 'exportChart.js:1.colour',
+        reason: expect.stringMatching(/named CSS colour.*white.*baseline palette/i),
+      },
+      {
+        surface: 'NamedBorder.jsx:1.colour',
+        reason: expect.stringMatching(/named CSS colour.*white.*baseline palette/i),
+      },
+      {
+        surface: 'NamedBorder.jsx:1.colour',
+        reason: expect.stringMatching(/named CSS colour.*black.*baseline palette/i),
+      },
+    ]);
+  });
+
+  it('excludes only QrSignupManager print-document HTML', () => {
+    const result = reportOffPaletteColours([{
+      path: 'src/components/QrSignupManager.jsx',
+      source: [
+        "const panel = { bgcolor: '#123456' };",
+        'printWindow.document.write(`',
+        '  <style>body { background: #654321; }</style>',
+        '`);',
+      ].join('\n'),
+    }]);
+
+    expect(result.findings).toHaveLength(1);
+    expect(result.findings[0]).toEqual({
+      surface: 'src/components/QrSignupManager.jsx:1.colour',
+      reason: expect.stringMatching(/#123456/),
+    });
+  });
+
+  it('derives its allowlist from the supplied palette', () => {
+    const source = [{ path: 'NewToken.jsx', source: "const sx = { bgcolor: '#123456' };" }];
+    const extendedPalette = {
+      ...BASELINE_PALETTE,
+      fixture: { main: '#123456' },
+    };
+
+    expect(reportOffPaletteColours(source).findings).toHaveLength(1);
+    expect(reportOffPaletteColours(source, { palette: extendedPalette }).findings).toEqual([]);
+  });
+
+  it('reports MUI numeric ramps separately without treating token paths as literals', () => {
+    const result = reportOffPaletteColours([{
+      path: 'Ramp.jsx',
+      source: "const sx = { bgcolor: 'grey.50', borderColor: 'divider', color: 'success.bg', transition: 'release.50' };",
+    }]);
+
+    expect(result.findings).toEqual([{
+      surface: 'Ramp.jsx:1.colour',
+      reason: expect.stringMatching(/^Report only:.*grey\.50.*untouched numeric palette ramp/i),
+    }]);
+  });
+
+  it('ignores comment issue numbers and theme implementation sources', () => {
+    const result = reportOffPaletteColours([
+      {
+        path: 'src/components/charts/chartLabels.js',
+        source: '// MUI issues mui-x#18768 and #18399',
+      },
+      {
+        path: 'src/theme/createAppTheme.js',
+        source: "const contrastSurface = '#123456';",
+      },
+    ]);
+
+    expect(result.findings).toEqual([]);
+  });
+
+  it('keeps current kit source free of hard off-palette findings', () => {
+    const result = reportOffPaletteColours(sourceFiles(path.resolve('src')));
+    const hardFindings = result.findings.filter(
+      ({ reason }) => !reason.startsWith('Report only:'),
+    );
+
+    expect(hardFindings).toEqual([]);
+    expect(result.findings.some(({ reason }) => reason.includes('grey.50'))).toBe(true);
+  });
+});