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

package/src/framework/utils/file-structure.ts

@@ -0,0 +1,88 @@
+/**
+ * @hua-labs/hua-ux/framework - File Structure Validation
+ * 
+ * Validates project file structure according to framework conventions
+ * 
+ * **서버 전용**: 이 모듈은 Node.js 환경에서만 사용 가능합니다.
+ * **Server Only**: This module is only available in Node.js environment.
+ */
+
+// 서버 환경에서만 fs 사용
+let existsSync: typeof import('fs')['existsSync'];
+let join: typeof import('path')['join'];
+
+if (typeof window === 'undefined' && typeof require !== 'undefined') {
+  // Node.js 환경
+  const fs = require('fs');
+  const path = require('path');
+  existsSync = fs.existsSync;
+  join = path.join;
+} else {
+  // 클라이언트 환경: 더미 함수 (사용 시 에러)
+  existsSync = () => {
+    throw new Error('validateFileStructure is only available in Node.js environment');
+  };
+  join = (...args: string[]) => args.join('/');
+}
+
+/**
+ * Expected directory structure
+ */
+const REQUIRED_DIRS = [
+  'app',
+  'components',
+  'lib',
+] as const;
+
+const OPTIONAL_DIRS = [
+  'hooks',
+  'store',
+  'translations',
+] as const;
+
+/**
+ * File structure validation result
+ */
+export interface FileStructureResult {
+  valid: boolean;
+  missing: string[];
+  warnings: string[];
+}
+
+/**
+ * Validate project file structure
+ * 
+ * @example
+ * ```ts
+ * const result = validateFileStructure(process.cwd());
+ * if (!result.valid) {
+ *   console.error('Missing directories:', result.missing);
+ * }
+ * ```
+ */
+export function validateFileStructure(projectRoot: string): FileStructureResult {
+  const missing: string[] = [];
+  const warnings: string[] = [];
+
+  // Check required directories
+  for (const dir of REQUIRED_DIRS) {
+    const dirPath = join(projectRoot, dir);
+    if (!existsSync(dirPath)) {
+      missing.push(dir);
+    }
+  }
+
+  // Check optional directories (warnings only)
+  for (const dir of OPTIONAL_DIRS) {
+    const dirPath = join(projectRoot, dir);
+    if (!existsSync(dirPath)) {
+      warnings.push(`Optional directory "${dir}" not found`);
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+    warnings,
+  };
+}

package/src/framework/utils/metadata.ts

@@ -0,0 +1,152 @@
+/**
+ * @hua-labs/hua-ux/framework - Metadata Utilities
+ * 
+ * Next.js Metadata 생성 유틸리티 (Next.js 없이도 사용 가능)
+ * 
+ * Next.js가 설치되어 있으면 Next.js Metadata 타입을 사용하고,
+ * 없으면 일반 메타데이터 객체 타입을 사용합니다.
+ * 
+ * Works with or without Next.js:
+ * - With Next.js: Returns Next.js Metadata type
+ * - Without Next.js: Returns generic metadata object type
+ */
+
+// Next.js Metadata 타입 - 조건부 타입으로 타입 안전성 향상
+// Next.js Metadata type - Improved type safety with conditional type
+type MetadataType = 
+  // Next.js가 설치되어 있으면 실제 Metadata 타입 사용
+  // Use actual Metadata type if Next.js is installed
+  typeof import('next') extends { Metadata: infer T } ? T
+  // 없으면 일반 메타데이터 객체 타입 사용
+  // Use generic metadata object type if not installed
+  : {
+      title?: string;
+      description?: string;
+      keywords?: string[];
+      openGraph?: {
+        title?: string;
+        description?: string;
+        type?: 'website' | 'article' | 'product';
+        images?: Array<{ url: string }>;
+      };
+      twitter?: {
+        card?: 'summary' | 'summary_large_image';
+        title?: string;
+        description?: string;
+        images?: string[];
+      };
+    };
+
+/**
+ * SEO 설정 타입
+ */
+export interface SEOConfig {
+  keywords?: string[];
+  ogImage?: string;
+  ogTitle?: string;
+  ogDescription?: string;
+  ogType?: 'website' | 'article' | 'product';
+}
+
+/**
+ * 페이지 메타데이터 생성
+ * 
+ * Next.js App Router의 `export const metadata`에서 사용할 수 있는 메타데이터를 생성합니다.
+ * CRA/Vite 등 일반 React 앱에서도 사용 가능합니다 (React Helmet 등과 함께).
+ * 
+ * Generates metadata that can be used in Next.js App Router's `export const metadata`.
+ * Also works in plain React apps (CRA/Vite) with React Helmet, etc.
+ * 
+ * @param options - 메타데이터 옵션
+ * @param options.title - 페이지 제목
+ * @param options.description - 페이지 설명
+ * @param options.seo - SEO 설정 (선택적)
+ * @returns Next.js Metadata 객체 (Next.js가 있으면) 또는 일반 메타데이터 객체 (없으면)
+ * 
+ * @example
+ * ```tsx
+ * // Next.js App Router
+ * // app/page.tsx
+ * import { generatePageMetadata } from '@hua-labs/hua-ux/framework';
+ * 
+ * export const metadata = generatePageMetadata({
+ *   title: '홈',
+ *   description: '환영합니다',
+ *   seo: {
+ *     keywords: ['키워드1', '키워드2'],
+ *     ogImage: '/og-image.png',
+ *   },
+ * });
+ * 
+ * export default function HomePage() {
+ *   return <div>...</div>;
+ * }
+ * ```
+ * 
+ * @example
+ * ```tsx
+ * // CRA/Vite (React Helmet 사용)
+ * import { Helmet } from 'react-helmet-async';
+ * import { generatePageMetadata } from '@hua-labs/hua-ux/framework';
+ * 
+ * export default function HomePage() {
+ *   const metadata = generatePageMetadata({
+ *     title: 'Home',
+ *     description: 'Welcome',
+ *   });
+ * 
+ *   return (
+ *     <>
+ *       <Helmet>
+ *         <title>{metadata.title}</title>
+ *         <meta name="description" content={metadata.description} />
+ *       </Helmet>
+ *       <div>...</div>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function generatePageMetadata(options: {
+  title: string;
+  description?: string;
+  seo?: SEOConfig;
+}): MetadataType {
+  const { title, description, seo } = options;
+
+  // 메타데이터 객체 직접 구성 (타입 안전하게)
+  // Build metadata object directly (type-safe)
+  const metadata: Record<string, unknown> = {
+    title,
+    description,
+  };
+
+  // Keywords 추가
+  if (seo?.keywords && seo.keywords.length > 0) {
+    metadata.keywords = seo.keywords;
+  }
+
+  // Open Graph 메타데이터
+  if (seo?.ogImage || seo?.ogTitle || seo?.ogDescription || seo?.ogType) {
+    metadata.openGraph = {
+      title: seo.ogTitle || title,
+      description: seo.ogDescription || description,
+      type: seo.ogType || 'website',
+      ...(seo.ogImage && { images: [{ url: seo.ogImage }] }),
+    };
+  }
+
+  // Twitter Card 메타데이터 (Open Graph가 있으면 자동으로 사용)
+  if (seo?.ogImage) {
+    metadata.twitter = {
+      card: 'summary_large_image',
+      ...(seo.ogTitle && { title: seo.ogTitle }),
+      ...(seo.ogDescription && { description: seo.ogDescription }),
+      ...(seo.ogImage && { images: [seo.ogImage] }),
+    };
+  }
+
+  // MetadataType으로 타입 단언 (조건부 타입이 컴파일 타임에 올바르게 추론됨)
+  // Type assertion to MetadataType (conditional type is correctly inferred at compile time)
+  return metadata as MetadataType;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @hua-labs/hua-ux
+ * 
+ * Ship UX faster: UI + motion + i18n, pre-wired.
+ * A framework for React product teams.
+ */
+
+// Re-export UI components
+// Note: Button and Card are overridden below with branded versions
+export * from '@hua-labs/ui'
+
+// Override Button and Card with branded versions for automatic branding
+// When branding is configured, these components automatically use branding colors
+// When branding is not configured, they work exactly like the original components
+export { BrandedButton as Button, BrandedCard as Card } from './framework'
+
+// Re-export Button and Card types (they're compatible with BrandedButton and BrandedCard)
+export type { ButtonProps } from '@hua-labs/ui'
+export type { CardProps, CardHeaderProps, CardTitleProps, CardDescriptionProps, CardContentProps, CardFooterProps } from '@hua-labs/ui'
+
+// Re-export Motion hooks
+export * from '@hua-labs/motion-core'
+
+// Re-export i18n core
+export * from '@hua-labs/i18n-core'
+
+// Re-export i18n Zustand adapter
+export * from '@hua-labs/i18n-core-zustand'
+
+// Re-export state management
+export * from '@hua-labs/state'

package/src/presets/index.ts

@@ -0,0 +1,8 @@
+/**
+ * HUA UX Presets
+ * 
+ * Pre-configured settings for common use cases
+ */
+
+export * from './product'
+export * from './marketing'

package/src/presets/marketing.ts

@@ -0,0 +1,88 @@
+/**
+ * Marketing Preset
+ * 
+ * 랜딩 페이지 모션 중심 설정
+ * 마케팅 페이지, 랜딩 페이지에 적합
+ */
+
+import type { MotionPreset, PresetConfig } from '@hua-labs/motion-core'
+
+/**
+ * Marketing Preset Configuration
+ * 
+ * - 드라마틱한 모션 (느린 전환, 긴 딜레이)
+ * - 넓은 스페이싱 (xl 기본값)
+ * - 호버/클릭 인터랙션 강조
+ */
+export const marketingPreset = {
+  /**
+   * Motion Presets for Marketing UI
+   */
+  motion: {
+    hero: {
+      entrance: 'fadeIn',
+      delay: 300,
+      duration: 1000,
+      hover: false,
+      click: false
+    } as MotionPreset,
+    title: {
+      entrance: 'slideUp',
+      delay: 500,
+      duration: 800,
+      hover: false,
+      click: false
+    } as MotionPreset,
+    button: {
+      entrance: 'scaleIn',
+      delay: 700,
+      duration: 400,
+      hover: true,
+      click: true
+    } as MotionPreset,
+    card: {
+      entrance: 'slideUp',
+      delay: 600,
+      duration: 600,
+      hover: true,
+      click: false
+    } as MotionPreset,
+    text: {
+      entrance: 'fadeIn',
+      delay: 400,
+      duration: 700,
+      hover: false,
+      click: false
+    } as MotionPreset,
+    image: {
+      entrance: 'scaleIn',
+      delay: 500,
+      duration: 800,
+      hover: true,
+      click: false
+    } as MotionPreset
+  } as PresetConfig,
+
+  /**
+   * Spacing Guidelines
+   * 
+   * - 기본 스페이싱: xl (24px)
+   * - 섹션 간격: xl (32px+)
+   * - 컴포넌트 내부: md (8px)
+   */
+  spacing: {
+    default: 'xl',
+    section: 'xl',
+    component: 'md'
+  },
+
+  /**
+   * i18n Configuration
+   */
+  i18n: {
+    defaultLanguage: 'ko',
+    supportedLanguages: ['ko', 'en']
+  }
+} as const
+
+export type MarketingPreset = typeof marketingPreset

package/src/presets/product.ts

@@ -0,0 +1,81 @@
+/**
+ * Product Preset
+ * 
+ * 기본 여백 + 기본 모션 설정
+ * 제품 페이지, 대시보드 등 일반적인 제품 UI에 적합
+ */
+
+import type { MotionPreset, PresetConfig } from '@hua-labs/motion-core'
+
+/**
+ * Product Preset Configuration
+ * 
+ * - 보수적인 모션 (빠른 전환, 최소한의 딜레이)
+ * - 일관된 스페이싱 (md 기본값)
+ * - 호버/클릭 인터랙션 최소화
+ */
+export const productPreset = {
+  /**
+   * Motion Presets for Product UI
+   */
+  motion: {
+    hero: {
+      entrance: 'fadeIn',
+      delay: 100,
+      duration: 400,
+      hover: false,
+      click: false
+    } as MotionPreset,
+    title: {
+      entrance: 'slideUp',
+      delay: 150,
+      duration: 350,
+      hover: false,
+      click: false
+    } as MotionPreset,
+    button: {
+      entrance: 'scaleIn',
+      delay: 200,
+      duration: 200,
+      hover: true,
+      click: true
+    } as MotionPreset,
+    card: {
+      entrance: 'slideUp',
+      delay: 100,
+      duration: 300,
+      hover: true,
+      click: false
+    } as MotionPreset,
+    text: {
+      entrance: 'fadeIn',
+      delay: 50,
+      duration: 300,
+      hover: false,
+      click: false
+    } as MotionPreset
+  } as PresetConfig,
+
+  /**
+   * Spacing Guidelines
+   * 
+   * - 기본 스페이싱: md (8px)
+   * - 섹션 간격: lg (16px)
+   * - 컴포넌트 내부: sm (4px)
+   */
+  spacing: {
+    default: 'md',
+    section: 'lg',
+    component: 'sm'
+  },
+
+  /**
+   * i18n Configuration
+   */
+  i18n: {
+    defaultLanguage: 'ko',
+    supportedLanguages: ['ko', 'en']
+  }
+} as const
+
+export type ProductPreset = typeof productPreset