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

package/src/framework/license/index.ts

@@ -0,0 +1,137 @@
+/**
+ * @hua-labs/hua-ux/framework - License System
+ * 
+ * 라이선스 검증 및 관리 시스템
+ */
+
+import type { LicenseInfo, LicenseFeature, LicenseCheckResult } from './types';
+import { loadLicense } from './loader';
+import { FEATURE_LICENSE_MAP } from './types';
+import { createLicenseError } from './errors';
+
+/**
+ * 전역 라이선스 인스턴스
+ */
+let globalLicense: LicenseInfo | null = null;
+
+/**
+ * 라이선스 초기화
+ * 
+ * 설정 파일의 라이선스 정보를 사용하여 라이선스를 로드합니다.
+ * 
+ * @param configLicense - 설정 파일의 라이선스 정보 (선택적)
+ */
+export function initLicense(configLicense?: { apiKey?: string; type?: 'free' | 'pro' | 'enterprise' }): void {
+  globalLicense = loadLicense(configLicense);
+}
+
+/**
+ * 현재 라이선스 가져오기
+ * 
+ * @returns 라이선스 정보
+ */
+export function getLicense(): LicenseInfo {
+  if (!globalLicense) {
+    // 초기화되지 않은 경우 기본값 (Free) 로드
+    globalLicense = loadLicense();
+  }
+  return globalLicense;
+}
+
+/**
+ * 라이선스 검증
+ * 
+ * 특정 기능이 현재 라이선스에서 사용 가능한지 확인합니다.
+ * 
+ * @param feature - 확인할 기능
+ * @returns 검증 결과
+ * 
+ * @example
+ * ```ts
+ * const result = checkLicense('motion-pro');
+ * if (result.valid) {
+ *   // Pro 기능 사용
+ * }
+ * ```
+ */
+export function checkLicense(feature: LicenseFeature): LicenseCheckResult {
+  const license = getLicense();
+  
+  // 라이선스가 유효하지 않은 경우
+  if (!license.valid) {
+    return {
+      valid: false,
+      reason: 'License is not valid',
+    };
+  }
+  
+  // 만료 확인
+  if (license.expiresAt && license.expiresAt < new Date()) {
+    return {
+      valid: false,
+      reason: 'License has expired',
+      expiresAt: license.expiresAt,
+    };
+  }
+  
+  // 기능 확인
+  const requiredLicenses = FEATURE_LICENSE_MAP[feature];
+  if (!requiredLicenses.includes(license.type)) {
+    return {
+      valid: false,
+      reason: `Feature "${feature}" requires one of: ${requiredLicenses.join(', ')}`,
+    };
+  }
+  
+  // 기능이 features 목록에 있는지 확인 (Enterprise는 모든 기능 사용 가능)
+  if (license.type !== 'enterprise' && !license.features.includes(feature)) {
+    return {
+      valid: false,
+      reason: `Feature "${feature}" is not included in the license`,
+    };
+  }
+  
+  return {
+    valid: true,
+    expiresAt: license.expiresAt,
+  };
+}
+
+/**
+ * 라이선스 확인 (간단한 boolean 반환)
+ * 
+ * @param feature - 확인할 기능
+ * @returns 사용 가능 여부
+ * 
+ * @example
+ * ```ts
+ * if (hasLicense('motion-pro')) {
+ *   // Pro 기능 사용
+ * }
+ * ```
+ */
+export function hasLicense(feature: LicenseFeature): boolean {
+  return checkLicense(feature).valid;
+}
+
+/**
+ * 라이선스 필수 확인
+ * 
+ * 라이선스가 없으면 에러를 throw합니다.
+ * 
+ * @param feature - 확인할 기능
+ * @throws 라이선스가 없을 경우 에러
+ * 
+ * @example
+ * ```ts
+ * requireLicense('motion-pro');
+ * // Pro 기능 사용 (에러 없음)
+ * ```
+ */
+export function requireLicense(feature: LicenseFeature): void {
+  const result = checkLicense(feature);
+  if (!result.valid) {
+    const license = getLicense();
+    throw new Error(createLicenseError(feature, license.type));
+  }
+}

package/src/framework/license/loader.ts

@@ -0,0 +1,158 @@
+/**
+ * @hua-labs/hua-ux/framework - License Loader
+ * 
+ * 라이선스 로드 및 검증
+ */
+
+import type { LicenseInfo, LicenseType } from './types';
+
+/**
+ * 라이선스 캐시
+ */
+let cachedLicense: LicenseInfo | null = null;
+
+/**
+ * Free 라이선스 기본값 / Free license default
+ */
+const FREE_LICENSE: LicenseInfo = {
+  type: 'free',
+  valid: true,
+  features: ['core', 'motion-basic', 'i18n-basic', 'preset-basic'],
+};
+
+/**
+ * API 키 검증 (미구현 - 향후 구현)
+ * 
+ * 실제 구현 시에는 서버 API를 호출하여 라이선스를 검증합니다.
+ * In actual implementation, this would call a server API to validate the license.
+ * 
+ * @param apiKey - API 키
+ * @returns 라이선스 정보 또는 null
+ */
+function validateLicenseKey(apiKey: string): LicenseInfo | null {
+  // TODO: 실제 API 호출 구현
+  // TODO: Implement actual API call
+  
+  // 현재는 기본값 반환 (개발 단계)
+  // Currently returns default (development phase)
+  if (apiKey.startsWith('pro_')) {
+    return {
+      type: 'pro',
+      valid: true,
+      features: ['core', 'motion-basic', 'motion-pro', 'i18n-basic', 'i18n-pro', 'preset-basic', 'preset-pro'],
+      apiKey,
+    };
+  }
+  
+  if (apiKey.startsWith('enterprise_')) {
+    return {
+      type: 'enterprise',
+      valid: true,
+      features: ['core', 'motion-basic', 'motion-pro', 'i18n-basic', 'i18n-pro', 'preset-basic', 'preset-pro', 'white-labeling'],
+      apiKey,
+      companyName: 'Enterprise Customer',
+    };
+  }
+  
+  return null;
+}
+
+/**
+ * 환경 변수에서 라이선스 로드
+ * 
+ * @returns 라이선스 정보 또는 null
+ */
+function loadLicenseFromEnv(): LicenseInfo | null {
+  // Node.js 환경에서만 동작
+  if (typeof process === 'undefined' || !process.env) {
+    return null;
+  }
+  
+  const apiKey = process.env.HUA_UX_LICENSE_KEY;
+  if (!apiKey) {
+    return null;
+  }
+  
+  return validateLicenseKey(apiKey);
+}
+
+/**
+ * 설정 파일에서 라이선스 로드
+ * 
+ * @param configLicense - 설정 파일의 라이선스 정보
+ * @returns 라이선스 정보 또는 null
+ */
+function loadLicenseFromConfig(configLicense?: { apiKey?: string; type?: LicenseType }): LicenseInfo | null {
+  if (!configLicense) {
+    return null;
+  }
+  
+  // API 키가 있으면 검증
+  if (configLicense.apiKey) {
+    return validateLicenseKey(configLicense.apiKey);
+  }
+  
+  // 타입만 지정된 경우 (개발용)
+  if (configLicense.type) {
+    if (configLicense.type === 'pro') {
+      return {
+        type: 'pro',
+        valid: true,
+        features: ['core', 'motion-basic', 'motion-pro', 'i18n-basic', 'i18n-pro', 'preset-basic', 'preset-pro'],
+      };
+    }
+    
+    if (configLicense.type === 'enterprise') {
+      return {
+        type: 'enterprise',
+        valid: true,
+        features: ['core', 'motion-basic', 'motion-pro', 'i18n-basic', 'i18n-pro', 'preset-basic', 'preset-pro', 'white-labeling'],
+      };
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * 라이선스 로드
+ * 
+ * 로드 순서:
+ * 1. 환경 변수 (HUA_UX_LICENSE_KEY)
+ * 2. 설정 파일 (hua-ux.config.ts)
+ * 3. 기본값 (Free)
+ * 
+ * @param configLicense - 설정 파일의 라이선스 정보 (선택적)
+ * @returns 라이선스 정보
+ */
+export function loadLicense(configLicense?: { apiKey?: string; type?: LicenseType }): LicenseInfo {
+  // 캐시 확인
+  if (cachedLicense) {
+    return cachedLicense;
+  }
+  
+  // 1. 환경 변수에서 로드
+  const envLicense = loadLicenseFromEnv();
+  if (envLicense) {
+    cachedLicense = envLicense;
+    return cachedLicense;
+  }
+  
+  // 2. 설정 파일에서 로드
+  const configLicenseInfo = loadLicenseFromConfig(configLicense);
+  if (configLicenseInfo) {
+    cachedLicense = configLicenseInfo;
+    return cachedLicense;
+  }
+  
+  // 3. 기본값 (Free)
+  cachedLicense = FREE_LICENSE;
+  return cachedLicense;
+}
+
+/**
+ * 라이선스 캐시 초기화 (테스트용)
+ */
+export function resetLicenseCache(): void {
+  cachedLicense = null;
+}

package/src/framework/license/types.ts

@@ -0,0 +1,95 @@
+/**
+ * @hua-labs/hua-ux/framework - License Types
+ * 
+ * 라이선스 타입 정의
+ */
+
+/**
+ * 라이선스 타입 / License type
+ */
+export type LicenseType = 'free' | 'pro' | 'enterprise';
+
+/**
+ * 라이선스 기능 / License feature
+ * 
+ * 각 기능은 특정 라이선스 타입에서만 사용 가능합니다.
+ * Each feature is available only with specific license types.
+ */
+export type LicenseFeature =
+  | 'core' // 기본 기능 (모든 라이선스)
+  | 'motion-basic' // 기본 모션 (Free)
+  | 'motion-pro' // 고급 모션 (Pro+)
+  | 'i18n-basic' // 기본 i18n (Free)
+  | 'i18n-pro' // 고급 i18n (Pro+)
+  | 'preset-basic' // 기본 프리셋 (Free)
+  | 'preset-pro' // 고급 프리셋 (Pro+)
+  | 'white-labeling'; // 화이트 라벨링 (Enterprise)
+
+/**
+ * 라이선스 정보 / License information
+ */
+export interface LicenseInfo {
+  /**
+   * 라이선스 타입 / License type
+   */
+  type: LicenseType;
+  
+  /**
+   * 라이선스 유효성 / License validity
+   */
+  valid: boolean;
+  
+  /**
+   * 만료일 (선택적) / Expiration date (optional)
+   */
+  expiresAt?: Date;
+  
+  /**
+   * 사용 가능한 기능 목록 / List of available features
+   */
+  features: LicenseFeature[];
+  
+  /**
+   * 회사/서비스 이름 (Enterprise) / Company/service name (Enterprise)
+   */
+  companyName?: string;
+  
+  /**
+   * API 키 (Pro/Enterprise) / API key (Pro/Enterprise)
+   */
+  apiKey?: string;
+}
+
+/**
+ * 라이선스 검증 결과 / License check result
+ */
+export interface LicenseCheckResult {
+  /**
+   * 검증 성공 여부 / Validation success
+   */
+  valid: boolean;
+  
+  /**
+   * 실패 이유 (검증 실패 시) / Failure reason (if validation failed)
+   */
+  reason?: string;
+  
+  /**
+   * 만료일 (선택적) / Expiration date (optional)
+   */
+  expiresAt?: Date;
+}
+
+/**
+ * 기능별 필요한 라이선스 타입 매핑 / Feature to license type mapping
+ */
+export const FEATURE_LICENSE_MAP: Record<LicenseFeature, LicenseType[]> = {
+  'core': ['free', 'pro', 'enterprise'],
+  'motion-basic': ['free', 'pro', 'enterprise'],
+  'motion-pro': ['pro', 'enterprise'],
+  'i18n-basic': ['free', 'pro', 'enterprise'],
+  'i18n-pro': ['pro', 'enterprise'],
+  'preset-basic': ['free', 'pro', 'enterprise'],
+  'preset-pro': ['pro', 'enterprise'],
+  'white-labeling': ['enterprise'],
+};

package/src/framework/loading/components/SkeletonGroup.tsx

@@ -0,0 +1,70 @@
+/**
+ * @hua-labs/hua-ux/framework - SkeletonGroup
+ * 
+ * 여러 Skeleton을 그룹으로 묶는 컴포넌트
+ * Component for grouping multiple Skeletons
+ */
+
+'use client';
+
+import React from 'react';
+import { Skeleton } from '@hua-labs/ui';
+
+/**
+ * SkeletonGroup 컴포넌트 props
+ */
+export interface SkeletonGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 자식 요소들
+   * Children elements
+   */
+  children?: React.ReactNode;
+  
+  /**
+   * 간격 크기
+   * Spacing size
+   * 
+   * @default "md"
+   */
+  spacing?: 'sm' | 'md' | 'lg';
+}
+
+/**
+ * SkeletonGroup 컴포넌트
+ * 
+ * 여러 Skeleton을 일관된 간격으로 그룹화합니다.
+ * Groups multiple Skeletons with consistent spacing.
+ * 
+ * @example
+ * ```tsx
+ * <SkeletonGroup>
+ *   <Skeleton width="60%" height={32} />
+ *   <Skeleton width="80%" />
+ *   <Skeleton width="70%" />
+ * </SkeletonGroup>
+ * ```
+ * 
+ * @param props - SkeletonGroup props
+ * @returns SkeletonGroup 컴포넌트
+ */
+export function SkeletonGroup({
+  children,
+  spacing = 'md',
+  className,
+  ...props
+}: SkeletonGroupProps): React.JSX.Element {
+  const spacingClasses = {
+    sm: 'space-y-2', // 8px
+    md: 'space-y-4', // 16px
+    lg: 'space-y-6', // 24px
+  };
+
+  return (
+    <div
+      className={`${spacingClasses[spacing]} ${className || ''}`}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}

package/src/framework/loading/components/SuspenseWrapper.tsx

@@ -0,0 +1,88 @@
+/**
+ * @hua-labs/hua-ux/framework - SuspenseWrapper
+ * 
+ * React Suspense를 더 쉽게 사용할 수 있게 해주는 컴포넌트
+ * Component that makes React Suspense easier to use
+ */
+
+'use client';
+
+import React, { Suspense, useMemo, type ReactNode } from 'react';
+import { Skeleton } from '@hua-labs/ui';
+import { SkeletonGroup } from './SkeletonGroup';
+
+/**
+ * SuspenseWrapper 컴포넌트 props
+ */
+export interface SuspenseWrapperProps {
+  /**
+   * Suspense로 감쌀 자식 요소
+   * Children to wrap with Suspense
+   */
+  children: ReactNode;
+  
+  /**
+   * 로딩 중 표시할 fallback
+   * Fallback to show while loading
+   * 
+   * @default <SkeletonGroup>...</SkeletonGroup>
+   */
+  fallback?: ReactNode;
+  
+  /**
+   * 기본 Skeleton fallback 사용 여부
+   * Whether to use default Skeleton fallback
+   * 
+   * @default true
+   */
+  useDefaultFallback?: boolean;
+}
+
+/**
+ * SuspenseWrapper 컴포넌트
+ * 
+ * React Suspense를 더 쉽게 사용할 수 있게 해줍니다.
+ * 기본적으로 Skeleton fallback을 제공합니다.
+ * 
+ * Makes React Suspense easier to use.
+ * Provides Skeleton fallback by default.
+ * 
+ * @example
+ * ```tsx
+ * // 기본 사용 (자동 Skeleton fallback)
+ * <SuspenseWrapper>
+ *   <AsyncComponent />
+ * </SuspenseWrapper>
+ * 
+ * // 커스텀 fallback
+ * <SuspenseWrapper fallback={<Spinner />}>
+ *   <AsyncComponent />
+ * </SuspenseWrapper>
+ * ```
+ * 
+ * @param props - SuspenseWrapper props
+ * @returns SuspenseWrapper 컴포넌트
+ */
+export function SuspenseWrapper({
+  children,
+  fallback,
+  useDefaultFallback = true,
+}: SuspenseWrapperProps): React.JSX.Element {
+  const defaultFallback = useMemo(
+    () =>
+      useDefaultFallback ? (
+        <SkeletonGroup>
+          <Skeleton width="60%" height={32} />
+          <Skeleton width="80%" />
+          <Skeleton width="70%" />
+        </SkeletonGroup>
+      ) : null,
+    [useDefaultFallback]
+  );
+
+  return (
+    <Suspense fallback={fallback ?? defaultFallback}>
+      {children}
+    </Suspense>
+  );
+}

package/src/framework/loading/hoc/withSuspense.tsx

@@ -0,0 +1,96 @@
+/**
+ * @hua-labs/hua-ux/framework - withSuspense
+ * 
+ * 컴포넌트를 Suspense로 감싸는 HOC
+ * HOC that wraps a component with Suspense
+ */
+
+'use client';
+
+import React, { Suspense, useMemo, type ComponentType, type ReactNode } from 'react';
+import { Skeleton } from '@hua-labs/ui';
+import { SkeletonGroup } from '../components/SkeletonGroup';
+
+/**
+ * withSuspense 옵션
+ */
+export interface WithSuspenseOptions {
+  /**
+   * 로딩 중 표시할 fallback
+   * Fallback to show while loading
+   */
+  fallback?: ReactNode;
+  
+  /**
+   * 기본 Skeleton fallback 사용 여부
+   * Whether to use default Skeleton fallback
+   * 
+   * @default true
+   */
+  useDefaultFallback?: boolean;
+}
+
+/**
+ * withSuspense HOC
+ * 
+ * 컴포넌트를 Suspense로 감싸는 Higher-Order Component입니다.
+ * 
+ * Higher-Order Component that wraps a component with Suspense.
+ * 
+ * @example
+ * ```tsx
+ * const AsyncPosts = withSuspense(Posts, <Skeleton height={200} />);
+ * 
+ * function MyPage() {
+ *   return <AsyncPosts />;
+ * }
+ * ```
+ * 
+ * @param Component - 감쌀 컴포넌트
+ * @param options - 옵션 또는 fallback
+ * @returns Suspense로 감싼 컴포넌트
+ */
+export function withSuspense<P extends object>(
+  Component: ComponentType<P>,
+  optionsOrFallback?: WithSuspenseOptions | ReactNode
+): ComponentType<P> {
+  let fallback: ReactNode | undefined;
+  let useDefaultFallback = true;
+
+  if (optionsOrFallback !== undefined) {
+    if (React.isValidElement(optionsOrFallback) || typeof optionsOrFallback === 'string') {
+      // fallback이 직접 전달된 경우
+      fallback = optionsOrFallback;
+      useDefaultFallback = false;
+    } else {
+      // 옵션 객체가 전달된 경우
+      const options = optionsOrFallback as WithSuspenseOptions;
+      fallback = options.fallback;
+      useDefaultFallback = options.useDefaultFallback ?? true;
+    }
+  }
+
+  const defaultFallback = useMemo(
+    () =>
+      useDefaultFallback ? (
+        <SkeletonGroup>
+          <Skeleton width="60%" height={32} />
+          <Skeleton width="80%" />
+          <Skeleton width="70%" />
+        </SkeletonGroup>
+      ) : null,
+    [useDefaultFallback]
+  );
+
+  const WrappedComponent = (props: P) => {
+    return (
+      <Suspense fallback={fallback ?? defaultFallback}>
+        <Component {...props} />
+      </Suspense>
+    );
+  };
+
+  WrappedComponent.displayName = `withSuspense(${Component.displayName || Component.name || 'Component'})`;
+
+  return WrappedComponent;
+}