@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/otp-input/AGENTS.md

@@ -0,0 +1,162 @@
+# OTP Input
+
+> 텍스트 입력 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+인증번호처럼 정해진 자리수의 코드를 입력하는 칸. 실제 입력창 하나 위에 칸을 그리는 구조라 타이핑, 붙여넣기, SMS 자동완성, IME가 모두 자연스럽게 동작해요. 확인 중에는 회색으로 빛이 지나가고, 틀리면 빨갛게 흔들리고, 맞으면 초록색이 돼요.
+
+```tsx
+import { OtpInput } from '@iamfiro/design'
+```
+
+## API
+
+### OtpInput
+
+ref는 안쪽 <input>을 가리켜요. 초기화 후 ref.current.focus()로 다시 포커스할 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `length` | `number` | `6` | 자리수. |
+| `groups` | `number[]` |  | 칸 묶음. 예: [3, 3]. 합이 length와 다르면 무시돼요. |
+| `value` | `string` |  | 입력값(제어). |
+| `defaultValue` | `string` | `''` | 처음 값(비제어). |
+| `onValueChange` | `(value: string) => void` |  | 값이 바뀔 때. 걸러진 값(숫자만, 대문자)이 와요. |
+| `onComplete` | `(value: string) => void` |  | 모든 칸이 채워지는 순간 한 번. 여기서 확인을 시작하세요. |
+| `pattern` | `'numeric' \| 'alphanumeric'` | `'numeric'` | 받을 글자 종류. |
+| `status` | `'loading' \| 'error' \| 'success'` |  | loading: 회색 + shimmer · error: 빨강 + 흔들림 · success: 초록. loading과 success는 입력을 잠가요. |
+| `mask` | `boolean` |  | 글자 대신 점 표시. |
+| `size` | `'md' \| 'lg'` | `'md'` | 칸 크기. |
+| `disabled` | `boolean` |  | 비활성. |
+| `autoFocus` | `boolean` |  | 처음에 바로 포커스. |
+| `name` | `string` |  | 폼 제출용 이름. |
+| `id` | `string` |  | 안쪽 input의 id. Field htmlFor와 연결돼요. |
+| `aria-label` | `string` | `'인증번호'` | 스크린 리더 이름. 뒤에 'n자리'가 붙어요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 인증 흐름
+
+onComplete에서 확인을 시작하고 status를 'loading' → 'success' / 'error'로 바꿔요. 확인 중과 완료 후에는 입력이 잠겨요. 틀렸을 땐 지우고 다시 입력하면 돼요. 이 예제의 정답은 123456.
+
+```tsx
+import { useRef, useState } from 'react'
+import { RotateCcw } from 'lucide-react'
+import { Button, Text, OtpInput, type OtpInputProps } from '@iamfiro/design'
+
+// 서버 확인을 흉내 내요. 이 예제의 정답은 123456이에요.
+const checkCode = (code: string) => new Promise<boolean>((resolve) => setTimeout(() => resolve(code === '123456'), 1200))
+
+const MESSAGES = {
+  loading: '확인하는 중이에요…',
+  success: '인증이 완료됐어요.',
+  error: '인증번호가 달라요. 다시 입력해 주세요.',
+}
+
+export default function Example() {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const [code, setCode] = useState('')
+  const [status, setStatus] = useState<OtpInputProps['status']>()
+
+  const verify = async (value: string) => {
+    setStatus('loading')
+    const ok = await checkCode(value)
+    setStatus(ok ? 'success' : 'error')
+  }
+
+  const reset = () => {
+    setCode('')
+    setStatus(undefined)
+    inputRef.current?.focus()
+  }
+
+  return (
+    <div style={{ display: 'grid', gap: 12, justifyItems: 'center' }}>
+      <OtpInput
+        ref={inputRef}
+        groups={[3, 3]}
+        value={code}
+        onValueChange={(value) => {
+          setCode(value)
+          setStatus(undefined)
+        }}
+        onComplete={verify}
+        status={status}
+        aria-label="문자로 받은 인증번호"
+      />
+      <Text variant="body-sm" tone={status === 'success' ? 'success' : status === 'error' ? 'danger' : 'tertiary'}>
+        {status ? MESSAGES[status] : '문자로 받은 6자리 번호를 입력해 주세요.'}
+      </Text>
+      {(status === 'success' || status === 'error') && (
+        <Button variant="ghost" size="sm" icon={<RotateCcw />} onClick={reset}>
+          처음부터 다시
+        </Button>
+      )}
+    </div>
+  )
+}
+```
+
+### 그룹 · 붙여넣기
+
+groups로 칸 사이에 구분선을 넣어요(합이 length와 같아야 해요). 붙여넣은 "482-913"의 하이픈·공백은 자동으로 빠져요.
+
+```tsx
+import { CopyButton, Text, OtpInput } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 16, justifyItems: 'center' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <Text variant="body-sm" tone="secondary">
+          인증번호는{' '}
+          <Text as="strong" variant="label-md" numeric>
+            482-913
+          </Text>
+          이에요.
+        </Text>
+        <CopyButton value="482-913" label="복사" />
+      </div>
+      <OtpInput groups={[3, 3]} aria-label="인증번호" />
+    </div>
+  )
+}
+```
+
+### 가리기
+
+mask는 글자 대신 점을 보여줘요. 비밀번호·PIN에 쓰세요. size는 md / lg.
+
+```tsx
+import { Field, OtpInput } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Field label="결제 비밀번호" hint="숫자 4자리" htmlFor="payment-pin">
+      <OtpInput id="payment-pin" length={4} mask size="lg" aria-label="결제 비밀번호" />
+    </Field>
+  )
+}
+```
+
+### 영문 + 숫자
+
+pattern='alphanumeric'은 영문과 숫자를 받고 대문자로 바꿔요. 기본 'numeric'은 숫자 외 입력을 무시해요.
+
+```tsx
+import { Field, OtpInput } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 20 }}>
+      <Field label="백업 코드" hint="영문과 숫자 8자리. 소문자로 입력해도 대문자로 바뀌어요." htmlFor="backup-code">
+        <OtpInput id="backup-code" length={8} groups={[4, 4]} pattern="alphanumeric" aria-label="백업 코드" />
+      </Field>
+      <Field label="비활성" htmlFor="backup-code-off">
+        <OtpInput id="backup-code-off" length={8} groups={[4, 4]} pattern="alphanumeric" defaultValue="K7PQ2M9X" disabled aria-label="백업 코드" />
+      </Field>
+    </div>
+  )
+}
+```

package/agents/pagination/AGENTS.md

@@ -0,0 +1,189 @@
+# Pagination
+
+> 내비게이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+긴 목록을 페이지로 나눠 이동해요. 현재 페이지는 채워진 칩이고, 페이지를 바꾸면 칩이 새 번호로 미끄러져요. 양 끝(boundaryCount)과 현재 페이지 양옆(siblingCount)만 보이고 나머지는 "…"로 접혀요. 칸 수가 일정해서 넘겨도 버튼이 들썩이지 않아요. 페이지 수 대신 전체 개수 + 페이지 크기를 주면 "1–20 / 248개" 범위 글과 "페이지당 N개" Select를 함께 보여 줘요.
+
+```tsx
+import { Pagination, paginationRange } from '@iamfiro/design'
+```
+
+## API
+
+### Pagination
+
+<nav aria-label>로 감싸고, 현재 페이지에는 aria-current="page", 각 번호 버튼에는 "N페이지" 이름이 붙어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `page` | `number` |  | 현재 페이지(1부터, 제어). |
+| `defaultPage` | `number` | `1` | 처음 페이지(비제어). |
+| `onPageChange` | `(page: number) => void` |  | 페이지가 바뀔 때. |
+| `totalPages` | `number` |  | 전체 페이지 수. 없으면 totalItems ÷ pageSize로 계산해요. |
+| `totalItems` | `number` |  | 전체 항목 수. 주면 범위 글("1–20 / 248개")이 보여요. |
+| `pageSize / defaultPageSize` | `number` | `20` | 페이지당 항목 수(제어 / 비제어). |
+| `onPageSizeChange` | `(pageSize: number) => void` |  | 페이지 크기가 바뀔 때. |
+| `pageSizeOptions` | `number[]` |  | 주면 "페이지당 N개" Select가 보여요. |
+| `siblingCount` | `number` | `1` | 현재 페이지 양옆에 보일 페이지 수. |
+| `boundaryCount` | `number` | `1` | 양 끝에 항상 보일 페이지 수. |
+| `variant` | `'default' \| 'simple'` | `'default'` | default: 번호 버튼 · simple: "3 / 12" 글자만. |
+| `tone` | `'neutral' \| 'primary'` | `'neutral'` | 현재 페이지 칩 색. neutral 회색 · primary 거의 검정. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 버튼 높이 28 · 34 · 40. |
+| `showFirstLast` | `boolean` |  | 첫 · 마지막 페이지 버튼. |
+| `showRange` | `boolean` | `totalItems가 있으면 true` | 범위 글 표시. |
+| `formatRange` | `({ start, end, total }) => ReactNode` |  | 범위 글을 직접 만들 때. |
+| `showJump` | `boolean` |  | 번호를 입력해 이동하는 작은 칸. |
+| `disabled` | `boolean` |  | 모든 버튼 비활성(불러오는 중). |
+| `aria-label` | `string` | `'페이지'` | nav 랜드마크 이름. 한 화면에 여럿이면 구분되게. |
+
+### paginationRange
+
+번호를 직접 그릴 때 쓰는 계산 함수. 결과는 (number | "start-ellipsis" | "end-ellipsis")[].
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `page` (필수) | `number` |  | 현재 페이지. |
+| `count` (필수) | `number` |  | 전체 페이지 수. |
+| `siblingCount` | `number` | `1` | 현재 페이지 양옆 개수. |
+| `boundaryCount` | `number` | `1` | 양 끝 개수. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+비제어(defaultPage). 첫 · 마지막 페이지에서는 화살표가 비활성돼요. 숫자는 tabular라 자릿수가 바뀌어도 폭이 흔들리지 않아요.
+
+```tsx
+import { Pagination } from '@iamfiro/design'
+
+export default function Example() {
+  return <Pagination totalPages={20} defaultPage={5} />
+}
+```
+
+### 표 아래 · 개수와 페이지 크기
+
+totalItems + pageSize로 페이지 수를 계산하고, 왼쪽에 범위 글("1–10 / 248개")과 페이지당 개수 Select가 붙어요. 페이지 크기를 바꾸면 보고 있던 첫 항목이 들어 있는 페이지로 옮겨 가요.
+
+```tsx
+import { useState } from 'react'
+import { Pagination, Table, Stack } from '@iamfiro/design'
+
+const NAMES = ['김민지', '이도현', '박서연', '최준호', '정하은', '강지우', '윤서준', '임수아', '한예린', '오태윤']
+const TEAMS = ['디자인', '개발', '마케팅', '운영']
+const TOTAL = 248
+
+const members = Array.from({ length: TOTAL }, (_, i) => ({
+  id: i + 1,
+  name: NAMES[i % NAMES.length],
+  team: TEAMS[(i * 7) % TEAMS.length],
+  joined: `${(i % 12) + 1}월 ${(i % 28) + 1}일`,
+}))
+
+export default function Example() {
+  const [page, setPage] = useState(1)
+  const [pageSize, setPageSize] = useState(10)
+  const rows = members.slice((page - 1) * pageSize, page * pageSize)
+
+  return (
+    <Stack gap={4}>
+      <Table
+        density="compact"
+        rowKey={(r) => r.id}
+        columns={[
+          { key: 'id', header: '번호', numeric: true, width: 72 },
+          { key: 'name', header: '이름' },
+          { key: 'team', header: '팀' },
+          { key: 'joined', header: '가입일', align: 'end' },
+        ]}
+        rows={rows}
+      />
+      <Pagination
+        page={page}
+        onPageChange={setPage}
+        totalItems={TOTAL}
+        pageSize={pageSize}
+        onPageSizeChange={setPageSize}
+        pageSizeOptions={[10, 20, 50]}
+        size="sm"
+        aria-label="멤버 목록 페이지"
+      />
+    </Stack>
+  )
+}
+```
+
+### simple · 처음/마지막 · 범위
+
+variant='simple'은 번호 대신 "3 / 12"만 보여 줘요. showFirstLast는 « » 버튼, tone='primary'는 진한 칩이에요.
+
+```tsx
+import { Pagination, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={6}>
+      <Stack gap={2}>
+        <Text variant="label-sm" tone="secondary">
+          simple — 좁은 곳 · 모바일
+        </Text>
+        <Pagination variant="simple" totalPages={12} defaultPage={3} aria-label="사진 페이지" />
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="label-sm" tone="secondary">
+          처음 · 마지막 버튼 + primary 칩
+        </Text>
+        <Pagination totalPages={48} defaultPage={24} showFirstLast tone="primary" aria-label="검색 결과 페이지" />
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="label-sm" tone="secondary">
+          siblingCount 2 · boundaryCount 2
+        </Text>
+        <Pagination totalPages={80} defaultPage={40} siblingCount={2} boundaryCount={2} aria-label="게시글 페이지" />
+      </Stack>
+    </Stack>
+  )
+}
+```
+
+### 페이지로 이동
+
+showJump: 페이지가 많을 때 번호를 입력해 바로 이동해요. Enter = 이동, Esc나 포커스를 떠나면 비워요. 한글 조합 중 Enter는 무시해요.
+
+```tsx
+import { useState } from 'react'
+import { Pagination, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [page, setPage] = useState(37)
+  return (
+    <Stack gap={3}>
+      <Pagination page={page} onPageChange={setPage} totalPages={120} showFirstLast showJump aria-label="주문 내역 페이지" />
+      <Text variant="body-sm" tone="secondary" numeric>
+        지금 {page}페이지를 보고 있어요. 번호를 입력하고 Enter를 누르면 이동하고, 범위를 넘으면 끝 페이지로 가요.
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 크기와 비활성
+
+size sm / md / lg(버튼 높이 28 · 34 · 40). disabled면 모든 버튼이 잠겨요.
+
+```tsx
+import { Pagination, Stack } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4}>
+      <Pagination size="sm" totalPages={10} defaultPage={2} aria-label="작은 페이지 이동" />
+      <Pagination size="md" totalPages={10} defaultPage={2} aria-label="기본 페이지 이동" />
+      <Pagination size="lg" totalPages={10} defaultPage={2} aria-label="큰 페이지 이동" />
+      <Pagination totalPages={10} defaultPage={2} disabled aria-label="불러오는 중인 페이지" />
+    </Stack>
+  )
+}
+```

package/agents/phone-input/AGENTS.md

@@ -0,0 +1,131 @@
+# PhoneInput
+
+> 텍스트 입력 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+국가를 고르고 전화번호를 입력하는 칸. 왼쪽 국기 + 국가 번호를 누르면 국가 목록이 칸 전체 폭으로 열리고, 번호 칸엔 숫자만 들어가며 그 나라 방식대로 하이픈 · 괄호가 붙어요. 붙여넣은 "+82 10-…"는 국가까지 맞춰 줘요.
+
+```tsx
+import { PhoneInput } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 숫자만 받는 칸(금액 · 전화번호 · 카드 번호)은 `useDigitInput`을 Input에 펼친다: 글자는 아예 안 들어가고, 쉼표 · 하이픈은 `format`으로 붙이고, 커서는 같은 숫자 뒤에 머물고, 구분자 위 Backspace는 앞 숫자를 지운다. `type="number"`는 쓰지 않는다. 전화번호는 `PhoneInput`(칸 안 `Select bare` 국가 선택 + 국기 `Flag`, 목록은 `anchorRef`로 칸 전체 폭). 국기는 이모지 대신 `Flag`(Windows에서 이모지 국기는 글자로 나온다).
+
+## API
+
+### PhoneInput
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value / defaultValue` | `string` |  | 국내 번호 숫자만("01012345678"). |
+| `onValueChange` | `(digits, { country, e164 }) => void` |  | 번호가 바뀔 때. e164는 "+821012345678"처럼 국제 번호(맨 앞 0 제외). |
+| `country / defaultCountry` | `FlagCode` | `'KR'` | 고른 국가. |
+| `onCountryChange` | `(code: FlagCode) => void` |  | 국가가 바뀔 때. |
+| `countries` | `PhoneCountry[]` | `PHONE_COUNTRIES` | 보여 줄 국가와 순서. 각 국가는 code · name · dial · pattern("###-####-####") · example · trunk. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 높이 36 / 44 / 52px. |
+| `invalid` | `boolean` |  | 오류 표시. |
+| `disabled` | `boolean` |  | 국가 선택과 번호 칸 모두 비활성. |
+| `placeholder` | `string` |  | 생략하면 그 나라의 예시 번호. |
+| `name` | `string` |  | 폼으로 보낼 때 이 이름으로 국제 번호를 보내요. |
+
+### useDigitInput
+
+숫자만 받는 입력 훅(@/ds/hooks). PhoneInput과 금액 칸이 같이 써요. 결과를 Input에 펼쳐 넣어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `digits` (필수) | `string` |  | 숫자만 담긴 값. |
+| `onDigitsChange` (필수) | `(digits: string) => void` |  | 숫자가 바뀔 때. |
+| `format` | `(digits: string) => string` |  | 보여 줄 모양(쉼표, 하이픈). 커서는 같은 숫자 뒤에 머물러요. |
+| `maxDigits` | `number` |  | 최대 자릿수. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+숫자만 들어가요. 글자를 쳐도 무시되고, 하이픈 위에서 Backspace를 누르면 앞 숫자가 지워져요. 국가를 바꾸면 자릿수와 모양이 따라 바뀌어요.
+
+```tsx
+import { Field, PhoneInput } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ width: 320 }}>
+      <Field label="휴대폰 번호" htmlFor="phone" hint="인증번호를 문자로 보내 드려요.">
+        <PhoneInput id="phone" />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 제어 · 국제 번호
+
+value / country로 제어하고 onValueChange의 e164로 저장할 국제 번호(+821012345678)를 받아요. "+1 201 555 0123"을 붙여넣어 보세요.
+
+```tsx
+import { useState } from 'react'
+import { Field, Stack, DescriptionList, PhoneInput, type PhoneInputProps } from '@iamfiro/design'
+
+export default function Example() {
+  const [country, setCountry] = useState<PhoneInputProps['country']>('KR')
+  const [digits, setDigits] = useState('01012345678')
+  const [e164, setE164] = useState('+821012345678')
+
+  return (
+    <Stack gap={4} style={{ width: 320 }}>
+      <Field label="연락처" htmlFor="contact">
+        <PhoneInput
+          id="contact"
+          country={country}
+          onCountryChange={setCountry}
+          value={digits}
+          onValueChange={(next, { e164 }) => {
+            setDigits(next)
+            setE164(e164)
+          }}
+        />
+      </Field>
+      <DescriptionList
+        variant="soft"
+        layout="inline"
+        items={[
+          { label: '국가', value: country },
+          { label: '입력한 숫자', value: digits || '—' },
+          { label: '국제 번호', value: e164 || '—' },
+        ]}
+      />
+    </Stack>
+  )
+}
+```
+
+### 크기와 상태
+
+Input과 같은 size · invalid · disabled.
+
+```tsx
+import { Field, PhoneInput } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 280px)', gap: 16, alignItems: 'end' }}>
+      <Field label="작게 (sm)" htmlFor="phone-sm">
+        <PhoneInput id="phone-sm" size="sm" defaultCountry="US" />
+      </Field>
+      <Field label="크게 (lg)" htmlFor="phone-lg">
+        <PhoneInput id="phone-lg" size="lg" defaultCountry="JP" />
+      </Field>
+      <Field label="오류" htmlFor="phone-invalid" hint="번호를 끝까지 입력해 주세요." invalid>
+        <PhoneInput id="phone-invalid" defaultValue="0101234" invalid />
+      </Field>
+      <Field label="비활성" htmlFor="phone-disabled">
+        <PhoneInput id="phone-disabled" defaultValue="01098765432" disabled />
+      </Field>
+    </div>
+  )
+}
+```