@pantoia/ui 0.15.2 → 0.16.0

package/README.md

@@ -1,4 +1,4 @@
-# Pantoia UI
+# @pantoia/ui
 
 React 디자인 시스템 패키지. 문서는 `design.pantoia.com`
 
@@ -19,7 +19,7 @@ npx @pantoia/ui diff          복사한 소스와 배포본의 차이
 
 ## 개발
 
-Node 20.11 이상이 필요하다.
+개발 런타임은 Node 24 LTS다.
 
 ```
 git clone git@github.com:pantoia/pantoia-ui.git

package/date-picker/index.tsx

@@ -0,0 +1,376 @@
+'use client'
+
+import { Field as FieldPrimitive } from '@base-ui/react/field'
+import { useEffect, useRef, useState, useSyncExternalStore, type KeyboardEvent, type ReactNode } from 'react'
+
+import { BottomSheet, BottomSheetBody, BottomSheetContent, BottomSheetHeader, BottomSheetTitle } from '../bottom-sheet'
+import { Button } from '../button'
+import { input } from '../input'
+import { Popover, PopoverContent, PopoverTrigger } from '../popover'
+import { tv } from '../tv'
+
+const WIDE = '(min-width: 48rem)'
+
+const WEEKDAYS = ['일', '월', '화', '수', '목', '금', '토']
+
+const DAY_STEPS: Record<string, number> = { ArrowLeft: -1, ArrowRight: 1, ArrowUp: -7, ArrowDown: 7 }
+
+const FOCUS_ATTR = 'data-picker-focus'
+
+export const pickerShell = tv({
+  slots: {
+    trigger: 'flex cursor-pointer items-center justify-between gap-tight text-left whitespace-nowrap'
+      + ' read-only:text-fg disabled:cursor-not-allowed',
+    text: 'min-w-0 truncate tabular-nums',
+    icon: 'text-fg-subtle size-4 shrink-0',
+  },
+
+  variants: {
+    surface: {
+      bare: { trigger: 'read-only:bg-transparent' },
+      well: {},
+      ghost: { trigger: 'enabled:not-focus:hover:bg-bg-neutral-hover read-only:focus:bg-bg-neutral-selected' },
+    },
+    empty: {
+      true: { text: 'text-fg-placeholder' },
+    },
+  },
+})
+
+const datePickerCalendar = tv({
+  slots: {
+    root: 'flex w-full min-w-70 flex-col gap-1.5',
+    head: 'flex items-center justify-between',
+    title: 'text-t14 font-bold tabular-nums',
+    titleButton: 'text-t14 h-8 rounded-r8 px-2 font-bold tabular-nums transition-state hover:bg-bg-neutral-hover'
+      + ' focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-line-focus-ring',
+    months: 'grid grid-cols-4 gap-1',
+    month: 'text-t13 h-11 rounded-r8 tabular-nums transition-state'
+      + ' not-on:hover:bg-bg-neutral-hover on:bg-bg-neutral-solid on:font-bold on:text-fg-neutral-solid-contrast'
+      + ' focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-line-focus-ring',
+    days: 'grid grid-cols-7 justify-items-center gap-y-1.5',
+    weekday: 'text-t12 text-fg-subtle py-1',
+    day: 'text-t13 flex size-8 items-center justify-center rounded-full tabular-nums transition-state'
+      + ' enabled:not-on:hover:bg-bg-neutral-hover on:bg-bg-neutral-solid on:font-bold on:text-fg-neutral-solid-contrast'
+      + ' focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-line-focus-ring'
+      + ' disabled:cursor-not-allowed disabled:opacity-40',
+    foot: 'flex justify-end',
+    navIcon: 'size-4',
+  },
+
+  variants: {
+    tone: {
+      plain: {},
+      outside: { day: 'text-fg-subtle' },
+      sunday: { day: 'text-fg-danger' },
+    },
+    today: {
+      true: { day: 'not-on:font-bold not-on:ring-1 not-on:ring-inset not-on:ring-line-strong' },
+    },
+  },
+})
+
+const pad = (value: number) => String(value).padStart(2, '0')
+
+const toDay = (year: number, month: number, date: number) => `${year}-${pad(month + 1)}-${pad(date)}`
+
+const toUtc = (day: string) => new Date(`${day}T00:00:00Z`)
+
+function addDays(day: string, amount: number) {
+  const next = toUtc(day)
+  next.setUTCDate(next.getUTCDate() + amount)
+
+  return next.toISOString().slice(0, 10)
+}
+
+function localToday() {
+  const now = new Date()
+
+  return toDay(now.getFullYear(), now.getMonth(), now.getDate())
+}
+
+function viewOf(day: string) {
+  const date = toUtc(day)
+
+  return { year: date.getUTCFullYear(), month: date.getUTCMonth() }
+}
+
+function fullDate(day: string) {
+  const [year, month, date] = day.split('-').map(Number)
+
+  return `${year}년 ${month}월 ${date}일`
+}
+
+const media = () => (typeof window.matchMedia === 'function' ? window.matchMedia(WIDE) : null)
+
+function subscribe(notify: () => void) {
+  const list = media()
+  list?.addEventListener('change', notify)
+
+  return () => list?.removeEventListener('change', notify)
+}
+
+function NavButton({ label, direction, onClick }: { label: string, direction: 'left' | 'right', onClick: () => void }) {
+  return (
+    <Button type="button" color="neutral" emphasis="ghost" size="sm" shape="square" aria-label={label} onClick={onClick}>
+      <svg className={datePickerCalendar().navIcon()} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+        <path d={direction === 'left' ? 'm15 18-6-6 6-6' : 'm9 18 6-6-6-6'} />
+      </svg>
+    </Button>
+  )
+}
+
+interface CalendarProps {
+  value: string | null
+  min?: string
+  max?: string
+  today: string
+  onPick: (day: string) => void
+}
+
+function Calendar({ value, min, max, today, onPick }: CalendarProps) {
+  const [view, setView] = useState(() => viewOf(value ?? today))
+  const [mode, setMode] = useState<'days' | 'months'>('days')
+  const [focused, setFocused] = useState(value ?? today)
+  const grid = useRef<HTMLDivElement>(null)
+  const moved = useRef(false)
+  const ui = datePickerCalendar()
+  const allowed = (day: string) => !(min && day < min) && !(max && day > max)
+
+  useEffect(() => {
+    if (!moved.current) return
+
+    moved.current = false
+    grid.current?.querySelector<HTMLElement>(`[data-day="${focused}"]`)?.focus()
+  }, [focused, view])
+
+  const showMonth = (year: number, month: number, focus = toDay(year, month, 1)) => {
+    const first = new Date(Date.UTC(year, month, 1))
+
+    setView({ year: first.getUTCFullYear(), month: first.getUTCMonth() })
+    setFocused(focus)
+  }
+
+  const onDayKey = (event: KeyboardEvent<HTMLButtonElement>, day: string) => {
+    const step = DAY_STEPS[event.key]
+    if (!step) return
+
+    event.preventDefault()
+    const next = addDays(day, step)
+
+    if (allowed(next)) {
+      moved.current = true
+      showMonth(viewOf(next).year, viewOf(next).month, next)
+    }
+  }
+
+  if (mode === 'months') {
+    return (
+      <div className={ui.root()}>
+        <div className={ui.head()}>
+          <NavButton label="이전 해" direction="left" onClick={() => setView({ ...view, year: view.year - 1 })} />
+          <span className={ui.title()}>{view.year}년</span>
+          <NavButton label="다음 해" direction="right" onClick={() => setView({ ...view, year: view.year + 1 })} />
+        </div>
+        <div className={ui.months()}>
+          {Array.from({ length: 12 }, (_, month) => (
+            <button
+              key={month}
+              type="button"
+              aria-pressed={month === view.month}
+              className={ui.month()}
+              onClick={() => {
+                showMonth(view.year, month)
+                setMode('days')
+              }}
+            >
+              {month + 1}월
+            </button>
+          ))}
+        </div>
+      </div>
+    )
+  }
+
+  const start = addDays(toDay(view.year, view.month, 1), -new Date(Date.UTC(view.year, view.month, 1)).getUTCDay())
+  const days = Array.from({ length: 42 }, (_, index) => addDays(start, index))
+  const target = days.includes(focused) && allowed(focused)
+    ? focused
+    : days.find(day => viewOf(day).month === view.month && allowed(day))
+
+  return (
+    <div className={ui.root()}>
+      <div className={ui.head()}>
+        <NavButton label="이전 달" direction="left" onClick={() => showMonth(view.year, view.month - 1)} />
+        <button type="button" aria-label="연월 고르기" className={ui.titleButton()} onClick={() => setMode('months')}>
+          {view.year}년 {view.month + 1}월
+        </button>
+        <NavButton label="다음 달" direction="right" onClick={() => showMonth(view.year, view.month + 1)} />
+      </div>
+      <div ref={grid} className={ui.days()}>
+        {WEEKDAYS.map(day => <span key={day} className={ui.weekday()}>{day}</span>)}
+        {days.map((day, index) => {
+          const tone = viewOf(day).month !== view.month ? 'outside' : index % 7 === 0 ? 'sunday' : 'plain'
+
+          return (
+            <button
+              key={day}
+              type="button"
+              data-day={day}
+              {...{ [FOCUS_ATTR]: day === target ? '' : undefined }}
+              disabled={!allowed(day)}
+              tabIndex={day === target ? 0 : -1}
+              aria-label={fullDate(day)}
+              aria-pressed={day === value}
+              aria-current={day === today ? 'date' : undefined}
+              className={datePickerCalendar({ tone, today: day === today }).day()}
+              onKeyDown={event => onDayKey(event, day)}
+              onClick={() => onPick(day)}
+            >
+              {Number(day.slice(8))}
+            </button>
+          )
+        })}
+      </div>
+      <div className={ui.foot()}>
+        <Button type="button" color="neutral" emphasis="ghost" size="sm" onClick={() => showMonth(viewOf(today).year, viewOf(today).month, today)}>
+          오늘
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+export interface PickerTriggerProps {
+  id?: string
+  disabled?: boolean
+  surface?: 'bare' | 'well' | 'ghost'
+  size?: 'sm' | 'md' | 'lg'
+  className?: string
+  'aria-label'?: string
+  'aria-invalid'?: boolean
+}
+
+export type PickerShellProps = PickerTriggerProps & {
+  value: string | null
+  text: ReactNode
+  placeholder: string
+  title: string
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  children: ReactNode
+}
+
+export function PickerShell({ title, open, onOpenChange, children, value, text, placeholder, id, disabled, surface = 'bare', size, className, ...aria }: PickerShellProps) {
+  const wide = useSyncExternalStore(subscribe, () => media()?.matches ?? false, () => false)
+  const popup = useRef<HTMLDivElement>(null)
+  const ui = pickerShell({ surface, empty: value === null })
+
+  const trigger = (onClick?: () => void) => (
+    <FieldPrimitive.Control
+      id={id}
+      disabled={disabled}
+      render={(props) => {
+        const { onChange: _onChange, defaultValue: _defaultValue, value: _value, ...rest } = props as typeof props & { value?: unknown }
+
+        return (
+          <button
+            {...rest}
+            {...aria}
+            type="button"
+            value={value ?? ''}
+            onClick={(event) => {
+              rest.onClick?.(event as never)
+              onClick?.()
+            }}
+            className={input({ surface, size, className: ui.trigger({ className }) })}
+          >
+            <span className={ui.text()}>{value === null ? placeholder : text}</span>
+            <svg className={ui.icon()} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+              <path d="m6 9 6 6 6-6" />
+            </svg>
+          </button>
+        )
+      }}
+    />
+  )
+
+  if (!wide) {
+    return (
+      <>
+        {trigger(() => onOpenChange(true))}
+        <BottomSheet open={open} onOpenChange={next => onOpenChange(next)}>
+          <BottomSheetContent initialFocus={false}>
+            <BottomSheetHeader closable>
+              <BottomSheetTitle>{title}</BottomSheetTitle>
+            </BottomSheetHeader>
+            <BottomSheetBody>{children}</BottomSheetBody>
+          </BottomSheetContent>
+        </BottomSheet>
+      </>
+    )
+  }
+
+  return (
+    <Popover open={open} onOpenChange={next => onOpenChange(next)}>
+      <PopoverTrigger render={trigger()} />
+      <PopoverContent
+        ref={popup}
+        aria-label={title}
+        align="start"
+        arrow={false}
+        className="p-3"
+        initialFocus={() => popup.current?.querySelector<HTMLElement>(`[${FOCUS_ATTR}]`) ?? true}
+      >
+        {children}
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+export type DatePickerProps = PickerTriggerProps & {
+  value?: string | null
+  defaultValue?: string | null
+  onValueChange?: (value: string) => void
+  min?: string
+  max?: string
+  today?: string
+  title?: string
+  placeholder?: string
+  format?: (day: string) => ReactNode
+}
+
+export function DatePicker({
+  value,
+  defaultValue = null,
+  onValueChange,
+  min,
+  max,
+  today,
+  title = '날짜 고르기',
+  placeholder = '날짜를 고르세요',
+  format = fullDate,
+  ...trigger
+}: DatePickerProps) {
+  const [open, setOpen] = useState(false)
+  const [inner, setInner] = useState<string | null>(defaultValue)
+  const current = value === undefined ? inner : value
+
+  return (
+    <PickerShell {...trigger} title={title} value={current} text={current === null ? null : format(current)} placeholder={placeholder} open={open} onOpenChange={setOpen}>
+      <Calendar
+        value={current}
+        min={min}
+        max={max}
+        today={today ?? localToday()}
+        onPick={(next) => {
+          setOpen(false)
+          if (next === current) return
+
+          onValueChange?.(next)
+          if (value === undefined) setInner(next)
+        }}
+      />
+    </PickerShell>
+  )
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantoia/ui",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "Pantoia Design System",
   "homepage": "https://design.pantoia.com",
   "repository": {
@@ -64,13 +64,13 @@
     "@types/node": "26.4.0",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.5",
-    "happy-dom": "^20.12.0",
+    "happy-dom": "^21.0.4",
     "oxlint": "1.81.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "tailwindcss": "4.3.3",
     "tsx": "4.23.12",
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.12"
   }
 }

package/registry.json

@@ -305,6 +305,30 @@
         ]
       }
     },
+    {
+      "name": "date-picker",
+      "type": "registry:ui",
+      "title": "DatePicker",
+      "files": [
+        {
+          "path": "date-picker/index.tsx",
+          "type": "registry:ui"
+        }
+      ],
+      "dependencies": [
+        "@base-ui/react"
+      ],
+      "registryDependencies": [
+        "bottom-sheet",
+        "button",
+        "input",
+        "popover",
+        "tv"
+      ],
+      "meta": {
+        "layer": "ui"
+      }
+    },
     {
       "name": "dialog",
       "type": "registry:ui",
@@ -754,6 +778,24 @@
         "layer": "ui"
       }
     },
+    {
+      "name": "time-picker",
+      "type": "registry:ui",
+      "title": "TimePicker",
+      "files": [
+        {
+          "path": "time-picker/index.tsx",
+          "type": "registry:ui"
+        }
+      ],
+      "registryDependencies": [
+        "date-picker",
+        "tv"
+      ],
+      "meta": {
+        "layer": "derived"
+      }
+    },
     {
       "name": "toast",
       "type": "registry:ui",

package/skills/pantoia-design/SKILL.md

@@ -48,7 +48,7 @@ import 경로는 저장 위치와 프로젝트의 경로 별칭을 따른다.
 패키지는 컴포넌트와 `tv`를 export하지 않는다. `add`로 복사한 파일만 import한다.
 
 `value`와 `defaultValue`, `onValueChange`를 짝으로 쓴다.
-고르지 않은 상태는 `null`이다. Select, RadioGroup, Combobox, NumberField가 같다.
+고르지 않은 상태는 `null`이다. Select, RadioGroup, Combobox, NumberField, DatePicker, TimePicker가 같다.
 Select와 RadioGroup의 state는 `useState<string | null>`로 둔다.
 
 ## 디자인 규칙
@@ -104,6 +104,19 @@ Tailwind 기본 색  bg-blue-500, text-gray-700. 역할 토큰을 쓴다
 px 직접 지정      간격과 둥글기는 토큰으로 쓴다
 ```
 
+### 비활성
+
+disabled는 이럴 때만 준다.
+
+```
+처리 중인 버튼과 메뉴 항목        끝날 때까지 다시 누르지 못하게 한다
+값을 고르거나 입력하는 컨트롤     Checkbox, RadioGroup, Select와 그 항목, Switch, NumberField. 이유를 설명이나 도움말에 적는다
+확인 문구를 입력해야 하는 버튼    입력하기 전까지
+아직 갈 수 없는 단계              단계 표시의 다음 단계
+```
+
+그 밖의 버튼과 메뉴 항목은 조건이 맞지 않아도 disabled로 두지 않는다. 누르면 이유를 `toast.warning`으로 알린다.
+
 ## 커스텀 값 추가
 
 전역 CSS에 적는다. 값은 라이트와 다크 양쪽에 모두 적는다.
@@ -158,6 +171,7 @@ className     그 한 곳만 바뀐다
 | Combobox | combobox | Combobox, ComboboxAnchor, ComboboxInput, ComboboxTrigger, ComboboxCancel, ComboboxContent, ComboboxViewport, ComboboxCollection, ComboboxItem, ComboboxItemText, ComboboxItemDescription, ComboboxGroup, ComboboxEmpty, ComboboxSeparator | surface, size |
 | CommandPalette | command-palette | CommandPalette | - |
 | ContextMenu | context-menu | ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuItemDescription, ContextMenuCheckboxItem, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent | color |
+| DatePicker | date-picker | DatePicker, PickerShell | surface, size |
 | Dialog | dialog | Dialog, DialogTrigger, DialogClose, DialogContent, DialogTitle, DialogDescription, DialogHeader, DialogBody, DialogFooter | size |
 | Drawer | drawer | Drawer, DrawerTrigger, DrawerClose, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerBody, DrawerFooter | side |
 | DropdownMenu | dropdown-menu | DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuItemDescription, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent | color |
@@ -179,6 +193,7 @@ className     그 한 곳만 바뀐다
 | Table | table | Table, TableHeader, TableHeadCell, TableBody, TableRow, TableCell | fixed, mono |
 | Tabs | tabs | Tabs, TabsList, TabsTrigger, TabsContent | - |
 | Textarea | textarea | Textarea | surface, size |
+| TimePicker | time-picker | TimePicker | surface, size |
 | Toast | toast | Toast | - |
 | Toggle | toggle | Toggle | size, shape, color, surface |
 | ToggleGroup | toggle-group | ToggleGroup, ToggleGroupItem | size, shape, surface |
@@ -212,11 +227,13 @@ Dialog, AlertDialog, Drawer, BottomSheet의 Footer는 layout으로 버튼을 배
 
 Modal은 기준 폭(기본 xs, 480px)보다 넓으면 Dialog, 좁으면 BottomSheet로 연다.
 
-Input, Textarea, NumberField, Select, ComboboxAnchor의 surface는 폼에서는 bare나 well을 쓰고, 표 셀, 헤더, 문장 안에서 값을 바로 고칠 때는 ghost를 쓴다.
+DatePicker는 `YYYY-MM-DD`, TimePicker는 `HH:mm` 글자 값을 쓴다. 48rem보다 넓으면 Popover, 좁으면 BottomSheet로 연다. 폭은 wrapper로 정한다.
+
+Input, Textarea, NumberField, Select, ComboboxAnchor, DatePicker, TimePicker의 surface는 폼에서는 bare나 well을 쓰고, 표 셀, 헤더, 문장 안에서 값을 바로 고칠 때는 ghost를 쓴다.
 
 Fieldset 안의 컨트롤은 Field로 감싼다. Fieldset의 disabled는 Field를 거쳐 컨트롤에 전달된다.
 
-Field는 라벨, 도움말, 오류 메시지를 입력 컨트롤에 묶는다. Input, Textarea, NumberField, Select, Combobox와 함께 쓴다.
+Field는 라벨, 도움말, 오류 메시지를 입력 컨트롤에 묶는다. Input, Textarea, NumberField, Select, Combobox, DatePicker, TimePicker와 함께 쓴다.
 
 Select는 고른 항목의 `SelectItemText`나 글자를 트리거에 보인다. `SelectItem`을 다른 컴포넌트로 감싸면 `items`로 라벨을 넘긴다.
 Combobox 항목이 `{ value, label }`이 아닌 객체면 `itemToStringLabel`로 `ComboboxInput`에 보일 글자를 정한다.
@@ -235,7 +252,18 @@ import { TooltipProvider } from '@/components/ui/tooltip'
 </TooltipProvider>
 ```
 
-알림은 `toast('저장했어요.')`로 띄운다. `toast.success`, `toast.error`, `toast.warning`, `toast.info`, `toast.dismiss`도 있다.
+알림은 일어난 일에 맞는 함수로 띄운다. 예시는 https://design.pantoia.com/toast/ 에 있다.
+
+```
+toast.success   요청한 작업을 끝냈다
+toast.error     요청이 실패했거나 대상을 찾을 수 없다
+toast.warning   작업이 일부만 끝났다. 권한, 상태, 규칙 때문에 할 수 없는 동작을 눌렀다
+toast.info      작업이 진행 중이다. 작업을 되돌렸다
+toast()         결과와 함께 다음 할 일이나 보이는 위치를 알린다. 바뀐 것이 없다
+toast.dismiss   띄운 알림을 닫는다
+```
+
+고쳐야 할 입력은 알림으로 띄우지 않고 FieldError나 Callout으로 화면에 남긴다. FieldError를 둘 곳이 없을 때만 `toast.warning`을 쓴다.
 
 ## 컴포넌트 내려받기
 

package/time-picker/index.tsx

@@ -0,0 +1,160 @@
+'use client'
+
+import { useState, type KeyboardEvent } from 'react'
+
+import { PickerShell, type PickerTriggerProps } from '../date-picker'
+import { tv } from '../tv'
+
+const DEFAULT_HOUR = 9
+
+const timePicker = tv({
+  slots: {
+    root: 'grid w-full min-w-52 grid-cols-3 gap-1',
+    column: 'scrollbar-thin scrollbar-thumb-line-strong scrollbar-track-transparent flex h-54 flex-col gap-0.5 overflow-y-auto',
+    item: 'text-t13 h-9 shrink-0 rounded-r8 tabular-nums transition-state'
+      + ' not-on:hover:bg-bg-neutral-hover on:bg-bg-neutral-solid on:font-bold on:text-fg-neutral-solid-contrast'
+      + ' focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-line-focus-ring',
+  },
+})
+
+const pad = (value: number) => String(value).padStart(2, '0')
+
+function partsOf(value: string | null) {
+  if (value === null) return { hour: DEFAULT_HOUR, minute: 0 }
+
+  const [hour = DEFAULT_HOUR, minute = 0] = value.split(':').map(Number)
+
+  return { hour, minute }
+}
+
+function clockText(value: string) {
+  const { hour, minute } = partsOf(value)
+
+  return `${hour < 12 ? '오전' : '오후'} ${hour % 12 || 12}:${pad(minute)}`
+}
+
+function centerInColumn(node: HTMLButtonElement | null) {
+  const column = node?.parentElement
+
+  if (node && column)
+    column.scrollTop = node.offsetTop - column.offsetTop - (column.clientHeight - node.offsetHeight) / 2
+}
+
+interface ColumnItem {
+  key: number
+  label: string
+}
+
+interface ColumnProps {
+  label: string
+  items: ColumnItem[]
+  anchor: number
+  picked: boolean
+  focusFirst?: boolean
+  onPick: (key: number) => void
+}
+
+function Column({ label, items, anchor, picked, focusFirst, onPick }: ColumnProps) {
+  const ui = timePicker()
+
+  const onKey = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+
+    event.preventDefault()
+    const index = items.findIndex(item => item.key === anchor) + (event.key === 'ArrowDown' ? 1 : -1)
+    const next = items[index]
+    if (!next) return
+
+    onPick(next.key)
+    event.currentTarget.querySelectorAll('button')[index]?.focus()
+  }
+
+  return (
+    <div role="group" aria-label={label} className={ui.column()} onKeyDown={onKey}>
+      {items.map(item => (
+        <button
+          key={item.key}
+          ref={item.key === anchor ? centerInColumn : undefined}
+          type="button"
+          aria-pressed={picked && item.key === anchor}
+          data-picker-focus={focusFirst && item.key === anchor ? '' : undefined}
+          tabIndex={item.key === anchor ? 0 : -1}
+          className={ui.item()}
+          onClick={() => onPick(item.key)}
+        >
+          {item.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+export type TimePickerProps = PickerTriggerProps & {
+  value?: string | null
+  defaultValue?: string | null
+  onValueChange?: (value: string) => void
+  step?: number
+  title?: string
+  placeholder?: string
+}
+
+export function TimePicker({
+  value,
+  defaultValue = null,
+  onValueChange,
+  step = 1,
+  title = '시각 고르기',
+  placeholder = '시각을 고르세요',
+  ...trigger
+}: TimePickerProps) {
+  const [open, setOpen] = useState(false)
+  const [inner, setInner] = useState<string | null>(defaultValue)
+  const current = value === undefined ? inner : value
+  const picked = current !== null
+  const { hour, minute } = partsOf(current)
+  const minutes = Array.from({ length: Math.ceil(60 / step) }, (_, index) => index * step)
+
+  const set = (nextHour: number, nextMinute: number) => {
+    const next = `${pad(nextHour)}:${pad(nextMinute)}`
+
+    onValueChange?.(next)
+    if (value === undefined) setInner(next)
+  }
+
+  if (!minutes.includes(minute)) {
+    minutes.push(minute)
+    minutes.sort((a, b) => a - b)
+  }
+
+  return (
+    <PickerShell {...trigger} title={title} value={current} text={current === null ? null : clockText(current)} placeholder={placeholder} open={open} onOpenChange={setOpen}>
+      <div className={timePicker().root()}>
+        <Column
+          label="오전 오후"
+          picked={picked}
+          anchor={hour < 12 ? 0 : 1}
+          items={[
+            { key: 0, label: '오전' },
+            { key: 1, label: '오후' },
+          ]}
+          onPick={key => set(hour % 12 + (key === 1 ? 12 : 0), minute)}
+        />
+        <Column
+          label="시"
+          focusFirst
+          picked={picked}
+          anchor={hour % 12 || 12}
+          items={Array.from({ length: 12 }, (_, index) => ({ key: index + 1, label: `${index + 1}시` }))}
+          onPick={key => set(key % 12 + (hour >= 12 ? 12 : 0), minute)}
+        />
+        <Column
+          label="분"
+          picked={picked}
+          anchor={minute}
+          items={minutes.map(key => ({ key, label: `${pad(key)}분` }))}
+          onPick={key => set(hour, key)}
+        />
+      </div>
+    </PickerShell>
+  )
+}