@hjmds/design-contracts 0.8.2

package/docs/notification.md

@@ -0,0 +1,54 @@
+# Notification — 별도 컴포넌트를 만들지 않는다
+
+**문제로 제기된 것.** Ant Design은 `message`(Toast)와 `notification`을 지속 시간과
+정보량으로 가릅니다 — `message`는 한 줄, 짧게, 화면 중앙; `notification`은 제목+본문
+두 층, 모서리에 여러 개 쌓임, 기본적으로 더 오래 남거나 닫을 때까지 유지됩니다.
+
+**판정: 이 구분은 HJM에서 성립하지 않는다.** `src/toast.ts`와 `docs/toast.md`를 정독한
+결과, antd가 두 컴포넌트로 나눈 모든 축이 이미 `Toast` 하나의 **설정 값**으로 존재합니다.
+새 상태 축도, 새 접근성 개념도 필요하지 않습니다.
+
+| antd가 가르는 축 | antd `message` | antd `notification` | HJM `Toast`의 같은 축 |
+| --- | --- | --- | --- |
+| 정보 층 | 한 줄 | 제목 + 본문 | `ToastDescriptor.title?` + `description`(이미 두 층) |
+| 지속 시간 | 짧음, 자동 닫힘 | 길거나 수동 닫힘 | `durationMs: number \| null` — `null`이 이미 수동 닫힘 |
+| 동시 개수 | 보통 1개 | 여러 개 모서리에 쌓임 | `ToastStoreOptions.maxVisible` — 1보다 크게 설정하면 여러 개 |
+| 위치 | 화면 상/하단 중앙 | 모서리(우상단 등) | `docs/toast.md`의 `top-start\|top-end\|bottom-start\|bottom-end` placement |
+| 긴급도 | 낮음 | 상대적으로 높음 | `priority: normal \| high` |
+
+즉 "notification처럼 보이는 Toast"는 `createToastStore({ maxVisible: 3, ... })` +
+`durationMs: null` + 모서리 placement + `priority: "high"` 조합이며, 이는 **제품이
+Toast를 구성하는 방식**이지 새로운 platform-neutral 계약이 아닙니다. 이 저장소는
+`Radio`(`selectionControlRecipe`), `TextArea`(`fieldRecipe`)처럼 antd 목록의 한 항목이
+이미 있는 recipe/behavior를 재사용하고 새 recipe를 얻지 못하는 사례를 이미 갖고
+있습니다 — Notification도 같은 자리입니다.
+
+**성립하지 않는다고 판단한 근거.**
+
+1. 새 상태 축이 없습니다. `idle→visible→closing→closed`, pause reason, exact-once
+   dismiss 중 어느 것도 "notification이라서 다르게" 필요하지 않습니다.
+2. 새 접근성 개념이 없습니다. `normal`/`high` announcement priority가 이미 긴급도
+   차이를 담습니다.
+3. 측정된 제품 요구가 없습니다. 로드맵 어디에도 "Toast로는 안 되고 별도 알림이
+   필요했다"는 vertical slice 기록이 없습니다. 이 저장소는 측정되지 않은 표면을
+   미리 만들지 않습니다(로드맵 「무엇을 흡수하는가」 원칙).
+
+**만들지 않은 것.** `src/notification.ts`, `test/notification.test.ts`는 없습니다. 새
+계약이 없는데 파일만 만들면 다음 사람이 "Toast와 뭐가 다른가"를 또 물어야 하는 빈
+추상화가 됩니다.
+
+## catalog 배선 명세 (리드 적용)
+
+crosswalk(`component-references.ts:117`, `Notification → direct`)는 antd 범위 추적용
+그대로 둡니다. catalog 항목은 새 recipe를 만들지 않고 기존 Toast 계약을 가리키는 쪽을
+권합니다.
+
+```ts
+{ name: "Notification", category: "feedback", platform: "adaptive", status: "planned", recipe: "toastRecipe", behavior: "toast" }
+```
+
+`planned → beta` 승격은 이 recipe/behavior 재사용을 그대로 유지한 채, 실제 제품이
+`maxVisible > 1` + 모서리 placement + persistent duration 조합을 notification 용도로
+쓰는 vertical slice가 나온 뒤 결정합니다. 만약 그 슬라이스에서 Toast로 표현할 수 없는
+요구(예: 화면 밖 push 발표, 별도 알림함 이력)가 나오면 그때는 이 문서를 갱신하고 새
+계약을 여는 것이 맞습니다 — 지금은 그 증거가 없습니다.

package/docs/number-field.md

@@ -0,0 +1,82 @@
+# NumberField contract
+
+**문제.** 사용자가 정확한 수 하나를 정한다 — 타율 계산기의 타수, 예약 인원, 코멘트
+글자 수 제한처럼 "이 숫자 그대로"가 중요한 입력이다. 대략적인 감으로 고르는 Slider와는
+반대 극단의 문제다.
+
+**일반화한 계약.** min/max/step/value의 판정은 Slider와 `src/number-field.ts`의
+`validateNumericRangeConfig`/`clampToRange`/`snapToStep`을 공유한다. 두 컴포넌트가 각자
+다른 반올림·경계 규칙을 갖게 되면 같은 "범위 있는 수"라는 개념이 두 이름으로 갈라지기
+때문이다. NumberField 쪽 전용 판단은 값이 `number | null`이라는 점뿐이다 — `null`은
+아직 아무 값도 입력하지 않은 상태이며 `min`을 포함한 어떤 실수 값과도 다르다.
+
+- `value: number | null`, `min`, `max`, `step?`(기본 1).
+- validator는 min≥max, step≤0, step이 min–max 폭보다 큰 조합, 범위 밖 value를 던진다.
+  경계값(`value === min` 또는 `max`)과 `value === null`은 허용해야 하는 입력이라 먼저
+  통과 시험한다.
+- stepper 방향 disabled는 `resolveNumberFieldStepperState`가 계산한다: 현재 값이 `min`이면
+  decrement, `max`이면 increment가 disabled. `value === null`일 때는 아직 경계에
+  닿지 않았으므로 두 방향 모두 disabled가 아니다.
+- `stepNumberFieldValue`는 empty에서 누르면 increment는 `min`, decrement는 `max`로
+  이동한다 — 어느 방향으로 처음 눌러도 그 방향이 향하는 경계에 착지한다.
+- step grid의 소수 정밀도는 `step`만이 아니라 기준점 `min`까지 함께 사용한다. 예를 들어
+  `min=0.05, step=0.1`의 유효한 순서는 `0.05, 0.15, 0.25…`이며 `0.15`를 `0.2`로
+  반올림하지 않는다.
+- 표시 문자열(단위, 소수 자릿수, 통화 기호 등)은 만들지 않는다. 제품이 포맷한 문자열을
+  받는 Statistic과 같은 원칙이다.
+- Web/RN renderer의 편집 중 문자열은 `parseNumberFieldInput`으로 같은 판정을 받는다.
+  빈 문자열은 `null`, `-`/`1e` 같은 미완성 draft는 `undefined`이고, blur/submit에서만
+  `commitNumberFieldInput`이 clamp와 step snap을 적용한다. 따라서 controlled 숫자 모델에
+  미완성 문자열을 밀어 넣지 않으면서도 사용자의 단일 행 편집을 중간에 방해하지 않는다.
+- 증감 action은 `stepNumberFieldInput`으로 draft를 직접 판정한다. off-grid draft에서 먼저
+  nearest snap을 한 뒤 다시 한 step을 더하지 않고, 요청 방향의 바로 다음 유효 경계로
+  이동한다(`4.26`, step `0.5`의 increment는 `4.5`, decrement는 `4.0`).
+- `resolveNumberFieldInputStepperState`도 같은 draft를 사용한다. committed 값이 max여도 사용자가
+  더 작은 draft를 편집 중이면 increment 버튼을 활성화하여 visible value, keyboard, 버튼과
+  Native accessibility action의 capability가 서로 모순되지 않게 한다.
+
+**HJM 기본값.** Field의 `fieldFrameContract`/`formSupportContract`를 그대로 재사용한다
+(`numberFieldRecipe.frame`, `.support`). 새 프레임을 만들면 Field와 높이·radius·invalid
+border가 갈린다. stepper 버튼은 44-unit target(`control.minTouchTarget`)을 유지하고
+disabled는 opacity만으로 표현하지 않는다 — 버튼 자체가 눌리지 않는 상태(no press
+feedback)와 짝지어 판단할 수 있는 대상이라 색만으로 말하지 않는다.
+
+held-repeat(꾹 눌러 연속 증가)는 이번 계약에 넣지 않는다. 실제 제품에서 측정된 수요가
+없고, 지금 넣으면 반복 속도·가속 곡선을 검증 없이 추측해야 한다. 한 번 누름 = 한 번
+step만 공개한다.
+
+**플랫폼 번역.**
+
+- Web: role `spinbutton`, keyboard `Tab`(진입/이탈), `ArrowUp`/`ArrowDown`(step). 타이핑
+  자체는 native text input 동작이라 별도 키를 등록하지 않는다.
+  locale-neutral draft와 브라우저 단일 행 편집을 지키기 위해 `type="text"`를 사용하므로
+  무효인 HTML `min`/`max`/`step` attribute에는 기대지 않는다. 범위는 `aria-valuemin`/
+  `aria-valuemax`와 공통 resolver가 집행한다. stepper는 `tabIndex=-1`인 보조 action이다.
+  입력 하나만 Tab 순서에 두고 Arrow 키로 같은 기능을 제공하되, pointer와 voice control은
+  제품이 주입한 이름의 증감 버튼을 직접 활성화할 수 있다.
+- React Native: `text` role(입력)과 `button` role(stepper) 조합, `disabled` state,
+  `focus`/`setText`/`increment`/`decrement` action. RN에는 `spinbutton` 동등물이 없어
+  두 역할의 조합으로 번역한다.
+- `validation`(valid/invalid) 축은 NumberField에만 공개한다 — 범위 자체의 유효성과는
+  독립적인, 제품이 매기는 별도 판정(예: "홀수만 허용")이기 때문이다. Slider는 이 축을
+  갖지 않는다.
+
+**검증 화면.** 아직 실제 제품 vertical slice가 없다 — catalog는 `planned`으로 남고,
+`beta` 승격은 로드맵의 gate(실제 화면 검증)를 통과한 뒤 리드가 진행한다.
+
+**명시적 범위 밖.** 기본 parser는 ASCII 부호·10진수·exponent만 받는 locale-neutral
+grammar다. 통화 기호, 단위 suffix, grouping separator, 아라비아/한 숫자 체계, locale별
+decimal separator의 자동 parse/format은 지원한다고 주장하지 않는다. 그런 요구는 향후
+양방향 parse/format adapter 계약과 IME·locale fixture를 함께 추가한 뒤 확장한다.
+Composition 중 문자열은 draft에만 남지만, 비-ASCII 숫자 IME의 parsing·caret 보존을
+검증했다는 claim도 하지 않는다.
+
+**참고한 공개 기준.** WAI-ARIA APG의
+[Spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/)에서 입력을
+단일 Tab stop으로 두고 ArrowUp/ArrowDown을 기본 조정 키로 삼았다. Adobe React Aria의
+[useNumberField](https://react-spectrum.adobe.com/react-aria/useNumberField.html)에서
+부분 문자열을 numeric model과 분리하고 blur에서 commit하는 판단을 참고했지만, 그
+라이브러리의 locale/currency parse나 held-repeat까지 구현했다고 주장하지 않는다.
+Native의 증감 action은 React Native 공식
+[Accessibility actions](https://reactnative.dev/docs/accessibility#accessibility-actions)
+API로 번역한다.

package/docs/otp-field.md

@@ -0,0 +1,103 @@
+# OtpField contract
+
+## 문제
+
+문자로 온 인증번호를 한 자씩 여러 칸에 입력한다. Ant Design `Input.OTP`와 `direct`
+crosswalk를 따른다(`Input`의 decomposed target 중 하나).
+
+## 접근성이 본체다: 여러 칸이지만 하나의 값이다
+
+**판정.** OtpField는 **하나의 포커스 가능한, 하나의 접근 가능한 이름·값을 가진 텍스트
+컨트롤**이다 — 칸마다 별도로 포커스를 받는 N개의 실제 input이 아니다. 화면에 보이는
+N개의 칸은 그 하나의 컨트롤이 가진 문자들을 보여주는 **장식**일 뿐이다
+(`getOtpFieldSlotValues`).
+
+**근거.** 칸마다 독립된 실제 input을 만들면 스크린 리더는 각 칸에 포커스가 갈 때마다
+"6개 중 3번째, 빈 칸" 같은 것을 읽는다 — 사용자는 자신이 지금 무엇을 입력하고 있는지
+(인증번호 전체 중 어디까지 왔는지, 지금까지 뭘 입력했는지) 알 수 없다. 이건 이 종류의
+컴포넌트가 접근성에서 가장 흔히 실패하는 지점이다. 반면 하나의 실제 텍스트 필드에
+글자 간격(letter-spacing) 스타일과 그 위에 겹쳐 그리는 장식 칸 테두리를 쓰면, 화면
+읽기는 평범한 한 텍스트 필드("인증번호, 123 입력됨" 같은 하나의 이름과 값)이고, 보기에는
+여전히 칸이 나뉜 것처럼 보인다. 시각적 유연성(칸별 강조색 등)도 잃지 않는다 —
+`getOtpFieldSlotValues`가 칸별 문자를 그대로 주므로 장식 칸 하나하나를 다르게 칠하는
+것은 여전히 가능하다.
+
+## 붙여넣기·입력·지우기가 거의 공짜인 이유
+
+실제 input이 하나이므로 타이핑·붙여넣기(중간 선택 영역에 붙여넣기 포함)·Backspace는
+**모두 플랫폼의 기본 텍스트 편집**이 처리한다 — 문자 삽입 위치, 선택 영역 교체, 커서
+이동을 이 패키지가 다시 구현하지 않는다. 브리프가 요구한 "지우기 동작"(빈 칸에서
+Backspace → 앞 칸으로)도 이 모델에서는 별도 로직이 필요 없다 — 마지막 문자 바로 뒤
+커서에서 Backspace를 누르면 원래 텍스트 필드가 마지막 문자를 지우고 커서를 한 칸
+앞으로 옮기는 것과 정확히 같은 동작이기 때문이다.
+
+그래서 HJM이 실제로 소유하는 판단은 딱 하나 — **편집 결과로 나온 원시 문자열을 어떻게
+정리하는가**(`resolveOtpFieldValue(length, rawText)`): 숫자만 남기고, `length`를 넘지
+않게 자른다. 타이핑이든, 붙여넣기든, 중간 위치에 붙여넣은 결과든 항상 이 하나의
+함수로 들어온다 — 그래서 이 계약이 함수를 여러 개(칸별 입력, 칸별 붙여넣기, 칸별
+지우기) 만들지 않고 하나만 갖는다.
+
+**경계 입력(테스트로 잠갔다).**
+
+- 길이 초과: `"1234567890"` → `length`만큼 자른다(던지지 않는다).
+- 숫자가 아닌 문자: `"12-34 56"`, `"abc123def456"` → 숫자만 남긴다(거부하지 않는다,
+  붙여넣은 문자열에 공백·하이픈이 섞여 오는 실제 SMS 문구를 그대로 허용하기 위해서다).
+- 중간 위치에 붙여넣기: 실제 input에서는 "칸 3에 붙여넣기"가 아니라 "이미 있던
+  텍스트의 중간에 붙여넣어 병합된 새 문자열"로 이 함수에 도착한다 — 그 이미
+  병합된 문자열을 정리하는 것으로 충분하다(테스트: `"12" + "99"(붙여넣음) + "34"` →
+  `"129934"`, `length=4`면 `"1299"`로 자름).
+
+`value.length > length`인 **커밋된 descriptor**는 여전히 던진다
+(`validateOtpFieldDescriptor`) — 이건 편집 경로가 아니라 "이미 잘못된 상태를 그대로
+렌더링하려는" 렌더러 버그 신호다. 편집 중(자름)과 커밋된 상태 검증(던짐)은 다른
+문제다.
+
+## 값은 항상 빈틈없다
+
+`OtpFieldDescriptor.value`는 항상 인덱스 0부터 채워진 문자열이다 — 칸 2는 채워지고 칸
+0~1은 비어 있는 상태를 표현하지 않는다(`getOtpFieldSlotValues`가 인덱스 `i`는
+`i < value.length`일 때만 채워졌다고 보는 것과 정확히 같다). 이 하나의 불변식 때문에
+타이핑·붙여넣기·지우기가 모두 "평범한 문자열 편집"으로 환원된다 — 빈틈을 허용했다면
+칸별 위치 계산을 이 패키지가 다시 만들어야 했을 것이다.
+
+## 숫자만 받는다
+
+인증번호는 이 브리프가 설명하는 그대로 숫자다. 영숫자 혼합 OTP는 지금 계약에 없다 —
+문자 집합을 설정 가능하게 만들면 검증되지 않은 패턴을 미리 얹는 것이 된다. 실제
+필요가 나오면 그때 `characterPattern` 같은 축을 연다.
+
+## HJM 기본값
+
+- 칸(`slot`) 테두리는 새 팔레트를 만들지 않고 `fieldFrameContract`의 `border`/
+  `focusBorder`/`invalidBorder`/`radius`/`borderWidth`를 그대로 쓴다 — 칸 하나하나가
+  작은 Field 프레임이라는 뜻이다. 채워진 칸의 테두리만 `content.brand`로 강조한다.
+- `support`(hint/error)는 `formSupportContract`를 그대로 쓴다.
+
+## 플랫폼 번역
+
+- Web: 실제 `<input>` 하나(`type="text"`, `inputMode="numeric"`, `maxLength={length}`,
+  `autoComplete="one-time-code"`). 화면에는 letter-spacing과 겹쳐진 칸 테두리로
+  나뉜 것처럼 보이지만 접근 가능한 이름과 값은 하나다. 클릭으로 특정 칸 근처를
+  누르면 그 위치 근처로 네이티브 캐럿이 이동한다 — 별도 포커스 이동 로직이 필요
+  없다.
+- Native: `TextInput` 하나, `keyboardType="number-pad"`, `maxLength={length}`. 칸은
+  같은 방식으로 그 위에 겹쳐 그리는 장식 뷰다.
+- 낭독 팁(코드로 강제하지 않음, 렌더러 안내): 여러 자리 숫자를 화면 낭독기가 통째로
+  큰 수("이십삼만사천오백육십칠")로 읽을 수 있다. 자릿수 낭독이 필요하면 렌더러가
+  접근성 이름/값에 숫자 사이 공백을 넣어 한 자씩 읽히게 할 수 있다 — 이건 제품
+  카피(어떻게 띄어 읽을지)의 문제라 composer 콜백을 새로 만들지 않고 문서로만
+  안내한다.
+
+## 공개한 축 / 배제한 축
+
+| 축 | 상태 |
+| --- | --- |
+| `value`(controlled, 하나의 문자열) | 공개 |
+| `availability`(enabled/disabled/readOnly/busy) | 공개 — 서버 인증 중 `busy` |
+| `validation`(valid/invalid) | 공개 — 오류 카피는 Field의 `error` 슬롯 |
+| 칸별 포커스·칸별 접근성 발화 | **배제**(의도적) — 위 판정 참고 |
+| 영숫자 문자 집합 | **배제** — 측정된 요구 없음 |
+
+## 검증 화면
+
+아직 없음. `planned → beta` 승격은 실제 제품 vertical slice 이후 리드가 진행한다.

package/docs/pagination.md

@@ -0,0 +1,139 @@
+# Pagination contract
+
+## 문제
+
+경계가 있는 결과 집합(검색 결과, 관리자 테이블)에서 사용자가 임의의 페이지로
+바로 이동할 수 있어야 한다. 이는 계속 스크롤해서 다음 항목을 불러오는 열린
+목록과는 다른 문제다.
+
+## Pagination과 LoadMore의 경계 (로드맵이 이미 그은 선)
+
+`docs/expansion-roadmap.md`는 이미 명시한다: "Native 긴 목록에는 페이지 번호
+보다 LoadMore/infinite loading을 사용한다." 그래서 Pagination은 `platform:
+web` 전용이고 LoadMore(`shared`)는 두 플랫폼 다 있다. 이유는 표면적
+"페이지 번호 vs 무한 스크롤" 취향이 아니라 총량과 입력 장치의 차이다.
+
+- Pagination은 **안정된 총 개수/총 페이지**를 전제한다 — 사용자가 "42페이지로
+  가겠다"는 의도를 표현할 수 있는 자리다.
+- LoadMore는 **총량을 몰라도** 되고, 사용자는 "다음 조금 더"만 의도한다 —
+  `LoadMoreState`에 `totalPages` 개념 자체가 없다.
+- 마우스/키보드가 있는 Web에서는 임의 페이지 클릭이 싸다. 터치로 스크롤하는
+  Native 긴 목록에서는 페이지 번호 탭이 스크롤 관성과 경쟁하고, 오차 없이
+  작은 숫자를 누르기도 어렵다.
+
+두 계약은 서로를 참조하지 않는다(`src/load-more.ts`는 Pagination을 모르고
+반대도 마찬가지). 제품이 고르는 기준은 이 문서에 있다: **총량이 고정되고
+사용자가 임의 페이지로 점프해야 하면 Pagination, 그렇지 않고 계속 이어지는
+피드면 LoadMore.** 같은 화면에 두 계약을 동시에 쓸 이유는 없다 — 하나의
+목록은 둘 중 하나의 탐색 모델만 가진다.
+
+## 일반화한 계약
+
+### 필수 입력
+
+`PaginationDescriptor`는 `currentPage`와, 총량을 표현하는 두 형태 중
+정확히 하나를 받는 discriminated union이다.
+
+- `{ currentPage, totalCount, pageSize }` — 제품이 원본 개수와 페이지 크기를
+  아는 가장 흔한 경우. `totalPages = max(1, ceil(totalCount / pageSize))`로
+  유도한다.
+- `{ currentPage, totalPages }` — 서버가 이미 페이지 수 단위로 응답하거나
+  페이지 크기 개념이 없는 경우.
+
+`totalPages`와 `totalCount`/`pageSize`를 동시에 주거나 아무것도 안 주면
+validator가 `TypeError`로 거부한다. `currentPage`가 유도된 `totalPages`
+범위를 벗어나면 `RangeError`로 거부한다 — 조용히 clamp하지 않는다(브리프:
+"validator는 던진다").
+
+### 배제한 것 — size changer와 jump-to-page
+
+**페이지 크기 변경(size changer)과 "몇 페이지로 이동" 입력은 넣지 않는다.**
+둘 다 antd `Pagination`에는 있지만:
+
+- 측정된 제품 수요가 없다 — 로드맵의 어떤 vertical slice도 이 두 기능을
+  요구한 적이 없다.
+- 둘 다 이미 있는 `currentPage`/`totalPages` 상태에 도달하는 **또 다른
+  경로**일 뿐 새 상태 축이 아니다. size changer는 제품이 `pageSize`를 바꿔서
+  같은 `PaginationDescriptor`를 다시 넘기면 되고, jump-to-page는 별도
+  `NumberField` + 제품 코드가 같은 `onPageChange(page, "page")`를 호출하면
+  된다. 이 모듈이 그 UI를 대신 만들 필요가 없다.
+
+필요해지면 그때 이 문서를 갱신하고 여는 것이 맞다 — 지금은 그 증거가 없다
+(Dropdown/Notification 문서와 같은 원칙).
+
+### 페이지 번호 목록은 순수 함수다
+
+`computePaginationItems(totalPages, currentPage, { siblingCount,
+boundaryCount })`는 접근성 이름 조립과 완전히 분리된 순수 함수다. 항상
+보여야 하는 페이지(양쪽 경계 `boundaryCount`개 + `currentPage` 주변
+`siblingCount`개)의 합집합을 구하고, 그 사이 숨는 페이지 수에 따라:
+
+- 숨는 페이지가 **정확히 1개**면 그 번호를 그대로 보여준다 — `...`이 숫자
+  하나보다 자리를 아끼지 않으므로 생략할 이유가 없다.
+- 숨는 페이지가 **2개 이상**이면 생략 표시 하나로 접는다.
+
+경계 입력을 테스트로 잠갔다: 총 1페이지(생략 없음, 번호 하나), 총 2페이지
+(생략 없음, 둘 다 표시), 현재가 첫 페이지(꼬리만 접힘), 현재가 마지막 페이지
+(머리만 접힘), 숨는 페이지가 정확히 1개인 경우(생략 대신 번호), 1~14페이지
+전 조합에 대한 "연속 생략 없음 / 항상 1과 totalPages로 시작·끝남" 불변식.
+
+### 접근성 이름은 제품이 조립한다
+
+`ComposePaginationAccessibleName`은 `steps.ts`의 `composeAccessibleName`
+선례를 그대로 따른다 — `{ page, totalPages, current }`를 받아 "5 페이지 중 3
+페이지" 같은 문장을 제품이 조립해 각 페이지 버튼의 accessible name으로 쓴다.
+Steps와 같은 이유다: 순서를 나타내는 문장의 어순과 조사는 언어마다 다르고
+(한국어 "5 페이지 중 3 페이지"는 영어 "page 3 of 5"와 구조가 다르다), 생략
+표시로 페이지가 듬성듬성 보이는 상황에서는 화면에 찍힌 숫자 하나만으로
+전체 맥락(총 몇 페이지 중인지)이 전달되지 않는다. resolver는 composer가 빈
+문자열을 반환하면 던진다.
+
+생략 표시(`...`)는 **장식**이다. `ResolvedPaginationItem`의 ellipsis 분기는
+`accessibleName` 필드 자체가 없다 — 렌더러가 `aria-hidden`으로 완전히 숨겨야
+하고, 페이지 버튼과 달리 focus를 받지 않는다.
+
+## HJM 기본값
+
+- `siblingCount: 1`, `boundaryCount: 1` — 현재 페이지 양옆 1개, 양쪽 경계
+  1개씩만 항상 보인다. antd 기본값을 복사한 것이 아니라 가장 흔한 폭(모바일
+  전체 폭 웹뷰~데스크톱 사이드바)에서 항목 수가 과도하게 늘어나지 않는
+  선에서 고른 값이다. 더 넓은 화면이 필요하면 제품이 두 값을 올린다.
+- 현재 페이지 표시는 `identity.md`의 "primary fill은 주요 행동에, 더 밝은
+  contentBrand는 focus·선택 indicator·현재 위치에" 원칙과 `stepsRecipe`의
+  현재 단계 처리(배경 채우지 않고 border+글자색만 brand)를 그대로 따른다.
+  `paginationRecipe.item`은 현재 페이지에 `action.brand` 채움을 쓰지 않고
+  `border.focus`/`content.brand` 외곽선만 쓴다 — 페이지 번호는 위치 표시이지
+  버튼 커맨드가 아니다.
+- 이전/다음 아이콘은 새 glyph를 만들지 않고 기존 논리 방향 아이콘
+  `chevronStart`/`chevronEnd`(RTL에서 자동 mirror)를 재사용한다. 생략 표시의
+  장식 마크도 기존 `more` 아이콘을 재사용한다.
+
+## 플랫폼 번역
+
+- Web: root는 `<nav>` 랜드마크다. 각 페이지 버튼은 `aria-current="page"`를
+  현재 페이지에만 달고, 시각 숫자와 함께 제품이 조립한 `accessibleName`을
+  accessible name으로 쓴다. 생략 표시는 `aria-hidden`이며 tabbable하지 않다.
+  이전/다음 버튼은 `PaginationLabels`의 고정 현지화 문구를 쓰고, 경계에서는
+  `disabled`(색만이 아니라 `aria-disabled`와 `opacity.disabled`)로 표시한다.
+- Native: `platform: web`이므로 이 계약은 Native 렌더러를 갖지 않는다 —
+  긴 목록의 Native 대응은 `LoadMore`다(위 경계 참고).
+- Reduce Motion: 페이지 전환은 이동 애니메이션 없이 콘텐츠만 교체한다 —
+  Pagination 자체는 전환 모션을 소유하지 않는다.
+
+## 공개한 축 / 배제한 축
+
+| 축 | 상태 |
+| --- | --- |
+| `currentPage`, `totalPages`(또는 `totalCount`+`pageSize`) | 공개(필수) |
+| 페이지 window 크기(`siblingCount`/`boundaryCount`) | 공개(선택, 기본값 있음) |
+| 생략 표시 | 공개하되 장식으로 한정 — 낭독 제외 |
+| page size changer | **배제** — 측정된 수요 없음, 필요 시 제품이 같은 상태를 다시 넘기는 방식으로 조합 가능 |
+| "몇 페이지로 이동" 입력 | **배제** — 위와 같은 이유, 별도 `NumberField` + `onPageChange`로 조합 가능 |
+| `disabled`(컨트롤 전체) | **배제** — 브리프가 요구한 필수 계약을 넘는 축이라 지금은 열지 않는다. 필요해지면 availability 축에서 `enabled`/`disabled`만 추가한다 |
+| Native 대응 | **배제** — `LoadMore`가 이미 같은 문제의 Native 해法이다 |
+
+## 검증 화면
+
+아직 없음. `planned → beta` 승격은 실제 제품 vertical slice 이후 리드가
+진행한다(로드맵 maturity gate). 유력 후보는 검색 결과나 관리자 테이블처럼
+안정된 총 개수가 있는 Web 목록이다.

package/docs/password-field.md

@@ -0,0 +1,98 @@
+# PasswordField contract
+
+## 문제
+
+비밀번호를 입력하면서 필요할 때만 값을 눈으로 확인한다. Ant Design `Input.Password`와
+`direct` crosswalk를 따르되, 이 저장소에서는 `Input`이 `Field`/`TextArea`/`SearchField`/
+`PasswordField`/`OtpField`로 이미 분해돼 있다(`decomposed`).
+
+## Field 프레임을 재사용한다
+
+`Field`는 이미 stable이고, `NumberField`가 방금 같은 판단을 내렸다(`src/number-field.ts`) —
+새 필드 프레임을 만들지 않고 `fieldFrameContract`/`formSupportContract`(둘 다
+`src/component-contracts.ts`)를 그대로 가져다 쓴다. PasswordField는 `value`/
+`onValueChange`도 새로 정의하지 않는다 — 비밀번호의 값은 그냥 문자열이고, Field의 값과
+다른 어떤 것도 아니다(NumberField가 파싱된 숫자를 다뤄야 해서 자기 값 타입을 가진 것과
+다른 지점). 그래서 이 모듈이 계약하는 새 문제는 정확히 하나, **가림 토글**뿐이다.
+
+## 토글의 접근 가능한 이름: 상태가 아니라 행동
+
+**판정.** 토글의 이름은 "지금 비밀번호가 보이는가/숨겨져 있는가"(현재 상태)가 아니라
+**누르면 무슨 일이 일어나는가**(다음 행동)를 말한다 — 접힘일 때 "비밀번호 보이기",
+펼침일 때 "비밀번호 숨기기".
+
+**근거.**
+
+1. 이 컨트롤은 `aria-pressed`가 있는 진짜 토글 버튼이 아니라 평범한 버튼이다(눌렀다 뗀
+   자국이 남는 게 아니라 그때그때 동작만 일어난다). `aria-pressed` 없이 상태만 말하는
+   이름("비밀번호 숨겨짐")을 쓰면 사용자가 "그래서 눌러서 뭐가 되는가"를 추론해야 한다.
+2. 실제 참조 구현들(브라우저 내장 비밀번호 보기, 비밀번호 관리자, 접근성 가이드가 이
+   패턴을 설명할 때)이 일관되게 행동형 문구("Show password"/"Hide password")를 쓴다 —
+   상태형 문구를 쓰는 참조 구현을 찾지 못했다.
+3. 이 저장소에 이미 있는 비슷한 자리도 행동/다음 상태 쪽이다 — `LoadMore`의 트리거
+   라벨은 "지금 안 불러와짐"이 아니라 "더 보기"(누르면 할 일)를 말하고,
+   `play`/`pause`처럼 서로 다른 아이콘 이름이 지금 상태가 아니라 누르면 일어날 동작을
+   가리킨다(`semanticIconNames`).
+
+**타입으로 강제한 지점.** `PasswordToggleAccessibleNameInfo`는 `revealed`가 아니라
+`willReveal`(= `!revealed`)을 담아 제품에 넘긴다. 필드 이름을 "현재 상태"로 지어
+어차피 뒤집어야 하는 계산을 제품 composer 안에 숨기지 않고, 호출부(`resolvePasswordFieldDescriptor`)에서
+미리 뒤집어 건넨다 — Steps/Timeline/Carousel/Tree가 이미 하는 "제품이 어순·조사를
+조립하되 계산은 HJM이 미리 한다"는 원칙과 같다. 아이콘도 같은 논리로
+`concealed → visibility`(누르면 보임), `revealed → visibilityOff`(누르면 숨김)로 매칭했다
+— 이름과 아이콘이 서로 다른 근거로 다른 결론에 도달하지 않는다.
+
+## 값은 절대 바뀌지 않는다
+
+`resolvePasswordFieldDescriptor`는 값을 파라미터로도 받지 않는다 — 받을 수 없으니
+바꿀 수도 없다. `passwordFieldBehavior.controlled`는 `value`/`onValueChange`와 `revealed`/
+`onRevealedChange`를 **서로 다른 두 triplet**으로 나열한다(같은 자리 하나로 합치지
+않는다) — Carousel의 `currentKey`(정체성)와 `position`(발화)을 분리한 것과 같은 이유로,
+"토글이 표시 방식만 바꾼다"는 것을 상태 축 자체로 증명한다.
+
+## 자동완성 힌트: 계약은 만들지만 값은 제품이 정한다
+
+`autofillHint: "current" | "new"`는 필수 필드다. HJM이 로그인 화면인지 가입/비밀번호
+변경 화면인지 판단할 방법이 없고, 잘못 추측하면(로그인 화면에 "새 비밀번호" 힌트를
+주는 식) 브라우저/OS의 자동완성 제안을 실제로 망가뜨린다 — 그래서 제품이 명시적으로
+결정해서 넘긴다. 반면 각 플랫폼의 **정확한 속성 이름**(Web `autocomplete` 토큰, iOS
+`textContentType`, Android autofill 힌트)은 여기서 문자열로 고정하지 않는다 — 이 값들은
+RN 버전에 따라 이름이 바뀐 적이 있고, 이 패키지는 런타임 의존성이 없어 그 사실을
+검증할 방법이 없다(`docs/architecture.md`의 "런타임 의존성 금지" 원칙). 렌더러가 자기
+플랫폼의 현재 API로 `current`/`new` 두 값 중 하나를 골라 번역한다 — Icon의 semantic
+name → 실제 글리프 번역과 같은 경계다.
+
+## 강도 표시(strength meter)는 넣지 않는다
+
+비밀번호 강도 판정은 보안 정책이고, 정책은 제품(또는 서버)마다 다르며 일반화된 "이
+정도면 강하다" 계산을 이 패키지가 갖고 있을 이유가 없다. 강도를 보여주고 싶은 제품은
+Field가 이미 가진 `description`/`hint` 슬롯에 자기 문구를 채우면 된다 — 새 상태 축이
+필요 없다.
+
+## HJM 기본값
+
+- `frame`/`support`는 `fieldFrameContract`/`formSupportContract` 그대로.
+- toggle 자리는 SearchField의 clear 버튼과 같은 자리·같은 hit target
+  (`control.minTouchTarget`)을 쓴다 — 필드 안에 있는 보조 버튼이라는 점에서 같은 문제다.
+
+## 플랫폼 번역
+
+- Web: `<input type={webInputType}>`(`text`/`password`) — `resolvePasswordFieldDescriptor`가
+  `revealed`로부터 유도한다. 토글은 SearchField의 clear 버튼처럼 필드 뒤에 오는 별도
+  tab stop이다(architecture.md의 "선택 행 안에 또 다른 button을 넣지 않는다"는 규칙은
+  선택 목록 행에 대한 것이고, Field의 trailing action에는 이미 SearchField가 선례로
+  적용된다).
+- Native: `secureTextEntry={nativeSecureTextEntry}`(= `!revealed`).
+
+## 공개한 축 / 배제한 축
+
+| 축 | 상태 |
+| --- | --- |
+| `revealed`(controlled) | 공개 |
+| `autofillHint`(필수 입력) | 공개 — 값은 제품, 플랫폼 번역표는 문서로만(코드로 단정하지 않음) |
+| `value`/`onValueChange` | Field 재사용, 새로 정의 안 함 |
+| 강도 표시 | **배제** — 보안 정책은 제품 몫 |
+
+## 검증 화면
+
+아직 없음. `planned → beta` 승격은 실제 제품 vertical slice 이후 리드가 진행한다.

package/docs/popover.md

@@ -0,0 +1,124 @@
+# Popover contract
+
+## 문제
+
+트리거에 붙어 뜨는 표면 중, plain text 보충 설명(Tooltip)도 아니고 항목 목록
+(Menu)도 아닌 **임의의 interactive 콘텐츠**(작은 폼, 링크가 섞인 본문, 여러
+control이 섞인 레이아웃)를 보여줘야 하는 자리가 있다. `docs/dropdown.md`가
+이미 이 문제를 `Popover`의 이름표로 예약해 두었다 — Dropdown을 "임의 콘텐츠"용
+으로 다시 정의하는 대신, 그 문제를 여기서 계약한다.
+
+## Tooltip · Menu · Popover 삼각 경계 (판정)
+
+세 컴포넌트는 모두 "트리거에 붙는 floating surface"라는 같은 anatomy를 공유하지만
+콘텐츠 종류와 focus 계약이 다르다.
+
+| | Tooltip | Menu | Popover |
+| --- | --- | --- | --- |
+| 콘텐츠 | 현지화된 plain text 한 문장 | stable id를 가진 action/선택 항목 목록 | 임의의 interactive 콘텐츠(폼, 링크, 혼합 레이아웃) |
+| focus가 surface 안으로 들어가는가 | **아니오** — `docs/tooltip.md`: "tabbable descendant가 없다" | 예 — 항목에 roving/activate focus | **예** — 결정적 차이 |
+| dismiss 계기 | hover/focus 해제, Escape, sibling 전환 | 선택, Escape/back, outside | close action, outside pointer, **outside-focus**(Tab이 surface 밖으로 나감), Escape |
+| trigger 상호작용 | hover(지연) + focus(즉시) | click/Enter/Space로 열림, 방향키로 탐색 | **click/Enter/Space만** — content가 interactive라 hover로 열고 hover로 유지하는 Tooltip 모델을 재사용하면 키보드·터치 사용자가 content에 도달하기 전에 닫히는 경쟁이 생긴다 |
+| positioning | 제품 renderer의 비공개 `AnchoredOverlay` | 같은 anatomy(`menuRecipe`)가 이미 소유 | Tooltip과 동일하게 비공개 `AnchoredOverlay`에 위임 — 새 portal/flip/shift API를 만들지 않는다 |
+
+`docs/tooltip.md`가 그은 경계("interactive Popover로 확장하지 않는다")를
+Popover가 정확히 이어받는다 — Tooltip이 멈춘 자리에서 focus가 surface 안으로
+들어가는 순간 계약이 달라지고, 그 한 가지 사실에서 나머지 전부(비-hover
+트리거, 명시적 dismiss 어휘, focus 복귀)가 따라 나온다.
+
+Menu와 구분되는 지점은 콘텐츠 형태다. Menu는 Collection 기본 계약(stable id,
+label/textValue, selection mode)을 따르는 항목 **목록**이고 그 role/keyboard
+표는 `behaviorRegistry.menu`가 이미 완결했다. Popover는 그 계약을 만족하지
+않는, 목록이 아닌 콘텐츠를 위한 자리다. 제품이 실제로 액션 목록을 띄우려는
+것이라면 그것은 Popover가 아니라 Menu다.
+
+## ConfirmPopover는 별개로 만들지 않는다 (판정, 한 줄)
+
+catalog에 별도 `planned` 항목으로 있는 `ConfirmPopover`(antd `Popconfirm`,
+`relationship: "adapted"`)는 이 Popover 위의 **조합**이다 — Popover의 anchored
+비-모달 surface에 AlertDialog의 `idle → busy → error/closing → closed` confirm
+session(`docs/architecture.md`의 "위험 확인의 생명주기")을 얹은 것이지, 셋째
+독립 primitive가 아니다. 지금은 만들지 않는다: 이 판정만 남긴다.
+
+## 일반화한 계약
+
+### Open state
+
+`PopoverOpenState`는 Tooltip과 같은 `open`/`defaultOpen`/`onOpenChange`
+discriminated union이다. `onOpenChange`는 `reason`을 `trigger` 또는
+구체적인 dismiss reason 중 하나로 보고한다 — Sheet가 dismiss reason을 추측하지
+않고 값으로 보고하는 것과 같은 이유(`SheetOpenChangeDetails`).
+
+### Dismiss 어휘와 정책
+
+`PopoverDismissReason`은 `close-action | outside-pointer | outside-focus |
+escape | programmatic`이다. `SheetDismissReason`과 다른 점 둘:
+
+- `back`/`swipe`가 없다 — Popover는 web 전용이고 native 뒤로가기·스와이프
+  표면이 아니다.
+- `outside-pointer`와 `outside-focus`를 분리한다 — Popover는 Dialog/Sheet처럼
+  모달이 아니므로 Tab이 surface 밖으로 정당하게 나갈 수 있고, 그 키보드
+  이탈은 포인터로 바깥을 클릭하는 것과 다른 입력 양식이라 정책으로 따로
+  켜고 끌 수 있어야 한다.
+
+`PopoverDismissPolicy`는 `dismissible`, `outsideDismiss`, `escapeDismiss`,
+`focusOutDismiss` 네 값이다. `busy` 축은 없다 — Sheet/AlertDialog와 달리
+Popover는 모달이 아니라 "모든 dismiss를 막는 전역 상태"가 성립하지 않는다.
+콘텐츠 안의 폼이 제출 중 Escape를 무시하고 싶다면 그것은 콘텐츠 레벨의
+판단이지 Popover 계약의 축이 아니다. `canDismissPopover`는 `canDismissSheet`와
+같은 모양으로 controlled owner의 `programmatic` 닫힘은 항상 허용한다.
+
+### Positioning은 소유하지 않는다
+
+`docs/tooltip.md`의 "Positioning boundary"를 그대로 재사용한다. HJM은
+preferred placement(`top|bottom|start|end`), align(`start|center|end`),
+arrow 크기, spacing, collision padding, motion만 소유한다. DOM 측정, portal,
+flip/shift, RTL 논리 방향 변환은 제품 Web renderer의 비공개 `AnchoredOverlay`가
+소유하며 이 모듈은 그 도구를 공개 API로 노출하지 않는다 — Tooltip이 세운
+"이 내부 도구를 catalog의 public Popover로 노출하지 않는다"는 경계를 Popover
+자신이 어기지 않는다.
+
+## HJM 기본값
+
+- `placement` 기본값 `bottom`, `align` 기본값 `start` — Tooltip(`top`/`center`)
+  과 의도적으로 다르다. Popover 콘텐츠는 Menu처럼 아래로 펼쳐지는 목록형
+  레이아웃을 담는 경우가 많아 Menu의 시각적 관성(아래로 열림)에 더 가깝다.
+- `accessibilityLabel`은 선택 사항이다. 대부분의 Popover 콘텐츠는 자체 heading을
+  가지므로 그것이 surface의 접근 가능한 이름이 된다. heading이 없는 콘텐츠만
+  명시적으로 공급한다 — 기본값을 발명하지 않는다(Tooltip이 `content`를 필수로
+  요구하는 것과 반대로, Popover는 콘텐츠 자체를 타입으로 갖지 않으므로 대신
+  이 escape hatch만 둔다).
+- trigger는 click/Enter/Space로만 연다. hover는 열지 않는다 — 위 삼각 경계
+  표의 이유와 동일하다.
+
+## 플랫폼 번역
+
+- Web: surface는 `role="dialog"`(비모달, `aria-modal` 없음), trigger는
+  `aria-haspopup="dialog"`와 `aria-expanded`를 합성한다. 열릴 때 초기 focus는
+  콘텐츠의 첫 focusable 요소로 이동하고(없으면 콘텐츠 root, `tabIndex={-1}`),
+  모든 dismiss 경로 이후 focus는 trigger로 복귀한다. Escape·outside pointer·
+  focus가 surface 밖으로 나감 세 경로 모두 이 복귀 규칙을 따른다.
+- Native: 이 컴포넌트는 `platform: web`이다 — `docs/expansion-roadmap.md`
+  Batch 3에 `web`으로만 분류되어 있고, Native adaptive 대응(예: bottom sheet로
+  펼치는 대안)이 필요해지면 그때 별도 적응 계약을 연다.
+- Reduce Motion: Tooltip과 같은 enter/exit preset(`motionPreset.enter/exit`)을
+  재사용하며 이동 없는 opacity로 대체한다.
+
+## 공개한 축 / 배제한 축
+
+| 축 | 상태 |
+| --- | --- |
+| `open` (controlled/uncontrolled) | 공개 |
+| dismiss reason(`close-action`/`outside-pointer`/`outside-focus`/`escape`/`programmatic`) | 공개 |
+| `placement`/`align` | 공개(Tooltip과 같은 값 집합) |
+| `busy`(모든 dismiss 차단) | **배제** — 비모달이라 전역 차단 상태가 성립하지 않는다 |
+| hover trigger | **배제** — focus가 콘텐츠 안으로 들어가는 계약과 hover 열기/유지가 경쟁한다 |
+| portal/flip/shift 공개 API | **배제** — Tooltip의 `AnchoredOverlay` 경계를 그대로 상속 |
+| content 데이터 모델 | **배제** — 런타임 의존성 금지 원칙상 React 콘텐츠 타입을 이 패키지가 가질 수 없다. 콘텐츠 자체는 항상 제품/렌더러 소유다 |
+
+## 검증 화면
+
+아직 없음. `planned → beta` 승격은 실제 제품 vertical slice 이후 리드가
+진행한다. 유력 후보는 필터·정렬 옵션처럼 여러 control이 섞인 작은 패널이며,
+단순 action 목록이면 그것은 Popover가 아니라 이미 beta인 Menu를 먼저
+검토해야 한다.