@aglyn/shared-ui-theme 1.0.0-beta.143

package/src/lib/util/accessible-shade.js

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { decomposeColor, hslToRgb, rgbToHex } from "../../vendor/mui.js";
+/** WCAG 2.x AA contrast bar for normal-size text. */ export const AA_TEXT_CONTRAST = 4.5;
+function srgbChannelToLinear(channel) {
+    const value = channel / 255;
+    return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+/**
+ * Exact WCAG relative luminance. MUI's `getLuminance` truncates to three
+ * digits, which is enough slop to misclassify a borderline shade either side
+ * of the 4.5:1 bar — the whole reason this module exists — so the math here
+ * keeps full precision. Alpha is ignored (this pipeline derives opaque
+ * tokens), matching MUI's behaviour for rgba inputs.
+ */ export function relativeLuminance(color) {
+    const decomposed = decomposeColor(color);
+    if (decomposed.type === 'color') {
+        // `color(display-p3 …)` values are not 0–255 channels; a caller that
+        // feeds these must handle its own contrast.
+        throw new Error(`accessible-shade: unsupported color format "${color}"`);
+    }
+    const values = decomposed.type.startsWith('hsl') ? decomposeColor(hslToRgb(color)).values : decomposed.values;
+    return 0.2126 * srgbChannelToLinear(values[0]) + 0.7152 * srgbChannelToLinear(values[1]) + 0.0722 * srgbChannelToLinear(values[2]);
+}
+/** Exact WCAG contrast ratio between two colors, 1–21. */ export function contrastRatio(colorA, colorB) {
+    const luminanceA = relativeLuminance(colorA);
+    const luminanceB = relativeLuminance(colorB);
+    return (Math.max(luminanceA, luminanceB) + 0.05) / (Math.min(luminanceA, luminanceB) + 0.05);
+}
+/** True when `foreground` clears `minContrast` against EVERY background. */ export function meetsContrast(foreground, backgrounds, minContrast = AA_TEXT_CONTRAST) {
+    return backgrounds.every((background)=>contrastRatio(foreground, background) >= minContrast);
+}
+/** [hue 0–360, saturation 0–1, lightness 0–1] */ function toHslValues(color) {
+    const decomposed = decomposeColor(color);
+    if (decomposed.type.startsWith('hsl')) {
+        const [h, s, l] = decomposed.values;
+        return [
+            h,
+            s / 100,
+            l / 100
+        ];
+    }
+    const r = decomposed.values[0] / 255;
+    const g = decomposed.values[1] / 255;
+    const b = decomposed.values[2] / 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const lightness = (max + min) / 2;
+    if (max === min) return [
+        0,
+        0,
+        lightness
+    ];
+    const delta = max - min;
+    const saturation = lightness > 0.5 ? delta / (2 - max - min) : delta / (max + min);
+    let hue;
+    if (max === r) hue = (g - b) / delta + (g < b ? 6 : 0);
+    else if (max === g) hue = (b - r) / delta + 2;
+    else hue = (r - g) / delta + 4;
+    return [
+        hue * 60,
+        saturation,
+        lightness
+    ];
+}
+function hslToHex(hue, saturation, lightness) {
+    return rgbToHex(hslToRgb(`hsl(${hue}, ${saturation * 100}%, ${lightness * 100}%)`));
+}
+/**
+ * Nearest shade of `color`, walking HSL lightness in `direction` only, that
+ * clears `minContrast` against every background (AGL-1297). Hue and
+ * saturation are held fixed so the result stays the same colour, just
+ * deeper or lighter.
+ *
+ * - If `color` already clears the bar, it is returned UNCHANGED —
+ *   byte-identical, so a value that was fine yesterday stays byte-stable.
+ * - The walk is one-directional: pass `'darken'` for a foreground on light
+ *   backgrounds, `'lighten'` for a foreground on dark backgrounds.
+ * - If the bar is unreachable in that direction (e.g. lightening against a
+ *   mid-grey), the walk stops at the pole (black/white) or the iteration
+ *   cap and returns that best-effort value rather than looping or
+ *   reversing direction.
+ */ export function accessibleShade(color, backgrounds, direction, options = {}) {
+    const { minContrast = AA_TEXT_CONTRAST, step = 0.01, maxSteps = 120 } = options;
+    if (!backgrounds.length || meetsContrast(color, backgrounds, minContrast)) {
+        return color;
+    }
+    const [hue, saturation, initialLightness] = toHslValues(color);
+    const delta = direction === 'lighten' ? step : -step;
+    let lightness = initialLightness;
+    let candidate = color;
+    for(let i = 0; i < maxSteps; i += 1){
+        lightness = Math.min(1, Math.max(0, lightness + delta));
+        candidate = hslToHex(hue, saturation, lightness);
+        if (meetsContrast(candidate, backgrounds, minContrast)) return candidate;
+        // Pole reached without clearing: nothing further exists in this
+        // direction, so return the extreme as the best effort.
+        if (lightness === 0 || lightness === 1) return candidate;
+    }
+    return candidate;
+}
+export default accessibleShade;
+
+//# sourceMappingURL=accessible-shade.js.map

package/src/lib/util/accessible-shade.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/theme/src/lib/util/accessible-shade.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { decomposeColor, hslToRgb, rgbToHex } from '../../vendor/mui'\n\n/** Ramp direction for a shade walk. */\nexport type ShadeDirection = 'darken' | 'lighten'\n\n/** WCAG 2.x AA contrast bar for normal-size text. */\nexport const AA_TEXT_CONTRAST = 4.5\n\nexport type AccessibleShadeOptions = {\n  /** Contrast every background must clear. Default {@link AA_TEXT_CONTRAST}. */\n  minContrast?: number\n  /** HSL lightness moved per iteration (0–1 scale). Default 0.01. */\n  step?: number\n  /**\n   * Iteration cap. The default covers the full lightness range at the\n   * default step with headroom, so the walk always terminates at a pole\n   * before hitting it in practice.\n   */\n  maxSteps?: number\n}\n\nfunction srgbChannelToLinear(channel: number): number {\n  const value = channel / 255\n  return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4\n}\n\n/**\n * Exact WCAG relative luminance. MUI's `getLuminance` truncates to three\n * digits, which is enough slop to misclassify a borderline shade either side\n * of the 4.5:1 bar — the whole reason this module exists — so the math here\n * keeps full precision. Alpha is ignored (this pipeline derives opaque\n * tokens), matching MUI's behaviour for rgba inputs.\n */\nexport function relativeLuminance(color: string): number {\n  const decomposed = decomposeColor(color)\n  if (decomposed.type === 'color') {\n    // `color(display-p3 …)` values are not 0–255 channels; a caller that\n    // feeds these must handle its own contrast.\n    throw new Error(`accessible-shade: unsupported color format \"${color}\"`)\n  }\n  const values = decomposed.type.startsWith('hsl')\n    ? decomposeColor(hslToRgb(color)).values\n    : decomposed.values\n  return (\n    0.2126 * srgbChannelToLinear(values[0]) +\n    0.7152 * srgbChannelToLinear(values[1]) +\n    0.0722 * srgbChannelToLinear(values[2])\n  )\n}\n\n/** Exact WCAG contrast ratio between two colors, 1–21. */\nexport function contrastRatio(colorA: string, colorB: string): number {\n  const luminanceA = relativeLuminance(colorA)\n  const luminanceB = relativeLuminance(colorB)\n  return (\n    (Math.max(luminanceA, luminanceB) + 0.05) /\n    (Math.min(luminanceA, luminanceB) + 0.05)\n  )\n}\n\n/** True when `foreground` clears `minContrast` against EVERY background. */\nexport function meetsContrast(\n  foreground: string,\n  backgrounds: ReadonlyArray<string>,\n  minContrast: number = AA_TEXT_CONTRAST,\n): boolean {\n  return backgrounds.every(\n    (background) => contrastRatio(foreground, background) >= minContrast,\n  )\n}\n\n/** [hue 0–360, saturation 0–1, lightness 0–1] */\nfunction toHslValues(color: string): [number, number, number] {\n  const decomposed = decomposeColor(color)\n  if (decomposed.type.startsWith('hsl')) {\n    const [h, s, l] = decomposed.values\n    return [h, s / 100, l / 100]\n  }\n  const r = decomposed.values[0] / 255\n  const g = decomposed.values[1] / 255\n  const b = decomposed.values[2] / 255\n  const max = Math.max(r, g, b)\n  const min = Math.min(r, g, b)\n  const lightness = (max + min) / 2\n  if (max === min) return [0, 0, lightness]\n  const delta = max - min\n  const saturation =\n    lightness > 0.5 ? delta / (2 - max - min) : delta / (max + min)\n  let hue: number\n  if (max === r) hue = (g - b) / delta + (g < b ? 6 : 0)\n  else if (max === g) hue = (b - r) / delta + 2\n  else hue = (r - g) / delta + 4\n  return [hue * 60, saturation, lightness]\n}\n\nfunction hslToHex(hue: number, saturation: number, lightness: number): string {\n  return rgbToHex(\n    hslToRgb(`hsl(${hue}, ${saturation * 100}%, ${lightness * 100}%)`),\n  )\n}\n\n/**\n * Nearest shade of `color`, walking HSL lightness in `direction` only, that\n * clears `minContrast` against every background (AGL-1297). Hue and\n * saturation are held fixed so the result stays the same colour, just\n * deeper or lighter.\n *\n * - If `color` already clears the bar, it is returned UNCHANGED —\n *   byte-identical, so a value that was fine yesterday stays byte-stable.\n * - The walk is one-directional: pass `'darken'` for a foreground on light\n *   backgrounds, `'lighten'` for a foreground on dark backgrounds.\n * - If the bar is unreachable in that direction (e.g. lightening against a\n *   mid-grey), the walk stops at the pole (black/white) or the iteration\n *   cap and returns that best-effort value rather than looping or\n *   reversing direction.\n */\nexport function accessibleShade(\n  color: string,\n  backgrounds: ReadonlyArray<string>,\n  direction: ShadeDirection,\n  options: AccessibleShadeOptions = {},\n): string {\n  const {\n    minContrast = AA_TEXT_CONTRAST,\n    step = 0.01,\n    maxSteps = 120,\n  } = options\n  if (!backgrounds.length || meetsContrast(color, backgrounds, minContrast)) {\n    return color\n  }\n  const [hue, saturation, initialLightness] = toHslValues(color)\n  const delta = direction === 'lighten' ? step : -step\n  let lightness = initialLightness\n  let candidate = color\n  for (let i = 0; i < maxSteps; i += 1) {\n    lightness = Math.min(1, Math.max(0, lightness + delta))\n    candidate = hslToHex(hue, saturation, lightness)\n    if (meetsContrast(candidate, backgrounds, minContrast)) return candidate\n    // Pole reached without clearing: nothing further exists in this\n    // direction, so return the extreme as the best effort.\n    if (lightness === 0 || lightness === 1) return candidate\n  }\n  return candidate\n}\n\nexport default accessibleShade\n"],"names":["decomposeColor","hslToRgb","rgbToHex","AA_TEXT_CONTRAST","srgbChannelToLinear","channel","value","relativeLuminance","color","decomposed","type","Error","values","startsWith","contrastRatio","colorA","colorB","luminanceA","luminanceB","Math","max","min","meetsContrast","foreground","backgrounds","minContrast","every","background","toHslValues","h","s","l","r","g","b","lightness","delta","saturation","hue","hslToHex","accessibleShade","direction","options","step","maxSteps","length","initialLightness","candidate","i"],"mappings":"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"}

package/src/lib/util/color-scheme-hint.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ThemeMode } from '../hocs/create-with-theme-provider';
+/**
+ * The device's own light/dark preference, carried on the request.
+ *
+ * `prefers-color-scheme` is a media feature, and a media feature is a browser
+ * fact: a server render has no viewport to evaluate it against, so
+ * `useMediaQuery` reports light for every visitor whose device is dark. This
+ * user-agent client hint is the same preference in a form the server CAN read
+ * — the browser puts it on the request, so a visitor following their device
+ * gets their scheme in the first byte rather than a light document that
+ * repaints once React has hydrated the whole page.
+ *
+ * A browser sends it only where the origin asked for it, and the tenant
+ * middleware is what asks — it advertises this same token in `Accept-CH` and
+ * `Critical-CH` and splits its cache on it in `Vary`, from a copy of its own,
+ * since an edge bundle takes no library imports. Reading the request header by
+ * this constant is safe whatever the transport did to the casing: `Headers`
+ * matches case-insensitively.
+ *
+ * ⚠️ CHROMIUM ONLY. Firefox and Safari implement neither this hint nor the
+ * `Accept-CH` negotiation that asks for it, so on those browsers the header is
+ * simply absent and the scheme settles once the page has hydrated. Absence is
+ * therefore an ordinary answer, never an error: every reader must have a
+ * behavior for "the request did not say".
+ *
+ * Nothing in this module imports React, MUI or `js-cookie`, and its one import
+ * is a type erased at compile time. That is what lets a Server Component take
+ * it without pulling the theme library's context providers into the RSC graph
+ * — the same reason `util/theme-mode-cookie`, `util/emotion-cache` and
+ * `util/host-theme` are deep-imported rather than taken from the barrel.
+ */
+export declare const COLOR_SCHEME_HINT_HEADER = "Sec-CH-Prefers-Color-Scheme";
+/**
+ * A `Sec-CH-Prefers-Color-Scheme` request-header value as a theme mode.
+ *
+ * Only `light` and `dark` are schemes; anything else — a header the browser
+ * never sent, a value from a future revision of the media feature — is `null`,
+ * meaning "the request named no scheme, fall back to the browser's own answer
+ * once there is one". A caller that mistook an unknown value for light would
+ * pin a dark device to the wrong scheme for the whole render.
+ *
+ * The value is a structured-field string, so it may arrive quoted (`"dark"`);
+ * the quotes are stripped and the token is compared case-insensitively so one
+ * parser reads every spelling a conforming user agent may send.
+ *
+ * This is the device-preference counterpart to `parseThemeModeCookie`, which
+ * reads the visitor's EXPLICIT choice off the same request. The two are
+ * separate answers on purpose and are never merged here: a stated preference
+ * outranks a device default, and the layering that enforces that lives in
+ * `useThemeModeState`, where the switcher can still tell them apart.
+ */
+export declare function parseColorSchemeHint(value: string | undefined | null): ThemeMode;

package/src/lib/util/color-scheme-hint.js

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The device's own light/dark preference, carried on the request.
+ *
+ * `prefers-color-scheme` is a media feature, and a media feature is a browser
+ * fact: a server render has no viewport to evaluate it against, so
+ * `useMediaQuery` reports light for every visitor whose device is dark. This
+ * user-agent client hint is the same preference in a form the server CAN read
+ * — the browser puts it on the request, so a visitor following their device
+ * gets their scheme in the first byte rather than a light document that
+ * repaints once React has hydrated the whole page.
+ *
+ * A browser sends it only where the origin asked for it, and the tenant
+ * middleware is what asks — it advertises this same token in `Accept-CH` and
+ * `Critical-CH` and splits its cache on it in `Vary`, from a copy of its own,
+ * since an edge bundle takes no library imports. Reading the request header by
+ * this constant is safe whatever the transport did to the casing: `Headers`
+ * matches case-insensitively.
+ *
+ * ⚠️ CHROMIUM ONLY. Firefox and Safari implement neither this hint nor the
+ * `Accept-CH` negotiation that asks for it, so on those browsers the header is
+ * simply absent and the scheme settles once the page has hydrated. Absence is
+ * therefore an ordinary answer, never an error: every reader must have a
+ * behavior for "the request did not say".
+ *
+ * Nothing in this module imports React, MUI or `js-cookie`, and its one import
+ * is a type erased at compile time. That is what lets a Server Component take
+ * it without pulling the theme library's context providers into the RSC graph
+ * — the same reason `util/theme-mode-cookie`, `util/emotion-cache` and
+ * `util/host-theme` are deep-imported rather than taken from the barrel.
+ */ export const COLOR_SCHEME_HINT_HEADER = 'Sec-CH-Prefers-Color-Scheme';
+/**
+ * A `Sec-CH-Prefers-Color-Scheme` request-header value as a theme mode.
+ *
+ * Only `light` and `dark` are schemes; anything else — a header the browser
+ * never sent, a value from a future revision of the media feature — is `null`,
+ * meaning "the request named no scheme, fall back to the browser's own answer
+ * once there is one". A caller that mistook an unknown value for light would
+ * pin a dark device to the wrong scheme for the whole render.
+ *
+ * The value is a structured-field string, so it may arrive quoted (`"dark"`);
+ * the quotes are stripped and the token is compared case-insensitively so one
+ * parser reads every spelling a conforming user agent may send.
+ *
+ * This is the device-preference counterpart to `parseThemeModeCookie`, which
+ * reads the visitor's EXPLICIT choice off the same request. The two are
+ * separate answers on purpose and are never merged here: a stated preference
+ * outranks a device default, and the layering that enforces that lives in
+ * `useThemeModeState`, where the switcher can still tell them apart.
+ */ export function parseColorSchemeHint(value) {
+    const scheme = value == null ? void 0 : value.trim().replace(/^"|"$/g, '').toLowerCase();
+    return scheme === 'dark' || scheme === 'light' ? scheme : null;
+}
+
+//# sourceMappingURL=color-scheme-hint.js.map

package/src/lib/util/color-scheme-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/theme/src/lib/util/color-scheme-hint.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { ThemeMode } from '../hocs/create-with-theme-provider'\n\n/**\n * The device's own light/dark preference, carried on the request.\n *\n * `prefers-color-scheme` is a media feature, and a media feature is a browser\n * fact: a server render has no viewport to evaluate it against, so\n * `useMediaQuery` reports light for every visitor whose device is dark. This\n * user-agent client hint is the same preference in a form the server CAN read\n * — the browser puts it on the request, so a visitor following their device\n * gets their scheme in the first byte rather than a light document that\n * repaints once React has hydrated the whole page.\n *\n * A browser sends it only where the origin asked for it, and the tenant\n * middleware is what asks — it advertises this same token in `Accept-CH` and\n * `Critical-CH` and splits its cache on it in `Vary`, from a copy of its own,\n * since an edge bundle takes no library imports. Reading the request header by\n * this constant is safe whatever the transport did to the casing: `Headers`\n * matches case-insensitively.\n *\n * ⚠️ CHROMIUM ONLY. Firefox and Safari implement neither this hint nor the\n * `Accept-CH` negotiation that asks for it, so on those browsers the header is\n * simply absent and the scheme settles once the page has hydrated. Absence is\n * therefore an ordinary answer, never an error: every reader must have a\n * behavior for \"the request did not say\".\n *\n * Nothing in this module imports React, MUI or `js-cookie`, and its one import\n * is a type erased at compile time. That is what lets a Server Component take\n * it without pulling the theme library's context providers into the RSC graph\n * — the same reason `util/theme-mode-cookie`, `util/emotion-cache` and\n * `util/host-theme` are deep-imported rather than taken from the barrel.\n */\nexport const COLOR_SCHEME_HINT_HEADER = 'Sec-CH-Prefers-Color-Scheme'\n\n/**\n * A `Sec-CH-Prefers-Color-Scheme` request-header value as a theme mode.\n *\n * Only `light` and `dark` are schemes; anything else — a header the browser\n * never sent, a value from a future revision of the media feature — is `null`,\n * meaning \"the request named no scheme, fall back to the browser's own answer\n * once there is one\". A caller that mistook an unknown value for light would\n * pin a dark device to the wrong scheme for the whole render.\n *\n * The value is a structured-field string, so it may arrive quoted (`\"dark\"`);\n * the quotes are stripped and the token is compared case-insensitively so one\n * parser reads every spelling a conforming user agent may send.\n *\n * This is the device-preference counterpart to `parseThemeModeCookie`, which\n * reads the visitor's EXPLICIT choice off the same request. The two are\n * separate answers on purpose and are never merged here: a stated preference\n * outranks a device default, and the layering that enforces that lives in\n * `useThemeModeState`, where the switcher can still tell them apart.\n */\nexport function parseColorSchemeHint(\n  value: string | undefined | null,\n): ThemeMode {\n  const scheme = value?.trim().replace(/^\"|\"$/g, '').toLowerCase()\n  return scheme === 'dark' || scheme === 'light' ? scheme : null\n}\n"],"names":["COLOR_SCHEME_HINT_HEADER","parseColorSchemeHint","value","scheme","trim","replace","toLowerCase"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GACD,OAAO,MAAMA,2BAA2B,8BAA6B;AAErE;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASC,qBACdC,KAAgC;IAEhC,MAAMC,SAASD,yBAAAA,MAAOE,IAAI,GAAGC,OAAO,CAAC,UAAU,IAAIC,WAAW;IAC9D,OAAOH,WAAW,UAAUA,WAAW,UAAUA,SAAS;AAC5D"}

package/src/lib/util/create-responsive-theme.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2024 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { CssVarsThemeOptions } from '@mui/material/styles';
+import { responsiveFontSizes, type Theme, type ThemeOptions } from '../../vendor/mui';
+export type CreateResponsiveThemeOptions = {
+    themeOptions?: ThemeOptions;
+    responsiveFontSizesOptions?: Parameters<typeof responsiveFontSizes>[1];
+};
+/**
+ * START EXAMPLE – OVERRIDE DEFAULT PROPS ↓
+ * ⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄
+ * ```typescript
+ * const theme = createMuiTheme({
+ *   props: {
+ *     // Name of the component ⚛️
+ *     MuiButtonBase: {
+ *       // The default props to change
+ *       disableRipple: true, // No more ripple, on the whole application 💣!
+ *     },
+ *   },
+ * })
+ * ```
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * END EXAMPLE – OVERRIDE DEFAULT PROPS ↑
+ *
+ * START EXAMPLE – OVERRIDE DEFAULT STYLES ↓
+ * ⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄
+ * ```typescript
+ * const theme = createMuiTheme({
+ *   overrides: {
+ *     // Style sheet name ⚛️
+ *     MuiButton: {
+ *       // Name of the rule
+ *       text: {
+ *         // Some CSS
+ *         color: 'white',
+ *       },
+ *     },
+ *     MuiCssBaseline: {
+ *       '@global': {
+ *         html: {
+ *           WebkitFontSmoothing: 'auto',
+ *         },
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * END EXAMPLE – OVERRIDE DEFAULT STYLES ↑
+ *
+ * @param {ThemeOptions} options
+ * @returns {Theme}
+ */
+export declare function createResponsiveTheme(options: CreateResponsiveThemeOptions): Theme;
+export declare function createResponsiveCssVarTheme(light: Theme, dark: Theme, options?: CssVarsThemeOptions): Omit<Theme, "applyStyles"> & import("@mui/material").CssVarsTheme;
+export default createResponsiveTheme;

package/src/lib/util/create-responsive-theme.js

@@ -0,0 +1,287 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * @license
+ * Copyright 2024 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { extendTheme as muiExtendTheme } from "@mui/material/styles";
+import { createTheme, darken, getContrastRatio, lighten, responsiveFontSizes } from "../../vendor/mui.js";
+import { accessibleShade, contrastRatio, meetsContrast } from "./accessible-shade.js";
+var ContrastText = /*#__PURE__*/ function(ContrastText) {
+    ContrastText["LIGHT"] = "rgba(0, 0, 0, 0.87)";
+    ContrastText["DARK"] = "#FFFFFF";
+    return ContrastText;
+}(ContrastText || {});
+function resolveTonalOffsets(tonalOffset) {
+    var _ref, _ref1, _ref2;
+    const offsetObj = typeof tonalOffset === 'number' ? undefined : tonalOffset;
+    const offsetNum = typeof tonalOffset === 'number' ? tonalOffset : undefined;
+    return {
+        light: (_ref = (_ref1 = offsetObj == null ? void 0 : offsetObj.light) != null ? _ref1 : offsetNum) != null ? _ref : 0.2,
+        dark: (_ref2 = offsetObj == null ? void 0 : offsetObj.dark) != null ? _ref2 : (offsetNum != null ? offsetNum : 0.2) * 1.5
+    };
+}
+function getContrastTextColor(background, contrastThreshold) {
+    return getContrastRatio(background, "#FFFFFF") >= (contrastThreshold != null ? contrastThreshold : 3) ? "#FFFFFF" : "rgba(0, 0, 0, 0.87)";
+}
+function addShade(paletteColor, shade, variant, tonalOffset) {
+    // Custom palette colors (tertiary, surface) are optional in host themes.
+    if (!(paletteColor == null ? void 0 : paletteColor.main)) return;
+    const { light: tonalOffsetLight, dark: tonalOffsetDark } = resolveTonalOffsets(tonalOffset);
+    const indexed = paletteColor;
+    if (!indexed[shade]) {
+        // eslint-disable-next-line no-prototype-builtins
+        if (paletteColor.hasOwnProperty(variant)) {
+            indexed[shade] = indexed[variant];
+        } else if (shade === 'light') {
+            paletteColor.light = lighten(paletteColor.main, tonalOffsetLight);
+        } else if (shade === 'dark') {
+            paletteColor.dark = darken(paletteColor.main, tonalOffsetDark);
+        } else if (shade === 'contrastText') {
+            paletteColor.contrastText = getContrastTextColor(paletteColor.main, tonalOffsetDark);
+        }
+    }
+}
+function addShadeVariants(paletteColor, tonalOffset) {
+    addShade(paletteColor, 'dark', undefined, tonalOffset);
+    addShade(paletteColor, 'light', undefined, tonalOffset);
+    addShade(paletteColor, 'contrastText', undefined, tonalOffset);
+}
+/**
+ * Colour families whose shades act as FOREGROUNDS — the `dark` slot carries
+ * "accessible accent text" (AGL-1293 put the marketing brand blue there), so
+ * its derivation must clear AA against the scheme's real backgrounds.
+ *
+ * `surface` is deliberately absent: its `light`/`dark` are surface STEPS
+ * (panel fills, borders — see the designer's box styler), and walking them to
+ * text contrast would repaint layout chrome, not fix any text.
+ */ const FOREGROUND_COLOR_KEYS = [
+    'primary',
+    'secondary',
+    'tertiary',
+    'error',
+    'warning',
+    'info',
+    'success'
+];
+/** `contrastText` IS a text pairing wherever it lives, so `surface` joins here. */ const CONTRAST_TEXT_COLOR_KEYS = [
+    ...FOREGROUND_COLOR_KEYS,
+    'surface'
+];
+/**
+ * Post-`createTheme` pass making DERIVED shades scheme- and AA-aware
+ * (AGL-1297). Fixed tonal offsets derive `dark = darken(main, 0.3)` no
+ * matter the scheme, which (a) misses 4.5:1 on real off-white surfaces and
+ * (b) points the wrong way entirely in dark mode, where the accessible
+ * direction for a foreground shade is LIGHTER.
+ *
+ * Invariants:
+ * - Only slots ABSENT from the caller's `palette` input are ever touched;
+ *   an explicitly authored shade passes through byte-identical (the
+ *   marketing host's hand-set `primary.dark` values depend on this).
+ * - A derived value that already clears 4.5:1 against both
+ *   `background.default` and `background.paper` is kept byte-identical, so
+ *   themes that were fine yesterday do not shift.
+ * - A failing derived `dark` is re-seeded at the tonal offset from `main`
+ *   in the scheme's foreground direction (darken in light, lighten in
+ *   dark), then walked in HSL lightness until it clears the bar.
+ * - A light-scheme `light` is a background TINT — its ramp direction points
+ *   away from the text bar by design — so it keeps the tonal derivation.
+ *   In dark schemes `light` is foreground-capable and gets the same walk.
+ * - Derived `contrastText` keeps the threshold choice unless that pairing
+ *   is below 4.5:1 against `main`; then it walks toward the pole with more
+ *   contrast headroom.
+ */ function ensureAccessibleShades(theme, inputPalette) {
+    var _palette_background, _palette_background1;
+    const { palette } = theme;
+    const backgrounds = [
+        (_palette_background = palette.background) == null ? void 0 : _palette_background.default,
+        (_palette_background1 = palette.background) == null ? void 0 : _palette_background1.paper
+    ].filter((background)=>typeof background === 'string');
+    if (!backgrounds.length) return;
+    const mode = palette.mode === 'dark' ? 'dark' : 'light';
+    const foregroundDirection = mode === 'dark' ? 'lighten' : 'darken';
+    const tonalOffsetDark = resolveTonalOffsets(palette.tonalOffset).dark;
+    const providedColors = inputPalette;
+    for (const key of CONTRAST_TEXT_COLOR_KEYS){
+        const color = palette[key];
+        if (!color || typeof color.main !== 'string') continue;
+        const provided = providedColors == null ? void 0 : providedColors[key];
+        // A ColorPartial ramp (`{ 50…900 }`) is an author-owned scale — MUI maps
+        // its shades straight across, so nothing in it counts as derived.
+        if (provided && typeof provided === 'object' && !('main' in provided)) {
+            continue;
+        }
+        // Read with brackets, not dots: these keys come from an index signature,
+        // and `json-editor` compiles this file under
+        // `noPropertyAccessFromIndexSignature` (paths resolve to source, so a
+        // consumer's flags check its dependencies). Dot access reds that build
+        // while this project's own stays green — AGL-1323.
+        const explicit = provided != null ? provided : {};
+        const isForeground = FOREGROUND_COLOR_KEYS.includes(key);
+        try {
+            if (isForeground && !explicit['dark'] && typeof color.dark === 'string' && !meetsContrast(color.dark, backgrounds)) {
+                const seed = mode === 'dark' ? lighten(color.main, tonalOffsetDark) : color.dark;
+                color.dark = accessibleShade(seed, backgrounds, foregroundDirection);
+            }
+            if (isForeground && mode === 'dark' && !explicit['light'] && typeof color.light === 'string' && !meetsContrast(color.light, backgrounds)) {
+                color.light = accessibleShade(color.light, backgrounds, 'lighten');
+            }
+            if (!explicit['contrastText'] && typeof color.contrastText === 'string' && !meetsContrast(color.contrastText, [
+                color.main
+            ])) {
+                const textDirection = contrastRatio('#fff', color.main) >= contrastRatio('#000', color.main) ? 'lighten' : 'darken';
+                color.contrastText = accessibleShade(color.contrastText, [
+                    color.main
+                ], textDirection);
+            }
+        } catch (unused) {
+        // Unparseable colour (CSS variable, color-mix()): leave the derived
+        // value alone rather than failing theme creation.
+        }
+    }
+}
+/**
+ * MUI's own default `responsiveFontSizes` variant list, spelled out because
+ * passing `variants` replaces it rather than extending it.
+ */ const RAMPED_MUI_VARIANTS = [
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'subtitle1',
+    'subtitle2',
+    'body1',
+    'body2',
+    'caption',
+    'button',
+    'overline'
+];
+/**
+ * The brand's custom display rungs, which MUI cannot know about.
+ *
+ * Only variants whose size genuinely needs to shrink belong here. `lede`,
+ * `bodyCompact` and `micro` are body-scale text that reads the same at every
+ * width and are deliberately absent.
+ */ const RAMPED_DISPLAY_VARIANTS = [
+    'displayXl'
+];
+/**
+ * START EXAMPLE – OVERRIDE DEFAULT PROPS ↓
+ * ⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄
+ * ```typescript
+ * const theme = createMuiTheme({
+ *   props: {
+ *     // Name of the component ⚛️
+ *     MuiButtonBase: {
+ *       // The default props to change
+ *       disableRipple: true, // No more ripple, on the whole application 💣!
+ *     },
+ *   },
+ * })
+ * ```
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * END EXAMPLE – OVERRIDE DEFAULT PROPS ↑
+ *
+ * START EXAMPLE – OVERRIDE DEFAULT STYLES ↓
+ * ⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄
+ * ```typescript
+ * const theme = createMuiTheme({
+ *   overrides: {
+ *     // Style sheet name ⚛️
+ *     MuiButton: {
+ *       // Name of the rule
+ *       text: {
+ *         // Some CSS
+ *         color: 'white',
+ *       },
+ *     },
+ *     MuiCssBaseline: {
+ *       '@global': {
+ *         html: {
+ *           WebkitFontSmoothing: 'auto',
+ *         },
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * END EXAMPLE – OVERRIDE DEFAULT STYLES ↑
+ *
+ * @param {ThemeOptions} options
+ * @returns {Theme}
+ */ export function createResponsiveTheme(options) {
+    const { themeOptions, responsiveFontSizesOptions } = options;
+    let theme = createTheme(themeOptions);
+    addShadeVariants(theme.palette.tertiary, theme.palette.tonalOffset);
+    addShadeVariants(theme.palette.surface, theme.palette.tonalOffset);
+    // `tint` is deliberately absent from BOTH shade passes (AGL-1244). It is a
+    // group of string leaves rather than a PaletteColor — no `main` to ramp
+    // from, no `contrastText` to pair — so `addShadeVariants` would no-op and
+    // `ensureAccessibleShades` (which keys off `CONTRAST_TEXT_COLOR_KEYS`) never
+    // sees it. Both correct: a 90%-desaturated wash is authored, not derived,
+    // and walking it to a text-contrast bar would repaint the fill.
+    // Scheme- and AA-aware repair of DERIVED shades only (AGL-1297); explicit
+    // palette values pass through byte-identical.
+    ensureAccessibleShades(theme, themeOptions == null ? void 0 : themeOptions.palette);
+    theme = responsiveFontSizes(theme, _extends({
+        // Override to include `xs` and `xl` - default: ['sm', 'md', 'lg']
+        breakpoints: [
+            'xs',
+            'sm',
+            'md',
+            'lg',
+            'xl'
+        ],
+        // MUI only ramps the variants it ships, so a CUSTOM display variant would
+        // keep its desktop size on a phone — `displayXl` at 72px on a 375px
+        // screen. Passing `variants` REPLACES MUI's default list, so the defaults
+        // are spelled out here and ours appended; drop one and that variant
+        // silently stops scaling.
+        variants: [
+            ...RAMPED_MUI_VARIANTS,
+            ...RAMPED_DISPLAY_VARIANTS
+        ]
+    }, responsiveFontSizesOptions));
+    return theme;
+}
+export function createResponsiveCssVarTheme(light, dark, options) {
+    var _ref, _ref1;
+    var _options_colorSchemes, _options_colorSchemes1;
+    const { palette: lightPalette } = light, lightTheme = _object_without_properties_loose(light, [
+        "palette"
+    ]);
+    const { palette: darkPalette } = dark;
+    return muiExtendTheme(_extends({}, lightTheme, {
+        // Allow setMode() to work by driving the color scheme via a CSS class on
+        // <html> instead of the OS-level @media query (the default 'media' selector
+        // makes setMode() a no-op because media queries can't be overridden in JS).
+        colorSchemeSelector: 'class'
+    }, options, {
+        colorSchemes: _extends({}, options == null ? void 0 : options.colorSchemes, {
+            light: _extends({
+                palette: lightPalette
+            }, (_ref = options == null ? void 0 : (_options_colorSchemes = options.colorSchemes) == null ? void 0 : _options_colorSchemes.light) != null ? _ref : {}),
+            dark: _extends({
+                palette: darkPalette
+            }, (_ref1 = options == null ? void 0 : (_options_colorSchemes1 = options.colorSchemes) == null ? void 0 : _options_colorSchemes1.dark) != null ? _ref1 : {})
+        })
+    }));
+}
+export default createResponsiveTheme;
+
+//# sourceMappingURL=create-responsive-theme.js.map