@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/copy-button/AGENTS.md

@@ -0,0 +1,84 @@
+# CopyButton
+
+> 버튼 & 링크 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+value를 클립보드에 복사하는 버튼. 복사되면 아이콘이 잠깐 체크로 바뀌어 결과를 바로 보여 줘요. 글자 없이 쓰면 아이콘 버튼 + 툴팁이 돼요.
+
+```tsx
+import { CopyButton } from '@iamfiro/design'
+```
+
+## API
+
+### CopyButton
+
+Button의 variant · size · disabled 등도 그대로 받아요(onClick · icon · children 제외).
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `string` |  | 클립보드에 넣을 글자. |
+| `label` | `string` |  | 아이콘 옆 글자. 생략하면 아이콘 버튼 + 툴팁. |
+| `copiedLabel` | `string` | `'복사했어요'` | 복사 직후(1.6초) 보이는 글자와 툴팁. |
+| `onCopy` | `(value: string) => void` |  | 복사에 성공했을 때. |
+| `variant` | `ButtonVariant` | `'ghost'` | 버튼 스타일. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | 버튼 크기. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+label이 없으면 아이콘만 보이고, 마우스를 올리면 "복사" 툴팁이 떠요.
+
+```tsx
+import { CopyButton, Text } from '@iamfiro/design'
+
+const API_KEY = 'pk_demo_7Gq2XvT9nR4w'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+      <Text variant="code">{API_KEY}</Text>
+      <CopyButton value={API_KEY} />
+    </div>
+  )
+}
+```
+
+### 글자와 함께
+
+label을 주면 글자가 붙고, 복사 직후에는 copiedLabel로 잠깐 바뀌어요.
+
+```tsx
+import { CopyButton } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 8 }}>
+      <CopyButton value="https://lumen.app/invite/8f2k1" label="초대 링크 복사" variant="secondary" size="md" />
+      <CopyButton value="npm install @lumen/ui" label="명령어 복사" copiedLabel="복사 완료" />
+    </div>
+  )
+}
+```
+
+### 복사 후 알림
+
+onCopy는 복사에 성공했을 때만 불려요. 토스트로 한 번 더 알려 줄 수 있어요.
+
+```tsx
+import { CopyButton, toast } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <CopyButton
+      value="ORD-20261025-4821"
+      label="주문번호 복사"
+      variant="secondary"
+      size="md"
+      onCopy={() => toast.success('주문번호를 복사했어요')}
+    />
+  )
+}
+```

package/agents/count-badge/AGENTS.md

@@ -0,0 +1,115 @@
+# CountBadge
+
+> 라벨 & 배지 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+섹션 제목 · 아이콘 옆에 붙는 작은 숫자 원. 기다리는 일, 읽지 않은 항목의 개수를 알려요. 숫자는 tabular라 흔들리지 않고, 두 자리 이상이면 둥근 캡슐로 늘어나요. 값이 바뀌면 배지가 살짝 튀고 새 숫자가 아래에서 올라와요. 글자가 있는 상태 라벨은 Badge, 탭 옆 개수는 Tabs의 count를 써요.
+
+```tsx
+import { CountBadge } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 제목 · 아이콘 옆 개수 원은 `CountBadge`(tone · `max` "99+" · 바뀌면 튀기). 글자가 있는 상태 라벨은 `Badge`.
+- 글 속 변경 내용(추적된 변경)은 `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
+
+### CountBadge
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `count` (필수) | `number` |  | 보여 줄 숫자. |
+| `max` | `number` | `99` | 넘으면 "99+"처럼 보여요. |
+| `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger' \| 'info'` | `'accent'` | 색(Badge와 같아요). |
+| `variant` | `'solid' \| 'soft'` | `'solid'` | solid: 채운 원 · soft: 연한 배경 + 색 숫자. |
+| `size` | `'sm' \| 'md'` | `'md'` | sm 16px · md 18px 높이. |
+| `showZero` | `boolean` |  | 0일 때도 보여요(기본은 숨김). |
+| `label` | `string` |  | 숫자 대신 읽힐 이름("승인 대기 1건"). |
+| `className / style` | `string / CSSProperties` |  | 추가 클래스 · 스타일. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 섹션 제목 옆
+
+버튼으로 개수를 바꿔 튀는 움직임을 확인해 보세요. label을 주면 화면 읽기 프로그램이 "승인 대기 1건"으로 읽어요.
+
+```tsx
+import { useState } from 'react'
+import { Minus, Plus } from 'lucide-react'
+import { Button, CountBadge, Inline, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [waiting, setWaiting] = useState(1)
+  return (
+    <Stack gap={4} style={{ width: 320 }}>
+      <Inline gap={2} wrap={false}>
+        <Text variant="heading-xs" as="h3">
+          승인 대기
+        </Text>
+        <CountBadge count={waiting} tone="warning" label={`승인 대기 ${waiting}건`} />
+      </Inline>
+      <Text variant="body-sm" tone="secondary">
+        숫자가 바뀌면 배지가 살짝 튀어 오르고 새 숫자가 아래에서 올라와요. 0이면 사라지고, 99를 넘으면 "99+"가 돼요.
+      </Text>
+      <Inline gap={2}>
+        <Button size="sm" icon={<Plus />} onClick={() => setWaiting((n) => n + 1)}>
+          요청 추가
+        </Button>
+        <Button size="sm" variant="ghost" icon={<Minus />} disabled={waiting === 0} onClick={() => setWaiting((n) => Math.max(0, n - 1))}>
+          하나 처리
+        </Button>
+        <Button size="sm" variant="ghost" onClick={() => setWaiting(120)}>
+          120건
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 색 · 모양 · 크기
+
+Badge와 같은 tone. solid는 채운 원 + 흰 숫자, soft는 연한 상태색 + 색 숫자예요. sm 16 · md 18px, max를 넘으면 "99+".
+
+```tsx
+import { CountBadge, Inline, Stack, Text, type Tone } from '@iamfiro/design'
+
+const TONES: Tone[] = ['accent', 'neutral', 'success', 'warning', 'danger', 'info']
+
+export default function Example() {
+  return (
+    <Stack gap={4}>
+      <Inline gap={3}>
+        {TONES.map((tone) => (
+          <CountBadge key={tone} tone={tone} count={3} />
+        ))}
+        <Text variant="caption" tone="tertiary">
+          solid
+        </Text>
+      </Inline>
+      <Inline gap={3}>
+        {TONES.map((tone) => (
+          <CountBadge key={tone} tone={tone} variant="soft" count={3} />
+        ))}
+        <Text variant="caption" tone="tertiary">
+          soft
+        </Text>
+      </Inline>
+      <Inline gap={3}>
+        <CountBadge size="sm" count={1} tone="warning" />
+        <CountBadge size="sm" count={24} />
+        <CountBadge count={8} />
+        <CountBadge count={128} tone="danger" />
+        <CountBadge count={1500} max={999} tone="neutral" />
+        <CountBadge count={0} showZero tone="neutral" variant="soft" />
+        <Text variant="caption" tone="tertiary">
+          sm · md · max · showZero
+        </Text>
+      </Inline>
+    </Stack>
+  )
+}
+```

package/agents/countdown/AGENTS.md

@@ -0,0 +1,101 @@
+# Countdown
+
+> 진행 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+남은 시간을 "8초" · "1:05"처럼 글자로 보여 줘요. 글자라서 Badge · 캡션 · 버튼 어디에나 들어가고, 숫자는 tabular라 흔들리지 않아요. 렌더 중엔 시계를 읽지 않고 타이머 안에서 마감 시각과 비교해 밀리지 않아요. 직접 그리고 싶으면 useCountdown 훅을 써요. 시작한 뒤 지난 시간을 올려 세려면 Elapsed를 써요.
+
+```tsx
+import { Countdown, formatCountdown, useCountdown } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 남은 시간("8초")은 `Countdown` / `useCountdown`(렌더 중 시계 읽기 금지). Badge 안엔 글자로 넣는다.
+
+## API
+
+### Countdown
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `seconds` (필수) | `number` |  | 몇 초부터 셀지. 값이 바뀌면 처음부터. |
+| `running` | `boolean` | `true` | false면 그 자리에서 멈추고, true면 이어서 세요. |
+| `onComplete` | `() => void` |  | 0이 될 때 한 번. |
+| `format` | `(remaining: number) => ReactNode` | `formatCountdown` | 남은 초를 글자로. 기본은 "8초" / "1:05" / "1:02:05". |
+| `doneLabel` | `ReactNode` |  | 0일 때 "0초" 대신 보일 글자. |
+| `className / style` | `string / CSSProperties` |  | span(role="timer")에 전달. |
+
+### useCountdown(seconds, options)
+
+반환값 { remaining, done, restart(seconds?) }.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `seconds` (필수) | `number` |  | 시작 초. 바뀌면 처음부터 다시. |
+| `options.running` | `boolean` | `true` | 멈춤 / 이어 세기. |
+| `options.onComplete` | `() => void` |  | 0이 될 때 한 번. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### Badge 안의 카운트다운
+
+Badge는 그대로 두고 글자 자리에 Countdown을 넣어요. 0이 되면 onComplete로 상태를 바꿔요. 1분이 넘으면 "2:05" 형식.
+
+```tsx
+import { useState } from 'react'
+import { Badge, Button, Countdown, Inline } from '@iamfiro/design'
+
+export default function Example() {
+  const [limited, setLimited] = useState(true)
+  return (
+    <Inline gap={3}>
+      {limited ? (
+        <Badge tone="warning" dot>
+          요청 제한 · <Countdown seconds={8} onComplete={() => setLimited(false)} />
+        </Badge>
+      ) : (
+        <Badge tone="success" dot>
+          다시 보낼 수 있어요
+        </Badge>
+      )}
+      <Badge>
+        세션 만료까지 <Countdown seconds={125} />
+      </Badge>
+      <Button size="sm" variant="ghost" disabled={limited} onClick={() => setLimited(true)}>
+        다시 제한 걸기
+      </Button>
+    </Inline>
+  )
+}
+```
+
+### useCountdown
+
+남은 초(remaining) · done · restart()를 받아 막대와 색을 직접 그려요. seconds가 바뀌어도 처음부터 다시 세요.
+
+```tsx
+import { RotateCcw } from 'lucide-react'
+import { Button, Inline, Progress, Stack, Text, formatCountdown, useCountdown } from '@iamfiro/design'
+
+const SECONDS = 30
+
+export default function Example() {
+  const { remaining, done, restart } = useCountdown(SECONDS)
+  return (
+    <Stack gap={3} style={{ width: 320 }}>
+      <Inline justify="between" wrap={false}>
+        <Text variant="label-md">인증번호 유효 시간</Text>
+        <Text variant="label-md" tone={done ? 'danger' : remaining <= 10 ? 'warning' : 'secondary'} numeric>
+          {done ? '만료됨' : formatCountdown(remaining)}
+        </Text>
+      </Inline>
+      <Progress value={remaining} max={SECONDS} size="sm" tone={remaining <= 10 ? 'warning' : 'accent'} aria-label="남은 시간" />
+      <Button size="sm" icon={<RotateCcw />} onClick={() => restart()} disabled={!done}>
+        인증번호 다시 받기
+      </Button>
+    </Stack>
+  )
+}
+```