blacktrigram 0.7.2

package/lib/utils/koreanThemeHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"koreanThemeHelpers.js","names":[],"sources":["../../src/utils/koreanThemeHelpers.ts"],"sourcesContent":["/**\n * Korean Theme Helper Utilities for HTML Overlays\n *\n * Provides consistent Korean martial arts cyberpunk theming across all HTML overlay components.\n * These utilities ensure color consistency, bilingual text formatting, and responsive spacing.\n *\n * @module utils/koreanThemeHelpers\n * @category UI Utilities\n * @korean 한국테마도우미\n */\n\nimport { KOREAN_COLORS, FONT_FAMILY } from \"@/types/constants\";\nimport { SPACING, BORDER_RADIUS } from \"../types/constants/ui\";\nimport { hexToRgbaString } from \"./colorUtils\";\nimport {\n  getNeonGlowEffect,\n  getNeonTextShadow,\n  getLayeredDepthEffect,\n  getCyberpunkGradient,\n  getSmoothTransition,\n  getKoreanFontOptimization,\n  getHoverStateStyles,\n  getFocusStateStyles,\n  getBackdropBlurEffect,\n  getTrigramSymbolGlow as getTrigramGlowEffect,\n  combineShadowEffects,\n  type GlowIntensity,\n  type HoverAnimationType,\n} from \"./visualEffects\";\n\n/**\n * Bilingual text format options\n * @korean 이중언어형식\n */\nexport type BilingualFormat = \"pipe\" | \"parentheses\" | \"bracket\" | \"slash\";\n\n/**\n * Button variant types for Korean theme\n * @korean 버튼변형\n */\nexport type KoreanButtonVariant =\n  | \"primary\"\n  | \"secondary\"\n  | \"danger\"\n  | \"success\"\n  | \"warning\";\n\n/**\n * Responsive spacing size\n * @korean 반응형간격크기\n */\nexport type SpacingSize = \"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\" | \"xxl\";\n\n/**\n * Enhanced overlay styles configuration\n * @korean 향상된오버레이스타일설정\n */\nexport interface EnhancedOverlayConfig {\n  readonly opacity?: number;\n  readonly glowIntensity?: GlowIntensity;\n  readonly includeGradient?: boolean;\n  readonly includeBackdropBlur?: boolean;\n  readonly depthLayers?: number;\n}\n\n/**\n * Base styles for all Korean-themed overlays\n *\n * Provides consistent dark background with cyan/gold accents\n *\n * @param opacity - Background opacity (0-1), default 0.9\n * @returns React.CSSProperties object with Korean theme\n *\n * @example\n * ```tsx\n * <div style={getKoreanOverlayBaseStyles(0.95)}>\n *   Content\n * </div>\n * ```\n *\n * @korean 한국오버레이기본스타일얻기\n */\nexport function getKoreanOverlayBaseStyles(\n  opacity: number = 0.9,\n): React.CSSProperties {\n  return {\n    backgroundColor: hexToRgbaString(KOREAN_COLORS.UI_BACKGROUND_DARK, opacity),\n    border: `2px solid ${hexToRgbaString(KOREAN_COLORS.PRIMARY_CYAN, 0.8)}`,\n    borderRadius: `${BORDER_RADIUS.MD}px`,\n    fontFamily: FONT_FAMILY.KOREAN,\n    color: hexToRgbaString(KOREAN_COLORS.TEXT_PRIMARY),\n    boxShadow: `0 4px 20px ${hexToRgbaString(KOREAN_COLORS.BLACK_SOLID, 0.5)}`,\n  };\n}\n\n/**\n * Enhanced Korean overlay styles with visual effects\n *\n * Provides advanced cyberpunk styling with neon glow, depth effects,\n * gradients, and backdrop blur for Korean-themed overlays.\n *\n * @param config - Enhanced overlay configuration\n * @returns React.CSSProperties with advanced visual effects\n *\n * @example\n * ```tsx\n * const styles = getEnhancedKoreanOverlayStyles({\n *   opacity: 0.95,\n *   glowIntensity: 'medium',\n *   includeGradient: true,\n *   includeBackdropBlur: true,\n *   depthLayers: 3,\n * });\n * <div style={styles}>Enhanced Content</div>\n * ```\n *\n * @korean 향상된한국오버레이스타일얻기\n */\nexport function getEnhancedKoreanOverlayStyles(\n  config: EnhancedOverlayConfig = {},\n): React.CSSProperties {\n  const {\n    opacity = 0.9,\n    glowIntensity = \"medium\",\n    includeGradient = false,\n    includeBackdropBlur = false,\n    depthLayers = 2,\n  } = config;\n\n  // Base styles\n  const baseStyles = getKoreanOverlayBaseStyles(opacity);\n\n  // Neon glow effect\n  const neonGlow = getNeonGlowEffect(\n    KOREAN_COLORS.PRIMARY_CYAN,\n    glowIntensity,\n    true,\n  );\n\n  // Depth effect\n  const depthShadow = getLayeredDepthEffect({\n    layers: depthLayers,\n    baseOffset: 2,\n    baseBlur: 4,\n    color: KOREAN_COLORS.BLACK_SOLID,\n    opacity: 0.5,\n  });\n\n  // Combine shadows\n  const boxShadow = combineShadowEffects([neonGlow, depthShadow]);\n\n  // Optional gradient background\n  let background = baseStyles.backgroundColor;\n  if (includeGradient) {\n    const gradient = getCyberpunkGradient(\n      KOREAN_COLORS.PRIMARY_CYAN,\n      KOREAN_COLORS.UI_BACKGROUND_DARK,\n      135,\n    );\n    background = `${gradient}, ${background}`;\n  }\n\n  // Optional backdrop blur\n  const backdropStyles = includeBackdropBlur\n    ? getBackdropBlurEffect(10, 1.5)\n    : {};\n\n  // Combine all styles\n  return {\n    ...baseStyles,\n    ...backdropStyles,\n    background,\n    boxShadow,\n    transition: getSmoothTransition(\"all\", \"normal\"),\n    ...getKoreanFontOptimization(16, \"normal\"),\n  };\n}\n\n/**\n * Format bilingual text with Korean and English\n *\n * Supports multiple formatting styles:\n * - pipe: \"한글 | English\"\n * - parentheses: \"한글 (English)\"\n * - bracket: \"한글 [English]\"\n * - slash: \"한글 / English\"\n *\n * @param korean - Korean text\n * @param english - English text\n * @param format - Format style, default \"pipe\"\n * @returns Formatted bilingual string\n *\n * @example\n * ```tsx\n * formatBilingualText('공격', 'Attack', 'pipe') // \"공격 | Attack\"\n * formatBilingualText('방어', 'Defense', 'parentheses') // \"방어 (Defense)\"\n * ```\n *\n * @korean 이중언어텍스트형식화\n */\nexport function formatBilingualText(\n  korean: string,\n  english: string,\n  format: BilingualFormat = \"pipe\",\n): string {\n  switch (format) {\n    case \"pipe\":\n      return `${korean} | ${english}`;\n    case \"parentheses\":\n      return `${korean} (${english})`;\n    case \"bracket\":\n      return `${korean} [${english}]`;\n    case \"slash\":\n      return `${korean} / ${english}`;\n    default:\n      return `${korean} | ${english}`;\n  }\n}\n\n/**\n * Get Korean button styles with variant support\n *\n * Returns consistent button styling based on variant:\n * - primary: Cyan border, gold text\n * - secondary: Gold border, white text\n * - danger: Red border, red text\n * - success: Green border, green text\n * - warning: Orange border, orange text\n *\n * @param variant - Button variant type\n * @param isHovered - Whether button is hovered\n * @param isPressed - Whether button is pressed\n * @returns React.CSSProperties for button\n *\n * @example\n * ```tsx\n * <button style={getKoreanButtonStyles('primary', isHovered, isPressed)}>\n *   {formatBilingualText('확인', 'Confirm')}\n * </button>\n * ```\n *\n * @korean 한국버튼스타일얻기\n */\nexport function getKoreanButtonStyles(\n  variant: KoreanButtonVariant = \"primary\",\n  isHovered: boolean = false,\n  isPressed: boolean = false,\n): React.CSSProperties {\n  // Variant-specific colors\n  const variantColors = {\n    primary: {\n      border: KOREAN_COLORS.PRIMARY_CYAN,\n      text: KOREAN_COLORS.ACCENT_GOLD,\n      hoverBg: KOREAN_COLORS.PRIMARY_CYAN,\n    },\n    secondary: {\n      border: KOREAN_COLORS.ACCENT_GOLD,\n      text: KOREAN_COLORS.TEXT_PRIMARY,\n      hoverBg: KOREAN_COLORS.ACCENT_GOLD,\n    },\n    danger: {\n      border: KOREAN_COLORS.ACCENT_RED,\n      text: KOREAN_COLORS.ACCENT_RED,\n      hoverBg: KOREAN_COLORS.ACCENT_RED,\n    },\n    success: {\n      border: KOREAN_COLORS.ACCENT_GREEN,\n      text: KOREAN_COLORS.ACCENT_GREEN,\n      hoverBg: KOREAN_COLORS.ACCENT_GREEN,\n    },\n    warning: {\n      border: KOREAN_COLORS.WARNING_ORANGE,\n      text: KOREAN_COLORS.WARNING_ORANGE,\n      hoverBg: KOREAN_COLORS.WARNING_ORANGE,\n    },\n  };\n\n  const colors = variantColors[variant];\n\n  let backgroundColor = hexToRgbaString(\n    KOREAN_COLORS.UI_BACKGROUND_MEDIUM,\n    0.9,\n  );\n  let borderColor = hexToRgbaString(colors.border, 0.8);\n  const textColor = hexToRgbaString(colors.text);\n  let boxShadow = \"none\";\n  let transform = \"scale(1)\";\n\n  if (isPressed) {\n    backgroundColor = hexToRgbaString(colors.hoverBg, 0.2);\n    transform = \"scale(0.98)\";\n  } else if (isHovered) {\n    backgroundColor = hexToRgbaString(colors.hoverBg, 0.1);\n    borderColor = hexToRgbaString(colors.border, 1.0);\n    boxShadow = `0 0 10px ${hexToRgbaString(colors.border, 0.5)}`;\n  }\n\n  return {\n    backgroundColor,\n    border: `2px solid ${borderColor}`,\n    borderRadius: `${BORDER_RADIUS.SM}px`,\n    color: textColor,\n    fontFamily: FONT_FAMILY.KOREAN,\n    fontWeight: \"bold\",\n    padding: `${SPACING.SM}px ${SPACING.MD}px`,\n    cursor: \"pointer\",\n    transition: \"all 0.2s ease\",\n    userSelect: \"none\",\n    WebkitUserSelect: \"none\",\n    boxShadow,\n    transform,\n    textShadow: `0 2px 4px ${hexToRgbaString(KOREAN_COLORS.BLACK_SOLID, 0.5)}`,\n  };\n}\n\n/**\n * Enhanced Korean button configuration\n * @korean 향상된한국버튼설정\n */\nexport interface EnhancedButtonConfig {\n  readonly variant?: KoreanButtonVariant;\n  readonly isHovered?: boolean;\n  readonly isPressed?: boolean;\n  readonly isFocused?: boolean;\n  readonly glowIntensity?: GlowIntensity;\n  readonly hoverAnimation?: HoverAnimationType;\n}\n\n/**\n * Get enhanced Korean button styles with neon glow\n *\n * Provides advanced button styling with cyberpunk neon effects,\n * smooth transitions, and Korean font optimization.\n *\n * @param config - Enhanced button configuration\n * @returns React.CSSProperties with neon glow effects\n *\n * @example\n * ```tsx\n * const buttonStyle = getKoreanButtonWithGlow({\n *   variant: 'primary',\n *   isHovered: true,\n *   glowIntensity: 'strong',\n *   hoverAnimation: 'combined',\n * });\n * <button style={buttonStyle}>\n *   {formatBilingualText('공격', 'Attack')}\n * </button>\n * ```\n *\n * @korean 네온글로우한국버튼스타일얻기\n */\nexport function getKoreanButtonWithGlow(\n  config: EnhancedButtonConfig = {},\n): React.CSSProperties {\n  const {\n    variant = \"primary\",\n    isHovered = false,\n    isPressed = false,\n    isFocused = false,\n    glowIntensity = \"medium\",\n    hoverAnimation = \"combined\",\n  } = config;\n\n  // Get base button styles\n  const baseStyles = getKoreanButtonStyles(variant, false, isPressed);\n\n  // Variant-specific glow colors\n  const glowColors = {\n    primary: KOREAN_COLORS.PRIMARY_CYAN,\n    secondary: KOREAN_COLORS.ACCENT_GOLD,\n    danger: KOREAN_COLORS.ACCENT_RED,\n    success: KOREAN_COLORS.ACCENT_GREEN,\n    warning: KOREAN_COLORS.WARNING_ORANGE,\n  };\n\n  const glowColor = glowColors[variant];\n\n  // Hover state with visual effects\n  let hoverStyles: React.CSSProperties = {};\n  if (isHovered) {\n    hoverStyles = getHoverStateStyles(glowColor, hoverAnimation, glowIntensity);\n  }\n\n  // Focus state\n  let focusStyles: React.CSSProperties = {};\n  if (isFocused) {\n    focusStyles = getFocusStateStyles(glowColor, true);\n  }\n\n  // Extract font size from base styles (getKoreanButtonStyles always returns number | string)\n  const baseFontSize =\n    typeof baseStyles.fontSize === \"number\"\n      ? baseStyles.fontSize\n      : parseInt(String(baseStyles.fontSize), 10) || 14;\n\n  // Neon text glow for button text\n  const textGlow = getNeonTextShadow(\n    glowColor,\n    isHovered ? \"medium\" : \"subtle\",\n  );\n\n  // Korean font optimization\n  const fontOptimization = getKoreanFontOptimization(baseFontSize, \"bold\");\n\n  return {\n    ...baseStyles,\n    ...fontOptimization,\n    ...hoverStyles,\n    ...focusStyles,\n    textShadow: textGlow,\n    transition: getSmoothTransition(\"all\", \"normal\"),\n  };\n}\n\n/**\n * Get button visual effects only (no color/background/border)\n *\n * Extracts only visual effects (boxShadow, transition, transform, textShadow) from\n * getKoreanButtonWithGlow without color-related properties. This is useful for cases\n * where buttons need custom colors (e.g., menu selection states) but want to preserve\n * the visual effects system.\n *\n * This function provides an explicit contract for visual effects extraction, preventing\n * fragile coupling that could occur with destructuring patterns. If getKoreanButtonWithGlow\n * adds new visual effect properties in the future, they should be explicitly added here.\n *\n * **Intentionally Excluded Properties:**\n * - Layout: fontSize, fontFamily, fontWeight, padding, width, height, cursor\n * - Typography: letterSpacing, lineHeight, textRendering, WebkitFontSmoothing, MozOsxFontSmoothing\n * - Colors: color, background, backgroundColor, border, borderColor\n *\n * **Included Visual Effects:**\n * - boxShadow: Neon glow effects\n * - transition: Smooth state changes (0.2s ease)\n * - transform: Hover/press animations (scale)\n * - textShadow: Text glow effects\n *\n * **Note:** If getKoreanButtonWithGlow adds new visual effect properties (e.g., 'filter',\n * 'opacity', 'willChange', 'backdropFilter'), they must be explicitly added to this function's\n * return type and extraction logic to maintain the explicit contract.\n *\n * @param config - Same configuration as getKoreanButtonWithGlow\n * @returns React.CSSProperties with only visual effects (boxShadow, transition, transform, textShadow)\n *\n * @example\n * ```tsx\n * const visualEffects = getButtonVisualEffectsOnly({\n *   variant: 'primary',\n *   glowIntensity: 'strong',\n *   hoverAnimation: 'combined'\n * });\n *\n * <button style={{\n *   ...visualEffects,\n *   color: customColor,        // Apply custom colors\n *   background: customBg,\n *   border: customBorder\n * }}>\n *   Custom Button\n * </button>\n * ```\n *\n * @korean 버튼시각효과만얻기\n */\nexport function getButtonVisualEffectsOnly(\n  config: Parameters<typeof getKoreanButtonWithGlow>[0],\n): Pick<\n  React.CSSProperties,\n  \"boxShadow\" | \"transition\" | \"transform\" | \"textShadow\"\n> {\n  const fullStyles = getKoreanButtonWithGlow(config);\n\n  // Explicitly extract only visual effect properties\n  // Note: This explicitly excludes layout, typography, and color properties.\n  // If new visual effects (filter, opacity, willChange, etc.) are added to\n  // getKoreanButtonWithGlow, they must be added here to maintain the contract.\n  return {\n    boxShadow: fullStyles.boxShadow,\n    transition: fullStyles.transition,\n    transform: fullStyles.transform,\n    textShadow: fullStyles.textShadow,\n  };\n}\n\n/**\n * Get responsive spacing value\n *\n * Returns SPACING constant value for consistent spacing across components.\n * Optionally scales for mobile devices.\n *\n * **IMPORTANT**: This function accepts lowercase size parameters ('xs', 'sm', 'md', etc.)\n * to provide a more intuitive API, then internally converts to uppercase to match\n * SPACING constant keys ('XS', 'SM', 'MD', etc.). This design choice prioritizes\n * developer experience while maintaining compatibility with the SPACING constants.\n *\n * @param size - Spacing size constant ('xs', 'sm', 'md', 'lg', 'xl', 'xxl')\n * @param isMobile - Whether to apply mobile scaling (87.5% for mobile devices)\n * @returns Spacing value in pixels\n *\n * @example\n * ```tsx\n * const padding = getResponsiveSpacing('md', isMobile); // 16px desktop, 14px mobile\n * <div style={{ padding: `${padding}px` }}>Content</div>\n * ```\n *\n * @korean 반응형간격얻기\n */\nexport function getResponsiveSpacing(\n  size: SpacingSize,\n  isMobile: boolean = false,\n): number {\n  // Convert lowercase API parameter to uppercase SPACING constant key\n  // This provides a more ergonomic API while maintaining internal consistency\n  const spacingKey = size.toUpperCase() as keyof typeof SPACING;\n  const spacingValue = SPACING[spacingKey];\n  const mobileScale = 0.875; // 87.5% for mobile\n\n  // Runtime validation: While TypeScript prevents invalid sizes at compile time,\n  // this check provides safety for JavaScript consumers and edge cases where\n  // type assertions bypass TypeScript checks (e.g., 'as any', dynamic values)\n  if (spacingValue === undefined) {\n    const fallback = SPACING.MD;\n    console.warn(\n      `[koreanThemeHelpers:getResponsiveSpacing] Invalid spacing size \"${String(\n        size,\n      )}\" provided. Falling back to \"MD\".`,\n    );\n    return isMobile ? Math.round(fallback * mobileScale) : fallback;\n  }\n\n  return isMobile ? Math.round(spacingValue * mobileScale) : spacingValue;\n}\n\n/**\n * Get trigram symbol by name\n *\n * Returns Unicode trigram symbol for visual embellishment\n *\n * @param name - Trigram name in Korean\n * @returns Unicode trigram symbol\n *\n * @example\n * ```tsx\n * <div>{getTrigramSymbol('건')} 건 (Heaven)</div>\n * ```\n *\n * @korean 팔괘기호얻기\n */\nexport function getTrigramSymbol(\n  name: \"건\" | \"태\" | \"리\" | \"진\" | \"손\" | \"감\" | \"간\" | \"곤\",\n): string {\n  const symbols = {\n    건: \"☰\", // Heaven - 乾\n    태: \"☱\", // Lake - 兌\n    리: \"☲\", // Fire - 離\n    진: \"☳\", // Thunder - 震\n    손: \"☴\", // Wind - 巽\n    감: \"☵\", // Water - 坎\n    간: \"☶\", // Mountain - 艮\n    곤: \"☷\", // Earth - 坤\n  };\n  return symbols[name];\n}\n\n/**\n * Get trigram symbol styles with glow effect\n *\n * Enhances trigram symbols (☰☱☲☳☴☵☶☷) with cyberpunk neon glow\n * based on stance-specific colors and active state.\n *\n * @param config - Configuration object\n * @param config.stance - Trigram stance identifier (\"geon\", \"tae\", etc.)\n * @param config.isActive - Whether the trigram stance is currently active\n * @param config.size - Font size in pixels (optional, defaults based on active state)\n * @returns React.CSSProperties with trigram-specific glow\n *\n * @example\n * ```tsx\n * const trigramStyle = getTrigramSymbolWithGlow({ stance: 'geon', isActive: true });\n * <div style={trigramStyle}>\n *   ☰ 건 | Geon\n * </div>\n * ```\n *\n * @korean 팔괘기호네온글로우스타일얻기\n */\nexport function getTrigramSymbolWithGlow(config: {\n  readonly stance:\n    | \"geon\"\n    | \"tae\"\n    | \"li\"\n    | \"jin\"\n    | \"son\"\n    | \"gam\"\n    | \"gan\"\n    | \"gon\";\n  readonly isActive?: boolean;\n  readonly size?: number;\n}): React.CSSProperties & {\n  WebkitUserSelect?: string;\n} {\n  const { stance, isActive = false, size } = config;\n\n  // Map English stance names to Korean\n  const stanceToKorean = {\n    geon: \"건\",\n    tae: \"태\",\n    li: \"리\",\n    jin: \"진\",\n    son: \"손\",\n    gam: \"감\",\n    gan: \"간\",\n    gon: \"곤\",\n  };\n\n  const koreanName = stanceToKorean[stance];\n\n  // Trigram-specific colors matching KOREAN_COLORS\n  // Note: Comments reflect actual hex color values\n  // TODO: Fix source constants (colors.ts lines 84, 87) - TRIGRAM_GEON_PRIMARY should say \"Gold\" not \"White\",\n  //       TRIGRAM_JIN_PRIMARY should say \"Medium Purple\" not \"Yellow\"\n  const trigramColors: Record<string, number> = {\n    건: KOREAN_COLORS.TRIGRAM_GEON_PRIMARY, // Heaven - Gold (0xffd700)\n    태: KOREAN_COLORS.TRIGRAM_TAE_PRIMARY, // Lake - Sky Blue\n    리: KOREAN_COLORS.TRIGRAM_LI_PRIMARY, // Fire - Orange Red\n    진: KOREAN_COLORS.TRIGRAM_JIN_PRIMARY, // Thunder - Medium Purple (0x9370db)\n    손: KOREAN_COLORS.TRIGRAM_SON_PRIMARY, // Wind - Light Green\n    감: KOREAN_COLORS.TRIGRAM_GAM_PRIMARY, // Water - Blue\n    간: KOREAN_COLORS.TRIGRAM_GAN_PRIMARY, // Mountain - Brown\n    곤: KOREAN_COLORS.TRIGRAM_GON_PRIMARY, // Earth - Dark Gray\n  };\n\n  const trigramColor = trigramColors[koreanName];\n\n  // Get glow effect from visualEffects\n  const glowStyles = getTrigramGlowEffect(trigramColor, isActive);\n\n  // Korean font optimization for trigram symbols\n  const fontSize = size ?? (isActive ? 32 : 28);\n  const fontStyles = getKoreanFontOptimization(fontSize, \"bold\");\n\n  return {\n    ...fontStyles,\n    ...glowStyles,\n    fontFamily: FONT_FAMILY.KOREAN,\n    display: \"inline-block\",\n    userSelect: \"none\",\n    WebkitUserSelect: \"none\",\n  };\n}\n\n/**\n * Get Korean color name for documentation\n *\n * Maps hex color to Korean color name for better documentation\n *\n * @param hexColor - Hex color value from KOREAN_COLORS\n * @returns Korean name and English translation\n *\n * @internal Used primarily for JSDoc documentation\n * @korean 한국색상이름얻기\n */\nexport function getKoreanColorName(hexColor: number): {\n  korean: string;\n  english: string;\n} {\n  const colorNames: Record<number, { korean: string; english: string }> = {\n    [KOREAN_COLORS.PRIMARY_CYAN]: { korean: \"청록\", english: \"Cyan\" },\n    [KOREAN_COLORS.ACCENT_GOLD]: { korean: \"금색\", english: \"Gold\" },\n    [KOREAN_COLORS.ACCENT_RED]: { korean: \"빨강\", english: \"Red\" },\n    [KOREAN_COLORS.ACCENT_GREEN]: { korean: \"초록\", english: \"Green\" },\n    [KOREAN_COLORS.WARNING_ORANGE]: { korean: \"주황\", english: \"Orange\" },\n    [KOREAN_COLORS.TEXT_PRIMARY]: { korean: \"흰색\", english: \"White\" },\n    [KOREAN_COLORS.UI_BACKGROUND_DARK]: {\n      korean: \"어두운배경\",\n      english: \"Dark Background\",\n    },\n  };\n\n  return colorNames[hexColor] ?? { korean: \"알수없음\", english: \"Unknown\" };\n}\n\n/**\n * Format stat row with bilingual labels\n *\n * Creates consistent stat row styling for training/combat statistics\n *\n * @param korean - Korean label\n * @param english - English label\n * @param value - Stat value\n * @param valueColor - Hex color for value text\n * @param isMobile - Mobile responsive mode\n * @returns Stat row configuration object for React rendering\n *\n * @example\n * ```tsx\n * const statConfig = formatStatRow('점수', 'Score', 1500, KOREAN_COLORS.ACCENT_GOLD, false);\n * ```\n *\n * @korean 통계행형식화\n */\nexport function formatStatRow(\n  korean: string,\n  english: string,\n  value: string | number,\n  valueColor: number,\n  isMobile: boolean,\n): {\n  korean: string;\n  english: string;\n  value: string | number;\n  valueColor: number;\n  labelSize: string;\n  subLabelSize: string;\n  valueSize: string;\n} {\n  const labelSize = isMobile ? \"11px\" : \"12px\";\n  const subLabelSize = isMobile ? \"8px\" : \"9px\";\n  const valueSize = isMobile ? \"16px\" : \"18px\";\n\n  return {\n    korean,\n    english,\n    value,\n    valueColor,\n    labelSize,\n    subLabelSize,\n    valueSize,\n  };\n}\n"],"mappings":"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"}

package/lib/utils/math.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Mathematical utility functions for Black Trigram
+ *
+ * Provides shared mathematical operations used across combat, training,
+ * and physics systems to ensure consistency and follow DRY principles.
+ *
+ * **Korean**: 수학 유틸리티 함수
+ *
+ * @module utils/math
+ * @korean 수학유틸리티
+ */
+/**
+ * Calculate 3D Euclidean distance between two positions
+ *
+ * Uses the standard 3D distance formula: √(dx² + dy² + dz²)
+ * This is used throughout the combat and training systems to calculate
+ * distance between combatants, ensuring consistent distance calculations.
+ *
+ * **Korean**: 3D 유클리드 거리 계산
+ *
+ * @param pos1 - First position as [x, y, z] tuple
+ * @param pos2 - Second position as [x, y, z] tuple
+ * @returns The 3D Euclidean distance in meters
+ *
+ * @example
+ * const distance = calculateDistance3D([0, 0, 0], [3, 4, 0]);
+ * // Returns: 5.0 (3-4-5 triangle)
+ *
+ * @public
+ * @category Math Utilities
+ * @korean 3D거리계산
+ */
+export declare function calculateDistance3D(pos1: [number, number, number], pos2: [number, number, number]): number;
+/**
+ * Calculate squared 3D distance between two positions
+ *
+ * Optimized version that avoids the expensive square root operation.
+ * Useful when comparing distances (A > B) where the square root is unnecessary.
+ *
+ * **Korean**: 3D 거리 제곱 계산
+ *
+ * @param pos1 - First position as [x, y, z] tuple
+ * @param pos2 - Second position as [x, y, z] tuple
+ * @returns The squared 3D distance in meters²
+ *
+ * @example
+ * const distSq = calculateDistance3DSquared([0, 0, 0], [3, 4, 0]);
+ * // Returns: 25.0
+ *
+ * @public
+ * @category Math Utilities
+ * @korean 3D거리제곱계산
+ */
+export declare function calculateDistance3DSquared(pos1: [number, number, number], pos2: [number, number, number]): number;
+/**
+ * Convert degrees to radians
+ *
+ * Used throughout animation systems for bone rotations where angles are
+ * specified in degrees for readability but need to be converted to radians
+ * for Three.js rendering.
+ *
+ * **Korean**: 각도를 라디안으로 변환
+ *
+ * @param degrees - Angle in degrees (0-360)
+ * @returns Angle in radians (0-2π)
+ *
+ * @example
+ * const rightAngle = toRadians(90);
+ * // Returns: approximately 1.5708 (π/2)
+ *
+ * @example
+ * const straightAngle = toRadians(180);
+ * // Returns: approximately 3.1416 (π)
+ *
+ * @public
+ * @category Math Utilities
+ * @korean 각도변환
+ */
+export declare function toRadians(degrees: number): number;
+//# sourceMappingURL=math.d.ts.map

package/lib/utils/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC9B,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CAKR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC9B,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CAKR;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/lib/utils/math.js

@@ -0,0 +1,70 @@
+//#region src/utils/math.ts
+/**
+* Mathematical utility functions for Black Trigram
+* 
+* Provides shared mathematical operations used across combat, training,
+* and physics systems to ensure consistency and follow DRY principles.
+* 
+* **Korean**: 수학 유틸리티 함수
+* 
+* @module utils/math
+* @korean 수학유틸리티
+*/
+/**
+* Calculate 3D Euclidean distance between two positions
+* 
+* Uses the standard 3D distance formula: √(dx² + dy² + dz²)
+* This is used throughout the combat and training systems to calculate
+* distance between combatants, ensuring consistent distance calculations.
+* 
+* **Korean**: 3D 유클리드 거리 계산
+* 
+* @param pos1 - First position as [x, y, z] tuple
+* @param pos2 - Second position as [x, y, z] tuple
+* @returns The 3D Euclidean distance in meters
+* 
+* @example
+* const distance = calculateDistance3D([0, 0, 0], [3, 4, 0]);
+* // Returns: 5.0 (3-4-5 triangle)
+* 
+* @public
+* @category Math Utilities
+* @korean 3D거리계산
+*/
+function calculateDistance3D(pos1, pos2) {
+	const dx = pos1[0] - pos2[0];
+	const dy = pos1[1] - pos2[1];
+	const dz = pos1[2] - pos2[2];
+	return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+/**
+* Convert degrees to radians
+* 
+* Used throughout animation systems for bone rotations where angles are
+* specified in degrees for readability but need to be converted to radians
+* for Three.js rendering.
+* 
+* **Korean**: 각도를 라디안으로 변환
+* 
+* @param degrees - Angle in degrees (0-360)
+* @returns Angle in radians (0-2π)
+* 
+* @example
+* const rightAngle = toRadians(90);
+* // Returns: approximately 1.5708 (π/2)
+* 
+* @example
+* const straightAngle = toRadians(180);
+* // Returns: approximately 3.1416 (π)
+* 
+* @public
+* @category Math Utilities
+* @korean 각도변환
+*/
+function toRadians(degrees) {
+	return degrees * (Math.PI / 180);
+}
+//#endregion
+export { calculateDistance3D, toRadians };
+
+//# sourceMappingURL=math.js.map

package/lib/utils/math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.js","names":[],"sources":["../../src/utils/math.ts"],"sourcesContent":["/**\n * Mathematical utility functions for Black Trigram\n * \n * Provides shared mathematical operations used across combat, training,\n * and physics systems to ensure consistency and follow DRY principles.\n * \n * **Korean**: 수학 유틸리티 함수\n * \n * @module utils/math\n * @korean 수학유틸리티\n */\n\n/**\n * Calculate 3D Euclidean distance between two positions\n * \n * Uses the standard 3D distance formula: √(dx² + dy² + dz²)\n * This is used throughout the combat and training systems to calculate\n * distance between combatants, ensuring consistent distance calculations.\n * \n * **Korean**: 3D 유클리드 거리 계산\n * \n * @param pos1 - First position as [x, y, z] tuple\n * @param pos2 - Second position as [x, y, z] tuple\n * @returns The 3D Euclidean distance in meters\n * \n * @example\n * const distance = calculateDistance3D([0, 0, 0], [3, 4, 0]);\n * // Returns: 5.0 (3-4-5 triangle)\n * \n * @public\n * @category Math Utilities\n * @korean 3D거리계산\n */\nexport function calculateDistance3D(\n  pos1: [number, number, number],\n  pos2: [number, number, number]\n): number {\n  const dx = pos1[0] - pos2[0];\n  const dy = pos1[1] - pos2[1];\n  const dz = pos1[2] - pos2[2];\n  return Math.sqrt(dx * dx + dy * dy + dz * dz);\n}\n\n/**\n * Calculate squared 3D distance between two positions\n * \n * Optimized version that avoids the expensive square root operation.\n * Useful when comparing distances (A > B) where the square root is unnecessary.\n * \n * **Korean**: 3D 거리 제곱 계산\n * \n * @param pos1 - First position as [x, y, z] tuple\n * @param pos2 - Second position as [x, y, z] tuple\n * @returns The squared 3D distance in meters²\n * \n * @example\n * const distSq = calculateDistance3DSquared([0, 0, 0], [3, 4, 0]);\n * // Returns: 25.0\n * \n * @public\n * @category Math Utilities\n * @korean 3D거리제곱계산\n */\nexport function calculateDistance3DSquared(\n  pos1: [number, number, number],\n  pos2: [number, number, number]\n): number {\n  const dx = pos1[0] - pos2[0];\n  const dy = pos1[1] - pos2[1];\n  const dz = pos1[2] - pos2[2];\n  return dx * dx + dy * dy + dz * dz;\n}\n\n/**\n * Convert degrees to radians\n * \n * Used throughout animation systems for bone rotations where angles are\n * specified in degrees for readability but need to be converted to radians\n * for Three.js rendering.\n * \n * **Korean**: 각도를 라디안으로 변환\n * \n * @param degrees - Angle in degrees (0-360)\n * @returns Angle in radians (0-2π)\n * \n * @example\n * const rightAngle = toRadians(90);\n * // Returns: approximately 1.5708 (π/2)\n * \n * @example\n * const straightAngle = toRadians(180);\n * // Returns: approximately 3.1416 (π)\n * \n * @public\n * @category Math Utilities\n * @korean 각도변환\n */\nexport function toRadians(degrees: number): number {\n  return degrees * (Math.PI / 180);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,oBACd,MACA,MACQ;CACR,MAAM,KAAK,KAAK,KAAK,KAAK;CAC1B,MAAM,KAAK,KAAK,KAAK,KAAK;CAC1B,MAAM,KAAK,KAAK,KAAK,KAAK;AAC1B,QAAO,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;AAyD/C,SAAgB,UAAU,SAAyB;AACjD,QAAO,WAAW,KAAK,KAAK"}

package/lib/utils/mobileLayoutHelpers.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Mobile Layout Helpers
+ *
+ * Shared utilities for calculating mobile area bounds with consistent aspect ratios
+ * and device-specific sizing. Used by both combat and training layout hooks.
+ *
+ * @module utils/mobileLayoutHelpers
+ * @category Layout
+ * @korean 모바일레이아웃도우미
+ */
+/**
+ * Mobile area bounds with world dimensions.
+ *
+ * @public
+ */
+export interface MobileAreaBounds {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly scale: number;
+    readonly worldWidthMeters: number;
+    readonly worldDepthMeters: number;
+}
+/**
+ * Calculate mobile area bounds with 4:3 aspect ratio
+ *
+ * Implements consistent mobile area sizing logic shared between combat and training screens.
+ * Adapts to different device resolutions while maintaining a 4:3 aspect ratio.
+ * Enhanced with extra-small device support (<380px) for low-end mobile devices.
+ *
+ * @param width - Screen width in pixels
+ * @param height - Screen height in pixels
+ * @param topClearance - Minimum space to reserve at top (for HUD/header)
+ * @param bottomClearance - Minimum space to reserve at bottom (for controls)
+ * @param yOffset - Y position offset (typically header height + padding)
+ * @returns Mobile area bounds with position, dimensions, scale, and world dimensions
+ *
+ * @example
+ * ```typescript
+ * const bounds = calculateMobileAreaBounds(375, 667, 80, 120, 100);
+ * // Returns: { x: ~37, y: 100, width: 300, height: 225, scale: 0.3125, worldWidthMeters: 6, worldDepthMeters: 6 }
+ *
+ * const boundsSmall = calculateMobileAreaBounds(320, 568, 75, 110, 90);
+ * // Returns: { x: ~25, y: 90, width: 270, height: 202, scale: 0.28125, worldWidthMeters: 6, worldDepthMeters: 6 }
+ * ```
+ *
+ * @public
+ * @korean 모바일영역경계계산
+ */
+export declare function calculateMobileAreaBounds(width: number, height: number, topClearance: number, bottomClearance: number, yOffset: number): MobileAreaBounds;
+//# sourceMappingURL=mobileLayoutHelpers.d.ts.map

package/lib/utils/mobileLayoutHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobileLayoutHelpers.d.ts","sourceRoot":"","sources":["../../src/utils/mobileLayoutHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,GACd,gBAAgB,CA0DlB"}

package/lib/utils/mobileLayoutHelpers.js

@@ -0,0 +1,66 @@
+import { calculateArenaWorldDimensions } from "./arenaWorldDimensions.js";
+//#region src/utils/mobileLayoutHelpers.ts
+/**
+* Mobile Layout Helpers
+*
+* Shared utilities for calculating mobile area bounds with consistent aspect ratios
+* and device-specific sizing. Used by both combat and training layout hooks.
+*
+* @module utils/mobileLayoutHelpers
+* @category Layout
+* @korean 모바일레이아웃도우미
+*/
+/**
+* Calculate mobile area bounds with 4:3 aspect ratio
+*
+* Implements consistent mobile area sizing logic shared between combat and training screens.
+* Adapts to different device resolutions while maintaining a 4:3 aspect ratio.
+* Enhanced with extra-small device support (<380px) for low-end mobile devices.
+*
+* @param width - Screen width in pixels
+* @param height - Screen height in pixels
+* @param topClearance - Minimum space to reserve at top (for HUD/header)
+* @param bottomClearance - Minimum space to reserve at bottom (for controls)
+* @param yOffset - Y position offset (typically header height + padding)
+* @returns Mobile area bounds with position, dimensions, scale, and world dimensions
+*
+* @example
+* ```typescript
+* const bounds = calculateMobileAreaBounds(375, 667, 80, 120, 100);
+* // Returns: { x: ~37, y: 100, width: 300, height: 225, scale: 0.3125, worldWidthMeters: 6, worldDepthMeters: 6 }
+*
+* const boundsSmall = calculateMobileAreaBounds(320, 568, 75, 110, 90);
+* // Returns: { x: ~25, y: 90, width: 270, height: 202, scale: 0.28125, worldWidthMeters: 6, worldDepthMeters: 6 }
+* ```
+*
+* @public
+* @korean 모바일영역경계계산
+*/
+function calculateMobileAreaBounds(width, height, topClearance, bottomClearance, yOffset) {
+	const horizontalMargin = width < 380 ? 30 : 40;
+	const availableHeight = height - topClearance - bottomClearance;
+	const availableWidth = width - horizontalMargin;
+	let maxMobileWidth;
+	if (width >= 1440) maxMobileWidth = Math.min(availableWidth, 800);
+	else if (width >= 1200) maxMobileWidth = Math.min(availableWidth, 600);
+	else if (width >= 768) maxMobileWidth = Math.min(availableWidth, 500);
+	else if (width >= 380) maxMobileWidth = Math.min(availableWidth, 400);
+	else maxMobileWidth = Math.min(availableWidth, 320);
+	const areaWidth = Math.max(Math.min(maxMobileWidth, Math.min(availableHeight, width < 380 ? 240 : 800) * (4 / 3)), 280);
+	const areaHeight = areaWidth * (3 / 4);
+	const worldDimensions = calculateArenaWorldDimensions(areaWidth);
+	const scale = areaWidth / worldDimensions.widthMeters / 100;
+	return {
+		x: (width - areaWidth) / 2,
+		y: yOffset,
+		width: areaWidth,
+		height: areaHeight,
+		scale,
+		worldWidthMeters: worldDimensions.widthMeters,
+		worldDepthMeters: worldDimensions.depthMeters
+	};
+}
+//#endregion
+export { calculateMobileAreaBounds };
+
+//# sourceMappingURL=mobileLayoutHelpers.js.map

package/lib/utils/mobileLayoutHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobileLayoutHelpers.js","names":[],"sources":["../../src/utils/mobileLayoutHelpers.ts"],"sourcesContent":["/**\n * Mobile Layout Helpers\n *\n * Shared utilities for calculating mobile area bounds with consistent aspect ratios\n * and device-specific sizing. Used by both combat and training layout hooks.\n *\n * @module utils/mobileLayoutHelpers\n * @category Layout\n * @korean 모바일레이아웃도우미\n */\n\nimport { calculateArenaWorldDimensions } from \"./arenaWorldDimensions\";\n\n/**\n * Mobile area bounds with world dimensions.\n *\n * @public\n */\nexport interface MobileAreaBounds {\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly scale: number;\n  readonly worldWidthMeters: number;\n  readonly worldDepthMeters: number;\n}\n\n/**\n * Calculate mobile area bounds with 4:3 aspect ratio\n *\n * Implements consistent mobile area sizing logic shared between combat and training screens.\n * Adapts to different device resolutions while maintaining a 4:3 aspect ratio.\n * Enhanced with extra-small device support (<380px) for low-end mobile devices.\n *\n * @param width - Screen width in pixels\n * @param height - Screen height in pixels\n * @param topClearance - Minimum space to reserve at top (for HUD/header)\n * @param bottomClearance - Minimum space to reserve at bottom (for controls)\n * @param yOffset - Y position offset (typically header height + padding)\n * @returns Mobile area bounds with position, dimensions, scale, and world dimensions\n *\n * @example\n * ```typescript\n * const bounds = calculateMobileAreaBounds(375, 667, 80, 120, 100);\n * // Returns: { x: ~37, y: 100, width: 300, height: 225, scale: 0.3125, worldWidthMeters: 6, worldDepthMeters: 6 }\n *\n * const boundsSmall = calculateMobileAreaBounds(320, 568, 75, 110, 90);\n * // Returns: { x: ~25, y: 90, width: 270, height: 202, scale: 0.28125, worldWidthMeters: 6, worldDepthMeters: 6 }\n * ```\n *\n * @public\n * @korean 모바일영역경계계산\n */\nexport function calculateMobileAreaBounds(\n  width: number,\n  height: number,\n  topClearance: number,\n  bottomClearance: number,\n  yOffset: number,\n): MobileAreaBounds {\n  // Calculate available space for the area\n  // Extra-small devices (<380px) use tighter margins for more screen real estate\n  const horizontalMargin = width < 380 ? 30 : 40; // 15px vs 20px per side\n  const availableHeight = height - topClearance - bottomClearance;\n  const availableWidth = width - horizontalMargin;\n\n  // Determine max width based on device resolution\n  // Device-specific sizing with extra-small support:\n  // - 4K/QHD+ (≥1440px): up to 800px\n  // - 2K (1200-1439px): up to 600px\n  // - Large phones (768-1199px): up to 500px\n  // - Standard phones (380-767px): up to 400px\n  // - Extra-small phones (<380px): up to 320px\n  let maxMobileWidth: number;\n  if (width >= 1440) {\n    maxMobileWidth = Math.min(availableWidth, 800);\n  } else if (width >= 1200) {\n    maxMobileWidth = Math.min(availableWidth, 600);\n  } else if (width >= 768) {\n    maxMobileWidth = Math.min(availableWidth, 500);\n  } else if (width >= 380) {\n    maxMobileWidth = Math.min(availableWidth, 400);\n  } else {\n    // Extra-small devices (iPhone SE, old Android, budget phones)\n    maxMobileWidth = Math.min(availableWidth, 320);\n  }\n\n  // Extra-small devices also get reduced max height for better fit\n  const maxMobileHeight = Math.min(availableHeight, width < 380 ? 240 : 800);\n\n  // Use 4:3 aspect ratio for arena (width > height)\n  // Calculate area width first, constrained by available space\n  const areaWidth = Math.max(\n    Math.min(maxMobileWidth, maxMobileHeight * (4 / 3)),\n    280,\n  );\n  const areaHeight = areaWidth * (3 / 4); // 4:3 aspect ratio\n\n  // Calculate world dimensions based on RENDERED arena width (not screen width)\n  // This ensures correct pixels-per-meter ratio for the actual visible arena\n  const worldDimensions = calculateArenaWorldDimensions(areaWidth);\n\n  // Calculate 3D scale factor based on reference arena\n  // Reference: 10m arena at 1000px = 100 px/m\n  const pixelsPerMeter = areaWidth / worldDimensions.widthMeters;\n  const referencePixelsPerMeter = 100;\n  const scale = pixelsPerMeter / referencePixelsPerMeter;\n\n  return {\n    x: (width - areaWidth) / 2, // Centered horizontally\n    y: yOffset,\n    width: areaWidth,\n    height: areaHeight, // 4:3 aspect ratio\n    scale,\n    worldWidthMeters: worldDimensions.widthMeters,\n    worldDepthMeters: worldDimensions.depthMeters,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,SAAgB,0BACd,OACA,QACA,cACA,iBACA,SACkB;CAGlB,MAAM,mBAAmB,QAAQ,MAAM,KAAK;CAC5C,MAAM,kBAAkB,SAAS,eAAe;CAChD,MAAM,iBAAiB,QAAQ;CAS/B,IAAI;AACJ,KAAI,SAAS,KACX,kBAAiB,KAAK,IAAI,gBAAgB,IAAI;UACrC,SAAS,KAClB,kBAAiB,KAAK,IAAI,gBAAgB,IAAI;UACrC,SAAS,IAClB,kBAAiB,KAAK,IAAI,gBAAgB,IAAI;UACrC,SAAS,IAClB,kBAAiB,KAAK,IAAI,gBAAgB,IAAI;KAG9C,kBAAiB,KAAK,IAAI,gBAAgB,IAAI;CAQhD,MAAM,YAAY,KAAK,IACrB,KAAK,IAAI,gBALa,KAAK,IAAI,iBAAiB,QAAQ,MAAM,MAAM,IAAI,IAK5B,IAAI,GAAG,EACnD,IACD;CACD,MAAM,aAAa,aAAa,IAAI;CAIpC,MAAM,kBAAkB,8BAA8B,UAAU;CAMhE,MAAM,QAFiB,YAAY,gBAAgB,cACnB;AAGhC,QAAO;EACL,IAAI,QAAQ,aAAa;EACzB,GAAG;EACH,OAAO;EACP,QAAQ;EACR;EACA,kBAAkB,gBAAgB;EAClC,kBAAkB,gBAAgB;EACnC"}

package/lib/utils/mobileUIUtils.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Mobile UI utilities for responsive touch-optimized interfaces
+ *
+ * Provides helpers for touch target sizing, responsive font scaling,
+ * and mobile-specific layout calculations following iOS/Android guidelines.
+ *
+ * PRIORITY: High-end mobile devices (Super HD, 2K+) are top priority and get:
+ * - Enhanced touch targets (56px vs 48px)
+ * - Larger Korean fonts (+10% for better readability)
+ * - Optimized spacing and layout
+ * - Full feature parity with desktop
+ *
+ * Supported Devices (Priority Order):
+ * 1. Super HD Mobile (≥768px): Motorola Edge 60 Pro, Galaxy S-series
+ * 2. Standard Mobile (375-767px): iPhone 12/13/14, standard Android
+ * 3. Small Mobile (<375px): iPhone SE, budget devices
+ *
+ * @module utils/mobileUIUtils
+ * @category Mobile Utilities
+ * @korean 모바일UI유틸리티
+ */
+import { KOREAN_MOBILE_FONT_SIZES } from "../types/constants/typography";
+/**
+ * Viewport size category for responsive design
+ *
+ * @category Mobile UI
+ * @korean 뷰포트크기범주
+ */
+export type ViewportSize = "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * Touch target size configuration
+ *
+ * @category Mobile UI
+ * @korean 터치타겟크기설정
+ */
+export interface TouchTargetSize {
+    readonly minWidth: number;
+    readonly minHeight: number;
+    readonly padding: number;
+    readonly spacing: number;
+}
+/**
+ * Get viewport size category from width
+ *
+ * PRIORITY: High-end mobile devices (Super HD, 2K+) are treated as 'md' for optimal layout
+ *
+ * @param width - Viewport width in pixels
+ * @returns Viewport size category
+ *
+ * @example
+ * ```typescript
+ * getViewportSize(375); // 'xs' (iPhone SE)
+ * getViewportSize(768); // 'sm' (Standard phones, high-end mobiles start here)
+ * getViewportSize(2712); // 'md' (Motorola Edge 60 Pro Super HD)
+ * getViewportSize(1200); // 'lg' (Desktop)
+ * ```
+ *
+ * @public
+ * @korean 뷰포트크기얻기
+ */
+export declare function getViewportSize(width: number): ViewportSize;
+/**
+ * Get touch-optimized button size configuration
+ * Ensures minimum 48px touch targets per iOS/Android guidelines
+ *
+ * PRIORITY: High-end mobile devices (Super HD, 2K+) get enhanced touch targets (56px)
+ * for better precision on high-resolution displays
+ *
+ * @param isMobile - Whether on mobile device
+ * @param viewportWidth - Optional viewport width for fine-tuning
+ * @returns Touch target size configuration
+ *
+ * @example
+ * ```typescript
+ * const buttonSize = getTouchTargetSize(true, 375);
+ * // { minWidth: 48, minHeight: 48, padding: 12, spacing: 8 }
+ *
+ * const superHDButtonSize = getTouchTargetSize(true, 2712);
+ * // { minWidth: 56, minHeight: 56, padding: 16, spacing: 12 }
+ * ```
+ *
+ * @public
+ * @korean 터치타겟크기얻기
+ */
+export declare function getTouchTargetSize(isMobile: boolean, viewportWidth?: number): TouchTargetSize;
+/**
+ * Get responsive Korean font size for mobile
+ * Ensures minimum 16px for body text on mobile
+ *
+ * PRIORITY: High-end mobile (Super HD, 2K+) get enhanced font sizes for better readability
+ *
+ * @param size - Size category ('SMALL', 'MEDIUM', 'LARGE')
+ * @param viewportWidth - Viewport width in pixels
+ * @returns Font size in pixels
+ *
+ * @example
+ * ```typescript
+ * getMobileKoreanFontSize('SMALL', 375); // 16
+ * getMobileKoreanFontSize('MEDIUM', 410); // 18
+ * getMobileKoreanFontSize('MEDIUM', 2712); // 20 (Super HD enhanced)
+ * getMobileKoreanFontSize('LARGE', 768); // 24
+ * ```
+ *
+ * @public
+ * @korean 모바일한글글꼴크기얻기
+ */
+export declare function getMobileKoreanFontSize(size: keyof typeof KOREAN_MOBILE_FONT_SIZES, viewportWidth: number): number;
+/**
+ * Get responsive spacing value
+ * Scales spacing based on viewport size
+ *
+ * @param baseSpacing - Base spacing value from SPACING constant
+ * @param isMobile - Whether on mobile device
+ * @returns Scaled spacing in pixels
+ *
+ * @example
+ * ```typescript
+ * getResponsiveSpacing(SPACING.MD, true); // 12 (COMPACT on mobile)
+ * getResponsiveSpacing(SPACING.MD, false); // 16 (original)
+ * ```
+ *
+ * @public
+ * @korean 반응형간격얻기
+ */
+export declare function getResponsiveSpacing(baseSpacing: number, isMobile: boolean): number;
+/**
+ * Calculate responsive panel width
+ * Ensures panels fit within viewport with proper margins
+ *
+ * @param viewportWidth - Viewport width in pixels
+ * @param isMobile - Whether on mobile device
+ * @param minMargin - Minimum margin on each side (default: 20px)
+ * @returns Panel width in pixels
+ *
+ * @example
+ * ```typescript
+ * getResponsivePanelWidth(375, true); // ~335px (375 - 40 margin)
+ * getResponsivePanelWidth(1200, false); // ~400px (max width applied)
+ * ```
+ *
+ * @public
+ * @korean 반응형패널폭얻기
+ */
+export declare function getResponsivePanelWidth(viewportWidth: number, isMobile: boolean, minMargin?: number): number;
+/**
+ * Check if viewport is in landscape orientation
+ *
+ * @param viewportWidth - Viewport width in pixels
+ * @param viewportHeight - Viewport height in pixels
+ * @returns Whether in landscape orientation
+ *
+ * @example
+ * ```typescript
+ * isLandscape(812, 375); // true (iPhone X landscape)
+ * isLandscape(375, 812); // false (iPhone X portrait)
+ * ```
+ *
+ * @public
+ * @korean 가로모드여부
+ */
+export declare function isLandscape(viewportWidth: number, viewportHeight: number): boolean;
+/**
+ * Get responsive button styles for touch optimization
+ *
+ * @param isMobile - Whether on mobile device
+ * @param viewportWidth - Optional viewport width
+ * @returns CSS properties for button
+ *
+ * @example
+ * ```typescript
+ * const buttonStyles = getResponsiveButtonStyles(true, 375);
+ * // {
+ * //   minWidth: '48px',
+ * //   minHeight: '48px',
+ * //   padding: '12px',
+ * //   fontSize: '16px',
+ * //   ...
+ * // }
+ * ```
+ *
+ * @public
+ * @korean 반응형버튼스타일얻기
+ */
+export declare function getResponsiveButtonStyles(isMobile: boolean, viewportWidth?: number): React.CSSProperties;
+/**
+ * Get responsive text styles with proper Korean font sizing
+ *
+ * @param size - Font size category
+ * @param isMobile - Whether on mobile device
+ * @param viewportWidth - Viewport width in pixels
+ * @returns CSS properties for text
+ *
+ * @example
+ * ```typescript
+ * const textStyles = getResponsiveTextStyles('MEDIUM', true, 375);
+ * // {
+ * //   fontSize: '18px',
+ * //   lineHeight: '1.5',
+ * //   letterSpacing: '0.02em',
+ * // }
+ * ```
+ *
+ * @public
+ * @korean 반응형텍스트스타일얻기
+ */
+export declare function getResponsiveTextStyles(size: keyof typeof KOREAN_MOBILE_FONT_SIZES, isMobile: boolean, viewportWidth: number): React.CSSProperties;
+/**
+ * Calculate minimum spacing between interactive elements
+ * Ensures adequate spacing for touch accuracy
+ *
+ * @param isMobile - Whether on mobile device
+ * @returns Minimum spacing in pixels
+ *
+ * @example
+ * ```typescript
+ * getMinimumInteractiveSpacing(true); // 8px (mobile)
+ * getMinimumInteractiveSpacing(false); // 12px (desktop)
+ * ```
+ *
+ * @public
+ * @korean 최소상호작용간격얻기
+ */
+export declare function getMinimumInteractiveSpacing(isMobile: boolean): number;
+/**
+ * Viewport detection utilities
+ *
+ * PRIORITY: High-end mobile devices (Super HD, 2K+) are explicitly supported
+ *
+ * @category Mobile UI
+ * @korean 뷰포트감지
+ */
+export declare const ViewportDetection: {
+    /**
+     * Check if iPhone SE or similar small device
+     * @korean iPhone SE여부
+     */
+    readonly isSmallMobile: (width: number) => boolean;
+    /**
+     * Check if standard mobile device (excluding high-end)
+     * @korean 표준모바일여부
+     */
+    readonly isMobile: (width: number) => boolean;
+    /**
+     * Check if high-end mobile device (Super HD, 2K+)
+     * Uses height + DPR to distinguish phones from tablets
+     * High-end phones: short side 400-600px, long side >=800px, DPR >=2
+     * @korean 고급모바일여부
+     */
+    readonly isSuperHDMobile: (width: number, height?: number) => boolean;
+    /**
+     * Check if tablet device
+     * @korean 태블릿여부
+     */
+    readonly isTablet: (width: number) => boolean;
+    /**
+     * Check if desktop device
+     * @korean 데스크톱여부
+     */
+    readonly isDesktop: (width: number) => boolean;
+    /**
+     * Check if device has notch (iPhone X+)
+     * @korean 노치여부
+     */
+    readonly hasNotch: (width: number, height: number) => boolean;
+};
+//# sourceMappingURL=mobileUIUtils.d.ts.map

package/lib/utils/mobileUIUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobileUIUtils.d.ts","sourceRoot":"","sources":["../../src/utils/mobileUIUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EACL,wBAAwB,EAEzB,MAAM,+BAA+B,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAM3D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,OAAO,EACjB,aAAa,CAAC,EAAE,MAAM,GACrB,eAAe,CA8BjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,OAAO,wBAAwB,EAC3C,aAAa,EAAE,MAAM,GACpB,MAAM,CAUR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,OAAO,GAChB,MAAM,CAER;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,OAAO,EACjB,SAAS,SAAK,GACb,MAAM,CAOR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,GACrB,OAAO,CAET;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,OAAO,EACjB,aAAa,CAAC,EAAE,MAAM,GACrB,KAAK,CAAC,aAAa,CAgBrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,OAAO,wBAAwB,EAC3C,QAAQ,EAAE,OAAO,EACjB,aAAa,EAAE,MAAM,GACpB,KAAK,CAAC,aAAa,CAUrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAItE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;;OAGG;oCACoB,MAAM;IAE7B;;;OAGG;+BACe,MAAM;IAExB;;;;;OAKG;sCACsB,MAAM,WAAU,MAAM;IAO/C;;;OAGG;+BACe,MAAM;IAExB;;;OAGG;gCACgB,MAAM;IAEzB;;;OAGG;+BACe,MAAM,UAAU,MAAM;CAMhC,CAAC"}

package/lib/utils/mobileUIUtils.js

@@ -0,0 +1,33 @@
+import { getKoreanFontSize } from "../types/constants/typography.js";
+import "../types/constants/ui.js";
+//#region src/utils/mobileUIUtils.ts
+/**
+* Get responsive Korean font size for mobile
+* Ensures minimum 16px for body text on mobile
+* 
+* PRIORITY: High-end mobile (Super HD, 2K+) get enhanced font sizes for better readability
+* 
+* @param size - Size category ('SMALL', 'MEDIUM', 'LARGE')
+* @param viewportWidth - Viewport width in pixels
+* @returns Font size in pixels
+* 
+* @example
+* ```typescript
+* getMobileKoreanFontSize('SMALL', 375); // 16
+* getMobileKoreanFontSize('MEDIUM', 410); // 18
+* getMobileKoreanFontSize('MEDIUM', 2712); // 20 (Super HD enhanced)
+* getMobileKoreanFontSize('LARGE', 768); // 24
+* ```
+* 
+* @public
+* @korean 모바일한글글꼴크기얻기
+*/
+function getMobileKoreanFontSize(size, viewportWidth) {
+	const fontSize = getKoreanFontSize(size, viewportWidth);
+	if (viewportWidth >= 768) return Math.ceil(fontSize * 1.1);
+	return fontSize;
+}
+//#endregion
+export { getMobileKoreanFontSize };
+
+//# sourceMappingURL=mobileUIUtils.js.map