@umituz/react-native-design-system 1.15.0 → 2.0.1

package/src/responsive/validation.ts

@@ -0,0 +1,158 @@
+/**
+ * Input Validation Utilities
+ *
+ * Centralized validation for all responsive utility functions.
+ * Ensures type safety and prevents runtime errors.
+ */
+
+import { VALIDATION_CONSTRAINTS } from './config';
+
+/**
+ * Custom error class for responsive utilities
+ */
+export class ResponsiveValidationError extends Error {
+  constructor(message: string) {
+    super(`[Responsive] ${message}`);
+    this.name = 'ResponsiveValidationError';
+  }
+}
+
+/**
+ * Validates a numeric input parameter
+ * @param value - The value to validate
+ * @param paramName - Parameter name for error messages
+ * @param min - Minimum allowed value
+ * @param max - Maximum allowed value
+ * @throws ResponsiveValidationError if validation fails
+ */
+export const validateNumber = (
+  value: number | undefined,
+  paramName: string,
+  min: number = VALIDATION_CONSTRAINTS.MIN_BASE_SIZE,
+  max: number = VALIDATION_CONSTRAINTS.MAX_BASE_SIZE
+): number => {
+  if (value === undefined || value === null) {
+    throw new ResponsiveValidationError(`${paramName} is required`);
+  }
+
+  if (typeof value !== 'number' || isNaN(value)) {
+    throw new ResponsiveValidationError(`${paramName} must be a valid number`);
+  }
+
+  if (!isFinite(value)) {
+    throw new ResponsiveValidationError(`${paramName} must be a finite number`);
+  }
+
+  if (value < min) {
+    throw new ResponsiveValidationError(`${paramName} must be at least ${min}`);
+  }
+
+  if (value > max) {
+    throw new ResponsiveValidationError(`${paramName} must be at most ${max}`);
+  }
+
+  return value;
+};
+
+/**
+ * Validates font size input
+ * @param fontSize - Font size to validate
+ * @param paramName - Parameter name for error messages
+ * @returns Validated font size
+ */
+export const validateFontSize = (fontSize: number, paramName: string = 'fontSize'): number => {
+  return validateNumber(
+    fontSize,
+    paramName,
+    VALIDATION_CONSTRAINTS.MIN_BASE_FONT_SIZE,
+    VALIDATION_CONSTRAINTS.MAX_BASE_FONT_SIZE
+  );
+};
+
+/**
+ * Validates screen dimensions
+ * @param width - Screen width
+ * @param height - Screen height
+ * @throws ResponsiveValidationError if validation fails
+ */
+export const validateScreenDimensions = (width: number, height: number): void => {
+  validateNumber(
+    width,
+    'width',
+    VALIDATION_CONSTRAINTS.MIN_SCREEN_DIMENSION,
+    VALIDATION_CONSTRAINTS.MAX_SCREEN_DIMENSION
+  );
+  
+  validateNumber(
+    height,
+    'height',
+    VALIDATION_CONSTRAINTS.MIN_SCREEN_DIMENSION,
+    VALIDATION_CONSTRAINTS.MAX_SCREEN_DIMENSION
+  );
+};
+
+/**
+ * Validates safe area insets
+ * @param insets - Safe area insets object
+ * @throws ResponsiveValidationError if validation fails
+ */
+export const validateSafeAreaInsets = (insets: {
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+}): void => {
+  if (!insets || typeof insets !== 'object') {
+    throw new ResponsiveValidationError('Safe area insets must be an object');
+  }
+
+  const { top = 0, bottom = 0, left = 0, right = 0 } = insets;
+
+  validateNumber(top, 'insets.top', 0, 1000);
+  validateNumber(bottom, 'insets.bottom', 0, 1000);
+  validateNumber(left, 'insets.left', 0, 1000);
+  validateNumber(right, 'insets.right', 0, 1000);
+};
+
+/**
+ * Validates grid column parameters
+ * @param mobileColumns - Number of columns for mobile
+ * @param tabletColumns - Number of columns for tablet
+ * @throws ResponsiveValidationError if validation fails
+ */
+export const validateGridColumns = (
+  mobileColumns?: number,
+  tabletColumns?: number
+): void => {
+  if (mobileColumns !== undefined) {
+    validateNumber(mobileColumns, 'mobileColumns', 1, 20);
+  }
+  
+  if (tabletColumns !== undefined) {
+    validateNumber(tabletColumns, 'tabletColumns', 1, 20);
+  }
+};
+
+/**
+ * Clamps a value between min and max bounds
+ * @param value - Value to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped value
+ */
+export const clamp = (value: number, min: number, max: number): number => {
+  return Math.min(Math.max(value, min), max);
+};
+
+/**
+ * Safely calculates a percentage of a value
+ * @param value - Base value
+ * @param percentage - Percentage (0-1)
+ * @returns Calculated percentage
+ */
+export const safePercentage = (value: number, percentage: number): number => {
+  const validatedValue = validateNumber(value, 'value', 0, Infinity);
+  const validatedPercentage = clamp(percentage, 0, 1);
+  
+  return validatedValue * validatedPercentage;
+};

package/src/theme/core/BaseTokens.ts

@@ -0,0 +1,42 @@
+/**
+ * BASE TOKENS - Main Export
+ * 
+ * Aggregates all token modules into BASE_TOKENS
+ */
+
+import { spacing } from './tokens/Spacing';
+import { typography } from './tokens/Typography';
+import { borders } from './tokens/Borders';
+import { iconSizes, opacity, avatarSizes, sizes } from './tokens/Sizes';
+import type { BaseTokens } from './tokens/BaseTokens';
+
+/**
+ * BASE_TOKENS - Static design tokens
+ * These values don't change with theme (light/dark)
+ */
+export const BASE_TOKENS: BaseTokens = {
+  spacing,
+  typography,
+  borders,
+  iconSizes,
+  opacity,
+  avatarSizes,
+  sizes,
+};
+
+// Convenience exports
+export { spacing, typography, borders, iconSizes, opacity, avatarSizes, sizes };
+
+
+
+// Type exports
+export type {
+  BaseTokens,
+  Spacing,
+  Typography,
+  Borders,
+  IconSizes,
+  Opacity,
+  AvatarSizes,
+  ComponentSizes
+} from './tokens/BaseTokens';

package/src/theme/core/ColorPalette.ts

@@ -0,0 +1,29 @@
+/**
+ * COLOR PALETTE - Main Export
+ * 
+ * Aggregates all color modules and provides theme utilities
+ */
+
+import { lightColors } from './colors/LightColors';
+import { darkColors } from './colors/DarkColors';
+import { withAlpha, isValidHexColor } from './colors/ColorUtils';
+
+export type ColorPalette = typeof lightColors;
+export type ThemeMode = 'light' | 'dark';
+
+/**
+ * Get color palette for specific theme mode
+ * @param mode - 'light' or 'dark'
+ * @returns Color palette object
+ */
+export const getColorPalette = (mode: ThemeMode): ColorPalette => {
+  return mode === 'dark' ? darkColors : lightColors;
+};
+
+// Export all colors and utilities
+export { 
+  lightColors, 
+  darkColors, 
+  withAlpha, 
+  isValidHexColor 
+};

package/src/theme/core/CustomColors.ts

@@ -0,0 +1,122 @@
+/**
+ * Custom Colors Types
+ * 
+ * Types for custom theme color overrides
+ */
+
+import type { ColorPalette } from './ColorPalette';
+import { isValidHexColor } from './colors/ColorUtils';
+
+/**
+ * Custom theme colors that can override default colors
+ */
+export interface CustomThemeColors {
+  primary?: string;
+  primaryLight?: string;
+  primaryDark?: string;
+  secondary?: string;
+  secondaryLight?: string;
+  secondaryDark?: string;
+  accent?: string;
+  accentLight?: string;
+  accentDark?: string;
+  buttonPrimary?: string;
+  buttonSecondary?: string;
+}
+
+/**
+ * Validate custom colors object
+ * @param customColors - Custom colors to validate
+ * @returns true if all colors are valid hex format
+ */
+export const validateCustomColors = (customColors: CustomThemeColors): boolean => {
+  const colorValues = Object.values(customColors).filter(Boolean) as string[];
+  
+  for (const color of colorValues) {
+    if (!isValidHexColor(color)) {
+      if (__DEV__) {
+        console.warn('[validateCustomColors] Invalid hex color:', color);
+      }
+      return false;
+    }
+  }
+  
+  return true;
+};
+
+/**
+ * Apply custom colors to color palette
+ * @param palette - Base color palette
+ * @param customColors - Custom colors to apply
+ * @returns Color palette with custom colors applied
+ */
+export const applyCustomColors = (
+  palette: ColorPalette,
+  customColors?: CustomThemeColors,
+): ColorPalette => {
+  if (!customColors) {
+    return palette;
+  }
+
+  // Validate custom colors
+  if (!validateCustomColors(customColors)) {
+    if (__DEV__) {
+      console.error('[applyCustomColors] Invalid custom colors provided, using defaults');
+    }
+    return 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 custom secondary colors
+  if (customColors.secondary) {
+    result.secondary = customColors.secondary;
+    if (!customColors.buttonSecondary) {
+      result.buttonSecondary = customColors.secondary;
+    }
+  }
+  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 custom button colors (override primary/secondary if set)
+  if (customColors.buttonPrimary) {
+    result.buttonPrimary = customColors.buttonPrimary;
+  }
+  if (customColors.buttonSecondary) {
+    result.buttonSecondary = customColors.buttonSecondary;
+  }
+
+  return result as ColorPalette;
+};
+

package/src/theme/core/NavigationTheme.ts

@@ -0,0 +1,72 @@
+import type { ColorPalette, ThemeMode } from "./ColorPalette";
+import type { ExtendedColorPalette } from "./themes";
+
+/**
+ * Font weight type compatible with React Navigation v7
+ */
+type FontWeight =
+  | "normal"
+  | "bold"
+  | "100"
+  | "200"
+  | "300"
+  | "400"
+  | "500"
+  | "600"
+  | "700"
+  | "800"
+  | "900";
+
+/**
+ * Font configuration for navigation theme
+ */
+interface FontConfig {
+  fontFamily: string;
+  fontWeight: FontWeight;
+}
+
+/**
+ * Navigation theme type compatible with React Navigation v7
+ */
+export interface NavigationTheme {
+  dark: boolean;
+  colors: {
+    primary: string;
+    background: string;
+    card: string;
+    text: string;
+    border: string;
+    notification: string;
+  };
+  fonts: {
+    regular: FontConfig;
+    medium: FontConfig;
+    bold: FontConfig;
+    heavy: FontConfig;
+  };
+}
+
+/**
+ * Creates a React Navigation theme from design system colors
+ * Compatible with React Navigation v7+
+ */
+export const createNavigationTheme = (
+  colors: ColorPalette | ExtendedColorPalette,
+  themeMode: ThemeMode
+): NavigationTheme => ({
+  dark: themeMode === "dark",
+  colors: {
+    primary: colors.primary,
+    background: colors.backgroundPrimary,
+    card: colors.surface,
+    text: colors.textPrimary,
+    border: colors.borderLight,
+    notification: colors.error,
+  },
+  fonts: {
+    regular: { fontFamily: "System", fontWeight: "400" },
+    medium: { fontFamily: "System", fontWeight: "500" },
+    bold: { fontFamily: "System", fontWeight: "700" },
+    heavy: { fontFamily: "System", fontWeight: "800" },
+  },
+});

package/src/theme/core/TokenFactory.ts

@@ -0,0 +1,103 @@
+/**
+ * TOKEN FACTORY - THEME INJECTION LOGIC
+ *
+ * ✅ Factory Pattern for creating complete design tokens
+ * ✅ Combines static tokens (BaseTokens) + dynamic colors (ColorPalette)
+ * ✅ Type-safe token generation
+ * ✅ Zero duplication - SINGLE SOURCE OF TRUTH
+ *
+ * @module TokenFactory
+ */
+
+import { BASE_TOKENS } from './BaseTokens';
+import { getColorPalette, withAlpha, type ThemeMode, type ColorPalette } from './ColorPalette';
+import { applyCustomColors, type CustomThemeColors } from './CustomColors';
+
+// =============================================================================
+// DESIGN TOKENS TYPE
+// =============================================================================
+
+/**
+ * Complete design tokens shape
+ * Combines static tokens (spacing, typography, borders) + dynamic colors
+ */
+export type DesignTokens = {
+  colors: ColorPalette;
+  spacing: typeof BASE_TOKENS.spacing;
+  typography: typeof BASE_TOKENS.typography;
+  iconSizes: typeof BASE_TOKENS.iconSizes;
+  opacity: typeof BASE_TOKENS.opacity;
+  avatarSizes: typeof BASE_TOKENS.avatarSizes;
+  borders: typeof BASE_TOKENS.borders & {
+    card: typeof BASE_TOKENS.borders.card & { borderColor: string };
+    input: typeof BASE_TOKENS.borders.input & { borderColor: string };
+  };
+};
+
+// =============================================================================
+// TOKEN FACTORY FUNCTION
+// =============================================================================
+
+/**
+ * Create complete design tokens for a specific theme mode
+ *
+ * @param mode - Theme mode ('light' or 'dark')
+ * @param customColors - Optional custom colors to override default colors
+ * @returns Complete design tokens object
+ *
+ * @example
+ * ```typescript
+ * const lightTokens = createDesignTokens('light');
+ * const darkTokens = createDesignTokens('dark');
+ * const customTokens = createDesignTokens('dark', { primary: '#FF6B35' });
+ *
+ * // Use in components
+ * <View style={{ backgroundColor: lightTokens.colors.primary }}>
+ *   <Text style={lightTokens.typography.bodyLarge}>Hello!</Text>
+ * </View>
+ * ```
+ */
+export const createDesignTokens = (
+  mode: ThemeMode,
+  customColors?: CustomThemeColors,
+): DesignTokens => {
+  // Get color palette for theme mode
+  const baseColors = getColorPalette(mode);
+
+  // Apply custom colors if provided
+  const colors = applyCustomColors(baseColors, customColors);
+
+  // Combine static tokens + dynamic colors
+  return {
+    // ✅ DYNAMIC: Colors from theme mode + custom overrides
+    colors,
+
+    // ✅ STATIC: These don't change with theme
+    spacing: BASE_TOKENS.spacing,
+    typography: BASE_TOKENS.typography,
+    iconSizes: BASE_TOKENS.iconSizes,
+    opacity: BASE_TOKENS.opacity,
+    avatarSizes: BASE_TOKENS.avatarSizes,
+
+    // ✅ BORDERS: Static + injected border colors from theme
+    borders: {
+      ...BASE_TOKENS.borders,
+      card: {
+        ...BASE_TOKENS.borders.card,
+        borderColor: colors.border,
+      },
+      input: {
+        ...BASE_TOKENS.borders.input,
+        borderColor: colors.border,
+      },
+    },
+  };
+};
+
+// =============================================================================
+// UTILITY EXPORTS
+// =============================================================================
+
+export { withAlpha };
+export type { ThemeMode, ColorPalette };
+

package/src/theme/core/colors/ColorUtils.ts

@@ -0,0 +1,53 @@
+/**
+ * COLOR UTILITIES
+ * 
+ * Color manipulation and validation utilities
+ */
+
+import { DESIGN_CONSTANTS } from '../constants/DesignConstants';
+
+/**
+ * Validate hex color format
+ * @param hexColor - Hex color string to validate
+ * @returns true if valid hex color
+ */
+export const isValidHexColor = (hexColor: string): boolean => {
+  if (!hexColor || typeof hexColor !== 'string') {
+    return false;
+  }
+  
+  return DESIGN_CONSTANTS.HEX_COLOR_REGEX.test(hexColor);
+};
+
+/**
+ * Add alpha transparency to hex color
+ * @param hexColor - Hex color string (#RRGGBB or #RGB)
+ * @param alpha - Alpha value 0-1
+ * @returns Hex color with alpha (#RRGGBBAA)
+ */
+export const withAlpha = (hexColor: string, alpha: number): string => {
+  if (!isValidHexColor(hexColor)) {
+    if (__DEV__) {
+      console.warn('[withAlpha] Invalid hex color format:', hexColor);
+    }
+    return hexColor;
+  }
+
+  if (typeof alpha !== 'number' || alpha < 0 || alpha > 1) {
+    if (__DEV__) {
+      console.warn('[withAlpha] Invalid alpha value, must be 0-1:', alpha);
+    }
+    return hexColor;
+  }
+
+  // Convert 3-digit hex to 6-digit
+  const hex = hexColor.length === 4 
+    ? hexColor.split('').map(c => c + c).join('')
+    : hexColor;
+
+  const alphaHex = Math.round(alpha * 255)
+    .toString(16)
+    .padStart(2, '0');
+
+  return hex + alphaHex;
+};