21 KiB
21 KiB
Component / Pattern Reference Index
AI 화면 구현 Quick Start의 Component·Pattern 검색에 사용하는 파일 인덱스다. 오전 HMDesignTest.zip과 현재 개발 저장소는 별도 스냅샷이다. 현재 검증된 최신 테스트 배포 기준 HMDesignTest-Portable-Test-r3.zip에는 아래 44개 Component와 8개 Pattern 모듈, Dashboard Status 소스/export/CSS/문서/정적 예제와 사전 빌드된 Storybook을 모두 포함한다. HMDesignTest-Portable-Test-r2.zip, 기존 HMDesignTest-Portable-Test.zip 및 오전 ZIP은 이전 스냅샷이며, 아래 오전 ZIP 수량은 역사적 비교로 표시한다. 공개 심볼의 Source of Truth는 packages/ui/src/index.ts이며, Props와 상태는 각 연결 문서 및 구현을 확인한다. 파일 수, 공개 API 심볼 수, Story 그룹 수는 서로 다른 집계 단위다.
Component
현재 packages/ui/src/components/ui/에는 구현 TSX 44개가 있다. 각 구현 파일은 packages/ui/src/index.ts의 공개 export를 통해 소비한다. 아래 Story는 실제 Story 파일의 대표 그룹이다.
| Component | 구현·공개 API (@hm-design/ui) |
사용 문서 | 대표 Story |
|---|---|---|---|
| Accordion | Accordion, AccordionContent, AccordionItem, AccordionTrigger구현 |
문서 | Disclosure/Accordion |
| Alert | Alert, AlertDescription, AlertTitle구현 |
문서 | Feedback/Alert |
| Alert Dialog | AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger구현 |
문서 | Overlay/Alert Dialog |
| Aspect Ratio | AspectRatio구현 |
문서 | Data & Display/Aspect Ratio |
| Avatar | Avatar, AvatarFallback, AvatarImage구현 |
문서 | Data & Display/Avatar |
| Badge | Badge, badgeVariants구현 |
문서 | Data & Display/Badge |
| Breadcrumb | Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator구현 |
문서 | Navigation/Breadcrumb |
| Button | Button, buttonVariants, ButtonAppearance구현 |
문서 | Form/Button |
| Calendar | Calendar구현 |
문서 | Search & Date/Calendar |
| Card | Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CardSurface구현 |
문서 | Data & Display/Card |
| Carousel | Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, useCarousel, CarouselApi구현 |
문서 | Data & Display/Carousel |
| Checkbox | Checkbox구현 |
문서 | Form/Checkbox |
| Collapsible | Collapsible, CollapsibleContent, CollapsibleTrigger구현 |
문서 | Disclosure/Collapsible |
| Combobox | Combobox, ComboboxOption, ComboboxSize구현 |
문서 | Search & Date/Combobox |
| Command | Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut구현 |
문서 | Search & Date/Command |
| Context Menu | ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger구현 |
문서 | Overlay/Context Menu |
| Date Picker | DatePicker, DatePickerSize구현 |
문서 | Search & Date/Date Picker |
| Dialog | Dialog, DialogBody, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger구현 |
문서 | Overlay/Dialog |
| Drawer | Drawer, DrawerBody, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger구현 |
문서 | Overlay/Drawer |
| Dropdown Menu | DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger구현 |
문서 | Overlay/Dropdown Menu |
| Hover Card | HoverCard, HoverCardContent, HoverCardTrigger구현 |
문서 | Overlay/Hover Card |
| Input | Input, InputSize구현 |
문서 | Form/Input |
| Label | Label구현 |
문서 | Form/Label |
| Menubar | Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger구현 |
문서 | Navigation/Menubar |
| Navigation Menu | NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport구현 |
문서 | Navigation/Navigation Menu |
| Pagination | Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious구현 |
문서 | Navigation/Pagination |
| Popover | Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger구현 |
문서 | Overlay/Popover |
| Progress | Progress구현 |
문서 | Data & Display/Progress |
| Radio Group | RadioGroup, RadioGroupItem구현 |
문서 | Form/Radio Group |
| Resizable | ResizableHandle, ResizablePanel, ResizablePanelGroup구현 |
문서 | Disclosure/Resizable |
| Scroll Area | ScrollArea, ScrollBar구현 |
문서 | Data & Display/Scroll Area |
| Select | Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, SelectSize구현 |
문서 | Form/Select |
| Separator | Separator구현 |
문서 | Data & Display/Separator |
| Sheet | Sheet, SheetBody, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger구현 |
문서 | Overlay/Sheet |
| Skeleton | Skeleton구현 |
문서 | Data & Display/Skeleton |
| Slider | Slider구현 |
문서 | Form/Slider |
| Sonner | Toaster, toast, ExternalToast, ToasterProps구현 |
문서 | Feedback/Sonner |
| Switch | Switch구현 |
문서 | Form/Switch |
| Table | Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow구현 |
문서 | Data & Display/Table |
| Tabs | Tabs, TabsContent, TabsList, TabsTrigger, TabsPanelSurface구현 기본 <TabsList> = Primary (fill=true, panelSurface="content"). Secondary: fill panelSurface="surface". Legacy: fill={false} (panelSurface 시각 무시). 패널은 Primary bg-background, Secondary / Legacy bg-card로 조합한다 |
문서·기본값 변경 영향 | Navigation/Tabs |
| Textarea | Textarea, TextareaResize구현 |
문서 | Form/Textarea |
| Toggle | Toggle, toggleVariants구현 |
문서 | Form/Toggle |
| Toggle Group | ToggleGroup, ToggleGroupItem구현 |
문서 | Form/Toggle Group |
| Tooltip | Tooltip, TooltipContent, TooltipProvider, TooltipTrigger구현 |
문서 | Overlay/Tooltip |
packages/ui/src/index.ts에는 위 44개 Component 모듈의 named export 222개(값과 type 포함)가 연결되어 있다. 사용 시 API·Props·Variant·주요 상태·Theme 연결은 해당 Component 문서의 API/상태/Token/Storybook 절을 따른다. 문서 45개 중 field.md는 별도 field.tsx 공개 Component를 나타내지 않는 Field 소비 가이드다.
Pattern
현재 개발 저장소와 포터블 r3의 packages/ui/src/patterns/에는 8개 디렉터리와 62개 named export(값과 type 포함)가 있다. 역사적 오전 배포 기준 HMDesignTest.zip에는 7개 Pattern 모듈과 50개 named export가 있었다. Pattern 소스 디렉터리, Story 파일, Story 그룹 수는 별도 집계다.
| Pattern / 분류 | 공개 API 위치 | 사용 문서 | 대표 Reference / 계약 |
|---|---|---|---|
| Dashboard Layout — Layout Pattern | 운영: DashboardLayout, DashboardHeader, DashboardMain, DashboardContent, DashboardLayoutProps.기존 호환성·검증용: DashboardSidebar, 선택적 sidebar slot. 공개 Export 존재는 운영 허용을 뜻하지 않음 |
dashboard-layout.md | Patterns/Layout/Dashboard → Dashboard — Sidebar 없는 48px Header·업무 상태 필터·960px 최소 폭 |
| Dashboard Status — Runtime 상태 계약 | countDashboardFilter, dashboardFilterDefinitions, dashboardFilterIds, dashboardStatusAttributes, dashboardStatusDefinitions, matchesDashboardFilter, DashboardFilterDefinition, DashboardFilterId, DashboardStatusDefinition, DashboardStatusId, DashboardStatusRecord, DashboardStatusTone |
Dashboard 문서의 상태 계약 절 | 최신 포터블 테스트 ZIP에 export·소스·CSS·Static HTML·빌드 결과 포함. 오전 ZIP에는 없음. 현재 contract.ts, Runtime-neutral CSS, React 대표 Story, Static HTML 예제 |
| Data Table — 여러 Component 조합 Pattern | DataTable, DataTableColumnHeader, DataTablePagination, DataTableViewOptions, dataTableSelectColumn, useDataTable, DataTableColumnDef, DataTableInstance, DataTableOptions, DataTableProps |
data-table.md | Patterns/Data/Data Table → Data Table |
| Filter Bar — 여러 Component 조합 Pattern | FilterBar, FilterBarActions, FilterBarSearch 및 FilterBarSearchProps |
filter-bar.md | Patterns/Data/Filter Bar → Filter Bar |
| GNB — Navigation Pattern | GNB, GNBBrand, GNBMobileGroup, GNBMobileLink, GNBMobileMenu, GNBNav, GNBUser, GNBUtilities, GNBMobileMenuProps, GNBUserProps |
gnb.md | Patterns/Layout/GNB |
| LNB — Navigation Pattern | LNB, LNBBrand, LNBGroup, LNBItem, LNBNav, LNBProfile, LNBMobileHeader, LNBMobileBrand, LNBMobileMenu, LNBMobileLink, LNBMobileGroup, LNBMobileMenuProps, LNBGroupProps, LNBProfileProps |
lnb.md | Patterns/Layout/LNB |
| Loading Screen — 화면 UI Pattern | LoadingScreen |
loading-screen.md | Patterns/Layout/Loading Screen |
| Page Header — 화면 구성 Pattern | PageHeader, PageHeaderActions, PageHeaderContent, PageHeaderDescription, PageHeaderTitle |
page-header.md | Patterns/Layout/Page Header → Page Header (patterns-layout-page-header--all). Breadcrumb + Title + Description + 단일 Brand Action. Dashboard 조합은 Dashboard Layout 계약을 따름 |
Data Table은 기존 Table·Pagination·Checkbox·Select·Dropdown Menu 등을 조합한다. 연동 예제가 필요하면 Data Table Story 안의 With Filter Bar를 참고하되 숨김 verification Story이므로 일반 화면의 단독 기본 Reference로 삼지 않는다. Filter Bar는 단독으로도 사용 가능하며 검색·Select·Combobox·Date Picker 등 조회 조건의 layout이다. Dashboard 빠른 상태 필터는 Filter Bar API가 아니라 Dashboard Status 계약을 따른다.
오전 소스 ZIP을 받은 AI는 Dashboard Status 행의 현재 개발 경로를 사용할 수 있다고 가정하지 않는다. 최신 포터블 ZIP에서는 해당 상대경로와 공개 API를 사용할 수 있다. ZIP에 실제 포함된 Dashboard 구현·Story와 해당 ZIP 안의 Dashboard 문서를 확인하고, Status 공개 API가 없으면 없다고 보고한다.
Reference 읽는 순서
화면 생성 시 놓치기 쉬운 소비 계약
- Navigation 미지정: 선택 근거를 기록한다. GNB/LNB의 목적과 대표 화면 구조로 판단하며 일반 목록의 기본 모드를 임의 확정하지 않는다.
- GNB ONLY: Desktop·Mobile 구성을 함께 구현한다. 대표
patterns-layout-gnb--all의 Overview·Usage · GNB Sidebar를 확인하고 Sidebar 예제도 Sheet 하나만 사용한다. - LNB ONLY: 기존 독립 LNB 구조와 LNB Mobile Header/Menu를 유지한다.
- DASHBOARD ONLY: Sidebar를 생성하지 않는다. 대표
patterns-layout-dashboard-layout--all의 전용 Header(48px)·업무 상태 필터 + Content, 최소 폭 960px·내부 가로 스크롤을 따른다.DashboardSidebar와sidebarslot은 호환성·검증용이며 과거 Sidebar verification Story는 신규 운영 화면 구현 기준이 아니다. - Dashboard Status: 공개
@hm-design/ui/dashboard-status.css는 변수만 제공한다. Theme → Status CSS → 기존 Outline Badge mapping·React 소비 예제를 사용한다.issue는 독립 flag다. Static HTML Reference도 같은 계약을 소비한다. - FilterBar: 입력 draft / 조회 applied·초기화 예제를 확인한다. 대표
patterns-data-filter-bar--all은 조회 callback 없는 조합 예시이며 DataTable의patterns-data-data-table--with-filter-bar-story는 즉시 적용 verification이다. - React 소비 CSS: Tailwind v4 검색 범위와 HM source 유지, Runtime Theme 연결을 확인한다.
- 실행 위치별 Asset: Noto Sans KR·폰트 URL·단일 HTML 내장을 확인한다.
탐색 절차
- 이 인덱스에서 후보를 찾고 실제 파일·공개 API가 존재하는지 확인한다.
- 사용 문서에서 Props/Variant, 상태, Theme Token, 조합 규칙을 확인한다.
- 대표 Story에서 시각 언어와 실제 composition을 확인한다. Storybook을 실행할 수 없으면 Story 소스에서 확인한다.
verificationStory는 계약·상태 검사로, Compatibility 예제는 호환성 확인으로, Fixture는 시각 테스트 데이터로 분류한다. 이들을 Production API나 운영 화면 예제로 일반화하지 않는다.- Dashboard는 GNB/LNB와 함께 사용하지 않는다. 허용되는 페이지 모드와 Responsive 규칙은 Navigation Single Mode Policy를 따른다.
- Theme Source of Truth는
themes/default.json및 공개 Runtime 계약이다. Component Token/상태 mapping은 연결된 Theme 문서를 확인한다.
정적 Storybook 빌드가 없거나 실행할 수 없는 환경에서는 확인된 Story 소스와 문서만 근거로 삼고, 검증하지 않은 시각 동작은 미확인으로 보고한다.