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

package/src/organisms/FormContainer.tsx

@@ -0,0 +1,169 @@
+/**
+ * FormContainer Component
+ *
+ * A reusable container for forms with proper keyboard handling and responsive layout.
+ *
+ * Features:
+ * - Pure React Native implementation (no Paper dependency)
+ * - Universal keyboard handling (no platform-specific code)
+ * - ScrollView with automatic content padding
+ * - Safe area insets for bottom tab navigation overlap
+ * - Responsive max width for large screens (tablets)
+ * - Consistent vertical spacing between form elements
+ * - Theme-aware surface colors
+ * - Optimized performance with memoized styles
+ *
+ * Usage:
+ * ```tsx
+ * <FormContainer>
+ *   <AtomicInput label="Name" value={name} onChangeText={setName} />
+ *   <AtomicTextArea label="Description" value={desc} onChangeText={setDesc} />
+ *   <AtomicButton variant="primary" onPress={handleSubmit}>
+ *     Submit
+ *   </AtomicButton>
+ * </FormContainer>
+ * ```
+ *
+ * Why This Component:
+ * - Prevents keyboard from covering input fields (universal solution)
+ * - Handles safe area (notch, bottom tabs) automatically
+ * - Consistent form layout across all 100+ generated apps
+ * - Responsive design for tablets (max 700px) and phones (full width)
+ * - Automatic vertical spacing between form elements (no manual marginBottom)
+ * - Reduces boilerplate in form screens
+ * - Universal code - no platform checks, works on iOS, Android, Web
+ *
+ * Technical Details:
+ * - Uses ScrollView with contentContainerStyle for keyboard handling
+ * - Pure React Native View for surface (lightweight)
+ * - Vertical spacing via Children.map() wrapping (universal compatibility)
+ * - Safe area insets from react-native-safe-area-context
+ * - Responsive values from useResponsive hook
+ *
+ * @module FormContainer
+ */
+
+import React, { Children } from 'react';
+import {
+  ScrollView,
+  View,
+  StyleSheet,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useAppDesignTokens } from '../theme';
+import { useResponsive } from '../responsive';
+
+/**
+ * Props for FormContainer component
+ */
+export interface FormContainerProps {
+  /** Form content (inputs, buttons, etc.) */
+  children: React.ReactNode;
+  /** Container style override (for outer View) */
+  containerStyle?: StyleProp<ViewStyle>;
+  /** Content container style override (for ScrollView content) */
+  contentContainerStyle?: StyleProp<ViewStyle>;
+  /** Show vertical scroll indicator */
+  showsVerticalScrollIndicator?: boolean;
+  /** Optional test ID for E2E testing */
+  testID?: string;
+  /** Show surface border (default: true) */
+  showBorder?: boolean;
+  /** Accessibility label for the container */
+  accessibilityLabel?: string;
+  /** Accessibility hint for the container */
+  accessibilityHint?: string;
+  /** Whether the container is accessible */
+  accessible?: boolean;
+}
+
+/**
+ * FormContainer - Universal form wrapper component
+ *
+ * Wraps forms with:
+ * - Pure React Native surface
+ * - Universal keyboard handling (no platform checks)
+ * - ScrollView for content overflow
+ * - Safe area insets (bottom tabs, notch)
+ * - Responsive max width (tablets)
+ * - Theme integration
+ */
+export const FormContainer: React.FC<FormContainerProps> = ({
+  children,
+  containerStyle,
+  contentContainerStyle,
+  showsVerticalScrollIndicator = false,
+  testID,
+  showBorder = true,
+}) => {
+  const tokens = useAppDesignTokens();
+  const insets = useSafeAreaInsets();
+  const { maxContentWidth, bottomPosition } = useResponsive();
+  const formContentWidth = maxContentWidth;
+  const formBottomPadding = bottomPosition;
+  const formElementSpacing = tokens.spacing.lg;
+
+  // Create styles for form container
+  const styles = StyleSheet.create({
+    container: {
+      flex: 1,
+      backgroundColor: tokens.colors.backgroundPrimary,
+    },
+    surface: {
+      flex: 1,
+      backgroundColor: tokens.colors.surface,
+      borderWidth: showBorder ? 1 : 0,
+      borderColor: tokens.colors.border,
+      borderRadius: tokens.borders.radius.md,
+    },
+    scrollView: {
+      flex: 1,
+    },
+    contentContainer: {
+      flexGrow: 1,
+      padding: tokens.spacing.lg,
+      paddingTop: tokens.spacing.xl,
+      paddingBottom: formBottomPadding + insets.bottom,
+      maxWidth: formContentWidth,
+      alignSelf: 'center',
+      width: '100%',
+    },
+    formElementWrapper: {
+      marginBottom: formElementSpacing,
+    },
+  });
+
+  // Wrap each child with spacing View (universal gap replacement)
+  // Children.map() handles arrays, fragments, single elements correctly
+  const childrenWithSpacing = Children.map(children, (child, index) => {
+    const childArray = Children.toArray(children);
+    const childKey = (child as React.ReactElement)?.key || `child-${index}`;
+    return (
+      <View
+        key={childKey}
+        style={index < childArray.length - 1 ? styles.formElementWrapper : undefined}
+      >
+        {child}
+      </View>
+    );
+  });
+
+  return (
+    <View style={[styles.container, containerStyle]} testID={testID}>
+      <View style={styles.surface}>
+        <ScrollView
+          style={styles.scrollView}
+          contentContainerStyle={[styles.contentContainer, contentContainerStyle]}
+          keyboardShouldPersistTaps="handled"
+          keyboardDismissMode="on-drag"
+          showsVerticalScrollIndicator={showsVerticalScrollIndicator}
+          testID={testID ? `${testID}-scroll` : undefined}
+        >
+          {childrenWithSpacing}
+        </ScrollView>
+      </View>
+    </View>
+  );
+};

package/src/organisms/ScreenLayout.tsx

@@ -0,0 +1,183 @@
+/**
+ * ScreenLayout - Universal Screen Container Component
+ *
+ * Provides consistent layout structure for all screens:
+ * - SafeAreaView with configurable edges
+ * - Optional ScrollView for content
+ * - Theme-aware background colors
+ * - Optional header/footer slots
+ * - Consistent spacing and padding
+ *
+ * Usage:
+ * <ScreenLayout>
+ *   <View>Your content here</View>
+ * </ScreenLayout>
+ *
+ * Advanced:
+ * <ScreenLayout
+ *   scrollable={false}
+ *   edges={['top', 'bottom']}
+ *   header={<CustomHeader />}
+ * >
+ *   <View>Content</View>
+ * </ScreenLayout>
+ */
+
+import React, { useMemo } from 'react';
+import { View, ScrollView, StyleSheet, ViewStyle } from 'react-native';
+import { SafeAreaView, Edge } from 'react-native-safe-area-context';
+import { useAppDesignTokens } from '../theme';
+
+export interface ScreenLayoutProps {
+  /**
+   * Content to render inside the layout
+   */
+  children: React.ReactNode;
+
+  /**
+   * Enable scrolling (default: true)
+   * Set to false for screens with custom scroll logic
+   */
+  scrollable?: boolean;
+
+  /**
+   * Safe area edges to apply (default: ['top'])
+   * Common values:
+   * - ['top'] - For screens with bottom tabs
+   * - ['top', 'bottom'] - For modal screens
+   * - [] - No safe area (use cautiously)
+   */
+  edges?: Edge[];
+
+  /**
+   * Optional header component
+   * Rendered above scrollable content
+   */
+  header?: React.ReactNode;
+
+  /**
+   * Optional footer component
+   * Rendered below scrollable content
+   */
+  footer?: React.ReactNode;
+
+  /**
+   * Override background color
+   * If not provided, uses theme's backgroundPrimary
+   */
+  backgroundColor?: string;
+
+  /**
+   * Custom container style
+   */
+  containerStyle?: ViewStyle;
+
+  /**
+   * Custom content container style (for ScrollView)
+   */
+  contentContainerStyle?: ViewStyle;
+
+  /**
+   * Test ID for automation
+   */
+  testID?: string;
+
+  /**
+   * Hide vertical scroll indicator (default: false)
+   */
+  hideScrollIndicator?: boolean;
+
+  /**
+   * Enable keyboard avoiding behavior (default: false)
+   * Useful for screens with inputs
+   */
+  keyboardAvoiding?: boolean;
+
+  /**
+   * Accessibility label for the layout
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Accessibility hint for the layout
+   */
+  accessibilityHint?: string;
+
+  /**
+   * Whether the layout is accessible
+   */
+  accessible?: boolean;
+
+}
+
+export const ScreenLayout: React.FC<ScreenLayoutProps> = ({
+  children,
+  scrollable = true,
+  edges = ['top'],
+  header,
+  footer,
+  backgroundColor,
+  containerStyle,
+  contentContainerStyle,
+  testID,
+  hideScrollIndicator = false,
+  keyboardAvoiding = false,
+}) => {
+  // Automatically uses current theme from global store
+  const tokens = useAppDesignTokens();
+  const styles = useMemo(() => StyleSheet.create({
+    container: {
+      flex: 1,
+    },
+    content: {
+      flex: 1,
+    },
+    scrollView: {
+      flex: 1,
+    },
+    scrollContent: {
+      flexGrow: 1,
+      paddingHorizontal: tokens.spacing.md,
+      paddingBottom: tokens.spacing.lg,
+    },
+  }), [tokens]);
+
+  const bgColor = backgroundColor || tokens.colors.backgroundPrimary;
+
+  // Non-scrollable layout
+  if (!scrollable) {
+    return (
+      <SafeAreaView
+        style={[styles.container, { backgroundColor: bgColor }, containerStyle]}
+        edges={edges}
+        testID={testID}
+      >
+        {header}
+        <View style={[styles.content, contentContainerStyle]}>
+          {children}
+        </View>
+        {footer}
+      </SafeAreaView>
+    );
+  }
+
+  // Scrollable layout (default)
+  return (
+    <SafeAreaView
+      style={[styles.container, { backgroundColor: bgColor }, containerStyle]}
+      edges={edges}
+      testID={testID}
+    >
+      {header}
+      <ScrollView
+        style={styles.scrollView}
+        contentContainerStyle={[styles.scrollContent, contentContainerStyle]}
+        showsVerticalScrollIndicator={!hideScrollIndicator}
+        keyboardShouldPersistTaps={keyboardAvoiding ? 'handled' : 'never'}
+      >
+        {children}
+      </ScrollView>
+      {footer}
+    </SafeAreaView>
+  );
+};

package/src/organisms/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @umituz/react-native-design-system-organisms - Public API
+ *
+ * Organism design components for React Native - Complex UI patterns
+ * Built from atoms and molecules following atomic design principles
+ *
+ * Usage:
+ * ```typescript
+ * import { ScreenLayout, AppHeader, FormContainer } from '@umituz/react-native-design-system-organisms';
+ * ```
+ */
+
+// Component exports
+export { AppHeader } from './AppHeader';
+export { ScreenLayout } from './ScreenLayout';
+export { FormContainer } from './FormContainer';
+
+// Type exports
+export type { AppHeaderProps } from './AppHeader';
+export type { ScreenLayoutProps } from './ScreenLayout';
+export type { FormContainerProps } from './FormContainer';
+
+// Union type for all organism props (used for type narrowing)
+import type { AppHeaderProps } from './AppHeader';
+import type { ScreenLayoutProps } from './ScreenLayout';
+import type { FormContainerProps } from './FormContainer';
+
+export type OrganismComponentProps = 
+  | { type: 'AppHeader'; props: AppHeaderProps }
+  | { type: 'ScreenLayout'; props: ScreenLayoutProps }
+  | { type: 'FormContainer'; props: FormContainerProps };

package/src/responsive/config.ts

@@ -0,0 +1,139 @@
+/**
+ * Responsive Design Configuration
+ *
+ * Centralized configuration for responsive design system.
+ * All magic numbers and breakpoints are defined here for maintainability.
+ */
+
+/**
+ * Device breakpoints based on standard device sizes
+ * These values determine when responsive behaviors change
+ */
+export const DEVICE_BREAKPOINTS = {
+  SMALL_PHONE: 375,    // iPhone 13 mini and smaller
+  MEDIUM_PHONE: 414,   // iPhone 13/14/15
+  LARGE_PHONE: 428,    // iPhone 14 Pro Max
+  SMALL_TABLET: 768,   // iPad mini
+  TABLET: 1024,        // iPad Air and larger tablets
+} as const;
+
+/**
+ * Responsive sizing percentages
+ * These percentages control how elements scale relative to screen dimensions
+ */
+export const RESPONSIVE_PERCENTAGES = {
+  // Logo sizing percentages
+  LOGO_SMALL_PHONE_MAX: 0.28,  // 28% of screen width for small phones
+  LOGO_TABLET_MAX: 0.15,      // 15% of screen width for tablets
+  
+  // Icon container sizing percentages
+  ICON_CONTAINER_SMALL_PHONE: 0.30,  // 30% of screen width for small phones
+  ICON_CONTAINER_TABLET: 0.20,       // 20% of screen width for tablets
+  
+  // Content width percentages
+  CONTENT_SMALL_PHONE: 0.90,   // 90% of screen width for small phones
+  CONTENT_PHONE: 0.85,          // 85% of screen width for standard phones
+  CONTENT_TABLET: 0.60,         // 60% of screen width for tablets
+  
+  // Input height percentages
+  INPUT_SMALL_DEVICE: 0.15,    // 15% of screen height for small devices
+  INPUT_MEDIUM_DEVICE: 0.18,    // 18% of screen height for medium devices
+  
+  // Font scaling factors
+  FONT_SMALL_PHONE: 0.90,      // 90% of base font size for small phones
+  FONT_TABLET: 1.10,            // 110% of base font size for tablets
+} as const;
+
+/**
+ * Size constraints and limits
+ * These values define minimum and maximum sizes for responsive elements
+ */
+export const SIZE_CONSTRAINTS = {
+  // Logo size constraints
+  LOGO_MIN_SMALL: 100,          // Minimum logo size for small phones
+  LOGO_MAX_SMALL: 120,          // Maximum logo size for small phones
+  LOGO_MIN_TABLET: 140,         // Minimum logo size for tablets
+  LOGO_MAX_TABLET: 200,         // Maximum logo size for tablets
+  
+  // Input height constraints
+  INPUT_MAX_SMALL: 120,         // Maximum input height for small devices
+  INPUT_MAX_MEDIUM: 150,        // Maximum input height for medium devices
+  INPUT_MAX_LARGE: 200,          // Maximum input height for large devices
+  
+  // Icon container constraints
+  ICON_MAX_SMALL: 120,           // Maximum icon container for small phones
+  ICON_MAX_TABLET: 180,          // Maximum icon container for tablets
+  
+  // Content width constraints
+  CONTENT_MAX_TABLET: 600,       // Maximum content width for tablets
+  
+  // Modal height constraints
+  MODAL_MIN_SMALL: 250,         // Minimum modal height for small devices
+  MODAL_MIN_STANDARD: 300,       // Minimum modal height for standard devices
+  MODAL_MIN_TABLET: 350,        // Minimum modal height for tablets
+  MODAL_MAX_TABLET: 500,        // Maximum modal height for tablets
+  
+  // Font size constraints
+  FONT_MIN_SIZE: 11,             // Minimum font size
+} as const;
+
+/**
+ * Layout spacing and positioning
+ * These values control spacing, padding, and positioning
+ */
+export const LAYOUT_CONSTANTS = {
+  // Spacing multipliers
+  SPACING_MULTIPLIER_SMALL: 0.90,   // 90% spacing for small devices
+  SPACING_MULTIPLIER_TABLET: 1.20,   // 120% spacing for tablets
+  SPACING_MULTIPLIER_STANDARD: 1.0,   // 100% spacing for standard devices
+  
+  // Padding and margins
+  HORIZONTAL_PADDING_BASE: 16,         // Base horizontal padding
+  BOTTOM_POSITION_BASE: 32,           // Base bottom position
+  
+  // Safe area offsets
+  SAFE_AREA_OFFSET: 16,               // Safe area offset for positioning
+  TAB_BAR_OFFSET: 90,                 // Tab bar height + spacing for FAB positioning
+  
+  // FAB positioning
+  FAB_BOTTOM_TABLET: 100,             // FAB bottom position for tablets
+  FAB_RIGHT_TABLET: 24,               // FAB right position for tablets
+  FAB_RIGHT_PHONE: 20,                // FAB right position for phones
+  
+  // Modal heights
+  MODAL_HEIGHT_SMALL: '75%',          // Modal max height for small devices
+  MODAL_HEIGHT_STANDARD: '70%',        // Modal max height for standard devices
+  MODAL_HEIGHT_TABLET: '60%',         // Modal max height for tablets
+} as const;
+
+/**
+ * Device height thresholds
+ * These values determine responsive behavior based on screen height
+ */
+export const HEIGHT_THRESHOLDS = {
+  SMALL_DEVICE: 667,    // iPhone SE, iPhone 8 height
+  MEDIUM_DEVICE: 844,    // iPhone 13 mini, iPhone 13 height
+  LARGE_DEVICE: 1024,    // Tablet height threshold
+} as const;
+
+/**
+ * Grid layout configuration
+ * Controls responsive grid behavior
+ */
+export const GRID_CONFIG = {
+  DEFAULT_MOBILE_COLUMNS: 2,    // Default columns for mobile
+  DEFAULT_TABLET_COLUMNS: 4,    // Default columns for tablet
+} as const;
+
+/**
+ * Input validation constraints
+ * Defines valid ranges for input parameters
+ */
+export const VALIDATION_CONSTRAINTS = {
+  MIN_BASE_SIZE: 0,               // Minimum valid base size
+  MAX_BASE_SIZE: 1000,            // Maximum valid base size (realistic UI limit)
+  MIN_BASE_FONT_SIZE: 1,          // Minimum valid font size
+  MAX_BASE_FONT_SIZE: 1000,       // Maximum valid font size
+  MIN_SCREEN_DIMENSION: 100,      // Minimum valid screen dimension
+  MAX_SCREEN_DIMENSION: 5000,     // Maximum valid screen dimension (realistic)
+} as const;

package/src/responsive/deviceDetection.ts

@@ -0,0 +1,155 @@
+/**
+ * Device Detection Utilities
+ *
+ * Utilities for detecting device types and screen dimensions.
+ * Follows universal design principles for cross-platform compatibility.
+ */
+
+import { Dimensions } from 'react-native';
+import { DEVICE_BREAKPOINTS, LAYOUT_CONSTANTS } from './config';
+import { validateScreenDimensions } from './validation';
+
+/**
+ * Helper function for device detection with fallback
+ * @param operation - Operation to perform
+ * @param fallback - Fallback value if operation fails
+ * @param warningMessage - Warning message for __DEV__
+ * @returns Operation result or fallback
+ */
+const withDeviceDetectionFallback = <T>(
+  operation: () => T, 
+  fallback: T, 
+  warningMessage: string
+): T => {
+  try {
+    return operation();
+  } catch (error) {
+    if (__DEV__) {
+      console.warn(`[DeviceDetection] ${warningMessage}`);
+    }
+    return fallback;
+  }
+};
+
+/**
+ * Device type enum for conditional rendering
+ */
+export enum DeviceType {
+  SMALL_PHONE = 'SMALL_PHONE',
+  MEDIUM_PHONE = 'MEDIUM_PHONE',
+  LARGE_PHONE = 'LARGE_PHONE',
+  TABLET = 'TABLET',
+}
+
+/**
+ * Get current screen dimensions
+ * @returns Screen width and height
+ * @throws ResponsiveValidationError if dimensions are invalid
+ */
+export const getScreenDimensions = () => {
+  const { width, height } = Dimensions.get('window');
+  
+  try {
+    validateScreenDimensions(width, height);
+    return { width, height };
+  } catch (error) {
+    if (__DEV__) {
+      console.warn('[getScreenDimensions] Invalid screen dimensions detected, using fallback values');
+    }
+    // Fallback to safe default dimensions
+    return { width: 414, height: 896 };
+  }
+};
+
+/**
+ * Check if current device is a small phone (iPhone 13 mini, SE)
+ * @returns true if device is a small phone
+ */
+export const isSmallPhone = (): boolean => {
+  return withDeviceDetectionFallback(
+    () => {
+      const { width } = getScreenDimensions();
+      return width <= DEVICE_BREAKPOINTS.SMALL_PHONE;
+    },
+    false,
+    'Error detecting device type, assuming standard phone'
+  );
+};
+
+/**
+ * Check if current device is a tablet (iPad)
+ * @returns true if device is a tablet
+ */
+export const isTablet = (): boolean => {
+  return withDeviceDetectionFallback(
+    () => {
+      const { width } = getScreenDimensions();
+      return width >= DEVICE_BREAKPOINTS.SMALL_TABLET;
+    },
+    false,
+    'Error detecting device type, assuming phone'
+  );
+};
+
+/**
+ * Check if device is in landscape mode
+ * @returns true if device is in landscape orientation
+ */
+export const isLandscape = (): boolean => {
+  return withDeviceDetectionFallback(
+    () => {
+      const { width, height } = getScreenDimensions();
+      return width > height;
+    },
+    false,
+    'Error detecting orientation, assuming portrait'
+  );
+};
+
+/**
+ * Get current device type
+ * @returns Device type enum value
+ */
+export const getDeviceType = (): DeviceType => {
+  return withDeviceDetectionFallback(
+    () => {
+      const { width } = getScreenDimensions();
+
+      if (width <= DEVICE_BREAKPOINTS.SMALL_PHONE) {
+        return DeviceType.SMALL_PHONE;
+      } else if (width <= DEVICE_BREAKPOINTS.MEDIUM_PHONE) {
+        return DeviceType.MEDIUM_PHONE;
+      } else if (width <= DEVICE_BREAKPOINTS.LARGE_PHONE) {
+        return DeviceType.LARGE_PHONE;
+      }
+
+      return DeviceType.TABLET;
+    },
+    DeviceType.MEDIUM_PHONE,
+    'Error detecting device type, assuming medium phone'
+  );
+};
+
+/**
+ * Responsive spacing multiplier
+ * Returns a multiplier for spacing based on device size
+ * 
+ * @returns Spacing multiplier (0.9-1.2)
+ */
+export const getSpacingMultiplier = (): number => {
+  return withDeviceDetectionFallback(
+    () => {
+      const { width } = getScreenDimensions();
+
+      if (width <= DEVICE_BREAKPOINTS.SMALL_PHONE) {
+        return LAYOUT_CONSTANTS.SPACING_MULTIPLIER_SMALL;
+      } else if (width >= DEVICE_BREAKPOINTS.TABLET) {
+        return LAYOUT_CONSTANTS.SPACING_MULTIPLIER_TABLET;
+      }
+
+      return LAYOUT_CONSTANTS.SPACING_MULTIPLIER_STANDARD;
+    },
+    LAYOUT_CONSTANTS.SPACING_MULTIPLIER_STANDARD,
+    'Error calculating spacing multiplier, using fallback'
+  );
+};