@iamfiro/design 0.0.0-stage → 0.1.0

package/agents/tag-input/AGENTS.md

@@ -0,0 +1,246 @@
+# TagInput
+
+> 텍스트 입력 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+자유롭게 친 글자를 태그로 모으는 입력 칸. Enter · 쉼표 · Tab으로 추가하고, 붙여넣은 글은 구분자로 나눠 한꺼번에 넣어요. 빈 칸에서 Backspace는 처음엔 마지막 태그를 표시만 하고 두 번째에 지워서, 한 번 잘못 눌러 지워지는 일이 없어요. 중복·규칙 위반은 흔들어서 알리고, 지운 태그는 폭이 접히며 나머지가 미끄러져 와요. 한글 조합 중의 키는 무시해요. 태그 모양·여백은 MultiSelect · Combobox와 같아요(왼쪽 8, 높이 28, 간격 6).
+
+```tsx
+import { TagInput, type TagRejectReason } from '@iamfiro/design'
+```
+
+## API
+
+### TagInput
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `string[]` |  | 태그 목록(제어). |
+| `defaultValue` | `string[]` | `[]` | 처음 태그(비제어). |
+| `onValueChange` | `(tags: string[]) => void` |  | 추가 · 삭제 · 수정할 때. |
+| `delimiters` | `string[]` | `['Enter', 'Tab', ',']` | 태그를 만드는 키. 'Enter' · 'Tab' 또는 한 글자(',' ';' ' '). 붙여넣기는 이 글자(와 줄바꿈 · 탭)로 나눠요. |
+| `validate` | `(tag, tags) => boolean \| string` |  | true면 통과, false나 메시지면 거절(칸이 흔들림). |
+| `allowInvalid` | `boolean` |  | validate에 걸린 태그도 빨간 톤으로 남겨요. |
+| `allowDuplicates` | `boolean` | `false` | 중복 허용. 기본은 대소문자 · 앞뒤 공백 무시하고 거절, 기존 태그가 흔들려요. |
+| `transform` | `(text: string) => string` |  | 태그가 되기 전에 다듬기(앞의 # 제거, 소문자 등). |
+| `max` | `number` |  | 최대 개수. 넘치면 칸이 흔들려요. |
+| `onReject` | `(text, reason: 'duplicate' \| 'invalid' \| 'max', message?) => void` |  | 거절될 때마다. 이유를 hint에 보여줄 때. |
+| `suggestions` | `string[]` |  | 치는 동안 보여줄 추천. ↓로 골라 Enter, 그냥 Enter는 친 글자 그대로. |
+| `editable` | `boolean` | `true` | 더블클릭 · 표시 후 Enter로 그 자리 수정. 비우고 확정하면 삭제. |
+| `placeholder` | `string` | `'입력 후 Enter'` | 태그가 없을 때 문구. |
+| `leading` | `ReactNode` |  | 앞쪽 아이콘. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 최소 높이 36 / 44 / 52px. 태그가 많으면 줄을 바꿔 늘어나요. |
+| `invalid / disabled` | `boolean` |  | 오류 · 비활성. |
+| `name` | `string` |  | 폼 제출용. 태그마다 hidden input. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+제어 모드(value + onValueChange). ×로 지우고, 태그를 한 번 누르면 표시, 더블클릭하면 그 자리에서 고쳐요.
+
+```tsx
+import { useState } from 'react'
+import { Field, Stack, Text, TagInput } from '@iamfiro/design'
+
+export default function Example() {
+  const [tags, setTags] = useState(['디자인 시스템', '접근성', '모션'])
+  return (
+    <Stack gap={2} style={{ width: 360 }}>
+      <Field label="관심 주제" htmlFor="topics" hint="Enter · 쉼표 · Tab으로 추가해요. 쉼표로 이어 붙여넣어도 나눠져요.">
+        <TagInput id="topics" value={tags} onValueChange={setTags} placeholder="주제 입력 후 Enter" />
+      </Field>
+      <Text variant="caption" tone="tertiary">
+        {tags.length}개: {tags.join(' · ') || '없음'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 키보드
+
+입력 칸에 포커스를 둔 채 태그를 오가요. 표시된 태그는 한 단계 진한 회색이에요.
+
+```tsx
+import { Field, Inline, Kbd, Stack, Text, TagInput } from '@iamfiro/design'
+
+const KEYS: { keys: string[]; label: string }[] = [
+  { keys: ['backspace'], label: '빈 칸에서 한 번: 마지막 태그 표시 · 한 번 더: 삭제' },
+  { keys: ['left', 'right'], label: '태그 사이 이동 (맨 오른쪽 다음은 입력 칸)' },
+  { keys: ['enter'], label: '표시한 태그 수정 · 더블클릭도 같아요' },
+  { keys: ['esc'], label: '표시 해제 · 수정 취소' },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={4} style={{ width: 400 }}>
+      <Field label="라벨" htmlFor="labels" hint="한글을 조합하는 중의 Enter · 쉼표는 글자를 끝내는 데만 쓰여요.">
+        <TagInput id="labels" defaultValue={['버그', '긴급', '디자인 검토', '백엔드']} placeholder="라벨 추가" />
+      </Field>
+      <Stack gap={2}>
+        {KEYS.map((k) => (
+          <Inline key={k.label} gap={2} align="center">
+            <Kbd keys={k.keys} size="sm" />
+            <Text variant="body-sm" tone="secondary">
+              {k.label}
+            </Text>
+          </Inline>
+        ))}
+      </Stack>
+    </Stack>
+  )
+}
+```
+
+### 규칙 · 최대 개수
+
+validate · max · 중복 거절. onReject로 이유를 받아 Field hint에 보여줘요.
+
+```tsx
+import { useState } from 'react'
+import { Field, TagInput, type TagRejectReason } from '@iamfiro/design'
+
+const MAX = 5
+
+const MESSAGES: Record<TagRejectReason, string> = {
+  duplicate: '이미 있는 키워드예요.',
+  invalid: '키워드는 12자까지 쓸 수 있어요.',
+  max: `키워드는 ${MAX}개까지예요.`,
+}
+
+export default function Example() {
+  const [keywords, setKeywords] = useState(['봄 신상', '린넨'])
+  const [error, setError] = useState<string | null>(null)
+  return (
+    <div style={{ width: 380 }}>
+      <Field
+        label={`검색 키워드 (${keywords.length}/${MAX})`}
+        htmlFor="keywords"
+        invalid={!!error}
+        hint={error ?? '같은 키워드를 다시 넣으면 기존 태그가 흔들려요. 12자를 넘거나 5개를 넘기면 칸이 흔들려요.'}
+      >
+        <TagInput
+          id="keywords"
+          value={keywords}
+          onValueChange={(next) => {
+            setKeywords(next)
+            setError(null)
+          }}
+          max={MAX}
+          validate={(text) => text.length <= 12}
+          onReject={(_, reason) => setError(MESSAGES[reason])}
+          placeholder="키워드 입력"
+        />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 형식이 틀린 태그 남기기
+
+allowInvalid면 validate에 걸린 태그도 빨간 톤으로 남겨요(받는 사람 칸). 마우스를 올리면 이유가 보여요.
+
+```tsx
+import { Field, TagInput } from '@iamfiro/design'
+import { Mail } from 'lucide-react'
+
+const isEmail = (text: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(text) || '이메일 형식이 아니에요'
+
+export default function Example() {
+  return (
+    <div style={{ width: 420 }}>
+      <Field label="받는 사람" htmlFor="recipients" hint="스페이스 · 쉼표 · 세미콜론으로 나눠요. 형식이 틀린 주소는 빨간 태그로 남아 바로 고칠 수 있어요(더블클릭).">
+        <TagInput
+          id="recipients"
+          leading={<Mail />}
+          defaultValue={['minji.kim@lumen.app', 'dohyun.lee@lumen', 'seoyeon@lumen.app']}
+          delimiters={['Enter', 'Tab', ',', ';', ' ']}
+          validate={isEmail}
+          allowInvalid
+          transform={(text) => text.toLowerCase()}
+          placeholder="이메일 주소"
+        />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 추천 목록
+
+suggestions를 주면 치는 동안 Listbox가 떠요. 이미 넣은 것은 빠져요.
+
+```tsx
+import { Field, TagInput } from '@iamfiro/design'
+
+const SKILLS = ['React', 'React Native', 'TypeScript', 'JavaScript', 'Next.js', 'Vite', 'Node.js', 'GraphQL', 'Figma', 'Storybook', '접근성', '애니메이션', '디자인 토큰', '테스트 자동화']
+
+export default function Example() {
+  return (
+    <div style={{ width: 380 }}>
+      <Field label="기술 스택" htmlFor="skills" hint="치는 동안 추천이 떠요. ↓로 골라 Enter, 그냥 Enter는 친 글자 그대로 추가해요. 앞의 #은 지워져요.">
+        <TagInput
+          id="skills"
+          suggestions={SKILLS}
+          defaultValue={['React', 'TypeScript']}
+          transform={(text) => text.replace(/^#+/, '')}
+          placeholder="#태그 또는 이름"
+        />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 크기 · 상태 · 폼
+
+size · invalid · disabled. name을 주면 태그마다 hidden input으로 제출돼요.
+
+```tsx
+import { useState, type FormEvent } from 'react'
+import { Button, Field, Grid, Stack, Text, TagInput } from '@iamfiro/design'
+
+export default function Example() {
+  const [sent, setSent] = useState<string[] | null>(null)
+  const submit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault()
+    setSent(new FormData(e.currentTarget).getAll('tags').map(String))
+  }
+  return (
+    <Stack gap={5} style={{ width: 520 }}>
+      <Grid columns={2} gap={4}>
+        <Field label="작게 (sm)" htmlFor="ti-sm">
+          <TagInput id="ti-sm" size="sm" defaultValue={['기획', '리서치']} />
+        </Field>
+        <Field label="크게 (lg)" htmlFor="ti-lg">
+          <TagInput id="ti-lg" size="lg" defaultValue={['출시']} />
+        </Field>
+        <Field label="태그" invalid hint="태그를 하나 이상 넣어 주세요." htmlFor="ti-err">
+          <TagInput id="ti-err" invalid />
+        </Field>
+        <Field label="잠긴 태그" htmlFor="ti-off">
+          <TagInput id="ti-off" defaultValue={['보관됨', '읽기 전용']} disabled />
+        </Field>
+      </Grid>
+      <form onSubmit={submit}>
+        <Stack gap={2}>
+          <Field label="폼으로 보내기 (name=&quot;tags&quot;)" htmlFor="ti-form">
+            <TagInput id="ti-form" name="tags" defaultValue={['서울', '부산']} />
+          </Field>
+          <Button type="submit" size="sm" style={{ alignSelf: 'flex-start' }}>
+            제출
+          </Button>
+          {sent && (
+            <Text variant="caption" tone="tertiary">
+              보낸 값: {sent.join(', ') || '없음'}
+            </Text>
+          )}
+        </Stack>
+      </form>
+    </Stack>
+  )
+}
+```

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>
+  )
+}
+```