@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/time-picker/AGENTS.md

@@ -0,0 +1,228 @@
+# TimePicker
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+시각 입력. DatePicker와 같은 입력 칸이라 '14:30', '오후 2시 반'처럼 바로 쳐도 되고, 누르면 오전·오후 / 시 / 분 열이 열려요. 열마다 따로 스크롤되고 한 칸씩 맞춰 멈춰요. 고르는 동안은 칸에 미리 보여주기만 하고, Enter · 확인 · 바깥 클릭에서 확정, Esc는 열기 전 시각으로 되돌려요. 값은 언제나 'HH:mm'(24시간) 문자열이에요. 일정처럼 정해진 칸에서 고를 땐 mode="list".
+
+```tsx
+import { TimePicker, formatTime, parseTimeInput } from '@iamfiro/design'
+```
+
+## API
+
+### TimePicker
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `string \| null` |  | 'HH:mm'(제어). |
+| `defaultValue` | `string \| null` | `null` | 처음 값(비제어). |
+| `onValueChange` | `(time: string \| null) => void` |  | 확정하거나 지울 때. |
+| `hourCycle` | `12 \| 24` | `12` | '오후 2:30' + 오전·오후 열, 또는 '14:30'. |
+| `minuteStep` | `number` | `5 (list: 30)` | 분 열 간격 · 목록 칸 간격. |
+| `min / max` | `string` |  | 고를 수 있는 처음 · 마지막 시각('HH:mm'). |
+| `isTimeDisabled` | `(time: string) => boolean` |  | 추가로 막을 시각(점심시간, 예약된 칸). |
+| `mode` | `'columns' \| 'list'` | `'columns'` | 열 팝오버 또는 Listbox 목록. |
+| `durationFrom` | `string` |  | 목록 모드: 이 시각부터의 길이를 설명으로 보여주고, 이전 칸은 막아요(종료 시간). |
+| `formatValue` | `(time: string) => string` | `formatTime` | 칸에 쓰는 형식. |
+| `placeholder` | `string` | `'시간 입력 또는 선택'` | 비었을 때 문구. |
+| `clearable` | `boolean` | `true` | × 지우기. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 높이 36 / 44 / 52px. |
+| `invalid / disabled` | `boolean` |  | 오류 · 비활성. |
+| `align` | `'start' \| 'end'` | `'start'` | 팝오버 정렬. |
+| `name` | `string` |  | 폼 제출용 hidden input('HH:mm'). |
+
+### 도우미 함수
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `formatTime(time, hourCycle?)` | `string` |  | '14:30' → '오후 2:30' / '14:30'. |
+| `parseTimeInput(text)` | `string \| null` |  | '오후 2시 반' → '14:30'. 못 읽으면 null. |
+| `timeToMinutes / minutesToTime` | `number · string` |  | 'HH:mm' ↔ 자정부터의 분. |
+| `formatDuration(minutes)` | `string` |  | 90 → '1시간 30분'. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+'오후 2:30'처럼 보이고 값은 '14:30'. ↓로 열에 들어가 ↑↓로 바꾸고, ←→ · Tab으로 열을 옮겨요. Enter 확정, Esc 취소.
+
+```tsx
+import { useState } from 'react'
+import { Field, Stack, Text, TimePicker } from '@iamfiro/design'
+
+export default function Example() {
+  const [time, setTime] = useState<string | null>('14:30')
+  return (
+    <Stack gap={2} style={{ width: 260 }}>
+      <Field label="알림 시간" htmlFor="remind-at">
+        <TimePicker id="remind-at" value={time} onValueChange={setTime} />
+      </Field>
+      <Text variant="caption" tone="tertiary">
+        값: {time ?? '없음'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 직접 입력
+
+완전한 시각이 되면 열이 따라와요. 못 알아들으면 빨갛게, 칸을 벗어나면 원래 값으로. 오전·오후가 없으면 24시간으로 읽어요.
+
+```tsx
+import { useState } from 'react'
+import { Field, Stack, Text, TimePicker } from '@iamfiro/design'
+
+export default function Example() {
+  const [time, setTime] = useState<string | null>(null)
+  return (
+    <Stack gap={2} style={{ width: 260 }}>
+      <Field label="퇴근 시간" htmlFor="leave-at" hint="예) 18:30 · 1830 · 오후 6시 반 · 6:30pm · 정오">
+        <TimePicker id="leave-at" value={time} onValueChange={setTime} />
+      </Field>
+      <Text variant="caption" tone="tertiary">
+        값: {time ?? '없음'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 12시간 · 24시간 · 간격
+
+hourCycle과 minuteStep. 간격에 안 맞게 친 분(09:07)도 열에 끼워 보여줘요.
+
+```tsx
+import { Field, Grid, TimePicker } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Grid columns={2} gap={4} style={{ width: 480 }}>
+      <Field label="12시간 · 5분 단위" htmlFor="tp-12">
+        <TimePicker id="tp-12" defaultValue="09:05" />
+      </Field>
+      <Field label="24시간 · 15분 단위" htmlFor="tp-24">
+        <TimePicker id="tp-24" hourCycle={24} minuteStep={15} defaultValue="21:45" />
+      </Field>
+    </Grid>
+  )
+}
+```
+
+### 고를 수 있는 시간 제한
+
+min · max · isTimeDisabled. 모든 분이 막힌 시와 오전·오후도 함께 막혀요.
+
+```tsx
+import { Field, TimePicker, timeToMinutes } from '@iamfiro/design'
+
+// 점심시간(12:00 – 12:59)은 예약할 수 없어요.
+const isLunch = (time: string) => timeToMinutes(time) >= 12 * 60 && timeToMinutes(time) < 13 * 60
+
+export default function Example() {
+  return (
+    <div style={{ width: 260 }}>
+      <Field label="방문 예약" htmlFor="visit-at" hint="09:00 – 18:00, 점심시간 제외. 막힌 시간은 취소선이에요.">
+        <TimePicker id="visit-at" min="09:00" max="18:00" minuteStep={10} isTimeDisabled={isLunch} />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 목록 모드(일정)
+
+mode="list"는 30분 간격 목록. 종료 칸은 durationFrom으로 길이('1시간 30분')를 보여주고 시작 이전은 막아요. 입력 칸에서 ↑↓로 옮기며 계속 칠 수 있어요.
+
+```tsx
+import { useState } from 'react'
+import { Field, Grid, TimePicker, minutesToTime, timeToMinutes } from '@iamfiro/design'
+
+export default function Example() {
+  const [start, setStart] = useState<string | null>('10:00')
+  const [end, setEnd] = useState<string | null>('11:00')
+  return (
+    <Grid columns={2} gap={4} style={{ width: 480 }}>
+      <Field label="시작" htmlFor="meet-start">
+        <TimePicker
+          id="meet-start"
+          mode="list"
+          min="08:00"
+          max="20:00"
+          value={start}
+          onValueChange={(next) => {
+            setStart(next)
+            // 시작을 옮기면 끝도 같은 길이만큼 따라가요.
+            if (next && start && end) {
+              const length = timeToMinutes(end) - timeToMinutes(start)
+              setEnd(minutesToTime(Math.min(timeToMinutes(next) + length, 21 * 60)))
+            }
+          }}
+        />
+      </Field>
+      <Field label="종료" htmlFor="meet-end">
+        <TimePicker id="meet-end" mode="list" min="08:00" max="21:00" durationFrom={start ?? undefined} value={end} onValueChange={setEnd} />
+      </Field>
+    </Grid>
+  )
+}
+```
+
+### DatePicker와 함께
+
+날짜와 시각을 따로 받아 하나의 Date로 합쳐요.
+
+```tsx
+import { useState } from 'react'
+import { Field, Grid, Stack, Text, DatePicker, TimePicker, formatDate, formatTime, timeToMinutes } from '@iamfiro/design'
+
+export default function Example() {
+  const [date, setDate] = useState<Date | null>(new Date(2026, 9, 28))
+  const [time, setTime] = useState<string | null>('15:00')
+  const at = date && time ? new Date(date.getFullYear(), date.getMonth(), date.getDate(), 0, timeToMinutes(time)) : null
+  return (
+    <Stack gap={2} style={{ width: 480 }}>
+      <Grid columns={2} gap={3}>
+        <Field label="게시 날짜" htmlFor="publish-date">
+          <DatePicker id="publish-date" value={date} onValueChange={setDate} />
+        </Field>
+        <Field label="게시 시간" htmlFor="publish-time">
+          <TimePicker id="publish-time" value={time} onValueChange={setTime} minuteStep={15} />
+        </Field>
+      </Grid>
+      <Text variant="caption" tone="tertiary">
+        {at && time ? `${formatDate(at)} ${formatTime(time)}에 게시돼요` : '날짜와 시간을 골라 주세요'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 크기와 상태
+
+size · invalid · disabled. Field와 함께 쓰면 라벨이 연결돼요.
+
+```tsx
+import { Field, Grid, TimePicker } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Grid columns={2} gap={4} style={{ width: 480 }}>
+      <Field label="작게 (sm)" htmlFor="tp-sm">
+        <TimePicker id="tp-sm" size="sm" defaultValue="08:30" />
+      </Field>
+      <Field label="크게 (lg)" htmlFor="tp-lg">
+        <TimePicker id="tp-lg" size="lg" />
+      </Field>
+      <Field label="마감 시간" invalid hint="마감 시간을 골라 주세요." htmlFor="tp-err">
+        <TimePicker id="tp-err" invalid />
+      </Field>
+      <Field label="정산 시간" htmlFor="tp-off">
+        <TimePicker id="tp-off" defaultValue="00:00" disabled />
+      </Field>
+    </Grid>
+  )
+}
+```