@hjmds/design-contracts 1.1.0 → 1.2.0

package/docs/calendar.md

@@ -1,154 +1,82 @@
-# Calendar contract
-
-## 문제
-
-한 달의 날짜를 격자로 보여주고, 날짜마다 제품이 붙인 콘텐츠(경기 수, 점 표시 등)를 함께
-드러내며, 오늘·선택된 날짜·선택 불가능한 날짜를 색이 아닌 방식으로 구분한다. Yajalal의
-일정 탐색기(`schedule-explorer`)가 겨냥한 화면이 이 문제다.
-
-## Calendar와 DatePicker의 경계 — 이 저작의 핵심 판정
-
-antd는 `Calendar`(data-display, 상시 표시)와 `DatePicker`(data-entry, 트리거+오버레이)를
-분리한다. 둘 다 "월 격자, 날짜 셀, 오늘, 선택, 비활성 날짜"라는 **같은 조각**을 공유한다.
-그래서:
-
-- 격자(월 표시, 날짜 셀, 오늘 표시, 선택 표시, 비활성 날짜, 방향키 이동)는 **공유 조각**이며
-  이 파일(`calendar.ts`)에 전부 담는다.
-- `Calendar` = 이 격자 그 자체 + 날짜별 콘텐츠. 트리거도 오버레이도 없이 항상 화면에 있다.
-- `DatePicker`(`date-picker.ts`)는 필드 트리거 + 오버레이(Web popover / Native Sheet) 안에
-  **이 격자를 그대로** 담는다. `resolveDatePickerGrid`는 `resolveCalendarGridDescriptor`를
-  그대로 호출할 뿐, 셀 의미를 다시 정의하지 않는다.
-
-`Select`/`Combobox`가 `collection.ts`를 공유하는 것과 같은 구조다 — 다만 여기서는 "제공자"가
-`Calendar`(격자 자체가 컴포넌트인 쪽)이고 `DatePicker`가 그 격자를 오버레이 안에 담는 소비자다.
-
-## Yajalal 실사용처 재확인 — 전제가 이미 바뀌어 있었다
-
-이 작업을 위임받을 때 "일정 탐색기가 월 달력 격자를 자체 구현하고 있다"는 전제가 있었다.
-`modules/app-rn/src/features/schedule-explorer/model.ts`와 `ScheduleExplorerScreen.tsx`를
-직접 읽은 결과, 그 전제는 **더 이상 사실이 아니다**:
-
-- `buildCalendarCells`/`CalendarDayCell`는 여전히 존재하지만, 커밋
-  `0f4887c 비교 프리셋 제목 정정, 일정 탐색기 월 그리드를 날짜 레일로 교체`에서 **화면에
-  격자를 그리는 코드 자체가 삭제**됐다. 지금 남은 역할은 월 범위 쿼리(`monthRange`)와
-  §6 날짜 레일(`createScheduleDateRail`)의 입력을 만드는 내부 데이터 계산뿐이다.
-- 실제로 렌더되는 것은 `MonthHeader`(월 이름 + 이전/다음 버튼, 격자 없음)와
-  `ScheduleDateRail`(7일 문맥의 가로 스크롤 레일, §6 계약)이다. 레일은 이 저작의 범위 밖으로
-  지정됐고, 레일 자체도 날짜 그리드가 아니라 완전히 다른 형태(승/패/응원/휴식 마크가 있는
-  1차원 트랙)다.
-- 앱 전체를 훑어도(`날짜 선택`/`DatePicker` 검색) 값 하나를 고르는 압축 트리거형 UI는
-  어디에도 없다. `calendar` 아이콘이 쓰이는 다른 화면(FA, 선수 기록, 데일리 픽, 온보딩)은
-  모두 장식 아이콘일 뿐 날짜 격자가 아니다.
-
-**결론.** 현재 Yajalal에는 Calendar나 DatePicker의 살아있는 vertical slice 후보가 없다.
-그렇다고 Notification/Dropdown처럼 "만들지 않는다"로 판정하지는 않았다 — 그 두 문서의
-판정 근거는 "문제 자체가 이미 다른 컴포넌트로 완결됐다"였고, 날짜 격자를 보여주거나
-고르는 문제는 Select/Menu/Toast 어느 것으로도 흡수되지 않는 별개의 문제이기 때문이다(로드맵
-Batch 3에도 명시적으로 planned로 예약돼 있다). 다만 `planned → beta` 승격에 필요한 실제
-vertical slice는 **아직 없다** — 이 계약은 그 전 단계("계약+recipe 준비됨")만 완성한다.
-후보가 다시 필요해지면 일정 탐색기가 아니라 (a) 언젠가 월 그리드가 되돌아오는 화면이거나
-(b) 생년월일·계약일처럼 값 하나를 고르는 새 폼 필드가 될 것이다.
-
-## 일반화한 계약
-
-### Collection 기본 계약을 적용하지 않는다
-
-격자는 목록이 아니라 2차원이다. `stable id / label / textValue / none|single|multiple
-selection mode / idle|loading|loadingMore|empty|error` 중 어느 것도 날짜 셀에 억지로
-채우지 않았다:
-
-- 날짜 자체(`"YYYY-MM-DD"`)가 이미 stable id다. 별도 `id`/`label`/`textValue` 삼중주를
-  만들면 같은 값을 두 번 말하는 유령 필드가 된다.
-- 날짜 셀은 검색·타이핑 대상이 아니다(Steps가 같은 이유로 `textValue`를 배제한 것과 같다).
-- 격자는 서버에서 비동기로 채워지는 목록이 아니다. 어느 달의 날짜가 며칠까지 있는지는
-  제품이 항상 동기로 안다 — `idle|loading|loadingMore|empty|error`는 셀이 아니라 그 안의
-  `content`(경기 데이터)에 대한 것이고, 그건 제품이 격자 바깥에서 스스로 감싼다(Yajalal의
-  `AppStateRegion`처럼). Statistic이 값 포맷을 소유하지 않듯, Calendar도 그 로딩 상태를
-  소유하지 않는다.
-
-### 날짜는 항상 문자열이다
-
-`Date` 객체는 계약 어디에도 없다. `cells[].date`, `todayDate`, `selectedDate`,
-`focusedMonth`는 전부 `"YYYY-MM-DD"` 또는 `"YYYY-MM"` 문자열이다 — Yajalal이 이미
-`gameDate.slice(0, 10)`을 키로 쓰는 이유와 같다(시간대에 따라 같은 순간이 다른 날짜가
-되는 문제를 원천 차단). `validateCalendarGridDescriptor`는 형태(정규식)만 검사하고
-달력 산수(윤년, 월별 일수, 요일 계산)는 절대 하지 않는다 — 제품이 이미 그 계산을
-가지고 있고(Yajalal의 `buildCalendarCells`), 시간대 의존적인 `Date` 연산을 이 패키지에
-들이면 "런타임 의존성 금지"와 "제품이 포맷한 문자열을 받는다" 원칙을 동시에 어긴다.
-
-### 격자 모양은 제품이 만들고, 의미는 HJM이 유도한다
-
-`CalendarGridDescriptor`는 이미 계산된 7열 배열(`cells`, row-major)을 받는다. 어떤 날짜가
-이 달에 속하는지, 앞뒤로 몇 칸이 비는지는 제품이 이미 안다. HJM은:
-
-- 모양을 검증한다(7의 배수, 요일 라벨 7개, 날짜 형식, 중복 없음).
-- 셀마다 `row`/`column`/`isToday`/`isSelected`/`selectable`을 유도한다(Steps가 `currentStepId`
-  하나에서 `pending/current/complete`를 유도하는 것과 같은 원칙 — 제품이 상태를 배열로 다시
-  넘기지 않는다).
-- `date`가 없는 셀은 순수한 채움칸이다(이번 달 1일 전 요일들처럼). 채움칸은 절대 포커스,
-  선택, 접근성 이름을 갖지 않는다.
-
-### 낭독은 제품이 조립한다
-
-"8월 19일 수요일, 경기 2개, 선택됨" 같은 문장은 `composeAccessibleName`이 만든다 — Steps의
-`composeAccessibleName`과 같은 이유(어순·조사는 언어마다 다르고, `content`의 의미는 제품만
-안다). 빈 문자열을 반환하면 resolver가 던진다.
-
-### 선택 불가능한 날짜는 포커스를 잃지 않는다
-
-`getCollectionNavigationTarget`(Menu/Select/Combobox)은 disabled 항목을 건너뛴다. Calendar는
-**건너뛰지 않는다** — WAI-ARIA Date Picker Dialog 패턴처럼, 화살표 아래는 항상 정확히 한 주
-아래로 이동해야 예측 가능하다. 비활성 날짜에 포커스가 앉는 것과 그 날짜를 **활성화**할 수
-있는 것은 별개다: `resolveCalendarGridDescriptor`가 내주는 `selectable: false`가 그 경계를
-표시하고, activate(Enter/Space/tap) 자체를 막는 책임은 renderer에 있다.
-
-### 격자 밖으로 나가면 넘긴다, 감싸지 않는다
-
-한 페이지(보이는 달)의 경계를 넘는 화살표 이동은 순환하지 않고 `{ overflow: "before" |
-"after" }`를 돌려준다 — HJM은 인접 달의 모양을 모르기 때문이다. 제품이 이 신호를 받아
-달을 넘기고(`focusedMonth` 변경) 해당 날짜에 포커스를 옮긴다. **월 이동은 별도 통제
-축(`focusedMonth`/`onFocusedMonthChange`)이며, 선택(`selectedDate`)과 완전히 독립이다** —
-달을 넘겨도 선택은 지워지지 않는다.
-
-## HJM 기본값
-
-- `today`는 지속되는 테두리(`border.focus`)로, `selected`는 채워진 배경
-  (`action.brand.background`)으로 표시한다 — 겹쳐도(오늘이면서 선택된 날) 둘 다 읽힌다.
-- 비활성 날짜와 이번 달 밖 날짜는 각각 `disabledOpacity`/`outsideFocusedMonthOpacity`로
-  구분한다(같은 회색조가 아니라 서로 다른 강도).
-- 셀 지름은 `control.minTouchTarget`(medium) 이상을 보장한다.
-
-## 플랫폼 번역
-
-- Web: `grid`/`row`/`gridcell` role과 roving tabindex 화살표 이동을 쓴다(같은 결과: 원하는
-  날짜에 도달). 채움칸은 `aria-hidden`.
-- Native: 복합 grid role의 동등물이 없다 — Steps/Breadcrumb가 이미 같은 결론을 냈다. 각
-  날짜는 독립적으로 포커스·탭 가능한 요소이고, 월 이동은 두 플랫폼 모두 있는 이전/다음
-  버튼으로만 이뤄진다(화살표 스와이프 같은 제스처 기반 이동은 이 계약에 없다).
-- 두 플랫폼 모두 "오늘·선택·비활성"을 같은 세 가지 비-색 신호(테두리/배경/투명도)로
-  전달한다. 픽셀 parity가 아니라 같은 action/result/announcement라는 `beta →
-  stable(adaptive)` gate의 기준을 그대로 따랐다 — Calendar 자체는 `adaptive`가 아니라
-  `shared`로 분류하지만(오버레이 선택이 없으므로), 접근성 경로가 플랫폼마다 다르다는 점은
-  같다.
-
-## 공개한 축 / 배제한 축
-
-| 축 | 상태 |
-| --- | --- |
-| `today` / `selected` / `disabled` / `outsideFocusedMonth` | 공개 |
-| 월 이동(`focusedMonth`, 선택과 독립) | 공개 |
-| 방향키 격자 이동(일/주 단위, Home/End) | 공개 — Web roving tabindex |
-| range 선택(시작~끝 날짜 구간) | **배제** — 측정된 요구가 없다. Yajalal FA 조회, 경기 일정
-  어디에도 기간 선택 UI가 없다. 필요해지면 `CalendarSelection`을 확장하지 않고 별도
-  `CalendarRangeSelection` 타입을 새로 여는 쪽을 권한다 — 단일 선택 소비자의 타입을
-  좁히지 않기 위해서다. |
-| 요일 시작(일요일/월요일) 로직 | **배제** — 제품이 `weekdayLabels`와 `cells` 순서로 이미
-  결정해서 넘긴다. HJM이 로케일별 첫 요일을 판단하지 않는다. |
-| PageUp/PageDown 월·년 이동 단축키 | **배제** — 화살표 overflow 신호 + 명시적 이전/다음
-  버튼이 이미 월 이동을 커버한다. 측정된 단축키 요구가 나오면 추가한다. |
-| 다중 월 동시 표시(antd `Calendar`의 연간 뷰 등) | **배제** — 한 번에 한 달만 다룬다. |
-
-## 검증 화면
-
-아직 없다. 위 「Yajalal 실사용처 재확인」에서 밝혔듯 현재 살아있는 vertical slice 후보가
-없다 — `planned → beta` 승격은 실제 제품 화면이 나온 뒤 리드가 진행한다.
+# Calendar
+
+2026-09-16 · React / React Native beta. 날짜별 기록을 탐색하는 작동 예제를 제공한다.
+제품의 실제 채택·기기 검증·npm 게시를 뜻하지 않는다.
+
+## 설계와 참조
+
+- [React Aria Calendar](https://react-aria.adobe.com/Calendar)의 선택과 현재 표시 월을
+  별도로 통제하는 구성을 비교했다. HJM은 제품이 계산한 ISO 날짜 배열을 받는다.
+  달력 체계·로케일·시간대 계산을 renderer에 추가하는 대안은 기존 문자열 계약을 깨므로 채택하지 않았다.
+- [WAI 날짜 선택 예제](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/)의
+  격자·roving focus·요일 탐색을 참고했다. HJM은 inline Calendar와 DatePicker의 overlay를 구분한다.
+- 토스 UI의 읽기 쉬운 제목, 평평한 콘텐츠, 하나의 명확한 선택 강조를 HJM 토큰으로 표현한다.
+  외부 라이브러리의 코드·자산·폰트를 복사하지 않는다.
+
+과거 Yajalal 조사에서는 월 격자가 날짜 레일로 바뀌어 살아 있는 Calendar 소비 화면이 없었다.
+이번 구현의 근거는 React/RN 컴포넌트를 채우라는 명시 요청이며, 검증 화면은 Showcase의
+`Patterns/Calendar` 기록 탐색이다. 이를 Yajalal 채택으로 기록하지 않는다.
+
+## 경계
+
+Calendar는 항상 표시되는 한 달의 격자다. DatePicker는 날짜 필드와 Web dialog / Native Sheet에
+같은 Calendar를 담는다. 날짜 선택·접근성·큰 글자 수정이 양쪽에 동시에 반영되도록 렌더링을
+공유한다. DatePicker의 선택 후 닫기·trigger copy·clear·읽기 전용은 바깥 필드가 맡는다.
+
+- `grid.cells`: 제품이 만든 7열 row-major 배열. 길이는 양의 7의 배수다.
+- `date`: ISO `YYYY-MM-DD` stable key. 빈 셀은 `{}`이며 focus나 접근성 이름을 갖지 않는다.
+- `weekdayLabels`, `todayDate`, `monthLabel`: 제품이 정한 로케일·시계의 결과를 받는다.
+- `selectedDate` / `defaultSelectedDate` / `onSelectionChange`: 단일 선택. 월 이동과 독립이다.
+- `focusedMonth` / `defaultFocusedMonth` / `onFocusedMonthChange`: 제품의 표시 월 요청 계약.
+  실제 `grid`와 `monthLabel` 갱신은 제품이 수행한다. handler가 없으면 월 버튼은 비활성이다.
+- `composeAccessibleName`: 날짜·오늘·비활성·제품 콘텐츠를 현지화한다. 선택 상태는 별도
+  `aria-selected` / native accessibilityState로도 제공한다.
+- `renderCellContent`: 점·짧은 개수 등 장식 콘텐츠. 독립된 버튼/입력을 넣지 않는다.
+  내용 의미는 `composeAccessibleName`에 포함한다. 중복 낭독 방지를 위해 slot은 접근성에서 숨긴다.
+
+## 공개 API
+
+```tsx
+import { Calendar } from "@hjmds/react/calendar";
+// Native: @hjmds/react-native/calendar
+
+<Calendar
+  descriptor={{ grid, monthLabel, focusedMonth: month, onFocusedMonthChange: setMonth,
+    selectedDate: date, onSelectionChange: setDate }}
+  previousMonth={{ month: previousMonthKey, label: "이전 달" }}
+  nextMonth={{ month: nextMonthKey, label: "다음 달" }}
+  composeAccessibleName={formatCellName}
+/>
+```
+
+두 renderer는 `size="medium" | "large"`, `renderCellContent`,
+`ref.current.focusDate(date)`를 지원한다. focus 요청 날짜가 다음 렌더에서 도착하면 그때 적용한다.
+Web의 `autoFocus`는 기본 false이며 DatePicker가 열린 격자에만 true로 설정한다.
+
+### Web 경계 이동
+
+방향키는 좌우 하루/상하 한 주, RTL 좌우 반전, Home/End는 현재 행의 첫/마지막 날짜다.
+비활성 날짜에도 초점은 이동하지만 클릭·Enter/Space로 선택할 수 없다. 월 페이지 밖으로 이동하면
+`onNavigateBeyondGrid({ date, intent, overflow }, focusDate)`를 호출한다.
+
+날짜 계산을 소유하는 제품이 다음 날짜/월을 계산하고 `setMonth(nextMonth); focusDate(nextDate)`를
+호출한다. 이 handler가 없으면 격자 경계에 머무른다. 연속 키보드 월 탐색이 필요한 제품은 반드시
+연결한다. DatePicker도 같은 callback을 받는다. Native는 명시적 이전/다음 버튼으로 월을 이동한다.
+
+## 시각·접근성
+
+- 오늘은 border, 선택은 fill, 비활성은 opacity와 접근성 상태로 구분한다.
+- 7열의 최소 touch target을 유지한다. 폭이 부족하면 격자만 가로 스크롤하고 본문은 넘치지 않는다.
+- 셀 높이를 고정하지 않아 2배 글자나 짧은 제품 콘텐츠가 잘리지 않는다.
+- Web: grid / row / columnheader / gridcell, 하나의 날짜 tab stop, visible focus.
+- Native: 각 날짜는 독립 접근 가능한 button. 실제 플랫폼과 RN Web의 focus 경로를 구분한다.
+- 단일 날짜·한 페이지 계약이다. range, 연간 view, 비그레고리력 계산 엔진은 이 컴포넌트에 없다.
+  제품이 준비한 날짜 배열의 의미를 보존하며 HJM은 날짜 형식·중복·격자 모양을 검증한다.
+
+## 검증
+
+Web 테스트는 비활성 날짜 focus/활성화 분리, 하루/주/Home/End, 경계에서 새 페이지의 지정 날짜로
+focus 이동, controlled 선택 보존, 320px·2배 글자·RTL 최소 target과 본문 overflow를 검사한다.
+Native 테스트는 개별 날짜의 접근성·비활성·선택, 명시적 월 이동, 크기와 스크롤 경계를 검사한다.
+DatePicker의 기존 선택·닫기·방향키 회귀와 controlled-open 읽기 전용/disabled 활성화 방지도 검사한다.
+전체 패키지·Showcase 검증 및 브라우저 확인은 `react-native-completion.md` 실행 기록에 남긴다.

package/docs/carousel.md

@@ -8,8 +8,9 @@
 
 사용자가 한 번에 하나만 보이는 카드 묶음을 순서대로 넘겨 본다 — 야잘알 홈의 "내 구단
 경기 스트립"(가로 스크롤 페이저)이 실사용처다. Ant Design `Carousel`과 같은 사용자
-문제를 풀지만, HJM은 `direct` crosswalk를 따르면서도 antd의 기본 동작 두 가지(무한
-순환, 자동 재생 기본값)를 의도적으로 걷어낸다.
+문제를 풀지만, HJM은 `direct` crosswalk를 따르면서도 antd의 기본 무한
+순환을 제공하지 않는다. 자동재생은 두 라이브러리 모두 기본 false다. 2026-09-16
+[공식 API](https://ant.design/components/carousel/) 대조로 기존 문서의 기본값 오류를 수정했다.
 
 ## 일반화한 계약
 
@@ -128,3 +129,27 @@ mount policy 참고) — 새로 만든 개념이 아니라 이미 검증된 패
 
 아직 없음. `planned → beta` 승격은 실제 제품 vertical slice 이후 리드가 진행한다(로드맵
 maturity gate). 유력 후보: 야잘알 홈의 내 구단 경기 스트립.
+
+
+## React / React Native renderer (2026-09-16)
+
+두 패키지의 `./carousel` 경로에서 `Carousel`을 제공한다. 공통 props는 label, slides,
+renderSlide, composeAccessibleName, labels(previous/next/pause/resume/navigation),
+currentKey 또는 defaultCurrentKey, onCurrentKeyChange와 선택적 autoplay다.
+Web은 ref/HTML attributes, Native는 View style을 받는다. 빈 목록이나 존재하지 않는
+currentKey는 계약 오류다. 동적으로 현재 항목을 제거하는 제품은 새 key도 함께 정한다.
+
+[WAI APG](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/)에 따라 Web 재생 제어를
+카드보다 먼저 배치하고 focus 진입 후 자동 재개하지 않는다. hover/숨겨진 페이지에서는
+일시 정지하고 마지막 카드에서 종료한다. 명시적 재시작은 첫 카드부터 시작한다.
+이전/다음/각 위치 버튼은 Tab 순서에 남고, 카드 내부 입력의 화살표 키는 가로채지 않는다.
+
+Native는 현재 위치의 별도 adjustable 제어를 둬 카드 안의 버튼을 접근성 그룹에
+흡수하지 않는다. 수평 의도가 분명한 swipe만 한 장 이동으로 처리하며 수직 scroll은
+제품에 남긴다. VoiceOver/TalkBack이 켜지거나 OS 확인 전에는 자동재생하지 않는다.
+앱이 background인 동안 멈추고, 터치·수동 이동은 명시적 재생 전까지 멈춘다.
+Native 위치 제어는 숫자 버튼으로 표현해 현재 위치를 눈으로도 읽게 한다.
+
+자동재생은 선택 기능이며 기본 화면 예제는 수동이다. Web browser 및 Native renderer
+테스트는 숨김·key 유지·경계·controlled 요청·RTL·자동재생 중지와 swipe/접근성 action을
+검증한다. Native 기기 제스처·스크린 리더 실측은 별도이며 이 증거로 stable 승격하지 않는다.

package/docs/cascader.md

@@ -91,3 +91,20 @@ alias 판정과 같은 자리가 된다.
    폭이 넓은 실제 계층 데이터가 나와, "렌더러 선택"이라던 전제가 깨진다.
 3. `changeOnSelect`형 중간 노드 커밋이 `commitAt` 하나로 표현하기엔 부족한 추가 규칙
    (예: 중간 노드 커밋 시 하위 요약값 표시)이 실제 화면에서 요구된다.
+
+## 2026-09-18 후속: 축을 추가하지 않고 조합으로 닫았다
+
+이 판정은 `valueMode`/`commitAt` 두 축을 **TreeSelect 컴포넌트**에 추가하는 것을 전제로
+썼다. 그 사이 TreeSelect 자체가 별도 컴포넌트가 아니라 조합(Popover 표면 + Tree
+collection + tri-state 판정 모듈)으로 확정됐고, Tree renderer가 들어오면서 두 축이
+가리키던 동작이 이미 존재한다.
+
+- `valueMode: "path"` — Tree의 resolve 결과가 `parentId` 사슬을 들고 있으므로 경로는
+  파생이다. 저장 규칙은 여전히 제품 소유이고 계약이 값 모양을 새로 규정하지 않는다.
+- `commitAt: "any"` — 중간 노드를 그냥 고르면 된다. Tree의 단일 선택이 리프를 강제하지
+  않으므로 막아 둔 자리를 여는 새 축이 필요 없다.
+
+그래서 catalog의 Cascader 행은 `prerequisite`에서 `composed`(Popover·Tree)로 옮겼고,
+작동 예제는 Showcase `Patterns/Tree`의 Cascader 화면이다. "만들지 않는다"는 판정 자체는
+그대로다 — 바뀐 것은 흡수하는 쪽이 컴포넌트가 아니라 조합이라는 점뿐이다.
+

package/docs/chart.md

@@ -0,0 +1,33 @@
+# Chart — 렌더러를 만들지 않는다
+
+**결정.** 막대·선·원 차트 렌더러를 HJM에 두지 않는다. 대신 **색·축·격자·범례 토큰**만
+`dataviz` 계약으로 고정하고, 그리는 일은 제품이 고른 라이브러리(Recharts·victory-native·
+d3 등)에 맡긴다.
+
+**왜.** 차트를 하나 그리기 시작하면 축 눈금, 툴팁, 애니메이션, 반응형 재계산, 키보드
+탐색, 데이터 테이블 대체 표현까지 전부 따라온다. 그 전부를 이 패키지가 두 표면에서
+유지하는 비용이 제품이 라이브러리 하나를 붙이는 비용보다 크다. 게다가 반쯤 만든 차트는
+제품이 **우리 차트와 자기 차트 두 벌**을 갖게 만든다.
+
+**실제로 어긋난 것은 색이었다.** Spint 열지도와 Yajalal 통계가 각자 색을 골랐고, 같은
+포트폴리오의 두 화면이 다른 파랑을 썼다. 그건 렌더러가 없어서가 아니라 **팔레트가 없어서**
+생긴 문제다. 그래서 그 자리만 계약으로 막는다.
+
+## 계약이 정하는 것
+
+- `datavizSeriesPalette` — light/dark 각 8색의 계열 팔레트. 상태색(info/success/warning/
+  attention)은 **쓰지 않는다**: 뜻을 가진 색이라 "3번 계열"에 쓰면 사용자가 경고로 읽는다.
+- `resolveDatavizSeriesColor(theme, index)` — 8을 넘으면 **순환**한다. 색을 자동 생성하지
+  않는다. 생성색은 대비를 보장할 수 없고, 9번째 계열이 필요한 화면은 대개 표가 맞다.
+- `datavizChromeTokens` — 축선·축라벨·격자·범례·툴팁은 본문 토큰(`border`·`textMuted`·
+  `textBody`·`surface`)을 그대로 쓴다. 차트 전용 회색을 따로 두면 같은 화면의 표·캡션과
+  어긋난다.
+- `datavizRedundantEncodings` / `validateDatavizEncoding` — 색만으로 계열을 구분하지
+  않는다(WCAG 1.4.1). 직접 라벨·패턴·마커 모양 중 **하나 이상**을 색과 함께 쓴다. 색각
+  이상과 흑백 인쇄에서 차트가 남는 조건이다.
+
+## 계약이 정하지 않는 것
+
+축 스케일, 보간, 툴팁 동작, 데이터 정렬, 빈 상태 문구. 전부 제품과 라이브러리의 몫이다.
+이 결정을 뒤집으려면 "제품 두 곳 이상이 같은 차트 종류를 필요로 하고, 라이브러리 위임으로
+해결되지 않는 접근성 문제가 실측으로 확인됐다"가 먼저 있어야 한다.

package/docs/clipboard.md

@@ -0,0 +1,13 @@
+# ClipboardButton
+
+복사는 제품이 반복해서 다시 만들던 세 가지다: 비동기 clipboard 호출, 잠깐 보이는 "복사됨"
+상태, 그리고 **그 상태를 읽어 주는 것**.
+
+마지막 하나가 늘 빠졌다 — 라벨이 눈에만 바뀌면 보조기기 사용자는 아무 일도 일어나지
+않은 것과 같다. 그래서 `role="status"`로 함께 알린다.
+
+- **거부된 클립보드를 성공으로 속이지 않는다.** 권한이 없으면 `onCopyError`로 알리고
+  라벨은 그대로 둔다.
+- **값이 바뀌면 "복사됨"을 지운다.** 그 표시는 이전 문자열을 가리키던 것이라, 남겨 두면
+  사실이 아닌 말을 화면에 두는 셈이다.
+- 두 상태의 문구는 제품이 준다.

package/docs/collapsible.md

@@ -0,0 +1,19 @@
+# Collapsible contract
+
+**문제.** 접었다 펴는 한 덩어리. "더 보기", 필터 패널, 접히는 본문처럼 **이웃이 없는
+disclosure**다.
+
+**Accordion과 다른 것은 개수가 아니라 관계다.** Accordion의 항목들은 서로를 안다 —
+하나를 열면 다른 것이 닫히는 정책, 항목 사이 구분선, 그룹 전체의 키보드 이동이 있다.
+Collapsible에는 그 셋이 전부 없다. `items.length === 1`인 Accordion으로 대신하면 그룹
+chrome이 따라오고 그걸 다시 CSS로 지우게 된다. 그래서 별도로 둔다 — 상태 어휘와 모션은
+공유한다.
+
+**닫힌 내용은 트리에서 뺀다.** 시각적으로만 숨기면 화면 리더와 브라우저 찾기가 그대로
+도달한다. "접혀 있다"는 표시와 실제가 어긋나므로 renderer는 unmount한다. 애니메이션을
+위해 남겨 두고 싶다면 그건 제품이 아니라 이 계약을 바꿀 일이다.
+
+**trigger는 `aria-expanded`와 `aria-controls`를 함께 낸다.** 상태만 알리고 무엇이 열렸는지
+가리키지 않으면 사용자는 방금 나타난 것을 찾아야 한다.
+
+**Web·Native 공통.** 네이티브도 `button` role에 expanded 상태를 그대로 쓴다.

package/docs/command-palette.md

@@ -114,3 +114,22 @@ heading을 가지므로) — CommandPalette는 다르다: `role="dialog"` 표면
 ## 검증 화면
 
 아직 없음. `planned → beta` 승격은 실제 제품 vertical slice 이후 리드가 진행한다.
+
+## Web renderer (2026-09-18)
+
+`@hjmds/react/command-palette`의 `CommandPalette`가 이 계약을 실행한다. catalog는
+Web `beta`, Native `unsupported`다.
+
+- **모달 takeover다.** Dialog·Sheet·SidePanel과 같은 모달 스택·스크롤 락·배경 격리를
+  공유한다(`packages/react/src/modal.tsx`). 별도 `modal` 축은 없다.
+- **실행은 언제나 닫는다.** `activation`은 정책이 거부할 수 없는 dismiss 사유이고,
+  `onActivateAfterDismiss`는 팔레트가 사라진 뒤에 실행된다 — 다음 표면을 여는 명령이
+  겹쳐 뜨지 않도록.
+- **결과 목록은 Combobox 어휘 그대로다.** 검색 input이 `role="combobox"`,
+  결과가 `listbox`/`option`, 활성 행은 `aria-activedescendant`로 가리킨다.
+  방향키는 계약의 `getCollectionNavigationTarget`(disabled 건너뜀)을 쓴다.
+- **query가 바뀌면 활성 행이 첫 결과로 되돌아간다.** Enter의 대상이 언제나 분명해야 한다.
+- **전역 단축키는 제품 소유다.** 이 renderer는 여는 키를 정하지 않는다.
+- 로컬 검증: `test/command-palette.browser.test.tsx` 5개(이름·초점·배경 inert, 활성 행과
+  disabled 건너뜀·재필터, 실행 시 강제 종료와 사유, 종료 후 후속 명령 순서, Escape·바깥
+  pointer 종료)와 `Patterns/CommandPalette`.

package/docs/confirm-popover.md

@@ -1,4 +1,4 @@
-# ConfirmPopover — 별도 컴포넌트를 만들지 않는다
+# ConfirmPopover — Popover 위의 확인 조합
 
 ## 문제로 제기된 것
 
@@ -91,3 +91,13 @@ Component Explorer에서 이 문서로 연결한다.
    반복되어, 그 조합 자체(콜백 규약, 포커스 초기값)를 매번 다시 구현하는 비용이
    측정 가능하게 커진다 — 그때는 새 상태 축이 아니라 **Popover 위의 얇은
    합성 헬퍼**(recipe 없이 콜백 배선만 감싸는 유틸리티) 형태를 먼저 검토한다.
+
+## 2026-09-16 작동 예제
+
+React/RN 확장 요청에 따라 `Patterns/Popover/ReversibleConfirmation`을 제공한다.
+`@hjmds/react/popover`의 children 함수에서 `close()`와 HJM Button을 조합한다.
+취소 버튼을 초기 초점으로 지정하고, 보관 후 사라지는 트리거 대신 보관 취소 버튼에
+초점을 보낸다. 보관 취소는 실제 로컬 상태를 복원한다. 외부 서버 요청이나 배포 증거는 아니다.
+
+별도 `ConfirmPopover` renderer/export는 추가하지 않는다. catalog의 composed 항목과
+Popover/AlertDialog 선택 경계는 유지하며, 이 예제를 완성된 조합으로 추적한다.

package/docs/context-menu.md

@@ -0,0 +1,23 @@
+# ContextMenu contract
+
+**문제.** 포인터 위치에서 열리는 메뉴 — 우클릭, 그리고 터치의 길게 누르기.
+
+**Menu와 목록은 같고 앵커가 다르다.** Menu는 트리거 버튼에 붙고 ContextMenu는 이벤트가
+일어난 **좌표**에 붙는다. 항목 타입은 `MenuItemDescriptor` 그대로다. 두 번째 항목 어휘를
+만들면 tone·shortcut·disabled 규칙이 두 곳에서 갈라진다.
+
+**트리거가 없다는 점이 접근성까지 번진다.** 버튼이 없으므로 키보드 사용자에게 여는 방법을
+따로 줘야 한다(Shift+F10, 또는 메뉴 키). 그것을 빼면 마우스 없이는 존재하지 않는 기능이
+된다 — 이 계약이 여는 이유(`openReason`)를 값으로 갖는 이유다.
+
+**키보드로 열 때의 앵커는 초점 요소의 상자다.** 좌표가 없다고 (0,0)에 띄우면 메뉴가 방금
+초점이 있던 항목과 무관해 보인다. `resolveContextMenuAnchor`가 이 판단을 갖고 있고,
+좌표도 초점 상자도 없으면 렌더링 대신 던진다.
+
+**닫으면 열었던 자리로 초점을 돌린다.** 좌표에서 열렸다고 초점까지 떠 있으면 다음 Tab이
+문서 처음으로 간다.
+
+**브라우저 기본 메뉴를 제품이 소유한 표면에서만 대체한다.** 텍스트 선택·링크·이미지 위의
+기본 메뉴를 빼앗으면 복사·새 탭 열기를 사용자에게서 뺏는 것이다.
+
+**Web 전용.** 네이티브의 길게 누르기 메뉴는 OS가 제공하는 표면이라 같은 계약이 아니다.

package/docs/data-table.md

@@ -77,3 +77,25 @@
 
 **검증 화면.** 아직 실제 제품 vertical slice가 없다 — catalog는 `planned`으로
 남고, `beta` 승격은 로드맵 gate(실제 화면 검증)를 통과한 뒤 리드가 진행한다.
+
+## Web renderer (2026-09-18)
+
+`@hjmds/react/data-table`의 `DataTable`이 이 계약을 실행한다. catalog는 Web `beta`,
+Native `unsupported`다.
+
+- **기존 `Table`과 겹치지 않는다.** `@hjmds/react`의 `Table`(advanced-display)은 열·행을
+  그려 주는 표시용이고 선택·tri-state·async 상태·정렬 상태 순환이 없다. DataTable은 그
+  상호작용 계약을 실행하는 쪽이다. 단순 표는 계속 `Table`을 쓴다 — 같은 화면에 둘을 겹쳐
+  쓰지 않는다.
+- **정렬 버튼은 header 안에 있다.** `th` 자체를 버튼으로 만들지 않고, 방향은
+  `aria-sort`에 그대로 흘린다. 다음 상태는 `getNextDataTableSortState`가 정하고 실제 정렬은
+  제품이 한다.
+- **선택은 공용 collection 모델 그대로다.** multiple은 checkbox, single은 radio 의미를
+  쓰고, 머리글의 tri-state는 `resolveDataTableSelectAllState`가 파생한다. disabled 행은
+  분모·분자 양쪽에서 빠진다.
+- **셀 하나에 focusable 컨트롤은 최대 하나다.** roving tabindex grid 탐색을 도입하지 않고
+  기본 tab 순서를 쓴다.
+- **페이지네이션은 표 아래에 조합한다.** `footer` slot은 제품이 채우고 표가 소유하지 않는다.
+- 로컬 검증: `test/data-table.browser.test.tsx` 5개(header 안 정렬 버튼과 aria-sort 3단계,
+  tri-state 선택과 disabled 제외, 단일 선택 radio 의미, 셀당 컨트롤 하나와 기본 tab 순서,
+  async 상태 발표와 footer 조합)와 `Patterns/CommandPalette`의 표 화면.

package/docs/date-range.md

@@ -0,0 +1,31 @@
+# DateRange contract
+
+**문제.** 날짜 **구간** 선택 — 통계 기간, 예약, 검색 필터.
+
+**Calendar에 `mode` 축을 넣지 않은 이유.** 단일 선택의 값은 `string | null`이고 구간의
+값은 `{ start, end }`다. 한 컴포넌트가 두 값 모양을 가지면 모든 소비자가 매번 좁히기를
+해야 하고, "range 모드인데 `selectedDate`를 준" 조합이 타입에 남는다. 격자는 그대로
+재사용하고 **구간 판정만** 이 모듈이 갖는다.
+
+**다음 클릭이 무엇을 하는가.**
+
+| 현재 | 클릭 | 결과 |
+| --- | --- | --- |
+| 비어 있음 | 아무 날 | 시작 |
+| 고르는 중(시작만) | 시작 이후 | 끝 확정 |
+| 고르는 중(시작만) | 시작 이전 | 두 값을 **바꿔 담는다** |
+| 완성됨 | 아무 날 | 새로 시작 |
+
+완성된 구간을 다시 눌렀을 때 가까운 끝을 옮기는 동작은 넣지 않았다 — "어느 쪽 끝인가"를
+추측해야 하고, 추측이 틀리면 사용자가 왜 그렇게 됐는지 알 수 없다. 다시 시작하는 쪽이
+예측 가능하다. 시작보다 앞선 날짜를 거절하지 않고 바꿔 담는 것도 같은 이유다.
+
+**"고르는 중"은 별도 플래그가 아니다.** `start`가 있고 `end`가 없는 상태가 그것이다.
+플래그를 두면 플래그와 값이 어긋난 상태가 표현 가능해진다.
+
+**미리보기는 같은 함수를 쓴다.** `resolveDateRangeCellState(value, date, hoveredDate)`가
+확정된 구간과 hover 미리보기를 함께 처리한다 — renderer가 두 벌의 칠하기 규칙을 만들지
+않게 한다.
+
+**Native.** renderer는 아직 없다(catalog `planned`). 구간 선택은 제스처·스크롤과 함께
+검증해야 해서 Web 먼저 낸다.

package/docs/density.md

@@ -0,0 +1,23 @@
+# 전역 density 축
+
+**문제.** 같은 화면의 목록·메뉴·표가 각각 다른 밀도로 그려졌다. `ListRow density`,
+`Menu density`, `DataTable density`가 서로를 모르는 값이라 제품이 세 군데를 따로 맞췄다.
+
+**해결.** Provider에 `density` 축을 하나 둔다(`"comfortable" | "compact"`, 기본
+`comfortable`). 그 아래의 목록·메뉴·표가 **기본값으로** 이 값을 읽는다.
+
+**컴포넌트의 명시적 prop이 언제나 이긴다.** 전역값은 기본이지 강제가 아니다. 한 화면
+안에서 "표만 빽빽하게"가 필요한 경우가 실제로 있고, 그때 전역 축을 끄러 Provider까지
+올라가야 한다면 축이 없느니만 못하다.
+
+**어휘를 하나로 통일하지 않았다.** 목록의 `relaxed`와 표의 `regular`는 같은 말이 아니다.
+억지로 합치면 둘 중 하나가 거짓말을 한다. 대신 `resolveDensityDefault(density, {
+comfortable, compact })`가 전역 축을 각 컴포넌트의 어휘로 옮긴다 — 매핑이 한 곳에 있다.
+
+**OS 신호가 없다.** 밀도는 "같은 화면에 얼마나 담을 것인가"라는 제품의 입장이지 사용자
+설정이 아니다. 그래서 `systemDensity` 같은 짝을 두지 않았다. 반대로 큰 글자는 사용자
+설정이므로, `textScale`이 큰 상태에서 `compact`를 켜는 것은 제품이 스스로 막아야 한다 —
+계약이 대신 꺼 주면 제품이 그 충돌을 영영 모른다.
+
+**Provider 밖에서는 각 recipe의 기본값이 그대로 선다.** 전역 축이 "감싸지 않은 렌더러"를
+다르게 만들면 축 자체가 숨은 의존이 된다.

package/docs/expansion-roadmap.md

@@ -1,5 +1,18 @@
 # HJM Design System Expansion Roadmap
 
+## 2026-09-16 React·React Native 완성
+
+사용자가 Flutter를 제외하고 토스 UI를 중심 모티브로 컴포넌트를 채우도록 요청했습니다.
+[전체 누락 목록·참조·완성 기준](react-native-completion.md)을 따라 renderer와 실제 조합
+화면을 함께 만듭니다. 기존 소수 수정으로 전체 목표를 완료 처리하지 않습니다.
+
+## 2026-09-15 실제 제품 조사에서 추가한 작업
+
+[8개 앱 업데이트 목록](product-audit-2026-09-15.md)에 공통 결함·기존 컴포넌트 채택·제품 소유
+기능을 구분했다. Toast/Notice compact 레이아웃과 Showcase 스타일 충돌부터 수정하고,
+입력 설명/focus·Dialog 완료 신호·상태 조합을 다음 순서로 등록한다. 넓은 간격·어색한 버튼에
+대한 사용자 피드백과 실제 소스/브라우저 결과가 근거이며 catalog maturity는 바꾸지 않는다.
+
 ## 무엇을 흡수하는가
 
 HJM은 외부 라이브러리의 외형이나 public prop 이름을 복사하지 않습니다. 각 시스템에서
@@ -229,7 +242,7 @@ surface별 `planned → beta` gate는 public renderer export와 package CI가
 남아 있지만 렌더되지 않고 월 범위 쿼리의 내부 계산일 뿐이며, 화면은 월 헤더 + 7일
 날짜 레일이다. 앱 전체에 값 하나를 고르는 압축 트리거 UI도 없다.
 
-이후 DatePicker에는 first-party Web·Native renderer와 canonical 환경 증거가 추가되어
+이후 DatePicker와 Calendar에는 first-party Web·Native renderer와 canonical 환경 증거가 추가되어
 `beta`로 승격됐다. 다만 위 실측은 여전히 유효하다. **제품 adoption evidence는 없고**,
 Yajalal의 날짜 레일을 DatePicker 채택으로 세지 않는다. 따라서 `stable` 승격 근거는 없다.
 
@@ -238,8 +251,8 @@ Yajalal의 날짜 레일을 DatePicker 채택으로 세지 않는다. 따라서
 
 ### Batch 3 — 복합 데이터와 파일
 
-- beta: Timeline, UploadItem, DatePicker, FilePicker
-- planned: TimePicker
+- beta: Timeline, UploadItem, DatePicker, Calendar, FilePicker
+- composed: TimePicker (Web/RN 시·분 선택·확정 예제 제공, 독립 renderer는 없음)
 - web: DataTable, Tree, ColorPicker, CommandPalette, SidePanel, Popover
 
 FilePicker는 파일 선택 의도만 소유합니다. 업로드 요청·재시도·서버 상태는 제품이 소유하고,