@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/tabs/AGENTS.md

@@ -0,0 +1,305 @@
+# Tabs
+
+> 내비게이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+같은 자리에서 여러 패널을 바꿔 보여줘요. Tabs 안에 TabList · Tab · TabPanel을 조합하고, 선택 표시는 탭 사이를 미끄러지듯 이동해요. ← → · Home / End로 탭을 옮기고, 무거운 패널은 manual 활성화로 Enter / Space를 누를 때만 바꿔요.
+
+```tsx
+import { Tab, TabList, TabPanel, Tabs } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 탭은 `Tabs`(패널 연결). `SegmentedControl`은 같은 화면 안의 보기 전환에만.
+
+## API
+
+### Tabs
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `string` |  | 선택된 탭(제어). |
+| `defaultValue` | `string` | `''` | 처음 선택된 탭(비제어). |
+| `onValueChange` | `(value: string) => void` |  | 선택이 바뀔 때. |
+| `activation` | `'auto' \| 'manual'` | `'auto'` | auto: 화살표로 옮기면 바로 선택 · manual: 화살표는 포커스만, Enter / Space로 선택. |
+| `className` | `string` |  | 바깥 요소에 전달. |
+
+### TabList
+
+Tabs.List로도 쓸 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `variant` | `'underline' \| 'pill'` | `'underline'` | underline: 선택 탭 아래 선 · pill: 회색 트랙 위 흰 칩. |
+| `size` | `'sm' \| 'md'` | `'md'` | 탭 크기. |
+| `fitted` | `boolean` |  | 탭이 줄 전체를 같은 폭으로 채워요. |
+| `aria-label` | `string` |  | 탭 목록의 접근성 이름. |
+| `className` | `string` |  | tablist 요소에 전달. |
+
+### Tab
+
+Tabs.Tab으로도 쓸 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `string` |  | 이 탭의 값. 같은 value의 TabPanel과 연결돼요. |
+| `children` (필수) | `ReactNode` |  | 탭 이름. |
+| `icon` | `ReactNode` |  | 이름 앞 아이콘. |
+| `count` | `number` |  | 이름 뒤 작은 숫자. |
+| `disabled` | `boolean` |  | 비활성. 키보드 이동에서도 건너뛰어요. |
+
+### TabPanel
+
+Tabs.Panel로도 쓸 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `string` |  | 연결할 Tab의 value. |
+| `children` (필수) | `ReactNode` |  | 패널 내용. |
+| `keepMounted` | `boolean` |  | 숨겨져도 DOM에 남겨 폼 상태·스크롤을 유지해요. |
+| `className` | `string` |  | tabpanel 요소에 전달. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본 (underline)
+
+선택된 탭 아래 선이 움직여요. value를 생략하면 defaultValue로 비제어 사용.
+
+```tsx
+import { Box, Stack, Text, Tab, TabList, TabPanel, Tabs } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Tabs defaultValue="overview">
+      <Box style={{ width: 480 }}>
+        <TabList aria-label="프로젝트">
+          <Tab value="overview">개요</Tab>
+          <Tab value="activity">활동</Tab>
+          <Tab value="settings">설정</Tab>
+        </TabList>
+        <TabPanel value="overview">
+          <Stack gap={1}>
+            <Text variant="label-md">Lumen 리디자인</Text>
+            <Text variant="body-sm" tone="secondary">
+              10월 31일 출시를 목표로 디자인 시스템과 랜딩 페이지를 새로 만들고 있어요.
+            </Text>
+          </Stack>
+        </TabPanel>
+        <TabPanel value="activity">
+          <Text variant="body-sm" tone="secondary">
+            이도현님이 2분 전에 ‘버튼 상태 정리’ 작업을 완료했어요.
+          </Text>
+        </TabPanel>
+        <TabPanel value="settings">
+          <Text variant="body-sm" tone="secondary">
+            프로젝트 이름, 공개 범위, 보관 설정을 바꿀 수 있어요.
+          </Text>
+        </TabPanel>
+      </Box>
+    </Tabs>
+  )
+}
+```
+
+### pill
+
+회색 트랙 위 흰 칩. 화면 안의 작은 보기 전환에 어울려요. size="sm"으로 더 작게.
+
+```tsx
+import { Box, Stack, Text, Tab, TabList, TabPanel, Tabs } from '@iamfiro/design'
+
+const RANGES = [
+  { value: 'day', label: '오늘', visitors: '1,284' },
+  { value: 'week', label: '이번 주', visitors: '8,903' },
+  { value: 'month', label: '이번 달', visitors: '32,410' },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={8} align="start">
+      <Tabs defaultValue="week">
+        <Box>
+          <TabList variant="pill" aria-label="기간">
+            {RANGES.map((r) => (
+              <Tab key={r.value} value={r.value}>
+                {r.label}
+              </Tab>
+            ))}
+          </TabList>
+          {RANGES.map((r) => (
+            <TabPanel key={r.value} value={r.value}>
+              <Stack gap={1}>
+                <Text variant="caption" tone="tertiary">
+                  {r.label} 방문자
+                </Text>
+                <Text variant="number-lg">{r.visitors}</Text>
+              </Stack>
+            </TabPanel>
+          ))}
+        </Box>
+      </Tabs>
+      <Tabs defaultValue="code">
+        <TabList variant="pill" size="sm" aria-label="보기">
+          <Tab value="preview">미리 보기</Tab>
+          <Tab value="code">코드</Tab>
+        </TabList>
+      </Tabs>
+    </Stack>
+  )
+}
+```
+
+### 아이콘과 개수
+
+icon과 count로 탭 옆에 아이콘·숫자를 붙여요. disabled 탭은 키보드 이동에서도 건너뛰어요.
+
+```tsx
+import { Archive, CircleDot, GitPullRequest, Inbox } from 'lucide-react'
+import { Box, Text, Tab, TabList, TabPanel, Tabs } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Tabs defaultValue="inbox">
+      <Box style={{ width: 520 }}>
+        <TabList aria-label="받은 항목">
+          <Tab value="inbox" icon={<Inbox />} count={12}>
+            받은 편지함
+          </Tab>
+          <Tab value="issues" icon={<CircleDot />} count={4}>
+            이슈
+          </Tab>
+          <Tab value="reviews" icon={<GitPullRequest />} count={2}>
+            리뷰 요청
+          </Tab>
+          <Tab value="archive" icon={<Archive />} disabled>
+            보관함
+          </Tab>
+        </TabList>
+        <TabPanel value="inbox">
+          <Text variant="body-sm" tone="secondary">
+            읽지 않은 알림 12개가 있어요.
+          </Text>
+        </TabPanel>
+        <TabPanel value="issues">
+          <Text variant="body-sm" tone="secondary">
+            나에게 배정된 열린 이슈 4개.
+          </Text>
+        </TabPanel>
+        <TabPanel value="reviews">
+          <Text variant="body-sm" tone="secondary">
+            김민지님과 박서연님이 리뷰를 요청했어요.
+          </Text>
+        </TabPanel>
+      </Box>
+    </Tabs>
+  )
+}
+```
+
+### 꽉 채우기
+
+fitted를 주면 탭이 줄 전체를 같은 폭으로 나눠 가져요.
+
+```tsx
+import { Stack, Tab, TabList, Tabs } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={6} style={{ width: 400 }}>
+      <Tabs defaultValue="login">
+        <TabList fitted aria-label="계정">
+          <Tab value="login">로그인</Tab>
+          <Tab value="signup">회원가입</Tab>
+        </TabList>
+      </Tabs>
+      <Tabs defaultValue="monthly">
+        <TabList variant="pill" fitted aria-label="결제 주기">
+          <Tab value="monthly">월간</Tab>
+          <Tab value="yearly">연간</Tab>
+          <Tab value="custom">맞춤</Tab>
+        </TabList>
+      </Tabs>
+    </Stack>
+  )
+}
+```
+
+### 수동 활성화
+
+activation="manual"이면 화살표는 포커스만 옮기고 Enter / Space로 선택해요. 패널을 그리는 비용이 클 때. 제어(value / onValueChange) 예시이기도 해요.
+
+```tsx
+import { useState } from 'react'
+import { Box, Kbd, Stack, Text, Tab, TabList, TabPanel, Tabs } from '@iamfiro/design'
+
+const REPORTS = [
+  { value: 'sales', label: '매출', summary: '10월 매출은 지난달보다 12% 늘었어요.' },
+  { value: 'users', label: '사용자', summary: '주간 활성 사용자는 8,903명이에요.' },
+  { value: 'retention', label: '리텐션', summary: '4주 리텐션은 41%예요.' },
+]
+
+export default function Example() {
+  const [report, setReport] = useState('sales')
+  return (
+    <Tabs value={report} onValueChange={setReport} activation="manual">
+      <Stack gap={5} style={{ width: 460 }}>
+        <Box>
+          <TabList aria-label="리포트">
+            {REPORTS.map((r) => (
+              <Tab key={r.value} value={r.value}>
+                {r.label}
+              </Tab>
+            ))}
+          </TabList>
+          {REPORTS.map((r) => (
+            <TabPanel key={r.value} value={r.value}>
+              <Text variant="body-sm">{r.summary}</Text>
+            </TabPanel>
+          ))}
+        </Box>
+        <Text variant="caption" tone="tertiary">
+          <Kbd>←</Kbd> <Kbd>→</Kbd>로 포커스를 옮기고 <Kbd>Enter</Kbd>로 열어요.
+        </Text>
+      </Stack>
+    </Tabs>
+  )
+}
+```
+
+### 숨겨도 상태 유지
+
+keepMounted 패널은 숨겨져도 DOM에 남아서, 탭을 오가도 입력한 내용이 지워지지 않아요.
+
+```tsx
+import { Box, Field, Input, Stack, Textarea, Tab, TabList, TabPanel, Tabs } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Tabs defaultValue="basic">
+      <Box style={{ width: 440 }}>
+        <TabList aria-label="새 일정">
+          <Tab value="basic">기본 정보</Tab>
+          <Tab value="detail">상세 설명</Tab>
+        </TabList>
+        <TabPanel value="basic" keepMounted>
+          <Stack gap={4}>
+            <Field label="일정 이름" htmlFor="event-name">
+              <Input id="event-name" placeholder="예: 디자인 리뷰" />
+            </Field>
+            <Field label="날짜" htmlFor="event-date">
+              <Input id="event-date" placeholder="10월 25일" />
+            </Field>
+          </Stack>
+        </TabPanel>
+        <TabPanel value="detail" keepMounted>
+          <Field label="설명" htmlFor="event-desc">
+            <Textarea id="event-desc" rows={4} placeholder="탭을 바꿔도 입력한 내용이 남아 있어요." />
+          </Field>
+        </TabPanel>
+      </Box>
+    </Tabs>
+  )
+}
+```

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