@hjmds/design-contracts 1.12.1 → 1.13.1

package/docs/usage/components/select.md

@@ -0,0 +1,142 @@
+# Select
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [cross-platform core](../../cross-platform-core-normalization.md), [Native legacy 제거](../../migration-native-legacy-removal.md), `src/component-recipes.ts`(`selectRecipe`)
+- 스토리북: `배포/컴포넌트/입력/목록에서 선택`, `배포/컴포넌트/입력/단계별 선택`
+
+## 언제 쓰나
+
+폼 한 칸에서 여러 선택지 중 하나를 고르게 할 때 쓴다. 선택지가 많거나(대략 7개 이상),
+섹션으로 나뉘거나, 서버에서 비동기로 오거나, 화면에 펼쳐 둘 공간이 없을 때 맞다.
+Web은 popover listbox, Native는 modal sheet로 목록을 연다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 2~6개 선택지를 펼쳐서 비교, 항목마다 설명 | [RadioGroup](radio-group.md) |
+| 2~4개 짧은 보기 즉시 전환 | [SegmentedControl](segmented-control.md) |
+| 입력하며 후보를 거름 | [Combobox](combobox.md) |
+| 행동 목록(편집·삭제) | [Menu](menu.md) |
+| 여러 개 선택 | [CheckboxGroup](checkbox-group.md), [TransferList](transfer-list.md) |
+| Web 폼 제출·자동완성·모바일 브라우저 picker가 중요 | `NativeSelect`(아래) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Select` | 기본(커스텀 listbox / modal sheet) | `@hjmds/react`, `/forms` | `@hjmds/react-native`, `/forms` |
+| `NativeSelect` | 동반(브라우저 `<select>` 대안) | `@hjmds/react`, `/forms` | — |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Select } from "@hjmds/react/forms";
+
+<Select
+  label={t("profile.country.label")}
+  placeholder={t("profile.country.placeholder")}
+  emptySelectionLabel={t("profile.country.none")}
+  items={countries.map((c) => ({ id: c.code, label: t(c.nameKey), textValue: t(c.nameKey) }))}
+  selectedKey={country}
+  onSelectionChange={setCountry}
+/>
+```
+
+```tsx
+// Native
+import { Select } from "@hjmds/react-native/forms";
+
+<Select
+  label={t("profile.country.label")}
+  placeholder={t("profile.country.placeholder")}
+  dismissLabel={t("common.close")}
+  items={countries.map((c) => ({ id: c.code, label: t(c.nameKey), textValue: t(c.nameKey) }))}
+  selectedKey={country}
+  onSelectionChange={setCountry}
+/>
+```
+
+```tsx
+// Web
+// 대안 — 브라우저 기본 select
+import { NativeSelect } from "@hjmds/react/forms";
+
+<NativeSelect name="country" label={t("profile.country.label")}
+  options={[{ value: "kr", label: t("country.kr") }]} value={code} onValueChange={setCode} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `items` / `sections` | `readonly { id, label: string, textValue: string, description?, disabled? }[]` / 섹션 `{ id, label?, accessibilityLabel?, items }` | — | 항목 필수 필드는 `id`·`label`·`textValue`. Native는 `source`도 가능 |
+| `size` | `medium` · `large` | `medium` | 트리거 높이 44 · 52 |
+| `density` | `compact` · `comfortable` | `comfortable` | 선택지 행 44 · 56 |
+| `selectedKey` · `defaultSelectedKey` | 키 · `null` | 비제어 `null` | 제어하면 Web은 `onSelectionChange` 필수 |
+| `onSelectionChange` | `(key: Key \| null) => void` | — | 선택 해제 허용이 기본이라 `null`이 올 수 있다 |
+| `onSelectionAfterDismiss`(Native) | `(value: Key) => void \| Promise<void>` | — | sheet가 실제로 닫힌 뒤. 화면 이동·다른 modal은 여기서 |
+| `disallowEmptySelection` | `boolean` | `false` | — |
+| `asyncState` | `{ status: "idle" }` · `{ status: "loading" \| "loadingMore" \| "empty" \| "error", message: string }` | `{ status: "idle" }` | 비동기 상태를 그린다. 목록이 아직 없는 동안 선택된 항목은 `selectedItem` |
+| `open` · `defaultOpen` | `boolean` | 비제어 `false` | 제어하면 Web은 `onOpenChange` 필수 |
+| `onOpenChange` | `(open: boolean, reason) => void` | — | `reason`: `trigger` · `keyboard` · `selection` · `escape` · `outside` · `blur` · `programmatic` |
+| `renderLeading` | `(item \| null, appearance: { color, size }) => ReactNode` | — | 트리거 앞 아이콘(선택 없으면 `item`이 `null`). Web `color`는 `"currentColor"` |
+| `renderOptionLeading` | `(item, appearance: { color, size, selected, highlighted, disabled }) => ReactNode` | — | 선택지 앞 아이콘 |
+| `busy`, `readOnly`, `required`, `disabled` | `boolean` | `false` | `busy`는 포커스 순서를 유지한 채 조작을 막는다. `disabled`는 라벨과 트리거만 `selectRecipe.states.disabledOpacity`(0.5)로 흐리고 도움말·오류는 그대로 둔다([Field](field.md)). NativeSelect는 Field 기본값 0.6 |
+| `label` / `accessibilityLabel` | 문자열 | — | 둘 중 하나 필수 |
+| `layoutStyle` | 배치 전용 style 객체 | — | 필드 전체(라벨·트리거·설명) 배치. Web `style`은 트리거 버튼에 붙는다 |
+| `options`(NativeSelect) | `readonly { value: string; label: string; disabled? }[]` | 필수 | 브라우저 `<select>` 대안 |
+| `onValueChange`(NativeSelect) | `(value: string) => void` | — | 원시 `onChange`도 받는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 트리거 최소 높이 `medium` 44 · `large` 52, 폼 열 폭을 채운다(Web `inline-size: 100%`). 선택지 행 `comfortable` 56 · `compact` 44. Web 목록 최대 폭 420(`min(26.25rem, 100vw − 2×spacing.md)`)·최대 높이 360. Native sheet 최대 높이 75% | `fieldFrameContract.minHeight`, `control.buttonHeight.large`, `selectRecipe.density`·`popover`, `.hjm-select__listbox`, Native `forms.tsx` |
+| 간격 | 트리거 좌우 `medium` `spacing.md` 16 · `large` `spacing.lg` 20(recipe), 안쪽 요소 사이 `spacing.sm` 12. 라벨·설명·오류와 `spacing.xs` 8. Web 목록은 트리거에서 8 떨어지고 안쪽 여백 `spacing.xs` 8(`selectRecipe.popover.padding`; 2026-10-06까지 4, 1.12.1 이후 미게시), 화면 가장자리에서 8(`selectRecipe.popover.collisionPadding`). Native sheet 안쪽 `spacing.md` 16, 머리와 목록 사이 `spacing.sm` 12 | `selectRecipe.sizes`·`value.gap`, `formSupportContract.gap`, `selectRecipe.popover`(sideOffset 8, collisionPadding 8, padding 8), Native `forms.tsx` |
+| 순서·정렬 | 트리거: 앞 아이콘 → 값(넘치면 말줄임) → 펼침 표시. Web 목록은 트리거 아래·트리거와 같은 폭, 공간이 없으면 위로 뒤집힌다. Native sheet 머리는 제목 + 끝쪽 닫기 ×(44). 확인 버튼은 없고 항목을 누르면 선택하고 닫힌다 | `.hjm-select__trigger`, `select.tsx`(`matchAnchorWidth`), `CollectionSheetHeader` |
+| 고정·스크롤 | Web 목록은 `position: fixed` popover(z-index `layer.dropdown` 400), 넘치면 목록 안에서 스크롤. Native는 화면 아래에서 올라오는 modal sheet로 목록만 스크롤되고, 아래 여백에 안전 영역(`safeArea.bottom`)을 더한다. 배경(scrim)을 누르면 닫힌다 | `.hjm-select__listbox`, Native `Select`(Modal·ScrollView) |
+| 좁은 폭·큰 글자 | 트리거 높이는 최소값이라 큰 글자에서 늘어나고 값은 한 줄 말줄임이다. Web 목록 폭은 화면 폭 − 32를 넘지 않는다 | `.hjm-select__value`, `.hjm-select__listbox` |
+
+```text
+Web popover                         Native sheet
+라벨                                 ┌──────── scrim (누르면 닫힘) ────────┐
+┌──────────────────────┐            │                                     │
+│ 선택된 값          ⌄ │ 44         ├─────────────────────────────────────┤ radius.lg 16
+└──────────────────────┘            │ 정렬 기준                       (×) │ ← 머리, × 44
+  ↓ 8                               │   gap spacing.sm 12                 │
+┌──────────────────────┐            │ ┌─────────────────────────────────┐ │
+│ 최신순             ✓ │ 56         │ │ 최신순                        ✓ │ │ 56 ↕ 스크롤
+│ 인기순               │            │ │ 인기순                          │ │
+└──────────────────────┘ max 360    │ └─────────────────────────────────┘ │
+ 트리거 폭, max 420                  │ padding 16 + 안전 영역              │ max 75%
+                                    └─────────────────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 모든 문구(`placeholder`, Web `emptySelectionLabel`, Native `dismissLabel`)는 i18n 키로 넣는다. 비면 `TypeError`.
+- 항목이 0개인데 `asyncState`가 `idle`이면 오류를 던진다. 로딩·빈 결과는 `asyncState`로 알린다.
+  controlled 키가 목록에 없으면(그리고 `selectedItem`도 아니면) Native는 `RangeError`다.
+- 옛 Native `options`·`value`·`onValueChange`는 1.11에서 제거됐다. `items`/`selectedKey`/`onSelectionChange`를 쓴다.
+- Native 선택 후 화면 이동·다른 modal 열기는 `onSelectionAfterDismiss`에서 한다. sheet가 닫히기 전에
+  다음 modal을 띄우지 않는다.
+- 배치는 `layoutStyle`로 한다. Web `className`·`style`은 트리거 버튼에 붙는다. Native `style`은 deprecated(개발 모드 경고,
+  다음 major 제거)다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 목록 표면 | anchored popover(`align`, `portalContainer`) | modal sheet(`dismissLabel` 필수) |
+| 컬렉션 입력 | `items` 또는 `sections` | `source`·`items`·`sections` 중 정확히 하나 |
+| 선택 해제 항목 문구 | `emptySelectionLabel` 필수 | 없음 |
+| 재시도 | 없음 | `onRetry`, `retryLabel` |
+| 낭독 보조 | 없음 | `readOnlyLabel`, `openHint`, `optionsAccessibilityLabel` |
+| 키보드 | `loop`, typeahead(`locale`) | 해당 없음 |
+| `description`·`error` 타입 | `ReactNode` | `string` |

package/docs/usage/components/settings-screen.md

@@ -0,0 +1,126 @@
+# SettingsScreen
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screens.tsx`·`src/screen-flows.tsx`; 기존 개별 지침을 새 규격으로 통합. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/화면/설정/앱 설정`
+
+## 언제 쓰나
+
+앱의 설정 화면 전체에 쓴다. 제목, 선택적 프로필 영역, id가 있는 섹션 목록을 받아
+[ScreenLayout](screen-layout.md) 안에 [Section](section.md)으로 쌓는다. 섹션 안의 행은
+기존 ListRow·Switch·Select·Field를 그대로 넣는다.
+
+2026-09-23 소비 감사에서 제품마다 같은 설정 화면을 직접 조립하고 있었다. 제목·섹션 틀·구분선·
+상태 교체를 제품이 다시 만들지 않는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 섹션 구조가 아닌 일반 화면 | [ScreenLayout](screen-layout.md) |
+| 프로필 보기·편집 화면 | [ProfileScreen](profile-screen.md) |
+| 설정 한 항목을 편집하는 입력 패널 | [Sheet](sheet.md) |
+| 섹션 하나만 필요(다른 화면 안) | [Section](section.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `SettingsScreen` | supplemental. root에서는 내보내지 않는다 | `/screens` | `/screens` |
+
+## 최소 사용 예
+
+```tsx
+// Web — Switch는 /selection, ListRow는 /display, 행 이동은 onClick(또는 href)
+import { SettingsScreen } from "@hjmds/react/screens";
+import { Switch } from "@hjmds/react/selection";
+import { ListRow } from "@hjmds/react/display";
+
+<SettingsScreen
+  title={t("settings.title")}
+  sections={[
+    { id: "notifications", title: t("settings.notifications"), children: (
+      <Switch
+        presentation="row"
+        label={t("settings.push.label")}
+        description={t("settings.push.description")}
+        checked={pushEnabled}
+        onCheckedChange={setPushEnabled}
+      />
+    ) },
+    { id: "account", title: t("settings.account"), children: (
+      <ListRow title={t("settings.language")} description={currentLanguageName} onClick={openLanguageSheet} />
+    ) },
+  ]}
+/>
+```
+
+```tsx
+// Native — Switch는 /inputs, ListRow는 /data-display, 행 이동은 onPress
+import { SettingsScreen } from "@hjmds/react-native/screens";
+import { Switch } from "@hjmds/react-native/inputs";
+import { ListRow } from "@hjmds/react-native/data-display";
+
+<SettingsScreen
+  title={t("settings.title")}
+  sections={[
+    { id: "notifications", title: t("settings.notifications"), children: (
+      <Switch
+        presentation="row"
+        label={t("settings.push.label")}
+        description={t("settings.push.description")}
+        checked={pushEnabled}
+        onCheckedChange={setPushEnabled}
+      />
+    ) },
+    { id: "account", title: t("settings.account"), children: (
+      <ListRow title={t("settings.language")} description={currentLanguageName} onPress={openLanguageSheet} />
+    ) },
+  ]}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `sections` | `readonly { id: string; title: string; description?: string; children: ReactNode }[]` | 필수 | 각 항목을 Section 하나로 그린다. `id`는 안정적인 key |
+| `profile` | `ReactNode` | 없음 | 섹션 위 프로필 영역 |
+| 나머지 | `ScreenLayout`과 같음(`children`·`scroll` 제외) | — | `title` 필수, `state`·`stateAction`·`notice`·`footer`·`header`·`leading`·`actions`·`contentInset`. 화면 전체가 스크롤한다 |
+
+두 플랫폼 모두 섹션 내용 위에 1px 구분선을 그리고 회색 카드 배경은 쓰지 않는다(2026-10-05 사용자 결정).
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | ScreenLayout 폭(최대 720) 안에서 섹션을 세로로 쌓는다; 행 높이는 ListRow·Switch row 계약 | `ScreenLayout`, `Section` |
+| 간격 | 화면 padding `spacing.md` 16; `profile`·섹션 사이 `spacing.xl` 24; 섹션 제목–내용 `spacing.xs` 8, 제목–설명 `spacing.xxs` 4; 행 사이 간격은 없고 구분선 1 | Web·Native `SettingsScreen` `Stack gap="xl"`, `sectionRecipe` |
+| 순서·정렬 | 헤더(제목) → `notice` → `profile` → `sections` 순서대로 → `footer` | 렌더 순서 |
+| 고정·스크롤 | 헤더·footer 고정, 본문 화면 스크롤(`scroll` 고정 `"screen"`); 저장 실패는 `notice` | `ScreenLayout` |
+| 좁은 폭·큰 글자 | 섹션 제목·행 문구는 줄바꿈되고 자르지 않는다; 제목 열 최소 폭 120 × 글자 배율 | `.hjm-section` `overflow-wrap: anywhere`, `headerMinWidth` |
+
+## 꼭 지킬 것
+
+- **켜고 끄는 행은 `Switch presentation="row"`로 만든다.** label·description·checked·onCheckedChange를
+  넘기면 행 전체가 switch 하나다. Pressable·button·ListRow `onPress`로 다시 감싸지 않는다.
+  Web 기본은 `inline`, Native 기본은 `row`이므로 Web·Native 같은 화면에서는 `presentation`을 명시한다.
+- ListRow의 trailing에 Switch만 둘 때는 `labelVisibility="hidden"`을 쓰고 그 ListRow에는 `onPress`를 두지 않는다.
+- 현재 선택값(언어·테마)은 행 `description`에 두고, 선택은 [Select](select.md) 또는 [Sheet](sheet.md)로 연다.
+- 섹션 `id`는 안정적인 키로 둔다(번역 문구를 id로 쓰지 않는다).
+- 저장 방식·낙관적 갱신·실패 복구·탈퇴 확인은 제품과 [action-session](../../action-session.md)이 소유한다.
+  저장 실패는 `state`가 아니라 `notice`로 알린다.
+- 배치: Web·Native 모두 `layoutStyle`(Web은 `className`도 있다). 섹션 색·여백을 덮지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 섹션 구분 | Section(`hjm-settings-section`) 내용 위 1px 구분선(CSS) | Section + 내용 위 1px 구분선(`View`) |
+| 조각 import | `Switch` `/selection`, `ListRow` `/display` | `Switch` `/inputs`, `ListRow` `/data-display` |
+| Switch 기본 `presentation` | `inline` | `row` |
+| 행 이동 이벤트 | ListRow `href`/`onClick` | ListRow `onPress` |

package/docs/usage/components/shared-transition-element.md

@@ -0,0 +1,111 @@
+# SharedTransitionElement
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Optional interaction adapters · Shared screen transition](../../../../../docs/interaction-adapters.md#shared-screen-transition)(Native 전용, experimental, supplemental, 카탈로그 계약 없음), `packages/react-native/src/screen-transition.tsx`, 시연은 구성 스토리 `배포/구성/직접 조작과 모션/끌기·밀기·화면 전환` › 카드 확대와 화면 전환. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/구성/직접 조작과 모션/끌기·밀기·화면 전환`
+
+## 언제 쓰나
+
+목록의 카드(사진·썸네일)를 눌러 상세 화면으로 갈 때, 같은 요소가 두 화면 사이에서 확대·축소되어
+이어지는 공유 요소 전환에 쓴다. 출발 화면과 도착 화면에 **같은 `id`** 로 하나씩 둔다.
+[SharedTransitionScreen](shared-transition-screen.md), `useSharedTransitionOptions`, `createHjmTransitionStack`과
+한 묶음으로만 동작한다.
+
+2026-09-30 기준 포트폴리오 Expo 앱은 모두 expo-router 57을 React Navigation 없이 쓰므로 이 경로를
+쓸 수 있는 소비 앱이 아직 없다. 도입 전에 아래 전제를 모두 충족하는지 먼저 확인한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 같은 화면 안에서 내용만 바뀜 | [ContentTransition](content-transition.md) |
+| Web 화면 전환 | 없음. 제품 router를 쓴다 |
+| 한 화면 위에 보조 내용을 띄움 | [Sheet](sheet.md) |
+| expo-router만 쓰는 앱 | 제품 router 기본 전환 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `SharedTransitionElement` | 기본(공유 요소 경계) | — | `/screen-transition` |
+| `SharedTransitionScreen` | 동반(라우트 본문 감싸개) | — | `/screen-transition` |
+| `useSharedTransitionOptions` | 보조(화면 옵션 hook) | — | `/screen-transition` |
+| `createHjmTransitionStack` | 보조(stack navigator 생성) | — | `/screen-transition` |
+
+granular subpath로만 가져온다(root·barrel에 없음). 이 subpath는 아래 optional peer를 import 하며,
+없으면 tsc·테스트는 통과해도 기기 Metro 번들에서 죽는다.
+
+- 직접: `react-native-screen-transitions` 4.0.0, `@react-navigation/native` 7.4.1(HJM `peerDependencies`, optional).
+- 상위 라이브러리 요구: `react-native-gesture-handler`, `react-native-reanimated` 4, `react-native-worklets`,
+  `react-native-safe-area-context`.
+- 소비 앱 패키지 관리자에 [exports patch](../../../../react-native/docs/patches/react-native-screen-transitions.patch)를
+  등록해야 한다. HJM tarball이 patch를 대신 적용하지 않는다.
+
+## 최소 사용 예
+
+Web: 없음.
+
+```tsx
+// Native
+// 목록 화면과 상세 화면 양쪽에 같은 id
+import { SharedTransitionElement } from "@hjmds/react-native/screen-transition";
+
+<SharedTransitionElement id={`place-${place.id}`} accessibilityLabel={place.name}>
+  <PlacePhoto place={place} /> {/* 제품 콘텐츠 */}
+</SharedTransitionElement>
+```
+
+화면 옵션: `const options = useSharedTransitionOptions(\`place-${place.id}\`)`를 `createHjmTransitionStack()`이 만든
+`Stack.Screen`에 붙인다. 전체 예는 설계 문서의 Shared screen transition 절을 따른다.
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `id` | 문자열 | 필수 | 데이터의 안정 키. 빈 문자열이면 `TypeError` |
+| `children` | ReactNode | 필수 | 크기가 분명한 시각 요소 하나 |
+| `accessibilityLabel` | 문자열 | — | 경계의 접근성 이름 |
+| `style` | `StyleProp<ViewStyle>` | — | 경계 바깥 배치. 이 컴포넌트는 optional motion host frame이라 1.13 deprecated 대상에서 제외돼 있다 |
+| `useSharedTransitionOptions` | `(id: string) => ScreenTransitionConfig` | — | 도착 화면 `Stack.Screen` `options`에 붙인다. 동작 줄이기면 전환 시간 0·제스처 꺼짐 |
+| `createHjmTransitionStack` | `() => Stack` | — | `react-native-screen-transitions`의 blank stack navigator를 그대로 내보낸다 |
+
+Props는 `id`·`children`·`accessibilityLabel`·`style` 넷뿐이고 콜백은 없다.
+동작 줄이기가 켜지면 경계가 비활성화되고 화면 옵션의 전환 시간이 0, 제스처가 꺼진다.
+live-view handoff·clipping escape는 꺼져 있고 공개하지 않는다(`react-native-teleport` 불필요).
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 경계는 자체 크기·여백을 갖지 않는다. 크기는 `children`, 바깥 배치는 `style`이 정한다. 크기가 분명한 시각 요소 하나(사진·썸네일)만 감싼다. 전환이 경계의 측정 크기 사이를 확대·축소(`zoom`, target `bound`)하기 때문이다 | `screen-transition.tsx`(`Transition.Boundary`, `useSharedTransitionOptions`) |
+| 간격 | 간격 토큰 없음. 감싸는 레이아웃이 정한다 | — |
+| 순서·정렬 | 출발 화면(목록 카드의 사진)과 도착 화면(상세 상단의 큰 사진)에 하나씩, 같은 `id`로 둔다. 한 화면에 같은 `id`를 둘 이상 두지 않는다. 각 화면 본문은 [SharedTransitionScreen](shared-transition-screen.md)(`flex: 1`, 테마 배경) 안에 둔다 | `SharedTransitionScreen` |
+| 고정·스크롤 | 상세 화면은 아래로 쓸어내려 닫힌다(`gestureDirection: "vertical"`). 도착 화면 상단 사진 위에 세로 드래그 제스처를 겹치지 않는다 | `useSharedTransitionOptions` |
+| 좁은 폭·큰 글자 | 크기는 `children`을 따른다. 동작 줄이기에서는 전환 없이 바로 바뀐다 | `environment.reducedMotion` |
+
+```text
+목록 화면                          상세 화면
+┌──────────────────┐              ┌──────────────────┐
+│ ┌────┐ 장소 이름  │   zoom →     │ ┌──────────────┐ │
+│ │ id │ 설명       │              │ │      id      │ │ ← 같은 id
+│ └────┘            │   ← 아래로   │ └──────────────┘ │
+│ ┌────┐ …          │    쓸어 닫기  │ 본문 (제품)       │
+└──────────────────┘              └──────────────────┘
+```
+
+## 꼭 지킬 것
+
+- `id`는 데이터의 안정 키로 만든다. 빈 문자열이면 `TypeError`, 두 화면의 id가 다르면 전환이 맺히지 않는다.
+- 각 라우트 본문은 SharedTransitionScreen으로 감싼다. 남아 있는 이전 화면이 접근성·터치에 새지 않게 한다.
+- host와 어댑터가 같은 navigation 인스턴스를 써야 한다. pnpm에서 peer가 둘로 갈리면
+  `LinkingContext`/`DescriptorsStore` 오류가 난다.
+- 라우트 파라미터·포커스·스크롤 복원·navigation container는 제품 소유다.
+
+## 함정
+
+- patch 없이 설치하면 Expo TypeScript가 upstream `.tsx`를 읽어 오류가 수백 개 난다.
+  teleport 네이티브 뷰가 링크되지 않은 client에서는 patch가 없으면 `Unimplemented component: PortalHostView`가 났다.

package/docs/usage/components/shared-transition-screen.md

@@ -0,0 +1,86 @@
+# SharedTransitionScreen
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Optional interaction adapters · Shared screen transition](../../../../../docs/interaction-adapters.md#shared-screen-transition), `src/screen-transition.tsx`. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/구성/직접 조작과 모션/끌기·밀기·화면 전환`
+
+## 언제 쓰나
+
+`createHjmTransitionStack()`으로 만든 stack에서 공유 요소 전환을 쓸 때, **각 라우트 본문**을 감싼다.
+전환 뒤에도 출발 화면은 역방향 전환 기하를 위해 mount된 채 남는데, 이 감싸개가 포커스를 잃은 화면을
+접근성 트리와 터치에서 빼고, 테마 배경으로 불투명하게 칠해 전환 backdrop이 내용에 비치지 않게 한다.
+공유 요소 자체는 [SharedTransitionElement](shared-transition-element.md)가 맡는다.
+
+설치 전제(peer, exports patch, 단일 navigation 인스턴스)와 "현재 쓸 수 있는 소비 앱 없음"(expo-router 전용)은
+[SharedTransitionElement](shared-transition-element.md#공개-이름과-import)와 같다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 공유 요소 전환이 없는 stack | 감싸지 않는다 |
+| Web | 없음 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `SharedTransitionScreen` | 기본(라우트 본문 감싸개) | — | `/screen-transition` |
+| `SharedTransitionElement` | 동반(공유 요소 경계, 같이 씀) | — | `/screen-transition` |
+
+granular subpath로만 가져온다. `react-native-screen-transitions` 4.0.0과 `@react-navigation/native` 7.4.1
+(optional peer)이 설치돼 있지 않으면 기기 Metro 번들에서 죽는다.
+
+## 최소 사용 예
+
+Web: 없음.
+
+```tsx
+// Native — 라우트 컴포넌트마다
+import { SharedTransitionScreen, SharedTransitionElement } from "@hjmds/react-native/screen-transition";
+
+function PlaceDetail({ place }: Props) {
+  return (
+    <SharedTransitionScreen testID="place-detail">
+      <SharedTransitionElement id={`place-${place.id}`}>
+        <PlacePhoto place={place} />
+      </SharedTransitionElement>
+      <PlaceBody place={place} />
+    </SharedTransitionScreen>
+  );
+}
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` | ReactNode | — | 라우트 본문 |
+| `style` | `StyleProp<ViewStyle>` | `flex: 1` + 테마 `bg` 배경 | 배치용. optional motion host frame이라 1.13 deprecated 대상에서 제외돼 있다 |
+| 나머지 | React Native `ViewProps`(`testID` 등) | — | `pointerEvents`·`accessibilityElementsHidden`·`importantForAccessibility`는 덮어쓰인다 |
+| (포커스 상태) | `useIsFocused(): boolean` | — | 포커스가 없으면 `importantForAccessibility="no-hide-descendants"`, `accessibilityElementsHidden`, `pointerEvents="none"`을 건다 |
+
+콜백 prop은 없다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 라우트 영역 전체(`flex: 1`)를 채우고 테마 `bg`로 불투명하게 칠한다 | `src/screen-transition.tsx` |
+| 간격 | 자체 여백 없음. 화면 여백·안전 영역은 안쪽 화면 골격이 맡는다 | `src/screen-transition.tsx` |
+| 순서·정렬 | 라우트 컴포넌트의 가장 바깥 요소. 그 안에 [SharedTransitionElement](shared-transition-element.md)와 나머지 본문을 둔다 | — |
+| 고정·스크롤 | 스크롤하지 않는다. 스크롤 영역(ScrollView·FlatList)은 안쪽에 둔다 | `src/screen-transition.tsx` |
+| 좁은 폭·큰 글자 | 바뀌는 것 없음(부모 크기를 따른다) | — |
+
+## 꼭 지킬 것
+
+- React Navigation의 navigation context 안(host `NavigationContainer` 아래)에서만 렌더한다.
+  `useIsFocused`가 그 context를 요구한다.
+- `HjmNativeProvider` 아래에 둔다(테마 배경을 읽는다).
+- `style`은 배치용으로만 쓴다. 배경색을 덮으면 전환 중 backdrop이 내용에 비친다.
+- `pointerEvents`·`accessibilityElementsHidden`·`importantForAccessibility`를 직접 넘기지 않는다.
+  감싸개가 포커스 상태로 다시 덮어쓴다.

package/docs/usage/components/sheet.md

@@ -0,0 +1,157 @@
+# Sheet
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Sheet 입력 화면과 가용 영역](../../sheet.md), [optional adapters](../../optional-adapters.md)(Native 제스처 확장), `src/component-recipes.ts`(`sheetRecipe`), `src/sheet.ts`(`sheetBehaviorDefaults`)
+- 스토리북: `배포/컴포넌트/오버레이/시트`
+
+## 언제 쓰나
+
+현재 화면 위에 모달로 띄우는 보조 작업 패널에 쓴다. 설정 한 항목 편집, 선택 목록(테마·언어),
+짧은 입력 폼, 공유·사진 출처 선택처럼 끝나면 원래 화면으로 돌아오는 작업이다. 기본은 하단에서 올라온다.
+
+2026-09-23 소비 감사에서 제품마다 Sheet를 직접 조립하며 제목 정렬, 키보드 높이, top inset, 본문 maxHeight를
+따로 보정하고 있었다. 이 보정은 Sheet가 소유한다. 제품 wrapper에서 Modal·키보드 listener·강제 maxHeight를
+다시 만들지 않는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 짧은 확인·되돌리기 어려운 결정 | [AlertDialog](alert-dialog.md) |
+| 화면 중앙의 집중 작업 | [Dialog](dialog.md) |
+| Web 가장자리 서랍, 비모달 보조 패널 | [SidePanel](side-panel.md) |
+| 트리거 옆에 붙는 작은 내용 | [Popover](popover.md) |
+| 행동 목록 | [Menu](menu.md) |
+| 폼 한 칸의 선택 | [Select](select.md)(Native는 자체 sheet를 연다) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Sheet` | 기본(모달) | `@hjmds/react`, `/overlays` | `@hjmds/react-native`, `/overlays` |
+| `GestureSheet` | 확장(optional: 끌어서 snap·닫기) | — | `/sheet-gesture` |
+| `GestureSheetProvider` | 동반(optional: GestureSheet host) | — | `/sheet-gesture` |
+| `GestureSheetInput` | 동반(GestureSheet 안 입력, 계약은 [Field](field.md)) | — | `/sheet-gesture` |
+
+`/sheet-gesture`는 granular subpath로만 가져오며 optional peer `@gorhom/bottom-sheet` 5.2.14,
+`react-native-reanimated` 4.x, `react-native-gesture-handler` 2.32.0이 필요하다. 없으면 기기 Metro 번들에서 죽는다.
+기본 `Sheet`는 추가 peer가 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Button } from "@hjmds/react/actions";
+import { TextField } from "@hjmds/react/forms";
+import { Sheet } from "@hjmds/react/overlays";
+
+<Sheet open={open} onOpenChange={(next) => setOpen(next)}
+  title={t("profile.edit.title")} closeLabel={t("common.close")}
+  footer={<Button onClick={save} loading={saving}>{t("common.save")}</Button>}>
+  <TextField label={t("profile.name")} value={name} onValueChange={setName} />
+</Sheet>
+```
+
+```tsx
+// Native — 입력 폼은 keyboardAvoidance + scrollable
+import { Button } from "@hjmds/react-native/actions";
+import { TextField } from "@hjmds/react-native/inputs";
+import { Sheet } from "@hjmds/react-native/overlays";
+
+<Sheet open={open} onOpenChange={(next) => setOpen(next)}
+  title={t("profile.edit.title")} closeLabel={t("common.close")}
+  keyboardAvoidance scrollable busy={saving}
+  footer={<Button onPress={save} loading={saving}>{t("common.save")}</Button>}>
+  <TextField label={t("profile.name")} value={name} onValueChange={setName} />
+</Sheet>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `placement` | `bottom` · `start` · `end` | `bottom` | 나오는 가장자리 |
+| `size` | `auto` · `medium`(60%) · `large`(85%) · `full`(100%) | `auto` | `auto`는 내용 높이. 비율은 화면 높이 기준(Web `dvh`), 두 플랫폼 모두 위 safe area(Native는 키보드도)를 뺀 남은 높이를 넘지 않는다. `maxHeightRatio` 0.9 상한은 `auto`에만 걸린다 |
+| `open` · `defaultOpen` | `boolean` | 비제어 `false` | Web은 제어하면 `onOpenChange` 필수, 비제어면 `trigger` 필수 |
+| `onOpenChange` | `(open: boolean, detail: { reason }) => void` | — | reason: `trigger` · `close-action` · `escape` · `back` · `outside` · `swipe` · `programmatic`. Android 하드웨어 back은 Native에서만 `back` |
+| `onDismissComplete` | `(detail: { reason }) => void` | — | 표면이 실제로 사라진 뒤 한 번. 다음 modal·화면 이동은 여기서 |
+| `dismissPolicy` | `{ dismissible?, dismissWhileBusy?, outsideDismiss?, escapeOrBackDismiss?, swipeDismiss? }` | `dismissible` true · `dismissWhileBusy` false · `outsideDismiss` true · `escapeOrBackDismiss` true · `swipeDismiss` false | 닫기 허용 범위 |
+| `busy` | `boolean` | `false` | 사용자 닫기를 막는다 |
+| `title` · `closeLabel` | 문구 | 필수 | Native `title`이 element면 `accessibilityTitle`(string) 필수 |
+| `description` · `footer` | 노드(Native `description`은 `string`) | — | `footer`는 스크롤 밖 고정. 저장 행동은 여기 |
+| `detents`(Web) · `activeDetent` · `onDetentChange` | `readonly ("medium" \| "large" \| "full")[]` · `(detent) => void` | — | 사용자가 높이를 바꿀 단계. `detentLabels: { expand, collapse }` 필수 |
+| `keyboardAvoidance` · `scrollable`(Native) | `boolean` | `false` | 입력 폼은 둘 다 켠다 |
+| `safeAreaInsets`(Native) | `Partial<Insets>` | provider inset | — |
+| `contentStyle`(Native) | 배치 key만 | — | 배치 밖 key(색·높이 등)는 deprecated(개발 모드 경고), 다음 major에서 배치 전용 타입으로 좁힌다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 하단 시트 높이: `auto` 내용 높이(최대 화면 높이 × `maxHeightRatio` 0.9), `medium` 60%, `large` 85%, `full` 위 safe area 안 전체 높이(0.9 상한 없음). Web 하단 시트 최대 폭 640. 위 두 모서리만 `radius.xl` 24. 옆 시트(`start`·`end`): Web 폭 `min(28rem, 100%)`·높이 화면 − 32, Native 폭 88%(최대 420)·화면 높이 | `sheetRecipe.sizes`·`content`·`web`, `.hjm-sheet`, Native `Sheet` |
+| 간격 | 두 플랫폼 같은 값: 좌우 `content.paddingHorizontal`(`spacing.lg` 20), 위·아래 `content.paddingTop/Bottom`(`spacing.sm` 12, 하단 시트는 아래 safe area를 더함), 머리·본문·footer 사이 `body.gap`(`spacing.md` 16), footer 위 `footer.paddingTop`(`spacing.sm` 12), 제목–닫기 `header.gap`(`spacing.sm` 12), footer 버튼 사이 `footer.gap`(`spacing.sm` 12) | `.hjm-sheet__*`, `sheetRecipe.content`·`body`·`footer` |
+| 순서·정렬 | 머리(제목·설명 + 닫기) → 본문 → `footer`. 머리 최소 높이 44(`control.minTouchTarget`), 닫기는 끝 쪽에서 제목 세로 중앙. Web footer는 오른쪽 정렬 가로 줄 [보조][주]. Native footer는 세로 열이라 꽉 찬 폭 버튼을 주 행동 먼저 둔다. Web에서 `detents`를 주면 위 가운데 36×4 손잡이 버튼(터치 최소 폭 44 · 높이 `spacing.lg` 20). Native 기본 Sheet는 손잡이가 없다 | `sheetRecipe.header`·`handle`, `.hjm-sheet__footer`, `.hjm-sheet__handle` |
+| 고정·스크롤 | 본문만 스크롤, 머리·`footer` 고정(Native는 `scrollable`일 때 ScrollView). 고정 높이(`medium`·`large`·`full`, 옆 시트)에서는 본문이 머리·footer를 뺀 남은 높이를 차지하고 `footer`는 시트 아래에 붙는다. 그래서 본문의 `flex: 1` 자식(SearchScreen, 목록 화면)이 그 높이를 채운다(Web `.hjm-sheet__body` `flex: 1 1 auto`, Native 본문 `flexGrow: 1`·`minHeight: 0`, 미게시(1.13.1 이후)). `auto`는 내용 높이 그대로다. 저장·확인은 `footer`에. 아래 안전 영역은 시트가 자기 여백에 더한다(`spacing.sm` 12 + 아래 inset, Web은 `env(safe-area-inset-bottom)`). 위 inset은 시트가 올라갈 높이를 줄인다. 제품이 inset을 다시 더하지 않는다 | `.hjm-sheet__body`, `sheetRecipe.safeArea`, Native `Sheet` |
+| 좁은 폭·큰 글자 | 폭 < 640이면 하단 시트가 화면 폭을 채운다. Web footer는 줄을 바꾼다. 큰 글자로 내용이 길어지면 `auto`는 최대 90%에서 멈추고 본문이 스크롤된다(`full`은 위 safe area까지) | `.hjm-sheet[data-placement="bottom"]`, `maxHeightRatio` |
+
+```text
+폭 < 640(모바일)                        Web 넓은 폭: 가운데, 최대 640
+┌──────────────────────────────┐       ┌────────────────────────────────────┐
+│   (뒤 화면 + scrim, 누르면 닫힘)│       │        (scrim)                     │
+│ ╭──────────────────────────╮ │       │      ╭────────────────────╮        │
+│ │   ▬▬ (Web detents일 때)   │ │       │      │ 제목           [×] │        │
+│ │ 제목·설명            [×] │ │ ← 고정 │      │ 본문(스크롤)        │        │
+│ │──────────────────────────│ │       │      │      [취소] [저장] │        │
+│ │ 본문 ↕ 스크롤             │ │       └──────┴────────────────────┴────────┘
+│ │──────────────────────────│ │
+│ │ footer: Web [취소][저장]  │ │ ← 고정
+│ │ Native [   저장   ]       │ │
+│ │        [   취소   ]       │ │
+│ │ ░ 안전 영역(inset 더함) ░ │ │
+└─┴──────────────────────────┴─┘
+```
+
+## 꼭 지킬 것
+
+- 입력 폼 Native Sheet는 `keyboardAvoidance`와 `scrollable`을 함께 켜고, 제품의 키보드 listener·maxHeight·
+  중첩 ScrollView를 지운다. 본문이 FlatList 등 가상화 목록이면 `scrollable={false}`로 둔다.
+- 저장 버튼은 `footer`에 둔다. 저장 중에는 `busy`로 닫기를 막는다.
+- 닫힌 뒤 다른 modal을 열거나 화면 이동은 `onDismissComplete`에서 한다. 두 modal을 동시에 띄우지 않는다.
+- 문구(`title`, `closeLabel`, 본문)는 i18n 키로 넣는다. 제목 정렬을 위해 `as unknown as string` 캐스트나
+  `.hjm-sheet__header` CSS 덮어쓰기를 하지 않는다.
+- Native `contentStyle`은 배치 key만 쓴다. 높이는 `size`로 정한다(`contentStyle={{ height }}` 금지, 배치 밖 key는 deprecated).
+- Web Sheet는 `layoutStyle`을 받지 않는다(Web `layoutStyle` 제외 15개 중 하나). 표면 위치·크기는 `placement`·`size`가 정한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| uncontrolled 트리거 | `trigger`(uncontrolled면 필수) | 없음 |
+| 사용자 높이 조절 | `detents`·`activeDetent`·`onDetentChange`·`detentLabels` | 없음(GestureSheet `snapPoints`) |
+| 키보드·스크롤 | CSS scroll body | `keyboardAvoidance`, `scrollable` |
+| 고정 높이 본문 채우기 | 항상 `flex: 1 1 auto` | `size`가 `auto`가 아니거나 옆 시트일 때 `flexGrow: 1`(1.13.1부터). `scrollable`이면 ScrollView 자체만 늘고 그 안 내용은 내용 높이다 |
+| 초점 | `initialFocusRef`, `returnFocusRef`, focus trap | `returnFocusRef` |
+| 겹침 순서 | `modalPriority`, `portalContainer` | RN `Modal` props(`testID` 등) |
+| `title` 타입 | `ReactNode` | `string` 또는 element + `accessibilityTitle` |
+
+### GestureSheet(Native optional)
+
+- controlled `open`/`onOpenChange(open)`만 있다. `title`·`closeLabel`·`children` 필수, `snapPoints` 기본 `["50%", "90%"]`,
+  `initialIndex` 기본 `0`, `busy`면 끌어 닫기·backdrop 닫기를 막는다. 닫기 버튼이 본문 끝에 자동으로 들어간다.
+- 화면을 `GestureHandlerRootView` 안의 `GestureSheetProvider`로 감싼다. 입력은 `GestureSheetInput`을 쓴다.
+- RN `Modal` 안에 GestureSheet를 두면 Android back이 `onRequestClose`로만 간다. 그 host는
+  `dismissTopGestureSheet()`를 먼저 부르고 `false`일 때만 자기 자신을 닫는다.
+- 동적 높이·footer·dismissPolicy·reason은 없다. 이것들이 필요하면 기본 Sheet를 쓴다.
+
+## 함정
+
+- 미게시(1.12.1 이후) 변경: 1.12.1까지 `size="full"`(Web `detents`의 `full` 포함)은 0.9 상한에 걸려 90%에서 멈췄다. 1.12.1을 쓰는 앱에서 화면 전체가 필요하면 화면 전환을 쓴다.
+- 1.13.0 이하 Native 고정 높이 Sheet는 본문이 내용 높이라서 `flex: 1` 자식이 0pt가 됐다. 시트 안 SearchScreen이 검색 입력만 그리고
+  필터 줄·목록이 사라졌다(2026-10-06 utilverse 채팅 도구 선택, iPhone 17 Pro · iOS 26.5). 제품은 창 높이 `flexBasis`로 우회했다.
+  1.13.1부터는 그 우회 없이 채워진다. 1.13.0 이하에서도 footer는 본문 바로 아래에 있었고, 1.13.1부터 고정 높이 시트에서는 시트 아래에 붙는다.
+- `scrollable` 본문 안에서는 자식이 `flex: 1`로 높이를 채울 수 없다(ScrollView 내용은 내용 높이다). 자기 스크롤을 가진 화면(SearchScreen 등)은
+  `scrollable` 없이 넣는다.