@makitt.io/mds-mcp-server 0.1.2 → 0.2.0

package/dist/data/playbook/data-grid.md

@@ -1,23 +1,23 @@
 # MDS Playbook — DataGrid + Table
 
-list / table 데이터 표시 의 약속.
+list / table 데이터 표시에 대한 약속.
 
-> mds 의 list 컴포넌트 = **DataGrid** (full-feature) + **Table** (custom column).
-> 99% list 페이지 = DataGrid. Table 은 특수 case.
+> mds 의 list 컴포넌트 = **DataGrid** (full-feature) + **Table** (custom
+> column). 99% list 페이지 = DataGrid. Table 은 특수 case.
 
 ---
 
 ## 1. DataGrid vs Table 선택
 
-| 케이스 | 답 | 이유 |
-|---|---|---|
-| 셀러 admin 의 list 페이지 (customers / orders / products) | **DataGrid** | filter / search / sort / pagination / selection / bulk action / loading / empty / error 자동 |
-| URL state 동기화 필요 (deep link) | **DataGrid** | controlled props (page / sort / filter / search) 모두 노출 |
-| Server-side filter/sort | **DataGrid** `mode="server"` | totalItems / onPageChange / onSortChange caller 처리 |
-| 단순 정보 표시 (정적 list, 보통 5-10 row) | **Table** | DataGrid 의 toolbar 과잉 |
-| 페이지의 한 섹션 안 작은 list (예: 고객의 최근 주문 3개) | **Table** | 페이지의 다른 컨텍스트와 통합 |
-| 매우 custom layout (column 별 다른 component) | **Table** + caller column render |
-| Tree / nested rows | **Tree** (compounds) — Table 아님 |
+| 케이스                                                    | 답                                | 이유                                                                                         |
+| --------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------- |
+| 셀러 admin 의 list 페이지 (customers / orders / products) | **DataGrid**                      | filter / search / sort / pagination / selection / bulk action / loading / empty / error 자동 |
+| URL state 동기화 필요 (deep link)                         | **DataGrid**                      | controlled props (page / sort / filter / search) 모두 노출                                   |
+| Server-side filter/sort                                   | **DataGrid** `mode="server"`      | totalItems / onPageChange / onSortChange caller 처리                                         |
+| 단순 정보 표시 (정적 list, 보통 5-10 row)                 | **Table**                         | DataGrid 의 toolbar 과잉                                                                     |
+| 페이지의 한 섹션 안 작은 list (예: 고객의 최근 주문 3개)  | **Table**                         | 페이지의 다른 컨텍스트와 통합                                                                |
+| 매우 custom layout (column 별 다른 component)             | **Table** + caller column render  |
+| Tree / nested rows                                        | **Tree** (compounds) — Table 아님 |
 
 > **Default = DataGrid**. Table 은 의식적 결정.
 
@@ -34,7 +34,12 @@ list / table 데이터 표시 의 약속.
   title="주문"
   filters={[
     { value: 'all', label: '전체', count: 248, predicate: () => true },
-    { value: 'pending', label: '결제 대기', count: 12, predicate: (o) => o.status === 'pending' },
+    {
+      value: 'pending',
+      label: '결제 대기',
+      count: 12,
+      predicate: (o) => o.status === 'pending',
+    },
   ]}
   defaultFilter="all"
   searchableKeys={['id', 'customer']}
@@ -52,7 +57,7 @@ list / table 데이터 표시 의 약속.
   onRowClick={(o) => navigate(`/orders/${o.id}`)}
   density="default"
   stickyHeader
-  storageKey="orders-grid"  // localStorage column widths / hidden
+  storageKey="orders-grid" // localStorage column widths / hidden
 />
 ```
 
@@ -69,104 +74,195 @@ const columns: ColumnDef<Order>[] = [
 
 ### Column 패턴 (셀러 admin 표준)
 
-| Column 종류 | 컴포넌트 | 예 |
-|---|---|---|
-| ID / 번호 | `Code size="xs"` | `#HE-2719` |
-| 사람 (고객 / 사용자) | `PersonCell` | avatar + name + sub |
-| 상태 | `Pill tone={...}` | success / warning / danger / info |
-| 금액 | tabular-nums + right-align | `₩123,456` |
-| 날짜 | `relativeDate` 또는 `formatDate` | `3일 전` / `2026-05-01` |
-| 액션 | `IconButton` / `Menu` | 행 끝 |
-| 진행률 | `ProgressRow` | bar + pct |
-| 추세 | `Sparkline` | mini chart |
+| Column 종류          | 컴포넌트                         | 예                                |
+| -------------------- | -------------------------------- | --------------------------------- |
+| ID / 번호            | `Code size="xs"`                 | `#HE-2719`                        |
+| 사람 (고객 / 사용자) | `PersonCell`                     | avatar + name + sub               |
+| 상태                 | `Pill tone={...}`                | success / warning / danger / info |
+| 금액                 | tabular-nums + right-align       | `₩123,456`                        |
+| 날짜                 | `relativeDate` 또는 `formatDate` | `3일 전` / `2026-05-01`           |
+| 액션                 | `IconButton` / `Menu`            | 행 끝                             |
+| 진행률               | `ProgressRow`                    | bar + pct                         |
+| 추세                 | `Sparkline`                      | mini chart                        |
+
+### Column key 명명 표준 (필수)
+
+| 표준 key                  | 의도                            | 비고                                                                    |
+| ------------------------- | ------------------------------- | ----------------------------------------------------------------------- |
+| `id`                      | entity primary id               | snake_case 금지 (`created_at` ❌ → `createdAt`)                         |
+| `name` / `title`          | entity 의 식별용 이름 / 제목    | 도메인 별 alias (`orderNumber` / `productName`) 는 의도가 명확하면 허용 |
+| `customer`                | actor (PersonCell)              | —                                                                       |
+| `status`                  | Pill tone enum                  | —                                                                       |
+| `amount`                  | 금액 (right-align mono)         | `total` 같은 alias 허용 단 의도 일관성 우선                             |
+| `createdAt` / `updatedAt` | 날짜 (camelCase 필수)           | `created_at` 같은 snake_case 금지                                       |
+| `actions`                 | row actions (IconButton / Menu) | 모든 list 의 마지막 column 으로 고정                                    |
+
+→ **camelCase 필수**. snake_case (`created_at`) / mixed naming 금지.
+
+### Column 순서 표준
+
+`[entity-id → entity-info → actor → status → amount → metadata → actions]`
+
+```ts
+// 표준 순서 예 (order list)
+const columns = [
+  { key: 'id', header: '주문 번호' }, // 1. entity-id
+  { key: 'product', header: '상품' }, // 2. entity-info
+  { key: 'customer', header: '고객' }, // 3. actor
+  { key: 'status', header: '상태' }, // 4. status
+  { key: 'amount', header: '금액', align: 'right' }, // 5. amount
+  { key: 'createdAt', header: '주문일' }, // 6. metadata
+  { key: 'actions', header: '', align: 'right' }, // 7. actions (마지막)
+];
+```
+
+> 일부 도메인 (예: blog) 은 amount 가 없을 수 있음 → metadata 직전 으로 의도된
+> 생략 OK. 단 — `id → ... → actions` 의 **앞 / 뒤 anchor** 는 모든 list 에서
+> 동일.
+
+### Actions column 활용
+
+```tsx
+{
+  key: 'actions',
+  header: '',
+  align: 'right',
+  width: '60px',
+  render: (row) => (
+    <Menu.Root>
+      <Menu.Trigger><IconButton aria-label="더보기" variant="ghost"><MoreHorizontal size={14} /></IconButton></Menu.Trigger>
+      <Menu.Content>
+        <Menu.Item onClick={() => edit(row.id)}>편집</Menu.Item>
+        <Menu.Item onClick={() => duplicate(row.id)}>복제</Menu.Item>
+        <Menu.Separator />
+        <Menu.Item onClick={() => remove(row.id)} variant="danger">삭제</Menu.Item>
+      </Menu.Content>
+    </Menu.Root>
+  ),
+}
+```
+
+- **모든 list 의 마지막 column 은 actions** (강제)
+- Menu 활용 — 2 개 이상 action 이면 Menu 안에 단일 IconButton trigger
+- Single action — 직접 IconButton (예: preview / open)
+- destructive action — `Menu.Item variant="danger"` + Menu.Separator 로 분리
 
 ---
 
-## 3. Mobile 변형
+## 3. Mobile 변형 (Responsive 표준)
+
+| Desktop (≥ md)                            | Mobile (< md)                                              |
+| ----------------------------------------- | ---------------------------------------------------------- |
+| DataGrid table 형                         | **Card list** (각 row → card, primary column 1-2개만 표시) |
+| Sticky header                             | `position: sticky` 그대로                                  |
+| Toolbar (filter pills + search + actions) | toolbar collapse — filter drawer / search expand           |
+| Pagination (page numbers)                 | infinite scroll 또는 numeric only                          |
+| selection (checkbox column)               | hidden — long-press 또는 명시 toggle                       |
+| actions column (Menu)                     | swipe-actions 또는 row-bottom IconButton                   |
+
+### Mobile 변환 mechanism
+
+```tsx
+<DataGrid
+  data={rows}
+  columns={columns}
+  // Mobile = card 형식 으로 자동 변환
+  mobileView={{
+    title: (row) => row.name, // card primary
+    subtitle: (row) => row.email, // card secondary
+    statusKey: 'status', // status badge 표시 column
+    actionsKey: 'actions', // 우측 swipe actions
+  }}
+/>
+```
 
-| Desktop | Mobile (< md) |
-|---|---|
-| DataGrid table 형 | **Card list** (각 row → card, primary column 1-2개만 표시) |
-| Sticky header | `position: sticky` 그대로 (모바일도 동작) |
-| Toolbar (filter pills + search + actions) | toolbar collapse — filter drawer / search expand |
-| Pagination (page numbers) | infinite scroll 또는 numeric only |
-| selection (checkbox column) | 일반적으로 숨김 — long-press 로 multi-select 도 가능 (TBD) |
+- **Default**: Tailwind preset 의 token responsive (text-3xl / space-\* 등
+  mobile fallback 자동 — responsive-tokens.md)
+- **DataGrid 의 mobile = card list 자동 변환** — `mobileView` prop 만 지정하면
+  caller 가 별도 layout 작성 없이 mobile 의 card 표시 가능
+- **Breakpoint = md (768px)** — `useIsBreakpointUp('md')` 내부 활용
 
-> Mobile 변환 mechanism — DataGrid 의 `mobileView` prop 또는 자동 (`useIsBreakpointUp('md')`).
-> 현재 mds 의 DataGrid = desktop only. Mobile 자동 변환 = **TBD** (Step 11 builder / web 마이그레이션 시).
+> 현재 상태 — DataGrid 의 `mobileView` prop 은 **TBD: mds 의 DataGrid 에 추가
+> 필요** (지금은 desktop only). 임시로는 caller 가 `useBreakpoint()` + 별도
+> CardList 직접 구현.
 
 ---
 
 ## 4. Loading / Error / Empty state — async-states.md §1 참조
 
-| state | 컴포넌트 |
-|---|---|
-| loading (초기 fetch) | `<SkeletonRows>` (DataGrid 자동) |
-| loading 더 보기 (page 2) | 부분 skeleton + 기존 row 유지 |
-| error | `<ErrorState error={err} onRetry={refetch}>` (DataGrid `errorState` prop) |
-| empty (필터 결과 0) | `<EmptyState variant="search" action={resetFilters}>` |
-| empty (한 번도 없음) | `<EmptyState variant="onboarding" action={createX}>` |
+| state                    | 컴포넌트                                                                  |
+| ------------------------ | ------------------------------------------------------------------------- |
+| loading (초기 fetch)     | `<SkeletonRows>` (DataGrid 자동)                                          |
+| loading 더 보기 (page 2) | 부분 skeleton + 기존 row 유지                                             |
+| error                    | `<ErrorState error={err} onRetry={refetch}>` (DataGrid `errorState` prop) |
+| empty (필터 결과 0)      | `<EmptyState variant="search" action={resetFilters}>`                     |
+| empty (한 번도 없음)     | `<EmptyState variant="onboarding" action={createX}>`                      |
 
 ---
 
 ## 5. 결정 표 (lookup)
 
-| 케이스 | 답 |
-|---|---|
-| "page list 표시" | DataGrid |
-| "5개 정도 단순 table" | Table |
-| "tree / nested" | Tree (compounds) |
-| "row click → 상세" | DataGrid `onRowClick={navigate(...)}` |
-| "row click → 옆 편집 (목록 유지)" | DataGrid `onRowClick={() => openDrawer(...)}` |
-| "URL filter / page 동기화" | DataGrid controlled props (`page`, `onPageChange` etc.) |
-| "Server-side" | DataGrid `mode="server" totalItems={N}` |
-| "bulk action" | DataGrid `selectable bulkActions={(selected) => ...}` |
-| "column resize / hide / reorder" | DataGrid `storageKey` + 자동 |
-| "column custom component" | `column.render` prop |
-| "특정 column 만 sortable" | `column.sortable: true` |
-| "1 필드 inline 편집" | DataGrid column.render = controlled input + form.md §5 (Inline 편집 — Enter 명시 저장) |
+| 케이스                            | 답                                                                                     |
+| --------------------------------- | -------------------------------------------------------------------------------------- |
+| "page list 표시"                  | DataGrid                                                                               |
+| "5개 정도 단순 table"             | Table                                                                                  |
+| "tree / nested"                   | Tree (compounds)                                                                       |
+| "row click → 상세"                | DataGrid `onRowClick={navigate(...)}`                                                  |
+| "row click → 옆 편집 (목록 유지)" | DataGrid `onRowClick={() => openDrawer(...)}`                                          |
+| "URL filter / page 동기화"        | DataGrid controlled props (`page`, `onPageChange` etc.)                                |
+| "Server-side"                     | DataGrid `mode="server" totalItems={N}`                                                |
+| "bulk action"                     | DataGrid `selectable bulkActions={(selected) => ...}`                                  |
+| "column resize / hide / reorder"  | DataGrid `storageKey` + 자동                                                           |
+| "column custom component"         | `column.render` prop                                                                   |
+| "특정 column 만 sortable"         | `column.sortable: true`                                                                |
+| "1 필드 inline 편집"              | DataGrid column.render = controlled input + form.md §5 (Inline 편집 — Enter 명시 저장) |
 
 ---
 
 ## 6. 안티 패턴
 
-- ❌ **DataGrid 안에 form (모든 row 의 input)** — 큰 form 은 별도 페이지 (page-form). DataGrid 는 list / inline 편집 1 필드만
-- ❌ **Table 으로 DataGrid 흉내** — toolbar / filter / pagination 다 caller 구현 = 중복. DataGrid 사용
+- ❌ **DataGrid 안에 form (모든 row 의 input)** — 큰 form 은 별도 페이지
+  (page-form). DataGrid 는 list / inline 편집 1 필드만
+- ❌ **Table 으로 DataGrid 흉내** — toolbar / filter / pagination 다 caller 구현
+  = 중복. DataGrid 사용
 - ❌ **DataGrid 의 column 50+** — 사용자 스캔 불가. 일부 hidden + caller 가 선택
-- ❌ **Loading 시 empty state 표시** — async-states.md §2 — 로딩 중 ErrorState/EmptyState 금지
-- ❌ **row 클릭 + checkbox 동시 작동** — 한쪽만. selection 모드 시 row click 막힘 또는 다른 의미
+- ❌ **Loading 시 empty state 표시** — async-states.md §2 — 로딩 중
+  ErrorState/EmptyState 금지
+- ❌ **row 클릭 + checkbox 동시 작동** — 한쪽만. selection 모드 시 row click
+  막힘 또는 다른 의미
 - ❌ **pagination size 가 50+** — render 부담 + a11y. 최대 20-30 권장
 - ❌ **column header 가 너무 길거나 wrap** — fixed height, ellipsis
-- ❌ **selection state 가 page 이동 후 사라짐** — DataGrid 의 selectedIds Set 유지 (cross-page)
+- ❌ **selection state 가 page 이동 후 사라짐** — DataGrid 의 selectedIds Set
+  유지 (cross-page)
 
 ---
 
 ## 7. Cross-cutting
 
-| Axis | 적용 |
-|---|---|
-| **Responsive** | DataGrid → card list mobile (TBD 자동 변환) |
-| **A11y** | `<table role="table">` 자동 / column header `<th scope="col">` / sortable button aria-sort / selection checkbox aria-label |
-| **i18n** | column label / filter label / empty message 모두 `t()` |
-| **AI fill** | DataGrid 의 filter 가 AI 자동 제안 가능 (Step 4.8) |
-| **Catalog** | DataGrid props (columns / filters / mode / state props) 자동 catalog (Step 5) |
-| **Telemetry** | row click / sort / filter / search / bulk action 자동 log (Step 7) |
+| Axis           | 적용                                                                                                                       |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| **Responsive** | DataGrid → card list mobile (TBD 자동 변환)                                                                                |
+| **A11y**       | `<table role="table">` 자동 / column header `<th scope="col">` / sortable button aria-sort / selection checkbox aria-label |
+| **i18n**       | column label / filter label / empty message 모두 `t()`                                                                     |
+| **AI fill**    | DataGrid 의 filter 가 AI 자동 제안 가능 (Step 4.8)                                                                         |
+| **Catalog**    | DataGrid props (columns / filters / mode / state props) 자동 catalog (Step 5)                                              |
+| **Telemetry**  | row click / sort / filter / search / bulk action 자동 log (Step 7)                                                         |
 
 ---
 
 ## 8. apps/web 의 실 사용 (Step 7 Web Playbook 의 baseline)
 
-| Page | DataGrid 사용 |
-|---|---|
-| `/merchant/customers` | DataGrid (filter / search / row click → drawer / bulk action) |
-| `/merchant/orders` | DataGrid (filter / search / row click → detail page / status update bulk) |
-| `/merchant/payment/transactions` | DataGrid (server mode + URL state) |
-| `/merchant/payment/refunds` | 동일 |
-| `/merchant/content/blogs` (list) | DataGrid |
-| `/merchant/content/announcements` | DataGrid |
-| `/merchant/content/banners` | DataGrid |
-| `/admin/dead-letters` | DataGrid (admin) |
-| `/admin/exchange-rates` | DataGrid (admin) |
+| Page                              | DataGrid 사용                                                             |
+| --------------------------------- | ------------------------------------------------------------------------- |
+| `/merchant/customers`             | DataGrid (filter / search / row click → drawer / bulk action)             |
+| `/merchant/orders`                | DataGrid (filter / search / row click → detail page / status update bulk) |
+| `/merchant/payment/transactions`  | DataGrid (server mode + URL state)                                        |
+| `/merchant/payment/refunds`       | 동일                                                                      |
+| `/merchant/content/blogs` (list)  | DataGrid                                                                  |
+| `/merchant/content/announcements` | DataGrid                                                                  |
+| `/merchant/content/banners`       | DataGrid                                                                  |
+| `/admin/dead-letters`             | DataGrid (admin)                                                          |
+| `/admin/exchange-rates`           | DataGrid (admin)                                                          |
 
 → 20+ 페이지가 DataGrid 사용. 균일성 보장 = Web Playbook (Step 7) 의 표준.
 
@@ -176,7 +272,8 @@ const columns: ColumnDef<Order>[] = [
 
 1. **Mobile 자동 변환** — DataGrid → card list 의 자동 변환 컴포넌트 (CardList?)
 2. **Long-press multi-select** — 모바일 의 selection 패턴
-3. **Inline 편집 컴포넌트** — DataGrid cell 의 EditCell wrapper 추가 (Enter / 체크 명시 저장)
+3. **Inline 편집 컴포넌트** — DataGrid cell 의 EditCell wrapper 추가 (Enter /
+   체크 명시 저장)
 4. **Sticky column** — first / last column 의 sticky (가로 scroll 시)
 5. **Virtual scroll** — row 1000+ 시 virtualization (현재 mds 미지원)
 6. **Group by** — row grouping (예: status 별 group)