@webpros/mui-theme 0.3.2 → 0.3.3

package/README.md

@@ -79,6 +79,57 @@ const App = () => (
 import { Box } from '@mui/material'; // NOT import { Box } from '@webpros/mui-theme';
 ```
 
+# Development
+
+## Using Custom ESLint Rules
+
+The package exports custom ESLint rules to enforce Material Design 3 design system best practices. To use them in your project:
+
+```js
+// eslint.config.js
+import webprosMuiThemeRules from '@webpros/mui-theme/eslint';
+
+export default [
+  // ... your other config
+  {
+    plugins: {
+      '@webpros/mui-theme': webprosMuiThemeRules,
+    },
+    rules: {
+      '@webpros/mui-theme/no-palette-usage': 'error',
+      '@webpros/mui-theme/no-standard-typography-variants': 'error',
+      '@webpros/mui-theme/no-hardcoded-typography-in-sx': 'error',
+    },
+  },
+];
+```
+
+For detailed documentation of available rules, see [configs/eslint/README.md](configs/eslint/README.md).
+
+## Adding New Custom ESLint Rules
+
+To add a new custom rule:
+
+1. Create a new file in `configs/eslint/rules/` with your rule implementation (use CommonJS format)
+2. Export the rule using `module.exports`
+3. Import and add it to `configs/eslint/index.cjs` using `require()`
+4. Add the rule to `eslint.config.js` in the plugins and rules sections
+5. Document the rule in `configs/eslint/README.md`
+
+### Testing Custom Rules
+
+Test your custom rules by running ESLint on specific files:
+
+```bash
+# Test on a specific file
+npx eslint src/path/to/file.ts
+
+# Test on all TypeScript files
+npx eslint 'src/**/*.{ts,tsx}'
+```
+
+For more information about the existing custom rules and their usage, see [eslint/README.md](eslint/README.md).
+
 # Tools configuration
 
 ## Webpack
@@ -86,17 +137,17 @@ import { Box } from '@mui/material'; // NOT import { Box } from '@webpros/mui-th
 If you use Webpack, you probably need to add the following rules to your configuration:
 
 ```js
-  module: {
-    rules: [
-      {
-        test: /\.m?js/,
-        type: "javascript/auto",
-        resolve: {
-          fullySpecified: false,
-        },
+module: {
+  rules: [
+    {
+      test: /\.m?js/,
+      type: 'javascript/auto',
+      resolve: {
+        fullySpecified: false,
       },
-      
-      // your other rules
-    ]
-  }
+    },
+
+    // your other rules
+  ];
+}
 ```

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@webpros/mui-theme",
     "description": "MUI v7 theme for WebPros products",
-    "version": "0.3.2",
+    "version": "0.3.3",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -14,7 +14,7 @@
         "theming",
         "ui"
     ],
-    "main": "dist/index.js",
+    "main": "src/index.js",
     "types": "dist/index.d.ts",
     "exports": {
         ".": {
@@ -38,7 +38,9 @@
         "yarn": "^1.22.0"
     },
     "scripts": {
-        "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+        "build": "yarn build:main && yarn build:eslint",
+        "build:main": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+        "build:eslint": "tsc -p ./eslint/tsconfig.eslint.json",
         "storybook:dev": "storybook dev -p 6006",
         "storybook:build": "storybook build",
         "test": "npm run prettier:test && npm run lint && npm run typecheck",
@@ -48,7 +50,7 @@
         "prettier:write": "prettier --write \"**/*.{ts,tsx}\"",
         "typecheck": "tsc --noEmit",
         "extract-tokens": "node tools/extractM3Tokens.js",
-        "generate:icons": "node scripts/generate-icons.cjs"
+        "generate:icons": "node tools/generate-icons.js"
     },
     "peerDependencies": {
         "@emotion/react": "^11.14.0",

package/dist/src/components/feedback/Dialog/Dialog.theme.js

@@ -1,7 +1,7 @@
 // Copyright 2025 WebPros International GmbH. All rights reserved.
 import { modalClasses, dialogContentClasses, dialogClasses, iconButtonClasses, } from '@mui/material';
 export const getDialog = (theme) => {
-    const { spacing, palette, colors } = theme;
+    const { spacing, colors } = theme;
     const closeButtonPosition = {
         position: 'absolute',
         right: spacing(3),
@@ -15,7 +15,7 @@ export const getDialog = (theme) => {
             styleOverrides: {
                 root: {
                     padding: spacing(3.75, 8.25, 2.375, 4.5),
-                    color: palette.onSurface.main,
+                    color: colors.schemes.surfaces.onSurface,
                     [`& + .${dialogContentClasses.root}`]: {
                         paddingTop: '0 !important',
                     },
@@ -55,7 +55,7 @@ export const getDialog = (theme) => {
         MuiDialogContent: {
             styleOverrides: {
                 root: {
-                    color: palette.onSurfaceVariant.main,
+                    color: colors.schemes.surfaces.onSurfaceVariant,
                     padding: spacing(0, 4.5, 1, 4.5),
                 },
                 dividers: {
@@ -88,7 +88,7 @@ export const getDialog = (theme) => {
         MuiDialogContentText: {
             styleOverrides: {
                 root: {
-                    color: palette.onSurfaceVariant.main,
+                    color: colors.schemes.surfaces.onSurfaceVariant,
                 },
             },
         },

package/dist/src/components/surfaces/AppBar/AppBar.theme.d.ts

@@ -6,6 +6,6 @@ interface M3AppBar {
         variants?: ComponentsVariants['MuiAppBar'];
     };
 }
-export declare const getAppBar: (theme: Theme) => M3AppBar;
+export declare const getAppBar: (_theme: Theme) => M3AppBar;
 declare const _default: {};
 export default _default;

package/dist/src/components/surfaces/AppBar/AppBar.theme.js

@@ -1,21 +1,10 @@
-export const getAppBar = (theme) => {
-    const { palette } = theme;
+export const getAppBar = (_theme) => {
     return {
         MuiAppBar: {
             defaultProps: {
                 elevation: 0,
                 color: 'default',
             },
-            styleOverrides: {
-                colorDefault: {
-                    background: palette.surface.main,
-                    color: palette.onSurface.main,
-                },
-                colorPrimary: {
-                    background: palette.surface.main,
-                    color: palette.onSurface.main,
-                },
-            },
         },
     };
 };

package/dist/src/index.d.ts

@@ -1,4 +1,5 @@
 export { default as WebProsMuiThemeProvider } from './providers/WebProsMuiThemeProvider';
+export type { WebProsMuiThemeProviderProps } from './providers/WebProsMuiThemeProvider';
 export { useThemeModeContext } from './providers/ThemeModeProvider';
 export * from './utils';
 export * from './tokens';

package/dist/src/providers/WebProsMuiThemeProvider.d.ts

@@ -1,9 +1,25 @@
 import { Localization } from '@mui/material/locale';
 import { ThemeMode } from '../tokens/ThemeMode';
-type WebProsProps = {
+import { ThemeOptions, Theme } from '@mui/material';
+import { M3Components } from '../utils';
+export type WebProsMuiThemeProviderProps = {
     children?: React.ReactNode;
     themeMode?: ThemeMode;
     localization?: Localization;
+    /**
+     * Modifier function to customize theme foundation (palette, typography, spacing, etc.).
+     * This function receives base theme options (without components) and should return modified options.
+     * Changes are applied before component styles are generated.
+     */
+    themeOptionsModifier?: (options: Omit<ThemeOptions, 'components'>) => Omit<ThemeOptions, 'components'>;
+    /**
+     * Modifier function to customize MUI component styles and default props.
+     * This function receives generated component configurations and theme and should return modified configurations.
+     * Changes are applied after the full theme is created.
+     *
+     * **Important:** WebPros component styles are assembled in `getMUIComponents()`.
+     */
+    themeComponentsModifier?: (options: M3Components, theme: Theme) => M3Components;
 };
-declare const WebProsMuiThemeProvider: ({ children, localization, themeMode }: WebProsProps) => import("react/jsx-runtime").JSX.Element;
+declare const WebProsMuiThemeProvider: ({ children, localization, themeMode, themeOptionsModifier, themeComponentsModifier, }: WebProsMuiThemeProviderProps) => import("react/jsx-runtime").JSX.Element;
 export default WebProsMuiThemeProvider;

package/dist/src/providers/WebProsMuiThemeProvider.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import ThemeModeProvider from './ThemeModeProvider';
 import WebProsTheme from './WebProsTheme';
-const WebProsMuiThemeProvider = ({ children, localization, themeMode }) => (_jsx(ThemeModeProvider, { children: _jsx(WebProsTheme, { mode: themeMode, localization: localization, children: children }) }));
+const WebProsMuiThemeProvider = ({ children, localization, themeMode, themeOptionsModifier, themeComponentsModifier, }) => (_jsx(ThemeModeProvider, { children: _jsx(WebProsTheme, { mode: themeMode, localization: localization, themeOptionsModifier: themeOptionsModifier, themeComponentsModifier: themeComponentsModifier, children: children }) }));
 export default WebProsMuiThemeProvider;

package/dist/src/providers/WebProsTheme.d.ts

@@ -1,10 +1,28 @@
+import { ThemeOptions, Theme } from '@mui/material';
 import '../utils/getMUIThemeCustoimzationType';
+import { M3Components } from '../utils/getMUIComponents';
 import { ThemeMode } from '../tokens/ThemeMode';
 import { Localization } from '@mui/material/locale';
 type WebProsThemeProps = {
     children?: React.ReactNode;
     mode?: ThemeMode;
     localization?: Localization;
+    /**
+     * Modifier function for theme foundation (palette, typography, spacing, etc.).
+     * Applied before component styles generation.
+     *
+     * **Performance Note**: To avoid unnecessary theme recreations, wrap modifier functions
+     * with `useCallback` if they depend on dynamic values, or define them outside component.
+     */
+    themeOptionsModifier?: (options: Omit<ThemeOptions, 'components'>) => Omit<ThemeOptions, 'components'>;
+    /**
+     * Modifier function for MUI component configurations.
+     * Applied after theme creation with access to all theme tokens.
+     *
+     * **Performance Note**: To avoid unnecessary theme recreations, wrap modifier functions
+     * with `useCallback` if they depend on dynamic values, or define them outside component.
+     */
+    themeComponentsModifier?: (options: M3Components, theme: Theme) => M3Components;
 };
-export declare const WebProsTheme: ({ children, mode, localization }: WebProsThemeProps) => import("react/jsx-runtime").JSX.Element;
+export declare const WebProsTheme: ({ children, mode, localization, themeOptionsModifier, themeComponentsModifier, }: WebProsThemeProps) => import("react/jsx-runtime").JSX.Element;
 export default WebProsTheme;

package/dist/src/providers/WebProsTheme.js

@@ -11,21 +11,34 @@ import { enUS } from '@mui/material/locale';
 import { patchMUIShadows } from '../utils/patchMUIShadows';
 import { ThemeSchemeDefault } from '../tokens/ThemeScheme';
 import { getMUITypography } from '../utils/getMUITypography';
-export const WebProsTheme = ({ children, mode, localization = enUS }) => {
+export const WebProsTheme = ({ children, mode, localization = enUS, themeOptionsModifier, themeComponentsModifier, }) => {
     const themeModeContext = useContext(ThemeModeContext);
     const themeMode = mode !== null && mode !== void 0 ? mode : themeModeContext.themeMode;
-    const typography = getMUITypography();
     const webprosTheme = useMemo(() => {
+        const typography = getMUITypography();
         const muiPalette = getMUIPalette(themeMode, ThemeSchemeDefault);
-        let theme = createTheme({
+        // Prepare base theme options (without components)
+        const baseThemeOptions = {
             palette: muiPalette.palette,
             colors: muiPalette.colors,
-            typography: Object.assign(Object.assign({}, getMUITypography()), { fontFamily: "'Roboto', 'Helvetica', 'Arial', sans-serif", fontSize: 14, fontWeightLight: 300, fontWeightRegular: 400, fontWeightMedium: 500, fontWeightBold: 700, h1: Object.assign({}, typography.DisplayLarge), h2: Object.assign({}, typography.DisplayMedium), h3: Object.assign({}, typography.DisplaySmall), h4: Object.assign({}, typography.HeadlineLarge), h5: Object.assign({}, typography.HeadlineMedium), h6: Object.assign({}, typography.HeadlineSmall), subtitle1: Object.assign({}, typography.TitleLarge), subtitle2: Object.assign({}, typography.TitleMedium), body1: Object.assign({}, typography.BodyMedium), body2: Object.assign({}, typography.BodySmall), button: Object.assign({}, typography.HeadlineLarge), caption: Object.assign({}, typography.BodySmall), overline: Object.assign({}, typography.LabelSmall) }),
-        }, localization);
+            typography: Object.assign(Object.assign({}, typography), { fontFamily: "'Roboto', 'Helvetica', 'Arial', sans-serif", fontSize: 14, fontWeightLight: 300, fontWeightRegular: 400, fontWeightMedium: 500, fontWeightBold: 700, h1: Object.assign({}, typography.DisplayLarge), h2: Object.assign({}, typography.DisplayMedium), h3: Object.assign({}, typography.DisplaySmall), h4: Object.assign({}, typography.HeadlineLarge), h5: Object.assign({}, typography.HeadlineMedium), h6: Object.assign({}, typography.HeadlineSmall), subtitle1: Object.assign({}, typography.TitleLarge), subtitle2: Object.assign({}, typography.TitleMedium), body1: Object.assign({}, typography.BodyMedium), body2: Object.assign({}, typography.BodySmall), button: Object.assign({}, typography.HeadlineLarge), caption: Object.assign({}, typography.BodySmall), overline: Object.assign({}, typography.LabelSmall) }),
+        };
+        // Apply themeOptionsModifier (palette, typography, spacing, etc.)
+        let themeOptions = baseThemeOptions;
+        if (themeOptionsModifier) {
+            themeOptions = themeOptionsModifier(themeOptions);
+        }
+        let theme = createTheme(themeOptions, localization);
         patchMUIShadows(theme);
-        theme = deepmerge(theme, getMUIComponents(theme, themeMode));
+        // Apply themeComponentsModifier (component styles and props)
+        if (themeComponentsModifier) {
+            theme = deepmerge(theme, themeComponentsModifier(getMUIComponents(theme, themeMode), theme));
+        }
+        else {
+            theme = deepmerge(theme, getMUIComponents(theme, themeMode));
+        }
         return theme;
-    }, [themeMode, localization]);
+    }, [themeMode, localization, themeOptionsModifier, themeComponentsModifier]);
     return (_jsxs(ThemeProvider, { theme: webprosTheme, children: [_jsx(CssBaseline, { enableColorScheme: true }), children] }));
 };
 export default WebProsTheme;

package/dist/src/tokens/ThemeColorTokens.d.ts

@@ -1,6 +1,5 @@
-import { ThemeColorTokensLegacy } from '../tokens/legacyColors/ThemeColorTokensLegacy';
 import { Schemes, SchemesGenerated, StateLayers, StateLayersGenerated, InverseSchemes, InverseSchemesGenerated, InverseStateLayers, InverseStateLayersGenerated } from '../tokens/colors';
-export type ThemeColorTokens = ThemeColorTokensLegacy & {
+export type ThemeColorTokens = {
     schemes: Schemes;
     stateLayers: StateLayers;
     inverseSchemes: InverseSchemes;

package/dist/src/tokens/ThemeColorTokens.js

@@ -1,8 +1,25 @@
 // Copyright 2025 WebPros International GmbH. All rights reserved.
 import { DarkSchemes, DarkSchemesGenerated, DarkStateLayers, DarkStateLayersGenerated, DarkInverseSchemes, DarkInverseSchemesGenerated, DarkInverseStateLayers, DarkInverseStateLayersGenerated, LightSchemes, LightSchemesGenerated, LightStateLayers, LightStateLayersGenerated, LightInverseSchemes, LightInverseSchemesGenerated, LightInverseStateLayers, LightInverseStateLayersGenerated, } from '../tokens/colors';
-import { LegacyDarkTokensDefault, LegacyLightTokensDefault, } from '../tokens/legacyColors';
 // reference
-export const LightTokensDefault = Object.assign(Object.assign({}, LegacyLightTokensDefault), { schemes: LightSchemes, stateLayers: LightStateLayers, inverseSchemes: LightInverseSchemes, inverseStateLayers: LightInverseStateLayers, generatedSchemes: LightSchemesGenerated, generatedStateLayers: LightStateLayersGenerated, generatedInverseSchemes: LightInverseSchemesGenerated, generatedInverseStateLayers: LightInverseStateLayersGenerated });
+export const LightTokensDefault = {
+    schemes: LightSchemes,
+    stateLayers: LightStateLayers,
+    inverseSchemes: LightInverseSchemes,
+    inverseStateLayers: LightInverseStateLayers,
+    generatedSchemes: LightSchemesGenerated,
+    generatedStateLayers: LightStateLayersGenerated,
+    generatedInverseSchemes: LightInverseSchemesGenerated,
+    generatedInverseStateLayers: LightInverseStateLayersGenerated,
+};
 // reference
 // https://www.figma.com/design/RPLeGa2LdhKElQQ0xIXtSh/WebPros-dashboard?node-id=53699-35493&t=pvKyGGnGRUL3kYn8-1
-export const DarkTokensDefault = Object.assign(Object.assign({}, LegacyDarkTokensDefault), { schemes: DarkSchemes, stateLayers: DarkStateLayers, inverseSchemes: DarkInverseSchemes, inverseStateLayers: DarkInverseStateLayers, generatedSchemes: DarkSchemesGenerated, generatedStateLayers: DarkStateLayersGenerated, generatedInverseSchemes: DarkInverseSchemesGenerated, generatedInverseStateLayers: DarkInverseStateLayersGenerated });
+export const DarkTokensDefault = {
+    schemes: DarkSchemes,
+    stateLayers: DarkStateLayers,
+    inverseSchemes: DarkInverseSchemes,
+    inverseStateLayers: DarkInverseStateLayers,
+    generatedSchemes: DarkSchemesGenerated,
+    generatedStateLayers: DarkStateLayersGenerated,
+    generatedInverseSchemes: DarkInverseSchemesGenerated,
+    generatedInverseStateLayers: DarkInverseStateLayersGenerated,
+};

package/dist/src/utils/createIcon.js

@@ -16,29 +16,27 @@ function extractPath(svg) {
 const StyledIconWrapper = styled('span', {
     shouldForwardProp: (prop) => prop !== 'iconColor',
 })(({ theme, iconColor }) => {
+    const { colors } = theme;
     if (!iconColor || iconColor === 'inherit') {
         return { display: 'inline-flex', color: 'inherit' };
     }
-    const paletteColors = [
-        'primary',
-        'secondary',
-        'error',
-        'warning',
-        'info',
-        'success',
-    ];
-    if (paletteColors.includes(iconColor)) {
+    // Map MUI color tokens to M3 color schemes
+    const colorMapping = {
+        primary: colors.schemes.base.primary,
+        secondary: colors.schemes.base.secondary,
+        error: colors.schemes.status.error,
+        warning: colors.schemes.status.warning,
+        info: colors.schemes.status.info,
+        success: colors.schemes.status.success,
+        action: colors.schemes.surfaces.onSurfaceVariant,
+        disabled: colors.stateLayers.surfaces.onSurface.opacity38,
+    };
+    if (colorMapping[iconColor]) {
         return {
             display: 'inline-flex',
-            color: theme.palette[iconColor].main,
+            color: colorMapping[iconColor],
         };
     }
-    if (iconColor === 'action') {
-        return { display: 'inline-flex', color: theme.palette.action.active };
-    }
-    if (iconColor === 'disabled') {
-        return { display: 'inline-flex', color: theme.palette.action.disabled };
-    }
     return { display: 'inline-flex', color: iconColor };
 });
 function extractPathsData(svg) {

package/dist/src/utils/getMUIComponents.d.ts

@@ -1,7 +1,6 @@
 import { Theme } from '@mui/material';
 import { ThemeMode } from '../tokens/ThemeMode';
-type M3Components = {
+export type M3Components = {
     components: Theme['components'];
 };
 export declare const getMUIComponents: (theme: Theme, _mode: ThemeMode) => M3Components;
-export {};

package/dist/src/utils/getMUIPalette.d.ts

@@ -1,24 +1,8 @@
-import { PaletteColor, PaletteColorOptions, ThemeOptions } from '@mui/material';
+import { ThemeOptions } from '@mui/material';
 import { ThemeMode } from '../tokens/ThemeMode';
 import { ThemeScheme } from '../tokens/ThemeScheme';
-import { Schemes, StateLayers } from '../tokens/colors';
 declare module '@mui/material/styles' {
-    interface M3Palette {
-        onPrimary: PaletteColor;
-        onPrimaryContainer: PaletteColor;
-        secondary: PaletteColor;
-        onError: PaletteColor;
-        surface: PaletteColor;
-        onSurface: PaletteColor;
-        surfaceDim: PaletteColor;
-        surfaceContainerLowest: PaletteColor;
-        surfaceContainer: PaletteColor;
-        onSurfaceVariant: PaletteColor;
-        supportive: PaletteColor;
-    }
-    interface Palette extends M3Palette {
-    }
-    interface M3PaletteOptions extends Record<keyof M3Palette, PaletteColorOptions | StateLayers | Schemes> {
+    interface M3PaletteOptions {
         themeMode: string;
     }
     interface PaletteOptions extends M3PaletteOptions {