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

package/src/typography/__tests__/textStyleUtils.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Tests for typography style utilities
+ */
+
+import { getTextStyle, isTextStyleVariant, getAllTextStyleVariants } from '../presentation/utils/textStyleUtils';
+import type { TextStyleVariant } from '../domain/entities/TypographyTypes';
+import type { DesignTokens } from '@umituz/react-native-design-system-theme';
+
+const mockTokens: DesignTokens = {
+  colors: {
+    textPrimary: '#000000',
+    textSecondary: '#666666',
+    textTertiary: '#999999',
+    textDisabled: '#CCCCCC',
+    textInverse: '#FFFFFF',
+    onSurface: '#000000',
+    onBackground: '#000000',
+    onPrimary: '#FFFFFF',
+    onSecondary: '#FFFFFF',
+    onSuccess: '#FFFFFF',
+    onError: '#FFFFFF',
+    onWarning: '#000000',
+    onInfo: '#FFFFFF',
+    success: '#4CAF50',
+    error: '#F44336',
+    warning: '#FF9800',
+    info: '#2196F3',
+    primary: '#2196F3',
+    secondary: '#FF9800',
+    tertiary: '#9C27B0',
+    surface: '#FFFFFF',
+    surfaceVariant: '#F5F5F5',
+    background: '#FFFFFF',
+  },
+  typography: {
+    displayLarge: { fontSize: 57, fontWeight: '400' },
+    displayMedium: { fontSize: 45, fontWeight: '400' },
+    displaySmall: { fontSize: 36, fontWeight: '400' },
+    headlineLarge: { fontSize: 32, fontWeight: '400' },
+    headlineMedium: { fontSize: 28, fontWeight: '400' },
+    headlineSmall: { fontSize: 24, fontWeight: '400' },
+    titleLarge: { fontSize: 22, fontWeight: '500' },
+    titleMedium: { fontSize: 16, fontWeight: '500' },
+    titleSmall: { fontSize: 14, fontWeight: '500' },
+    bodyLarge: { fontSize: 16, fontWeight: '400' },
+    bodyMedium: { fontSize: 14, fontWeight: '400' },
+    bodySmall: { fontSize: 12, fontWeight: '400' },
+    labelLarge: { fontSize: 14, fontWeight: '500' },
+    labelMedium: { fontSize: 12, fontWeight: '500' },
+    labelSmall: { fontSize: 11, fontWeight: '500' },
+  },
+  spacing: {},
+  shadows: {},
+  borderRadius: {},
+  iconSizes: {},
+  opacity: {},
+  avatarSizes: {},
+  borders: {},
+};
+
+describe('getTextStyle', () => {
+  test('should throw error when tokens is null', () => {
+    expect(() => getTextStyle('bodyLarge', null as any)).toThrow(
+      'Invalid design tokens: tokens and tokens.typography are required'
+    );
+  });
+
+  test('should throw error when tokens is undefined', () => {
+    expect(() => getTextStyle('bodyLarge', undefined as any)).toThrow(
+      'Invalid design tokens: tokens and tokens.typography are required'
+    );
+  });
+
+  test('should throw error when tokens.typography is null', () => {
+    expect(() => getTextStyle('bodyLarge', { typography: null } as any)).toThrow(
+      'Invalid design tokens: tokens and tokens.typography are required'
+    );
+  });
+
+  test('should return correct style for displayLarge', () => {
+    const result = getTextStyle('displayLarge', mockTokens);
+    expect(result).toEqual({ fontSize: 57, fontWeight: '400' });
+  });
+
+  test('should return correct style for headlineMedium', () => {
+    const result = getTextStyle('headlineMedium', mockTokens);
+    expect(result).toEqual({ fontSize: 28, fontWeight: '400' });
+  });
+
+  test('should return correct style for titleSmall', () => {
+    const result = getTextStyle('titleSmall', mockTokens);
+    expect(result).toEqual({ fontSize: 14, fontWeight: '500' });
+  });
+
+  test('should return correct style for bodyMedium', () => {
+    const result = getTextStyle('bodyMedium', mockTokens);
+    expect(result).toEqual({ fontSize: 14, fontWeight: '400' });
+  });
+
+  test('should return correct style for labelSmall', () => {
+    const result = getTextStyle('labelSmall', mockTokens);
+    expect(result).toEqual({ fontSize: 11, fontWeight: '500' });
+  });
+
+  test('should return fallback style for unknown variant', () => {
+    const result = getTextStyle('unknownVariant' as TextStyleVariant, mockTokens);
+    expect(result).toEqual({ fontSize: 16, fontWeight: '400' }); // bodyLarge fallback
+  });
+});
+
+describe('isTextStyleVariant', () => {
+  test('should return true for valid variants', () => {
+    expect(isTextStyleVariant('displayLarge')).toBe(true);
+    expect(isTextStyleVariant('headlineMedium')).toBe(true);
+    expect(isTextStyleVariant('titleSmall')).toBe(true);
+    expect(isTextStyleVariant('bodyMedium')).toBe(true);
+    expect(isTextStyleVariant('labelSmall')).toBe(true);
+  });
+
+  test('should return false for invalid variants', () => {
+    expect(isTextStyleVariant('invalid')).toBe(false);
+    expect(isTextStyleVariant('display')).toBe(false);
+    expect(isTextStyleVariant('')).toBe(false);
+    expect(isTextStyleVariant('body')).toBe(false);
+  });
+});
+
+describe('getAllTextStyleVariants', () => {
+  test('should return all text style variants', () => {
+    const variants = getAllTextStyleVariants();
+    
+    expect(variants).toHaveLength(15);
+    expect(variants).toContain('displayLarge');
+    expect(variants).toContain('displayMedium');
+    expect(variants).toContain('displaySmall');
+    expect(variants).toContain('headlineLarge');
+    expect(variants).toContain('headlineMedium');
+    expect(variants).toContain('headlineSmall');
+    expect(variants).toContain('titleLarge');
+    expect(variants).toContain('titleMedium');
+    expect(variants).toContain('titleSmall');
+    expect(variants).toContain('bodyLarge');
+    expect(variants).toContain('bodyMedium');
+    expect(variants).toContain('bodySmall');
+    expect(variants).toContain('labelLarge');
+    expect(variants).toContain('labelMedium');
+    expect(variants).toContain('labelSmall');
+  });
+
+  test('should return readonly array', () => {
+    const variants = getAllTextStyleVariants();
+    expect(Array.isArray(variants)).toBe(true);
+  });
+});
+
+describe('TextStyleVariant validation', () => {
+  test('should validate all defined text style variants', () => {
+    const validVariants: TextStyleVariant[] = getAllTextStyleVariants();
+
+    validVariants.forEach(variant => {
+      const result = getTextStyle(variant, mockTokens);
+      expect(result).toHaveProperty('fontSize');
+      expect(result).toHaveProperty('fontWeight');
+      expect(typeof result.fontSize).toBe('number');
+      expect(typeof result.fontWeight).toBe('string');
+    });
+  });
+});

package/src/typography/domain/entities/TypographyTypes.ts

@@ -0,0 +1,88 @@
+/**
+ * Typography Types - Material Design 3 Text Style Variants
+ * 
+ * This file defines all typography-related types for React Native applications.
+ * These types are used by components like AtomicText to ensure type-safe typography usage.
+ * 
+ * @fileoverview Provides type definitions for Material Design 3 typography system
+ * @author Ümit UZ <umit@umituz.com>
+ * @since 1.0.0
+ * @version 1.2.0
+ */
+
+/**
+ * Material Design 3 Text Style Variants
+ * 
+ * These variants correspond to Material Design 3 typography scale:
+ * - Display: Largest text (57px, 45px, 36px)
+ * - Headline: Section headers (32px, 28px, 24px)
+ * - Title: Card titles, list headers (22px, 16px, 14px)
+ * - Body: Main content text (16px, 14px, 12px)
+ * - Label: UI labels, buttons (14px, 12px, 11px)
+ */
+export type TextStyleVariant =
+  | 'displayLarge'
+  | 'displayMedium'
+  | 'displaySmall'
+  | 'headlineLarge'
+  | 'headlineMedium'
+  | 'headlineSmall'
+  | 'titleLarge'
+  | 'titleMedium'
+  | 'titleSmall'
+  | 'bodyLarge'
+  | 'bodyMedium'
+  | 'bodySmall'
+  | 'labelLarge'
+  | 'labelMedium'
+  | 'labelSmall';
+
+/**
+ * Material Design 3 Text Color Variants
+ * 
+ * TEXT COLORS (for text on surfaces):
+ * - textPrimary, textSecondary, textTertiary: General text colors
+ * - onSurface, onBackground: Text on surface/background
+ * 
+ * ON COLORS (for text on colored backgrounds):
+ * - onPrimary, onSecondary: Text on primary/secondary colored backgrounds
+ * - onSuccess, onError, onWarning, onInfo: Text on semantic colored backgrounds
+ * 
+ * SEMANTIC COLORS (can be used as text colors):
+ * - success, error, warning, info: Semantic colors (can be text or background)
+ * 
+ * NOTE: 'primary' and 'secondary' are BACKGROUND colors, not text colors.
+ * Use 'onPrimary'/'onSecondary' for text on colored backgrounds, or
+ * 'textPrimary'/'textSecondary' for general text.
+ */
+export type ColorVariant =
+  // General text colors (Material Design 3)
+  | 'textPrimary'
+  | 'textSecondary'
+  | 'textTertiary'
+  | 'textDisabled'
+  | 'textInverse'
+  // Text on surfaces (Material Design 3)
+  | 'onSurface'
+  | 'onBackground'
+  // Text on colored backgrounds (Material Design 3)
+  | 'onPrimary'
+  | 'onSecondary'
+  | 'onSuccess'
+  | 'onError'
+  | 'onWarning'
+  | 'onInfo'
+  // Semantic colors (can be used as text)
+  | 'success'
+  | 'error'
+  | 'warning'
+  | 'info'
+  // Legacy support (deprecated - use textPrimary/textSecondary instead)
+  | 'primary'
+  | 'secondary'
+  | 'tertiary'
+  | 'disabled'
+  | 'inverse'
+  // Legacy: surfaceVariant is a background color, maps to textSecondary
+  | 'surfaceVariant';
+

package/src/typography/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @umituz/react-native-design-system-typography - Public API
+ *
+ * Typography types and utilities for React Native applications
+ * Material Design 3 text styles and color variants
+ *
+ * This package provides:
+ * - Typography type definitions (TextStyleVariant, ColorVariant)
+ * - Text color utility functions
+ * - Type-safe typography helpers
+ *
+ * Usage:
+ *   import { TextStyleVariant, ColorVariant, getTextColor } from '@umituz/react-native-design-system-typography';
+ */
+
+// =============================================================================
+// DOMAIN LAYER - Entities (Types)
+// =============================================================================
+
+export type {
+  TextStyleVariant,
+  ColorVariant,
+} from './domain/entities/TypographyTypes';
+
+// =============================================================================
+// PRESENTATION LAYER - Utilities
+// =============================================================================
+
+export {
+  getTextColor,
+} from './presentation/utils/textColorUtils';
+
+export {
+  getTextStyle,
+  isTextStyleVariant,
+  getAllTextStyleVariants,
+  clearTypographyCache,
+} from './presentation/utils/textStyleUtils';
+
+export {
+  clearColorCache,
+} from './presentation/utils/textColorUtils';
+
+export {
+  isValidHexColor,
+  isValidRgbColor,
+  isValidHslColor,
+  isValidNamedColor,
+  isValidColor,
+  getColorFormat,
+  normalizeColor,
+} from './presentation/utils/colorValidationUtils';
+

package/src/typography/presentation/utils/colorValidationUtils.ts

@@ -0,0 +1,133 @@
+/**
+ * Color Validation Utilities
+ * 
+ * Helper functions for validating color formats and values.
+ * These utilities ensure color strings are in valid formats.
+ * 
+ * @fileoverview Provides color validation utilities
+ * @author Ümit UZ <umit@umituz.com>
+ * @since 1.2.0
+ * @version 1.2.0
+ */
+
+/**
+ * Regular expressions for color format validation
+ */
+const COLOR_PATTERNS = {
+  // #RGB, #RRGGBB
+  hex: /^#([A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$/,
+  // rgb(R, G, B), rgba(R, G, B, A)
+  rgb: /^rgba?\(\s*(\d{1,3}%?)\s*,\s*(\d{1,3}%?)\s*,\s*(\d{1,3}%?)\s*(?:,\s*([01]?\.?\d*)\s*)?\)$/,
+  // hsl(H, S, L), hsla(H, S, L, A)
+  hsl: /^hsla?\(\s*(\d{1,3})\s*,\s*(\d{1,3}%)\s*,\s*(\d{1,3}%)\s*(?:,\s*([01]?\.?\d*)\s*)?\)$/,
+  // CSS color names (limited to common ones)
+  named: /^(red|blue|green|yellow|orange|purple|pink|brown|black|white|gray|grey|transparent|inherit|initial|unset|currentcolor)$/i,
+};
+
+/**
+ * Check if a string is a valid hex color
+ * 
+ * @param color - Color string to validate
+ * @returns True if valid hex color
+ */
+export function isValidHexColor(color: string): boolean {
+  return COLOR_PATTERNS.hex.test(color);
+}
+
+/**
+ * Check if a string is a valid RGB/RGBA color
+ * 
+ * @param color - Color string to validate
+ * @returns True if valid RGB/RGBA color
+ */
+export function isValidRgbColor(color: string): boolean {
+  if (!COLOR_PATTERNS.rgb.test(color)) {
+    return false;
+  }
+  
+  // Additional validation for RGB values
+  const match = color.match(/\d+/g);
+  if (!match || match.length < 3) return false;
+  
+  const [r, g, b] = match.map(Number);
+  return r >= 0 && r <= 255 && g >= 0 && g <= 255 && b >= 0 && b <= 255;
+}
+
+/**
+ * Check if a string is a valid HSL/HSLA color
+ * 
+ * @param color - Color string to validate
+ * @returns True if valid HSL/HSLA color
+ */
+export function isValidHslColor(color: string): boolean {
+  if (!COLOR_PATTERNS.hsl.test(color)) {
+    return false;
+  }
+  
+  // Additional validation for HSL values
+  const match = color.match(/\d+/g);
+  if (!match || match.length < 3) return false;
+  
+  const [h, s, l] = match.map(Number);
+  return h >= 0 && h <= 360 && s >= 0 && s <= 100 && l >= 0 && l <= 100;
+}
+
+/**
+ * Check if a string is a valid CSS named color
+ * 
+ * @param color - Color string to validate
+ * @returns True if valid CSS named color
+ */
+export function isValidNamedColor(color: string): boolean {
+  return COLOR_PATTERNS.named.test(color);
+}
+
+/**
+ * Check if a string is a valid color in any supported format
+ * 
+ * @param color - Color string to validate
+ * @returns True if valid color in any format
+ */
+export function isValidColor(color: string): boolean {
+  return isValidHexColor(color) || 
+         isValidRgbColor(color) || 
+         isValidHslColor(color) || 
+         isValidNamedColor(color);
+}
+
+/**
+ * Get the format of a color string
+ * 
+ * @param color - Color string to analyze
+ * @returns Color format or 'unknown' if not recognized
+ */
+export function getColorFormat(color: string): 'hex' | 'rgb' | 'hsl' | 'named' | 'unknown' {
+  if (isValidHexColor(color)) return 'hex';
+  if (isValidRgbColor(color)) return 'rgb';
+  if (isValidHslColor(color)) return 'hsl';
+  if (isValidNamedColor(color)) return 'named';
+  return 'unknown';
+}
+
+/**
+ * Normalize a color string to a consistent format
+ * 
+ * @param color - Color string to normalize
+ * @returns Normalized color string
+ */
+export function normalizeColor(color: string): string {
+  if (!isValidColor(color)) {
+    return color;
+  }
+
+  // Convert 3-digit hex to 6-digit
+  if (isValidHexColor(color) && color.length === 4) {
+    const r = color[1];
+    const g = color[2];
+    const b = color[3];
+    return `#${r}${r}${g}${g}${b}${b}`;
+  }
+
+  // Convert to lowercase for consistency
+  return color.toLowerCase();
+}

package/src/typography/presentation/utils/textColorUtils.ts

@@ -0,0 +1,205 @@
+/**
+ * Text Color Utilities
+ * 
+ * Helper functions for resolving text colors from design tokens.
+ * These utilities are used by components like AtomicText to map color variants
+ * to actual color values from theme.
+ * 
+ * @fileoverview Provides color resolution utilities for Material Design 3
+ * @author Ümit UZ <umit@umituz.com>
+ * @since 1.0.0
+ * @version 1.2.0
+ * 
+ * @example
+ * ```typescript
+ * import { getTextColor } from '@umituz/react-native-design-system-typography';
+ * import { useAppDesignTokens } from '@umituz/react-native-design-system-theme';
+ * 
+ * const MyComponent = () => {
+ *   const tokens = useAppDesignTokens();
+ *   const textColor = getTextColor('textPrimary', tokens);
+ *   return <Text style={{ color: textColor }}>Hello</Text>;
+ * };
+ * ```
+ */
+
+import type { ColorVariant } from '../../domain/entities/TypographyTypes';
+import type { DesignTokens } from '../../../theme';
+
+// Cache for color variant validation to improve performance
+const COLOR_VARIANT_SET = new Set<string>([
+  'textPrimary',
+  'textSecondary',
+  'textTertiary',
+  'textDisabled',
+  'textInverse',
+  'onSurface',
+  'onBackground',
+  'onPrimary',
+  'onSecondary',
+  'onSuccess',
+  'onError',
+  'onWarning',
+  'onInfo',
+  'success',
+  'error',
+  'warning',
+  'info',
+  'primary',
+  'secondary',
+  'tertiary',
+  'disabled',
+  'inverse',
+  'surfaceVariant',
+]);
+
+/**
+ * Color mapper interface for dependency injection
+ */
+interface ColorMapper {
+  getColor(color: ColorVariant, tokens: DesignTokens): string;
+}
+
+/**
+ * Material Design 3 color mapper implementation
+ */
+class MaterialColorMapper implements ColorMapper {
+  getColor(color: ColorVariant, tokens: DesignTokens): string {
+    switch (color) {
+      // General text colors (Material Design 3)
+      case 'textPrimary':
+        return tokens.colors.textPrimary;
+      case 'textSecondary':
+        return tokens.colors.textSecondary;
+      case 'textTertiary':
+        return tokens.colors.textTertiary;
+      case 'textDisabled':
+        return tokens.colors.textDisabled;
+      case 'textInverse':
+        return tokens.colors.textInverse;
+
+      // Text on surfaces (Material Design 3)
+      case 'onSurface':
+        return tokens.colors.onSurface;
+      case 'onBackground':
+        return tokens.colors.onBackground;
+
+      // Text on colored backgrounds (Material Design 3)
+      case 'onPrimary':
+        return tokens.colors.onPrimary;
+      case 'onSecondary':
+        return tokens.colors.onSecondary;
+      case 'onSuccess':
+        return tokens.colors.onSuccess;
+      case 'onError':
+        return tokens.colors.onError;
+      case 'onWarning':
+        return tokens.colors.onWarning;
+      case 'onInfo':
+        return tokens.colors.onInfo;
+
+      // Semantic colors (can be used as text)
+      case 'success':
+        return tokens.colors.success;
+      case 'error':
+        return tokens.colors.error;
+      case 'warning':
+        return tokens.colors.warning;
+      case 'info':
+        return tokens.colors.info;
+
+      // Legacy support (deprecated - maps to new names)
+      case 'primary':
+        return tokens.colors.textPrimary;
+      case 'secondary':
+        return tokens.colors.textSecondary;
+      case 'tertiary':
+        return tokens.colors.textTertiary;
+      case 'disabled':
+        return tokens.colors.textDisabled;
+      case 'inverse':
+        return tokens.colors.textInverse;
+      case 'surfaceVariant':
+        return tokens.colors.textSecondary;
+
+      default:
+        if (__DEV__) {
+          // eslint-disable-next-line no-console
+          console.warn(`Unknown color variant: ${color}`);
+        }
+        return tokens.colors.textPrimary;
+    }
+  }
+}
+
+// Singleton instance for performance
+const colorMapper = new MaterialColorMapper();
+
+// Cache for resolved colors to improve performance
+const colorCache = new Map<string, string>();
+
+/**
+ * Clear the color cache
+ * Useful for testing or theme changes
+ */
+export function clearColorCache(): void {
+  colorCache.clear();
+}
+
+/**
+ * Get text color from design tokens based on color variant
+ * 
+ * @param color - Color variant or custom color string
+ * @param tokens - Design tokens containing color values
+ * @returns Resolved color string
+ * 
+ * @example
+ * ```tsx
+ * const tokens = useAppDesignTokens();
+ * const textColor = getTextColor('textPrimary', tokens);
+ * ```
+ */
+export function getTextColor(
+  color: ColorVariant | string | undefined,
+  tokens: DesignTokens,
+): string {
+  // Validate tokens parameter
+  if (!tokens || !tokens.colors) {
+    throw new Error('Invalid design tokens: tokens and tokens.colors are required');
+  }
+
+  if (!color) {
+    return tokens.colors.textPrimary;
+  }
+
+  // If it's a custom color string (not a variant), return as-is
+  if (typeof color === 'string' && !isColorVariant(color)) {
+    return color;
+  }
+
+  // Create cache key - use hash instead of JSON.stringify to prevent memory leaks
+  const cacheKey = `${color}_${Object.keys(tokens.colors).length}_${tokens.colors.textPrimary}`;
+
+  // Check cache first
+  if (colorCache.has(cacheKey)) {
+    return colorCache.get(cacheKey)!;
+  }
+
+  // Resolve color and cache it
+  const resolvedColor = colorMapper.getColor(color as ColorVariant, tokens);
+  colorCache.set(cacheKey, resolvedColor);
+
+  return resolvedColor;
+}
+
+/**
+ * Check if a string is a valid ColorVariant
+ * Uses Set for O(1) lookup performance
+ * 
+ * @param value - String to check
+ * @returns True if value is a ColorVariant
+ */
+function isColorVariant(value: string): value is ColorVariant {
+  return COLOR_VARIANT_SET.has(value);
+}
+