blacktrigram 0.7.2

package/lib/types/LayoutTypes.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Layout-related type definitions for unified positioning system
+ *
+ * Provides type-safe interfaces for grid-based layout, responsive positioning,
+ * and z-index hierarchy management across all screens.
+ *
+ * @module types/LayoutTypes
+ * @category Type Definitions
+ * @korean 레이아웃타입
+ */
+import { Position } from "./common";
+/**
+ * Screen size breakpoints for responsive design
+ *
+ * @category Layout Types
+ * @korean 화면크기
+ */
+export interface ScreenSize {
+    /** Screen width in pixels */
+    readonly width: number;
+    /** Screen height in pixels */
+    readonly height: number;
+    /** Whether the device is mobile (<768px) */
+    readonly isMobile: boolean;
+    /** Whether the device is tablet (768-1199px) */
+    readonly isTablet: boolean;
+    /** Whether the device is desktop (≥1200px) */
+    readonly isDesktop: boolean;
+    /** Whether the screen is in landscape orientation */
+    readonly isLandscape: boolean;
+}
+/**
+ * Grid-based position configuration
+ *
+ * Uses 12-column grid system for consistent alignment.
+ *
+ * **Important:** Valid combinations must satisfy:
+ * - column: 0-11 (starting column)
+ * - span: 1-12 (number of columns to span)
+ * - column + span ≤ 12 (must not exceed grid width)
+ *
+ * Invalid combinations (e.g., column: 10, span: 5) will throw runtime errors.
+ * Use LayoutSystem.calculateGridPosition() which validates inputs.
+ *
+ * @category Layout Types
+ * @korean 그리드위치
+ *
+ * @example Valid positions
+ * ```typescript
+ * { column: 0, span: 12 }  // Full width
+ * { column: 2, span: 8 }   // Centered 8 columns
+ * { column: 0, span: 6 }   // Left half
+ * { column: 6, span: 6 }   // Right half
+ * ```
+ *
+ * @example Invalid positions (will throw errors)
+ * ```typescript
+ * { column: 10, span: 5 }  // ERROR: 10 + 5 = 15 > 12
+ * { column: -1, span: 6 }  // ERROR: column < 0
+ * { column: 5, span: 0 }   // ERROR: span < 1
+ * ```
+ */
+export interface GridPosition {
+    /** Grid column to start from (0-11) */
+    readonly column: number;
+    /** Number of columns to span (1-12) */
+    readonly span: number;
+    /** Row index for vertical positioning (multiplied by DEFAULT_ROW_HEIGHT=100px) */
+    readonly row?: number;
+    /** Gutter size in pixels (default: 20) */
+    readonly gutter?: number;
+}
+/**
+ * Responsive position that adapts to screen size
+ *
+ * @category Layout Types
+ * @korean 반응형위치
+ */
+export interface ResponsivePosition {
+    /** Base position for desktop (1200px+) */
+    readonly base: Position;
+    /** Position override for tablet (768-1199px) */
+    readonly tablet?: Position;
+    /** Position override for mobile (<768px) */
+    readonly mobile?: Position;
+    /** Whether to scale proportionally based on screen width */
+    readonly scaleProportionally?: boolean;
+}
+/**
+ * Z-index hierarchy for layering UI elements
+ *
+ * Ensures consistent stacking order across all screens
+ *
+ * **Usage Guidelines:**
+ * - NEVER use arbitrary z-index values (e.g., 999)
+ * - Use these constants to maintain consistent layer ordering
+ * - Layer order: Scene → HUD → Overlay → Modal → Pause Menu
+ *
+ * @category Layout Constants
+ * @korean z인덱스계층
+ */
+export declare const Z_INDEX: {
+    /** Background scenes and effects - 배경 */
+    readonly BACKGROUND: 0;
+    /** Combat arena and training grounds - 경기장 */
+    readonly ARENA: 10;
+    /** Player characters and enemies - 플레이어 */
+    readonly PLAYERS: 20;
+    /** Visual effects and particles - 효과 */
+    readonly EFFECTS: 30;
+    /** HUD background elements - HUD 배경 */
+    readonly HUD_BACKGROUND: 40;
+    /** Main HUD elements (health bars, timers, stats) - 주 HUD */
+    readonly HUD: 50;
+    /** TechniqueBar for combat techniques - 기술바 */
+    readonly TECHNIQUE_BAR: 55;
+    /** HUD overlay elements (within HUD components) - HUD 오버레이 */
+    readonly HUD_OVERLAY: 60;
+    /** Mobile touch controls - 모바일제어 */
+    readonly MOBILE_CONTROLS: 100;
+    /** Modal dialogs and overlays - 모달 */
+    readonly MODAL: 200;
+    /** Tooltips and hints - 툴팁 */
+    readonly TOOLTIP: 300;
+    /** Pause menu - 일시정지 메뉴 */
+    readonly PAUSE_MENU: 1000;
+    /** Loading screens - 로딩 */
+    readonly LOADING: 2000;
+    /** Debug and performance overlays - 디버그 */
+    readonly DEBUG: 9000;
+};
+/**
+ * Type for Z_INDEX values
+ *
+ * @category Layout Types
+ */
+export type ZIndexValue = (typeof Z_INDEX)[keyof typeof Z_INDEX];
+/**
+ * Alignment options for positioning elements
+ *
+ * @category Layout Types
+ * @korean 정렬
+ */
+export type HorizontalAlignment = "left" | "center" | "right";
+export type VerticalAlignment = "top" | "middle" | "bottom";
+/**
+ * Layout configuration for a component
+ *
+ * @category Layout Types
+ * @korean 레이아웃설정
+ */
+export interface LayoutConfig {
+    /** Grid-based position (if using grid system) */
+    readonly grid?: GridPosition;
+    /** Responsive position (if not using grid) */
+    readonly position?: ResponsivePosition;
+    /** Z-index layer for stacking */
+    readonly zIndex?: ZIndexValue;
+    /** Horizontal alignment within container */
+    readonly horizontalAlign?: HorizontalAlignment;
+    /** Vertical alignment within container */
+    readonly verticalAlign?: VerticalAlignment;
+    /** Margin in pixels */
+    readonly margin?: number;
+    /** Padding in pixels */
+    readonly padding?: number;
+}
+/**
+ * Safe area insets for mobile devices with notches
+ *
+ * @category Layout Types
+ * @korean 안전영역
+ */
+export interface SafeAreaInsets {
+    /** Top inset (notch, status bar) */
+    readonly top: number;
+    /** Right inset (typically 0) */
+    readonly right: number;
+    /** Bottom inset (home indicator) */
+    readonly bottom: number;
+    /** Left inset (typically 0) */
+    readonly left: number;
+}
+/**
+ * Container bounds for positioning child elements
+ *
+ * @category Layout Types
+ * @korean 컨테이너경계
+ */
+export interface ContainerBounds {
+    /** X position in pixels */
+    readonly x: number;
+    /** Y position in pixels */
+    readonly y: number;
+    /** Width in pixels */
+    readonly width: number;
+    /** Height in pixels */
+    readonly height: number;
+    /** Scale factor (1.0 = no scaling) */
+    readonly scale?: number;
+}
+/**
+ * HUD Positioning Strategy Documentation
+ *
+ * This section defines the standardized approach for positioning HUD elements
+ * across all screens in the Black Trigram game.
+ *
+ * **Screen-Level HUDs (Left/Right/Top/Bottom)**:
+ * - Use `position: "absolute"` to anchor to screen edges
+ * - Anchor directly to edges: `left: 0`, `right: 0`, `top: 0`, `bottom: 0`
+ * - Size using percentage-based calculations: `width: ${width * 0.14}px`
+ * - Use Z_INDEX.HUD for consistent layering
+ * - Example: Combat Left/Right HUDs, Top/Bottom bars
+ *
+ * **HUD Internal Content**:
+ * - Use `position: "relative"` for natural document flow
+ * - Use Flexbox for vertical/horizontal layouts: `display: "flex"`, `flexDirection`, `gap`
+ * - Use CSS Grid for complex multi-dimensional layouts
+ * - Avoid absolute positioning within HUDs (except for special cases)
+ * - Example: Player stats, technique cards, control buttons
+ *
+ * **Special Cases (Overlays/Tooltips)**:
+ * - Use `position: "absolute"` for floating elements that must overlay content
+ * - Position relative to parent container
+ * - Use Z_INDEX.HUD_OVERLAY or Z_INDEX.TOOLTIP
+ * - Example: Combat messages, feedback overlays, tooltips
+ *
+ * **Responsive Design**:
+ * - All components must support `isMobile` prop
+ * - Use responsive calculations: `isMobile ? 18 : 14` for mobile scaling
+ * - Apply `positionScale` multiplier for 4K displays (1.0-1.5)
+ *
+ * @category Layout Guidelines
+ * @korean HUD위치전략
+ */
+/**
+ * HUD width percentages for screen-level HUDs
+ *
+ * These constants define the standard widths for left and right HUD panels.
+ * Values are decimals (0.14 = 14% of screen width).
+ *
+ * **Usage:**
+ * ```tsx
+ * const hudWidth = width * HUD_WIDTH_PERCENT.LEFT_DESKTOP;
+ * ```
+ *
+ * @category Layout Constants
+ * @korean HUD너비
+ */
+export declare const HUD_WIDTH_PERCENT: {
+    /** Left HUD width on desktop (14% = leaves 72% for arena) */
+    readonly LEFT_DESKTOP: 0.14;
+    /** Left HUD width on mobile (18% for touch targets) */
+    readonly LEFT_MOBILE: 0.18;
+    /** Right HUD width on desktop (14% = leaves 72% for arena) */
+    readonly RIGHT_DESKTOP: 0.14;
+    /** Right HUD width on mobile (18% for touch targets) */
+    readonly RIGHT_MOBILE: 0.18;
+    /** Top HUD width (full screen width) */
+    readonly TOP: 1;
+    /** Bottom HUD width (full screen width) */
+    readonly BOTTOM: 1;
+};
+/**
+ * HUD height constants for top and bottom bars
+ *
+ * These constants define the standard heights for top and bottom HUD bars.
+ * Values are in pixels and should be scaled with `positionScale` for 4K displays.
+ *
+ * **Usage:**
+ * ```tsx
+ * const hudHeight = HUD_HEIGHT.TOP_DESKTOP * positionScale;
+ * ```
+ *
+ * @category Layout Constants
+ * @korean HUD높이
+ */
+export declare const HUD_HEIGHT: {
+    /** Top bar height on desktop (slim for minimal obstruction) */
+    readonly TOP_DESKTOP: 70;
+    /** Top bar height on mobile (extra slim) */
+    readonly TOP_MOBILE: 50;
+    /** Bottom bar height on desktop (fits technique cards) */
+    readonly BOTTOM_DESKTOP: 120;
+    /** Bottom bar height on mobile (compact) */
+    readonly BOTTOM_MOBILE: 100;
+    /** Combat-specific top bar height */
+    readonly COMBAT_TOP_DESKTOP: 70;
+    /** Combat-specific top bar height on mobile */
+    readonly COMBAT_TOP_MOBILE: 55;
+    /** Combat-specific bottom bar height */
+    readonly COMBAT_BOTTOM_DESKTOP: 120;
+    /** Combat-specific bottom bar height on mobile */
+    readonly COMBAT_BOTTOM_MOBILE: 100;
+    /** Training-specific top bar height */
+    readonly TRAINING_TOP_DESKTOP: 70;
+    /** Training-specific top bar height on mobile */
+    readonly TRAINING_TOP_MOBILE: 50;
+    /** Training-specific bottom bar height */
+    readonly TRAINING_BOTTOM_DESKTOP: 130;
+    /** Training-specific bottom bar height on mobile */
+    readonly TRAINING_BOTTOM_MOBILE: 110;
+};
+/**
+ * HUD positioning configuration interface
+ *
+ * Defines the positioning strategy for a HUD component.
+ *
+ * @category Layout Types
+ * @korean HUD위치설정
+ */
+export interface HUDPositionConfig {
+    /** Positioning strategy */
+    readonly strategy: "absolute" | "relative" | "flex" | "grid";
+    /** Anchor point for absolute positioning */
+    readonly anchor?: "left" | "right" | "top" | "bottom" | "center";
+    /** Offset from anchor point */
+    readonly offset?: {
+        x?: number;
+        y?: number;
+    };
+    /** Size configuration */
+    readonly size?: {
+        width?: string | number;
+        height?: string | number;
+    };
+    /** Z-index layer */
+    readonly zIndex?: ZIndexValue;
+}
+//# sourceMappingURL=LayoutTypes.d.ts.map

package/lib/types/LayoutTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LayoutTypes.d.ts","sourceRoot":"","sources":["../../src/types/LayoutTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO;IAElB,yCAAyC;;IAEzC,8CAA8C;;IAE9C,2CAA2C;;IAE3C,wCAAwC;;IAIxC,uCAAuC;;IAEvC,6DAA6D;;IAE7D,+CAA+C;;IAE/C,8DAA8D;;IAI9D,oCAAoC;;IAEpC,sCAAsC;;IAEtC,8BAA8B;;IAE9B,2BAA2B;;IAE3B,2BAA2B;;IAE3B,2CAA2C;;CAEnC,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IACvC,iCAAiC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,mBAAmB,CAAC;IAC/C,0CAA0C;IAC1C,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAC3C,uBAAuB;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB;IAC5B,6DAA6D;;IAE7D,uDAAuD;;IAEvD,8DAA8D;;IAE9D,wDAAwD;;IAExD,wCAAwC;;IAExC,2CAA2C;;CAEnC,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;IACrB,+DAA+D;;IAE/D,4CAA4C;;IAE5C,0DAA0D;;IAE1D,4CAA4C;;IAE5C,qCAAqC;;IAErC,+CAA+C;;IAE/C,wCAAwC;;IAExC,kDAAkD;;IAElD,uCAAuC;;IAEvC,iDAAiD;;IAEjD,0CAA0C;;IAE1C,oDAAoD;;CAE5C,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7D,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACjE,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,yBAAyB;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACtE,oBAAoB;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B"}

package/lib/types/LayoutTypes.js

@@ -0,0 +1,118 @@
+//#region src/types/LayoutTypes.ts
+/**
+* Z-index hierarchy for layering UI elements
+*
+* Ensures consistent stacking order across all screens
+*
+* **Usage Guidelines:**
+* - NEVER use arbitrary z-index values (e.g., 999)
+* - Use these constants to maintain consistent layer ordering
+* - Layer order: Scene → HUD → Overlay → Modal → Pause Menu
+*
+* @category Layout Constants
+* @korean z인덱스계층
+*/
+var Z_INDEX = {
+	BACKGROUND: 0,
+	ARENA: 10,
+	PLAYERS: 20,
+	EFFECTS: 30,
+	HUD_BACKGROUND: 40,
+	HUD: 50,
+	TECHNIQUE_BAR: 55,
+	HUD_OVERLAY: 60,
+	MOBILE_CONTROLS: 100,
+	MODAL: 200,
+	TOOLTIP: 300,
+	PAUSE_MENU: 1e3,
+	LOADING: 2e3,
+	DEBUG: 9e3
+};
+/**
+* HUD Positioning Strategy Documentation
+*
+* This section defines the standardized approach for positioning HUD elements
+* across all screens in the Black Trigram game.
+*
+* **Screen-Level HUDs (Left/Right/Top/Bottom)**:
+* - Use `position: "absolute"` to anchor to screen edges
+* - Anchor directly to edges: `left: 0`, `right: 0`, `top: 0`, `bottom: 0`
+* - Size using percentage-based calculations: `width: ${width * 0.14}px`
+* - Use Z_INDEX.HUD for consistent layering
+* - Example: Combat Left/Right HUDs, Top/Bottom bars
+*
+* **HUD Internal Content**:
+* - Use `position: "relative"` for natural document flow
+* - Use Flexbox for vertical/horizontal layouts: `display: "flex"`, `flexDirection`, `gap`
+* - Use CSS Grid for complex multi-dimensional layouts
+* - Avoid absolute positioning within HUDs (except for special cases)
+* - Example: Player stats, technique cards, control buttons
+*
+* **Special Cases (Overlays/Tooltips)**:
+* - Use `position: "absolute"` for floating elements that must overlay content
+* - Position relative to parent container
+* - Use Z_INDEX.HUD_OVERLAY or Z_INDEX.TOOLTIP
+* - Example: Combat messages, feedback overlays, tooltips
+*
+* **Responsive Design**:
+* - All components must support `isMobile` prop
+* - Use responsive calculations: `isMobile ? 18 : 14` for mobile scaling
+* - Apply `positionScale` multiplier for 4K displays (1.0-1.5)
+*
+* @category Layout Guidelines
+* @korean HUD위치전략
+*/
+/**
+* HUD width percentages for screen-level HUDs
+*
+* These constants define the standard widths for left and right HUD panels.
+* Values are decimals (0.14 = 14% of screen width).
+*
+* **Usage:**
+* ```tsx
+* const hudWidth = width * HUD_WIDTH_PERCENT.LEFT_DESKTOP;
+* ```
+*
+* @category Layout Constants
+* @korean HUD너비
+*/
+var HUD_WIDTH_PERCENT = {
+	LEFT_DESKTOP: .14,
+	LEFT_MOBILE: .18,
+	RIGHT_DESKTOP: .14,
+	RIGHT_MOBILE: .18,
+	TOP: 1,
+	BOTTOM: 1
+};
+/**
+* HUD height constants for top and bottom bars
+*
+* These constants define the standard heights for top and bottom HUD bars.
+* Values are in pixels and should be scaled with `positionScale` for 4K displays.
+*
+* **Usage:**
+* ```tsx
+* const hudHeight = HUD_HEIGHT.TOP_DESKTOP * positionScale;
+* ```
+*
+* @category Layout Constants
+* @korean HUD높이
+*/
+var HUD_HEIGHT = {
+	TOP_DESKTOP: 70,
+	TOP_MOBILE: 50,
+	BOTTOM_DESKTOP: 120,
+	BOTTOM_MOBILE: 100,
+	COMBAT_TOP_DESKTOP: 70,
+	COMBAT_TOP_MOBILE: 55,
+	COMBAT_BOTTOM_DESKTOP: 120,
+	COMBAT_BOTTOM_MOBILE: 100,
+	TRAINING_TOP_DESKTOP: 70,
+	TRAINING_TOP_MOBILE: 50,
+	TRAINING_BOTTOM_DESKTOP: 130,
+	TRAINING_BOTTOM_MOBILE: 110
+};
+//#endregion
+export { HUD_HEIGHT, HUD_WIDTH_PERCENT, Z_INDEX };
+
+//# sourceMappingURL=LayoutTypes.js.map

package/lib/types/LayoutTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LayoutTypes.js","names":[],"sources":["../../src/types/LayoutTypes.ts"],"sourcesContent":["/**\n * Layout-related type definitions for unified positioning system\n *\n * Provides type-safe interfaces for grid-based layout, responsive positioning,\n * and z-index hierarchy management across all screens.\n *\n * @module types/LayoutTypes\n * @category Type Definitions\n * @korean 레이아웃타입\n */\n\nimport { Position } from \"./common\";\n\n/**\n * Screen size breakpoints for responsive design\n *\n * @category Layout Types\n * @korean 화면크기\n */\nexport interface ScreenSize {\n  /** Screen width in pixels */\n  readonly width: number;\n  /** Screen height in pixels */\n  readonly height: number;\n  /** Whether the device is mobile (<768px) */\n  readonly isMobile: boolean;\n  /** Whether the device is tablet (768-1199px) */\n  readonly isTablet: boolean;\n  /** Whether the device is desktop (≥1200px) */\n  readonly isDesktop: boolean;\n  /** Whether the screen is in landscape orientation */\n  readonly isLandscape: boolean;\n}\n\n/**\n * Grid-based position configuration\n *\n * Uses 12-column grid system for consistent alignment.\n * \n * **Important:** Valid combinations must satisfy:\n * - column: 0-11 (starting column)\n * - span: 1-12 (number of columns to span)\n * - column + span ≤ 12 (must not exceed grid width)\n * \n * Invalid combinations (e.g., column: 10, span: 5) will throw runtime errors.\n * Use LayoutSystem.calculateGridPosition() which validates inputs.\n *\n * @category Layout Types\n * @korean 그리드위치\n * \n * @example Valid positions\n * ```typescript\n * { column: 0, span: 12 }  // Full width\n * { column: 2, span: 8 }   // Centered 8 columns\n * { column: 0, span: 6 }   // Left half\n * { column: 6, span: 6 }   // Right half\n * ```\n * \n * @example Invalid positions (will throw errors)\n * ```typescript\n * { column: 10, span: 5 }  // ERROR: 10 + 5 = 15 > 12\n * { column: -1, span: 6 }  // ERROR: column < 0\n * { column: 5, span: 0 }   // ERROR: span < 1\n * ```\n */\nexport interface GridPosition {\n  /** Grid column to start from (0-11) */\n  readonly column: number;\n  /** Number of columns to span (1-12) */\n  readonly span: number;\n  /** Row index for vertical positioning (multiplied by DEFAULT_ROW_HEIGHT=100px) */\n  readonly row?: number;\n  /** Gutter size in pixels (default: 20) */\n  readonly gutter?: number;\n}\n\n/**\n * Responsive position that adapts to screen size\n *\n * @category Layout Types\n * @korean 반응형위치\n */\nexport interface ResponsivePosition {\n  /** Base position for desktop (1200px+) */\n  readonly base: Position;\n  /** Position override for tablet (768-1199px) */\n  readonly tablet?: Position;\n  /** Position override for mobile (<768px) */\n  readonly mobile?: Position;\n  /** Whether to scale proportionally based on screen width */\n  readonly scaleProportionally?: boolean;\n}\n\n/**\n * Z-index hierarchy for layering UI elements\n *\n * Ensures consistent stacking order across all screens\n *\n * **Usage Guidelines:**\n * - NEVER use arbitrary z-index values (e.g., 999)\n * - Use these constants to maintain consistent layer ordering\n * - Layer order: Scene → HUD → Overlay → Modal → Pause Menu\n *\n * @category Layout Constants\n * @korean z인덱스계층\n */\nexport const Z_INDEX = {\n  // 3D Scene layers (0-30)\n  /** Background scenes and effects - 배경 */\n  BACKGROUND: 0,\n  /** Combat arena and training grounds - 경기장 */\n  ARENA: 10,\n  /** Player characters and enemies - 플레이어 */\n  PLAYERS: 20,\n  /** Visual effects and particles - 효과 */\n  EFFECTS: 30,\n\n  // HUD layers (40-99)\n  /** HUD background elements - HUD 배경 */\n  HUD_BACKGROUND: 40,\n  /** Main HUD elements (health bars, timers, stats) - 주 HUD */\n  HUD: 50,\n  /** TechniqueBar for combat techniques - 기술바 */\n  TECHNIQUE_BAR: 55,\n  /** HUD overlay elements (within HUD components) - HUD 오버레이 */\n  HUD_OVERLAY: 60,\n\n  // Top-level UI (100+)\n  /** Mobile touch controls - 모바일제어 */\n  MOBILE_CONTROLS: 100,\n  /** Modal dialogs and overlays - 모달 */\n  MODAL: 200,\n  /** Tooltips and hints - 툴팁 */\n  TOOLTIP: 300,\n  /** Pause menu - 일시정지 메뉴 */\n  PAUSE_MENU: 1000,\n  /** Loading screens - 로딩 */\n  LOADING: 2000,\n  /** Debug and performance overlays - 디버그 */\n  DEBUG: 9000,\n} as const;\n\n/**\n * Type for Z_INDEX values\n *\n * @category Layout Types\n */\nexport type ZIndexValue = (typeof Z_INDEX)[keyof typeof Z_INDEX];\n\n/**\n * Alignment options for positioning elements\n *\n * @category Layout Types\n * @korean 정렬\n */\nexport type HorizontalAlignment = \"left\" | \"center\" | \"right\";\nexport type VerticalAlignment = \"top\" | \"middle\" | \"bottom\";\n\n/**\n * Layout configuration for a component\n *\n * @category Layout Types\n * @korean 레이아웃설정\n */\nexport interface LayoutConfig {\n  /** Grid-based position (if using grid system) */\n  readonly grid?: GridPosition;\n  /** Responsive position (if not using grid) */\n  readonly position?: ResponsivePosition;\n  /** Z-index layer for stacking */\n  readonly zIndex?: ZIndexValue;\n  /** Horizontal alignment within container */\n  readonly horizontalAlign?: HorizontalAlignment;\n  /** Vertical alignment within container */\n  readonly verticalAlign?: VerticalAlignment;\n  /** Margin in pixels */\n  readonly margin?: number;\n  /** Padding in pixels */\n  readonly padding?: number;\n}\n\n/**\n * Safe area insets for mobile devices with notches\n *\n * @category Layout Types\n * @korean 안전영역\n */\nexport interface SafeAreaInsets {\n  /** Top inset (notch, status bar) */\n  readonly top: number;\n  /** Right inset (typically 0) */\n  readonly right: number;\n  /** Bottom inset (home indicator) */\n  readonly bottom: number;\n  /** Left inset (typically 0) */\n  readonly left: number;\n}\n\n/**\n * Container bounds for positioning child elements\n *\n * @category Layout Types\n * @korean 컨테이너경계\n */\nexport interface ContainerBounds {\n  /** X position in pixels */\n  readonly x: number;\n  /** Y position in pixels */\n  readonly y: number;\n  /** Width in pixels */\n  readonly width: number;\n  /** Height in pixels */\n  readonly height: number;\n  /** Scale factor (1.0 = no scaling) */\n  readonly scale?: number;\n}\n\n/**\n * HUD Positioning Strategy Documentation\n *\n * This section defines the standardized approach for positioning HUD elements\n * across all screens in the Black Trigram game.\n *\n * **Screen-Level HUDs (Left/Right/Top/Bottom)**:\n * - Use `position: \"absolute\"` to anchor to screen edges\n * - Anchor directly to edges: `left: 0`, `right: 0`, `top: 0`, `bottom: 0`\n * - Size using percentage-based calculations: `width: ${width * 0.14}px`\n * - Use Z_INDEX.HUD for consistent layering\n * - Example: Combat Left/Right HUDs, Top/Bottom bars\n *\n * **HUD Internal Content**:\n * - Use `position: \"relative\"` for natural document flow\n * - Use Flexbox for vertical/horizontal layouts: `display: \"flex\"`, `flexDirection`, `gap`\n * - Use CSS Grid for complex multi-dimensional layouts\n * - Avoid absolute positioning within HUDs (except for special cases)\n * - Example: Player stats, technique cards, control buttons\n *\n * **Special Cases (Overlays/Tooltips)**:\n * - Use `position: \"absolute\"` for floating elements that must overlay content\n * - Position relative to parent container\n * - Use Z_INDEX.HUD_OVERLAY or Z_INDEX.TOOLTIP\n * - Example: Combat messages, feedback overlays, tooltips\n *\n * **Responsive Design**:\n * - All components must support `isMobile` prop\n * - Use responsive calculations: `isMobile ? 18 : 14` for mobile scaling\n * - Apply `positionScale` multiplier for 4K displays (1.0-1.5)\n *\n * @category Layout Guidelines\n * @korean HUD위치전략\n */\n\n/**\n * HUD width percentages for screen-level HUDs\n *\n * These constants define the standard widths for left and right HUD panels.\n * Values are decimals (0.14 = 14% of screen width).\n *\n * **Usage:**\n * ```tsx\n * const hudWidth = width * HUD_WIDTH_PERCENT.LEFT_DESKTOP;\n * ```\n *\n * @category Layout Constants\n * @korean HUD너비\n */\nexport const HUD_WIDTH_PERCENT = {\n  /** Left HUD width on desktop (14% = leaves 72% for arena) */\n  LEFT_DESKTOP: 0.14,\n  /** Left HUD width on mobile (18% for touch targets) */\n  LEFT_MOBILE: 0.18,\n  /** Right HUD width on desktop (14% = leaves 72% for arena) */\n  RIGHT_DESKTOP: 0.14,\n  /** Right HUD width on mobile (18% for touch targets) */\n  RIGHT_MOBILE: 0.18,\n  /** Top HUD width (full screen width) */\n  TOP: 1.0,\n  /** Bottom HUD width (full screen width) */\n  BOTTOM: 1.0,\n} as const;\n\n/**\n * HUD height constants for top and bottom bars\n *\n * These constants define the standard heights for top and bottom HUD bars.\n * Values are in pixels and should be scaled with `positionScale` for 4K displays.\n *\n * **Usage:**\n * ```tsx\n * const hudHeight = HUD_HEIGHT.TOP_DESKTOP * positionScale;\n * ```\n *\n * @category Layout Constants\n * @korean HUD높이\n */\nexport const HUD_HEIGHT = {\n  /** Top bar height on desktop (slim for minimal obstruction) */\n  TOP_DESKTOP: 70,\n  /** Top bar height on mobile (extra slim) */\n  TOP_MOBILE: 50,\n  /** Bottom bar height on desktop (fits technique cards) */\n  BOTTOM_DESKTOP: 120,\n  /** Bottom bar height on mobile (compact) */\n  BOTTOM_MOBILE: 100,\n  /** Combat-specific top bar height */\n  COMBAT_TOP_DESKTOP: 70,\n  /** Combat-specific top bar height on mobile */\n  COMBAT_TOP_MOBILE: 55,\n  /** Combat-specific bottom bar height */\n  COMBAT_BOTTOM_DESKTOP: 120,\n  /** Combat-specific bottom bar height on mobile */\n  COMBAT_BOTTOM_MOBILE: 100,\n  /** Training-specific top bar height */\n  TRAINING_TOP_DESKTOP: 70,\n  /** Training-specific top bar height on mobile */\n  TRAINING_TOP_MOBILE: 50,\n  /** Training-specific bottom bar height */\n  TRAINING_BOTTOM_DESKTOP: 130,\n  /** Training-specific bottom bar height on mobile */\n  TRAINING_BOTTOM_MOBILE: 110,\n} as const;\n\n/**\n * HUD positioning configuration interface\n *\n * Defines the positioning strategy for a HUD component.\n *\n * @category Layout Types\n * @korean HUD위치설정\n */\nexport interface HUDPositionConfig {\n  /** Positioning strategy */\n  readonly strategy: \"absolute\" | \"relative\" | \"flex\" | \"grid\";\n  /** Anchor point for absolute positioning */\n  readonly anchor?: \"left\" | \"right\" | \"top\" | \"bottom\" | \"center\";\n  /** Offset from anchor point */\n  readonly offset?: { x?: number; y?: number };\n  /** Size configuration */\n  readonly size?: { width?: string | number; height?: string | number };\n  /** Z-index layer */\n  readonly zIndex?: ZIndexValue;\n}\n"],"mappings":";;;;;;;;;;;;;;AA0GA,IAAa,UAAU;CAGrB,YAAY;CAEZ,OAAO;CAEP,SAAS;CAET,SAAS;CAIT,gBAAgB;CAEhB,KAAK;CAEL,eAAe;CAEf,aAAa;CAIb,iBAAiB;CAEjB,OAAO;CAEP,SAAS;CAET,YAAY;CAEZ,SAAS;CAET,OAAO;CACR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8HD,IAAa,oBAAoB;CAE/B,cAAc;CAEd,aAAa;CAEb,eAAe;CAEf,cAAc;CAEd,KAAK;CAEL,QAAQ;CACT;;;;;;;;;;;;;;;AAgBD,IAAa,aAAa;CAExB,aAAa;CAEb,YAAY;CAEZ,gBAAgB;CAEhB,eAAe;CAEf,oBAAoB;CAEpB,mBAAmB;CAEnB,uBAAuB;CAEvB,sBAAsB;CAEtB,sBAAsB;CAEtB,qBAAqB;CAErB,yBAAyB;CAEzB,wBAAwB;CACzB"}