@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/icon-stack/AGENTS.md

@@ -0,0 +1,120 @@
+# IconStack
+
+> 아이콘 & 아바타 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+작은 아이콘 · 로고 2–3개를 겹쳐 한 줄로 보여 줘요. 작업 설명 앞에 "어떤 앱이 관련됐는지"를 붙일 때 좋아요. AvatarGroup도 이 컴포넌트로 만들어져 있어요. 아이콘끼리는 테두리가 아니라 바탕색 링으로 잘라 구분해요.
+
+```tsx
+import { IconStack } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 겹친 작은 아이콘 · 로고는 `IconStack`(AvatarGroup도 이것으로). 겹침은 테두리가 아니라 바탕색 링으로 자른다.
+
+## API
+
+### IconStack
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `icons` (필수) | `ReactNode[]` |  | 앞에서부터 보일 아이콘 · 로고 · 아바타. 크기는 각 아이콘에서 정해요. |
+| `size` | `number` | `20` | 항목 하나의 지름(px). |
+| `max` | `number` | `3` | 보여 줄 개수. 나머지는 +N. |
+| `overlap` | `number` | `size / 3` | 앞 항목 밑으로 들어가는 폭(px). |
+| `shape` | `'circle' \| 'square'` | `'circle'` | 항목 모양. |
+| `tile` | `boolean` |  | 아이콘 밑에 흰 타일 + 옅은 그림자. |
+| `renderOverflow` | `(hidden: number) => ReactNode` |  | +N 항목을 직접 그려요(AvatarGroup은 Avatar로). |
+| `label` | `string` |  | 묶음 전체의 이름. 없으면 장식으로 취급해 스크린 리더에서 숨겨요. |
+| `className` | `string` |  | 추가 클래스. |
+| `style` | `CSSProperties` |  | 인라인 스타일. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+tile은 로고마다 흰 타일을 깔고, max를 넘는 아이콘은 +N으로 묶어요. BrandIcon의 size는 직접 정해요(타일 크기의 70% 정도).
+
+```tsx
+import { BrandIcon, IconStack, Inline } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Inline gap={8}>
+      <IconStack tile icons={[<BrandIcon key="slack" name="slack" size={14} />, <BrandIcon key="github" name="github" size={14} />]} label="Slack, GitHub" />
+      <IconStack
+        tile
+        icons={(['figma', 'slack', 'gmail'] as const).map((n) => (
+          <BrandIcon key={n} name={n} size={14} />
+        ))}
+        label="Figma, Slack, Gmail"
+      />
+      <IconStack
+        tile
+        size={24}
+        max={2}
+        icons={(['gmail', 'clickup', 'figma', 'github', 'slack'] as const).map((n) => (
+          <BrandIcon key={n} name={n} size={16} />
+        ))}
+        label="Gmail, ClickUp 외 3개"
+      />
+    </Inline>
+  )
+}
+```
+
+### 작업 행
+
+ListItem의 leading에 넣어 관련 앱을 보여 줘요. label을 주면 스크린 리더가 앱 이름을 읽어요.
+
+```tsx
+import { Badge, BrandIcon, IconStack, type BrandName, List, ListItem } from '@iamfiro/design'
+
+const TASKS: Array<{ id: string; title: string; meta: string; apps: BrandName[]; names: string }> = [
+  { id: 'design', title: '디자인 리뷰 코멘트 정리', meta: '김민지', apps: ['figma', 'slack'], names: 'Figma, Slack' },
+  { id: 'release', title: '릴리스 노트 메일 보내기', meta: '이도현', apps: ['github', 'gmail'], names: 'GitHub, Gmail' },
+  { id: 'sprint', title: '스프린트 보드 업데이트', meta: '최서연', apps: ['clickup', 'slack', 'github', 'figma'], names: 'ClickUp, Slack, GitHub, Figma' },
+]
+
+export default function Example() {
+  return (
+    <List label="오늘 할 일" style={{ width: '100%', maxWidth: 460 }}>
+      {TASKS.map((t) => (
+        <ListItem
+          key={t.id}
+          leading={<IconStack tile max={2} icons={t.apps.map((a) => <BrandIcon key={a} name={a} size={14} />)} label={t.names} />}
+          title={t.title}
+          meta={t.meta}
+          trailing={t.id === 'release' ? <Badge tone="warning" size="sm">오늘 마감</Badge> : undefined}
+        />
+      ))}
+    </List>
+  )
+}
+```
+
+### 모양 · 크기 · 겹침
+
+shape="square"는 앱 아이콘처럼 둥근 사각형. overlap으로 겹치는 정도를 조절해요.
+
+```tsx
+import { FileText, Image as ImageIcon, Table2 } from 'lucide-react'
+import { Avatar, BrandIcon, IconStack, Inline } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Inline gap={8}>
+      <IconStack
+        tile
+        shape="square"
+        size={28}
+        icons={[<BrandIcon key="figma" name="figma" size={18} />, <BrandIcon key="github" name="github" size={18} />, <BrandIcon key="slack" name="slack" size={18} />]}
+      />
+      <IconStack tile size={24} overlap={4} icons={[<FileText key="doc" size={13} />, <Table2 key="sheet" size={13} />, <ImageIcon key="image" size={13} />]} />
+      <IconStack size={32} overlap={10} icons={['김민지', '이도현', '최서연', '정우진'].map((n) => <Avatar key={n} name={n} size={32} />)} />
+    </Inline>
+  )
+}
+```

package/agents/icon-tile/AGENTS.md

@@ -0,0 +1,94 @@
+# IconTile
+
+> 아이콘 & 아바타 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+아이콘이나 글자 하나를 담는 작은 채움 타일. 도구 · 사이트 · 문서처럼 사람이 아닌 것의 목록 행 앞(ListItem leading)에 써요. 사람은 Avatar로. 기본은 작은 회색 채움이고, 상태 색은 tone으로 골라요. 로고나 여러 색 아이콘은 회색이 탁해 보이니 tone="surface"(흰 타일 + 옅은 그림자)로.
+
+```tsx
+import { IconTile } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 행 앞 타일: 사람은 `Avatar`, 도구·사이트·문서는 `IconTile`(회색 채움 + 아이콘/글자). 선택된 것을 보여 주고 메뉴로 바꾸는 버튼(워크스페이스·계정 전환, 드롭다운 제목)은 `SelectorButton`을 `DropdownMenu` trigger에.
+
+## API
+
+### IconTile
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | 아이콘 또는 짧은 글자. |
+| `size` | `number` | `28` | 한 변 길이(px). |
+| `tone` | `'neutral' \| 'surface' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | neutral은 회색 채움, surface는 옅은 그림자로 띄운 흰 타일(로고 · 여러 색 아이콘용), 나머지는 연한 상태색. |
+| `round` | `boolean` |  | 둥근 모양. |
+| `aria-label` | `string` |  | 주면 role="img"로 읽혀요. 없으면 장식으로 숨겨요. |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에 전달. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 모양 · 톤 · 크기
+
+아이콘은 타일 크기의 약 절반으로 맞춰져요. 글자는 한 글자(또는 두 글자)까지.
+
+```tsx
+import { FileText, Globe, ImageIcon, Sparkles, TriangleAlert } from 'lucide-react'
+import { IconTile, Inline, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={5}>
+      <Stack gap={2}>
+        <Text variant="caption" tone="tertiary">
+          아이콘 · 글자
+        </Text>
+        <Inline gap={3}>
+          <IconTile>
+            <FileText />
+          </IconTile>
+          <IconTile>
+            <Globe />
+          </IconTile>
+          <IconTile>문</IconTile>
+          <IconTile>N</IconTile>
+          <IconTile round>
+            <ImageIcon />
+          </IconTile>
+        </Inline>
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="caption" tone="tertiary">
+          tone
+        </Text>
+        <Inline gap={3}>
+          <IconTile tone="surface">
+            <Globe />
+          </IconTile>
+          <IconTile tone="accent">
+            <Sparkles />
+          </IconTile>
+          <IconTile tone="success">완</IconTile>
+          <IconTile tone="warning">
+            <TriangleAlert />
+          </IconTile>
+          <IconTile tone="danger">!</IconTile>
+        </Inline>
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="caption" tone="tertiary">
+          size 20 · 28 · 36 · 44
+        </Text>
+        <Inline gap={3}>
+          {[20, 28, 36, 44].map((s) => (
+            <IconTile key={s} size={s}>
+              <FileText />
+            </IconTile>
+          ))}
+        </Inline>
+      </Stack>
+    </Stack>
+  )
+}
+```

package/agents/inline-diff/AGENTS.md

@@ -0,0 +1,211 @@
+# InlineDiff
+
+> 텍스트 & 코드 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+글 속 변경 내용(추적된 변경)을 그대로 보여 줘요. 지운 글자는 빨간 취소선 + 연한 빨간 배경, 넣은 글자는 초록 + 연한 초록 배경이고, 진짜 <del> · <ins>에 화면 읽기용 "삭제" · "추가"가 붙어요. 바로 이어진 삭제 + 추가는 한 변경으로 묶여요. reviewable이면 변경마다 눌러 수락 · 거절하는 작은 팝오버가 열리고, 수락하면 새 글로 · 거절하면 원래 글로 폭을 접으며 자연스럽게 정리돼요. 툴바(남은 개수, 이전 · 다음, 모두 수락)는 useDiffReview가 돌려주는 같은 상태로 조립해요.
+
+```tsx
+import { InlineDiff, applyDiffDecisions, diffWords, useDiffReview } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 글 속 변경 내용(추적된 변경)은 `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
+
+### InlineDiff
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `changes` | `DiffSegment[]` |  | { type: 'equal' \| 'insert' \| 'delete', text, changeId? } 목록. changeId가 없으면 바로 이어진 삭제 · 추가를 한 변경으로 묶어요. |
+| `before / after` | `string` |  | changes 대신 두 문자열. diffWords로 단어 단위 비교. |
+| `review` | `DiffReview` |  | useDiffReview 결과. 툴바와 상태를 나눌 때. 주면 segments · decisions를 여기서 읽어요. |
+| `reviewable` | `boolean` | `review가 있으면 true` | 변경을 눌러 수락 · 거절(팝오버). 화살표 · Home/End로 이동, Enter · Space로 열기. |
+| `decisions` | `DiffDecisions` |  | { [changeId]: 'accepted' \| 'rejected' } 제어 값. 없는 id는 대기. |
+| `defaultDecisions` | `DiffDecisions` |  | 비제어 초기값. |
+| `onDecisionsChange` | `(decisions) => void` |  | 결정이 바뀔 때. |
+| `variant` | `TextVariant` | `'body-md'` | 글자 역할. |
+| `as` | `'p' \| 'div' \| 'span'` | `'p'` | 루트 요소. |
+| `aria-label` | `string` |  | 본문 이름. |
+
+### useDiffReview
+
+옵션은 changes / before · after / decisions · defaultDecisions · onDecisionsChange / advance(기본 true: 결정 뒤 다음 남은 변경으로).
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `remaining · total` | `number` |  | 남은(대기) 변경 수 · 전체 변경 수. |
+| `current · currentIndex` | `string \| null · number` |  | 현재 변경 id와 순서. |
+| `next() · prev()` | `() => void` |  | 다음 · 이전 남은 변경으로(모두 정했으면 전체에서), 끝에서 처음으로 돌아요. 스크롤해 보여 줘요. |
+| `goTo(id) · setCurrent(id)` | `(id) => void` |  | 현재 변경 바꾸기(goTo는 스크롤까지). |
+| `accept(id?) · reject(id?)` | `(id?) => void` |  | 하나 결정. 기본은 현재 변경. |
+| `decide(id, decision | null)` | `function` |  | null이면 대기로 되돌려요. |
+| `acceptAll() · rejectAll()` | `() => void` |  | 남은 변경 전부. 이미 정한 건 그대로. |
+| `setDecisions · reset` | `function` |  | 결정 통째로 바꾸기(실행 취소) · 모두 대기로. |
+| `decisions · changes · segments · text` | `—` |  | 결정 맵, 변경 목록({ id, deleted, inserted }), 묶인 조각, 결정이 반영된 글. |
+
+### diff 도우미
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `diffWords(before, after)` | `DiffSegment[]` |  | 단어 · 공백 · 문장부호 토큰의 LCS. 변경 사이의 공백은 변경에 합쳐 한 번의 삭제 + 추가로 정리해요. |
+| `applyDiffDecisions(segments, decisions, pending?)` | `string` |  | 결정이 반영된 글. 대기 중인 변경은 pending('after' 기본 \| 'before'). |
+| `resolveDiffSegments · listDiffChanges` | `function` |  | changeId 묶기 · 변경 목록 만들기. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 검토 카드 (툴바 조립)
+
+CardFrame(회색 판 + 위 캡션) 안에 Card raised를 두고, useDiffReview로 만든 상태를 InlineDiff review와 툴바가 함께 써요. CountBadge soft = 남은 개수, Button iconOnly = 이전 · 다음(현재 변경을 스크롤해 보여 주고 파란 링으로 표시), 모두 거절 · 모두 수락은 확인 대신 바로 실행 + 실행 취소 토스트. 하나를 수락 · 거절하면 다음 남은 변경으로 넘어가요.
+
+```tsx
+import { Check, ChevronLeft, ChevronRight, FileText } from 'lucide-react'
+import { Badge, Button, CountBadge, Inline, Stack, Text, Card, CardBody, CardFrame, InlineDiff, toast, useDiffReview, type DiffDecision, type DiffSegment } from '@iamfiro/design'
+
+// A delete right before an insert (with no changeId) is grouped into one change automatically.
+const changes: DiffSegment[] = [
+  { type: 'equal', text: '3분기 매출은 전년 대비 ' },
+  { type: 'delete', text: '18%' },
+  { type: 'insert', text: '21%' },
+  { type: 'equal', text: ' 늘었어요. 신규 계약은 ' },
+  { type: 'delete', text: '2분기와 같은 수준에 머물렀고' },
+  { type: 'insert', text: '2분기보다 소폭 줄었고' },
+  { type: 'equal', text: ', 해지율은 ' },
+  { type: 'delete', text: '2.4%' },
+  { type: 'insert', text: '1.9%' },
+  { type: 'equal', text: '로 낮아졌어요. ' },
+  { type: 'insert', text: '환율 영향을 빼면 성장률은 19%예요. ' },
+  { type: 'equal', text: '4분기에는 ' },
+  { type: 'delete', text: '신제품 출시' },
+  { type: 'insert', text: '기존 고객 확대' },
+  { type: 'equal', text: '에 집중할 계획이에요.' },
+]
+
+export default function Example() {
+  const review = useDiffReview({ changes })
+  const done = review.remaining === 0
+
+  // Reversible, so no confirm dialog: decide right away and offer 실행 취소.
+  const decideAll = (decision: DiffDecision) => {
+    const previous = review.decisions
+    const count = review.remaining
+    if (decision === 'accepted') review.acceptAll()
+    else review.rejectAll()
+    toast.undo(`${count}곳을 ${decision === 'accepted' ? '수락' : '거절'}했어요`, { onUndo: () => review.setDecisions(previous) })
+  }
+
+  return (
+    <CardFrame
+      style={{ width: '100%', maxWidth: 460 }}
+      header={
+        <Inline gap={2} wrap={false}>
+          <FileText size={14} aria-hidden />
+          <Text variant="label-sm" tone="tertiary" truncate>
+            이사회 메모 – 3분기 · 매출
+          </Text>
+        </Inline>
+      }
+    >
+      <Card variant="raised" padding="sm">
+        <CardBody>
+          <Stack gap={3}>
+            <Inline gap={2} justify="between">
+              <Inline gap={1} wrap={false}>
+                {done ? (
+                  <Badge tone="success" size="sm" icon={<Check />}>
+                    검토 완료
+                  </Badge>
+                ) : (
+                  <span aria-live="polite">
+                    <CountBadge count={review.remaining} variant="soft" tone="success" label={`남은 변경 ${review.remaining}곳`} />
+                  </span>
+                )}
+                <Button size="sm" variant="ghost" iconOnly icon={<ChevronLeft />} aria-label="이전 변경" onClick={review.prev} disabled={done} />
+                <Button size="sm" variant="ghost" iconOnly icon={<ChevronRight />} aria-label="다음 변경" onClick={review.next} disabled={done} />
+              </Inline>
+              <Inline gap={2} wrap={false}>
+                {done ? (
+                  <Button size="sm" variant="ghost" onClick={review.reset}>
+                    처음부터 다시
+                  </Button>
+                ) : (
+                  <>
+                    <Button size="sm" variant="secondary" onClick={() => decideAll('rejected')}>
+                      모두 거절
+                    </Button>
+                    <Button size="sm" variant="primary" onClick={() => decideAll('accepted')}>
+                      모두 수락
+                    </Button>
+                  </>
+                )}
+              </Inline>
+            </Inline>
+            <InlineDiff review={review} variant="body-md" aria-label="이사회 메모 본문" />
+          </Stack>
+        </CardBody>
+      </Card>
+    </CardFrame>
+  )
+}
+```
+
+### 읽기 전용
+
+reviewable 없이 changes만 주면 보여 주기만 해요. changeId로 삭제와 추가를 직접 짝지을 수 있어요(추가만 있는 변경도 가능).
+
+```tsx
+import { Stack, Text, InlineDiff, type DiffSegment } from '@iamfiro/design'
+
+// changeId pairs a delete with its insert explicitly.
+const changes: DiffSegment[] = [
+  { type: 'equal', text: '제3조(계약 기간) 이 계약의 기간은 체결일로부터 ' },
+  { type: 'delete', text: '1년', changeId: 'term' },
+  { type: 'insert', text: '2년', changeId: 'term' },
+  { type: 'equal', text: '으로 하며, 어느 한쪽이 만료 ' },
+  { type: 'delete', text: '30일', changeId: 'notice' },
+  { type: 'insert', text: '60일', changeId: 'notice' },
+  { type: 'equal', text: ' 전까지 서면으로 해지 의사를 알리지 않으면 같은 조건으로 ' },
+  { type: 'insert', text: '1년씩 ', changeId: 'renew' },
+  { type: 'equal', text: '자동 연장한다.' },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={2} style={{ width: '100%', maxWidth: 440 }}>
+      <Text variant="label-sm" tone="secondary">
+        공급 계약서 · 이도현 님이 10월 25일에 고침
+      </Text>
+      <InlineDiff changes={changes} aria-label="제3조 변경 내용" />
+    </Stack>
+  )
+}
+```
+
+### before / after 문자열
+
+두 문자열을 주면 단어 단위로 비교해요(공백 · 한글 단어를 그대로 지키는 LCS). 결정은 decisions + onDecisionsChange로 제어하고, applyDiffDecisions로 결정이 반영된 글을 얻어요.
+
+```tsx
+import { useState } from 'react'
+import { Box, Stack, DescriptionSection, InlineDiff, applyDiffDecisions, diffWords, type DiffDecisions } from '@iamfiro/design'
+
+const before = '회의는 다음주 월요일 오전 10시에 진행 됩니다. 참석 여부를 금요일 까지 알려주세요.'
+const after = '회의는 다음 주 월요일 오전 10시에 진행됩니다. 참석 여부는 금요일까지 알려 주세요.'
+// The same word diff InlineDiff makes from before / after, for the result preview below.
+const segments = diffWords(before, after)
+
+export default function Example() {
+  const [decisions, setDecisions] = useState<DiffDecisions>({})
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 440 }}>
+      <InlineDiff before={before} after={after} reviewable decisions={decisions} onDecisionsChange={setDecisions} aria-label="맞춤법 교정" />
+      <Box background="subtle" radius="md" padding={3}>
+        <DescriptionSection title="결과 (아직 고르지 않은 곳은 원문)">{applyDiffDecisions(segments, decisions, 'before')}</DescriptionSection>
+      </Box>
+    </Stack>
+  )
+}
+```