@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/toast/AGENTS.md

@@ -0,0 +1,266 @@
+# Toast
+
+> 알림 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+잠깐 떠올랐다 사라지는 알림. 앱 최상단에 <Toaster />를 한 번만 두고, 어디서든 toast()를 부르면 돼요. 새 토스트가 앞을 덮고 이전 것은 뒤로 살짝 겹쳐 쌓이며, 마우스를 올리면 펼쳐지고 자동 닫힘 시간이 멈춰요. 탭이 안 보이는 동안에도 타이머가 멈춰요.
+
+```tsx
+import { Toaster, toast } from '@iamfiro/design'
+
+// 앱 최상단에 한 번
+<Toaster />
+```
+
+## 디자인 규칙
+
+- 겹친 카드 묶음(`Toaster`, `NoticeStack`)은 같은 방식: 뒤 카드는 앞 카드 높이로 맞춰 가장자리만 보이고, hover(의도 지연·유예)·focus로 펼치며, 닫힌 카드는 제자리에서 등장 역방향으로 나가고 나머지가 그 자리로 이동.
+- 되돌릴 수 있는 작업(삭제·보관·이동): 확인 모달 대신 **즉시 실행 + "실행 취소" 토스트**. → `toast.undo()`
+- 글 속 변경 내용(추적된 변경)은 `InlineDiff`: 삭제 = 빨간 취소선 + `--danger-soft`, 추가 = 초록 + `--success-soft`, 진짜 `<del>` · `<ins>` + 화면 읽기 "삭제" · "추가". 검토(수락 · 거절)는 `reviewable`, 툴바(남은 개수 `CountBadge variant="soft" tone="success"`, 이전 · 다음 `Button iconOnly`, 모두 거절 · 모두 수락)는 `useDiffReview` 상태를 함께 써서 조립한다. 검토 카드는 `CardFrame header`(회색 판 위 아이콘 + 문서 이름) 안에 `Card raised` — 회색 Box를 카드 안 제목줄로 넣으면 입력창처럼 보인다. 본문 줄 간격은 넉넉하게(위아래 줄의 색 배경이 닿지 않게). 모두 수락 · 거절은 확인 대신 `toast.undo`. 두 문자열 비교는 `diffWords`, 결과 글은 `applyDiffDecisions`.
+
+## API
+
+### toast
+
+모든 함수는 토스트 id(string)를 돌려줘요. promise는 넘긴 promise를 그대로 돌려줘요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `toast(title, options?)` | `(ReactNode, ToastOptions) => string` |  | 기본 토스트. |
+| `toast.success / error / warning / info` | `(title, options?) => string` |  | 아이콘이 붙은 상태별 토스트. |
+| `toast.loading` | `(title, options?) => string` |  | 스피너가 도는 토스트. 자동으로 닫히지 않아요. |
+| `toast.update` | `(id, patch) => void` |  | type · title · description · action 등을 바꿔요. 타이머도 다시 시작해요. |
+| `toast.dismiss` | `(id?) => void` |  | 닫기 애니메이션 후 제거. id를 생략하면 모두 닫아요. |
+| `toast.promise` | `(promise, { loading, success, error }, options?) => Promise<T>` |  | 로딩 → 성공 / 오류로 바뀌는 토스트. 각 상태는 문구, { title, description }, 또는 결과를 받는 함수. |
+| `toast.undo` | `(title, { onUndo, onCommit?, undoLabel?, ...options }) => string` |  | '실행 취소' 버튼이 달린 토스트. 기본 6초 동안 보이고, 취소 없이 닫히면 onCommit을 불러요. |
+
+### ToastOptions
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `description` | `ReactNode` |  | 제목 아래 설명. |
+| `type` | `'default' \| 'success' \| 'error' \| 'warning' \| 'info' \| 'loading'` | `'default'` | toast()에서 종류를 직접 지정할 때. |
+| `action` | `{ label: ReactNode; onClick: () => void }` |  | 오른쪽 버튼. 누르면 onClick 후 닫혀요. |
+| `duration` | `number` | `4000` | 자동 닫힘까지 ms. Infinity면 계속 남아요. |
+| `id` | `string` |  | 같은 id가 있으면 새로 쌓지 않고 그 토스트를 바꿔요. |
+| `icon` | `ReactNode` |  | 종류별 아이콘 대신 쓸 아이콘. |
+| `closable` | `boolean` | `true` | false면 × 버튼을 숨겨요. |
+| `onDismiss` | `() => void` |  | 어떤 이유로든 닫힐 때 한 번 불려요. |
+
+### Toaster
+
+앱에 한 번만 둬요. document.body에 포털로 그려요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `position` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-right'` | 화면 위치. |
+| `visibleToasts` | `number` | `3` | 스택에 보이는 최대 개수. 더 오래된 것은 뒤로 사라져요. |
+| `duration` | `number` | `4000` | 기본 자동 닫힘 시간(ms). |
+| `gap` | `number` | `10` | 펼쳤을 때 토스트 사이 간격(px). |
+| `expand` | `boolean` |  | 마우스를 올리지 않아도 항상 펼쳐 둬요. |
+| `className` | `string` |  | 루트에 붙일 클래스. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 종류
+
+toast()는 기본, toast.success / error / warning / info / loading은 아이콘이 붙어요. loading은 직접 닫거나 바꾸기 전까지 남아 있어요. toast.dismiss()는 모두 닫아요.
+
+```tsx
+import { Button, toast } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', justifyContent: 'center', gap: 8 }}>
+      <Button onClick={() => toast('변경사항을 저장했어요')}>기본</Button>
+      <Button onClick={() => toast.success('결제가 완료됐어요', { description: '영수증을 이메일로 보냈어요.' })}>성공</Button>
+      <Button onClick={() => toast.error('저장하지 못했어요', { description: '네트워크 연결을 확인해 주세요.' })}>오류</Button>
+      <Button onClick={() => toast.warning('저장 공간이 거의 찼어요', { description: '10GB 중 9.2GB 사용 중' })}>경고</Button>
+      <Button onClick={() => toast.info('새 버전이 나왔어요', { description: '새로고침하면 적용돼요.' })}>정보</Button>
+      <Button onClick={() => toast.loading('동기화 중…', { description: '닫기 전까지 계속 보여요.' })}>로딩</Button>
+      <Button variant="ghost" onClick={() => toast.dismiss()}>
+        모두 닫기
+      </Button>
+    </div>
+  )
+}
+```
+
+### 실행 취소
+
+되돌릴 수 있는 작업은 확인 창 대신 바로 실행하고 toast.undo()로 "실행 취소"를 보여 줘요. 실제 영구 처리는 토스트가 취소 없이 닫힐 때 onCommit에서 해요. ⌘/Ctrl+Z로도 취소돼요.
+
+```tsx
+import { useState } from 'react'
+import { FileText, RotateCcw, Trash2 } from 'lucide-react'
+import { Button, Text, Card, CardHeader, toast } from '@iamfiro/design'
+
+const FILES = [
+  { id: 'f1', name: '3분기 이사회 보고서.pdf', meta: '4.2MB · 김민지' },
+  { id: 'f2', name: '브랜드 가이드 v3.fig', meta: '18MB · 박서연' },
+  { id: 'f3', name: '10월 회의록.docx', meta: '120KB · 이도현' },
+]
+
+export default function Example() {
+  // 화면에서 바로 지운 파일(되돌릴 수 있음)과 실제로 영구 삭제된 파일을 따로 들고 있어요.
+  const [hidden, setHidden] = useState<string[]>([])
+  const [committed, setCommitted] = useState<string[]>([])
+
+  const remove = (file: (typeof FILES)[number]) => {
+    setHidden((ids) => [...ids, file.id])
+    toast.undo(`‘${file.name}’ 파일을 삭제했어요`, {
+      onUndo: () => setHidden((ids) => ids.filter((id) => id !== file.id)),
+      onCommit: () => setCommitted((ids) => [...ids, file.id]),
+    })
+  }
+
+  const reset = () => {
+    setHidden([])
+    setCommitted([])
+  }
+
+  const files = FILES.filter((f) => !hidden.includes(f.id))
+
+  return (
+    <div style={{ display: 'grid', gap: 8, width: 380 }}>
+      {files.map((file) => (
+        <Card key={file.id} padding="sm">
+          <CardHeader
+            icon={<FileText />}
+            title={file.name}
+            description={file.meta}
+            actions={<Button iconOnly variant="ghost" size="sm" icon={<Trash2 />} aria-label={`${file.name} 삭제`} onClick={() => remove(file)} />}
+          />
+        </Card>
+      ))}
+      <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginTop: 4 }}>
+        <Text variant="body-sm" tone="tertiary" numeric>
+          영구 삭제됨 {committed.length}개
+        </Text>
+        <Button variant="ghost" size="sm" icon={<RotateCcw />} onClick={reset}>
+          처음으로
+        </Button>
+      </div>
+    </div>
+  )
+}
+```
+
+### 상태 바꾸기
+
+toast.loading()이 돌려준 id로 toast.update()를 부르면 같은 토스트가 새 상태로 바뀌어요. 아이콘이 바뀌고 글이 한 줄씩 다시 올라와요.
+
+```tsx
+import { Upload } from 'lucide-react'
+import { Button, toast } from '@iamfiro/design'
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+const FILE = '3분기 이사회 보고서.pdf · 4.2MB'
+
+async function upload() {
+  const id = toast.loading('보고서 업로드 중…', { description: FILE })
+  await wait(1600)
+  toast.update(id, { type: 'warning', title: '연결이 느려요', description: '조금만 기다려 주세요 · 62%' })
+  await wait(1600)
+  toast.update(id, { type: 'loading', title: '마무리하는 중…', description: FILE })
+  await wait(1200)
+  toast.update(id, {
+    type: 'success',
+    title: '업로드 완료',
+    description: '팀원 4명에게 공유했어요.',
+    action: { label: '열기', onClick: () => toast.info('보고서를 열었어요') },
+  })
+}
+
+export default function Example() {
+  return (
+    <Button variant="primary" icon={<Upload />} onClick={upload}>
+      보고서 업로드
+    </Button>
+  )
+}
+```
+
+### promise
+
+toast.promise()는 로딩 토스트를 띄우고 promise 결과에 따라 성공·오류로 바꿔요. 각 문구는 결과값이나 오류를 받는 함수로 쓸 수 있어요.
+
+```tsx
+import { Button, toast } from '@iamfiro/design'
+
+const sendInvites = (ok: boolean) =>
+  new Promise<number>((resolve, reject) => setTimeout(() => (ok ? resolve(3) : reject(new Error('권한이 없어요'))), 1800))
+
+export default function Example() {
+  const invite = (ok: boolean) =>
+    toast
+      .promise(sendInvites(ok), {
+        loading: { title: '초대 메일 보내는 중…', description: 'design@lumen.app 외 2명' },
+        success: (count) => ({ title: `${count}명에게 초대를 보냈어요`, description: '수락하면 알려 드릴게요.' }),
+        error: (error) => ({ title: '초대를 보내지 못했어요', description: (error as Error).message }),
+      })
+      .catch(() => {})
+
+  return (
+    <div style={{ display: 'flex', gap: 8 }}>
+      <Button variant="primary" onClick={() => invite(true)}>
+        초대 보내기
+      </Button>
+      <Button onClick={() => invite(false)}>실패하는 경우</Button>
+    </div>
+  )
+}
+```
+
+### 옵션
+
+action으로 버튼을 달고(누르면 닫혀요), duration: Infinity와 closable: false로 계속 띄워 둘 수 있어요. icon으로 아이콘을 바꾸고, 같은 id로 다시 부르면 새로 쌓이지 않고 그 자리에서 바뀌어요.
+
+```tsx
+import { useRef } from 'react'
+import { PartyPopper, WifiOff } from 'lucide-react'
+import { Button, toast } from '@iamfiro/design'
+
+export default function Example() {
+  const unread = useRef(0)
+
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', justifyContent: 'center', gap: 8 }}>
+      <Button
+        onClick={() =>
+          toast.error('저장하지 못했어요', {
+            description: '네트워크 연결을 확인해 주세요.',
+            action: { label: '다시 시도', onClick: () => toast.success('저장했어요') },
+          })
+        }
+      >
+        액션 버튼
+      </Button>
+      <Button
+        onClick={() =>
+          toast('오프라인 상태예요', {
+            id: 'offline',
+            icon: <WifiOff />,
+            description: '연결되면 자동으로 동기화해요.',
+            duration: Infinity,
+            closable: false,
+            action: { label: '다시 연결', onClick: () => toast.success('다시 연결했어요') },
+          })
+        }
+      >
+        닫을 때까지 유지
+      </Button>
+      <Button onClick={() => toast('10월 목표를 달성했어요', { icon: <PartyPopper />, duration: 8000 })}>사용자 아이콘 · 8초</Button>
+      <Button
+        onClick={() => {
+          unread.current += 1
+          toast.info(`새 댓글 ${unread.current}개`, { id: 'comments', description: '김민지님 외 여러 명이 남겼어요.' })
+        }}
+      >
+        같은 id로 교체
+      </Button>
+    </div>
+  )
+}
+```

package/agents/toggle-group/AGENTS.md

@@ -0,0 +1,216 @@
+# ToggleGroup
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+눌러서 켜고 끄는 버튼 묶음. type='single'은 라디오처럼 하나만, 'multiple'은 각각 따로 켜져요. 단일 선택은 흰 배경이 선택된 항목으로 미끄러지고, 화살표 키로 이동하면 선택도 함께 옮겨가요.
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from '@iamfiro/design'
+```
+
+## API
+
+### ToggleGroup
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `type` (필수) | `'single' \| 'multiple'` |  | 하나만 / 여러 개. |
+| `value` | `V \| null  ·  V[] (multiple)` |  | 선택된 값(제어). V는 string \| number. |
+| `defaultValue` | `V \| null  ·  V[] (multiple)` |  | 처음 선택값(비제어). |
+| `onValueChange` | `(value: V \| null) => void  ·  (value: V[]) => void` |  | 값이 바뀔 때. |
+| `required` | `boolean` |  | type='single' 전용. 선택된 항목을 다시 눌러도 해제되지 않아요. |
+| `variant` | `'soft' \| 'ghost'` | `'soft'` | soft: 회색 트랙 + 흰 선택 · ghost: 글자만, 선택 시 회색 채움. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기. |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 배치 방향. 화살표 키 방향도 따라 바뀌어요. |
+| `disabled` | `boolean` |  | 모든 항목 비활성. |
+| `aria-label` | `string` |  | 그룹 이름(스크린 리더). |
+
+### ToggleGroupItem
+
+나머지 button 속성(aria-label, onClick 등)도 그대로 받아요. ToggleGroup.Item으로도 쓸 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `string \| number` |  | 이 항목의 값. |
+| `icon` | `ReactNode` |  | 앞 아이콘. children이 없으면 아이콘 전용 정사각형 버튼. |
+| `children` | `ReactNode` |  | 버튼 글자. |
+| `disabled` | `boolean` |  | 이 항목만 비활성. 키보드 이동에서도 건너뛰어요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 하나만 선택
+
+required를 주면 선택된 항목을 다시 눌러도 꺼지지 않아요. Tab은 선택된 항목에 멈추고, ←→ / Home / End로 이동해요.
+
+```tsx
+import { useState } from 'react'
+import { AlignCenter, AlignLeft, AlignRight } from 'lucide-react'
+import { ToggleGroup, ToggleGroupItem } from '@iamfiro/design'
+
+export default function Example() {
+  const [align, setAlign] = useState<string | null>('left')
+  return (
+    <ToggleGroup type="single" required value={align} onValueChange={setAlign} aria-label="문단 정렬">
+      <ToggleGroupItem value="left" icon={<AlignLeft />}>
+        왼쪽
+      </ToggleGroupItem>
+      <ToggleGroupItem value="center" icon={<AlignCenter />}>
+        가운데
+      </ToggleGroupItem>
+      <ToggleGroupItem value="right" icon={<AlignRight />}>
+        오른쪽
+      </ToggleGroupItem>
+    </ToggleGroup>
+  )
+}
+```
+
+### 여러 개 선택 · 아이콘만
+
+글자 없이 icon만 주면 정사각형 버튼이 돼요. 이때는 aria-label을 꼭 넣어 주세요.
+
+```tsx
+import { useState } from 'react'
+import { Bold, Italic, Strikethrough, Underline } from 'lucide-react'
+import { ToggleGroup, ToggleGroupItem } from '@iamfiro/design'
+
+export default function Example() {
+  const [marks, setMarks] = useState<string[]>(['bold'])
+  return (
+    <ToggleGroup type="multiple" value={marks} onValueChange={setMarks} aria-label="텍스트 서식">
+      <ToggleGroupItem value="bold" icon={<Bold />} aria-label="굵게" />
+      <ToggleGroupItem value="italic" icon={<Italic />} aria-label="기울임" />
+      <ToggleGroupItem value="underline" icon={<Underline />} aria-label="밑줄" />
+      <ToggleGroupItem value="strike" icon={<Strikethrough />} aria-label="취소선" />
+    </ToggleGroup>
+  )
+}
+```
+
+### ghost
+
+variant='ghost'는 트랙 없이 글자만 두고, 선택된 항목에만 회색 채움이 생겨요. 개별 항목은 disabled로 막을 수 있어요.
+
+```tsx
+import { useState } from 'react'
+import { ToggleGroup, ToggleGroupItem } from '@iamfiro/design'
+
+export default function Example() {
+  const [period, setPeriod] = useState<string | null>('week')
+  return (
+    <div style={{ display: 'grid', gap: 16, justifyItems: 'start' }}>
+      <ToggleGroup type="single" variant="ghost" required value={period} onValueChange={setPeriod} aria-label="기간">
+        <ToggleGroupItem value="day">일</ToggleGroupItem>
+        <ToggleGroupItem value="week">주</ToggleGroupItem>
+        <ToggleGroupItem value="month">월</ToggleGroupItem>
+        <ToggleGroupItem value="year">년</ToggleGroupItem>
+        <ToggleGroupItem value="custom" disabled>
+          직접 설정
+        </ToggleGroupItem>
+      </ToggleGroup>
+      <ToggleGroup type="multiple" variant="ghost" size="sm" defaultValue={['mine']} aria-label="보기 옵션">
+        <ToggleGroupItem value="mine">내 작업</ToggleGroupItem>
+        <ToggleGroupItem value="archived">보관됨 포함</ToggleGroupItem>
+        <ToggleGroupItem value="subtasks">하위 작업</ToggleGroupItem>
+      </ToggleGroup>
+    </div>
+  )
+}
+```
+
+### 세로 배치
+
+orientation='vertical'이면 ↑↓로 이동해요.
+
+```tsx
+import { CalendarDays, GanttChart, KanbanSquare, List } from 'lucide-react'
+import { ToggleGroup, ToggleGroupItem } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <ToggleGroup type="single" orientation="vertical" required defaultValue="board" aria-label="보기 방식">
+      <ToggleGroupItem value="list" icon={<List />}>
+        목록
+      </ToggleGroupItem>
+      <ToggleGroupItem value="board" icon={<KanbanSquare />}>
+        보드
+      </ToggleGroupItem>
+      <ToggleGroupItem value="calendar" icon={<CalendarDays />}>
+        캘린더
+      </ToggleGroupItem>
+      <ToggleGroupItem value="timeline" icon={<GanttChart />}>
+        타임라인
+      </ToggleGroupItem>
+    </ToggleGroup>
+  )
+}
+```
+
+### 테마 전환 (세로 · 아이콘만)
+
+새 컴포넌트 없이 soft · vertical · 아이콘만으로 만든 테마 전환. 선택된 해 · 달 아이콘 밑으로 흰 바탕이 미끄러져요. 아이콘만 쓸 땐 항목마다 aria-label을 넣어요.
+
+```tsx
+import { useState } from 'react'
+import { Monitor, Moon, Sun } from 'lucide-react'
+import { Inline, Text, ToggleGroup, ToggleGroupItem } from '@iamfiro/design'
+
+type Theme = 'light' | 'dark' | 'system'
+
+const LABEL: Record<Theme, string> = { light: '밝게', dark: '어둡게', system: '시스템 설정' }
+
+export default function Example() {
+  const [theme, setTheme] = useState<Theme>('light')
+  return (
+    <Inline gap={5} align="center">
+      <ToggleGroup
+        type="single"
+        required
+        orientation="vertical"
+        size="sm"
+        value={theme}
+        onValueChange={(v) => v && setTheme(v)}
+        aria-label="테마"
+      >
+        <ToggleGroupItem value="light" icon={<Sun />} aria-label={LABEL.light} />
+        <ToggleGroupItem value="dark" icon={<Moon />} aria-label={LABEL.dark} />
+        <ToggleGroupItem value="system" icon={<Monitor />} aria-label={LABEL.system} />
+      </ToggleGroup>
+      <Text variant="body-sm" tone="secondary">
+        지금: {LABEL[theme]}
+      </Text>
+    </Inline>
+  )
+}
+```
+
+### 크기와 비활성
+
+size sm / md / lg. 그룹에 disabled를 주면 모든 항목이 비활성돼요.
+
+```tsx
+import { ToggleGroup, ToggleGroupItem, type ToggleGroupSize } from '@iamfiro/design'
+
+const SIZES: ToggleGroupSize[] = ['sm', 'md', 'lg']
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 16, justifyItems: 'start' }}>
+      {SIZES.map((size) => (
+        <ToggleGroup key={size} type="single" size={size} required defaultValue="all" aria-label={`보기 범위 (${size})`}>
+          <ToggleGroupItem value="all">전체</ToggleGroupItem>
+          <ToggleGroupItem value="active">진행 중</ToggleGroupItem>
+          <ToggleGroupItem value="done">완료</ToggleGroupItem>
+        </ToggleGroup>
+      ))}
+      <ToggleGroup type="single" disabled defaultValue="all" aria-label="보기 범위 (비활성)">
+        <ToggleGroupItem value="all">전체</ToggleGroupItem>
+        <ToggleGroupItem value="active">진행 중</ToggleGroupItem>
+        <ToggleGroupItem value="done">완료</ToggleGroupItem>
+      </ToggleGroup>
+    </div>
+  )
+}
+```