@hua-labs/hua-ux 0.1.0-alpha.0.1

package/src/framework/a11y/hooks/useFocusTrap.ts

@@ -0,0 +1,239 @@
+/**
+ * @hua-labs/hua-ux/framework - useFocusTrap
+ * 
+ * 모달, 드로어 등에서 포커스를 트랩하는 hook
+ * Traps focus within a container (e.g., modal, drawer)
+ */
+
+'use client';
+
+import { useEffect, useRef, useCallback, type RefObject } from 'react';
+
+/**
+ * Focus Trap 옵션
+ */
+export interface FocusTrapOptions {
+  /**
+   * 포커스 트랩 활성화 여부
+   * Whether focus trap is active
+   * 
+   * @default true
+   */
+  isActive?: boolean;
+  
+  /**
+   * Escape 키를 눌렀을 때 호출할 콜백
+   * Callback when Escape key is pressed
+   */
+  onEscape?: () => void;
+  
+  /**
+   * 포커스할 초기 요소 선택자
+   * Selector for initial element to focus
+   */
+  initialFocus?: string;
+  
+  /**
+   * 포커스가 트랩 밖으로 나갔을 때 호출할 콜백
+   * Callback when focus leaves the trap
+   */
+  onFocusOut?: () => void;
+}
+
+/**
+ * Focus Trap Hook
+ * 
+ * 모달, 드로어 등에서 포커스를 컨테이너 내부에 트랩합니다.
+ * Traps focus within a container (e.g., modal, drawer).
+ * 
+ * @example
+ * ```tsx
+ * function Modal({ isOpen, onClose }) {
+ *   const modalRef = useFocusTrap({ 
+ *     isActive: isOpen, 
+ *     onEscape: onClose 
+ *   });
+ * 
+ *   if (!isOpen) return null;
+ * 
+ *   return (
+ *     <div ref={modalRef} role="dialog" aria-modal="true">
+ *       <button onClick={onClose}>Close</button>
+ *       Modal content
+ *     </div>
+ *   );
+ * }
+ * ```
+ * 
+ * @param options - Focus Trap 옵션
+ * @returns 컨테이너에 연결할 ref
+ */
+export function useFocusTrap<T extends HTMLElement = HTMLElement>(
+  options: FocusTrapOptions = {}
+): RefObject<T | null> {
+  const {
+    isActive = true,
+    onEscape,
+    initialFocus,
+    onFocusOut,
+  } = options;
+
+  const ref = useRef<T>(null);
+  const previousActiveElement = useRef<HTMLElement | null>(null);
+  const onEscapeRef = useRef(onEscape);
+  const onFocusOutRef = useRef(onFocusOut);
+
+  // 콜백 ref 업데이트
+  useEffect(() => {
+    onEscapeRef.current = onEscape;
+    onFocusOutRef.current = onFocusOut;
+  }, [onEscape, onFocusOut]);
+
+  useEffect(() => {
+    if (!isActive || !ref.current) {
+      return;
+    }
+
+    const container = ref.current;
+
+    // 현재 포커스된 요소 저장
+    previousActiveElement.current = document.activeElement as HTMLElement;
+
+    // 포커스 가능한 요소들 찾기
+    const getFocusableElements = (): HTMLElement[] => {
+      const focusableSelectors = [
+        'a[href]',
+        'button:not([disabled])',
+        'textarea:not([disabled])',
+        'input:not([disabled])',
+        'select:not([disabled])',
+        '[tabindex]:not([tabindex="-1"])',
+      ].join(', ');
+
+      return Array.from(container.querySelectorAll<HTMLElement>(focusableSelectors))
+        .filter((el) => {
+          // 숨겨진 요소 제외
+          const style = window.getComputedStyle(el);
+          return style.display !== 'none' && style.visibility !== 'hidden';
+        });
+    };
+
+    // 초기 포커스 설정
+    const focusInitialElement = () => {
+      try {
+        if (initialFocus) {
+          const element = container.querySelector<HTMLElement>(initialFocus);
+          if (element) {
+            element.focus();
+            return;
+          }
+        }
+
+        // 첫 번째 포커스 가능한 요소에 포커스
+        const focusableElements = getFocusableElements();
+        if (focusableElements.length > 0) {
+          focusableElements[0].focus();
+        } else {
+          // 포커스 가능한 요소가 없으면 컨테이너에 포커스
+          container.setAttribute('tabindex', '-1');
+          container.focus();
+        }
+      } catch (error) {
+        // focus() 실패 시 (예: 요소가 아직 렌더링되지 않음)
+        // 조용히 실패 (접근성 기능이므로 에러를 던지지 않음)
+        if (process.env.NODE_ENV === 'development') {
+          console.warn('[useFocusTrap] Failed to focus initial element:', error);
+        }
+      }
+    };
+
+    // 키보드 이벤트 핸들러
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && onEscapeRef.current) {
+        event.preventDefault();
+        onEscapeRef.current();
+        return;
+      }
+
+      // Tab 키 처리
+      if (event.key === 'Tab') {
+        const focusableElements = getFocusableElements();
+        if (focusableElements.length === 0) {
+          event.preventDefault();
+          return;
+        }
+
+        const firstElement = focusableElements[0];
+        const lastElement = focusableElements[focusableElements.length - 1];
+        const currentElement = document.activeElement as HTMLElement;
+
+        // Shift + Tab (역방향)
+        if (event.shiftKey) {
+          if (currentElement === firstElement) {
+            event.preventDefault();
+            try {
+              lastElement.focus();
+            } catch (error) {
+              // focus() 실패 시 조용히 처리
+              if (process.env.NODE_ENV === 'development') {
+                console.warn('[useFocusTrap] Failed to focus last element:', error);
+              }
+            }
+          }
+        } else {
+          // Tab (정방향)
+          if (currentElement === lastElement) {
+            event.preventDefault();
+            try {
+              firstElement.focus();
+            } catch (error) {
+              // focus() 실패 시 조용히 처리
+              if (process.env.NODE_ENV === 'development') {
+                console.warn('[useFocusTrap] Failed to focus first element:', error);
+              }
+            }
+          }
+        }
+      }
+    };
+
+    // 포커스 아웃 감지
+    const handleFocusIn = (event: FocusEvent) => {
+      if (!container.contains(event.target as Node)) {
+        onFocusOutRef.current?.();
+        // 포커스를 다시 컨테이너 내부로 이동
+        try {
+          const focusableElements = getFocusableElements();
+          if (focusableElements.length > 0) {
+            focusableElements[0].focus();
+          }
+        } catch (error) {
+          // focus() 실패 시 조용히 처리
+          if (process.env.NODE_ENV === 'development') {
+            console.warn('[useFocusTrap] Failed to refocus element:', error);
+          }
+        }
+      }
+    };
+
+    // 초기 포커스 설정
+    focusInitialElement();
+
+    // 이벤트 리스너 등록
+    container.addEventListener('keydown', handleKeyDown);
+    document.addEventListener('focusin', handleFocusIn);
+
+    // 정리 함수
+    return () => {
+      container.removeEventListener('keydown', handleKeyDown);
+      document.removeEventListener('focusin', handleFocusIn);
+
+      // 이전 포커스 복원
+      if (previousActiveElement.current) {
+        previousActiveElement.current.focus();
+      }
+    };
+  }, [isActive, initialFocus]);
+
+  return ref;
+}

package/src/framework/a11y/hooks/useLiveRegion.ts

@@ -0,0 +1,95 @@
+/**
+ * @hua-labs/hua-ux/framework - useLiveRegion
+ * 
+ * 프로그래밍 방식으로 Live Region을 사용하는 hook
+ * Hook for programmatically using Live Region
+ */
+
+'use client';
+
+import React, { useCallback, useState } from 'react';
+import { LiveRegion, type LiveRegionProps } from '../components/LiveRegion';
+
+/**
+ * useLiveRegion 반환 타입
+ */
+export interface UseLiveRegionReturn {
+  /**
+   * 메시지를 알림
+   * Announce a message
+   */
+  announce: (message: string, politeness?: 'polite' | 'assertive') => void;
+  
+  /**
+   * LiveRegion 컴포넌트
+   * LiveRegion component to render
+   */
+  LiveRegionComponent: React.JSX.Element;
+  
+  /**
+   * 현재 메시지
+   * Current message
+   */
+  message: string | undefined;
+}
+
+/**
+ * useLiveRegion Hook
+ * 
+ * 프로그래밍 방식으로 Live Region을 사용할 수 있습니다.
+ * Allows programmatic use of Live Region.
+ * 
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { announce, LiveRegionComponent } = useLiveRegion();
+ * 
+ *   const handleClick = () => {
+ *     announce('버튼이 클릭되었습니다');
+ *   };
+ * 
+ *   return (
+ *     <div>
+ *       <button onClick={handleClick}>Click me</button>
+ *       {LiveRegionComponent}
+ *     </div>
+ *   );
+ * }
+ * ```
+ * 
+ * @param defaultPoliteness - 기본 politeness 레벨
+ * @returns Live Region 제어 함수와 컴포넌트
+ */
+export function useLiveRegion(
+  defaultPoliteness: 'polite' | 'assertive' = 'polite'
+): UseLiveRegionReturn {
+  const [message, setMessage] = useState<string | undefined>(undefined);
+  const [politeness, setPoliteness] = useState<'polite' | 'assertive'>(defaultPoliteness);
+
+  const announce = useCallback(
+    (newMessage: string, newPoliteness?: 'polite' | 'assertive') => {
+      // 메시지를 초기화한 후 다시 설정하여 스크린 리더가 변경을 감지하도록 함
+      setMessage(undefined);
+      
+      // 다음 틱에 메시지 설정
+      setTimeout(() => {
+        setMessage(newMessage);
+        if (newPoliteness) {
+          setPoliteness(newPoliteness);
+        }
+      }, 0);
+    },
+    []
+  );
+
+  const LiveRegionComponent = React.createElement(LiveRegion, {
+    message,
+    politeness,
+  });
+
+  return {
+    announce,
+    LiveRegionComponent,
+    message,
+  };
+}

package/src/framework/a11y/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @hua-labs/hua-ux/framework - Accessibility (a11y)
+ * 
+ * WCAG 2.1 준수를 위한 접근성 도구 모음
+ * Accessibility tools for WCAG 2.1 compliance
+ */
+
+export { useFocusManagement } from './hooks/useFocusManagement';
+export { useFocusTrap } from './hooks/useFocusTrap';
+export { SkipToContent } from './components/SkipToContent';
+export { LiveRegion } from './components/LiveRegion';
+export { useLiveRegion } from './hooks/useLiveRegion';
+
+export type { FocusManagementOptions } from './hooks/useFocusManagement';
+export type { FocusTrapOptions } from './hooks/useFocusTrap';
+export type { SkipToContentProps } from './components/SkipToContent';
+export type { LiveRegionProps } from './components/LiveRegion';

package/src/framework/branding/context.tsx

@@ -0,0 +1,135 @@
+/**
+ * @hua-labs/hua-ux/framework - Branding Context
+ * 
+ * 브랜딩 설정을 컴포넌트에서 사용하기 위한 Context
+ */
+
+'use client';
+
+import React, { createContext, useContext } from 'react';
+import type { HuaUxConfig } from '../types';
+import { generateCSSVariables } from './css-vars';
+
+/**
+ * Branding context value
+ */
+interface BrandingContextValue {
+  branding: NonNullable<HuaUxConfig['branding']> | null;
+}
+
+/**
+ * Branding context
+ */
+const BrandingContext = createContext<BrandingContextValue>({
+  branding: null,
+});
+
+/**
+ * BrandingProvider component
+ * 
+ * 브랜딩 설정을 제공하고 CSS 변수를 자동으로 주입하는 Provider입니다.
+ * Provides branding configuration and automatically injects CSS variables.
+ * 
+ * @example
+ * ```tsx
+ * <BrandingProvider branding={config.branding}>
+ *   {children}
+ * </BrandingProvider>
+ * ```
+ */
+export function BrandingProvider({
+  branding,
+  children,
+}: {
+  branding: NonNullable<HuaUxConfig['branding']> | null;
+  children: React.ReactNode;
+}) {
+  // SSR 시 초기 CSS 변수 주입 (FOUC 방지)
+  // Inject initial CSS variables on SSR (prevent FOUC)
+  // Next.js의 suppressHydrationWarning을 사용하여 클라이언트 하이드레이션 시 경고 방지
+  // Use Next.js suppressHydrationWarning to prevent warnings during client hydration
+  const cssVarsString = React.useMemo(() => {
+    if (!branding) return '';
+    return generateCSSVariables(branding);
+  }, [branding]);
+
+  // 클라이언트 사이드에서 CSS 변수 동적 업데이트
+  // Dynamically update CSS variables on client side
+  React.useEffect(() => {
+    if (!branding || !cssVarsString) return;
+
+    // style 태그 생성 또는 업데이트
+    // Create or update style tag
+    const styleId = 'hua-ux-branding-vars';
+    let styleElement = document.getElementById(styleId) as HTMLStyleElement;
+    
+    if (!styleElement) {
+      styleElement = document.createElement('style');
+      styleElement.id = styleId;
+      document.head.appendChild(styleElement);
+    }
+    
+    styleElement.textContent = cssVarsString;
+
+    // Cleanup
+    return () => {
+      const element = document.getElementById(styleId);
+      if (element) {
+        element.remove();
+      }
+    };
+  }, [branding, cssVarsString]);
+
+  return (
+    <BrandingContext.Provider value={{ branding }}>
+      {/* SSR 시 초기 CSS 변수 주입 (FOUC 방지) */}
+      {/* Inject initial CSS variables on SSR (prevent FOUC) */}
+      {cssVarsString && (
+        <style
+          id="hua-ux-branding-vars"
+          dangerouslySetInnerHTML={{ __html: cssVarsString }}
+          suppressHydrationWarning
+        />
+      )}
+      {children}
+    </BrandingContext.Provider>
+  );
+}
+
+/**
+ * useBranding hook
+ * 
+ * 브랜딩 설정을 가져오는 훅입니다.
+ * 
+ * @returns Branding configuration or null
+ * 
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const branding = useBranding();
+ *   const primaryColor = branding?.colors?.primary || 'blue';
+ *   return <div style={{ color: primaryColor }}>Hello</div>;
+ * }
+ * ```
+ */
+export function useBranding(): NonNullable<HuaUxConfig['branding']> | null {
+  const { branding } = useContext(BrandingContext);
+  return branding;
+}
+
+/**
+ * Get color from branding
+ * 
+ * 브랜딩에서 색상을 가져옵니다. 없으면 기본값을 반환합니다.
+ * 
+ * @param colorKey - Color key (primary, secondary, etc.)
+ * @param defaultValue - Default color if not found
+ * @returns Color value
+ */
+export function useBrandingColor(
+  colorKey: keyof NonNullable<NonNullable<HuaUxConfig['branding']>['colors']>,
+  defaultValue?: string
+): string | undefined {
+  const branding = useBranding();
+  return branding?.colors?.[colorKey] || defaultValue;
+}

package/src/framework/branding/css-vars.ts

@@ -0,0 +1,110 @@
+/**
+ * @hua-labs/hua-ux/framework - CSS Variables Generator
+ * 
+ * 브랜딩 설정을 CSS 변수로 자동 생성
+ */
+
+import type { HuaUxConfig } from '../types';
+
+/**
+ * Generate CSS variables from branding configuration
+ * 
+ * 브랜딩 설정을 CSS 변수 문자열로 변환합니다.
+ * 
+ * @param branding - Branding configuration
+ * @returns CSS variables string
+ * 
+ * @example
+ * ```ts
+ * const css = generateCSSVariables({
+ *   colors: { primary: '#3B82F6' },
+ *   typography: { fontFamily: ['Inter', 'sans-serif'] },
+ * });
+ * // Returns: ":root {\n  --color-primary: #3B82F6;\n  --font-family: Inter, sans-serif;\n}"
+ * ```
+ */
+export function generateCSSVariables(branding: NonNullable<HuaUxConfig['branding']>): string {
+  const vars: string[] = [];
+  
+  // 색상 변수
+  if (branding.colors) {
+    Object.entries(branding.colors).forEach(([key, value]) => {
+      if (value) {
+        vars.push(`  --color-${key}: ${value};`);
+      }
+    });
+  }
+  
+  // 타이포그래피 변수
+  if (branding.typography) {
+    if (branding.typography.fontFamily) {
+      vars.push(`  --font-family: ${branding.typography.fontFamily.join(', ')};`);
+    }
+    if (branding.typography.fontSize) {
+      Object.entries(branding.typography.fontSize).forEach(([key, value]) => {
+        if (value) {
+          vars.push(`  --font-size-${key}: ${value};`);
+        }
+      });
+    }
+  }
+  
+  // 커스텀 변수
+  if (branding.customVariables) {
+    Object.entries(branding.customVariables).forEach(([key, value]) => {
+      vars.push(`  --${key}: ${value};`);
+    });
+  }
+  
+  if (vars.length === 0) {
+    return '';
+  }
+  
+  return `:root {\n${vars.join('\n')}\n}`;
+}
+
+/**
+ * Generate CSS variables as object
+ * 
+ * 브랜딩 설정을 CSS 변수 객체로 변환합니다.
+ * 
+ * @param branding - Branding configuration
+ * @returns CSS variables object
+ */
+export function generateCSSVariablesObject(
+  branding: NonNullable<HuaUxConfig['branding']>
+): Record<string, string> {
+  const vars: Record<string, string> = {};
+  
+  // 색상 변수
+  if (branding.colors) {
+    Object.entries(branding.colors).forEach(([key, value]) => {
+      if (value) {
+        vars[`--color-${key}`] = value;
+      }
+    });
+  }
+  
+  // 타이포그래피 변수
+  if (branding.typography) {
+    if (branding.typography.fontFamily) {
+      vars['--font-family'] = branding.typography.fontFamily.join(', ');
+    }
+    if (branding.typography.fontSize) {
+      Object.entries(branding.typography.fontSize).forEach(([key, value]) => {
+        if (value) {
+          vars[`--font-size-${key}`] = value;
+        }
+      });
+    }
+  }
+  
+  // 커스텀 변수
+  if (branding.customVariables) {
+    Object.entries(branding.customVariables).forEach(([key, value]) => {
+      vars[`--${key}`] = value;
+    });
+  }
+  
+  return vars;
+}

package/src/framework/branding/tailwind-config.ts

@@ -0,0 +1,90 @@
+/**
+ * @hua-labs/hua-ux/framework - Tailwind Config Generator
+ * 
+ * 브랜딩 설정을 Tailwind Config로 자동 생성
+ */
+
+import type { HuaUxConfig } from '../types';
+
+/**
+ * Generate Tailwind config from branding configuration
+ * 
+ * 브랜딩 설정을 Tailwind Config 객체로 변환합니다.
+ * 
+ * @param branding - Branding configuration
+ * @returns Tailwind config object
+ * 
+ * @example
+ * ```ts
+ * const tailwindConfig = generateTailwindConfig({
+ *   colors: { primary: '#3B82F6' },
+ *   typography: { fontFamily: ['Inter', 'sans-serif'] },
+ * });
+ * 
+ * // Use in tailwind.config.js:
+ * module.exports = {
+ *   ...tailwindConfig,
+ *   // ... other config
+ * };
+ * ```
+ */
+export function generateTailwindConfig(
+  branding: NonNullable<HuaUxConfig['branding']>
+): {
+  theme: {
+    extend: {
+      colors?: Record<string, string>;
+      fontFamily?: Record<string, string[]>;
+      fontSize?: Record<string, string>;
+    };
+  };
+} {
+  const config: {
+    theme: {
+      extend: {
+        colors?: Record<string, string>;
+        fontFamily?: Record<string, string[]>;
+        fontSize?: Record<string, string>;
+      };
+    };
+  } = {
+    theme: {
+      extend: {},
+    },
+  };
+  
+  // 색상 설정
+  if (branding.colors) {
+    const colors: Record<string, string> = {};
+    Object.entries(branding.colors).forEach(([key, value]) => {
+      if (value) {
+        colors[key] = value;
+      }
+    });
+    if (Object.keys(colors).length > 0) {
+      config.theme.extend.colors = colors;
+    }
+  }
+  
+  // 타이포그래피 설정
+  if (branding.typography) {
+    if (branding.typography.fontFamily) {
+      config.theme.extend.fontFamily = {
+        sans: branding.typography.fontFamily,
+      };
+    }
+    if (branding.typography.fontSize) {
+      const fontSize: Record<string, string> = {};
+      Object.entries(branding.typography.fontSize).forEach(([key, value]) => {
+        if (value) {
+          fontSize[key] = value;
+        }
+      });
+      if (Object.keys(fontSize).length > 0) {
+        config.theme.extend.fontSize = fontSize;
+      }
+    }
+  }
+  
+  return config;
+}