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

package/src/framework/components/BrandedButton.tsx

@@ -0,0 +1,94 @@
+/**
+ * @hua-labs/hua-ux/framework - BrandedButton
+ * 
+ * Button 컴포넌트에 branding을 자동으로 적용하는 wrapper
+ * Wrapper that automatically applies branding to Button component
+ * 
+ * CSS 변수를 사용하여 Tailwind의 최적화를 활용합니다.
+ * Uses CSS variables to leverage Tailwind's optimization.
+ */
+
+'use client';
+
+import * as React from 'react';
+import type { ComponentPropsWithoutRef } from 'react';
+import { Button, merge } from '@hua-labs/ui';
+import { useBranding } from '../branding/context';
+
+/**
+ * BrandedButton Component
+ * 
+ * Button 컴포넌트에 branding 설정을 자동으로 적용합니다.
+ * Automatically applies branding configuration to Button component.
+ * 
+ * **자동 적용되는 branding**:
+ * - Primary 색상: `variant="default"`일 때 `bg-[var(--color-primary)]` 사용
+ * - Secondary 색상: `variant="secondary"`일 때 `bg-[var(--color-secondary)]` 사용
+ * - Accent 색상: `variant="outline"`일 때 `border-[var(--color-accent)]` 사용
+ * 
+ * **Auto-applied branding**:
+ * - Primary color: Uses `bg-[var(--color-primary)]` when `variant="default"`
+ * - Secondary color: Uses `bg-[var(--color-secondary)]` when `variant="secondary"`
+ * - Accent color: Uses `border-[var(--color-accent)]` when `variant="outline"`
+ * 
+ * **CSS 변수 방식의 장점**:
+ * - Tailwind의 JIT 컴파일러 최적화 활용
+ * - 인라인 스타일 없이 깔끔한 코드
+ * - 런타임에 동적으로 색상 변경 가능
+ * 
+ * **Advantages of CSS variables**:
+ * - Leverages Tailwind's JIT compiler optimization
+ * - Clean code without inline styles
+ * - Dynamic color changes at runtime
+ * 
+ * @example
+ * ```tsx
+ * // branding 설정이 있으면 자동으로 primary 색상 적용
+ * // Automatically applies primary color if branding is configured
+ * <BrandedButton variant="default">저장</BrandedButton>
+ * 
+ * // branding이 없으면 기본 Button과 동일하게 동작
+ * // Works same as default Button if branding is not configured
+ * <BrandedButton variant="outline">취소</BrandedButton>
+ * ```
+ */
+type BrandedButtonProps = ComponentPropsWithoutRef<typeof Button>;
+
+export const BrandedButton = React.forwardRef<
+  HTMLButtonElement | HTMLAnchorElement,
+  BrandedButtonProps
+>((props: BrandedButtonProps, ref: React.ForwardedRef<HTMLButtonElement | HTMLAnchorElement>) => {
+  const { variant = 'default', className, ...restProps } = props;
+  const branding = useBranding();
+
+  // Branding 색상이 있으면 Tailwind arbitrary values 사용
+  // Use Tailwind arbitrary values if branding colors exist
+  let brandingClasses = '';
+
+  if (branding?.colors) {
+    if (variant === 'default' && branding.colors.primary) {
+      // Primary 색상을 배경으로 사용
+      // Use primary color as background
+      brandingClasses = 'bg-[var(--color-primary)] text-white border-[var(--color-primary)] hover:opacity-90';
+    } else if (variant === 'secondary' && branding.colors.secondary) {
+      // Secondary 색상을 배경으로 사용
+      // Use secondary color as background
+      brandingClasses = 'bg-[var(--color-secondary)] text-white border-[var(--color-secondary)] hover:opacity-90';
+    } else if (variant === 'outline' && branding.colors.accent) {
+      // Accent 색상을 테두리와 텍스트로 사용
+      // Use accent color for border and text
+      brandingClasses = 'border-[var(--color-accent)] text-[var(--color-accent)] bg-transparent hover:bg-[var(--color-accent)]/10';
+    }
+  }
+
+  return (
+    <Button
+      ref={ref}
+      variant={variant}
+      className={merge(brandingClasses, className)}
+      {...restProps}
+    />
+  );
+});
+
+BrandedButton.displayName = 'BrandedButton';

package/src/framework/components/BrandedCard.tsx

@@ -0,0 +1,87 @@
+/**
+ * @hua-labs/hua-ux/framework - BrandedCard
+ * 
+ * Card 컴포넌트에 branding을 자동으로 적용하는 wrapper
+ * Wrapper that automatically applies branding to Card component
+ * 
+ * CSS 변수를 사용하여 Tailwind의 최적화를 활용합니다.
+ * Uses CSS variables to leverage Tailwind's optimization.
+ */
+
+'use client';
+
+import React from 'react';
+import { Card, merge, type CardProps } from '@hua-labs/ui';
+import { useBranding } from '../branding/context';
+
+/**
+ * BrandedCard Component
+ * 
+ * Card 컴포넌트에 branding 설정을 자동으로 적용합니다.
+ * Automatically applies branding configuration to Card component.
+ * 
+ * **자동 적용되는 branding**:
+ * - Accent 색상: `variant="outline"`일 때 `border-[var(--color-accent)]` 사용
+ * - Primary 색상: `variant="default"`일 때 `bg-[var(--color-primary)]/5` 사용
+ * 
+ * **Auto-applied branding**:
+ * - Accent color: Uses `border-[var(--color-accent)]` when `variant="outline"`
+ * - Primary color: Uses `bg-[var(--color-primary)]/5` when `variant="default"`
+ * 
+ * **CSS 변수 방식의 장점**:
+ * - Tailwind의 JIT 컴파일러 최적화 활용
+ * - 인라인 스타일 없이 깔끔한 코드
+ * - 런타임에 동적으로 색상 변경 가능
+ * 
+ * **Advantages of CSS variables**:
+ * - Leverages Tailwind's JIT compiler optimization
+ * - Clean code without inline styles
+ * - Dynamic color changes at runtime
+ * 
+ * @example
+ * ```tsx
+ * // branding 설정이 있으면 자동으로 색상 적용
+ * // Automatically applies colors if branding is configured
+ * <BrandedCard variant="outline">
+ *   <CardContent>내용</CardContent>
+ * </BrandedCard>
+ * 
+ * // branding이 없으면 기본 Card와 동일하게 동작
+ * // Works same as default Card if branding is not configured
+ * <BrandedCard variant="elevated">
+ *   <CardContent>내용</CardContent>
+ * </BrandedCard>
+ * ```
+ */
+export const BrandedCard = React.forwardRef<HTMLDivElement, CardProps>(
+  ({ variant = 'default', className, ...props }, ref) => {
+    const branding = useBranding();
+
+    // Branding 색상이 있으면 Tailwind arbitrary values 사용
+    // Use Tailwind arbitrary values if branding colors exist
+    let brandingClasses = '';
+
+    if (branding?.colors) {
+      if (variant === 'outline' && branding.colors.accent) {
+        // Accent 색상을 테두리로 사용
+        // Use accent color as border
+        brandingClasses = 'border-[var(--color-accent)]';
+      } else if (variant === 'default' && branding.colors.primary) {
+        // Primary 색상의 약간의 tint를 배경에 적용
+        // Apply slight tint of primary color to background
+        brandingClasses = 'bg-[var(--color-primary)]/5';
+      }
+    }
+
+    return (
+      <Card
+        ref={ref}
+        variant={variant}
+        className={merge(brandingClasses, className)}
+        {...props}
+      />
+    );
+  }
+);
+
+BrandedCard.displayName = 'BrandedCard';

package/src/framework/components/ErrorBoundary.tsx

@@ -0,0 +1,215 @@
+/**
+ * @hua-labs/hua-ux/framework - ErrorBoundary
+ *
+ * React Error Boundary component for catching and handling errors
+ */
+
+'use client';
+
+import React, { Component, ReactNode, ErrorInfo } from 'react';
+
+/**
+ * Global error reporter interface
+ * 
+ * 프로덕션 환경에서 에러 리포팅 서비스(Sentry, LogRocket 등)와 통합하기 위한 인터페이스
+ * Interface for integrating with error reporting services (Sentry, LogRocket, etc.) in production
+ * 
+ * @example
+ * ```ts
+ * // Sentry 통합 예시
+ * window.__ERROR_REPORTER__ = (error, errorInfo) => {
+ *   Sentry.captureException(error, {
+ *     contexts: { react: errorInfo },
+ *   });
+ * };
+ * ```
+ */
+declare global {
+  interface Window {
+    __ERROR_REPORTER__?: (error: Error, errorInfo: ErrorInfo) => void;
+  }
+}
+
+/**
+ * Error Boundary Props
+ */
+export interface ErrorBoundaryProps {
+  /**
+   * Children to render
+   */
+  children: ReactNode;
+
+  /**
+   * Fallback UI to show when error occurs
+   * Can be a ReactNode or a function that receives error and reset callback
+   */
+  fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+
+  /**
+   * Callback when error is caught
+   */
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+
+  /**
+   * Custom error filter - return true to catch, false to rethrow
+   */
+  onReset?: () => void;
+}
+
+/**
+ * Error Boundary State
+ */
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+/**
+ * Default fallback UI
+ */
+function DefaultFallback({ error, reset }: { error: Error; reset: () => void }) {
+  return (
+    <div
+      role="alert"
+      style={{
+        padding: '2rem',
+        margin: '2rem auto',
+        maxWidth: '600px',
+        border: '1px solid #ef4444',
+        borderRadius: '0.5rem',
+        backgroundColor: '#fef2f2',
+        color: '#991b1b',
+      }}
+    >
+      <h2 style={{ fontSize: '1.5rem', fontWeight: 'bold', marginBottom: '1rem' }}>
+        ⚠️ 오류가 발생했습니다 / An error occurred
+      </h2>
+      <details style={{ marginBottom: '1rem' }}>
+        <summary style={{ cursor: 'pointer', fontWeight: 500 }}>
+          에러 상세 정보 / Error details
+        </summary>
+        <pre
+          style={{
+            marginTop: '0.5rem',
+            padding: '1rem',
+            backgroundColor: '#fee2e2',
+            borderRadius: '0.25rem',
+            overflow: 'auto',
+            fontSize: '0.875rem',
+          }}
+        >
+          {error.message}
+        </pre>
+      </details>
+      <button
+        onClick={reset}
+        style={{
+          padding: '0.5rem 1rem',
+          backgroundColor: '#dc2626',
+          color: 'white',
+          border: 'none',
+          borderRadius: '0.25rem',
+          cursor: 'pointer',
+          fontWeight: 500,
+        }}
+      >
+        🔄 다시 시도 / Try again
+      </button>
+    </div>
+  );
+}
+
+/**
+ * Error Boundary Component
+ *
+ * Catches JavaScript errors anywhere in the child component tree,
+ * logs those errors, and displays a fallback UI.
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary fallback={<div>Something went wrong</div>}>
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary
+ *   fallback={(error, reset) => (
+ *     <div>
+ *       <h1>Error: {error.message}</h1>
+ *       <button onClick={reset}>Try again</button>
+ *     </div>
+ *   )}
+ * >
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    // Update state so the next render will show the fallback UI
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+    // 개발 모드: 콘솔에 에러 로그
+    // Development mode: Log error to console
+    if (process.env.NODE_ENV === 'development') {
+      console.error('[ErrorBoundary] Caught error:', error);
+      console.error('[ErrorBoundary] Error info:', errorInfo);
+    }
+
+    // 프로덕션 모드: 에러 리포팅 서비스 통합 (선택적)
+    // Production mode: Integrate with error reporting service (optional)
+    if (process.env.NODE_ENV === 'production') {
+      // 전역 에러 리포터가 설정되어 있으면 사용
+      // Use global error reporter if configured
+      if (typeof window !== 'undefined' && window.__ERROR_REPORTER__) {
+        try {
+          window.__ERROR_REPORTER__(error, errorInfo);
+        } catch (reportingError) {
+          // 에러 리포팅 자체가 실패해도 앱은 계속 동작해야 함
+          // App should continue working even if error reporting fails
+          console.error('[ErrorBoundary] Error reporting failed:', reportingError);
+        }
+      }
+    }
+
+    // Call onError callback if provided
+    this.props.onError?.(error, errorInfo);
+  }
+
+  reset = (): void => {
+    // Call onReset callback if provided
+    this.props.onReset?.();
+
+    // Reset error state
+    this.setState({ hasError: false, error: null });
+  };
+
+  render(): ReactNode {
+    if (this.state.hasError && this.state.error) {
+      // Render fallback UI
+      const { fallback } = this.props;
+
+      if (typeof fallback === 'function') {
+        return fallback(this.state.error, this.reset);
+      }
+
+      if (fallback) {
+        return fallback;
+      }
+
+      // Default fallback
+      return <DefaultFallback error={this.state.error} reset={this.reset} />;
+    }
+
+    return this.props.children;
+  }
+}

package/src/framework/components/HuaUxLayout.tsx

@@ -0,0 +1,36 @@
+/**
+ * @hua-labs/hua-ux/framework - HuaUxLayout
+ * 
+ * Root layout wrapper that automatically sets up all providers
+ */
+
+'use client';
+
+import React from 'react';
+import type { HuaUxLayoutProps } from '../types';
+import { UnifiedProviders } from './Providers';
+
+/**
+ * HuaUxLayout Component
+ * 
+ * Automatically configures i18n, motion, and state providers based on configuration.
+ * 
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { HuaUxLayout } from '@hua-labs/hua-ux/framework';
+ * 
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html lang="ko">
+ *       <body>
+ *         <HuaUxLayout>{children}</HuaUxLayout>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+export function HuaUxLayout({ children, config }: HuaUxLayoutProps) {
+  return <UnifiedProviders config={config}>{children}</UnifiedProviders>;
+}

package/src/framework/components/HuaUxPage.tsx

@@ -0,0 +1,138 @@
+/**
+ * @hua-labs/hua-ux/framework - HuaUxPage
+ * 
+ * Page wrapper with automatic motion and i18n support
+ */
+
+'use client';
+
+import React from 'react';
+import type { HuaUxPageProps } from '../types';
+import { getConfig } from '../config';
+import { useMotion } from '../hooks/useMotion';
+import { ErrorBoundary } from './ErrorBoundary';
+
+/**
+ * HuaUxPage Component
+ * 
+ * 페이지 콘텐츠를 자동 모션 애니메이션과 i18n 지원으로 감싸는 컴포넌트입니다.
+ * Wraps page content with automatic motion animations and i18n support.
+ * 
+ * **바이브 코딩 친화적 / Vibe Coding Friendly**:
+ * - 한 파일에서 SEO, Motion, i18n을 모두 결정할 수 있습니다.
+ * - You can decide SEO, Motion, and i18n all in one file.
+ * - AI가 파일 하나만 보고도 완벽한 페이지를 생성할 수 있습니다.
+ * - AI can generate a perfect page by looking at just one file.
+ * 
+ * @example
+ * ```tsx
+ * // app/page.tsx
+ * import { HuaUxPage } from '@hua-labs/hua-ux/framework';
+ * 
+ * export default function HomePage() {
+ *   return (
+ *     <HuaUxPage
+ *       vibe="clean"
+ *       i18nKey="home"
+ *       title="홈"
+ *       description="환영합니다"
+ *     >
+ *       <h1>Welcome</h1>
+ *     </HuaUxPage>
+ *   );
+ * }
+ * ```
+ * 
+ * @example
+ * ```tsx
+ * // 바이브 코더용: vibe만으로 스타일 결정
+ * // For vibe coders: decide style with just vibe
+ * <HuaUxPage vibe="fancy">
+ *   <div>화려한 인터랙션이 자동 적용됩니다</div>
+ * </HuaUxPage>
+ * ```
+ */
+export function HuaUxPage({
+  children,
+  title,
+  description,
+  vibe,
+  i18nKey,
+  enableMotion = true,
+  enableErrorBoundary = true,
+  errorBoundaryFallback,
+  seo,
+  motion,
+}: HuaUxPageProps) {
+  const config = getConfig();
+
+  // vibe에 따라 모션 설정 조정
+  // Adjust motion settings based on vibe
+  const motionDuration = vibe === 'fancy' ? 800 : vibe === 'minimal' ? 300 : 600;
+  const shouldEnableMotion = enableMotion && config.motion?.enableAnimations !== false;
+
+  // motion prop 또는 vibe에 따라 모션 타입 결정
+  // Determine motion type based on motion prop or vibe
+  const motionType = motion || (vibe === 'fancy' ? 'slideUp' : vibe === 'minimal' ? 'fadeIn' : 'fadeIn');
+
+  // 통합 Motion Hook 사용 (성능 최적화)
+  // Use unified Motion Hook (performance optimization)
+  // Note: React Rules of Hooks를 준수하기 위해 내부적으로 모든 hook을 호출하지만,
+  // 실제로는 선택된 hook만 활성화되어 성능 오버헤드를 최소화합니다.
+  // Note: All hooks are called internally to respect React Rules of Hooks,
+  // but only the selected hook is actually activated to minimize performance overhead.
+  const motionResult = useMotion<HTMLDivElement>({
+    type: motionType,
+    duration: motionDuration,
+    autoStart: false, // 수동으로 start 호출
+  });
+
+  // Start the selected motion if enabled
+  // 모션이 활성화된 경우 선택된 모션 시작
+  React.useEffect(() => {
+    if (shouldEnableMotion) {
+      motionResult.start?.();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [shouldEnableMotion]); // motionResult.start는 안정적인 함수이므로 dependency에서 제외
+  const pageRef = motionResult.ref;
+
+  // SEO 메타데이터는 Next.js App Router에서 page.tsx의 export const metadata로 처리하는 것이 권장됩니다.
+  // 이 컴포넌트는 Client Component이므로 메타데이터를 직접 설정할 수 없습니다.
+  // SEO 설정이 있으면 개발자에게 경고 메시지 표시 (개발 모드에서만)
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === 'development' && seo) {
+      console.warn(
+        '[HuaUxPage] SEO metadata should be set using `export const metadata` in page.tsx.\n' +
+        'Use `generatePageMetadata()` helper function from @hua-labs/hua-ux/framework'
+      );
+    }
+  }, [seo]);
+
+  // i18nKey가 있으면 해당 네임스페이스를 자동으로 로드하도록 안내
+  // (실제 로드는 I18nProvider에서 자동 처리됨)
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === 'development' && i18nKey) {
+      // i18nKey가 설정되어 있으면 해당 네임스페이스가 자동으로 로드됩니다.
+      // 번역 키는 `${i18nKey}:title`, `${i18nKey}:description` 형식으로 사용할 수 있습니다.
+      // Translation keys can be used in the format `${i18nKey}:title`, `${i18nKey}:description`
+    }
+  }, [i18nKey]);
+
+  const pageContent = (
+    <div ref={pageRef} style={motionResult.style}>
+      {children}
+    </div>
+  );
+
+  // Wrap with ErrorBoundary if enabled
+  if (enableErrorBoundary) {
+    return (
+      <ErrorBoundary fallback={errorBoundaryFallback}>
+        {pageContent}
+      </ErrorBoundary>
+    );
+  }
+
+  return pageContent;
+}

package/src/framework/components/Providers.tsx

@@ -0,0 +1,98 @@
+/**
+ * @hua-labs/hua-ux/framework - Providers
+ * 
+ * Unified providers for i18n, motion, and state
+ */
+
+'use client';
+
+import React from 'react';
+import type { ReactNode } from 'react';
+import type { HuaUxConfig } from '../types';
+import { getConfig } from '../config';
+import { createZustandI18n } from '@hua-labs/i18n-core-zustand';
+import { createI18nStore } from '@hua-labs/state';
+import { BrandingProvider } from '../branding/context';
+
+/**
+ * Create providers based on configuration
+ * 
+ * Provider 체인을 생성합니다. Branding Provider는 가장 바깥쪽에 위치하여
+ * 다른 Provider들이 브랜딩 설정을 사용할 수 있도록 합니다.
+ * 
+ * Creates a provider chain. Branding Provider is placed at the outermost level
+ * so other providers can use branding configuration.
+ */
+function createProviders(config: HuaUxConfig) {
+  const providers: React.ComponentType<{ children: ReactNode }>[] = [];
+
+  // Branding Provider를 먼저 추가 (다른 Provider들이 사용 가능하도록)
+  // Add Branding Provider first (so other providers can use it)
+  if (config.branding) {
+    providers.push(({ children }) => (
+      <BrandingProvider branding={config.branding || null}>{children}</BrandingProvider>
+    ));
+  }
+
+  // i18n Provider
+  if (config.i18n) {
+    const i18nStore = createI18nStore({
+      defaultLanguage: config.i18n.defaultLanguage,
+      supportedLanguages: config.i18n.supportedLanguages,
+      persist: config.state?.persist ?? true,
+      ssr: config.state?.ssr ?? true,
+    });
+
+    // Type assertion: I18nStoreState extends ZustandLanguageStore, so this is safe
+    const I18nProvider = createZustandI18n(
+      i18nStore as any, // Type assertion needed due to Zustand's complex type system
+      {
+        fallbackLanguage: config.i18n.fallbackLanguage || 'en',
+        namespaces: config.i18n.namespaces || ['common'],
+        translationLoader: config.i18n.translationLoader || 'api',
+        translationApiPath: config.i18n.translationApiPath || '/api/translations',
+        defaultLanguage: config.i18n.defaultLanguage,
+        loadTranslations: config.i18n.loadTranslations,
+        debug: config.i18n.debug,
+      }
+    );
+
+    providers.push(I18nProvider);
+  }
+
+  // Return a combined provider
+  return function CombinedProvider({ children }: { children: ReactNode }) {
+    // Provider 체인 생성 (Branding Provider가 가장 바깥쪽)
+    // Create provider chain (Branding Provider is outermost)
+    const wrapped = providers.reduceRight(
+      (acc, Provider) => <Provider>{acc}</Provider>,
+      children
+    );
+
+    return wrapped;
+  };
+}
+
+/**
+ * UnifiedProviders component
+ * 
+ * Automatically creates and wraps children with all necessary providers
+ */
+export function UnifiedProviders({
+  children,
+  config: overrideConfig,
+}: {
+  children: ReactNode;
+  config?: Partial<HuaUxConfig>;
+}) {
+  const baseConfig = getConfig();
+  const config = overrideConfig
+    ? { ...baseConfig, ...overrideConfig }
+    : baseConfig;
+
+  const Provider = React.useMemo(() => createProviders(config), [config]);
+
+  // Provider 체인은 createProviders 내부에서 처리됨
+  // Provider chain is handled inside createProviders
+  return <Provider>{children}</Provider>;
+}