@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/spark-chart/AGENTS.md

@@ -0,0 +1,257 @@
+# SparkChart
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+축 없이 흐름만 보여 주는 아주 작은 차트. 표의 칸이나 KPI 카드에 넣어요. SparkLine(선) · SparkArea(선 + 옅은 그라데이션) · Sparkbar(막대)가 같은 props를 쓰고, SparkChart type으로 하나를 골라요. 24–40px 높이에서도 또렷하게 실제 픽셀 크기로 그리며, 마우스·터치·←/→로 십자선 점과 값 카드를 띄워요. tone="trend"는 처음 값 대비 마지막 값의 방향으로 색을 정해요(Delta처럼 higherIs로 좋고 나쁨).
+
+```tsx
+import { SparkArea, SparkChart, SparkLine } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 표 칸 · KPI 카드의 작은 추이는 `SparkLine` · `SparkArea` · `Sparkbar`(같은 props, 하나로 고르면 `SparkChart type`). 축 없음, 실제 픽셀 크기로 그려 24–40px에서도 또렷하게, 값 범위는 0이 아니라 최솟값–최댓값. 색은 `tone="trend"` + `higherIs`(Delta와 같은 규칙), 마지막 값은 `endDot`. 긴 표에선 `tooltip={false}`로 이벤트 없는 정적 그림(`role="img"`). KPI 카드는 Card 안 `Stat` + `Delta` + `SparkArea`.
+
+## API
+
+### SparkLine · SparkArea
+
+SparkArea는 SparkLine props + fill.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `(number \| null)[]` |  | 한 칸에 값 하나(오래된 것부터). null이면 선이 끊겨요. |
+| `height` | `number` | `32` | 높이(px). 24–40을 권장해요. |
+| `width` | `number \| string` | `'100%'` | 너비. 표 칸에선 숫자로 고정해요. |
+| `curve` | `'linear' \| 'smooth'` | `'smooth'` | 직선 또는 튀어 오르지 않는 단조 곡선. |
+| `tone` | `'accent' \| 'neutral' \| 'trend'` | `'accent'` | trend는 방향(마지막 값 − 처음 값)에 따라 초록 / 주황. |
+| `higherIs` | `'better' \| 'worse' \| 'neutral'` | `'better'` | trend에서 오르는 게 좋은지. 시간 · 비용 · 오류는 worse. |
+| `worseTone` | `'warning' \| 'danger'` | `'warning'` | 나빠졌을 때 색. |
+| `color` | `string` |  | 직접 정한 색(CSS 변수 '--chart-2' 또는 색). tone보다 우선. |
+| `min / max` | `number` |  | 값 범위. 기본은 데이터의 최솟값 · 최댓값(모양을 보여 주는 차트라 0부터가 아니에요). |
+| `endDot` | `boolean` |  | 마지막 값에 점. |
+| `fill` | `'gradient' \| 'solid'` | `'gradient'` | SparkArea 채움. |
+| `tooltip` | `boolean` | `true` | 십자선 점 + 값 카드. false면 이벤트 · 포커스 없는 정적 그림. |
+| `formatLabel` | `(index) => string` | `'3일'` | 툴팁 제목. |
+| `valueLabel` | `string` | `'값'` | 툴팁 행 이름. |
+| `formatValue` | `(value) => string` | `'1,234'` | 툴팁 값 형식. |
+| `activeIndex / defaultActiveIndex / onActiveIndexChange` | `number \| null` |  | 고른 칸(제어/비제어). |
+| `aria-label` | `string` | `'추이'` | 이름. 고른 값은 aria-live로 읽어요. |
+
+### SparkChart
+
+위 props 전부 + type. bar는 Sparkbar로 그려요(Sparkbar도 tone · higherIs · worseTone을 받아요).
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `type` | `'line' \| 'area' \| 'bar'` | `'line'` | 그릴 모양. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### KPI 카드
+
+Card 안에 Stat + Delta + SparkArea. 응답 시간처럼 낮을수록 좋은 지표는 higherIs="worse"로 내려가는 선이 초록이 돼요. endDot은 마지막 값에 점을 찍어요.
+
+```tsx
+import { Delta, Grid, Stack, Card, CardBody, SparkArea, Stat } from '@iamfiro/design'
+
+const DAYS = ['10월 12일', '10월 13일', '10월 14일', '10월 15일', '10월 16일', '10월 17일', '10월 18일', '10월 19일', '10월 20일', '10월 21일', '10월 22일', '10월 23일', '10월 24일', '10월 25일']
+
+const KPIS = [
+  {
+    label: '매출',
+    value: '₩4,820만',
+    delta: 12.4,
+    higherIs: 'better' as const,
+    unit: '만 원',
+    data: [312, 298, 330, 341, 325, 352, 368, 344, 371, 389, 402, 396, 418, 432],
+  },
+  {
+    label: '활성 사용자',
+    value: '18,240',
+    delta: -3.1,
+    higherIs: 'better' as const,
+    unit: '명',
+    data: [19400, 19120, 19310, 18980, 18760, 18900, 18640, 18520, 18710, 18450, 18390, 18300, 18260, 18240],
+  },
+  {
+    label: '평균 응답 시간',
+    value: '182ms',
+    delta: -8.6,
+    higherIs: 'worse' as const,
+    unit: 'ms',
+    data: [214, 220, 205, 211, 198, 201, 195, 190, 193, 188, 186, 191, 184, 182],
+  },
+]
+
+export default function Example() {
+  return (
+    <Grid minItemWidth={200} gap={3} style={{ width: '100%' }}>
+      {KPIS.map((k) => (
+        <Card key={k.label}>
+          <CardBody>
+            <Stack gap={3}>
+              <Stat label={k.label} value={k.value} delta={<Delta value={k.delta} format={(n) => `${n}%`} higherIs={k.higherIs} size="sm" />} />
+              <SparkArea
+                data={k.data}
+                height={40}
+                tone="trend"
+                higherIs={k.higherIs}
+                endDot
+                formatLabel={(i) => DAYS[i]}
+                valueLabel={k.label}
+                formatValue={(v) => `${v.toLocaleString('ko-KR')}${k.unit}`}
+                aria-label={`${k.label} 최근 14일`}
+              />
+            </Stack>
+          </CardBody>
+        </Card>
+      ))}
+    </Grid>
+  )
+}
+```
+
+### 표 안의 추이
+
+Table 칸에 width를 정한 SparkLine. null은 선이 끊긴 칸이에요. 칸 위에서 마우스를 움직이면 그날 값이 떠요.
+
+```tsx
+import { Delta, Text, SparkLine, Table, type TableColumn } from '@iamfiro/design'
+
+interface Page {
+  id: string
+  path: string
+  views: number
+  change: number
+  /** 최근 14일 조회수 */
+  trend: Array<number | null>
+}
+
+const PAGES: Page[] = [
+  { id: 'p1', path: '/요금제', views: 12840, change: 18.2, trend: [620, 640, 610, 700, 760, 720, 810, 840, 860, 900, 950, 930, 1010, 1080] },
+  { id: 'p2', path: '/시작하기', views: 9310, change: 4.1, trend: [640, 660, 650, 630, 670, 690, 660, 680, 700, 690, 710, 700, 720, 730] },
+  { id: 'p3', path: '/블로그/출시-노트', views: 6120, change: -22.5, trend: [880, 820, 760, 640, 600, 520, 480, 430, 410, 380, 350, 330, 310, 290] },
+  { id: 'p4', path: '/고객-사례', views: 3470, change: 0, trend: [240, 260, 230, 250, 270, 240, 250, 260, 240, 250, 255, 245, 250, 248] },
+  { id: 'p5', path: '/문의', views: 1980, change: 9.7, trend: [110, 120, null, null, 130, 135, 140, 128, 150, 145, 155, 160, 158, 170] },
+]
+
+const COLUMNS: TableColumn<Page>[] = [
+  { key: 'path', header: '페이지', render: (p) => <Text variant="label-md">{p.path}</Text> },
+  { key: 'views', header: '조회수', numeric: true, render: (p) => p.views.toLocaleString('ko-KR') },
+  {
+    key: 'trend',
+    header: '최근 14일',
+    width: 120,
+    render: (p) => (
+      <SparkLine
+        data={p.trend}
+        width={112}
+        height={28}
+        tone="trend"
+        formatLabel={(i) => `10월 ${12 + i}일`}
+        valueLabel="조회수"
+        formatValue={(v) => `${v.toLocaleString('ko-KR')}회`}
+        aria-label={`${p.path} 최근 14일 조회수`}
+      />
+    ),
+  },
+  { key: 'change', header: '변화', align: 'end', render: (p) => <Delta value={p.change} format={(n) => `${n}%`} size="sm" /> },
+]
+
+export default function Example() {
+  return <Table caption="많이 본 페이지" columns={COLUMNS} rows={PAGES} rowKey={(p) => p.id} style={{ width: '100%', maxWidth: 640 }} />
+}
+```
+
+### 세 가지 type
+
+SparkChart type="line" | "area" | "bar". 데이터를 바꾸면 선은 새 모양으로, 막대는 새 높이로 미끄러져요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Grid, Inline, Stack, Text, SparkChart } from '@iamfiro/design'
+
+const THIS_WEEK = [32, 41, 38, 52, 47, 61, 58, 66, 72, 69, 80, 84]
+const LAST_WEEK = [28, 30, 35, 31, 40, 38, 44, 41, 39, 46, 43, 50]
+
+const TYPES = [
+  { type: 'line', label: '선 (line)' },
+  { type: 'area', label: '영역 (area)' },
+  { type: 'bar', label: '막대 (bar)' },
+] as const
+
+export default function Example() {
+  const [week, setWeek] = useState<'this' | 'last'>('this')
+  const data = week === 'this' ? THIS_WEEK : LAST_WEEK
+  return (
+    <Stack gap={5} style={{ width: '100%', maxWidth: 560 }}>
+      <Grid columns={3} gap={6}>
+        {TYPES.map((t) => (
+          <Stack key={t.type} gap={2}>
+            <Text variant="caption" tone="tertiary">
+              {t.label}
+            </Text>
+            <SparkChart
+              type={t.type}
+              data={data}
+              height={36}
+              tone="accent"
+              formatLabel={(i) => `${i * 2}시`}
+              valueLabel="주문"
+              formatValue={(v) => `${v}건`}
+              aria-label={`시간대별 주문 · ${t.label}`}
+            />
+          </Stack>
+        ))}
+      </Grid>
+      <Inline gap={2}>
+        <Button size="sm" variant={week === 'last' ? 'primary' : 'secondary'} onClick={() => setWeek('last')}>
+          지난주
+        </Button>
+        <Button size="sm" variant={week === 'this' ? 'primary' : 'secondary'} onClick={() => setWeek('this')}>
+          이번 주
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 추세 색 · 정적
+
+tone="trend" + higherIs · worseTone. tooltip={false}면 이벤트 없이 그림만 그려서(role="img") 긴 표에서도 가벼워요. fill="solid"는 한 겹의 옅은 색.
+
+```tsx
+import { Inline, Stack, Text, SparkArea, SparkLine } from '@iamfiro/design'
+
+const UP = [12, 14, 13, 17, 16, 19, 22, 21, 25, 27]
+const DOWN = [27, 25, 26, 22, 21, 19, 18, 15, 14, 12]
+
+const ROWS = [
+  { label: '가입 · 늘수록 좋음', data: UP, higherIs: 'better' as const },
+  { label: '이탈 · 줄수록 좋음', data: DOWN, higherIs: 'worse' as const },
+  { label: '오류 · 늘면 위험', data: UP, higherIs: 'worse' as const, worseTone: 'danger' as const },
+  { label: '방문 · 줄었음', data: DOWN, higherIs: 'better' as const },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 420 }}>
+      {ROWS.map((r) => (
+        <Inline key={r.label} justify="between" gap={4} wrap={false}>
+          <Text variant="body-sm" tone="secondary">
+            {r.label}
+          </Text>
+          <Inline gap={4} wrap={false}>
+            <SparkLine data={r.data} width={96} height={24} tone="trend" higherIs={r.higherIs} worseTone={r.worseTone} endDot tooltip={false} aria-label={r.label} />
+            <SparkArea data={r.data} width={96} height={24} tone="trend" higherIs={r.higherIs} worseTone={r.worseTone} curve="linear" fill="solid" tooltip={false} aria-label={r.label} />
+          </Inline>
+        </Inline>
+      ))}
+    </Stack>
+  )
+}
+```

package/agents/sparkbar/AGENTS.md

@@ -0,0 +1,92 @@
+# Sparkbar
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+축 없이 막대만 늘어놓은 작은 막대 줄. 합계 아래 일별 추이처럼 흐름만 보여 줄 때 써요. 바닥에서 자라고 데이터가 바뀌면 새 높이로 미끄러지며, 마우스·터치·←/→로 막대를 고르면 차트 툴팁 카드에 값이 떠요. null은 아직 기록이 없는 칸으로 납작한 자리 표시가 돼요.
+
+```tsx
+import { Sparkbar } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 차트: 시리즈 색은 `--chart-1…6`을 순서대로, 그리드는 `--chart-grid`로 아주 옅게(세로선·축선 없음). 범례·툴팁의 색 표시는 `ColorDot`, 툴팁은 `Card raised` + `Separator`로 조립. 축·툴팁·범례·호버/키보드는 `components/Chart/`의 공용 조각(`ChartTooltip`, `ChartLegend`, `useChartInteraction`)을 쓴다. → `LineChart` · `BarChart` · `PieChart` · `Sparkbar`
+- 표 칸 · KPI 카드의 작은 추이는 `SparkLine` · `SparkArea` · `Sparkbar`(같은 props, 하나로 고르면 `SparkChart type`). 축 없음, 실제 픽셀 크기로 그려 24–40px에서도 또렷하게, 값 범위는 0이 아니라 최솟값–최댓값. 색은 `tone="trend"` + `higherIs`(Delta와 같은 규칙), 마지막 값은 `endDot`. 긴 표에선 `tooltip={false}`로 이벤트 없는 정적 그림(`role="img"`). KPI 카드는 Card 안 `Stat` + `Delta` + `SparkArea`.
+
+## API
+
+### Sparkbar
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `(number \| null)[]` |  | 한 칸에 값 하나. null은 기록 없음(자리 표시). |
+| `height` | `number` | `48` | 높이(px). |
+| `max` | `number` |  | 막대가 꽉 차는 값. 기본은 가장 큰 값. |
+| `color` | `string` | `'--n5'` | 막대 색. CSS 변수 이름('--accent') 또는 색. |
+| `tone / higherIs / worseTone` | `'accent' \| 'neutral' \| 'trend'` |  | SparkLine과 같은 색 규칙. trend는 처음 대비 마지막 값의 방향으로 초록 / 주황. color가 우선이고, 둘 다 없으면 옅은 회색. |
+| `formatLabel` | `(index) => string` | `'3일'` | 툴팁 제목. |
+| `formatValue` | `(value) => string` | `'1,234'` | 툴팁 값 형식. |
+| `valueLabel` | `string` | `'값'` | 툴팁 행 이름. |
+| `tooltip` | `boolean` | `true` | 값 카드 표시. |
+| `activeIndex / defaultActiveIndex / onActiveIndexChange` | `number \| null` |  | 고른 막대(제어/비제어). |
+| `aria-label` | `string` | `'막대 그래프'` | 이름. 고른 막대는 aria-live로 읽어요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+기본 막대는 옅은 회색이고, 고른 막대만 조금 진해져요. 포커스한 뒤 ←/→, Home/End, Esc로도 움직여요.
+
+```tsx
+import { Sparkbar } from '@iamfiro/design'
+
+const VISITS = [42, 58, 51, 66, 73, 40, 35, 61, 70, 68, 77, 82, 49, 44, 69, 88, 91, 76, 84, 52, 47, 79, 86, 93]
+
+export default function Example() {
+  return (
+    <div style={{ width: '100%', maxWidth: 360 }}>
+      <Sparkbar data={VISITS} formatLabel={(i) => `${i}시`} valueLabel="방문" aria-label="시간대별 방문 수" />
+    </div>
+  )
+}
+```
+
+### 자리 표시 · 색 · 데이터 바뀜
+
+앞으로 올 날은 null로 두면 바닥에 납작한 선으로 보여요. color로 막대 색을 바꾸고, 달을 바꾸면 막대가 새 높이로 미끄러져요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, Stack, Sparkbar } from '@iamfiro/design'
+
+// 10월은 22일까지만 기록이 있어요. 남은 날은 null → 납작한 자리 표시.
+const OCTOBER = [12, 31, 29, 25, 42, 36, 16, 14, 38, 35, 34, 44, 33, 17, 19, 48, 42, 38, 40, 47, 22, 23, ...Array<null>(9).fill(null)]
+const SEPTEMBER = [26, 30, 28, 33, 31, 18, 15, 29, 35, 33, 30, 36, 20, 17, 31, 38, 34, 32, 40, 21, 19, 33, 36, 35, 31, 39, 22, 18, 30, 32]
+
+export default function Example() {
+  const [month, setMonth] = useState<9 | 10>(10)
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 360 }}>
+      <Sparkbar
+        data={month === 10 ? OCTOBER : SEPTEMBER}
+        height={56}
+        color="--accent"
+        formatLabel={(i) => `${month}월 ${i + 1}일`}
+        formatValue={(v) => `${v}건`}
+        valueLabel="주문"
+        aria-label={`${month}월 일별 주문`}
+      />
+      <Inline gap={2}>
+        <Button size="sm" variant={month === 9 ? 'primary' : 'secondary'} onClick={() => setMonth(9)}>
+          9월
+        </Button>
+        <Button size="sm" variant={month === 10 ? 'primary' : 'secondary'} onClick={() => setMonth(10)}>
+          10월
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```

package/agents/spinner/AGENTS.md

@@ -0,0 +1,123 @@
+# Spinner
+
+> 진행 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+옅은 고리 위로 호가 돌면서 늘었다 줄었다 하는 로딩 표시. 진행률을 알 수 없는 짧은 기다림에 써요. 기본 색은 주변 글자 색을 따라가고, 스크린 리더에는 label을 읽어 줘요.
+
+```tsx
+import { Spinner } from '@iamfiro/design'
+```
+
+## API
+
+### Spinner
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number` | `'sm'` | 이름 있는 크기 또는 px 숫자. |
+| `tone` | `'default' \| 'muted' \| 'accent' \| 'inverse' \| 'inherit'` | `'inherit'` | 색. inherit은 글자 색을 따라가요. |
+| `label` | `string` | `'불러오는 중'` | 스크린 리더가 읽는 이름(role="status"). |
+| `className / style` | `string / CSSProperties` |  | 루트에 적용돼요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 크기
+
+xs 12 · sm 14 · md 18 · lg 24 · xl 32px. 숫자를 넘기면 그 크기(px)로 그려요.
+
+```tsx
+import { Spinner, Text, type SpinnerSize } from '@iamfiro/design'
+
+const SIZES: SpinnerSize[] = ['xs', 'sm', 'md', 'lg', 'xl']
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'flex-end', gap: 32 }}>
+      {SIZES.map((size) => (
+        <div key={size} style={{ display: 'grid', justifyItems: 'center', gap: 10 }}>
+          <Spinner size={size} tone="default" />
+          <Text variant="caption" tone="tertiary">
+            {size}
+          </Text>
+        </div>
+      ))}
+      <div style={{ display: 'grid', justifyItems: 'center', gap: 10 }}>
+        <Spinner size={48} tone="default" />
+        <Text variant="caption" tone="tertiary">
+          48
+        </Text>
+      </div>
+    </div>
+  )
+}
+```
+
+### 색
+
+default · muted · accent는 정해진 색, inverse는 어두운 배경용이에요. 기본값 'inherit'은 currentColor를 써서 글자 색을 따라가요.
+
+```tsx
+import { Spinner, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', justifyContent: 'center', gap: 28 }}>
+      <Spinner size="lg" tone="default" label="기본" />
+      <Spinner size="lg" tone="muted" label="흐리게" />
+      <Spinner size="lg" tone="accent" label="강조" />
+      <div style={{ display: 'grid', placeItems: 'center', width: 48, height: 48, borderRadius: 12, background: 'var(--primary)' }}>
+        <Spinner size="lg" tone="inverse" label="어두운 배경" />
+      </div>
+      <Text tone="success" style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}>
+        <Spinner />
+        글자 색을 따라가요
+      </Text>
+    </div>
+  )
+}
+```
+
+### 버튼 · 인라인
+
+Button의 loading을 켜면 아이콘 자리에 Spinner가 들어가고 눌리지 않아요. 짧은 상태 문구 옆에도 써요.
+
+```tsx
+import { useState } from 'react'
+import { RefreshCw, Save } from 'lucide-react'
+import { Button, Spinner, Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [saving, setSaving] = useState(false)
+  const [syncing, setSyncing] = useState(false)
+
+  const save = () => {
+    setSaving(true)
+    setTimeout(() => setSaving(false), 1600)
+  }
+
+  const sync = () => {
+    setSyncing(true)
+    setTimeout(() => setSyncing(false), 2400)
+  }
+
+  return (
+    <div style={{ display: 'grid', justifyItems: 'center', gap: 20 }}>
+      <div style={{ display: 'flex', gap: 8 }}>
+        <Button variant="primary" icon={<Save />} loading={saving} onClick={save}>
+          {saving ? '저장 중…' : '저장'}
+        </Button>
+        <Button iconOnly icon={<RefreshCw />} loading={syncing} onClick={sync} aria-label="동기화" />
+        <Button size="sm" loading>
+          작은 버튼
+        </Button>
+      </div>
+      <Text variant="body-sm" tone="tertiary" style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}>
+        {syncing && <Spinner size="xs" />}
+        {syncing ? '동기화 중…' : '2분 전에 동기화됨'}
+      </Text>
+    </div>
+  )
+}
+```