@atomazing-org/design-system 1.0.62 → 1.0.63

package/README.md

@@ -0,0 +1,82 @@
+@atomazing-org/design-system
+
+Modern MUI + Emotion design system with a ready theme factory, extended typography, global styles, component overrides, animations, and handy utilities.
+
+Contents
+- Introduction
+- Installation
+- Quick Start
+- Extended Palette (4 variants)
+- Ad‑hoc Custom Colors
+- SSR Notes
+- Peer Dependencies
+
+Introduction
+The package streamlines consistent theming across apps: dark/light mode, typography variants, global styles, and component defaults. Built on MUI v7 + Emotion.
+
+Installation
+```bash
+npm install @atomazing-org/design-system
+npm install @mui/material @mui/icons-material @emotion/react @emotion/styled @emotion/css
+```
+
+Quick Start
+```tsx
+import { ThemeProviderWrapper } from '@atomazing-org/design-system';
+
+export function App() {
+  return (
+    <ThemeProviderWrapper>
+      {/* your app */}
+    </ThemeProviderWrapper>
+  );
+}
+```
+
+Extended Palette (4 variants)
+The design system adds four typed colors to the MUI palette, available on common components via the `color` prop:
+
+- brand: project brand color (independent from `primary`); defaults to the currently selected theme’s primary.
+- neutral: neutral/gray scale color (from the design-system palette).
+- accent: supporting accent color (from palette `accent`).
+- muted: soft/desaturated color (based on neutral by default).
+
+Supported components (out of the box): `Button`, `Chip`, `Badge`, `Alert`.
+
+Examples
+```tsx
+import { Button, Chip, Alert } from '@mui/material';
+
+<Button color="brand" variant="contained">Brand</Button>
+<Button color="neutral" variant="outlined">Neutral</Button>
+<Chip color="accent" label="Accent" />
+<Alert color="muted" variant="filled">Muted Alert</Alert>
+```
+
+Ad‑hoc Custom Colors
+If you need additional colors without extending types, use `customColors`. They will be available under `theme.palette.custom[<name>]` with generated light/dark/contrast shades.
+
+```tsx
+<ThemeProviderWrapper customColors={{ marketing: '#FF6A00', accent2: '#4ADE80' }}>
+  {/* ... */}
+</ThemeProviderWrapper>
+
+// Usage
+import { Box } from '@mui/material';
+
+<Box sx={{ bgcolor: (t) => t.palette.custom?.marketing.main }} />
+```
+
+Notes
+- To add more typed colors to the `color` prop, augment MUI types (see `src/styles/muiAugmentations.d.ts`).
+- You can override the global color palette via `colorPaletteOverride` and theme map via `themeConfigOverride`.
+
+SSR Notes
+- The library guards `localStorage`/`navigator` usage. Wrap your app in `<ThemeProviderWrapper>` as usual in SSR frameworks; settings hydrate on the client.
+
+Peer Dependencies
+- `@mui/material` ^7
+- `@mui/icons-material` ^7
+- `@emotion/react` ^11
+- `@emotion/styled` ^11
+- `@emotion/css` ^11 (optional)

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as _emotion_styled from '@emotion/styled';
 import * as _emotion_react from '@emotion/react';
 import * as React$1 from 'react';
-import React__default, { ErrorInfo, FC, PropsWithChildren } from 'react';
+import React__default, { ErrorInfo, ReactNode, FC, PropsWithChildren } from 'react';
 import * as _mui_material_OverridableComponent from '@mui/material/OverridableComponent';
 import * as _mui_material from '@mui/material';
 import { Theme, PaletteMode } from '@mui/material';
@@ -46,7 +46,7 @@ type DarkModeOptions = "system" | "auto" | "light" | "dark";
 interface OptionItem {
     label: string;
     value: DarkModeOptions;
-    icon: any;
+    icon: ReactNode;
 }
 /**
  * Represents user-specific theme preferences stored in the application.
@@ -198,33 +198,41 @@ declare module "@mui/material/Typography" {
     }
 }
 
-declare const useThemeSettings: () => ThemeContextProps;
+interface ColorPaletteType {
+    fontDark: string;
+    fontLight: string;
+    brand: string;
+    accent: string;
+    muted: string;
+    success: string;
+    info: string;
+    warning: string;
+    error: string;
+    neutral: string;
+}
 
-declare const ThemeProviderWrapper: FC<PropsWithChildren>;
+declare const darkModeOptions: OptionItem[];
 
-/**
- * Validates whether a given string is a valid 3- or 6-digit hex color code (e.g., "#fff" or "#ffffff").
- *
- * @param value - The string to check.
- * @returns `true` if the string is a valid hex color; otherwise, `false`.
- */
-declare const isHexColor: (value: string) => boolean;
-/**
- * Determines the ideal font color (white or black) for contrast against a given background color.
- *
- * Uses luminance calculation (YIQ) to ensure accessibility and visual clarity.
- *
- * @param backgroundColor - A valid hex color (e.g., "#ffffff").
- * @returns A hex color string (`fontLight` or `fontDark`) suitable for overlay text.
- */
-declare const getFontColor: (backgroundColor: string) => string;
-/**
- * Determines whether the ideal font color for a background is light (i.e., white).
- *
- * @param color - The background color in hex.
- * @returns `true` if white text is recommended; otherwise, `false`.
- */
-declare const isFontLight: (color: string) => boolean;
+declare const defaultColorPalette: ColorPaletteType;
+
+declare const useThemeSettings: () => ThemeContextProps;
+
+type ThemeProviderWrapperProps = PropsWithChildren<{
+    /** Optional font stack to apply across the app. */
+    fontFamily?: string;
+    /** Optional direct override for a single theme primary color. */
+    primaryColor?: string;
+    /** Optional map to override default themeConfig with custom themes. */
+    themeConfigOverride?: Record<string, {
+        primaryColor: string;
+        secondaryColor?: string;
+    }>;
+    /** Optional color palette override (e.g., fontLight/fontDark/accent colors). */
+    colorPaletteOverride?: Partial<ColorPaletteType>;
+    /** Optional registry of ad-hoc colors to inject into theme.palette.custom */
+    customColors?: Record<string, string>;
+}>;
+declare const ThemeProviderWrapper: FC<ThemeProviderWrapperProps>;
 
 /**
  * Common component style overrides and default props shared across the design system.
@@ -232,7 +240,7 @@ declare const isFontLight: (color: string) => boolean;
  */
 declare const commonComponentProps: Theme["components"];
 
-declare const createCustomTheme: (primaryColor: string, mode?: PaletteMode) => Theme;
+declare const createCustomTheme: (primaryColor: string, mode?: PaletteMode, secondaryColor?: string) => Theme;
 /**
  * A predefined list of named themes based on the `themeConfig` definition.
  */
@@ -240,17 +248,6 @@ declare const themes: {
     name: string;
     MuiTheme: Theme;
 }[];
-/**
- * Determines whether dark mode should be enabled based on user settings and system conditions.
- *
- * @param darkMode - User preference: 'light' | 'dark' | 'system' | 'auto'.
- * @param systemTheme - Detected OS-level theme: 'light' | 'dark'.
- * @param backgroundColor - The background color to assess contrast in 'auto' mode.
- * @returns True if dark mode should be used.
- */
-declare const isDarkMode: (darkMode: AppSettings["darkMode"], systemTheme: SystemTheme) => boolean;
-
-declare const darkModeOptions: OptionItem[];
 
 /**
  * Injects global styles into the document using Emotion.
@@ -259,7 +256,11 @@ declare const darkModeOptions: OptionItem[];
  *
  * Uses the MUI theme to dynamically adjust colors for light/dark mode.
  */
-declare const GlobalStyles: FC;
+interface GlobalStylesProps {
+    /** Optional font stack to apply across the app. */
+    fontFamily?: string;
+}
+declare const GlobalStyles: FC<GlobalStylesProps>;
 
 /**
  * Fade in from the left with slight movement on the X-axis.
@@ -352,18 +353,43 @@ declare const installAppAnimation: {
     toString: () => string;
 } & string;
 
-declare const ColorPalette: {
-    readonly fontDark: "#101727";
-    readonly fontLight: "#f0f0f0";
-    readonly purple: "#440850";
-    readonly lavender: "#9FA9EA";
-    readonly carrot: "#F3503A";
-    readonly pistachio: "#62ED97";
-};
+/** Returns the active color palette, allowing app-level overrides. */
+declare const getColorPalette: () => ColorPaletteType;
+/**
+ * Overrides the active color palette with app-provided values.
+ * Pass `undefined` or empty to reset to defaults.
+ */
+declare const setColorPaletteOverride: (override?: Partial<ColorPaletteType>) => void;
 declare const themeConfig: Record<string, {
     primaryColor: string;
     secondaryColor?: string;
 }>;
+/** Backward-compatible live view of the active palette. */
+declare const ColorPalette: Readonly<ColorPaletteType>;
+
+/**
+ * Validates whether a given string is a valid 3- or 6-digit hex color code (e.g., "#fff" or "#ffffff").
+ *
+ * @param value - The string to check.
+ * @returns `true` if the string is a valid hex color; otherwise, `false`.
+ */
+declare const isHexColor: (value: string) => boolean;
+/**
+ * Determines the ideal font color (white or black) for contrast against a given background color.
+ *
+ * Uses luminance calculation (YIQ) to ensure accessibility and visual clarity.
+ *
+ * @param backgroundColor - A valid hex color (e.g., "#ffffff").
+ * @returns A hex color string (`fontLight` or `fontDark`) suitable for overlay text.
+ */
+declare const getFontColor: (backgroundColor: string) => string;
+/**
+ * Determines whether the ideal font color for a background is light (i.e., white).
+ *
+ * @param color - The background color in hex.
+ * @returns `true` if white text is recommended; otherwise, `false`.
+ */
+declare const isFontLight: (color: string) => boolean;
 
 /**
  * Returns a greeting based on the current time.
@@ -386,12 +412,23 @@ type OperatingSystem = "Windows" | "macOS" | "Linux" | "iOS" | "Android" | "Unkn
 type Browser = "Chrome" | "Firefox" | "Safari" | "Edge" | "Unknown";
 /**
  * Basic information about the user's system (OS and browser).
+ * Safe for SSR: resolves to Unknown values on server.
  */
 declare const systemInfo: {
     os: OperatingSystem;
     browser: Browser;
 };
 
+/**
+ * Determines whether dark mode should be enabled based on user settings and system conditions.
+ *
+ * @param darkMode - User preference: 'light' | 'dark' | 'system' | 'auto'.
+ * @param systemTheme - Detected OS-level theme: 'light' | 'dark'.
+ * @param backgroundColor - The background color to assess contrast in 'auto' mode.
+ * @returns True if dark mode should be used.
+ */
+declare const isDarkMode: (darkMode: AppSettings["darkMode"], systemTheme: SystemTheme) => boolean;
+
 /**
  * Converts a given date to a human-readable relative time string.
  *
@@ -416,4 +453,4 @@ declare const useResponsiveDisplay: (breakpoint?: number) => boolean;
  */
 declare const useSystemTheme: () => SystemTheme;
 
-export { type AppSettings, ColorPalette, type CustomTypographyVariants, type DarkModeOptions, DialogBtn, ErrorBoundary, GlobalStyles, Loading, type OptionItem, PathName, type SystemTheme, type ThemeContextProps, ThemeProviderWrapper, commonComponentProps, createCustomTheme, darkModeOptions, displayGreeting, fadeIn, fadeInLeft, getDayIdentifier, getFontColor, installAppAnimation, isDarkMode, isFontLight, isHexColor, logoutAnimation, progressPulse, pulseAnimation, scale, slideIn, slideInBottom, systemInfo, themeConfig, themes, timeAgo, timeAgoFromStart, useResponsiveDisplay, useSystemTheme, useThemeSettings };
+export { type AppSettings, ColorPalette, type ColorPaletteType, type CustomTypographyVariants, type DarkModeOptions, DialogBtn, ErrorBoundary, GlobalStyles, Loading, type OptionItem, PathName, type SystemTheme, type ThemeContextProps, ThemeProviderWrapper, commonComponentProps, createCustomTheme, darkModeOptions, defaultColorPalette, displayGreeting, fadeIn, fadeInLeft, getColorPalette, getDayIdentifier, getFontColor, installAppAnimation, isDarkMode, isFontLight, isHexColor, logoutAnimation, progressPulse, pulseAnimation, scale, setColorPaletteOverride, slideIn, slideInBottom, systemInfo, themeConfig, themes, timeAgo, timeAgoFromStart, useResponsiveDisplay, useSystemTheme, useThemeSettings };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as _emotion_styled from '@emotion/styled';
 import * as _emotion_react from '@emotion/react';
 import * as React$1 from 'react';
-import React__default, { ErrorInfo, FC, PropsWithChildren } from 'react';
+import React__default, { ErrorInfo, ReactNode, FC, PropsWithChildren } from 'react';
 import * as _mui_material_OverridableComponent from '@mui/material/OverridableComponent';
 import * as _mui_material from '@mui/material';
 import { Theme, PaletteMode } from '@mui/material';
@@ -46,7 +46,7 @@ type DarkModeOptions = "system" | "auto" | "light" | "dark";
 interface OptionItem {
     label: string;
     value: DarkModeOptions;
-    icon: any;
+    icon: ReactNode;
 }
 /**
  * Represents user-specific theme preferences stored in the application.
@@ -198,33 +198,41 @@ declare module "@mui/material/Typography" {
     }
 }
 
-declare const useThemeSettings: () => ThemeContextProps;
+interface ColorPaletteType {
+    fontDark: string;
+    fontLight: string;
+    brand: string;
+    accent: string;
+    muted: string;
+    success: string;
+    info: string;
+    warning: string;
+    error: string;
+    neutral: string;
+}
 
-declare const ThemeProviderWrapper: FC<PropsWithChildren>;
+declare const darkModeOptions: OptionItem[];
 
-/**
- * Validates whether a given string is a valid 3- or 6-digit hex color code (e.g., "#fff" or "#ffffff").
- *
- * @param value - The string to check.
- * @returns `true` if the string is a valid hex color; otherwise, `false`.
- */
-declare const isHexColor: (value: string) => boolean;
-/**
- * Determines the ideal font color (white or black) for contrast against a given background color.
- *
- * Uses luminance calculation (YIQ) to ensure accessibility and visual clarity.
- *
- * @param backgroundColor - A valid hex color (e.g., "#ffffff").
- * @returns A hex color string (`fontLight` or `fontDark`) suitable for overlay text.
- */
-declare const getFontColor: (backgroundColor: string) => string;
-/**
- * Determines whether the ideal font color for a background is light (i.e., white).
- *
- * @param color - The background color in hex.
- * @returns `true` if white text is recommended; otherwise, `false`.
- */
-declare const isFontLight: (color: string) => boolean;
+declare const defaultColorPalette: ColorPaletteType;
+
+declare const useThemeSettings: () => ThemeContextProps;
+
+type ThemeProviderWrapperProps = PropsWithChildren<{
+    /** Optional font stack to apply across the app. */
+    fontFamily?: string;
+    /** Optional direct override for a single theme primary color. */
+    primaryColor?: string;
+    /** Optional map to override default themeConfig with custom themes. */
+    themeConfigOverride?: Record<string, {
+        primaryColor: string;
+        secondaryColor?: string;
+    }>;
+    /** Optional color palette override (e.g., fontLight/fontDark/accent colors). */
+    colorPaletteOverride?: Partial<ColorPaletteType>;
+    /** Optional registry of ad-hoc colors to inject into theme.palette.custom */
+    customColors?: Record<string, string>;
+}>;
+declare const ThemeProviderWrapper: FC<ThemeProviderWrapperProps>;
 
 /**
  * Common component style overrides and default props shared across the design system.
@@ -232,7 +240,7 @@ declare const isFontLight: (color: string) => boolean;
  */
 declare const commonComponentProps: Theme["components"];
 
-declare const createCustomTheme: (primaryColor: string, mode?: PaletteMode) => Theme;
+declare const createCustomTheme: (primaryColor: string, mode?: PaletteMode, secondaryColor?: string) => Theme;
 /**
  * A predefined list of named themes based on the `themeConfig` definition.
  */
@@ -240,17 +248,6 @@ declare const themes: {
     name: string;
     MuiTheme: Theme;
 }[];
-/**
- * Determines whether dark mode should be enabled based on user settings and system conditions.
- *
- * @param darkMode - User preference: 'light' | 'dark' | 'system' | 'auto'.
- * @param systemTheme - Detected OS-level theme: 'light' | 'dark'.
- * @param backgroundColor - The background color to assess contrast in 'auto' mode.
- * @returns True if dark mode should be used.
- */
-declare const isDarkMode: (darkMode: AppSettings["darkMode"], systemTheme: SystemTheme) => boolean;
-
-declare const darkModeOptions: OptionItem[];
 
 /**
  * Injects global styles into the document using Emotion.
@@ -259,7 +256,11 @@ declare const darkModeOptions: OptionItem[];
  *
  * Uses the MUI theme to dynamically adjust colors for light/dark mode.
  */
-declare const GlobalStyles: FC;
+interface GlobalStylesProps {
+    /** Optional font stack to apply across the app. */
+    fontFamily?: string;
+}
+declare const GlobalStyles: FC<GlobalStylesProps>;
 
 /**
  * Fade in from the left with slight movement on the X-axis.
@@ -352,18 +353,43 @@ declare const installAppAnimation: {
     toString: () => string;
 } & string;
 
-declare const ColorPalette: {
-    readonly fontDark: "#101727";
-    readonly fontLight: "#f0f0f0";
-    readonly purple: "#440850";
-    readonly lavender: "#9FA9EA";
-    readonly carrot: "#F3503A";
-    readonly pistachio: "#62ED97";
-};
+/** Returns the active color palette, allowing app-level overrides. */
+declare const getColorPalette: () => ColorPaletteType;
+/**
+ * Overrides the active color palette with app-provided values.
+ * Pass `undefined` or empty to reset to defaults.
+ */
+declare const setColorPaletteOverride: (override?: Partial<ColorPaletteType>) => void;
 declare const themeConfig: Record<string, {
     primaryColor: string;
     secondaryColor?: string;
 }>;
+/** Backward-compatible live view of the active palette. */
+declare const ColorPalette: Readonly<ColorPaletteType>;
+
+/**
+ * Validates whether a given string is a valid 3- or 6-digit hex color code (e.g., "#fff" or "#ffffff").
+ *
+ * @param value - The string to check.
+ * @returns `true` if the string is a valid hex color; otherwise, `false`.
+ */
+declare const isHexColor: (value: string) => boolean;
+/**
+ * Determines the ideal font color (white or black) for contrast against a given background color.
+ *
+ * Uses luminance calculation (YIQ) to ensure accessibility and visual clarity.
+ *
+ * @param backgroundColor - A valid hex color (e.g., "#ffffff").
+ * @returns A hex color string (`fontLight` or `fontDark`) suitable for overlay text.
+ */
+declare const getFontColor: (backgroundColor: string) => string;
+/**
+ * Determines whether the ideal font color for a background is light (i.e., white).
+ *
+ * @param color - The background color in hex.
+ * @returns `true` if white text is recommended; otherwise, `false`.
+ */
+declare const isFontLight: (color: string) => boolean;
 
 /**
  * Returns a greeting based on the current time.
@@ -386,12 +412,23 @@ type OperatingSystem = "Windows" | "macOS" | "Linux" | "iOS" | "Android" | "Unkn
 type Browser = "Chrome" | "Firefox" | "Safari" | "Edge" | "Unknown";
 /**
  * Basic information about the user's system (OS and browser).
+ * Safe for SSR: resolves to Unknown values on server.
  */
 declare const systemInfo: {
     os: OperatingSystem;
     browser: Browser;
 };
 
+/**
+ * Determines whether dark mode should be enabled based on user settings and system conditions.
+ *
+ * @param darkMode - User preference: 'light' | 'dark' | 'system' | 'auto'.
+ * @param systemTheme - Detected OS-level theme: 'light' | 'dark'.
+ * @param backgroundColor - The background color to assess contrast in 'auto' mode.
+ * @returns True if dark mode should be used.
+ */
+declare const isDarkMode: (darkMode: AppSettings["darkMode"], systemTheme: SystemTheme) => boolean;
+
 /**
  * Converts a given date to a human-readable relative time string.
  *
@@ -416,4 +453,4 @@ declare const useResponsiveDisplay: (breakpoint?: number) => boolean;
  */
 declare const useSystemTheme: () => SystemTheme;
 
-export { type AppSettings, ColorPalette, type CustomTypographyVariants, type DarkModeOptions, DialogBtn, ErrorBoundary, GlobalStyles, Loading, type OptionItem, PathName, type SystemTheme, type ThemeContextProps, ThemeProviderWrapper, commonComponentProps, createCustomTheme, darkModeOptions, displayGreeting, fadeIn, fadeInLeft, getDayIdentifier, getFontColor, installAppAnimation, isDarkMode, isFontLight, isHexColor, logoutAnimation, progressPulse, pulseAnimation, scale, slideIn, slideInBottom, systemInfo, themeConfig, themes, timeAgo, timeAgoFromStart, useResponsiveDisplay, useSystemTheme, useThemeSettings };
+export { type AppSettings, ColorPalette, type ColorPaletteType, type CustomTypographyVariants, type DarkModeOptions, DialogBtn, ErrorBoundary, GlobalStyles, Loading, type OptionItem, PathName, type SystemTheme, type ThemeContextProps, ThemeProviderWrapper, commonComponentProps, createCustomTheme, darkModeOptions, defaultColorPalette, displayGreeting, fadeIn, fadeInLeft, getColorPalette, getDayIdentifier, getFontColor, installAppAnimation, isDarkMode, isFontLight, isHexColor, logoutAnimation, progressPulse, pulseAnimation, scale, setColorPaletteOverride, slideIn, slideInBottom, systemInfo, themeConfig, themes, timeAgo, timeAgoFromStart, useResponsiveDisplay, useSystemTheme, useThemeSettings };