@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/tree-diagram/AGENTS.md

@@ -0,0 +1,260 @@
+# TreeDiagram
+
+> 데이터 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+조직도 · 작업 분해처럼 위계를 상자와 연결선으로 그려요. 루트 아래 자식이 한 줄로 놓이고, 깊은 단계는 부모 아래 들여쓴 목록으로 매달 수 있어요. 연결선은 실제 노드 상자를 재서 그리기 때문에 상자 크기가 바뀌거나 접고 펼 때도 따라가요. 노드 모양은 renderNode로 직접(보통 Card) 그리고, 넓어지면 가로로 스크롤돼요.
+
+```tsx
+import { TreeDiagram, TreeDiagramToggle } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 위계(부모 → 자식): 들여쓴 행이면 `TreeView`(WAI-ARIA tree, roving tabindex, typeahead는 `TIMING.typeahead`), 상자 + 연결선이면 `TreeDiagram`(노드는 `renderNode`로 Card 조립, 접기 토글은 `state.toggle`).
+
+## API
+
+### TreeDiagram
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `items` (필수) | `TreeDiagramNode<T>[]` |  | 루트 노드(보통 하나). 여러 개면 나란히 놓여요. |
+| `renderNode` (필수) | `(node, state: TreeDiagramNodeState) => ReactNode` |  | 노드 상자. 보통 Card + Avatar · Text · Badge와 state.toggle. |
+| `collapsed / defaultCollapsed` | `string[]` |  | 접힌 노드 id(제어 / 비제어). |
+| `onCollapsedChange` | `(ids: string[]) => void` |  | 접힘이 바뀔 때. |
+| `indentFrom` | `number` |  | 이 깊이 이상인 노드는 하위를 들여쓴 목록으로(0 = 루트). 노드의 childLayout이 우선해요. |
+| `gap` | `Space` | `4` | 한 줄에 놓인 형제 사이 간격. 들여쓴 목록은 그 절반. |
+| `levelGap` | `Space` | `8` | 부모와 아래 줄 사이 세로 간격. |
+| `indent` | `Space` | `8` | 들여쓴 목록이 부모보다 오른쪽으로 들어가는 폭. |
+| `nodeWidth` | `number \| string` |  | 모든 노드 상자의 고정 폭. 줄이 반듯해져요. |
+| `aria-label` | `string` |  | 다이어그램의 접근성 이름. |
+| `className / style` | `string / CSSProperties` |  | 스크롤되는 바깥 요소에 전달. |
+
+### TreeDiagramNode<T>
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `id` (필수) | `string` |  | 다이어그램 전체에서 고유. |
+| `data` | `T` |  | renderNode에서 쓸 값. |
+| `children` | `TreeDiagramNode<T>[]` |  | 하위 노드. |
+| `childLayout` | `'row' \| 'indented'` |  | 하위 배치. row: 한 단계 아래 한 줄로(가로 연결선) · indented: 아래로 들여쓴 목록(왼쪽 꺾은 연결선). indented 노드의 하위도 기본으로 indented. |
+
+### TreeDiagramNodeState
+
+renderNode의 두 번째 인자.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `depth` | `number` |  | 깊이(루트 0). |
+| `childCount` | `number` |  | 직계 하위 수. |
+| `collapsed / setCollapsed` | `boolean / (next: boolean) => void` |  | 이 노드의 접힘 상태와 변경 함수. |
+| `toggle` | `ReactNode` |  | 이 노드에 연결된 "3 ⌄" 토글. 하위가 없으면 null. |
+| `childLayout` | `'row' \| 'indented'` |  | 이 노드의 하위 배치. |
+
+### TreeDiagramToggle
+
+하위 수 + 셰브런. state.toggle로 충분하지 않을 때 직접 배치해요. 눌러도 감싼 카드의 클릭으로 번지지 않아요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `count` (필수) | `number` |  | 하위 수. |
+| `collapsed` (필수) | `boolean` |  | 접힘 상태(셰브런 방향 · aria-expanded). |
+| `onToggle` (필수) | `() => void` |  | 눌렀을 때. |
+| `aria-controls / aria-label` | `string` |  | 접히는 영역 id / 접근성 이름(기본 "하위 3개 접기"). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 조직도
+
+대표 아래 팀장이 한 줄로, indentFrom={1}로 팀원은 팀장 아래 목록으로 매달려요. state.toggle("3 ⌄")을 CardHeader actions에 넣으면 하위를 접고 펴요. defaultCollapsed로 처음부터 접어 둘 수 있어요.
+
+```tsx
+import { Avatar, Inline, Stack, Text, Card, CardHeader, TreeDiagram, type TreeDiagramNode } from '@iamfiro/design'
+
+interface Person {
+  name: string
+  role: string
+}
+
+const p = (id: string, name: string, role: string, children?: TreeDiagramNode<Person>[]): TreeDiagramNode<Person> => ({ id, data: { name, role }, children })
+
+const ORG = [
+  p('ceo', '최유진', '대표', [
+    p('design', '김민지', '디자인 팀장', [p('d1', '박서연', '프로덕트 디자이너'), p('d2', '정하늘', 'UX 리서처'), p('d3', '윤채원', '브랜드 디자이너')]),
+    p('dev', '이도현', '개발 팀장', [p('e1', '한지우', '프론트엔드 개발'), p('e2', '오세훈', '백엔드 개발')]),
+    p('biz', '장예린', '사업 팀장', [p('b1', '강태오', '영업'), p('b2', '서지민', '마케팅'), p('b3', '문가은', '고객 지원')]),
+  ]),
+]
+
+export default function Example() {
+  return (
+    <TreeDiagram
+      aria-label="조직도"
+      items={ORG}
+      indentFrom={1}
+      nodeWidth={220}
+      defaultCollapsed={['biz']}
+      renderNode={(node, state) => (
+        <Card padding="sm">
+          <CardHeader actions={state.toggle}>
+            <Inline gap={3} wrap={false}>
+              <Avatar name={node.data?.name ?? ''} size={32} />
+              <Stack gap={0} style={{ minWidth: 0 }}>
+                <Text variant="label-md" truncate>
+                  {node.data?.name}
+                </Text>
+                <Text variant="caption" tone="tertiary" truncate>
+                  {node.data?.role}
+                </Text>
+              </Stack>
+            </Inline>
+          </CardHeader>
+        </Card>
+      )}
+    />
+  )
+}
+```
+
+### 작업 분해 (제어)
+
+collapsed / onCollapsedChange로 제어해 모두 펼치기 · 단계만 보기 버튼을 만들었어요. 상태는 Badge, 깊이에 따라 제목 크기를 바꿨어요.
+
+```tsx
+import { useState } from 'react'
+import { Badge, Button, Inline, Stack, Text, type Tone, Card, CardHeader, TreeDiagram, type TreeDiagramNode } from '@iamfiro/design'
+
+interface Task {
+  title: string
+  owner: string
+  status: '완료' | '진행 중' | '대기'
+}
+
+const TONE: Record<Task['status'], Tone> = { 완료: 'success', '진행 중': 'accent', 대기: 'neutral' }
+
+const t = (id: string, title: string, owner: string, status: Task['status'], children?: TreeDiagramNode<Task>[]): TreeDiagramNode<Task> => ({
+  id,
+  data: { title, owner, status },
+  children,
+})
+
+const PROJECT = [
+  t('app', '모바일 앱 리뉴얼', '김민지', '진행 중', [
+    t('plan', '기획', '최유진', '완료', [t('plan-1', '요구사항 정리', '최유진', '완료'), t('plan-2', '경쟁 서비스 분석', '장예린', '완료')]),
+    t('design', '디자인', '박서연', '진행 중', [t('design-1', '와이어프레임', '박서연', '완료'), t('design-2', '시각 디자인', '윤채원', '진행 중'), t('design-3', '사용성 테스트', '정하늘', '대기')]),
+    t('build', '개발', '이도현', '대기', [t('build-1', '화면 개발', '한지우', '대기'), t('build-2', 'API 연동', '오세훈', '대기')]),
+  ]),
+]
+
+const PARENTS = ['app', 'plan', 'design', 'build']
+
+export default function Example() {
+  const [collapsed, setCollapsed] = useState<string[]>(['plan'])
+  return (
+    <Stack gap={3}>
+      <Inline justify="between">
+        <Text variant="label-md">작업 분해</Text>
+        <Inline gap={1}>
+          <Button variant="ghost" size="sm" onClick={() => setCollapsed([])}>
+            모두 펼치기
+          </Button>
+          <Button variant="ghost" size="sm" onClick={() => setCollapsed(PARENTS.slice(1))}>
+            단계만 보기
+          </Button>
+        </Inline>
+      </Inline>
+      <TreeDiagram
+        aria-label="모바일 앱 리뉴얼 작업 분해"
+        items={PROJECT}
+        collapsed={collapsed}
+        onCollapsedChange={setCollapsed}
+        indentFrom={1}
+        nodeWidth={200}
+        renderNode={(node, state) => {
+          const task = node.data
+          if (!task) return null
+          return (
+            <Card padding="sm">
+              <CardHeader actions={state.toggle}>
+                <Stack gap={1}>
+                  <Text variant={state.depth === 0 ? 'heading-xs' : 'label-md'} truncate>
+                    {task.title}
+                  </Text>
+                  <Inline gap={2} wrap={false}>
+                    <Badge tone={TONE[task.status]} dot>
+                      {task.status}
+                    </Badge>
+                    <Text variant="caption" tone="tertiary" truncate>
+                      {task.owner}
+                    </Text>
+                  </Inline>
+                </Stack>
+              </CardHeader>
+            </Card>
+          )
+        }}
+      />
+    </Stack>
+  )
+}
+```
+
+### 노드별 배치 · 크기 변화
+
+childLayout: 'indented'를 준 노드만 하위를 목록으로 매달아요. 페이지를 추가하면 상자와 연결선이 함께 자라요.
+
+```tsx
+import { useState } from 'react'
+import { Plus } from 'lucide-react'
+import { Button, Stack, Text, Card, CardHeader, TreeDiagram, type TreeDiagramNode } from '@iamfiro/design'
+
+interface Page {
+  title: string
+  path: string
+}
+
+const page = (id: string, title: string, path: string, children?: TreeDiagramNode<Page>[]): TreeDiagramNode<Page> => ({ id, data: { title, path }, children })
+
+const EXTRA = ['공지사항', '이용 안내', '환불 정책', '제휴 문의']
+
+export default function Example() {
+  const [added, setAdded] = useState(0)
+  const support = [page('faq', '자주 묻는 질문', '/support/faq'), ...EXTRA.slice(0, added).map((title, i) => page(`extra-${i}`, title, `/support/${i + 1}`))]
+  const site = [
+    page('home', '홈', '/', [
+      page('products', '제품', '/products', [page('new', '신제품', '/products/new'), page('best', '인기 상품', '/products/best')]),
+      // This one hangs its pages as a list, the others stay in rows.
+      { ...page('support', '고객 지원', '/support', support), childLayout: 'indented' as const },
+      page('about', '회사 소개', '/about', [page('team', '팀', '/about/team'), page('careers', '채용', '/about/careers')]),
+    ]),
+  ]
+  return (
+    <Stack gap={3} align="start">
+      <Button size="sm" icon={<Plus />} disabled={added === EXTRA.length} onClick={() => setAdded((n) => n + 1)}>
+        고객 지원에 페이지 추가
+      </Button>
+      <TreeDiagram
+        aria-label="사이트맵"
+        items={site}
+        gap={3}
+        levelGap={6}
+        style={{ alignSelf: 'stretch' }}
+        renderNode={(node, state) => (
+          <Card padding="sm" style={{ minWidth: 140 }}>
+            <CardHeader actions={state.toggle}>
+              <Stack gap={0}>
+                <Text variant="label-md">{node.data?.title}</Text>
+                <Text variant="code" tone="tertiary">
+                  {node.data?.path}
+                </Text>
+              </Stack>
+            </CardHeader>
+          </Card>
+        )}
+      />
+    </Stack>
+  )
+}
+```

package/agents/tree-view/AGENTS.md

@@ -0,0 +1,329 @@
+# TreeView
+
+> 내비게이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+단계별로 들여쓴 행을 접고 펴는 트리. 폴더 · 파일, 작업 분해, 사이트맵처럼 위아래 관계가 있는 행에 써요. 행 모양은 List와 같고(앞 아이콘 · 굵은 이름 · 잘리는 회색 설명 · 뒤 자리), 하위 항목은 실제 높이만큼 부드럽게 펼쳐져요. 행 높이가 고정이라 옆에 일정 막대 같은 것을 행 단위로 맞춰 그릴 수 있어요.
+
+```tsx
+import { TreeItem, TreeView, flattenTree, TREE_ROW_HEIGHT } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 위계(부모 → 자식): 들여쓴 행이면 `TreeView`(WAI-ARIA tree, roving tabindex, typeahead는 `TIMING.typeahead`), 상자 + 연결선이면 `TreeDiagram`(노드는 `renderNode`로 Card 조립, 접기 토글은 `state.toggle`).
+
+## API
+
+### TreeView
+
+키보드: ↑ ↓ 이동 · → 펼치기 / 첫 하위로 · ← 접기 / 부모로 · Home / End · Enter / Space 선택 · * 형제 모두 펼치기 · 글자 입력으로 이동(typeahead). 탭 순서에는 한 행만 들어가요(roving tabindex).
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `items` | `TreeNode<T>[]` |  | 데이터로 그릴 노드. 없으면 children의 TreeItem을 읽어요. |
+| `children` | `ReactNode` |  | items 대신 중첩한 TreeItem. |
+| `expanded / defaultExpanded` | `string[]` |  | 펼친 노드 id(제어 / 비제어). |
+| `onExpandedChange` | `(ids: string[]) => void` |  | 펼침이 바뀔 때. |
+| `selected / defaultSelected` | `string \| null` |  | 선택한 노드 id(제어 / 비제어). null = 제어 중, 선택 없음. |
+| `onSelectedChange` | `(id: string \| null) => void` |  | 선택이 바뀔 때. |
+| `selectionMode` | `'single' \| 'none'` | `'single'` | none이면 선택 없이 펼치고 접기만 해요. |
+| `expandOnClick` | `boolean` | `selectionMode === 'none'` | 부모 행을 누르면 펼침도 바꿔요(파일 탐색기). 아니면 셰브런으로만. |
+| `onAction` | `(node: TreeNode<T>) => void` |  | 행을 누르거나 Enter / Space를 눌렀을 때. |
+| `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | 행 높이 32 / 40 / 48. |
+| `rowHeight` | `number` |  | density의 행 높이를 덮어써요(px). |
+| `indent` | `Space` | `6` | 단계마다 들여쓰는 폭(4px 단위). 기본 24px이면 하위 셰브런이 부모 아이콘 아래 와요. |
+| `guides` | `boolean` |  | 열린 부모 아래 옅은 세로 안내선. |
+| `animated` | `boolean` | `true` | 하위 항목 접고 펴기 애니메이션. 옆 차트가 행 위치를 바로 따라가야 하면 끄세요. |
+| `renderItem` | `(node, state: TreeItemState) => ReactNode` |  | 이름 + 설명 자리를 직접 그려요. leading / trailing은 노드 값 그대로. |
+| `onVisibleChange` | `(rows: TreeRow<T>[]) => void` |  | 보이는 행이 바뀔 때마다 순서대로(펼침 · 접힘 · 데이터 변경). |
+| `aria-label / aria-labelledby` | `string` |  | 트리의 접근성 이름. |
+| `className / style` | `string / CSSProperties` |  | 바깥 ul에 전달. |
+
+### TreeNode<T> · TreeItem
+
+items의 노드 모양. TreeItem은 같은 props(+ 중첩 children)를 JSX로 받아요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `id` (필수) | `string` |  | 트리 전체에서 고유. |
+| `label` (필수) | `ReactNode` |  | 굵은 이름. |
+| `description` | `ReactNode` |  | 이름 뒤 회색 글자. 자리가 모자라면 먼저 잘려요. |
+| `leading` | `ReactNode` |  | 이름 앞 아이콘 · 아바타 · 파일 아이콘. |
+| `trailing` | `ReactNode` |  | 오른쪽: 기간, 개수, Spinner 등. |
+| `disabled` | `boolean` |  | 흐리게. 포커스는 되지만 선택 · 펼침은 안 돼요. |
+| `textValue` | `string` |  | label이 문자열이 아닐 때 typeahead가 읽을 글자. |
+| `children` | `TreeNode<T>[]` |  | 하위 노드. |
+| `data` | `T` |  | renderItem · 콜백에서 다시 꺼내 쓸 값. |
+
+### flattenTree · TreeRow · TREE_ROW_HEIGHT
+
+flattenTree(items, expanded)는 보이는 행을 위에서부터 돌려줘요. TREE_ROW_HEIGHT는 density별 행 높이 { compact: 32, default: 40, comfortable: 48 }.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `id / node` | `string / TreeNode<T>` |  | 행의 노드. |
+| `index` | `number` |  | 보이는 목록에서의 위치(0부터). × 행 높이 = 행의 top. |
+| `depth` | `number` |  | 단계(맨 위 0). |
+| `parentId` | `string \| null` |  | 부모 id. |
+| `hasChildren / expanded` | `boolean` |  | 하위가 있는지 / 펼쳐져 있는지. |
+| `posinset / setsize` | `number` |  | 형제 중 순서(1부터) / 형제 수. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 파일 탐색기
+
+expandOnClick으로 폴더 행을 누르면 펼쳐져요. guides는 열린 폴더 아래 옅은 세로선을 그려요. 펼침과 선택을 모두 제어(expanded · selected)해 폴더 아이콘을 바꿨어요.
+
+```tsx
+import { useState } from 'react'
+import { Folder, FolderOpen } from 'lucide-react'
+import { FileIcon, Stack, Text, TreeView, type TreeNode } from '@iamfiro/design'
+
+const file = (id: string, name: string, meta: string): TreeNode => ({ id, label: name, leading: <FileIcon name={name} size={16} />, trailing: meta })
+
+const ITEMS: TreeNode[] = [
+  {
+    id: 'design',
+    label: '디자인',
+    children: [
+      file('design/landing', '랜딩 페이지 시안.png', '5.1MB'),
+      file('design/guide', '브랜드 가이드.pdf', '12MB'),
+      {
+        id: 'design/icons',
+        label: '아이콘',
+        children: [file('design/icons/set', '아이콘 세트.zip', '3.2MB'), file('design/icons/note', '사용 규칙.docx', '84KB')],
+      },
+    ],
+  },
+  {
+    id: 'plan',
+    label: '기획',
+    children: [file('plan/q4', '4분기 로드맵.pptx', '8.4MB'), file('plan/research', '사용자 인터뷰 정리.docx', '220KB')],
+  },
+  {
+    id: 'finance',
+    label: '재무',
+    children: [file('finance/sales', '10월 매출 정리.xlsx', '860KB'), file('finance/budget', '2027 예산안.xlsx', '1.1MB')],
+  },
+  file('readme', '폴더 안내.txt', '2KB'),
+]
+
+// Open folders show an open-folder icon.
+const withFolderIcons = (nodes: TreeNode[], open: string[]): TreeNode[] =>
+  nodes.map((n) => (n.children ? { ...n, leading: open.includes(n.id) ? <FolderOpen /> : <Folder />, children: withFolderIcons(n.children, open) } : n))
+
+export default function Example() {
+  const [expanded, setExpanded] = useState<string[]>(['design'])
+  const [selected, setSelected] = useState<string | null>('design/landing')
+  return (
+    <Stack gap={3} style={{ width: 420 }}>
+      <TreeView
+        aria-label="공유 폴더"
+        items={withFolderIcons(ITEMS, expanded)}
+        expanded={expanded}
+        onExpandedChange={setExpanded}
+        selected={selected}
+        onSelectedChange={setSelected}
+        expandOnClick
+        guides
+      />
+      <Text variant="caption" tone="tertiary">
+        선택: {selected ?? '없음'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 작업 분해
+
+trailing에 기간이나 Spinner, description에 잘리는 설명. 아직 시작하지 않은 작업은 disabled로 흐리게 — 포커스는 가지만 선택 · 펼침은 안 돼요.
+
+```tsx
+import { CircleCheck, CircleDashed, CircleDot } from 'lucide-react'
+import { Spinner, TreeView, type TreeNode } from '@iamfiro/design'
+
+const done = <CircleCheck color="var(--success)" />
+const doing = <CircleDot color="var(--accent)" />
+const todo = <CircleDashed />
+
+const ITEMS: TreeNode[] = [
+  {
+    id: 'launch',
+    label: '신규 서비스 출시',
+    description: '10월 1일 – 11월 7일',
+    leading: doing,
+    trailing: '38일',
+    children: [
+      {
+        id: 'research',
+        label: '사용자 조사',
+        description: '인터뷰 12명, 설문 340건 분석',
+        leading: done,
+        trailing: '6일',
+        children: [
+          { id: 'interview', label: '심층 인터뷰', description: '김민지 · 박서연', leading: done, trailing: '4일' },
+          { id: 'survey', label: '설문 분석', description: '응답 340건, 주요 불편 5가지 정리', leading: done, trailing: '2일' },
+        ],
+      },
+      {
+        id: 'design',
+        label: '디자인',
+        description: '와이어프레임부터 최종 시안까지',
+        leading: doing,
+        trailing: '12일',
+        children: [
+          { id: 'wire', label: '와이어프레임', description: '핵심 화면 8개', leading: done, trailing: '3일' },
+          { id: 'visual', label: '시각 디자인', description: '디자인 시스템 컴포넌트로 조립 중', leading: doing, trailing: <Spinner size={14} label="진행 중" /> },
+        ],
+      },
+      {
+        id: 'build',
+        label: '개발',
+        description: '디자인 확정 후 시작',
+        leading: todo,
+        trailing: '14일',
+        disabled: true,
+        children: [
+          { id: 'front', label: '프론트엔드', leading: todo, trailing: '9일', disabled: true },
+          { id: 'back', label: '백엔드 API', leading: todo, trailing: '5일', disabled: true },
+        ],
+      },
+      { id: 'qa', label: 'QA · 출시', description: '11월 4일부터', leading: todo, trailing: '4일', disabled: true },
+    ],
+  },
+]
+
+export default function Example() {
+  return <TreeView aria-label="출시 작업" items={ITEMS} defaultExpanded={['launch', 'design']} defaultSelected="visual" style={{ width: 520 }} />
+}
+```
+
+### TreeItem으로 쓰기 · 모두 펼치기
+
+items 대신 TreeItem을 중첩해 JSX로 적을 수 있어요. selectionMode="none"이면 행을 눌러 펼치고 접기만 해요.
+
+```tsx
+import { useState } from 'react'
+import { FileText, House, Settings, ShoppingBag, Users } from 'lucide-react'
+import { Button, Inline, Stack, Text, TreeItem, TreeView } from '@iamfiro/design'
+
+const PARENTS = ['home', 'products', 'about', 'support']
+
+export default function Example() {
+  const [expanded, setExpanded] = useState<string[]>(['home'])
+  const allOpen = expanded.length === PARENTS.length
+  return (
+    <Stack gap={3} style={{ width: 440 }}>
+      <Inline justify="between">
+        <Text variant="label-md">사이트맵</Text>
+        <Button variant="ghost" size="sm" onClick={() => setExpanded(allOpen ? [] : PARENTS)}>
+          {allOpen ? '모두 접기' : '모두 펼치기'}
+        </Button>
+      </Inline>
+      <TreeView aria-label="사이트맵" expanded={expanded} onExpandedChange={setExpanded} selectionMode="none" density="compact">
+        <TreeItem id="home" label="홈" description="/" leading={<House />}>
+          <TreeItem id="products" label="제품" description="/products" leading={<ShoppingBag />}>
+            <TreeItem id="products/new" label="신제품" description="/products/new" leading={<FileText />} />
+            <TreeItem id="products/best" label="인기 상품" description="/products/best" leading={<FileText />} />
+            <TreeItem id="products/sale" label="할인 행사" description="/products/sale · 11월 1일 공개" leading={<FileText />} disabled />
+          </TreeItem>
+          <TreeItem id="about" label="회사 소개" description="/about" leading={<Users />}>
+            <TreeItem id="about/team" label="팀" description="/about/team" leading={<FileText />} />
+            <TreeItem id="about/careers" label="채용" description="/about/careers" leading={<FileText />} />
+          </TreeItem>
+          <TreeItem id="support" label="고객 지원" description="/support" leading={<Settings />}>
+            <TreeItem id="support/faq" label="자주 묻는 질문" description="/support/faq" leading={<FileText />} />
+            <TreeItem id="support/contact" label="문의하기" description="/support/contact" leading={<FileText />} />
+          </TreeItem>
+        </TreeItem>
+      </TreeView>
+    </Stack>
+  )
+}
+```
+
+### 밀도
+
+density로 행 높이를 compact(32) · default(40) · comfortable(48) 중에 골라요. 행 좌우 여백은 List와 같아요.
+
+```tsx
+import { useState } from 'react'
+import { Avatar, SegmentedControl, Stack, TreeView, type TreeDensity, type TreeNode } from '@iamfiro/design'
+
+const person = (id: string, name: string, role: string, children?: TreeNode[]): TreeNode => ({
+  id,
+  label: name,
+  description: role,
+  leading: <Avatar name={name} size={20} />,
+  children,
+})
+
+const ITEMS = [
+  person('ceo', '최유진', '대표', [
+    person('lead-1', '김민지', '디자인 팀장', [person('m-1', '박서연', '프로덕트 디자이너'), person('m-2', '정하늘', 'UX 리서처')]),
+    person('lead-2', '이도현', '개발 팀장', [person('m-3', '한지우', '프론트엔드'), person('m-4', '오세훈', '백엔드')]),
+  ]),
+]
+
+export default function Example() {
+  const [density, setDensity] = useState<TreeDensity>('default')
+  return (
+    <Stack gap={4} align="start" style={{ width: 420 }}>
+      <SegmentedControl
+        ariaLabel="행 높이"
+        value={density}
+        onChange={setDensity}
+        options={[
+          { value: 'compact', label: 'compact' },
+          { value: 'default', label: 'default' },
+          { value: 'comfortable', label: 'comfortable' },
+        ]}
+      />
+      <TreeView aria-label="조직" items={ITEMS} density={density} defaultExpanded={['ceo', 'lead-1']} guides style={{ alignSelf: 'stretch' }} />
+    </Stack>
+  )
+}
+```
+
+### 보이는 행 (옆에 차트 맞추기)
+
+onVisibleChange는 보이는 행을 순서대로 알려 줘요. 행 높이(TREE_ROW_HEIGHT 또는 rowHeight) × index가 그 행의 위치예요. 데이터만 있을 땐 flattenTree(items, expanded)로 같은 목록을 얻어요.
+
+```tsx
+import { useState } from 'react'
+import { Stack, Text, TREE_ROW_HEIGHT, TreeView, type TreeNode, type TreeRow } from '@iamfiro/design'
+
+const ITEMS: TreeNode[] = [
+  {
+    id: 'web',
+    label: '웹사이트 개편',
+    trailing: '21일',
+    children: [
+      { id: 'web/ia', label: '정보 구조 정리', trailing: '3일' },
+      { id: 'web/design', label: '화면 디자인', trailing: '8일', children: [{ id: 'web/design/main', label: '메인', trailing: '3일' }, { id: 'web/design/sub', label: '하위 페이지', trailing: '5일' }] },
+      { id: 'web/dev', label: '개발', trailing: '10일' },
+    ],
+  },
+  { id: 'app', label: '앱 업데이트', trailing: '9일', children: [{ id: 'app/push', label: '알림 설정 개선', trailing: '4일' }, { id: 'app/login', label: '간편 로그인', trailing: '5일' }] },
+]
+
+export default function Example() {
+  const [rows, setRows] = useState<TreeRow[]>([])
+  const h = TREE_ROW_HEIGHT.default
+  return (
+    <Stack gap={3} style={{ width: 460 }}>
+      {/* animated={false}: rows move at once, so whatever is drawn beside them can follow without lagging. */}
+      <TreeView aria-label="프로젝트 일정" items={ITEMS} defaultExpanded={['web']} animated={false} onVisibleChange={setRows} />
+      <Text variant="caption" tone="tertiary" numeric>
+        보이는 행 {rows.length}개 · 행 높이 {h}px · 전체 {rows.length * h}px
+      </Text>
+      <Text variant="caption" tone="tertiary" numeric>
+        {rows.map((r) => `${r.index * h}px ${'·'.repeat(r.depth)}${typeof r.node.label === 'string' ? r.node.label : r.id}`).join('  /  ')}
+      </Text>
+    </Stack>
+  )
+}
+```