@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/line-chart/AGENTS.md

@@ -0,0 +1,393 @@
+# LineChart
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+여러 시리즈의 추이를 비교하는 선 차트. 마우스·터치·화살표 키로 안내선을 옮기면 그날의 값이 Card 툴팁으로 따라오고, 오른쪽 끝에선 반대편으로 넘어가요. 툴팁은 ColorDot · Text · Separator로만 조립했고, 색은 --chart-* 토큰을 순서대로 써요.
+
+```tsx
+import { LineChart, type LineSeries } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 차트: 시리즈 색은 `--chart-1…6`을 순서대로, 그리드는 `--chart-grid`로 아주 옅게(세로선·축선 없음). 범례·툴팁의 색 표시는 `ColorDot`, 툴팁은 `Card raised` + `Separator`로 조립. 축·툴팁·범례·호버/키보드는 `components/Chart/`의 공용 조각(`ChartTooltip`, `ChartLegend`, `useChartInteraction`)을 쓴다. → `LineChart` · `BarChart` · `PieChart` · `Sparkbar`
+- 차트에서 한 칸을 고르는 화면(피벗)은 `BarChart selected` + `Table selectedKey`를 같은 상태로 묶는다. 고르지 않은 칸은 옅은 색, 고른 칸의 x축 아이콘(`xIcon`)은 흰 칩으로 펼친다. 임계치·이상 구간은 `LineChart referenceLines` · `bands`, 실시간 데이터는 `streaming`(모양 변형 대신 한 칸 미끄러짐) + `endDot="pulse"`.
+
+## API
+
+### LineChart
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `LineChartRow[]` |  | 행 목록. 한 행 = x축 한 칸. |
+| `xKey` (필수) | `string` |  | x축 라벨이 든 필드. |
+| `series` (필수) | `LineSeries[]` |  | 그릴 시리즈. color를 생략하면 --chart-1부터 순서대로. |
+| `height` | `number` | `240` | 축 라벨을 포함한 높이(px). 너비는 부모를 채워요. |
+| `curve` | `'linear' \| 'smooth'` | `'linear'` | 직선 또는 단조 곡선. |
+| `area` | `boolean \| 'gradient' \| 'solid'` | `false` | 선 아래 채움. true·'gradient'는 아래로 옅어지고, 'solid'는 한 겹의 옅은 색이에요. |
+| `stack` | `'stacked' \| 'percent'` |  | 시리즈를 위로 쌓아요(percent = 행마다 100%). 보통은 AreaChart type으로 써요. |
+| `connectNulls` | `boolean` |  | null에서 끊지 않고 건너 이어 그려요. |
+| `showTotal` | `boolean` | `stack이면 true` | 툴팁 마지막 줄에 합계. |
+| `yTickCount` | `number` | `3` | y축 라벨 개수(0 포함). 간격은 1·2·2.5·3·5 단위로 반올림해요. |
+| `yMax` | `number` |  | y축 위 끝을 고정. |
+| `yTicks` | `number[]` |  | y축 값을 직접 지정(예: [0, 12, 24]). yTickCount · yMax보다 우선해요. |
+| `xTicks` | `'auto' \| 'edges'` | `'auto'` | x축 라벨. edges는 첫 행과 마지막 행만('96초 전' … '지금'). |
+| `bands` | `LineChartBand[]` |  | 플롯 뒤에 칠하는 x 구간. |
+| `referenceLines` | `LineChartReferenceLine[]` |  | 가로 점선 기준선(임계치·목표). |
+| `endDot` | `boolean \| 'pulse'` |  | 각 선의 마지막 점에 점을 찍어요. 'pulse'면 퍼지는 링이 반복돼요. |
+| `streaming` | `boolean \| number` |  | 갱신마다 행이 하나 추가되고 가장 오래된 행이 빠지는 데이터. 모양 변형 대신 한 칸 왼쪽으로 미끄러져요. 숫자는 이동 시간(ms, 선형). |
+| `formatValue` | `(value, series) => string` | `'1,234'` | 툴팁 값 형식. |
+| `formatAxisValue` | `(value) => string` | `'6천'` | y축 라벨 형식(한국어 축약). |
+| `formatX` | `(row, index) => string` |  | x축 라벨 형식. 기본은 xKey 값 그대로. |
+| `formatTitle` | `(row, index) => ReactNode` |  | 툴팁 제목. 기본은 formatX. |
+| `tooltipSort` | `'value' \| 'series' \| 'reverse'` | `'value' (stack이면 'reverse')` | 툴팁 행 순서. reverse = 위에 쌓인 시리즈부터. |
+| `legend` | `boolean` | `true` | 아래 범례. 마우스를 올리면 해당 선을 강조해요. |
+| `activeIndex` | `number \| null` |  | 하이라이트한 행(제어). null이면 없음. |
+| `defaultActiveIndex` | `number \| null` | `null` | 처음 하이라이트(비제어). |
+| `onActiveIndexChange` | `(index: number \| null) => void` |  | 하이라이트가 바뀔 때. |
+| `aria-label` | `string` | `'선 차트'` | 차트 이름. 하이라이트한 값은 aria-live로 읽어 줘요. |
+
+### LineSeries
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `key` (필수) | `string` |  | 행에서 값을 읽을 필드. |
+| `label` (필수) | `string` |  | 범례·툴팁 이름. |
+| `color` | `string` |  | CSS 변수('--chart-2') 또는 색. |
+
+### LineChartBand
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `from / to` (필수) | `number` |  | 구간의 시작 · 끝 행 index. |
+| `tone` | `'neutral' \| 'accent' \| 'warning' \| 'danger'` | `'warning'` | 옅은 채움 색(--*-soft). |
+
+### LineChartReferenceLine
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `number` |  | 선을 그을 y 값. |
+| `label` | `string` |  | 오른쪽 끝, 선 위의 작은 라벨. |
+| `tone` | `'neutral' \| 'accent' \| 'warning' \| 'danger'` | `'neutral'` | 선과 라벨 색. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+툴팁엔 값이 큰 순서로 나와요. 범례에 마우스를 올리면 그 선만 강조돼요. 차트에 포커스하고 ←/→, Home/End, Esc로도 움직여요.
+
+```tsx
+import { LineChart, type LineSeries } from '@iamfiro/design'
+
+const SERIES: LineSeries[] = [
+  { key: 'paid', label: '유료 광고' },
+  { key: 'organic', label: '검색 유입' },
+  { key: 'email', label: '이메일' },
+  { key: 'referral', label: '추천' },
+  { key: 'direct', label: '직접 방문' },
+]
+
+const DATA = [
+  { date: '3월 3일', day: '월', paid: 3600, organic: 4200, email: 1200, referral: 1800, direct: 600 },
+  { date: '3월 4일', day: '화', paid: 3350, organic: 4700, email: 1100, referral: 2300, direct: 900 },
+  { date: '3월 5일', day: '수', paid: 4400, organic: 3900, email: 1700, referral: 2000, direct: 700 },
+  { date: '3월 6일', day: '목', paid: 4800, organic: 4600, email: 2100, referral: 1500, direct: 800 },
+  { date: '3월 7일', day: '금', paid: 4500, organic: 5300, email: 1800, referral: 1900, direct: 1000 },
+  { date: '3월 8일', day: '토', paid: 4300, organic: 5600, email: 1450, referral: 2400, direct: 1200 },
+  { date: '3월 9일', day: '일', paid: 4200, organic: 6000, email: 1500, referral: 2700, direct: 1100 },
+]
+
+export default function Example() {
+  return (
+    <LineChart
+      data={DATA}
+      xKey="date"
+      series={SERIES}
+      formatValue={(v) => `${v.toLocaleString('ko-KR')}만 원`}
+      formatTitle={(row) => `${row.date} (${row.day})`}
+      aria-label="유입 경로별 매출"
+      style={{ width: '100%', maxWidth: 560 }}
+    />
+  )
+}
+```
+
+### 부드러운 곡선
+
+curve="smooth"는 단조 보간이라 실제 값보다 튀어 오르지 않아요. 값이 빠진 날(null)은 선이 끊겨요.
+
+```tsx
+import { LineChart, type LineSeries } from '@iamfiro/design'
+
+const SERIES: LineSeries[] = [
+  { key: 'web', label: '웹', color: '--chart-2' },
+  { key: 'app', label: '앱', color: '--chart-3' },
+]
+
+const DATA = [
+  { week: '1주', web: 820, app: 410 },
+  { week: '2주', web: 940, app: 520 },
+  { week: '3주', web: 910, app: null },
+  { week: '4주', web: 1180, app: 690 },
+  { week: '5주', web: 1260, app: 760 },
+  { week: '6주', web: 1210, app: 880 },
+  { week: '7주', web: 1420, app: 1010 },
+  { week: '8주', web: 1530, app: 1120 },
+]
+
+export default function Example() {
+  return (
+    <LineChart
+      data={DATA}
+      xKey="week"
+      series={SERIES}
+      curve="smooth"
+      height={200}
+      yTickCount={4}
+      formatValue={(v) => `${v.toLocaleString('ko-KR')}명`}
+      aria-label="주간 활성 사용자"
+      style={{ width: '100%', maxWidth: 560 }}
+    />
+  )
+}
+```
+
+### 영역 (area)
+
+area를 켜면 선 아래를 옅은 그라데이션으로 채워 양의 크기를 강조해요.
+
+```tsx
+import { LineChart, type LineSeries } from '@iamfiro/design'
+
+const SERIES: LineSeries[] = [
+  { key: 'pro', label: '프로', color: '--chart-2' },
+  { key: 'team', label: '팀', color: '--chart-4' },
+]
+
+const DATA = [
+  { month: '5월', pro: 1200, team: 400 },
+  { month: '6월', pro: 1450, team: 520 },
+  { month: '7월', pro: 1380, team: 610 },
+  { month: '8월', pro: 1720, team: 790 },
+  { month: '9월', pro: 1950, team: 880 },
+  { month: '10월', pro: 2240, team: 1130 },
+]
+
+export default function Example() {
+  return (
+    <LineChart
+      data={DATA}
+      xKey="month"
+      series={SERIES}
+      area
+      curve="smooth"
+      height={220}
+      formatValue={(v) => `${v.toLocaleString('ko-KR')}명`}
+      aria-label="요금제별 구독자"
+      style={{ width: '100%', maxWidth: 560 }}
+    />
+  )
+}
+```
+
+### 선택 연동 (activeIndex)
+
+하이라이트한 날을 앱 상태로 들고 있어 다른 UI와 맞물려요. 데이터를 바꾸면 선이 새 모양으로 미끄러져요.
+
+```tsx
+import { useState } from 'react'
+import { LineChart, type LineSeries, Inline, SegmentedControl, Stack, Text } from '@iamfiro/design'
+
+const SERIES: LineSeries[] = [
+  { key: 'signup', label: '가입' },
+  { key: 'paid', label: '결제' },
+]
+
+const RANGES = {
+  week: [
+    { x: '월', signup: 120, paid: 32 },
+    { x: '화', signup: 180, paid: 41 },
+    { x: '수', signup: 150, paid: 38 },
+    { x: '목', signup: 210, paid: 55 },
+    { x: '금', signup: 260, paid: 61 },
+    { x: '토', signup: 190, paid: 44 },
+    { x: '일', signup: 170, paid: 40 },
+  ],
+  lastWeek: [
+    { x: '월', signup: 90, paid: 20 },
+    { x: '화', signup: 110, paid: 28 },
+    { x: '수', signup: 160, paid: 35 },
+    { x: '목', signup: 140, paid: 30 },
+    { x: '금', signup: 200, paid: 47 },
+    { x: '토', signup: 230, paid: 52 },
+    { x: '일', signup: 150, paid: 33 },
+  ],
+}
+
+export default function Example() {
+  const [range, setRange] = useState<keyof typeof RANGES>('week')
+  const [active, setActive] = useState<number | null>(4)
+  const data = RANGES[range]
+  const row = active === null ? null : data[active]
+
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 560 }}>
+      <Inline>
+        <SegmentedControl
+          value={range}
+          onChange={setRange}
+          ariaLabel="기간"
+          options={[
+            { value: 'week', label: '이번 주' },
+            { value: 'lastWeek', label: '지난주' },
+          ]}
+        />
+      </Inline>
+      <LineChart data={data} xKey="x" series={SERIES} activeIndex={active} onActiveIndexChange={setActive} formatTitle={(r) => `${r.x}요일`} />
+      <Text variant="body-sm" tone="secondary">
+        {row ? `${row.x}요일 결제 전환율 ${Math.round((row.paid / row.signup) * 100)}%` : '차트에서 요일을 골라 보세요.'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 구간 · 기준선
+
+bands는 x 구간(행 index from → to)을 옅은 tone 색으로 칠하고, referenceLines는 값 위치에 점선과 라벨을 그려요. 기준선 값은 y축 범위에 포함돼요.
+
+```tsx
+import { ChartLegend, LineChart, type LineChartBand, type LineChartReferenceLine, Stack } from '@iamfiro/design'
+
+const TRAFFIC = [820, 610, 450, 380, 360, 520, 1100, 2300, 3600, 4100, 4300, 4500, 4800, 4600, 4400, 4700, 5200, 5900, 6800, 7100, 6200, 4300, 2600, 1400]
+const DATA = TRAFFIC.map((rps, h) => ({ hour: `${h}시`, rps }))
+
+const BANDS: LineChartBand[] = [
+  { from: 2, to: 5, tone: 'neutral' },
+  { from: 18, to: 20, tone: 'danger' },
+]
+
+const LINES: LineChartReferenceLine[] = [
+  { value: 4000, label: '평시 4,000', tone: 'neutral' },
+  { value: 6500, label: '한도 6,500', tone: 'danger' },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 560 }}>
+      <LineChart
+        data={DATA}
+        xKey="hour"
+        series={[{ key: 'rps', label: '초당 요청', color: '--chart-2' }]}
+        curve="smooth"
+        area
+        height={220}
+        bands={BANDS}
+        referenceLines={LINES}
+        formatValue={(v) => `${v.toLocaleString('ko-KR')}건/초`}
+        legend={false}
+        aria-label="시간대별 초당 요청 수"
+      />
+      <ChartLegend
+        items={[
+          { key: 'maintenance', label: '정기 점검', color: '--surface-active' },
+          { key: 'over', label: '한도 초과', color: '--danger-soft' },
+        ]}
+      />
+    </Stack>
+  )
+}
+```
+
+### 실시간 스트리밍
+
+streaming은 데이터가 한 칸씩 밀릴 때 모양을 바꾸지 않고 플롯 전체를 왼쪽으로 미끄러뜨려요(숫자 = 이동 ms, 갱신 주기와 맞추면 끊김 없이 흘러요). 작고 낮은 높이에 yTicks={[0, 12, 24]}, xTicks="edges"로 양 끝 라벨만, endDot="pulse"로 마지막 점에 맥박을 둬요.
+
+```tsx
+import { useEffect, useState } from 'react'
+import { Pause, Play } from 'lucide-react'
+import { LineChart, type LineChartBand, Button, Inline, Stack, Text } from '@iamfiro/design'
+
+const POINTS = 97 // one per second → "96초 전" … "지금"
+const LIMIT = 12
+
+/** Next queue depth: small drift pulled back toward ~6, an occasional burst or drain. */
+const step = (prev: number, r: number) => {
+  const drift = (r < 0.06 ? 8 : r > 0.94 ? -6 : (r - 0.5) * 3) + (6 - prev) * 0.12
+  return Math.max(0, Math.min(23, Math.round(prev + drift)))
+}
+
+// A fixed seed keeps the first picture the same on every load.
+const INITIAL = (() => {
+  let seed = 11
+  const rand = () => (seed = (seed * 16807) % 2147483647) / 2147483647
+  const rows: Array<{ id: number; depth: number }> = []
+  let depth = 4
+  for (let i = 0; i < POINTS; i++) {
+    depth = step(depth, rand())
+    rows.push({ id: i, depth })
+  }
+  return rows
+})()
+
+/** Runs of rows at or over the limit become warning bands. */
+function overLimit(rows: Array<{ depth: number }>): LineChartBand[] {
+  const bands: LineChartBand[] = []
+  rows.forEach((r, i) => {
+    if (r.depth < LIMIT) return
+    const last = bands[bands.length - 1]
+    if (last && last.to === i - 1) last.to = i
+    else bands.push({ from: Math.max(0, i - 1), to: i, tone: 'warning' })
+  })
+  return bands
+}
+
+const ago = (i: number) => (i === POINTS - 1 ? '지금' : `${POINTS - 1 - i}초 전`)
+
+export default function Example() {
+  const [rows, setRows] = useState(INITIAL)
+  const [running, setRunning] = useState(true)
+
+  useEffect(() => {
+    if (!running) return
+    const id = window.setInterval(() => {
+      setRows((prev) => {
+        const last = prev[prev.length - 1]
+        return [...prev.slice(1), { id: last.id + 1, depth: step(last.depth, Math.random()) }]
+      })
+    }, 1000)
+    return () => window.clearInterval(id)
+  }, [running])
+
+  return (
+    <Stack gap={2} style={{ width: '100%', maxWidth: 560 }}>
+      <Inline justify="between">
+        <Text variant="overline">배포 대기열</Text>
+        <Button size="sm" variant="ghost" icon={running ? <Pause /> : <Play />} onClick={() => setRunning((r) => !r)}>
+          {running ? '일시정지' : '재개'}
+        </Button>
+      </Inline>
+      <LineChart
+        data={rows}
+        xKey="id"
+        series={[{ key: 'depth', label: '대기 작업', color: '--chart-4' }]}
+        area="solid"
+        height={140}
+        yTicks={[0, 12, 24]}
+        xTicks="edges"
+        formatX={(_, i) => ago(i)}
+        formatTitle={(_, i) => ago(i)}
+        formatValue={(v) => `${v}개`}
+        bands={overLimit(rows)}
+        referenceLines={[{ value: LIMIT }]}
+        endDot={running ? 'pulse' : true}
+        streaming={1000}
+        legend={false}
+        aria-label="최근 96초 배포 대기열 길이"
+      />
+    </Stack>
+  )
+}
+```

package/agents/link/AGENTS.md

@@ -0,0 +1,53 @@
+# Link
+
+> 버튼 & 링크 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+글 속 링크. 옅은 밑줄이 있고 마우스를 올리면 밑줄이 진해져요. 본문에선 파란 accent, 회색 설명 줄 · 이벤트 줄(Marker) 안에선 주변 글자색을 그대로 쓰는 inherit을 써요. 버튼처럼 동작하는 것은 Button variant="ghost"로 만들어요.
+
+```tsx
+import { Link } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 대화 사이의 이벤트 줄(초대 · 병합 · 고정)은 `Marker`: 16px 아이콘 + 회색 한 줄, 배경 · 테두리 없음. 아이콘은 기본 회색, 결과에 상태가 담긴 이벤트만 `tone`(병합 = success). 스레드 안에선 `gutter={avatarSize}`로 아바타 열에 맞춘다. 글 속 참조(#482)는 `Link variant="inherit"`(주변 색 + 밑줄).
+
+## API
+
+### Link
+
+<a>의 모든 속성(href, target, onClick…)을 그대로 받아요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `variant` | `'accent' \| 'inherit'` | `'accent'` | accent: 파란 글자 · inherit: 주변 글자색 + 밑줄, hover에 진한 글자. |
+| `href` | `string` |  | 이동할 주소. |
+| `className` | `string` |  | 추가 클래스. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### accent · inherit
+
+accent는 본문 속 링크, inherit은 회색 글 안에서 밑줄로만 링크임을 알려요. 키보드로 포커스하면 파란 링이 생겨요.
+
+```tsx
+import { Link, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ maxWidth: 420 }}>
+      <Text variant="body-md">
+        자세한 설정은 <Link href="#">워크스페이스 설정</Link>에서 바꿀 수 있어요.
+      </Text>
+      <Text variant="body-md" tone="secondary">
+        박솔 님이 <Link variant="inherit" href="#">#482</Link>를 main에 병합했어요.
+      </Text>
+      <Text variant="caption" tone="tertiary">
+        마지막 배포 <Link variant="inherit" href="#">v2.14.0</Link> · 10월 25일
+      </Text>
+    </Stack>
+  )
+}
+```