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

package/dist/presets/product.js

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

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@hua-labs/hua-ux",
+  "version": "0.1.0-alpha.0.1",
+  "description": "HUA UX - Ship UX faster: UI + motion + i18n, pre-wired. A framework for React product teams.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./src/index.ts",
+      "require": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./framework": {
+      "types": "./dist/framework/index.d.ts",
+      "import": "./src/framework/index.ts",
+      "require": "./src/framework/index.ts",
+      "default": "./dist/framework/index.js"
+    },
+    "./presets": {
+      "types": "./dist/presets/index.d.ts",
+      "import": "./src/presets/index.ts",
+      "require": "./src/presets/index.ts",
+      "default": "./dist/presets/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@hua-labs/i18n-core": "2.0.0",
+    "@hua-labs/i18n-core-zustand": "2.0.0",
+    "@hua-labs/motion-core": "2.0.1",
+    "@hua-labs/state": "0.1.0-alpha.0.1",
+    "@hua-labs/ui": "1.1.0-alpha.0.1"
+  },
+  "peerDependencies": {
+    "next": ">=13.0.0",
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "hua-ux",
+    "framework",
+    "react",
+    "ui",
+    "motion",
+    "i18n",
+    "typescript",
+    "nextjs"
+  ],
+  "author": "HUA Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HUA-Labs/HUA-Labs-public.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HUA-Labs/HUA-Labs-public/issues"
+  },
+  "homepage": "https://github.com/HUA-Labs/HUA-Labs-public#readme",
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "jsdom": "^27.2.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14"
+  },
+  "scripts": {
+    "build": "node ../../node_modules/typescript/lib/tsc.js",
+    "dev": "node ../../node_modules/typescript/lib/tsc.js --watch",
+    "clean": "rm -rf dist",
+    "lint": "echo 'Skipping lint for hua-ux (ESLint 8, needs separate config)'",
+    "type-check": "tsc --noEmit",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage"
+  }
+}

package/src/framework/README.md

@@ -0,0 +1,329 @@
+# @hua-labs/hua-ux/framework
+
+**Framework layer for hua-ux** - Structure and rules enforcement with developer affordances.
+
+A framework layer that wraps Next.js to enforce structure and conventions while providing maximum convenience through affordances.
+
+## Installation
+
+This is part of `@hua-labs/hua-ux`. Install the main package:
+
+```bash
+pnpm add @hua-labs/hua-ux zustand
+```
+
+## Features
+
+- ✅ **Automatic Provider Setup**: `HuaUxLayout` automatically configures i18n, motion, and state
+- ✅ **Configuration System**: Type-safe configuration via `hua-ux.config.ts`
+- ✅ **Data Fetching**: Type-safe utilities for server and client components
+- ✅ **Middleware System**: Built-in i18n middleware for language detection
+- ✅ **File Structure Validation**: Ensures project follows framework conventions
+- ✅ **Type Safe**: Full TypeScript support with autocomplete
+
+## Quick Start
+
+### 사용 방법 선택
+
+**프레임워크 레이어를 사용하는 방법 (권장)**:
+- `HuaUxLayout`을 사용하면 모든 Provider가 자동으로 설정됩니다
+- 설정 파일만으로 간단하게 시작할 수 있습니다
+
+**직접 사용하는 방법**:
+- 더 세밀한 제어가 필요한 경우 `createI18nStore` + `createZustandI18n` 조합 사용
+- 자세한 내용은 [메인 README](../../README.md)의 "방법 2: 직접 사용" 섹션 참고
+
+### 1. Configuration
+
+Create `hua-ux.config.ts` in your project root:
+
+```tsx
+import { defineConfig } from '@hua-labs/hua-ux/framework';
+
+export default defineConfig({
+  i18n: {
+    defaultLanguage: 'ko',
+    supportedLanguages: ['ko', 'en'],
+    namespaces: ['common'],
+    translationLoader: 'api',
+    translationApiPath: '/api/translations',
+  },
+  motion: {
+    defaultPreset: 'product',
+    enableAnimations: true,
+  },
+  state: {
+    persist: true,
+    ssr: true,
+  },
+});
+```
+
+### 2. Root Layout
+
+```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>
+  );
+}
+```
+
+### 3. Pages
+
+#### Basic Page (Client Component)
+
+```tsx
+// app/page.tsx
+'use client';
+
+import { HuaUxPage } from '@hua-labs/hua-ux/framework';
+
+export default function HomePage() {
+  return (
+    <HuaUxPage title="Home" description="Welcome page">
+      <h1>Welcome</h1>
+    </HuaUxPage>
+  );
+}
+```
+
+#### Page with SEO Metadata (Server Component + Client Component)
+
+For better SEO, use Next.js `metadata` export in Server Components:
+
+```tsx
+// app/page.tsx
+import { generatePageMetadata } from '@hua-labs/hua-ux/framework';
+import { HomePageContent } from './HomePageContent';
+
+export const metadata = generatePageMetadata({
+  title: '홈',
+  description: '환영합니다',
+  seo: {
+    keywords: ['키워드1', '키워드2'],
+    ogImage: '/og-image.png',
+    ogTitle: '홈 | 우리 회사',
+    ogDescription: '우리 회사에 오신 것을 환영합니다',
+  },
+});
+
+export default function HomePage() {
+  return <HomePageContent />;
+}
+```
+
+```tsx
+// app/HomePageContent.tsx (Client Component)
+'use client';
+
+import { HuaUxPage } from '@hua-labs/hua-ux/framework';
+
+export function HomePageContent() {
+  return (
+    <HuaUxPage title="Home" description="Welcome page">
+      <h1>Welcome</h1>
+    </HuaUxPage>
+  );
+}
+```
+
+## API
+
+### Components
+
+#### `HuaUxLayout`
+
+Root layout wrapper that automatically sets up all providers.
+
+```tsx
+<HuaUxLayout config={overrideConfig}>
+  {children}
+</HuaUxLayout>
+```
+
+#### `HuaUxPage`
+
+Page wrapper with automatic motion and i18n support.
+
+```tsx
+<HuaUxPage title="Page Title" enableMotion={true}>
+  {children}
+</HuaUxPage>
+```
+
+### Configuration
+
+#### `defineConfig(config)`
+
+Define framework configuration.
+
+```tsx
+export default defineConfig({
+  i18n: { /* ... */ },
+  motion: { /* ... */ },
+  state: { /* ... */ },
+});
+```
+
+### Data Fetching
+
+#### `useData<T>(url, options?)`
+
+Client-side data fetching hook.
+
+**Parameters**:
+- `url`: API endpoint to fetch from
+- `options`: Optional `RequestInit` configuration (standard fetch options)
+  - **Note**: Currently supports standard `RequestInit` only. For advanced features like `revalidateOnFocus`, `revalidateOnReconnect`, or `refreshInterval`, consider using SWR or React Query.
+
+**Returns**:
+- `data`: Fetched data (or `null` if loading/error)
+- `isLoading`: Loading state
+- `error`: Error object (or `null`)
+- `refetch`: Function to manually refetch data
+
+**Usage in Client Components**:
+
+```tsx
+'use client';
+
+import { useData } from '@hua-labs/hua-ux/framework';
+
+interface Post {
+  id: string;
+  title: string;
+}
+
+export default function PostsPage() {
+  const { data, isLoading, error, refetch } = useData<Post[]>('/api/posts');
+  
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
+  return (
+    <div>
+      {data?.map(post => (
+        <div key={post.id}>{post.title}</div>
+      ))}
+      <button onClick={() => refetch()}>Refresh</button>
+    </div>
+  );
+}
+```
+
+#### `fetchData<T>(url, options?)`
+
+Server-side data fetching utility.
+
+**Parameters**:
+- `url`: API endpoint to fetch from
+- `options`: Optional `RequestInit` configuration (standard fetch options)
+
+**Returns**: Promise that resolves to the fetched data
+
+**Throws**: `Error` if the request fails or response is not ok
+
+**Usage in Server Components**:
+
+```tsx
+// app/posts/page.tsx (Server Component)
+import { fetchData } from '@hua-labs/hua-ux/framework';
+
+interface Post {
+  id: string;
+  title: string;
+}
+
+export default async function PostsPage() {
+  try {
+    const posts = await fetchData<Post[]>('/api/posts');
+    
+    return (
+      <div>
+        {posts.map(post => (
+          <div key={post.id}>{post.title}</div>
+        ))}
+      </div>
+    );
+  } catch (error) {
+    // Handle error appropriately
+    console.error('Failed to fetch posts:', error);
+    return <div>Error loading posts. Please try again later.</div>;
+  }
+}
+```
+
+**Error Handling**:
+Always wrap `fetchData` calls in try-catch blocks in Server Components, as it throws errors on failure.
+
+### Middleware
+
+#### `createI18nMiddleware(config)`
+
+Create i18n middleware for Next.js.
+
+**⚠️ Edge Runtime Required**: Next.js middleware runs on Edge Runtime. Make sure to export the runtime config:
+
+```tsx
+// middleware.ts
+import { createI18nMiddleware } from '@hua-labs/hua-ux/framework';
+
+// Edge Runtime 명시 (권장)
+// Next.js middleware는 기본적으로 Edge Runtime에서 실행됩니다.
+// Vercel과 같은 플랫폼은 자동으로 Edge Runtime을 감지하지만,
+// 명시적으로 설정하는 것이 좋습니다.
+// Next.js middleware runs on Edge Runtime by default.
+// Platforms like Vercel auto-detect Edge Runtime, but explicit configuration is recommended.
+export const runtime = 'edge';
+
+export default createI18nMiddleware({
+  defaultLanguage: 'ko',
+  supportedLanguages: ['ko', 'en'],
+  detectionStrategy: 'header',
+});
+```
+
+**Edge Runtime 제약사항 / Edge Runtime Limitations**:
+- Node.js API 사용 불가 (fs, path 등) / Cannot use Node.js APIs (fs, path, etc.)
+- 일부 npm 패키지가 Edge Runtime과 호환되지 않을 수 있음 / Some npm packages may not be compatible with Edge Runtime
+- Next.js middleware는 기본적으로 Edge Runtime에서 실행됩니다 / Next.js middleware runs on Edge Runtime by default
+
+**대안 / Alternatives**: 
+- Edge Runtime을 사용하지 않으려면 API Route나 클라이언트 컴포넌트에서 언어 감지를 처리할 수 있습니다.  
+- If you don't want to use Edge Runtime, you can handle language detection in API routes or client components.
+
+**Edge Runtime에서 사용 불가능한 기능 / Features Not Available in Edge Runtime**:
+- `loadConfig()`: 설정 파일 동적 로드 (서버 전용) / Dynamic config file loading (server-only)
+- `validateFileStructure()`: 파일 구조 검증 (서버 전용) / File structure validation (server-only)
+- Node.js 모듈 사용 (`fs`, `path` 등) / Using Node.js modules (`fs`, `path`, etc.)
+
+**권장 사항 / Recommendations**:
+- 미들웨어는 선택적 기능입니다. 사용하지 않아도 프레임워크는 정상 작동합니다.  
+- Middleware is optional. The framework works fine without it.
+- 언어 감지는 클라이언트 컴포넌트나 API Route에서 처리할 수 있습니다.  
+- Language detection can be handled in client components or API routes.
+
+### File Structure
+
+#### `validateFileStructure(projectRoot)`
+
+Validate project file structure.
+
+```tsx
+const result = validateFileStructure(process.cwd());
+if (!result.valid) {
+  console.error('Missing directories:', result.missing);
+}
+```
+
+## License
+
+MIT

package/src/framework/__tests__/branding/css-vars.test.ts

@@ -0,0 +1,147 @@
+/**
+ * @hua-labs/hua-ux/framework - CSS Variables Generator Tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import { generateCSSVariables, generateCSSVariablesObject } from '../../branding/css-vars';
+import type { HuaUxConfig } from '../../types';
+
+describe('generateCSSVariables', () => {
+  it('should generate empty string for empty branding', () => {
+    const branding = {} as NonNullable<HuaUxConfig['branding']>;
+    const result = generateCSSVariables(branding);
+
+    expect(result).toBe('');
+  });
+
+  it('should generate color variables', () => {
+    const branding: NonNullable<HuaUxConfig['branding']> = {
+      colors: {
+        primary: '#3B82F6',
+        secondary: '#8B5CF6',
+      },
+    };
+
+    const result = generateCSSVariables(branding);
+
+    expect(result).toContain('--color-primary: #3B82F6');
+    expect(result).toContain('--color-secondary: #8B5CF6');
+    expect(result).toContain(':root');
+  });
+
+  it('should generate typography variables', () => {
+    const branding: NonNullable<HuaUxConfig['branding']> = {
+      typography: {
+        fontFamily: ['Inter', 'sans-serif'],
+        fontSize: {
+          sm: '0.875rem',
+          md: '1rem',
+        },
+      },
+    };
+
+    const result = generateCSSVariables(branding);
+
+    expect(result).toContain('--font-family: Inter, sans-serif');
+    expect(result).toContain('--font-size-sm: 0.875rem');
+    expect(result).toContain('--font-size-md: 1rem');
+  });
+
+  it('should generate custom variables', () => {
+    const branding: NonNullable<HuaUxConfig['branding']> = {
+      customVariables: {
+        'spacing-unit': '8px',
+        'border-radius': '4px',
+      },
+    };
+
+    const result = generateCSSVariables(branding);
+
+    expect(result).toContain('--spacing-unit: 8px');
+    expect(result).toContain('--border-radius: 4px');
+  });
+
+  it('should generate all variable types together', () => {
+    const branding: NonNullable<HuaUxConfig['branding']> = {
+      colors: {
+        primary: '#3B82F6',
+      },
+      typography: {
+        fontFamily: ['Inter', 'sans-serif'],
+      },
+      customVariables: {
+        'spacing-unit': '8px',
+      },
+    };
+
+    const result = generateCSSVariables(branding);
+
+    expect(result).toContain('--color-primary: #3B82F6');
+    expect(result).toContain('--font-family: Inter, sans-serif');
+    expect(result).toContain('--spacing-unit: 8px');
+  });
+
+  it('should format output correctly', () => {
+    const branding: NonNullable<HuaUxConfig['branding']> = {
+      colors: {
+        primary: '#3B82F6',
+      },
+    };
+
+    const result = generateCSSVariables(branding);
+
+    expect(result).toMatch(/^:root \{[^}]*\}$/);
+    expect(result).toContain('\n');
+  });
+});
+
+describe('generateCSSVariablesObject', () => {
+  it('should generate empty object for empty branding', () => {
+    const branding = {} as NonNullable<HuaUxConfig['branding']>;
+    const result = generateCSSVariablesObject(branding);
+
+    expect(result).toEqual({});
+  });
+
+  it('should generate color variables as object', () => {
+    const branding: NonNullable<HuaUxConfig['branding']> = {
+      colors: {
+        primary: '#3B82F6',
+        secondary: '#8B5CF6',
+      },
+    };
+
+    const result = generateCSSVariablesObject(branding);
+
+    expect(result['--color-primary']).toBe('#3B82F6');
+    expect(result['--color-secondary']).toBe('#8B5CF6');
+  });
+
+  it('should generate typography variables as object', () => {
+    const branding: NonNullable<HuaUxConfig['branding']> = {
+      typography: {
+        fontFamily: ['Inter', 'sans-serif'],
+        fontSize: {
+          sm: '0.875rem',
+        },
+      },
+    };
+
+    const result = generateCSSVariablesObject(branding);
+
+    expect(result['--font-family']).toBe('Inter, sans-serif');
+    expect(result['--font-size-sm']).toBe('0.875rem');
+  });
+
+  it('should generate custom variables as object', () => {
+    const branding: NonNullable<HuaUxConfig['branding']> = {
+      customVariables: {
+        'spacing-unit': '8px',
+      },
+    };
+
+    const result = generateCSSVariablesObject(branding);
+
+    expect(result['--spacing-unit']).toBe('8px');
+  });
+});