@hjmds/design-contracts 1.12.0 → 1.13.0

package/docs/usage/compositions/interaction-flow-search.md

@@ -0,0 +1,171 @@
+# 늦은 응답보다 최신 검색 유지
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [공통 실행과 실패 복구](../../action-session.md), [제품 상호작용 품질](../../../../../docs/INTERACTION_QUALITY.md), `src/action-session.ts`, `showcase/web/src/patterns/interaction-flow-previews.tsx`, `showcase/native/src/interaction-flow-previews.tsx`. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/구성/상호작용 예제/늦은 응답보다 최신 검색 유지`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/입력과 작성/늦은 응답보다 최신 검색 유지`
+
+## 언제 쓰나
+
+검색어를 바꿔 다시 검색했을 때 먼저 보낸 요청이 늦게 도착해도 최신 검색 결과를 덮어쓰지 않게 할 때 쓴다.
+
+검색처럼 **읽기 전용** 요청에만 쓴다. 이전 결과를 버려도 서버에 남는 것이 없기 때문이다. 저장·수정 요청이 겹치는 경우는
+같은 세션의 중복 실행 차단([저장과 재시도](action-recovery-save.md))으로 다룬다. 이 방식은 서버 요청 취소가 아니다.
+
+같은 `상호작용 예제` 묶음: [선택 후 적용·취소](interaction-flow-apply.md) · [닫았다 열고 초안 이어쓰기](interaction-flow-draft.md) ·
+[대표 항목과 묶음 전체 선택](selection-scope.md). 세션 연결과 상태 알림은 [저장과 재시도의 공통 절](action-recovery-save.md#공통-세션과-상태-알림)을 따른다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `Container`·`Stack` | 바깥 틀. 구획 사이 `gap="xl"`, 묶음 안 `gap="md"` | [Container](../components/container.md), [Stack](../components/stack.md) |
+| `Heading` | 묶음 제목 | [Heading](../components/heading.md) |
+| `createActionSession` | 검색 결과 값. 새 검색 전에 `reset`으로 세대를 바꿔 이전 응답을 무시 | [계약](../../action-session.md) |
+| `SearchField` | 검색어와 지우기(×). 진행 중에는 Web `loading`, Native `busy`+`busyLabel`로 뒤쪽 자리만 진행 표시로 바뀌고 입력은 그대로 쓸 수 있다. 빈 검색어면 검색 버튼 `disabled`. Web·Native 모두 `onValueChange` | [SearchField](../components/search-field.md) |
+| `Button` 검색 / `Button` 다시 검색(secondary) | 검색 실행(primary 하나), 실패했을 때만 보이는 재시도 | [Button](../components/button.md) |
+| `Text` | 진행·결과·실패 문구 | [Text](../components/text.md) |
+
+스토리의 "느린 응답으로 검색"(900ms)·"빠른 응답으로 검색"(150ms) 두 버튼은 역순 응답을 재현하는 데모다. 제품은 검색 버튼 하나(또는 입력 중 검색)로 둔다.
+`다음 검색 실패시키기`는 실패 경로를 여는 데모 도구다. 스토리는 기본·어두운 테마·큰 글자, `검색 중`, `실패와 다시 검색`, 제품 팔레트 두 가지(`보라 테마`, `초록 테마 · 어둡게`)다.
+2026-10-06 같은 SearchField 진행 상태와 팔레트를 보이던 `입력과 작성/검색 입력`을 이 항목으로 합쳤다([옛 링크](../../../../../docs/STORYBOOK_NAVIGATION.md#실험-정리와-합친-항목-2026-10-06)).
+검색 입력 칸·결과 목록이 필요한 화면이면 [SearchField](../components/search-field.md)·[List](../components/list.md)에 같은 세대 규칙을 연결한다.
+
+## 배치
+
+```text
+┌ 화면 ────────────────────────────────┐
+│ Native ScrollView 위아래 16          │
+│ (keyboardShouldPersistTaps=handled)  │
+│ └ Container gutter 16/20             │
+│   Heading 제목                       │
+│          ↕ spacing.md 16             │
+│   검색어                             │
+│   [🔍 입력                    (×)] │ SearchField 높이 44, 진행 중 × 자리 = 진행 표시
+│          ↕ spacing.md 16             │
+│   [        검색 (primary)          ] │ ← 주 행동
+│          ↕ spacing.md 16             │
+│   검색 중이에요 / 결과 / 실패 (status)│
+│   [ 다시 검색 ] (secondary, 실패 때만)│
+└──────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Native: `ScrollView keyboardShouldPersistTaps="handled"` → `Container` → `Stack gap="xl"`. Web: `Container` → `Stack gap="xl"` | 화면 본문. 안전 영역은 화면 셸이 준다. 키보드가 열린 채 검색 버튼을 누를 수 있게 Native 스크롤은 탭을 통과시킨다. 입력이 화면 아래쪽에 있으면 [KeyboardFormScrollView](../components/keyboard-form-scroll-view.md)를 쓴다 | Native `ScrollView` 위아래 `spacing.md` 16, 좌우 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 구획 사이 `layout.sectionGap` 24 |
+| 제목 | `Heading level="level3"` | 묶음 맨 위 | 24/32(`heading.level3`) |
+| 입력 | `SearchField` | 제목 아래 | 높이 `control.fieldHeight` 44, `layout.contentGap` 16 |
+| 주 행동 | `Button` 검색 | 입력 아래 | `medium` 44(`control.buttonHeight`), `spacing.md` 16 |
+| 결과·상태 | `Text` | 행동 아래 | `spacing.md` 16 |
+| 재시도 | `Button tone="secondary"` | 실패 문구 아래, 실패일 때만 | `medium` 44, `spacing.md` 16 |
+
+근거: `src/foundations.ts`(`spacing`, `control`, `layout`, `heading`), `src/action-session.ts`
+
+## 흐름과 상태
+
+1. 사용자가 검색어를 입력하고 검색한다. 앞뒤 공백을 지운 값을 캡처한다.
+2. 새 검색 직전에 `session.reset(state.value)`를 부른다. 진행 중이던 이전 요청의 세대가 끝나 그 응답과 재시도는 무시된다.
+3. `session.run(() => api.search(submitted), { retryable: true })`. pending 중 상태 문구는 `t("search.pending")`이다.
+4. 검색어를 바꿔 다시 검색하면 2~3을 반복한다. 늦게 온 이전 결과는 화면을 바꾸지 않는다.
+5. 최신 요청이 끝나면 결과를 보인다. 실패하면 "다시 검색"으로 같은 검색어를 `session.retry()`한다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 아직 검색 전이면 `t("search.notYet")`, `reset` 뒤(idle)에는 직전 결과(`state.value`) | — |
+| 진행 중 | 이전 결과 대신 `t("search.pending")`. 검색 버튼은 그대로 눌린다(새 검색이 `reset`으로 이전 요청을 떼어 낸다) | 포커스는 입력·버튼에 유지, 진행 알림 |
+| 성공 | 최신 검색어의 결과 | 결과 문구 알림 |
+| 실패 | 네트워크·서버 실패: `t("search.failed")` + "다시 검색"(secondary). `state.value`는 직전 값이라 이전 결과를 실패 문구 대신 보이지 않는다. 재시도도 실패하면 같은 문구로 다시 error가 된다. 새 검색어로 검색하면 `reset`이 실패 시도를 버린다 | 실패 알림 |
+
+`reset` 없이 run을 다시 부르면 pending 중이라 `blocked`가 되어 새 검색이 실행되지 않는다.
+상태→문구 키는 상수 표(`searchStatusKey`)로 둔다. 템플릿 문자열 키는 키 추출·누락 검사가 찾지 못한다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { useState, useSyncExternalStore } from "react";
+import { createActionSession } from "@hjmds/design-contracts/action-session";
+import { Button } from "@hjmds/react/actions";
+import { SearchField } from "@hjmds/react/forms";
+import { Heading } from "@hjmds/react/heading";
+import { Container, Stack, Text } from "@hjmds/react/layout";
+
+const searchStatusKey = { idle: "search.notYet", pending: "search.pending", error: "search.failed" } as const;
+
+const [session] = useState(() => createActionSession<Result | null>(null));
+const state = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+const [query, setQuery] = useState("");
+const search = () => {
+  const submitted = query.trim();
+  if (!submitted) return;
+  session.reset(state.value); // 이전 응답만 버린다. 서버 요청 취소가 아니다
+  void session.run(() => api.search(submitted), { retryable: true });
+};
+const message = state.status === "pending" || state.status === "error" ? t(searchStatusKey[state.status])
+  : state.value ? renderResult(state.value) : t(searchStatusKey.idle);
+
+<Container gutter={gutter}>
+  <Stack gap="xl">
+    <Stack gap="md">
+      <Heading level="level3" semanticLevel={2}>{t("search.title")}</Heading>
+      <SearchField label={t("search.label")} clearLabel={t("common.clearSearch")} value={query} onValueChange={setQuery}
+        loading={state.status === "pending"} />
+      <Button disabled={!query.trim()} onClick={search}>{t("search.action")}</Button>
+      <Text role="status">{message}</Text>
+      {state.status === "error" ? <Button tone="secondary" onClick={() => void session.retry()}>{t("search.retry")}</Button> : null}
+    </Stack>
+  </Stack>
+</Container>
+```
+
+```tsx
+// Native
+import { ScrollView, useWindowDimensions } from "react-native";
+import { Button } from "@hjmds/react-native/actions";
+import { Heading } from "@hjmds/react-native/heading";
+import { SearchField } from "@hjmds/react-native/inputs";
+import { Container, Stack } from "@hjmds/react-native/primitives";
+import { useHjmNativeTheme } from "@hjmds/react-native/provider";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+
+const { spacing } = useHjmNativeTheme().tokens;
+const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "compact" : "regular";
+
+<ScrollView keyboardShouldPersistTaps="handled" contentContainerStyle={{ paddingVertical: spacing.md }}>
+  <Container gutter={gutter}>
+    <Stack gap="xl">
+      <Stack gap="md">
+        <Heading level="level3" semanticLevel={2}>{t("search.title")}</Heading>
+        <SearchField label={t("search.label")} clearLabel={t("common.clearSearch")} value={query} onValueChange={setQuery}
+          busy={state.status === "pending"} busyLabel={t("search.pending")} />
+        <Button disabled={!query.trim()} onPress={search}>{t("search.action")}</Button>
+        <StatusText>{message}</StatusText>
+        {state.status === "error" ? <Button tone="secondary" onPress={() => void session.retry()}>{t("search.retry")}</Button> : null}
+      </Stack>
+    </Stack>
+  </Container>
+</ScrollView>
+```
+
+`api.search`·`renderResult`·`Result`·문구 키는 제품 소유다. `StatusText`는 [저장과 재시도의 공통 절](action-recovery-save.md#공통-세션과-상태-알림)의 Native 상태 알림 helper다.
+세션·`search`·`message`는 Web과 같다. 네트워크 요청을 실제로 끊어야 하면 제품이 `AbortController` 등을 따로 쓴다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 입력 이벤트 | `onValueChange`(문자열 값). DOM 이벤트가 필요할 때만 `onChange`(둘 다 호출된다) | `onValueChange` |
+| 상태 알림 | `role="status"` | live region(Android) + iOS 알림 호출 |
+| 바깥 틀 | `Container` | `ScrollView`(세로 여백, `keyboardShouldPersistTaps="handled"`) 안 `Container` |
+| 검색 중 표시 | SearchField `loading` | SearchField `busy` + `busyLabel`(필수) |
+
+## 함정
+
+- 데모의 인위 지연(150·900ms)을 제품에 최소 대기 시간으로 복사하지 않는다.
+- TanStack Query처럼 키별 캐시가 최신 요청을 이미 고르는 앱은 세션을 겹치지 않는다.
+- 구획 제목은 Heading으로 표시한다. 이전 Text heading 예제는 2026-10-06 제목 의미 구조를 맞추면서 수정했다.
+- 진행 표시를 결과 영역에 따로 두지 않는다. SearchField의 진행 표시와 상태 문구 하나면 된다(흡수한 `검색 입력` 예제의 규칙).
+- 실패와 결과 없음은 다른 상태다. 실패는 `다시 검색`(`session.retry()`), 결과 없음은 검색어를 바꾸는 경로를 준다.

package/docs/usage/compositions/native-renderers.md

@@ -0,0 +1,106 @@
+# 네이티브 컴포넌트 기기 확인
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `showcase/native/src/NativeRenderers.stories.tsx`, `showcase/native/src/story-registry.ts` `nativeRendererStoryGroups`
+- 스토리북: `배포/구성/비교와 검증/네이티브 컴포넌트 기기 확인`
+
+## 언제 쓰나
+
+Native 공개 컴포넌트가 실제 기기·시뮬레이터에서 그려지고 눌리는지 범주별로 한 화면에서 확인할 때 쓴다. 화면 설계의 본보기가 아니라
+렌더 확인용 모음이다. 여기서 범주를 찾은 뒤 배치·문구 규칙은 각 컴포넌트 지침에서 가져온다.
+
+## 구성 요소
+
+여덟 스토리가 아래 범주를 하나씩 그린다. 달력·떠 있는 버튼·데이터 배치·생각 구슬은 이 모음이 아니라 각자의 스토리에 있다.
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| 디자인 기초 | Provider·글자·표면·레이아웃·아이콘·제목, 로그인 화면 골격 | [DesignSystemProvider](../components/design-system-provider.md), [Text](../components/text.md), [Surface](../components/surface.md), [Stack](../components/stack.md), [Container](../components/container.md), [AspectRatio](../components/aspect-ratio.md), [Grid](../components/grid.md), [Layout](../components/layout.md), [Icon](../components/icon.md), [Section](../components/section.md), [Divider](../components/divider.md), [Top](../components/top.md), [Heading](../components/heading.md), [AuthScreenLayout](../components/auth-screen-layout.md) |
+| 동작 | 버튼·링크·하단 고정 행동·소셜 로그인 버튼 | [Button](../components/button.md), [IconButton](../components/icon-button.md), [Link](../components/link.md), [BottomCTA](../components/bottom-cta.md), [AuthProviderButton](../components/auth-provider-button.md) |
+| 약관 동의 | 전체 동의·필수/선택 항목·상세 보기 | [Agreement](../components/agreement.md) |
+| 입력 | 텍스트·숫자·날짜·파일·선택 입력 | [Field](../components/field.md), [SearchField](../components/search-field.md), [TextArea](../components/text-area.md), [PasswordField](../components/password-field.md), [OtpField](../components/otp-field.md), [NumberField](../components/number-field.md), [Slider](../components/slider.md), [Form](../components/form.md), [DatePicker](../components/date-picker.md), [FilePicker](../components/file-picker.md), [Checkbox](../components/checkbox.md), [Radio](../components/radio.md), [CheckboxGroup](../components/checkbox-group.md), [RadioGroup](../components/radio-group.md), [Switch](../components/switch.md), [SegmentedControl](../components/segmented-control.md), [Select](../components/select.md), [Combobox](../components/combobox.md), [Chip](../components/chip.md), [ToggleGroup](../components/toggle-group.md), [TagsInput](../components/tags-input.md), [DateRangePicker](../components/date-range-picker.md), [Mentions](../components/mentions.md), [TransferList](../components/transfer-list.md) |
+| 탐색 | 상단 막대·탭·단계·메뉴·하단 탭·더 보기 | [Tabs](../components/tabs.md), [Steps](../components/steps.md), [TopBar](../components/top-bar.md), [Menu](../components/menu.md), [BottomNavigation](../components/bottom-navigation.md), [LoadMore](../components/load-more.md) |
+| 데이터 표시 | 목록·카드·배지·수치·미디어 | [Badge](../components/badge.md), [Avatar](../components/avatar.md), [Card](../components/card.md), [ListRow](../components/list-row.md), [Tag](../components/tag.md), [Timeline](../components/timeline.md), [DescriptionList](../components/description-list.md), [Image](../components/image.md), [CounterBadge](../components/counter-badge.md), [List](../components/list.md), [Carousel](../components/carousel.md), [Statistic](../components/statistic.md), [UploadItem](../components/upload-item.md), [Accordion](../components/accordion.md), [Collapsible](../components/collapsible.md), [Asset](../components/asset.md) |
+| 상태와 알림 | 빈 상태·결과·알림·진행·토스트 | [EmptyState](../components/empty-state.md), [Result](../components/result.md), [Notice](../components/notice.md), [Progress](../components/progress.md), [Skeleton](../components/skeleton.md), [Spinner](../components/spinner.md), [Toast](../components/toast.md), [BottomInfo](../components/bottom-info.md) |
+| 오버레이 | 대화상자·확인 대화상자·하단 시트 | [Dialog](../components/dialog.md), [AlertDialog](../components/alert-dialog.md), [Sheet](../components/sheet.md) |
+
+## 배치
+
+```text
+┌──────── 안전 영역 안(제품 화면 host) ────┐
+│ ScrollView  위아래 spacing.md 16         │ ← 스크롤 영역, 탭 유지(handled)
+│ └ Container gutter 16/20                 │
+│   Section 범주 제목 (header 역할)        │
+│   설명                                   │
+│   ↕ contentGap 16 (Stack gap="md")       │
+│   컴포넌트 A                             │
+│   컴포넌트 B                             │
+│   ...  공개 import 순서대로 세로로 쌓음   │
+│   오버레이 트리거 → 열면 화면 위에 뜬다   │
+└──────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | `ScrollView keyboardShouldPersistTaps="handled"` → `Container` → `Section` | 화면 전체. 안전 영역은 제품 화면 host(또는 Provider `safeAreaInsets`)가 소유한다. 입력 범주는 키보드가 필드를 가리지 않게 `automaticallyAdjustKeyboardInsets`를 주거나, keyboard-controller가 있는 앱은 [KeyboardFormScrollView](../components/keyboard-form-scroll-view.md)로 바꾼다 | `ScrollView` 위아래 `spacing.md` 16, 좌우 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 범주를 여럿 이으면 범주 사이 `layout.sectionGap` 24(`Stack gap="xl"`) |
+| 범주 제목 | [Section](../components/section.md) `title`·`description` | 맨 위 | 제목과 본문 사이 `spacing.xs` 8, 제목과 설명 사이 `spacing.xxs` 4(`sectionRecipe`) |
+| 컴포넌트 | 범주의 공개 컴포넌트, `Stack gap="md"` | 제목 아래 세로 | 요소 사이 `layout.contentGap` 16. 각 컴포넌트는 기본 크기 그대로 |
+| 오버레이 | Dialog·AlertDialog·Sheet | 트리거를 누르면 화면 위 | 각 recipe |
+
+## 흐름과 상태
+
+1. 범주 스토리를 연다.
+2. 각 컴포넌트를 눌러 보고, 아래 "Last action"·"Pressed" 같은 상태 문구로 이벤트가 왔는지 확인한다.
+3. 같은 범주를 어두운 테마·큰 글자 전역 설정으로 다시 본다.
+4. 문제가 있으면 해당 컴포넌트 지침과 계약에서 원인을 찾는다. 이 모음에서 배치를 베끼지 않는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 범주의 컴포넌트가 기본 축으로 그려진다 | 키보드가 열려도 탭이 먹힌다(`handled`) |
+| 진행 중 | 업로드 64%(UploadItem `uploading`·Progress), LoadMore 불러오기, AuthScreenLayout `pendingLabel`(카드 크기를 유지한 가운데 로딩) 같은 예시 상태 | 각 컴포넌트 지침의 진행 알림 |
+| 실패 | — (렌더 확인 모음이라 네트워크 요청이 없다). 실패 표현은 상태와 알림 범주의 Result·Notice로 확인하고, 실제 실패·재시도 흐름은 [저장과 재시도](action-recovery-save.md) 같은 구성 지침을 따른다 | — |
+| 비활성 | 동작 범주의 `disabled` Button | — |
+| 다크·큰 글자 | 전역 설정으로 같은 화면을 다시 확인 | — |
+
+## 코드 골격
+
+```tsx
+// Web
+// 없음. Web은 각 컴포넌트 스토리(`배포/컴포넌트/...`)에서 확인한다.
+```
+
+```tsx
+// Native
+import { ScrollView, useWindowDimensions } from "react-native";
+import { Container, Section, Stack } from "@hjmds/react-native/primitives";
+import { useHjmNativeTheme } from "@hjmds/react-native/provider";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+
+// 제품의 개발용 확인 화면에서 범주 하나를 같은 틀로 모을 때
+const { spacing } = useHjmNativeTheme().tokens;
+const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "compact" : "regular";
+
+<ScrollView keyboardShouldPersistTaps="handled" automaticallyAdjustKeyboardInsets
+  contentContainerStyle={{ paddingVertical: spacing.md }}>
+  <Container gutter={gutter}>
+    <Section title={t("dev.inputs.title")} description={t("dev.inputs.description")}>
+      <Stack gap="md">
+        {/* 범주의 컴포넌트를 공개 import에서 가져와 순서대로 둔다 */}
+      </Stack>
+    </Section>
+  </Container>
+</ScrollView>
+```
+
+스토리의 영어 예시 문구, `Glyph`(첫 글자 아이콘), 직접 만든 입력의 `#667085` 테두리는 확인용이며 제품에 가져오지 않는다.
+
+## 함정
+
+- 이 모음의 순서·간격은 확인용이다. 실제 화면은 화면 지침과 각 구성 지침의 배치를 따른다.
+- 구획 제목은 Heading으로 표시한다. 이전 Text heading 예제는 2026-10-06 제목 의미 구조를 맞추면서 수정했다.
+- 스토리의 직접 만든 입력 스타일(`#667085`, radius 12)은 토큰이 아니다. 제품 코드에 숫자로 옮기지 않는다.
+- StoryFrame은 Container compact·Stack md와 위아래 spacing.md를 사용하며 `automaticallyAdjustKeyboardInsets`를 켠다. Android 키보드 회피·큰 입력 폼은 해당 제품 기기에서 별도로 확인한다.

package/docs/usage/compositions/navigation-bar-collection.md

@@ -0,0 +1,164 @@
+# 내비게이션 바 비교
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [BottomNavigation](../../bottom-navigation.md), `src/component-recipes.ts` `bottomNavigationRecipe`, `packages/react/src/styles.css` `.hjm-bottom-navigation`, `showcase/shared/navigation-bar-references.ts`
+- 스토리북: `배포/구성/비교와 검증/내비게이션 바 비교`
+
+## 언제 쓰나
+
+하단 탭에 목적지 이동과 별개의 행동(작성·전원·기록 추가)을 함께 둘지, 선택한 목적지를 어떻게 보여 줄지 고를 때 이 비교를 본다.
+스토리는 BottomNavigation 하나를 `configuration`과 `primaryAction`만 바꿔 네 가지 동작으로 보여 준다.
+열 가지 색·라벨은 참고 예시이고 동작은 네 가지뿐이다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| BottomNavigation | 목적지 2~6개, 선택 상태, 배지 | [BottomNavigation](../components/bottom-navigation.md) |
+| IconButton `tone="primary" size="large" shape="circle"` | `primaryAction`: 목적지가 아닌 행동 | [IconButton](../components/icon-button.md) |
+| HjmProvider / HjmNativeProvider `brandPalette` | 막대 범위의 제품 색(스토리 색은 예시) | [DesignSystemProvider](../components/design-system-provider.md) |
+| Button `secondary` `selected` | 스토리에서 참고 표현을 고르는 선택기(제품에는 필요 없음) | [Button](../components/button.md) |
+
+## 배치
+
+네 가지 동작과 고르는 기준이다.
+
+| 동작 | `configuration` | `primaryAction` 위치 | 고를 때 |
+| --- | --- | --- | --- |
+| 중앙에서 작업 실행 | `presentation: "floating"`, `distribution: "center-gap"` | 막대 정중앙(목적지 사이 빈칸 위) | 생성이 앱의 핵심 행동이고 목적지가 짝수(2·4·6)일 때 |
+| 탐색 옆에서 작업 실행 | `presentation: "capsule"`, `distribution: "equal"` | 캡슐 밖 끝 쪽, 캡슐과 `spacing.xs` 8 간격 | 행동이 목적지와 섞여 보이면 안 될 때, 목적지가 홀수일 때 |
+| 선택한 목적지 이름 표시 | `presentation: "capsule"`, 행동 없음 | — | 아이콘만으로 목적지가 모호해 선택 항목의 이름을 보여야 할 때 |
+| 사각 영역으로 현재 위치 표시 | `capsule` + 목록·항목 radius `lg` 16 | — | 둥근 캡슐이 제품 표현과 맞지 않을 때(radius 변경은 제품 스타일) |
+
+```text
+중앙에서 작업 실행 (floating + center-gap)         탐색 옆에서 작업 실행 (capsule)
+┌──── 스크롤 본문 (하단 여백 = 막대 높이) ────┐     ┌───────────────────────────────────────┐
+│ ...                                        │     │ ...                                   │
+├──────── 고정 막대, outer 좌우 16 ──────────┤     ├───────────────────────────────────────┤
+│ ╭───────────────────────────────────────╮ │     │ ╭─────────────────────────────╮ 8 (●) │
+│ │ [홈] [공간]   (●)   [스토어] [전력]   │ │     │ │ [●홈 ] [달력] [통계] [기록] │   ↑   │
+│ ╰──────── center gap 68 ────────────────╯ │     │ ╰───── radius full ───────────╯ 주 행동│
+│              ↑ 주 행동 IconButton 52      │     │  선택 항목만 아이콘+이름(가로)         │
+├──── 안전 영역 + spacing.xs 8 ─────────────┤     ├──── 안전 영역 + spacing.xs 8 ─────────┤
+└────────────────────────────────────────────┘     └───────────────────────────────────────┘
+  radius xl 24, 최대 폭 384                          최대 폭 480
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web: 문서 스크롤 본문(`Container`) + 화면 아래 고정 막대. Native: 화면 루트 세로 flex(`flex: 1`) — 위 `ScrollView`(flex 1) → `Container`, 아래 막대(탭 navigator의 tabBar 자리) | 막대는 스크롤하지 않는다. 하단 안전 영역은 막대가 받는다(Web `env(safe-area-inset-bottom)`, Native `safeAreaBottom`). 상단 안전 영역은 화면 header가 받는다. 키보드가 열리면 막대가 숨는다(`keyboardBehavior: "hide"` 기본) | 본문 좌우는 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20), Native `ScrollView` 위아래 `spacing.md` 16. Web 본문 하단 여백 = 잰 막대 높이(막대가 `position: fixed`라 내용이 아래로 들어간다) |
+| 막대 | BottomNavigation | Web `position: fixed` 하단, Native는 제품 navigator가 하단에 둔다 | outer 위 `spacing.xs` 8, 좌우 `spacing.md` 16(floating·capsule), `bar`는 0 |
+| 표면 | floating / capsule | 막대 가운데 | floating 최대 폭 384·radius `xl` 24, capsule 최대 폭 480·radius `full` |
+| 항목 | 목적지 | 표면 안 균등 분배 | `compact` 최소 52×52·padding `spacing.xxs` 4, `regular` 56×64·padding `spacing.xs` 8 |
+| 중앙 빈칸 | `center-gap` | 목적지 가운데 | `control.buttonHeight.large` 52 + `spacing.md` 16 = 68 |
+| 주 행동 | IconButton | center-gap이면 정중앙, capsule이면 목록 뒤 끝 쪽 | `large` 지름 52, capsule 목록과 `spacing.xs` 8 |
+| 하단 안전 영역 | — | 막대 아래 | Web `env(safe-area-inset-bottom)` + `spacing.xs` 8, Native `safeAreaBottom` |
+| 스크롤 본문 | 제품 화면 | 막대 위 | Web은 하단 여백을 막대 높이만큼 제품이 둔다. Native는 막대가 flex 형제라 겹치지 않는다 |
+
+capsule은 기본 크기에서 선택되지 않은 항목의 이름을 접는다. 큰 글자(계약 기준 1.5 이상)이거나 목적지가 5~6개면
+모든 이름을 세로로 보인다. 접힌 항목도 접근성 이름은 유지된다.
+
+## 흐름과 상태
+
+1. 목적지를 누르면 `onActivate`로 이동 의도만 받는다. 선택은 제품 router가 확정해 `selectedKey`로 다시 넘긴다.
+2. `primaryAction`을 누르면 작성 화면·시트를 연다. `selectedKey`는 바뀌지 않는다.
+3. 같은 탭을 다시 누르면 Native는 `reason: "reselect"`로 오므로 목록 맨 위로 스크롤하는 데 쓴다.
+4. 소프트 키보드가 열리면 기본(`keyboardBehavior: "hide"`)으로 막대를 숨긴다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 선택 목적지가 `content.brand` 아이콘·라벨, capsule은 `surfaceAccent` 배경 | Web `aria-current`, Native 선택 state |
+| 진행 중 | — (막대는 즉시 바뀐다. 목적지 화면을 불러오는 동안의 로딩은 그 화면이 표시하고, 막대는 `selectedKey`가 바뀐 상태로 남는다) | — |
+| 실패 | — (막대 자체는 실패하지 않는다. 목적지 화면의 불러오기 실패·재요청 실패는 그 화면의 [Result](../components/result.md)·[Notice](../components/notice.md)가 표시한다. `primaryAction`이 연 작성 화면의 저장 실패는 [저장과 재시도](action-recovery-save.md)를 따른다) | — |
+| 배지 | 숫자 배지(`count`·`max`) | 배지 `accessibilityLabel`을 항목 이름과 함께 읽는다 |
+| 키보드 열림 | 막대가 숨는다(`remain`이면 유지) | — |
+| 큰 글자 | capsule의 모든 이름이 세로로 보인다 | 같다 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { BottomNavigation } from "@hjmds/react/navigation";
+import { IconButton } from "@hjmds/react/actions";
+import { Container } from "@hjmds/react/layout";
+
+<>
+  {/* 막대가 position: fixed라 본문 끝이 가려진다. 잰 막대 높이만큼 아래 여백을 둔다. */}
+  <main style={{ paddingBlockEnd: barHeight }}>
+    <Container>{page}</Container>
+  </main>
+  <BottomNavigation ref={barRef}
+    descriptor={{ accessibilityLabel: t("nav.main"), selectedKey: route, items }}
+    configuration={{ presentation: "floating", density: "compact", distribution: "center-gap" }}
+    getHref={(item) => routes[item.id]}
+    renderLink={(props) => <Link {...props} />}
+    renderIcon={renderGlyph}
+    primaryAction={
+      <IconButton label={t("post.create")} tone="primary" size="large" shape="circle" onClick={openComposer}>
+        <PlusGlyph aria-hidden="true" />
+      </IconButton>
+    }
+  />
+</>
+```
+
+```tsx
+// Native
+import { ScrollView, View, useWindowDimensions } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { BottomNavigation } from "@hjmds/react-native/navigation";
+import { IconButton } from "@hjmds/react-native/actions";
+import { Container } from "@hjmds/react-native/primitives";
+import { useHjmNativeTheme } from "@hjmds/react-native/provider";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+
+const { colors, tokens } = useHjmNativeTheme();
+const insets = useSafeAreaInsets();
+const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "compact" : "regular";
+
+<View style={{ flex: 1 }}>
+  <ScrollView style={{ flex: 1 }} contentContainerStyle={{ paddingVertical: tokens.spacing.md }}>
+    <Container gutter={gutter}>{page}</Container>
+  </ScrollView>
+  <BottomNavigation
+    descriptor={{ accessibilityLabel: t("nav.main"), selectedKey: route, items }}
+    configuration={{ presentation: "capsule", density: "compact", distribution: "equal" }}
+    safeAreaBottom={insets.bottom}
+    renderIcon={renderGlyph}
+    onActivate={({ key }) => navigation.navigate(key)}
+    primaryAction={
+      <IconButton label={t("record.add")} tone="primary" size="large" shape="circle" onPress={openRecord}>
+        <PlusGlyph color={colors.onPrimary} />
+      </IconButton>
+    }
+  />
+</View>
+```
+
+`route`·`items`·`routes`·`Link`·`renderGlyph`·`PlusGlyph`·`barRef`/`barHeight`(막대 높이 측정)·`navigation`은 제품 소유다.
+탭 navigator를 쓰면 `View` 대신 navigator의 `tabBar`에 `BottomNavigation`을 넘기고 본문은 각 탭 화면이 그린다.
+
+스토리의 참고 색(`accent`·`soft`), 아이콘 세트, 막대를 감싼 테두리 카드와 `padding-inline: 0`(320 폭 갤러리용) 덮어쓰기는
+제품에 가져오지 않는다. 제품 색은 앱 루트 Provider의 `brandPalette`로 준다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 배치 | CSS `position: fixed`(스토리는 갤러리용으로 `relative`로 덮음), 본문 하단 여백은 제품 | 화면 루트 세로 flex의 마지막 자식 또는 navigator `tabBar` |
+| 목적지 | 링크(`getHref` 필수, `renderLink`) | tab 역할 + `onActivate` 필수 |
+| 사각 선택 표현 | 공개 축이 없다. 스토리는 CSS로 목록·항목 radius를 `lg`로 덮는다 | 공개 축이 없다. 스토리는 deprecated `listStyle={{ borderRadius: radius.lg }}`로 덮는다 |
+| 행동 아이콘 색 | `currentColor` | `colors.onPrimary`를 직접 넘김 |
+
+## 함정
+
+- `center-gap`은 홀수 목적지에서, `capsule`과 함께 쓰면 오류다.
+- 생성 행동을 목적지 항목으로 넣지 않는다. 선택 상태가 생성 화면으로 옮겨 가 탭 의미가 깨진다.
+- "사각 영역으로 현재 위치 표시"는 `configuration` 축이 아니라 radius 덮어쓰기다. Native `listStyle`·`style`은 deprecated(다음 major에서 제거)라 제품에 옮기면 그때 깨진다. 필요하면 공개 축 추가를 먼저 요청한다.
+- 구획 제목은 Heading으로 표시한다. 이전 Text heading 예제는 2026-10-06 제목 의미 구조를 맞추면서 수정했다.
+- 현재 스토리는 Native 막대에 deprecated `style={{ paddingHorizontal: 0 }}`를 준다(320 폭 갤러리용). 제품은 바깥 좌우 `spacing.md` 16을 그대로 둔다.
+- 현재 스토리는 바깥 틀(본문 스크롤·하단 여백)이 없고 막대를 갤러리 카드 안에 둔다. 제품은 바깥 틀 행대로 둔다.

package/docs/usage/compositions/optional-adapters.md

@@ -0,0 +1,169 @@
+# 이미지·시트·키보드 조작
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Optional presentation adapters](../../optional-adapters.md#behavior-boundaries), `packages/react-native/src/keyboard-controller.tsx`, `packages/react-native/src/sheet-gesture.tsx`, `showcase/native/src/OptionalAdapters.stories.tsx`. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/구성/이미지·시트·키보드 조작`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/직접 조작과 모션/이미지·시트·키보드 조작`
+
+## 언제 쓰나
+
+Native 앱 한 화면에서 이미지 확대 보기, 끌어서 높이를 바꾸는 시트, OS 길게 누르기 메뉴, 키보드를 따라 올라가는 하단 행동을 함께 쓸 때 provider 중첩 순서와 각 요소의 자리를 확인하는 구성이다.
+
+네 어댑터(`image-viewer`·`sheet-gesture`·`context-menu-native`·`keyboard-controller`)는 모두 experimental이고 Native 전용이다. 링크된 네이티브 모듈이 필요하므로
+Expo Go가 아니라 호환 개발 클라이언트에서만 확인된다. 이 기능이 필요 없으면 기본 [Sheet](../components/sheet.md)·[ContextMenu](../components/context-menu.md)·
+[KeyboardAvoiding](../components/keyboard-avoiding.md)을 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `GestureHandlerRootView` | 제스처 host. 화면 루트 하나 | — |
+| `KeyboardMotionProvider` | 키보드 추적. 앱(화면) 루트에 하나, 필드마다 두지 않는다 | [KeyboardMotionProvider](../components/keyboard-motion-provider.md) |
+| `GestureSheetProvider` | GestureSheet host. `GestureHandlerRootView` 안 | [Sheet](../components/sheet.md) |
+| `KeyboardFormScrollView` | 입력이 있는 본문 스크롤. 초점 필드를 키보드 위로 | [KeyboardFormScrollView](../components/keyboard-form-scroll-view.md) |
+| `KeyboardDock` | 하단 행동(완료 등)이 키보드를 따라 올라감 | [KeyboardDock](../components/keyboard-dock.md) |
+| `GestureSheet` + `GestureSheetInput` | 끌어서 snap(기본 `["50%", "90%"]`)·닫기, 시트 안 입력 | [Sheet](../components/sheet.md) |
+| `ImageViewer` | 전체 화면 이미지 확대·넘기기, 실패 시 다시 시도 | [Image](../components/image.md) |
+| `NativeContextMenu` | 길게 눌러 OS 메뉴. 자식은 접근 가능한 native 요소 하나 | [ContextMenu](../components/context-menu.md) |
+| `Button`·`Text` | 트리거·결과 문구 | [Button](../components/button.md), [Text](../components/text.md) |
+
+## 배치
+
+```text
+┌ GestureHandlerRootView ▸ KeyboardMotionProvider ▸ GestureSheetProvider ┐
+│ ░ 상단 안전 영역(insets.top) ░                                          │
+│ 상단 바 영역 (Container gutter 16/20)                                   │ ← 고정
+├─────────────────────────────────────────────────────────────────────────┤
+│ KeyboardFormScrollView  위아래 spacing.md 16                            │ ↑ 스크롤
+│ └ Container gutter 16/20 ▸ Stack gap="md" 16                            │ │
+│    [ 이미지 보기 ] (secondary)                                          │ │
+│    [ 시트 열기 ] (secondary)                                            │ │
+│    (길게 눌러 메뉴 열기)  ← NativeContextMenu 자식                      │ │
+│    결과 문구 (live region)                                              │ │
+│    [ 입력 TextField ]                                                   │ ↓
+├─────────────────────────────────────────────────────────────────────────┤
+│ KeyboardDock: [        완료 (primary)        ]  Container gutter       │ ← 주 행동, 키보드 위로 이동
+│ ░ 하단 안전 영역: 키보드 닫힘일 때만 insets.bottom ░                    │
+└─────────────────────────────────────────────────────────────────────────┘
+  위에 겹침: GestureSheet(하단, 50% ↔ 90%) / ImageViewer(전체 화면, safeAreaInsets)
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | `GestureHandlerRootView` ▸ `KeyboardMotionProvider` ▸ `GestureSheetProvider`(이 순서로 화면 루트에 하나씩) → 본문 `KeyboardFormScrollView` → `Container` → `Stack gap="md"` | 화면 전체. 위 안전 영역은 상단 바 영역이 `paddingTop: insets.top`으로, 아래 안전 영역은 하단 행동 영역이 받는다. 키보드: 본문은 `KeyboardFormScrollView`가 초점 필드를 올리고 하단 행동은 `KeyboardDock`이 따라 올라간다 | 본문 위아래 `spacing.md` 16, 좌우 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20), 요소 사이 `layout.contentGap` 16 |
+| 상단 | 제품 상단 바([TopBar](../components/top-bar.md) 등) | 고정, `paddingTop: insets.top` | 좌우 `Container` gutter |
+| 트리거 | `Button tone="secondary"` × 2 | 본문 맨 위 | 높이 44. 화면의 primary는 하단 완료 하나 |
+| 메뉴 트리거 | `NativeContextMenu` 자식(`Pressable` + 지역화된 `accessibilityLabel`) | 본문 안 | 터치 영역 최소 44(`control.minTouchTarget`) 권장 |
+| 결과 문구 | `Text accessibilityLiveRegion="polite"` | 메뉴 트리거 아래 | — |
+| 입력 | [TextField](../components/field.md) | 본문 끝 | 높이 44 |
+| 하단 행동 | `KeyboardDock` + `Button`(primary) | 하단 고정, 키보드가 열리면 그 위로 | 좌우 `Container` gutter, 아래 여백은 키보드 닫힘 시 `insets.bottom`·열림 시 0, 추가 간격은 `clearance`(기본 0) |
+| 시트 | `GestureSheet` + `GestureSheetInput` | 하단 오버레이 | snap 기본 50%·90%, 닫기 버튼이 본문 끝에 자동 |
+| 이미지 | `ImageViewer` | 전체 화면 오버레이 | `safeAreaInsets` 필수(가장자리까지 그릴 때) |
+
+- 하단 안전 영역은 host(제품)가 소유한다. `KeyboardDock`은 키보드만 따라가므로, 키보드가 닫혀 있을 때만 `insets.bottom`을 더한다.
+- `KeyboardDock`을 다른 키보드 회피 wrapper와 같은 내용에 겹쳐 쓰지 않는다.
+- 시트 안 입력은 `GestureSheetInput`이다. 시트의 키보드 여백은 시트가 소유하므로 시트 안에 `KeyboardFormScrollView`를 또 두지 않는다.
+
+근거: `showcase/native/src/OptionalAdapters.stories.tsx`, `packages/react-native/src/keyboard-controller.tsx`(`clearance`), `packages/react-native/src/sheet-gesture.tsx`(`snapPoints`·`busy`), `packages/react-native/src/image-viewer.tsx`(로딩·실패·다시 시도), `src/foundations.ts`(`layout`)
+
+## 흐름과 상태
+
+1. 이미지 보기를 누르면 `ImageViewer`가 `open`으로 열린다. 닫으면 unmount되어 확대 상태가 초기화된다.
+2. 시트 열기를 누르면 `GestureSheet`가 첫 snap(50%)으로 열린다. 끌어서 90%로 올리거나 아래로 끌어 닫는다.
+3. 메뉴 트리거를 길게 누르면 OS 메뉴가 열리고, 고른 항목 id가 `onAction`으로 온다. 제품은 id를 결과 문구 키로 바꿔 보인다.
+4. 입력에 초점이 가면 본문이 초점 필드를 키보드 위로 올리고, 완료 버튼이 키보드 위에 붙는다. 완료는 `Keyboard.dismiss()`다.
+5. Android back: 열린 GestureSheet가 있으면 그것부터 닫는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 트리거 두 개·메뉴 트리거·안내 결과 문구(`memo.menuHint`)·입력, 하단에 완료 | — |
+| 진행 중 | 이미지: 이미지마다 `loadingLabel` 문구. 시트 `busy`: 끌어 닫기·배경 닫기·Android back이 막힌다(코드로는 닫을 수 있다) | 이미지 로딩 문구는 live region(polite) |
+| 실패 | 이미지 로드 실패: `errorLabel` + `retryLabel` 버튼. 다시 시도는 같은 이미지를 새로 요청하고, 다시 실패하면 같은 실패 문구와 버튼으로 돌아온다. 시트·메뉴는 요청이 없다. 시트 안 저장처럼 제품 요청이 실패하면 `busy`를 풀고 시트를 연 채 실패 문구를 둔다 | 실패 문구는 live region이 아니다(함정) |
+| 시트 열림 | 하단 시트, 배경 눌러 닫기 | 열었던 트리거로 포커스 복귀는 제품이 처리 |
+| 키보드 열림 | 완료 버튼이 키보드 위, 아래 안전 영역 0 | — |
+| 메뉴 항목 disabled·danger | OS가 비활성·파괴 표시 | OS 메뉴 접근성 |
+
+메뉴 결과처럼 상태→문구 키는 상수 표로 둔다. 템플릿 문자열 키는 키 추출·누락 검사가 찾지 못한다.
+
+## 코드 골격
+
+```tsx
+// Web
+// 없음: 네 어댑터 모두 Native 전용이다. Web은 기본 Sheet·ContextMenu와 브라우저 키보드 동작을 쓴다.
+```
+
+```tsx
+// Native
+import { Keyboard, Pressable, View, useWindowDimensions } from "react-native";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { Button } from "@hjmds/react-native/actions";
+import { Container, Stack, Text } from "@hjmds/react-native/primitives";
+import { TextField } from "@hjmds/react-native/inputs";
+import { useHjmNativeTheme } from "@hjmds/react-native/provider";
+import { KeyboardMotionProvider, KeyboardDock, KeyboardFormScrollView } from "@hjmds/react-native/keyboard-controller";
+import { GestureSheet, GestureSheetProvider, GestureSheetInput } from "@hjmds/react-native/sheet-gesture";
+import { ImageViewer } from "@hjmds/react-native/image-viewer";
+import { NativeContextMenu } from "@hjmds/react-native/context-menu-native";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+
+const menuResultKey = { none: "memo.menuHint", save: "memo.saved", delete: "memo.deleted" } as const;
+const { spacing } = useHjmNativeTheme().tokens;
+const insets = useSafeAreaInsets();
+const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "compact" : "regular";
+
+<GestureHandlerRootView style={{ flex: 1 }}>
+  <KeyboardMotionProvider>
+    <GestureSheetProvider>
+      <View style={{ paddingTop: insets.top }}><Container gutter={gutter}>{topBar}</Container></View>
+      <KeyboardFormScrollView contentContainerStyle={{ paddingVertical: spacing.md }}>
+        <Container gutter={gutter}>
+          <Stack gap="md">
+            <Button tone="secondary" onPress={() => setViewer(true)}>{t("photo.view")}</Button>
+            <Button tone="secondary" onPress={() => setSheet(true)}>{t("detail.open")}</Button>
+            <NativeContextMenu items={menuItems} onAction={(id) => setMenuResult(id === "delete" ? "delete" : "save")}>
+              <Pressable accessibilityRole="button" accessibilityLabel={t("memo.moreActions")}>{card}</Pressable>
+            </NativeContextMenu>
+            <Text accessibilityLiveRegion="polite">{t(menuResultKey[menuResult])}</Text>
+            <TextField label={t("memo.label")} value={memo} onValueChange={setMemo} />
+          </Stack>
+        </Container>
+      </KeyboardFormScrollView>
+      <KeyboardDock>
+        <View style={{ paddingBottom: keyboardOpen ? 0 : insets.bottom }}>
+          <Container gutter={gutter}>
+            <Button onPress={() => Keyboard.dismiss()}>{t("common.done")}</Button>
+          </Container>
+        </View>
+      </KeyboardDock>
+      <GestureSheet open={sheet} onOpenChange={setSheet} busy={sheetBusy} title={t("detail.title")} closeLabel={t("common.close")}>
+        <GestureSheetInput accessibilityLabel={t("detail.memo")} />
+      </GestureSheet>
+      <ImageViewer open={viewer} onClose={() => setViewer(false)} safeAreaInsets={insets} items={images}
+        closeLabel={t("common.close")} previousLabel={t("common.previous")} nextLabel={t("common.next")}
+        loadingLabel={t("common.loading")} errorLabel={t("photo.loadFailed")} retryLabel={t("photo.retryLoad")} />
+    </GestureSheetProvider>
+  </KeyboardMotionProvider>
+</GestureHandlerRootView>
+```
+
+`keyboardOpen`은 `Keyboard`의 `keyboardDidShow`·`keyboardDidHide` 구독으로 제품이 만든다. `images`·`menuItems`·`card`·`topBar`·문구는 제품 소유다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 지원 | 없음(기본 Sheet·ContextMenu 사용) | 네 어댑터 experimental |
+| 실행 환경 | — | 호환 개발 클라이언트(Expo Go 불가) |
+
+## 함정
+
+- RN `Modal` 안에 GestureSheet를 두면 Android back이 `Modal`의 `onRequestClose`로만 간다. `dismissTopGestureSheet()`를 먼저 부르고 `false`일 때만 host를 닫는다.
+- KeyboardDock은 window 기준 좌표를 쓴다. Storybook 캔버스처럼 아래에 다른 영역이 남는 host에서는 위치가 어긋나 스토리가 전체 화면 `Modal`로 띄운다. 제품도 앱 크기 host에서 쓴다.
+- NativeContextMenu 패치(Zeego 3.0.6 관련)는 HJM 설치로 적용되지 않는다. `@hjmds/react-native/docs/patches/`를 제품에 복사해 등록한다.
+- 필요한 optional peer(`react-native-zoom-toolkit` 5.1.1, `react-native-keyboard-controller` 1.22.5, `@gorhom/bottom-sheet` 5.2.14, `zeego` 3.0.6 등)가 없으면 기기 Metro 번들이 실패한다.
+- 현재 `ImageViewer`는 로딩 문구만 live region이고 실패 문구(`errorLabel`)는 알리지 않는다. 실패를 낭독해야 하면 제품이 따로 알린다(renderer 수정 후보).
+- 2026-10-06 예제 검수에서 머리·본문·하단의 좌우 여백을 Container compact로 맞추고 본문 간격은 Stack md로 옮겼다. 안전 영역·키보드 좌표는 바깥 host가 유지한다. 메뉴 결과는 상태 문구와 iOS/Android 알림을 함께 갱신한다.