@hjmds/design-contracts 1.12.1 → 1.13.1

package/docs/usage/components/icon.md

@@ -0,0 +1,105 @@
+# Icon
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Icon](../../icon.md), recipe `iconRecipe`(`src/component-recipes.ts`)
+- 스토리북: `배포/컴포넌트/글자와 아이콘/아이콘`, `배포/컴포넌트/글자와 아이콘/루시드 아이콘`
+
+## 언제 쓰나
+
+HJM semantic 이름(`search`, `back`, `chevronEnd`, `notifications` 등 43개)으로 고르는 그림 기호에 쓴다.
+크기·색·선 굵기·RTL 반전은 HJM이 정하고, 그림 자체는 내장 경로(Web)나 제품이 넘긴 glyph가 그린다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 아이콘만 있는 누를 수 있는 행동 | [IconButton](icon-button.md) (이름은 버튼이 소유) |
+| 사진·일러스트 | [Image](image.md), [Asset](asset.md) |
+| 사람·계정 얼굴 | [Avatar](avatar.md) |
+| 소셜 로그인 제공자 로고 | [AuthProviderButton](auth-provider-button.md) (로고는 제품 자산) |
+| 미확인 개수 표시 | [CounterBadge](counter-badge.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Icon` | 기본 | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/primitives` |
+| `createLucideGlyph` | 보조 — Lucide glyph 연결 helper(컴포넌트 아님) | `/icon-lucide` | `/icon-lucide` |
+
+`/icon-lucide`는 optional peer가 필요하다. Web `lucide-react` 1.49.0,
+Native `lucide-react-native` 1.49.0. 루트 entry에서는 나오지 않는다.
+
+## 최소 사용 예
+
+```tsx
+// Web — 내장 glyph
+import { Icon } from "@hjmds/react/display";
+
+<Icon name="search" />
+<Icon name="warning" tone="warning" decorative={false} accessibilityLabel={t("sync.failed")} />
+```
+
+```tsx
+// Native — glyph는 제품이 공급한다(renderGlyph 필수)
+import { Icon } from "@hjmds/react-native/primitives";
+import { createLucideGlyph } from "@hjmds/react-native/icon-lucide";
+import { Search, ArrowLeft } from "lucide-react-native";
+
+const renderGlyph = createLucideGlyph({ search: Search, back: ArrowLeft });
+
+<Icon descriptor={{ name: "search" }} renderGlyph={renderGlyph} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `size` | `xs` 14 · `sm` 20 · `md` 24 · `lg` 28 · `xl` 32 · `xxl` 44 · `xxxl` 48 | `md` | — |
+| `tone` | `primary` · `secondary` · `decorative` · `brand` · `info` · `success` · `warning` · `danger` · `inverse` | `secondary` | — |
+| `weight` | `regular` · `strong` | `regular` | — |
+| `directionality` | — | — | 생략하면 `back`·`forward`·`chevronStart`·`chevronEnd`만 RTL에서 반전 |
+| `decorative` | `true` · `false` | `true` | 기본은 장식(`decorative` 생략 = true)이다. 정보 아이콘은 `decorative: false`와 현지화된 `accessibilityLabel`을 함께 준다 |
+| `renderGlyph` | `(props: { name; size: number; color: string; strokeWidth: number }) => ReactNode` | Web 내장 SVG · Native 필수 | HJM이 정한 크기·색·선 굵기를 받아 그린다. Native `name`은 `Icon<Name>`의 제품 이름 타입 |
+| `layoutStyle` | 배치 key | — | 바깥 배치만. 크기·색은 `size`·`tone`으로 |
+
+- 묘사 객체 모양(Native `descriptor`, Web 평평한 prop 같은 이름): 장식 `{ name, size?, tone?, weight?, directionality?, decorative?: true }`,
+  정보 `{ name, …, tone?: decorative 제외, decorative: false, accessibilityLabel: string }`. 두 모양은 타입으로 갈린다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | `size`로만 정한다. 정사각형 프레임 한 변이 `glyph` 값이다(`md` 24 기본, `sm` 20, `xs` 14). Icon은 누를 수 없고 터치 영역이 없다. 누를 수 있게 하려면 최소 44(`control.minTouchTarget`)를 갖는 [IconButton](icon-button.md)으로 감싼다 | `design-contracts/src/foundations.ts`(`glyph`, `control`) |
+| 간격 | 글자와의 간격은 감싸는 컴포넌트가 정한다(Link `spacing.xxs` 4, ListRow `spacing.sm` 12) | `design-contracts/src/component-recipes.ts` |
+| 순서·정렬 | 텍스트 옆 아이콘은 글자와 세로 가운데로 맞춘다(Web `.hjm-icon`은 `vertical-align: middle`, `flex: 0 0 auto`로 줄어들지 않는다) | `react/src/styles.css`(`.hjm-icon`) |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 큰 글자 설정에서도 크기가 늘지 않는다. 글자와 함께 커져야 하면 더 큰 `size`를 제품이 고른다 | `react-native/src/primitives.tsx`(Icon) |
+
+## 꼭 지킬 것
+
+- 장식 아이콘에 `accessibilityLabel`을 주거나, 정보 아이콘에 라벨을 빼면 `TypeError`가 난다.
+  정보 아이콘에는 `decorative` tone도 쓸 수 없다.
+- 이름은 모양이 아니라 목적으로 읽힌다. icon-only 행동의 이름은 바깥 IconButton·Link에 둔다.
+- `inverse`는 brand·danger처럼 채워진 면 위에서만 쓴다.
+- 크기·색·stroke를 `style`·`className`·glyph 쪽에서 바꾸지 않는다. 그림 라이브러리는 제품이 고르고
+  (`createLucideGlyph`에 named import만 넘김), 의미 이름과 외형은 HJM이 소유한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| API 모양 | 평평한 prop(`name`, `size`, `tone` …) | `descriptor` 객체 하나 |
+| glyph | 내장 SVG 경로, `renderGlyph`는 선택 | `renderGlyph` 필수(내장 그림 없음) |
+| 사용자 정의 이름 | `SemanticIconName`만 | `Icon<Name>` 제네릭으로 제품 이름 허용 |
+| 출력 | `<svg>`(장식이면 `aria-hidden`) | `View` 프레임(장식이면 `accessible={false}`) |
+| 배치 | `layoutStyle` | `layoutStyle`. `style`은 deprecated(개발 모드 1회 경고, 다음 major 제거) — `layoutStyle` 또는 descriptor `size`·`tone` |
+
+## 함정
+
+- 아이콘은 자기 `tone` 색을 직접 칠한다. Web CSS가 `data-tone`으로 색을 지정하므로 부모 색을 상속하지 않는다.
+  primary·danger IconButton 안에서 기본 tone(`secondary`)을 쓰면 채워진 면 위에 회색이 된다. 이때는 `tone="inverse"`.
+- `createLucideGlyph` 맵에 없는 이름을 그리면 실행 중 `TypeError`가 난다.

package/docs/usage/components/image.md

@@ -0,0 +1,122 @@
+# Image
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Image](../../image.md), [GridReveal](../../grid-reveal.md), [ImageViewer](../../optional-adapters.md#behavior-boundaries), recipe `imageRecipe`(`src/image.ts`)
+- 스토리북: `배포/컴포넌트/데이터 표시/이미지` · `배포/컴포넌트/시각 효과/격자 등장 효과`
+
+## 언제 쓰나
+
+원본 크기를 아는 사진·차트 이미지를 로드 전에 자리를 잡아 두고, 실패해도 의미를 잃지 않게 보여 줄 때 쓴다.
+로드 완료 순간 격자 마스크로 드러내려면 `GridReveal`로 감싸고, Native에서 사진을 크게 넘겨 보며
+확대하려면 `ImageViewer`를 연다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 의미 이름으로 고르는 그림 기호 | [Icon](icon.md) |
+| 사람·계정 얼굴, 이니셜 대체 | [Avatar](avatar.md) |
+| 제품 일러스트·자산 묶음 | [Asset](asset.md) |
+| 크기를 모르는 임의 콘텐츠의 비율 고정 | [AspectRatio](aspect-ratio.md) |
+| 여러 장을 넘겨 보는 띠 | [Carousel](carousel.md) |
+| 높이가 다른 사진 카드 격자 | [Masonry](masonry.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Image` | 기본 | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/data-display` |
+| `GridReveal` | 확장 — 로드 완료 시 4×4 마스크 연출(optional) | `/grid-reveal` | `/grid-reveal` |
+| `ImageViewer` | 확장 — 전체 화면 넘겨 보기·확대(optional) | — | `/image-viewer` |
+
+`GridReveal`은 추가 peer가 없다. `ImageViewer`는 granular subpath로만 import 되며 optional peer
+`react-native-zoom-toolkit` 5.1.1, `react-native-gesture-handler` 2.32.0과 Reanimated·Worklets 설치가 필요하다.
+Expo Go로는 검증할 수 없고 개발 클라이언트가 필요하다. tsc·테스트 통과는 peer 설치의 근거가 아니다.
+
+## 최소 사용 예
+
+```tsx
+// Web — next/image 같은 adapter는 renderImage로 연결
+import { Image } from "@hjmds/react/display";
+import { GridReveal } from "@hjmds/react/grid-reveal";
+
+<GridReveal ready={loaded}>
+  <Image src={photo.url} width={photo.width} height={photo.height}
+    decorative={false} accessibilityLabel={t("gallery.photoAlt", { title: photo.title })}
+    onLoadStatusChange={(status) => setLoaded(status === "loaded")} />
+</GridReveal>
+```
+
+```tsx
+// Native
+import { Image } from "@hjmds/react-native/data-display";
+import { ImageViewer } from "@hjmds/react-native/image-viewer";
+
+<Image src={chart.url} width={800} height={450}
+  decorative={false} accessibilityLabel={t("stats.chartAlt")} layoutStyle={{ width: "100%" }} />
+
+<ImageViewer open={viewerOpen} onClose={() => setViewerOpen(false)} items={photos}
+  safeAreaInsets={insets} closeLabel={t("common.close")} previousLabel={t("viewer.prev")}
+  nextLabel={t("viewer.next")} loadingLabel={t("common.loading")}
+  errorLabel={t("viewer.loadFailed")} retryLabel={t("common.retry")} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `src`, `width`, `height` | 필수, 양의 유한수 | — | 비율로 자리를 예약하고 루트 폭 기본값은 `width`다 |
+| `fit` | `cover` · `contain` · `fill` | `cover` | `fill`은 Native `stretch`로 번역 |
+| `decorative` | `true` · `false` | `true` | 기본은 장식이다. 이미지만으로 정보를 전하면 `decorative: false`와 현지화된 `accessibilityLabel`을 함께 준다 |
+| `accessibilityLabel` | 현지화 문구 | — | `decorative={false}`일 때만, 필수. Web은 `<img alt>`(실패 대체는 `aria-label`)로 간다. Web도 `alt` prop은 받지 않는다 |
+| `fallback` | `ReactNode` | 중립 배경 + 오류 기호 | 시각만 바꾼다 |
+| `onLoadStatusChange` | `(status: "loaded" \| "error") => void` | — | 로드 완료·실패를 한 번씩 알린다. GridReveal `ready`를 이 값으로 정한다 |
+| `renderImage` | Web `(props: ImageAdapterProps) => ReactElement` · Native `(props: CanonicalImageRenderProps) => ReactNode` | `<img>` · RN `Image` | adapter는 받은 `onLoad`·`onError`를 실제 요소에 넘긴다 |
+| Native `sourceAdapter` | `(descriptor: ResolvedImageDescriptor) => ImageSourcePropType` | — | 헤더·캐시가 필요한 원격 이미지 |
+| GridReveal `ready` | `true` · `false` | — (필수) | — |
+| GridReveal `active` | `true` · `false` | `true` | — |
+| ImageViewer `items` | `id`·`uri`·`label` | — | 라벨 6종, `safeAreaInsets`가 필수 |
+| ImageViewer `initialIndex` | 0 이상 정수 | `0` | — |
+| ImageViewer `onClose` · `onIndexChange` | `() => void` · `(index: number) => void` | `onClose` 필수 | — |
+| ImageViewer `safeAreaInsets` | `{ top: number; bottom: number }` | 필수 | — |
+
+- 실패하면 중립 배경 위에 오류 기호를 그리고, 정보 이미지의 이름은 그대로 유지한다. `fallback`은 시각만 바꾼다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 자리는 `width`·`height` 비율로 미리 잡는다(Web `aspect-ratio`, Native `aspectRatio`). 로드 전후로 높이가 바뀌지 않는다. 모서리는 `radius.md` 12로 잘린다(`imageRecipe.radius`) | `design-contracts/src/image.ts`(`imageRecipe`), `design-contracts/src/foundations.ts`(`radius`), `react/src/supplemental-display.tsx`(Image) |
+| 간격 | 카드 안에 넣을 때 카드 padding 안쪽에 둔다 | — |
+| 순서·정렬 | 여러 장은 직접 줄 세우지 말고 [Grid](grid.md)·[Masonry](masonry.md)·[Carousel](carousel.md)로 배치한다 | — |
+| 고정·스크롤 | ImageViewer는 전체 화면을 덮는다. 상·하단 버튼은 `safeAreaInsets` 안쪽에 그려지므로 호스트가 inset을 넘긴다 | `react-native/src/image-viewer.tsx` |
+| 좁은 폭·큰 글자 | Web 루트는 `inline-size: width`, `max-inline-size: 100%`라 부모보다 넓어지지 않는다. Native 루트 폭은 `width` 숫자 그대로이므로 화면 폭 사진은 `layoutStyle={{ width: "100%" }}`로 준다. Grid·Masonry 칸에 채울 때 Web은 `layoutStyle={{ inlineSize: "100%" }}`(루트 `style`도 기본 `inline-size`를 덮는다), Native는 `layoutStyle={{ width: "100%" }}`로 칸 폭에 맞춘다. 원본이 칸보다 작으면 기본값으로는 좁게 남는다 | `react/src/styles.css`(`.hjm-image`), `react-native/src/data-display.tsx`(Image) |
+
+## 꼭 지킬 것
+
+- 장식인데 라벨을 주거나 정보인데 라벨을 빼면 `TypeError`가 난다.
+- GridReveal의 `ready`는 `onLoadStatusChange`가 `loaded`일 때만 true, 오류·소스 변경·재시도 전에는 false로 돌린다.
+  Native에서 화면이 가려진 채 mounted면 `active={false}`.
+- ImageViewer는 `open`으로 제어하고 닫히면 상태를 버린다. 라벨·`id`가 비거나 중복이면 `TypeError`.
+- ImageViewer는 불러오는 중(`loadingLabel`)과 실패(`errorLabel`)를 모두 알린다. 실패는 Android assertive live region, iOS는 `announceForAccessibility`다(미게시(1.12.1 이후). 1.12.1은 실패를 알리지 않았다).
+- 원격 이미지 권한·URL 수명·캐시는 제품 소유다. HJM은 메타데이터를 가져오지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 배치 | `layoutStyle`, 루트 `style`/`className`(기본 `inline-size: width`, `max-inline-size: 100%`) | `layoutStyle`(루트 프레임) |
+| 정보 이미지 이름 | `accessibilityLabel` → `<img alt>`(`alt` prop은 받지 않는다) | `accessibilityLabel` |
+| 이미지 host 스타일 | `imageProps.style`/`className` | `style`(ImageStyle) |
+| 다른 이미지 엔진 | `renderImage`(받은 props를 `<img>`까지 전달) | `renderImage`(예: expo-image), `sourceAdapter`(헤더·캐시) |
+| 확대 보기 | — | `ImageViewer` |
+
+## 함정
+
+- `renderImage` adapter가 받은 `onLoad`·`onError`를 실제 이미지 요소에 넘기지 않으면 HJM이 실패를 보지 못해
+  대체 화면과 GridReveal의 `ready`가 동작하지 않는다.
+- Native 루트 폭은 `width` 숫자 그대로다. 화면 폭에 맞추려면 `layoutStyle`로 폭을 준다.

package/docs/usage/components/keyboard-avoiding.md

@@ -0,0 +1,93 @@
+# KeyboardAvoiding
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Native platform](../../native-platform.md#키보드-회피), 판정 `resolveKeyboardInset`(`src/native-platform.ts`)
+- 스토리북: 없음
+
+## 언제 쓰나
+
+추가 native peer 없이 하단 행동(BottomCTA, 채팅 입력창)이 소프트웨어 키보드에 가려지지 않게 할 때 쓴다.
+키보드가 뜨면 측정한 높이만큼 아래 여백을 늘리고, 내려가면 safe area 여백만 남긴다.
+`react-native-keyboard-controller`를 설치하지 않은 앱의 기본 선택이다(Native 전용, 별도 보조 기능).
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| keyboard-controller를 설치한 앱에서 하단 행동을 키보드에 붙여 움직임 | [KeyboardDock](keyboard-dock.md) |
+| 입력이 여러 개인 스크롤 폼에서 포커스된 필드를 보이게 | [KeyboardFormScrollView](keyboard-form-scroll-view.md) |
+| keyboard-controller 어댑터를 쓰기 위한 앱 루트 설정 | [KeyboardMotionProvider](keyboard-motion-provider.md) |
+| Sheet 안의 입력 | [Sheet](sheet.md)의 `keyboardAvoidance` (시트가 여백을 소유) |
+| Web | 해당 없음. Web에는 이 문제와 계약이 없다 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `KeyboardAvoiding` | 기본 | — | `@hjmds/react-native`, `/keyboard` |
+| `resolveKeyboardAvoidanceBehavior` | 보조 — 플랫폼별 `KeyboardAvoidingView` behavior 판정 함수 | — | 같은 entry |
+
+추가 peer가 필요 없다.
+
+## 최소 사용 예
+
+Web: 없음. Web 구현은 없다.
+
+```tsx
+// Native
+import { KeyboardAvoiding } from "@hjmds/react-native/keyboard";
+import { BottomCTA } from "@hjmds/react-native/bottom-cta";
+
+<KeyboardAvoiding safeAreaBottom={insets.bottom}>
+  <BottomCTA primaryAction={{ label: t("signup.next"), onPress: next }} />
+</KeyboardAvoiding>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `offset` | 숫자 | `spacing.sm`(12) | 키보드 위에 남길 여백 |
+| `safeAreaBottom` | 숫자 | `0` | 하단 safe area 값. 키보드가 닫혀 있으면 이 값만큼, 열려 있으면 키보드 높이 + `offset` 만큼 아래 여백을 준다. safe area는 한 번만 센다 |
+| `style` | `StyleProp<ViewStyle>` | — | 감싸는 `View`의 스타일. renderer가 주는 `paddingBottom` 뒤에 합쳐진다. 플랫폼 host라 1.13 deprecated 대상이 아니고 `layoutStyle`은 없다 |
+| `resolveKeyboardAvoidanceBehavior` | `(platform: "ios" \| "android") => KeyboardAvoidanceBehavior` | — | RN `KeyboardAvoidingView`를 직접 쓸 때의 `behavior` 판정. 이 컴포넌트는 쓰지 않는다 |
+
+- 콜백·상태 prop은 없다. 키보드 높이는 컴포넌트 안에서 키보드 이벤트로 잰다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 아래 여백: 키보드 닫힘 = `safeAreaBottom`, 열림 = 키보드 높이 + `offset`(기본 `spacing.sm` 12) | `design-contracts/src/native-platform.ts`(`resolveKeyboardInset`, `keyboardAvoidanceDefaults`) |
+| 간격 | safe area는 키보드 높이 안에 포함돼 한 번만 센다 | `design-contracts/src/native-platform.ts`(`resolveKeyboardInset`) |
+| 순서·정렬 | 화면 맨 아래, 스크롤 영역 **바깥**에서 하단 행동(BottomCTA, 입력창)만 감싼다. 본문 스크롤은 위에 따로 둔다 | `react-native/src/keyboard.tsx` |
+| 고정·스크롤 | 높이 변화는 키보드 이벤트에 맞춰 `LayoutAnimation`(easeInEaseOut)으로 움직인다 | `react-native/src/keyboard.tsx` |
+| 좁은 폭·큰 글자 | — | — |
+
+```text
+키보드 닫힘                         키보드 열림
+┌──────────────────────┐            ┌──────────────────────┐
+│ 본문(스크롤)          │            │ 본문(스크롤, 줄어듦)  │
+│                      │            ├──────────────────────┤
+├──────────────────────┤            │ [     다음(primary)   ]│ ← KeyboardAvoiding 안
+│ [     다음(primary)   ]│ ← 고정    ├────── offset 12 ──────┤
+├── safeAreaBottom ────┤            │ ░░░░░ 키보드 ░░░░░░░ │
+└──────────────────────┘            └──────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 같은 내용을 다른 키보드 회피 래퍼(`KeyboardAvoidingView`, KeyboardDock, 호스트 어댑터)와 겹쳐 감싸지 않는다.
+- safe area 여백을 안쪽 컴포넌트(BottomCTA `safeAreaBottom` 등)와 이 래퍼에 동시에 주지 않는다. 한 곳에서만 센다.
+- `style`로 `paddingBottom`을 덮으면 키보드 여백이 사라진다. 배치 외 값을 넣지 않는다.
+
+## 함정
+
+- `KeyboardAvoidingView`가 아니다. 플랫폼과 무관하게 키보드 이벤트로 잰 높이를 `paddingBottom`으로 준다
+  (iOS는 `keyboardWillChangeFrame`, Android는 `keyboardDidShow`). `resolveKeyboardAvoidanceBehavior`는
+  제품이 RN `KeyboardAvoidingView`를 직접 쓸 때를 위한 판정이며 이 컴포넌트는 그 값을 쓰지 않는다.
+- 이 래퍼는 아래 여백만 늘린다. 스크롤 안의 포커스된 필드를 보이는 곳으로 옮겨 주지 않는다.

package/docs/usage/components/keyboard-dock.md

@@ -0,0 +1,110 @@
+# KeyboardDock
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Optional adapters](../../optional-adapters.md#behavior-boundaries). 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/구성/직접 조작과 모션/이미지·시트·키보드 조작`
+
+## 언제 쓰나
+
+`react-native-keyboard-controller`를 설치한 앱에서 화면 하단에 고정된 행동(BottomCTA, 채팅 입력창)이
+키보드와 함께 위아래로 움직이게 할 때 쓴다(Native 전용, 별도 보조 기능. API 성숙도는 실험적 어댑터). 내부는 `KeyboardStickyView`이며,
+여백을 바꾸는 대신 키보드 움직임을 따라 translate 한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| keyboard-controller 없이 하단 행동을 키보드 위로 | [KeyboardAvoiding](keyboard-avoiding.md) |
+| 입력이 여러 개인 스크롤 폼 본문 | [KeyboardFormScrollView](keyboard-form-scroll-view.md) (하단 버튼은 이 Dock과 함께) |
+| 앱 루트 설정 | [KeyboardMotionProvider](keyboard-motion-provider.md) (먼저 필요) |
+| Sheet 안의 입력 | [Sheet](sheet.md)의 `keyboardAvoidance` |
+| Web | 해당 없음 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `KeyboardDock` | 기본 — 하단 고정 행동을 키보드에 붙임 | — | `/keyboard-controller` |
+
+granular subpath로만 import 된다. 설치 조건(peer `react-native-keyboard-controller` 1.22.5, Reanimated·Worklets,
+개발 클라이언트)과 루트 Provider는 [KeyboardMotionProvider](keyboard-motion-provider.md)를 따른다.
+
+## 최소 사용 예
+
+Web: 없음. Web 구현은 없다.
+
+```tsx
+// Native — KeyboardMotionProvider 안, KeyboardFormScrollView의 다음 형제
+import { View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useKeyboardState } from "react-native-keyboard-controller";
+import { KeyboardDock } from "@hjmds/react-native/keyboard-controller";
+import { Button } from "@hjmds/react-native/actions";
+import { Container } from "@hjmds/react-native/primitives";
+
+const insets = useSafeAreaInsets();
+const keyboardOpen = useKeyboardState((state) => state.isVisible);
+
+<KeyboardDock clearance={8}>
+  <View style={{ paddingBottom: keyboardOpen ? 0 : insets.bottom }}>
+    <Container gutter="compact">
+      <Button onPress={submit} fullWidth>{t("form.done")}</Button>
+    </Container>
+  </View>
+</KeyboardDock>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `enabled` | `true` · `false` | `true` | `false`면 따라 움직이지 않는다 |
+| `clearance` | 0 이상 숫자(layout point) | `0` | 키보드 위 추가 간격. 음수나 유한하지 않은 값은 `TypeError` |
+| `children` | ReactNode(필수) | — | 하단 행동. 안쪽 여백·안전 영역은 호스트가 준다 |
+| `style` | `StyleProp<ViewStyle>` | — | 감싸는 sticky view의 host 스타일. 플랫폼 host라 1.13 deprecated 대상이 아니다([이관 문서](../../migration-native-legacy-removal.md#113-deprecated-시각-style-제거는-다음-major)). 배치 값만 넣는다 |
+
+- 이벤트·콜백 prop은 없다. 키보드 열림 여부가 필요하면 peer의 `useKeyboardState((state) => state.isVisible)`로 읽는다.
+- 내부에서 `KeyboardStickyView`에 `offset={{ closed: 0, opened: -clearance }}`를 넘긴다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | — | — |
+| 간격 | 안쪽 여백은 호스트가 준다. 좌우는 화면 본문과 같은 [Container](container.md) `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20 — [화면 여백과 너비](../tokens/layout.md)), 아래는 키보드 닫힘이면 `insets.bottom`, 열림이면 0이다. 키보드와의 추가 간격은 `clearance`(기본 0)로만 준다 | `react-native/src/keyboard-controller.tsx`, `tokens/layout.md` |
+| 순서·정렬 | 화면 맨 아래, 스크롤 영역([KeyboardFormScrollView](keyboard-form-scroll-view.md)) **다음 형제**로 둔다 | `showcase/native/src/OptionalAdapters.stories.tsx` |
+| 고정·스크롤 | 키보드가 열리면 그만큼 위로 translate 된다 | `react-native/src/keyboard-controller.tsx` |
+| 좁은 폭·큰 글자 | — | — |
+
+```text
+┌──────────────────────────┐
+│ 상단 고정 영역(insets.top) │
+├──────────────────────────┤
+│ KeyboardFormScrollView    │ ← 스크롤 영역, 안에 Container(gutter)
+│  필드 / 필드 / ...        │
+├──────────────────────────┤
+│ [        완료        ]    │ ← KeyboardDock 안 Container(gutter) — 주 행동
+├── insets.bottom(닫힘) / 0(열림) ──┤
+└──────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 하단 safe area는 호스트가 소유한다. 키보드가 열렸을 때 safe area 여백을 빼는 것도 호스트 몫이다
+  (키보드 상태에 따라 `paddingBottom`을 `insets.bottom`과 0 사이에서 바꾼다).
+- 좌우 여백은 숫자로 쓰지 않고 [Container](container.md) `gutter`로 준다.
+- 같은 내용을 KeyboardAvoiding이나 다른 키보드 회피 래퍼로 또 감싸지 않는다.
+- KeyboardMotionProvider 없이 쓰지 않는다.
+
+## 함정
+
+- 현재 쇼케이스(`showcase/native/src/OptionalAdapters.stories.tsx`)는 Dock 안 좌우 여백을 `paddingHorizontal: spacing.md`로
+  직접 주고, 키보드 상태를 `Keyboard.addListener`로 따로 추적하며, 버튼 문구가 i18n 키가 아니다. 규칙은 위 예처럼 Container `gutter`와 i18n 키다.
+
+- sticky 좌표는 창 기준이다. Storybook 캔버스처럼 아래에 다른 막대가 있는 host에서는 위치가 어긋나므로
+  쇼케이스도 앱 크기 host에서 확인한다.
+- API 성숙도가 실험적 어댑터다(2026-10-06 Storybook 배포와 별개, [근거](../../optional-adapters.md#evidence-and-promotion)). 실제 키보드 애니메이션은 mock 테스트로 검증되지 않는다. 개발 클라이언트로 확인한다.

package/docs/usage/components/keyboard-form-scroll-view.md

@@ -0,0 +1,95 @@
+# KeyboardFormScrollView
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Optional adapters](../../optional-adapters.md#behavior-boundaries). 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/구성/직접 조작과 모션/이미지·시트·키보드 조작`
+
+## 언제 쓰나
+
+입력 필드가 여러 개인 세로 스크롤 폼(가입, 프로필 수정, 주소 입력)에서 포커스된 필드가 키보드에
+가려지지 않게 스크롤해 줄 때 쓴다(Native 전용, 별도 보조 기능. API 성숙도는 실험적 어댑터). 내부는 `react-native-keyboard-controller`의
+`KeyboardAwareScrollView`이고, `keyboardShouldPersistTaps="handled"`로 고정돼 키보드가 열린 채 버튼을 눌러도 탭이 전달된다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 화면 하단에 고정된 버튼·입력창을 키보드에 붙임 | [KeyboardDock](keyboard-dock.md) (이 폼과 함께 쓸 수 있다) |
+| peer 없이 하단 행동만 올림 | [KeyboardAvoiding](keyboard-avoiding.md) |
+| 앱 루트 설정 | [KeyboardMotionProvider](keyboard-motion-provider.md) (먼저 필요) |
+| 입력 묶음·검증 구조 | [Form](form.md) (스크롤 컨테이너가 아니다) |
+| Sheet 안의 입력 | [Sheet](sheet.md)의 `keyboardAvoidance` |
+| Web | 해당 없음 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `KeyboardFormScrollView` | 기본 — 키보드 인지 폼 스크롤 | — | `/keyboard-controller` |
+
+granular subpath로만 import 된다. 설치 조건과 루트 Provider는 [KeyboardMotionProvider](keyboard-motion-provider.md)를 따른다.
+
+## 최소 사용 예
+
+Web: 없음. Web 구현은 없다.
+
+```tsx
+// Native — KeyboardMotionProvider 안
+import { KeyboardFormScrollView } from "@hjmds/react-native/keyboard-controller";
+import { Container, Stack } from "@hjmds/react-native/primitives";
+import { TextField } from "@hjmds/react-native/inputs";
+import { spacing } from "@hjmds/design-contracts/foundations";
+
+<KeyboardFormScrollView contentContainerStyle={{ paddingVertical: spacing.md }} bottomOffset={spacing.md}>
+  <Container gutter="compact">
+    <Stack gap="md">
+      <TextField label={t("profile.name")} value={name} onValueChange={setName} />
+      <TextField label={t("profile.email")} value={email} onValueChange={setEmail} />
+    </Stack>
+  </Container>
+</KeyboardFormScrollView>
+```
+
+스크롤 컨테이너는 세로 여백만 갖고, 좌우 여백은 안쪽 [Container](container.md) `gutter`(폭 600 미만 `compact` 16, 이상
+`regular` 20), 필드 사이는 [Stack](stack.md) `gap`이 준다.
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `bottomOffset` | 숫자(layout point) | `0`(peer 기본값) | 포커스된 입력의 caret과 키보드 사이 거리 |
+| `enabled` | `true` · `false` | `true`(peer 기본값) | `false`면 키보드에 맞춰 스크롤하지 않는다 |
+| `contentContainerStyle` | `StyleProp<ViewStyle>` | — | 세로 여백만 준다. 좌우 여백·필드 간격은 Container·Stack |
+| `style` | `StyleProp<ViewStyle>` | — | 스크롤 view 자체의 배치(`flex: 1` 등) |
+| `keyboardShouldPersistTaps` | `"handled"` | `"handled"`(고정) | 바꿀 수 없다 |
+
+- 받는 prop은 `children`, `style`, `contentContainerStyle`, `bottomOffset`, `enabled`, `testID`뿐이다. 이벤트·콜백 prop은 없다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 화면 본문 전체를 차지하는 스크롤 영역으로 둔다 | `showcase/native/src/OptionalAdapters.stories.tsx` |
+| 간격 | 세로 여백은 `contentContainerStyle`의 `paddingVertical`(`spacing.md` 16), 좌우 여백은 안쪽 [Container](container.md) `gutter`(폭 600 미만 16, 이상 20), 필드 사이는 [Stack](stack.md) `gap="md"` 16(`layout.contentGap`). 필드와 키보드 사이 여백은 `bottomOffset`으로 준다 | `tokens/layout.md`, `react-native/src/keyboard-controller.tsx` |
+| 순서·정렬 | 위에는 고정 헤더, 아래에는 [KeyboardDock](keyboard-dock.md)으로 붙인 하단 행동을 형제로 둔다 | `showcase/native/src/OptionalAdapters.stories.tsx` |
+| 고정·스크롤 | 포커스된 필드가 키보드 위로 보일 때까지 스크롤된다 | `react-native/src/keyboard-controller.tsx` |
+| 좁은 폭·큰 글자 | 큰 글자에서 필드가 길어져도 스크롤로 받는다. 높이를 고정하지 않는다 | — |
+
+## 꼭 지킬 것
+
+- KeyboardMotionProvider 없이 쓰지 않는다.
+- 다른 ScrollView 안에 넣지 않는다. 스크롤 컨테이너는 하나만 둔다.
+- 같은 내용을 KeyboardAvoiding이나 `KeyboardAvoidingView`로 또 감싸지 않는다.
+- `contentContainerStyle`에는 세로 여백만 HJM spacing 토큰으로 준다. 좌우 여백을 숫자로 넣지 않는다.
+
+## 함정
+
+- 현재 쇼케이스(`showcase/native/src/OptionalAdapters.stories.tsx`)는 `contentContainerStyle={{ gap: spacing.md, padding: spacing.md }}`로
+  좌우 여백까지 스크롤 컨테이너에 직접 준다. 규칙은 세로 여백만 스크롤에, 좌우는 Container `gutter`다.
+
+- `refreshControl`, `onScroll` 같은 다른 ScrollView prop은 타입에서 빠져 있어 넘길 수 없다.
+- API 성숙도가 실험적 어댑터다(2026-10-06 Storybook 배포와 별개, [근거](../../optional-adapters.md#evidence-and-promotion)). 포커스 이동·키보드 애니메이션은 개발 클라이언트로 기기에서 확인한다.

package/docs/usage/components/keyboard-motion-provider.md

@@ -0,0 +1,86 @@
+# KeyboardMotionProvider
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Optional adapters](../../optional-adapters.md#installation). 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/구성/직접 조작과 모션/이미지·시트·키보드 조작`
+
+## 언제 쓰나
+
+`@hjmds/react-native/keyboard-controller` 어댑터(KeyboardDock, KeyboardFormScrollView)를 쓰는 앱의
+루트에 **한 번** 설치한다(Native 전용, 별도 보조 기능. API 성숙도는 실험적 어댑터). 내부는 `react-native-keyboard-controller`의
+`KeyboardProvider`이며, 어댑터를 준비하려고 OS 키보드를 미리 띄우지 않도록 `preload={false}`로 고정돼 있다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| peer 없이 하단 행동만 키보드 위로 올림 | [KeyboardAvoiding](keyboard-avoiding.md) (Provider 불필요) |
+| 하단 행동을 키보드에 붙여 움직임 | [KeyboardDock](keyboard-dock.md) (이 Provider 안에서) |
+| 스크롤 폼의 포커스 필드 보이기 | [KeyboardFormScrollView](keyboard-form-scroll-view.md) (이 Provider 안에서) |
+| HJM 테마·환경 설정 | [DesignSystemProvider](design-system-provider.md) (역할이 다르다) |
+| Web | 해당 없음 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `KeyboardMotionProvider` | 기본 — 앱 루트 provider | — | `/keyboard-controller` |
+
+granular subpath로만 import 된다(루트 entry에 없음). optional peer `react-native-keyboard-controller` 1.22.5와
+`react-native-reanimated`(^4.5.1)·`react-native-worklets`(^0.10.1)를 앱에 설치해야 한다.
+native 모듈이 연결된 개발 클라이언트가 필요하며 Expo Go로는 확인할 수 없다.
+
+## 최소 사용 예
+
+Web: 없음. Web 구현은 없다.
+
+```tsx
+// Native — 앱 루트
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { KeyboardMotionProvider } from "@hjmds/react-native/keyboard-controller";
+
+<GestureHandlerRootView style={{ flex: 1 }}>
+  <KeyboardMotionProvider>
+    <AppNavigator />
+  </KeyboardMotionProvider>
+</GestureHandlerRootView>
+```
+
+`GestureHandlerRootView`는 쇼케이스 host 구성이며, 앱이 gesture 어댑터를 함께 쓸 때 필요하다.
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` | ReactNode | — | prop은 `children` 하나뿐이다 |
+| `preload` | `false` | `false`(고정) | 바꿀 수 없다 |
+
+- 이벤트·콜백 prop은 없다. 키보드 상태가 필요하면 peer의 `useKeyboardState`·`useKeyboardHandler`를 이 Provider 아래에서 쓴다.
+- 렌더하는 상자가 없어 `layoutStyle`·`style`을 받지 않는다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 화면에 그려지는 것이 없다 | `react-native/src/keyboard-controller.tsx` |
+| 간격 | — | — |
+| 순서·정렬 | 앱 루트(`GestureHandlerRootView` 안, 내비게이터 바깥)에 한 번 둔다. KeyboardDock·KeyboardFormScrollView는 이 Provider 아래 어느 화면에나 놓을 수 있다 | `showcase/native/src/OptionalAdapters.stories.tsx` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | — | — |
+
+## 꼭 지킬 것
+
+- 앱 루트에 한 번만 둔다. 입력 필드·CTA·화면마다 중첩하지 않는다.
+- KeyboardDock·KeyboardFormScrollView는 이 Provider 바깥에 두지 않는다.
+- 같은 앱에서 이 어댑터와 KeyboardAvoiding을 섞을 수는 있지만 같은 내용에 겹쳐 감싸지 않는다.
+
+## 함정
+
+- tsc·mock 테스트 통과는 peer 설치와 native 연결의 근거가 아니다. 다른 optional subpath
+  (celebration·effect-surface·qr-code·thinking-orb·toast-liquid)에서 앱에 없는 peer 때문에
+  기기 Metro에서만 크래시가 난 사례가 있다(2026-10). 개발 클라이언트로 실제 화면을 띄워 확인한다.
+- 이 어댑터의 API 성숙도는 실험이다(2026-10-06 Storybook 배포와 별개). 기기·보조기술 검증은 아직 없다([근거](../../optional-adapters.md#evidence-and-promotion)).