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

package/src/framework/config/merge.ts

@@ -0,0 +1,190 @@
+/**
+ * @hua-labs/hua-ux/framework - Config Merge
+ * 
+ * Preset 병합 및 깊은 병합 로직
+ */
+
+import type { HuaUxConfig, Preset, PresetName, PresetConfig } from '../types';
+import { productPreset } from '../../presets/product';
+import { marketingPreset } from '../../presets/marketing';
+
+/**
+ * Preset 맵
+ */
+const PRESET_MAP: Record<PresetName, any> = {
+  product: productPreset,
+  marketing: marketingPreset,
+};
+
+/**
+ * 깊은 병합 (Deep Merge)
+ * 
+ * 중첩된 객체를 재귀적으로 병합합니다.
+ * 사용자 설정이 Preset 설정보다 우선합니다.
+ */
+function deepMerge<T extends Record<string, any>>(
+  target: T,
+  source: Partial<T>
+): T {
+  const result = { ...target };
+
+  for (const key in source) {
+    if (source[key] === undefined) {
+      // undefined는 병합에서 제외 (사용자가 명시적으로 끄려는 경우)
+      continue;
+    }
+
+    if (
+      source[key] &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      target[key] &&
+      typeof target[key] === 'object' &&
+      !Array.isArray(target[key])
+    ) {
+      // 중첩 객체는 재귀적으로 병합
+      result[key] = deepMerge(target[key], source[key] as Partial<T[Extract<keyof T, string>]>);
+    } else {
+      // 배열이나 원시값은 그대로 덮어쓰기
+      result[key] = source[key] as T[Extract<keyof T, string>];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Preset에서 Config로 변환
+ * 
+ * Preset의 구조를 HuaUxConfig 형식으로 변환합니다.
+ */
+function presetToConfig(preset: typeof productPreset | typeof marketingPreset): Partial<HuaUxConfig> {
+  return {
+    motion: {
+      defaultPreset: preset === productPreset ? 'product' : 'marketing',
+      enableAnimations: true,
+    },
+    i18n: {
+      defaultLanguage: preset.i18n.defaultLanguage,
+      supportedLanguages: [...preset.i18n.supportedLanguages],
+    },
+    // Preset의 spacing은 나중에 컴포넌트에서 사용
+    // Config에는 직접 포함하지 않음 (컴포넌트가 PresetContext에서 가져옴)
+  };
+}
+
+/**
+ * Preset과 사용자 설정 병합
+ * 
+ * 1. Preset 기본값 로드
+ * 2. Preset 설정 오버라이드 (개발자 모드인 경우)
+ * 3. 사용자 설정으로 병합 (사용자 설정 우선)
+ * 4. 최종 검증
+ * 
+ * @param preset - 사용할 Preset (문자열 또는 객체)
+ * @param userConfig - 사용자 설정 (선택적)
+ * @returns 병합된 설정
+ */
+export function mergePresetWithConfig(
+  preset: Preset,
+  userConfig?: Partial<HuaUxConfig>
+): HuaUxConfig {
+  // 1. Preset 타입 추출
+  let presetName: PresetName;
+  let presetOverrides: Partial<HuaUxConfig> = {};
+  
+  if (typeof preset === 'string') {
+    // 바이브 모드: 문자열 Preset
+    presetName = preset;
+  } else {
+    // 개발자 모드: 객체 Preset
+    presetName = preset.type;
+    
+    // Preset 설정 오버라이드
+    if (preset.motion) {
+      presetOverrides.motion = {
+        ...presetOverrides.motion,
+        duration: preset.motion.duration,
+        easing: preset.motion.easing,
+      };
+    }
+    
+    // spacing은 나중에 컴포넌트 레벨에서 처리
+    // (Config에는 직접 포함하지 않음)
+  }
+
+  // 2. Preset 로드
+  const presetData = PRESET_MAP[presetName];
+  if (!presetData) {
+    throw new Error(
+      `Unknown preset: "${presetName}". Available presets: ${Object.keys(PRESET_MAP).join(', ')}`
+    );
+  }
+
+  // 3. Preset을 Config 형식으로 변환
+  const presetConfig = presetToConfig(presetData);
+  
+  // preset 속성 추가 (원본 preset 정보 보존)
+  presetConfig.preset = presetName;
+
+  // 4. Preset 오버라이드와 병합
+  const presetWithOverrides = deepMerge(presetConfig, presetOverrides);
+
+  // 5. 사용자 설정과 병합 (사용자 설정 우선)
+  const merged = userConfig
+    ? deepMerge(presetWithOverrides, userConfig)
+    : presetWithOverrides;
+
+  // 4. 최종 Config 형식으로 변환 (필수 필드 보장)
+  return {
+    ...presetConfig,
+    ...merged,
+    // i18n은 항상 있어야 함 (Preset에서 제공)
+    i18n: merged.i18n || presetConfig.i18n,
+    // motion은 항상 있어야 함
+    motion: merged.motion || presetConfig.motion,
+    // state는 기본값 사용
+    state: merged.state || {
+      persist: true,
+      ssr: true,
+    },
+    // fileStructure는 기본값 사용
+    fileStructure: merged.fileStructure || {
+      enforce: false,
+    },
+  } as HuaUxConfig;
+}
+
+/**
+ * Preset 없이 사용자 설정만으로 Config 생성
+ * 
+ * Preset을 사용하지 않고 모든 설정을 직접 지정하는 경우
+ */
+export function createConfigFromUserConfig(
+  userConfig: Partial<HuaUxConfig>
+): HuaUxConfig {
+  // 기본값과 사용자 설정 병합
+  const defaultConfig: Partial<HuaUxConfig> = {
+    i18n: {
+      defaultLanguage: 'ko',
+      supportedLanguages: ['ko', 'en'],
+      fallbackLanguage: 'en',
+      namespaces: ['common'],
+      translationLoader: 'api',
+      translationApiPath: '/api/translations',
+    },
+    motion: {
+      defaultPreset: 'product',
+      enableAnimations: true,
+    },
+    state: {
+      persist: true,
+      ssr: true,
+    },
+    fileStructure: {
+      enforce: false,
+    },
+  };
+
+  return deepMerge(defaultConfig, userConfig) as HuaUxConfig;
+}

package/src/framework/config/schema.ts

@@ -0,0 +1,140 @@
+/**
+ * @hua-labs/hua-ux/framework - Config Schema
+ * 
+ * Configuration schema and validation
+ */
+
+import type { HuaUxConfig, Preset } from '../types';
+
+/**
+ * Default configuration
+ * 
+ * Preset을 사용하지 않을 때의 기본값입니다.
+ * Preset을 사용하면 이 값은 무시되고 Preset 값이 사용됩니다.
+ */
+export const defaultConfig: Required<Omit<HuaUxConfig, 'branding' | 'plugins' | 'license'>> & { 
+  branding?: HuaUxConfig['branding'];
+  plugins?: HuaUxConfig['plugins'];
+  license?: HuaUxConfig['license'];
+} = {
+  preset: 'product',  // 기본 Preset
+  i18n: {
+    defaultLanguage: 'ko',
+    supportedLanguages: ['ko', 'en'],
+    fallbackLanguage: 'en',
+    namespaces: ['common'],
+    translationLoader: 'api',
+    translationApiPath: '/api/translations',
+  },
+  motion: {
+    defaultPreset: 'product',
+    enableAnimations: true,
+  },
+  state: {
+    persist: true,
+    ssr: true,
+  },
+  fileStructure: {
+    enforce: false,
+  },
+  plugins: [],
+  license: undefined,
+};
+
+/**
+ * Validate configuration
+ * 
+ * 설정의 유효성을 검증하고 친절한 에러 메시지를 제공합니다.
+ * Validates configuration and provides friendly error messages.
+ */
+export function validateConfig(config: Partial<HuaUxConfig>): HuaUxConfig {
+  // Preset 검증
+  if (config.preset) {
+    if (typeof config.preset === 'string') {
+      // 바이브 모드: 문자열 Preset
+      if (!['product', 'marketing'].includes(config.preset)) {
+        throw new Error(
+          `[hua-ux] ❌ 잘못된 Preset입니다: "${config.preset}"\n` +
+          `[hua-ux] ❌ Invalid preset: "${config.preset}"\n\n` +
+          `사용 가능한 Preset: 'product', 'marketing'\n` +
+          `Available presets: 'product', 'marketing'\n\n` +
+          `💡 해결 방법 / Solution:\n` +
+          `   - 'product' 또는 'marketing' 중 하나를 선택하세요.\n` +
+          `   - Select either 'product' or 'marketing'.\n\n` +
+          `📖 가이드 / Guide: https://github.com/HUA-Labs/hua-platform/tree/main/packages/hua-ux/docs`
+        );
+      }
+    } else {
+      // 개발자 모드: 객체 Preset
+      if (!['product', 'marketing'].includes(config.preset.type)) {
+        throw new Error(
+          `[hua-ux] ❌ 잘못된 Preset 타입입니다: "${config.preset.type}"\n` +
+          `[hua-ux] ❌ Invalid preset type: "${config.preset.type}"\n\n` +
+          `사용 가능한 Preset 타입: 'product', 'marketing'\n` +
+          `Available preset types: 'product', 'marketing'\n\n` +
+          `💡 해결 방법 / Solution:\n` +
+          `   - preset.type을 'product' 또는 'marketing'으로 설정하세요.\n` +
+          `   - Set preset.type to either 'product' or 'marketing'.\n\n` +
+          `📖 가이드 / Guide: https://github.com/HUA-Labs/hua-platform/tree/main/packages/hua-ux/docs`
+        );
+      }
+    }
+  }
+  
+  // motion.style을 defaultPreset으로 매핑 (바이브 코더용)
+  if (config.motion?.style && !config.motion.defaultPreset) {
+    const styleToPreset: Record<string, 'product' | 'marketing'> = {
+      smooth: 'product',
+      minimal: 'product',
+      dramatic: 'marketing',
+    };
+    
+    config.motion.defaultPreset = styleToPreset[config.motion.style];
+  }
+
+  // 기본값과 병합
+  const validated: HuaUxConfig = {
+    preset: config.preset || defaultConfig.preset,
+    i18n: {
+      ...defaultConfig.i18n,
+      ...config.i18n,
+    },
+    motion: {
+      ...defaultConfig.motion,
+      ...config.motion,
+    },
+    state: {
+      ...defaultConfig.state,
+      ...config.state,
+    },
+    fileStructure: {
+      ...defaultConfig.fileStructure,
+      ...config.fileStructure,
+    },
+  };
+
+  // Validate i18n
+  if (validated.i18n) {
+    if (!validated.i18n.supportedLanguages.includes(validated.i18n.defaultLanguage)) {
+      throw new Error(
+        `[hua-ux] ❌ i18n 설정 오류 / i18n configuration error\n\n` +
+        `기본 언어 "${validated.i18n.defaultLanguage}"가 지원 언어 목록에 없습니다.\n` +
+        `Default language "${validated.i18n.defaultLanguage}" is not in supportedLanguages.\n\n` +
+        `현재 지원 언어 / Current supported languages: ${validated.i18n.supportedLanguages.join(', ')}\n\n` +
+        `💡 해결 방법 / Solution:\n` +
+        `   1. supportedLanguages에 "${validated.i18n.defaultLanguage}"를 추가하세요.\n` +
+        `      Add "${validated.i18n.defaultLanguage}" to supportedLanguages.\n` +
+        `   2. 또는 defaultLanguage를 지원 언어 중 하나로 변경하세요.\n` +
+        `      Or change defaultLanguage to one of the supported languages.\n\n` +
+        `📝 예시 / Example:\n` +
+        `   i18n: {\n` +
+        `     defaultLanguage: 'ko',\n` +
+        `     supportedLanguages: ['ko', 'en', 'ja'],  // 'ko' 포함 필수\n` +
+        `   }\n\n` +
+        `📖 가이드 / Guide: https://github.com/HUA-Labs/hua-platform/tree/main/packages/hua-ux/docs`
+      );
+    }
+  }
+
+  return validated;
+}

package/src/framework/hooks/useMotion.ts

@@ -0,0 +1,57 @@
+/**
+ * @hua-labs/hua-ux/framework - useMotion
+ * 
+ * 통합 Motion Hook - motion-core의 useUnifiedMotion을 래핑
+ * Unified Motion Hook - Wraps motion-core's useUnifiedMotion
+ * 
+ * 이 hook은 motion-core의 useUnifiedMotion을 재export하여
+ * hua-ux 프레임워크에서 일관된 API를 제공합니다.
+ * 
+ * This hook re-exports motion-core's useUnifiedMotion to provide
+ * a consistent API within the hua-ux framework.
+ */
+
+'use client';
+
+import type { BaseMotionReturn, MotionElement, EntranceType } from '@hua-labs/motion-core';
+import { useUnifiedMotion } from '@hua-labs/motion-core';
+import type { UseUnifiedMotionOptions } from '@hua-labs/motion-core';
+
+/**
+ * Motion type (motion-core의 EntranceType과 동일)
+ */
+export type MotionType = EntranceType;
+
+/**
+ * useMotion options (motion-core의 UseUnifiedMotionOptions와 동일)
+ */
+export type UseMotionOptions = UseUnifiedMotionOptions;
+
+/**
+ * 통합 Motion Hook
+ * 
+ * motion-core의 useUnifiedMotion을 래핑하여 hua-ux 프레임워크에서 사용합니다.
+ * 
+ * Wraps motion-core's useUnifiedMotion for use in the hua-ux framework.
+ * 
+ * @param options - Motion options
+ * @returns Motion result with ref and control functions
+ * 
+ * @example
+ * ```tsx
+ * const motion = useMotion({
+ *   type: 'fadeIn',
+ *   duration: 600,
+ *   autoStart: false,
+ * });
+ * 
+ * return <div ref={motion.ref} style={motion.style}>Content</div>;
+ * ```
+ */
+export function useMotion<T extends MotionElement = HTMLDivElement>(
+  options: UseMotionOptions
+): BaseMotionReturn<T> {
+  // motion-core의 useUnifiedMotion을 직접 사용
+  // Directly use motion-core's useUnifiedMotion
+  return useUnifiedMotion<T>(options);
+}

package/src/framework/index.ts

@@ -0,0 +1,122 @@
+/**
+ * @hua-labs/hua-ux/framework
+ * 
+ * Framework layer for hua-ux
+ */
+
+// Components
+export { HuaUxLayout } from './components/HuaUxLayout';
+export { HuaUxPage } from './components/HuaUxPage';
+export { UnifiedProviders } from './components/Providers';
+export { BrandedButton } from './components/BrandedButton';
+export { BrandedCard } from './components/BrandedCard';
+export { ErrorBoundary } from './components/ErrorBoundary';
+export type { ErrorBoundaryProps } from './components/ErrorBoundary';
+
+// Configuration
+export { defineConfig, loadConfig, getConfig, setConfig, resetConfig } from './config';
+export type { HuaUxConfig, PresetName } from './types';
+
+// Data Fetching
+export { useData, fetchData } from './utils/data-fetching';
+export type { DataFetchResult } from './utils/data-fetching';
+
+// Middleware
+export { createI18nMiddleware } from './middleware/i18n';
+export type { I18nMiddlewareConfig } from './middleware/i18n';
+
+// File Structure
+// 서버 전용 유틸리티 (클라이언트 번들에서 제외)
+// Server-only utilities (excluded from client bundle)
+// export { validateFileStructure } from './utils/file-structure';
+// export type { FileStructureResult } from './utils/file-structure';
+// Note: validateFileStructure는 서버 전용이므로 필요시 직접 import
+
+// Metadata Utilities
+export { generatePageMetadata } from './utils/metadata';
+export type { SEOConfig } from './utils/metadata';
+
+// GEO (Generative Engine Optimization)
+export {
+  generateGEOMetadata,
+  renderJSONLD,
+  createAIContext,
+  generateSoftwareApplicationLD,
+  generateFAQPageLD,
+  generateTechArticleLD,
+  generateHowToLD,
+} from './seo/geo';
+export type {
+  GEOConfig,
+  GEOMetadata,
+  StructuredData,
+  SoftwareApplicationType,
+  SoftwareCategory,
+  ProgrammingLanguage,
+} from './seo/geo';
+
+// License System
+export { 
+  initLicense, 
+  getLicense, 
+  checkLicense, 
+  hasLicense, 
+  requireLicense 
+} from './license';
+export type { 
+  LicenseInfo, 
+  LicenseType, 
+  LicenseFeature, 
+  LicenseCheckResult 
+} from './license/types';
+
+// Plugin System
+export { 
+  pluginRegistry, 
+  registerPlugin, 
+  getPlugin, 
+  getAllPlugins 
+} from './plugins';
+export type { HuaUxPlugin } from './plugins/types';
+
+// Branding
+export { BrandingProvider, useBranding, useBrandingColor } from './branding/context';
+export { generateCSSVariables, generateCSSVariablesObject } from './branding/css-vars';
+export { generateTailwindConfig } from './branding/tailwind-config';
+
+// Accessibility (a11y)
+export {
+  useFocusManagement,
+  useFocusTrap,
+  SkipToContent,
+  LiveRegion,
+  useLiveRegion,
+} from './a11y';
+export type {
+  FocusManagementOptions,
+  FocusTrapOptions,
+  SkipToContentProps,
+  LiveRegionProps,
+} from './a11y';
+
+// Loading
+export {
+  useDelayedLoading,
+  useLoadingState,
+  Skeleton,
+  SkeletonGroup,
+  SuspenseWrapper,
+  withSuspense,
+} from './loading';
+export type {
+  DelayedLoadingOptions,
+  SkeletonGroupProps,
+  SuspenseWrapperProps,
+} from './loading';
+
+// Motion Hooks
+export { useMotion } from './hooks/useMotion';
+export type { MotionType, UseMotionOptions } from './hooks/useMotion';
+
+// Types
+export type { HuaUxLayoutProps, HuaUxPageProps } from './types';

package/src/framework/license/errors.ts

@@ -0,0 +1,63 @@
+/**
+ * @hua-labs/hua-ux/framework - License Errors
+ * 
+ * 라이선스 관련 에러 메시지
+ */
+
+import type { LicenseFeature } from './types';
+
+/**
+ * 구매 링크 (향후 실제 링크로 변경)
+ */
+const PURCHASE_URL = 'https://hua-labs.com/pricing';
+
+/**
+ * 라이선스 에러 메시지 생성
+ * 
+ * @param feature - 필요한 기능
+ * @param currentLicense - 현재 라이선스 타입
+ * @returns 에러 메시지
+ */
+export function createLicenseError(
+  feature: LicenseFeature,
+  currentLicense: 'free' | 'pro' | 'enterprise' = 'free'
+): string {
+  const featureNames: Record<LicenseFeature, string> = {
+    'core': 'Core features',
+    'motion-basic': 'Basic motion',
+    'motion-pro': 'Motion Pro',
+    'i18n-basic': 'Basic i18n',
+    'i18n-pro': 'i18n Pro',
+    'preset-basic': 'Basic presets',
+    'preset-pro': 'Preset Pro',
+    'white-labeling': 'White Labeling',
+  };
+  
+  const featureName = featureNames[feature] || feature;
+  
+  // 필요한 라이선스 타입 결정
+  let requiredLicense: 'pro' | 'enterprise' = 'pro';
+  if (feature === 'white-labeling') {
+    requiredLicense = 'enterprise';
+  }
+  
+  const messages = {
+    ko: [
+      `[hua-ux] ❌ "${featureName}" 기능을 사용하려면 ${requiredLicense === 'enterprise' ? 'Enterprise' : 'Pro'} 라이선스가 필요합니다.`,
+      `[hua-ux] ❌ Feature "${featureName}" requires a ${requiredLicense === 'enterprise' ? 'Enterprise' : 'Pro'} license.`,
+      '',
+      `현재 라이선스: ${currentLicense === 'free' ? 'Free' : currentLicense === 'pro' ? 'Pro' : 'Enterprise'}`,
+      `Current license: ${currentLicense === 'free' ? 'Free' : currentLicense === 'pro' ? 'Pro' : 'Enterprise'}`,
+      '',
+      `💡 해결 방법 / Solution:`,
+      `   - ${requiredLicense === 'enterprise' ? 'Enterprise' : 'Pro'} 라이선스를 구매하세요.`,
+      `   - Purchase a ${requiredLicense === 'enterprise' ? 'Enterprise' : 'Pro'} license.`,
+      `   - 구매 링크: ${PURCHASE_URL}`,
+      `   - Purchase link: ${PURCHASE_URL}`,
+      '',
+      `📖 가이드 / Guide: https://github.com/HUA-Labs/hua-platform/tree/main/packages/hua-ux/docs`,
+    ],
+  };
+  
+  return messages.ko.join('\n');
+}