@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/pie-chart/AGENTS.md

@@ -0,0 +1,243 @@
+# PieChart
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+전체 중 각 부분의 비율을 보여주는 도넛·원 차트. 얇은 링의 조각 사이엔 같은 폭의 틈이 있고 모서리는 살짝 둥글어요. 12시 방향에서 시계 방향으로 펼쳐지며 그려지고, 데이터가 바뀌면 조각이 제자리에서 모양을 바꿔요. 마우스를 올린 조각은 바깥으로 살짝 커지고 나머지는 흐려지며, 가운데 숫자가 그 조각의 값과 이름으로 바뀌어요.
+
+```tsx
+import { PieChart, type PieSlice } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 차트: 시리즈 색은 `--chart-1…6`을 순서대로, 그리드는 `--chart-grid`로 아주 옅게(세로선·축선 없음). 범례·툴팁의 색 표시는 `ColorDot`, 툴팁은 `Card raised` + `Separator`로 조립. 축·툴팁·범례·호버/키보드는 `components/Chart/`의 공용 조각(`ChartTooltip`, `ChartLegend`, `useChartInteraction`)을 쓴다. → `LineChart` · `BarChart` · `PieChart` · `Sparkbar`
+- 도넛은 얇은 링(`thickness` ≈ 지름 9%) + 조각 사이 같은 폭의 틈(`padAngle`) + 살짝 둥근 모서리(`cornerRadius`, 얇은 조각에선 저절로 줄어 뒤집히지 않게). 가운데는 큰 `number` 숫자 + 아래 옅은 caption, hover한 조각은 바깥으로 커지고 나머지는 흐려지며 가운데가 그 조각 값으로 바뀐다. 진행률은 `max` + 옅은 트랙. 마운트 시 12시부터 펼치고 데이터가 바뀌면 같은 키끼리 모양을 이어 간다(rAF, reduced motion에서도). → `PieChart`
+
+## API
+
+### PieChart
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `PieSlice[]` |  | 조각 목록. 0 이하는 그리지 않아요. |
+| `variant` | `'donut' \| 'pie'` | `'donut'` | 도넛 또는 구멍 없는 원. |
+| `size` | `number` | `200` | 지름(px). |
+| `thickness` | `number` | `지름의 약 9%` | 링 두께(px). |
+| `innerRadius` | `number` |  | 구멍 크기(반지름 비율, 이전 API). thickness가 우선이고 0이면 원. |
+| `padAngle` | `number` | `2` | 조각 사이 틈(도, 링 가운데 기준). 틈은 안팎 같은 폭이에요. |
+| `cornerRadius` | `number` | `3` | 조각 모서리 둥글기(px). 얇거나 짧은 조각에선 저절로 줄어요. |
+| `max` | `number` |  | 링 전체가 나타내는 값(진행률 도넛). 남은 부분은 비워 둬요. |
+| `track` | `boolean` | `max가 있으면 true` | 조각 뒤의 옅은 링. |
+| `formatValue` | `(value, slice) => string` | `'1,234'` | 값 형식. 조각 없이 부르면 합계. |
+| `centerLabel` | `ReactNode \| (ctx: PieCenterContext) => ReactNode` | `'합계'` | 가운데 숫자 아래 문구. 함수면 가운데 전체를 직접 그려요(ctx.total · ctx.active). |
+| `centerValue` | `ReactNode` |  | 가운데 숫자. 기본은 합계(max가 있으면 비율). |
+| `legend` | `boolean \| 'side' \| 'bottom'` | `true` | true · 'side' = 옆 목록(값 · 비율), 'bottom' = 아래 한 줄. |
+| `showPercent` | `boolean` | `true` | 옆 범례에 비율 표시. |
+| `tooltip` | `boolean` | `원이면 true` | 조각 옆 Card 툴팁. 도넛은 기본으로 가운데에서 읽어 줘요. |
+| `activeIndex / defaultActiveIndex / onActiveIndexChange` | `number \| null` |  | 하이라이트한 조각(제어/비제어). |
+| `aria-label` | `string` | `'원 차트'` | 차트 이름. 하이라이트한 조각은 aria-live로 읽어요. |
+
+### PieSlice
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `key` (필수) | `string` |  | 고유 키. 데이터가 바뀔 때 같은 키끼리 모양이 이어져요. |
+| `label` (필수) | `string` |  | 이름. |
+| `value` (필수) | `number` |  | 값. |
+| `color` | `string` |  | CSS 변수('--chart-3') 또는 색. 기본은 --chart-1부터 차례로. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 도넛 · 옆 범례
+
+분류별 지출. 가운데엔 합계, 조각이나 범례에 마우스를 올리면 그 조각의 값 · 이름 · 비율로 바뀌어요. 기간을 바꾸면 조각이 이어서 움직여요. ←/→로 조각을 돌아가며 고르고 화면 읽기 프로그램이 값을 읽어요.
+
+```tsx
+import { useState } from 'react'
+import { PieChart, type PieSlice, SegmentedControl, Stack } from '@iamfiro/design'
+
+const MONTHS: Record<'oct' | 'sep', PieSlice[]> = {
+  oct: [
+    { key: 'food', label: '식비', value: 86 },
+    { key: 'home', label: '주거', value: 72 },
+    { key: 'move', label: '교통', value: 31 },
+    { key: 'shop', label: '쇼핑', value: 44 },
+    { key: 'fun', label: '여가', value: 23 },
+    { key: 'etc', label: '기타', value: 9 },
+  ],
+  sep: [
+    { key: 'food', label: '식비', value: 78 },
+    { key: 'home', label: '주거', value: 72 },
+    { key: 'move', label: '교통', value: 26 },
+    { key: 'shop', label: '쇼핑', value: 61 },
+    { key: 'fun', label: '여가', value: 38 },
+    { key: 'etc', label: '기타', value: 14 },
+  ],
+}
+
+export default function Example() {
+  const [month, setMonth] = useState<'oct' | 'sep'>('oct')
+  return (
+    <Stack gap={5} align="start">
+      <SegmentedControl
+        value={month}
+        onChange={setMonth}
+        ariaLabel="기간"
+        options={[
+          { value: 'oct', label: '10월' },
+          { value: 'sep', label: '9월' },
+        ]}
+      />
+      <PieChart data={MONTHS[month]} size={208} formatValue={(v) => `${v}만 원`} centerLabel="이번 달 지출" aria-label="분류별 지출" />
+    </Stack>
+  )
+}
+```
+
+### 진행률 · 트랙
+
+max를 주면 단일 값의 진행 링이 돼요. 남은 부분엔 옅은 트랙이 보이고, cornerRadius를 두께의 절반으로 하면 끝이 둥근 막대가 돼요.
+
+```tsx
+import { useState } from 'react'
+import { PieChart, Slider, Stack } from '@iamfiro/design'
+
+export default function Example() {
+  const [done, setDone] = useState(68)
+  return (
+    <Stack gap={5} style={{ width: 240 }}>
+      <PieChart
+        data={[{ key: 'done', label: '달성', value: done, color: '--chart-2' }]}
+        max={100}
+        size={176}
+        thickness={14}
+        cornerRadius={7}
+        padAngle={0}
+        legend={false}
+        formatValue={(v) => `${v}%`}
+        centerLabel="분기 목표 달성"
+        aria-label="분기 목표 달성률"
+        style={{ alignSelf: 'center' }}
+      />
+      <Slider value={done} onValueChange={setDone} min={0} max={100} step={1} formatValue={(v) => `${v}%`} aria-label="달성률" />
+    </Stack>
+  )
+}
+```
+
+### 크기 · 범례 없음
+
+size로 지름을 정하면 링 두께와 가운데 숫자 크기가 따라 바뀌어요. 카드 안 작은 지표엔 범례를 꺼요.
+
+```tsx
+import { Card, CardBody, PieChart, Grid, Inline, Stack, Text } from '@iamfiro/design'
+
+const METRICS = [
+  { title: '저장 공간', used: 72, color: '--chart-2' },
+  { title: '이번 달 크레딧', used: 38, color: '--chart-3' },
+  { title: '좌석', used: 90, color: '--chart-1' },
+]
+
+const SIZES = [96, 128, 160]
+
+export default function Example() {
+  return (
+    <Stack gap={6} style={{ width: '100%', maxWidth: 560 }}>
+      <Grid minItemWidth={160} gap={4}>
+        {METRICS.map((m) => (
+          <Card key={m.title}>
+            <CardBody>
+              <Stack gap={3} align="center">
+                <PieChart
+                  size={112}
+                  max={100}
+                  legend={false}
+                  data={[{ key: 'used', label: '사용', value: m.used, color: m.color }]}
+                  formatValue={(v) => `${v}%`}
+                  centerLabel="사용"
+                  aria-label={`${m.title} 사용량`}
+                />
+                <Text variant="label-md">{m.title}</Text>
+              </Stack>
+            </CardBody>
+          </Card>
+        ))}
+      </Grid>
+      <Inline gap={6} justify="center">
+        {SIZES.map((s) => (
+          <PieChart
+            key={s}
+            size={s}
+            legend={false}
+            data={[
+              { key: 'a', label: '완료', value: 54 },
+              { key: 'b', label: '진행 중', value: 28 },
+              { key: 'c', label: '대기', value: 18 },
+            ]}
+            centerLabel={`${s}px`}
+            aria-label={`${s}px 도넛`}
+          />
+        ))}
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 툴팁 · 아래 범례 · 가운데 직접 그리기
+
+tooltip이면 조각 옆 Card에 값을 보여 주고 가운데는 그대로 둬요. legend="bottom"은 아래 한 줄 범례, centerLabel에 함수를 주면 가운데를 직접 그려요.
+
+```tsx
+import { PieChart, type PieSlice, Stack, Text } from '@iamfiro/design'
+
+const DATA: PieSlice[] = [
+  { key: 'paid', label: '유료 광고', value: 4800 },
+  { key: 'organic', label: '검색 유입', value: 4600 },
+  { key: 'email', label: '이메일', value: 2100 },
+  { key: 'referral', label: '추천', value: 1500 },
+  { key: 'direct', label: '직접 방문', value: 800 },
+]
+
+export default function Example() {
+  return (
+    <PieChart
+      data={DATA}
+      size={200}
+      legend="bottom"
+      tooltip
+      formatValue={(v) => `${v.toLocaleString('ko-KR')}만 원`}
+      centerLabel={({ total }) => (
+        <Stack gap={0} align="center">
+          <Text variant="overline" tone="tertiary">
+            이번 주 매출
+          </Text>
+          <Text variant="number-lg">{(total / 10000).toFixed(1)}억</Text>
+        </Stack>
+      )}
+      aria-label="유입 경로별 매출 비중"
+    />
+  )
+}
+```
+
+### 원
+
+variant="pie"(또는 innerRadius={0})이면 구멍 없는 원. 값은 조각 옆 툴팁으로 보여줘요.
+
+```tsx
+import { PieChart, type PieSlice } from '@iamfiro/design'
+
+const DATA: PieSlice[] = [
+  { key: 'mac', label: 'macOS', value: 46 },
+  { key: 'win', label: 'Windows', value: 31 },
+  { key: 'ios', label: 'iOS', value: 14 },
+  { key: 'android', label: 'Android', value: 9 },
+]
+
+export default function Example() {
+  return <PieChart data={DATA} variant="pie" size={180} formatValue={(v) => `${v}명`} aria-label="운영체제별 사용자" />
+}
+```

package/agents/popover/AGENTS.md

@@ -0,0 +1,190 @@
+# Popover
+
+> 메뉴 & 오버레이 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+트리거 옆에 붙어 뜨는 작은 패널. 작은 폼, 미리보기 카드, 알림 목록처럼 페이지를 떠나지 않고 잠깐 보는 내용에 써요. 부모의 overflow: hidden에 잘리지 않고, 아래 공간이 부족하면 위로 뒤집히며, 열리고 닫힐 때 모두 애니메이션돼요. 바깥을 누르거나 Esc로 닫히고, 안에 포커스가 있던 채로 닫히면 트리거로 포커스가 돌아가요.
+
+```tsx
+import { Popover } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 팝오버는 `ListboxPopover` / `Popover` / `DropdownMenu`(portal + fixed, 공간 부족 시 위로, `useFloating`의 `align`). 부모 `overflow: hidden`에 잘리면 안 된다.
+
+## API
+
+### Popover
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `trigger` (필수) | `ReactNode` |  | 여는 요소(보통 Button). |
+| `children` (필수) | `ReactNode \| (close) => ReactNode` |  | 패널 내용. 함수면 close를 받아요. |
+| `openOn` | `'click' \| 'hover'` | `'click'` | click: 누르면 토글 · hover: 머물면 열리고 유예 뒤 닫힘. |
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | 트리거 기준 가로 정렬. |
+| `width` | `number \| string` |  | 패널 폭(px 또는 CSS 값). 최대 화면 폭 - 16px. |
+| `padding` | `'none' \| 'sm' \| 'md'` | `'md'` | 안쪽 여백. 자체 여백이 있는 목록·미디어는 none. |
+| `autoFocus` | `boolean` | `true` | click 모드에서 열릴 때 패널 안 첫 요소로 포커스 이동. |
+| `open / onOpenChange` | `boolean / (open) => void` |  | 열림 상태를 밖에서 제어할 때. |
+| `defaultOpen` | `boolean` | `false` | 처음 열림 상태(비제어). |
+| `aria-label` | `string` |  | 패널(role="dialog")의 접근성 이름. |
+| `className` | `string` |  | 패널에 붙는 클래스. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 작은 폼
+
+클릭하면 열리고 첫 입력칸으로 포커스가 들어가요. children에 함수를 넘기면 close를 받아 저장·취소 뒤에 닫을 수 있어요.
+
+```tsx
+import { useState } from 'react'
+import { Link2 } from 'lucide-react'
+import { Button, Field, Inline, Input, Stack, Popover, toast } from '@iamfiro/design'
+
+export default function Example() {
+  const [url, setUrl] = useState('')
+
+  return (
+    <Popover trigger={<Button icon={<Link2 />}>링크 추가</Button>} width={320} aria-label="링크 추가">
+      {(close) => (
+        <Stack
+          as="form"
+          gap={4}
+          onSubmit={(e) => {
+            e.preventDefault()
+            toast.success('링크를 추가했어요', { description: url })
+            setUrl('')
+            close()
+          }}
+        >
+          <Field label="주소" htmlFor="link-url">
+            <Input id="link-url" type="url" placeholder="https://" value={url} onChange={(e) => setUrl(e.target.value)} />
+          </Field>
+          <Inline justify="end" gap={2}>
+            <Button size="sm" variant="ghost" onClick={close}>
+              취소
+            </Button>
+            <Button size="sm" variant="primary" type="submit" disabled={!url}>
+              추가
+            </Button>
+          </Inline>
+        </Stack>
+      )}
+    </Popover>
+  )
+}
+```
+
+### 정렬
+
+align으로 트리거의 왼쪽 · 가운데 · 오른쪽 끝에 맞춰요. 화면 오른쪽 끝의 버튼이면 end를 쓰세요.
+
+```tsx
+import { Button, Inline, Text, Popover } from '@iamfiro/design'
+
+const ALIGNS = [
+  { align: 'start', label: '왼쪽 맞춤 (start)' },
+  { align: 'center', label: '가운데 (center)' },
+  { align: 'end', label: '오른쪽 맞춤 (end)' },
+] as const
+
+export default function Example() {
+  return (
+    <Inline gap={3}>
+      {ALIGNS.map((a) => (
+        <Popover key={a.align} align={a.align} width={240} trigger={<Button>{a.label}</Button>}>
+          <Text variant="body-sm" tone="secondary">
+            트리거의 {a.align === 'start' ? '왼쪽' : a.align === 'center' ? '가운데' : '오른쪽'}에 맞춰 열려요. 아래 공간이 부족하면 위로 뒤집혀요.
+          </Text>
+        </Popover>
+      ))}
+    </Inline>
+  )
+}
+```
+
+### 호버 미리보기
+
+openOn="hover"는 포인터가 잠깐(200ms) 머물러야 열려서 지나가기만 하면 뜨지 않아요. 벗어나도 300ms 유예가 있어 패널로 옮겨 가는 동안 닫히지 않아요. 키보드 포커스로도 바로 열려요. 터치 기기에는 호버가 없으니 꼭 필요한 정보는 여기에만 두지 마세요.
+
+```tsx
+import { Avatar, Badge, Button, Inline, Stack, Text, Popover } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Text as="div" variant="body-md">
+      이 문서는{' '}
+      <Popover
+        openOn="hover"
+        width={280}
+        aria-label="김민지 프로필"
+        trigger={
+          <Button variant="ghost" size="sm" icon={<Avatar name="김민지" size={20} />}>
+            김민지
+          </Button>
+        }
+      >
+        <Stack gap={4}>
+          <Inline gap={3} wrap={false}>
+            <Avatar name="김민지" size={40} online />
+            <Stack gap={0}>
+              <Text variant="label-lg">김민지</Text>
+              <Text variant="body-sm" tone="secondary">
+                디자인 시스템 팀 · 리드
+              </Text>
+            </Stack>
+          </Inline>
+          <Text variant="body-sm" tone="secondary">
+            Lumen 컴포넌트와 토큰을 관리해요. 오후 6시 이후엔 답이 늦을 수 있어요.
+          </Text>
+          <Inline gap={2}>
+            <Badge tone="success" dot>
+              온라인
+            </Badge>
+            <Badge>서울</Badge>
+          </Inline>
+        </Stack>
+      </Popover>
+      님이 마지막으로 수정했어요.
+    </Text>
+  )
+}
+```
+
+### 여백과 폭
+
+목록·메뉴처럼 자체 여백이 있는 내용은 padding='none'. width는 px 숫자나 CSS 값이고, 화면보다 넓어지지 않아요.
+
+```tsx
+import { Bell, CircleHelp } from 'lucide-react'
+import { Avatar, Button, Inline, Text, List, ListItem, Popover } from '@iamfiro/design'
+
+const NOTIFICATIONS = [
+  { name: '이도현', text: '디자인 리뷰에 댓글을 남겼어요', time: '2분 전' },
+  { name: '최서연', text: '10월 회의록을 공유했어요', time: '1시간 전' },
+  { name: '정우진', text: '배포 승인을 요청했어요', time: '어제' },
+]
+
+export default function Example() {
+  return (
+    <Inline gap={3}>
+      <Popover padding="none" width={340} aria-label="알림" trigger={<Button icon={<Bell />}>알림 (padding none)</Button>}>
+        {(close) => (
+          <List density="comfortable" label="알림">
+            {NOTIFICATIONS.map((n) => (
+              <ListItem key={n.name} leading={<Avatar name={n.name} size={32} />} title={n.text} description={n.name} meta={n.time} onClick={close} />
+            ))}
+          </List>
+        )}
+      </Popover>
+      <Popover padding="sm" width={220} trigger={<Button icon={<CircleHelp />}>도움말 (padding sm)</Button>}>
+        <Text variant="body-sm" tone="secondary">
+          작은 안내 문구에는 sm, 폼이나 카드형 내용에는 기본값 md를 써요.
+        </Text>
+      </Popover>
+    </Inline>
+  )
+}
+```