@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/dropdown-menu/AGENTS.md

@@ -0,0 +1,322 @@
+# DropdownMenu
+
+> 메뉴 & 오버레이 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+버튼에서 펼쳐지는 동작 메뉴. 마우스를 누르는 순간 열리고, 누른 채 항목으로 끌어 놓으면 바로 실행돼요(press-drag-release). 그냥 클릭하면 열린 채로 남아요. 키보드는 ↑↓ · Home/End · 글자 입력으로 이동, Enter/Space로 실행, Esc로 닫고 트리거로 포커스가 돌아가요. 하위 메뉴는 잠깐 머물러야 열리고, 하위 패널 쪽으로 대각선으로 움직이는 동안은 지나치는 행이 강조를 빼앗지 않아요.
+
+```tsx
+import { DropdownMenu, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuSub } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 행 앞 타일: 사람은 `Avatar`, 도구·사이트·문서는 `IconTile`(회색 채움 + 아이콘/글자). 선택된 것을 보여 주고 메뉴로 바꾸는 버튼(워크스페이스·계정 전환, 드롭다운 제목)은 `SelectorButton`을 `DropdownMenu` trigger에.
+- 팝오버는 `ListboxPopover` / `Popover` / `DropdownMenu`(portal + fixed, 공간 부족 시 위로, `useFloating`의 `align`). 부모 `overflow: hidden`에 잘리면 안 된다.
+
+## API
+
+### DropdownMenu
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `trigger` (필수) | `ReactNode` |  | 여는 버튼. |
+| `children` (필수) | `ReactNode` |  | 항목, 라벨, 구분선, 하위 메뉴. |
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | 트리거 기준 가로 정렬. 오른쪽 끝의 "⋯" 버튼은 end. |
+| `minWidth` | `number` | `200` | 패널 최소 폭(px). |
+| `open / onOpenChange` | `boolean / (open) => void` |  | 열림 상태를 밖에서 제어할 때. |
+| `defaultOpen` | `boolean` | `false` | 처음 열림 상태(비제어). |
+| `aria-label` | `string` |  | 메뉴(role="menu")의 접근성 이름. |
+
+### DropdownMenuItem
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | 항목 이름. |
+| `onSelect` | `() => void` |  | 클릭 · Enter/Space · 끌어 놓기로 실행될 때. 메뉴가 먼저 닫혀요. |
+| `icon` | `ReactNode` |  | 앞 아이콘. |
+| `description` | `ReactNode` |  | 이름 아래 회색 설명. |
+| `shortcut` | `string[]` |  | 단축키 힌트. 예: ['mod', 'D']. 표시만 하고 단축키를 등록하지는 않아요. |
+| `danger` | `boolean` |  | 빨간 글자(파괴적 동작). |
+| `disabled` | `boolean` |  | 비활성. 키보드 이동에서 건너뛰어요. |
+| `keepOpen` | `boolean` |  | 실행 뒤에도 메뉴를 열어 둬요(반복 동작용). |
+
+### DropdownMenuCheckboxItem
+
+icon · description · shortcut · disabled도 받아요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `checked` (필수) | `boolean` |  | 켜짐 여부. |
+| `onCheckedChange` (필수) | `(checked: boolean) => void` |  | 토글될 때. |
+| `closeOnSelect` | `boolean` | `false` | 고르면 메뉴를 닫아요. |
+
+### DropdownMenuRadioGroup
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `string` |  | 선택된 값. |
+| `onValueChange` (필수) | `(value: string) => void` |  | 값이 바뀔 때. 메뉴는 열린 채로 남아요. |
+| `label` | `ReactNode` |  | 그룹 제목(문자열이면 aria-label). |
+
+### DropdownMenuRadioItem
+
+icon · description · shortcut · disabled도 받아요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `string` |  | 이 항목의 값. |
+
+### DropdownMenuSub
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` (필수) | `ReactNode` |  | 하위 메뉴를 여는 행의 이름. |
+| `children` (필수) | `ReactNode` |  | 하위 패널의 항목. |
+| `icon` | `ReactNode` |  | 앞 아이콘. |
+| `disabled` | `boolean` |  | 비활성. |
+
+### DropdownMenuLabel
+
+그룹 제목(선택 불가). 묶음 사이 구분선은 props 없는 <DropdownMenuSeparator />.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | 제목. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 동작 메뉴
+
+아이콘과 단축키 힌트(shortcut={['mod', 'D']}, OS에 맞게 ⌘/Ctrl로 표시)를 붙여요. 되돌릴 수 있는 "보관"은 바로 실행하고 toast.undo()로 실행 취소를 주고, 되돌릴 수 없는 "영구 삭제"만 AlertDialog로 확인해요. 메뉴 안에서 연 대화상자는 메뉴가 닫혀도 남도록 메뉴 바깥에 두고 open으로 제어해요.
+
+```tsx
+import { useState } from 'react'
+import { Archive, Copy, FileText, Link2, MoreHorizontal, Pencil, Trash2 } from 'lucide-react'
+import { Box, Button, AlertDialog, Card, CardHeader, DropdownMenu, DropdownMenuItem, DropdownMenuSeparator, toast } from '@iamfiro/design'
+
+export default function Example() {
+  const [archived, setArchived] = useState(false)
+  const [confirmDelete, setConfirmDelete] = useState(false)
+
+  const archive = () => {
+    setArchived(true)
+    toast.undo('‘3분기 이사회 보고서’를 보관했어요', {
+      onUndo: () => setArchived(false),
+    })
+  }
+
+  return (
+    <Box style={{ width: 380 }}>
+      <Card padding="sm">
+        <CardHeader
+          icon={<FileText />}
+          title="3분기 이사회 보고서"
+          description={archived ? '보관됨 · 김민지' : '10월 25일 수정 · 김민지'}
+          actions={
+            <DropdownMenu
+              align="end"
+              aria-label="문서 메뉴"
+              trigger={<Button iconOnly variant="ghost" size="sm" icon={<MoreHorizontal />} aria-label="더 보기" />}
+            >
+              <DropdownMenuItem icon={<Pencil />} shortcut={['F2']} onSelect={() => toast('이름 바꾸기를 열었어요')}>
+                이름 바꾸기
+              </DropdownMenuItem>
+              <DropdownMenuItem icon={<Copy />} shortcut={['mod', 'D']} onSelect={() => toast.success('사본을 만들었어요')}>
+                복제
+              </DropdownMenuItem>
+              <DropdownMenuItem icon={<Link2 />} shortcut={['mod', 'L']} onSelect={() => toast.success('링크를 복사했어요')}>
+                링크 복사
+              </DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem icon={<Archive />} onSelect={archive} disabled={archived}>
+                보관
+              </DropdownMenuItem>
+              <DropdownMenuItem icon={<Trash2 />} danger onSelect={() => setConfirmDelete(true)}>
+                영구 삭제
+              </DropdownMenuItem>
+            </DropdownMenu>
+          }
+        />
+      </Card>
+      <AlertDialog
+        open={confirmDelete}
+        onOpenChange={setConfirmDelete}
+        tone="danger"
+        title="문서를 영구 삭제할까요?"
+        description="‘3분기 이사회 보고서’와 댓글 18개가 함께 삭제돼요. 휴지통을 거치지 않아 되돌릴 수 없어요."
+        confirmLabel="삭제"
+        onConfirm={() => {
+          toast.success('문서를 삭제했어요')
+        }}
+      />
+    </Box>
+  )
+}
+```
+
+### 체크 항목
+
+DropdownMenuCheckboxItem은 기본적으로 고른 뒤에도 메뉴가 열려 있어 여러 개를 한 번에 켜고 끌 수 있어요. 바로 닫으려면 closeOnSelect.
+
+```tsx
+import { useState } from 'react'
+import { SlidersHorizontal } from 'lucide-react'
+import { Button, Stack, Text, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuLabel, DropdownMenuSeparator } from '@iamfiro/design'
+
+const COLUMNS = [
+  { id: 'assignee', label: '담당자' },
+  { id: 'due', label: '마감일' },
+  { id: 'priority', label: '우선순위' },
+  { id: 'tags', label: '태그' },
+]
+
+export default function Example() {
+  const [visible, setVisible] = useState<string[]>(['assignee', 'due'])
+  const [showDone, setShowDone] = useState(false)
+
+  const toggle = (id: string, on: boolean) => setVisible((ids) => (on ? [...ids, id] : ids.filter((x) => x !== id)))
+
+  return (
+    <Stack gap={3} align="start">
+      <DropdownMenu aria-label="보기 옵션" trigger={<Button icon={<SlidersHorizontal />}>보기</Button>}>
+        <DropdownMenuLabel>표시할 열</DropdownMenuLabel>
+        {COLUMNS.map((c) => (
+          <DropdownMenuCheckboxItem key={c.id} checked={visible.includes(c.id)} onCheckedChange={(on) => toggle(c.id, on)}>
+            {c.label}
+          </DropdownMenuCheckboxItem>
+        ))}
+        <DropdownMenuSeparator />
+        <DropdownMenuCheckboxItem checked={showDone} onCheckedChange={setShowDone} description="지난 30일 안에 끝난 작업">
+          완료된 작업 표시
+        </DropdownMenuCheckboxItem>
+      </DropdownMenu>
+      <Text variant="body-sm" tone="tertiary">
+        표시 중: {COLUMNS.filter((c) => visible.includes(c.id)).map((c) => c.label).join(', ') || '없음'}
+        {showDone && ' · 완료 포함'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 라디오 그룹
+
+하나만 고르는 옵션(정렬 기준, 순서). label을 주면 그룹 제목이 붙고 접근성 이름이 돼요.
+
+```tsx
+import { useState } from 'react'
+import { ArrowDownWideNarrow } from 'lucide-react'
+import { Button, DropdownMenu, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator } from '@iamfiro/design'
+
+const SORTS = [
+  { value: 'updated', label: '최근 수정순' },
+  { value: 'created', label: '만든 날짜순' },
+  { value: 'name', label: '이름순' },
+  { value: 'size', label: '크기순' },
+]
+
+export default function Example() {
+  const [sort, setSort] = useState('updated')
+  const [order, setOrder] = useState('desc')
+
+  const current = SORTS.find((s) => s.value === sort)?.label
+
+  return (
+    <DropdownMenu aria-label="정렬" trigger={<Button icon={<ArrowDownWideNarrow />}>{current}</Button>}>
+      <DropdownMenuRadioGroup label="정렬 기준" value={sort} onValueChange={setSort}>
+        {SORTS.map((s) => (
+          <DropdownMenuRadioItem key={s.value} value={s.value}>
+            {s.label}
+          </DropdownMenuRadioItem>
+        ))}
+      </DropdownMenuRadioGroup>
+      <DropdownMenuSeparator />
+      <DropdownMenuRadioGroup label="순서" value={order} onValueChange={setOrder}>
+        <DropdownMenuRadioItem value="desc">내림차순</DropdownMenuRadioItem>
+        <DropdownMenuRadioItem value="asc">오름차순</DropdownMenuRadioItem>
+      </DropdownMenuRadioGroup>
+    </DropdownMenu>
+  )
+}
+```
+
+### 하위 메뉴
+
+행에 200ms 머물면 열리고(→ · Enter도 가능, ←·Esc로 닫고 행으로 복귀), 벗어나도 300ms 유예가 있어요. 열린 하위 패널로 대각선으로 이동하는 동안에는 지나가는 "공유" 행이 강조를 가져가지 않아요 — 출발점과 하위 패널 가장자리로 만든 삼각형 안이면 "가는 중"으로 봐요.
+
+```tsx
+import { useState } from 'react'
+import { ExternalLink, Folder, FolderInput, Link2, Mail, MoreHorizontal, Share2 } from 'lucide-react'
+import { Button, Inline, Text, DropdownMenu, DropdownMenuItem, DropdownMenuSub, toast } from '@iamfiro/design'
+
+const FOLDERS = ['디자인', '마케팅', '회의록', '보관함']
+
+export default function Example() {
+  const [folder, setFolder] = useState('회의록')
+
+  const move = (to: string) => {
+    const from = folder
+    setFolder(to)
+    toast.undo(`‘${to}’ 폴더로 옮겼어요`, { onUndo: () => setFolder(from) })
+  }
+
+  return (
+    <Inline gap={3}>
+      <DropdownMenu aria-label="파일 메뉴" trigger={<Button iconOnly variant="ghost" icon={<MoreHorizontal />} aria-label="더 보기" />}>
+        <DropdownMenuItem icon={<ExternalLink />} onSelect={() => toast('새 탭에서 열었어요')}>
+          새 탭에서 열기
+        </DropdownMenuItem>
+        <DropdownMenuSub label="이동" icon={<FolderInput />}>
+          {FOLDERS.map((f) => (
+            <DropdownMenuItem key={f} icon={<Folder />} disabled={f === folder} description={f === folder ? '현재 폴더' : undefined} onSelect={() => move(f)}>
+              {f}
+            </DropdownMenuItem>
+          ))}
+        </DropdownMenuSub>
+        <DropdownMenuSub label="공유" icon={<Share2 />}>
+          <DropdownMenuItem icon={<Link2 />} onSelect={() => toast.success('링크를 복사했어요')}>
+            링크 복사
+          </DropdownMenuItem>
+          <DropdownMenuItem icon={<Mail />} onSelect={() => toast('메일 작성 창을 열었어요')}>
+            이메일로 보내기
+          </DropdownMenuItem>
+        </DropdownMenuSub>
+      </DropdownMenu>
+      <Text variant="body-sm" tone="secondary">
+        10월 회의록.docx · {folder}
+      </Text>
+    </Inline>
+  )
+}
+```
+
+### 비활성 항목
+
+비활성 항목은 키보드 이동에서 건너뛰고 눌러도 아무 일도 없어요. description으로 이유를 알려 주세요. 하위 메뉴도 disabled를 받을 수 있어요.
+
+```tsx
+import { ChevronDown, Download, FileSpreadsheet, Printer, Users } from 'lucide-react'
+import { Button, DropdownMenu, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuSub, toast } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <DropdownMenu aria-label="내보내기" trigger={<Button iconRight={<ChevronDown />}>내보내기</Button>}>
+      <DropdownMenuItem icon={<Download />} onSelect={() => toast.success('PDF로 내보냈어요')}>
+        PDF로 다운로드
+      </DropdownMenuItem>
+      <DropdownMenuItem icon={<FileSpreadsheet />} disabled description="표가 있는 문서에서만 쓸 수 있어요">
+        엑셀로 다운로드
+      </DropdownMenuItem>
+      <DropdownMenuItem icon={<Printer />} shortcut={['mod', 'P']} onSelect={() => toast('인쇄 미리보기를 준비하고 있어요')}>
+        인쇄
+      </DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <DropdownMenuSub label="팀에 공유" icon={<Users />} disabled>
+        <DropdownMenuItem>디자인 팀</DropdownMenuItem>
+      </DropdownMenuSub>
+    </DropdownMenu>
+  )
+}
+```

package/agents/dropzone/AGENTS.md

@@ -0,0 +1,116 @@
+# Dropzone
+
+> 파일 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+파일을 끌어 놓거나 눌러서 고르는 영역. 입력류라서 점선 윤곽을 가져요. 파일이 위에 오면 파랗게 바뀌고 종이가 부채처럼 펼쳐지며, accept에 맞지 않는 파일이 섞이면 영역이 흔들려요. Enter / Space로도 열려요. 목록과 진행률까지 필요하면 FileUpload를 쓰세요.
+
+```tsx
+import { Dropzone, matchesAccept } from '@iamfiro/design'
+```
+
+## API
+
+### Dropzone
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `onFiles` | `(accepted: File[], rejected: File[]) => void` |  | 끌어 놓거나 고른 파일. accept에 맞지 않으면 rejected로. |
+| `accept` | `string` |  | <input accept>와 같은 문법(.pdf, image/*). 끌어 놓은 파일에도 적용돼요. |
+| `multiple` | `boolean` | `true` | 여러 개 받기. false면 첫 파일만. |
+| `size` | `'sm' \| 'md'` | `'md'` | md: 그림 + 가운데 · sm: 한 줄. |
+| `title` | `ReactNode` | `여기에 파일을 끌어 놓거나 찾아보기` | 첫 줄. |
+| `description` | `ReactNode` |  | 회색 둘째 줄(형식, 용량). |
+| `invalid` | `boolean` |  | 빨간 윤곽 + 연한 빨강 배경. |
+| `disabled` | `boolean` |  | 받지 않음. |
+| `name` | `string` |  | 폼 전송용 숨은 input 이름. |
+| `aria-label` | `string` | `파일 올리기` | 접근성 이름. |
+
+### matchesAccept
+
+파일이 accept 문자열에 맞는지 확인하는 함수.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `file` (필수) | `File` |  | 확인할 파일. |
+| `accept` | `string` |  | 비어 있으면 모두 통과. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+onFiles(accepted, rejected)로 받아요. 이미지가 아닌 파일을 끌어 놓아 보세요.
+
+```tsx
+import { useState } from 'react'
+import { FileIcon, Stack, Text, Dropzone, List, ListItem, formatBytes } from '@iamfiro/design'
+
+export default function Example() {
+  const [files, setFiles] = useState<File[]>([])
+  const [rejected, setRejected] = useState(0)
+
+  return (
+    <Stack gap={3} style={{ width: 420 }}>
+      <Dropzone
+        accept="image/*"
+        description="PNG, JPG, WEBP 이미지만"
+        onFiles={(accepted, wrong) => {
+          setFiles((f) => [...f, ...accepted])
+          setRejected(wrong.length)
+        }}
+      />
+      {rejected > 0 && (
+        <Text variant="body-sm" tone="danger">
+          이미지가 아닌 파일 {rejected}개는 뺐어요.
+        </Text>
+      )}
+      {files.length > 0 && (
+        <List density="compact" aria-label="고른 이미지">
+          {files.map((f, i) => (
+            <ListItem key={i} leading={<FileIcon name={f.name} />} title={f.name} meta={formatBytes(f.size)} />
+          ))}
+        </List>
+      )}
+    </Stack>
+  )
+}
+```
+
+### 크기
+
+md는 그림과 함께 가운데 정렬, sm은 폼 안에 들어가는 한 줄.
+
+```tsx
+import { Stack, Dropzone } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4} style={{ width: 420 }}>
+      <Dropzone description="PDF, PNG, JPG 등 · 파일당 최대 25MB" />
+      <Dropzone size="sm" title="첨부 파일 추가" description="끌어 놓거나 눌러서 골라요" />
+    </Stack>
+  )
+}
+```
+
+### 오류와 비활성
+
+Field로 라벨과 안내를 붙여요. invalid는 연한 빨강, disabled는 회색 + 금지 커서.
+
+```tsx
+import { Field, Stack, Dropzone } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4} style={{ width: 420 }}>
+      <Field label="사업자등록증" hint="필수 서류예요. PDF로 올려 주세요." invalid>
+        <Dropzone size="sm" accept=".pdf" invalid title="PDF 파일을 끌어 놓거나 찾아보기" aria-label="사업자등록증 올리기" />
+      </Field>
+      <Field label="계약서" hint="검토가 끝나 더 올릴 수 없어요.">
+        <Dropzone size="sm" disabled title="파일 올리기가 잠겨 있어요" aria-label="계약서 올리기" />
+      </Field>
+    </Stack>
+  )
+}
+```

package/agents/elapsed/AGENTS.md

@@ -0,0 +1,160 @@
+# Elapsed
+
+> 진행 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+시작한 뒤 지난 시간을 "17:40" · "17분 40초"처럼 글자로 올려 세요. Countdown의 반대 방향이에요. startedAt을 주면 그 시각부터의 실제 시간을, 없으면 스톱워치처럼 initial부터 세요. running={false}면 그 자리에서 멈추고, 일이 끝나면 endedAt으로 최종 시간에 고정해요. 렌더 중엔 시계를 읽지 않고, 매 초 경계에 맞춰 다시 읽어 밀리지 않아요.
+
+```tsx
+import { Elapsed, formatElapsed, useElapsed } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 지난 시간("17:40", "17분 40초")은 `Elapsed` / `useElapsed`(`startedAt` · 스톱워치 · `running` 멈춤 · 끝나면 `endedAt`), 글자는 `formatElapsed`. 시작 시각은 클릭 핸들러 · effect에서만 잡는다.
+
+## API
+
+### Elapsed
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `startedAt` | `Date \| number \| string` |  | 시작 시각. 없으면 마운트(또는 initial)부터 세는 스톱워치. |
+| `running` | `boolean` | `true` | false면 그 자리에서 멈춰요. startedAt이 있으면 다시 켤 때 실제 시간으로 따라잡아요. |
+| `endedAt` | `Date \| number \| string` |  | 끝난 시각. startedAt과 함께면 최종 시간에 고정되고 더 세지 않아요. |
+| `initial` | `number` | `0` | startedAt 없을 때 시작 초. |
+| `format` | `(elapsed: number) => ReactNode` | `formatElapsed` | 지난 초를 글자로. 기본 "17:40" / "1:02:05". |
+| `className / style` | `string / CSSProperties` |  | span(role="timer")에 전달. |
+
+### useElapsed(startedAt?, options)
+
+반환값 { elapsed, running, reset() }. reset은 스톱워치(startedAt 없음)에서만 의미가 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `startedAt` | `Date \| number \| string` |  | 시작 시각. 없으면 스톱워치. |
+| `options.running` | `boolean` | `true` | 멈춤 / 이어 세기. |
+| `options.endedAt` | `Date \| number \| string` |  | 끝난 시각에 고정. |
+| `options.initial` | `number` | `0` | 스톱워치 시작 초. |
+
+### formatElapsed(seconds, style?)
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `style` | `'clock' \| 'text' \| 'short'` | `'clock'` | clock "17:40" · text "17분 40초" · short "17m 40s". text · short는 큰 단위 두 개까지만. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 머리글 · Badge
+
+시작 시각 옆 경과 시간, Badge 안의 글자. format으로 "1분 35초"(text) · "1h 2m"(short)를 골라요.
+
+```tsx
+import { Clock } from 'lucide-react'
+import { Badge, Elapsed, Inline, Stack, Text, formatElapsed } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4}>
+      <Inline gap={1} wrap={false}>
+        <Text as="span" tone="tertiary" style={{ display: 'inline-flex' }}>
+          <Clock size={14} aria-hidden />
+        </Text>
+        <Text variant="label-sm" tone="tertiary" numeric>
+          시작 오후 9:12 · <Elapsed initial={1060} />
+        </Text>
+      </Inline>
+      <Inline gap={2}>
+        <Badge tone="accent" spinner>
+          배포 중 · <Elapsed initial={95} format={(s) => formatElapsed(s, 'text')} />
+        </Badge>
+        <Badge>
+          <Elapsed initial={3725} format={(s) => formatElapsed(s, 'short')} />
+        </Badge>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 시작 · 끝 시각
+
+시작 시각(startedAt)은 클릭 핸들러에서 Date.now()로 잡아요. 끝내면 endedAt을 넘겨 걸린 시간에 고정돼요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Elapsed, Inline, Stack, StatusIcon, Text, formatElapsed } from '@iamfiro/design'
+
+export default function Example() {
+  // Real timestamps, taken in click handlers (never during render).
+  const [startedAt, setStartedAt] = useState<number>()
+  const [endedAt, setEndedAt] = useState<number>()
+  const status = startedAt === undefined ? 'pending' : endedAt === undefined ? 'active' : 'done'
+  return (
+    <Stack gap={4} style={{ width: 320 }}>
+      <Inline gap={3} justify="between" wrap={false}>
+        <Inline gap={2} wrap={false}>
+          <StatusIcon status={status} decorative />
+          <Text variant="label-md">월간 보고서 내보내기</Text>
+        </Inline>
+        <Text variant="label-sm" tone="tertiary">
+          {startedAt === undefined ? '아직 시작 전' : <Elapsed startedAt={startedAt} endedAt={endedAt} format={(s) => formatElapsed(s, 'text')} />}
+        </Text>
+      </Inline>
+      <Inline gap={2}>
+        <Button
+          size="sm"
+          variant="primary"
+          disabled={status === 'active'}
+          onClick={() => {
+            setStartedAt(Date.now())
+            setEndedAt(undefined)
+          }}
+        >
+          {status === 'done' ? '다시 시작' : '시작'}
+        </Button>
+        <Button size="sm" disabled={status !== 'active'} onClick={() => setEndedAt(Date.now())}>
+          끝내기
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### useElapsed
+
+startedAt 없이 쓰면 스톱워치예요. running으로 멈추고 이어 세고, reset()으로 0부터 다시.
+
+```tsx
+import { useState } from 'react'
+import { Pause, Play, RotateCcw } from 'lucide-react'
+import { Button, Inline, Stack, Text, formatElapsed, useElapsed } from '@iamfiro/design'
+
+export default function Example() {
+  const [running, setRunning] = useState(true)
+  const { elapsed, reset } = useElapsed(undefined, { running })
+  return (
+    <Stack gap={3} style={{ width: 320 }}>
+      <Inline justify="between" wrap={false}>
+        <Text variant="label-md">회의 기록</Text>
+        <Text variant="number-md" tone={running ? 'default' : 'tertiary'}>
+          {formatElapsed(elapsed)}
+        </Text>
+      </Inline>
+      <Text variant="caption" tone="tertiary">
+        {running ? '기록 중' : '일시 정지'} · {formatElapsed(elapsed, 'text')}
+      </Text>
+      <Inline gap={2}>
+        <Button size="sm" icon={running ? <Pause /> : <Play />} onClick={() => setRunning((r) => !r)}>
+          {running ? '일시 정지' : '이어서'}
+        </Button>
+        <Button size="sm" variant="ghost" icon={<RotateCcw />} onClick={reset}>
+          처음부터
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```