@micha.bigler/ui-core-micha 3.10.0 → 3.11.0

package/src/theme/createAppTheme.js

@@ -1,11 +1,16 @@
 import './fonts';
 
-import { createTheme, darken, getContrastRatio } from '@mui/material/styles';
+import { createTheme, darken, decomposeColor, getContrastRatio, lighten } from '@mui/material/styles';
 
 import {
   BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS,
+  BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS_DARK,
   BASELINE_PALETTE,
+  BASELINE_PALETTE_DARK,
   BASELINE_STATIC,
+  DARK_OVERLAY_SHADOW,
+  DARK_OVERLAY_SURFACE,
+  DARK_SCRIM,
   MOTION,
   withMainShades,
 } from './tokens';
@@ -42,6 +47,21 @@ function clearsContrast(colour, surfaces) {
   return surfaces.every((surface) => getContrastRatio(colour, surface) >= 3);
 }
 
+function normalizeColour(colour) {
+  const match = colour.match(/^rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/);
+  if (!match) return colour;
+  return `#${match.slice(1).map((channel) => Number(channel).toString(16).padStart(2, '0')).join('').toUpperCase()}`;
+}
+
+function lightenColour(colour, coefficient) {
+  const normalized = normalizeColour(colour);
+  const match = normalized.match(/^#([\da-f]{6})$/i);
+  if (!match) return normalizeColour(lighten(colour, coefficient));
+  const channels = [0, 2, 4].map((offset) => parseInt(match[1].slice(offset, offset + 2), 16));
+  return `#${channels.map((channel) => Math.round(channel + (255 - channel) * coefficient)
+    .toString(16).padStart(2, '0')).join('').toUpperCase()}`;
+}
+
 // 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
@@ -55,6 +75,16 @@ function deriveFocusColour(primary, surfaces) {
   return focus;
 }
 
+function deriveLightenedColour(original, surfaces) {
+  if (clearsContrast(original, surfaces)) return original;
+  let colour = original;
+  for (let coefficient = 0.05; !clearsContrast(colour, surfaces); coefficient += 0.05) {
+    colour = lightenColour(original, Math.min(coefficient, 0.9));
+    if (coefficient >= 0.9) break;
+  }
+  return colour;
+}
+
 function clearsPageContrast(colour, surfaces, threshold) {
   return surfaces.every((surface) => {
     const ratio = calculateContrastRatio(colour, surface);
@@ -73,6 +103,35 @@ function deriveDarkenedPageColour(original, surfaces, threshold) {
   return colour;
 }
 
+function deriveLightenedPageColour(original, surfaces, threshold) {
+  if (clearsPageContrast(original, surfaces, threshold)) return original;
+
+  let colour = original;
+  for (let coefficient = 0.05; !clearsPageContrast(colour, surfaces, threshold); coefficient += 0.05) {
+    colour = lightenColour(original, Math.min(coefficient, 0.9));
+    if (coefficient >= 0.9) break;
+  }
+  return colour;
+}
+
+// ink.primary may be supplied as hex or rgb(); decomposeColor normalises both.
+function inkChannels(ink) {
+  return decomposeColor(ink).values.slice(0, 3).map((value) => Math.round(value));
+}
+
+// 0.02 steps: the frozen sheet value (0.38) is the first even step that clears
+// 3:1; a 0.01 search would land on 0.37 and drift from the frozen baseline.
+function deriveDarkAlphaColour(ink, surfaces) {
+  const [red, green, blue] = inkChannels(ink);
+  let alpha = 0;
+  while (alpha <= 1) {
+    const colour = `rgba(${red},${green},${blue},${alpha.toFixed(2)})`;
+    if (clearsPageContrast(colour, surfaces, 3)) return colour;
+    alpha = Number((alpha + 0.02).toFixed(2));
+  }
+  return `rgba(${red},${green},${blue},1)`;
+}
+
 const RGBA_PATTERN = /^rgba\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d*\.?\d+)\s*\)$/;
 
 function deriveAlphaPageColour(original, surfaces, threshold) {
@@ -92,7 +151,7 @@ function deriveAlphaPageColour(original, surfaces, threshold) {
   return colour;
 }
 
-function createPaletteAwareComponents(palette) {
+function createPaletteAwareComponents(palette, isDark) {
   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': {
@@ -117,7 +176,7 @@ function createPaletteAwareComponents(palette) {
     ]),
   );
 
-  return {
+  const components = {
     MuiButton: {
       styleOverrides: {
         root: { transition: stateTransition },
@@ -199,6 +258,22 @@ function createPaletteAwareComponents(palette) {
       styleOverrides: alertStyles,
     },
   };
+
+  if (isDark) {
+    for (const component of ['MuiDialog', 'MuiMenu', 'MuiPopover', 'MuiDrawer']) {
+      components[component] = {
+        styleOverrides: {
+          paper: {
+            backgroundColor: DARK_OVERLAY_SURFACE,
+            boxShadow: DARK_OVERLAY_SHADOW,
+          },
+        },
+      };
+    }
+    components.MuiBackdrop = { styleOverrides: { root: { backgroundColor: DARK_SCRIM } } };
+  }
+
+  return components;
 }
 
 /**
@@ -212,19 +287,29 @@ export function createAppTheme(appConfig = {}) {
   }
   validateStyleOverrides(appConfig.components);
 
+  const isDark = appConfig.palette.mode === 'dark';
+  const baselinePalette = isDark ? BASELINE_PALETTE_DARK : BASELINE_PALETTE;
+
   const paletteTheme = createTheme(
     { palette: appConfig.palette },
-    { palette: BASELINE_PALETTE },
+    { palette: baselinePalette },
     { palette: appConfig.palette },
   );
   const finalPalette = paletteTheme.palette;
-  const contrastSurfaces = ['#FFFFFF', finalPalette.background.default];
+  const contrastSurfaces = isDark
+    ? [finalPalette.background.default, finalPalette.background.paper]
+    : ['#FFFFFF', finalPalette.background.default];
   const derivedStatusEntries = {};
   for (const status of ['success', 'warning', 'error', 'info']) {
     if (appConfig.palette?.[status]?.main !== undefined) continue;
 
     const current = finalPalette[status];
-    const main = deriveDarkenedPageColour(current.main, contrastSurfaces, 4.5);
+    const statusSurfaces = isDark
+      ? [finalPalette.background.default, current.bg]
+      : contrastSurfaces;
+    const main = isDark
+      ? deriveLightenedPageColour(current.main, statusSurfaces, 4.5)
+      : deriveDarkenedPageColour(current.main, statusSurfaces, 4.5);
     if (main !== current.main) {
       derivedStatusEntries[status] = {
         ...current,
@@ -238,19 +323,57 @@ export function createAppTheme(appConfig = {}) {
     if (appConfig.palette?.controlBorder?.[state] !== undefined) continue;
 
     const current = finalPalette.controlBorder[state];
-    const derived = state === 'error'
-      ? deriveDarkenedPageColour(current, contrastSurfaces, 3)
-      : deriveAlphaPageColour(current, contrastSurfaces, 3);
+    const derived = isDark
+      ? state === 'error'
+        ? deriveLightenedPageColour(current, [finalPalette.background.default, finalPalette.error.bg], 3)
+        : deriveDarkAlphaColour(finalPalette.ink.primary, contrastSurfaces)
+      : state === 'error'
+        ? deriveDarkenedPageColour(current, contrastSurfaces, 3)
+        : deriveAlphaPageColour(current, contrastSurfaces, 3);
     if (derived !== current) derivedControlBorderEntries[state] = derived;
   }
+  if (isDark && appConfig.palette?.controlBorder?.hover === undefined) {
+    const main = derivedControlBorderEntries.main || finalPalette.controlBorder.main;
+    const alpha = Number(main.match(/,([\d.]+)\)$/)?.[1] || 0);
+    const hoverAlpha = Math.min(1, Number((alpha + 0.15).toFixed(2)));
+    const [red, green, blue] = inkChannels(finalPalette.ink.primary);
+    derivedControlBorderEntries.hover = `rgba(${red},${green},${blue},${hoverAlpha.toFixed(2)})`;
+  }
+
+  const primaryMain = isDark
+    ? deriveLightenedPageColour(finalPalette.primary.main, [finalPalette.background.default], 4.5)
+    : finalPalette.primary.main;
+  const primaryContrastText = isDark
+    ? (getContrastRatio('#FFFFFF', primaryMain) >= getContrastRatio(finalPalette.background.default, primaryMain)
+      ? '#FFFFFF'
+      : finalPalette.background.default)
+    : finalPalette.primary.contrastText;
+  const derivedSeries = isDark && appConfig.palette?.dataSeries?.categorical === undefined
+    ? finalPalette.dataSeries.categorical.map((colour) => (
+      deriveLightenedPageColour(colour, [finalPalette.background.paper], 3)
+    ))
+    : finalPalette.dataSeries.categorical;
 
   const computedPalette = {
     ...derivedStatusEntries,
     controlBorder: {
       ...finalPalette.controlBorder,
       ...derivedControlBorderEntries,
-      focus: deriveFocusColour(finalPalette.primary.main, contrastSurfaces),
+      focus: isDark
+        ? (appConfig.palette?.controlBorder?.focus
+          ?? deriveLightenedColour(primaryMain, contrastSurfaces))
+        : deriveFocusColour(finalPalette.primary.main, contrastSurfaces),
+    },
+    primary: {
+      ...finalPalette.primary,
+      // A lightened main needs its own light/dark shades, or hover states keep
+      // the shades of the colour that was replaced.
+      ...(isDark && primaryMain !== finalPalette.primary.main
+        ? withMainShades(primaryMain, primaryContrastText)
+        : { main: primaryMain }),
+      contrastText: primaryContrastText,
     },
+    dataSeries: { categorical: derivedSeries },
   };
   const resolvedPalette = { ...finalPalette, ...computedPalette };
   const fontFamily = appConfig.typography?.fontFamily || BASELINE_STATIC.typography.fontFamily;
@@ -266,20 +389,24 @@ export function createAppTheme(appConfig = {}) {
         ...BASELINE_STATIC.fontLoading,
         weights: [...BASELINE_STATIC.fontLoading.weights],
       },
+      shadow: isDark ? { ...BASELINE_STATIC.shadow, overlay: DARK_OVERLAY_SHADOW } : BASELINE_STATIC.shadow,
       palette: resolvedPalette,
       themeCompleteness: {
         baseline: true,
-        exemptions: BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS.map((exemption) => ({
+        exemptions: (isDark
+          ? BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS_DARK
+          : BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS).map((exemption) => ({
           ...exemption,
         })),
       },
     },
     {
-      components: createPaletteAwareComponents(resolvedPalette),
+      components: createPaletteAwareComponents(resolvedPalette, isDark),
     },
     appConfig,
     {
       palette: {
+        ...(isDark ? computedPalette : {}),
         dataSeries: {
           categorical: [...resolvedPalette.dataSeries.categorical],
         },

package/src/theme/themeCompleteness.js

@@ -294,10 +294,16 @@ function contrastFindings(theme) {
     }
   }
 
-  const backgrounds = {
-    white: '#FFFFFF',
-    page: theme.palette?.background?.default,
-  };
+  const dark = theme.palette?.mode === 'dark';
+  const backgrounds = dark
+    ? {
+      paper: theme.palette?.background?.paper,
+      page: theme.palette?.background?.default,
+    }
+    : {
+      white: '#FFFFFF',
+      page: theme.palette?.background?.default,
+    };
   for (const status of STATUS_KEYS) {
     const main = theme.palette?.[status]?.main;
     if (!main) continue;

package/src/theme/tokens.js

@@ -113,6 +113,73 @@ export const BASELINE_PALETTE = {
   },
 };
 
+export const DARK_OVERLAY_SURFACE = '#232A31';
+export const DARK_OVERLAY_SHADOW = '0 8px 28px rgba(0,0,0,.45)';
+export const DARK_SCRIM = 'rgba(0,0,0,.55)';
+
+export const BASELINE_PALETTE_DARK = {
+  mode: 'dark',
+  ink: {
+    primary: '#E6EBEF',
+    secondary: '#AAB5BF',
+    muted: '#87919A',
+  },
+  text: {
+    primary: '#E6EBEF',
+    secondary: '#AAB5BF',
+    disabled: '#87919A',
+  },
+  background: {
+    default: '#14181B',
+    paper: '#1B2126',
+    subtle: '#20262C',
+  },
+  divider: '#2B333A',
+  controlBorder: {
+    // These are replaced by the dark alpha derivation in createAppTheme.
+    main: 'rgba(230,235,239,0)',
+    hover: 'rgba(230,235,239,0)',
+    error: '#E58B80',
+  },
+  success: {
+    ...withMainShades('#7BC496', '#14181B'),
+    text: '#7BC496',
+    fill: '#7BC496',
+    fillText: '#14181B',
+    bg: '#1C2A22',
+  },
+  warning: {
+    ...withMainShades('#D8BD7E', '#14181B'),
+    text: '#D8BD7E',
+    fill: '#D8BD7E',
+    fillText: '#14181B',
+    bg: '#2A2418',
+  },
+  error: {
+    ...withMainShades('#E58B80', '#14181B'),
+    text: '#E58B80',
+    fill: '#E58B80',
+    fillText: '#14181B',
+    bg: '#3A2320',
+  },
+  info: {
+    ...withMainShades('#8FB8E0', '#14181B'),
+    text: '#8FB8E0',
+    fill: '#8FB8E0',
+    fillText: '#14181B',
+    bg: '#1A2633',
+  },
+  stale: {
+    text: '#AAB5BF',
+    fill: '#AAB5BF',
+    fillText: '#14181B',
+    bg: '#20262C',
+  },
+  dataSeries: {
+    categorical: SERIES_COLOURS,
+  },
+};
+
 export const OVERLAY_SHADOW =
   '0 8px 24px rgba(20,26,31,.16), 0 2px 8px rgba(20,26,31,.08)';
 
@@ -399,3 +466,8 @@ export const BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS = [
     reason: `The canonical ${variant} weight deliberately equals MUI's numeric default.`,
   })),
 ];
+
+export const BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS_DARK =
+  BASELINE_INTENTIONAL_DEFAULT_EXEMPTIONS.filter(
+    ({ surface }) => surface !== 'palette.background.paper',
+  );

package/tests/createAppThemeDark.test.js

@@ -0,0 +1,127 @@
+import { darken, lighten } from '@mui/material/styles';
+import { describe, expect, it } from 'vitest';
+
+import {
+  assertThemeComplete,
+  calculateContrastRatio,
+  createAppTheme,
+} from '../src/theme';
+import {
+  BASELINE_PALETTE_DARK,
+  SERIES_COLOURS,
+  DARK_OVERLAY_SHADOW,
+  DARK_OVERLAY_SURFACE,
+  DARK_SCRIM,
+} from '../src/theme/tokens';
+
+const dark = (primary = '#468AB2', extra = {}) => createAppTheme({
+  palette: { mode: 'dark', primary: { main: primary }, ...extra },
+});
+
+describe('createAppTheme dark baseline', () => {
+  it('is complete, including a primary that must be lightened', () => {
+    expect(assertThemeComplete(dark()).findings).toEqual([]);
+    expect(assertThemeComplete(dark('#2F4F96')).findings).toEqual([]);
+  });
+
+  it('derives focus contrast against page and paper in both modes', () => {
+    for (const theme of [
+      createAppTheme({ palette: { primary: { main: '#0F62FE' } } }),
+      dark(),
+    ]) {
+      expect(calculateContrastRatio(theme.palette.controlBorder.focus, theme.palette.background.default)).toBeGreaterThanOrEqual(3);
+      expect(calculateContrastRatio(theme.palette.controlBorder.focus, theme.palette.background.paper)).toBeGreaterThanOrEqual(3);
+    }
+  });
+
+  it('derives dark control borders and focus from the rules', () => {
+    const theme = dark();
+    expect(theme.palette.controlBorder.main).toBe('rgba(230,235,239,0.38)');
+    expect(theme.palette.controlBorder.hover).toBe('rgba(230,235,239,0.53)');
+    expect(theme.palette.controlBorder.error).toBe('#E58B80');
+    expect(theme.palette.controlBorder.focus).toBe('#468AB2');
+    expect(dark('#2F4F96').palette.controlBorder.focus).toBe('#6D84B6');
+    const rgbInk = dark('#468AB2', { ink: { primary: 'rgb(230, 235, 239)' } });
+    expect(rgbInk.palette.controlBorder.main).toBe('rgba(230,235,239,0.38)');
+    const ownFocus = dark('#468AB2', { controlBorder: { focus: '#FFFFFF' } });
+    expect(ownFocus.palette.controlBorder.focus).toBe('#FFFFFF');
+  });
+
+  it('recomputes primary shades for a lightened primary', () => {
+    const theme = dark('#2F4F96');
+    expect(theme.palette.primary.light).toBe(lighten('#6D84B6', 0.2));
+    expect(theme.palette.primary.dark).toBe(darken('#6D84B6', 0.3));
+  });
+
+  it('uses the complete dark status family', () => {
+    for (const status of ['success', 'warning', 'error', 'info']) {
+      expect(dark().palette[status]).toMatchObject(BASELINE_PALETTE_DARK[status]);
+    }
+    expect(dark().palette.stale).toMatchObject(BASELINE_PALETTE_DARK.stale);
+  });
+
+  it.each([
+    ['#468AB2', '#468AB2'],
+    ['#2F4F96', '#6D84B6'],
+    ['#432CA1', '#8576C2'],
+    ['#D49040', '#D49040'],
+  ])('applies the dark primary rule to %s', (input, expected) => {
+    const theme = dark(input);
+    expect(theme.palette.primary.main).toBe(expected);
+    expect(theme.palette.primary.contrastText).toBe('#14181B');
+  });
+
+  it('keeps baseline statuses on webshop-guenter page and protects failing baseline values', () => {
+    const webshop = dark('#D49040', { background: { default: '#0E0B08', paper: '#171209' } });
+    for (const status of ['success', 'warning', 'error', 'info']) {
+      expect(webshop.palette[status].main).toBe(BASELINE_PALETTE_DARK[status].main);
+    }
+    const failing = dark('#468AB2', { background: { default: '#707070', paper: '#787878' } });
+    expect(failing.palette.success.main).not.toBe(BASELINE_PALETTE_DARK.success.main);
+    expect(calculateContrastRatio(failing.palette.success.main, failing.palette.background.default)).toBeGreaterThanOrEqual(4.5);
+    for (const status of ['success', 'warning', 'error', 'info']) {
+      const net = dark('#468AB2', { background: { default: '#707070', paper: '#787878' } }).palette[status];
+      expect(calculateContrastRatio(net.main, '#707070')).toBeGreaterThanOrEqual(4.5);
+      expect(calculateContrastRatio(net.main, net.bg)).toBeGreaterThanOrEqual(4.5);
+    }
+    const supplied = dark('#468AB2', {
+      background: { default: '#707070' },
+      success: { main: '#123456' },
+    });
+    expect(supplied.palette.success.main).toBe('#123456');
+  });
+
+  it('uses the dark overlay surface, shadow, scrim, and shadow token', () => {
+    const theme = dark();
+    for (const component of ['MuiDialog', 'MuiMenu', 'MuiPopover', 'MuiDrawer']) {
+      expect(theme.components[component].styleOverrides.paper).toMatchObject({
+        backgroundColor: DARK_OVERLAY_SURFACE,
+        boxShadow: DARK_OVERLAY_SHADOW,
+      });
+    }
+    expect(theme.components.MuiBackdrop.styleOverrides.root.backgroundColor).toBe(DARK_SCRIM);
+    expect(theme.shadow.overlay).toBe(DARK_OVERLAY_SHADOW);
+  });
+
+  it('lightens baseline series for baseline paper and adapts to app paper', () => {
+    const baseline = dark().palette.dataSeries.categorical;
+    expect(baseline).toEqual(['#506BA3', '#3E80B8', '#2E8F8A', '#7A5FA8', '#A1588C', '#8A7355']);
+    const adapted = dark('#D49040', { background: { paper: '#171209' } }).palette.dataSeries.categorical;
+    expect(adapted).toHaveLength(SERIES_COLOURS.length);
+    adapted.forEach((colour) => {
+      expect(calculateContrastRatio(colour, '#171209')).toBeGreaterThanOrEqual(3);
+    });
+  });
+
+  it('leaves app-supplied series untouched', () => {
+    const series = ['#111111', '#222222', '#333333'];
+    expect(dark('#468AB2', { dataSeries: { categorical: series } }).palette.dataSeries.categorical).toEqual(series);
+  });
+
+  it('resolves dark autofill from paper and primary ink', () => {
+    const input = dark().components.MuiOutlinedInput.styleOverrides.input['&:-webkit-autofill'];
+    expect(input.WebkitBoxShadow).toBe('0 0 0 100px #1B2126 inset');
+    expect(input.WebkitTextFillColor).toBe('#E6EBEF');
+    expect(input.caretColor).toBe('#E6EBEF');
+  });
+});

package/tests/createAppThemeLightGuard.test.js

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+import { createAppTheme } from '../src/theme';
+
+const sortValue = (value) => {
+  if (typeof value === 'function') return String(value);
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortValue(value[key])]));
+  }
+  return value;
+};
+
+const fixture = JSON.parse(readFileSync(new URL('./fixtures/light-theme-baseline.json', import.meta.url)));
+
+function snapshot(baselinePalette = {}) {
+  return sortValue({
+    baseline: createAppTheme({ palette: { primary: { main: '#0F62FE' }, ...baselinePalette } }),
+    override: createAppTheme({
+      palette: {
+        primary: { main: '#0F62FE' },
+        background: { default: '#F0F2F4' },
+        success: { main: '#126B36' },
+      },
+      typography: { fontFamily: 'Fixture Sans' },
+    }),
+  });
+}
+
+describe('createAppTheme light regression guard', () => {
+  it('matches the pre-change serialized light themes exactly', () => {
+    expect(snapshot()).toEqual(fixture);
+  });
+
+  it('detects a changed light value', () => {
+    // Produced by the real factory: one different light value must differ from the fixture.
+    expect(snapshot({ background: { default: '#FAFBFC' } })).not.toEqual(fixture);
+  });
+});