npm - @hua-labs/ui - Versions diffs - 1.1.0-alpha.2 → 1.1.0-alpha.5 - Mend

@hua-labs/ui 1.1.0-alpha.2 → 1.1.0-alpha.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +187 -881
package/package.json +10 -6

package/README.md CHANGED Viewed

@@ -1,23 +1,27 @@
 # @hua-labs/ui
 Modern React UI component library with 70+ production-ready components.
-70개 이상의 프로덕션 준비 완료 React UI 컴포넌트 라이브러리.
+70개 이상의 프로덕션 레디 React UI 컴포넌트 라이브러리
 [![npm version](https://img.shields.io/npm/v/@hua-labs/ui.svg)](https://www.npmjs.com/package/@hua-labs/ui)
 [![npm downloads](https://img.shields.io/npm/dw/@hua-labs/ui.svg)](https://www.npmjs.com/package/@hua-labs/ui)
 [![license](https://img.shields.io/npm/l/@hua-labs/ui.svg)](https://github.com/HUA-Labs/HUA-Labs-public/blob/main/LICENSE)
+[![React](https://img.shields.io/badge/React-19-blue)](https://reactjs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
 > **⚠️ Alpha Release**: This package is currently in alpha. APIs may change before the stable release.
 ---
+[English](#english) | [한국어](#korean)
 ## English
 ### Overview
 Accessible, TypeScript-native component library for React applications. Provides modular entry points for optimal bundle size and comprehensive dark mode support.
-## Features
+### Features
 - 70+ production-ready components
 - Modular entry points for bundle optimization
@@ -29,7 +33,7 @@ Accessible, TypeScript-native component library for React applications. Provides
 - Zero external dependencies (except React)
 - Tailwind CSS based styling
-## Installation
+### Installation
 ```bash
 npm install @hua-labs/ui
@@ -49,90 +53,7 @@ npm install react react-dom
 npm install @phosphor-icons/react
 ```
-### 엔트리 포인트
-HUA UI는 **Core**, **Form**, **Advanced** 엔트리로 나뉩니다. 필요한 컴포넌트만 선택적으로 import하여 번들 크기를 최적화할 수 있습니다.
-| Entry | Path | 설명 |
-|-------|------|------|
-| Core | `@hua-labs/ui` | 버튼/레이아웃/데이터 표시 등 기본 컴포넌트와 유틸 (대부분의 일반적인 앱 개발 가능) |
-| Form | `@hua-labs/ui/form` | 모든 폼 컴포넌트 (Input, Select, DatePicker, Upload, Autocomplete 등) |
-| Navigation | `@hua-labs/ui/navigation` | 대규모 앱 구조에 필요한 네비게이션 (PageNavigation, PageTransition) |
-| Feedback | `@hua-labs/ui/feedback` | 글로벌 상태 관리가 필요한 Toast (ToastProvider, useToast) |
-| Advanced (all) | `@hua-labs/ui/advanced` | 대시보드 위젯 + 고급 모션 전체 |
-| Dashboard widgets | `@hua-labs/ui/advanced/dashboard` | StatCard, TransactionsTable, TrendChart 등 데이터 위젯 |
-| Motion/Experimental | `@hua-labs/ui/advanced/motion` | AdvancedPageTransition 등 모션/실험 기능 |
-```tsx
-// Core 컴포넌트 (가장 자주 사용되는 컴포넌트들)
-import { Button, Card, Table, Badge, Alert, Modal, Drawer } from '@hua-labs/ui';
-// Form 컴포넌트만 (번들 최적화)
-import { Input, Select, DatePicker, Form } from '@hua-labs/ui/form';
-// Navigation 컴포넌트 (대규모 앱에서만 필요)
-import { PageNavigation, PageTransition } from '@hua-labs/ui/navigation';
-// Feedback 컴포넌트 (Toast - 글로벌 상태 관리)
-import { ToastProvider, useToast } from '@hua-labs/ui/feedback';
-import '@hua-labs/ui/styles/toast.css';
-// Advanced 전체
-import { StatCard, DashboardSidebar } from '@hua-labs/ui/advanced';
-// 필요한 영역만 선택적으로
-import { TransactionsTable } from '@hua-labs/ui/advanced/dashboard';
-import { AdvancedPageTransition } from '@hua-labs/ui/advanced/motion';
-```
-**참고**: 서브패키지 분리 분석 문서는 [`docs/SUBPACKAGE_ANALYSIS.md`](./docs/SUBPACKAGE_ANALYSIS.md)를 참고하세요.
-## Bundle Optimization
-HUA UI는 모듈 단위 번들링과 tree-shaking을 지원합니다. 필요한 컴포넌트만 선택적으로 import하여 번들 크기를 최적화할 수 있습니다.
-### 번들 최적화 전략
-- **Core**: 가장 자주 사용하는 80% 컴포넌트 포함 (대부분의 일반적인 앱 개발 가능)
-- **Form / Navigation / Feedback**: 필요한 경우에만 선택적으로 import
-- **Advanced / Dashboard / Motion**: 대규모 앱에서만 사용하는 특수 컴포넌트
-### 사용 예시
-#### Next.js (Turbopack)
-```tsx
-// 권장: 필요한 서브패키지만 import (tree-shaking 자동 적용)
-import { Input, Select, DatePicker } from '@hua-labs/ui/form';
-import { PageTransition } from '@hua-labs/ui/navigation';
-import { ToastProvider, useToast } from '@hua-labs/ui/feedback';
-// Core 전체를 불러오지 않으므로 번들 크기 최적화
-```
-#### Vite / Webpack
-```tsx
-// 권장: 서브패키지 사용
-import { Input } from '@hua-labs/ui/form';
-import { PageTransition } from '@hua-labs/ui/navigation';
-// 비권장: Core에서 모든 컴포넌트 import (번들 크기 증가)
-import { Input, PageTransition, ToastProvider } from '@hua-labs/ui';
-```
-### Tree-shaking
-모든 엔트리 포인트는 ESM 형식으로 제공되며, 최신 번들러(Next.js Turbopack, Vite, Webpack 5+)에서 tree-shaking이 자동으로 적용됩니다.
-**최적화 팁**:
-- 필요한 컴포넌트만 import
-- 서브패키지 활용 (Form, Navigation, Feedback)
-- Advanced 컴포넌트는 실제로 사용할 때만 import
-**참고**: Core에서도 모든 컴포넌트를 import할 수 있습니다 (하위 호환성). 서브패키지는 번들 크기 최적화를 위한 선택사항입니다. Next.js + Turbopack 환경에서 tree-shaking이 자동 적용됩니다.
-## Quick Start
+### Quick Start
 ```tsx
 import { Button, Input, Card, ThemeProvider } from '@hua-labs/ui';
@@ -157,896 +78,281 @@ function App() {
 }
 ```
-### CSS 스타일 import (Toast 컴포넌트 사용 시)
-Toast 컴포넌트의 애니메이션을 사용하려면 CSS 파일을 import해야 합니다:
-```css
-/* globals.css 또는 메인 CSS 파일에 추가 */
-@import '@hua-labs/ui/styles/toast.css';
-```
-또는 JavaScript/TypeScript에서:
-```tsx
-// app/layout.tsx 또는 _app.tsx
-import '@hua-labs/ui/styles/toast.css';
-```
-## Core Components
-### Basic UI
-#### Button
-```tsx
-import { Button } from '@hua-labs/ui';
-<Button>Default</Button>
-<Button variant="outline">Outline</Button>
-<Button variant="ghost">Ghost</Button>
-<Button variant="destructive">Destructive</Button>
-<Button variant="gradient">Gradient</Button>
-<Button variant="neon">Neon</Button>
-<Button variant="glass">Glass</Button>
-<Button size="sm">Small</Button>
-<Button size="md">Medium</Button>
-<Button size="lg">Large</Button>
-<Button loading>Loading</Button>
-<Button disabled>Disabled</Button>
-<Button fullWidth>Full Width</Button>
-```
-#### Action
-Advanced button component with additional effects and styles.
-```tsx
-import { Action } from '@hua-labs/ui';
-<Action actionType="primary">Primary Action</Action>
-<Action actionType="secondary">Secondary Action</Action>
-<Action actionType="magical">Magical</Action>
-<Action actionType="cyberpunk">Cyberpunk</Action>
-<Action feedback="ripple">Ripple Effect</Action>
-<Action feedback="particle">Particle Effect</Action>
-<Action particleEffect rippleEffect>Multiple Effects</Action>
-```
-#### Input
-```tsx
-import { Input } from '@hua-labs/ui';
-<Input placeholder="Enter text" />
-<Input type="password" />
-<Input disabled />
-<Input error="Error message" />
-```
-#### Icon
-```tsx
-import { Icon } from '@hua-labs/ui';
-<Icon name="heart" />
-<Icon name="star" size="lg" />
-<Icon name="user" className="text-blue-500" />
-```
-Supports Lucide React icons and optional Phosphor Icons.
-#### Avatar
-```tsx
-import { Avatar, AvatarImage, AvatarFallback } from '@hua-labs/ui';
-<Avatar>
-  <AvatarImage src="/avatar.jpg" alt="User" />
-  <AvatarFallback>JD</AvatarFallback>
-</Avatar>
-```
-### Layout Components
-#### Card
-```tsx
-import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@hua-labs/ui';
-<Card>
-  <CardHeader>
-    <CardTitle>Card Title</CardTitle>
-    <CardDescription>Card description</CardDescription>
-  </CardHeader>
-  <CardContent>
-    Card content
-  </CardContent>
-  <CardFooter>
-    Footer content
-  </CardFooter>
-</Card>
-```
-#### Panel
-Advanced card component with more styling options.
-```tsx
-import { Panel } from '@hua-labs/ui';
-<Panel style="elevated" padding="large">
-  Elevated panel
-</Panel>
-<Panel style="outline" padding="medium">
-  Outline panel
-</Panel>
-```
-#### Container
-```tsx
-import { Container } from '@hua-labs/ui';
-<Container size="sm">Small container</Container>
-<Container size="md">Medium container</Container>
-<Container size="lg">Large container</Container>
-<Container size="xl">Extra large container</Container>
-```
-#### Grid
-```tsx
-import { Grid } from '@hua-labs/ui';
-<Grid cols={3} gap={4}>
-  <div>Item 1</div>
-  <div>Item 2</div>
-  <div>Item 3</div>
-</Grid>
-```
-#### Stack
-```tsx
-import { Stack } from '@hua-labs/ui';
-<Stack direction="vertical" gap={4}>
-  <div>Item 1</div>
-  <div>Item 2</div>
-</Stack>
-```
-### Navigation Components
-#### Navigation
-```tsx
-import { Navigation, NavigationList, NavigationItem, NavigationContent } from '@hua-labs/ui';
-<Navigation defaultValue="tab1">
-  <NavigationList>
-    <NavigationItem value="tab1">Tab 1</NavigationItem>
-    <NavigationItem value="tab2">Tab 2</NavigationItem>
-  </NavigationList>
-  <NavigationContent value="tab1">Tab 1 content</NavigationContent>
-  <NavigationContent value="tab2">Tab 2 content</NavigationContent>
-</Navigation>
-```
-#### Tabs
-```tsx
-import { Tabs, TabsList, TabsTrigger, TabsContent } from '@hua-labs/ui';
-<Tabs defaultValue="tab1">
-  <TabsList>
-    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
-    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
-  </TabsList>
-  <TabsContent value="tab1">Tab 1 content</TabsContent>
-  <TabsContent value="tab2">Tab 2 content</TabsContent>
-</Tabs>
-```
-#### Breadcrumb
-```tsx
-import { Breadcrumb, BreadcrumbItem } from '@hua-labs/ui';
-<Breadcrumb>
-  <BreadcrumbItem href="/">Home</BreadcrumbItem>
-  <BreadcrumbItem href="/products">Products</BreadcrumbItem>
-  <BreadcrumbItem>Current</BreadcrumbItem>
-</Breadcrumb>
-```
-#### Pagination
-```tsx
-import { Pagination, PaginationWithInfo } from '@hua-labs/ui';
-<Pagination
-  currentPage={1}
-  totalPages={10}
-  onPageChange={(page) => console.log(page)}
-/>
-<PaginationWithInfo
-  currentPage={1}
-  totalPages={10}
-  totalItems={100}
-  itemsPerPage={10}
-  onPageChange={(page) => console.log(page)}
-/>
-```
-### Form Components
-#### Form
-```tsx
-import { Form, FormField, FormGroup } from '@hua-labs/ui';
-<Form onSubmit={handleSubmit}>
-  <FormGroup>
-    <FormField label="Name" required>
-      <Input name="name" />
-    </FormField>
-    <FormField label="Email" required>
-      <Input type="email" name="email" />
-    </FormField>
-  </FormGroup>
-</Form>
-```
-#### Select
-```tsx
-import { Select, SelectOption } from '@hua-labs/ui';
-<Select value={value} onValueChange={setValue}>
-  <SelectOption value="option1">Option 1</SelectOption>
-  <SelectOption value="option2">Option 2</SelectOption>
-</Select>
-```
-#### Checkbox
-```tsx
-import { Checkbox } from '@hua-labs/ui';
-<Checkbox checked={checked} onCheckedChange={setChecked}>
-  Accept terms
-</Checkbox>
-```
-#### Radio
-```tsx
-import { Radio } from '@hua-labs/ui';
-<Radio value="option1" checked={value === "option1"} onChange={handleChange}>
-  Option 1
-</Radio>
-```
-#### Switch
-```tsx
-import { Switch } from '@hua-labs/ui';
-<Switch checked={enabled} onCheckedChange={setEnabled} />
-```
-#### Textarea
-```tsx
-import { Textarea } from '@hua-labs/ui';
-<Textarea placeholder="Enter text" rows={4} />
-```
-#### Slider
-```tsx
-import { Slider } from '@hua-labs/ui';
-<Slider
-  value={value}
-  onValueChange={setValue}
-  min={0}
-  max={100}
-  step={1}
-/>
-```
-### Feedback Components
-#### Alert
-```tsx
-import { Alert, AlertSuccess, AlertWarning, AlertError, AlertInfo } from '@hua-labs/ui';
-<Alert>Default alert</Alert>
-<AlertSuccess>Success message</AlertSuccess>
-<AlertWarning>Warning message</AlertWarning>
-<AlertError>Error message</AlertError>
-<AlertInfo>Info message</AlertInfo>
-```
-#### Toast
-```tsx
-import { ToastProvider, useToast } from '@hua-labs/ui';
-function App() {
-  return (
-    <ToastProvider>
-      <YourApp />
-    </ToastProvider>
-  );
-}
-function Component() {
-  const { addToast } = useToast();
-  const handleClick = () => {
-    addToast({
-      title: "Success",
-      description: "Operation completed",
-      variant: "success"
-    });
-  };
-  return <Button onClick={handleClick}>Show Toast</Button>;
-}
-```
-#### LoadingSpinner
-```tsx
-import { LoadingSpinner } from '@hua-labs/ui';
-<LoadingSpinner />
-<LoadingSpinner size="sm" />
-<LoadingSpinner size="lg" />
-<LoadingSpinner color="primary" />
-```
-#### Tooltip
-```tsx
-import { Tooltip, TooltipLight, TooltipDark } from '@hua-labs/ui';
-<Tooltip content="Tooltip text">
-  <Button>Hover me</Button>
-</Tooltip>
-```
-### Overlay Components
-#### Modal
+### Entry Points
-```tsx
-import { Modal } from '@hua-labs/ui';
-<Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
-  <div className="p-6">
-    <h2>Modal Title</h2>
-    <p>Modal content</p>
-  </div>
-</Modal>
-```
+HUA UI is organized into **Core**, **Form**, **Navigation**, **Feedback**, and **Advanced** entry points. Import only the components you need from specific entry points to optimize bundle size.
-#### ConfirmModal
+| Entry | Path | Description |
+|-------|------|-------------|
+| Core | `@hua-labs/ui` | Most commonly used basic components (Button, Card, Badge, Alert, Modal, Drawer, etc.) |
+| Form | `@hua-labs/ui/form` | All form components (Input, Select, DatePicker, Upload, Autocomplete, etc.) |
+| Navigation | `@hua-labs/ui/navigation` | Navigation components for page transitions (PageNavigation, PageTransition) |
+| Feedback | `@hua-labs/ui/feedback` | Toast notifications for user feedback (ToastProvider, useToast) |
+| Advanced (all) | `@hua-labs/ui/advanced` | Advanced components + experimental features |
+| Dashboard widgets | `@hua-labs/ui/advanced/dashboard` | Dashboard-specific components (StatCard, TransactionsTable, TrendChart, etc.) |
+| Motion/Experimental | `@hua-labs/ui/advanced/motion` | AdvancedPageTransition and experimental features |
 ```tsx
-import { ConfirmModal } from '@hua-labs/ui';
-<ConfirmModal
-  isOpen={isOpen}
-  onClose={() => setIsOpen(false)}
-  onConfirm={handleConfirm}
-  title="Confirm Action"
-  description="Are you sure you want to proceed?"
-/>
-```
-#### Drawer
+// Core components (most commonly used components)
+import { Button, Card, Table, Badge, Alert, Modal, Drawer } from '@hua-labs/ui';
-```tsx
-import { Drawer, DrawerHeader, DrawerContent, DrawerFooter } from '@hua-labs/ui';
-<Drawer isOpen={isOpen} onClose={() => setIsOpen(false)}>
-  <DrawerHeader>Drawer Title</DrawerHeader>
-  <DrawerContent>
-    Drawer content
-  </DrawerContent>
-  <DrawerFooter>
-    Footer actions
-  </DrawerFooter>
-</Drawer>
-```
+// Form components (bundle optimized)
+import { Input, Select, DatePicker, Form } from '@hua-labs/ui/form';
-#### BottomSheet
+// Navigation components (for page transitions)
+import { PageNavigation, PageTransition } from '@hua-labs/ui/navigation';
-```tsx
-import { BottomSheet } from '@hua-labs/ui';
-<BottomSheet isOpen={isOpen} onClose={() => setIsOpen(false)}>
-  <div className="p-6">
-    <h2>Bottom Sheet Title</h2>
-    <p>Bottom sheet content</p>
-  </div>
-</BottomSheet>
-```
+// Feedback components (Toast - user feedback)
+import { ToastProvider, useToast } from '@hua-labs/ui/feedback';
+import '@hua-labs/ui/styles/toast.css';
-#### Popover
+// Advanced components
+import { StatCard, DashboardSidebar } from '@hua-labs/ui/advanced';
-```tsx
-import { Popover, PopoverTrigger, PopoverContent } from '@hua-labs/ui';
-<Popover>
-  <PopoverTrigger>
-    <Button>Open Popover</Button>
-  </PopoverTrigger>
-  <PopoverContent>
-    Popover content
-  </PopoverContent>
-</Popover>
+// Import from specific sub-paths
+import { TransactionsTable } from '@hua-labs/ui/advanced/dashboard';
+import { AdvancedPageTransition } from '@hua-labs/ui/advanced/motion';
 ```
-#### Dropdown
+**Note**: See [package structure documentation](./docs/PACKAGE_STRUCTURE.md) for detailed entry point information.
-```tsx
-import { Dropdown, DropdownMenu, DropdownItem, DropdownSeparator, DropdownLabel, DropdownGroup } from '@hua-labs/ui';
-<Dropdown>
-  <DropdownMenu>
-    <DropdownLabel>My Account</DropdownLabel>
-    <DropdownSeparator />
-    <DropdownGroup>
-      <DropdownItem>Profile</DropdownItem>
-      <DropdownItem>Settings</DropdownItem>
-    </DropdownGroup>
-    <DropdownSeparator />
-    <DropdownItem>Logout</DropdownItem>
-  </DropdownMenu>
-</Dropdown>
-```
+### Bundle Optimization
-### Data Display Components
+HUA UI supports modular entry points and tree-shaking. Import only the components you need from specific entry points to optimize bundle size.
-#### Table
+**Optimization Tips**:
+- Import only needed components
+- Use specific entry points (Form, Navigation, Feedback)
+- Import Advanced components only when actually used
-```tsx
-import { Table, TableHeader, TableBody, TableHead, TableRow, TableCell, TableCaption } from '@hua-labs/ui';
-<Table>
-  <TableCaption>Table caption</TableCaption>
-  <TableHeader>
-    <TableRow>
-      <TableHead>Name</TableHead>
-      <TableHead>Email</TableHead>
-    </TableRow>
-  </TableHeader>
-  <TableBody>
-    <TableRow>
-      <TableCell>John Doe</TableCell>
-      <TableCell>john@example.com</TableCell>
-    </TableRow>
-  </TableBody>
-</Table>
-```
+**Note**: You can import all components from Core, but it's not recommended. Using specific entry points provides better bundle size optimization. Next.js + Turbopack supports tree-shaking automatically.
-#### Badge
+### CSS Import (Toast Component Usage)
-```tsx
-import { Badge } from '@hua-labs/ui';
+If you use Toast components, you need to import the CSS file:
-<Badge>Default</Badge>
-<Badge variant="success">Success</Badge>
-<Badge variant="warning">Warning</Badge>
-<Badge variant="error">Error</Badge>
-<Badge variant="info">Info</Badge>
+```css
+/* Add to globals.css or main CSS file */
+@import '@hua-labs/ui/styles/toast.css';
 ```
-#### Progress
+Or in JavaScript/TypeScript:
 ```tsx
-import { Progress, ProgressSuccess, ProgressWarning, ProgressError, ProgressInfo } from '@hua-labs/ui';
-<Progress value={50} />
-<ProgressSuccess value={75} />
-<ProgressWarning value={50} />
-<ProgressError value={25} />
-<ProgressInfo value={60} />
+// app/layout.tsx or _app.tsx
+import '@hua-labs/ui/styles/toast.css';
 ```
-#### Skeleton
+### API Overview
-```tsx
-import { Skeleton, SkeletonText, SkeletonCircle, SkeletonCard, SkeletonAvatar } from '@hua-labs/ui';
+#### Core Components
-<Skeleton className="h-4 w-full" />
-<SkeletonText lines={3} />
-<SkeletonCircle size={40} />
-<SkeletonCard />
-<SkeletonAvatar />
-```
+- **Basic UI**: Button, Action, Input, Icon, Avatar
+- **Layout**: Container, Grid, Stack, Card, Panel
+- **Navigation**: Navigation, Breadcrumb, Pagination, PageNavigation, PageTransition
+- **Data Display**: Table, Badge, Progress, Skeleton
+- **Feedback**: Alert, Toast, LoadingSpinner, Tooltip
+- **Overlay**: Modal, Drawer, Popover, Dropdown, BottomSheet
+- **Form**: Form, Input, Select, Checkbox, Radio, Switch, Slider, Textarea, DatePicker, Upload, Autocomplete
+- **Interactive**: Accordion, Tabs, Menu, Command
+- **Theme**: ThemeProvider, ThemeToggle
-### Interactive Components
+#### Utilities
-#### Accordion
+- `merge`, `mergeIf`, `mergeMap`, `cn` - Class merging utilities
+- `formatRelativeTime` - Date formatting utility
-```tsx
-import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@hua-labs/ui';
-<Accordion type="single" collapsible>
-  <AccordionItem value="item-1">
-    <AccordionTrigger>Item 1</AccordionTrigger>
-    <AccordionContent>Content 1</AccordionContent>
-  </AccordionItem>
-  <AccordionItem value="item-2">
-    <AccordionTrigger>Item 2</AccordionTrigger>
-    <AccordionContent>Content 2</AccordionContent>
-  </AccordionItem>
-</Accordion>
-```
+### Documentation
-#### Menu
+- [Architecture Documentation](./docs/ARCHITECTURE.md) - Core architecture and design principles
+- [Package Structure](./docs/PACKAGE_STRUCTURE.md) - Package structure and internal organization
+- [Development Guide](./docs/DEVELOPMENT_GUIDE.md) - Component development guide
+- [Icon System](./docs/ICON_SYSTEM.md) - Icon system guide
-```tsx
-import { Menu, MenuItem, MenuSeparator, MenuLabel, MenuHorizontal, MenuVertical } from '@hua-labs/ui';
-<Menu>
-  <MenuItem>Item 1</MenuItem>
-  <MenuItem>Item 2</MenuItem>
-  <MenuSeparator />
-  <MenuLabel>Label</MenuLabel>
-  <MenuItem>Item 3</MenuItem>
-</Menu>
-```
+### Related Packages
-#### Command
+- [`@hua-labs/hua-ux`](../hua-ux/README.md) - Integrated framework (UI + Motion + i18n)
+- [`@hua-labs/motion-core`](../hua-motion-core/README.md) - Animation hooks
+- [`@hua-labs/i18n-core`](../hua-i18n-core/README.md) - Internationalization core
-```tsx
-import { Command, CommandInput, CommandList, CommandItem, CommandGroup, CommandEmpty } from '@hua-labs/ui';
-<Command>
-  <CommandInput placeholder="Search..." />
-  <CommandList>
-    <CommandEmpty>No results found.</CommandEmpty>
-    <CommandGroup heading="Suggestions">
-      <CommandItem>Calendar</CommandItem>
-      <CommandItem>Search Emoji</CommandItem>
-    </CommandGroup>
-  </CommandList>
-</Command>
-```
-### Scroll Components
+### Requirements
-#### ScrollToTop
-```tsx
-import { ScrollToTop } from '@hua-labs/ui';
+- React >= 19.0.0
+- React DOM >= 19.0.0
+- Tailwind CSS (for styling)
+- Optional: @phosphor-icons/react (for Phosphor icon support)
-<ScrollToTop
-  className="fixed bottom-6 right-6"
-  threshold={150}
-/>
-```
+## Korean
-#### ScrollProgress
+### 개요
-```tsx
-import { ScrollProgress } from '@hua-labs/ui';
+접근 가능하고 TypeScript 네이티브인 React 컴포넌트 라이브러리입니다. 최적의 번들 크기를 위한 모듈식 진입점과 포괄적인 다크 모드 지원을 제공합니다.
-<ScrollProgress />
-```
+### 주요 기능
-#### ScrollIndicator
+- 70개 이상의 프로덕션 레디 컴포넌트
+- 번들 최적화를 위한 모듈식 진입점
+- 완전한 TypeScript 지원
+- 다크 모드 지원
+- 접근성 (ARIA 속성, 키보드 네비게이션)
+- 반응형 디자인
+- Tree-shaking 친화적
+- React 외부 의존성 없음
+- Tailwind CSS 기반 스타일링
-```tsx
-import { ScrollIndicator } from '@hua-labs/ui';
+### 설치
-<ScrollIndicator />
+```bash
+npm install @hua-labs/ui
+# or
+yarn add @hua-labs/ui
+# or
+pnpm add @hua-labs/ui
 ```
-#### ScrollArea
+### Peer Dependencies
-```tsx
-import { ScrollArea } from '@hua-labs/ui';
+```bash
+# 필수
+npm install react react-dom
-<ScrollArea className="h-72">
-  <div>Scrollable content</div>
-</ScrollArea>
+# 선택사항 (Phosphor Icons 지원용)
+npm install @phosphor-icons/react
 ```
-### Theme Components
-#### ThemeProvider
+### 빠른 시작
 ```tsx
-import { ThemeProvider } from '@hua-labs/ui';
+import { Button, Input, Card, ThemeProvider } from '@hua-labs/ui';
 function App() {
   return (
-    <ThemeProvider
-      attribute="class"
-      defaultTheme="system"
-      enableSystem
-    >
-      <YourApp />
+    <ThemeProvider>
+      <div>
+        <Button>클릭하세요</Button>
+        <Input placeholder="텍스트 입력" />
+        <Card>
+          <CardHeader>
+            <CardTitle>카드 제목</CardTitle>
+          </CardHeader>
+          <CardContent>
+            카드 내용
+          </CardContent>
+        </Card>
+      </div>
     </ThemeProvider>
   );
 }
 ```
-#### ThemeToggle
-```tsx
-import { ThemeToggle } from '@hua-labs/ui';
-<ThemeToggle />
-```
-### Specialized Components
-#### ChatMessage
+### 진입점
-```tsx
-import { ChatMessage } from '@hua-labs/ui';
+HUA UI는 **Core**, **Form**, **Navigation**, **Feedback**, **Advanced** 진입점으로 구성됩니다. 번들 크기를 최적화하려면 필요한 컴포넌트만 특정 진입점에서 import하세요.
-<ChatMessage
-  message="Hello, world!"
-  sender="user"
-  timestamp={new Date()}
-/>
-```
-#### EmotionAnalysis
-```tsx
-import { EmotionAnalysis } from '@hua-labs/ui';
-<EmotionAnalysis
-  emotions={['joy', 'sadness', 'anger']}
-  intensity={[0.8, 0.3, 0.2]}
-/>
-```
-#### EmotionSelector
-```tsx
-import { EmotionSelector } from '@hua-labs/ui';
-<EmotionSelector
-  value={selectedEmotion}
-  onValueChange={setSelectedEmotion}
-/>
-```
-#### InfoCard
-```tsx
-import { InfoCard } from '@hua-labs/ui';
-<InfoCard
-  title="Information"
-  description="This is an info card"
-  variant="info"
-/>
-```
-#### FeatureCard
-```tsx
-import { FeatureCard } from '@hua-labs/ui';
-<FeatureCard
-  title="Feature"
-  description="Feature description"
-  icon={<Icon name="star" />}
-/>
-```
-### Dashboard Components
-Dashboard components are available from the advanced export:
-```tsx
-import {
-  StatCard,
-  QuickActionCard,
-  DashboardGrid,
-  ActivityFeed,
-  ProfileCard,
-  MembershipBadge,
-  MiniBarChart,
-  SummaryCard,
-  NotificationCard,
-  MetricCard,
-  ProgressCard
-} from '@hua-labs/ui';
-```
-Or import from the dashboard subpath:
-```tsx
-import * from '@hua-labs/ui/advanced/dashboard';
-```
-### Advanced Page Transitions
-Advanced page transition components are available from the advanced export:
-```tsx
-import {
-  AdvancedPageTransition,
-  usePageTransition,
-  usePageTransitionManager
-} from '@hua-labs/ui/advanced';
-```
-## Utilities
-### merge
-Smart class merging utility that resolves duplicate Tailwind classes.
-```tsx
-import { merge } from '@hua-labs/ui';
-const className = merge("px-2 py-1", "px-4"); // "py-1 px-4"
-const className2 = merge("text-red-500", "text-blue-500"); // "text-blue-500"
-```
-### mergeIf
-Conditional class merging.
-```tsx
-import { mergeIf } from '@hua-labs/ui';
-const className = mergeIf(isActive, "bg-blue-500", "bg-gray-200");
-const className2 = mergeIf(isLoading, "opacity-50 cursor-not-allowed");
-```
-### mergeMap
-Object-based conditional class merging.
-```tsx
-import { mergeMap } from '@hua-labs/ui';
-const className = mergeMap({
-  "bg-blue-500": isPrimary,
-  "bg-gray-500": !isPrimary,
-  "text-white": true,
-  "opacity-50": isDisabled
-});
-```
-### cn
-Alias for `merge` (for compatibility with shadcn/ui).
+| 진입점 | 경로 | 설명 |
+|--------|------|------|
+| Core | `@hua-labs/ui` | 가장 많이 사용되는 기본 컴포넌트 (Button, Card, Badge, Alert, Modal, Drawer 등) |
+| Form | `@hua-labs/ui/form` | 모든 폼 컴포넌트 (Input, Select, DatePicker, Upload, Autocomplete 등) |
+| Navigation | `@hua-labs/ui/navigation` | 페이지 전환용 네비게이션 컴포넌트 (PageNavigation, PageTransition) |
+| Feedback | `@hua-labs/ui/feedback` | 사용자 피드백용 Toast 알림 (ToastProvider, useToast) |
+| Advanced (전체) | `@hua-labs/ui/advanced` | 고급 컴포넌트 + 실험적 기능 |
+| Dashboard 위젯 | `@hua-labs/ui/advanced/dashboard` | 대시보드 전용 컴포넌트 (StatCard, TransactionsTable, TrendChart 등) |
+| Motion/실험적 | `@hua-labs/ui/advanced/motion` | AdvancedPageTransition 및 실험적 기능 |
 ```tsx
-import { cn } from '@hua-labs/ui';
+// Core 컴포넌트 (가장 많이 사용되는 컴포넌트)
+import { Button, Card, Table, Badge, Alert, Modal, Drawer } from '@hua-labs/ui';
-const className = cn("px-2", "py-1");
-```
+// Form 컴포넌트 (번들 최적화)
+import { Input, Select, DatePicker, Form } from '@hua-labs/ui/form';
-### formatRelativeTime
+// Navigation 컴포넌트 (페이지 전환용)
+import { PageNavigation, PageTransition } from '@hua-labs/ui/navigation';
-Format a date as relative time (e.g., "방금 전", "5분 전", "2시간 전", "3일 전"). Returns absolute date for dates older than 7 days.
+// Feedback 컴포넌트 (Toast - 사용자 피드백)
+import { ToastProvider, useToast } from '@hua-labs/ui/feedback';
+import '@hua-labs/ui/styles/toast.css';
-```tsx
-import { formatRelativeTime } from '@hua-labs/ui';
+// Advanced 컴포넌트
+import { StatCard, DashboardSidebar } from '@hua-labs/ui/advanced';
-formatRelativeTime(new Date()) // "방금 전"
-formatRelativeTime(new Date(Date.now() - 5 * 60000)) // "5분 전"
-formatRelativeTime(new Date(Date.now() - 2 * 3600000)) // "2시간 전"
-formatRelativeTime(new Date(Date.now() - 3 * 86400000)) // "3일 전"
-formatRelativeTime(new Date("2024-01-01")) // "2024. 1. 1." (7일 이상 경과)
+// 특정 하위 경로에서 import
+import { TransactionsTable } from '@hua-labs/ui/advanced/dashboard';
+import { AdvancedPageTransition } from '@hua-labs/ui/advanced/motion';
 ```
-## Icon Support
+**참고**: 자세한 진입점 정보는 [패키지 구조 문서](./docs/PACKAGE_STRUCTURE.md)를 참고하세요.
-The Icon component supports multiple icon libraries:
-- Lucide React (default, included)
-- Phosphor Icons (optional, requires `@phosphor-icons/react`)
-```tsx
-import { Icon } from '@hua-labs/ui';
+### 번들 최적화
-// Lucide icons (default)
-<Icon name="heart" />
-<Icon name="star" />
+HUA UI는 모듈식 진입점과 tree-shaking을 지원합니다. 번들 크기를 최적화하려면 필요한 컴포넌트만 특정 진입점에서 import하세요.
-// Phosphor icons (if installed)
-<Icon name="heart" provider="phosphor" />
-```
+**최적화 팁**:
+- 필요한 컴포넌트만 import
+- 특정 진입점 사용 (Form, Navigation, Feedback)
+- Advanced 컴포넌트는 실제로 사용할 때만 import
-## Exports
+**참고**: Core에서 모든 컴포넌트를 import할 수 있지만 권장하지 않습니다. 특정 진입점을 사용하면 더 나은 번들 크기 최적화를 제공합니다. Next.js + Turbopack은 자동으로 tree-shaking을 지원합니다.
-### Main Export
+### CSS Import (Toast 컴포넌트 사용 시)
-```tsx
-import { Button, Input, Card } from '@hua-labs/ui';
-```
+Toast 컴포넌트를 사용하는 경우 CSS 파일을 import해야 합니다:
-### Advanced Exports
-```tsx
-import * from '@hua-labs/ui/advanced';
-import * from '@hua-labs/ui/advanced/dashboard';
-import * from '@hua-labs/ui/advanced/motion';
+```css
+/* globals.css 또는 메인 CSS 파일에 추가 */
+@import '@hua-labs/ui/styles/toast.css';
 ```
-### Style Exports
+또는 JavaScript/TypeScript에서:
 ```tsx
+// app/layout.tsx 또는 _app.tsx
 import '@hua-labs/ui/styles/toast.css';
 ```
-## Development
+### API 개요
-### Build
+#### Core 컴포넌트
-```bash
-pnpm build
-```
+- **기본 UI**: Button, Action, Input, Icon, Avatar
+- **레이아웃**: Container, Grid, Stack, Card, Panel
+- **네비게이션**: Navigation, Breadcrumb, Pagination, PageNavigation, PageTransition
+- **데이터 표시**: Table, Badge, Progress, Skeleton
+- **피드백**: Alert, Toast, LoadingSpinner, Tooltip
+- **오버레이**: Modal, Drawer, Popover, Dropdown, BottomSheet
+- **폼**: Form, Input, Select, Checkbox, Radio, Switch, Slider, Textarea, DatePicker, Upload, Autocomplete
+- **인터랙티브**: Accordion, Tabs, Menu, Command
+- **테마**: ThemeProvider, ThemeToggle
-### Development Mode
+#### 유틸리티
-```bash
-pnpm dev
-```
+- `merge`, `mergeIf`, `mergeMap`, `cn` - 클래스 병합 유틸리티
+- `formatRelativeTime` - 날짜 포맷팅 유틸리티
-### Type Check
+### 문서
-```bash
-pnpm type-check
-```
-### Lint
-```bash
-pnpm lint
-```
+- [아키텍처 문서](./docs/ARCHITECTURE.md) - 핵심 아키텍처 및 설계 원칙
+- [패키지 구조](./docs/PACKAGE_STRUCTURE.md) - 패키지 구조 및 내부 구조
+- [개발 가이드](./docs/DEVELOPMENT_GUIDE.md) - 컴포넌트 추가 및 개발 가이드
+- [아이콘 시스템](./docs/ICON_SYSTEM.md) - 아이콘 시스템 가이드
-### Test
+### 관련 패키지
-```bash
-pnpm test
-```
+- [`@hua-labs/hua-ux`](../hua-ux/README.md) - 통합 프레임워크 (UI + Motion + i18n)
+- [`@hua-labs/motion-core`](../hua-motion-core/README.md) - 애니메이션 훅
+- [`@hua-labs/i18n-core`](../hua-i18n-core/README.md) - 국제화 핵심
-## Requirements
+### 요구사항
-- React >= 16.8.0
-- React DOM >= 16.8.0
-- Tailwind CSS (for styling)
-- Optional: @phosphor-icons/react (for Phosphor icon support)
+- React >= 19.0.0
+- React DOM >= 19.0.0
+- Tailwind CSS (스타일링용)
+- 선택사항: @phosphor-icons/react (Phosphor 아이콘 지원용)
 ## License
 MIT License
-## 문서
-- [아키텍처 문서](./docs/ARCHITECTURE.md) - 전체 아키텍처 및 설계 원칙
-- [패키지 구조](./docs/PACKAGE_STRUCTURE.md) - 디렉토리 구조 및 파일 조직
-- [개발 가이드](./docs/DEVELOPMENT_GUIDE.md) - 컴포넌트 추가 및 개발 가이드
-- [모노레포/멀티레포 호환성](./docs/MONOREPO_COMPATIBILITY.md) - 모노레포 및 멀티레포 환경 호환성
-- [서브패키지 분석](./docs/SUBPACKAGE_ANALYSIS.md) - 서브패키지 분리 전략
-- [아이콘 시스템](./docs/ICON_SYSTEM.md) - 아이콘 시스템 가이드
-- [개선 사항](./docs/IMPROVEMENTS_2025-12-06.md) - 개선 이력
 ## Repository
-https://github.com/HUA-Labs/HUA-Labs-public
+<https://github.com/HUA-Labs/HUA-Labs-public>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hua-labs/ui",
-  "version": "1.1.0-alpha.2",
+  "version": "1.1.0-alpha.5",
   "description": "HUA Labs - Modern React UI Component Library - Beautiful, accessible, and customizable components for React applications",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -66,12 +66,12 @@
     "tailwind-merge": "^2.0.0"
   },
   "devDependencies": {
-    "@phosphor-icons/react": "^2.1.10",
+    "@phosphor-icons/react": "*",
     "@testing-library/jest-dom": "^6.8.0",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
     "@types/jest": "^29.0.0",
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.0.3",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.1",
@@ -87,10 +87,10 @@
     "vitest": "^4.0.14"
   },
   "peerDependencies": {
-    "@hua-labs/motion-core": "^2.1.0-alpha.0",
     "@phosphor-icons/react": "*",
-    "react": ">=16.8.0",
-    "react-dom": ">=16.8.0"
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "@hua-labs/motion-core": "2.1.0-alpha.3"
   },
   "keywords": [
     "hua-labs",
@@ -116,6 +116,10 @@
     "url": "https://github.com/HUA-Labs/HUA-Labs-public/issues"
   },
   "homepage": "https://github.com/HUA-Labs/HUA-Labs-public#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "build": "pnpm exec tsup && pnpm exec tsc --emitDeclarationOnly",
     "build:watch": "pnpm exec tsup --watch",