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

package/src/framework/loading/hooks/useDelayedLoading.ts

@@ -0,0 +1,127 @@
+/**
+ * @hua-labs/hua-ux/framework - useDelayedLoading
+ * 
+ * 빠른 API 응답 시 로딩 UI 깜빡임을 방지하는 hook
+ * Prevents loading UI flicker for fast API responses
+ */
+
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Delayed Loading 옵션
+ */
+export interface DelayedLoadingOptions {
+  /**
+   * 로딩 UI를 표시하기 전 대기 시간 (밀리초)
+   * Delay before showing loading UI (milliseconds)
+   * 
+   * @default 300
+   */
+  delay?: number;
+  
+  /**
+   * 최소 표시 시간 (밀리초) - 로딩이 너무 빨리 끝나도 최소한 이 시간은 표시
+   * Minimum display time (milliseconds) - show loading for at least this duration
+   * 
+   * @default 0
+   */
+  minDisplayTime?: number;
+}
+
+/**
+ * useDelayedLoading Hook
+ * 
+ * 빠른 API 응답 시 로딩 UI가 깜빡거리는 것을 방지합니다.
+ * 300ms 이하로 끝나면 로딩 UI를 아예 표시하지 않습니다.
+ * 
+ * Prevents loading UI flicker for fast API responses.
+ * If loading completes within 300ms, the loading UI is not shown at all.
+ * 
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const [isLoading, setIsLoading] = useState(false);
+ *   const showLoading = useDelayedLoading(isLoading);
+ * 
+ *   const fetchData = async () => {
+ *     setIsLoading(true);
+ *     await api.getData(); // 빠르게 끝나면 로딩 UI 안보임
+ *     setIsLoading(false);
+ *   };
+ * 
+ *   return showLoading ? <Spinner /> : <Content />;
+ * }
+ * ```
+ * 
+ * @param isLoading - 현재 로딩 상태
+ * @param options - 옵션
+ * @returns 실제로 로딩 UI를 표시할지 여부
+ */
+export function useDelayedLoading(
+  isLoading: boolean,
+  options: DelayedLoadingOptions = {}
+): boolean {
+  const { delay = 300, minDisplayTime = 0 } = options;
+  const [showLoading, setShowLoading] = useState(false);
+  const loadingStartTimeRef = useRef<number | null>(null);
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  useEffect(() => {
+    // 이전 timeout 정리 (race condition 방지)
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    if (isLoading) {
+      // 로딩 시작 시간 기록
+      const startTime = Date.now();
+      loadingStartTimeRef.current = startTime;
+
+      // delay 후에 로딩 UI 표시
+      timeoutRef.current = setTimeout(() => {
+        // timeout이 여전히 유효한지 확인 (race condition 방지)
+        if (timeoutRef.current) {
+          setShowLoading(true);
+          timeoutRef.current = null;
+        }
+      }, delay);
+    } else {
+      // 로딩이 끝났을 때
+      if (loadingStartTimeRef.current !== null) {
+        const elapsedTime = Date.now() - loadingStartTimeRef.current;
+        const remainingTime = Math.max(0, minDisplayTime - elapsedTime);
+
+        if (remainingTime > 0) {
+          // 최소 표시 시간이 남아있으면 그 시간만큼 더 표시
+          timeoutRef.current = setTimeout(() => {
+            // timeout이 여전히 유효한지 확인 (race condition 방지)
+            if (timeoutRef.current) {
+              setShowLoading(false);
+              loadingStartTimeRef.current = null;
+              timeoutRef.current = null;
+            }
+          }, remainingTime);
+        } else {
+          // 이미 최소 표시 시간을 넘었으면 즉시 숨김
+          setShowLoading(false);
+          loadingStartTimeRef.current = null;
+        }
+      } else {
+        // 로딩이 시작되지 않았으면 즉시 숨김
+        setShowLoading(false);
+      }
+    }
+
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    };
+  }, [isLoading, delay, minDisplayTime]);
+
+  return showLoading;
+}

package/src/framework/loading/hooks/useLoadingState.ts

@@ -0,0 +1,103 @@
+/**
+ * @hua-labs/hua-ux/framework - useLoadingState
+ * 
+ * 로딩 상태를 관리하는 편의성 hook
+ * Convenience hook for managing loading state
+ */
+
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useDelayedLoading, type DelayedLoadingOptions } from './useDelayedLoading';
+
+/**
+ * useLoadingState 반환 타입
+ */
+export interface UseLoadingStateReturn {
+  /**
+   * 실제로 로딩 UI를 표시할지 여부 (useDelayedLoading 적용)
+   * Whether to actually show loading UI (with useDelayedLoading applied)
+   */
+  showLoading: boolean;
+  
+  /**
+   * 로딩 시작
+   * Start loading
+   */
+  startLoading: () => void;
+  
+  /**
+   * 로딩 종료
+   * Stop loading
+   */
+  stopLoading: () => void;
+  
+  /**
+   * 로딩 상태 토글
+   * Toggle loading state
+   */
+  toggleLoading: () => void;
+  
+  /**
+   * 현재 로딩 상태 (지연 없이)
+   * Current loading state (without delay)
+   */
+  isLoading: boolean;
+}
+
+/**
+ * useLoadingState Hook
+ * 
+ * 로딩 상태를 쉽게 관리할 수 있는 편의성 hook입니다.
+ * useDelayedLoading이 자동으로 적용됩니다.
+ * 
+ * Convenience hook for easily managing loading state.
+ * useDelayedLoading is automatically applied.
+ * 
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { showLoading, startLoading, stopLoading } = useLoadingState();
+ * 
+ *   const fetchData = async () => {
+ *     startLoading();
+ *     try {
+ *       await api.getData();
+ *     } finally {
+ *       stopLoading();
+ *     }
+ *   };
+ * 
+ *   return showLoading && <Spinner />;
+ * }
+ * ```
+ * 
+ * @param options - useDelayedLoading 옵션
+ * @returns 로딩 상태 제어 함수
+ */
+export function useLoadingState(
+  options: DelayedLoadingOptions = {}
+): UseLoadingStateReturn {
+  const [isLoading, setIsLoading] = useState(false);
+  const showLoading = useDelayedLoading(isLoading, options);
+
+  const startLoading = useCallback(() => {
+    setIsLoading(true);
+  }, []);
+
+  const stopLoading = useCallback(() => {
+    setIsLoading(false);
+  }, []);
+
+  const toggleLoading = useCallback(() => {
+    setIsLoading((prev) => !prev);
+  }, []);
+
+  return {
+    showLoading,
+    startLoading,
+    stopLoading,
+    toggleLoading,
+    isLoading,
+  };
+}

package/src/framework/loading/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @hua-labs/hua-ux/framework - Loading State
+ * 
+ * 로딩 상태 최적화 도구 모음
+ * Loading state optimization tools
+ */
+
+export { useDelayedLoading } from './hooks/useDelayedLoading';
+export { useLoadingState } from './hooks/useLoadingState';
+export { SkeletonGroup } from './components/SkeletonGroup';
+export { SuspenseWrapper } from './components/SuspenseWrapper';
+export { withSuspense } from './hoc/withSuspense';
+
+// Skeleton은 @hua-labs/ui에서 re-export
+export { Skeleton } from '@hua-labs/ui';
+
+export type { DelayedLoadingOptions } from './hooks/useDelayedLoading';
+export type { SkeletonGroupProps } from './components/SkeletonGroup';
+export type { SuspenseWrapperProps } from './components/SuspenseWrapper';

package/src/framework/middleware/i18n.ts

@@ -0,0 +1,161 @@
+/**
+ * @hua-labs/hua-ux/framework - i18n Middleware
+ * 
+ * i18n middleware for automatic language detection and routing
+ * 
+ * **타입 안전성**: Next.js를 peerDependency로 사용하므로,
+ * Next.js 프로젝트에서는 자동으로 타입이 추론됩니다.
+ * 
+ * **Type Safety**: Next.js is used as a peerDependency,
+ * so types are automatically inferred in Next.js projects.
+ */
+
+// Next.js types - 조건부 import로 타입 안전성 향상
+// Next.js types - Improved type safety with conditional import
+
+/**
+ * Base interface for NextRequest (when Next.js is not available)
+ */
+interface BaseNextRequest {
+  headers: {
+    get(name: string): string | null;
+  };
+  cookies: {
+    get(name: string): { value: string } | undefined;
+  };
+  nextUrl: {
+    pathname: string;
+    searchParams: URLSearchParams;
+  };
+}
+
+/**
+ * NextRequest type - Next.js가 있으면 실제 타입, 없으면 기본 인터페이스
+ * 
+ * Next.js가 optional peerDependency이므로, 타입 레벨에서만 처리합니다.
+ * 실제 Next.js 프로젝트에서는 Next.js의 NextRequest 타입이 자동으로 사용됩니다.
+ */
+type NextRequest = BaseNextRequest;
+
+/**
+ * Base interface for NextResponse (when Next.js is not available)
+ */
+interface BaseNextResponse {
+  headers: Headers;
+  next?(): BaseNextResponse;
+  redirect?(url: string): BaseNextResponse;
+}
+
+/**
+ * NextResponse factory function
+ * Next.js가 설치되어 있으면 실제 NextResponse를 사용하고, 없으면 폴백 구현을 사용합니다.
+ */
+let NextResponseFactory: {
+  next(): BaseNextResponse;
+  redirect(url: string): BaseNextResponse;
+};
+
+try {
+  // Next.js가 설치되어 있으면 실제 NextResponse 사용
+  const nextServer = require('next/server');
+  NextResponseFactory = nextServer.NextResponse;
+} catch {
+  // Next.js가 없으면 폴백 구현
+  // Fallback implementation if Next.js is not available
+  NextResponseFactory = {
+    next: () => ({
+      headers: new Headers(),
+    } as BaseNextResponse),
+    redirect: (url: string) => ({
+      headers: new Headers(),
+    } as BaseNextResponse),
+  };
+}
+
+/**
+ * i18n middleware configuration
+ */
+export interface I18nMiddlewareConfig {
+  /**
+   * Default language
+   */
+  defaultLanguage: string;
+  
+  /**
+   * Supported languages
+   */
+  supportedLanguages: string[];
+  
+  /**
+   * Language detection strategy
+   */
+  detectionStrategy?: 'header' | 'cookie' | 'path' | 'query';
+}
+
+/**
+ * Create i18n middleware for Next.js
+ * 
+ * **⚠️ Edge Runtime Note**: This middleware runs on Edge Runtime.
+ * Make sure your middleware.ts file exports the runtime config:
+ * 
+ * ```ts
+ * export const runtime = 'edge';
+ * ```
+ * 
+ * @example
+ * ```ts
+ * // middleware.ts
+ * import { createI18nMiddleware } from '@hua-labs/hua-ux/framework';
+ * 
+ * // Edge Runtime 명시 (Vercel 자동 감지 방지)
+ * export const runtime = 'edge';
+ * 
+ * export default createI18nMiddleware({
+ *   defaultLanguage: 'ko',
+ *   supportedLanguages: ['ko', 'en'],
+ * });
+ * ```
+ * 
+ * **Alternative**: If you don't want to use Edge Runtime, you can handle
+ * language detection in your API routes or client components instead.
+ */
+export function createI18nMiddleware(config: I18nMiddlewareConfig) {
+  return function i18nMiddleware(request: NextRequest) {
+    const { defaultLanguage, supportedLanguages, detectionStrategy = 'header' } = config;
+    
+    // Get language from various sources
+    let language = defaultLanguage;
+    
+    if (detectionStrategy === 'header') {
+      const acceptLanguage = request.headers.get('accept-language');
+      if (acceptLanguage) {
+        // Simple language detection from Accept-Language header
+        const preferredLang = acceptLanguage.split(',')[0].split('-')[0].toLowerCase();
+        if (supportedLanguages.includes(preferredLang)) {
+          language = preferredLang;
+        }
+      }
+    } else if (detectionStrategy === 'cookie') {
+      const cookieLang = request.cookies.get('language')?.value;
+      if (cookieLang && supportedLanguages.includes(cookieLang)) {
+        language = cookieLang;
+      }
+    } else if (detectionStrategy === 'path') {
+      const pathLang = request.nextUrl.pathname.split('/')[1];
+      if (pathLang && supportedLanguages.includes(pathLang)) {
+        language = pathLang;
+      }
+    } else if (detectionStrategy === 'query') {
+      const queryLang = request.nextUrl.searchParams.get('lang');
+      if (queryLang && supportedLanguages.includes(queryLang)) {
+        language = queryLang;
+      }
+    }
+    
+    // Add language to request headers for use in components
+    const response = NextResponseFactory.next();
+    response.headers.set('x-language', language);
+    
+    return response;
+  };
+}

package/src/framework/middleware/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @hua-labs/hua-ux/framework - Middleware System
+ * 
+ * Middleware system for framework-level functionality
+ */
+
+export * from './i18n';

package/src/framework/plugins/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @hua-labs/hua-ux/framework - Plugin System
+ * 
+ * 플러그인 시스템 메인 export
+ */
+
+export { 
+  pluginRegistry, 
+  registerPlugin, 
+  getPlugin, 
+  getAllPlugins 
+} from './registry';
+export type { HuaUxPlugin } from './types';

package/src/framework/plugins/registry.ts

@@ -0,0 +1,186 @@
+/**
+ * @hua-labs/hua-ux/framework - Plugin Registry
+ * 
+ * 플러그인 등록 및 관리 시스템
+ */
+
+import type { HuaUxPlugin } from './types';
+import { hasLicense } from '../license';
+
+/**
+ * 플러그인 레지스트리 / Plugin registry
+ * 
+ * 모든 플러그인을 등록하고 관리하는 싱글톤 클래스
+ * Singleton class that registers and manages all plugins
+ */
+class PluginRegistry {
+  private plugins: Map<string, HuaUxPlugin> = new Map();
+  private initialized: Set<string> = new Set();
+
+  /**
+   * 플러그인 등록 / Register plugin
+   * 
+   * @param plugin - 등록할 플러그인
+   * @throws 라이선스가 없을 경우 에러
+   * 
+   * @example
+   * ```ts
+   * import { registerPlugin } from '@hua-labs/hua-ux/framework';
+   * import { motionProPlugin } from '@hua-labs/motion-core/pro';
+   * 
+   * registerPlugin(motionProPlugin);
+   * ```
+   */
+  register(plugin: HuaUxPlugin): void {
+    // 중복 등록 확인
+    if (this.plugins.has(plugin.name)) {
+      console.warn(
+        `[hua-ux] Plugin "${plugin.name}" is already registered. Overwriting...`
+      );
+    }
+
+    // 라이선스 검증
+    if (plugin.license !== 'free') {
+      // 플러그인의 checkLicense 함수가 있으면 사용
+      if (plugin.checkLicense) {
+        if (!plugin.checkLicense()) {
+          throw new Error(
+            `[hua-ux] ❌ Plugin "${plugin.name}" requires a valid ${plugin.license} license.\n` +
+            `[hua-ux] ❌ Please purchase a ${plugin.license} license.\n\n` +
+            `💡 Purchase link: https://hua-labs.com/pricing`
+          );
+        }
+      } else {
+        // 기본 라이선스 검증 (license feature 기반)
+        const feature = `plugin-${plugin.name}` as any;
+        if (!hasLicense(feature)) {
+          // 라이선스가 없어도 경고만 표시 (개발 환경)
+          if (process.env.NODE_ENV === 'development') {
+            console.warn(
+              `[hua-ux] ⚠️ Plugin "${plugin.name}" may require a ${plugin.license} license.\n` +
+              `[hua-ux] ⚠️ Some features may not work without a valid license.`
+            );
+          }
+        }
+      }
+    }
+
+    // 플러그인 등록
+    this.plugins.set(plugin.name, plugin);
+
+    if (process.env.NODE_ENV === 'development') {
+      console.log(
+        `[hua-ux] ✅ Plugin "${plugin.name}" v${plugin.version} registered successfully`
+      );
+    }
+  }
+
+  /**
+   * 플러그인 초기화 / Initialize plugin
+   * 
+   * 등록된 플러그인의 init 함수를 호출합니다.
+   * Calls the init function of registered plugins.
+   * 
+   * @param pluginName - 플러그인 이름
+   * @param config - 프레임워크 설정
+   */
+  async initialize(pluginName: string, config: any): Promise<void> {
+    const plugin = this.plugins.get(pluginName);
+    if (!plugin) {
+      throw new Error(`[hua-ux] Plugin "${pluginName}" not found`);
+    }
+
+    // 이미 초기화된 경우 스킵
+    if (this.initialized.has(pluginName)) {
+      return;
+    }
+
+    // init 함수 호출
+    if (plugin.init) {
+      await plugin.init(config);
+      this.initialized.add(pluginName);
+    }
+  }
+
+  /**
+   * 모든 플러그인 초기화 / Initialize all plugins
+   * 
+   * @param config - 프레임워크 설정
+   */
+  async initializeAll(config: any): Promise<void> {
+    const promises = Array.from(this.plugins.keys()).map(name =>
+      this.initialize(name, config)
+    );
+    await Promise.all(promises);
+  }
+
+  /**
+   * 플러그인 가져오기 / Get plugin
+   * 
+   * @param name - 플러그인 이름
+   * @returns 플러그인 또는 undefined
+   */
+  get(name: string): HuaUxPlugin | undefined {
+    return this.plugins.get(name);
+  }
+
+  /**
+   * 모든 플러그인 가져오기 / Get all plugins
+   * 
+   * @returns 플러그인 배열
+   */
+  getAll(): HuaUxPlugin[] {
+    return Array.from(this.plugins.values());
+  }
+
+  /**
+   * 플러그인 등록 해제 / Unregister plugin
+   * 
+   * @param name - 플러그인 이름
+   */
+  unregister(name: string): void {
+    this.plugins.delete(name);
+    this.initialized.delete(name);
+  }
+
+  /**
+   * 레지스트리 초기화 (테스트용) / Reset registry (for testing)
+   */
+  reset(): void {
+    this.plugins.clear();
+    this.initialized.clear();
+  }
+}
+
+/**
+ * 전역 플러그인 레지스트리 인스턴스 / Global plugin registry instance
+ */
+export const pluginRegistry = new PluginRegistry();
+
+/**
+ * 플러그인 등록 (편의 함수) / Register plugin (convenience function)
+ * 
+ * @param plugin - 등록할 플러그인
+ */
+export function registerPlugin(plugin: HuaUxPlugin): void {
+  pluginRegistry.register(plugin);
+}
+
+/**
+ * 플러그인 가져오기 (편의 함수) / Get plugin (convenience function)
+ * 
+ * @param name - 플러그인 이름
+ * @returns 플러그인 또는 undefined
+ */
+export function getPlugin(name: string): HuaUxPlugin | undefined {
+  return pluginRegistry.get(name);
+}
+
+/**
+ * 모든 플러그인 가져오기 (편의 함수) / Get all plugins (convenience function)
+ * 
+ * @returns 플러그인 배열
+ */
+export function getAllPlugins(): HuaUxPlugin[] {
+  return pluginRegistry.getAll();
+}