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

package/tests/themeCompleteness.test.js

@@ -1,13 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
 import { createTheme } from '@mui/material/styles';
 import { describe, expect, it } from 'vitest';
 
 import {
   assertThemeComplete,
+  assertKitSxDisjoint,
   calculateContrastRatio,
   createAppTheme,
+  KIT_COMPONENT_SX_REGISTRY,
+  reportKitSxBypasses,
   THEME_COMPLETENESS_SURFACES,
 } from '../src/theme';
 
+function jsxSources(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 [];
+    return [{ path: path.relative(process.cwd(), entryPath), source: fs.readFileSync(entryPath, 'utf8') }];
+  });
+}
+
 describe('theme completeness', () => {
   it('finds untouched MUI surfaces and accepts createAppTheme', () => {
     const bare = assertThemeComplete(createTheme());
@@ -154,3 +169,187 @@ describe('theme completeness', () => {
     );
   });
 });
+
+describe('kit sx disjointness', () => {
+  const theme = createAppTheme({ palette: { primary: { main: '#0F62FE' } } });
+
+  it('finds the real shadowing incident shape and names every part', () => {
+    const result = assertKitSxDisjoint(theme, {
+      registry: [{
+        component: 'FixtureBottomNav',
+        muiComponent: 'MuiBottomNavigation',
+        sx: { boxShadow: 'none' },
+      }],
+    });
+
+    expect(result.findings).toEqual([{
+      surface: 'FixtureBottomNav.MuiBottomNavigation.boxShadow',
+      reason: expect.stringMatching(/FixtureBottomNav.*MuiBottomNavigation.*boxShadow/),
+    }]);
+  });
+
+  it('checks same-root variant slots without conflating child slots', () => {
+    const chipResult = assertKitSxDisjoint(theme, {
+      registry: [{
+        component: 'FixtureChip',
+        muiComponent: 'MuiChip',
+        sx: { borderColor: 'red' },
+      }],
+    });
+    const bottomNavActionResult = assertKitSxDisjoint(theme, {
+      registry: [{
+        component: 'FixtureBottomNavAction',
+        muiComponent: 'MuiBottomNavigationAction',
+        sx: { maxWidth: 'none' },
+      }],
+    });
+
+    expect(chipResult.findings.map(({ surface }) => surface))
+      .toContain('FixtureChip.MuiChip.borderColor');
+    expect(bottomNavActionResult.findings).toEqual([]);
+  });
+
+  it('keeps every registered kit sx object disjoint from the baseline', () => {
+    expect(KIT_COMPONENT_SX_REGISTRY.length).toBeGreaterThan(2);
+    expect(assertKitSxDisjoint(theme, {
+      exemptions: [
+        {
+          surface: 'UserListComponent.bodyCell.MuiTableCell.py',
+          reason: 'The user list intentionally uses a tighter row density than the baseline TableCell default.',
+        },
+        {
+          surface: 'UserListComponent.emptyCell.MuiTableCell.py',
+          reason: 'The empty-state message intentionally uses more vertical breathing room than the baseline TableCell default.',
+        },
+      ],
+    }).findings).toEqual([]);
+  });
+
+  it('flags inline sx while accepting a top-level exported object', () => {
+    const result = reportKitSxBypasses([
+      {
+        path: 'InlineFixture.jsx',
+        source: 'export function Fixture() { return <Button sx={{ minHeight: 12 }} />; }',
+      },
+      {
+        path: 'ExportedFixture.jsx',
+        source: 'export const FIXTURE_SX = { minHeight: 12 }; export function Fixture() { return <Button sx={FIXTURE_SX} />; }',
+      },
+    ]);
+
+    expect(result.findings).toHaveLength(1);
+    expect(result.findings[0]).toEqual({
+      surface: 'InlineFixture.jsx:1.MuiButton.sx',
+      reason: expect.stringMatching(/Button.*inline sx object.*exported object/i),
+    });
+  });
+
+  it('flags a local sx identifier and ignores nested JSX props', () => {
+    const result = reportKitSxBypasses([
+      {
+        path: 'LocalFixture.jsx',
+        source: 'const LOCAL_SX = { minHeight: 12 }; export function Fixture() { return <Button sx={LOCAL_SX} />; }',
+      },
+      {
+        path: 'NestedFixture.jsx',
+        source: 'export function Fixture() { return <Button startIcon={<Box sx={{ width: 12 }} />} />; }',
+      },
+    ]);
+
+    expect(result.findings).toEqual([{
+      surface: 'LocalFixture.jsx:1.MuiButton.sx',
+      reason: expect.stringMatching(/Button.*non-exported sx object.*LOCAL_SX/i),
+    }]);
+  });
+
+  it('flags an exported sx object omitted from the registry', () => {
+    const result = reportKitSxBypasses([{
+      path: 'UnregisteredFixture.jsx',
+      source: 'export const UNREGISTERED_SX = { minHeight: 12 }; export function Fixture() { return <Button sx={UNREGISTERED_SX} />; }',
+    }], { registry: [] });
+
+    expect(result.findings).toEqual([{
+      surface: 'UnregisteredFixture.jsx:1.MuiButton.sx',
+      reason: expect.stringMatching(/Button.*exported sx object.*UNREGISTERED_SX.*MuiButton registry entry/i),
+    }]);
+  });
+
+  it('flags an sx object registered against the wrong MUI key', () => {
+    const result = reportKitSxBypasses([{
+      path: 'WrongTargetFixture.jsx',
+      source: 'export const WRONG_TARGET_SX = { minHeight: 12 }; export function Fixture() { return <Button sx={WRONG_TARGET_SX} />; }',
+    }], {
+      registry: [{ exportName: 'WRONG_TARGET_SX', muiComponent: 'MuiPaper' }],
+    });
+
+    expect(result.findings).toEqual([{
+      surface: 'WrongTargetFixture.jsx:1.MuiButton.sx',
+      reason: expect.stringMatching(/WRONG_TARGET_SX.*MuiButton registry entry/i),
+    }]);
+  });
+
+  it('does not let current kit source bypass the exported-object convention', () => {
+    expect(reportKitSxBypasses(
+      jsxSources(path.resolve('src')),
+      { registry: KIT_COMPONENT_SX_REGISTRY },
+    ).findings).toEqual([]);
+  });
+
+  it('suppresses exactly one collision with a reason', () => {
+    const registry = [{
+      component: 'FixtureButton',
+      muiComponent: 'MuiButton',
+      sx: { minHeight: 12, textTransform: 'uppercase' },
+    }];
+    const before = assertKitSxDisjoint(theme, { registry }).findings;
+    const after = assertKitSxDisjoint(theme, {
+      registry,
+      exemptions: [{
+        surface: 'FixtureButton.MuiButton.minHeight',
+        reason: 'The fixture deliberately overrides one baseline property.',
+      }],
+    }).findings;
+
+    expect(before).toHaveLength(2);
+    expect(after).toHaveLength(1);
+    expect(after[0].surface).toBe('FixtureButton.MuiButton.textTransform');
+  });
+
+  it('honours a reasoned exemption declared on the theme', () => {
+    const exemptTheme = {
+      ...theme,
+      themeCompleteness: {
+        ...theme.themeCompleteness,
+        exemptions: [{
+          surface: 'FixtureButton.MuiButton.minHeight',
+          reason: 'The fixture deliberately owns its compact height.',
+        }],
+      },
+    };
+    const result = assertKitSxDisjoint(exemptTheme, {
+      registry: [{
+        component: 'FixtureButton',
+        muiComponent: 'MuiButton',
+        sx: { minHeight: 12 },
+      }],
+    });
+
+    expect(result.findings).toEqual([]);
+  });
+
+  it('reports an exemption without a reason as its own finding', () => {
+    const result = assertKitSxDisjoint(theme, {
+      registry: [{
+        component: 'FixtureButton',
+        muiComponent: 'MuiButton',
+        sx: { minHeight: 12 },
+      }],
+      exemptions: [{ surface: 'FixtureButton.MuiButton.minHeight' }],
+    });
+
+    expect(result.findings.map(({ surface }) => surface)).toEqual([
+      'exemption.FixtureButton.MuiButton.minHeight',
+      'FixtureButton.MuiButton.minHeight',
+    ]);
+  });
+});

package/work-orders/THEME-4.md

@@ -178,6 +178,92 @@ note, not folded in as tidying.
 > `git status` before your own review; an implementer commit is a blocker to surface, and a register
 > row naming a review the Orchestrator did not itself start is invalid.
 
+### Context package
+
+**Precondition confirmed:** `THEME-3` is landed and published (`1b25117`, register row `done`).
+`git log --oneline -3` at hand-off time shows the Orchestrator's own docs commits on top of it, no
+implementer commit — clean to start from.
+
+**The established `sx`-export convention (scope item 1's shape to follow), already shipped in
+`src/components/MobileBottomNav.jsx`:**
+```js
+export const MOBILE_BOTTOM_NAV_ROOT_SX = {
+  position: 'fixed', left: 0, right: 0, bottom: 0,
+  borderTop: '1px solid', borderColor: 'divider',
+  paddingBottom: 'env(safe-area-inset-bottom)',
+};
+export const MOBILE_BOTTOM_NAV_ACTION_SX = { minWidth: 0, maxWidth: 'none' };
+```
+Both are plain top-level `export const` object literals, used directly as (or spread into) the
+`sx` prop on the MUI element they style. This is the shape the registry (item 1) should match
+against — a component "carries its own `sx` for a MUI component the baseline styles" means: look for
+`<BottomNavigation`, `<Button`, `<Card`, etc. (the 23 baseline-styled MUI component names) receiving
+an `sx=` prop inside `src/**/*.jsx`, then check whether that `sx` is a top-level exported identifier
+(covered) or an inline/conditional literal (item 3's bypass check should flag the latter if it isn't
+exported).
+
+**The exemption contract to mirror exactly (scope item 2 + required test 4), from
+`src/theme/themeCompleteness.js:333-350` (`assertThemeComplete`):**
+```js
+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);
+  }
+  ...
+}
+```
+The new check's `{ findings: [{ surface, reason }] }` return shape and exemption handling should be
+structurally identical to this, not a reinvention — same two failure modes (missing reason is itself
+a finding; a valid exemption suppresses exactly one finding).
+
+**The bypass-check precedent (scope item 3), from `src/theme/themeCompleteness.js:370-379`
+(`reportThemeAdoption`):**
+```js
+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);
+  ...
+}
+```
+Same module, same input shape (an array of `{ path, source }` or raw source strings), same
+regex-over-source-text technique — the new bypass check takes the same input shape and regexes for
+an inline `sx={{ ... }}` object literal that is not a reference to a top-level exported identifier.
+
+**Where to put the new code:** co-locate in `src/theme/themeCompleteness.js` alongside
+`reportThemeAdoption` (the WO's own "same module" language for item 3), or a new sibling file if
+the additions make that file unwieldy — Codex's call, but export everything new from
+`src/theme/index.js` and `src/index.js` (follow the existing export list pattern in both) so the
+check is part of the public API per the WO's "additive API is a minor" versioning note.
+
+**Discovery is the actual task, not pre-solved here:** the WO's own measurement (51 `.jsx` files
+under `src/` carry `sx=`, baseline styles 23 MUI keys) is a starting estimate, not a fixed list —
+grep `src/**/*.jsx` for `sx=` against the 23 keys named in the Envelope's "Why the whole kit,
+measured" section to build the actual registry. This is scope item 1 itself; do not skip it by
+registering only `MobileBottomNav`'s two already-known exports.
+
+**On the "stop and report if large" clause:** if fixing every real finding from test 2 would grow
+this WO well beyond a layer-relocation pass (i.e. touches component *behaviour*, not just moving an
+`sx` value into an export), STOP before committing anything and report the finding list instead of
+silently absorbing it all — this is explicitly named in the Envelope as an operator-level scope
+decision, not an implementer judgment call.
+
+**Known repeat-offense warning, restated because it has happened on the two immediately preceding
+work orders in this exact repo:** do not run `git commit` or `git push` under any circumstance. Leave
+the diff for the Orchestrator. If you find yourself about to commit "because everything passed", stop
+— that decision is not yours in this workflow, regardless of how clean the result looks.
+
 ### Mini-handover
 
 Repo: `ui-core-micha` (`C:\Users\biglmi\Documents\webapps\ui-core-micha`), branch `main`.