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

package/src/framework/__tests__/seo/geo/structuredData.test.ts

@@ -0,0 +1,262 @@
+/**
+ * @hua-labs/hua-ux/framework - Structured Data Tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  generateSoftwareApplicationLD,
+  generateFAQPageLD,
+  generateTechArticleLD,
+  generateHowToLD,
+} from '../../../seo/geo/structuredData';
+import type { GEOConfig } from '../../../seo/geo/types';
+
+describe('generateSoftwareApplicationLD', () => {
+  const baseConfig: GEOConfig = {
+    name: 'Test App',
+    description: 'A test application',
+  };
+
+  it('should generate basic SoftwareApplication JSON-LD', () => {
+    const result = generateSoftwareApplicationLD(baseConfig);
+
+    expect(result['@context']).toBe('https://schema.org');
+    expect(result['@type']).toBe('SoftwareApplication');
+    expect(result.name).toBe('Test App');
+    expect(result.description).toBe('A test application');
+  });
+
+  it('should include alternate names', () => {
+    const config: GEOConfig = {
+      ...baseConfig,
+      alternateName: ['test-app', '@test/app'],
+    };
+
+    const result = generateSoftwareApplicationLD(config);
+
+    expect(result.alternateName).toEqual(['test-app', '@test/app']);
+  });
+
+  it('should include version', () => {
+    const config: GEOConfig = {
+      ...baseConfig,
+      version: '1.0.0',
+    };
+
+    const result = generateSoftwareApplicationLD(config);
+
+    expect(result.softwareVersion).toBe('1.0.0');
+  });
+
+  it('should include application category', () => {
+    const config: GEOConfig = {
+      ...baseConfig,
+      applicationCategory: 'UX Framework',
+    };
+
+    const result = generateSoftwareApplicationLD(config);
+
+    expect(result.applicationCategory).toBe('UX Framework');
+  });
+
+  it('should handle multiple application categories', () => {
+    const config: GEOConfig = {
+      ...baseConfig,
+      applicationCategory: ['UX Framework', 'Developer Tool'],
+    };
+
+    const result = generateSoftwareApplicationLD(config);
+
+    expect(result.applicationCategory).toBe('UX Framework, Developer Tool');
+  });
+
+  it('should include programming language', () => {
+    const config: GEOConfig = {
+      ...baseConfig,
+      programmingLanguage: 'TypeScript',
+    };
+
+    const result = generateSoftwareApplicationLD(config);
+
+    expect(result.programmingLanguage).toBe('TypeScript');
+  });
+
+  it('should include URLs', () => {
+    const config: GEOConfig = {
+      ...baseConfig,
+      url: 'https://example.com',
+      documentationUrl: 'https://example.com/docs',
+      codeRepository: 'https://github.com/example/app',
+    };
+
+    const result = generateSoftwareApplicationLD(config);
+
+    expect(result.url).toBe('https://example.com');
+    expect(result.softwareHelp).toBeDefined();
+    expect(result.softwareHelp?.['@type']).toBe('CreativeWork');
+    expect(result.codeRepository).toBe('https://github.com/example/app');
+  });
+
+  it('should include license', () => {
+    const config: GEOConfig = {
+      ...baseConfig,
+      license: 'MIT',
+    };
+
+    const result = generateSoftwareApplicationLD(config);
+
+    expect(result.license).toBe('MIT');
+  });
+
+  it('should include author', () => {
+    const config: GEOConfig = {
+      ...baseConfig,
+      author: {
+        name: 'Test Author',
+        url: 'https://example.com/author',
+      },
+    };
+
+    const result = generateSoftwareApplicationLD(config);
+
+    expect(result.author).toBeDefined();
+    expect(result.author?.['@type']).toBe('Organization');
+    expect(result.author?.name).toBe('Test Author');
+    expect(result.author?.url).toBe('https://example.com/author');
+  });
+
+  it('should include features', () => {
+    const config: GEOConfig = {
+      ...baseConfig,
+      features: ['i18n', 'Motion', 'Accessibility'],
+    };
+
+    const result = generateSoftwareApplicationLD(config);
+
+    expect(result.featureList).toBe('i18n, Motion, Accessibility');
+  });
+
+  it('should include keywords', () => {
+    const config: GEOConfig = {
+      ...baseConfig,
+      keywords: ['react', 'nextjs'],
+    };
+
+    const result = generateSoftwareApplicationLD(config);
+
+    expect(result.keywords).toBe('react, nextjs');
+  });
+});
+
+describe('generateFAQPageLD', () => {
+  it('should generate FAQPage JSON-LD', () => {
+    const faqs = [
+      { question: 'What is it?', answer: 'It is a test app' },
+      { question: 'How to use?', answer: 'Just use it' },
+    ];
+
+    const result = generateFAQPageLD(faqs);
+
+    expect(result['@context']).toBe('https://schema.org');
+    expect(result['@type']).toBe('FAQPage');
+    expect(result.mainEntity).toBeDefined();
+    expect(result.mainEntity.length).toBe(2);
+  });
+
+  it('should format FAQ items correctly', () => {
+    const faqs = [
+      { question: 'What is it?', answer: 'It is a test app' },
+    ];
+
+    const result = generateFAQPageLD(faqs);
+
+    const question = result.mainEntity[0];
+    expect(question['@type']).toBe('Question');
+    expect(question.name).toBe('What is it?');
+    expect(question.acceptedAnswer['@type']).toBe('Answer');
+    expect(question.acceptedAnswer.text).toBe('It is a test app');
+  });
+});
+
+describe('generateTechArticleLD', () => {
+  it('should generate TechArticle JSON-LD', () => {
+    const article = {
+      headline: 'Test Article',
+      description: 'A test article',
+      datePublished: '2025-12-29',
+      author: { name: 'Test Author' },
+    };
+
+    const result = generateTechArticleLD(article);
+
+    expect(result['@context']).toBe('https://schema.org');
+    expect(result['@type']).toBe('TechArticle');
+    expect(result.headline).toBe('Test Article');
+    expect(result.description).toBe('A test article');
+    expect(result.datePublished).toBe('2025-12-29');
+  });
+
+  it('should include optional fields', () => {
+    const article = {
+      headline: 'Test Article',
+      dateModified: '2025-12-30',
+      image: 'https://example.com/image.jpg',
+    };
+
+    const result = generateTechArticleLD(article);
+
+    expect(result.dateModified).toBe('2025-12-30');
+    expect(result.image).toBe('https://example.com/image.jpg');
+  });
+});
+
+describe('generateHowToLD', () => {
+  it('should generate HowTo JSON-LD', () => {
+    const howTo = {
+      name: 'How to test',
+      description: 'A test guide',
+      steps: [
+        { name: 'Step 1', text: 'Do this' },
+        { name: 'Step 2', text: 'Do that' },
+      ],
+    };
+
+    const result = generateHowToLD(howTo);
+
+    expect(result['@context']).toBe('https://schema.org');
+    expect(result['@type']).toBe('HowTo');
+    expect(result.name).toBe('How to test');
+    expect(result.description).toBe('A test guide');
+    expect(result.step).toBeDefined();
+    expect(result.step.length).toBe(2);
+  });
+
+  it('should format steps correctly', () => {
+    const howTo = {
+      name: 'How to test',
+      steps: [
+        { name: 'Step 1', text: 'Do this' },
+      ],
+    };
+
+    const result = generateHowToLD(howTo);
+
+    const step = result.step[0];
+    expect(step['@type']).toBe('HowToStep');
+    expect(step.position).toBe(1);
+    expect(step.name).toBe('Step 1');
+    expect(step.text).toBe('Do this');
+  });
+
+  it('should include totalTime when provided', () => {
+    const howTo = {
+      name: 'How to test',
+      steps: [{ name: 'Step 1', text: 'Do this' }],
+      totalTime: 'PT10M',
+    };
+
+    const result = generateHowToLD(howTo);
+
+    expect(result.totalTime).toBe('PT10M');
+  });
+});

package/src/framework/a11y/components/LiveRegion.tsx

@@ -0,0 +1,89 @@
+/**
+ * @hua-labs/hua-ux/framework - LiveRegion
+ * 
+ * 스크린 리더 사용자에게 동적 상태 변화를 알리는 컴포넌트
+ * Component that announces dynamic state changes to screen reader users
+ */
+
+'use client';
+
+import React from 'react';
+
+/**
+ * LiveRegion 컴포넌트 props
+ */
+export interface LiveRegionProps {
+  /**
+   * 알림할 메시지
+   * Message to announce
+   */
+  message?: string;
+  
+  /**
+   * Live region의 politeness 레벨
+   * Politeness level of the live region
+   * 
+   * - 'polite': 현재 작업이 완료된 후 알림 (기본값)
+   * - 'assertive': 즉시 알림
+   * - 'off': 알림 비활성화
+   * 
+   * @default "polite"
+   */
+  politeness?: 'polite' | 'assertive' | 'off';
+  
+  /**
+   * 추가 CSS 클래스
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * LiveRegion 컴포넌트
+ * 
+ * 스크린 리더 사용자에게 동적 상태 변화를 알립니다.
+ * Announces dynamic state changes to screen reader users.
+ * 
+ * @example
+ * ```tsx
+ * function MyForm() {
+ *   const [message, setMessage] = useState('');
+ * 
+ *   const handleSubmit = async () => {
+ *     setMessage('저장 중...');
+ *     await saveData();
+ *     setMessage('저장되었습니다!');
+ *   };
+ * 
+ *   return (
+ *     <div>
+ *       <form onSubmit={handleSubmit}>Form fields</form>
+ *       <LiveRegion message={message} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ * 
+ * @param props - LiveRegion props
+ * @returns LiveRegion 컴포넌트
+ */
+export function LiveRegion({
+  message,
+  politeness = 'polite',
+  className,
+}: LiveRegionProps): React.JSX.Element {
+  // aria-live는 자동으로 업데이트를 감지하므로
+  // 메시지 변경만으로도 알림이 발생합니다.
+  // 별도의 useEffect는 필요하지 않습니다.
+
+  return (
+    <div
+      role="status"
+      aria-live={politeness}
+      aria-atomic="true"
+      className={className || 'sr-only'}
+    >
+      {message}
+    </div>
+  );
+}

package/src/framework/a11y/components/SkipToContent.tsx

@@ -0,0 +1,103 @@
+/**
+ * @hua-labs/hua-ux/framework - SkipToContent
+ * 
+ * 키보드 사용자를 위한 "콘텐츠로 건너뛰기" 링크
+ * "Skip to content" link for keyboard users
+ */
+
+'use client';
+
+import React from 'react';
+
+/**
+ * SkipToContent 컴포넌트 props
+ */
+export interface SkipToContentProps {
+  /**
+   * 메인 콘텐츠의 ID
+   * ID of the main content element
+   * 
+   * @default "main-content"
+   */
+  targetId?: string;
+  
+  /**
+   * 링크 텍스트
+   * Link text
+   * 
+   * @default "Skip to content"
+   */
+  children?: React.ReactNode;
+  
+  /**
+   * 추가 CSS 클래스
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * SkipToContent 컴포넌트
+ * 
+ * 키보드 사용자가 네비게이션을 건너뛰고 메인 콘텐츠로 바로 이동할 수 있도록 합니다.
+ * Allows keyboard users to skip navigation and go directly to main content.
+ * 
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { SkipToContent } from '@hua-labs/hua-ux/framework';
+ * 
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <SkipToContent />
+ *         <nav>Navigation</nav>
+ *         <main id="main-content" tabIndex={-1}>
+ *           {children}
+ *         </main>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ * 
+ * @param props - SkipToContent props
+ * @returns SkipToContent 컴포넌트
+ */
+export function SkipToContent({
+  targetId = 'main-content',
+  children = 'Skip to content',
+  className,
+}: SkipToContentProps): React.JSX.Element {
+  const handleClick = (event: React.MouseEvent<HTMLAnchorElement>) => {
+    event.preventDefault();
+    
+    try {
+      const target = document.getElementById(targetId);
+      if (target) {
+        target.focus();
+        target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      } else if (process.env.NODE_ENV === 'development') {
+        console.warn(`[SkipToContent] Target element with id "${targetId}" not found`);
+      }
+    } catch (error) {
+      // focus() 또는 scrollIntoView() 실패 시 조용히 처리
+      if (process.env.NODE_ENV === 'development') {
+        console.warn('[SkipToContent] Failed to focus or scroll to target:', error);
+      }
+    }
+  };
+
+  const defaultClassName = 'sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-blue-600 focus:text-white focus:rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2';
+
+  return (
+    <a
+      href={`#${targetId}`}
+      onClick={handleClick}
+      className={className || defaultClassName}
+    >
+      {children}
+    </a>
+  );
+}

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

@@ -0,0 +1,125 @@
+/**
+ * @hua-labs/hua-ux/framework - useFocusManagement
+ * 
+ * 페이지 전환 시 자동으로 메인 콘텐츠에 포커스를 이동시키는 hook
+ * Automatically focuses main content on page transitions
+ */
+
+'use client';
+
+import { useEffect, useRef, useMemo, type RefObject } from 'react';
+
+/**
+ * Focus Management 옵션
+ */
+export interface FocusManagementOptions {
+  /**
+   * 마운트 시 자동으로 포커스할지 여부
+   * Whether to automatically focus on mount
+   * 
+   * @default true
+   */
+  autoFocus?: boolean;
+  
+  /**
+   * 포커스할 요소의 선택자 (기본값: 요소 자체)
+   * Selector for element to focus (default: element itself)
+   */
+  focusSelector?: string;
+  
+  /**
+   * 포커스 시 스크롤할지 여부
+   * Whether to scroll when focusing
+   * 
+   * @default false
+   */
+  scrollIntoView?: boolean;
+  
+  /**
+   * 스크롤 옵션 (scrollIntoView가 true일 때)
+   * Scroll options (when scrollIntoView is true)
+   */
+  scrollOptions?: ScrollIntoViewOptions;
+}
+
+/**
+ * Focus Management Hook
+ * 
+ * 페이지 전환 시 자동으로 메인 콘텐츠에 포커스를 이동시킵니다.
+ * Automatically focuses main content on page transitions.
+ * 
+ * @example
+ * ```tsx
+ * function MyPage() {
+ *   const mainRef = useFocusManagement({ autoFocus: true });
+ * 
+ *   return (
+ *     <main ref={mainRef} tabIndex={-1}>
+ *       <h1>Page Title</h1>
+ *     </main>
+ *   );
+ * }
+ * ```
+ * 
+ * @param options - Focus Management 옵션
+ * @returns 요소에 연결할 ref
+ */
+export function useFocusManagement<T extends HTMLElement = HTMLElement>(
+  options: FocusManagementOptions = {}
+): RefObject<T | null> {
+  const {
+    autoFocus = true,
+    focusSelector,
+    scrollIntoView = false,
+    scrollOptions: userScrollOptions,
+  } = options;
+
+  const ref = useRef<T>(null);
+  
+  // scrollOptions 메모이제이션 (객체가 매번 새로 생성되는 것을 방지)
+  const scrollOptions = useMemo<ScrollIntoViewOptions>(
+    () => userScrollOptions ?? { behavior: 'smooth' as const, block: 'start' as const },
+    [userScrollOptions]
+  );
+
+  useEffect(() => {
+    if (!autoFocus || !ref.current) {
+      return;
+    }
+
+    // 포커스할 요소 찾기
+    let elementToFocus: HTMLElement | null = ref.current;
+
+    if (focusSelector) {
+      const found = ref.current.querySelector<HTMLElement>(focusSelector);
+      if (found) {
+        elementToFocus = found;
+      }
+    }
+
+    // 포커스 이동
+    if (elementToFocus) {
+      // 약간의 지연을 두어 렌더링 완료 후 포커스
+      const timeoutId = setTimeout(() => {
+        try {
+          elementToFocus?.focus();
+          
+          if (scrollIntoView && elementToFocus && scrollOptions) {
+            elementToFocus.scrollIntoView(scrollOptions);
+          }
+        } catch (error) {
+          // focus() 실패 시 조용히 처리
+          if (process.env.NODE_ENV === 'development') {
+            console.warn('[useFocusManagement] Failed to focus element:', error);
+          }
+        }
+      }, 0);
+
+      return () => {
+        clearTimeout(timeoutId);
+      };
+    }
+  }, [autoFocus, focusSelector, scrollIntoView, scrollOptions]);
+
+  return ref;
+}