@hjmds/design-contracts 1.12.1 → 1.13.0

package/docs/usage/components/watermark.md

@@ -0,0 +1,78 @@
+# Watermark
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Watermark](../../watermark.md), `src/watermark.ts`(`watermarkRecipe`)
+- 스토리북: `배포/컴포넌트/상태와 알림/워터마크`
+
+## 언제 쓰나
+
+Web에서 문서 미리보기·초안 화면 위에 "초안", 프로젝트 이름 같은 **장식용 출처 표시 텍스트**를 비스듬히
+반복해 깔 때 쓴다. inline SVG pattern이라 외부 요청·canvas가 없고, 오버레이는 클릭·텍스트 선택을 막지 않는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 스크린샷·복제·유출 방지 | 없음. Watermark는 보안 기능이 아니다 |
+| 반드시 읽혀야 하는 출처·보안 고지 | 본문 [Notice](notice.md) 또는 [Text](text.md) |
+| 이미지 워터마크, 다운로드 파일에 삽입 | 없음(제공하지 않음) |
+| 화면 상태 배지("초안" 한 곳 표시) | [Badge](badge.md), [Tag](tag.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Watermark` | 기본 | `/watermark`만(root 없음) | — |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Watermark } from "@hjmds/react/watermark";
+
+<Watermark text={[t("document.draft"), projectName]}>
+  <DocumentPreview />
+</Watermark>
+```
+
+Native: 없음.
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `text` | 문자열 또는 1~3줄 배열 | — | 각 줄은 비어 있지 않고 120자 이하 |
+| `tileWidth` | 80 이상 | 240 | 범위를 벗어나면 `TypeError` |
+| `tileHeight` | 60 이상 | 160 | 범위를 벗어나면 `TypeError` |
+| `rotate` | -90~90 | -22 | 범위를 벗어나면 `TypeError` |
+| `opacity` | 0~1 | 0.12 | 범위를 벗어나면 `TypeError` |
+| `children` | `ReactNode` | — (필수) | 표시를 깔 내용 |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 감싸는 루트의 바깥 배치(margin·폭·flex·`alignSelf`) |
+
+글자 색은 `--hjm-color-text-sub` 토큰이다. 색 prop은 없다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 자체 크기·여백이 없다. 감싼 내용이 그대로 흐르고 오버레이가 그 영역 전체(`inset: 0`)를 덮으며, 넘치는 무늬는 영역 경계에서 잘린다. 타일 기본 240×160, -22° 회전 | `.hjm-watermark__overlay`, `watermarkRecipe` |
+| 간격 | 영역 크기와 바깥 간격은 `layoutStyle`이나 감싸는 요소가 정한다 | `react/src/watermark.tsx` |
+| 순서·정렬 | 내용(z-index 0) 위에 오버레이(z-index 1), 클릭·선택은 내용으로 통과 | `.hjm-watermark__content`, `.hjm-watermark__overlay`(pointer-events: none) |
+| 고정·스크롤 | 표시를 깔 영역(문서 미리보기 카드·초안 본문)만 감싼다. 화면 전체나 TopBar·BottomCTA 같은 고정 영역까지 감싸지 않는다. 스크롤 영역 안에 두면 내용과 함께 스크롤되고, 스크롤 컨테이너 자체를 감싸면 무늬는 보이는 창에 고정된다 | `.hjm-watermark`(position: relative) |
+| 좁은 폭·큰 글자 | 영역이 타일 하나보다 작으면 문구가 잘려 보이므로 `tileWidth`·`tileHeight`를 영역에 맞게 줄인다(최소 80×60) | `resolveWatermark` |
+
+## 꼭 지킬 것
+
+- 표시 문구는 i18n 키로 만들고, 프로젝트명 같은 데이터는 그대로 넘긴다. 문자열은 React text node로만 들어가 마크업으로 해석되지 않는다.
+- 긴 문구는 줄을 자르지 말고 `tileWidth`·`tileHeight`를 키운다.
+- 오버레이는 `aria-hidden`이다. 보조기술 사용자에게도 필요한 내용이면 본문에 따로 쓴다.
+- `className`·`style`·`ref`를 받지 않는다. 배치는 `layoutStyle`이나 감싸는 요소에서 한다. 오버레이 위치는 `hjm-watermark`의
+  `position: relative`에 의존하므로 `@hjmds/react`의 `styles.css`가 필요하다.
+
+## 함정
+
+- SVG는 DOM 콘텐츠라 인쇄에도 나온다. 인쇄 결과는 소비 환경에서 확인한다(계약 문서 기준, HJM이 인쇄를 검증하지 않음).

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

@@ -0,0 +1,180 @@
+# 즉시 반영과 복구
+
+- 단계: 구성
+- 상태: 배포
+- 지원: 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-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/피드백과 복구/즉시 반영과 복구`
+
+## 언제 쓰나
+
+북마크·좋아요·알림 켜기처럼 되돌려도 피해가 없는 저위험 토글을 누르는 즉시 화면에 반영하고, 서버가 실패하면 직전 확인 값으로 되돌릴 때 쓴다.
+
+결제·영구 삭제·권한 변경처럼 실패를 화면만 되돌려 숨기면 안 되는 작업에는 쓰지 않는다. 그때는 [저장과 재시도](action-recovery-save.md)처럼
+서버 확인 뒤 표시한다.
+
+같은 `공통 동작` 묶음: [저장과 재시도](action-recovery-save.md) · [보관과 실행 취소](action-recovery-undo.md).
+세션 생성·구독·상태 알림은 [저장과 재시도의 공통 절](action-recovery-save.md#공통-세션과-상태-알림)을 따른다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `createActionSession` + `optimisticValue` | pending 동안 새 값을 먼저 보이고, 실패하면 이전 확인 값으로 복구 | [계약](../../action-session.md) |
+| `Heading` | 묶음 제목(선택). 크기 `level3`(24), 문서 단계는 화면 구조에 맞춰 `semanticLevel` | [Heading](../components/heading.md) |
+| `Button selected` | 켜고 끄는 토글. `selected`=현재(낙관) 값, pending 중 `disabled` | [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) |
+| `Container` · `ScrollView` | 바깥 틀. 제품 화면이 소유한다 | [Container](../components/container.md), [화면 여백](../tokens/layout.md) |
+
+스토리의 `tone="ghost"` "서버에서 새 상태 불러오기"는 `reset`이 지난 응답을 버리는 것을 보여 주는 데모 버튼이다.
+제품에서는 이 동작을 버튼이 아니라 재조회·계정 변경 시점에 연결한다. "다음 요청 실패시키기"와 350ms 지연도 데모 전용이다.
+
+## 배치
+
+```text
+┌ 화면 바깥 틀(제품 소유) ─────────────────┐
+│ Web: 문서 스크롤 · Native: ScrollView    │
+│ ↕ Native 위아래 spacing.lg 20            │
+│ ←gutter 16|20→ Container ←gutter 16|20→ │
+│ ┌ Stack gap="md" ──────────────────────┐ │
+│ │ 제목 Heading level3 (선택)           │ │
+│ │          ↕ spacing.md 16             │ │
+│ │ [ 북마크 추가 / 해제 (selected) ]    │ │ ← 토글, 높이 44
+│ │          ↕ spacing.md 16             │ │
+│ │ [ 북마크 다시 반영 (secondary) ]     │ │ ← error일 때만
+│ │          ↕ spacing.md 16             │ │
+│ │ 상태 문구 (role=status)              │ │
+│ └──────────────────────────────────────┘ │
+└──────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | 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 |
+| 토글 | `Button selected` | 대상 콘텐츠 아래, 스크롤 | `medium` 44(`control.buttonHeight`), 이웃 `spacing.md` 16. Stack 기본 `align="stretch"`로 꽉 찬 폭 |
+| 재시도 | `Button tone="secondary"` | 토글 아래, error일 때만 | `medium` 44, `spacing.md` 16. 라벨은 무엇을 다시 하는지 적는다(`t("bookmark.retry")`) |
+| 상태 | `Text` | 행동 아래 | `spacing.md` 16 |
+
+- 토글이 목록 행 끝에 들어가면 Button 지침대로 `size="small"`(36, `control.buttonHitSlop.small` 4로 터치 44)과 `secondary`·`ghost`를 쓴다.
+  상태 문구는 행마다 두지 않고 [Toast](../components/toast.md) 등 화면 단위로 한 번 알린다.
+- 라벨은 상태에 따라 바뀐다(`t("bookmark.add")` ↔ `t("bookmark.remove")`). 두 라벨 모두 두 줄 안에 들어가야 한다.
+- 꺼진 토글(`selected={false}`)은 기본 tone primary로 칠해지고, 켜진 토글은 `selected` 처리로 칠해져 primary 수에 세지 않는다
+  ([Button](../components/button.md) 꼭 지킬 것). 그래서 한 화면 primary 하나를 지키려면 재시도는 `secondary`다.
+
+근거: `src/foundations.ts`(`spacing`, `control`, `layout`), `src/action-session.ts`(`optimisticValue`)
+
+## 흐름과 상태
+
+1. 화면은 서버에서 확인한 값으로 토글을 그린다(`createActionSession(serverValue)`).
+2. 누르면 `next = !state.value`로 `session.run(() => api.set(next), { optimisticValue: next, retryable: true })`를 부른다.
+3. pending 동안 `state.value`가 곧바로 `next`가 되어 토글이 바뀌고, 버튼은 `disabled`다. 같은 세션의 새 run·retry는 `blocked`다.
+4. 성공하면 서버가 돌려준 값으로 확정한다.
+5. 실패(네트워크·서버 오류, 작업 함수의 throw·reject)하면 `state.value`가 실행 전 확인 값으로 돌아가고 재시도 버튼이 나온다.
+   `session.retry()`는 같은 `optimisticValue`로 다시 실행해 토글이 다시 새 값으로 바뀐다. 재시도도 실패하면 다시 이전 값으로 돌아가고
+   재시도 버튼이 남는다. error 중 토글을 다시 누르면 새 run이 되고 이전 실패 작업은 버려진다.
+6. 재조회·계정 변경 시 `session.reset(serverValue)`를 부르면 늦게 온 이전 응답과 재시도가 무시된다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | idle. 확인된 값의 토글, 상태 문구 `t("bookmark.hint")` | 알림 없음(첫 렌더는 알리지 않는다) |
+| 진행 중 | pending. 토글이 새 값으로 바뀌고 `disabled`, 상태 문구 `t("bookmark.pending")` | 포커스는 토글에 유지, 상태 문구 알림 |
+| 성공 | success. 서버 값으로 확정, `t("bookmark.saved")` | 상태 문구 알림 |
+| 실패 | error. 이전 값으로 복귀, 재시도 버튼, `t("bookmark.reverted")` | 상태 문구 알림, 포커스 이동 없음 |
+| 재시도 실패 | error 유지. 재시도 → pending → error로 문구가 바뀌므로 다시 알린다 | 상태 문구 알림, 포커스 이동 없음 |
+
+- 상태→문구 키는 상수 표(`bookmarkStatusKey`)로 둔다. 템플릿 문자열 키(`` `bookmark.${status}` ``)는 키 추출·누락 검사가 찾지 못하고
+  위 표의 키와 어긋난다.
+- 오래된 요청이 서버에 반영됐을 수 있으면 `reset`만으로 정합성이 보장되지 않는다. 제품이 재조회·캐시 무효화로 맞춘다.
+- 객체 값은 불변 데이터로 넘긴다.
+- 오류 문구는 제품이 지역화한다. raw exception(`state.error`)을 그대로 보이지 않는다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { useState, useSyncExternalStore } from "react";
+import { createActionSession } 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 bookmarkStatusKey = { idle: "bookmark.hint", pending: "bookmark.pending", success: "bookmark.saved", error: "bookmark.reverted" } as const;
+
+function BookmarkToggle({ initial, setBookmark }: { initial: boolean; setBookmark(next: boolean): Promise<boolean> }) {
+  const [session] = useState(() => createActionSession(initial)); // 렌더마다 새로 만들지 않는다
+  const state = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+  const toggle = () => {
+    const next = !state.value;
+    void session.run(() => setBookmark(next), { optimisticValue: next, retryable: true });
+  };
+  const gutter = resolveWindowClass(window.innerWidth) === "compact" ? "compact" : "regular";
+  return (
+    <Container gutter={gutter}>
+      <Stack gap="md">
+        <Button selected={state.value} disabled={state.status === "pending"} onClick={toggle}>
+          {state.value ? t("bookmark.remove") : t("bookmark.add")}
+        </Button>
+        {state.status === "error" && <Button tone="secondary" onClick={() => void session.retry()}>{t("bookmark.retry")}</Button>}
+        <Text as="p" role="status">{t(bookmarkStatusKey[state.status])}</Text>
+      </Stack>
+    </Container>
+  );
+}
+```
+
+```tsx
+// Native
+import { useState, useSyncExternalStore } from "react";
+import { ScrollView, useWindowDimensions } from "react-native";
+import { createActionSession } 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 } from "@hjmds/react-native/primitives";
+
+const bookmarkStatusKey = { idle: "bookmark.hint", pending: "bookmark.pending", success: "bookmark.saved", error: "bookmark.reverted" } as const;
+
+function BookmarkToggle({ initial, setBookmark }: { initial: boolean; setBookmark(next: boolean): Promise<boolean> }) {
+  const [session] = useState(() => createActionSession(initial));
+  const state = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+  const { width } = useWindowDimensions();
+  const toggle = () => {
+    const next = !state.value;
+    void session.run(() => setBookmark(next), { optimisticValue: next, retryable: true });
+  };
+  return (
+    <ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
+      <Container gutter={resolveWindowClass(width) === "compact" ? "compact" : "regular"}>
+        <Stack gap="md">
+          <Button selected={state.value} disabled={state.status === "pending"} onPress={toggle}>
+            {state.value ? t("bookmark.remove") : t("bookmark.add")}
+          </Button>
+          {state.status === "error" && <Button tone="secondary" onPress={() => void session.retry()}>{t("bookmark.retry")}</Button>}
+          <StatusText>{t(bookmarkStatusKey[state.status])}</StatusText>
+        </Stack>
+      </Container>
+    </ScrollView>
+  );
+}
+```
+
+`setBookmark`(서버가 확정한 boolean을 돌려줌)과 `StatusText`는 제품 소유다([공통 절](action-recovery-save.md#공통-세션과-상태-알림)의 helper).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `selected` 알림 | `aria-pressed` | 접근성 state |
+| 이벤트 | `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/action-recovery-save.md

@@ -0,0 +1,235 @@
+# 저장과 재시도
+
+- 단계: 구성
+- 상태: 배포
+- 지원: 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-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/피드백과 복구/저장과 재시도`
+
+## 언제 쓰나
+
+입력한 내용을 서버에 저장하는 폼 한 덩어리에서 저장 중 중복 실행을 막고, 실패하면 입력을 지우지 않은 채 제출했던 값 그대로 다시 보낼 때 쓴다.
+
+확인창 안의 비동기 확인은 AlertDialog 세션이 이미 소유하므로 여기에 쓰지 않는다. 제품이 TanStack Query mutation 등으로
+상태를 이미 소유하면 세션을 겹쳐 만들지 않고 같은 규칙만 연결한다.
+
+같은 `공통 동작` 묶음: [즉시 반영과 복구](action-recovery-optimistic.md) · [보관과 실행 취소](action-recovery-undo.md).
+세 구성과 [늦은 응답보다 최신 검색 유지](interaction-flow-search.md)가 함께 쓰는 세션 연결·상태 알림은
+이 문서의 [공통: 세션과 상태 알림](#공통-세션과-상태-알림)에 있다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `createActionSession` | idle → pending → success/error 상태, 같은 세션의 중복 실행 차단, `retry` | [계약](../../action-session.md) |
+| `Heading` | 묶음 제목. 크기 `level3`(24), 문서 단계는 화면 구조에 맞춰 `semanticLevel` | [Heading](../components/heading.md) |
+| `TextField` | 저장할 입력. 값은 제품 state(초안)가 소유 | [Field](../components/field.md) |
+| `Button` 저장 | 주 행동. `loading`=pending, 입력이 비면 `disabled` | [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) |
+| `Container` · `ScrollView` | 바깥 틀. 제품 화면이 소유한다 | [Container](../components/container.md), [화면 여백](../tokens/layout.md) |
+
+스토리의 "다음 요청 실패시키기"(secondary 토글)와 350ms 지연은 데모 전용이다. 제품에 넣지 않는다.
+
+## 배치
+
+```text
+┌ 화면 바깥 틀(제품 소유) ─────────────────┐
+│ Web: 문서 스크롤 · Native: ScrollView    │
+│ ↕ Native 위아래 spacing.lg 20            │
+│ ←gutter 16|20→ Container ←gutter 16|20→ │
+│ ┌ Stack gap="md" ──────────────────────┐ │
+│ │ 제목 Heading level3                  │ │
+│ │          ↕ spacing.md 16             │ │
+│ │ 라벨                                 │ │
+│ │ [ 입력                             ] │ │ TextField, 높이 44
+│ │          ↕ spacing.md 16             │ │
+│ │ [        저장 (primary)            ] │ │ ← 주 행동, 높이 44
+│ │          ↕ spacing.md 16             │ │
+│ │ [ 실패한 내용 다시 저장 (secondary)] │ │ ← error일 때만
+│ │          ↕ spacing.md 16             │ │
+│ │ 상태 문구 (role=status)              │ │
+│ │ 저장된 내용: state.value (선택)      │ │
+│ │ 보조 설명 (제품 소유, 선택)          │ │
+│ └──────────────────────────────────────┘ │
+│ 하단 안전 영역(Native, 스크롤 끝 여백)    │
+└──────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web 문서 스크롤 > `Container size="reading"`. Native `ScrollView`(`keyboardShouldPersistTaps="handled"`) > `Container size="reading"` | 이 구성을 감싸는 제품 화면. 상단 안전 영역은 내비게이션 헤더(또는 [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 |
+| 입력 | `TextField` | 제목 아래, 스크롤 | 높이 `control.fieldHeight` 44 |
+| 주 행동 | `Button` 저장(primary) | 입력 바로 아래, 스크롤 | `medium` 44(`control.buttonHeight`), 이웃 `spacing.md` 16. Stack 기본 `align="stretch"`로 꽉 찬 폭이 되므로 `fullWidth`·`layoutStyle`은 필요 없다 |
+| 재시도 | `Button tone="secondary"` 다시 저장 | 주 행동 아래, error일 때만 | `medium` 44, `spacing.md` 16. 라벨은 무엇을 다시 하는지 적는다(스토리 "실패한 내용 다시 저장"). 일반 "다시 시도"만 쓰지 않는다 |
+| 상태 | `Text` | 행동 아래 | `spacing.md` 16 |
+| 확정 값(선택) | `Text` — `state.value` | 상태 문구 아래 | `spacing.md` 16 |
+
+- 모든 간격은 `Stack gap="md"`(`spacing.md` 16) 하나로 맞춘다. `stackRecipe.defaults.gap`도 `md`다.
+- 스토리는 좁은 폭 기준 바깥 틀(Web `Container gutter="compact" size="reading"`, Native `ScrollView` > 같은 Container)을 그린다. 넓은 폭에서는 위 표의 첫 행대로 `regular`를 고른다.
+  키보드가 입력·저장 버튼을 가리는 Native 폼은 입력이 여러 개면 [KeyboardFormScrollView](../components/keyboard-form-scroll-view.md)
+  (peer 필요), peer가 없으면 [KeyboardAvoiding](../components/keyboard-avoiding.md) 기준을 따른다.
+- 저장이 화면 하단 고정 행동이면 Button 대신 [BottomCTA](../components/bottom-cta.md)에 두고, 재시도 버튼과 상태 문구는 본문(스크롤)에 남긴다.
+- 한 화면의 primary는 하나다([Button](../components/button.md)). 재시도는 `secondary`로 두거나 저장 버튼 하나로 모은다.
+
+근거: `src/component-recipes.ts`(`stackRecipe`), `src/foundations.ts`(`spacing`, `control`, `layout`), `src/container.ts`
+
+## 흐름과 상태
+
+1. 사용자가 입력한다. 입력이 비어 있으면 저장 버튼은 `disabled`다.
+2. 저장을 누르면 그 순간의 입력값을 캡처해 `session.run(() => api.save(submitted), { retryable: true })`를 부른다.
+3. pending 동안 같은 세션의 새 run·retry는 `blocked`라 작업 함수가 불리지 않는다.
+4. 실패(네트워크·서버 오류, 작업 함수의 throw·reject)하면 세션 값은 실행 전 값으로 돌아가고 입력 초안은 그대로 남으며
+   재시도 버튼이 나온다. `session.retry()`는 실패한 작업을 캡처한 값으로 다시 부른다.
+5. 재시도도 실패하면 다시 error가 되고 재시도 버튼이 남는다(`retryable` 실행은 실패할 때마다 다시 재시도할 수 있다).
+   error 중 사용자가 입력을 고쳐 저장을 누르면 새 run이 되고 이전 실패 작업은 버려진다.
+6. 성공하면 세션 `state.value`가 서버가 resolve한 값이 된다. 확정 값을 보여 줄 때는 `state.value`를 읽고 입력 초안(draft)은
+   덮어쓰지 않는다(스토리의 "저장된 내용" 줄).
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | idle. 저장 버튼만, 상태 문구 `t("save.hint")`. 입력이 비면 저장 `disabled` | 알림 없음(첫 렌더는 알리지 않는다) |
+| 진행 중 | pending. 저장 버튼 `loading`(라벨 자리 유지, 중앙 스피너 하나), 상태 문구 `t("save.pending")` | 포커스는 버튼에 유지, 상태 문구 알림 |
+| 성공 | success. 상태 문구 `t("save.done")`, 확정 값 줄 갱신 | 상태 문구 알림 |
+| 실패 | error. 입력 유지, 재시도 버튼 등장, 상태 문구 `t("save.failed")` | 상태 문구 알림, 포커스 이동 없음 |
+| 재시도 실패 | error 유지. 재시도 → pending → error로 문구가 바뀌므로 다시 알린다 | 상태 문구 알림, 포커스 이동 없음 |
+
+- 상태→문구 키는 상수 표(`saveStatusKey`)로 둔다. 템플릿 문자열 키(`` `save.${status}` ``)는 키 추출·누락 검사가 찾지 못하고
+  위 표의 키와 어긋난다.
+- 상태 문구 `Text`의 tone은 기본값을 쓴다(스토리). 오류를 색으로도 구분하려면 error일 때만 `tone="danger"`를 주되,
+  색만으로 의미를 전하지 않도록 문구 자체가 실패를 말해야 한다.
+- `retryable` 기본값은 `false`다. 재시도가 안전하다고 제품이 판단한 경우만 켠다.
+- 서버가 멱등 키를 지원하면 같은 제출의 재시도에 같은 제품 요청 키를 쓴다. 세션의 `operationId`는 서버 멱등 키가 아니다.
+- 오류 문구는 제품이 지역화한다. raw exception(`state.error`)을 그대로 보이지 않는다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { useState, useSyncExternalStore } from "react";
+import { createActionSession } from "@hjmds/design-contracts/action-session";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+import { Button } from "@hjmds/react/actions";
+import { TextField } from "@hjmds/react/forms";
+import { Heading } from "@hjmds/react/heading";
+import { Container, Stack, Text } from "@hjmds/react/layout";
+
+const saveStatusKey = { idle: "save.hint", pending: "save.pending", success: "save.done", error: "save.failed" } as const;
+
+function SaveNote({ save }: { save(value: string): Promise<string> }) {
+  const [session] = useState(() => createActionSession("")); // 렌더마다 새로 만들지 않는다
+  const state = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+  const [draft, setDraft] = useState("");
+  const gutter = resolveWindowClass(window.innerWidth) === "compact" ? "compact" : "regular";
+  return (
+    <Container size="reading" gutter={gutter}>
+      <Stack gap="md">
+        <Heading level="level3" semanticLevel={2}>{t("note.title")}</Heading>
+        <TextField label={t("note.body")} value={draft} onValueChange={setDraft} />
+        <Button loading={state.status === "pending"} disabled={!draft.trim()}
+          onClick={() => { const submitted = draft; void session.run(() => save(submitted), { retryable: true }); }}>
+          {t("common.save")}
+        </Button>
+        {state.status === "error" && <Button tone="secondary" onClick={() => void session.retry()}>{t("save.retry")}</Button>}
+        <Text as="p" role="status">{t(saveStatusKey[state.status])}</Text>
+        {state.value && <Text as="p">{t("save.savedValue", { value: state.value })}</Text>}
+      </Stack>
+    </Container>
+  );
+}
+```
+
+```tsx
+// Native
+import { useState, useSyncExternalStore } from "react";
+import { ScrollView, useWindowDimensions } from "react-native";
+import { createActionSession } 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 { Heading } from "@hjmds/react-native/heading";
+import { TextField } from "@hjmds/react-native/inputs";
+import { Container, Stack, Text } from "@hjmds/react-native/primitives";
+
+const saveStatusKey = { idle: "save.hint", pending: "save.pending", success: "save.done", error: "save.failed" } as const;
+
+function SaveNote({ save }: { save(value: string): Promise<string> }) {
+  const [session] = useState(() => createActionSession(""));
+  const state = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+  const [draft, setDraft] = useState("");
+  const { width } = useWindowDimensions();
+  return (
+    <ScrollView keyboardShouldPersistTaps="handled" contentContainerStyle={{ paddingVertical: spacing.lg }}>
+      <Container size="reading" gutter={resolveWindowClass(width) === "compact" ? "compact" : "regular"}>
+        <Stack gap="md">
+          <Heading level="level3" semanticLevel={2}>{t("note.title")}</Heading>
+          <TextField label={t("note.body")} value={draft} onValueChange={setDraft} />
+          <Button loading={state.status === "pending"} disabled={!draft.trim()}
+            onPress={() => { const submitted = draft; void session.run(() => save(submitted), { retryable: true }); }}>
+            {t("common.save")}
+          </Button>
+          {state.status === "error" && <Button tone="secondary" onPress={() => void session.retry()}>{t("save.retry")}</Button>}
+          <StatusText>{t(saveStatusKey[state.status])}</StatusText>{/* 아래 공통 절의 제품 helper */}
+          {state.value ? <Text>{t("save.savedValue", { value: state.value })}</Text> : null}
+        </Stack>
+      </Container>
+    </ScrollView>
+  );
+}
+```
+
+문구 키·저장 API는 제품 소유다.
+
+### 공통: 세션과 상태 알림
+
+- 세션은 엔티티·행동 하나에 하나다. 화면 컴포넌트에서는 `useState(() => createActionSession(initial))`로 한 번 만들고,
+  화면보다 오래 살아야 하면 제품의 작업 소유자(store)에 둔다. unmount 시 자동 reset은 기본으로 넣지 않는다.
+- 구독은 Web·Native 모두 `useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot)`다. SSR은 요청별 세션을 만든다.
+- `reset(value)`는 세대를 바꿔 이전 응답과 재시도를 버린다. 서버 작업을 취소하지는 않는다.
+- 상태 문구 알림: Web은 `<Text role="status">`다. Native는 `Text`에 `accessibilityLiveRegion="polite"`(Android)를 주고,
+  iOS에서는 문구가 바뀌었고 비어 있지 않을 때만, 앱이 active일 때 `AccessibilityInfo.announceForAccessibilityWithOptions(message, { queue: true })`를 부른다.
+  스토리의 `PatternStatus`(`showcase/native/src/pattern-status.tsx`)는 공개 API가 아니므로 제품에서 같은 동작의 helper를 만든다.
+  나머지 Text prop은 `Omit<ComponentProps<typeof Text>, ...>`로 받아 그대로 넘긴다(optional prop을 `tone?: …`로 따로 받아 넘기면
+  `exactOptionalPropertyTypes`에서 TS2375가 난다).
+
+```tsx
+// Native
+import { useEffect, useRef, type ComponentProps } from "react";
+import { AccessibilityInfo, AppState, Platform } from "react-native";
+import { Text } from "@hjmds/react-native/primitives";
+
+type StatusTextProps = Omit<ComponentProps<typeof Text>, "children" | "accessibilityLiveRegion"> & { children: string };
+
+function StatusText({ children, ...props }: StatusTextProps) {
+  const previous = useRef(children); // 첫 렌더는 알리지 않는다
+  useEffect(() => {
+    const changed = previous.current !== children;
+    previous.current = children;
+    if (changed && children.trim() && Platform.OS === "ios" && AppState.currentState === "active") {
+      AccessibilityInfo.announceForAccessibilityWithOptions(children, { queue: true });
+    }
+  }, [children]);
+  return <Text {...props} accessibilityLiveRegion="polite">{children}</Text>;
+}
+```
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 입력 import·이벤트 | `@hjmds/react/forms`, `onValueChange`(문자열 값, Native와 같은 이름). DOM 이벤트가 필요할 때만 `onChange`(둘 다 호출된다) | `@hjmds/react-native/inputs`, `onValueChange` |
+| 버튼 이벤트 | `onClick` | `onPress` |
+| 바깥 스크롤 | 문서 스크롤 | `ScrollView`(`keyboardShouldPersistTaps="handled"`, 위아래 `spacing.lg`) |
+| 상태 알림 | `role="status"` | live region(Android) + iOS 알림 호출 |
+| 로딩 중 포커스 | — | Button이 기본으로 포커스 유지(`disableWhileLoading`으로만 옛 동작) |
+
+## 함정
+
+- 재시도에서 현재 입력 state를 다시 읽으면 실패 뒤 고친 값이 "같은 제출의 재시도"로 나간다. 제출 시점 값을 캡처한다.
+- 렌더 중 `createActionSession`을 부르면 매 렌더 새 세션이 생겨 중복 차단이 사라진다.
+- 구획 제목은 Heading으로 표시한다. 이전 Text heading 예제는 2026-10-06 제목 의미 구조를 맞추면서 수정했다.
+- 재시도는 secondary로 두어 저장과 경쟁하는 primary를 만들지 않는다(2026-10-06 예제 반영).