@iamfiro/design 0.0.0-stage → 0.1.0

package/agents/data-grid/AGENTS.md

@@ -0,0 +1,460 @@
+# DataGrid
+
+> 데이터 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+Notion 데이터베이스처럼 타입이 있는 속성과 보기(정렬·필터·그룹·검색)를, Google Sheets·Numbers처럼 범위 선택·키보드 편집·복사/붙여넣기·채우기 핸들을 갖춘 표. 열은 끌어서 순서·너비를 바꾸고 고정·숨기기·타입 변경까지 머리글 메뉴에서 할 수 있어요. 모든 데이터 변경은 실행 취소(⌘/Ctrl+Z)할 수 있고, 행이 많으면 보이는 줄만 그려요. 단순히 보여 주기만 하는 표는 Table을 쓰세요.
+
+```tsx
+import { DataGrid, type GridColumn, type GridRow } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 표: 보여 주기만 하면 `Table`, 편집·정렬·필터·범위 선택이 필요하면 `DataGrid`. 셀 편집·키 입력·클립보드·한글 IME는 셀 위에 놓인 textarea 하나가 모두 받는다(조합 중에 포커스를 옮기면 한글이 깨진다).
+
+## API
+
+### DataGrid
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `rows / defaultRows / onRowsChange` | `R[] / R[] / (rows) => void` |  | 행 데이터(제어/비제어). 행마다 고유한 id가 있어야 해요. |
+| `columns / defaultColumns / onColumnsChange` | `GridColumn<R>[]` |  | 열 정의. 너비·순서·고정·숨김·타입 변경이 여기에 반영돼요. |
+| `view / defaultView / onViewChange` | `GridView / Partial<GridView>` |  | 정렬·필터·그룹·검색·행 높이 같은 보기 상태. |
+| `selectedRowIds / onSelectedRowIdsChange` | `string[]` |  | 체크된 행(일괄 작업 대상). |
+| `createRow` | `(values) => R` |  | 새 행을 만들 때. values에는 현재 필터·그룹에 맞는 값이 들어 있어요. |
+| `onCellEdit` | `({ row, column, value, previous }) => void` |  | 셀이 확정될 때마다(입력·붙여넣기·채우기·지우기). |
+| `readOnly` | `boolean` | `false` | 데이터 변경 금지. 보기 조작과 복사는 돼요. |
+| `columnEditing` | `boolean` | `true` | 사용자가 속성을 추가·이름 변경·타입 변경·삭제할 수 있는지. |
+| `toolbar` | `boolean` | `true` | 검색·필터·정렬·그룹·속성·보기 설정·실행 취소·새로 만들기 막대. |
+| `title / actions` | `ReactNode` |  | 툴바 왼쪽 제목 / 오른쪽 끝에 붙일 버튼. |
+| `footer` | `boolean` | `true` | 열마다 계산을 고르는 아래 줄. |
+| `height` | `number \| string` | `520` | 스크롤 영역 최대 높이. |
+| `emptyState` | `ReactNode` |  | 보일 행이 없을 때 대신 보여 줄 내용. |
+
+### GridColumn
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `key / name` (필수) | `string` |  | 값을 읽고 쓰는 필드 / 머리글 이름. |
+| `type` | `'text' \| 'number' \| 'select' \| 'multiSelect' \| 'checkbox' \| 'date' \| 'url'` | `'text'` | 표시·편집·정렬·필터·붙여넣기 해석이 타입을 따라요. |
+| `width / minWidth` | `number` | `180 / 64` | 열 너비(px). 경계를 더블클릭하면 내용에 맞춰요. |
+| `pinned / hidden / wrap` | `boolean` |  | 왼쪽 고정 / 숨김 / 줄바꿈(켜면 행 가상화가 꺼져요). |
+| `options / creatable` | `GridOption[] / boolean` |  | 선택지({ label, tone }). 없는 값을 입력하면 새로 만들어요(creatable: false면 거절). |
+| `format / decimals` | `'plain' \| 'comma' \| 'percent' \| 'won' \| 'usd'` | `'comma'` | 숫자 표시 형식. |
+| `aggregate` | `GridAggregate` |  | 아래 줄 계산('sum', 'avg', 'percentChecked', 'earliest' …). |
+| `readOnly / locked` | `boolean` |  | 셀 편집 금지 / 속성 삭제·타입 변경 금지. |
+| `align` | `'start' \| 'center' \| 'end'` |  | 정렬. 숫자는 기본이 오른쪽. |
+| `render` | `(value, row) => ReactNode` |  | 셀 모양을 직접 그릴 때. |
+| `validate` | `(value, row) => string \| null` |  | 메시지를 돌려주면 그 편집을 거절해요. |
+
+### 키보드
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `↑ ↓ ← → · Tab` | `이동` |  | Shift를 같이 누르면 범위 확장, ⌘/Ctrl은 끝까지. |
+| `Enter · F2 · 더블클릭` | `편집` |  | 바로 글자를 쳐도 편집이 시작돼요(한글 입력 포함). Enter 확정 후 아래로, Tab은 오른쪽, Esc 취소. |
+| `Shift+Enter · Alt+Enter` | `줄바꿈` |  | 텍스트 셀 안에서 새 줄. |
+| `Delete · Backspace` | `지우기` |  | 선택 범위의 값을 지워요. |
+| `Space` | `체크` |  | 체크박스 열에서 범위를 한꺼번에 토글. |
+| `⌘/Ctrl + C · X · V` | `클립보드` |  | TSV로 주고받아 Sheets·Excel·Numbers와 호환돼요. |
+| `⌘/Ctrl + D` | `아래로 채우기` |  | 범위의 첫 행 값을 아래로 복사(숫자는 이어서). |
+| `⌘/Ctrl + A · Z · Shift+Z` | `전체 선택 · 실행 취소 · 다시 실행` |  |  |
+| `Esc (끄는 중)` | `취소` |  | 열 너비·순서, 행 순서, 채우기를 끄는 도중 Esc면 원래대로. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 데이터베이스 (Notion)
+
+텍스트·숫자·선택·다중 선택·날짜·체크박스·URL 속성. 머리글의 ⌄ 메뉴(또는 우클릭)에서 이름·타입·정렬·필터·그룹·고정·줄바꿈·삽입·삭제를 하고, 맨 오른쪽 +로 속성을 추가해요. 행 왼쪽 손잡이로 순서를 바꾸고, 체크하면 아래에 일괄 작업 막대가 떠요. 맨 아래 칸을 누르면 합계·평균·체크 비율 같은 계산을 고를 수 있어요.
+
+```tsx
+import { DataGrid, type GridColumn, type GridRow } from '@iamfiro/design'
+
+interface Task extends GridRow {
+  title: string
+  status: string | null
+  owner: string | null
+  tags: string[]
+  due: string | null
+  budget: number | null
+  progress: number | null
+  done: boolean
+  link: string | null
+}
+
+const COLUMNS: GridColumn<Task>[] = [
+  { key: 'title', name: '작업', type: 'text', width: 240, pinned: true, aggregate: 'count', locked: true },
+  {
+    key: 'status',
+    name: '상태',
+    type: 'select',
+    width: 130,
+    options: [
+      { label: '시작 전', tone: 'neutral' },
+      { label: '진행 중', tone: 'info' },
+      { label: '검토', tone: 'warning' },
+      { label: '완료', tone: 'success' },
+    ],
+  },
+  {
+    key: 'owner',
+    name: '담당자',
+    type: 'select',
+    width: 120,
+    options: [{ label: '김민지' }, { label: '이도현' }, { label: '박서연' }, { label: '최준호' }],
+  },
+  {
+    key: 'tags',
+    name: '태그',
+    type: 'multiSelect',
+    width: 200,
+    options: [
+      { label: '디자인', tone: 'accent' },
+      { label: '개발', tone: 'info' },
+      { label: '마케팅', tone: 'warning' },
+      { label: '긴급', tone: 'danger' },
+    ],
+  },
+  { key: 'due', name: '마감일', type: 'date', width: 130, aggregate: 'earliest' },
+  { key: 'budget', name: '예산', type: 'number', format: 'won', width: 140, aggregate: 'sum' },
+  { key: 'progress', name: '진행률', type: 'number', format: 'percent', width: 110, aggregate: 'avg' },
+  { key: 'done', name: '완료', type: 'checkbox', width: 90, aggregate: 'percentChecked' },
+  { key: 'link', name: '문서', type: 'url', width: 200 },
+]
+
+const ROWS: Task[] = [
+  { id: 't1', title: '랜딩 페이지 리뉴얼', status: '진행 중', owner: '김민지', tags: ['디자인', '마케팅'], due: '2026-11-03', budget: 4200000, progress: 0.6, done: false, link: 'figma.com/lumen-landing' },
+  { id: 't2', title: '결제 모듈 교체', status: '검토', owner: '이도현', tags: ['개발', '긴급'], due: '2026-10-28', budget: 8800000, progress: 0.9, done: false, link: 'github.com/lumen/pay' },
+  { id: 't3', title: '10월 뉴스레터', status: '완료', owner: '박서연', tags: ['마케팅'], due: '2026-10-20', budget: 600000, progress: 1, done: true, link: null },
+  { id: 't4', title: '디자인 토큰 정리', status: '진행 중', owner: '김민지', tags: ['디자인', '개발'], due: '2026-11-10', budget: 1500000, progress: 0.35, done: false, link: 'lumen.app/tokens' },
+  { id: 't5', title: '온보딩 인터뷰 5건', status: '시작 전', owner: '최준호', tags: ['디자인'], due: '2026-11-14', budget: 500000, progress: 0, done: false, link: null },
+  { id: 't6', title: '모바일 앱 2.0 QA', status: '진행 중', owner: '이도현', tags: ['개발'], due: '2026-11-07', budget: 3200000, progress: 0.45, done: false, link: null },
+  { id: 't7', title: '파트너 웨비나', status: '시작 전', owner: '박서연', tags: ['마케팅'], due: '2026-11-21', budget: 2000000, progress: 0.1, done: false, link: null },
+  { id: 't8', title: '접근성 감사', status: '완료', owner: '최준호', tags: ['디자인', '개발'], due: '2026-10-15', budget: 1200000, progress: 1, done: true, link: 'lumen.app/a11y' },
+  { id: 't9', title: '요금제 페이지 A/B 테스트', status: '검토', owner: '김민지', tags: ['마케팅', '긴급'], due: '2026-10-30', budget: 900000, progress: 0.8, done: false, link: null },
+  { id: 't10', title: '고객 지원 매크로 정비', status: '시작 전', owner: null, tags: [], due: null, budget: null, progress: null, done: false, link: null },
+]
+
+export default function Example() {
+  return <DataGrid title="4분기 로드맵" defaultColumns={COLUMNS} defaultRows={ROWS} height={460} style={{ width: '100%' }} />
+}
+```
+
+### 스프레드시트 (Sheets · Numbers)
+
+셀을 끌어 범위를 고르고, 선택 오른쪽 아래 점(채우기 핸들)을 끌면 1, 2 → 3, 4처럼 이어서 채워요. Sheets·Excel에서 복사한 범위를 그대로 붙여 넣을 수 있고, 범위를 넘으면 행이 새로 생겨요. 합계 열은 readOnly로 두고 onRowsChange에서 다시 계산해요.
+
+```tsx
+import { useState } from 'react'
+import { DataGrid, type GridColumn, type GridRow } from '@iamfiro/design'
+
+interface Line extends GridRow {
+  item: string
+  oct: number | null
+  nov: number | null
+  dec: number | null
+  total: number
+}
+
+const MONTHS = ['oct', 'nov', 'dec'] as const
+
+const COLUMNS: GridColumn<Line>[] = [
+  { key: 'item', name: '항목', width: 180, pinned: true },
+  { key: 'oct', name: '10월', type: 'number', format: 'comma', width: 120, aggregate: 'sum' },
+  { key: 'nov', name: '11월', type: 'number', format: 'comma', width: 120, aggregate: 'sum' },
+  { key: 'dec', name: '12월', type: 'number', format: 'comma', width: 120, aggregate: 'sum' },
+  { key: 'total', name: '합계', type: 'number', format: 'comma', width: 140, aggregate: 'sum', readOnly: true, locked: true },
+]
+
+// 합계 열은 직접 고칠 수 없고, 월별 값이 바뀔 때마다 다시 계산해요.
+const withTotal = (l: Line): Line => ({ ...l, total: MONTHS.reduce((s, m) => s + (l[m] ?? 0), 0) })
+
+const START: Line[] = [
+  { id: 'l1', item: '클라우드 서버', oct: 1820000, nov: 1910000, dec: 2000000, total: 0 },
+  { id: 'l2', item: '디자인 툴 구독', oct: 360000, nov: 360000, dec: 360000, total: 0 },
+  { id: 'l3', item: '광고', oct: 2500000, nov: 3000000, dec: 3500000, total: 0 },
+  { id: 'l4', item: '외주 번역', oct: 800000, nov: null, dec: 450000, total: 0 },
+  { id: 'l5', item: '사무용품', oct: 120000, nov: 95000, dec: 130000, total: 0 },
+].map(withTotal)
+
+export default function Example() {
+  const [rows, setRows] = useState(START)
+  return (
+    <DataGrid
+      title="4분기 비용"
+      rows={rows}
+      onRowsChange={(next) => setRows(next.map(withTotal))}
+      defaultColumns={COLUMNS}
+      defaultView={{ gridlines: true, density: 'compact' }}
+      createRow={(values) => withTotal({ id: crypto.randomUUID(), item: '', oct: null, nov: null, dec: null, total: 0, ...values })}
+      height={360}
+      style={{ width: '100%' }}
+    />
+  )
+}
+```
+
+### 저장된 보기
+
+view / onViewChange로 정렬·필터·그룹·접힘 상태를 밖에서 들고 있어요. 탭마다 다른 보기를 저장하고, 표에서 바꾼 내용도 그 탭에 남아요. 그룹 머리의 +로 그 그룹 값이 채워진 행을 만들어요.
+
+```tsx
+import { useState } from 'react'
+import { SegmentedControl, DEFAULT_GRID_VIEW, DataGrid, type GridColumn, type GridRow, type GridView } from '@iamfiro/design'
+
+interface Ticket extends GridRow {
+  title: string
+  status: string
+  priority: string
+  owner: string
+  due: string
+}
+
+const COLUMNS: GridColumn<Ticket>[] = [
+  { key: 'title', name: '제목', width: 260 },
+  {
+    key: 'status',
+    name: '상태',
+    type: 'select',
+    width: 120,
+    options: [
+      { label: '접수', tone: 'neutral' },
+      { label: '처리 중', tone: 'info' },
+      { label: '해결', tone: 'success' },
+    ],
+  },
+  {
+    key: 'priority',
+    name: '우선순위',
+    type: 'select',
+    width: 110,
+    options: [
+      { label: '높음', tone: 'danger' },
+      { label: '보통', tone: 'warning' },
+      { label: '낮음', tone: 'neutral' },
+    ],
+  },
+  { key: 'owner', name: '담당자', type: 'select', width: 110, options: [{ label: '김민지' }, { label: '이도현' }, { label: '박서연' }] },
+  { key: 'due', name: '기한', type: 'date', width: 120 },
+]
+
+const ROWS: Ticket[] = [
+  { id: 'k1', title: '로그인 후 빈 화면이 떠요', status: '처리 중', priority: '높음', owner: '이도현', due: '2026-10-26' },
+  { id: 'k2', title: '영수증 이메일이 늦게 와요', status: '접수', priority: '보통', owner: '박서연', due: '2026-10-29' },
+  { id: 'k3', title: '다크 모드 대비가 낮아요', status: '해결', priority: '낮음', owner: '김민지', due: '2026-10-21' },
+  { id: 'k4', title: 'CSV 내보내기 한글 깨짐', status: '처리 중', priority: '높음', owner: '김민지', due: '2026-10-27' },
+  { id: 'k5', title: '팀 초대 링크 만료 기간', status: '접수', priority: '낮음', owner: '이도현', due: '2026-11-04' },
+  { id: 'k6', title: '알림 설정이 저장되지 않아요', status: '처리 중', priority: '보통', owner: '박서연', due: '2026-10-31' },
+]
+
+type ViewId = 'all' | 'open' | 'byOwner' | 'urgent'
+
+// 탭마다 보기(정렬·필터·그룹)를 따로 저장해요. 표에서 바꾼 내용도 그 탭에 남아요.
+const PRESETS: Record<ViewId, GridView> = {
+  all: { ...DEFAULT_GRID_VIEW },
+  open: { ...DEFAULT_GRID_VIEW, filters: [{ id: 'f1', key: 'status', op: 'isNot', value: '해결' }], sorts: [{ key: 'due', dir: 'asc' }] },
+  byOwner: { ...DEFAULT_GRID_VIEW, groupBy: 'owner' },
+  urgent: { ...DEFAULT_GRID_VIEW, groupBy: 'priority', collapsed: ['낮음'], sorts: [{ key: 'due', dir: 'asc' }] },
+}
+
+export default function Example() {
+  const [tab, setTab] = useState<ViewId>('open')
+  const [views, setViews] = useState(PRESETS)
+
+  return (
+    <div style={{ display: 'grid', gap: 12, width: '100%' }}>
+      <SegmentedControl
+        variant="underline"
+        value={tab}
+        onChange={setTab}
+        ariaLabel="저장된 보기"
+        options={[
+          { value: 'all', label: '전체' },
+          { value: 'open', label: '미해결' },
+          { value: 'byOwner', label: '담당자별' },
+          { value: 'urgent', label: '우선순위별' },
+        ]}
+      />
+      <DataGrid
+        toolbar
+        defaultColumns={COLUMNS}
+        defaultRows={ROWS}
+        view={views[tab]}
+        onViewChange={(view) => setViews((v) => ({ ...v, [tab]: view }))}
+        height={420}
+        aria-label="지원 티켓"
+      />
+    </div>
+  )
+}
+```
+
+### 1만 행
+
+보이는 줄만 그려서 1만 행도 부드럽게 스크롤돼요. 검색·정렬·필터·하단 계산은 전체 행 기준이에요.
+
+```tsx
+import { useMemo } from 'react'
+import { DataGrid, type GridColumn, type GridRow } from '@iamfiro/design'
+
+interface Order extends GridRow {
+  no: number
+  customer: string
+  region: string
+  amount: number
+  ordered: string
+  paid: boolean
+}
+
+const NAMES = ['김민지', '이도현', '박서연', '최준호', '정하은', '강지우', '윤서준', '한예린']
+const REGIONS = ['서울', '부산', '대구', '인천', '광주', '대전']
+
+const COLUMNS: GridColumn<Order>[] = [
+  { key: 'no', name: '주문 번호', type: 'number', format: 'plain', width: 120, readOnly: true, aggregate: 'count' },
+  { key: 'customer', name: '고객', width: 140 },
+  { key: 'region', name: '지역', type: 'select', width: 110, options: REGIONS.map((label) => ({ label })) },
+  { key: 'amount', name: '금액', type: 'number', format: 'won', width: 140, aggregate: 'sum' },
+  { key: 'ordered', name: '주문일', type: 'date', width: 130, aggregate: 'latest' },
+  { key: 'paid', name: '결제', type: 'checkbox', width: 90, aggregate: 'percentChecked' },
+]
+
+/** 1만 행을 만들어요(같은 결과가 나오도록 간단한 의사 난수). */
+function makeOrders(count: number): Order[] {
+  let seed = 7
+  const rand = () => (seed = (seed * 16807) % 2147483647) / 2147483647
+  return Array.from({ length: count }, (_, i) => {
+    const day = new Date(2026, 0, 1 + Math.floor(rand() * 298))
+    return {
+      id: `o${i}`,
+      no: 100001 + i,
+      customer: NAMES[Math.floor(rand() * NAMES.length)],
+      region: REGIONS[Math.floor(rand() * REGIONS.length)],
+      amount: Math.round(rand() * 400) * 1000 + 9000,
+      ordered: `${day.getFullYear()}-${String(day.getMonth() + 1).padStart(2, '0')}-${String(day.getDate()).padStart(2, '0')}`,
+      paid: rand() > 0.2,
+    }
+  })
+}
+
+export default function Example() {
+  const rows = useMemo(() => makeOrders(10000), [])
+  return <DataGrid title="주문 10,000건" defaultRows={rows} defaultColumns={COLUMNS} defaultView={{ density: 'compact' }} height={440} style={{ width: '100%' }} />
+}
+```
+
+### 커스텀 셀 · 검증
+
+render로 셀 모양을 바꾸고(편집은 type을 따라요), validate로 잘못된 값을 막아요(칸이 흔들리고 편집이 유지돼요). creatable: false인 선택 열은 새 선택지를 만들 수 없고, readOnly 열은 고칠 수 없어요. onCellEdit으로 모든 변경을 받아요.
+
+```tsx
+import { Avatar, Text, DataGrid, toast, type GridColumn, type GridRow } from '@iamfiro/design'
+
+interface Member extends GridRow {
+  name: string
+  email: string
+  role: string
+  seats: number
+  joined: string
+}
+
+const COLUMNS: GridColumn<Member>[] = [
+  {
+    key: 'name',
+    name: '이름',
+    width: 180,
+    // render는 보이는 모습만 바꿔요. 편집·복사·정렬은 여전히 type(텍스트)을 따라요.
+    render: (value) => (
+      <span style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}>
+        <Avatar name={String(value ?? '')} size={22} />
+        <Text variant="label-md">{String(value ?? '')}</Text>
+      </span>
+    ),
+  },
+  {
+    key: 'email',
+    name: '이메일',
+    width: 220,
+    validate: (v) => (v && !/^\S+@\S+\.\S+$/.test(String(v)) ? '이메일 형식이 아니에요' : null),
+  },
+  {
+    key: 'role',
+    name: '역할',
+    type: 'select',
+    width: 120,
+    creatable: false,
+    options: [
+      { label: '관리자', tone: 'accent' },
+      { label: '편집자', tone: 'success' },
+      { label: '뷰어', tone: 'neutral' },
+    ],
+  },
+  {
+    key: 'seats',
+    name: '좌석',
+    type: 'number',
+    format: 'plain',
+    width: 90,
+    validate: (v) => (typeof v === 'number' && (v < 1 || v > 50 || !Number.isInteger(v)) ? '1–50 사이 정수만 돼요' : null),
+  },
+  { key: 'joined', name: '가입일', type: 'date', width: 130, readOnly: true },
+]
+
+const ROWS: Member[] = [
+  { id: 'm1', name: '김민지', email: 'minji@lumen.app', role: '관리자', seats: 12, joined: '2025-03-02' },
+  { id: 'm2', name: '이도현', email: 'dohyun@lumen.app', role: '편집자', seats: 4, joined: '2025-07-18' },
+  { id: 'm3', name: '박서연', email: 'seoyeon@lumen.app', role: '편집자', seats: 2, joined: '2026-01-09' },
+  { id: 'm4', name: '최준호', email: 'junho@lumen.app', role: '뷰어', seats: 1, joined: '2026-09-30' },
+]
+
+export default function Example() {
+  return (
+    <DataGrid
+      title="멤버"
+      defaultColumns={COLUMNS}
+      defaultRows={ROWS}
+      columnEditing={false}
+      footer={false}
+      defaultView={{ rowNumbers: false }}
+      onCellEdit={({ row, column, value }) => toast.success(`${row.name} · ${column.name} → ${String(value ?? '비움')}`)}
+      height={320}
+      style={{ width: '100%' }}
+    />
+  )
+}
+```
+
+### 읽기 전용
+
+readOnly면 데이터는 바뀌지 않지만 선택·복사·정렬·너비 조절은 그대로 돼요. toolbar·footer를 끄면 작은 표로도 써요.
+
+```tsx
+import { DataGrid, type GridColumn, type GridRow } from '@iamfiro/design'
+
+interface Release extends GridRow {
+  version: string
+  date: string
+  changes: number
+  stable: boolean
+}
+
+const COLUMNS: GridColumn<Release>[] = [
+  { key: 'version', name: '버전', width: 120 },
+  { key: 'date', name: '배포일', type: 'date', width: 130 },
+  { key: 'changes', name: '변경', type: 'number', width: 100 },
+  { key: 'stable', name: '안정판', type: 'checkbox', width: 90 },
+]
+
+const ROWS: Release[] = [
+  { id: 'v5', version: 'v2.4.0', date: '2026-10-21', changes: 38, stable: true },
+  { id: 'v4', version: 'v2.4.0-rc.2', date: '2026-10-14', changes: 12, stable: false },
+  { id: 'v3', version: 'v2.3.2', date: '2026-09-30', changes: 7, stable: true },
+  { id: 'v2', version: 'v2.3.1', date: '2026-09-18', changes: 4, stable: true },
+]
+
+export default function Example() {
+  return <DataGrid readOnly toolbar={false} footer={false} defaultColumns={COLUMNS} defaultRows={ROWS} defaultView={{ rowNumbers: false }} style={{ width: 460 }} />
+}
+```

package/agents/date-picker/AGENTS.md

@@ -0,0 +1,197 @@
+# DatePicker · Calendar
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+날짜 입력. 입력창처럼 생긴 필드를 누르면 Popover 안에 달력이 열리고, 고르면 닫혀요. 화살표로 하루씩, PageUp/PageDown으로 한 달씩(Shift는 1년) 움직이고, 달을 넘기면 그 방향으로 미끄러져요. 위의 "2026년 10월"을 누르면 한 화면에서 연도(왼쪽 스크롤 목록)와 월(오른쪽)을 고를 수 있고, 월을 누르면 바로 그 달로 돌아와요. Esc는 날짜 화면으로 돌아가요. 기간 선택은 마우스를 올린 날까지 범위를 미리 보여줘요.
+
+```tsx
+import { Calendar, DatePicker, DateRangePicker, type DateRange } from '@iamfiro/design'
+```
+
+## API
+
+### DatePicker
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `Date \| null` |  | 선택한 날짜(제어). |
+| `defaultValue` | `Date \| null` | `null` | 처음 값(비제어). |
+| `onValueChange` | `(date: Date \| null) => void` |  | 고르거나 지울 때. |
+| `formatValue` | `(date: Date) => string` | `"10월 25일"` | 필드에 쓰는 형식. |
+| `placeholder` | `string` | `'날짜 입력 또는 선택'` | 비었을 때 문구. |
+| `clearable` | `boolean` | `true` | × 지우기 버튼. |
+| `min / max` | `Date` |  | 고를 수 있는 처음·마지막 날. |
+| `isDateDisabled` | `(date: Date) => boolean` |  | 추가로 막을 날(공휴일, 주말…). |
+| `weekStartsOn` | `0 \| 1` | `0` | 0 = 일요일 시작, 1 = 월요일 시작. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 필드 높이 36 / 44 / 52px. |
+| `invalid / disabled` | `boolean` |  | 오류 · 비활성. |
+| `align` | `'start' \| 'end'` | `'start'` | 달력이 필드 어느 쪽에 맞춰 열릴지. |
+
+### DateRangePicker
+
+DatePicker와 같은 props에 아래가 다르거나 추가돼요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value / defaultValue` | `DateRange` |  | { from: Date \| null, to: Date \| null } |
+| `onValueChange` | `(range: DateRange) => void` |  | 시작·끝을 고를 때마다. 두 날짜가 다 고르면 닫혀요. |
+| `presets` | `DatePreset[]` | `DEFAULT_DATE_PRESETS` | { label, range: () => DateRange }[]. []면 숨김. |
+
+### Calendar
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `mode` | `'single' \| 'range'` | `'single'` | 하루 또는 기간. |
+| `value / onValueChange` | `Date \| null · DateRange` |  | mode에 맞는 값. |
+| `defaultMonth` | `Date` |  | 처음 보여줄 달. 생략하면 선택한 날 또는 오늘. |
+| `min / max / isDateDisabled / weekStartsOn` | `…` |  | DatePicker와 같아요. |
+| `autoFocus` | `boolean` |  | 처음에 선택한 날(또는 오늘)로 포커스. 팝오버 안에서 써요. |
+| `showFooter` | `boolean` | `true` | 아래 줄("오늘" 버튼, 기간 선택 안내). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 날짜 선택
+
+값이 올해면 연도는 생략해요("10월 25일"). ×로 지울 수 있어요.
+
+```tsx
+import { useState } from 'react'
+import { Stack, Text, DatePicker, formatDate } from '@iamfiro/design'
+
+export default function Example() {
+  const [date, setDate] = useState<Date | null>(() => new Date())
+  return (
+    <Stack gap={2} style={{ width: 260 }}>
+      <DatePicker value={date} onValueChange={setDate} aria-label="마감일" />
+      <Text variant="caption" tone="tertiary">
+        선택: {date ? formatDate(date, true) : '없음'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 직접 입력
+
+"10/25", "2026.10.25", "10월 25일", "내일"처럼 쳐도 돼요. 완전한 날짜가 되면 달력이 따라오고, Enter로 확정, ↓로 달력에 들어가요. 못 알아들으면 빨갛게 표시하고, 칸을 벗어나면 원래 값으로 돌아가요.
+
+```tsx
+import { useState } from 'react'
+import { Field, Stack, Text, DatePicker, formatDate } from '@iamfiro/design'
+
+export default function Example() {
+  const [date, setDate] = useState<Date | null>(null)
+  return (
+    <Stack gap={2} style={{ width: 280 }}>
+      <Field label="출발일" htmlFor="depart" hint="예) 10/25 · 2026.10.25 · 10월 25일 · 내일">
+        <DatePicker id="depart" value={date} onValueChange={setDate} />
+      </Field>
+      <Text variant="caption" tone="tertiary">
+        값: {date ? formatDate(date, true) : '없음'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 기간 선택
+
+두 날짜를 차례로 누르거나, 왼쪽의 빠른 선택(오늘·최근 7일…)을 써요. presets로 바꾸거나 []로 숨겨요.
+
+```tsx
+import { useState } from 'react'
+import { Stack, Text, DateRangePicker, formatDate, type DateRange } from '@iamfiro/design'
+
+export default function Example() {
+  const [range, setRange] = useState<DateRange>({ from: null, to: null })
+  const days = range.from && range.to ? Math.round((range.to.getTime() - range.from.getTime()) / 86400000) + 1 : 0
+  return (
+    <Stack gap={2} style={{ width: 300 }}>
+      <DateRangePicker value={range} onValueChange={setRange} aria-label="조회 기간" />
+      <Text variant="caption" tone="tertiary">
+        {range.from && range.to ? `${formatDate(range.from)} ~ ${formatDate(range.to)} · ${days}일` : '두 날짜를 고르거나 빠른 선택을 눌러 보세요'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 선택 가능한 날짜 제한
+
+min · max와 isDateDisabled로 지난 날짜와 주말을 막아요. 막힌 날은 취소선으로 보여요.
+
+```tsx
+import { Field, DatePicker } from '@iamfiro/design'
+
+const today = new Date()
+const inThreeMonths = new Date(today.getFullYear(), today.getMonth() + 3, today.getDate())
+const isWeekend = (d: Date) => d.getDay() === 0 || d.getDay() === 6
+
+export default function Example() {
+  return (
+    <Field label="미팅 날짜 · 평일, 오늘부터 3개월 안" htmlFor="meeting-date">
+      <div style={{ width: 280 }}>
+        <DatePicker id="meeting-date" min={today} max={inThreeMonths} isDateDisabled={isWeekend} placeholder="평일을 고르세요" />
+      </div>
+    </Field>
+  )
+}
+```
+
+### Calendar 단독
+
+팝오버 없이 화면에 바로 두는 달력. 일요일은 빨강, 토요일은 파랑 톤. 아래 "오늘"로 바로 이동하고, 월요일 시작(weekStartsOn={1})도 돼요.
+
+```tsx
+import { useState } from 'react'
+import { Card, CardBody, Calendar, Inline } from '@iamfiro/design'
+
+export default function Example() {
+  const [date, setDate] = useState<Date | null>(() => new Date())
+  return (
+    <Inline gap={4} align="start">
+      <Card>
+        <CardBody>
+          <Calendar value={date} onValueChange={setDate} />
+        </CardBody>
+      </Card>
+      <Card>
+        <CardBody>
+          <Calendar value={date} onValueChange={setDate} weekStartsOn={1} />
+        </CardBody>
+      </Card>
+    </Inline>
+  )
+}
+```
+
+### 크기와 상태
+
+Field와 함께 쓰면 라벨이 연결돼요. size · invalid · disabled.
+
+```tsx
+import { Field, Grid, DatePicker } from '@iamfiro/design'
+
+const TODAY = new Date()
+
+export default function Example() {
+  return (
+    <Grid columns={2} gap={4} style={{ width: 480 }}>
+      <Field label="작게 (sm)" htmlFor="dp-sm">
+        <DatePicker id="dp-sm" size="sm" defaultValue={TODAY} />
+      </Field>
+      <Field label="크게 (lg)" htmlFor="dp-lg">
+        <DatePicker id="dp-lg" size="lg" />
+      </Field>
+      <Field label="시작일" invalid hint="시작일을 골라 주세요." htmlFor="dp-err">
+        <DatePicker id="dp-err" invalid />
+      </Field>
+      <Field label="계약일" htmlFor="dp-off">
+        <DatePicker id="dp-off" defaultValue={new Date(2026, 0, 2)} disabled />
+      </Field>
+    </Grid>
+  )
+}
+```