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

package/templates/nextjs/ai-context.md

@@ -0,0 +1,332 @@
+# hua-ux Project AI Context
+
+This document is a guide for AI tools (Cursor, etc.) to understand the structure and usage of this project.
+
+## Project Overview
+
+This project uses the **hua-ux framework** for Next.js applications.
+
+**Core Philosophy**: "You don't need to know Next.js. Just configure and tell AI what to do."
+
+## Architecture Layers
+
+### Top Layer: AI Context & CLI (Current Location)
+- `.cursorrules`: Rules for AI to follow when generating code
+- `ai-context.md`: This document (project structure explanation)
+- `.claude/project-context.md`: Claude-specific context
+
+### Middle Layer: Framework & Config
+- `hua-ux.config.ts`: Framework configuration
+- `HuaUxLayout`: Automatic Provider setup
+- `HuaUxPage`: Page wrapper (Motion, i18n, SEO automatically applied)
+
+### Bottom Layer: Core & Types
+- `@hua-labs/state`: State management
+- `@hua-labs/motion-core`: Motion/animations
+- `@hua-labs/i18n-core`: Internationalization
+- `@hua-labs/ui`: UI component library
+
+## Project Structure
+
+```
+Project Root/
+├── app/                    # Next.js App Router pages
+│   ├── layout.tsx          # Root layout (uses HuaUxLayout)
+│   ├── page.tsx            # Home page (uses HuaUxPage)
+│   └── api/                # API Routes
+│       └── translations/   # i18n translation API
+├── components/             # Reusable components
+├── lib/                    # Utility functions
+│   └── i18n-setup.ts      # i18n setup
+├── store/                  # Zustand stores
+│   └── useAppStore.ts     # Global state
+├── translations/           # Translation files
+│   ├── ko/                # Korean
+│   │   └── common.json    # Common translations
+│   └── en/                # English
+│       └── common.json    # Common translations
+└── hua-ux.config.ts        # Framework configuration
+```
+
+## Available Components and Hooks
+
+### @hua-labs/ui Components
+
+**Core UI**:
+- `Button`, `Action`, `Input`, `Link`, `Icon`, `Avatar`, `Modal`
+
+**Layout**:
+- `Container`, `Grid`, `Stack`, `Divider`, `Card` (CardHeader, CardTitle, CardDescription, CardContent, CardFooter), `Panel`, `ActionToolbar`, `ComponentLayout`
+
+**Navigation**:
+- `Navigation`, `Breadcrumb`, `Pagination`, `PageNavigation`, `PageTransition`
+
+**Data Display**:
+- `Table`, `Badge`, `Progress`, `Skeleton` (various variants)
+
+**Feedback**:
+- `Alert` (Success, Warning, Error, Info), `Toast` (ToastProvider, useToast), `LoadingSpinner`, `Tooltip`
+
+**Overlay**:
+- `Popover`, `Dropdown`, `Drawer`, `BottomSheet`, `ConfirmModal`
+
+**Form**:
+- `Form`, `Label`, `Checkbox`, `Radio`, `Select`, `Switch`, `Slider`, `Textarea`, `DatePicker`, `Upload`, `Autocomplete`
+
+**Interactive**:
+- `Accordion`, `Tabs`, `Menu`, `ContextMenu`, `Command`
+
+**Specialized**:
+- `ScrollArea`, `ScrollToTop`, `ThemeProvider`, `ThemeToggle`, `useTheme`
+
+### @hua-labs/hua-ux/framework
+
+**Framework Components**:
+- `HuaUxLayout`: Automatic Provider setup
+- `HuaUxPage`: Page wrapper (Motion, i18n, SEO automatically applied)
+- `UnifiedProviders`: All Providers unified
+- `BrandedButton`, `BrandedCard`: Components with automatic branding
+- `ErrorBoundary`: Error boundary
+
+**Hooks**:
+- `useMotion`: Unified motion hook
+- `useData`: Client data fetching
+- `useFocusManagement`, `useFocusTrap`: Accessibility hooks
+- `useDelayedLoading`, `useLoadingState`: Loading state hooks
+- `useLiveRegion`: Screen reader support
+
+**Utilities**:
+- `fetchData`: Server data fetching
+- `generatePageMetadata`: SEO metadata generation
+- `generateGEOMetadata`: GEO metadata generation
+- `createI18nMiddleware`: i18n middleware creation
+
+**Configuration**:
+- `defineConfig`: Framework configuration definition
+- `getConfig`: Get configuration
+
+### @hua-labs/motion-core
+
+**Motion Hooks**:
+- `useFadeIn`, `useSlideUp`, `useSlideLeft`, `useSlideRight`, `useScaleIn`, `useBounceIn`, `usePulse`, `useSpringMotion`
+- `useHoverMotion`, `useClickToggle`, `useFocusToggle`
+- `useScrollReveal`, `useScrollProgress`
+
+### @hua-labs/i18n-core
+
+**i18n Hooks**:
+- `useTranslation`: Translation hook
+- `useLanguage`: Language change hook
+
+## Key Patterns
+
+### 1. Page Creation Pattern
+
+```tsx
+// app/my-page/page.tsx
+import { HuaUxPage } from '@hua-labs/hua-ux/framework';
+import { useTranslation } from '@hua-labs/i18n-core';
+
+export default function MyPage() {
+  const { t } = useTranslation('my-page');
+  
+  return (
+    <HuaUxPage title={t('title')} description={t('description')}>
+      <h1>{t('title')}</h1>
+      {/* content */}
+    </HuaUxPage>
+  );
+}
+```
+
+**Important**: 
+- Wrapping with `HuaUxPage` automatically applies Motion, i18n, SEO
+- Add translation keys to `translations/{language}/my-page.json`
+- Create as Server Component (add `'use client'` only when client features are needed)
+
+### 2. Client Component Creation Pattern
+
+```tsx
+// components/MyComponent.tsx
+'use client';
+
+import { Card, Button } from '@hua-labs/ui';
+import { useMotion } from '@hua-labs/hua-ux/framework';
+import { useTranslation } from '@hua-labs/i18n-core';
+
+export function MyComponent() {
+  const { t } = useTranslation('my-component');
+  const motion = useMotion();
+  
+  return (
+    <Card ref={motion.ref} style={motion.style}>
+      <h2>{t('title')}</h2>
+      <Button>{t('button')}</Button>
+    </Card>
+  );
+}
+```
+
+**Important**:
+- Client components require `'use client'`
+- Utilize framework components (`@hua-labs/ui`, `@hua-labs/motion-core`)
+- Consider applying motion
+
+### 3. Data Fetching Pattern
+
+**Server Component**:
+```tsx
+// app/data/page.tsx
+import { fetchData } from '@hua-labs/hua-ux/framework';
+
+export default async function DataPage() {
+  const data = await fetchData<DataType>('/api/data');
+  return <div>{/* display data */}</div>;
+}
+```
+
+**Client Component**:
+```tsx
+// components/DataComponent.tsx
+'use client';
+
+import { useData } from '@hua-labs/hua-ux/framework';
+import { LoadingSpinner, AlertError } from '@hua-labs/ui';
+
+export function DataComponent() {
+  const { data, isLoading, error } = useData<DataType>('/api/data');
+  
+  if (isLoading) return <LoadingSpinner />;
+  if (error) return <AlertError>{error.message}</AlertError>;
+  return <div>{/* display data */}</div>;
+}
+```
+
+### 4. Translation File Pattern
+
+```json
+// translations/ko/my-page.json
+{
+  "title": "Title",
+  "description": "Description",
+  "button": "Button"
+}
+
+// translations/en/my-page.json
+{
+  "title": "Title",
+  "description": "Description",
+  "button": "Button"
+}
+```
+
+**Important**:
+- Add all translation keys to both Korean and English
+- Namespace should match page name
+- Use `common` namespace for shared translations
+
+## Understanding Configuration Files
+
+### hua-ux.config.ts
+
+```typescript
+import { defineConfig } from '@hua-labs/hua-ux/framework';
+
+export default defineConfig({
+  preset: 'product',  // 'product' or 'marketing'
+  
+  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,
+  },
+});
+```
+
+**Preset Selection**:
+- `'product'`: For product pages (professional, efficient)
+- `'marketing'`: For marketing pages (dramatic, eye-catching)
+
+**Branding Configuration** (optional):
+```typescript
+branding: {
+  colors: {
+    primary: '#000000',
+    secondary: '#666666',
+  },
+  typography: {
+    fontFamily: {
+      sans: ['Pretendard', 'sans-serif'],
+    },
+  },
+}
+```
+
+## Guidelines for AI Code Generation
+
+1. **When Creating Pages**:
+   - Wrap with `HuaUxPage`
+   - Generate translation files together
+   - Use `useTranslation` hook
+   - Prefer Server Components (add `'use client'` only when client features are needed)
+
+2. **When Creating Components**:
+   - Add `'use client'` directive (for client components)
+   - Utilize framework components
+   - Consider applying motion
+   - Consider accessibility (aria-label, etc.)
+
+3. **When Adding Translations**:
+   - Add both Korean and English
+   - Maintain namespace consistency
+   - Use `common` namespace for shared translations
+
+4. **When Changing Configuration**:
+   - Only modify `hua-ux.config.ts`
+   - Prefer Preset (over manual configuration)
+
+5. **When Fetching Data**:
+   - Use `fetchData` in Server Components
+   - Use `useData` in Client Components
+   - Error handling is required
+
+## Common Commands
+
+```bash
+# Start development server
+pnpm dev
+
+# Build
+pnpm build
+
+# Start production
+pnpm start
+
+# Lint
+pnpm lint
+
+# Fix linting automatically
+pnpm lint:fix
+```
+
+## References
+
+- Framework docs: `node_modules/@hua-labs/hua-ux/README.md`
+- UI components: `node_modules/@hua-labs/ui/README.md`
+- Motion: `node_modules/@hua-labs/motion-core/README.md`
+- i18n: `node_modules/@hua-labs/i18n-core-zustand/README.md`
+- `.cursorrules`: Cursor IDE rules
+- `.claude/project-context.md`: Claude-specific context

package/templates/nextjs/app/api/translations/[language]/[namespace]/route.ts

@@ -0,0 +1,86 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Translation API Route (Dynamic Path)
+ * 
+ * 번역 파일을 제공하는 API 엔드포인트입니다.
+ * Provides translation files via API endpoint.
+ * 
+ * 경로: /api/translations/[language]/[namespace]
+ * Path: /api/translations/[language]/[namespace]
+ * 
+ * @param request - Next.js request object
+ * @param params - Route parameters: { language: string, namespace: string }
+ * @returns Translation object or error response
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { language: string; namespace: string } }
+) {
+  const { language, namespace } = params;
+
+  // 언어 검증
+  // Validate language
+  const supportedLanguages = ['ko', 'en'];
+  if (!supportedLanguages.includes(language)) {
+    return NextResponse.json(
+      { error: 'Unsupported language' },
+      { status: 400 }
+    );
+  }
+
+  // 네임스페이스 검증 (보안: 파일 경로 조작 방지)
+  // Validate namespace (security: prevent path traversal)
+  const safeNamespace = namespace.replace(/[^a-zA-Z0-9-_]/g, '');
+  if (safeNamespace !== namespace) {
+    return NextResponse.json(
+      { error: 'Invalid namespace' },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const filePath = join(process.cwd(), 'translations', language, `${safeNamespace}.json`);
+    const fileContents = readFileSync(filePath, 'utf-8');
+    const translations = JSON.parse(fileContents);
+
+    return NextResponse.json(translations, {
+      headers: {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
+      },
+    });
+  } catch (error) {
+    // 에러 타입 구분
+    // Distinguish error types
+    
+    // 파일이 없는 경우
+    // File not found
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return NextResponse.json(
+        { error: 'Translation file not found' },
+        { status: 404 }
+      );
+    }
+    
+    // JSON 파싱 에러
+    // JSON parse error
+    if (error instanceof SyntaxError) {
+      console.error('Translation JSON parse error:', error);
+      return NextResponse.json(
+        { error: 'Invalid translation file format' },
+        { status: 500 }
+      );
+    }
+
+    // 기타 에러
+    // Other errors
+    console.error('Translation load error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}

package/templates/nextjs/app/globals.css

@@ -0,0 +1,24 @@
+@import "tailwindcss";
+
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: system-ui, -apple-system, sans-serif;
+}

package/templates/nextjs/app/layout-with-geo.example.tsx

@@ -0,0 +1,106 @@
+/**
+ * Root Layout with GEO (Generative Engine Optimization)
+ * 
+ * AI 검색 엔진 최적화를 위한 예제 레이아웃
+ * Example layout with AI search engine optimization
+ * 
+ * 사용 방법:
+ * 1. 이 파일을 app/layout.tsx로 복사
+ * 2. GEO 설정을 프로젝트에 맞게 수정
+ * 3. JSON-LD 스크립트를 추가하려면 Script 컴포넌트 import
+ */
+
+import type { Metadata } from "next";
+import { headers } from "next/headers";
+import Script from "next/script";
+import "./globals.css";
+import { HuaUxLayout } from "@hua-labs/hua-ux/framework";
+import { generateGEOMetadata, renderJSONLD } from "@hua-labs/hua-ux/framework";
+
+// GEO 메타데이터 생성
+// Generate GEO metadata for AI search engines
+const geoMetadata = generateGEOMetadata({
+  name: 'My App',
+  description: 'Built with hua-ux framework - A modern UX framework for Next.js',
+  version: '1.0.0',
+  applicationCategory: ['UX Framework', 'Developer Tool'],
+  programmingLanguage: ['TypeScript', 'React', 'Next.js'],
+  features: [
+    'Internationalization (i18n)',
+    'Motion animations',
+    'Accessibility (WCAG 2.1)',
+    'Error handling',
+    'Loading state optimization',
+  ],
+  useCases: [
+    'Building multilingual Next.js applications',
+    'Creating accessible web applications',
+    'Rapid prototyping with AI-friendly documentation',
+  ],
+  keywords: [
+    'nextjs',
+    'react',
+    'ux',
+    'i18n',
+    'internationalization',
+    'accessibility',
+    'a11y',
+    'motion',
+    'animation',
+    'framework',
+  ],
+  codeRepository: 'https://github.com/your-org/your-app',
+  documentationUrl: 'https://your-app.com/docs',
+  license: 'MIT',
+  author: {
+    name: 'Your Organization',
+    url: 'https://your-org.com',
+  },
+});
+
+// Next.js Metadata와 GEO 통합
+// Integrate GEO with Next.js Metadata
+export const metadata: Metadata = {
+  title: geoMetadata.meta.find((m) => m.name === 'description')?.content || 'My App',
+  description: geoMetadata.meta.find((m) => m.name === 'description')?.content,
+  keywords: geoMetadata.meta.find((m) => m.name === 'keywords')?.content?.split(', '),
+  openGraph: {
+    title: geoMetadata.openGraph?.find((og) => og.property === 'og:title')?.content,
+    description: geoMetadata.openGraph?.find((og) => og.property === 'og:description')?.content,
+    type: 'website',
+  },
+  twitter: {
+    card: geoMetadata.twitter?.find((t) => t.name === 'twitter:card')?.content as 'summary_large_image',
+    title: geoMetadata.twitter?.find((t) => t.name === 'twitter:title')?.content,
+    description: geoMetadata.twitter?.find((t) => t.name === 'twitter:description')?.content,
+  },
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  // 동적 언어 설정 (middleware에서 설정한 헤더 사용)
+  // Dynamic language setting (use header set by middleware)
+  const headersList = headers();
+  const language = headersList.get('x-language') || 'ko'; // 기본값: 'ko'
+
+  return (
+    <html lang={language}>
+      <head>
+        {/* JSON-LD Structured Data for AI search engines */}
+        {/* AI 검색 엔진을 위한 구조화된 데이터 */}
+        {geoMetadata.jsonLd.map((jsonLd, index) => (
+          <Script
+            key={index}
+            {...renderJSONLD(jsonLd)}
+          />
+        ))}
+      </head>
+      <body className="antialiased">
+        <HuaUxLayout>{children}</HuaUxLayout>
+      </body>
+    </html>
+  );
+}

package/templates/nextjs/app/layout.tsx

@@ -0,0 +1,30 @@
+import type { Metadata } from "next";
+import { headers } from "next/headers";
+import "./globals.css";
+import { HuaUxLayout } from "@hua-labs/hua-ux/framework";
+
+export const metadata: Metadata = {
+  title: "HUA UX App",
+  description: "Created with hua-ux",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  // 동적 언어 설정 (middleware에서 설정한 헤더 사용)
+  // Dynamic language setting (use header set by middleware)
+  // middleware.ts에서 'x-language' 헤더를 설정하면 여기서 읽을 수 있습니다.
+  // If middleware.ts sets 'x-language' header, it can be read here.
+  const headersList = headers();
+  const language = headersList.get('x-language') || 'ko'; // 기본값: 'ko'
+
+  return (
+    <html lang={language}>
+      <body className="antialiased">
+        <HuaUxLayout>{children}</HuaUxLayout>
+      </body>
+    </html>
+  );
+}

package/templates/nextjs/app/page-with-geo.example.tsx

@@ -0,0 +1,80 @@
+/**
+ * Home Page with GEO and SEO Metadata
+ * 
+ * GEO 및 SEO 메타데이터가 포함된 홈 페이지 예제
+ * Example home page with GEO and SEO metadata
+ * 
+ * 사용 방법:
+ * 1. Server Component로 page.tsx 생성
+ * 2. Client Component로 page-content.tsx 생성
+ * 3. 이 예제를 참고하여 구현
+ */
+
+// ============================================
+// app/page.tsx (Server Component)
+// ============================================
+import { generatePageMetadata, generateGEOMetadata, renderJSONLD } from '@hua-labs/hua-ux/framework';
+import Script from 'next/script';
+import { HomePageContent } from './page-content';
+
+// 페이지별 GEO 메타데이터 생성
+// Generate page-specific GEO metadata
+const pageGeoMetadata = generateGEOMetadata({
+  name: 'Home - My App',
+  description: 'Welcome to My App - Built with hua-ux framework',
+  applicationCategory: 'WebApplication',
+  keywords: ['home', 'welcome', 'nextjs', 'react'],
+});
+
+// Next.js Metadata 생성 (GEO와 통합)
+// Generate Next.js Metadata (integrated with GEO)
+export const metadata = generatePageMetadata({
+  title: 'Home',
+  description: pageGeoMetadata.meta.find((m) => m.name === 'description')?.content || 'Welcome',
+  seo: {
+    keywords: ['home', 'welcome'],
+    ogImage: '/og-home.png',
+  },
+});
+
+export default function HomePage() {
+  return (
+    <>
+      {/* JSON-LD Structured Data */}
+      <Script {...renderJSONLD(pageGeoMetadata.jsonLd[0])} />
+      <HomePageContent />
+    </>
+  );
+}
+
+// ============================================
+// app/page-content.tsx (Client Component)
+// ============================================
+'use client';
+
+import { HuaUxPage } from "@hua-labs/hua-ux/framework";
+import { Button, Card } from "@hua-labs/hua-ux";
+import { useTranslation } from '@hua-labs/i18n-core';
+
+export function HomePageContent() {
+  const { t } = useTranslation('common');
+  
+  return (
+    <HuaUxPage title={t('title')} description={t('welcome')}>
+      <div className="min-h-screen flex items-center justify-center p-8">
+        <Card className="max-w-2xl w-full">
+          <div className="p-8 text-center space-y-6">
+            <h1 className="text-4xl font-bold">{t('title')}</h1>
+            <p className="text-gray-600 dark:text-gray-400">
+              {t('welcome')}
+            </p>
+            <div className="flex gap-4 justify-center">
+              <Button variant="default">{t('getStarted')}</Button>
+              <Button variant="outline">{t('learnMore')}</Button>
+            </div>
+          </div>
+        </Card>
+      </div>
+    </HuaUxPage>
+  );
+}

package/templates/nextjs/app/page.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+import { HuaUxPage } from "@hua-labs/hua-ux/framework";
+import { Button, Card } from "@hua-labs/hua-ux";
+import { useTranslation } from '@hua-labs/i18n-core';
+
+export default function HomePage() {
+  const { t } = useTranslation('common');
+  
+  return (
+    <HuaUxPage title={t('title')} description={t('welcome')}>
+      <div className="min-h-screen flex items-center justify-center p-8">
+        <Card className="max-w-2xl w-full">
+          <div className="p-8 text-center space-y-6">
+            <h1 className="text-4xl font-bold">{t('title')}</h1>
+            <p className="text-gray-600 dark:text-gray-400">
+              {t('welcome')}
+            </p>
+            <div className="flex gap-4 justify-center">
+              <Button variant="default">{t('getStarted')}</Button>
+              <Button variant="outline">{t('learnMore')}</Button>
+            </div>
+          </div>
+        </Card>
+      </div>
+    </HuaUxPage>
+  );
+}