@hjmds/design-contracts 1.12.1 → 1.13.0

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

@@ -0,0 +1,109 @@
+# 숫자 변화와 메뉴 변형
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Statistic](../../statistic.md), [선택 어댑터](../../optional-adapters.md), `showcase/web/src/components/OptionalMotion.stories.tsx`
+- 스토리북: `배포/구성/직접 조작과 모션/숫자 변화와 메뉴 변형`
+
+## 언제 쓰나
+
+선택 설치 모션(숫자 자리 단위 변화, 메뉴 형태 변환)을 기존 컴포넌트 자리에 끼워 넣을 때 쓴다. 숫자 지표가 사용자 행동으로
+바뀌는 곳에 AnimatedStatistic을, 실행만 하는 짧은 작업 메뉴에 MorphingMenu를 둔다. 모션이 꺼진 환경에서는 둘 다 기본
+컴포넌트 동작으로 돌아간다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| AnimatedStatistic (`/statistic-motion`) | 숫자 값 변화를 자리 단위로 보인다(optional peer `@number-flow/react` 0.6.2) | [Statistic](../components/statistic.md) |
+| Button | 값을 바꾸는 행동 | [Button](../components/button.md) |
+| MorphingMenu (`/menu-morph`) | 실행 전용 작업 메뉴(optional peer `bloom-menu` 0.1.0) | [Menu](../components/menu.md) |
+| `Text role="status"` | 마지막 실행·갱신 결과 문구 | [Text](../components/text.md) |
+| Stack | 세로 묶음 간격 | [Stack](../components/stack.md) |
+
+## 배치
+
+```text
+┌ 제품 화면 Container(gutter) 안 ─────────────┐
+│ Stack gap="md" 16                           │
+│ 조회 수                                     │
+│ 1,280           ← AnimatedStatistic         │
+│ [ 조회 수 새로고침 ]  secondary             │
+│ [ 작업 선택 ▾ ]   ← MorphingMenu 트리거     │
+│   ├ 저장                                    │
+│   ├ 공유                                    │
+│   └ 삭제 (disabled)                         │
+│ 결과 문구        ← Text role="status"       │
+└─────────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | 제품 화면의 `Container`(좌우 여백·최대 폭) 안에 `Stack gap="md"` | 본문 흐름 안. 스크롤·안전 영역은 화면(문서 스크롤)이 소유하고, 텍스트 입력이 없어 키보드 처리는 없다 | 좌우 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 요소 사이 `layout.contentGap` 16. 다른 구획과는 `layout.sectionGap` 24 |
+| 지표 | AnimatedStatistic | 맨 위 | 값은 Statistic `comfortable`(`heading` 크기) |
+| 값 갱신 | Button `secondary` | 지표 아래 | 높이 `medium` 44. 화면의 primary는 제품 주 행동에 남긴다 |
+| 작업 메뉴 | MorphingMenu | 값 갱신 아래 | 트리거에서 펼쳐짐 |
+| 결과 문구 | `Text as="p" role="status"` | 맨 아래 | — |
+
+## 흐름과 상태
+
+1. "조회 수 새로고침"을 누르면 제품이 새 값을 요청한다. 응답이 오면 `value`가 바뀌고 AnimatedStatistic이 바뀐 자리만 굴려 보인다.
+2. "작업 선택"을 열면 메뉴가 트리거에서 형태를 바꿔 펼쳐진다. 항목을 고르면 `onAction(id)`가 오고 메뉴가 닫힌다. 제품은 결과를 상태로 바꿔 결과 문구 키를 고른다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 현재 값과 닫힌 메뉴, 안내 결과 문구(`post.actionHint`) | — |
+| 진행 중 | 새로고침 Button `loading`(다시 누를 수 없음), 지표는 직전 값 유지 | Button의 진행 표시 |
+| 실패 | 새로고침 요청 실패: 지표는 직전 값을 유지하고 결과 문구가 `stats.refreshFailed`. 버튼을 다시 누르면 재요청하고, 재요청도 실패하면 같은 문구를 다시 둔다. 메뉴 작업 실패도 같은 결과 문구 자리에 둔다 | `role="status"`로 알림 |
+| 값 변화 | 자리 단위 숫자 전환 | 최종 값만 읽힌다 |
+| 비활성 항목 | `disabled` 항목은 고를 수 없다 | — |
+| reduced motion·RTL | AnimatedStatistic은 정적 값, MorphingMenu는 `Menu`로 돌아간다 | 같다 |
+| 라틴 숫자가 아닌 numbering system, `ar`·`fa`·`he`·`ur` locale | AnimatedStatistic이 정적 값으로 그린다 | — |
+
+상태→문구 키는 상수 표로 둔다(아래 `resultKey`). 템플릿 문자열 키는 키 추출·누락 검사가 찾지 못한다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { Stack, Text } from "@hjmds/react/layout";
+import { AnimatedStatistic } from "@hjmds/react/statistic-motion";
+import { MorphingMenu } from "@hjmds/react/menu-morph";
+import { Button } from "@hjmds/react/actions";
+
+const resultKey = { idle: "post.actionHint", saved: "post.saved", shared: "post.shared", refreshFailed: "stats.refreshFailed" } as const;
+
+<Stack gap="md">
+  <AnimatedStatistic descriptor={{ id: "views", label: t("stats.views") }} value={views} locale={locale} />
+  <Button tone="secondary" loading={refreshing} onClick={refresh}>{t("stats.refresh")}</Button>
+  <MorphingMenu label={t("post.actions")} items={[
+    { id: "save", label: t("post.save") },
+    { id: "share", label: t("post.share") },
+  ]} onAction={(id) => setResult(id === "share" ? "shared" : "saved")} />
+  <Text as="p" role="status">{t(resultKey[result])}</Text>
+</Stack>
+```
+
+```tsx
+// Native
+// 없음. MorphingMenu는 Native가 없다. Native AnimatedStatistic(`@hjmds/react-native/statistic-motion`)은 지표 전체를 rise로 전환한다.
+```
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 스토리 | 있음 | 없음 |
+| AnimatedStatistic 모션 | 숫자 자리 단위 NumberFlow | 지표 전체 `rise` 전환 |
+| MorphingMenu | `/menu-morph` | 없음, `Menu`를 쓴다 |
+
+## 함정
+
+- AnimatedStatistic `descriptor`에 `value`를 넣지 않는다. 값은 `value` prop의 숫자로 받는다.
+- MorphingMenu는 실행 전용이다. 선택 상태나 비동기 목록이 필요하면 `Menu`를 쓴다.
+- optional peer를 설치하지 않으면 subpath import가 실패한다. 제품 package.json에 peer를 명시한다.
+- 예제는 `Stack gap="md"`, secondary 값 변경 버튼과 `Text role="status"`를 사용한다. 작업 ID는 사용자 문구로 변환한 뒤 표시한다.
+- 현재 스토리는 값을 로컬에서 바로 올려 진행 중·실패 상태가 없다. 서버 값을 새로고침하는 제품은 위 진행 중·실패 행을 따른다.

package/docs/usage/compositions/photo-source.md

@@ -0,0 +1,104 @@
+# 사진 촬영과 앨범 선택
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/구성/사진/촬영과 앨범 선택`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/선택과 필터/사진 촬영과 앨범 선택`
+
+## 언제 쓰나
+
+명시적으로 선택 후 플랫폼 picker 실행 흐름이 필요할 때 쓴다. PhotoSourceSheet의 상태·콜백을 제품 로직에 연결하며 새 데이터 엔진을 만들지 않는다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| PhotoSourceSheet | 명시적으로 선택 후 플랫폼 picker 실행 | [공개 계약](../components/photo-source-sheet.md) |
+| Button | 명시 행동·재시도 | [Button](../components/button.md) |
+
+## 배치
+
+```text
+부모 화면의 공개 슬롯
+└─ 제목 → 앨범 → 촬영
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | PhotoSourceSheet 또는 포함 Surface | 부모 화면의 해당 슬롯 | [배치](../components/photo-source-sheet.md#배치)에 따른다 |
+| 내용 | PhotoSourceSheet 내부 슬롯 | 제목 → 앨범 → 촬영 | spacing 토큰과 포함 컴포넌트 recipe |
+| 행동 | Button 또는 공개 콜백 | 내용과 가까운 명시 진입점 | 주 행동 하나, 보조 행동과 구분 |
+
+## 흐름과 상태
+
+1. 명시적으로 선택 후 플랫폼 picker 실행.
+2. 진행 상태와 제품의 실제 확정을 분리한다.
+3. 권한 거부·취소는 기존 선택 유지.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 제목 → 앨범 → 촬영 | 이름·선택 여부를 보조공학에 노출 |
+| 진행 중 | 해당 작업 pending, 입력·기존 결과 보존 | 중복 요청 차단, 로딩에 포커스를 옮기지 않음 |
+| 실패 | 권한 거부·취소는 기존 선택 유지 | 오류 근처 재시도, 필요할 때만 오류 읽기 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { PhotoSourceSheet } from "@hjmds/react/screen-flows";
+
+const libraryInput = useRef<HTMLInputElement>(null);
+const cameraInput = useRef<HTMLInputElement>(null);
+
+<>
+  <input ref={libraryInput} type="file" accept="image/*" multiple hidden onChange={(e) => addFiles(e.currentTarget.files)} />
+  <input ref={cameraInput} type="file" accept="image/*" capture="environment" hidden onChange={(e) => addFiles(e.currentTarget.files)} />
+  <PhotoSourceSheet
+    open={open}
+    onOpenChange={setOpen}
+    labels={{
+      title: t("photo.source.title"),
+      library: t("photo.source.library"),
+      camera: t("photo.source.camera"),
+      cancel: t("common.cancel"),
+    }}
+    cameraAvailable={hasCamera}
+    onSelect={(source) => (source === "camera" ? cameraInput : libraryInput).current?.click()}
+  />
+</>
+```
+
+```tsx
+// Native
+import { PhotoSourceSheet } from "@hjmds/react-native/screen-flows";
+
+<PhotoSourceSheet
+  open={open}
+  onOpenChange={setOpen}
+  labels={{
+    title: t("photo.source.title"),
+    library: t("photo.source.library"),
+    camera: t("photo.source.camera"),
+    cancel: t("common.cancel"),
+  }}
+  cameraAvailable={hasCamera}
+  onSelect={(source) => (source === "camera" ? takePhoto() : pickFromLibrary())}
+/>
+```
+
+제품 데이터·콜백은 주입한다. 위 공개 API 지침에 Web·Native 차이를 유지한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `onSelect` 호출 시점 | 버튼 클릭 안에서 동기 호출 — 파일 입력 `click()`이 사용자 활성화 안에 있어야 브라우저가 막지 않는다 | 시트 닫힘이 끝난 뒤(`onDismissComplete`) 호출 — iOS는 닫히는 Modal 위에 카메라·앨범을 띄우지 못한다 |
+| picker 실행 | 제품의 `<input type="file">`(촬영은 `capture`) | 제품의 이미지 picker·카메라 모듈 |
+
+## 함정
+
+- 권한 거부·취소는 기존 선택 유지.
+- 포인터·제스처만으로 기능을 숨기지 않는다. 키보드·단일 탭 경로와 취소 후 복귀도 검증한다.

package/docs/usage/compositions/purpose-input-comment.md

@@ -0,0 +1,110 @@
+# 댓글 작성
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [MessageComposer](../components/message-composer.md), [공통 실행과 실패 복구](../../action-session.md), `showcase/web/src/patterns/conversation-previews.tsx`, `showcase/native/src/conversation-previews.tsx`. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/구성/입력과 작성/댓글 작성`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/입력과 작성/댓글 작성`
+
+## 언제 쓰나
+
+게시물·기록 아래에서 댓글이나 특정 댓글에 대한 답글을 남기고, 실패하면 글과 답글 대상을 그대로 남겨 다시 등록하게 할 때 쓴다. 새 입력 엔진을 만들지 않고 MessageComposer를 쓴다.
+
+댓글 목록·답글 펼침·더 보기까지 포함한 화면은 [댓글 화면](../screens/common-comments.md)이 소유한다. 이 구성은 그 화면 하단 composer의 진행 중·실패·초안 유지만 따로 보인다.
+사진을 함께 보내는 대화는 [메시지 작성](purpose-input-message.md)을 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `MessageComposer` | 입력·전송. `pending`이면 전송 버튼이 스피너만 보이고 접근성 이름은 유지한다 | [MessageComposer](../components/message-composer.md) |
+| `replyTo` | 답글을 달 댓글 발췌와 취소 | [MessageComposer](../components/message-composer.md) |
+| `context` 슬롯 + `Text tone="danger"` | 실패 문구를 입력 바로 위에 둔다 | [Text](../components/text.md) |
+| `Heading level="level5"` | 구획 제목(선택). 화면 composer 슬롯에 넣을 때는 두지 않는다 | [Heading](../components/heading.md) |
+| `createActionSession` | 전송 진행·중복 차단·재시도 | [계약](../../action-session.md) |
+
+## 배치
+
+```text
+┌ 바깥 틀: Web 문서 스크롤 · Native ScrollView(위아래 spacing.md 16) ┐
+│ ← Container gutter 16(폭 600 미만)/20 →                             │
+│ ┌ Surface padding lg ────────────────────────────────┐              │
+│ │ 댓글 작성                       Heading level5     │              │
+│ │ ┌ MessageComposer ───────────────────────────────┐ │              │
+│ │ │ context: 실패 문구(실패일 때만)                │ │              │
+│ │ │ 답글 대상: 서연 · 발췌 ............ [답글 취소]│ │              │
+│ │ │ [ 댓글을 남겨 주세요 (1~5줄)          (↑) ]    │ │ ← circle 등록│
+│ │ └────────────────────────────────────────────────┘ │              │
+│ │ 등록한 댓글 목록(예제)                             │              │
+│ └────────────────────────────────────────────────────┘              │
+│ [답글 대상 선택] [다음 전송 실패시키기]  ← 데모 보조 행동             │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | 화면의 composer 슬롯(ChatScreen·CommentThreadScreen `composer`). 단독 예제는 Web 문서 스크롤 > `Container`, Native `ScrollView` > `Container` | 화면 하단(footer). 키보드 adapter는 화면 host 하나만 | 좌우 `Container gutter`: 폭 600 미만 `compact` 16, 이상 `regular` 20. Native 위아래 `spacing.md` 16 |
+| 제목(선택) | `Heading level5` | Surface 맨 위 | 아래 `spacing.md` 16 |
+| composer | `MessageComposer` | 제목 아래 | 입력 1~5줄(`composerMaxLines`), 세로 묶음 `screenPatternRecipe.itemGap` 12(두 플랫폼, 1.12.1 이하 Web은 8)([배치](../components/message-composer.md#배치)) |
+| 실패 문구 | `context` | composer 맨 위 | composer 세로 간격 |
+| 데모 보조 행동 | `Button` secondary·ghost | Surface 아래 가로 줄 | `spacing.sm` 12. 제품에는 넣지 않는다 |
+
+## 흐름과 상태
+
+1. 사용자가 글을 쓰고 필요하면 답글 대상을 고른 뒤 전송한다(Enter는 줄바꿈).
+2. 전송 중에는 `pending`으로 입력과 전송을 잠그고 같은 요청을 다시 보내지 않는다.
+3. 서버가 성공을 확정한 뒤에만 글·답글 대상을 지운다.
+4. 실패하면 모두 그대로 두고 `context`에 실패 문구를 보인다. 같은 전송 버튼으로 다시 보낸다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 빈 입력, 전송 비활성(글이 없을 때) | 입력 이름 `label` |
+| 진행 중 | `pending`: 입력 잠금, 전송 자리 스피너 | 포커스 유지, 중복 요청 차단 |
+| 실패 | 글·답글 대상 유지, `context`에 실패 문구 | 실패 문구는 입력 근처, 포커스 이동 없음 |
+| 성공 | 초안 정리, 보낸 항목이 목록에 추가 | 포커스는 입력에 남는다 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { MessageComposer } from "@hjmds/react/screens";
+import { Text } from "@hjmds/react/layout";
+
+<MessageComposer
+  label={t("comments.input")}
+  sendLabel={t("comments.send")}
+  value={draft}
+  onValueChange={setDraft}
+  pending={sending}
+  context={failed ? <Text tone="danger">{t("comments.sendFailed")}</Text> : null}
+  {...(replyTo ? { replyTo: { author: replyTo.author, excerpt: replyTo.text, cancelLabel: t("comments.cancelReply"), onCancel: () => setReplyTo(null) } } : {})}
+  onSend={async (text) => { const ok = await send(text); if (ok) clearDraft(); }}
+/>
+```
+
+```tsx
+// Native
+import { MessageComposer } from "@hjmds/react-native/screens";
+import { Text } from "@hjmds/react-native/primitives";
+
+<MessageComposer
+  label={t("comments.input")}
+  sendLabel={t("comments.send")}
+  value={draft}
+  onValueChange={setDraft}
+  pending={sending}
+  context={failed ? <Text tone="danger">{t("comments.sendFailed")}</Text> : null}
+  {...(replyTo ? { replyTo: { author: replyTo.author, excerpt: replyTo.text, cancelLabel: t("comments.cancelReply"), onCancel: () => setReplyTo(null) } } : {})}
+  onSend={async (text) => { const ok = await send(text); if (ok) clearDraft(); }}
+/>
+```
+
+`send`·`clearDraft`·`replyTo`는 제품 소유다. `onSend`는 문자열만 넘기므로 답글 대상은 제품 상태에서 읽는다.
+
+## 함정
+
+- 실패 시 글·답글 대상을 지우지 않는다. 성공을 먼저 표시하고 지우면 재전송할 내용이 사라진다.
+- Enter 전송을 덧붙이지 않는다. IME 조합 중 Enter를 전송으로 가로채면 한글 마지막 글자가 빠진다.
+- 스토리의 "다음 전송 실패시키기"·350ms 지연·예제 사진은 로컬 시연이다. 업로드·서버 저장·권한은 제품이 연결한다.

package/docs/usage/compositions/purpose-input-message.md

@@ -0,0 +1,119 @@
+# 메시지 작성
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [MessageComposer](../components/message-composer.md), [공통 실행과 실패 복구](../../action-session.md), `showcase/web/src/patterns/conversation-previews.tsx`, `showcase/native/src/conversation-previews.tsx`. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/구성/입력과 작성/메시지 작성`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/입력과 작성/메시지 작성`
+
+## 언제 쓰나
+
+대화 화면 하단에서 글과 사진 여러 장을 함께 보내고, 실패하면 글·사진·답장 대상을 그대로 남겨 다시 보내게 할 때 쓴다. 새 입력 엔진을 만들지 않고 MessageComposer를 쓴다.
+
+2026-10-06 `실험/구성/공통 화면/메시지 작성`(Web id `common-screen-composer`)이 같은 MessageComposer를 보이던 중복이라 이 구성으로 합쳤다.
+그 항목의 고유 변형이던 여러 사진 전송은 `여러 사진 전송` 스토리로 옮겼고, 효과가 없던 화면 상태 스토리(불러오는 중·빈·오류·로그인 필요)는 [채팅 화면](../screens/common-chat.md)이 소유한다.
+댓글처럼 사진 없이 답글 대상만 다루면 [댓글 작성](purpose-input-comment.md)을 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `MessageComposer` | 입력·전송. `pending`이면 전송 버튼이 스피너만 보이고 접근성 이름은 유지한다 | [MessageComposer](../components/message-composer.md) |
+| `attachmentAction`·`attachments`·`onRemoveAttachment` | 사진 추가(여러 장), 썸네일마다 제거 | [MessageComposer](../components/message-composer.md) |
+| `replyTo` | 답장할 메시지 발췌와 취소 | [MessageComposer](../components/message-composer.md) |
+| `context` 슬롯 + `Text tone="danger"` | 실패 문구를 입력 바로 위에 둔다 | [Text](../components/text.md) |
+| `Heading level="level5"` | 구획 제목(선택). 화면 composer 슬롯에 넣을 때는 두지 않는다 | [Heading](../components/heading.md) |
+| `createActionSession` | 전송 진행·중복 차단·재시도 | [계약](../../action-session.md) |
+
+## 배치
+
+```text
+┌ 바깥 틀: Web 문서 스크롤 · Native ScrollView(위아래 spacing.md 16) ┐
+│ ← Container gutter 16(폭 600 미만)/20 →                             │
+│ ┌ Surface padding lg ────────────────────────────────┐              │
+│ │ 메시지 작성                     Heading level5     │              │
+│ │ ┌ MessageComposer ───────────────────────────────┐ │              │
+│ │ │ context: 실패 문구(실패일 때만)                │ │              │
+│ │ │ 답장 대상: 서연 · 발췌 ............ [답장 취소]│ │              │
+│ │ │ [사진][사진] [+ 사진 추가]   ← 가로 스크롤     │ │              │
+│ │ │ [ 메시지 입력 (1~5줄)                 (↑) ]    │ │ ← circle 전송│
+│ │ └────────────────────────────────────────────────┘ │              │
+│ │ 보낸 메시지 목록(예제)                             │              │
+│ └────────────────────────────────────────────────────┘              │
+│ [답장할 메시지 선택] [다음 전송 실패시키기]  ← 데모 보조 행동         │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | 화면의 composer 슬롯(ChatScreen·CommentThreadScreen `composer`). 단독 예제는 Web 문서 스크롤 > `Container`, Native `ScrollView` > `Container` | 화면 하단(footer). 키보드 adapter는 화면 host 하나만 | 좌우 `Container gutter`: 폭 600 미만 `compact` 16, 이상 `regular` 20. Native 위아래 `spacing.md` 16 |
+| 제목(선택) | `Heading level5` | Surface 맨 위 | 아래 `spacing.md` 16 |
+| composer | `MessageComposer` | 제목 아래 | 입력 1~5줄(`composerMaxLines`), 세로 묶음 `screenPatternRecipe.itemGap` 12(두 플랫폼, 1.12.1 이하 Web은 8)([배치](../components/message-composer.md#배치)) |
+| 실패 문구 | `context` | composer 맨 위 | composer 세로 간격 |
+| 데모 보조 행동 | `Button` secondary·ghost | Surface 아래 가로 줄 | `spacing.sm` 12. 제품에는 넣지 않는다 |
+
+## 흐름과 상태
+
+1. 사용자가 글을 쓰고 사진을 여러 장 고른 뒤 전송한다(Enter는 줄바꿈).
+2. 전송 중에는 `pending`으로 입력과 전송을 잠그고 같은 요청을 다시 보내지 않는다.
+3. 서버가 성공을 확정한 뒤에만 글·사진·답장 대상을 지운다.
+4. 실패하면 모두 그대로 두고 `context`에 실패 문구를 보인다. 같은 전송 버튼으로 다시 보낸다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 빈 입력, 전송 비활성(글·사진이 없을 때) | 입력 이름 `label` |
+| 진행 중 | `pending`: 입력 잠금, 전송 자리 스피너 | 포커스 유지, 중복 요청 차단 |
+| 실패 | 글·사진·답장 대상 유지, `context`에 실패 문구 | 실패 문구는 입력 근처, 포커스 이동 없음 |
+| 성공 | 초안 정리, 보낸 항목이 목록에 추가 | 포커스는 입력에 남는다 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { MessageComposer } from "@hjmds/react/screens";
+import { Text } from "@hjmds/react/layout";
+
+<MessageComposer
+  label={t("chat.input")}
+  sendLabel={t("chat.send")}
+  value={draft}
+  onValueChange={setDraft}
+  pending={sending}
+  context={failed ? <Text tone="danger">{t("chat.sendFailed")}</Text> : null}
+  {...(replyTo ? { replyTo: { author: replyTo.author, excerpt: replyTo.text, cancelLabel: t("chat.cancelReply"), onCancel: () => setReplyTo(null) } } : {})}
+  attachmentAction={{ label: t("chat.addPhoto"), icon: <PlusIcon />, onPress: pickPhotos }}
+  attachments={photos.map((photo) => ({ id: photo.id, removeLabel: t("chat.removePhoto"), preview: <img src={photo.uri} alt="" /> }))}
+  onRemoveAttachment={(id) => setPhotos((list) => list.filter((photo) => photo.id !== id))}
+  onSend={async (text) => { const ok = await send(text); if (ok) clearDraft(); }}
+/>
+```
+
+```tsx
+// Native
+import { MessageComposer } from "@hjmds/react-native/screens";
+import { Text } from "@hjmds/react-native/primitives";
+
+<MessageComposer
+  label={t("chat.input")}
+  sendLabel={t("chat.send")}
+  value={draft}
+  onValueChange={setDraft}
+  pending={sending}
+  context={failed ? <Text tone="danger">{t("chat.sendFailed")}</Text> : null}
+  {...(replyTo ? { replyTo: { author: replyTo.author, excerpt: replyTo.text, cancelLabel: t("chat.cancelReply"), onCancel: () => setReplyTo(null) } } : {})}
+  attachmentAction={{ label: t("chat.addPhoto"), icon: <PlusIcon />, onPress: pickPhotos }}
+  attachments={photos.map((photo) => ({ id: photo.id, removeLabel: t("chat.removePhoto"), preview: <Image source={{ uri: photo.uri }} style={thumb} /> }))}
+  onRemoveAttachment={(id) => setPhotos((list) => list.filter((photo) => photo.id !== id))}
+  onSend={async (text) => { const ok = await send(text); if (ok) clearDraft(); }}
+/>
+```
+
+`send`·`clearDraft`·`pickPhotos`·`photos`·`replyTo`는 제품 소유다. `onSend`는 문자열만 넘기므로 사진 목록은 제품 상태에서 읽는다.
+
+## 함정
+
+- 실패 시 글·사진·답장 대상을 지우지 않는다. 성공을 먼저 표시하고 지우면 재전송할 내용이 사라진다.
+- Enter 전송을 덧붙이지 않는다. IME 조합 중 Enter를 전송으로 가로채면 한글 마지막 글자가 빠진다.
+- 스토리의 "다음 전송 실패시키기"·350ms 지연·예제 사진은 로컬 시연이다. 업로드·서버 저장·권한은 제품이 연결한다.

package/docs/usage/compositions/reference-first.md

@@ -0,0 +1,96 @@
+# 첫 작업을 만들고 이어하기
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/구성/시작하기/첫 작업을 만들고 이어하기`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/입력과 작성/첫 작업을 만들고 이어하기`
+
+## 언제 쓰나
+
+첫 기록을 단계별 작성하고 중단한 초안 이어가기 흐름이 필요할 때 쓴다. Steps의 상태·콜백을 제품 로직에 연결하며 새 데이터 엔진을 만들지 않는다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| Steps | 첫 기록을 단계별 작성하고 중단한 초안 이어가기 | [공개 계약](../components/steps.md) |
+| Button | 명시 행동·재시도 | [Button](../components/button.md) |
+
+## 배치
+
+```text
+부모 화면의 공개 슬롯
+└─ 주제 → 입력 → 검토 → 결과
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Steps 또는 포함 Surface | 부모 화면의 해당 슬롯 | [배치](../components/steps.md#배치)에 따른다 |
+| 내용 | Steps 내부 슬롯 | 주제 → 입력 → 검토 → 결과 | spacing 토큰과 포함 컴포넌트 recipe |
+| 행동 | Button 또는 공개 콜백 | 내용과 가까운 명시 진입점 | 주 행동 하나, 보조 행동과 구분 |
+
+## 흐름과 상태
+
+1. 첫 기록을 단계별 작성하고 중단한 초안 이어가기.
+2. 진행 상태와 제품의 실제 확정을 분리한다.
+3. 저장 실패는 입력·단계 유지; 메모리 초안은 새로고침 복구를 보장하지 않음.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 주제 → 입력 → 검토 → 결과 | 이름·선택 여부를 보조공학에 노출 |
+| 진행 중 | 해당 작업 pending, 입력·기존 결과 보존 | 중복 요청 차단, 로딩에 포커스를 옮기지 않음 |
+| 실패 | 저장 실패는 입력·단계 유지; 메모리 초안은 새로고침 복구를 보장하지 않음 | 오류 근처 재시도, 필요할 때만 오류 읽기 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { Steps } from "@hjmds/react/steps";
+
+<Steps
+  descriptor={{
+    currentStepId: "team",
+    steps: [
+      { id: "welcome", label: t("onboarding.welcome") },
+      { id: "team", label: t("onboarding.team") },
+      { id: "alerts", label: t("onboarding.alerts") },
+    ],
+  }}
+  statusLabels={{
+    pending: t("steps.pending"), current: t("steps.current"),
+    complete: t("steps.complete"), error: t("steps.error"),
+  }}
+  composeAccessibleName={({ position, total, label }) => t("steps.name", { position, total, label })}
+/>
+```
+
+```tsx
+// Native
+import { Steps } from "@hjmds/react-native/steps";
+
+<Steps
+  descriptor={{
+    currentStepId: "team",
+    steps: [
+      { id: "welcome", label: t("onboarding.welcome") },
+      { id: "team", label: t("onboarding.team") },
+      { id: "alerts", label: t("onboarding.alerts") },
+    ],
+  }}
+  statusLabels={{
+    pending: t("steps.pending"), current: t("steps.current"),
+    complete: t("steps.complete"), error: t("steps.error"),
+  }}
+  composeAccessibleName={({ position, total, label }) => t("steps.name", { position, total, label })}
+/>
+```
+
+제품 데이터·콜백은 주입한다. 위 공개 API 지침에 Web·Native 차이를 유지한다.
+
+## 함정
+
+- 저장 실패는 입력·단계 유지; 메모리 초안은 새로고침 복구를 보장하지 않음.
+- 포인터·제스처만으로 기능을 숨기지 않는다. 키보드·단일 탭 경로와 취소 후 복귀도 검증한다.

package/docs/usage/compositions/reference-review.md

@@ -0,0 +1,107 @@
+# 선택 내용 검토와 수정
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/구성/확인/선택 내용 검토와 수정`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/입력과 작성/선택 내용 검토와 수정`
+
+## 언제 쓰나
+
+선택 내용을 검토하고 수정 후 명시적으로 확정 흐름이 필요할 때 쓴다. Form의 상태·콜백을 제품 로직에 연결하며 새 데이터 엔진을 만들지 않는다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| Form | 선택 내용을 검토하고 수정 후 명시적으로 확정 | [공개 계약](../components/form.md) |
+| Button | 명시 행동·재시도 | [Button](../components/button.md) |
+
+## 배치
+
+```text
+부모 화면의 공개 슬롯
+└─ 입력 → 요약 → 수정·저장
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Form 또는 포함 Surface | 부모 화면의 해당 슬롯 | [배치](../components/form.md#배치)에 따른다 |
+| 내용 | Form 내부 슬롯 | 입력 → 요약 → 수정·저장 | spacing 토큰과 포함 컴포넌트 recipe |
+| 행동 | Button 또는 공개 콜백 | 내용과 가까운 명시 진입점 | 주 행동 하나, 보조 행동과 구분 |
+
+## 흐름과 상태
+
+1. 선택 내용을 검토하고 수정 후 명시적으로 확정.
+2. 진행 상태와 제품의 실제 확정을 분리한다.
+3. 실패한 저장은 요약·입력 유지; 확인 전 자동 저장 금지.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 입력 → 요약 → 수정·저장 | 이름·선택 여부를 보조공학에 노출 |
+| 진행 중 | 해당 작업 pending, 입력·기존 결과 보존 | 중복 요청 차단, 로딩에 포커스를 옮기지 않음 |
+| 실패 | 실패한 저장은 요약·입력 유지; 확인 전 자동 저장 금지 | 오류 근처 재시도, 필요할 때만 오류 읽기 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { useRef } from "react";
+import { Form, TextField } from "@hjmds/react/forms";
+import { Button } from "@hjmds/react/actions";
+
+const nicknameInputRef = useRef<HTMLInputElement>(null);
+
+<Form
+  aria-label={t("profile.formLabel")}
+  onSubmit={async () => {
+    setServerError(null);
+    if (nicknameError) { nicknameInputRef.current?.focus(); return; } // Web은 첫 오류 포커스를 제품이 한다
+    try { await save(values); } catch { setServerError(t("profile.saveFailed")); }
+  }}
+  formError={serverError}
+  actions={<Button type="submit">{t("profile.save")}</Button>}
+>
+  <TextField ref={nicknameInputRef} label={t("profile.nickname")} value={values.nickname}
+    onValueChange={setNickname} error={nicknameError ? t(nicknameError) : undefined} />
+</Form>
+```
+
+```tsx
+// Native
+import { useRef } from "react";
+import type { TextInput } from "react-native";
+import { Form } from "@hjmds/react-native/forms";
+import { TextField } from "@hjmds/react-native/inputs";
+
+const nicknameInputRef = useRef<TextInput>(null);
+
+<Form
+  label={t("profile.formLabel")}
+  values={values}
+  onSubmit={save} // 거절되면 Form이 오류를 표시한다(메시지가 없으면 fallbackErrorMessage)
+  submitLabel={t("profile.save")}
+  fallbackErrorMessage={t("profile.saveFailed")}
+  {...(nicknameError ? { firstInvalidFieldRef: nicknameInputRef } : {})} // Native는 Form이 첫 오류로 포커스를 옮긴다
+>
+  <TextField ref={nicknameInputRef} label={t("profile.nickname")} value={values.nickname}
+    onValueChange={setNickname} {...(nicknameError ? { error: t(nicknameError) } : {})} />
+</Form>
+```
+
+제품 데이터·콜백은 주입한다. 위 공개 API 지침에 Web·Native 차이를 유지한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 첫 오류 포커스 | 제품이 `onSubmit`에서 해당 입력 `ref.focus()` | `firstInvalidFieldRef`를 주면 Form이 그 입력에 포커스·보조공학 포커스를 옮기고 제출을 멈춘다 |
+| 저장 실패 표시 | 제품이 `formError`로 넘긴다 | `onSubmit`이 거절되면 Form이 오류 메시지(없으면 `fallbackErrorMessage`)를 표시한다 |
+| 제출 버튼 | `actions`에 `type="submit"` Button | `submitLabel`로 내장 버튼, `actions`로 교체 가능 |
+
+## 함정
+
+- 실패한 저장은 요약·입력 유지; 확인 전 자동 저장 금지.
+- 포인터·제스처만으로 기능을 숨기지 않는다. 키보드·단일 탭 경로와 취소 후 복귀도 검증한다.