@hjmds/design-contracts 1.12.1 → 1.13.0

package/docs/usage/components/activity-heatmap.md

@@ -0,0 +1,104 @@
+# ActivityHeatmap
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Activity heatmap](../../activity-heatmap.md), descriptor `resolveActivityHeatmap`(`src/activity-heatmap.ts`)
+- 스토리북: `배포/컴포넌트/데이터 표시/활동 히트맵`
+
+## 언제 쓰나
+
+최대 1년(366일) 범위의 일별 활동량을 한눈에 보여 주는 읽기 전용 개요에 쓴다. 프로필의 기록 빈도,
+습관 달성 일수 같은 화면이다. 카탈로그 계약이 아닌 별도 보조 기능(supplemental)이다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 날짜를 고르거나 일정 보기 | [Calendar](calendar.md), [DatePicker](date-picker.md) |
+| 366일보다 긴 기록 | 제품이 범위를 나눠 페이지로 보인다(한 번에 넘기면 throw) |
+| 숫자 하나의 요약 | [Statistic](statistic.md) |
+| 시간 순 사건 목록 | [Timeline](timeline.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ActivityHeatmap` | 기본(supplemental, granular subpath만) | `@hjmds/react/activity-heatmap` | `@hjmds/react-native/activity-heatmap` |
+| `ActivityHeatmapDescriptor` 타입 | 보조(입력 descriptor) | `@hjmds/design-contracts/activity-heatmap` | 같음 |
+
+root entry에서는 export되지 않는다. `ActivityHeatmaps` 같은 복수형 공개 이름은 없다.
+optional peer는 필요 없다(Native는 `react-native` 기본 View·ScrollView만 쓴다).
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ActivityHeatmap } from "@hjmds/react/activity-heatmap";
+
+<ActivityHeatmap
+  label={t("profile.activity.label")}
+  descriptor={{ startDate: "2026-01-01", endDate: "2026-12-31", days }}
+  formatDay={(date, value) =>
+    value === null ? t("profile.activity.unknown", { date }) : t("profile.activity.day", { date, count: value })}
+  view={view}
+/>
+```
+
+```tsx
+// Native
+import { ActivityHeatmap } from "@hjmds/react-native/activity-heatmap";
+
+<ActivityHeatmap
+  label={t("profile.activity.label")}
+  descriptor={{ startDate: "2026-01-01", endDate: "2026-12-31", days, weekStartsOn: 0 }}
+  formatDay={(date, value) =>
+    value === null ? t("profile.activity.unknown", { date }) : t("profile.activity.day", { date, count: value })}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | `string` | 필수 | 영역 접근성 이름 |
+| `descriptor` | `{ startDate, endDate, days, thresholds?, weekStartsOn? }`(`ActivityHeatmapDescriptor`) | 필수 | 날짜는 `YYYY-MM-DD`, 범위 1~366일 |
+| `formatDay` | `(date: string, value: number \| null) => string` | 필수 | 칸 접근성 이름·hover `title`·list 문구. `null`은 미상 |
+| `view` | `grid` · `list` | `grid` | list는 같은 정보를 보이는 문구로 나열한다. 전환 버튼은 제품이 [Button](button.md)으로 둔다 |
+| descriptor `thresholds` | 양수이고 증가하는 세 수 `[number, number, number]` | `[1, 3, 7]` | 0보다 크면 4단계 세기로 나뉜다 |
+| descriptor `weekStartsOn` | `1`(월요일) · `0`(일요일) | `1` | — |
+| descriptor `days` | `{ date: string, value: number }[]`(`ActivityDay`) | — | 목록에 없는 날은 `formatDay`에 `null`(미상, 점선 테두리)로 온다. 명시한 `0`은 0이다. 둘 다 중립 면 색이다 |
+| Web `layoutStyle` | margin·width·flex·`alignSelf` | — | 바깥 배치 전용. Native는 없다(바깥 wrapper) |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 칸 16×16(Web `1rem`, Native `spacing.md`), 7행(요일) × 주 수 열. 366일이면 53열 × 20 − 4 = 1056 폭이다. 칸은 터치 대상이 아니다(44 미만) | `react/src/activity-heatmap.tsx`, `react-native/src/activity-heatmap.tsx` |
+| 간격 | 칸 사이 `spacing.xxs` 4. 위 제목·범례 블록과는 `layout.contentGap` 16 | 같은 파일, `foundations.ts` `layout` |
+| 순서·정렬 | 제목·범례·보기 전환 버튼은 제품이 Heatmap 위에 둔다. 칸은 위→아래 요일, 시작→끝 주 순서다 | `design-contracts/src/activity-heatmap.ts`(`row`·`column`) |
+| 고정·스크롤 | 화면 폭보다 넓으면 컴포넌트 자체가 가로 스크롤한다(Web `overflow-x: auto` 영역, Native `ScrollView horizontal`). 바깥에서 폭을 줄이거나 칸 크기를 덮지 않는다 | 같은 renderer 파일 |
+| 좁은 폭·큰 글자 | 칸 크기는 글자 크기를 따라 커지지 않는다. 날짜별 행동·큰 글자 사용자에게는 `view="list"` 전환을 제공한다 | 같은 renderer 파일 |
+
+## 꼭 지킬 것
+
+- `label`과 `formatDay`는 i18n 문구로 넣고 `value === null`을 따로 처리한다. 색만으로 값을 전하지 않는다.
+- 날짜는 `YYYY-MM-DD`이고 범위 안에서 고유해야 한다. 값은 유한한 0 이상. 어기면 렌더 중 throw다.
+- 세기 색은 테마의 brand semantic 색이 정한다. 제공자별 색·데이터 fetch는 들어 있지 않다(제품 소유).
+- 배치는 Web `layoutStyle`, Native는 바깥 wrapper로 한다. 칸 크기·색을 덮는 스타일 통로는 없다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| grid 넘침 | 가로 스크롤 region(`tabIndex=0`) | 가로 `ScrollView` |
+| 값 확인 | 셀 접근성 이름 + hover `title` | 셀 접근성 이름 |
+| list 길이 | 페이지 흐름 | 세로 `ScrollView`는 host가 감싼다 |
+| 배치 prop | `layoutStyle` | 없음(바깥 wrapper) |
+
+## 함정
+
+- grid 셀은 읽기 전용이라 눌러서 상세로 가는 동작이 없다. 셀 단위 상호작용이 필요하면 계약 공백으로 올린다.
+- 실기기 렌더와 VoiceOver 청취 순회는 아직 검증되지 않았다([계약 문서](../../activity-heatmap.md)).

package/docs/usage/components/affix.md

@@ -0,0 +1,86 @@
+# Affix
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Affix — Web 상단 고정](../../affix.md), `affixRecipe`(`src/affix.ts`)
+- 스토리북: `배포/컴포넌트/기반 기능/고정 배치`
+
+## 언제 쓰나
+
+Web에서 스크롤하는 동안 요약·필터·저장 버튼 같은 작은 영역을 가장 가까운 스크롤 조상의 상단에
+붙여 두고, 부모가 끝나면 함께 풀리게 할 때 쓴다. CSS sticky라 원래 DOM 자리와 초점·입력값이 유지된다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 화면 하단에 고정된 주 행동 | [BottomCTA](bottom-cta.md) |
+| 화면 상단 앱 바·제목 | [TopBar](top-bar.md), [Top](top.md) |
+| 페이지 안 섹션 목차 | [Anchor](anchor.md) |
+| 떠 있는 주 행동 | [FloatingActionButton](floating-action-button.md) |
+| Native 화면 | 없음. Native renderer에는 Affix가 없다 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Affix` | 기본(root entry에 없다) | `@hjmds/react/affix` | 없음 |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Affix } from "@hjmds/react/affix";
+import { Button } from "@hjmds/react/actions";
+
+<Affix offset={16} onChange={setPinned}>
+  <Button onClick={save}>{t("form.save")}</Button>
+</Affix>
+```
+
+Native 사용 예는 없다(renderer 없음).
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `offset` | 유한한 0 이상의 CSS px | `0` | 스크롤 조상 상단에서 띄울 거리. 아니면 `TypeError` |
+| `disabled` | `boolean` | `false` | 고정을 끄고 일반 흐름으로 둔다. 자식은 재마운트되지 않는다 |
+| `onChange` | `(affixed: boolean) => void` | — | 최초 측정 결과와 이후 붙음↔풀림 전환 때만 호출된다(스크롤마다 호출하지 않는다) |
+| `layoutStyle` | margin·width·flex·`alignSelf` | — | sticky 상자의 배치 전용. `position`·`top`은 Affix가 소유한다 |
+| `children` | `ReactNode` | 필수 | 고정할 영역 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 자식이 정한다. Affix는 여백·높이를 더하지 않고 화면 배경(`--hjm-color-bg`)만 깔아 아래 내용을 가린다 | `.hjm-affix` |
+| 간격 | 스크롤 조상 상단에서 `offset`만큼 띄운다. 상단 바가 있는 화면은 그 높이를 준다(스토리는 `offset={8}`) | `react/src/affix.tsx`, `showcase/web/src/patterns/WebAdditions.stories.tsx` |
+| 순서·정렬 | 고정하려는 영역이 원래 있던 자리(DOM 순서)에 그대로 둔다. z-index를 지정하지 않으므로 뒤에 오는 positioned 요소와 겹치면 바깥 wrapper에서 쌓임 순서를 정한다(`layer.sticky` 100) | `react/src/affix.tsx`, `foundations.ts` `layer` |
+| 고정·스크롤 | 상단 sticky만 된다. 고정 구간은 부모 높이 안에서만 생기고 부모가 끝나면 함께 밀려 올라간다. 한 스크롤 영역에 Affix를 여러 개 두지 않는다 | `affixRecipe`(`edge: "top"`, `position: "sticky"`) |
+| 좁은 폭·큰 글자 | 자식이 스크롤 영역 높이 − `offset`보다 크면 고정하지 않는다(`data-oversize`). 좁은 폭·큰 글자에서는 자식을 한 줄 요약으로 줄인다 | `affixRecipe.oversize: "flow"` |
+
+```text
+스크롤 영역
+┌──────────────────────────────┐
+│ TopBar (고정, 높이 = offset)  │
+├──────────────────────────────┤ ← offset
+│ [필터 요약]      [저장]       │ ← Affix(붙은 상태)
+│ ↑ 스크롤 콘텐츠               │
+└──────────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 부모에 스크롤할 공간이 있어야 고정 구간이 생긴다. 부모의 overflow 설정이 sticky 기준을 바꾼다.
+- 자식의 의미·접근성 이름은 제품이 소유한다. Affix는 role이나 알림을 더하지 않는다.
+- `className`·`style` prop이 없다. 배치는 `layoutStyle`이나 `offset`으로 한다(`position`·`top`은 덮을 수 없다).
+- 상단 고정만 된다. 하단 고정·portal·여러 sticky 영역 충돌 조정은 없다.
+
+## 함정
+
+- 콘텐츠가 스크롤 영역 높이에서 `offset`을 뺀 값보다 크면 고정이 풀리고 일반 흐름으로 돌아간다
+  (`data-oversize`). 고정이 안 된다고 보이면 콘텐츠 높이부터 확인한다.

package/docs/usage/components/agreement.md

@@ -0,0 +1,129 @@
+# Agreement
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Agreement contract](../../agreement.md), `agreementRecipe`·`resolveAgreementState`(`src/agreement.ts`)
+- 스토리북: `배포/컴포넌트/입력/약관 동의`
+
+## 언제 쓰나
+
+가입·결제·서비스 시작 앞의 약관 동의 묶음에 쓴다. 전체 동의 한 줄, 필수/선택 항목, 항목별 전문
+보기가 한 덩어리로 움직이고, 제출 가능 여부(`satisfied`)를 HJM이 판정한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 법적 의미 없는 여러 선택 | [CheckboxGroup](checkbox-group.md) |
+| 동의 하나를 켜고 끄는 설정(마케팅 수신 등) | [Switch](switch.md), [Checkbox](checkbox.md) |
+| 로그인 화면 하단의 "계속하면 동의" 고지 | [AuthScreenLayout](auth-screen-layout.md)의 `footer` |
+| 약관 전문 표시 | 제품 화면·[Sheet](sheet.md)·[Link](link.md) (Agreement는 여는 경로만 가진다) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Agreement` | 기본 | `@hjmds/react`, `/agreement` | `@hjmds/react-native`, `/agreement` |
+| `AgreementDescriptor`·`AgreementState` 타입 | 보조(입력·파생 상태) | `@hjmds/design-contracts/components/agreement` | 같음 |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Agreement } from "@hjmds/react/agreement";
+
+<Agreement
+  descriptor={{
+    accessibilityLabel: t("signup.terms.group"),
+    allLabel: t("signup.terms.all"),
+    items: [
+      { id: "tos", label: t("signup.terms.tos"), required: true, detail: { label: t("common.view"), href: "/legal/terms" } },
+      { id: "marketing", label: t("signup.terms.marketing") },
+    ],
+  }}
+  requiredLabel={t("signup.terms.required")}
+  optionalLabel={t("signup.terms.optional")}
+  onStateChange={(state) => setCanSubmit(state.satisfied)}
+/>
+```
+
+```tsx
+// Native
+import { Agreement } from "@hjmds/react-native/agreement";
+
+<Agreement
+  descriptor={descriptor}
+  requiredLabel={t("signup.terms.required")}
+  optionalLabel={t("signup.terms.optional")}
+  onDetail={(id) => openTermsSheet(id)}
+  onStateChange={(state) => setCanSubmit(state.satisfied)}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `descriptor` | `{ accessibilityLabel, allLabel, items }`(`AgreementDescriptor`) | 필수 | 문구는 모두 i18n |
+| 항목 | `{ id, label, description?, disabled?, required?, detail?: { label, href? } }` | — | 필수이면서 `disabled`인 항목은 throw |
+| 항목 `required` | `boolean` | `false`(선택) | 필수 항목이 하나라도 비면 `satisfied`가 `false`다 |
+| 전체 동의 | tri-state(파생) | — | 저장되는 값이 아니라 개별 항목에서 파생한다. 비활성 항목은 분모에서 빠진다 |
+| `checkedIds` · `defaultCheckedIds` | `ReadonlySet<Id>` | 비제어 빈 Set | 제어·비제어. 목록에서 빠진 항목의 체크는 자동으로 버려진다(`reconcileAgreementSelection`) |
+| `onCheckedIdsChange` | `(ids: ReadonlySet<Id>) => void` | — | 체크 목록이 바뀔 때 |
+| `onStateChange` | `(state: AgreementState) => void`, `state` = `{ all: boolean \| "mixed", satisfied: boolean, missingRequiredIds: readonly Id[] }` | — | 마운트 때 초기 상태로 한 번, 그 뒤 체크를 바꿀 때마다 호출된다(마운트 호출은 미게시(1.12.1 이후)) |
+| `onDetail` | `(id: Id) => void` | — | 전문 보기. Web은 `detail.href`가 없을 때만 호출 |
+| `requiredLabel` · `optionalLabel` | `string` | 필수 | 행 끝 "(필수)"·"(선택)" 문구 |
+| `layoutStyle` | margin·width·flex·`alignSelf` | — | 바깥 배치 전용 |
+| Native `style` | — | — | deprecated — `layoutStyle` 또는 recipe(개발 모드 1회 경고, 다음 major 제거) |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 폭을 꽉 채운다. 전체 동의 줄 최소 44(`control.minTouchTarget`), 항목 줄 최소 44, [전문 보기] 높이 44, 체크 표시 16×16(`spacing.md`) | `agreementRecipe`, `collectionItemContract`, `.hjm-agreement__mark` |
+| 간격 | 전체 동의 ↔ 목록 `spacing.xs` 8. 전체 동의 안쪽 위아래 `spacing.sm` 12 · 좌우 `spacing.md` 16, 배경 `canvas`, 모서리 `radius.md` 12. 항목 좌우 `spacing.sm` 12, 체크↔라벨 `spacing.sm` 12, [전문 보기] 좌우 `spacing.xs` 8 | `agreementRecipe`, `.hjm-agreement*` |
+| 순서·정렬 | 가입·결제 화면에서 입력 필드 아래, 제출 버튼 바로 위. 안쪽은 [전체 동의] → 항목 목록, 항목은 체크·라벨이 시작 쪽, [전문 보기]가 끝 쪽, 설명은 라벨 아래 줄. 스토리는 Top → TextField → Agreement → 남은 필수 항목 안내(`role="status"`) → Button을 `Stack gap="md"`(16)로 쌓는다 | `showcase/web/src/patterns/Agreement.stories.tsx` |
+| 고정·스크롤 | Agreement는 스크롤 본문에 둔다. 하단에 고정할 제출 버튼은 [BottomCTA](bottom-cta.md)로 두고 `satisfied`가 `false`면 비활성 | 같은 스토리 |
+| 좁은 폭·큰 글자 | 라벨이 줄바꿈되고(`overflow-wrap: anywhere`) [전문 보기]는 끝 쪽에 남는다 | `.hjm-agreement__copy` |
+
+```text
+┌──────────────────────────────┐
+│ Top: 제목·설명                │
+│ [이메일 TextField]            │
+│ ┌──────────────────────────┐ │
+│ │ ☐ 전체 동의하기           │ │ ← all(canvas 배경)
+│ └──────────────────────────┘ │
+│  ☐ 이용약관 (필수)  전문 보기 │
+│  ☐ 마케팅 (선택)    전문 보기 │
+│    설명 한 줄                 │
+│ 남은 필수 항목 안내(status)   │
+│ [   가입하고 시작하기   ]     │ ← primary, satisfied 전 disabled
+└──────────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 제출 버튼은 `onStateChange`로 받은 `satisfied`만 읽는다. 남은 필수 항목 안내는 `missingRequiredIds`로 제품이 문장을 만든다.
+- `accessibilityLabel`·`allLabel`·항목 `label`·`requiredLabel`·`optionalLabel`은 모두 제품의 i18n 문구다.
+  빈 문자열, 빈 목록, 중복 id, 필수이면서 `disabled`인 항목은 throw다.
+- 약관 문구·링크 주소·법적 유효성·동의 기록 저장은 제품 소유다. HJM은 판정과 배치만 가진다.
+- 전문 보기 컨트롤은 체크박스와 별개이며 눌러도 체크되지 않는다. 같은 행에 다른 누름 영역을 덧붙이지 않는다.
+- 색·간격은 recipe가 정한다. 배치는 `layoutStyle`로만 한다. Native `style`은 deprecated다([소비 정책 §3](../../consumer-policy.md)).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 전문 열기 | `detail.href`가 있으면 `<a>`, 없으면 버튼이 `onDetail(id)` 호출 | `href`를 쓰지 않고 항상 `onDetail(id)` |
+| 배치 prop | `layoutStyle`(+`className`) | `layoutStyle`(`style`은 deprecated) |
+| `ref` | root `div`로 전달 | 없음 |
+
+## 함정
+
+- 1.12.1까지 `onStateChange`는 사용자가 체크를 바꿀 때만 호출돼, `defaultCheckedIds`로 필수 항목을 미리 채운 경우 첫
+  `satisfied`를 받지 못했다. 미게시(1.12.1 이후) 버전은 마운트 때 초기 상태를 한 번 알린다. 1.12.1에서는 제출 버튼의 첫 상태를
+  `resolveAgreementState(descriptor, checkedIds)`(`@hjmds/design-contracts/components/agreement`)로 직접 계산한다.
+  호출 횟수를 세는 코드는 마운트 1회가 늘어난다.

package/docs/usage/components/alert-dialog.md

@@ -0,0 +1,130 @@
+# AlertDialog
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `AlertDialogRequest`·`createAlertDialogSession`(`src/alert-dialog.ts`), recipe `alertDialogRecipe`, Popover와의 경계 [ConfirmPopover 결정](../../confirm-popover.md), Native 긴 문구 처리 [Dialog](../../dialog.md)
+- 스토리북: `배포/컴포넌트/오버레이/확인 대화상자`
+
+## 언제 쓰나
+
+삭제·결제·탈퇴처럼 되돌릴 수 없는 행동 직전의 확인(`mode="confirm"`)과, 사용자가 반드시 읽고
+닫아야 하는 짧은 알림(`mode="alert"`)에 쓴다. 비동기 확인 중 중복 누름·닫힘 차단·실패 문구를 세션이 소유한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 폼·자유 콘텐츠가 들어가는 모달 | [Dialog](dialog.md) |
+| 되돌릴 수 있는 가벼운 확인 | [Popover](popover.md), `InlineConfirm`([Button](button.md) 확장) |
+| 화면을 막지 않는 결과 알림 | [Toast](toast.md) |
+| 화면 안에 남는 안내 | [Notice](notice.md) |
+| 아래에서 올라오는 선택지 | [Sheet](sheet.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `AlertDialog` | 기본 | `@hjmds/react`, `/overlays` | `@hjmds/react-native`, `/overlays` |
+| `AlertDialogRequest` 타입 | 보조(문구·행동 descriptor) | `@hjmds/design-contracts/components/alert-dialog` | 같음 |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { AlertDialog } from "@hjmds/react/overlays";
+
+<AlertDialog
+  open={open}
+  onOpenChange={(next) => setOpen(next)}
+  request={{
+    mode: "confirm",
+    tone: "danger",
+    title: t("post.delete.title"),
+    description: t("post.delete.body"),
+    confirmLabel: t("post.delete.confirm"),
+    cancelLabel: t("common.cancel"),
+    onConfirm: () => deletePost(id),
+    fallbackErrorMessage: t("post.delete.failed"),
+  }}
+/>
+```
+
+```tsx
+// Native
+import { AlertDialog } from "@hjmds/react-native/overlays";
+
+<AlertDialog
+  open={open}
+  onOpenChange={(next) => setOpen(next)}
+  onResult={(result) => { if (result.outcome === "confirmed") router.back(); }}
+  request={request}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `request` | `{ mode, tone?, title, description, confirmLabel, cancelLabel?, onConfirm?, fallbackErrorMessage?, resolveErrorMessage? }`(`AlertDialogRequest`) | 필수 | `mode`에 따라 허용 key가 갈린다(아래) |
+| `request.mode` | `alert` · `confirm` | — | alert는 확인 버튼 하나, confirm은 취소 + 확인(`cancelLabel` 필수) |
+| `request.tone` | `attention` · `info` · `success` · `danger` | `attention` | `danger`는 `confirm` 모드에서만 허용된다(타입으로 막힌다) |
+| `request.onConfirm` | `() => void \| Promise<void>` | — | confirm 모드만. 주면 `fallbackErrorMessage: string`도 필수, 선택 `resolveErrorMessage: (error: unknown) => string` |
+| `open` · `defaultOpen` | `boolean` | 비제어 `false` | 제어가 기본 |
+| `onOpenChange` | `(open: boolean, detail: { reason: "trigger" \| "confirm" \| "cancel-action" \| "escape" \| "back" \| "programmatic" \| "interrupted" }) => void` | — | 닫힌 이유를 `detail.reason`으로 받는다 |
+| Native `onResult` | `(result: { outcome: "confirmed" } \| { outcome: "cancelled", reason }) => void` | — | 결과 한 번 |
+| 첫 초점 | — | — | `alert`는 확인, `confirm`은 취소 버튼 |
+| 닫기 | — | — | 바깥 누름으로 닫히지 않는다. Escape(Web)·뒤로(Native)는 취소로 끝난다. 처리 중(`busy`)에는 닫을 수 없다 |
+| `request.onConfirm` 실패 | — | — | 열린 채로 `resolveErrorMessage` 또는 `fallbackErrorMessage`를 보여 준다 |
+| Web `trigger` | `ReactNode` | — | 비제어면 필수 |
+| Web `size` | `small` · `medium` · `large` | `medium`(Dialog recipe) | — |
+| Web `modalPriority` | `number` | `0` | 높은 우선순위 모달이 뒤에 열린 낮은 모달 위에서 동작한다 |
+| Native `contentStyle` | 배치 key(margin·width·flex·`alignSelf`)만 | — | 색·radius·padding 등 시각 key는 deprecated(개발 모드 1회 경고, 다음 major에서 배치 key로 좁힘) |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | Web `size` `medium` `min(36rem, 100%)` · `small` 28rem · `large` 48rem, 최대 높이 `100dvh − 32`. Native는 recipe 기본 `small`로 최대 폭 320, 폭 100%. 아이콘 원 44(`control.minTouchTarget`). Native 행동 버튼 최소 폭 96 | `.hjm-alert-dialog`, `alertDialogRecipe`·`dialogRecipe.sizes`, `react-native/src/overlays.tsx` |
+| 간격 | 화면 가장자리와 최소 `spacing.md` 16. 안쪽 여백 `spacing.lg` 20(Web·Native small). 요소 사이 Web `spacing.sm` 12 · Native `dialogRecipe.content.gap` `spacing.md` 16. 행동 사이 `spacing.sm` 12, 세로로 쌓이면 `spacing.xs` 8. Native 버튼 좌우 `spacing.md` 16 | `.hjm-overlay`, `.hjm-alert-dialog__actions`, `alertDialogRecipe.actions` |
+| 순서·정렬 | 화면 가운데. 위→아래 [아이콘] → 제목 → 설명 → 오류 문구 → 행동. 행동은 끝 정렬 한 줄 [취소][확인]. 버튼 수는 `mode`가 정한다(alert 1 · confirm 2) | `.hjm-overlay`, `alertDialogRecipe.slots` |
+| 고정·스크롤 | 배경막(`backdrop.modal`)이 화면 전체를 덮고 하단 고정 바보다 위에 쌓인다(Web z-index `layer.modal` 900). 내용이 길면 대화상자 안에서 스크롤한다 | `.hjm-overlay`, `.hjm-alert-dialog` |
+| 좁은 폭·큰 글자 | 폭 < 600(`breakpoint.medium`)이면 행동을 세로로 쌓고 **확인이 위**에 온다(Web DOM은 [취소][확인] 유지). Native는 글자 배율 1.6 이상(`largeTextThreshold`)에서도 쌓는다 | `alertDialogRecipe.actions.stackBelow`·`stackedOrder`, `react-native/src/overlays.tsx` |
+
+```text
+넓은 폭                                  폭 < 600 또는 Native 큰 글자
+┌────────────────────────────┐           ┌──────────────────────┐
+│ (!)                        │           │ (!)                  │
+│ 제목                        │           │ 제목                  │
+│ 설명                        │           │ 설명                  │
+│ 오류 문구(실패 시)          │           │ [       삭제       ] │ ← confirm(위)
+│               [취소] [삭제]│           │ [       취소       ] │
+└────────────────────────────┘           └──────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- `title`·`description`·`confirmLabel`·`cancelLabel`·`fallbackErrorMessage`는 i18n 문구로 넣는다. 빈 문자열이면 `TypeError`.
+- `onConfirm`을 주면 `fallbackErrorMessage`도 필수다. 확인 버튼에 별도 Spinner를 얹지 않는다(세션이 `loading`을 그린다).
+- 열림은 제어(`open` + `onOpenChange`)로 두는 것이 기본이다. 비제어 Web은 `trigger`가 필수다.
+  Native는 제어/비제어를 마운트 뒤 바꾸면 throw한다.
+- 버튼 색·배치는 tone과 recipe가 정한다. Web은 `layoutStyle`이 없는 제외 대상(위치를 recipe가 고정)이고, `className`으로 색·radius를 덮지 않는다.
+  Native `contentStyle`에는 배치 key만 넣는다([소비 정책 §3](../../consumer-policy.md)).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 여는 요소 | `trigger`(선택, 비제어면 필수) | 없음. `open`/`defaultOpen`으로만 연다 |
+| 결과 콜백 | 없음(`onOpenChange` 사유 `confirm`/`cancel-action`/`escape`) | `onResult({ outcome })` |
+| 아이콘 | `icon` | 없음 |
+| 크기·우선순위·portal | `size`, `modalPriority`, `portalContainer` | 없음(RN `Modal` props 일부를 그대로 받는다) |
+| 초점 복귀 | `returnFocusRef`(없으면 trigger) | `returnFocusRef` |
+| 배치 prop | 없음(`layoutStyle` 제외 대상) | `contentStyle` 배치 key만 |
+
+## 함정
+
+- Native에서 매우 긴 확인 문구는 본문이 스크롤되도록 바뀌었지만 큰 글자 실기기 검증은 끝나지 않았다([Dialog](../../dialog.md)).
+  문구를 자르거나 글자 크기 상한으로 피하지 않는다.

package/docs/usage/components/anchor.md

@@ -0,0 +1,96 @@
+# Anchor
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Anchor — 같은 문서 안의 목차](../../anchor.md), `anchorRecipe`(`src/anchor.ts`)
+- 스토리북: `배포/컴포넌트/탐색/문서 내 바로가기`
+
+## 언제 쓰나
+
+Web의 긴 문서·가이드·약관에서 같은 페이지 안 섹션으로 이동하는 목차에 쓴다. 현재 읽는 섹션을
+실제 스크롤 위치로 계산해 `aria-current="location"`으로 표시하고, 클릭하면 대상 섹션에 초점을 옮긴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 다른 페이지·URL로 이동 | [Link](link.md) |
+| 상위 경로 표시 | [Breadcrumb](breadcrumb.md) |
+| 같은 자리의 화면 전환 | [Tabs](tabs.md) |
+| 앱 전역 탐색 | [Sidebar](sidebar.md), [BottomNavigation](bottom-navigation.md) |
+| 키보드 사용자를 본문으로 건너뛰기 | [SkipNav](skip-nav.md) |
+| Native 화면 | 없음. Native renderer에는 Anchor가 없다 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Anchor` | 기본 | `@hjmds/react`, `/anchor` | 없음 |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Anchor } from "@hjmds/react/anchor";
+
+<Anchor
+  label={t("guide.toc")}
+  offset={64}
+  items={[
+    { id: "start", label: t("guide.start") },
+    { id: "next", label: t("guide.next") },
+  ]}
+/>
+// 같은 문서에 <section id="start">, <section id="next">를 둔다.
+```
+
+Native 사용 예는 없다(renderer 없음).
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | `string` | 필수 | nav 접근성 이름 |
+| `items` | `{ id: string, label: string }[]` | 필수 | 한 개 이상, id 고유·공백 없음 |
+| `onNavigate` | `(id: string, event: MouseEvent<HTMLAnchorElement>) => void` | — | 기본 동작 전에 호출. `event.preventDefault()`면 HJM 스크롤·초점·history를 건너뛴다 |
+| `layoutStyle` | margin·width·flex·`alignSelf` | — | 바깥 배치 전용 |
+| `orientation` | `vertical` · `horizontal` | `vertical` | 좁은 폭에서 줄바꿈하고 label을 자르지 않는다 |
+| `offset` | 0 이상의 CSS px | `0` | 상단 고정 헤더 아래 남길 거리. 음수·비유한 값은 `RangeError` |
+| `historyMode` | `push` · `replace` · `none` | `push` | URL을 쓰면 안 되는 미리보기는 `none` |
+| `container` | `HTMLElement` · `null` | 생략(문서 스크롤) | `HTMLElement`면 그 영역 안만, `null`이면 ref를 기다리며 관찰하지 않는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 링크 안쪽 여백 `spacing.xs` 8. 링크 높이는 44를 보장하지 않으므로 터치 중심 화면에서는 항목을 줄이거나 [Tabs](tabs.md)를 검토한다 | `anchorRecipe.link`, `.hjm-anchor__link` |
+| 간격 | 항목 사이 `spacing.xxs` 4. 스토리는 Section 제목 아래 `Stack gap="md"`(16)로 [Anchor] → [본문 스크롤 영역]을 쌓는다 | `anchorRecipe.gap`, `showcase/web/src/patterns/Anchor.stories.tsx` |
+| 순서·정렬 | 가리키는 본문 앞에 둔다. 넓은 문서 화면은 `vertical`로 본문 옆 열, 좁은 폭은 `horizontal`로 본문 위. 현재 위치는 세로형 시작 쪽·가로형 아래쪽 2px 선(`stroke.strong`, `border.focus`) | `anchorRecipe.current`, `.hjm-anchor*` |
+| 고정·스크롤 | 스크롤 중에도 보이게 하려면 [Affix](affix.md)로 감싸고, 상단 고정 헤더가 있으면 `offset`을 그 높이로 맞춘다 | `getAnchorCurrentId`(`src/anchor.ts`) |
+| 좁은 폭·큰 글자 | 가로 목차는 줄바꿈되며 가로 스크롤을 만들지 않는다. label은 줄바꿈되고 잘리지 않는다 | `.hjm-anchor[data-orientation="horizontal"] .hjm-anchor__list`(`flex-wrap: wrap`) |
+
+```text
+넓은 폭                                 좁은 폭
+┌──────────┬────────────────────┐       ┌──────────────────────┐
+│ ▍시작하기 │ 본문 섹션(스크롤)   │       │ 시작하기 · 다음 단계  │ ← horizontal
+│  다음 단계│                    │       │ ▔▔▔▔▔▔              │
+│  (Affix) │                    │       │ 본문 섹션(스크롤)     │
+└──────────┴────────────────────┘       └──────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- `label`(nav 접근성 이름)과 항목 `label`은 i18n 문구로 넣는다. 빈 문자열이면 `TypeError`.
+- 항목 `id`는 공백 없는 HTML id이고 문서 안에서 고유해야 한다. 중복·빈 목록은 throw다.
+- 목차의 sticky 배치와 문서 레이아웃은 호스트가 소유한다. 고정이 필요하면 [Affix](affix.md)나 호스트 CSS로 감싼다.
+- 앱 라우터로 처리하려면 `onNavigate(id, event)`에서 `event.preventDefault()`를 호출한다.
+- 배치는 `layoutStyle`로 한다. `className`으로 현재 표시 색·선 굵기를 덮지 않는다([소비 정책 §3](../../consumer-policy.md)).
+
+## 함정
+
+- DOM에 대상이 없는 항목은 현재 위치 후보에서 빠지고 기본 href 동작을 한다. 지연 렌더 섹션은 삽입되면 자동으로 관찰된다.
+- modifier 클릭(새 탭 등)은 브라우저 기본 동작에 맡긴다. 스크롤·초점 이동이 일어나지 않는 것이 정상이다.
+- 중첩 트리 목차·제목 자동 수집은 없다. 항목은 호스트가 넘긴다.

package/docs/usage/components/aspect-ratio.md

@@ -0,0 +1,89 @@
+# AspectRatio
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [AspectRatio contract](../../aspect-ratio.md), recipe `aspectRatioRecipe`(`src/aspect-ratio.ts`)
+- 스토리북: `배포/컴포넌트/레이아웃/화면 비율`
+
+## 언제 쓰나
+
+이미지·동영상·지도처럼 늦게 로드되는 매체의 자리를 미리 잡아 레이아웃 흔들림을 막을 때 쓴다.
+폭은 부모를 채우고 높이는 비율로 정해진다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 이미지 로드·실패 상태까지 다룸 | [Image](image.md) (비율 틀이 필요하면 AspectRatio 안에 넣는다) |
+| 아이콘·이미지·Lottie를 같은 정사각 액자에 맞춤 | [Asset](asset.md) |
+| 프로필 사진 | [Avatar](avatar.md) |
+| 비율이 아닌 고정 폭 컬럼 | [Grid](grid.md), [Container](container.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `AspectRatio` | 기본 | `@hjmds/react`, `/layout` | `@hjmds/react-native`, `/primitives` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { AspectRatio } from "@hjmds/react/layout";
+
+<AspectRatio ratio="wide">
+  <img src={cover.url} alt={t("post.coverAlt")} style={{ objectFit: "cover" }} />
+</AspectRatio>
+```
+
+```tsx
+// Native
+import { Image } from "react-native";
+import { AspectRatio } from "@hjmds/react-native/primitives";
+
+<AspectRatio ratio="landscape">
+  <Image source={{ uri: cover.url }} accessibilityLabel={t("post.coverAlt")}
+    style={{ width: "100%", height: "100%" }} resizeMode="cover" />
+</AspectRatio>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `ratio` | `square`(1) · `portrait`(3/4) · `landscape`(4/3) · `wide`(16/9) 또는 양의 유한수(가로/세로) | `wide` | 0·음수·`Infinity`는 `RangeError`, 모르는 preset 이름은 `TypeError`로 렌더 중에 거절한다. Web은 `data-ratio`에 preset 이름 또는 `custom`을 남긴다 |
+| `children` | `ReactNode` | — | 매체 하나 |
+| Web `layoutStyle` | margin·width·flex·`alignSelf` | — | 바깥 배치 전용. 비율·`width`는 덮지 않는다 |
+| Native `style` | `ViewProps["style"]` | — | layout primitive라 deprecated가 아니다. 배치 key만 넣는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 폭은 항상 부모를 꽉 채우고(`width: 100%`) 높이는 비율에서 나온다. AspectRatio에 높이를 주지 않는다. 자식은 틀을 100%×100%로 채운다 | `aspectRatioRecipe.sizing`, `.hjm-aspect-ratio`, `react-native/src/primitives.tsx` |
+| 간격 | 자체 여백이 없다. 카드 안 썸네일이면 카드의 안쪽 간격을 따른다 | `.hjm-aspect-ratio` |
+| 순서·정렬 | 카드·상세의 맨 위 매체 자리에 두고 제목·본문이 아래로 이어진다. 모서리는 감싸는 Card나 자식이 정한다 | `aspectRatioRecipe.slots` |
+| 고정·스크롤 | 고정 영역이 없다 | — |
+| 좁은 폭·큰 글자 | 비율은 그대로이고 높이만 줄어든다. 세로가 긴 비율(`portrait`, `9 / 16`)은 화면 높이를 넘지 않도록 부모 폭을 제한한다 | `aspectRatioRecipe.ratios` |
+
+## 꼭 지킬 것
+
+- 대체 텍스트, `object-fit`/`resizeMode`, 모서리, 로딩·오류 표시는 자식과 제품이 소유한다. 틀은 비율만 보장한다.
+- 숫자 비율은 가로/세로다. 9:16 세로 영상은 `9 / 16`이다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 구현 | CSS `aspect-ratio` | `ViewStyle.aspectRatio` + `width: "100%"` |
+| 자식 크기 | CSS가 직계 자식을 틀 크기로 늘린다 | 늘리지 않는다. 자식에 `width/height: "100%"`나 `flex: 1`을 준다 |
+| 추가 props | `div` 속성 전체(`className`, `style`) + `layoutStyle` | `View` 속성 전체(`style`). `layoutStyle` 없음 |
+
+## 함정
+
+- Native에서 `Image`에 크기를 주지 않으면 틀만 잡히고 그림이 보이지 않는다(위 표).
+- Web `style`에 `aspectRatio`를 넣으면 `ratio`를 덮는다(사용자 `style`이 뒤에 펼쳐진다). 비율은 `ratio`로만 주고 배치는 `layoutStyle`로 준다.
+  `layoutStyle`은 `aspectRatio`보다 먼저 펼쳐지므로 비율을 덮지 못한다.