@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/bar-chart/AGENTS.md

@@ -0,0 +1,386 @@
+# BarChart
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+항목끼리 크기를 비교하는 막대 차트. LineChart와 같은 축·툴팁·범례를 써요. 마우스를 올린 칸은 옅은 회색으로 채워지고 나머지 막대는 흐려지며, 막대는 바닥에서 자라고 데이터가 바뀌면 새 높이로 미끄러져요.
+
+```tsx
+import { BarChart, type BarSeries } 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
+
+### BarChart
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `BarChartRow[]` |  | 행 목록. 한 행 = 막대 한 칸. |
+| `xKey` (필수) | `string` |  | x축 라벨이 든 필드. |
+| `series` (필수) | `BarSeries[]` |  | 시리즈. color를 생략하면 --chart-1부터 순서대로. |
+| `stacked` | `boolean` | `false` | 한 막대에 쌓아요. |
+| `height` | `number` | `240` | 축 라벨을 포함한 높이(px). |
+| `yTickCount` | `number` | `3` | y축 라벨 개수(0 포함). |
+| `yMax` | `number` |  | y축 위 끝을 고정. |
+| `formatValue` | `(value, series) => string` | `'1,234'` | 툴팁 값 형식. |
+| `formatAxisValue` | `(value) => string` | `'6천'` | y축 라벨 형식. |
+| `formatX / formatTitle` | `(row, index) => …` |  | x축 라벨 · 툴팁 제목 형식. |
+| `showTotal` | `boolean` | `stacked` | 툴팁 아래 합계 행. |
+| `legend` | `boolean` | `true` | 아래 범례. 마우스를 올리면 해당 시리즈 강조. |
+| `activeIndex / defaultActiveIndex / onActiveIndexChange` | `number \| null` |  | 하이라이트한 칸(제어/비제어). |
+| `selected / defaultSelected / onSelectedChange` | `number \| null` |  | 고른 칸(제어/비제어). 고른 칸과 마우스를 올린 칸만 진하고 나머지는 옅어져요. |
+| `selectable` | `boolean` |  | 클릭 · Enter/Space로 칸을 골라요. selected 관련 prop을 넘기면 자동으로 켜져요. |
+| `xIcon` | `(row, index) => ReactNode` |  | x축 라벨 대신 아이콘. 고른 칸은 아이콘 + formatX 라벨의 흰 칩(--shadow-chip)으로 펼쳐져요. |
+| `yAxis` | `'left' \| 'right'` | `'left'` | 값 축 위치. |
+| `yTicks` | `number[]` |  | y축 값을 직접 지정(yTickCount · yMax 무시). |
+| `segmentGap` | `number` | `0` | 누적 조각 사이 흰 틈(px). |
+| `tooltipLeading` | `(row, index) => ReactNode` |  | 툴팁 제목 앞 요소(아이콘, Checkbox). |
+| `totalPlacement` | `'footer' \| 'header'` | `'footer'` | 합계 위치. header면 제목 줄 오른쪽에 두고 Separator 아래에 시리즈 행이 와요. |
+| `tooltipSort` | `'series' \| 'reverse' \| 'value'` | `'series'` | 툴팁 행 순서. reverse는 누적 막대의 위 조각부터. |
+| `aria-label` | `string` | `'막대 차트'` | 차트 이름. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 묶음
+
+시리즈를 나란히 세워 칸마다 비교해요. ←/→, Home/End, Esc로도 움직여요.
+
+```tsx
+import { BarChart, type BarSeries } from '@iamfiro/design'
+
+const SERIES: BarSeries[] = [
+  { key: 'thisYear', label: '올해', color: '--chart-2' },
+  { key: 'lastYear', label: '작년', color: '--chart-5' },
+]
+
+const DATA = [
+  { q: '1분기', thisYear: 4200, lastYear: 3100 },
+  { q: '2분기', thisYear: 5100, lastYear: 3900 },
+  { q: '3분기', thisYear: 4700, lastYear: 4400 },
+  { q: '4분기', thisYear: 6200, lastYear: 4800 },
+]
+
+export default function Example() {
+  return (
+    <BarChart
+      data={DATA}
+      xKey="q"
+      series={SERIES}
+      formatValue={(v) => `${v.toLocaleString('ko-KR')}만 원`}
+      aria-label="분기별 매출"
+      style={{ width: '100%', maxWidth: 560 }}
+    />
+  )
+}
+```
+
+### 누적
+
+stacked는 한 막대에 쌓고, 툴팁 아래에 합계를 보여줘요. 맨 위 조각만 모서리가 둥글어요.
+
+```tsx
+import { BarChart, type BarSeries } from '@iamfiro/design'
+
+const SERIES: BarSeries[] = [
+  { key: 'bug', label: '버그' },
+  { key: 'feature', label: '기능' },
+  { key: 'chore', label: '정리' },
+]
+
+const DATA = [
+  { day: '월', bug: 8, feature: 12, chore: 3 },
+  { day: '화', bug: 5, feature: 15, chore: 6 },
+  { day: '수', bug: 11, feature: 9, chore: 4 },
+  { day: '목', bug: 6, feature: 18, chore: 2 },
+  { day: '금', bug: 4, feature: 14, chore: 9 },
+  { day: '토', bug: 2, feature: 5, chore: 1 },
+  { day: '일', bug: 1, feature: 3, chore: 2 },
+]
+
+export default function Example() {
+  return (
+    <BarChart
+      data={DATA}
+      xKey="day"
+      series={SERIES}
+      stacked
+      formatValue={(v) => `${v}건`}
+      formatTitle={(row) => `${row.day}요일`}
+      aria-label="요일별 처리한 이슈"
+      style={{ width: '100%', maxWidth: 560 }}
+    />
+  )
+}
+```
+
+### 단일 시리즈
+
+시리즈가 하나면 범례를 끄고 제목만으로 충분해요.
+
+```tsx
+import { BarChart, Stack, Text } from '@iamfiro/design'
+
+const DATA = [
+  { hour: '9시', visits: 120 },
+  { hour: '10시', visits: 340 },
+  { hour: '11시', visits: 410 },
+  { hour: '12시', visits: 290 },
+  { hour: '13시', visits: 260 },
+  { hour: '14시', visits: 380 },
+  { hour: '15시', visits: 450 },
+  { hour: '16시', visits: 400 },
+  { hour: '17시', visits: 310 },
+  { hour: '18시', visits: 180 },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 560 }}>
+      <Text variant="heading-xs" as="h3">
+        시간대별 방문
+      </Text>
+      <BarChart data={DATA} xKey="hour" series={[{ key: 'visits', label: '방문' }]} legend={false} height={200} formatValue={(v) => `${v}회`} />
+    </Stack>
+  )
+}
+```
+
+### 선택 · 아이콘 축
+
+selected/onSelectedChange로 한 칸을 고르면 나머지는 옅은 색으로 바뀌어요. 클릭하거나 화살표로 옮겨 Enter/Space로 골라요. xIcon은 x축에 아이콘을 두고, 고른 칸은 아이콘 + 이름이 든 흰 칩으로 펼쳐져요. yAxis="right", segmentGap, 시리즈별 color, 툴팁 제목 줄의 tooltipLeading · totalPlacement="header"도 함께 보여요.
+
+```tsx
+import { useState } from 'react'
+import { CreditCard, Globe, Search, Server, Smartphone } from 'lucide-react'
+import { BarChart, type BarSeries, Stack, Text } from '@iamfiro/design'
+
+const SERIES: BarSeries[] = [
+  { key: 'success', label: '성공', color: '--chart-3' },
+  { key: 'rollback', label: '롤백', color: '--warning' },
+  { key: 'failed', label: '실패', color: '--danger' },
+]
+
+const DATA = [
+  { service: '웹', success: 42, rollback: 3, failed: 2 },
+  { service: '모바일', success: 18, rollback: 1, failed: 1 },
+  { service: 'API', success: 57, rollback: 5, failed: 4 },
+  { service: '결제', success: 12, rollback: 2, failed: 0 },
+  { service: '검색', success: 25, rollback: 0, failed: 1 },
+]
+
+const ICONS = [Globe, Smartphone, Server, CreditCard, Search]
+
+export default function Example() {
+  const [selected, setSelected] = useState<number | null>(2)
+  const row = selected === null ? null : DATA[selected]
+
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 560 }}>
+      <BarChart
+        data={DATA}
+        xKey="service"
+        series={SERIES}
+        stacked
+        segmentGap={2}
+        yAxis="right"
+        height={260}
+        xIcon={(_, i) => { const Icon = ICONS[i]; return <Icon size={16} /> }}
+        selected={selected}
+        onSelectedChange={setSelected}
+        tooltipLeading={(_, i) => { const Icon = ICONS[i]; return <Icon size={16} /> }}
+        totalPlacement="header"
+        tooltipSort="reverse"
+        formatValue={(v) => `${v}건`}
+        aria-label="서비스별 이번 주 배포"
+      />
+      <Text variant="body-sm" tone="secondary">
+        {row ? `${row.service}: 배포 ${row.success + row.rollback + row.failed}건 중 ${row.success}건 성공` : '막대를 눌러 서비스를 골라 보세요.'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 표와 연동 (피벗)
+
+스프린트 작업을 상태 × 우선순위로 나눠요. 막대를 고르면 표의 행이, 표의 행을 누르면 막대가 강조돼요. 위의 Select로 측정값·분류·세분화를 바꾸면 막대가 새 높이로 미끄러지고, 범례는 표 아래에 ChartLegend로 따로 둬요.
+
+```tsx
+import { useState, type ReactNode } from 'react'
+import { CircleSlash, Clock, Eye, Inbox, Square, SquareCheck } from 'lucide-react'
+import { BarChart, Card, CardBody, CardHeader, ChartLegend, Select, Table, type BarChartRow, type BarSeries, type TableColumn, Avatar, ColorDot, Field, Grid, Inline, Stack, Text } from '@iamfiro/design'
+
+type Measure = 'count' | 'points'
+type Slice = 'status' | 'assignee'
+type Segment = 'priority' | 'none'
+
+const PRIORITIES = [
+  { key: 'urgent', label: '긴급', color: '--danger', points: 5 },
+  { key: 'high', label: '높음', color: '--warning', points: 3 },
+  { key: 'medium', label: '보통', color: '--accent', points: 3 },
+  { key: 'low', label: '낮음', color: '--chart-seq-3', points: 2 },
+  { key: 'none', label: '없음', color: '--chart-5', points: 1 },
+]
+
+interface Group {
+  id: string
+  label: string
+  icon: ReactNode
+  /** Task count per priority, in PRIORITIES order. */
+  counts: number[]
+}
+
+const GROUPS: Record<Slice, Group[]> = {
+  status: [
+    { id: 'backlog', label: '백로그', icon: <Inbox size={16} color="var(--text-3)" />, counts: [3, 6, 6, 8, 3] },
+    { id: 'todo', label: '할 일', icon: <Square size={16} color="var(--text-3)" />, counts: [1, 7, 12, 11, 5] },
+    { id: 'progress', label: '진행 중', icon: <Clock size={16} color="var(--accent)" />, counts: [1, 9, 12, 7, 5] },
+    { id: 'review', label: '검토 중', icon: <Eye size={16} color="var(--chart-4)" />, counts: [0, 1, 6, 4, 2] },
+    { id: 'done', label: '완료', icon: <SquareCheck size={16} color="var(--accent)" />, counts: [7, 14, 23, 25, 27] },
+    { id: 'canceled', label: '취소', icon: <CircleSlash size={16} color="var(--text-3)" />, counts: [0, 1, 3, 1, 2] },
+  ],
+  assignee: [
+    { id: 'minji', label: '김민지', icon: <Avatar name="김민지" size={18} />, counts: [4, 11, 17, 14, 9] },
+    { id: 'dohyun', label: '이도현', icon: <Avatar name="이도현" size={18} />, counts: [3, 9, 15, 12, 10] },
+    { id: 'seoyeon', label: '박서연', icon: <Avatar name="박서연" size={18} />, counts: [2, 10, 16, 18, 13] },
+    { id: 'junho', label: '최준호', icon: <Avatar name="최준호" size={18} />, counts: [3, 8, 14, 12, 12] },
+  ],
+}
+
+const MEASURE_LABEL: Record<Measure, string> = { count: '작업 수', points: '스토리 포인트' }
+const SLICE_LABEL: Record<Slice, string> = { status: '상태', assignee: '담당자' }
+
+/** One row per group: the total plus a field per priority. */
+function pivot(slice: Slice, measure: Measure): BarChartRow[] {
+  return GROUPS[slice].map((g) => {
+    const values = g.counts.map((c, i) => (measure === 'points' ? c * PRIORITIES[i].points : c))
+    return {
+      id: g.id,
+      label: g.label,
+      total: values.reduce((a, b) => a + b, 0),
+      ...Object.fromEntries(PRIORITIES.map((p, i) => [p.key, values[i]])),
+    }
+  })
+}
+
+export default function Example() {
+  const [measure, setMeasure] = useState<Measure>('count')
+  const [slice, setSlice] = useState<Slice>('status')
+  const [segment, setSegment] = useState<Segment>('priority')
+  const [selectedId, setSelectedId] = useState<string | null>('done')
+
+  const rows = pivot(slice, measure)
+  const icons = Object.fromEntries(GROUPS[slice].map((g) => [g.id, g.icon]))
+  const series: BarSeries[] =
+    segment === 'priority' ? PRIORITIES.map((p) => ({ key: p.key, label: p.label, color: p.color })) : [{ key: 'total', label: MEASURE_LABEL[measure], color: '--accent' }]
+  const selectedIndex = rows.findIndex((r) => r.id === selectedId)
+  const grandTotal = rows.reduce((a, r) => a + Number(r.total), 0)
+  const unit = measure === 'count' ? '개' : '점'
+
+  const columns: TableColumn<BarChartRow>[] = [
+    { key: 'label', header: SLICE_LABEL[slice], leading: (r) => icons[String(r.id)] },
+    { key: 'total', header: MEASURE_LABEL[measure], numeric: true },
+    ...(segment === 'priority'
+      ? PRIORITIES.map((p): TableColumn<BarChartRow> => ({ key: p.key, header: p.label, headerLeading: <ColorDot color={p.color} />, numeric: true }))
+      : []),
+  ]
+
+  return (
+    <Card style={{ width: '100%', maxWidth: 620 }}>
+      <CardHeader
+        title="스프린트 24"
+        actions={
+          <Inline gap={1} align="baseline" wrap={false}>
+            <Text variant="number-sm">{grandTotal.toLocaleString('ko-KR')}</Text>
+            <Text variant="body-sm" tone="tertiary">
+              {unit}
+            </Text>
+          </Inline>
+        }
+      />
+      <CardBody>
+        <Stack gap={5}>
+          <Grid columns={3} gap={2}>
+            <Field label="측정값" htmlFor="pivot-measure">
+              <Select<Measure>
+                id="pivot-measure"
+                size="sm"
+                value={measure}
+                onValueChange={setMeasure}
+                options={[
+                  { value: 'count', label: '작업 수' },
+                  { value: 'points', label: '스토리 포인트' },
+                ]}
+              />
+            </Field>
+            <Field label="분류" htmlFor="pivot-slice">
+              <Select<Slice>
+                id="pivot-slice"
+                size="sm"
+                value={slice}
+                onValueChange={(v) => {
+                  setSlice(v)
+                  setSelectedId(null)
+                }}
+                options={[
+                  { value: 'status', label: '상태' },
+                  { value: 'assignee', label: '담당자' },
+                ]}
+              />
+            </Field>
+            <Field label="세분화" htmlFor="pivot-segment">
+              <Select<Segment>
+                id="pivot-segment"
+                size="sm"
+                value={segment}
+                onValueChange={setSegment}
+                options={[
+                  { value: 'priority', label: '우선순위' },
+                  { value: 'none', label: '없음' },
+                ]}
+              />
+            </Field>
+          </Grid>
+
+          <BarChart
+            data={rows}
+            xKey="label"
+            series={series}
+            stacked
+            segmentGap={2}
+            height={280}
+            yAxis="right"
+            yTickCount={6}
+            xIcon={(r) => icons[String(r.id)]}
+            selected={selectedIndex < 0 ? null : selectedIndex}
+            onSelectedChange={(i) => setSelectedId(i === null ? null : String(rows[i].id))}
+            tooltipLeading={(r) => icons[String(r.id)]}
+            totalPlacement="header"
+            tooltipSort="reverse"
+            legend={false}
+            aria-label={`${SLICE_LABEL[slice]}별 ${MEASURE_LABEL[measure]}`}
+          />
+
+          <Table
+            columns={columns}
+            rows={rows}
+            rowKey={(r) => String(r.id)}
+            headerVariant="overline"
+            striped={false}
+            selectedKey={selectedId}
+            onRowClick={(r) => setSelectedId(String(r.id))}
+          />
+
+          {segment === 'priority' && <ChartLegend items={PRIORITIES.map((p) => ({ key: p.key, label: p.label, color: p.color }))} />}
+        </Stack>
+      </CardBody>
+    </Card>
+  )
+}
+```

package/agents/bar-list/AGENTS.md

@@ -0,0 +1,223 @@
+# BarList
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+많이 본 페이지 · 유입 경로 · 국가처럼 순위를 매긴 가로 막대 목록. 이름 뒤로 값에 비례한 옅은 막대가 깔리고, 값은 오른쪽에 tabular 숫자로 맞춰요. 처음엔 막대가 왼쪽에서 자라고, 데이터가 바뀌면 새 폭으로 미끄러지며 순서가 바뀐 행은 새 자리로 움직여요. 긴 목록은 limit으로 접어 "더 보기"로 펼쳐요.
+
+```tsx
+import { BarList } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 순위 목록(많이 본 페이지 · 유입 경로 · 국가)은 `BarList`: 이름 뒤로 옅은 막대(`tone` 또는 `color` 16% 섞기), 값은 오른쪽 tabular. 긴 목록은 `limit` + "더 보기"(0fr ↔ 1fr), 순위가 바뀌면 행이 새 자리로 미끄러진다. 행 진행률 하나면 `ListItem progress`.
+
+## API
+
+### BarList
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `BarListItem[]` |  | { key?, name, value, icon?, href?, color? } 목록. |
+| `sortOrder` | `'descending' \| 'ascending' \| 'none'` | `'descending'` | 행 순서. none은 data 순서 그대로. |
+| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger'` | `'accent'` | 막대의 옅은 채움 색. |
+| `color` | `string` |  | tone 대신 쓸 색. CSS 변수 이름('--chart-1') 또는 색, 옅게 섞어 칠해요. 행마다 item.color로도. |
+| `formatValue` | `(value, item) => string` | `'1,234'` | 값 형식. |
+| `onValueChange` | `(item, index) => void` |  | 주면 행이 버튼이 되고, 누른 행을 알려 줘요. |
+| `showAnimation` | `boolean` | `true` | 처음 자라기 · 폭 미끄러짐 · 순서 바뀜 이동. |
+| `max` | `number` |  | 막대가 꽉 차는 값. 기본은 가장 큰 값. |
+| `limit` | `number` |  | 접기 전에 보일 행 수. 넘치면 "더 보기" 버튼. |
+| `expanded / defaultExpanded / onExpandedChange` | `boolean` | `false` | 나머지 행 펼침(제어/비제어). |
+| `moreLabel / lessLabel` | `(hidden) => ReactNode / ReactNode` | `'더 보기 (7)' / '접기'` | 펼침 버튼 문구. |
+| `nameLabel / valueLabel` | `ReactNode` |  | 오버라인 머리줄("페이지" / "방문수"). |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 행 높이 28 · 32 · 36px. |
+| `aria-label` | `string` |  | 목록 이름. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본 · 머리줄
+
+nameLabel · valueLabel을 주면 위에 오버라인 머리줄이 붙어요. href가 있는 행은 이름이 링크가 되고, 긴 이름은 말줄임돼요.
+
+```tsx
+import { BarList } from '@iamfiro/design'
+
+const PAGES = [
+  { name: '/', value: 8420, href: '#' },
+  { name: '/요금제', value: 3910, href: '#' },
+  { name: '/블로그/디자인-시스템-만들기', value: 2875, href: '#' },
+  { name: '/문서/시작하기', value: 2140, href: '#' },
+  { name: '/고객-사례', value: 1260, href: '#' },
+  { name: '/채용', value: 640, href: '#' },
+]
+
+export default function Example() {
+  return (
+    <div style={{ width: '100%', maxWidth: 420 }}>
+      <BarList data={PAGES} nameLabel="페이지" valueLabel="방문수" aria-label="많이 본 페이지" />
+    </div>
+  )
+}
+```
+
+### 톤 · 아이콘 · 색
+
+tone으로 막대 채움을 바꾸고(accent · neutral · success · warning · danger), 행마다 color에 차트 색('--chart-2')을 주면 그 색의 옅은 톤으로 칠해요. icon은 이름 앞에 붙어요.
+
+```tsx
+import { Globe, Mail, Search, Link } from 'lucide-react'
+import { Grid, Stack, Text, BarList } from '@iamfiro/design'
+
+const SOURCES = [
+  { name: '검색', value: 4820, icon: <Search size={14} /> },
+  { name: '직접 방문', value: 3150, icon: <Globe size={14} /> },
+  { name: '외부 링크', value: 1730, icon: <Link size={14} /> },
+  { name: '뉴스레터', value: 960, icon: <Mail size={14} /> },
+]
+
+const STATUS = [
+  { name: '200 성공', value: 18240 },
+  { name: '304 변경 없음', value: 4120 },
+  { name: '404 없음', value: 310 },
+]
+
+const ERRORS = [
+  { name: '시간 초과', value: 128 },
+  { name: '권한 없음', value: 74 },
+  { name: '잘못된 요청', value: 31 },
+]
+
+const DEVICES = [
+  { name: '데스크톱', value: 61, color: '--chart-2' },
+  { name: '휴대폰', value: 34, color: '--chart-1' },
+  { name: '태블릿', value: 5, color: '--chart-3' },
+]
+
+export default function Example() {
+  return (
+    <Grid minItemWidth={240} gap={8} style={{ width: '100%' }}>
+      <Stack gap={2}>
+        <Text variant="label-sm">유입 경로 · 아이콘</Text>
+        <BarList data={SOURCES} tone="neutral" />
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="label-sm">응답 코드 · success</Text>
+        <BarList data={STATUS} tone="success" />
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="label-sm">오류 · danger</Text>
+        <BarList data={ERRORS} tone="danger" formatValue={(v) => `${v}건`} />
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="label-sm">기기 · 행마다 차트 색</Text>
+        <BarList data={DEVICES} max={100} formatValue={(v) => `${v}%`} />
+      </Stack>
+    </Grid>
+  )
+}
+```
+
+### 누를 수 있는 행 · 정렬 · 데이터 바뀜
+
+onValueChange를 주면 행이 버튼이 돼요(hover 채움, Tab · ↑/↓ · Home/End). 기간을 바꾸면 막대가 새 폭으로, 순위가 바뀐 행은 새 자리로 미끄러져요.
+
+```tsx
+import { useState } from 'react'
+import { Inline, SegmentedControl, Stack, Text, BarList, type BarListSortOrder } from '@iamfiro/design'
+
+const WEEK = [
+  { key: 'seoul', name: '서울', value: 5240 },
+  { key: 'busan', name: '부산', value: 1820 },
+  { key: 'incheon', name: '인천', value: 1460 },
+  { key: 'daegu', name: '대구', value: 980 },
+  { key: 'gwangju', name: '광주', value: 610 },
+]
+
+const MONTH = [
+  { key: 'seoul', name: '서울', value: 19800 },
+  { key: 'busan', name: '부산', value: 6100 },
+  { key: 'incheon', name: '인천', value: 7350 },
+  { key: 'daegu', name: '대구', value: 4120 },
+  { key: 'gwangju', name: '광주', value: 4380 },
+]
+
+export default function Example() {
+  const [period, setPeriod] = useState<'week' | 'month'>('week')
+  const [sortOrder, setSortOrder] = useState<BarListSortOrder>('descending')
+  const [picked, setPicked] = useState<string | null>(null)
+
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 420 }}>
+      <Inline justify="between" gap={3}>
+        <SegmentedControl
+          ariaLabel="기간"
+          value={period}
+          onChange={setPeriod}
+          options={[
+            { value: 'week', label: '7일' },
+            { value: 'month', label: '30일' },
+          ]}
+        />
+        <SegmentedControl
+          ariaLabel="정렬"
+          variant="text"
+          value={sortOrder}
+          onChange={setSortOrder}
+          options={[
+            { value: 'descending', label: '많은 순' },
+            { value: 'ascending', label: '적은 순' },
+            { value: 'none', label: '원래 순서' },
+          ]}
+        />
+      </Inline>
+      <BarList
+        data={period === 'week' ? WEEK : MONTH}
+        sortOrder={sortOrder}
+        nameLabel="지역"
+        valueLabel="방문수"
+        onValueChange={(item) => setPicked(item.name)}
+        aria-label="지역별 방문수"
+      />
+      <Text variant="body-sm" tone="secondary">
+        {picked ? `${picked}을(를) 골랐어요.` : '행을 눌러 지역을 고르세요. Tab으로 들어와 ↑/↓로도 움직여요.'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 더 보기 · 카드 안
+
+limit개만 보이고 나머지는 접혀요. "더 보기"를 누르면 실제 높이까지 펼쳐져요. expanded · onExpandedChange로 제어할 수도 있어요.
+
+```tsx
+import { Card, CardBody, CardHeader, BarList } from '@iamfiro/design'
+
+const COUNTRIES = [
+  { name: '대한민국', value: 48210 },
+  { name: '미국', value: 12840 },
+  { name: '일본', value: 9630 },
+  { name: '베트남', value: 4210 },
+  { name: '독일', value: 3180 },
+  { name: '캐나다', value: 2470 },
+  { name: '영국', value: 2210 },
+  { name: '싱가포르', value: 1650 },
+  { name: '호주', value: 1320 },
+  { name: '프랑스', value: 980 },
+  { name: '태국', value: 760 },
+  { name: '브라질', value: 420 },
+]
+
+export default function Example() {
+  return (
+    <Card style={{ width: '100%', maxWidth: 420 }}>
+      <CardHeader title="국가별 방문" description="최근 30일" />
+      <CardBody>
+        <BarList data={COUNTRIES} limit={5} nameLabel="국가" valueLabel="방문수" aria-label="국가별 방문" />
+      </CardBody>
+    </Card>
+  )
+}
+```