blacktrigram 0.7.2

package/lib/utils/EventManager.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Statistics about event listeners managed by EventManager
+ * EventManager가 관리하는 이벤트 리스너에 대한 통계
+ */
+export interface EventManagerStats {
+    /** Total number of active listeners / 활성 리스너 총 개수 */
+    readonly totalListeners: number;
+    /** Number of unique event types / 고유한 이벤트 유형 수 */
+    readonly uniqueEventTypes: number;
+    /** Number of listeners using passive mode / 패시브 모드를 사용하는 리스너 수 */
+    readonly passiveListeners: number;
+    /** Event types and their listener counts / 이벤트 유형 및 해당 리스너 수 */
+    readonly eventTypeCounts: Record<string, number>;
+}
+/**
+ * EventManager class for centralized event listener management
+ * 중앙 집중식 이벤트 리스너 관리를 위한 EventManager 클래스
+ */
+export declare class EventManager {
+    /**
+     * Map of event keys to their tracked listeners
+     * Format: "ElementType-eventName" -> TrackedListener[]
+     * 이벤트 키를 추적된 리스너에 매핑
+     * 형식: "ElementType-eventName" -> TrackedListener[]
+     */
+    private listeners;
+    /**
+     * Add an event listener with automatic cleanup tracking
+     * 자동 정리 추적 기능이 있는 이벤트 리스너 추가
+     *
+     * @param element - The element to attach the listener to / 리스너를 연결할 요소
+     * @param event - The event name (e.g., "click", "keydown") / 이벤트 이름 (예: "click", "keydown")
+     * @param listener - The event handler function / 이벤트 핸들러 함수
+     * @param options - Optional event listener options / 선택적 이벤트 리스너 옵션
+     * @returns A cleanup function to remove this specific listener / 이 리스너를 제거하는 정리 함수
+     *
+     * @example
+     * ```typescript
+     * const cleanup = eventManager.add(window, "keydown", (e) => {
+     *   console.log("Key pressed:", e.key);
+     * });
+     *
+     * // Later, remove just this listener
+     * cleanup();
+     * ```
+     */
+    add(element: EventTarget, event: string, listener: EventListener, options?: AddEventListenerOptions | boolean): () => void;
+    /**
+     * Remove all tracked event listeners
+     * 추적된 모든 이벤트 리스너 제거
+     *
+     * This method should be called when the EventManager instance is no longer needed,
+     * typically in a React useEffect cleanup function.
+     * 이 메서드는 EventManager 인스턴스가 더 이상 필요하지 않을 때,
+     * 일반적으로 React useEffect 정리 함수에서 호출해야 합니다.
+     *
+     * @example
+     * ```typescript
+     * useEffect(() => {
+     *   const eventManager = new EventManager();
+     *   // ... add listeners
+     *   return () => eventManager.cleanup();
+     * }, []);
+     * ```
+     */
+    cleanup(): void;
+    /**
+     * Get statistics about current event listeners
+     * 현재 이벤트 리스너에 대한 통계 가져오기
+     *
+     * Useful for debugging and monitoring memory usage.
+     * 디버깅 및 메모리 사용량 모니터링에 유용합니다.
+     *
+     * @returns Statistics object / 통계 객체
+     */
+    getStats(): EventManagerStats;
+    /**
+     * Check if there are any active listeners
+     * 활성 리스너가 있는지 확인
+     *
+     * @returns true if there are active listeners, false otherwise
+     */
+    hasActiveListeners(): boolean;
+    /**
+     * Generate a unique key for an event listener
+     * 이벤트 리스너에 대한 고유 키 생성
+     */
+    private generateKey;
+    /**
+     * Extract event name from a key
+     * 키에서 이벤트 이름 추출
+     */
+    private extractEventFromKey;
+    /**
+     * Determine if an event should use passive listeners
+     * 이벤트가 패시브 리스너를 사용해야 하는지 결정
+     */
+    private shouldBePassive;
+    /**
+     * Merge passive option into existing options
+     * 기존 옵션에 패시브 옵션 병합
+     */
+    private mergePassiveOption;
+    /**
+     * Check if options specify passive mode
+     * 옵션이 패시브 모드를 지정하는지 확인
+     */
+    private isPassiveOption;
+    /**
+     * Remove a tracked listener from the internal map
+     * 내부 맵에서 추적된 리스너 제거
+     */
+    private removeTracked;
+}
+/**
+ * Factory function to create a new EventManager instance
+ * 새로운 EventManager 인스턴스를 생성하기 위한 팩토리 함수
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   // Create a shared EventManager instance for this component
+ *   const eventManager = useMemo(() => createEventManager(), []);
+ *
+ *   useEffect(() => {
+ *     eventManager.add(window, "keydown", handleKeyDown);
+ *     return () => eventManager.cleanup();
+ *   }, [eventManager, handleKeyDown]);
+ * }
+ * ```
+ */
+export declare function createEventManager(): EventManager;
+//# sourceMappingURL=EventManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EventManager.d.ts","sourceRoot":"","sources":["../../src/utils/EventManager.ts"],"names":[],"mappings":"AAyDA;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,kDAAkD;IAClD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB;;;;;OAKG;IACH,OAAO,CAAC,SAAS,CAA6C;IAE9D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,CACD,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,GAC1C,MAAM,IAAI;IA6Cb;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,IAAI,IAAI;IAqBf;;;;;;;;OAQG;IACH,QAAQ,IAAI,iBAAiB;IA6B7B;;;;;OAKG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAKnB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAiBvB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAQvB;;;OAGG;IACH,OAAO,CAAC,aAAa;CAetB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD"}

package/lib/utils/EventManager.js

@@ -0,0 +1 @@
+import "./eventConstants.js";

package/lib/utils/accessibility.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Accessibility utility functions for WCAG 2.1 Level AA compliance
+ * Provides keyboard navigation, focus management, color contrast checking,
+ * and screen reader support utilities
+ *
+ * @module utils/accessibility
+ * @category Accessibility
+ * @korean 접근성 유틸리티
+ */
+import React from "react";
+import { AriaAttributes, ColorContrastConfig, FocusIndicatorStyle, KeyboardActions, ScreenReaderAnnouncement, WCAGComplianceResult } from "../types/AccessibilityTypes";
+/**
+ * Handle keyboard navigation events with WCAG compliance
+ * Supports Tab, Enter, Space, Escape, Arrow keys, Home, End
+ *
+ * @param event - Keyboard event
+ * @param actions - Actions to perform for different keys
+ *
+ * @example
+ * ```tsx
+ * <div onKeyDown={(e) => handleKeyboardNav(e, {
+ *   onActivate: () => handleClick(),
+ *   onCancel: () => handleClose(),
+ *   onNavigate: (dir) => handleMove(dir),
+ * })}>
+ * ```
+ */
+export declare function handleKeyboardNav(event: KeyboardEvent, actions: KeyboardActions): void;
+/**
+ * Default focus indicator style (WCAG 2.1 Level AA compliant)
+ * @deprecated Use getDefaultFocusStyle() instead for lazy computation
+ */
+export declare const DEFAULT_FOCUS_STYLE: FocusIndicatorStyle;
+/**
+ * Get focus indicator CSS style object
+ *
+ * @param isFocused - Whether element is currently focused
+ * @param customStyle - Optional custom focus style overrides
+ * @returns CSS style object for focus indicator
+ *
+ * @example
+ * ```tsx
+ * const [isFocused, setIsFocused] = useState(false);
+ * <button
+ *   style={getFocusStyle(isFocused)}
+ *   onFocus={() => setIsFocused(true)}
+ *   onBlur={() => setIsFocused(false)}
+ * >
+ * ```
+ */
+export declare function getFocusStyle(isFocused: boolean, customStyle?: Partial<FocusIndicatorStyle>): React.CSSProperties;
+/**
+ * Convert hex color to RGB components
+ *
+ * @param hex - Hex color code (0xRRGGBB)
+ * @returns RGB components
+ */
+export declare function hexToRgb(hex: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Calculate contrast ratio between two colors (WCAG 2.1)
+ *
+ * @param foreground - Foreground color (hex)
+ * @param background - Background color (hex)
+ * @returns Contrast ratio (1-21)
+ *
+ * @example
+ * ```typescript
+ * const ratio = getContrastRatio(KOREAN_COLORS.TEXT_PRIMARY, KOREAN_COLORS.UI_BACKGROUND_DARK);
+ * console.log(`Contrast ratio: ${ratio.toFixed(2)}:1`); // Should be >= 4.5:1 for WCAG AA
+ * ```
+ */
+export declare function getContrastRatio(foreground: number, background: number): number;
+/**
+ * Check if color combination meets WCAG contrast requirements
+ *
+ * @param config - Color contrast configuration
+ * @returns Whether contrast meets WCAG requirements
+ *
+ * @example
+ * ```typescript
+ * const meetsWCAG = meetsContrastRequirement({
+ *   foreground: KOREAN_COLORS.TEXT_PRIMARY,
+ *   background: KOREAN_COLORS.UI_BACKGROUND_DARK,
+ *   targetRatio: 4.5,
+ * });
+ * ```
+ */
+export declare function meetsContrastRequirement(config: ColorContrastConfig): boolean;
+/**
+ * Get WCAG-compliant foreground color for given background
+ * Returns white or black depending on which provides better contrast
+ *
+ * @param background - Background color (hex)
+ * @returns Foreground color (hex) that meets WCAG AA
+ */
+export declare function getAccessibleForeground(background: number): number;
+export declare function announceToScreenReader(announcement: ScreenReaderAnnouncement): void;
+/**
+ * Clean up screen reader live region (for testing or app unmount)
+ */
+export declare function cleanupScreenReaderRegion(): void;
+/**
+ * Trap focus within a container element
+ * Prevents focus from leaving the container (e.g., for modals)
+ *
+ * @param container - Container element to trap focus within
+ * @returns Cleanup function to remove focus trap
+ *
+ * @example
+ * ```typescript
+ * useEffect(() => {
+ *   const cleanup = trapFocus(modalRef.current);
+ *   return cleanup;
+ * }, []);
+ * ```
+ */
+export declare function trapFocus(container: HTMLElement | null): () => void;
+/**
+ * Get all focusable elements within a container
+ *
+ * @param container - Container element
+ * @returns Array of focusable elements
+ */
+export declare function getFocusableElements(container: HTMLElement): HTMLElement[];
+/**
+ * Validate WCAG 2.1 Level AA compliance for a component
+ *
+ * Note: Color contrast checking requires access to computed styles,
+ * which is not available in all testing environments. This validation
+ * focuses on structural accessibility attributes.
+ *
+ * @param element - Element to validate
+ * @param config - Validation configuration
+ * @returns Compliance validation result
+ */
+export declare function validateWCAGCompliance(element: HTMLElement | null, config?: {
+    checkKeyboard?: boolean;
+    checkFocusVisible?: boolean;
+    checkAria?: boolean;
+}): WCAGComplianceResult;
+/**
+ * Create comprehensive ARIA attributes for a component
+ *
+ * @param label - Bilingual label (Korean | English)
+ * @param role - ARIA role
+ * @param additionalAttrs - Additional ARIA attributes
+ * @returns Complete ARIA attributes object
+ *
+ * @example
+ * ```tsx
+ * const ariaProps = createAriaAttributes(
+ *   createBilingualLabel('공격', 'Attack'),
+ *   'button',
+ *   { 'aria-pressed': isPressed }
+ * );
+ * <button {...ariaProps}>
+ * ```
+ */
+export declare function createAriaAttributes(label: string | {
+    korean: string;
+    english: string;
+}, role?: AriaAttributes["role"], additionalAttrs?: Partial<AriaAttributes>): AriaAttributes;
+/**
+ * Check if element is currently visible
+ * Useful for skip-to-content and focus management
+ *
+ * @param element - Element to check
+ * @returns Whether element is visible
+ */
+export declare function isElementVisible(element: HTMLElement | null): boolean;
+/**
+ * Focus first error element in a form
+ * Useful for form validation accessibility
+ *
+ * @param container - Form container
+ */
+export declare function focusFirstError(container: HTMLElement): void;
+/**
+ * Create skip to content link for keyboard navigation
+ * Returns a link that allows users to skip to main content
+ *
+ * Returns an object with the link element and a cleanup function to properly
+ * remove event listeners when the component is no longer needed.
+ *
+ * **Breaking Change**: This function now returns `{ element, cleanup }` instead of
+ * just `HTMLAnchorElement`. Update usage from:
+ * ```typescript
+ * const link = createSkipLink(id);
+ * ```
+ * to:
+ * ```typescript
+ * const { element, cleanup } = createSkipLink(id);
+ * ```
+ *
+ * 컴포넌트가 더 이상 필요하지 않을 때 이벤트 리스너를 적절히 제거하기 위한
+ * 링크 요소와 정리 함수가 포함된 객체를 반환합니다.
+ *
+ * @param targetId - ID of main content element
+ * @returns Object with skip link element and cleanup function
+ *
+ * @example
+ * ```typescript
+ * const { element, cleanup } = createSkipLink("main-content");
+ * document.body.prepend(element);
+ * // Later, when component unmounts
+ * cleanup();
+ * element.remove();
+ * ```
+ */
+export declare function createSkipLink(targetId: string): {
+    element: HTMLAnchorElement;
+    cleanup: () => void;
+};
+//# sourceMappingURL=accessibility.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility.d.ts","sourceRoot":"","sources":["../../src/utils/accessibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EACL,cAAc,EACd,mBAAmB,EAEnB,mBAAmB,EACnB,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EAErB,MAAM,6BAA6B,CAAC;AAIrC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,eAAe,GACvB,IAAI,CA0DN;AAmBD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBAA4C,CAAC;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,OAAO,EAClB,WAAW,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACzC,KAAK,CAAC,aAAa,CAoBrB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAMzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,MAAM,CAsBR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAQlE;AAmBD,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,wBAAwB,GACrC,IAAI,CAmCN;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAKhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI,GAAG,MAAM,IAAI,CAkCnE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAW1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,MAAM,CAAC,EAAE;IACP,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GACA,oBAAoB,CAqFtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EACnD,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,EAC7B,eAAe,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GACxC,cAAc,CAWhB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAUrE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI,CAY5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG;IAChD,OAAO,EAAE,iBAAiB,CAAC;IAC3B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAuCA"}

package/lib/utils/accessibility.js

@@ -0,0 +1,167 @@
+import { KOREAN_COLORS } from "../types/constants/colors.js";
+import "../types/constants/index.js";
+import "./EventManager.js";
+//#region src/utils/accessibility.ts
+/**
+* Handle keyboard navigation events with WCAG compliance
+* Supports Tab, Enter, Space, Escape, Arrow keys, Home, End
+*
+* @param event - Keyboard event
+* @param actions - Actions to perform for different keys
+*
+* @example
+* ```tsx
+* <div onKeyDown={(e) => handleKeyboardNav(e, {
+*   onActivate: () => handleClick(),
+*   onCancel: () => handleClose(),
+*   onNavigate: (dir) => handleMove(dir),
+* })}>
+* ```
+*/
+function handleKeyboardNav(event, actions) {
+	const { key, shiftKey } = event;
+	switch (key) {
+		case "Enter":
+		case " ":
+			event.preventDefault();
+			actions.onActivate?.();
+			break;
+		case "Escape":
+			event.preventDefault();
+			actions.onCancel?.();
+			break;
+		case "Tab":
+			actions.onTab?.(shiftKey);
+			break;
+		case "ArrowUp":
+			event.preventDefault();
+			actions.onNavigate?.("up");
+			break;
+		case "ArrowDown":
+			event.preventDefault();
+			actions.onNavigate?.("down");
+			break;
+		case "ArrowLeft":
+			event.preventDefault();
+			actions.onNavigate?.("left");
+			break;
+		case "ArrowRight":
+			event.preventDefault();
+			actions.onNavigate?.("right");
+			break;
+		case "Home":
+			event.preventDefault();
+			actions.onJump?.("start");
+			break;
+		case "End":
+			event.preventDefault();
+			actions.onJump?.("end");
+			break;
+	}
+}
+/**
+* Get default focus indicator style (WCAG 2.1 Level AA compliant)
+* Uses 2px solid outline with high contrast cyan color
+* Computed lazily to avoid initialization order dependencies
+*/
+function getDefaultFocusStyle() {
+	const rgb = hexToRgb(KOREAN_COLORS.PRIMARY_CYAN);
+	return {
+		outlineWidth: 2,
+		outlineColor: KOREAN_COLORS.PRIMARY_CYAN,
+		outlineOffset: 2,
+		outlineStyle: "solid",
+		boxShadow: `0 0 0 2px rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, 0.5)`,
+		transitionDuration: .2
+	};
+}
+getDefaultFocusStyle();
+/**
+* Get focus indicator CSS style object
+*
+* @param isFocused - Whether element is currently focused
+* @param customStyle - Optional custom focus style overrides
+* @returns CSS style object for focus indicator
+*
+* @example
+* ```tsx
+* const [isFocused, setIsFocused] = useState(false);
+* <button
+*   style={getFocusStyle(isFocused)}
+*   onFocus={() => setIsFocused(true)}
+*   onBlur={() => setIsFocused(false)}
+* >
+* ```
+*/
+function getFocusStyle(isFocused, customStyle) {
+	const defaultStyle = getDefaultFocusStyle();
+	if (!isFocused) return { transition: `all ${defaultStyle.transitionDuration}s ease` };
+	const style = {
+		...defaultStyle,
+		...customStyle
+	};
+	const rgb = hexToRgb(style.outlineColor ?? KOREAN_COLORS.PRIMARY_CYAN);
+	return {
+		outline: `${style.outlineWidth}px ${style.outlineStyle} rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`,
+		outlineOffset: `${style.outlineOffset}px`,
+		boxShadow: style.boxShadow ?? `0 0 0 2px rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, 0.5)`,
+		transition: `all ${style.transitionDuration}s ease`
+	};
+}
+/**
+* Convert hex color to RGB components
+*
+* @param hex - Hex color code (0xRRGGBB)
+* @returns RGB components
+*/
+function hexToRgb(hex) {
+	return {
+		r: hex >> 16 & 255,
+		g: hex >> 8 & 255,
+		b: hex & 255
+	};
+}
+/**
+* Announce message to screen readers
+* Creates a live region announcement with configurable politeness
+*
+* @param announcement - Screen reader announcement configuration
+*
+* @example
+* ```typescript
+* announceToScreenReader({
+*   message: '공격 성공 | Attack successful',
+*   politeness: 'polite',
+*   delay: 100,
+* });
+* ```
+*/
+var liveRegionInstance = null;
+function announceToScreenReader(announcement) {
+	const { message, politeness = "polite", delay = 0 } = announcement;
+	setTimeout(() => {
+		if (!liveRegionInstance) {
+			liveRegionInstance = document.createElement("div");
+			liveRegionInstance.id = "sr-live-region";
+			liveRegionInstance.setAttribute("aria-live", politeness);
+			liveRegionInstance.setAttribute("aria-atomic", "true");
+			liveRegionInstance.style.cssText = `
+        position: absolute;
+        left: -10000px;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+      `;
+			document.body.appendChild(liveRegionInstance);
+		}
+		if (liveRegionInstance.getAttribute("aria-live") !== politeness) liveRegionInstance.setAttribute("aria-live", politeness);
+		liveRegionInstance.textContent = message;
+		setTimeout(() => {
+			if (liveRegionInstance) liveRegionInstance.textContent = "";
+		}, 3e3);
+	}, delay);
+}
+//#endregion
+export { announceToScreenReader, getFocusStyle, handleKeyboardNav };
+
+//# sourceMappingURL=accessibility.js.map

package/lib/utils/accessibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility.js","names":[],"sources":["../../src/utils/accessibility.ts"],"sourcesContent":["/**\n * Accessibility utility functions for WCAG 2.1 Level AA compliance\n * Provides keyboard navigation, focus management, color contrast checking,\n * and screen reader support utilities\n *\n * @module utils/accessibility\n * @category Accessibility\n * @korean 접근성 유틸리티\n */\n\nimport React from \"react\";\nimport {\n  AriaAttributes,\n  ColorContrastConfig,\n  createBilingualLabel,\n  FocusIndicatorStyle,\n  KeyboardActions,\n  ScreenReaderAnnouncement,\n  WCAGComplianceResult,\n  WCAGLevel,\n} from \"../types/AccessibilityTypes\";\nimport { KOREAN_COLORS } from \"@/types/constants\";\nimport { EventManager } from \"./EventManager\";\n\n/**\n * Handle keyboard navigation events with WCAG compliance\n * Supports Tab, Enter, Space, Escape, Arrow keys, Home, End\n *\n * @param event - Keyboard event\n * @param actions - Actions to perform for different keys\n *\n * @example\n * ```tsx\n * <div onKeyDown={(e) => handleKeyboardNav(e, {\n *   onActivate: () => handleClick(),\n *   onCancel: () => handleClose(),\n *   onNavigate: (dir) => handleMove(dir),\n * })}>\n * ```\n */\nexport function handleKeyboardNav(\n  event: KeyboardEvent,\n  actions: KeyboardActions,\n): void {\n  const { key, shiftKey } = event;\n\n  switch (key) {\n    case \"Enter\":\n    case \" \":\n      // Activate element (button, link, etc.)\n      event.preventDefault();\n      actions.onActivate?.();\n      break;\n\n    case \"Escape\":\n      // Cancel or close action\n      event.preventDefault();\n      actions.onCancel?.();\n      break;\n\n    case \"Tab\":\n      // Tab navigation (forward or backward with Shift)\n      actions.onTab?.(shiftKey);\n      break;\n\n    case \"ArrowUp\":\n      // Navigate up\n      event.preventDefault();\n      actions.onNavigate?.(\"up\");\n      break;\n\n    case \"ArrowDown\":\n      // Navigate down\n      event.preventDefault();\n      actions.onNavigate?.(\"down\");\n      break;\n\n    case \"ArrowLeft\":\n      // Navigate left\n      event.preventDefault();\n      actions.onNavigate?.(\"left\");\n      break;\n\n    case \"ArrowRight\":\n      // Navigate right\n      event.preventDefault();\n      actions.onNavigate?.(\"right\");\n      break;\n\n    case \"Home\":\n      // Jump to start\n      event.preventDefault();\n      actions.onJump?.(\"start\");\n      break;\n\n    case \"End\":\n      // Jump to end\n      event.preventDefault();\n      actions.onJump?.(\"end\");\n      break;\n  }\n}\n\n/**\n * Get default focus indicator style (WCAG 2.1 Level AA compliant)\n * Uses 2px solid outline with high contrast cyan color\n * Computed lazily to avoid initialization order dependencies\n */\nfunction getDefaultFocusStyle(): FocusIndicatorStyle {\n  const rgb = hexToRgb(KOREAN_COLORS.PRIMARY_CYAN);\n  return {\n    outlineWidth: 2,\n    outlineColor: KOREAN_COLORS.PRIMARY_CYAN,\n    outlineOffset: 2,\n    outlineStyle: \"solid\",\n    boxShadow: `0 0 0 2px rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, 0.5)`,\n    transitionDuration: 0.2,\n  };\n}\n\n/**\n * Default focus indicator style (WCAG 2.1 Level AA compliant)\n * @deprecated Use getDefaultFocusStyle() instead for lazy computation\n */\nexport const DEFAULT_FOCUS_STYLE: FocusIndicatorStyle = getDefaultFocusStyle();\n\n/**\n * Get focus indicator CSS style object\n *\n * @param isFocused - Whether element is currently focused\n * @param customStyle - Optional custom focus style overrides\n * @returns CSS style object for focus indicator\n *\n * @example\n * ```tsx\n * const [isFocused, setIsFocused] = useState(false);\n * <button\n *   style={getFocusStyle(isFocused)}\n *   onFocus={() => setIsFocused(true)}\n *   onBlur={() => setIsFocused(false)}\n * >\n * ```\n */\nexport function getFocusStyle(\n  isFocused: boolean,\n  customStyle?: Partial<FocusIndicatorStyle>,\n): React.CSSProperties {\n  const defaultStyle = getDefaultFocusStyle();\n\n  if (!isFocused) {\n    return {\n      // Preserve browser default focus indicator instead of 'none'\n      transition: `all ${defaultStyle.transitionDuration}s ease`,\n    };\n  }\n\n  const style = { ...defaultStyle, ...customStyle };\n  const rgb = hexToRgb(style.outlineColor ?? KOREAN_COLORS.PRIMARY_CYAN);\n\n  return {\n    outline: `${style.outlineWidth}px ${style.outlineStyle} rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`,\n    outlineOffset: `${style.outlineOffset}px`,\n    boxShadow:\n      style.boxShadow ?? `0 0 0 2px rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, 0.5)`,\n    transition: `all ${style.transitionDuration}s ease`,\n  };\n}\n\n/**\n * Convert hex color to RGB components\n *\n * @param hex - Hex color code (0xRRGGBB)\n * @returns RGB components\n */\nexport function hexToRgb(hex: number): { r: number; g: number; b: number } {\n  return {\n    r: (hex >> 16) & 255,\n    g: (hex >> 8) & 255,\n    b: hex & 255,\n  };\n}\n\n/**\n * Calculate contrast ratio between two colors (WCAG 2.1)\n *\n * @param foreground - Foreground color (hex)\n * @param background - Background color (hex)\n * @returns Contrast ratio (1-21)\n *\n * @example\n * ```typescript\n * const ratio = getContrastRatio(KOREAN_COLORS.TEXT_PRIMARY, KOREAN_COLORS.UI_BACKGROUND_DARK);\n * console.log(`Contrast ratio: ${ratio.toFixed(2)}:1`); // Should be >= 4.5:1 for WCAG AA\n * ```\n */\nexport function getContrastRatio(\n  foreground: number,\n  background: number,\n): number {\n  const fg = hexToRgb(foreground);\n  const bg = hexToRgb(background);\n\n  // Calculate relative luminance (WCAG formula)\n  const getLuminance = (r: number, g: number, b: number): number => {\n    const [rs, gs, bs] = [r, g, b].map((c) => {\n      const sRGB = c / 255;\n      return sRGB <= 0.03928\n        ? sRGB / 12.92\n        : Math.pow((sRGB + 0.055) / 1.055, 2.4);\n    });\n    return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;\n  };\n\n  const l1 = getLuminance(fg.r, fg.g, fg.b);\n  const l2 = getLuminance(bg.r, bg.g, bg.b);\n\n  // Contrast ratio formula\n  const lighter = Math.max(l1, l2);\n  const darker = Math.min(l1, l2);\n  return (lighter + 0.05) / (darker + 0.05);\n}\n\n/**\n * Check if color combination meets WCAG contrast requirements\n *\n * @param config - Color contrast configuration\n * @returns Whether contrast meets WCAG requirements\n *\n * @example\n * ```typescript\n * const meetsWCAG = meetsContrastRequirement({\n *   foreground: KOREAN_COLORS.TEXT_PRIMARY,\n *   background: KOREAN_COLORS.UI_BACKGROUND_DARK,\n *   targetRatio: 4.5,\n * });\n * ```\n */\nexport function meetsContrastRequirement(config: ColorContrastConfig): boolean {\n  const ratio = getContrastRatio(config.foreground, config.background);\n  return ratio >= config.targetRatio;\n}\n\n/**\n * Get WCAG-compliant foreground color for given background\n * Returns white or black depending on which provides better contrast\n *\n * @param background - Background color (hex)\n * @returns Foreground color (hex) that meets WCAG AA\n */\nexport function getAccessibleForeground(background: number): number {\n  const whiteRatio = getContrastRatio(KOREAN_COLORS.TEXT_PRIMARY, background);\n  const blackRatio = getContrastRatio(KOREAN_COLORS.BLACK_SOLID, background);\n\n  // Return color with better contrast\n  return whiteRatio >= blackRatio\n    ? KOREAN_COLORS.TEXT_PRIMARY\n    : KOREAN_COLORS.BLACK_SOLID;\n}\n\n/**\n * Announce message to screen readers\n * Creates a live region announcement with configurable politeness\n *\n * @param announcement - Screen reader announcement configuration\n *\n * @example\n * ```typescript\n * announceToScreenReader({\n *   message: '공격 성공 | Attack successful',\n *   politeness: 'polite',\n *   delay: 100,\n * });\n * ```\n */\nlet liveRegionInstance: HTMLElement | null = null;\n\nexport function announceToScreenReader(\n  announcement: ScreenReaderAnnouncement,\n): void {\n  const { message, politeness = \"polite\", delay = 0 } = announcement;\n\n  setTimeout(() => {\n    // Create or get existing live region\n    if (!liveRegionInstance) {\n      liveRegionInstance = document.createElement(\"div\");\n      liveRegionInstance.id = \"sr-live-region\";\n      liveRegionInstance.setAttribute(\"aria-live\", politeness);\n      liveRegionInstance.setAttribute(\"aria-atomic\", \"true\");\n      liveRegionInstance.style.cssText = `\n        position: absolute;\n        left: -10000px;\n        width: 1px;\n        height: 1px;\n        overflow: hidden;\n      `;\n      document.body.appendChild(liveRegionInstance);\n    }\n\n    // Update politeness level if changed\n    if (liveRegionInstance.getAttribute(\"aria-live\") !== politeness) {\n      liveRegionInstance.setAttribute(\"aria-live\", politeness);\n    }\n\n    // Update message\n    liveRegionInstance.textContent = message;\n\n    // Clear message after 3 seconds\n    setTimeout(() => {\n      if (liveRegionInstance) {\n        liveRegionInstance.textContent = \"\";\n      }\n    }, 3000);\n  }, delay);\n}\n\n/**\n * Clean up screen reader live region (for testing or app unmount)\n */\nexport function cleanupScreenReaderRegion(): void {\n  if (liveRegionInstance?.parentNode) {\n    liveRegionInstance.parentNode.removeChild(liveRegionInstance);\n    liveRegionInstance = null;\n  }\n}\n\n/**\n * Trap focus within a container element\n * Prevents focus from leaving the container (e.g., for modals)\n *\n * @param container - Container element to trap focus within\n * @returns Cleanup function to remove focus trap\n *\n * @example\n * ```typescript\n * useEffect(() => {\n *   const cleanup = trapFocus(modalRef.current);\n *   return cleanup;\n * }, []);\n * ```\n */\nexport function trapFocus(container: HTMLElement | null): () => void {\n  if (!container) return () => {};\n\n  const focusableElements = getFocusableElements(container);\n  const firstElement = focusableElements[0];\n  const lastElement = focusableElements[focusableElements.length - 1];\n\n  const handleKeyDown = (event: KeyboardEvent) => {\n    if (event.key !== \"Tab\") return;\n\n    if (event.shiftKey) {\n      // Shift + Tab: Move focus backward\n      if (document.activeElement === firstElement) {\n        event.preventDefault();\n        lastElement?.focus();\n      }\n    } else {\n      // Tab: Move focus forward\n      if (document.activeElement === lastElement) {\n        event.preventDefault();\n        firstElement?.focus();\n      }\n    }\n  };\n\n  container.addEventListener(\"keydown\", handleKeyDown);\n\n  // Set initial focus\n  firstElement?.focus();\n\n  // Return cleanup function\n  return () => {\n    container.removeEventListener(\"keydown\", handleKeyDown);\n  };\n}\n\n/**\n * Get all focusable elements within a container\n *\n * @param container - Container element\n * @returns Array of focusable elements\n */\nexport function getFocusableElements(container: HTMLElement): HTMLElement[] {\n  const selector = [\n    \"a[href]\",\n    \"button:not([disabled])\",\n    \"input:not([disabled])\",\n    \"select:not([disabled])\",\n    \"textarea:not([disabled])\",\n    '[tabindex]:not([tabindex=\"-1\"])',\n  ].join(\", \");\n\n  return Array.from(container.querySelectorAll<HTMLElement>(selector));\n}\n\n/**\n * Validate WCAG 2.1 Level AA compliance for a component\n *\n * Note: Color contrast checking requires access to computed styles,\n * which is not available in all testing environments. This validation\n * focuses on structural accessibility attributes.\n *\n * @param element - Element to validate\n * @param config - Validation configuration\n * @returns Compliance validation result\n */\nexport function validateWCAGCompliance(\n  element: HTMLElement | null,\n  config?: {\n    checkKeyboard?: boolean;\n    checkFocusVisible?: boolean;\n    checkAria?: boolean;\n  },\n): WCAGComplianceResult {\n  const {\n    checkKeyboard = true,\n    checkFocusVisible = true,\n    checkAria = true,\n  } = config ?? {};\n\n  const issues: string[] = [];\n  let keyboardAccessible = true;\n  const colorContrast = true; // Note: Requires computed styles - use getContrastRatio() directly for color validation\n  let focusVisible = true;\n  let ariaLabels = true;\n\n  if (!element) {\n    issues.push(\"Element not found\");\n    return {\n      level: WCAGLevel.A,\n      compliant: false,\n      criteria: {\n        keyboardAccessible: false,\n        colorContrast: false,\n        focusVisible: false,\n        ariaLabels: false,\n        semanticHTML: false,\n        errorIdentification: false,\n      },\n      issues,\n    };\n  }\n\n  // Check keyboard accessibility\n  if (checkKeyboard) {\n    const isInteractive =\n      element.tagName === \"BUTTON\" ||\n      element.tagName === \"A\" ||\n      element.tagName === \"INPUT\" ||\n      element.hasAttribute(\"onclick\");\n\n    if (isInteractive && element.getAttribute(\"tabindex\") === \"-1\") {\n      keyboardAccessible = false;\n      issues.push(\"Interactive element not keyboard accessible\");\n    }\n  }\n\n  // Check ARIA labels\n  if (checkAria) {\n    const hasAriaLabel =\n      element.hasAttribute(\"aria-label\") ||\n      element.hasAttribute(\"aria-labelledby\");\n\n    const hasTextContent = element.textContent?.trim();\n\n    if (!hasAriaLabel && !hasTextContent) {\n      ariaLabels = false;\n      issues.push(\"Missing ARIA label or text content\");\n    }\n  }\n\n  // Check focus indicator\n  if (checkFocusVisible) {\n    const computedStyle = window.getComputedStyle(element);\n    const outline = computedStyle.outline;\n\n    if (outline === \"none\" || outline === \"\") {\n      focusVisible = false;\n      issues.push(\"Missing visible focus indicator\");\n    }\n  }\n\n  const allPass =\n    keyboardAccessible && colorContrast && focusVisible && ariaLabels;\n\n  return {\n    level: allPass ? WCAGLevel.AA : WCAGLevel.A,\n    compliant: allPass,\n    criteria: {\n      keyboardAccessible,\n      colorContrast, // Note: Always true - use getContrastRatio() for actual color validation\n      focusVisible,\n      ariaLabels,\n      semanticHTML: true, // Requires manual verification\n      errorIdentification: true, // Requires manual verification\n    },\n    issues,\n  };\n}\n\n/**\n * Create comprehensive ARIA attributes for a component\n *\n * @param label - Bilingual label (Korean | English)\n * @param role - ARIA role\n * @param additionalAttrs - Additional ARIA attributes\n * @returns Complete ARIA attributes object\n *\n * @example\n * ```tsx\n * const ariaProps = createAriaAttributes(\n *   createBilingualLabel('공격', 'Attack'),\n *   'button',\n *   { 'aria-pressed': isPressed }\n * );\n * <button {...ariaProps}>\n * ```\n */\nexport function createAriaAttributes(\n  label: string | { korean: string; english: string },\n  role?: AriaAttributes[\"role\"],\n  additionalAttrs?: Partial<AriaAttributes>,\n): AriaAttributes {\n  const bilingualLabel =\n    typeof label === \"string\"\n      ? label\n      : createBilingualLabel(label.korean, label.english).label;\n\n  return {\n    role,\n    \"aria-label\": bilingualLabel,\n    ...additionalAttrs,\n  };\n}\n\n/**\n * Check if element is currently visible\n * Useful for skip-to-content and focus management\n *\n * @param element - Element to check\n * @returns Whether element is visible\n */\nexport function isElementVisible(element: HTMLElement | null): boolean {\n  if (!element) return false;\n\n  const style = window.getComputedStyle(element);\n  return (\n    style.display !== \"none\" &&\n    style.visibility !== \"hidden\" &&\n    style.opacity !== \"0\" &&\n    element.offsetParent !== null\n  );\n}\n\n/**\n * Focus first error element in a form\n * Useful for form validation accessibility\n *\n * @param container - Form container\n */\nexport function focusFirstError(container: HTMLElement): void {\n  const errorElements = container.querySelectorAll<HTMLElement>(\n    '[aria-invalid=\"true\"]',\n  );\n\n  if (errorElements.length > 0) {\n    errorElements[0].focus();\n    announceToScreenReader({\n      message: \"오류가 발견되었습니다 | Errors found\",\n      politeness: \"assertive\",\n    });\n  }\n}\n\n/**\n * Create skip to content link for keyboard navigation\n * Returns a link that allows users to skip to main content\n *\n * Returns an object with the link element and a cleanup function to properly\n * remove event listeners when the component is no longer needed.\n *\n * **Breaking Change**: This function now returns `{ element, cleanup }` instead of\n * just `HTMLAnchorElement`. Update usage from:\n * ```typescript\n * const link = createSkipLink(id);\n * ```\n * to:\n * ```typescript\n * const { element, cleanup } = createSkipLink(id);\n * ```\n *\n * 컴포넌트가 더 이상 필요하지 않을 때 이벤트 리스너를 적절히 제거하기 위한\n * 링크 요소와 정리 함수가 포함된 객체를 반환합니다.\n *\n * @param targetId - ID of main content element\n * @returns Object with skip link element and cleanup function\n *\n * @example\n * ```typescript\n * const { element, cleanup } = createSkipLink(\"main-content\");\n * document.body.prepend(element);\n * // Later, when component unmounts\n * cleanup();\n * element.remove();\n * ```\n */\nexport function createSkipLink(targetId: string): {\n  element: HTMLAnchorElement;\n  cleanup: () => void;\n} {\n  const skipLink = document.createElement(\"a\");\n  skipLink.href = `#${targetId}`;\n  skipLink.textContent = \"본문으로 건너뛰기 | Skip to content\";\n  skipLink.className = \"skip-link\";\n  skipLink.style.cssText = `\n    position: absolute;\n    top: -40px;\n    left: 0;\n    background: #00e6e6;\n    color: #000;\n    padding: 8px;\n    text-decoration: none;\n    z-index: 10000;\n    font-weight: bold;\n  `;\n\n  // Use EventManager for consistent event handling across the codebase\n  const eventManager = new EventManager();\n\n  // Event handlers\n  const handleFocus = () => {\n    skipLink.style.top = \"0\";\n  };\n\n  const handleBlur = () => {\n    skipLink.style.top = \"-40px\";\n  };\n\n  // Add event listeners via EventManager\n  eventManager.add(skipLink, \"focus\", handleFocus);\n  eventManager.add(skipLink, \"blur\", handleBlur);\n\n  // Cleanup function to remove all event listeners\n  const cleanup = () => {\n    eventManager.cleanup();\n  };\n\n  return { element: skipLink, cleanup };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,kBACd,OACA,SACM;CACN,MAAM,EAAE,KAAK,aAAa;AAE1B,SAAQ,KAAR;EACE,KAAK;EACL,KAAK;AAEH,SAAM,gBAAgB;AACtB,WAAQ,cAAc;AACtB;EAEF,KAAK;AAEH,SAAM,gBAAgB;AACtB,WAAQ,YAAY;AACpB;EAEF,KAAK;AAEH,WAAQ,QAAQ,SAAS;AACzB;EAEF,KAAK;AAEH,SAAM,gBAAgB;AACtB,WAAQ,aAAa,KAAK;AAC1B;EAEF,KAAK;AAEH,SAAM,gBAAgB;AACtB,WAAQ,aAAa,OAAO;AAC5B;EAEF,KAAK;AAEH,SAAM,gBAAgB;AACtB,WAAQ,aAAa,OAAO;AAC5B;EAEF,KAAK;AAEH,SAAM,gBAAgB;AACtB,WAAQ,aAAa,QAAQ;AAC7B;EAEF,KAAK;AAEH,SAAM,gBAAgB;AACtB,WAAQ,SAAS,QAAQ;AACzB;EAEF,KAAK;AAEH,SAAM,gBAAgB;AACtB,WAAQ,SAAS,MAAM;AACvB;;;;;;;;AASN,SAAS,uBAA4C;CACnD,MAAM,MAAM,SAAS,cAAc,aAAa;AAChD,QAAO;EACL,cAAc;EACd,cAAc,cAAc;EAC5B,eAAe;EACf,cAAc;EACd,WAAW,kBAAkB,IAAI,EAAE,IAAI,IAAI,EAAE,IAAI,IAAI,EAAE;EACvD,oBAAoB;EACrB;;AAOqD,sBAAsB;;;;;;;;;;;;;;;;;;AAmB9E,SAAgB,cACd,WACA,aACqB;CACrB,MAAM,eAAe,sBAAsB;AAE3C,KAAI,CAAC,UACH,QAAO,EAEL,YAAY,OAAO,aAAa,mBAAmB,SACpD;CAGH,MAAM,QAAQ;EAAE,GAAG;EAAc,GAAG;EAAa;CACjD,MAAM,MAAM,SAAS,MAAM,gBAAgB,cAAc,aAAa;AAEtE,QAAO;EACL,SAAS,GAAG,MAAM,aAAa,KAAK,MAAM,aAAa,OAAO,IAAI,EAAE,IAAI,IAAI,EAAE,IAAI,IAAI,EAAE;EACxF,eAAe,GAAG,MAAM,cAAc;EACtC,WACE,MAAM,aAAa,kBAAkB,IAAI,EAAE,IAAI,IAAI,EAAE,IAAI,IAAI,EAAE;EACjE,YAAY,OAAO,MAAM,mBAAmB;EAC7C;;;;;;;;AASH,SAAgB,SAAS,KAAkD;AACzE,QAAO;EACL,GAAI,OAAO,KAAM;EACjB,GAAI,OAAO,IAAK;EAChB,GAAG,MAAM;EACV;;;;;;;;;;;;;;;;;AA+FH,IAAI,qBAAyC;AAE7C,SAAgB,uBACd,cACM;CACN,MAAM,EAAE,SAAS,aAAa,UAAU,QAAQ,MAAM;AAEtD,kBAAiB;AAEf,MAAI,CAAC,oBAAoB;AACvB,wBAAqB,SAAS,cAAc,MAAM;AAClD,sBAAmB,KAAK;AACxB,sBAAmB,aAAa,aAAa,WAAW;AACxD,sBAAmB,aAAa,eAAe,OAAO;AACtD,sBAAmB,MAAM,UAAU;;;;;;;AAOnC,YAAS,KAAK,YAAY,mBAAmB;;AAI/C,MAAI,mBAAmB,aAAa,YAAY,KAAK,WACnD,oBAAmB,aAAa,aAAa,WAAW;AAI1D,qBAAmB,cAAc;AAGjC,mBAAiB;AACf,OAAI,mBACF,oBAAmB,cAAc;KAElC,IAAK;IACP,MAAM"}