@umituz/react-native-design-system 2.10.1 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "2.10.1",
+  "version": "2.11.0",
   "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive, safe area, exception, infinite scroll, UUID, image, timezone, offline, onboarding, and loading utilities",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -158,5 +158,8 @@
     "src",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "dependencies": {
+    "@umituz/react-native-design-system": "^2.10.1"
+  }
 }

package/src/theme/core/CustomColors.ts

@@ -1,38 +1,126 @@
 /**
  * Custom Colors Types
- * 
+ *
  * Types for custom theme color overrides
+ *
+ * ARCHITECTURE:
+ * - Apps provide CustomThemeColors to DesignSystemProvider
+ * - These colors override the default palette
+ * - Supports both light and dark mode overrides
+ * - Apps control their own brand colors completely
+ *
+ * BEST PRACTICES (based on Shopify Restyle, React Native Paper, Tamagui):
+ * - All color keys are optional - only override what you need
+ * - Provide separate light/dark palettes for proper theme switching
+ * - Use semantic color names (primary, surface, etc.) not literal colors
  */
 
 import type { ColorPalette } from './ColorPalette';
 import { isValidHexColor } from './colors/ColorUtils';
 
 /**
- * Custom theme colors that can override default colors
+ * Complete custom theme colors - can override ANY color in the palette
+ * All properties are optional - apps only provide what they want to customize
  */
 export interface CustomThemeColors {
+  // PRIMARY BRAND COLORS
   primary?: string;
   primaryLight?: string;
   primaryDark?: string;
+
+  // SECONDARY COLORS
   secondary?: string;
   secondaryLight?: string;
   secondaryDark?: string;
+
+  // ACCENT COLORS
   accent?: string;
   accentLight?: string;
   accentDark?: string;
-  buttonPrimary?: string;
-  buttonSecondary?: string;
-  
-  // Background overrides
+
+  // ON-COLORS (text on colored backgrounds - CRITICAL for contrast)
+  onPrimary?: string;
+  onSecondary?: string;
+  onSuccess?: string;
+  onError?: string;
+  onWarning?: string;
+  onInfo?: string;
+  onSurface?: string;
+  onBackground?: string;
+  onSurfaceDisabled?: string;
+  onSurfaceVariant?: string;
+
+  // CONTAINER COLORS
+  primaryContainer?: string;
+  onPrimaryContainer?: string;
+  secondaryContainer?: string;
+  onSecondaryContainer?: string;
+  errorContainer?: string;
+  onErrorContainer?: string;
+
+  // OUTLINE COLORS
+  outline?: string;
+  outlineVariant?: string;
+  outlineDisabled?: string;
+
+  // SEMANTIC UI COLORS
+  success?: string;
+  successLight?: string;
+  successDark?: string;
+  error?: string;
+  errorLight?: string;
+  errorDark?: string;
+  warning?: string;
+  warningLight?: string;
+  warningDark?: string;
+  info?: string;
+  infoLight?: string;
+  infoDark?: string;
+
+  // SEMANTIC CONTAINER COLORS
+  successContainer?: string;
+  onSuccessContainer?: string;
+  warningContainer?: string;
+  onWarningContainer?: string;
+  infoContainer?: string;
+  onInfoContainer?: string;
+
+  // BACKGROUND COLORS
   backgroundPrimary?: string;
   backgroundSecondary?: string;
+
+  // SURFACE COLORS
   surface?: string;
   surfaceVariant?: string;
-  
-  // Text overrides
+  surfaceSecondary?: string;
+  surfaceDisabled?: string;
+
+  // TEXT COLORS
   textPrimary?: string;
   textSecondary?: string;
   textTertiary?: string;
+  textDisabled?: string;
+  textInverse?: string;
+
+  // BORDER COLORS
+  border?: string;
+  borderLight?: string;
+  borderMedium?: string;
+  borderFocus?: string;
+  borderDisabled?: string;
+
+  // COMPONENT-SPECIFIC COLORS
+  buttonPrimary?: string;
+  buttonSecondary?: string;
+  inputBackground?: string;
+  inputBorder?: string;
+  cardBackground?: string;
+
+  // SPECIAL & UTILITY COLORS
+  transparent?: string;
+  black?: string;
+  white?: string;
+  modalOverlay?: string;
 }
 
 /**
@@ -54,8 +142,13 @@ export const validateCustomColors = (customColors: CustomThemeColors): boolean =
 
 /**
  * Apply custom colors to color palette
- * @param palette - Base color palette
- * @param customColors - Custom colors to apply
+ *
+ * This function takes a base palette and merges custom colors into it.
+ * Apps can override ANY color key - the system simply spreads custom values
+ * over the base palette.
+ *
+ * @param palette - Base color palette (light or dark)
+ * @param customColors - Custom colors to apply (partial override)
  * @returns Color palette with custom colors applied
  */
 export const applyCustomColors = (
@@ -68,90 +161,65 @@ export const applyCustomColors = (
 
   // Validate custom colors
   if (!validateCustomColors(customColors)) {
+    if (__DEV__) {
+      console.warn('[DesignSystem] Invalid custom colors provided - using default palette');
+    }
     return palette;
   }
 
+  // Start with base palette
   const result: Partial<ColorPalette> = {
     ...palette,
   };
 
-  // Apply custom primary colors
-  if (customColors.primary) {
-    result.primary = customColors.primary;
-    if (!customColors.buttonPrimary) {
-      result.buttonPrimary = customColors.primary;
-    }
-  }
-  if (customColors.primaryLight) {
-    result.primaryLight = customColors.primaryLight;
-  }
-  if (customColors.primaryDark) {
-    result.primaryDark = customColors.primaryDark;
-  }
+  // Apply ALL custom colors dynamically
+  // This approach allows any color key to be overridden
+  const colorKeys = Object.keys(customColors) as (keyof CustomThemeColors)[];
 
-  // Apply custom secondary colors
-  if (customColors.secondary) {
-    result.secondary = customColors.secondary;
-    if (!customColors.buttonSecondary) {
-      result.buttonSecondary = customColors.secondary;
+  for (const key of colorKeys) {
+    const value = customColors[key];
+    if (value !== undefined) {
+      // Direct assignment for matching keys
+      (result as Record<string, string>)[key] = value;
     }
   }
-  if (customColors.secondaryLight) {
-    result.secondaryLight = customColors.secondaryLight;
-  }
-  if (customColors.secondaryDark) {
-    result.secondaryDark = customColors.secondaryDark;
-  }
 
-  // Apply custom accent colors
-  if (customColors.accent) {
-    result.accent = customColors.accent;
-  }
-  if (customColors.accentLight) {
-    result.accentLight = customColors.accentLight;
-  }
-  if (customColors.accentDark) {
-    result.accentDark = customColors.accentDark;
+  // Apply smart defaults and aliases
+  // Primary -> buttonPrimary (if buttonPrimary not explicitly set)
+  if (customColors.primary && !customColors.buttonPrimary) {
+    result.buttonPrimary = customColors.primary;
   }
 
-  // Apply custom button colors (override primary/secondary if set)
-  if (customColors.buttonPrimary) {
-    result.buttonPrimary = customColors.buttonPrimary;
-  }
-  if (customColors.buttonSecondary) {
-    result.buttonSecondary = customColors.buttonSecondary;
+  // Secondary -> buttonSecondary (if buttonSecondary not explicitly set)
+  if (customColors.secondary && !customColors.buttonSecondary) {
+    result.buttonSecondary = customColors.secondary;
   }
 
-  // Apply background override
+  // Background aliases
   if (customColors.backgroundPrimary) {
-    result.backgroundPrimary = customColors.backgroundPrimary;
-    result.background = customColors.backgroundPrimary; // Alias
-  }
-  if (customColors.backgroundSecondary) {
-    result.backgroundSecondary = customColors.backgroundSecondary;
+    result.background = customColors.backgroundPrimary;
   }
-  
-  // Apply surface overrides
+
+  // Surface aliases
   if (customColors.surface) {
-    result.surface = customColors.surface;
-    result.card = customColors.surface; // Alias
-    result.cardBackground = customColors.surface; // Alias
+    result.card = customColors.surface;
+    result.cardBackground = customColors.surface;
   }
-  if (customColors.surfaceVariant) {
-    result.surfaceVariant = customColors.surfaceVariant;
-    result.surfaceSecondary = customColors.surfaceVariant; // Alias
+  if (customColors.surfaceVariant && !customColors.surfaceSecondary) {
+    result.surfaceSecondary = customColors.surfaceVariant;
   }
-  
-  // Apply text overrides
+
+  // Text aliases
   if (customColors.textPrimary) {
-    result.textPrimary = customColors.textPrimary;
-    result.text = customColors.textPrimary; // Alias
+    result.text = customColors.textPrimary;
   }
-  if (customColors.textSecondary) {
-    result.textSecondary = customColors.textSecondary;
+
+  // Input aliases
+  if (customColors.inputBorder && !result.inputBorder) {
+    result.inputBorder = customColors.inputBorder;
   }
-  if (customColors.textTertiary) {
-    result.textTertiary = customColors.textTertiary;
+  if (customColors.border && !customColors.inputBorder) {
+    result.inputBorder = customColors.border;
   }
 
   return result as ColorPalette;

package/src/theme/infrastructure/providers/DesignSystemProvider.tsx

@@ -4,7 +4,7 @@ import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import { useFonts } from 'expo-font';
 import { SafeAreaProvider, initialWindowMetrics } from '../../../safe-area';
 import { useThemeStore } from '../stores/themeStore';
-import { useDesignSystemTheme } from '../globalThemeStore';
+import { useDesignSystemTheme, type ThemeMode } from '../globalThemeStore';
 import type { CustomThemeColors } from '../../core/CustomColors';
 import { SplashScreen } from '../../../molecules/splash';
 import type { SplashScreenProps } from '../../../molecules/splash/types';
@@ -14,8 +14,24 @@ import { IconProvider, type IconRenderer } from '../../../atoms/IconRegistry';
 interface DesignSystemProviderProps {
   /** App content */
   children: ReactNode;
-  /** Custom theme colors to override defaults */
+  /**
+   * Custom theme colors to override defaults
+   * Apps can override ANY color key from the palette
+   * @example
+   * customColors={{
+   *   primary: '#FF6B6B',
+   *   onPrimary: '#FFFFFF',
+   *   backgroundPrimary: '#FFFFFF',
+   *   textPrimary: '#1A1A1A',
+   * }}
+   */
   customColors?: CustomThemeColors;
+  /**
+   * Initial theme mode for the app
+   * Apps control whether they start in light or dark mode
+   * @default 'light'
+   */
+  initialThemeMode?: ThemeMode;
   /** Custom fonts to load (name -> source map) */
   fonts?: Record<string, any>;
   /** Show loading indicator while initializing (default: true) */
@@ -30,10 +46,10 @@ interface DesignSystemProviderProps {
   onError?: (error: unknown) => void;
   /**
    * Custom icon renderer function
-   * Allows apps to use their own icon library instead of Ionicons
+   * Allows apps to use their own icon library
    * @example
    * iconRenderer={({ name, size, color }) => (
-   *   <MaterialIcons name={name} size={size} color={color} />
+   *   <LucideIcons name={name} size={size} color={color} />
    * )}
    */
   iconRenderer?: IconRenderer;
@@ -41,11 +57,22 @@ interface DesignSystemProviderProps {
 
 /**
  * DesignSystemProvider
- * Initializes theme store and applies custom colors.
+ *
+ * Main provider for the design system. Wraps your app and provides:
+ * - Theme (colors, spacing, typography)
+ * - Custom icon rendering
+ * - Safe area handling
+ * - Gesture handling
+ *
+ * ARCHITECTURE (based on Shopify Restyle, React Native Paper, Tamagui):
+ * - Apps provide customColors to override default palette
+ * - Apps set initialThemeMode to control light/dark mode
+ * - All design system components use these values via useAppDesignTokens
  */
 export const DesignSystemProvider: React.FC<DesignSystemProviderProps> = ({
   children,
   customColors,
+  initialThemeMode = 'light', // Default to light mode (most common)
   fonts,
   showLoadingIndicator = true,
   splashConfig,
@@ -55,12 +82,14 @@ export const DesignSystemProvider: React.FC<DesignSystemProviderProps> = ({
   iconRenderer,
 }: DesignSystemProviderProps) => {
   const [isInitialized, setIsInitialized] = useState(false);
-  
+
   // Load fonts if provided
   const [fontsLoaded, fontError] = fonts ? useFonts(fonts) : [true, null];
-  
+
   const initialize = useThemeStore((state) => state.initialize);
+  const setThemeMode = useThemeStore((state) => state.setThemeMode);
   const setCustomColors = useDesignSystemTheme((state) => state.setCustomColors);
+  const setGlobalThemeMode = useDesignSystemTheme((state) => state.setThemeMode);
 
   useEffect(() => {
     // Apply custom colors if provided
@@ -68,16 +97,22 @@ export const DesignSystemProvider: React.FC<DesignSystemProviderProps> = ({
       setCustomColors(customColors);
     }
 
-    // Initialize theme store
+    // Set initial theme mode from app
+    setGlobalThemeMode(initialThemeMode);
+
+    // Initialize theme store with the initial theme mode
     initialize()
-      .then(() => {
+      .then(async () => {
+        // After initialization, set the theme mode from app config
+        // This overrides any persisted theme mode if app explicitly sets one
+        await setThemeMode(initialThemeMode);
         setIsInitialized(true);
       })
       .catch((error) => {
         setIsInitialized(true); // Still render app even on error
         onError?.(error);
       });
-  }, [initialize, customColors, setCustomColors, onError]);
+  }, [initialize, customColors, initialThemeMode, setCustomColors, setGlobalThemeMode, setThemeMode, onError]);
 
   // Handle initialization completion when both theme and fonts are ready
   useEffect(() => {