blacktrigram 0.7.2

package/lib/systems/LayoutSystem.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Unified Layout System for consistent component positioning
+ *
+ * Provides grid-based layout calculations, responsive positioning utilities,
+ * and alignment helpers for all screens in Black Trigram (흑괘).
+ *
+ * Features:
+ * - 12-column grid system for consistent alignment
+ * - Responsive positioning that adapts to screen size
+ * - Safe area handling for mobile devices with notches
+ * - Z-index hierarchy management
+ * - Korean-English UI alignment support
+ *
+ * Performance target: <1ms for layout calculations
+ *
+ * @module systems/LayoutSystem
+ * @category Systems
+ * @korean 레이아웃시스템
+ */
+import { Position } from "../types/common";
+import { ContainerBounds, HorizontalAlignment, ResponsivePosition, SafeAreaInsets, ScreenSize, VerticalAlignment } from "../types/LayoutTypes";
+/**
+ * Default row height for grid-based vertical positioning (in pixels)
+ * Used when row index is specified in grid configuration
+ * Can be overridden by providing explicit y position
+ *
+ * @public
+ */
+export declare const DEFAULT_ROW_HEIGHT = 100;
+/**
+ * LayoutSystem Class
+ *
+ * Provides unified layout calculations and positioning utilities
+ * for consistent component placement across all screens.
+ *
+ * @example
+ * ```typescript
+ * const layout = new LayoutSystem();
+ *
+ * // Calculate grid position
+ * const pos = layout.calculateGridPosition(2, 4, 1200);
+ * // Returns { x: 200, width: 380 } for column 2, span 4
+ *
+ * // Calculate responsive position
+ * const screenSize = { width: 375, height: 667, isMobile: true, isTablet: false, isDesktop: false, isLandscape: false };
+ * const responsivePos = layout.calculateResponsivePosition(
+ *   { base: { x: 100, y: 50 } },
+ *   screenSize
+ * );
+ * ```
+ */
+export declare class LayoutSystem {
+    private readonly gridColumns;
+    private readonly gutterSize;
+    private readonly safeArea;
+    /**
+     * Create a new LayoutSystem instance
+     *
+     * @param gridColumns - Number of grid columns (default: 12)
+     * @param gutterSize - Gutter size between columns in pixels (default: 20)
+     * @param safeArea - Safe area insets for mobile devices
+     */
+    constructor(gridColumns?: number, gutterSize?: number, safeArea?: SafeAreaInsets);
+    /**
+     * Calculate position and width for grid-based layout
+     *
+     * Uses 12-column grid system for consistent alignment.
+     * Accounts for gutters between columns.
+     *
+     * @param column - Starting column (0-11)
+     * @param span - Number of columns to span (1-12)
+     * @param containerWidth - Total container width in pixels
+     * @param customGutter - Custom gutter size (optional)
+     * @returns Position and width for the grid cell
+     * @throws Error if column or span are outside valid ranges
+     *
+     * @example
+     * ```typescript
+     * // Center element spanning 6 columns
+     * const pos = layout.calculateGridPosition(3, 6, 1200);
+     * // Returns { x: 300, width: 580 }
+     * ```
+     */
+    calculateGridPosition(column: number, span: number, containerWidth: number, customGutter?: number): {
+        x: number;
+        width: number;
+    };
+    /**
+     * Calculate responsive position based on screen size
+     *
+     * Scales position proportionally or uses specific overrides for tablet/mobile.
+     *
+     * @param config - Responsive position configuration
+     * @param screenSize - Current screen dimensions and device type
+     * @returns Calculated position for current screen size
+     *
+     * @example
+     * ```typescript
+     * const pos = layout.calculateResponsivePosition(
+     *   {
+     *     base: { x: 100, y: 50 },
+     *     mobile: { x: 10, y: 20 },
+     *     scaleProportionally: true
+     *   },
+     *   screenSize
+     * );
+     * ```
+     */
+    calculateResponsivePosition(config: ResponsivePosition, screenSize: ScreenSize): Position;
+    /**
+     * Calculate safe position accounting for device notches and home indicators
+     *
+     * Ensures UI elements don't overlap with system UI on mobile devices.
+     *
+     * @param position - Base position
+     * @param edge - Which edge to apply safe area ('top' | 'bottom' | 'left' | 'right')
+     * @returns Position adjusted for safe area
+     *
+     * @example
+     * ```typescript
+     * // Adjust top position for status bar/notch
+     * const safePos = layout.calculateSafePosition({ x: 0, y: 10 }, 'top');
+     * // Returns { x: 0, y: 54 } (10 + 44 for notch)
+     * ```
+     */
+    calculateSafePosition(position: Position, edge: "top" | "bottom" | "left" | "right"): Position;
+    /**
+     * Align element horizontally within container
+     *
+     * @param elementWidth - Width of element to align
+     * @param containerWidth - Width of container
+     * @param alignment - Alignment type ('left' | 'center' | 'right')
+     * @param margin - Optional margin from edges
+     * @returns X position for alignment
+     *
+     * @example
+     * ```typescript
+     * const x = layout.alignHorizontal(200, 800, 'center', 10);
+     * // Returns 300 (centered with margins)
+     * ```
+     */
+    alignHorizontal(elementWidth: number, containerWidth: number, alignment: HorizontalAlignment, margin?: number): number;
+    /**
+     * Align element vertically within container
+     *
+     * @param elementHeight - Height of element to align
+     * @param containerHeight - Height of container
+     * @param alignment - Alignment type ('top' | 'middle' | 'bottom')
+     * @param margin - Optional margin from edges
+     * @returns Y position for alignment
+     *
+     * @example
+     * ```typescript
+     * const y = layout.alignVertical(100, 600, 'middle', 10);
+     * // Returns 250 (vertically centered)
+     * ```
+     */
+    alignVertical(elementHeight: number, containerHeight: number, alignment: VerticalAlignment, margin?: number): number;
+    /**
+     * Create screen size information from dimensions
+     *
+     * Determines device type and orientation based on screen dimensions.
+     *
+     * @param width - Screen width in pixels
+     * @param height - Screen height in pixels
+     * @returns ScreenSize object with device type flags
+     *
+     * @example
+     * ```typescript
+     * const screenSize = layout.getScreenSize(375, 667);
+     * // Returns { width: 375, height: 667, isMobile: true, ... }
+     * ```
+     */
+    getScreenSize(width: number, height: number): ScreenSize;
+    /**
+     * Calculate container bounds for arena or game area
+     *
+     * Accounts for HUD, controls, and safe areas to determine usable space.
+     *
+     * @param screenWidth - Total screen width
+     * @param screenHeight - Total screen height
+     * @param hudHeight - Height of top HUD
+     * @param controlsHeight - Height of bottom controls
+     * @param padding - Padding around content
+     * @returns Container bounds for game content
+     *
+     * @example
+     * ```typescript
+     * const bounds = layout.calculateContainerBounds(1200, 800, 120, 0, 10);
+     * // Returns bounds for desktop game area
+     * ```
+     */
+    calculateContainerBounds(screenWidth: number, screenHeight: number, hudHeight?: number, controlsHeight?: number, padding?: number): ContainerBounds;
+}
+/**
+ * Default singleton instance for convenience
+ *
+ * @example
+ * ```typescript
+ * import { defaultLayoutSystem } from './systems/LayoutSystem';
+ *
+ * const pos = defaultLayoutSystem.alignHorizontal(200, 800, 'center');
+ * ```
+ */
+export declare const defaultLayoutSystem: LayoutSystem;
+/**
+ * Helper function to create grid-based position
+ *
+ * Convenience wrapper around LayoutSystem.calculateGridPosition
+ *
+ * @param column - Starting column (0-11)
+ * @param span - Number of columns to span (1-12)
+ * @param containerWidth - Total container width
+ * @returns Position and width for grid cell
+ */
+export declare function calculateGridPosition(column: number, span: number, containerWidth: number): {
+    x: number;
+    width: number;
+};
+/**
+ * Helper function to align element horizontally
+ *
+ * @param elementWidth - Width of element
+ * @param containerWidth - Width of container
+ * @param alignment - Alignment type
+ * @param margin - Optional margin
+ * @returns X position
+ */
+export declare function alignHorizontal(elementWidth: number, containerWidth: number, alignment?: HorizontalAlignment, margin?: number): number;
+/**
+ * Helper function to align element vertically
+ *
+ * @param elementHeight - Height of element
+ * @param containerHeight - Height of container
+ * @param alignment - Alignment type
+ * @param margin - Optional margin
+ * @returns Y position
+ */
+export declare function alignVertical(elementHeight: number, containerHeight: number, alignment?: VerticalAlignment, margin?: number): number;
+/**
+ * Helper function to center element in container
+ *
+ * @param elementWidth - Width of element
+ * @param elementHeight - Height of element
+ * @param containerWidth - Width of container
+ * @param containerHeight - Height of container
+ * @returns Centered position
+ */
+export declare function centerElement(elementWidth: number, elementHeight: number, containerWidth: number, containerHeight: number): Position;
+//# sourceMappingURL=LayoutSystem.d.ts.map

package/lib/systems/LayoutSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LayoutSystem.d.ts","sourceRoot":"","sources":["../../src/systems/LayoutSystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAgB9B;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAatC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAE1C;;;;;;OAMG;gBAED,WAAW,GAAE,MAA6B,EAC1C,UAAU,GAAE,MAA4B,EACxC,QAAQ,GAAE,cAAkC;IAO9C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,qBAAqB,CACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,YAAY,CAAC,EAAE,MAAM,GACpB;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAgC/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,2BAA2B,CACzB,MAAM,EAAE,kBAAkB,EAC1B,UAAU,EAAE,UAAU,GACrB,QAAQ;IAsBX;;;;;;;;;;;;;;;OAeG;IACH,qBAAqB,CACnB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GACxC,QAAQ;IAcX;;;;;;;;;;;;;;OAcG;IACH,eAAe,CACb,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,mBAAmB,EAC9B,MAAM,GAAE,MAAU,GACjB,MAAM;IAWT;;;;;;;;;;;;;;OAcG;IACH,aAAa,CACX,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,iBAAiB,EAC5B,MAAM,GAAE,MAAU,GACjB,MAAM;IAWT;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU;IAgBxD;;;;;;;;;;;;;;;;;OAiBG;IACH,wBAAwB,CACtB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAU,EACrB,cAAc,GAAE,MAAU,EAC1B,OAAO,GAAE,MAAW,GACnB,eAAe;CAsBnB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,cAAqB,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACrB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAE9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,GAAE,mBAA8B,EACzC,MAAM,GAAE,MAAU,GACjB,MAAM,CAER;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,SAAS,GAAE,iBAA4B,EACvC,MAAM,GAAE,MAAU,GACjB,MAAM,CAER;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,GACtB,QAAQ,CAKV"}

package/lib/systems/LayoutSystem.js

@@ -0,0 +1,337 @@
+//#region src/systems/LayoutSystem.ts
+/**
+* Default grid configuration
+*/
+var DEFAULT_GRID_COLUMNS = 12;
+var DEFAULT_GUTTER_SIZE = 20;
+var BASE_DESKTOP_WIDTH = 1200;
+/**
+* Base width for mobile arena scaling calculations (in pixels)
+* This represents the standard desktop arena width (80% of 1200px)
+* Used to calculate scale factor for mobile devices
+*/
+var MOBILE_ARENA_BASE_WIDTH = 960;
+/**
+* Default row height for grid-based vertical positioning (in pixels)
+* Used when row index is specified in grid configuration
+* Can be overridden by providing explicit y position
+* 
+* @public
+*/
+var DEFAULT_ROW_HEIGHT = 100;
+/**
+* Default safe area insets for mobile devices
+* Based on typical iOS device dimensions (iPhone 14 Pro as reference)
+*/
+var DEFAULT_SAFE_AREA = {
+	top: 44,
+	right: 0,
+	bottom: 34,
+	left: 0
+};
+/**
+* LayoutSystem Class
+*
+* Provides unified layout calculations and positioning utilities
+* for consistent component placement across all screens.
+*
+* @example
+* ```typescript
+* const layout = new LayoutSystem();
+*
+* // Calculate grid position
+* const pos = layout.calculateGridPosition(2, 4, 1200);
+* // Returns { x: 200, width: 380 } for column 2, span 4
+*
+* // Calculate responsive position
+* const screenSize = { width: 375, height: 667, isMobile: true, isTablet: false, isDesktop: false, isLandscape: false };
+* const responsivePos = layout.calculateResponsivePosition(
+*   { base: { x: 100, y: 50 } },
+*   screenSize
+* );
+* ```
+*/
+var LayoutSystem = class {
+	gridColumns;
+	gutterSize;
+	safeArea;
+	/**
+	* Create a new LayoutSystem instance
+	*
+	* @param gridColumns - Number of grid columns (default: 12)
+	* @param gutterSize - Gutter size between columns in pixels (default: 20)
+	* @param safeArea - Safe area insets for mobile devices
+	*/
+	constructor(gridColumns = DEFAULT_GRID_COLUMNS, gutterSize = DEFAULT_GUTTER_SIZE, safeArea = DEFAULT_SAFE_AREA) {
+		this.gridColumns = gridColumns;
+		this.gutterSize = gutterSize;
+		this.safeArea = safeArea;
+	}
+	/**
+	* Calculate position and width for grid-based layout
+	*
+	* Uses 12-column grid system for consistent alignment.
+	* Accounts for gutters between columns.
+	*
+	* @param column - Starting column (0-11)
+	* @param span - Number of columns to span (1-12)
+	* @param containerWidth - Total container width in pixels
+	* @param customGutter - Custom gutter size (optional)
+	* @returns Position and width for the grid cell
+	* @throws Error if column or span are outside valid ranges
+	*
+	* @example
+	* ```typescript
+	* // Center element spanning 6 columns
+	* const pos = layout.calculateGridPosition(3, 6, 1200);
+	* // Returns { x: 300, width: 580 }
+	* ```
+	*/
+	calculateGridPosition(column, span, containerWidth, customGutter) {
+		if (column < 0 || column >= this.gridColumns) throw new Error(`Invalid column: ${column}. Column must be between 0 and ${this.gridColumns - 1}`);
+		if (span < 1 || span > this.gridColumns) throw new Error(`Invalid span: ${span}. Span must be between 1 and ${this.gridColumns}`);
+		if (column + span > this.gridColumns) throw new Error(`Invalid grid position: column ${column} + span ${span} = ${column + span} exceeds ${this.gridColumns} columns`);
+		const gutter = customGutter ?? this.gutterSize;
+		const columnWidth = containerWidth / this.gridColumns;
+		return {
+			x: column * columnWidth,
+			width: span * columnWidth - gutter
+		};
+	}
+	/**
+	* Calculate responsive position based on screen size
+	*
+	* Scales position proportionally or uses specific overrides for tablet/mobile.
+	*
+	* @param config - Responsive position configuration
+	* @param screenSize - Current screen dimensions and device type
+	* @returns Calculated position for current screen size
+	*
+	* @example
+	* ```typescript
+	* const pos = layout.calculateResponsivePosition(
+	*   {
+	*     base: { x: 100, y: 50 },
+	*     mobile: { x: 10, y: 20 },
+	*     scaleProportionally: true
+	*   },
+	*   screenSize
+	* );
+	* ```
+	*/
+	calculateResponsivePosition(config, screenSize) {
+		if (screenSize.isMobile && config.mobile) return config.mobile;
+		if (screenSize.isTablet && config.tablet) return config.tablet;
+		if (screenSize.isDesktop || !config.scaleProportionally) return config.base;
+		const scale = screenSize.width / BASE_DESKTOP_WIDTH;
+		return {
+			x: config.base.x * scale,
+			y: config.base.y * scale
+		};
+	}
+	/**
+	* Calculate safe position accounting for device notches and home indicators
+	*
+	* Ensures UI elements don't overlap with system UI on mobile devices.
+	*
+	* @param position - Base position
+	* @param edge - Which edge to apply safe area ('top' | 'bottom' | 'left' | 'right')
+	* @returns Position adjusted for safe area
+	*
+	* @example
+	* ```typescript
+	* // Adjust top position for status bar/notch
+	* const safePos = layout.calculateSafePosition({ x: 0, y: 10 }, 'top');
+	* // Returns { x: 0, y: 54 } (10 + 44 for notch)
+	* ```
+	*/
+	calculateSafePosition(position, edge) {
+		const inset = this.safeArea[edge];
+		switch (edge) {
+			case "top": return {
+				...position,
+				y: position.y + inset
+			};
+			case "bottom": return {
+				...position,
+				y: position.y - inset
+			};
+			case "left": return {
+				...position,
+				x: position.x + inset
+			};
+			case "right": return {
+				...position,
+				x: position.x - inset
+			};
+		}
+	}
+	/**
+	* Align element horizontally within container
+	*
+	* @param elementWidth - Width of element to align
+	* @param containerWidth - Width of container
+	* @param alignment - Alignment type ('left' | 'center' | 'right')
+	* @param margin - Optional margin from edges
+	* @returns X position for alignment
+	*
+	* @example
+	* ```typescript
+	* const x = layout.alignHorizontal(200, 800, 'center', 10);
+	* // Returns 300 (centered with margins)
+	* ```
+	*/
+	alignHorizontal(elementWidth, containerWidth, alignment, margin = 0) {
+		switch (alignment) {
+			case "left": return margin;
+			case "center": return (containerWidth - elementWidth) / 2;
+			case "right": return containerWidth - elementWidth - margin;
+		}
+	}
+	/**
+	* Align element vertically within container
+	*
+	* @param elementHeight - Height of element to align
+	* @param containerHeight - Height of container
+	* @param alignment - Alignment type ('top' | 'middle' | 'bottom')
+	* @param margin - Optional margin from edges
+	* @returns Y position for alignment
+	*
+	* @example
+	* ```typescript
+	* const y = layout.alignVertical(100, 600, 'middle', 10);
+	* // Returns 250 (vertically centered)
+	* ```
+	*/
+	alignVertical(elementHeight, containerHeight, alignment, margin = 0) {
+		switch (alignment) {
+			case "top": return margin;
+			case "middle": return (containerHeight - elementHeight) / 2;
+			case "bottom": return containerHeight - elementHeight - margin;
+		}
+	}
+	/**
+	* Create screen size information from dimensions
+	*
+	* Determines device type and orientation based on screen dimensions.
+	*
+	* @param width - Screen width in pixels
+	* @param height - Screen height in pixels
+	* @returns ScreenSize object with device type flags
+	*
+	* @example
+	* ```typescript
+	* const screenSize = layout.getScreenSize(375, 667);
+	* // Returns { width: 375, height: 667, isMobile: true, ... }
+	* ```
+	*/
+	getScreenSize(width, height) {
+		return {
+			width,
+			height,
+			isMobile: width < 768,
+			isTablet: width >= 768 && width < 1200,
+			isDesktop: width >= 1200,
+			isLandscape: width > height
+		};
+	}
+	/**
+	* Calculate container bounds for arena or game area
+	*
+	* Accounts for HUD, controls, and safe areas to determine usable space.
+	*
+	* @param screenWidth - Total screen width
+	* @param screenHeight - Total screen height
+	* @param hudHeight - Height of top HUD
+	* @param controlsHeight - Height of bottom controls
+	* @param padding - Padding around content
+	* @returns Container bounds for game content
+	*
+	* @example
+	* ```typescript
+	* const bounds = layout.calculateContainerBounds(1200, 800, 120, 0, 10);
+	* // Returns bounds for desktop game area
+	* ```
+	*/
+	calculateContainerBounds(screenWidth, screenHeight, hudHeight = 0, controlsHeight = 0, padding = 10) {
+		const screenSize = this.getScreenSize(screenWidth, screenHeight);
+		const topOffset = hudHeight + padding + (screenSize.isMobile ? this.safeArea.top : 0);
+		const bottomOffset = controlsHeight + padding + (screenSize.isMobile ? this.safeArea.bottom : 0);
+		const availableHeight = screenHeight - topOffset - bottomOffset;
+		const availableWidth = screenWidth - padding * 2;
+		return {
+			x: padding,
+			y: topOffset,
+			width: availableWidth,
+			height: availableHeight,
+			scale: screenSize.isMobile ? Math.min(availableWidth / MOBILE_ARENA_BASE_WIDTH, 1) : 1
+		};
+	}
+};
+/**
+* Default singleton instance for convenience
+*
+* @example
+* ```typescript
+* import { defaultLayoutSystem } from './systems/LayoutSystem';
+*
+* const pos = defaultLayoutSystem.alignHorizontal(200, 800, 'center');
+* ```
+*/
+var defaultLayoutSystem = new LayoutSystem();
+/**
+* Helper function to create grid-based position
+*
+* Convenience wrapper around LayoutSystem.calculateGridPosition
+*
+* @param column - Starting column (0-11)
+* @param span - Number of columns to span (1-12)
+* @param containerWidth - Total container width
+* @returns Position and width for grid cell
+*/
+function calculateGridPosition(column, span, containerWidth) {
+	return defaultLayoutSystem.calculateGridPosition(column, span, containerWidth);
+}
+/**
+* Helper function to align element horizontally
+*
+* @param elementWidth - Width of element
+* @param containerWidth - Width of container
+* @param alignment - Alignment type
+* @param margin - Optional margin
+* @returns X position
+*/
+function alignHorizontal(elementWidth, containerWidth, alignment = "center", margin = 0) {
+	return defaultLayoutSystem.alignHorizontal(elementWidth, containerWidth, alignment, margin);
+}
+/**
+* Helper function to align element vertically
+*
+* @param elementHeight - Height of element
+* @param containerHeight - Height of container
+* @param alignment - Alignment type
+* @param margin - Optional margin
+* @returns Y position
+*/
+function alignVertical(elementHeight, containerHeight, alignment = "middle", margin = 0) {
+	return defaultLayoutSystem.alignVertical(elementHeight, containerHeight, alignment, margin);
+}
+/**
+* Helper function to center element in container
+*
+* @param elementWidth - Width of element
+* @param elementHeight - Height of element
+* @param containerWidth - Width of container
+* @param containerHeight - Height of container
+* @returns Centered position
+*/
+function centerElement(elementWidth, elementHeight, containerWidth, containerHeight) {
+	return {
+		x: alignHorizontal(elementWidth, containerWidth, "center"),
+		y: alignVertical(elementHeight, containerHeight, "middle")
+	};
+}
+//#endregion
+export { DEFAULT_ROW_HEIGHT, LayoutSystem, alignHorizontal, alignVertical, calculateGridPosition, centerElement, defaultLayoutSystem };
+
+//# sourceMappingURL=LayoutSystem.js.map

package/lib/systems/LayoutSystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LayoutSystem.js","names":[],"sources":["../../src/systems/LayoutSystem.ts"],"sourcesContent":["/**\n * Unified Layout System for consistent component positioning\n *\n * Provides grid-based layout calculations, responsive positioning utilities,\n * and alignment helpers for all screens in Black Trigram (흑괘).\n *\n * Features:\n * - 12-column grid system for consistent alignment\n * - Responsive positioning that adapts to screen size\n * - Safe area handling for mobile devices with notches\n * - Z-index hierarchy management\n * - Korean-English UI alignment support\n *\n * Performance target: <1ms for layout calculations\n *\n * @module systems/LayoutSystem\n * @category Systems\n * @korean 레이아웃시스템\n */\n\nimport { Position } from \"../types/common\";\nimport {\n  ContainerBounds,\n  HorizontalAlignment,\n  ResponsivePosition,\n  SafeAreaInsets,\n  ScreenSize,\n  VerticalAlignment,\n} from \"../types/LayoutTypes\";\n\n/**\n * Default grid configuration\n */\nconst DEFAULT_GRID_COLUMNS = 12;\nconst DEFAULT_GUTTER_SIZE = 20;\nconst BASE_DESKTOP_WIDTH = 1200;\n\n/**\n * Base width for mobile arena scaling calculations (in pixels)\n * This represents the standard desktop arena width (80% of 1200px)\n * Used to calculate scale factor for mobile devices\n */\nconst MOBILE_ARENA_BASE_WIDTH = 960;\n\n/**\n * Default row height for grid-based vertical positioning (in pixels)\n * Used when row index is specified in grid configuration\n * Can be overridden by providing explicit y position\n * \n * @public\n */\nexport const DEFAULT_ROW_HEIGHT = 100;\n\n/**\n * Default safe area insets for mobile devices\n * Based on typical iOS device dimensions (iPhone 14 Pro as reference)\n */\nconst DEFAULT_SAFE_AREA: SafeAreaInsets = {\n  top: 44, // Status bar + notch\n  right: 0,\n  bottom: 34, // Home indicator\n  left: 0,\n};\n\n/**\n * LayoutSystem Class\n *\n * Provides unified layout calculations and positioning utilities\n * for consistent component placement across all screens.\n *\n * @example\n * ```typescript\n * const layout = new LayoutSystem();\n *\n * // Calculate grid position\n * const pos = layout.calculateGridPosition(2, 4, 1200);\n * // Returns { x: 200, width: 380 } for column 2, span 4\n *\n * // Calculate responsive position\n * const screenSize = { width: 375, height: 667, isMobile: true, isTablet: false, isDesktop: false, isLandscape: false };\n * const responsivePos = layout.calculateResponsivePosition(\n *   { base: { x: 100, y: 50 } },\n *   screenSize\n * );\n * ```\n */\nexport class LayoutSystem {\n  private readonly gridColumns: number;\n  private readonly gutterSize: number;\n  private readonly safeArea: SafeAreaInsets;\n\n  /**\n   * Create a new LayoutSystem instance\n   *\n   * @param gridColumns - Number of grid columns (default: 12)\n   * @param gutterSize - Gutter size between columns in pixels (default: 20)\n   * @param safeArea - Safe area insets for mobile devices\n   */\n  constructor(\n    gridColumns: number = DEFAULT_GRID_COLUMNS,\n    gutterSize: number = DEFAULT_GUTTER_SIZE,\n    safeArea: SafeAreaInsets = DEFAULT_SAFE_AREA\n  ) {\n    this.gridColumns = gridColumns;\n    this.gutterSize = gutterSize;\n    this.safeArea = safeArea;\n  }\n\n  /**\n   * Calculate position and width for grid-based layout\n   *\n   * Uses 12-column grid system for consistent alignment.\n   * Accounts for gutters between columns.\n   *\n   * @param column - Starting column (0-11)\n   * @param span - Number of columns to span (1-12)\n   * @param containerWidth - Total container width in pixels\n   * @param customGutter - Custom gutter size (optional)\n   * @returns Position and width for the grid cell\n   * @throws Error if column or span are outside valid ranges\n   *\n   * @example\n   * ```typescript\n   * // Center element spanning 6 columns\n   * const pos = layout.calculateGridPosition(3, 6, 1200);\n   * // Returns { x: 300, width: 580 }\n   * ```\n   */\n  calculateGridPosition(\n    column: number,\n    span: number,\n    containerWidth: number,\n    customGutter?: number\n  ): { x: number; width: number } {\n    // Validate inputs\n    if (column < 0 || column >= this.gridColumns) {\n      throw new Error(\n        `Invalid column: ${column}. Column must be between 0 and ${this.gridColumns - 1}`\n      );\n    }\n    if (span < 1 || span > this.gridColumns) {\n      throw new Error(\n        `Invalid span: ${span}. Span must be between 1 and ${this.gridColumns}`\n      );\n    }\n    if (column + span > this.gridColumns) {\n      throw new Error(\n        `Invalid grid position: column ${column} + span ${span} = ${column + span} exceeds ${this.gridColumns} columns`\n      );\n    }\n\n    const gutter = customGutter ?? this.gutterSize;\n    const columnWidth = containerWidth / this.gridColumns;\n\n    // Calculate x position\n    const x = column * columnWidth;\n\n    // Calculate width accounting for gutters\n    // Width = (span * columnWidth) - gutter\n    // The gutter is subtracted to create spacing between elements\n    const width = span * columnWidth - gutter;\n\n    return { x, width };\n  }\n\n  /**\n   * Calculate responsive position based on screen size\n   *\n   * Scales position proportionally or uses specific overrides for tablet/mobile.\n   *\n   * @param config - Responsive position configuration\n   * @param screenSize - Current screen dimensions and device type\n   * @returns Calculated position for current screen size\n   *\n   * @example\n   * ```typescript\n   * const pos = layout.calculateResponsivePosition(\n   *   {\n   *     base: { x: 100, y: 50 },\n   *     mobile: { x: 10, y: 20 },\n   *     scaleProportionally: true\n   *   },\n   *   screenSize\n   * );\n   * ```\n   */\n  calculateResponsivePosition(\n    config: ResponsivePosition,\n    screenSize: ScreenSize\n  ): Position {\n    // Use specific override if available\n    if (screenSize.isMobile && config.mobile) {\n      return config.mobile;\n    }\n    if (screenSize.isTablet && config.tablet) {\n      return config.tablet;\n    }\n\n    // Use base position for desktop\n    if (screenSize.isDesktop || !config.scaleProportionally) {\n      return config.base;\n    }\n\n    // Scale proportionally for mobile/tablet if no override\n    const scale = screenSize.width / BASE_DESKTOP_WIDTH;\n    return {\n      x: config.base.x * scale,\n      y: config.base.y * scale,\n    };\n  }\n\n  /**\n   * Calculate safe position accounting for device notches and home indicators\n   *\n   * Ensures UI elements don't overlap with system UI on mobile devices.\n   *\n   * @param position - Base position\n   * @param edge - Which edge to apply safe area ('top' | 'bottom' | 'left' | 'right')\n   * @returns Position adjusted for safe area\n   *\n   * @example\n   * ```typescript\n   * // Adjust top position for status bar/notch\n   * const safePos = layout.calculateSafePosition({ x: 0, y: 10 }, 'top');\n   * // Returns { x: 0, y: 54 } (10 + 44 for notch)\n   * ```\n   */\n  calculateSafePosition(\n    position: Position,\n    edge: \"top\" | \"bottom\" | \"left\" | \"right\"\n  ): Position {\n    const inset = this.safeArea[edge];\n    switch (edge) {\n      case \"top\":\n        return { ...position, y: position.y + inset };\n      case \"bottom\":\n        return { ...position, y: position.y - inset };\n      case \"left\":\n        return { ...position, x: position.x + inset };\n      case \"right\":\n        return { ...position, x: position.x - inset };\n    }\n  }\n\n  /**\n   * Align element horizontally within container\n   *\n   * @param elementWidth - Width of element to align\n   * @param containerWidth - Width of container\n   * @param alignment - Alignment type ('left' | 'center' | 'right')\n   * @param margin - Optional margin from edges\n   * @returns X position for alignment\n   *\n   * @example\n   * ```typescript\n   * const x = layout.alignHorizontal(200, 800, 'center', 10);\n   * // Returns 300 (centered with margins)\n   * ```\n   */\n  alignHorizontal(\n    elementWidth: number,\n    containerWidth: number,\n    alignment: HorizontalAlignment,\n    margin: number = 0\n  ): number {\n    switch (alignment) {\n      case \"left\":\n        return margin;\n      case \"center\":\n        return (containerWidth - elementWidth) / 2;\n      case \"right\":\n        return containerWidth - elementWidth - margin;\n    }\n  }\n\n  /**\n   * Align element vertically within container\n   *\n   * @param elementHeight - Height of element to align\n   * @param containerHeight - Height of container\n   * @param alignment - Alignment type ('top' | 'middle' | 'bottom')\n   * @param margin - Optional margin from edges\n   * @returns Y position for alignment\n   *\n   * @example\n   * ```typescript\n   * const y = layout.alignVertical(100, 600, 'middle', 10);\n   * // Returns 250 (vertically centered)\n   * ```\n   */\n  alignVertical(\n    elementHeight: number,\n    containerHeight: number,\n    alignment: VerticalAlignment,\n    margin: number = 0\n  ): number {\n    switch (alignment) {\n      case \"top\":\n        return margin;\n      case \"middle\":\n        return (containerHeight - elementHeight) / 2;\n      case \"bottom\":\n        return containerHeight - elementHeight - margin;\n    }\n  }\n\n  /**\n   * Create screen size information from dimensions\n   *\n   * Determines device type and orientation based on screen dimensions.\n   *\n   * @param width - Screen width in pixels\n   * @param height - Screen height in pixels\n   * @returns ScreenSize object with device type flags\n   *\n   * @example\n   * ```typescript\n   * const screenSize = layout.getScreenSize(375, 667);\n   * // Returns { width: 375, height: 667, isMobile: true, ... }\n   * ```\n   */\n  getScreenSize(width: number, height: number): ScreenSize {\n    const isMobile = width < 768;\n    const isTablet = width >= 768 && width < 1200;\n    const isDesktop = width >= 1200;\n    const isLandscape = width > height;\n\n    return {\n      width,\n      height,\n      isMobile,\n      isTablet,\n      isDesktop,\n      isLandscape,\n    };\n  }\n\n  /**\n   * Calculate container bounds for arena or game area\n   *\n   * Accounts for HUD, controls, and safe areas to determine usable space.\n   *\n   * @param screenWidth - Total screen width\n   * @param screenHeight - Total screen height\n   * @param hudHeight - Height of top HUD\n   * @param controlsHeight - Height of bottom controls\n   * @param padding - Padding around content\n   * @returns Container bounds for game content\n   *\n   * @example\n   * ```typescript\n   * const bounds = layout.calculateContainerBounds(1200, 800, 120, 0, 10);\n   * // Returns bounds for desktop game area\n   * ```\n   */\n  calculateContainerBounds(\n    screenWidth: number,\n    screenHeight: number,\n    hudHeight: number = 0,\n    controlsHeight: number = 0,\n    padding: number = 10\n  ): ContainerBounds {\n    const screenSize = this.getScreenSize(screenWidth, screenHeight);\n\n    // Calculate available height\n    const topOffset = hudHeight + padding + (screenSize.isMobile ? this.safeArea.top : 0);\n    const bottomOffset = controlsHeight + padding + (screenSize.isMobile ? this.safeArea.bottom : 0);\n    const availableHeight = screenHeight - topOffset - bottomOffset;\n\n    // Calculate width accounting for padding\n    const availableWidth = screenWidth - padding * 2;\n\n    // Calculate scale for mobile (arena should be smaller on mobile)\n    const scale = screenSize.isMobile ? Math.min(availableWidth / MOBILE_ARENA_BASE_WIDTH, 1.0) : 1.0;\n\n    return {\n      x: padding,\n      y: topOffset,\n      width: availableWidth,\n      height: availableHeight,\n      scale,\n    };\n  }\n}\n\n/**\n * Default singleton instance for convenience\n *\n * @example\n * ```typescript\n * import { defaultLayoutSystem } from './systems/LayoutSystem';\n *\n * const pos = defaultLayoutSystem.alignHorizontal(200, 800, 'center');\n * ```\n */\nexport const defaultLayoutSystem = new LayoutSystem();\n\n/**\n * Helper function to create grid-based position\n *\n * Convenience wrapper around LayoutSystem.calculateGridPosition\n *\n * @param column - Starting column (0-11)\n * @param span - Number of columns to span (1-12)\n * @param containerWidth - Total container width\n * @returns Position and width for grid cell\n */\nexport function calculateGridPosition(\n  column: number,\n  span: number,\n  containerWidth: number\n): { x: number; width: number } {\n  return defaultLayoutSystem.calculateGridPosition(column, span, containerWidth);\n}\n\n/**\n * Helper function to align element horizontally\n *\n * @param elementWidth - Width of element\n * @param containerWidth - Width of container\n * @param alignment - Alignment type\n * @param margin - Optional margin\n * @returns X position\n */\nexport function alignHorizontal(\n  elementWidth: number,\n  containerWidth: number,\n  alignment: HorizontalAlignment = \"center\",\n  margin: number = 0\n): number {\n  return defaultLayoutSystem.alignHorizontal(elementWidth, containerWidth, alignment, margin);\n}\n\n/**\n * Helper function to align element vertically\n *\n * @param elementHeight - Height of element\n * @param containerHeight - Height of container\n * @param alignment - Alignment type\n * @param margin - Optional margin\n * @returns Y position\n */\nexport function alignVertical(\n  elementHeight: number,\n  containerHeight: number,\n  alignment: VerticalAlignment = \"middle\",\n  margin: number = 0\n): number {\n  return defaultLayoutSystem.alignVertical(elementHeight, containerHeight, alignment, margin);\n}\n\n/**\n * Helper function to center element in container\n *\n * @param elementWidth - Width of element\n * @param elementHeight - Height of element\n * @param containerWidth - Width of container\n * @param containerHeight - Height of container\n * @returns Centered position\n */\nexport function centerElement(\n  elementWidth: number,\n  elementHeight: number,\n  containerWidth: number,\n  containerHeight: number\n): Position {\n  return {\n    x: alignHorizontal(elementWidth, containerWidth, \"center\"),\n    y: alignVertical(elementHeight, containerHeight, \"middle\"),\n  };\n}\n"],"mappings":"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"}