@umituz/react-native-design-system 1.14.0 → 2.0.0

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'
+  );
+};

package/src/responsive/gridUtils.ts

@@ -0,0 +1,79 @@
+/**
+ * Grid Utilities
+ * Responsive grid sizing and column calculations
+ */
+
+import { getScreenDimensions } from './deviceDetection';
+import { DEVICE_BREAKPOINTS, GRID_CONFIG } from './config';
+import { validateNumber } from './validation';
+
+/**
+ * Responsive grid columns
+ * Returns number of columns for grid layouts
+ *
+ * @param mobileColumns - Number of columns for mobile devices (default: 2)
+ * @param tabletColumns - Number of columns for tablet devices (default: 4)
+ * @returns Responsive number of grid columns
+ */
+export const getResponsiveGridColumns = (
+  mobileColumns: number = GRID_CONFIG.DEFAULT_MOBILE_COLUMNS,
+  tabletColumns: number = GRID_CONFIG.DEFAULT_TABLET_COLUMNS
+): number => {
+  try {
+    const validatedMobile = validateNumber(mobileColumns, 'mobileColumns', 1, 20);
+    const validatedTablet = validateNumber(tabletColumns, 'tabletColumns', 1, 20);
+
+    const { width } = getScreenDimensions();
+    return width >= DEVICE_BREAKPOINTS.TABLET ? validatedTablet : validatedMobile;
+  } catch {
+    return 2;
+  }
+};
+
+export interface GridCellSizeConfig {
+  columns: number;
+  rows: number;
+  horizontalPadding?: number;
+  verticalPadding?: number;
+  gap?: number;
+  headerHeight?: number;
+  tabBarHeight?: number;
+  statusBarHeight?: number;
+}
+
+/**
+ * Responsive grid cell size
+ * Calculates optimal square cell size for a grid that fills available space
+ *
+ * @param config - Grid configuration
+ * @returns Responsive cell size (width = height for square cells)
+ */
+export const getResponsiveGridCellSize = (config: GridCellSizeConfig): number => {
+  try {
+    const {
+      columns,
+      rows,
+      horizontalPadding = 32,
+      verticalPadding = 32,
+      gap = 8,
+      headerHeight = 120,
+      tabBarHeight = 80,
+      statusBarHeight = 50,
+    } = config;
+
+    const { width, height } = getScreenDimensions();
+
+    const totalHorizontalGap = gap * (columns - 1);
+    const availableWidth = width - horizontalPadding - totalHorizontalGap;
+    const maxCellWidth = availableWidth / columns;
+
+    const totalVerticalGap = gap * (rows - 1);
+    const usedHeight = headerHeight + tabBarHeight + statusBarHeight + verticalPadding;
+    const availableHeight = height - usedHeight - totalVerticalGap;
+    const maxCellHeight = availableHeight / rows;
+
+    return Math.floor(Math.min(maxCellWidth, maxCellHeight));
+  } catch {
+    return 60;
+  }
+};

package/src/responsive/index.ts

@@ -0,0 +1,52 @@
+/**
+ * @umituz/react-native-design-system-responsive - Public API
+ *
+ * Responsive design utilities for React Native - Screen dimensions, device detection,
+ * and responsive sizing utilities following Material Design 3 and iOS HIG principles.
+ *
+ * Usage:
+ * ```typescript
+ * import { useResponsive, isTablet, getResponsiveLogoSize } from '@umituz/react-native-design-system-responsive';
+ * ```
+ */
+
+// Hook exports
+export { useResponsive } from './useResponsive';
+export type { UseResponsiveReturn } from './useResponsive';
+
+// Utility function exports
+export {
+  getScreenDimensions,
+  isSmallPhone,
+  isTablet,
+  getResponsiveLogoSize,
+  getResponsiveInputHeight,
+  getResponsiveHorizontalPadding,
+  getResponsiveBottomPosition,
+  getResponsiveFABPosition,
+  getResponsiveModalMaxHeight,
+  getResponsiveMinModalHeight,
+  getResponsiveIconContainerSize,
+  getResponsiveGridColumns,
+  getResponsiveGridCellSize,
+  type GridCellSizeConfig,
+  getResponsiveMaxWidth,
+  getResponsiveFontSize,
+  isLandscape,
+  getDeviceType,
+  DeviceType,
+} from './responsive';
+
+// Device detection exports
+export { getSpacingMultiplier } from './deviceDetection';
+
+
+
+// Platform constants exports
+export {
+  IOS_HIG,
+  PLATFORM_CONSTANTS,
+  isValidTouchTarget,
+  getMinTouchTarget,
+} from './platformConstants';
+

package/src/responsive/platformConstants.ts

@@ -0,0 +1,98 @@
+/**
+ * Platform-Specific Constants
+ *
+ * Design system constants that ensure compliance with platform guidelines.
+ * These values are based on official Human Interface Guidelines (HIG) from Apple and Material Design from Google.
+ */
+
+/**
+ * iOS Human Interface Guidelines (HIG) Constants
+ *
+ * @see https://developer.apple.com/design/human-interface-guidelines/layout
+ */
+export const IOS_HIG = {
+  /**
+   * Minimum Touch Target Size
+   *
+   * Apple requires a minimum tappable area of 44pt x 44pt for ALL interactive controls.
+   * This is enforced during App Store review.
+   *
+   * @critical Violating this can result in App Store rejection
+   */
+  MIN_TOUCH_TARGET: 44,
+
+  /**
+   * Recommended Minimum Touch Target Size
+   *
+   * For better accessibility and usability, Apple recommends 48pt x 48pt.
+   */
+  RECOMMENDED_TOUCH_TARGET: 48,
+
+  /**
+   * Minimum Text Size
+   *
+   * Minimum font size for body text to ensure readability.
+   */
+  MIN_TEXT_SIZE: 17,
+
+
+} as const;
+
+
+
+/**
+ * Universal Platform Constants
+ *
+ * These values work across both iOS and Android, taking the more restrictive requirement.
+ */
+export const PLATFORM_CONSTANTS = {
+  /**
+   * Minimum Touch Target Size
+   *
+   * Uses iOS requirement (44pt) as it's more restrictive than Android (48dp).
+   * This ensures compliance on both platforms.
+   */
+  MIN_TOUCH_TARGET: Math.max(IOS_HIG.MIN_TOUCH_TARGET, 48),
+
+  /**
+   * Recommended Touch Target Size
+   *
+   * Uses the higher value between iOS and Android recommendations.
+   */
+  RECOMMENDED_TOUCH_TARGET: 48,
+
+  /**
+   * Minimum Text Size
+   *
+   * Uses iOS requirement as it's larger.
+   */
+  MIN_TEXT_SIZE: Math.max(IOS_HIG.MIN_TEXT_SIZE, 14),
+} as const;
+
+/**
+ * Helper function to validate touch target size
+ *
+ * @param size - The size to validate (in pt/dp)
+ * @returns true if size meets platform requirements
+ */
+export const isValidTouchTarget = (size: number): boolean => {
+  return size >= IOS_HIG.MIN_TOUCH_TARGET;
+};
+
+/**
+ * Helper function to get minimum touch target for component
+ *
+ * @param componentType - The type of component ('button' | 'input' | 'icon' | 'generic')
+ * @returns The minimum touch target size for that component type
+ */
+export const getMinTouchTarget = (componentType: 'button' | 'input' | 'icon' | 'generic' = 'generic'): number => {
+  switch (componentType) {
+    case 'button':
+    case 'input':
+      return PLATFORM_CONSTANTS.RECOMMENDED_TOUCH_TARGET; // 48pt recommended for buttons and inputs
+    case 'icon':
+    case 'generic':
+    default:
+      return IOS_HIG.MIN_TOUCH_TARGET; // 44pt minimum for icons and generic elements
+  }
+};

package/src/responsive/responsive.ts

@@ -0,0 +1,61 @@
+/**
+ * Responsive Design Utilities
+ *
+ * Centralized responsive sizing and spacing utilities to prevent
+ * Apple App Store rejection due to layout issues on different devices.
+ *
+ * This is the main export file that imports from specialized modules.
+ */
+
+// Device detection
+export {
+  getScreenDimensions,
+  isSmallPhone,
+  isTablet,
+  isLandscape,
+  getDeviceType,
+  DeviceType,
+} from './deviceDetection';
+
+// Responsive sizing
+export {
+  getResponsiveLogoSize,
+  getResponsiveInputHeight,
+  getResponsiveIconContainerSize,
+  getResponsiveMaxWidth,
+  getResponsiveFontSize,
+  getResponsiveGridColumns,
+  getResponsiveGridCellSize,
+  type GridCellSizeConfig,
+} from './responsiveSizing';
+
+// Responsive layout
+export {
+  getResponsiveHorizontalPadding,
+  getResponsiveBottomPosition,
+  getResponsiveFABPosition,
+  getResponsiveModalMaxHeight,
+  getResponsiveMinModalHeight,
+} from './responsiveLayout';
+
+// Platform constants
+export {
+  IOS_HIG,
+  PLATFORM_CONSTANTS,
+  isValidTouchTarget,
+  getMinTouchTarget,
+} from './platformConstants';
+
+// Configuration
+export {
+  DEVICE_BREAKPOINTS,
+  RESPONSIVE_PERCENTAGES,
+  SIZE_CONSTRAINTS,
+  LAYOUT_CONSTANTS,
+  HEIGHT_THRESHOLDS,
+  GRID_CONFIG,
+  VALIDATION_CONSTRAINTS,
+} from './config';
+
+
+

package/src/responsive/responsiveLayout.ts

@@ -0,0 +1,137 @@
+/**
+ * Responsive Layout Utilities
+ * Layout utilities for positioning and spacing.
+ */
+
+import { getScreenDimensions } from './deviceDetection';
+import {
+  DEVICE_BREAKPOINTS,
+  LAYOUT_CONSTANTS,
+  HEIGHT_THRESHOLDS,
+  SIZE_CONSTRAINTS,
+} from './config';
+import { validateNumber, validateSafeAreaInsets } from './validation';
+
+/**
+ * Responsive horizontal padding
+ * @param basePadding - Base padding value (default: 16)
+ * @param insets - Safe area insets object
+ */
+export const getResponsiveHorizontalPadding = (
+  basePadding: number = LAYOUT_CONSTANTS.HORIZONTAL_PADDING_BASE,
+  insets: { left?: number; right?: number } = { left: 0, right: 0 }
+): number => {
+  try {
+    const validatedBasePadding = validateNumber(basePadding, 'basePadding', 0, 100);
+    validateSafeAreaInsets(insets);
+
+    const { width } = getScreenDimensions();
+    const { left = 0, right = 0 } = insets;
+
+    if (width >= DEVICE_BREAKPOINTS.TABLET) {
+      const tabletPadding = validatedBasePadding * 1.5;
+      return Math.max(
+        tabletPadding,
+        left + LAYOUT_CONSTANTS.HORIZONTAL_PADDING_BASE,
+        right + LAYOUT_CONSTANTS.HORIZONTAL_PADDING_BASE
+      );
+    }
+
+    return Math.max(
+      validatedBasePadding,
+      left + LAYOUT_CONSTANTS.SAFE_AREA_OFFSET,
+      right + LAYOUT_CONSTANTS.SAFE_AREA_OFFSET
+    );
+  } catch {
+    return 16;
+  }
+};
+
+/**
+ * Responsive bottom positioning
+ * @param basePosition - Base bottom position (default: 32)
+ * @param insets - Safe area insets object
+ */
+export const getResponsiveBottomPosition = (
+  basePosition: number = LAYOUT_CONSTANTS.BOTTOM_POSITION_BASE,
+  insets: { bottom?: number } = { bottom: 0 }
+): number => {
+  try {
+    const validatedBasePosition = validateNumber(basePosition, 'basePosition', 0, 500);
+    validateSafeAreaInsets(insets);
+
+    const { bottom = 0 } = insets;
+    return Math.max(validatedBasePosition, bottom + LAYOUT_CONSTANTS.SAFE_AREA_OFFSET);
+  } catch {
+    return 32;
+  }
+};
+
+/**
+ * Responsive FAB position
+ * @param insets - Safe area insets object
+ */
+export const getResponsiveFABPosition = (
+  insets: { bottom?: number; right?: number } = { bottom: 0, right: 0 }
+): { bottom: number; right: number } => {
+  try {
+    validateSafeAreaInsets(insets);
+    const { width } = getScreenDimensions();
+    const { bottom = 0, right = 0 } = insets;
+
+    if (width >= DEVICE_BREAKPOINTS.TABLET) {
+      return {
+        bottom: Math.max(LAYOUT_CONSTANTS.FAB_BOTTOM_TABLET, bottom + LAYOUT_CONSTANTS.TAB_BAR_OFFSET),
+        right: Math.max(LAYOUT_CONSTANTS.FAB_RIGHT_TABLET, right + LAYOUT_CONSTANTS.HORIZONTAL_PADDING_BASE),
+      };
+    }
+
+    return {
+      bottom: Math.max(LAYOUT_CONSTANTS.TAB_BAR_OFFSET, bottom + LAYOUT_CONSTANTS.SAFE_AREA_OFFSET),
+      right: Math.max(LAYOUT_CONSTANTS.FAB_RIGHT_PHONE, right + LAYOUT_CONSTANTS.SAFE_AREA_OFFSET),
+    };
+  } catch {
+    return { bottom: 90, right: 20 };
+  }
+};
+
+/**
+ * Responsive modal max height
+ */
+export const getResponsiveModalMaxHeight = (): string => {
+  try {
+    const { height } = getScreenDimensions();
+
+    if (height <= HEIGHT_THRESHOLDS.SMALL_DEVICE) {
+      return LAYOUT_CONSTANTS.MODAL_HEIGHT_SMALL;
+    } else if (height >= HEIGHT_THRESHOLDS.LARGE_DEVICE) {
+      return LAYOUT_CONSTANTS.MODAL_HEIGHT_TABLET;
+    }
+
+    return LAYOUT_CONSTANTS.MODAL_HEIGHT_STANDARD;
+  } catch {
+    return '70%';
+  }
+};
+
+/**
+ * Responsive modal min height
+ */
+export const getResponsiveMinModalHeight = (): number => {
+  try {
+    const { height } = getScreenDimensions();
+
+    if (height <= HEIGHT_THRESHOLDS.SMALL_DEVICE) {
+      const calculatedHeight = height * 0.4;
+      return Math.max(calculatedHeight, SIZE_CONSTRAINTS.MODAL_MIN_SMALL);
+    } else if (height >= HEIGHT_THRESHOLDS.LARGE_DEVICE) {
+      const calculatedHeight = height * 0.35;
+      return Math.min(Math.max(calculatedHeight, SIZE_CONSTRAINTS.MODAL_MIN_TABLET), SIZE_CONSTRAINTS.MODAL_MAX_TABLET);
+    }
+
+    const calculatedHeight = height * 0.45;
+    return Math.max(calculatedHeight, SIZE_CONSTRAINTS.MODAL_MIN_STANDARD);
+  } catch {
+    return 300;
+  }
+};