@pantoia/ui 0.6.0 → 0.7.1

package/README.md

@@ -19,21 +19,17 @@ npx @pantoia/ui diff          복사한 소스와 배포본의 차이
 
 ## 개발
 
-호스트에는 Docker만 있으면 된다.
+Node 20.11 이상이 필요하다.
 
 ```
 git clone git@github.com:pantoia/pantoia-ui.git
 cd pantoia-ui
-docker compose up -d dev
+npm install
 ```
 
-편집기는 `.devcontainer/devcontainer.json`으로 컨테이너 안에서 연다.
-
 ```
-docker compose up -d dev                        실행
-docker compose down                             종료
-docker compose exec dev npm run verify          typecheck, check, lint, test
-docker compose exec dev npm pack                tarball
+npm run verify   typecheck, check, lint, test
+npm pack         tarball
 ```
 
 ## 구조

package/agents/pantoia-ui.md

@@ -10,6 +10,13 @@ React 디자인 시스템이다. Base UI 위에 스타일을 얹고 Tailwind CSS
 
 ## 설치
 
+```
+Node          20.11 이상
+react         19
+react-dom     19
+tailwindcss   4.0 이상. Tabs의 스크롤바 모양은 4.3부터
+```
+
 ```sh
 npx @pantoia/ui init
 ```
@@ -25,25 +32,28 @@ init은 컴포넌트를 저장할 위치와 전역 CSS 파일을 묻고 `compone
 다크 모드는 `.dark` 클래스로 켠다. `html`이나 `body`에 `.dark`를 두면 그 안의 토큰이 모두 바뀐다.
 next-themes를 쓸 때는 `attribute="class"`로 둔다.
 
+React Router 프레임워크 모드는 `react-router.config.ts`에 `future: { unstable_optimizeDeps: true }`를 더한다.
+없으면 개발 서버에서 처음 여는 route마다 페이지가 새로고침된다.
+
 ## 쓰는 법
 
-컴포넌트는 폴더 이름으로 가져온다.
+컴포넌트는 `add`로 프로젝트에 복사해서 쓴다. `components.json`의 `path` 아래에 `<이름>/index.tsx`로 들어가고, 함께 필요한 파일도 복사된다.
 
-```tsx
-import { Button } from '@pantoia/ui/button'
-import { Field, FieldLabel, FieldHelp } from '@pantoia/ui/field'
+```sh
+npx @pantoia/ui add button field
 ```
 
-쓰는 방식은 2가지다.
-
-```
-패키지로 쓴다     import해서 쓴다. 버전을 올리면 고친 내용이 따라온다
-복사해서 쓴다     npx @pantoia/ui add로 소스를 가져와 프로젝트 안에서 고친다
+```tsx
+import { Button } from '@/components/ui/button'
+import { Field, FieldLabel, FieldHelp } from '@/components/ui/field'
 ```
 
-기본은 패키지로 쓰는 것이다. 동작이나 마크업을 프로젝트에 맞게 바꿔야 할 때만 복사한다.
+import 경로는 저장 위치와 프로젝트의 경로 별칭을 따른다. 위는 저장 위치가 `components/ui`이고 별칭이 `@/`인 예다.
+`@pantoia/ui/<이름>`에서 컴포넌트를 import하지 않는다. Tailwind가 `node_modules`를 검사하지 않아서 스타일이 빠진다.
 
 제어 속성은 Base UI 규약을 따른다. `value`와 `defaultValue`, `onValueChange`를 짝으로 쓴다.
+고르지 않은 상태는 `null`이다. Select, RadioGroup, Combobox, NumberField가 같다.
+Select와 RadioGroup의 state는 `useState<string | null>`로 둔다. 문자열만 받는 setter를 `onValueChange`에 넘기면 타입 오류가 난다.
 컴포넌트마다의 속성과 이벤트는 https://design.pantoia.com 의 각 페이지에 있다.
 
 ## 디자인 규칙
@@ -119,6 +129,8 @@ px 직접 지정      간격과 둥글기는 토큰으로 쓴다
 @utility raised { @apply bg-bg-panel shadow-s2; }
 ```
 
+토큰 이름을 더했으면 저장 위치의 `tv.ts`에 있는 `twMergeConfig`의 그룹 목록에도 더한다. 빠지면 className으로 덮어쓸 때 겹치는 클래스가 함께 남는다.
+
 색 역할을 더하려면 팔레트 10단계를 양쪽 모드에 적고, 토큰 6개를 만든다.
 
 ```
@@ -139,34 +151,34 @@ className     그 한 곳만 바뀐다
 
 `variant`는 tailwind-variants로 만든 스타일 축이다. `-`는 축이 없다는 뜻이다.
 
-| 컴포넌트 | import | 하위 컴포넌트 | variant |
+| 컴포넌트 | add | 하위 컴포넌트 | variant |
 |---|---|---|---|
-| Accordion | @pantoia/ui/accordion | Accordion, AccordionItem, AccordionTrigger, AccordionContent | - |
-| AlertDialog | @pantoia/ui/alert-dialog | AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogTitle, AlertDialogDescription, AlertDialogHeader, AlertDialogFooter, AlertDialogAction, AlertDialogCancel | - |
-| Badge | @pantoia/ui/badge | Badge | color, shape |
-| Button | @pantoia/ui/button | Button | color, emphasis, size, shape |
-| Callout | @pantoia/ui/callout | Callout | color |
-| Checkbox | @pantoia/ui/checkbox | CheckboxGroup, Checkbox | color |
-| Combobox | @pantoia/ui/combobox | Combobox, ComboboxAnchor, ComboboxInput, ComboboxTrigger, ComboboxCancel, ComboboxContent, ComboboxViewport, ComboboxCollection, ComboboxItem, ComboboxItemText, ComboboxItemDescription, ComboboxGroup, ComboboxEmpty, ComboboxSeparator | surface, size |
-| CommandPalette | @pantoia/ui/command-palette | CommandPalette | - |
-| Dialog | @pantoia/ui/dialog | Dialog, DialogTrigger, DialogClose, DialogContent, DialogTitle, DialogDescription, DialogHeader, DialogFooter | size |
-| Drawer | @pantoia/ui/drawer | Drawer, DrawerTrigger, DrawerClose, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription | side |
-| DropdownMenu | @pantoia/ui/dropdown-menu | DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent | color |
-| Field | @pantoia/ui/field | Field, FieldLabel, FieldHelp, FieldError, FieldPending, FieldSuccess | layout |
-| Input | @pantoia/ui/input | Input | surface, size |
-| Kbd | @pantoia/ui/kbd | Kbd | - |
-| Label | @pantoia/ui/label | Label | - |
-| NumberField | @pantoia/ui/number-field | NumberField | surface, size, readonly |
-| Popover | @pantoia/ui/popover | Popover, PopoverTrigger, PopoverAnchor, PopoverClose, PopoverContent | - |
-| RadioGroup | @pantoia/ui/radio-group | RadioGroup, RadioGroupItem, RadioGroupItemLabel, RadioGroupItemDescription | color |
-| Select | @pantoia/ui/select | Select, SelectGroup, SelectItem, SelectItemText, SelectItemDescription, SelectSeparator | surface, size |
-| Switch | @pantoia/ui/switch | Switch | color |
-| Table | @pantoia/ui/table | Table, TableHeader, TableHeadCell, TableBody, TableRow, TableCell | fixed, mono |
-| Tabs | @pantoia/ui/tabs | Tabs, TabsList, TabsTrigger, TabsContent | - |
-| Textarea | @pantoia/ui/textarea | Textarea | surface, size |
-| Toast | @pantoia/ui/toast | Toast | - |
-| Toggle | @pantoia/ui/toggle | Toggle | surface |
-| Tooltip | @pantoia/ui/tooltip | TooltipProvider, Tooltip, TooltipTrigger, TooltipContent | - |
+| Accordion | accordion | Accordion, AccordionItem, AccordionTrigger, AccordionContent | - |
+| AlertDialog | alert-dialog | AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogTitle, AlertDialogDescription, AlertDialogHeader, AlertDialogFooter, AlertDialogAction, AlertDialogCancel | - |
+| Badge | badge | Badge | color, shape |
+| Button | button | Button | color, emphasis, size, shape |
+| Callout | callout | Callout | color |
+| Checkbox | checkbox | CheckboxGroup, Checkbox | color |
+| Combobox | combobox | Combobox, ComboboxAnchor, ComboboxInput, ComboboxTrigger, ComboboxCancel, ComboboxContent, ComboboxViewport, ComboboxCollection, ComboboxItem, ComboboxItemText, ComboboxItemDescription, ComboboxGroup, ComboboxEmpty, ComboboxSeparator | surface, size |
+| CommandPalette | command-palette | CommandPalette | - |
+| Dialog | dialog | Dialog, DialogTrigger, DialogClose, DialogContent, DialogTitle, DialogDescription, DialogHeader, DialogFooter | size |
+| Drawer | drawer | Drawer, DrawerTrigger, DrawerClose, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription | side |
+| DropdownMenu | dropdown-menu | DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent | color |
+| Field | field | Field, FieldLabel, FieldHelp, FieldError, FieldPending, FieldSuccess | layout |
+| Input | input | Input | surface, size |
+| Kbd | kbd | Kbd | - |
+| Label | label | Label | - |
+| NumberField | number-field | NumberField | surface, size, readonly |
+| Popover | popover | Popover, PopoverTrigger, PopoverAnchor, PopoverClose, PopoverContent | - |
+| RadioGroup | radio-group | RadioGroup, RadioGroupItem, RadioGroupItemLabel, RadioGroupItemDescription | color |
+| Select | select | Select, SelectGroup, SelectItem, SelectItemText, SelectItemDescription, SelectSeparator | surface, size |
+| Switch | switch | Switch | color |
+| Table | table | Table, TableHeader, TableHeadCell, TableBody, TableRow, TableCell | fixed, mono |
+| Tabs | tabs | Tabs, TabsList, TabsTrigger, TabsContent | - |
+| Textarea | textarea | Textarea | surface, size |
+| Toast | toast | Toast | - |
+| Toggle | toggle | Toggle | surface |
+| Tooltip | tooltip | TooltipProvider, Tooltip, TooltipTrigger, TooltipContent | - |
 
 컴포넌트를 고를 때 헷갈리는 짝은 이렇다.
 
@@ -183,14 +195,19 @@ Tooltip과 Popover        짧은 설명이면 Tooltip, 안에서 조작하면 Po
 
 Field는 라벨, 도움말, 오류 메시지를 입력 컨트롤에 묶는다. Input, Textarea, NumberField, Select, Combobox와 함께 쓴다.
 
-앱에 한 번만 두는 것이 2개다.
+Select는 고른 항목의 `SelectItemText`나 글자를 트리거에 보인다. `SelectItem`을 다른 컴포넌트로 감싸면 `items`로 라벨을 넘긴다.
+Combobox 항목이 `{ value, label }`이 아닌 객체면 `itemToStringLabel`로 `ComboboxInput`에 보일 글자를 정한다.
+
+앱에 한 번만 두는 것이 2개다. 플로팅 요소가 페이지의 z-index에 가려지지 않게 앱은 `isolate`로 감싼다.
 
 ```tsx
-import { Toast, toast } from '@pantoia/ui/toast'
-import { TooltipProvider } from '@pantoia/ui/tooltip'
+import { Toast, toast } from '@/components/ui/toast'
+import { TooltipProvider } from '@/components/ui/tooltip'
 
 <TooltipProvider>
-  <App />
+  <div className="isolate">
+    <App />
+  </div>
   <Toast />
 </TooltipProvider>
 ```

package/field/index.tsx

@@ -6,13 +6,13 @@ import { Label } from '../label'
 import { tv } from '../tv'
 
 export const field = tv({
-  base: 'group flex flex-wrap gap-x-2 gap-y-tight',
+  base: 'group flex gap-x-2 gap-y-tight',
 
   variants: {
     layout: {
       stack: 'flex-col',
-      inline: 'flex-row items-center',
-      split: 'flex-row items-center justify-between',
+      inline: 'flex-row flex-wrap content-start items-center',
+      split: 'flex-row flex-wrap content-start items-center justify-between',
     },
   },
 
@@ -39,7 +39,7 @@ export function FieldLabel({ render = <Label />, className, ...rest }: FieldLabe
 }
 
 const fieldHelp = tv({
-  base: 'basis-full text-caption text-fg-subtle'
+  base: 'w-full text-caption text-fg-subtle'
     + ' group-has-disabled:text-fg-disabled',
 })
 
@@ -57,7 +57,7 @@ export type FieldErrorProps = Omit<FieldPrimitive.Error.Props, 'className'> & {
 }
 
 const fieldError = tv({
-  base: 'basis-full text-caption text-fg-danger'
+  base: 'w-full text-caption text-fg-danger'
     + ' flex items-start gap-tight',
 })
 
@@ -79,7 +79,7 @@ export function FieldError({ items, match = true, render = <p />, className, chi
 }
 
 const fieldPending = tv({
-  base: 'basis-full text-caption text-fg-subtle'
+  base: 'w-full text-caption text-fg-subtle'
     + ' flex items-start gap-tight',
 })
 
@@ -97,7 +97,7 @@ export function FieldPending({ className, children, ...rest }: FieldPendingProps
 }
 
 const fieldSuccess = tv({
-  base: 'basis-full text-caption text-fg-success'
+  base: 'w-full text-caption text-fg-success'
     + ' flex items-start gap-tight',
 })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantoia/ui",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Pantoia Design System",
   "homepage": "https://design.pantoia.com",
   "repository": {
@@ -48,9 +48,7 @@
     "check": "tsx scripts/check.ts",
     "lint": "oxlint --deny-warnings",
     "test": "vitest run",
-    "verify": "npm run typecheck && npm run check && npm run lint && npm run test",
-    "dev:up": "docker compose up -d dev",
-    "dev:down": "docker compose down"
+    "verify": "npm run typecheck && npm run check && npm run lint && npm run test"
   },
   "dependencies": {
     "@base-ui/react": "^1.8.0",

package/radio-group/index.tsx

@@ -46,7 +46,7 @@ export const radioGroupItem = tv({
   defaultVariants: { color: 'neutral' },
 })
 
-export type RadioGroupProps = Omit<RadioGroupPrimitive.Props<string>, 'className'> & {
+export type RadioGroupProps = Omit<RadioGroupPrimitive.Props<string | null>, 'className'> & {
   color?: RadioColor
   className?: string
 }
@@ -56,7 +56,7 @@ const radioGroup = tv({ base: 'flex flex-col gap-3' })
 export function RadioGroup({ color = 'neutral', className, ...rest }: RadioGroupProps) {
   return (
     <ColorContext value={color}>
-      <RadioGroupPrimitive<string> {...rest} className={radioGroup({ className })} />
+      <RadioGroupPrimitive<string | null> {...rest} className={radioGroup({ className })} />
     </ColorContext>
   )
 }

package/select/index.tsx

@@ -51,12 +51,16 @@ function findItemText(children: ReactNode): { label: ReactNode } | undefined {
   return found
 }
 
+function plainText(children: ReactNode) {
+  return typeof children === 'string' || typeof children === 'number' ? children : undefined
+}
+
 function collectItems(children: ReactNode, items: Record<string, ReactNode>) {
   Children.forEach(children, child => {
     if (!isValidElement<ItemElementProps>(child)) return
     if (child.type === SelectItem && child.props.value !== undefined) {
-      const text = findItemText(child.props.children)
-      if (text) items[child.props.value] = text.label
+      const label = findItemText(child.props.children)?.label ?? plainText(child.props.children)
+      if (label !== undefined) items[child.props.value] = label
       return
     }
     collectItems(child.props.children, items)
@@ -67,9 +71,9 @@ function collectItems(children: ReactNode, items: Record<string, ReactNode>) {
 export type SelectProps = Omit<ComponentProps<typeof SelectPrimitive.Trigger>, 'className' | 'value' | 'defaultValue'>
   & Pick<SelectPrimitive.Root.Props<string>, 'open' | 'defaultOpen' | 'onOpenChange' | 'items' | 'name' | 'required' | 'readOnly' | 'modal' | 'form'>
   & {
-    value?: string
-    defaultValue?: string
-    onValueChange?: (value: string, eventDetails: SelectPrimitive.Root.ChangeEventDetails) => void
+    value?: string | null
+    defaultValue?: string | null
+    onValueChange?: (value: string | null, eventDetails: SelectPrimitive.Root.ChangeEventDetails) => void
     placeholder?: string
     surface?: 'bare' | 'well'
     size?: 'sm' | 'md' | 'lg'
@@ -118,7 +122,7 @@ export function Select({
     <SelectPrimitive.Root<string>
       value={value}
       defaultValue={defaultValue}
-      onValueChange={(next, eventDetails) => onValueChange?.(next ?? '', eventDetails)}
+      onValueChange={onValueChange}
       open={open}
       defaultOpen={defaultOpen}
       onOpenChange={(next, eventDetails) => {