@micha.bigler/ui-core-micha 3.9.1 → 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/checkKitIntegration.test.jsx

@@ -0,0 +1,219 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import i18next from 'i18next';
+import { I18nextProvider } from 'react-i18next';
+
+import apiClient from '../src/auth/apiClient';
+import { AuthContext } from '../src/auth/AuthContext';
+import { checkKitIntegration } from '../src/testing/checkKitIntegration';
+import { uiCoreTranslations } from '../src/i18n/uiCoreTranslations';
+import { LoginPage } from '../src/pages/LoginPage';
+
+const languages = ['de', 'en', 'fr', 'sw'];
+const authMethods = {
+  password_login: true,
+  password_reset: false,
+  signup: false,
+  signup_modes: [],
+  social_login: false,
+  passkey_login: false,
+};
+
+function resources() {
+  return Object.fromEntries(languages.map((language) => [language, {
+    translation: Object.fromEntries(
+      Object.entries(uiCoreTranslations).map(([key, values]) => [key, values[language]]),
+    ),
+  }]));
+}
+
+function makeWrapper(instance, authMethodsOverride = authMethods) {
+  return function FixtureWrapper({ children }) {
+    return (
+      <I18nextProvider i18n={instance}>
+        <AuthContext.Provider value={{
+          user: null,
+          loading: false,
+          login: vi.fn(),
+          authMethods: authMethodsOverride,
+        }}>
+          {children}
+        </AuthContext.Provider>
+      </I18nextProvider>
+    );
+  };
+}
+
+beforeAll(async () => {
+  globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+  await i18next.init({
+    lng: 'en',
+    fallbackLng: false,
+    supportedLngs: languages,
+    resources: resources(),
+    keySeparator: false,
+    nsSeparator: false,
+    interpolation: { escapeValue: false },
+  });
+});
+
+afterEach(async () => {
+  await i18next.changeLanguage('en');
+  for (const language of languages) {
+    i18next.removeResourceBundle(language, 'translation');
+    i18next.addResourceBundle(language, 'translation', resources()[language].translation, true, true);
+  }
+});
+
+describe('checkKitIntegration', () => {
+  it('passes for a correctly wired app fixture', async () => {
+    const { findings } = await checkKitIntegration({
+      i18n: i18next,
+      wrapper: makeWrapper(i18next),
+      pages: [LoginPage],
+    });
+
+    expect(findings).toEqual([]);
+  });
+
+  it('does not flag a legitimate short lowercase translated word as a raw backend code', async () => {
+    // Auth.LOGIN_OR's German value is literally "oder" -- all-lowercase, no
+    // spaces, length 4 -- the exact shape a naive raw-code heuristic would
+    // false-positive on. Render LoginForm's sign-up/forgot-password divider
+    // (onSignUp truthy) in German to actually exercise that rendered text.
+    await i18next.changeLanguage('de');
+    const { findings } = await checkKitIntegration({
+      i18n: i18next,
+      wrapper: makeWrapper(i18next, { ...authMethods, signup: true, signup_modes: ['self_signup_open'] }),
+      pages: [LoginPage],
+    });
+
+    expect(findings).toEqual([]);
+  });
+
+  it('reports one catalogue finding for one missing language key', async () => {
+    const key = 'Auth.field.email.invalid';
+    const french = { ...resources().fr.translation };
+    delete french[key];
+    i18next.removeResourceBundle('fr', 'translation');
+    i18next.addResourceBundle('fr', 'translation', french, true, true);
+
+    const { findings } = await checkKitIntegration({
+      i18n: i18next,
+      wrapper: makeWrapper(i18next),
+      pages: [],
+    });
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ check: 'catalogue' });
+    expect(findings[0].reason).toContain(`${key} for language fr`);
+  });
+
+  it('still reports a missing key when the consumer app configures a fallback language', async () => {
+    // A consumer typically sets fallbackLng (e.g. "en"), not "false" like the
+    // fixture above. Without forcing fallbackLng: false per-call, i18next's
+    // exists() would resolve the missing "fr" key through the fallback and
+    // read as present, masking the real gap this check exists to catch.
+    const key = 'Auth.field.email.invalid';
+    const french = { ...resources().fr.translation };
+    delete french[key];
+    i18next.removeResourceBundle('fr', 'translation');
+    i18next.addResourceBundle('fr', 'translation', french, true, true);
+    i18next.options.fallbackLng = 'en';
+
+    try {
+      const { findings } = await checkKitIntegration({
+        i18n: i18next,
+        wrapper: makeWrapper(i18next),
+        pages: [],
+      });
+
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toMatchObject({ check: 'catalogue' });
+      expect(findings[0].reason).toContain(`${key} for language fr`);
+    } finally {
+      i18next.options.fallbackLng = false;
+    }
+  });
+
+  it('reports when the app passes a separate i18next instance', async () => {
+    const separate = i18next.createInstance();
+    await separate.init({
+      lng: 'en',
+      fallbackLng: false,
+      supportedLngs: languages,
+      resources: resources(),
+      keySeparator: false,
+      nsSeparator: false,
+    });
+
+    const { findings } = await checkKitIntegration({
+      i18n: separate,
+      wrapper: makeWrapper(separate),
+      pages: [],
+    });
+
+    expect(findings.some(({ check }) => check === 'instance')).toBe(true);
+  });
+
+  it('reports a page when the consumer wrapper throws', async () => {
+    function ThrowingWrapper() {
+      throw new Error('provider exploded');
+    }
+
+    const before = apiClient.defaults.adapter;
+    const { findings } = await checkKitIntegration({
+      i18n: i18next,
+      wrapper: ThrowingWrapper,
+      pages: [LoginPage],
+    });
+
+    expect(findings.some(({ check, reason }) => check === 'render' && reason.includes('LoginPage'))).toBe(true);
+    expect(apiClient.defaults.adapter).toBe(before);
+  });
+
+  it('passes the exact invalid-email resolver regression through the real login page', async () => {
+    const { findings } = await checkKitIntegration({
+      i18n: i18next,
+      wrapper: makeWrapper(i18next),
+      pages: [],
+    });
+
+    expect(findings).toEqual([]);
+  });
+
+  it('restores the transport adapter after a successful check', async () => {
+    const before = apiClient.defaults.adapter;
+    await checkKitIntegration({
+      i18n: i18next,
+      wrapper: makeWrapper(i18next),
+      pages: [],
+    });
+    expect(apiClient.defaults.adapter).toBe(before);
+  });
+
+  it('no longer intercepts a real request once the check has finished', async () => {
+    // Proves the restore is functional, not just reference-equal: a request
+    // made AFTER the check completes must reach the app's own adapter, not
+    // the check's stub (which would reject it as "blocked" or fake a login
+    // failure for the allauth login path).
+    const sentinel = vi.fn().mockResolvedValue({ data: 'real-response', status: 200, headers: {}, config: {} });
+    const before = apiClient.defaults.adapter;
+    apiClient.defaults.adapter = sentinel;
+
+    try {
+      await checkKitIntegration({
+        i18n: i18next,
+        wrapper: makeWrapper(i18next),
+        pages: [],
+      });
+
+      const response = await apiClient.get('/api/some/path');
+      expect(sentinel).toHaveBeenCalled();
+      expect(response.data).toBe('real-response');
+    } finally {
+      apiClient.defaults.adapter = before;
+    }
+  });
+});