@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/card-frame/AGENTS.md

@@ -0,0 +1,227 @@
+# CardFrame
+
+> 컨테이너 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+흰 Card를 옅은 회색 판으로 한 번 더 감싸는 틀. 카드는 내용 그대로 두고, 몇 단계인지 · 얼마나 진행됐는지 같은 맥락은 카드 바깥 회색 위의 header · footer 줄에 둬요. 회색 테두리 4px + 카드 모서리 16px = 바깥 모서리 20px라 모서리가 겹쳐 보이지 않아요.
+
+```tsx
+import { CardFrame } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 카드를 회색 판으로 한 번 더 감싸고 맥락(몇 단계 · 어떤 도구 · 진행 상태)을 카드 바깥에 둘 땐 `CardFrame`(`header` 캡션 / `footer` 상태 줄, `--surface-active` 판 + 4px 테두리 + 바깥 모서리 20px로 카드 16px와 겹치지 않게). 카드 안쪽 아래 띠는 여전히 `CardFooter band`.
+- 글 속 변경 내용(추적된 변경)은 `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
+
+### CardFrame
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `header` | `ReactNode` |  | 카드 위 회색 캡션 줄. 자식이 둘이면 양 끝으로 벌어져요. |
+| `footer` | `ReactNode` |  | 카드 아래 회색 상태 줄. 자식이 둘이면 양 끝으로 벌어져요. |
+| `children` | `ReactNode` |  | 보통 Card 하나. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 아래 상태 줄
+
+footer에 진행 상태와 경과 시간. 두 요소를 넣으면 양 끝으로 벌어져요. 안쪽은 Card + CardHeader + StepList 그대로예요.
+
+```tsx
+import { ListChecks } from 'lucide-react'
+import { Elapsed, Inline, StatusIcon, Text, formatElapsed, Card, CardBody, CardFrame, CardHeader, StepList, type StepListStep } from '@iamfiro/design'
+
+const STEPS: StepListStep[] = [
+  {
+    id: 'pull',
+    status: 'done',
+    title: '3분기 매출 · 이탈률 가져오기',
+    description: (
+      <>
+        Stripe에서 7월 ~ 9월 <Text variant="code">stripe.query</Text>
+      </>
+    ),
+    meta: '2.1초',
+  },
+  {
+    id: 'read',
+    status: 'done',
+    title: '지난 분기 이사회 메모 읽기',
+    description: (
+      <>
+        이사회에 익숙한 구성을 유지 <Text variant="code">search</Text>
+      </>
+    ),
+    meta: '2.5초',
+  },
+  {
+    id: 'draft',
+    status: 'active',
+    title: '메모 초안 고치기',
+    description: (
+      <>
+        매출 · 이탈률 · 4분기 전망 <Text variant="code">docs.write</Text>
+      </>
+    ),
+    meta: <Elapsed initial={3} format={(s) => formatElapsed(s, 'text')} />,
+  },
+  {
+    id: 'send',
+    status: 'pending',
+    title: '김민지 님에게 초안 보내기',
+    description: (
+      <>
+        먼저 승인이 필요해요 <Text variant="code">gmail.send</Text>
+      </>
+    ),
+  },
+  {
+    id: 'book',
+    status: 'pending',
+    title: '김민지 님과 검토 일정 잡기',
+    description: (
+      <>
+        이사회 30분 전 <Text variant="code">calendar.create</Text>
+      </>
+    ),
+  },
+]
+
+export default function Example() {
+  const done = STEPS.filter((s) => s.status === 'done').length
+  return (
+    <CardFrame
+      style={{ width: '100%', maxWidth: 560 }}
+      footer={
+        <>
+          <Inline gap={2} wrap={false}>
+            <StatusIcon status="active" size="sm" decorative />
+            <Text variant="label-sm" tone="secondary" numeric>
+              실행 중 · {done + 1}/{STEPS.length}
+            </Text>
+          </Inline>
+          <Text variant="label-sm" tone="tertiary">
+            <Elapsed initial={5} />
+          </Text>
+        </>
+      }
+    >
+      <Card>
+        <CardHeader
+          eyebrow={
+            <Inline gap={1} wrap={false}>
+              <ListChecks size={14} aria-hidden />
+              계획 · {STEPS.length}단계
+            </Inline>
+          }
+          title="3분기 이사회 보고 준비"
+        />
+        <CardBody>
+          <StepList steps={STEPS} marker="status-number" aria-label="이사회 보고 준비 단계" />
+        </CardBody>
+      </Card>
+    </CardFrame>
+  )
+}
+```
+
+### 위 캡션
+
+header에 어느 단계 · 어떤 도구인지 적고, 안쪽 카드엔 승인 내용(IconTile · Badge · DescriptionList soft · 버튼)만 둬요.
+
+```tsx
+import { Mail } from 'lucide-react'
+import { Badge, Button, IconTile, Text, Card, CardBody, CardFooter, CardFrame, CardHeader, DescriptionItem, DescriptionList, toast } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <CardFrame
+      style={{ width: '100%', maxWidth: 360 }}
+      header={
+        <Text variant="label-sm" tone="tertiary">
+          4단계 · <Text variant="code">gmail.send</Text>
+        </Text>
+      }
+    >
+      <Card padding="sm">
+        <CardHeader
+          icon={
+            <IconTile>
+              <Mail />
+            </IconTile>
+          }
+          title="김민지 님에게 초안 보내기"
+          description="3분기 이사회 메모를 메일로 보내요."
+          actions={
+            <Badge tone="warning" dot size="sm">
+              보통
+            </Badge>
+          }
+        />
+        <CardBody>
+          <DescriptionList layout="inline" align="start" variant="soft" labelStyle="muted" size="sm" aria-label="보낼 메일">
+            <DescriptionItem label="받는 사람">김민지 (CFO)</DescriptionItem>
+            <DescriptionItem label="제목">3분기 이사회 보고 – 초안</DescriptionItem>
+            <DescriptionItem label="첨부">이사회 메모 – 2026년 3분기</DescriptionItem>
+          </DescriptionList>
+        </CardBody>
+        <CardFooter>
+          <Button size="sm" variant="secondary" onClick={() => toast('발송을 거절했어요')}>
+            거절
+          </Button>
+          <Button size="sm" variant="primary" onClick={() => toast.success('초안을 보냈어요')}>
+            승인
+          </Button>
+        </CardFooter>
+      </Card>
+    </CardFrame>
+  )
+}
+```
+
+### 위 · 아래 함께
+
+header와 footer를 같이 쓸 수 있어요.
+
+```tsx
+import { Sparkles } from 'lucide-react'
+import { Badge, Inline, RelativeTime, Text, Card, CardBody, CardFrame } from '@iamfiro/design'
+
+const SAVED_AT = new Date(Date.now() - 2 * 60_000)
+
+export default function Example() {
+  return (
+    <CardFrame
+      style={{ width: '100%', maxWidth: 420 }}
+      header={
+        <>
+          <Inline gap={1} wrap={false}>
+            <Sparkles size={14} aria-hidden />
+            <Text variant="label-sm" tone="tertiary">
+              이사회 메모 – 3분기 · 매출
+            </Text>
+          </Inline>
+          <Badge size="sm" tone="accent">
+            제안 3개
+          </Badge>
+        </>
+      }
+      footer={
+        <Text variant="label-sm" tone="tertiary">
+          <RelativeTime date={SAVED_AT} /> 자동 저장됨
+        </Text>
+      }
+    >
+      <Card>
+        <CardBody>
+          3분기 매출은 전 분기보다 12% 늘어난 48억 원이에요. 이탈률은 2.1%로 목표보다 낮게 유지됐고, 4분기에는 신규 요금제 효과로 성장이 이어질 것으로 보여요.
+        </CardBody>
+      </Card>
+    </CardFrame>
+  )
+}
+```

package/agents/chat-bubble/AGENTS.md

@@ -0,0 +1,266 @@
+# ChatBubble
+
+> 대화 & 활동 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+채팅 메시지 한 개를 채워진 말풍선으로 보여 줘요. 상대 메시지는 왼쪽 회색, 내 메시지는 오른쪽 파랑. ChatBubbleGroup으로 한 사람이 이어 보낸 메시지를 묶으면 이웃한 모서리가 좁아져 한 줄기로 읽히고, 시간 · 읽음 표시는 마지막 말풍선 옆에만 붙어요. 보내는 중(pending)은 옅게, 실패하면 빨간 글자와 "다시 보내기"가 나타나요.
+
+```tsx
+import { ChatBubble, ChatBubbleGroup } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 채팅(메신저형)은 `ChatBubble` + `ChatBubbleGroup`: 상대 = 왼쪽 회색(`--surface-active`), 나 = 오른쪽 파랑(`--accent`), 테두리 없이 채움만. 한 사람의 연속 메시지는 그룹으로 묶어 이웃한 모서리만 좁히고(`--r-lg` → `--r-xs`), 시간("오후 3:12", `formatChatTime`) · 읽음 체크는 마지막 말풍선 옆에만. 보내는 중 = 옅은 말풍선 + Spinner, 실패 = 빨간 글자 + "다시 보내기"(테두리 X). 새 메시지는 `appear`, 입력 중은 `typing`.
+
+## API
+
+### ChatBubble
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` |  | 메시지 내용. 줄바꿈이 그대로 보여요. |
+| `side` | `'start' \| 'end'` | `그룹의 side 또는 'start'` | start = 상대(왼쪽), end = 나(오른쪽). |
+| `tone` | `'neutral' \| 'accent' \| 'primary'` | `start → neutral, end → accent` | 말풍선 채움 색. |
+| `time` | `Date \| string \| number` |  | 보낸 시각. "오후 3:12"처럼 보이고, 올리면 전체 날짜가 나와요. 묶음의 마지막 말풍선에만 보여요. |
+| `status` | `'sending' \| 'sent' \| 'read' \| 'failed'` |  | 전송 상태. 보내는 중 · 실패는 묶음 위치와 상관없이 항상 보여요. |
+| `onRetry` | `() => void` |  | failed일 때 "다시 보내기" 버튼을 눌렀을 때. |
+| `typing` | `boolean` |  | 내용 대신 움직이는 점 세 개(입력 중). |
+| `actions` | `ReactNode` |  | 말풍선 옆 버튼(반응, 답장, 더 보기). hover · focus 때 나타나요. |
+| `footer` | `ReactNode` |  | 말풍선 아래(반응, 첨부, 링크 미리보기). |
+| `appear` | `boolean` |  | 마운트될 때 아래에서 떠오르기 — 방금 도착한 메시지에. |
+| `position` | `'single' \| 'first' \| 'middle' \| 'last'` |  | ChatBubbleGroup이 정해 줘요. 그룹 밖에서 쓸 때만 직접 넘겨요. |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에 전달. |
+
+### ChatBubbleGroup
+
+ChatBubble.Group으로도 쓸 수 있어요. 시간 글자("오후 3:12")만 필요하면 formatChatTime(date).
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | ChatBubble들(오래된 것부터). |
+| `author` | `ReactNode` |  | 보낸 사람. 시작 쪽에서 문자열이면 Avatar와 이름을 그려요. |
+| `side` | `'start' \| 'end'` | `'start'` | 묶음 전체의 방향. |
+| `avatar` | `ReactNode` |  | 기본 아바타 대신. null이면 자리만 비워 두어 정렬을 유지해요. |
+| `showName` | `boolean` | `side === 'start'` | 첫 말풍선 위의 이름. 1:1 대화에선 끄세요. |
+| `avatarSize` | `number` | `28` | 아바타 크기(px). |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에 전달. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 1:1 대화
+
+Card 안에 ChatBubbleGroup · Marker(날짜) · ChatComposer를 조립했어요. 메시지를 보내면 보내는 중 → 전송됨 → 읽음으로 바뀌고, 상대가 입력 중(typing)이다가 답장해요. 새 메시지는 appear로 제 모서리에서 떠올라요.
+
+```tsx
+import { useEffect, useRef, useState } from 'react'
+import { Stack, Text, Card, CardBody, CardHeader, ChatBubble, ChatBubbleGroup, ChatComposer, Marker, type ChatBubbleStatus } from '@iamfiro/design'
+
+const minutesAgo = (m: number) => new Date(Date.now() - m * 60_000)
+
+interface Message {
+  id: string
+  side: 'start' | 'end'
+  text: string
+  time: Date
+  status?: ChatBubbleStatus
+  fresh?: boolean
+}
+
+const INITIAL: Message[] = [
+  { id: '1', side: 'start', text: '민지 씨, 내일 디자인 리뷰 몇 시였죠?', time: minutesAgo(14) },
+  { id: '2', side: 'start', text: '회의실 예약을 아직 안 해서요', time: minutesAgo(14) },
+  { id: '3', side: 'end', text: '오후 2시예요!', time: minutesAgo(12), status: 'read' },
+  { id: '4', side: 'end', text: '3층 큰 회의실로 잡아 주시면 좋겠어요', time: minutesAgo(12), status: 'read' },
+]
+
+/** Consecutive messages from the same side become one group. */
+function groupRuns(messages: Message[]) {
+  const runs: Message[][] = []
+  for (const m of messages) {
+    const run = runs[runs.length - 1]
+    if (run && run[0].side === m.side) run.push(m)
+    else runs.push([m])
+  }
+  return runs
+}
+
+export default function Example() {
+  const [messages, setMessages] = useState(INITIAL)
+  const [typing, setTyping] = useState(false)
+  const timers = useRef<number[]>([])
+
+  useEffect(() => () => timers.current.forEach((t) => window.clearTimeout(t)), [])
+
+  const later = (ms: number, fn: () => void) => timers.current.push(window.setTimeout(fn, ms))
+  const setStatus = (id: string, status: ChatBubbleStatus) => setMessages((prev) => prev.map((m) => (m.id === id ? { ...m, status } : m)))
+
+  const send = (text: string) => {
+    const id = String(Date.now())
+    setMessages((prev) => [...prev, { id, side: 'end', text, time: new Date(), status: 'sending', fresh: true }])
+    later(700, () => setStatus(id, 'sent'))
+    later(1600, () => {
+      setStatus(id, 'read')
+      setTyping(true)
+    })
+    later(3400, () => {
+      setTyping(false)
+      setMessages((prev) => [...prev, { id: `${id}-r`, side: 'start', text: '네, 확인했어요. 바로 예약할게요 👍', time: new Date(), fresh: true }])
+    })
+  }
+
+  const runs = groupRuns(messages)
+  const lastSide = runs[runs.length - 1][0].side
+
+  return (
+    <Card padding="sm" style={{ width: 400 }}>
+      <CardHeader title={<Text variant="label-md">이도현</Text>} />
+      <CardBody>
+        <Stack gap={4}>
+          <Stack gap={4} aria-live="polite">
+            <Marker>오늘</Marker>
+            {runs.map((run, i) => (
+              <ChatBubbleGroup key={run[0].id} side={run[0].side} author="이도현" showName={false}>
+                {run.map((m) => (
+                  <ChatBubble key={m.id} time={m.time} status={m.status} appear={m.fresh}>
+                    {m.text}
+                  </ChatBubble>
+                ))}
+                {/* "입력 중" joins the other person's run when they spoke last. */}
+                {typing && i === runs.length - 1 && lastSide === 'start' && <ChatBubble key="typing" typing appear />}
+              </ChatBubbleGroup>
+            ))}
+            {typing && lastSide === 'end' && (
+              <ChatBubbleGroup author="이도현" showName={false}>
+                <ChatBubble typing appear />
+              </ChatBubbleGroup>
+            )}
+          </Stack>
+          <ChatComposer size="sm" placeholder="메시지 입력" aria-label="메시지" onSubmit={send} />
+        </Stack>
+      </CardBody>
+    </Card>
+  )
+}
+```
+
+### 그룹 대화
+
+시작 쪽 그룹은 이름과 아바타를 보여 줘요. 아바타는 첫 말풍선 옆, 시간은 마지막 말풍선 옆에 붙어요.
+
+```tsx
+import { Stack, ChatBubble, ChatBubbleGroup, Marker } from '@iamfiro/design'
+
+const at = (h: number, m: number) => new Date(2026, 9, 25, h, m)
+
+export default function Example() {
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 420 }}>
+      <Marker>10월 25일 일요일</Marker>
+      <ChatBubbleGroup author="김민지">
+        <ChatBubble time={at(15, 2)}>배포 끝났어요 🎉</ChatBubble>
+      </ChatBubbleGroup>
+      <ChatBubbleGroup author="박서준">
+        <ChatBubble>수고하셨어요!</ChatBubble>
+        <ChatBubble>혹시 변경 로그도 올라갔나요?</ChatBubble>
+        <ChatBubble time={at(15, 4)}>고객 공지에 링크를 걸어야 해서요</ChatBubble>
+      </ChatBubbleGroup>
+      <ChatBubbleGroup side="end">
+        <ChatBubble>방금 올렸어요</ChatBubble>
+        <ChatBubble time={at(15, 5)} status="read">
+          docs/changelog 맨 위에 있어요
+        </ChatBubble>
+      </ChatBubbleGroup>
+    </Stack>
+  )
+}
+```
+
+### 전송 상태
+
+sending은 옅은 말풍선 + 스피너, sent는 체크, read는 파란 이중 체크. failed는 테두리 대신 빨간 글자와 다시 보내기 버튼이에요.
+
+```tsx
+import { useEffect, useRef, useState } from 'react'
+import { Stack, ChatBubble, ChatBubbleGroup, type ChatBubbleStatus } from '@iamfiro/design'
+
+const NOW = new Date(2026, 9, 25, 16, 20)
+
+export default function Example() {
+  const [status, setStatus] = useState<ChatBubbleStatus>('failed')
+  const timer = useRef(0)
+
+  useEffect(() => () => window.clearTimeout(timer.current), [])
+
+  const retry = () => {
+    setStatus('sending')
+    timer.current = window.setTimeout(() => setStatus('sent'), 1200)
+  }
+
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 420 }}>
+      <ChatBubbleGroup side="end">
+        <ChatBubble time={NOW} status="read">
+          읽음 — 파란 이중 체크
+        </ChatBubble>
+      </ChatBubbleGroup>
+      <ChatBubbleGroup side="end">
+        <ChatBubble time={NOW} status="sent">
+          전송됨 — 회색 체크
+        </ChatBubble>
+      </ChatBubbleGroup>
+      <ChatBubbleGroup side="end">
+        <ChatBubble status="sending">보내는 중 — 옅은 말풍선</ChatBubble>
+      </ChatBubbleGroup>
+      <ChatBubbleGroup side="end">
+        <ChatBubble time={NOW} status={status} onRetry={retry}>
+          네트워크가 끊겨서 못 보낸 메시지
+        </ChatBubble>
+      </ChatBubbleGroup>
+    </Stack>
+  )
+}
+```
+
+### 색 · 액션 · 반응
+
+tone(neutral · accent · primary), 마우스를 올리면 나타나는 actions, 말풍선 아래 footer(반응)를 보여 줘요.
+
+```tsx
+import { useState } from 'react'
+import { Reply, SmilePlus } from 'lucide-react'
+import { Badge, Button, Stack, ChatBubble, ChatBubbleGroup } from '@iamfiro/design'
+
+const NOW = new Date(2026, 9, 25, 9, 41)
+
+export default function Example() {
+  const [liked, setLiked] = useState(false)
+
+  const actions = (
+    <>
+      <Button variant="ghost" size="sm" iconOnly icon={<SmilePlus />} aria-label="반응 남기기" onClick={() => setLiked((v) => !v)} />
+      <Button variant="ghost" size="sm" iconOnly icon={<Reply />} aria-label="답장" />
+    </>
+  )
+
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 420 }}>
+      <ChatBubbleGroup author="이도현" showName={false}>
+        <ChatBubble time={NOW} actions={actions} footer={liked && <Badge>👍 1</Badge>}>
+          올려 두면 반응 · 답장 버튼이 나타나요
+        </ChatBubble>
+        <ChatBubble typing />
+      </ChatBubbleGroup>
+      <ChatBubbleGroup side="end">
+        <ChatBubble time={NOW}>accent — 기본 내 메시지</ChatBubble>
+      </ChatBubbleGroup>
+      <ChatBubbleGroup side="end">
+        <ChatBubble tone="primary" time={NOW}>
+          primary — 검정 말풍선
+        </ChatBubble>
+      </ChatBubbleGroup>
+    </Stack>
+  )
+}
+```