@hjmds/design-contracts 1.12.1 → 1.13.1

package/docs/usage/compositions/action-recovery-undo.md

@@ -0,0 +1,193 @@
+# 보관과 실행 취소
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [공통 실행과 실패 복구 · 초안과 실행 취소](../../action-session.md#초안과-실행-취소), `src/action-session.ts`, `showcase/web/src/patterns/action-recovery-previews.tsx`, `showcase/native/src/action-recovery-previews.tsx`. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/구성/공통 동작/보관과 실행 취소`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/피드백과 복구/보관과 실행 취소`
+
+## 언제 쓰나
+
+보관·숨기기·목록에서 빼기처럼 제품이 역연산을 제공하는 작업 뒤에, 같은 자리에서 실행 취소를 주고 그 복구 요청이 성공해야 화면을 되돌릴 때 쓴다.
+
+금융 거래·영구 삭제에는 가짜 Undo를 넣지 않는다.
+
+같은 `공통 동작` 묶음: [저장과 재시도](action-recovery-save.md) · [즉시 반영과 복구](action-recovery-optimistic.md).
+세션 생성·구독·상태 알림은 [저장과 재시도의 공통 절](action-recovery-save.md#공통-세션과-상태-알림)을 따른다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `createActionSession` | 보관·복구 요청의 진행·실패 상태. 값은 "보관됨" 여부 | [계약](../../action-session.md) |
+| `Heading` | 묶음 제목(선택). 크기 `level3`(24), 문서 단계는 화면 구조에 맞춰 `semanticLevel` | [Heading](../components/heading.md) |
+| `Text` | 대상의 현재 위치(목록·보관함) | [Text](../components/text.md) |
+| `Button` 보관/실행 취소 | 같은 자리의 한 버튼, 라벨이 바뀜. pending 중 `loading` | [Button](../components/button.md) |
+| `Button` 다시 시도 | error일 때만 나타나는 보조 행동, `tone="secondary"` | [Button](../components/button.md) |
+| `Text` | 상태 문구. Web `role="status"`, Native 접근성 알림 | [Text](../components/text.md) |
+| `Stack` | 세로 쌓기 `gap="md"` | [Stack](../components/stack.md) |
+| `Toast` `action`(선택) | 행이 사라지는 목록에서 실행 취소 진입점 | [Toast](../components/toast.md) |
+| `Container` · `ScrollView` | 바깥 틀. 제품 화면이 소유한다 | [Container](../components/container.md), [화면 여백](../tokens/layout.md) |
+
+Toast의 `action`을 진입점으로 쓰면 토스트는 진입점만, 세션은 진행·실패 상태만 소유한다. Toast 지침대로 그 알림에서만 할 수 있는
+행동은 두지 않으므로 보관함 화면 등 다른 곳에도 복구 경로를 둔다. 스토리의 "다음 요청 실패시키기"·350ms 지연은 데모 전용이고,
+스토리에는 자동 만료가 없다(만료 시간은 제품이 정한다).
+
+## 배치
+
+```text
+┌ 화면 바깥 틀(제품 소유) ─────────────────┐
+│ Web: 문서 스크롤 · Native: ScrollView    │
+│ ↕ Native 위아래 spacing.lg 20            │
+│ ←gutter 16|20→ Container ←gutter 16|20→ │
+│ ┌ Stack gap="md" ──────────────────────┐ │
+│ │ 제목 Heading level3 (선택)           │ │
+│ │          ↕ spacing.md 16             │ │
+│ │ 대상: 목록 / 보관함 + 항목 이름      │ │
+│ │          ↕ spacing.md 16             │ │
+│ │ [ 보관 ]  →  [ 실행 취소 ]           │ │ ← 같은 자리, loading 중 스피너
+│ │          ↕ spacing.md 16             │ │
+│ │ [ 실패한 작업 다시 시도 (secondary)] │ │ ← error일 때만
+│ │          ↕ spacing.md 16             │ │
+│ │ 상태 문구 (role=status)              │ │
+│ └──────────────────────────────────────┘ │
+└──────────────────────────────────────────┘
+  토스트(선택): 화면 단위 오버레이, action = 실행 취소
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web 문서 스크롤 > `Container`. Native `ScrollView` > `Container` | 이 구성을 감싸는 제품 화면. 상단 안전 영역은 내비게이션 헤더(또는 [TopBar](../components/top-bar.md))가 맡는다 | 좌우 `Container gutter`: 폭 600 미만 `compact` 16, 이상 `regular` 20([화면 여백](../tokens/layout.md)). Native 위아래는 `contentContainerStyle` `paddingVertical: spacing.lg` 20 |
+| 제목(선택) | `Heading level="level3"` | Stack 맨 위 | 아래 `spacing.md` 16 |
+| 대상 표시 | `Text` | 행동 위, 스크롤 | 아래 `spacing.md` 16 |
+| 행동 | `Button` 보관/실행 취소(primary) | 대상 아래, 스크롤 | `medium` 44(`control.buttonHeight`). Stack 기본 `align="stretch"`로 꽉 찬 폭 |
+| 재시도 | `Button tone="secondary"` | 행동 아래, error일 때만 | `medium` 44, `spacing.md` 16. 라벨은 무엇을 다시 하는지 적는다(스토리 "실패한 작업 다시 시도") |
+| 상태 | `Text` | 맨 아래 | `spacing.md` 16 |
+| 토스트(선택) | `Toast` `action` | 화면 단위 오버레이 | action 높이 `control.minTouchTarget` 44 |
+
+- 보관과 실행 취소를 같은 자리의 한 버튼으로 둬서 방금 누른 위치에서 바로 되돌리게 한다.
+- 목록 행에서 보관을 시작하면 행 끝 `size="small"` 버튼이나 [SwipeActions](../components/swipe-actions.md)를 쓰고,
+  실행 취소는 화면 단위 Toast `action`으로 옮긴다(행이 사라지므로 행 안에 둘 수 없다).
+- 한 화면의 primary는 하나다([Button](../components/button.md)). 재시도는 `secondary`로 둔다.
+
+근거: `src/foundations.ts`(`spacing`, `control`, `layout`), [Toast 지침](../components/toast.md)
+
+## 흐름과 상태
+
+1. 대상이 목록에 있을 때 버튼은 `t("archive.action")`이다.
+2. 보관을 누르면 `session.run(() => api.archive(id), { retryable: true })`를 부르고 버튼은 `loading`이다. pending 동안 같은 세션의 새 run·retry는 `blocked`다.
+3. 성공하면 대상 표시가 보관함으로, 버튼이 `t("archive.undo")`로 바뀐다.
+4. 실행 취소를 누르면 같은 버튼으로 `session.run(() => api.unarchive(id), { retryable: true })`를 부른다. 성공해야 목록으로 돌아온다.
+5. 어느 쪽이든 실패(네트워크·서버 오류, 역연산 거부)하면 `state.value`는 마지막으로 확인한 상태를 유지하고 재시도 버튼을 보인다.
+   재시도도 실패하면 다시 error가 되고 재시도 버튼이 남는다. error 중 같은 자리 버튼을 누르면 새 run이 되고 이전 실패 작업은 버려진다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | idle(목록). 대상 "목록", 버튼 보관, 상태 문구 `t("archive.listed")` | 알림 없음(첫 렌더는 알리지 않는다) |
+| 진행 중 | pending. 버튼 `loading`(라벨 자리 유지, 중앙 스피너 하나), `t("archive.pending")` | 포커스는 버튼에 유지, 상태 문구 알림 |
+| 보관됨 | success, `state.value === true`. 대상 "보관함", 버튼 실행 취소, `t("archive.done")`(되돌릴 수 있음을 함께) | 상태 문구 알림 |
+| 복구됨 | success, `state.value === false`. 대상 "목록", 버튼 보관, `t("archive.listed")` | 상태 문구 알림 |
+| 실패 | error. 마지막 확인 상태 유지, 재시도 버튼, `t("archive.failed")` | 상태 문구 알림, 포커스 이동 없음 |
+| 재시도 실패 | error 유지. 재시도 → pending → error로 문구가 바뀌므로 다시 알린다 | 상태 문구 알림, 포커스 이동 없음 |
+
+- 상태 문구는 status와 값을 함께 본다. 키는 상수 표(`archiveStatusKey`)에서 고른다. 템플릿 문자열 키(`` `archive.${status}` ``)는
+  키 추출·누락 검사가 찾지 못하고 위 표의 키와 어긋난다.
+- 권한·만료·대상 버전·복구 데이터 검증은 제품이 한다. UI를 되돌렸다는 이유로 서버 취소 완료를 선언하지 않는다.
+- 오류 문구는 제품이 지역화한다. raw exception(`state.error`)을 그대로 보이지 않는다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { useState, useSyncExternalStore } from "react";
+import { createActionSession, type ActionSnapshot } from "@hjmds/design-contracts/action-session";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+import { Button } from "@hjmds/react/actions";
+import { Container, Stack, Text } from "@hjmds/react/layout";
+
+const archiveStatusKey = { pending: "archive.pending", error: "archive.failed", archived: "archive.done", listed: "archive.listed" } as const;
+const statusKeyOf = (state: ActionSnapshot<boolean>) =>
+  state.status === "pending" || state.status === "error" ? archiveStatusKey[state.status] : state.value ? archiveStatusKey.archived : archiveStatusKey.listed;
+
+type ArchiveApi = { archive(id: string): Promise<boolean>; unarchive(id: string): Promise<boolean> };
+
+function ArchiveItem({ id, name, api }: { id: string; name: string; api: ArchiveApi }) {
+  const [session] = useState(() => createActionSession(false)); // false = 목록에 있음
+  const state = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+  const toggle = () => {
+    const next = !state.value;
+    void session.run(() => (next ? api.archive(id) : api.unarchive(id)), { retryable: true });
+  };
+  const gutter = resolveWindowClass(window.innerWidth) === "compact" ? "compact" : "regular";
+  return (
+    <Container gutter={gutter}>
+      <Stack gap="md">
+        <Text as="p">{state.value ? t("archive.inArchive", { name }) : t("archive.inList", { name })}</Text>
+        <Button loading={state.status === "pending"} onClick={toggle}>
+          {state.value ? t("archive.undo") : t("archive.action")}
+        </Button>
+        {state.status === "error" && <Button tone="secondary" onClick={() => void session.retry()}>{t("archive.retry")}</Button>}
+        <Text as="p" role="status">{t(statusKeyOf(state))}</Text>
+      </Stack>
+    </Container>
+  );
+}
+```
+
+```tsx
+// Native
+import { useState, useSyncExternalStore } from "react";
+import { ScrollView, useWindowDimensions } from "react-native";
+import { createActionSession, type ActionSnapshot } from "@hjmds/design-contracts/action-session";
+import { spacing } from "@hjmds/design-contracts/foundations";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+import { Button } from "@hjmds/react-native/actions";
+import { Container, Stack, Text } from "@hjmds/react-native/primitives";
+
+const archiveStatusKey = { pending: "archive.pending", error: "archive.failed", archived: "archive.done", listed: "archive.listed" } as const;
+const statusKeyOf = (state: ActionSnapshot<boolean>) =>
+  state.status === "pending" || state.status === "error" ? archiveStatusKey[state.status] : state.value ? archiveStatusKey.archived : archiveStatusKey.listed;
+
+type ArchiveApi = { archive(id: string): Promise<boolean>; unarchive(id: string): Promise<boolean> };
+
+function ArchiveItem({ id, name, api }: { id: string; name: string; api: ArchiveApi }) {
+  const [session] = useState(() => createActionSession(false));
+  const state = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+  const { width } = useWindowDimensions();
+  const toggle = () => {
+    const next = !state.value;
+    void session.run(() => (next ? api.archive(id) : api.unarchive(id)), { retryable: true });
+  };
+  return (
+    <ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
+      <Container gutter={resolveWindowClass(width) === "compact" ? "compact" : "regular"}>
+        <Stack gap="md">
+          <Text>{state.value ? t("archive.inArchive", { name }) : t("archive.inList", { name })}</Text>
+          <Button loading={state.status === "pending"} onPress={toggle}>
+            {state.value ? t("archive.undo") : t("archive.action")}
+          </Button>
+          {state.status === "error" && <Button tone="secondary" onPress={() => void session.retry()}>{t("archive.retry")}</Button>}
+          <StatusText>{t(statusKeyOf(state))}</StatusText>
+        </Stack>
+      </Container>
+    </ScrollView>
+  );
+}
+```
+
+`api.archive`·`api.unarchive`(서버가 확정한 boolean을 돌려줌)와 `StatusText`는 제품 소유다([공통 절](action-recovery-save.md#공통-세션과-상태-알림)의 helper).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 이벤트 | `onClick` | `onPress` |
+| 바깥 스크롤 | 문서 스크롤 | `ScrollView`(위아래 `spacing.lg`) |
+| 상태 알림 | `role="status"` | live region(Android) + iOS 알림 호출 |
+
+## 함정
+
+- 구획 제목은 Heading으로 표시한다. 이전 Text heading 예제는 2026-10-06 제목 의미 구조를 맞추면서 수정했다.
+- 재시도는 secondary로 두어 저장과 경쟁하는 primary를 만들지 않는다(2026-10-06 예제 반영).

package/docs/usage/compositions/common-message.md

@@ -0,0 +1,132 @@
+# 대화 메시지
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [ChatMessage](../components/chat-message.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-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/정보 표시/대화 메시지`
+
+## 언제 쓰나
+
+말풍선 하나하나에 반응·답장·원문 이동·전송 실패 후 다시 보내기를 붙일 때 쓴다. ChatMessage의 슬롯과 콜백을 제품 로직에 연결하며 새 데이터 엔진을 만들지 않는다.
+
+2026-10-06 정리 전에는 이 스토리가 [채팅 화면](../screens/common-chat.md)과 같은 화면 전체를 그렸다. 지금은 말풍선 단위 상호작용만 보이고,
+대화 목록·하단 입력·불러오는 중·빈·오류·로그인 필요 상태는 채팅 화면이 소유한다. 입력은 [메시지 작성](purpose-input-message.md)을 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `ChatMessage` | 수신·발신 말풍선, 작성자·시각·전송 상태 | [ChatMessage](../components/chat-message.md) |
+| `reactions` | 길게 누르기·우클릭·메뉴로 여는 반응 선택 | [ChatMessage](../components/chat-message.md) |
+| `reply` + `replyLink` | 답장 인용과 원문 이동 | [ChatMessage](../components/chat-message.md) |
+| `actions` + `Button size="small"` secondary | 전송 실패 메시지의 "다시 보내기", 고른 반응 표시 | [Button](../components/button.md) |
+| `Avatar` | 수신 메시지 작성자 | [Avatar](../components/avatar.md) |
+| `createActionSession` | 다시 보내기 진행·실패 | [계약](../../action-session.md) |
+
+## 배치
+
+```text
+┌ 바깥 틀: 채팅 화면 본문(타임라인 스크롤). 단독 예제는 Container ┐
+│ (아바타) 서연                                                    │
+│ ┌ 수신 말풍선 ───────────┐   ← 시작 쪽, 최대 폭 84%              │
+│ └────────────────────────┘                                       │
+│ 오후 2:30  ❤️              ← 시각 · actions(고른 반응)            │
+│                     [서연 · 원문 발췌]   ← replyLink(ghost)       │
+│                ┌ 발신 말풍선 ───────────┐   ← 끝 쪽               │
+│                └────────────────────────┘                        │
+│                              오후 2:32 · 읽음                    │
+│                ┌ 발신 말풍선 ───────────┐                        │
+│                └────────────────────────┘                        │
+│              오후 2:33 · 전송 실패 [다시 보내기]  ← actions       │
+│ 상태 문구(Web role=status, Native live region)                    │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | [ChatScreen](../components/chat-screen.md) 본문 타임라인. 단독 예제는 Web `Container`, Native `ScrollView` > `Container` | 화면 본문 스크롤 | 좌우 `Container gutter` compact 16 / regular 20, 메시지 사이 `spacing.lg` 20 |
+| 말풍선 | `ChatMessage` | incoming 시작 쪽, outgoing 끝 쪽 | 최대 폭 `messageMaxWidth` 84%, 버블 padding `spacing.sm` 12([배치](../components/chat-message.md#배치)) |
+| 반응 | `reactions` | 말풍선 위 Popover(Web)·Modal 메뉴(Native) | 길게 누르기 450ms(`reactionHoldMs`) |
+| 다시 보내기 | `actions` 슬롯의 `Button size="small"` secondary | 실패한 발신 메시지의 시각 옆 | 높이 36(`control.buttonHitSlop.small` 4로 터치 44), 시각과 `spacing.xs` 8 |
+| 상태 | `Text` 상태 문구 | 목록 아래(단독 예제). 화면에서는 Toast 등 화면 단위로 한 번 알린다 | `spacing.lg` 20 |
+
+## 흐름과 상태
+
+1. 말풍선을 길게 누르거나(Web은 우클릭·Enter도) 메뉴를 열어 반응을 고른다. 같은 반응을 다시 고르면 `null`로 해제된다.
+2. 가로 스와이프(60px 이상)나 접근성 동작으로 답장을 시작하면 제품이 composer의 답장 대상을 채운다.
+3. 답장 인용(`replyLink`)을 누르면 제품이 원문 메시지로 스크롤하고 잠시 강조한다.
+4. 전송에 실패한 발신 메시지는 `deliveryLabel`로 실패를 적고 `actions`에 "다시 보내기"를 둔다. 누르면 진행 중 → 전송됨 또는 다시 실패.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 작성자 → 말풍선 → 시각·전송 상태. 반응은 길게 누르기·메뉴로 연 말풍선 위 메뉴에서 고른다 | 말풍선 이름(Web `author`·Native 본문), 반응 이름은 `reactions.label` |
+| 진행 중 | 다시 보내기 `loading`, `deliveryLabel` "보내는 중" | 포커스는 버튼에 유지 |
+| 실패 | `deliveryLabel` "전송 실패" + 다시 보내기 유지, 메시지 본문 유지 | 상태 문구로 알림, 포커스 이동 없음 |
+| 성공 | `deliveryLabel` "전송됨", 다시 보내기 사라짐 | 상태 문구 |
+
+- 전송 상태·반응 문구는 id→문구 키 상수 표로 둔다. 원문 이동·답장 준비·실패 알림은 제품 알림 계층(Toast 등)으로 화면 단위로 한 번 알린다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { Avatar } from "@hjmds/react/display";
+import { ChatMessage } from "@hjmds/react/screens";
+
+<ChatMessage
+  direction={mine ? "outgoing" : "incoming"}
+  author={message.authorName}
+  timestamp={formatTime(message.sentAt)}
+  {...(mine ? { deliveryLabel: t("chat.delivered") } : {})}
+  avatar={mine ? undefined : <Avatar name={message.authorName} />}
+  replyAction={{ label: t("chat.reply"), onPress: () => setReplyTo(message.id) }}
+  reactions={{
+    label: t("chat.react"), closeLabel: t("common.close"),
+    options: reactionOptions, value: message.myReaction, onValueChange: v => react(message.id, v),
+  }}
+>
+  {message.text}
+</ChatMessage>
+```
+
+```tsx
+// Native
+import { Avatar } from "@hjmds/react-native/data-display";
+import { ChatMessage } from "@hjmds/react-native/screens";
+
+<ChatMessage
+  direction={mine ? "outgoing" : "incoming"}
+  author={message.authorName}
+  timestamp={formatTime(message.sentAt)}
+  {...(mine ? { deliveryLabel: t("chat.delivered") } : {})}
+  avatar={mine ? undefined : <Avatar name={message.authorName} decorative />}
+  replyAction={{ label: t("chat.reply"), onPress: () => setReplyTo(message.id) }}
+  reactions={{
+    label: t("chat.react"), closeLabel: t("common.close"),
+    options: reactionOptions, value: message.myReaction, onValueChange: v => react(message.id, v),
+  }}
+>
+  {message.text}
+</ChatMessage>
+```
+
+제품 데이터·콜백은 주입한다. 위 공개 API 지침에 Web·Native 차이를 유지한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 반응 메뉴 여는 법 | 말풍선 길게 누르기 450ms(`reactionHoldMs`, 10px 넘게 움직이면 취소), 우클릭(`contextmenu`), 말풍선 자체에 포커스 후 Enter·Space(`interactiveContent` 안 버튼·링크의 Enter·Space는 그 컨트롤이 받는다) | 말풍선 길게 누르기 450ms(`delayLongPress`), 접근성 동작 `activate`. `interactiveContent`이면 말풍선 옆 `···` IconButton이 메뉴를 연다 |
+| 반응 메뉴 표면 | `Popover`(`placement: "top"`, `align: "start"`) — 충돌 회피·포커스·Escape·바깥 닫기는 Popover 소유. 시각적으로 숨긴 닫기 버튼은 포커스를 받으면 보인다 | 투명 `Modal`, 누른 위치 위쪽에 띄우고 안전 영역 안으로 맞춘다. 너비 최대 320(`reactionMenuWidth`). 닫기 대상은 표준 `activate` 동작에 답해 TalkBack에서도 닫힌다 |
+| 메시지 낭독 | 행 이름 `author`, 반응이 있으면 말풍선 이름 `reactions.label` | 말풍선이 본문 텍스트로 읽히고 `reactions.label`은 힌트, 작성자·시각은 별도 요소. 답장·반응은 접근성 동작 |
+| Avatar 이름 | `name`만으로 이름을 읽는다 | 작성자 caption이 이미 이름을 읽으므로 `decorative`. 아니면 `accessibilityLabel` 필수 |
+
+## 함정
+
+- 전송 실패를 말풍선 색만으로 알리지 않는다. `deliveryLabel` 글자와 다시 보내기를 함께 둔다.
+- 답장은 스와이프만으로 숨기지 않는다. Native 접근성 동작과 Web 키보드·메뉴 경로가 같은 `replyAction`을 부른다.
+- 화면 상태(불러오는 중·빈·오류·로그인 필요)를 말풍선 예제에 다시 만들지 않는다. [채팅 화면](../screens/common-chat.md)의 `state`가 소유한다.
+- 스토리의 "다음 전송 실패시키기"·350ms 지연은 데모 전용이다.

package/docs/usage/compositions/common-notification.md

@@ -0,0 +1,101 @@
+# 알림 항목
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [NotificationItem](../components/notification-item.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-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/정보 표시/알림 항목`
+
+## 언제 쓰나
+
+알림 한 행을 누르면 바로 읽음으로 바꾸고, 서버가 실패하면 읽지 않음으로 되돌릴 때 쓴다. NotificationItem과 낙관 반영 세션을 연결하며 새 데이터 엔진을 만들지 않는다.
+
+2026-10-06 정리 전에는 이 스토리가 [알림함 화면](../screens/common-inbox.md)과 같은 화면 전체를 그렸다. 지금은 행 단위의 읽음 처리와 복구만 보이고,
+필터·묶음 제목·불러오는 중·빈·오류·로그인 필요 상태는 알림함 화면이 소유한다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `NotificationItem` | 알림 한 행. `read`면 제목 굵기가 풀리고 `statusLabel`이 글로도 상태를 알린다 | [NotificationItem](../components/notification-item.md) |
+| `Avatar` | 보낸 사람(`leading`) | [Avatar](../components/avatar.md) |
+| `createActionSession` + `optimisticValue` | 읽음 즉시 반영, 실패하면 이전 확인 값으로 복구 | [계약](../../action-session.md), [즉시 반영과 복구](action-recovery-optimistic.md) |
+| `Text` 상태 | 읽음 처리 진행·실패 알림 | [Text](../components/text.md) |
+
+## 배치
+
+```text
+┌ 바깥 틀: 알림함 본문 스크롤. 단독 예제는 Container ────────┐
+│ ┌ NotificationItem ─────────────────────────────────────┐ │
+│ │ (아바타)  서연님이 답글을 남겼어요   ← 안 읽음은 굵게  │ │
+│ │           저도 그 산책길 좋아해요…                     │ │
+│ │           새 알림 · 5분 전           ← statusLabel·시각│ │
+│ └───────────────────────────────────────────────────────┘ │
+│          ↕ spacing.sm 12                                  │
+│ ┌ NotificationItem(확인함) ─────────────────────────────┐ │
+│ └───────────────────────────────────────────────────────┘ │
+│ 상태 문구(Web role=status, Native live region)             │
+└───────────────────────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | [NotificationInboxScreen](../components/notification-inbox-screen.md) 본문. 단독 예제는 Web `Container`, Native `ScrollView` > `Container` | 화면 본문 스크롤 | 좌우 `Container gutter` compact 16 / regular 20 |
+| 행 | `NotificationItem` | 세로 목록 | ListRow 크기, 행 사이 `Stack gap="sm"` 12. 행을 카드로 다시 감싸지 않는다 |
+| 상태 | `Text` | 목록 아래(단독 예제). 화면에서는 화면 단위로 한 번 알린다 | `spacing.lg` 20 |
+
+## 흐름과 상태
+
+1. 안 읽은 알림을 누르면 `optimisticValue`로 곧바로 읽음 표시가 되고 제품이 상세로 이동한다.
+2. 진행 중에는 다른 행을 `disabled`로 막아 같은 세션의 겹친 요청을 만들지 않는다(제품은 행마다 세션을 둘 수 있다).
+3. 서버가 실패하면 그 행만 읽지 않음으로 돌아오고 상태 문구가 알린다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 안 읽음: 제목 굵게, `statusLabel` "새 알림" | 행 이름에 제목·상태·시각 |
+| 진행 중 | 누른 행이 읽음으로 바뀜(낙관), 다른 행 `disabled` | 포커스 유지, 상태 문구 |
+| 실패 | 읽지 않음으로 복구 | 상태 문구 알림, 포커스 이동 없음 |
+| 성공 | 읽음 확정, `statusLabel` "확인함" | 상태 문구 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { NotificationItem } from "@hjmds/react/screens";
+
+<NotificationItem
+  read={n.read}
+  statusLabel={n.read ? t("inbox.read") : t("inbox.unread")}
+  timestamp={formatRelative(n.createdAt)}
+  title={n.title}
+  description={n.body}
+  leading={senderAvatar}
+  href={n.url}
+/>
+```
+
+```tsx
+// Native
+import { NotificationItem } from "@hjmds/react-native/screens";
+
+<NotificationItem
+  read={n.read}
+  statusLabel={n.read ? t("inbox.read") : t("inbox.unread")}
+  timestamp={formatRelative(n.createdAt)}
+  title={n.title}
+  description={n.body}
+  leading={senderAvatar}
+  onPress={() => openNotification(n.id)}
+/>
+```
+
+제품 데이터·콜백은 주입한다. 위 공개 API 지침에 Web·Native 차이를 유지한다.
+
+## 함정
+
+- 읽음 상태를 제목 굵기만으로 알리지 않는다. `statusLabel`을 반드시 준다.
+- 읽음 처리 실패를 조용히 삼키지 않는다. 이전 상태로 되돌리고 알린다.
+- 필터·묶음 제목·화면 상태를 행 예제에 다시 만들지 않는다. [알림함 화면](../screens/common-inbox.md)이 소유한다.
+- 스토리의 "다음 읽음 처리 실패시키기"·350ms 지연은 데모 전용이다.

package/docs/usage/compositions/compound-controls.md

@@ -0,0 +1,186 @@
+# 복합 입력 모음
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [복합 입력 계약](../../compound-controls.md), `showcase/shared/compound-controls.ts`, `showcase/{web/src/patterns,native/src}/compound-previews.tsx`
+- 스토리북: `배포/구성/비교와 검증/복합 입력 모음`
+
+## 언제 쓰나
+
+기존 컨트롤을 묶은 네 가지 복합 입력(소요 시간, 버튼 자리 확인, 이모지 반응, 알림 종)을 화면 안 한 블록으로 둘 때 쓴다.
+스토리 네 개(소요 시간 선택·버튼 안에서 확인·이모지 반응·알림 상태)가 각각 "제목 → 설명 → 컨트롤 → 결과" 블록 하나를 보인다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `Heading level="level3"` | 블록 제목(24). 문서 단계는 화면 구조에 맞춰 `semanticLevel` | [Heading](../components/heading.md) |
+| Text `tone="muted"` | 설명·안내 | [Text](../components/text.md) |
+| DurationField (`/duration-field`) | 시·분·초로 정수 초를 고른다 | [NumberField](../components/number-field.md) |
+| InlineConfirm (`/inline-confirm`) | 오버레이 없이 버튼 자리에서 한 번 더 확인(트리거·확인 `danger`, 취소 `ghost`) | [Button](../components/button.md) |
+| ReactionPicker (`/reaction-picker`) | 반응 하나를 고르거나 해제(`ghost` `pill` 토글 버튼 묶음) | [Button](../components/button.md) |
+| NotificationBell (`/notification-bell`) | 읽지 않은 수가 있는 종 아이콘 버튼 | [IconButton](../components/icon-button.md) |
+| `Stack` | 블록 안 세로 쌓기 `gap="xl"` | [Stack](../components/stack.md) |
+| `Container` · `ScrollView` | 바깥 틀. 제품 화면이 소유한다 | [Container](../components/container.md), [화면 여백](../tokens/layout.md) |
+| Switch, Button `ghost`·`primary` | 스토리의 실패 응답 토글·다시 시작·알림 추가(데모 전용, 제품에는 넣지 않는다) | [Switch](../components/switch.md), [Button](../components/button.md) |
+
+## 배치
+
+```text
+┌ 화면 바깥 틀(제품 소유) ───────────────────────────┐
+│ Web: 문서 스크롤 · Native: ScrollView              │
+│ ↕ Native 위아래 spacing.lg 20                      │
+│ ←gutter 16|20→ Container ←gutter 16|20→           │
+└────────────────────────────────────────────────────┘
+
+소요 시간 선택                          버튼 안에서 확인
+┌── Stack gap spacing.xl 24 ──────┐     ┌── Stack gap spacing.xl 24 ──────────┐
+│ 제목 (Heading level3)           │     │ 제목                                 │
+│ 설명 (muted)                    │     │ 설명 (muted)                         │
+│ 집중할 시간                     │     │ [ 초안 삭제 ] danger ← 처음 트리거   │
+│ [− 시 +] [− 분 +] [− 초 +]      │     │   ↓ 누르면 같은 자리에서             │
+│   ↑ 칸 사이 spacing.md 16,      │     │ 이 초안을 삭제할까요?                │
+│     좁거나 큰 글자면 줄바꿈      │     │ (오류 문구, 실패 때만)               │
+│ 총 1,500초  ← 결과              │     │ [유지하기] [삭제하기]  ← 취소 → 확인  │
+└─────────────────────────────────┘     │   ghost     danger, 사이 spacing.sm 12│
+                                        └──────────────────────────────────────┘
+이모지 반응                              알림 상태
+┌─────────────────────────────────┐     ┌──────────────────────────────────────┐
+│ 제목                            │     │ (🔔 3)   ← NotificationBell           │
+│ [👍] [💜] [🎉] [✨]  ← 하나 선택 │     │ 안내 (muted)                          │
+│   ghost pill, 사이 spacing.xs 8 │     └──────────────────────────────────────┘
+└─────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web 문서 스크롤 > `Container`. Native `ScrollView` > `Container` | 블록을 감싸는 제품 화면. 상단 안전 영역은 내비게이션 헤더(또는 [TopBar](../components/top-bar.md))가 맡는다 | 좌우 `Container gutter`: 폭 600 미만 `compact` 16, 이상 `regular` 20([화면 여백](../tokens/layout.md)). Native 위아래는 `contentContainerStyle` `paddingVertical: spacing.lg` 20 |
+| 블록 | `Stack gap="xl"` | 바깥 틀 안, 본문 흐름 | 자식 사이 `spacing.xl` 24 |
+| 소요 시간 | DurationField | 설명 아래 | NumberField 세 칸, 칸 사이 `spacing.md` 16. Web은 칸 최소 10ch로 자동 줄바꿈, Native는 글자 배율에 비례한 칸 폭으로 줄바꿈 |
+| 확인 | InlineConfirm | 트리거 자리 그대로 | 트리거와 확인 행동이 같은 자리, Button 높이 44, 질문·버튼 줄 사이와 두 버튼 사이 `spacing.sm` 12 |
+| 반응 | ReactionPicker | 제목 아래 | `ghost` `pill` Button 묶음, 사이 `spacing.xs` 8, 넘치면 줄바꿈 |
+| 알림 종 | NotificationBell | 블록 맨 위, 시작 쪽 정렬 | IconButton(기본 `medium` 44) + CounterBadge `floating`(끝·위 모서리) |
+
+## 흐름과 상태
+
+1. 소요 시간: 증감 버튼은 즉시, 타이핑은 blur에서 확정된다. 합계가 `min`~`max`로 clamp된다. `max`가 1시간 미만이면 시 칸이 비활성이다.
+2. 버튼 안에서 확인: 트리거를 누르면 같은 자리에 질문과 [취소][확인]이 나온다. 확인하면 `onConfirm`이 돌고 성공·오류를 같은 자리에 보인다.
+3. 확인이 실패(`onConfirm`의 throw·reject: 네트워크·서버 오류)하면 질문 아래 `errorLabel`이 나오고, 같은 확인 버튼이 다시 시도가 된다.
+   다시 시도도 실패하면 같은 오류 문구가 남는다. 취소하면 트리거로 돌아간다.
+4. 이모지 반응: 하나를 고르면 선택, 같은 것을 다시 누르면 해제, 다른 것을 누르면 바뀐다. 개수·저장은 제품 데이터다.
+   서버에 저장하다 실패하면 값을 되돌리는 것은 [즉시 반영과 복구](action-recovery-optimistic.md)대로 제품이 한다.
+5. 알림 종: 누르면 `onPress`만 온다. 읽음 처리는 제품이 한다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 각 블록의 초기 값. InlineConfirm은 트리거 버튼 하나(`danger`) | — |
+| 확인 대기 | 질문 + [유지하기][삭제하기] | Web은 취소에 처음 포커스, Escape는 취소하고 트리거로 포커스 복귀. Native는 질문이 live region, iOS 한 번 알림 |
+| 진행 중 | InlineConfirm busy. 두 행동 비활성, 확인 버튼 `loading` + `pendingLabel`. DurationField·ReactionPicker·NotificationBell은 진행 상태가 없다 | Native iOS는 상태마다 한 번 알림, Web Escape 무시 |
+| 실패 | InlineConfirm error. 질문 아래 `errorLabel`(Native `tone="danger"`), 확인 버튼으로 다시 시도 | Web `role="alert"`, Native `accessibilityRole="alert"` + iOS는 대기 중 음성을 끊고 알린다 |
+| 재시도 실패 | 같은 `errorLabel`이 다시 나온다(busy → error로 바뀌므로 다시 알림) | 실패와 같다 |
+| 확인 성공 | `successLabel`이 남는다 | Web `role="status"`, Native live region. 초기화는 새 `key`로 remount |
+| 알림 수 증가 | 종이 400ms 한 번 흔들린다 | 종 그림·배지는 숨기고 `label` 한 번만 읽는다 |
+| reduced motion·배경·`active={false}` | 종이 흔들리지 않는다 | — |
+
+- 문구(`labels`·확인 문구·반응 `label`·종 `label`)는 모두 제품이 i18n 키로 넣는다. 개수가 들어가는 문구는 `t(key, { count })`로 만든다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { useState } from "react";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+import { Icon } from "@hjmds/react/display";
+import { DurationField } from "@hjmds/react/duration-field";
+import { Heading } from "@hjmds/react/heading";
+import { InlineConfirm } from "@hjmds/react/inline-confirm";
+import { Container, Stack, Text } from "@hjmds/react/layout";
+import { NotificationBell } from "@hjmds/react/notification-bell";
+import { ReactionPicker } from "@hjmds/react/reaction-picker";
+
+function CompoundBlocks() {
+  const [seconds, setSeconds] = useState(1500);
+  const [reaction, setReaction] = useState<string | null>(null);
+  const gutter = resolveWindowClass(window.innerWidth) === "compact" ? "compact" : "regular";
+  return (
+    <Container gutter={gutter}>
+      <Stack gap="xl">
+        <Heading level="level3" semanticLevel={2}>{t("focus.title")}</Heading>
+        <Text as="p" tone="muted">{t("focus.description")}</Text>
+        <DurationField value={seconds} onValueChange={setSeconds} max={86399} labels={durationLabels} />
+        <InlineConfirm key={draft.id} label={t("draft.delete")} prompt={t("draft.delete.prompt")}
+          confirmLabel={t("draft.delete.confirm")} cancelLabel={t("draft.delete.cancel")}
+          pendingLabel={t("draft.delete.pending")} successLabel={t("draft.delete.done")}
+          errorLabel={t("draft.delete.error")} onConfirm={() => deleteDraft(draft.id)} />
+        <ReactionPicker label={t("reaction.group")} options={reactions} value={reaction} onValueChange={setReaction} />
+        <NotificationBell count={unread} label={t("inbox.unread", { count: unread })}
+          icon={<Icon name="notifications" />} onPress={openInbox} />
+      </Stack>
+    </Container>
+  );
+}
+```
+
+```tsx
+// Native
+import { useState } from "react";
+import { ScrollView, useWindowDimensions } from "react-native";
+import { spacing } from "@hjmds/design-contracts/foundations";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+import { DurationField } from "@hjmds/react-native/duration-field";
+import { Heading } from "@hjmds/react-native/heading";
+import { InlineConfirm } from "@hjmds/react-native/inline-confirm";
+import { NotificationBell } from "@hjmds/react-native/notification-bell";
+import { Container, Icon, Stack, Text } from "@hjmds/react-native/primitives";
+import { ReactionPicker } from "@hjmds/react-native/reaction-picker";
+
+function CompoundBlocks() {
+  const [seconds, setSeconds] = useState(1500);
+  const [reaction, setReaction] = useState<string | null>(null);
+  const { width } = useWindowDimensions();
+  return (
+    <ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
+      <Container gutter={resolveWindowClass(width) === "compact" ? "compact" : "regular"}>
+        <Stack gap="xl">
+          <Heading level="level3" semanticLevel={2}>{t("focus.title")}</Heading>
+          <Text tone="muted">{t("focus.description")}</Text>
+          <DurationField value={seconds} onValueChange={setSeconds} max={86399} labels={durationLabels} />
+          <InlineConfirm key={draft.id} {...confirmLabels} onConfirm={() => deleteDraft(draft.id)} />
+          <ReactionPicker label={t("reaction.group")} options={reactions} value={reaction} onValueChange={setReaction} />
+          <NotificationBell count={unread} label={t("inbox.unread", { count: unread })}
+            icon={<Icon descriptor={{ name: "notifications" }} renderGlyph={renderGlyph} />} onPress={openInbox} />
+        </Stack>
+      </Container>
+    </ScrollView>
+  );
+}
+```
+
+`durationLabels`는 `{ label, hours, minutes, seconds, increment(unit), decrement(unit) }`를 제품이 현지화한다.
+`confirmLabels`는 Web 예의 일곱 문구(`label`·`prompt`·`confirmLabel`·`cancelLabel`·`pendingLabel`·`successLabel`·`errorLabel`) 묶음이다.
+반응 목록·이모지·개수, 삭제 동작과 서버 멱등성, `renderGlyph`(예: `createLucideGlyph`)는 제품 소유다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 바깥 스크롤 | 문서 스크롤 | `ScrollView`(위아래 `spacing.lg`) |
+| 종 아이콘 | `<Icon name>` | `<Icon descriptor renderGlyph>` |
+| 확인 알림 | 포커스 이동 + Escape, 오류 `role="alert"` | iOS 명시 알림, Android live region, 오류 `accessibilityRole="alert"` |
+| 소요 시간 칸 줄바꿈 | CSS grid `auto-fit`(칸 최소 10ch) | 글자 배율에 비례한 칸 폭 + `flexWrap` |
+
+## 함정
+
+- 반응 개수를 화면낭독기에 알려야 하면 옵션 `label` 문구 안에 개수를 넣는다. 보이는 이모지·개수 그림은 장식으로 숨겨진다.
+- NotificationBell 누름이 읽음 처리를 하지 않는다. 제품이 count를 갱신해야 배지가 줄어든다.
+- DurationField 범위 밖 `value`는 조용히 고치지 않고 오류를 던진다.
+- InlineConfirm의 성공 상태는 다시 트리거로 돌아가지 않는다. 같은 자리에서 다시 쓰려면 새 `key`로 remount한다.
+- 현재 Native 스토리는 블록 제목을 `Text variant="heading"`으로 그리고, Web 스토리는 `Heading level="level2"`(32)를 쓴다.
+  플랫폼별 크기 차이에 근거가 없으므로 제품은 두 플랫폼 모두 `Heading level="level3"`(24)과 화면 구조에 맞는 `semanticLevel`을 쓴다.
+- 현재 Native 스토리는 `ScrollView contentContainerStyle={{ padding: spacing.xl, gap: spacing.xl }}`로 좌우 여백과 간격을 직접 준다.
+  좌우 여백은 `Container gutter`, 위아래는 `paddingVertical: spacing.lg`, 자식 간격은 `Stack gap="xl"`로 둔다([화면 여백](../tokens/layout.md)).
+- 현재 스토리의 Switch "실패 응답 보기"·"예제 다시 시작"·"새 알림 추가" 버튼은 데모 조작이다. 알림 상태 스토리의 "새 알림 추가"는 primary라
+  제품 화면에 옮기면 그 화면의 주 행동과 겹친다.