@iamfiro/design 0.0.0-stage → 0.1.0

package/agents/timeline/AGENTS.md

@@ -0,0 +1,1018 @@
+# Timeline
+
+> 대화 & 활동 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+숫자 구간(초, 분, 시각)을 가로 위치로 옮겨 그리는 시간 축. 위에는 눈금자와 아주 옅은 세로 그리드, 왼쪽에는 이름 칸, 오른쪽 트랙에는 구간 막대가 놓여요. 지금 위치(now)와 세로 표시선(markers)이 모든 행을 가로지르고, 막대는 처음에 시작점부터 쓸려 나오며 값이 바뀌면 새 위치·길이로 미끄러져요. 계획 대비 실제 일정표, 단계별 소요 시간(워터폴), 하루 일정에 써요.
+
+```tsx
+import { Timeline, TimelineRow, TimelineBar, formatClock, formatOffset } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 시간 축(계획 대비 실제, 워터폴, 하루 일정)은 `Timeline` + `TimelineRow` + `TimelineBar`로. 계획 = 점선 틀(`outline`), 실제 = 옅은 색 막대(`fill`), 계획 초과 = 주황(`limit`), 아직 = `faded` 행. 지금은 파란 `now` 선, 목표·예상은 `markers`(점선/실선 + 아래 Badge 칩 + 옅은 `band`). 진행 중 막대는 `running`(앞 가장자리 + shimmer). 범례 색 표시는 같은 옅기의 `ColorDot variant="soft" | "dashed" | "hatched"`.
+
+## API
+
+### Timeline
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `max` (필수) | `number` |  | 축의 끝. 가장 긴 막대 뒤 label이 들어갈 여유를 두세요. |
+| `min` | `number` | `0` | 축의 시작. |
+| `step` | `number` |  | 눈금 간격. 생략하면 눈금이 6개쯤 되는 둥근 값(1·2·5×10ⁿ). |
+| `ticks` | `number[]` |  | step 대신 눈금 위치를 직접 지정. |
+| `formatTick` | `(value) => string` | `String` | 눈금·툴팁·스크린 리더 문구의 값 형식. m:ss는 formatClock. |
+| `grid` | `boolean` | `true` | 눈금마다 아주 옅은 세로선. |
+| `now` | `number` |  | 눈금자 위 점 + 모든 행을 지나는 파란 선. |
+| `nowLabel` | `ReactNode` |  | 점 대신 눈금자에 놓는 작은 파란 칩("지금"). 같은 위치의 눈금 글자는 비켜 줘요. |
+| `nowLine` | `boolean` | `true` | now 선을 행 위로 그릴지. false면 눈금자 칩만. |
+| `markers` | `TimelineMarker[]` |  | 세로 표시선. { value, tone?, line?, label?, labelSide?, band? } |
+| `links` | `TimelineLink[]` |  | 막대 사이 점선 곡선. { from, to, tone? } — TimelineBar의 id. 행과 막대가 직계 자식일 때 위치를 읽어요. |
+| `labelWidth` | `number` | `160` | 왼쪽 이름 칸 폭(px). 0이면 이름 칸 없음. |
+| `labelHeader` | `ReactNode` |  | 이름 칸 위, 눈금자와 같은 줄의 제목. |
+| `aside` | `ReactNode` |  | 행마다 이름 대신 이름 칸 전체를 채우는 내용(보통 같은 행 높이의 TreeView). 선택 배경은 그 뒤에 깔려요. |
+| `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | 행 높이 28 / 36 / 56px. comfortable은 두 줄 이름 · 내용 막대 레인용. |
+| `rowHeight` | `number` |  | density 대신 행 높이(px)를 직접. TreeView와 맞출 땐 TREE_ROW_HEIGHT. |
+| `aria-label` | `string` |  | 전체 그룹의 이름. |
+
+### TimelineMarker
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `number` |  | 선 위치. |
+| `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | 선·띠·칩 색. |
+| `line` | `'solid' \| 'dashed'` | `'dashed'` | dashed는 목표·계획, solid는 예상·사건. |
+| `label` | `ReactNode` |  | 행 아래 칩(Badge) 문구. |
+| `labelSide` | `'center' \| 'left' \| 'right'` | `'center'` | 칩이 선에서 어느 쪽으로 붙을지. |
+| `band` | `number` |  | value와 이 값 사이를 옅게 칠해요. |
+
+### TimelineRow
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` |  | 왼쪽 칸. 문자열이면 한 줄 label-sm으로 줄여 보여요. |
+| `leading` | `ReactNode` |  | 이름 앞 타일(IconTile · Avatar). 주면 두 줄 이름이 돼요. |
+| `description` | `ReactNode` |  | 이름 아래 옅은 둘째 줄. 길면 말줄임. |
+| `badge` | `ReactNode` |  | 이름 바로 뒤 상태 칸(Badge size="sm"). |
+| `count` | `number \| ReactNode` |  | 이름 칸 오른쪽 끝 회색 칩. 숫자면 "+5". |
+| `depth` | `number` | `0` | 이름 들여쓰기 단계(16px씩). 하위 구간에. |
+| `faded` | `boolean` |  | 앞으로 할·건너뛴 행: 회색으로 흐리게. |
+| `selected` | `boolean` |  | 이름 칸까지 행 전체에 옅은 파란 배경. |
+| `onSelect` | `() => void` |  | 행을 선택할 수 있게: 행 어디든(막대 포함) 클릭, 포커스 후 Enter · Space. |
+| `children` | `ReactNode` |  | TimelineBar들. 한 행에 겹쳐 그려요. |
+
+### TimelineBar
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `start / end` (필수) | `number` |  | 구간. |
+| `id` | `string` |  | Timeline links에서 이 막대를 가리키는 이름. |
+| `variant` | `'fill' \| 'outline' \| 'pending'` | `'fill'` | 옅은 색 막대 / 점선 틀(같은 크기 fill을 감싸요) / 회색 자리. |
+| `tone` | `'neutral' \| 'accent' \| 'purple' \| 'teal' \| 'success' \| 'warning' \| 'danger'` | `outline이면 'neutral', 아니면 'accent'` | 막대 색. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md', 내용 막대는 'xl'` | 두께 10 / 16 / 20 / 32px. |
+| `children` | `ReactNode` |  | 막대 안 글자. 주면 8px 모서리의 큰 막대가 되고 톤 색 글자, 넘치면 말줄임. |
+| `leading` | `ReactNode` |  | 막대 안 글자 앞(보통 IconStack). |
+| `action` | `ReactNode` |  | 막대 안 오른쪽 칸(Badge as="button", 흰 바탕으로). 따로 눌려요. |
+| `segments` | `TimelineBarSegment[]` |  | 이어지는 색 구간 { start, end, tone? }. variant="outline"이면 실선 틀 안에 얇게. |
+| `onClick` | `(event) => void` |  | 막대 전체를 버튼으로. 선택 가능한 행이면 클릭이 행 선택으로도 이어져요. |
+| `renderTarget` | `(target) => ReactNode` |  | 막대의 포커스 대상을 감싸요: (t) => <Popover trigger={t}>…</Popover>. 감싼 요소가 막대 위로 늘어나 팝오버가 막대에 붙어요. |
+| `ref` | `Ref<HTMLSpanElement>` |  | 막대 요소(트랙 위 위치) — 직접 띄우는 UI의 기준점으로. |
+| `limit` | `number` |  | 이 값을 넘긴 부분을 overTone으로 칠해요(계획 초과). |
+| `overTone` | `TimelineBarTone` | `'warning'` | 초과 부분 색. |
+| `running` | `boolean` |  | 진행 중: 앞쪽 가장자리가 빛나고 shimmer가 지나가요. 내용 막대는 왼쪽에서 옅게 시작해 진한 오른쪽 끝선으로. |
+| `label` | `ReactNode` |  | 막대 뒤 내용(소요 시간, Badge, Spinner). |
+| `labelAt` | `number` |  | label 시작 위치. 기본은 end, 계획 틀이 더 길면 그 끝을 넘겨요. |
+| `tooltip` | `ReactNode` |  | hover·포커스 말풍선(Tooltip). 주면 막대가 포커스를 받아요. |
+| `aria-label` | `string` |  | 스크린 리더 문구. 기본은 "시작 – 끝". |
+
+### formatClock / formatOffset / useTimelineScale
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `formatClock(seconds)` | `(number) => string` |  | 초를 시계 형식으로: 52 → "0:52", 3725 → "1:02:05". |
+| `formatOffset(unit?, zero?)` | `(unit, zero) => (number) => string` |  | 상대 축 눈금: formatOffset('분')이면 −25 → "−25분", 5 → "+5분", 0 → zero(기본 "0"). |
+| `useTimelineScale()` | `{ min, max, pct, formatValue }` |  | Timeline 안에서 값 → 0–100 위치를 직접 계산할 때(맞춤 표시). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+max와 step으로 눈금을, formatTick으로 표시 형식을 정해요. 막대 뒤 label 칸에 소요 시간을 적어요.
+
+```tsx
+import { Timeline, TimelineBar, TimelineRow } from '@iamfiro/design'
+
+const STEPS = [
+  { name: '코드 검사', start: 0, end: 4 },
+  { name: '단위 테스트', start: 4, end: 11 },
+  { name: '이미지 빌드', start: 4, end: 16 },
+  { name: '스테이징 배포', start: 16, end: 21 },
+]
+
+export default function Example() {
+  return (
+    <Timeline max={30} step={5} formatTick={(v) => `${v}s`} now={21} labelWidth={112} aria-label="배포 파이프라인 단계별 시간" style={{ width: '100%', maxWidth: 560 }}>
+      {STEPS.map((s) => (
+        <TimelineRow key={s.name} label={s.name}>
+          <TimelineBar start={s.start} end={s.end} tone="accent" label={`${s.end - s.start}s`} />
+        </TimelineRow>
+      ))}
+    </Timeline>
+  )
+}
+```
+
+### 막대 종류
+
+fill은 옅은 색 막대(실제), outline은 점선 틀(계획), pending은 아직 시작하지 않은 회색 자리. limit을 넘긴 부분은 주황(overTone)으로, running이면 앞쪽 가장자리가 빛나고 shimmer가 지나가요. tooltip을 주면 마우스·키보드 포커스로 말풍선이 떠요.
+
+```tsx
+import { Timeline, TimelineBar, TimelineRow } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Timeline max={100} step={20} formatTick={(v) => `${v}%`} labelWidth={120} density="compact" style={{ width: '100%', maxWidth: 560 }}>
+      <TimelineRow label="fill · accent">
+        <TimelineBar start={0} end={48} tone="accent" label="48%" />
+      </TimelineRow>
+      <TimelineRow label="fill · purple">
+        <TimelineBar start={10} end={62} tone="purple" label="52%" />
+      </TimelineRow>
+      <TimelineRow label="fill · neutral">
+        <TimelineBar start={0} end={80} tone="neutral" label="80%" />
+      </TimelineRow>
+      <TimelineRow label="outline (계획)">
+        <TimelineBar start={20} end={70} variant="outline" label="50%" />
+      </TimelineRow>
+      <TimelineRow label="계획 + 실제">
+        <TimelineBar start={20} end={60} variant="outline" />
+        <TimelineBar start={20} end={72} tone="purple" limit={60} label="초과 12%" />
+      </TimelineRow>
+      <TimelineRow label="pending">
+        <TimelineBar start={60} end={90} variant="pending" label="대기" />
+      </TimelineRow>
+      <TimelineRow label="running">
+        <TimelineBar start={0} end={56} tone="accent" running label="진행 중" />
+      </TimelineRow>
+      <TimelineRow label="size sm · md · lg">
+        <TimelineBar start={0} end={20} size="sm" tone="accent" />
+        <TimelineBar start={30} end={50} size="md" tone="accent" />
+        <TimelineBar start={60} end={80} size="lg" tone="accent" />
+      </TimelineRow>
+      <TimelineRow label="툴팁">
+        <TimelineBar start={10} end={45} tone="neutral" tooltip="10% – 45% · 마우스를 올리거나 Tab으로 포커스" label="올려 보세요" />
+      </TimelineRow>
+    </Timeline>
+  )
+}
+```
+
+### 계획 대비 실제
+
+점선 틀(계획) 위에 실제 막대를 겹치고, 계획 시간을 넘긴 부분은 주황으로 보여 줘요. 앞으로 할 단계는 faded로 흐리게. 점선 표시선은 계획 종료, 주황 띠와 선은 예상 종료예요. "15초 진행"을 누르면 막대와 표시선이 새 위치로 미끄러져요. 범례는 ColorDot의 dashed · soft 변형으로 만들어요.
+
+```tsx
+import { useState } from 'react'
+import { Badge, Button, ColorDot, Inline, Spinner, Stack, Text, Card, CardBody, CardHeader, formatClock, Timeline, TimelineBar, TimelineRow } from '@iamfiro/design'
+
+// 단계마다 계획한 시간과 실제로 걸린(걸릴) 시간, 초 단위.
+const STEPS = [
+  { name: '요구사항 정리', plan: 40, actual: 52 },
+  { name: '디자인 검토', plan: 45, actual: 41 },
+  { name: '기능 개발', plan: 55, actual: 63 },
+  { name: 'QA 테스트', plan: 20, actual: 24 },
+  { name: '릴리스 노트 작성', plan: 15, actual: 18 },
+]
+
+const PLAN_TOTAL = STEPS.reduce((sum, s) => sum + s.plan, 0)
+
+function schedule(now: number) {
+  let planAt = 0
+  let actualAt = 0
+  let eta = 0
+  const rows = STEPS.map((s) => {
+    const row = { ...s, planStart: planAt, start: actualAt }
+    planAt += s.plan
+    const status = actualAt + s.actual <= now ? 'done' : actualAt <= now ? 'running' : 'next'
+    const end = status === 'done' ? actualAt + s.actual : status === 'running' ? now : actualAt
+    // 끝나지 않은 단계는 계획만큼(이미 넘겼으면 지금까지) 걸린다고 보고 예상 종료를 계산해요.
+    eta = status === 'done' ? end : Math.max(eta, actualAt) + (status === 'running' ? Math.max(s.plan, now - actualAt) : s.plan)
+    actualAt = status === 'next' ? actualAt : status === 'running' ? Math.max(now, actualAt + s.plan) : end
+    return { ...row, status, end }
+  })
+  return { rows, eta }
+}
+
+function delta(seconds: number) {
+  return seconds > 0 ? `+${seconds}초` : seconds < 0 ? `−${Math.abs(seconds)}초` : '±0초'
+}
+
+export default function Example() {
+  const [now, setNow] = useState(150)
+  const { rows, eta } = schedule(now)
+  const late = eta > PLAN_TOTAL
+
+  return (
+    <Card style={{ width: '100%', maxWidth: 640 }}>
+      <CardHeader
+        title="릴리스 준비"
+        description={`계획 대비 실제 · ${STEPS.length}단계`}
+        actions={
+          <Inline gap={2}>
+            <Button size="sm" variant="ghost" onClick={() => setNow(0)}>
+              처음으로
+            </Button>
+            <Button size="sm" onClick={() => setNow((n) => Math.min(n + 15, 240))}>
+              15초 진행
+            </Button>
+          </Inline>
+        }
+      />
+      <CardBody>
+        <Stack gap={4}>
+          <Timeline
+            max={240}
+            step={30}
+            formatTick={formatClock}
+            now={now}
+            labelWidth={128}
+            aria-label="단계별 계획과 실제 소요 시간"
+            markers={[
+              { value: PLAN_TOTAL, line: 'dashed', label: `계획 ${formatClock(PLAN_TOTAL)}`, labelSide: late ? 'left' : 'center' },
+              ...(late ? [{ value: eta, tone: 'warning' as const, line: 'solid' as const, band: PLAN_TOTAL, label: `예상 ${formatClock(eta)}`, labelSide: 'right' as const }] : []),
+            ]}
+          >
+            {rows.map((r) => (
+              <TimelineRow key={r.name} label={r.name} faded={r.status === 'next'}>
+                <TimelineBar
+                  start={r.planStart}
+                  end={r.planStart + r.plan}
+                  variant="outline"
+                  label={
+                    r.status === 'next' ? (
+                      <Text variant="label-xs" tone="tertiary" numeric>
+                        {formatClock(r.plan)}
+                      </Text>
+                    ) : undefined
+                  }
+                />
+                {r.status !== 'next' && (
+                  <TimelineBar
+                    start={r.start}
+                    end={r.end}
+                    tone="purple"
+                    limit={r.start + r.plan}
+                    running={r.status === 'running'}
+                    labelAt={r.planStart + r.plan}
+                    tooltip={`실제 ${formatClock(r.end - r.start)} · 계획 ${formatClock(r.plan)}`}
+                    label={
+                      <>
+                        <Text variant="label-xs" numeric>
+                          {formatClock(r.end - r.start)}
+                        </Text>
+                        {r.status === 'running' ? (
+                          <Spinner size="xs" tone="muted" label="진행 중" />
+                        ) : (
+                          <Badge tone={r.actual > r.plan ? 'warning' : 'success'} square>
+                            {delta(r.actual - r.plan)}
+                          </Badge>
+                        )}
+                      </>
+                    }
+                  />
+                )}
+              </TimelineRow>
+            ))}
+          </Timeline>
+
+          <Inline gap={4}>
+            <Inline gap={2} wrap={false}>
+              <ColorDot color="--n8" variant="dashed" size={12} />
+              <Text variant="body-sm" tone="secondary">
+                계획
+              </Text>
+            </Inline>
+            <Inline gap={2} wrap={false}>
+              <ColorDot color="--chart-4" variant="soft" size={12} />
+              <Text variant="body-sm" tone="secondary">
+                실제
+              </Text>
+            </Inline>
+            <Inline gap={2} wrap={false}>
+              <ColorDot color="--chart-6" variant="soft" size={12} />
+              <Text variant="body-sm" tone="secondary">
+                계획 초과
+              </Text>
+            </Inline>
+          </Inline>
+        </Stack>
+      </CardBody>
+    </Card>
+  )
+}
+```
+
+### 워터폴
+
+부모 구간은 회색, 하위 구간은 depth로 들여 써요. 진행 중인 구간은 now까지 자라며 Spinner를 함께 보여 주고, 가장 오래 걸린 구간엔 Badge를 붙여요.
+
+```tsx
+import { useEffect, useState } from 'react'
+import { Badge, Button, Spinner, Text, Card, CardBody, CardHeader, Timeline, TimelineBar, TimelineRow, type TimelineBarTone } from '@iamfiro/design'
+
+interface Span {
+  name: string
+  start: number
+  /** 끝나지 않은 구간은 생략해요. */
+  end?: number
+  depth: number
+  tone: TimelineBarTone
+  detail?: string
+  slowest?: boolean
+}
+
+const SPANS: Span[] = [
+  { name: '배포 파이프라인', start: 0, depth: 0, tone: 'neutral' },
+  { name: '소스 가져오기', start: 0, end: 1.2, depth: 1, tone: 'accent', detail: '48MB' },
+  { name: '의존성 설치', start: 1.2, end: 8.1, depth: 1, tone: 'purple', detail: '312MB', slowest: true },
+  { name: '단위 테스트', start: 8.1, end: 14.6, depth: 1, tone: 'accent', detail: '1,284개' },
+  { name: '이미지 빌드', start: 8.4, end: 13.0, depth: 1, tone: 'purple', detail: '186MB' },
+  { name: '레지스트리 업로드', start: 14.6, depth: 1, tone: 'accent' },
+]
+
+const DONE_AT = 21.4
+const seconds = (v: number) => `${v.toFixed(1)}s`
+
+export default function Example() {
+  const [elapsed, setElapsed] = useState(16.2)
+  const running = elapsed < DONE_AT
+
+  useEffect(() => {
+    if (!running) return
+    const timer = setTimeout(() => setElapsed((t) => Math.min(DONE_AT, Number((t + 0.4).toFixed(1)))), 400)
+    return () => clearTimeout(timer)
+  }, [elapsed, running])
+
+  return (
+    <Card style={{ width: '100%', maxWidth: 640 }}>
+      <CardHeader
+        title="배포 #482"
+        description={running ? '진행 중' : `완료 · ${seconds(DONE_AT)}`}
+        actions={
+          <Button size="sm" onClick={() => setElapsed(14.6)} disabled={running}>
+            다시 실행
+          </Button>
+        }
+      />
+      <CardBody>
+        <Timeline max={25} step={5} formatTick={(v) => `${v}s`} now={elapsed} labelWidth={150} density="compact" aria-label="배포 단계별 소요 시간">
+          {SPANS.map((s) => {
+            const open = s.end === undefined
+            const end = s.end ?? elapsed
+            return (
+              <TimelineRow key={s.name} depth={s.depth} label={<Text variant={s.depth === 0 ? 'label-sm' : 'body-sm'} tone={s.depth === 0 ? 'default' : 'secondary'} truncate>{s.name}</Text>}>
+                <TimelineBar
+                  start={s.start}
+                  end={end}
+                  tone={s.tone}
+                  size={s.depth === 0 ? 'md' : 'sm'}
+                  running={open && running}
+                  tooltip={`${s.name} · ${seconds(end - s.start)}`}
+                  label={
+                    <>
+                      <Text variant="caption" tone="secondary" numeric>
+                        {seconds(end - s.start)}
+                        {s.detail && ` · ${s.detail}`}
+                      </Text>
+                      {open && running && <Spinner size="xs" tone="muted" label="진행 중" />}
+                      {s.slowest && (
+                        <Badge tone="warning" square>
+                          가장 느림
+                        </Badge>
+                      )}
+                    </>
+                  }
+                />
+              </TimelineRow>
+            )
+          })}
+        </Timeline>
+      </CardBody>
+    </Card>
+  )
+}
+```
+
+### 표시선 · 띠
+
+markers의 line은 solid / dashed, band는 띠의 다른 쪽 끝, labelSide는 칩이 선의 어느 쪽으로 붙을지예요('left' · 'right'로 이웃한 칩이 겹치지 않게).
+
+```tsx
+import { Timeline, TimelineBar, TimelineRow } from '@iamfiro/design'
+
+const hour = (v: number) => `${String(Math.floor(v)).padStart(2, '0')}:${v % 1 ? '30' : '00'}`
+
+export default function Example() {
+  return (
+    <Timeline
+      min={9}
+      max={18}
+      step={1}
+      formatTick={hour}
+      now={14.5}
+      labelWidth={96}
+      aria-label="10월 25일 팀 일정"
+      markers={[
+        { value: 12, band: 13, line: 'solid', tone: 'neutral', label: '점심', labelSide: 'right' },
+        { value: 17, tone: 'danger', line: 'dashed', label: '마감 17:00', labelSide: 'left' },
+      ]}
+      style={{ width: '100%', maxWidth: 600 }}
+    >
+      <TimelineRow label="김민지">
+        <TimelineBar start={9.5} end={11} tone="accent" tooltip="주간 계획 회의" />
+        <TimelineBar start={14} end={16} tone="purple" tooltip="디자인 리뷰" />
+      </TimelineRow>
+      <TimelineRow label="이도현">
+        <TimelineBar start={10} end={12} tone="purple" tooltip="API 설계" />
+        <TimelineBar start={13} end={14.5} tone="accent" running tooltip="QA 대응 (진행 중)" />
+      </TimelineRow>
+      <TimelineRow label="박서연" faded>
+        <TimelineBar start={15} end={17} variant="outline" tooltip="릴리스 점검 (예정)" />
+      </TimelineRow>
+    </Timeline>
+  )
+}
+```
+
+### 팀원별 작업 레인
+
+최근 30분을 상대 축(formatOffset)으로 보여 주고, 눈금자 끝에는 nowLabel 칩 "지금"이 놓여요(nowLine={false}로 선은 생략). density="comfortable"(56px) 행에 Avatar · 이름 · 설명 · 상태 Badge를 두 줄로, 막대 안에는 IconStack과 작업 이름을 넣어요. 진행 중 막대는 왼쪽에서 옅게 시작해 오른쪽 끝이 진한 선으로 끝나요. 점선 곡선은 links로 이은 작업 의존 관계예요.
+
+```tsx
+import { TriangleAlert } from 'lucide-react'
+import { Avatar, Badge, BrandIcon, IconStack, Inline, Card, CardBody, CardHeader, Timeline, TimelineBar, TimelineRow, formatOffset, toast } from '@iamfiro/design'
+
+// Minutes before now: −30 … 0.
+const minutes = formatOffset('분')
+const icons = (...names: Array<'gmail' | 'slack' | 'figma' | 'github' | 'clickup'>) => (
+  <IconStack icons={names.map((n) => <BrandIcon key={n} name={n} size={16} />)} size={16} overlap={-4} shape="square" />
+)
+
+export default function Example() {
+  return (
+    <Card style={{ width: '100%', maxWidth: 760 }}>
+      <CardHeader
+        title={
+          <Inline gap={3}>
+            팀원별 작업
+            <Badge tone="accent" size="sm" dot>
+              진행 중 2
+            </Badge>
+            <Badge tone="warning" size="sm" dot>
+              확인 필요 1
+            </Badge>
+          </Inline>
+        }
+        actions={<Badge>최근 30분</Badge>}
+      />
+      <CardBody>
+        <Timeline
+          min={-30}
+          max={0}
+          ticks={[-25, -20, -15, -10, -5, 0]}
+          formatTick={minutes}
+          now={0}
+          nowLabel="지금"
+          nowLine={false}
+          density="comfortable"
+          labelWidth={200}
+          links={[{ from: 'research', to: 'pricing-page' }]}
+          aria-label="최근 30분 팀원별 작업 레인"
+        >
+          <TimelineRow label="김민지" description="프로덕트 디자인" leading={<Avatar name="김민지" size={36} />}>
+            <TimelineBar id="research" start={-26} end={-17} tone="neutral" leading={icons('gmail', 'clickup')}>
+              경쟁사 가격 조사
+            </TimelineBar>
+            <TimelineBar start={-10} end={0} running leading={icons('clickup', 'slack')}>
+              사용자 인터뷰 정리
+            </TimelineBar>
+          </TimelineRow>
+          <TimelineRow label="이도현" description="프론트엔드" leading={<Avatar name="이도현" size={36} />}>
+            <TimelineBar id="pricing-page" start={-16} end={0} running leading={icons('figma', 'github')}>
+              요금제 페이지 초안
+            </TimelineBar>
+          </TimelineRow>
+          <TimelineRow
+            label="박서연"
+            description="코드 리뷰"
+            leading={<Avatar name="박서연" size={36} />}
+            badge={<Badge size="sm">쉬는 중</Badge>}
+          >
+            <TimelineBar start={-30} end={-20} tone="neutral" leading={icons('github')}>
+              결제 모듈 PR #482 리뷰
+            </TimelineBar>
+          </TimelineRow>
+          <TimelineRow
+            label="최준호"
+            description="운영"
+            leading={<Avatar name="최준호" size={36} />}
+            badge={
+              <Badge size="sm" tone="warning">
+                확인 필요
+              </Badge>
+            }
+          >
+            <TimelineBar start={-26} end={-20.5} tone="danger" leading={icons('slack')}>
+              고객 데이터 동기화
+            </TimelineBar>
+            <TimelineBar
+              start={-13}
+              end={0}
+              tone="warning"
+              leading={icons('github')}
+              action={
+                <Badge as="button" tone="warning" icon={<TriangleAlert size={12} />} onClick={() => toast('최준호 님에게 확인 요청을 보냈어요')}>
+                  확인 필요
+                </Badge>
+              }
+            >
+              배포 키 교체
+            </TimelineBar>
+          </TimelineRow>
+        </Timeline>
+      </CardBody>
+    </Card>
+  )
+}
+```
+
+### 내용이 있는 막대
+
+children을 주면 8px 모서리의 큰 막대(xl, 32px)가 되고 글자는 톤 색으로 칠해져요. neutral · accent · danger · warning, 진행 중(running), 막대 안 오른쪽의 action 칸(흰 Badge 버튼), 말줄임. onClick을 주면 막대 전체가 버튼이 돼요.
+
+```tsx
+import { TriangleAlert } from 'lucide-react'
+import { Badge, BrandIcon, IconStack, Timeline, TimelineBar, TimelineRow, toast } from '@iamfiro/design'
+
+const logos = (...names: Array<'gmail' | 'slack' | 'figma' | 'github' | 'clickup'>) => (
+  <IconStack icons={names.map((n) => <BrandIcon key={n} name={n} size={16} />)} size={16} overlap={-4} shape="square" />
+)
+
+export default function Example() {
+  return (
+    <Timeline max={100} grid={false} labelWidth={96} density="comfortable" aria-label="내용이 있는 막대" style={{ width: '100%', maxWidth: 620 }}>
+      <TimelineRow label="neutral">
+        <TimelineBar start={0} end={46} tone="neutral" leading={logos('github')} onClick={() => toast('PR #482를 열었어요')}>
+          PR #482 리뷰
+        </TimelineBar>
+      </TimelineRow>
+      <TimelineRow label="accent">
+        <TimelineBar start={20} end={100} running leading={logos('figma', 'slack')}>
+          요금제 페이지 초안 (진행 중)
+        </TimelineBar>
+      </TimelineRow>
+      <TimelineRow label="danger">
+        <TimelineBar start={6} end={40} tone="danger" leading={logos('gmail')}>
+          고객 데이터 동기화 실패
+        </TimelineBar>
+      </TimelineRow>
+      <TimelineRow label="warning">
+        <TimelineBar
+          start={36}
+          end={100}
+          tone="warning"
+          leading={logos('github', 'clickup')}
+          action={
+            <Badge as="button" tone="warning" icon={<TriangleAlert size={12} />} onClick={() => toast('확인 요청을 열었어요')}>
+              확인 필요
+            </Badge>
+          }
+        >
+          배포 키 교체
+        </TimelineBar>
+      </TimelineRow>
+      <TimelineRow label="잘림">
+        <TimelineBar start={0} end={22} tone="neutral" leading={logos('slack')}>
+          아주 긴 작업 이름은 막대 폭에 맞춰 말줄임표로 잘려요
+        </TimelineBar>
+      </TimelineRow>
+    </Timeline>
+  )
+}
+```
+
+### 두 줄 이름 · 행 선택
+
+leading(IconTile) · description · badge · count("+5" 칩)로 두 줄 이름을 만들어요. onSelect를 주면 행 어디를 눌러도(Enter · Space 포함) 선택되고, selected 행은 이름 칸까지 옅은 파란 배경이 깔려요.
+
+```tsx
+import { useState } from 'react'
+import { Database, FileText, Rocket, Server } from 'lucide-react'
+import { Badge, IconTile, Text, Timeline, TimelineBar, TimelineRow } from '@iamfiro/design'
+
+const DEPLOYS = [
+  { id: 'web', name: '웹 프론트', description: 'main · 김민지', icon: <Rocket size={16} />, start: 2, end: 9, steps: 5 },
+  { id: 'api', name: 'API 서버', description: 'release/2.4 · 이도현', icon: <Server size={16} />, start: 4, end: 15, steps: 7, status: <Badge size="sm" spinner>진행 중</Badge> },
+  { id: 'db', name: '데이터베이스 이전', description: '스키마 v12 · 이도현', icon: <Database size={16} />, start: 9, end: 13, steps: 3, status: <Badge size="sm" tone="warning">확인 필요</Badge> },
+  { id: 'docs', name: '도움말 문서', description: '자동 배포', icon: <FileText size={16} />, start: 0, end: 3, steps: 0 },
+]
+
+export default function Example() {
+  const [selected, setSelected] = useState('api')
+  const current = DEPLOYS.find((d) => d.id === selected)
+  return (
+    <Timeline
+      max={20}
+      step={5}
+      formatTick={(v) => `${v}분`}
+      now={15}
+      density="comfortable"
+      labelWidth={260}
+      labelHeader={`선택: ${current?.name ?? '없음'}`}
+      aria-label="배포별 진행 시간"
+      style={{ width: '100%', maxWidth: 720 }}
+    >
+      {DEPLOYS.map((d) => (
+        <TimelineRow
+          key={d.id}
+          label={d.name}
+          description={d.description}
+          leading={<IconTile size={36}>{d.icon}</IconTile>}
+          badge={d.status}
+          count={d.steps > 0 ? d.steps : undefined}
+          selected={selected === d.id}
+          onSelect={() => setSelected(d.id)}
+        >
+          <TimelineBar
+            start={d.start}
+            end={d.end}
+            tone={d.id === 'db' ? 'warning' : d.id === 'docs' ? 'neutral' : 'accent'}
+            running={d.id === 'api'}
+            label={
+              <Text variant="caption" tone="secondary" numeric>
+                {d.end - d.start}분
+              </Text>
+            }
+          />
+        </TimelineRow>
+      ))}
+    </Timeline>
+  )
+}
+```
+
+### 의존 관계 연결선
+
+TimelineBar에 id를 주고 links={[{ from, to }]}로 앞 작업의 끝과 뒤 작업의 시작을 점선 곡선으로 이어요. 퍼센트 위치로 그려서 재지 않고, 값이 바뀌면 막대와 함께 곡선이 미끄러져요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Stack, Timeline, TimelineBar, TimelineRow, type TimelineLink } from '@iamfiro/design'
+
+const LINKS: TimelineLink[] = [
+  { from: 'design', to: 'build' },
+  { from: 'build', to: 'qa' },
+  { from: 'design', to: 'docs', tone: 'neutral' },
+]
+
+export default function Example() {
+  // Pushing the design task back moves every bar after it; the curves slide along.
+  const [delay, setDelay] = useState(0)
+  return (
+    <Stack gap={4} align="start" style={{ width: '100%', maxWidth: 620 }}>
+      <Timeline max={20} step={5} formatTick={(v) => `${v}일`} labelWidth={110} links={LINKS} aria-label="출시 작업 의존 관계" style={{ width: '100%' }}>
+        <TimelineRow label="화면 디자인">
+          <TimelineBar id="design" start={0} end={5 + delay} tone="purple" label={`${5 + delay}일`} />
+        </TimelineRow>
+        <TimelineRow label="기능 개발">
+          <TimelineBar id="build" start={6 + delay} end={13 + delay} tone="accent" label="7일" />
+        </TimelineRow>
+        <TimelineRow label="도움말 문서">
+          <TimelineBar id="docs" start={7 + delay} end={10 + delay} tone="neutral" label="3일" />
+        </TimelineRow>
+        <TimelineRow label="품질 검사">
+          <TimelineBar id="qa" start={13.5 + delay} end={16 + delay} tone="teal" label="2.5일" />
+        </TimelineRow>
+      </Timeline>
+      <Button size="sm" onClick={() => setDelay((d) => (d === 0 ? 2 : 0))}>
+        {delay === 0 ? '디자인 2일 늦추기' : '원래 일정으로'}
+      </Button>
+    </Stack>
+  )
+}
+```
+
+### 구간으로 나뉜 막대
+
+segments로 한 막대를 이어지는 색 구간(준비 · 작업 · 검토)으로 나눠요. variant="outline"과 함께 쓰면 옅은 실선 틀 안에 얇은 구간들이 놓이고, fill이면 막대 자체가 나뉘어요.
+
+```tsx
+import { ColorDot, Inline, Stack, Text, Timeline, TimelineBar, TimelineRow, type TimelineBarSegment } from '@iamfiro/design'
+
+// Each task split into consecutive phases: 준비 → 작업 → 검토.
+const TASKS: Array<{ name: string; segments: TimelineBarSegment[] }> = [
+  {
+    name: '요금제 문구 작성',
+    segments: [
+      { start: 11, end: 15, tone: 'teal' },
+      { start: 15, end: 42, tone: 'purple' },
+      { start: 42, end: 48, tone: 'accent' },
+    ],
+  },
+  {
+    name: '경쟁사 조사',
+    segments: [
+      { start: 6, end: 11, tone: 'teal' },
+      { start: 11, end: 24, tone: 'accent' },
+      { start: 24, end: 36, tone: 'purple' },
+    ],
+  },
+  {
+    name: '배포 점검',
+    segments: [
+      { start: 30, end: 33, tone: 'teal' },
+      { start: 33, end: 58, tone: 'accent' },
+    ],
+  },
+]
+
+const LEGEND = [
+  { label: '준비', color: 'var(--chart-3)' },
+  { label: '작업', color: 'var(--chart-4)' },
+  { label: '검토', color: 'var(--accent)' },
+]
+
+const seconds = (v: number) => `${v}s`
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 620 }}>
+      <Timeline max={90} step={30} formatTick={seconds} labelWidth={130} aria-label="작업 단계별 소요 시간">
+        {TASKS.map((t) => {
+          const start = t.segments[0].start
+          const end = t.segments[t.segments.length - 1].end
+          return (
+            <TimelineRow key={t.name} label={t.name}>
+              <TimelineBar start={start} end={end} variant="outline" segments={t.segments} label={seconds(end - start)} />
+            </TimelineRow>
+          )
+        })}
+        <TimelineRow label="테두리 없이">
+          <TimelineBar
+            start={6}
+            end={40}
+            size="sm"
+            segments={[
+              { start: 6, end: 14, tone: 'teal' },
+              { start: 14, end: 30, tone: 'accent' },
+              { start: 30, end: 40, tone: 'purple' },
+            ]}
+            label="34s"
+          />
+        </TimelineRow>
+      </Timeline>
+      <Inline gap={4}>
+        {LEGEND.map((l) => (
+          <Inline key={l.label} gap={2}>
+            <ColorDot color={l.color} />
+            <Text variant="caption" tone="secondary">
+              {l.label}
+            </Text>
+          </Inline>
+        ))}
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 트리 + 타임라인
+
+왼쪽 칸(aside)에 TreeView를 두고 flattenTree로 같은 보이는 행을 Timeline 행으로 그려요(rowHeight = TREE_ROW_HEIGHT, animated={false}). 접힌 부모는 "+N" 칩으로 숨은 단계 수를 보여 주고, 막대를 누르면 renderTarget으로 감싼 Popover가 막대에 붙어 상세(Stat + Grid)를 띄워요. 행을 고르면 이름 칸까지 파란 배경이 깔려요.
+
+```tsx
+import { useMemo, useState, type ReactNode } from 'react'
+import { FileText, FlaskConical, GitBranch, GitPullRequest, Package, PenLine, Rocket, Search, X } from 'lucide-react'
+import { Badge, Box, BrandIcon, Button, Grid, IconTile, Inline, Stack, Text, Popover, Stat, TREE_ROW_HEIGHT, Timeline, TimelineBar, TimelineRow, TreeView, flattenTree, type TimelineBarSegment, type TimelineBarTone, type TreeNode } from '@iamfiro/design'
+
+interface Span {
+  start: number
+  end: number
+  owner: string
+  tone: TimelineBarTone
+  icon: ReactNode
+  segments?: TimelineBarSegment[]
+  failed?: boolean
+  request?: string
+  result?: string
+}
+
+const tile = (icon: ReactNode, tone: 'neutral' | 'danger' = 'neutral') => (
+  <IconTile size={26} tone={tone}>
+    {icon}
+  </IconTile>
+)
+
+const node = (id: string, label: string, span: Span, children?: TreeNode<Span>[]): TreeNode<Span> => ({
+  id,
+  label,
+  description: span.owner,
+  leading: tile(span.icon, span.failed ? 'danger' : 'neutral'),
+  data: span,
+  children,
+})
+
+const ITEMS: TreeNode<Span>[] = [
+  node('release', '출시 준비', { start: 0, end: 82, owner: '김민지', tone: 'neutral', icon: <Rocket size={14} />, request: '금요일까지 새 요금제 페이지 출시', result: '요금제 페이지 배포 완료 · 공지 발송' }, [
+    node('plan', '일정 계획', { start: 0.5, end: 7.4, owner: '김민지', tone: 'purple', icon: <PenLine size={14} />, request: '출시까지 할 일과 담당자 정리', result: '작업 6개 · 담당자 3명 배정' }),
+    node(
+      'research',
+      '시장 조사',
+      {
+        start: 6,
+        end: 36,
+        owner: '이도현',
+        tone: 'accent',
+        icon: <Search size={14} />,
+        segments: [
+          { start: 6, end: 11, tone: 'teal' },
+          { start: 11, end: 24, tone: 'accent' },
+          { start: 24, end: 36, tone: 'purple' },
+        ],
+        request: '경쟁사 요금제 다섯 곳 비교',
+        result: '비교표를 문서에 정리',
+      },
+      [
+        node('research/a', '경쟁사 A 조사', { start: 6, end: 14, owner: '이도현', tone: 'accent', icon: <FileText size={14} /> }),
+        node('research/b', '경쟁사 B 조사', { start: 14, end: 24, owner: '이도현', tone: 'accent', icon: <FileText size={14} /> }),
+        node('research/sheet', '비교표 정리', { start: 24, end: 36, owner: '이도현', tone: 'purple', icon: <FileText size={14} /> }),
+      ],
+    ),
+    node(
+      'copy',
+      '요금제 문구 작성',
+      {
+        start: 11,
+        end: 48,
+        owner: '이도현',
+        tone: 'accent',
+        icon: <PenLine size={14} />,
+        segments: [
+          { start: 11, end: 15, tone: 'teal' },
+          { start: 15, end: 42, tone: 'purple' },
+          { start: 42, end: 48, tone: 'teal' },
+        ],
+        request: '세 가지 요금제의 소개 문구 작성',
+        result: '무료 · 프로 · 팀 문구를 문서에 저장',
+      },
+      [
+        node('copy/draft', '초안 작성', { start: 11, end: 30, owner: '이도현', tone: 'purple', icon: <PenLine size={14} /> }),
+        node('copy/review', '문구 검토', { start: 30, end: 48, owner: '김민지', tone: 'teal', icon: <PenLine size={14} /> }),
+      ],
+    ),
+    node('build', '페이지 개발', { start: 20, end: 74, owner: '박서연', tone: 'accent', icon: <Package size={14} />, request: '요금제 페이지 구현과 결제 연동', result: 'PR #482 병합' }, [
+      node('build/branch', '브랜치 만들기', { start: 20, end: 21.5, owner: 'GitHub', tone: 'neutral', icon: <GitBranch size={14} /> }),
+      node('build/page', '페이지 작성', { start: 21.5, end: 50, owner: '박서연', tone: 'accent', icon: <BrandIcon name="figma" size={14} /> }),
+      node('build/test', '결제 테스트', { start: 50, end: 56, owner: 'GitHub', tone: 'danger', icon: <FlaskConical size={14} />, failed: true, request: '결제 흐름 테스트 실행', result: '쿠폰 적용 테스트 1건 실패' }),
+      node('build/retry', '테스트 다시 실행', { start: 62, end: 68, owner: 'GitHub', tone: 'neutral', icon: <FlaskConical size={14} /> }),
+      node('build/pr', '풀 리퀘스트 #482', { start: 68, end: 74, owner: 'GitHub', tone: 'neutral', icon: <GitPullRequest size={14} /> }),
+    ]),
+    node('notify', '출시 공지', { start: 76, end: 81, owner: 'Slack', tone: 'teal', icon: <BrandIcon name="slack" size={14} /> }),
+  ]),
+]
+
+const ROW = TREE_ROW_HEIGHT.default
+const secs = (v: number) => `${Number(v.toFixed(1))}초`
+const tick = (v: number) => (v < 60 ? `${v}초` : `${Math.floor(v / 60)}분${v % 60 ? ` ${v % 60}초` : ''}`)
+const countAll = (n: TreeNode<Span>): number => (n.children ?? []).reduce((sum, c) => sum + 1 + countAll(c), 0)
+
+function SpanDetail({ item, close }: { item: TreeNode<Span>; close: () => void }) {
+  const span = item.data as Span
+  return (
+    <Stack gap={3}>
+      <Inline gap={3} wrap={false} align="start">
+        {item.leading}
+        <Stack gap={0} style={{ flex: 1, minWidth: 0 }}>
+          <Text variant="label-md" truncate>
+            {item.label}
+          </Text>
+          <Text variant="caption" tone="tertiary" truncate>
+            {span.owner}
+          </Text>
+        </Stack>
+        <Badge size="sm" tone={span.failed ? 'danger' : 'success'}>
+          {span.failed ? '실패' : '완료'}
+        </Badge>
+        <Button variant="ghost" size="sm" iconOnly icon={<X size={16} />} aria-label="닫기" onClick={close} />
+      </Inline>
+      <Box background="subtle" radius="lg" padding={3}>
+        <Grid columns={3} gap={3}>
+          <Stat size="sm" label="소요 시간" value={secs(span.end - span.start)} />
+          <Stat size="sm" label="시작" value={`+${secs(span.start)}`} />
+          <Stat size="sm" label="하위 단계" value={countAll(item)} />
+        </Grid>
+      </Box>
+      {span.request && (
+        <Stack gap={1}>
+          <Text variant="overline" tone="tertiary">
+            요청
+          </Text>
+          <Text variant="body-sm">{span.request}</Text>
+        </Stack>
+      )}
+      {span.result && (
+        <Stack gap={1}>
+          <Text variant="overline" tone="tertiary">
+            결과
+          </Text>
+          <Text variant="body-sm">{span.result}</Text>
+        </Stack>
+      )}
+    </Stack>
+  )
+}
+
+export default function Example() {
+  const [expanded, setExpanded] = useState(['release', 'build'])
+  const [selected, setSelected] = useState<string | null>('copy')
+
+  // Collapsed parents show how many steps they hide.
+  const items = useMemo(() => {
+    const withCounts = (list: TreeNode<Span>[]): TreeNode<Span>[] =>
+      list.map((n) => ({
+        ...n,
+        trailing:
+          n.children && !expanded.includes(n.id) ? (
+            <Badge size="sm" square>
+              +{countAll(n)}
+            </Badge>
+          ) : n.data?.failed ? (
+            <Badge size="sm" tone="danger">
+              실패
+            </Badge>
+          ) : undefined,
+        children: n.children && withCounts(n.children),
+      }))
+    return withCounts(ITEMS)
+  }, [expanded])
+
+  // The same visible rows the tree draws, in the same order: row N sits at N × ROW in both.
+  const rows = useMemo(() => flattenTree(items, expanded), [items, expanded])
+
+  return (
+    <Timeline
+      max={100}
+      step={30}
+      formatTick={tick}
+      labelWidth={300}
+      labelHeader="단계"
+      rowHeight={ROW}
+      aria-label="출시 준비 단계별 소요 시간"
+      style={{ width: '100%', maxWidth: 820 }}
+      aside={
+        <TreeView
+          aria-label="출시 준비 단계"
+          items={items}
+          expanded={expanded}
+          onExpandedChange={setExpanded}
+          selectionMode="none"
+          expandOnClick={false}
+          onAction={(n) => setSelected(n.id)}
+          animated={false}
+        />
+      }
+    >
+      {rows.map(({ id, node: item, depth }) => {
+        const span = item.data as Span
+        return (
+          <TimelineRow key={id} selected={selected === id}>
+            <TimelineBar
+              start={span.start}
+              end={span.end}
+              tone={span.tone}
+              variant={span.segments ? 'outline' : 'fill'}
+              segments={span.segments}
+              size={depth === 0 ? 'lg' : span.segments ? 'sm' : 'md'}
+              aria-label={`${item.label as string}, ${secs(span.end - span.start)}`}
+              onClick={() => setSelected(id)}
+              renderTarget={(target) => (
+                <Popover trigger={target} width={340} aria-label={`${item.label as string} 상세`}>
+                  {(close) => <SpanDetail item={item} close={close} />}
+                </Popover>
+              )}
+              label={
+                <Text variant="caption" tone="secondary" numeric>
+                  {secs(span.end - span.start)}
+                </Text>
+              }
+            />
+          </TimelineRow>
+        )
+      })}
+    </Timeline>
+  )
+}
+```