react-mcu 1.1.0 → 1.2.0

package/README.md

@@ -15,6 +15,27 @@ m3 references:
 | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [<img width="2836" height="2266" alt="CleanShot 2026-01-14 at 08 58 40@2x" src="https://github.com/user-attachments/assets/e4b47c00-716f-4b08-b393-de306d5ce302" />](https://material-foundation.github.io/material-theme-builder/) | [<img width="2836" height="2266" alt="CleanShot 2026-01-14 at 09 01 23@2x" src="https://github.com/user-attachments/assets/826e502d-e173-43c4-807a-53d0ba075a88" />](https://m3.material.io/styles/color/roles) |
 
+Support for:
+
+Base (like in the Builder):
+
+- [x] light/dark mode
+- [x] source color
+- [x] scheme
+- [x] contrast
+- [x] core-colors overrides: primary, secondary, tertiary, error, neutral,
+      neutralVariant
+- [x] custom-colors (aka. "Extended colors")
+  - [x] Harmonization (aka. `blend`) -- with effective color: `source` or
+        `primary` if defined
+- [x] Shades (aka. "tonals")
+- [ ] colorMatch
+
+Extra:
+
+- [x] `contrastAllColors`: contrast also applies to custom-colors and shades
+      (not only the core-colors)
+
 # Usage
 
 ```tsx

package/dist/index.d.ts

@@ -28,10 +28,30 @@ type McuConfig = {
      * When true, stays true to input colors without harmonization.
      * When false (default), colors may be adjusted for better harmonization.
      * Corresponds to "Color match - Stay true to my color inputs" in Material Theme Builder.
+     *
+     * @default false
+     * @deprecated Not yet implemented. This prop is currently ignored.
      */
     colorMatch?: boolean;
-    /** Array of custom colors to include in the generated palette */
+    /**
+     * Array of custom colors to include in the generated palette.
+     *
+     * @example
+     * ```ts
+     * customColors={[
+     *   { name: "brand", hex: "#FF5733", blend: true },
+     *   { name: "success", hex: "#28A745", blend: false }
+     * ]}
+     * ```
+     */
     customColors?: HexCustomColor[];
+    /**
+     * When true, applies the contrast level to all colors including custom colors and tonal palette shades.
+     * When false (default), only core colors are affected by the contrast level.
+     *
+     * @default false
+     */
+    contrastAllColors?: boolean;
 };
 declare const schemesMap: {
     readonly tonalSpot: typeof SchemeTonalSpot;
@@ -44,7 +64,7 @@ declare const schemesMap: {
 };
 declare const schemeNames: (keyof typeof schemesMap)[];
 type SchemeName = (typeof schemeNames)[number];
-declare function Mcu({ source, scheme, contrast, primary, secondary, tertiary, neutral, neutralVariant, error, colorMatch, customColors, children, }: McuConfig & {
+declare function Mcu({ source, scheme, contrast, primary, secondary, tertiary, neutral, neutralVariant, error, colorMatch, customColors, contrastAllColors, children, }: McuConfig & {
     children?: React.ReactNode;
 }): react_jsx_runtime.JSX.Element;
 declare const tokenNames: readonly ["background", "onBackground", "surface", "surfaceDim", "surfaceBright", "surfaceContainerLowest", "surfaceContainerLow", "surfaceContainer", "surfaceContainerHigh", "surfaceContainerHighest", "onSurface", "onSurfaceVariant", "outline", "outlineVariant", "inverseSurface", "inverseOnSurface", "primary", "onPrimary", "primaryContainer", "onPrimaryContainer", "primaryFixed", "primaryFixedDim", "onPrimaryFixed", "onPrimaryFixedVariant", "inversePrimary", "primaryFixed", "primaryFixedDim", "onPrimaryFixed", "onPrimaryFixedVariant", "secondary", "onSecondary", "secondaryContainer", "onSecondaryContainer", "secondaryFixed", "secondaryFixedDim", "onSecondaryFixed", "onSecondaryFixedVariant", "tertiary", "onTertiary", "tertiaryContainer", "onTertiaryContainer", "tertiaryFixed", "tertiaryFixedDim", "onTertiaryFixed", "onTertiaryFixedVariant", "error", "onError", "errorContainer", "onErrorContainer", "scrim", "shadow"];

package/dist/index.js

@@ -3,8 +3,8 @@
 // src/Mcu.tsx
 import {
   argbFromHex,
-  CorePalette,
-  customColor,
+  Blend,
+  DynamicColor,
   DynamicScheme,
   Hct,
   hexFromArgb as hexFromArgb2,
@@ -52,6 +52,7 @@ var McuProvider = ({
   scheme: initialScheme,
   contrast: initialContrast,
   customColors: initialCustomColors,
+  contrastAllColors: initialContrastAllColors,
   styleId,
   children
 }) => {
@@ -59,7 +60,8 @@ var McuProvider = ({
     source: initialSource,
     scheme: initialScheme,
     contrast: initialContrast,
-    customColors: initialCustomColors
+    customColors: initialCustomColors,
+    contrastAllColors: initialContrastAllColors
   }));
   const [mcuConfig, setMcuConfig] = useState(initials);
   const { css, mergedColorsLight, mergedColorsDark } = useMemo(
@@ -96,6 +98,16 @@ var McuProvider = ({
 
 // src/Mcu.tsx
 import { Fragment, jsx as jsx2, jsxs } from "react/jsx-runtime";
+function adjustToneForContrast(baseTone, contrastLevel, isDark, adjustmentFactor = DEFAULT_CONTRAST_ADJUSTMENT_FACTOR) {
+  if (contrastLevel === 0) return baseTone;
+  let adjustedTone;
+  if (isDark) {
+    adjustedTone = baseTone + contrastLevel * (100 - baseTone) * adjustmentFactor;
+  } else {
+    adjustedTone = baseTone - contrastLevel * baseTone * adjustmentFactor;
+  }
+  return Math.max(0, Math.min(100, adjustedTone));
+}
 var schemesMap = {
   tonalSpot: SchemeTonalSpot,
   monochrome: SchemeMonochrome,
@@ -112,6 +124,9 @@ var DEFAULT_SCHEME = "tonalSpot";
 var DEFAULT_CONTRAST = 0;
 var DEFAULT_COLOR_MATCH = false;
 var DEFAULT_CUSTOM_COLORS = [];
+var DEFAULT_CONTRAST_ALL_COLORS = false;
+var DEFAULT_BLEND = true;
+var DEFAULT_CONTRAST_ADJUSTMENT_FACTOR = 0.2;
 var STANDARD_TONES = [
   0,
   5,
@@ -165,6 +180,7 @@ function Mcu({
   error,
   colorMatch = DEFAULT_COLOR_MATCH,
   customColors = DEFAULT_CUSTOM_COLORS,
+  contrastAllColors = DEFAULT_CONTRAST_ALL_COLORS,
   children
 }) {
   const config = useMemo2(
@@ -179,7 +195,9 @@ function Mcu({
       neutralVariant,
       error,
       colorMatch,
-      customColors
+      customColors,
+      // extras features
+      contrastAllColors
     }),
     [
       contrast,
@@ -192,7 +210,8 @@ function Mcu({
       neutral,
       neutralVariant,
       error,
-      colorMatch
+      colorMatch,
+      contrastAllColors
     ]
   );
   const { css } = useMemo2(() => generateCss(config), [config]);
@@ -270,22 +289,63 @@ function toRecord(arr, getEntry) {
     {}
   );
 }
-function mergeBaseAndCustomColors(scheme, customColors, sourceArgb) {
+function getPalette(palettes, colorName) {
+  const palette = palettes[colorName];
+  if (!palette) {
+    throw new Error(
+      `Custom color palette not found for '${colorName}'. This is likely a bug in the implementation.`
+    );
+  }
+  return palette;
+}
+function mergeBaseAndCustomColors(scheme, customColors, colorPalettes, contrastAllColors) {
   const baseVars = toRecord(tokenNames, (tokenName) => {
     const dynamicColor = MaterialDynamicColors[tokenName];
     const argb = dynamicColor.getArgb(scheme);
     return [tokenName, argb];
   });
   const customVars = {};
-  const isDark = scheme.isDark;
   customColors.forEach((color) => {
-    const customColorGroup = customColor(sourceArgb, color);
-    const colorGroup = isDark ? customColorGroup.dark : customColorGroup.light;
     const colorname = color.name;
-    customVars[colorname] = colorGroup.color;
-    customVars[`on${upperFirst(colorname)}`] = colorGroup.onColor;
-    customVars[`${colorname}Container`] = colorGroup.colorContainer;
-    customVars[`on${upperFirst(colorname)}Container`] = colorGroup.onColorContainer;
+    const getPaletteForColor = (s) => getPalette(colorPalettes, colorname);
+    const getTone = (baseTone) => (s) => {
+      if (!contrastAllColors) return baseTone;
+      return adjustToneForContrast(baseTone, s.contrastLevel, s.isDark);
+    };
+    const colorDynamicColor = new DynamicColor(
+      colorname,
+      getPaletteForColor,
+      (s) => getTone(s.isDark ? 80 : 40)(s),
+      // Main color: lighter in dark mode, darker in light mode
+      true
+      // background
+    );
+    const onColorDynamicColor = new DynamicColor(
+      `on${upperFirst(colorname)}`,
+      getPaletteForColor,
+      (s) => getTone(s.isDark ? 20 : 100)(s),
+      // Text on main color: high contrast (dark on light, light on dark)
+      false
+    );
+    const containerDynamicColor = new DynamicColor(
+      `${colorname}Container`,
+      getPaletteForColor,
+      (s) => getTone(s.isDark ? 30 : 90)(s),
+      // Container: subtle variant (darker in dark mode, lighter in light mode)
+      true
+      // background
+    );
+    const onContainerDynamicColor = new DynamicColor(
+      `on${upperFirst(colorname)}Container`,
+      getPaletteForColor,
+      (s) => getTone(s.isDark ? 90 : 30)(s),
+      // Text on container: high contrast against container background
+      false
+    );
+    customVars[colorname] = colorDynamicColor.getArgb(scheme);
+    customVars[`on${upperFirst(colorname)}`] = onColorDynamicColor.getArgb(scheme);
+    customVars[`${colorname}Container`] = containerDynamicColor.getArgb(scheme);
+    customVars[`on${upperFirst(colorname)}Container`] = onContainerDynamicColor.getArgb(scheme);
   });
   return { ...baseVars, ...customVars };
 }
@@ -294,12 +354,38 @@ var cssVar = (colorName, colorValue) => {
   const value = hexFromArgb2(colorValue);
   return `${name}:${value};`;
 };
-var generateTonalPaletteVars = (paletteName, palette) => {
+var generateTonalPaletteVars = (paletteName, palette, scheme, applyContrast = false) => {
   return STANDARD_TONES.map((tone) => {
-    const color = palette.tone(tone);
+    let toneToUse = tone;
+    if (applyContrast && scheme) {
+      toneToUse = adjustToneForContrast(
+        tone,
+        scheme.contrastLevel,
+        scheme.isDark
+      );
+    }
+    const color = palette.tone(toneToUse);
     return cssVar(`${paletteName}-${tone}`, color);
   }).join(" ");
 };
+function createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonization) {
+  const colorArgb = argbFromHex(colorDef.hex);
+  const harmonizedArgb = colorDef.blend ? Blend.harmonize(colorArgb, effectiveSourceForHarmonization) : colorArgb;
+  const hct = Hct.fromInt(harmonizedArgb);
+  let targetChroma;
+  if (colorDef.core && colorDef.chromaSource) {
+    if (colorDef.chromaSource === "neutral") {
+      targetChroma = baseScheme.neutralPalette.chroma;
+    } else if (colorDef.chromaSource === "neutralVariant") {
+      targetChroma = baseScheme.neutralVariantPalette.chroma;
+    } else {
+      targetChroma = baseScheme.primaryPalette.chroma;
+    }
+  } else {
+    targetChroma = baseScheme.primaryPalette.chroma;
+  }
+  return TonalPalette.fromHueAndChroma(hct.hue, targetChroma);
+}
 var toCssVars = (mergedColors) => {
   return Object.entries(mergedColors).map(([name, value]) => cssVar(name, value)).join(" ");
 };
@@ -314,76 +400,159 @@ function generateCss({
   neutralVariant,
   error,
   colorMatch = DEFAULT_COLOR_MATCH,
-  customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS
+  customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
+  contrastAllColors = DEFAULT_CONTRAST_ALL_COLORS
 }) {
-  const hasCoreColors = primary ?? secondary ?? tertiary ?? neutral ?? neutralVariant ?? error;
   const sourceArgb = argbFromHex(hexSource);
+  const effectiveSource = primary || hexSource;
+  const effectiveSourceArgb = argbFromHex(effectiveSource);
+  const effectiveSourceForHarmonization = primary ? argbFromHex(primary) : sourceArgb;
+  const SchemeClass = schemesMap[scheme];
+  const primaryHct = Hct.fromInt(effectiveSourceArgb);
+  const baseScheme = new SchemeClass(primaryHct, false, contrast);
+  const allColors = [
+    // Core colors (hex may be undefined)
+    {
+      name: "primary",
+      hex: primary,
+      core: true,
+      chromaSource: "primary"
+    },
+    {
+      name: "secondary",
+      hex: secondary,
+      core: true,
+      chromaSource: "primary"
+    },
+    {
+      name: "tertiary",
+      hex: tertiary,
+      core: true,
+      chromaSource: "primary"
+    },
+    { name: "error", hex: error, core: true, chromaSource: "primary" },
+    {
+      name: "neutral",
+      hex: neutral,
+      core: true,
+      chromaSource: "neutral"
+    },
+    {
+      name: "neutralVariant",
+      hex: neutralVariant,
+      core: true,
+      chromaSource: "neutralVariant"
+    },
+    //
+    // Custom colors
+    //
+    ...hexCustomColors.map((c) => ({
+      name: c.name,
+      hex: c.hex,
+      blend: c.blend,
+      core: false
+    }))
+  ];
+  const definedColors = allColors.filter(
+    (c) => c.hex !== void 0
+  );
+  const colorPalettes = Object.fromEntries(
+    definedColors.map((colorDef) => [
+      colorDef.name,
+      createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonization)
+    ])
+  );
   const createSchemes = (baseConfig) => [
     new DynamicScheme({ ...baseConfig, isDark: false }),
     new DynamicScheme({ ...baseConfig, isDark: true })
   ];
-  let lightScheme;
-  let darkScheme;
-  let corePalette;
-  if (hasCoreColors) {
-    const coreColorsArgb = {
-      primary: primary ? argbFromHex(primary) : sourceArgb,
-      secondary: secondary ? argbFromHex(secondary) : void 0,
-      tertiary: tertiary ? argbFromHex(tertiary) : void 0,
-      neutral: neutral ? argbFromHex(neutral) : void 0,
-      neutralVariant: neutralVariant ? argbFromHex(neutralVariant) : void 0,
-      error: error ? argbFromHex(error) : void 0
-    };
-    corePalette = colorMatch ? CorePalette.fromColors(coreColorsArgb) : CorePalette.contentFromColors(coreColorsArgb);
-    const variant = schemeToVariant[scheme];
-    [lightScheme, darkScheme] = createSchemes({
-      sourceColorArgb: sourceArgb,
-      variant,
-      contrastLevel: contrast,
-      primaryPalette: corePalette.a1,
-      secondaryPalette: corePalette.a2,
-      tertiaryPalette: corePalette.a3,
-      neutralPalette: corePalette.n1,
-      neutralVariantPalette: corePalette.n2
-    });
-  } else {
-    const SchemeClass = schemesMap[scheme];
-    const hct = Hct.fromInt(sourceArgb);
-    lightScheme = new SchemeClass(hct, false, contrast);
-    darkScheme = new SchemeClass(hct, true, contrast);
-    corePalette = CorePalette.of(sourceArgb);
+  const variant = schemeToVariant[scheme];
+  const [lightScheme, darkScheme] = createSchemes({
+    sourceColorArgb: effectiveSourceArgb,
+    variant,
+    contrastLevel: contrast,
+    primaryPalette: colorPalettes["primary"] || baseScheme.primaryPalette,
+    secondaryPalette: colorPalettes["secondary"] || baseScheme.secondaryPalette,
+    tertiaryPalette: colorPalettes["tertiary"] || baseScheme.tertiaryPalette,
+    neutralPalette: colorPalettes["neutral"] || baseScheme.neutralPalette,
+    neutralVariantPalette: colorPalettes["neutralVariant"] || baseScheme.neutralVariantPalette
+  });
+  const errorPalette = colorPalettes["error"];
+  if (errorPalette) {
+    lightScheme.errorPalette = errorPalette;
+    darkScheme.errorPalette = errorPalette;
   }
-  const customColors = hexCustomColors.map(({ hex, ...rest }) => ({
-    ...rest,
-    value: argbFromHex(hex)
+  const customColors = definedColors.filter((c) => !c.core).map((c) => ({
+    name: c.name,
+    blend: c.blend ?? DEFAULT_BLEND,
+    value: argbFromHex(c.hex)
   }));
   const mergedColorsLight = mergeBaseAndCustomColors(
     lightScheme,
     customColors,
-    sourceArgb
+    colorPalettes,
+    contrastAllColors
   );
   const mergedColorsDark = mergeBaseAndCustomColors(
     darkScheme,
     customColors,
-    sourceArgb
+    colorPalettes,
+    contrastAllColors
   );
   const lightVars = toCssVars(mergedColorsLight);
   const darkVars = toCssVars(mergedColorsDark);
-  const coreColorsTonalVars = [
-    generateTonalPaletteVars("primary", corePalette.a1),
-    generateTonalPaletteVars("secondary", corePalette.a2),
-    generateTonalPaletteVars("tertiary", corePalette.a3),
-    generateTonalPaletteVars("neutral", corePalette.n1),
-    generateTonalPaletteVars("neutral-variant", corePalette.n2),
-    generateTonalPaletteVars("error", corePalette.error)
+  const allTonalVars = [
+    // Core colors from the scheme
+    generateTonalPaletteVars(
+      "primary",
+      lightScheme.primaryPalette,
+      lightScheme,
+      contrastAllColors
+    ),
+    generateTonalPaletteVars(
+      "secondary",
+      lightScheme.secondaryPalette,
+      lightScheme,
+      contrastAllColors
+    ),
+    generateTonalPaletteVars(
+      "tertiary",
+      lightScheme.tertiaryPalette,
+      lightScheme,
+      contrastAllColors
+    ),
+    generateTonalPaletteVars(
+      "error",
+      lightScheme.errorPalette,
+      lightScheme,
+      contrastAllColors
+    ),
+    generateTonalPaletteVars(
+      "neutral",
+      lightScheme.neutralPalette,
+      lightScheme,
+      contrastAllColors
+    ),
+    generateTonalPaletteVars(
+      "neutral-variant",
+      lightScheme.neutralVariantPalette,
+      lightScheme,
+      contrastAllColors
+    ),
+    // Custom colors from our unified palette map
+    ...customColors.map((customColorObj) => {
+      const palette = getPalette(colorPalettes, customColorObj.name);
+      return generateTonalPaletteVars(
+        kebabCase(customColorObj.name),
+        palette,
+        lightScheme,
+        contrastAllColors
+      );
+    })
   ].join(" ");
-  const customColorTonalVars = customColors.map((customColorObj) => {
-    const palette = TonalPalette.fromInt(customColorObj.value);
-    return generateTonalPaletteVars(kebabCase(customColorObj.name), palette);
-  }).join(" ");
   return {
     css: `
-:root { ${lightVars} ${coreColorsTonalVars} ${customColorTonalVars} }
+:root { ${lightVars} ${allTonalVars} }
 .dark { ${darkVars} }
 `,
     mergedColorsLight,

package/dist/tailwind.css

@@ -164,23 +164,4 @@
   --color-myCustomColor2-800: var(--mcu-my-custom-color-2-20);
   --color-myCustomColor2-900: var(--mcu-my-custom-color-2-10);
   --color-myCustomColor2-950: var(--mcu-my-custom-color-2-5);
-
-  --color-myCustomColor3: var(--mcu-my-custom-color-3);
-  --color-on-myCustomColor3: var(--mcu-on-my-custom-color-3);
-  --color-myCustomColor3-container: var(--mcu-my-custom-color-3-container);
-  --color-on-myCustomColor3-container: var(
-    --mcu-on-my-custom-color-3-container
-  );
-  /* Shades */
-  --color-myCustomColor3-50: var(--mcu-my-custom-color-3-95);
-  --color-myCustomColor3-100: var(--mcu-my-custom-color-3-90);
-  --color-myCustomColor3-200: var(--mcu-my-custom-color-3-80);
-  --color-myCustomColor3-300: var(--mcu-my-custom-color-3-70);
-  --color-myCustomColor3-400: var(--mcu-my-custom-color-3-60);
-  --color-myCustomColor3-500: var(--mcu-my-custom-color-3-50);
-  --color-myCustomColor3-600: var(--mcu-my-custom-color-3-40);
-  --color-myCustomColor3-700: var(--mcu-my-custom-color-3-30);
-  --color-myCustomColor3-800: var(--mcu-my-custom-color-3-20);
-  --color-myCustomColor3-900: var(--mcu-my-custom-color-3-10);
-  --color-myCustomColor3-950: var(--mcu-my-custom-color-3-5);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-mcu",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A React component library",
   "keywords": [
     "react",
@@ -66,14 +66,14 @@
   },
   "scripts": {
     "build": "tsup",
-    "ci": "pnpm run build && pnpm run check-format && pnpm run check-exports && pnpm run lint && pnpm run test",
-    "lint": "tsc",
+    "lgtm": "pnpm run build && pnpm run check-format && pnpm run check-exports && pnpm run typecheck && pnpm run test",
+    "typecheck": "tsc",
     "test": "vitest run",
     "format": "prettier --write .",
     "check-format": "prettier --check .",
     "check-exports": "attw --pack . --ignore-rules cjs-resolves-to-esm no-resolution",
     "release": "pnpm run build && changeset publish",
-    "local-release": "pnpm run ci && changeset version && changeset publish",
+    "local-release": "pnpm run lgtm && changeset version && changeset publish",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "chromatic": "chromatic --project-token $CHROMATIC_PROJECT_TOKEN",

package/src/tailwind.css

@@ -164,23 +164,4 @@
   --color-myCustomColor2-800: var(--mcu-my-custom-color-2-20);
   --color-myCustomColor2-900: var(--mcu-my-custom-color-2-10);
   --color-myCustomColor2-950: var(--mcu-my-custom-color-2-5);
-
-  --color-myCustomColor3: var(--mcu-my-custom-color-3);
-  --color-on-myCustomColor3: var(--mcu-on-my-custom-color-3);
-  --color-myCustomColor3-container: var(--mcu-my-custom-color-3-container);
-  --color-on-myCustomColor3-container: var(
-    --mcu-on-my-custom-color-3-container
-  );
-  /* Shades */
-  --color-myCustomColor3-50: var(--mcu-my-custom-color-3-95);
-  --color-myCustomColor3-100: var(--mcu-my-custom-color-3-90);
-  --color-myCustomColor3-200: var(--mcu-my-custom-color-3-80);
-  --color-myCustomColor3-300: var(--mcu-my-custom-color-3-70);
-  --color-myCustomColor3-400: var(--mcu-my-custom-color-3-60);
-  --color-myCustomColor3-500: var(--mcu-my-custom-color-3-50);
-  --color-myCustomColor3-600: var(--mcu-my-custom-color-3-40);
-  --color-myCustomColor3-700: var(--mcu-my-custom-color-3-30);
-  --color-myCustomColor3-800: var(--mcu-my-custom-color-3-20);
-  --color-myCustomColor3-900: var(--mcu-my-custom-color-3-10);
-  --color-myCustomColor3-950: var(--mcu-my-custom-color-3-5);
 }