@hjmds/design-contracts 0.8.2

package/docs/authoring-brief.md

@@ -0,0 +1,87 @@
+# 컴포넌트 저작 브리프 — planned → 계약·recipe·행동 완성
+
+이 문서는 planned 컴포넌트를 구현 가능한 상태로 끌어올리는 저작자(에이전트)의 작업
+계약이다. 사람이 유지보수하는 문서이기도 하므로, 규칙의 이유를 함께 적는다.
+
+## 먼저 통독할 것 (순서대로)
+
+1. `docs/identity.md` — 이 시스템의 문장("조용한 화면 위에 중요한 순간만 선명하게")
+2. `docs/architecture.md` — 층 구조와 경계
+3. `docs/expansion-roadmap.md` — **공통 상태 축, Collection 기본 계약, maturity gate.**
+   특히 「무엇을 흡수하는가」 표 — 외부 시스템에서 무엇을 가져오고 무엇을 가져오지
+   않는지가 이 저장소의 헌법이다.
+4. `docs/ant-design-coverage.md` — antd는 **reference inventory**일 뿐이다. 외형, token
+   값, prop 이름, 전용 자산을 복사하지 않는다. 같은 사용자 문제를 HJM의 의미로 다시
+   푼다.
+5. 본보기 모듈 **둘**: `src/statistic.ts`(+`test/statistic.test.ts`, `docs/statistic.md`) —
+   표현 계약의 본보기. `src/load-more.ts` — 행동 계약(컨트롤러)의 본보기.
+
+## 산출물 — 컴포넌트당 세 파일
+
+| 파일 | 내용 |
+|---|---|
+| `src/<name>.ts` | 계약 전부: descriptor 타입, defaults, validator, resolver, 시각 recipe 토큰, 행동 시나리오. **한 모듈에 자급자족**으로 담는다 |
+| `test/<name>.test.ts` | vitest. validator가 거부해야 할 입력, resolver의 경계 입력, 시나리오 불변식 |
+| `docs/<name>.md` | 로드맵이 정한 기록 형식: **문제 → 일반화한 계약 → HJM 기본값 → 플랫폼 번역 → 검증 화면** |
+
+### 왜 recipe·행동을 공용 레지스트리에 직접 쓰지 않는가
+
+`component-recipes.ts`, `behaviors.ts`, `catalog.ts`, `recipes.ts`, `index.ts`는 모든
+컴포넌트가 지나는 **공유 파일**이다. 여러 저작자가 병렬로 이 파일들을 고치면 서로의
+작업을 덮어쓴다. 그래서:
+
+- 저작자는 **자기 모듈 파일 안에** recipe와 행동까지 export한다.
+- 보고서에 **배선 명세**를 적는다 — catalog 한 줄(카테고리·platform·recipe 키·behavior
+  키), `index.ts`에 내보낼 심볼 목록, 공용 레지스트리로 옮길 것이 있으면 그 목록.
+- 배선은 리드가 순차로 적용한다.
+
+이 방식이면 저작자의 `pnpm check`는 자기 파일만으로 통과하고(아무도 아직 그 모듈을
+참조하지 않으므로), 충돌이 구조적으로 불가능하다.
+
+## 계약이 지켜야 할 것
+
+- **상태 축은 로드맵의 표에서 고른다.** 필요한 축만 공개한다 — Link가 disabled를
+  지원하지 않는 것처럼, 지원하지 않기로 한 축은 문서에 이유와 함께 적는다.
+- **collection이 있으면 Collection 기본 계약을 따른다** — stable string `id`, `label`과
+  `textValue`, `none|single|multiple`, `idle|loading|loadingMore|empty|error`.
+  새 데이터 모델을 만들지 않는다.
+- **제품이 포맷한 문자열을 받는다.** 숫자·날짜·단위 포맷은 제품 소유다(Statistic 참고).
+- **validator는 던진다.** 빈 label, 중복 id, 성립하지 않는 조합은 조용히 넘기지 않고
+  `TypeError`/`RangeError`로 거부한다. 그리고 **그 validator가 잘못 잡는 입력으로 먼저
+  시험한다** — 허락해야 할 것까지 막으면 잘못 만든 것이다.
+- **접근성은 계약의 일부다.** 각 상태가 Web keyboard/aria와 RN accessibilityState로
+  어떻게 번역되는지 모듈이 명시한다. 색으로만 말하는 상태를 만들지 않는다.
+- **런타임 의존성 금지.** 이 패키지는 React도 RN도 import하지 않는다. 타입과 순수
+  함수만 있다. renderer는 제품(BurnTok Web, Yajalal RN)이 소유한다.
+
+## maturity에 대해
+
+당신의 산출물로 컴포넌트는 **"계약+recipe 준비됨"**이 된다. catalog의 `planned → beta`
+승격은 실제 제품 vertical slice 검증 후 리드가 한다 — 로드맵의 gate가 그렇게 정했고,
+시각 recipe만으로 구현 완료를 주장하지 않는 것이 이 저장소의 원칙이다.
+
+## 게이트
+
+```bash
+cd /Users/jimin/Desktop/hjm-design-system
+pnpm typecheck && pnpm test
+```
+
+`pnpm build`는 dist를 다시 쓰므로 저작자는 돌리지 않는다(dist는 리드가 배선 후 한 번에).
+**기존 파일을 수정하지 않는다** — 이 저장소에는 커밋되지 않은 진행 중 변경이 있다.
+당신이 만드는 세 파일 외에는 읽기 전용이다.
+
+## 보고 형식
+
+```
+## <컴포넌트>
+- 문제: <이 컴포넌트가 푸는 사용자 문제 한 문장>
+- antd 대응: <source entry와 relationship — crosswalk와 일치해야 한다>
+- 공개한 상태 축: <축과 값. 지원하지 않기로 한 축과 이유>
+- 배선 명세:
+  - catalog: { name, category, platform, recipe: "<키>", behavior: "<키>" | 없음 }
+  - index 내보낼 심볼: <목록>
+  - 공용 레지스트리 이동 대상: <있으면>
+- 판단이 갈렸던 자리: <대안과 택한 이유>
+- 게이트: typecheck <결과> / test <N passed>
+```

package/docs/border-beam.md

@@ -0,0 +1,66 @@
+# BorderBeam — 새 컴포넌트를 만들지 않는다
+
+## 정정
+
+이 문서의 이전 판은 `BorderBeam`이 Ant Design 컴포넌트가 아니라 Magic UI/Aceternity
+계열의 장식 컴포넌트가 crosswalk에 잘못 섞여 들어온 것이라고 주장했다. **그 주장은
+사실이 아니었다** — antd의 실제 Components Overview를 직접 확인하지 않고 일반
+웹검색만으로 판단한 결과였고, 검색 결과가 더 대중적인 Magic UI/Aceternity 쪽으로
+쏠려 있어 antd가 별도로 같은 이름의 컴포넌트를 추가했을 가능성을 놓쳤다.
+
+리드가 공식 Overview를 직접 확인해 정정했다: `BorderBeam`은 antd "Other" 섹션에
+실재하는 컴포넌트다. `Watermark`도 crosswalk에서 빠지지 않았다 —
+`src/component-references.ts:123`에 `category: "feedback"`으로 이미 정확히 잡혀
+있다(antd에서 Watermark는 Other가 아니라 Feedback 섹션이다). 섹션별 수(general 4 /
+layout 7 / navigation 7 / data-entry 18 / data-display 21 / feedback 11 / other 5 =
+73)도 저장소 테스트의 단정과 전부 일치한다. `component-references.ts:127`의
+`BorderBeam` 행은 **정확하다** — 제거하지 않는다.
+
+## 판정: 그럼에도 만들지 않는다
+
+crosswalk이 맞다는 것과 이 컴포넌트를 지금 만들 것인가는 별개 질문이다. `BorderBeam`이
+실제로 antd에 있다 해도, 그 실체 — 사용자 행동에 반응하지 않는 **상시 반복 이동
+애니메이션**(컨테이너 테두리를 따라 빛줄기가 도는 효과) — 은 `docs/identity.md`와
+정면으로 충돌한다.
+
+- 첫 문장부터 "HJM은 장식으로 브랜드를 증명하지 않습니다."
+- Motion 원칙: "Reduce Motion에서는 이동과 반복을 제거하고 즉시 전환 또는 짧은 opacity로
+  대체합니다", "bounce와 spring은 공간 관계를 설명할 때만 사용합니다."
+- HJM답지 않은 패턴: "브랜드색을 장식 배경처럼 넓게 사용."
+
+두 질문으로 검증했다:
+
+1. **Reduce Motion에서 무엇이 남는가?** 이동 자체가 이 컴포넌트의 전부이므로, 이동을
+   제거하면 정적인 테두리 선(또는 아무것도) 만 남는다 — "즉시 전환"으로 대체할 상태
+   변화가 애초에 없다(열림/닫힘/포커스 같은 원인이 없다).
+2. **장식이 없어도 화면이 같은 뜻을 전하는가?** 그렇다 — 이 컴포넌트는 어떤 상태·값·
+   선택도 표현하지 않는다. 있으나 없으나 화면이 말하는 내용은 똑같고, 차이는 순전히
+   "화려함"뿐이다.
+
+두 질문 모두 "이 장식은 정보를 나르지 않는다"로 귀결됐다 — identity가 정확히 배제하는
+자리(장식으로 증명하는 브랜드, 원인 없는 반복 모션)다. 이 세 근거는 crosswalk 출처
+문제와 무관하게 그대로 성립한다.
+
+## 결론
+
+`src/border-beam.ts`, `test/border-beam.test.ts`는 만들지 않는다.
+
+## 판정이 뒤집힐 조건
+
+BurnTok/Yajalal 중 하나가 실제로 "강조해야 하는 순간"(예: 실시간 방송 중임을 알리는
+라이브 표시, 당첨/축하 모멘트)에 은은한 강조 테두리가 필요하다고 판단하면, 그건
+`BorderBeam`(상시 반복 장식)이 아니라 그 순간에 한정된 **의미 있는 강조 recipe**(예:
+`feedback.attention` 톤의 짧은 1회성 pulse, Toast의 `priority: high`처럼 특정 상태에만
+묶인 것)로 다시 계약해야 한다.
+
+## 배선 명세 (리드 적용)
+
+`src/component-references.ts:127`의 `BorderBeam` crosswalk 행은 **정확하므로 바꾸지
+않는다.** `src/catalog.ts`의 `{ name: "BorderBeam", category: "utility", platform:
+"web", status: "planned" }` 행만 대상이다 — 이 행은 "만들 계획"을 뜻하는 `planned`인데
+실제로는 "만들지 않기로 확정"이라 상태가 거짓말을 하고 있다. 이 불일치를 어떻게
+표현할지는 `docs/catalog-decision-status.md`에서 별도로 다룬다.
+
+## 출처
+
+- [Ant Design — Components Overview](https://ant.design/components/overview/)

package/docs/bottom-navigation.md

@@ -0,0 +1,127 @@
+# BottomNavigation contract
+
+`BottomNavigation`은 콘텐츠 panel을 바꾸는 `Tabs`가 아니라 앱의 안정된 최상위 route를
+이동합니다. 같은 destination 의미를 Web의 link와 React Native navigator tab으로 적응시키며,
+route state는 제품 router 한 곳에서만 소유합니다. BurnTok Web/RN과 Yajalal RN의 실제
+navigation renderer에서 route lifecycle·접근성·큰 글자·safe area를 검증해 catalog status는
+`beta`입니다.
+
+## Descriptor와 configuration
+
+descriptor에는 2–6개 destination, router가 확정한 `selectedKey`, navigation landmark 이름만
+둡니다. item icon은 label과 의미가 중복되므로 이름과 `decorative: true`만 허용하는
+`BottomNavigationIconDescriptor`를 사용합니다. 크기·tone·weight·RTL 방향은 recipe와
+semantic Icon registry가 소유하며 호출부에서 덮어쓸 수 없습니다.
+route path, React component, navigation callback, 생성 action은 descriptor에 넣지 않습니다.
+
+```ts
+const descriptor = {
+  accessibilityLabel: "주요 탐색",
+  selectedKey: currentRoute,
+  items: [
+    { id: "home", label: "홈", icon: { name: "home" } },
+    {
+      id: "messages",
+      label: "메시지",
+      icon: { name: "notifications" },
+      badge: {
+        count: unreadCount,
+        accessibilityLabel: `읽지 않은 메시지 ${unreadCount}개`,
+      },
+    },
+  ],
+} satisfies BottomNavigationDescriptor;
+```
+
+시각·플랫폼 선택은 별도 `BottomNavigationConfiguration`으로 전달합니다.
+
+- `presentation`: `bar | floating`
+- `distribution`: `equal | center-gap`
+- `density`: `compact | regular`
+- `direction`: `ltr | rtl`
+- `keyboardBehavior`: `hide | remain`
+
+두 renderer 모두 `resolveBottomNavigationConfiguration(configuration, itemCount)`를 사용합니다.
+`center-gap`은 짝수 destination에서만 유효합니다. 이 gap은 별도 primary action의 시각적 자리만
+예약하며 action을 collection에 추가하지 않습니다.
+
+Web renderer도 이름이 있는 실제 link landmark, `aria-current`, modifier click 보존,
+keyboard viewport hide와 center-gap 배치를 first-party SSR·browser test로 검증하므로 Web
+surface 역시 `beta`입니다. 제품 router와 결합한 브라우저 릴리스 증거는 stable 승격 전
+debt로 남습니다.
+
+## Route source of truth
+
+`selectedKey`는 controlled/uncontrolled selection API가 아니라 read-only input입니다.
+`resolveBottomNavigationActivation`은 `navigate | reselect` intent만 반환하고 값을 바꾸지 않습니다.
+renderer는 router 또는 navigator에 intent를 전달하며, route 전환이 실제로 완료된 뒤 새
+`selectedKey`를 받습니다. 인증 gate, preventDefault, navigation 실패가 있으면 기존 selected
+상태를 그대로 유지합니다. 각 destination의 nested stack과 scroll state도 navigator가
+보존하며 renderer가 screen을 조건부 remount하지 않습니다.
+
+## Badge announcement
+
+item의 기본 접근성 이름은 `item.accessibilityLabel ?? item.label`입니다. badge count가 0보다
+크면 resolver가 이 이름과 `badge.accessibilityLabel`을 한 번만 합쳐
+`resolvedAccessibilityLabel`로 반환합니다. visible badge는 `99+`처럼 CounterBadge 규칙으로
+제한할 수 있지만 실제 접근성 copy는 제품이 현지화합니다.
+
+resolved badge에는 `hiddenFromAccessibility: true`와 visible label만 있습니다. Web은 badge에
+`aria-hidden="true"`, RN은 badge subtree에 `accessible={false}`와 해당 플랫폼의 descendant
+hide 설정을 적용하고 item root에 `resolvedAccessibilityLabel`만 전달합니다. badge 자체에
+status/live role이나 별도 accessibility label을 추가하면 같은 정보가 두 번 낭독되므로
+금지합니다. polling으로 count가 바뀌어도 focus, selection, live announcement를 만들지 않습니다.
+
+## Adaptive renderer semantics
+
+### Web
+
+- 컴포넌트 root 자체가 이름이 있는 `nav` landmark이고 list 안에 실제 link를 렌더링합니다.
+  `footer`/contentinfo를 자체 생성하지 않으므로 `Layout`의 `footer` slot에 합성해도
+  `<footer>` 안에 `<footer>`가 중첩되지 않습니다.
+- 현재 link는 `aria-current="page"`를 사용합니다.
+- browser의 Tab/Enter, modifier click, context menu, 새 탭 열기를 보존합니다.
+- `tab`/`tablist` role, roving focus, 방향키 navigation을 적용하지 않습니다.
+- SPA router를 사용해도 link의 기본 의미를 button으로 바꾸지 않습니다.
+
+### React Native
+
+- 각 destination은 현지화된 label과 `selected`/`disabled` state를 가집니다. Android와
+  지원되는 renderer는 tab role을 사용합니다. iOS에서 navigator가 tab role을 안정적으로
+  발표하지 못하면 button role과 selected state를 함께 제공하는 플랫폼 fallback을 허용합니다.
+  지원되지 않는 role 문자열을 억지로 주입하는 것보다 실제 VoiceOver 발표를 우선합니다.
+- press 시 navigator의 preventable `tabPress`를 먼저 emit하고, 막히지 않았을 때만 navigate합니다.
+- `tabLongPress`와 test ID 같은 navigator option을 renderer까지 전달합니다.
+- navigator route collection과 scene lifecycle을 보존하며 별도 placeholder route를 만들지 않습니다.
+
+## Visual and layout requirements
+
+- inactive icon/label도 필수 정보이므로 `content.secondary` 이상을 사용합니다.
+- `indicator` slot은 icon target과 badge의 안정된 layout anchor일 뿐이며 selected pill을 그리지
+  않습니다(`visual: none`, `background`/`border`: `null`). renderer는 이 null paint를 플랫폼의
+  transparent 값으로 번역합니다. selected 상태는 label weight와 icon
+  emphasis를 함께 바꿔 색 하나에 의존하지 않습니다. stroke를 제어할 수 있는 icon adapter는
+  `strokeWidth`, 그렇지 않은 adapter는 `scale` 중 최소 하나를 recipe 값으로 적용합니다.
+- selected icon과 label의 색 intent는 모두 `content.brand`이며 renderer는 각각
+  `colors.selectedIcon`과 `colors.selectedLabel`을 소비합니다.
+- keyboard focus ring은 item 바깥에 그려 selected icon/label evidence와 별개로 동시에 보이게
+  합니다.
+- item target은 최소 44×44입니다. label은 항상 보이고 font scaling을 허용하며 고정 item 높이와
+  한 줄 clipping을 사용하지 않습니다. 모든 destination을 동시에 유지해야 하는 persistent chrome의
+  visual label은 최대 `1.4×`까지만 커지고, 원문 전체는 item의 접근성 이름으로 유지합니다.
+- safe-area bottom inset은 recipe의 최소 padding에 더합니다. `max(base, inset)`으로 대체하지
+  않습니다.
+- 기본 keyboard behavior는 `hide`입니다. software keyboard 위로 bottom navigation을 밀어
+  올려 입력 영역을 가리지 않습니다.
+- RTL에서는 item 순서와 badge의 inline-end anchor가 함께 뒤집힙니다. icon 자체의 mirror 여부는
+  semantic Icon contract가 결정합니다.
+- Reduce Motion에서는 transform을 제거해도 label weight evidence는 유지되며
+  selected/focus/route 상태와 press 결과는 같습니다.
+
+## Centered primary action
+
+BurnTok의 생성 버튼처럼 작업을 시작하는 control은 destination이 아닙니다. `center-gap`
+distribution을 선택하고 outer Dock frame에서 기존 Button/IconButton 기반 action을 sibling으로
+합성합니다. 이 action은 tab role, selected state, badge, `selectedKey`, destination count를
+가질 수 없습니다. Web은 button, RN은 button role과 activate action을 사용하며 제품 router나
+modal API를 직접 호출합니다.

package/docs/breadcrumb.md

@@ -0,0 +1,82 @@
+# Breadcrumb contract
+
+**문제.** 깊은 계층 안 화면에서 지금 위치가 전체 구조 어디쯤인지 보여 주고, 상위 계층으로
+곧장 돌아가게 합니다 — `구단 목록 › LG 트윈스 › 선수단`처럼 현재 화면까지의 경로입니다.
+
+**일반화한 계약.** Collection 기본 계약의 stable `id`와 보이는 `label`만 가져옵니다.
+`textValue`, 선택, 비동기 상태는 없습니다 — Breadcrumb는 선택하는 목록이 아니라 이미 온
+경로를 보여 주는 목록입니다. 항목은 순서가 곧 계층이며, **배열의 마지막 항목만 현재
+위치**이고 그 항목만 `destination`이 없습니다. 그 앞의 모든 항목은 `destination`이
+필수입니다.
+
+```ts
+const trail = {
+  items: [
+    { id: "teams", label: "구단", destination: { kind: "internal", href: "/teams" } },
+    { id: "lg", label: "LG 트윈스" },
+  ],
+} satisfies BreadcrumbDescriptor;
+```
+
+`validateBreadcrumbDescriptor`는 빈 trail, 중복 id, 빈 label, **마지막 항목의
+destination**, **마지막이 아닌 항목의 missing destination**을 모두 거부합니다. 항목이
+하나뿐인 trail(현재 화면만, 조상 없음)은 유효합니다.
+
+## Link 목적지 재사용
+
+Breadcrumb는 새 href 개념을 만들지 않습니다. 조상 항목의 `destination`은 `Link`의
+`LinkDestination`(`internal | external`) 타입 그대로이고, `validateBreadcrumbDescriptor`는
+각 조상 항목마다 `validateLinkDestination`을 그대로 호출합니다. 그래서 internal href가
+`/`, `?`, `#`로 시작해야 한다거나 external href가 허용된 protocol만 써야 한다는 규칙은
+Link 문서(`docs/link.md`)가 유일한 출처입니다. Breadcrumb 조상 항목은 Web에서는 실제
+anchor, Native가 이 컴포넌트를 쓴다면 Expo Router Link로 렌더링될 항목이라는 뜻이며,
+`Link`의 `disabled`/`onClick`/`onPress` 금지 규칙도 그대로 상속합니다.
+
+## HJM 기본값
+
+- 마지막 항목은 링크가 아니라 plain text이고 `aria-current="page"`로 표시합니다.
+- 구분자(`/`, `›`)는 정보가 아니라 장식입니다. `breadcrumbRecipe.separator.decorative`는
+  항상 `true`이고 renderer는 이를 접근성 트리에서 숨깁니다(Web `aria-hidden`, 스크린
+  리더는 순서만 듣습니다).
+- 구분자 아이콘은 `chevronEnd`처럼 Icon registry의 논리 방향 이름을 씁니다. RTL 미러링은
+  Icon 계약이 이미 소유하므로 Breadcrumb가 따로 방향을 계산하지 않습니다.
+- **축약(`...`)을 넣지 않습니다.** 항목이 많을 때 가운데를 접는 것은 실제 화면에서
+  측정된 수요가 아직 없습니다. 필요해지면 별도 `collapsed` 축으로 명시적으로 추가하고,
+  지금은 renderer가 전체 trail을 그대로 그립니다.
+- 크기는 Link의 inline 취급을 따릅니다 — 44-unit 최소 target을 강제하지 않고 밑줄과
+  focus indicator만 유지합니다. Breadcrumb 항목은 문장이 아니라 한 줄 경로이므로 독립된
+  standalone Link처럼 하나씩 별도 target으로 쓰기보다, 촘촘한 한 줄 trail로 배치됩니다.
+
+## 플랫폼 번역 — 왜 Web 전용인가
+
+Breadcrumb는 `platform: web`입니다. Native에서는 같은 문제("지금 어디에 있고 어떻게
+돌아가는가")를 이미 두 가지가 풀고 있습니다.
+
+- 플랫폼 back 제스처(스와이프, 하드웨어 back)가 바로 이전 화면으로 돌아가는 동작을
+  소유합니다.
+- `TopBarRecipe`의 `title` 슬롯이 지금 위치를 한 줄로 보여 줍니다(`docs/bottom-navigation.md`
+  및 `topBarRecipe` 참고 — slot은 `root/leading/title/trailing`뿐이고 다단계 경로 trail을
+  위한 자리가 없습니다).
+
+그래서 Native에 별도 Breadcrumb를 만들면 TopBar와 같은 정보를 두 번 계약하게 됩니다.
+`breadcrumbBehaviorSpec.native`는 의도적으로 빈 `{ roles: [], states: [], actions: [] }`이며,
+이는 미완성이 아니라 "이 컴포넌트는 Native에 존재하지 않는다"는 선언입니다.
+
+Web에서는:
+
+- `nav` landmark(`role="navigation"`) 하나가 전체 trail을 감싸고, 순서 있는 `list`/`listitem`
+  구조로 항목을 나열합니다.
+- 조상 항목은 `Link`의 `web.roles: ["link"]`, `keyboard: ["Tab", "Enter"]`를 그대로
+  가져오므로 Breadcrumb 자체가 새 키보드 상호작용을 정의하지 않습니다.
+- 현재 항목은 tab stop이 아니고 `aria-current="page"`만 갖습니다.
+
+## 검증 화면
+
+아직 없음. 이전 판정이 후보로 든 "야잘알의 구단 상세 → 선수단 → 선수 상세" 계층은
+검증 결과 근거가 될 수 없다 — Breadcrumb는 `platform: "web"`인데 야잘알(`modules/app`,
+`modules/app-rn`)은 Flutter/React Native 모바일 앱뿐이고 Web 화면 자체가 없다(Native
+계층 이동은 이미 위에서 TopBar가 담당하기로 판정했다). BurnTok의 Web 앱
+(`apps/web/src/app`)도 함께 확인했지만 지금 라우트는 대부분 2단 이하(`/c/[id]`,
+`/ideas/[id]`, `/messages/[peerId]`, `/u/[id]`)라 3단 이상 계층 화면을 아직 찾지
+못했다. `planned → beta` 승격은 실제 3단 이상 Web 화면이 나오고 키보드/스크린리더
+검증을 거친 뒤 리드가 결정한다.

package/docs/calendar.md

@@ -0,0 +1,154 @@
+# 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` 승격은 실제 제품 화면이 나온 뒤 리드가 진행한다.