@hjmds/design-contracts 1.12.1 → 1.13.0

package/docs/usage/components/content-transition.md

@@ -0,0 +1,101 @@
+# ContentTransition
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: contract `src/content-transition.ts`(`resolveContentTransition`)
+- 스토리북: `배포/컴포넌트/시각 효과/내용 전환`
+
+## 언제 쓰나
+
+같은 자리의 내용이 상태에 따라 바뀔 때(필터 결과 패널, 단계별 본문) 새 내용이 짧게 나타나도록 감싼다.
+`stateKey`가 바뀔 때만 움직이고, 화면에는 현재 내용 하나만 남는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 바뀌는 것이 텍스트 한 줄 | [TextTransition](text-transition.md) |
+| 화면 사이 이동 | [SharedTransitionScreen](shared-transition-screen.md) |
+| 내용이 아직 로딩 중 | [Skeleton](skeleton.md) |
+| 내용을 펼치고 접기 | [Collapsible](collapsible.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ContentTransition` | 보조 — 별도 보조 기능(supplemental) | `/content-transition` | `/content-transition` |
+| `TextTransition` | 동반 — 텍스트 전용, [별도 지침](text-transition.md) | `/content-transition` | `/content-transition` |
+
+root에서 export되지 않고 granular subpath로만 import 된다. Web은 optional peer `framer-motion`이 필요하다.
+Native는 React Native `Animated`만 써서 추가 peer가 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ContentTransition } from "@hjmds/react/content-transition";
+import { useRef } from "react";
+
+// 상태 → 키 상수 표. 키를 템플릿 문자열로 만들지 않는다.
+const titleKey = { all: "results.all.title", unread: "results.unread.title" } as const;
+
+function Results({ filter }: { filter: keyof typeof titleKey }) {
+  const heading = useRef<HTMLHeadingElement>(null);
+  return (
+    <ContentTransition stateKey={filter} preset="rise" focusTarget={heading}>
+      <h2 ref={heading} tabIndex={-1}>{t(titleKey[filter])}</h2>
+      <ResultList filter={filter} />
+    </ContentTransition>
+  );
+}
+```
+
+```tsx
+// Native
+import { ContentTransition } from "@hjmds/react-native/content-transition";
+
+<ContentTransition stateKey={step} preset="slide">
+  <StepBody step={step} />
+</ContentTransition>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `preset` | `fade` · `rise` · `slide` · `scale` | `fade` | `rise`는 아래 12에서, `slide`는 가로 16(RTL이면 반대), `scale`은 0.96에서 시작 |
+| `motion` | `system` · `none` | `system` | `system`은 reduced motion을 따르고 `none`은 항상 즉시 교체 |
+| `stateKey` | `string` | — (필수) | 바뀔 때만 새 내용이 나타난다 |
+| Web `focusTarget` | `RefObject<HTMLElement \| null>` | — | 바뀌기 전 포커스가 안에 있었으면 전환 뒤 이 요소로 옮긴다 |
+| Web `layoutStyle` | 배치 전용 style | — | 바깥 고정 wrapper에 붙는다(키가 바뀌는 안쪽 패널이 아님) |
+
+콜백 prop은 없다. `TextTransition`은 `text: string`을 `stateKey`로 쓴다.
+
+- 첫 렌더는 움직이지 않는다. 시간은 `motion.normal`, 곡선은 `easing.enter` 토큰이다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 자체 크기·여백이 없다. Web은 `div` 두 겹(블록), Native는 `Animated.View` 하나로 감싼다 | `packages/react/src/content-transition.tsx`, `packages/react-native/src/content-transition.tsx` |
+| 간격 | 자체 간격이 없다. 위아래 간격은 감싸는 [Stack](stack.md) 등이 정한다. 움직임 폭(세로 12·가로 16·0.96배)만큼 래퍼 밖으로 잠깐 밀려 나오므로 바로 옆 요소와 간격을 둔다 | `src/content-transition.ts` |
+| 순서·정렬 | 바뀌는 영역 하나만 감싼다(결과 패널, 단계 본문). 필터 막대·탭·제목처럼 그대로 남는 부분은 바깥에 둔다 | — |
+| 고정·스크롤 | Native 래퍼에는 `flex`가 없어 남은 높이를 채우지 않는다. 화면 높이를 채워야 하는 내용이면 바깥 View가 높이를 정한다 | `packages/react-native/src/content-transition.tsx` |
+| 좁은 폭·큰 글자 | — | — |
+
+## 꼭 지킬 것
+
+- `stateKey`는 내용의 의미가 바뀔 때만 바꾼다. 매 렌더 새 값을 주면 계속 다시 나타난다.
+- 사라지는 내용의 복사본을 남기지 않는 계약이다. 교차 페이드를 직접 만들려고 두 겹을 겹치지 않는다.
+- Web 배치는 `layoutStyle`(바깥 wrapper)로 한다. Native는 배치 prop(`style`·`layoutStyle`)이 없어 바깥 View가 배치한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 포커스 복원 | `focusTarget`: 바뀌기 전 포커스가 안에 있었으면 그 요소로 옮긴다 | 없음 |
+| 앱이 백그라운드로 감 | 해당 없음 | 진행 중 전환을 멈추고 바로 표시 |
+| 배치 prop | `layoutStyle`(바깥 wrapper) | 없음 |

package/docs/usage/components/context-menu.md

@@ -0,0 +1,136 @@
+# ContextMenu
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [ContextMenu](../../context-menu.md), [선택 어댑터](../../optional-adapters.md), recipe `menuRecipe`
+- 스토리북: `배포/컴포넌트/탐색/상황별 메뉴`
+
+## 언제 쓰나
+
+Web에서 제품이 소유한 영역(카드·목록 행·캔버스)의 우클릭·길게 누르기·Shift+F10에 명령 목록을
+띄울 때 쓴다. 같은 명령은 화면의 다른 경로(버튼·Menu)에도 있어야 한다. Native canonical 구현은 없고,
+OS 길게 누르기 메뉴가 필요하면 선택 어댑터 `NativeContextMenu`를 쓴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 버튼을 눌러 여는 명령 목록 | [Menu](menu.md) |
+| 앱 상단 메뉴 막대(Web) | [Menubar](menubar.md) |
+| 목록 행을 밀어 나오는 행동 | [SwipeActions](swipe-actions.md) |
+| 텍스트 선택·링크·이미지 위의 브라우저 기본 메뉴 대체 | 쓰지 않는다([계약](../../context-menu.md)) |
+| Native에서 추가 의존성 없이 행동 목록 | [Menu](menu.md), [Sheet](sheet.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ContextMenu` | 기본 — Web 전용 | `@hjmds/react`, `/context-menu` | 없음 |
+| `NativeContextMenu` | 확장 — OS 길게 누르기 메뉴 선택 어댑터 | 없음 | `/context-menu-native` |
+
+`NativeContextMenu`는 root에서 재노출되지 않는다. `@hjmds/react-native/context-menu-native`로만 import한다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ContextMenu } from "@hjmds/react/context-menu";
+
+<ContextMenu
+  accessibilityLabel={t("post.actions")}
+  items={[
+    { id: "share", label: t("post.share"), textValue: t("post.share") },
+    { id: "delete", label: t("post.delete"), textValue: t("post.delete"), tone: "danger" },
+  ]}
+  onAction={(id) => runPostAction(post, id)}
+>
+  <PostCard post={post} />
+</ContextMenu>
+```
+
+```tsx
+// Native (선택 어댑터)
+import { NativeContextMenu } from "@hjmds/react-native/context-menu-native";
+import { Pressable } from "react-native";
+
+<NativeContextMenu
+  items={[
+    { id: "share", label: t("post.share") },
+    { id: "delete", label: t("post.delete"), tone: "danger" },
+  ]}
+  onAction={(id) => runPostAction(post, id)}
+>
+  <Pressable accessibilityRole="button" accessibilityLabel={t("post.open")}>
+    <PostCardBody post={post} />
+  </Pressable>
+</NativeContextMenu>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| Web `items` | `{ id, label, textValue, shortcut?, disabled?, tone?: "default" \| "danger" }[]` | — (필수) | `MenuItemDescriptor`. `description`은 그리지 않는다 |
+| Native `items` | `{ id: string, label: string, disabled?, tone?: "default" \| "danger" }[]` | — (필수) | 비거나 id 중복·빈 라벨이면 `TypeError` |
+| `onAction` | Web `(id: Key) => void` · Native `(id: string) => void` | — (필수) | 고른 항목 id. 메뉴는 닫힌다 |
+| Web `accessibilityLabel` | `string` | — (필수) | 메뉴 이름 |
+| Native `onOpenChange` | `(open: boolean) => void` | — | OS 메뉴가 열리고 닫힐 때 |
+| Web `layoutStyle` | 배치 전용 style | — | 영역 래퍼(흐름 안)에 붙는다. 떠 있는 메뉴는 배치하지 않는다 |
+| Web `className` | `string` | — | 영역 래퍼 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 메뉴(Web): 최대 폭 `min(24rem, 90vw)`, 최대 높이 뷰포트 높이 − 2×`spacing.md`(16). 항목 최소 높이 `control.minTouchTarget` 44. 감싼 영역 래퍼(`.hjm-context-menu-host`)는 `min-inline-size: 0`만 가지며 크기·여백을 더하지 않는다 | `packages/react/src/styles.css` `.hjm-context-menu*` |
+| 간격 | 메뉴 안쪽 여백 `spacing.xs` 8(`menuRecipe.surface.padding`, Menu와 같다. 2026-10-06까지 4, 1.12.1 이후 미게시), 항목 여백 `spacing.xs` 8 · `spacing.sm` 12, 라벨–단축키 간격 `spacing.sm` 12 | `packages/react/src/styles.css` `.hjm-context-menu__item` |
+| 순서·정렬 | 항목은 `items` 배열 순서대로 위에서 아래로 그린다. 단축키는 끝에 붙고 줄바꿈하지 않는다. 우클릭·길게 누르기는 누른 좌표, Shift+F10·메뉴 키는 영역의 시작 쪽 아래 모서리에 메뉴를 연다 | `packages/react/src/context-menu.tsx`, `src/context-menu.ts` |
+| 고정·스크롤 | `position: fixed`로 뜨고 뷰포트 밖으로 넘치면 안쪽으로 밀어 넣는다. 최대 높이를 넘으면 메뉴 안에서 스크롤한다 | `packages/react/src/context-menu.tsx` |
+| 좁은 폭·큰 글자 | 좁은 폭에서는 최대 폭이 `90vw`로 줄고 항목 라벨은 줄바꿈한다. Native `NativeContextMenu`의 위치·크기·미리보기는 OS가 정한다 | `packages/react/src/styles.css` |
+
+```text
+┌ 카드(ContextMenu 영역) ─────────────────┐
+│                 ● 우클릭·길게 누른 지점   │
+│                 ┌──────────────────────┐ │
+│                 │ 공유          ⌘S     │ │  항목 최소 높이 44
+│                 │ 삭제(danger)         │ │
+│                 └──────────────────────┘ │
+└──────────────────────────────────────────┘
+키보드로 열면 메뉴 왼쪽 위가 영역의 왼쪽 아래 모서리에 붙는다(RTL은 시작 쪽).
+```
+
+## 꼭 지킬 것
+
+- 메뉴 이름·항목 라벨은 i18n 키로 넣는다. 위험한 행동은 `tone: "danger"`로 표시하고 실행 전 확인은 제품이 한다.
+- Web 항목은 `MenuItemDescriptor`(`id`·`label`·`textValue` 필수, `shortcut`·`disabled`·`tone` 선택)다.
+  `description`은 타입에 있지만 ContextMenu는 그리지 않는다.
+- Web 영역은 `tabIndex=0` 래퍼가 되어 키보드로 열 수 있다. 같은 명령을 다른 보이는 경로에도 둔다.
+- `NativeContextMenu`의 `children`은 접근 가능한 native 요소 하나다(`asChild`로 트리거가 된다).
+  항목이 비거나, id가 중복되거나, id·라벨이 비면 실행 중 `TypeError`다.
+- 메뉴 색·모양은 OS(Native)와 `menuRecipe`(Web)가 소유한다. 임의 색은 지원하지 않는다.
+
+### Native 선택 어댑터 설치 조건
+
+- `zeego` 3.0.6이 optional peer다. zeego가 요구하는 `@react-native-menu/menu` 1.2.2,
+  `react-native-ios-context-menu` 3.2.1, `react-native-ios-utilities` 5.2.0도 package.json의 optional peer로
+  고정돼 있다. 이 subpath를 쓰는 앱만 설치한다. 기본 entry는 이 peer 없이 동작한다.
+- native module이라 개발 클라이언트를 다시 빌드해야 하고 Expo Go로는 확인할 수 없다.
+- 배포된 HJM은 workspace patch를 적용해 주지 않는다. `@hjmds/react-native/docs/patches/`의 menu·
+  ios-context-menu·ios-utilities patch를 앱에 복사해 등록한 뒤 빌드한다([선택 어댑터](../../optional-adapters.md)).
+- 2026-10에 optional native peer가 없는 앱에서 다른 선택 subpath(celebration·effect-surface·qr-code·
+  thinking-orb·toast-liquid)가 tsc·테스트는 통과하고 기기 Metro에서 크래시를 냈다. 이 subpath도
+  peer를 import하므로 기기에서 실행해 확인한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 구현 | `ContextMenu` | `NativeContextMenu` |
+| 여는 방법 | 우클릭, 터치 길게 누르기(500ms), Shift+F10·메뉴 키 | OS 길게 누르기 |
+| 메뉴 접근성 이름 | `accessibilityLabel`(필수) | 없음(자식 요소가 이름을 가짐) |
+| 항목 `textValue`·`shortcut` | 있음 | 없음 |
+| 열림 알림 | 없음 | `onOpenChange(open)` |
+| 성숙도 | stable | 실험적 어댑터(기기 증거 전까지 canonical unsupported) |

package/docs/usage/components/counter-badge.md

@@ -0,0 +1,107 @@
+# CounterBadge
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: recipe `counterBadgeRecipe`(`src/counter-badge-recipe.ts`), 숫자 규칙 `formatCounterBadgeCount`(`src/counter-badge.ts`)
+- 스토리북: `배포/컴포넌트/데이터 표시/숫자 배지`
+
+## 언제 쓰나
+
+읽지 않은 알림·메시지·장바구니 수처럼 **셀 수 있는 개수**를 아이콘·행 옆에 작게 보일 때 쓴다.
+0이면 아무것도 그리지 않고, `max`를 넘으면 `99+`처럼 줄인다. Web은 숫자 없이 "새것이 있음"만
+알리는 점(`dot`)도 그린다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 상태·분류 텍스트(신규, 완료, 오류) | [Badge](badge.md), [Tag](tag.md) |
+| 하단 탭의 개수 | [BottomNavigation](bottom-navigation.md) 항목의 `badge` |
+| 큰 숫자 지표 | [Statistic](statistic.md) |
+| 진행률 | [Progress](progress.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `CounterBadge` | 기본 | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/data-display` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { CounterBadge } from "@hjmds/react/display";
+
+<CounterBadge
+  count={unread}
+  accessibilityLabel={t("inbox.unreadCount", { count: unread })}
+/>
+```
+
+```tsx
+// Native
+import { CounterBadge } from "@hjmds/react-native/data-display";
+
+<CounterBadge
+  count={unread}
+  accessibilityLabel={t("inbox.unreadCount", { count: unread })}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `tone` | `danger` · `brand` · `neutral` | `danger` | — |
+| `size` | `small` · `medium` | `medium` | — |
+| `variant` | `inline` · `floating` | `inline` | `floating`은 아이콘 모서리에 겹칠 때 쓰는 테두리 있는 판 |
+| `max` | 숫자 | `99` | 소수는 버리고 음수·`NaN`은 0으로 본다 |
+| `dot` | `true` · `false` | `false` | Web만. 숫자 대신 8px 점을 그린다 |
+| `count` | `number` | — (필수) | 0 이하면 아무것도 그리지 않는다 |
+| `accessibilityLabel` | `string` | — | 없으면 보조기술에서 숨는다. 빈 문자열은 `TypeError` |
+| `layoutStyle` | 배치 전용 style | — | 위치·여백만. Native `style`은 deprecated |
+
+콜백 prop은 없다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | `medium` 높이·최소 폭 20, `small` 높이·최소 폭 16, `dot` 8×8, 모두 `radius.full`. 자릿수가 늘면 폭만 늘어난다(`99+`). 터치 대상이 아니므로 누르는 것은 부모다 | `src/counter-badge-recipe.ts`, `packages/react/src/styles.css` `.hjm-counter-badge` |
+| 간격 | 좌우 여백 `medium` `spacing.xs` 8, `small` `spacing.xxs` 4. `floating` 테두리 `stroke.strong` 2가 아이콘과 배지를 떼어 보인다 | `src/counter-badge-recipe.ts` |
+| 순서·정렬 | `inline`: 탭 라벨·목록 행의 끝 쪽에 텍스트와 나란히 둔다. `floating`: 컴포넌트가 스스로 위치를 잡지 않으므로 부모를 relative로 두고 배지를 위·끝 모서리(`top: 0`, 끝 0)에 absolute로 놓는다. 공개된 `NotificationBell`(`/notification-bell`)이 IconButton 위에 이 배치를 그대로 쓴다 | `packages/react/src/notification-bell.tsx`, `packages/react-native/src/notification-bell.tsx` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | Web은 `flex-shrink: 0`이라 좁아져도 줄지 않는다 | `packages/react/src/styles.css` `.hjm-counter-badge` |
+
+```text
+inline (행 끝)                      floating (아이콘 모서리)
+┌─────────────────────────────┐     ┌──────┐(3)  ← top 0, 끝 0
+│ 받은 편지함          (12)   │     │  🔔  │
+└─────────────────────────────┘     └──────┘  IconButton 44×44
+```
+
+## 꼭 지킬 것
+
+- 이름을 붙이지 않으면 배지는 보조기술에서 숨겨진다. 부모(아이콘 버튼·행)의 접근성 이름이 개수를
+  이미 말할 때만 `accessibilityLabel`을 생략한다. 빈 문자열을 넘기면 `TypeError`가 난다.
+- `dot`에는 `accessibilityLabel`이 필수다(없으면 `TypeError`).
+- 개수 표기·`+` 처리는 컴포넌트에 맡기고 `"99+"` 같은 문자열을 앱에서 만들지 않는다. 배지가 아닌
+  자리에서 같은 표기가 필요하면 `formatCounterBadgeCount`(`@hjmds/design-contracts`, `/recipes`)를 쓴다.
+- 색은 `tone`과 제품 테마 토큰으로 바꾼다. 배지 색을 직접 칠하지 않는다.
+- 배치는 `layoutStyle`로 한다(Web·Native). Native `style`은 deprecated — 배치는 `layoutStyle`, 외형은 `tone`·`size`·`variant`로 옮긴다(개발 모드 1회 경고, 다음 major 제거).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `dot` | 있음 | 없음 |
+| 배치 | `layoutStyle`(그 밖에 `span` 속성 전달, `style`과 합친다) | `layoutStyle`(`style`은 deprecated) |
+| ref | `HTMLSpanElement` | 없음 |
+
+## 함정
+
+- `dot`이어도 `count`가 0이면 아무것도 그리지 않는다(숫자 계산이 먼저 `null`을 돌려준다).
+  점을 보이려면 `count`를 1 이상으로 넘긴다.

package/docs/usage/components/data-table.md

@@ -0,0 +1,122 @@
+# DataTable
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [DataTable](../../data-table.md), `src/data-table.ts`(`dataTableRecipe`, `getNextDataTableSortState`)
+- 스토리북: `배포/컴포넌트/데이터 표시/데이터 표`
+
+## 언제 쓰나
+
+여러 행의 데이터를 열로 맞춰 훑고, 열 기준으로 정렬하거나 행을 골라 일괄 작업할 때 쓴다(Web).
+정렬·필터 실행, 페이지 나누기는 제품이 소유한다. DataTable은 다음 정렬 상태와 선택 상태만 판정한다.
+선택·정렬이 없는 단순 표는 companion `Table`을 쓴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 한 대상의 속성(이름–값) 나열 | [DescriptionList](description-list.md) |
+| 행 하나가 하나의 항목인 목록, 모바일 화면 | [List](list.md), [ListRow](list-row.md) |
+| 아주 긴 목록의 가상 스크롤 | [VirtualList](virtual-list.md) |
+| 행 확장(상세 펼침) | [Accordion](accordion.md)·[Collapsible](collapsible.md)을 행 안에 합성 |
+| Native 화면 | Native renderer 없음 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `DataTable` | 기본 — 정렬·행 선택·비동기 상태를 갖는 표 | `@hjmds/react`, `/data-table` | 없음 |
+| `Table` | 동반 — 행 객체와 `cell` 렌더러를 받는 단순 표 | `@hjmds/react`, `/display` | 없음 |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { DataTable } from "@hjmds/react/data-table";
+
+<DataTable
+  columns={[
+    { id: "name", header: t("orders.col.name"), sortable: true },
+    { id: "total", header: t("orders.col.total"), align: "end" },
+  ]}
+  rows={orders.map((order) => ({ id: order.id }))}
+  renderCell={(rowId, columnId) => cellFor(rowId, columnId)}
+  labels={{
+    table: t("orders.table"),
+    selectAll: t("orders.selectAll"),
+    selectRow: (rowId) => t("orders.selectRow", { name: nameOf(rowId) }),
+    // 두 번째 인자는 이 열이 아니라 표 전체의 정렬 상태다(함정 참조).
+    sortColumn: (header) => t("orders.sortBy", { header }),
+  }}
+  sortState={sort}
+  onSortChange={setSort}
+  selection={{ mode: "multiple", selectedKeys: selected, onSelectionChange: setSelected }}
+  asyncState={loading ? { status: "loading", message: t("orders.loading") } : { status: "idle" }}
+  footer={pagination /* 제품이 합성한 Pagination 요소 */}
+/>
+```
+
+Native: 없음. Native renderer가 없다.
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `columns` | `{ id, header: string, align?, sortable?, width? }[]` | — (필수, 하나 이상) | `id`는 비어 있지 않고 중복 없음 |
+| `rows` | `{ id, disabled? }[]` | — (필수) | 셀 내용은 `renderCell`이 그린다 |
+| `renderCell` | `(rowId: RowKey, columnId: ColumnKey) => ReactNode` | — (필수) | 행·열 id로 셀을 그린다 |
+| `labels` | `{ table: string; selectAll: string; selectRow: (rowId: string) => string; sortColumn: (header: string, direction: DataTableSortState) => string }` | — (필수) | 모든 문구는 i18n 키 |
+| `sortState` | `{ columnId, direction: "ascending" \| "descending" } \| null` | `null` | 제어 전용(내부 상태 없음) |
+| `onSortChange` | `(next: DataTableSortState<ColumnKey>) => void` | — | 다음 정렬 상태(`null` = 정렬 없음)를 알린다. 재정렬은 제품이 한다 |
+| `sortCycle` | `three-state` · `two-state` | `three-state` | `three-state`는 오름차순 → 내림차순 → 정렬 없음 |
+| `selection` | `{ mode: "none" }` · `{ mode: "single", selectedKey: Key \| null, onSelectionChange: (key: Key \| null) => void, disallowEmptySelection? }` · `{ mode: "multiple", selectedKeys: ReadonlySet<Key>, onSelectionChange: (keys: ReadonlySet<Key>) => void }` | 없음(선택 열 없음) | 제어(`selectedKey(s)`) 대신 `defaultSelectedKey(s)`를 주면 비제어로 내부 상태가 유지된다 |
+| `asyncState` | `{ status: "idle" }` · `{ status: "loading" \| "loadingMore" \| "empty" \| "error", message: string }` | `{ status: "idle" }` | `error`는 `role="alert"`, 나머지는 `role="status"`로 표 위에 나온다 |
+| `density` | `regular` · `compact` | Provider 밀도 | 지정하지 않으면 Provider 밀도를 따른다(`comfortable` → `regular`) |
+| 열 `align` | `start` · `center` · `end` | `start` | 머리 칸과 본문 칸 모두에 적용 |
+| 열 `sortable` | `boolean` | `false` | — |
+| 열 `width` | 양수 px | — | 힌트 |
+| `footer` | `ReactNode` | — | 표 아래 합성 영역 |
+| `layoutStyle` | 배치 전용 style(여백·폭·grid 위치) | — | 루트 wrapper에 붙는다. 시각 키는 받지 않는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 본문 폭을 채운다(표 `inline-size: 100%`). 선택 열 폭 `control.minTouchTarget` 44, 정렬 버튼·체크 상자 터치 영역 44 | `packages/react/src/styles.css` `.hjm-data-table*`, `src/data-table.ts` |
+| 간격 | 루트 세로 간격 `spacing.sm` 12. 셀 여백(`dataTableRecipe.density`): `regular` 세로 `spacing.sm` 12 · 가로 `spacing.md` 16, `compact` 세로 `spacing.xs` 8 · 가로 `spacing.sm` 12. `footer` 간격 `spacing.sm` 12 | `packages/react/src/styles.css` |
+| 순서·정렬 | 위에서 [상태 메시지] → 표 → [footer]. 선택 열은 맨 앞. 숫자·금액 열은 `align: "end"`로 끝 정렬하고 머리 행 정렬도 열 `align`을 따른다. 셀은 위 정렬. `footer`는 한 줄 flex(`space-between`, 넘치면 줄바꿈)이며 요약을 앞에, [Pagination](pagination.md)을 끝에 둔다 | `packages/react/src/data-table.tsx` |
+| 고정·스크롤 | 가로 스크롤 컨테이너는 그리지 않는다. 긴 글자는 줄바꿈한다 | `packages/react/src/styles.css` |
+| 좁은 폭·큰 글자 | 좁은 폭(모바일)에서 열이 많으면 표를 줄이지 말고 [List](list.md)로 바꾼다 | — |
+
+```text
+┌ DataTable ───────────────────────────────────────┐
+│ 불러오는 중…(asyncState 메시지, status/alert)     │
+│ ☐ │ 이름 ▲             │ 상태     │       합계 │ ← 머리 행
+│ ☐ │ …                  │ …        │     12,000 │
+├────────────────────────────────────────────────────┤
+│ 3개 선택됨               [‹ 1 2 3 ›] Pagination   │ ← footer
+└────────────────────────────────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 열 `id`·행 `id`는 비어 있지 않고 중복이 없어야 한다. 열은 하나 이상. 어기면 렌더 중 `TypeError`가 난다.
+- `sortState`는 `sortable: true`인 열만 가리킨다. 아니면 `TypeError`.
+- `labels`의 모든 문구는 i18n 키로 만든다. `selectRow`는 행 `id`를 받으므로 사람이 읽을 이름으로 바꿔 돌려준다.
+- 받은 `onSortChange` 값으로 행을 재정렬하는 일은 제품이 한다(로컬 배열이든 서버 쿼리든).
+- 페이지네이션·더 보기는 `footer`에 [Pagination](pagination.md)·[LoadMore](load-more.md)로 합성한다.
+- 배치는 `layoutStyle`, 시각 override는 `className`으로만 한다. 행 hover·선택 색을 덮지 않는다.
+
+## 함정
+
+- `sortState`는 제어 전용이다. 내부 상태가 없어 `sortState` 없이 `onSortChange`만 주면 머리 칸 화살표가 바뀌지 않는다.
+  선택은 2026-10-06부터 `defaultSelectedKey(s)` 비제어도 내부 상태로 유지된다(이전에는 표시가 바뀌지 않았다).
+- 현재 `labels.sortColumn`의 두 번째 인자는 그 열의 방향이 아니라 표 전체의 `sortState`다(정렬되지 않은 열도 다른 열의
+  상태를 받는다). 열의 현재 방향을 이름에 넣으려면 제품이 `header`로 열을 찾아 `columnId`와 비교한다.
+- `asyncState`의 `message`는 표 위에 `status`/`alert`로 나오지만 표는 그대로 그려진다. 빈 상태 화면이
+  따로 필요하면 [EmptyState](empty-state.md)로 표를 대신 그린다.
+- `Table`의 `onSortChange`는 `null`을 받지 못해 항상 two-state로 돈다. `emptyState`는 필수 prop이다.
+- 미게시(1.12.1 이후) 변경: 1.12.1까지 Web `regular` 셀은 사방 `spacing.sm` 12였다. 열 폭을 그 값으로 맞춘 화면은 가로 16에서 다시 확인한다.

package/docs/usage/components/date-picker.md

@@ -0,0 +1,142 @@
+# DatePicker
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [DatePicker](../../date-picker.md), 격자는 [Calendar](../../calendar.md), recipe `datePickerRecipe`(`src/date-picker.ts`)
+- 스토리북: `배포/컴포넌트/입력/날짜 선택`
+
+## 언제 쓰나
+
+폼·필터 자리에서 날짜 **하나**를 고를 때 쓴다(생년월일, 방문일, 시작일 필터). 평소에는 필드 트리거만
+보이고, 누르면 Web은 필드에 붙은 팝오버, Native는 [Sheet](sheet.md) 안에 같은 달력 격자를 연다.
+날짜를 고르거나 지우면 닫히고 트리거로 포커스가 돌아간다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 시작~끝 기간 | [DateRangePicker](date-range-picker.md) |
+| 달력을 화면에 늘 펼쳐 둠 | [Calendar](calendar.md) |
+| 날짜를 키보드로 타이핑 | 지원하지 않는다(트리거로만 연다) |
+| 날짜가 아닌 목록에서 하나 고름 | [Select](select.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `DatePicker` | 기본 | `@hjmds/react`, `/date-picker`, `/forms` | `@hjmds/react-native`, `/date-picker`, `/inputs` |
+
+## 최소 사용 예
+
+격자 `cells`(7의 배수, 행 우선)·`weekdayLabels`·`todayDate`는 제품이 자기 시계와 로캘로 만든다.
+DatePicker는 날짜를 포맷하지 않으므로 `displayValue`도 제품이 만든다.
+
+```tsx
+// Web
+import { DatePicker } from "@hjmds/react/date-picker";
+
+<DatePicker
+  descriptor={{
+    grid: { cells, weekdayLabels, todayDate },
+    label: t("visit.date"),
+    placeholder: t("visit.datePlaceholder"),
+    displayValue: visitDate === null ? null : formatDate(visitDate),
+    selectedDate: visitDate,
+    onSelectionChange: (date) => setVisitDate(date),
+    focusedMonth: month,
+    onFocusedMonthChange: (next) => setMonth(next),
+  }}
+  monthLabel={formatMonth(month)}
+  previousMonth={{ month: prevMonthOf(month), label: t("calendar.previousMonth") }}
+  nextMonth={{ month: nextMonthOf(month), label: t("calendar.nextMonth") }}
+  composeAccessibleName={({ date, isToday, isSelected }) =>
+    t(isSelected ? "calendar.cell.selected" : isToday ? "calendar.cell.today" : "calendar.cell.default", { date: formatDate(date) })}
+  clearLabel={t("visit.clearDate")}
+  closeLabel={t("calendar.close")}
+/>
+```
+
+```tsx
+// Native
+import { DatePicker } from "@hjmds/react-native/date-picker";
+
+<DatePicker
+  descriptor={/* Web과 같은 descriptor */ descriptor}
+  monthLabel={formatMonth(month)}
+  composeAccessibleName={composeCellName}
+  clearLabel={t("visit.clearDate")}
+  closeLabel={t("calendar.close")}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `size` | `medium` · `large` | `medium` | — |
+| `descriptor.grid` | `{ cells: { date?, outsideFocusedMonth?, disabled?, content? }[], weekdayLabels: [7개 string], todayDate: string }` | — (필수) | `cells`는 7의 배수, 행 우선 |
+| `descriptor.label` · `accessibilityLabel` | `string` | — | 둘 중 하나는 필수 |
+| `descriptor.placeholder` · `displayValue` | `string` · `string \| null` | — (필수) | 트리거 문구. `displayValue`는 제품이 포맷한다 |
+| `descriptor.open` / `defaultOpen` / `onOpenChange` | `boolean` · `(open: boolean, reason: "trigger" \| "keyboard" \| "selection" \| "clear" \| "escape" \| "outside" \| "blur" \| "programmatic") => void` | 비제어 닫힘 | 제어(`open`+`onOpenChange`) 또는 비제어 한 쌍 |
+| `descriptor.selectedDate` / `defaultSelectedDate` / `onSelectionChange` | ISO `YYYY-MM-DD` \| `null` · `(date: string \| null, reason: "activate" \| "clear") => void` | — | 제어 또는 비제어 한 쌍만 쓴다. 지우기는 `null`, `"clear"` |
+| `descriptor.focusedMonth` / `defaultFocusedMonth` / `onFocusedMonthChange` | `YYYY-MM` · `(month: string, reason: "previous" \| "next" \| "jump") => void` | — | 표시 달. 제어 또는 비제어 한 쌍만 쓴다 |
+| `descriptor.disabled` · `readOnly` | `boolean` | `false` | 트리거를 열지 않고 모든 날짜 셀을 비활성으로 그린다. `disabled`는 라벨과 트리거 줄을 `fieldRecipe.disabledOpacity`(0.6)로 흐리고 도움말·오류는 그대로 둔다([Field](field.md)) |
+| `descriptor.invalid` · `error` | `boolean` · 오류 문구(Web `ReactNode`, Native `string`) | — | 둘 중 하나가 있으면 오류 테두리 |
+| `monthLabel` | `string` | — (필수) | 제품이 포맷한 달 제목 |
+| `composeAccessibleName` | `(info: { date, isToday, isSelected, disabled, content? }) => string` | — (필수) | 셀 이름 |
+| `previousMonth` · `nextMonth` | `{ month: string, label: string }` | — | 없으면 이동 버튼이 없다 |
+| `renderCellContent` | `(cell: ResolvedCalendarDateCell) => ReactNode` | — | 날짜 아래 보조 표시 |
+| Web `onNavigateBeyondGrid` | `(detail: { date, intent, overflow: "before" \| "after" }, focusDate: (date: string) => void) => void` | — | 키보드가 격자 밖으로 나갈 때 |
+| Native `safeAreaInsets` | Sheet `safeAreaInsets` | Provider 값 | — |
+| `layoutStyle` | 배치 전용 style | — | 루트 배치. Native `style`은 deprecated |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 트리거 높이: `medium` 44 · `large` 52(`datePickerRecipe.sizes`, 두 플랫폼), 좌우 여백 16 · 20. 2026-10-06까지 렌더 값이 Web 44·56, Native 48·56이었다(1.12.1 이후 미게시). 지우기 버튼 44×44. Web 팝오버 폭 `min(22.5rem, 100vw − 2rem)`(최대 360). 날짜 셀 44, 7열 | `datePickerRecipe.sizes`, `packages/react/src/styles.css` `.hjm-date-picker*`, `packages/react-native/src/date-picker.tsx`, `src/calendar.ts` |
+| 간격 | 라벨·트리거·설명·오류 사이 Web `spacing.xs` 8, Native 6(렌더러 고정값). 트리거 가로 여백 `medium` `spacing.md` 16, `large` `spacing.lg` 20. 팝오버는 트리거 아래 `spacing.xs` 8, 안쪽 여백 `spacing.sm` 12 | 같은 파일 |
+| 순서·정렬 | 폼 안에서 다른 필드와 같은 폭으로 세로로 쌓는다. 위에서 라벨 → 트리거 → 설명 → 오류. 지우기 버튼(값이 있을 때)은 Web은 트리거 안 끝에 겹치고(트리거가 끝 여백 3rem을 비움), Native는 트리거 바깥 끝에 최소 터치 영역으로 붙는다. Web 팝오버는 시작 쪽 정렬 | `packages/react/src/styles.css`, `packages/react-native/src/date-picker.tsx` |
+| 고정·스크롤 | Web 팝오버는 필드에 붙어 층 800에 뜬다. Native 달력은 화면 아래에서 올라오는 [Sheet](sheet.md)이며 하단 안전 영역은 Provider `safeAreaInsets`를 쓴다 | 같은 파일 |
+| 좁은 폭·큰 글자 | Web 팝오버 폭은 뷰포트 − 2rem까지 줄어든다 | `packages/react/src/styles.css` `.hjm-date-picker__popover` |
+
+```text
+Web                                  Native
+라벨                                  라벨
+┌──────────────────────────[×]┐      ┌───────────────────────┐[×]
+│ ▣ 2026-10-06                │      │ ▣ 2026-10-06          │
+└─────────────────────────────┘      └───────────────────────┘
+  ↓ spacing.xs 8                     ┌ Sheet ─────────────────┐
+┌ 팝오버 (최대 360) ───────────┐     │ 제목(라벨)         [닫기]│
+│ ‹   2026년 10월   ›          │     │ ‹   2026년 10월   ›     │
+│ 일 월 화 수 목 금 토          │     │ 7×N 날짜 격자           │
+│ 7×N 날짜 격자(셀 44)         │     │ ─ 안전 영역 ─           │
+└──────────────────────────────┘     └─────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- `label` 또는 `accessibilityLabel` 중 하나, 비어 있지 않은 `placeholder`가 필수다. 어기면 `TypeError`.
+- 모든 문구(라벨·placeholder·`clearLabel`·`closeLabel`·월 이동 라벨·셀 이름)는 i18n 키로 만든다.
+  셀 이름(`composeAccessibleName`)의 어순·문법은 제품이 소유한다.
+- 달을 넘기면 제품이 새 달의 `cells`와 `monthLabel`을 다시 만들어 넘긴다. 달을 바꿔도 선택값은 바뀌지 않는다.
+- 배치는 `layoutStyle`로 한다(Web·Native). 트리거 색·높이를 덮지 않는다. Native `style`은 deprecated — `layoutStyle` 또는 `size`로 옮긴다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 달력이 뜨는 곳 | 필드에 붙은 팝오버(뷰포트 안으로 밀고 공간이 없으면 위로 뒤집음) | `Sheet` |
+| `description`·`error` | `ReactNode` | `string` |
+| 격자 밖 이동 알림 `onNavigateBeyondGrid` | 있음 | 없음 |
+| 하단 안전 영역 `safeAreaInsets` | 없음 | 있음(기본은 Provider 값) |
+| 배치 | `layoutStyle`(그 밖에 `className`) | `layoutStyle`(`style`은 deprecated) |
+
+## 함정
+
+- `previousMonth`/`nextMonth`를 넘겨도 `descriptor.onFocusedMonthChange`가 없으면 두 renderer 모두 이동 버튼이 비활성이다.
+- 예시의 Native 호출처럼 `previousMonth`/`nextMonth`를 빼면 이동 버튼 자체가 없다. 여러 달을 오가야 하면 넘긴다.
+- 1.12.1 이하를 쓰는 화면은 트리거 높이가 recipe(`medium` 44 · `large` 52)와 달랐다(Web 44·56, Native 48·56). 다음 릴리스로 올리면 Native `medium`은 4, `large`는 두 플랫폼 모두 4 낮아지므로 그 높이로 맞춘 고정 높이 계산을 다시 본다.