@hjmds/design-contracts 1.18.0 → 1.20.0

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

@@ -3,7 +3,7 @@
 - 단계: 구성
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
+- 적용: 구성 API 지침 참조
 - 검토일: 2026-10-06
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/구성/시작하기/첫 작업을 만들고 이어하기`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/구성/입력과 작성/첫 작업을 만들고 이어하기`
@@ -28,8 +28,8 @@
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
-| 바깥 틀 | Steps 또는 포함 Surface | 부모 화면의 해당 슬롯 | [배치](../components/steps.md#배치)에 따른다 |
-| 내용 | Steps 내부 슬롯 | 주제 → 입력 → 검토 → 결과 | spacing 토큰과 포함 컴포넌트 recipe |
+| 바깥 틀 | 부모 화면 또는 포함 Surface | 부모 화면의 해당 슬롯 | [배치](../components/steps.md#배치)에 따른다 |
+| 내용 | Steps와 분리한 입력·요약 슬롯 | 주제 → 입력 → 검토 → 결과 | spacing 토큰과 포함 컴포넌트 recipe |
 | 행동 | Button 또는 공개 콜백 | 내용과 가까운 명시 진입점 | 주 행동 하나, 보조 행동과 구분 |
 
 ## 흐름과 상태
@@ -46,49 +46,70 @@
 
 ## 코드 골격
 
-```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 })}
-/>
-```
+<!-- usage-example: Web ../../../../../showcase/web/src/patterns/reference-flow-previews.tsx -->
+<!-- usage-example: Native ../../../../../showcase/native/src/reference-flow-previews.tsx -->
+
+이 이름의 독립 공개 컴포넌트는 없다. 아래는 공개 `createActionSession`과 입력·Steps·Sheet를 조합하는 예제다. Storybook 예제 파일을 제품에서 import하지 않는다.
+
+- [Web 실행 예제](../../../../../showcase/web/src/patterns/reference-flow-previews.tsx)의 `Editor(kind="first")`
+- [Native 실행 예제](../../../../../showcase/native/src/reference-flow-previews.tsx)의 `Editor(kind="first")`
+- [공통 검증·초안 비교](../../../../../showcase/shared/reference-flows.ts)의 `draftError`, `sameDraft`는 예제 데이터 규칙이며 제품 규칙으로 교체한다.
+
+주제 선택(0) → 입력(1) → 검토(2) → 저장 결과 순서다. 중단은 paused 표시만 바꾸고 draft와 stage를 보존한다. 이어하기는 이를 다시 보여 준다.
 
 ```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 })}
-/>
+// Web — Native도 같은 상태 골격을 사용한다. JSX/문구/영속 저장은 각 제품의 기존 화면 슬롯에 연결한다.
+import { useState, useSyncExternalStore } from "react";
+import { createActionSession } from "@hjmds/design-contracts/action-session";
+
+const [session] = useState(() => createActionSession(initialValue));
+const saved = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+const [draft, setDraft] = useState(initialValue);
+const [stage, setStage] = useState(0);
+const [paused, setPaused] = useState(false);
+const busy = saved.status === "pending";
+const dirty = !sameDraft(draft, saved.value);
+
+function review() {
+  if (busy || draftError(draft)) return; // 오류 문구를 입력에 연결하고 첫 오류 입력으로 이동
+  setStage(2);
+}
+async function save() {
+  if (draftError(draft)) return;
+  const submitted = { ...draft };
+  // pending 중 재호출은 계약이 차단한다. 실패하면 saved.value와 draft를 보존한다.
+  const result = await session.run(() => saveToServer(submitted));
+  if (result.status === "success") setDraft(result.value);
+}
+function discard() {
+  if (session.getSnapshot().status === "pending") return;
+  setDraft(saved.value);
+  session.reset(saved.value);
+  setPaused(true);
+}
 ```
 
-제품 데이터·콜백은 주입한다. 위 공개 API 지침에 Web·Native 차이를 유지한다.
+| 표시/행동 | 연결 |
+| --- | --- |
+| 진행 단계 | `Steps.descriptor.currentStepId`를 `stage`에서 도출, 저장 실패 시 `currentStepStatus="error"` |
+| 편집 | `TextField`/선택 컨트롤은 draft를 편집. pending 동안 disabled이며 이미 큐에 든 입력·이탈·되돌리기 콜백도 최신 session 상태로 차단. 변경 시 오래된 실패 표시를 해제 |
+| 검토 | 같은 draft의 요약과 수정 버튼. 요약에서 값을 따로 보관하지 않음 |
+| 저장 | `Button.loading=busy`, 성공 결과는 서버 응답에서, 실패는 Notice와 같은 저장 버튼 재시도 |
+| 되돌리기 | dirty이며 pending이 아닐 때 저장값 복원. 서버 요청 취소로 설명하지 않음 |
+| 중단/이탈 | first/review는 메모리 draft·stage를 유지해 이어하기. settings는 dirty이면 확인 Sheet |
+| 확정 이후 | 결과 확인과 새 편집 진입을 구분. 새 편집은 마지막 확정값으로 시작 |
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 입력/단계 포커스 | DOM 입력·제목 ref | Native 입력 ref와 접근성 포커스 |
+| 결과 알림 | role=status | Android live region + iOS 접근성 알림 |
+| 이탈 확인 | 공개 Sheet의 dismiss/focus 계약 | 공개 Sheet의 dismiss/키보드/복귀 계약 |
+
+입력 오류는 입력 ref로 복귀한다. 설정 Sheet를 취소하면 실제 이탈 버튼, 변경을 버려 버튼이 사라지면 유지되는 단계 제목으로 복귀한다. Web은 안정적인 단계 제목/입력 ref에 포커스를 옮기고 `role="status"`로 결과를 알린다. Native는 공개 입력 ref와 단계 제목의 접근성 포커스·알림을 연결하며, unmount 때 예약된 포커스 이동을 취소한다. Sheet의 포커스·키보드·dismiss 정책은 기존 계약에 맡긴다. 제품은 validation 결과, 저장 API, 라우터 이탈 이벤트와 확인 Sheet의 연결, i18n 키를 제공한다.
+
+메모리 초안은 이 예제의 mounted 화면 안에서만 유지된다. 새로고침·프로세스 종료·다른 기기 복구와 서버 중복 처리 방지는 제품 저장소와 API 계약이 있어야 한다. `session.reset`은 서버 요청 취소가 아니다.
 
 ## 함정
 

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

@@ -3,20 +3,20 @@
 - 단계: 구성
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
+- 적용: 구성 API 지침 참조
 - 검토일: 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) |
+| TextField · createActionSession | 선택 내용을 검토하고 수정 후 명시적으로 확정 | [공개 계약](../components/form.md) |
 | Button | 명시 행동·재시도 | [Button](../components/button.md) |
 
 ## 배치
@@ -28,8 +28,8 @@
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
-| 바깥 틀 | Form 또는 포함 Surface | 부모 화면의 해당 슬롯 | [배치](../components/form.md#배치)에 따른다 |
-| 내용 | Form 내부 슬롯 | 입력 → 요약 → 수정·저장 | spacing 토큰과 포함 컴포넌트 recipe |
+| 바깥 틀 | 부모 화면 또는 포함 Surface | 부모 화면의 해당 슬롯 | [배치](../components/form.md#배치)에 따른다 |
+| 내용 | 부모 화면의 입력·요약 슬롯 | 입력 → 요약 → 수정·저장 | spacing 토큰과 포함 컴포넌트 recipe |
 | 행동 | Button 또는 공개 콜백 | 내용과 가까운 명시 진입점 | 주 행동 하나, 보조 행동과 구분 |
 
 ## 흐름과 상태
@@ -46,60 +46,70 @@
 
 ## 코드 골격
 
-```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>
-```
+<!-- usage-example: Web ../../../../../showcase/web/src/patterns/reference-flow-previews.tsx -->
+<!-- usage-example: Native ../../../../../showcase/native/src/reference-flow-previews.tsx -->
+
+이 이름의 독립 공개 컴포넌트는 없다. 아래는 공개 `createActionSession`과 입력·Steps·Sheet를 조합하는 예제다. Storybook 예제 파일을 제품에서 import하지 않는다.
+
+- [Web 실행 예제](../../../../../showcase/web/src/patterns/reference-flow-previews.tsx)의 `Editor(kind="review")`
+- [Native 실행 예제](../../../../../showcase/native/src/reference-flow-previews.tsx)의 `Editor(kind="review")`
+- [공통 검증·초안 비교](../../../../../showcase/shared/reference-flows.ts)의 `draftError`, `sameDraft`는 예제 데이터 규칙이며 제품 규칙으로 교체한다.
+
+입력(1) → 검토(2) → 저장 결과 순서다. 검토에서 수정을 누르면 같은 draft로 입력 단계에 돌아간다. 저장은 검토한 draft의 복사본을 캡처한다.
 
 ```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>
+// Web — Native도 같은 상태 골격을 사용한다. JSX/문구/영속 저장은 각 제품의 기존 화면 슬롯에 연결한다.
+import { useState, useSyncExternalStore } from "react";
+import { createActionSession } from "@hjmds/design-contracts/action-session";
+
+const [session] = useState(() => createActionSession(initialValue));
+const saved = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+const [draft, setDraft] = useState(initialValue);
+const [stage, setStage] = useState(1);
+const [paused, setPaused] = useState(false);
+const busy = saved.status === "pending";
+const dirty = !sameDraft(draft, saved.value);
+
+function review() {
+  if (busy || draftError(draft)) return; // 오류 문구를 입력에 연결하고 첫 오류 입력으로 이동
+  setStage(2);
+}
+async function save() {
+  if (draftError(draft)) return;
+  const submitted = { ...draft };
+  // pending 중 재호출은 계약이 차단한다. 실패하면 saved.value와 draft를 보존한다.
+  const result = await session.run(() => saveToServer(submitted));
+  if (result.status === "success") setDraft(result.value);
+}
+function discard() {
+  if (session.getSnapshot().status === "pending") return;
+  setDraft(saved.value);
+  session.reset(saved.value);
+  setPaused(true);
+}
 ```
 
-제품 데이터·콜백은 주입한다. 위 공개 API 지침에 Web·Native 차이를 유지한다.
+| 표시/행동 | 연결 |
+| --- | --- |
+| 진행 단계 | `Steps.descriptor.currentStepId`를 `stage`에서 도출, 저장 실패 시 `currentStepStatus="error"` |
+| 편집 | `TextField`/선택 컨트롤은 draft를 편집. pending 동안 disabled이며 이미 큐에 든 입력·이탈·되돌리기 콜백도 최신 session 상태로 차단. 변경 시 오래된 실패 표시를 해제 |
+| 검토 | 같은 draft의 요약과 수정 버튼. 요약에서 값을 따로 보관하지 않음 |
+| 저장 | `Button.loading=busy`, 성공 결과는 서버 응답에서, 실패는 Notice와 같은 저장 버튼 재시도 |
+| 되돌리기 | dirty이며 pending이 아닐 때 저장값 복원. 서버 요청 취소로 설명하지 않음 |
+| 중단/이탈 | first/review는 메모리 draft·stage를 유지해 이어하기. settings는 dirty이면 확인 Sheet |
+| 확정 이후 | 결과 확인과 새 편집 진입을 구분. 새 편집은 마지막 확정값으로 시작 |
 
 ## 플랫폼 차이
 
 | 항목 | Web | Native |
 | --- | --- | --- |
-| 첫 오류 포커스 | 제품이 `onSubmit`에서 해당 입력 `ref.focus()` | `firstInvalidFieldRef`를 주면 Form이 그 입력에 포커스·보조공학 포커스를 옮기고 제출을 멈춘다 |
-| 저장 실패 표시 | 제품이 `formError`로 넘긴다 | `onSubmit`이 거절되면 Form이 오류 메시지(없으면 `fallbackErrorMessage`)를 표시한다 |
-| 제출 버튼 | `actions`에 `type="submit"` Button | `submitLabel`로 내장 버튼, `actions`로 교체 가능 |
+| 입력/단계 포커스 | DOM 입력·제목 ref | Native 입력 ref와 접근성 포커스 |
+| 결과 알림 | role=status | Android live region + iOS 접근성 알림 |
+| 이탈 확인 | 공개 Sheet의 dismiss/focus 계약 | 공개 Sheet의 dismiss/키보드/복귀 계약 |
+
+입력 오류는 입력 ref로 복귀한다. 설정 Sheet를 취소하면 실제 이탈 버튼, 변경을 버려 버튼이 사라지면 유지되는 단계 제목으로 복귀한다. Web은 안정적인 단계 제목/입력 ref에 포커스를 옮기고 `role="status"`로 결과를 알린다. Native는 공개 입력 ref와 단계 제목의 접근성 포커스·알림을 연결하며, unmount 때 예약된 포커스 이동을 취소한다. Sheet의 포커스·키보드·dismiss 정책은 기존 계약에 맡긴다. 제품은 validation 결과, 저장 API, 라우터 이탈 이벤트와 확인 Sheet의 연결, i18n 키를 제공한다.
+
+메모리 초안은 이 예제의 mounted 화면 안에서만 유지된다. 새로고침·프로세스 종료·다른 기기 복구와 서버 중복 처리 방지는 제품 저장소와 API 계약이 있어야 한다. `session.reset`은 서버 요청 취소가 아니다.
 
 ## 함정
 

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

@@ -3,20 +3,20 @@
 - 단계: 구성
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
+- 적용: 구성 API 지침 참조
 - 검토일: 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) |
+| TextField · createActionSession | 저장값과 편집 초안을 비교해 이탈 확인 | [공개 계약](../components/form.md) |
 | Button | 명시 행동·재시도 | [Button](../components/button.md) |
 
 ## 배치
@@ -28,8 +28,8 @@
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
-| 바깥 틀 | Form 또는 포함 Surface | 부모 화면의 해당 슬롯 | [배치](../components/form.md#배치)에 따른다 |
-| 내용 | Form 내부 슬롯 | 입력 → 저장·되돌리기 → 이탈 확인 | spacing 토큰과 포함 컴포넌트 recipe |
+| 바깥 틀 | 부모 화면 또는 포함 Surface | 부모 화면의 해당 슬롯 | [배치](../components/form.md#배치)에 따른다 |
+| 내용 | 부모 화면의 입력·요약 슬롯 | 입력 → 저장·되돌리기 → 이탈 확인 | spacing 토큰과 포함 컴포넌트 recipe |
 | 행동 | Button 또는 공개 콜백 | 내용과 가까운 명시 진입점 | 주 행동 하나, 보조 행동과 구분 |
 
 ## 흐름과 상태
@@ -46,60 +46,70 @@
 
 ## 코드 골격
 
-```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>
-```
+<!-- usage-example: Web ../../../../../showcase/web/src/patterns/reference-flow-previews.tsx -->
+<!-- usage-example: Native ../../../../../showcase/native/src/reference-flow-previews.tsx -->
+
+이 이름의 독립 공개 컴포넌트는 없다. 아래는 공개 `createActionSession`과 입력·Steps·Sheet를 조합하는 예제다. Storybook 예제 파일을 제품에서 import하지 않는다.
+
+- [Web 실행 예제](../../../../../showcase/web/src/patterns/reference-flow-previews.tsx)의 `Editor(kind="settings")`
+- [Native 실행 예제](../../../../../showcase/native/src/reference-flow-previews.tsx)의 `Editor(kind="settings")`
+- [공통 검증·초안 비교](../../../../../showcase/shared/reference-flows.ts)의 `draftError`, `sameDraft`는 예제 데이터 규칙이며 제품 규칙으로 교체한다.
+
+저장값 session.value와 편집 draft를 비교한다. dirty일 때만 저장·되돌리기를 켜고, 이탈은 확인 Sheet를 연다. 계속 수정은 Sheet만 닫고, 버리기는 마지막 저장값으로 draft를 복원한다.
 
 ```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>
+// Web — Native도 같은 상태 골격을 사용한다. JSX/문구/영속 저장은 각 제품의 기존 화면 슬롯에 연결한다.
+import { useState, useSyncExternalStore } from "react";
+import { createActionSession } from "@hjmds/design-contracts/action-session";
+
+const [session] = useState(() => createActionSession(initialValue));
+const saved = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+const [draft, setDraft] = useState(initialValue);
+const [stage, setStage] = useState(1);
+const [paused, setPaused] = useState(false);
+const busy = saved.status === "pending";
+const dirty = !sameDraft(draft, saved.value);
+
+function review() {
+  if (busy || draftError(draft)) return; // 오류 문구를 입력에 연결하고 첫 오류 입력으로 이동
+  setStage(2);
+}
+async function save() {
+  if (draftError(draft)) return;
+  const submitted = { ...draft };
+  // pending 중 재호출은 계약이 차단한다. 실패하면 saved.value와 draft를 보존한다.
+  const result = await session.run(() => saveToServer(submitted));
+  if (result.status === "success") setDraft(result.value);
+}
+function discard() {
+  if (session.getSnapshot().status === "pending") return;
+  setDraft(saved.value);
+  session.reset(saved.value);
+  setPaused(true);
+}
 ```
 
-제품 데이터·콜백은 주입한다. 위 공개 API 지침에 Web·Native 차이를 유지한다.
+| 표시/행동 | 연결 |
+| --- | --- |
+| 진행 단계 | `Steps.descriptor.currentStepId`를 `stage`에서 도출, 저장 실패 시 `currentStepStatus="error"` |
+| 편집 | `TextField`/선택 컨트롤은 draft를 편집. pending 동안 disabled이며 이미 큐에 든 입력·이탈·되돌리기 콜백도 최신 session 상태로 차단. 변경 시 오래된 실패 표시를 해제 |
+| 검토 | 같은 draft의 요약과 수정 버튼. 요약에서 값을 따로 보관하지 않음 |
+| 저장 | `Button.loading=busy`, 성공 결과는 서버 응답에서, 실패는 Notice와 같은 저장 버튼 재시도 |
+| 되돌리기 | dirty이며 pending이 아닐 때 저장값 복원. 서버 요청 취소로 설명하지 않음 |
+| 중단/이탈 | first/review는 메모리 draft·stage를 유지해 이어하기. settings는 dirty이면 확인 Sheet |
+| 확정 이후 | 결과 확인과 새 편집 진입을 구분. 새 편집은 마지막 확정값으로 시작 |
 
 ## 플랫폼 차이
 
 | 항목 | Web | Native |
 | --- | --- | --- |
-| 첫 오류 포커스 | 제품이 `onSubmit`에서 해당 입력 `ref.focus()` | `firstInvalidFieldRef`를 주면 Form이 그 입력에 포커스·보조공학 포커스를 옮기고 제출을 멈춘다 |
-| 저장 실패 표시 | 제품이 `formError`로 넘긴다 | `onSubmit`이 거절되면 Form이 오류 메시지(없으면 `fallbackErrorMessage`)를 표시한다 |
-| 제출 버튼 | `actions`에 `type="submit"` Button | `submitLabel`로 내장 버튼, `actions`로 교체 가능 |
+| 입력/단계 포커스 | DOM 입력·제목 ref | Native 입력 ref와 접근성 포커스 |
+| 결과 알림 | role=status | Android live region + iOS 접근성 알림 |
+| 이탈 확인 | 공개 Sheet의 dismiss/focus 계약 | 공개 Sheet의 dismiss/키보드/복귀 계약 |
+
+입력 오류는 입력 ref로 복귀한다. 설정 Sheet를 취소하면 실제 이탈 버튼, 변경을 버려 버튼이 사라지면 유지되는 단계 제목으로 복귀한다. Web은 안정적인 단계 제목/입력 ref에 포커스를 옮기고 `role="status"`로 결과를 알린다. Native는 공개 입력 ref와 단계 제목의 접근성 포커스·알림을 연결하며, unmount 때 예약된 포커스 이동을 취소한다. Sheet의 포커스·키보드·dismiss 정책은 기존 계약에 맡긴다. 제품은 validation 결과, 저장 API, 라우터 이탈 이벤트와 확인 Sheet의 연결, i18n 키를 제공한다.
+
+메모리 초안은 이 예제의 mounted 화면 안에서만 유지된다. 새로고침·프로세스 종료·다른 기기 복구와 서버 중복 처리 방지는 제품 저장소와 API 계약이 있어야 한다. `session.reset`은 서버 요청 취소가 아니다.
 
 ## 함정
 

package/docs/usage/compositions/selection-scope.md

@@ -24,11 +24,11 @@
 | --- | --- | --- |
 | `Heading level="level3" semanticLevel={2}` | 질문형 제목 `t("share.scopeQuestion")` | [Heading](../components/heading.md) |
 | `Text` | 묶음 설명: 대표 1개 포함 전체 N개 | [Text](../components/text.md) |
-| `Button selected`(secondary) × 2 | 범위 선택: "대표만 · 1개" / "묶음 전체 · N개". 라벨에 개수를 넣는다 | [Button](../components/button.md) |
+| `SegmentedControl` | 범위 선택: "대표만 · 1개" / "묶음 전체 · N개". 라벨에 개수를 넣는다 | [SegmentedControl](../components/segmented-control.md) |
 | `Text` | 선택 범위 요약(범위 이름 + 개수) | [Text](../components/text.md) |
 | `Button`(primary) | 적용. 라벨에 개수를 넣는다 `t("share.apply", { count })`. 진행 중은 `loading` | [Button](../components/button.md) |
 | `Text` 상태 | 적용 결과·안내·실패 | [Text](../components/text.md) |
-| `Container`·`Stack` | 바깥 틀, 바깥 `gap="md"`, 범위 버튼 묶음 `gap="sm"` | [Container](../components/container.md), [Stack](../components/stack.md) |
+| `Container`·`Stack` | 바깥 틀, 바깥 `gap="md"`, 선택지 내부는 SegmentedControl recipe | [Container](../components/container.md), [Stack](../components/stack.md) |
 
 ## 배치
 
@@ -53,14 +53,14 @@
 | --- | --- | --- | --- |
 | 바깥 틀 | Web: `Container size="reading"` → `Stack gap="md"`. Native: `ScrollView` → `Container` → `Stack gap="md"` | 화면 본문 스크롤. 안전 영역은 화면 host(SafeArea·navigation header)가 준다. 입력이 없어 키보드 처리는 없다. 적용 버튼을 하단에 고정하면 [BottomCTA](../components/bottom-cta.md)가 하단 안전 영역을 맡는다 | Native `ScrollView` 위아래 `spacing.md` 16, 좌우는 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 최대 폭 `layout.readingMaxWidth` 720 |
 | 질문·설명 | `Heading` + `Text` | 맨 위 | 사이 `spacing.md` 16 |
-| 범위 선택 | `Button selected` × 2 | 설명 아래, 세로 묶음 | 각 `medium` 44(`control.buttonHeight`), 서로 `spacing.sm` 12 |
+| 범위 선택 | `SegmentedControl` 단일 선택 | 설명 아래, 세로 묶음 | 각 `medium` 44(`control.buttonHeight`), 서로 `spacing.sm` 12 |
 | 범위 요약 | `Text` | 범위 선택 아래 | `spacing.md` 16 |
 | 주 행동 | `Button` 적용 | 요약 아래 | `medium` 44, `spacing.md` 16 |
 | 결과 | `Text` 상태 | 맨 아래 | `spacing.md` 16 |
 
-- 범위 버튼은 서로 가깝게(`spacing.sm` 12), 다른 덩어리와는 `spacing.md` 16으로 띄워 한 묶음으로 읽히게 한다.
+- 범위는 이름 있는 하나의 선택 그룹이다. 다른 덩어리와 `spacing.md` 16으로 띄우고 내부 간격은 SegmentedControl recipe를 따른다.
 - 순서는 좁은 범위(대표) → 넓은 범위(전체)다. 기본 선택은 스토리에서 대표 항목이지만 제품이 정한다.
-- 범위 버튼은 `selected` 처리로 칠해져 primary로 세지 않는다. 화면의 primary는 적용 하나다([Button](../components/button.md) "한 화면 primary 하나"의 예외).
+- 범위 선택은 SegmentedControl의 선택 의미와 외형을 사용한다. 화면의 primary 행동은 적용 하나다.
 - 적용 버튼이 화면 하단 고정이면 [BottomCTA](../components/bottom-cta.md)에 두고 라벨의 개수는 유지한다.
 
 근거: `src/component-recipes.ts`(`stackRecipe.gaps` = `spacing`, `buttonRecipe.states.selected`), `src/foundations.ts`(`control`·`layout`)
@@ -68,15 +68,15 @@
 ## 흐름과 상태
 
 1. 화면은 묶음 설명과 기본 범위(대표)를 보여 준다.
-2. 사용자가 범위 버튼을 누르면 `selected`가 옮겨 가고, 요약과 적용 버튼 라벨의 개수가 바뀐다. 이전 결과 문구는 지운다.
-3. 적용을 누르면 그 범위의 항목 ID로 제품 작업(공유 대상 확정 등)을 실행한다. 끝날 때까지 적용 버튼은 `loading`이다.
+2. 사용자가 범위를 고르면 `value`가 바뀌고, 요약과 적용 버튼 라벨의 개수가 바뀐다. 이전 결과 문구는 지운다.
+3. 적용을 누르면 그 범위의 항목 ID로 제품 작업(공유 대상 확정 등)을 실행한다. 끝날 때까지 적용 버튼은 `loading`이고 선택한 개수의 처리 중 상태를 표시한다. 비활성 렌더 전에 도착한 선택 callback도 현재 세션이 pending이면 거부한다.
 4. 결과 문구로 몇 개에 적용했는지 알린다. 실패하면 범위는 그대로 두고 실패 문구를 알린다. 적용을 다시 누르면 같은 범위로 재요청한다.
 
 | 상태 | 모습 | 포커스·알림 |
 | --- | --- | --- |
-| 기본 | 기본 범위 버튼 `selected`, 요약에 개수, 안내 문구 `share.chooseScope` | `selected`는 Web `aria-pressed`·Native 접근성 state로 알림 |
+| 기본 | 기본 범위를 `value`로 지정, 요약에 개수, 안내 문구 `share.chooseScope` | 그룹 이름과 선택 항목을 Web radio/Native radio 접근성 의미로 알림 |
 | 범위 변경 | 요약·적용 라벨의 개수 갱신, 결과 문구는 안내로 돌아감 | 같음 |
-| 진행 중 | 적용 버튼 `loading`(누름 막힘·스피너), 범위 버튼 `disabled` | 포커스는 적용 버튼 유지 |
+| 진행 중 | 적용 버튼 `loading`(누름 막힘·스피너), 선택 그룹 `disabled`, 제출 개수의 처리 중 문구 | 포커스는 적용 버튼 유지 |
 | 성공 | 결과 문구 `t("share.applied", { count })` | 결과 알림, 포커스는 적용 버튼 유지 |
 | 실패 | 네트워크·서버 실패: 범위 유지, 결과 문구 `share.applyFailed`, 적용 버튼 다시 활성. 재요청도 실패하면 같은 문구를 다시 알린다 | 결과 알림(Web `role="status"`, Native live region + iOS 알림) |
 
@@ -87,46 +87,49 @@
 
 ```tsx
 // Web
-import { useState } from "react";
+import { useState, useSyncExternalStore } from "react";
+import { createActionSession } from "@hjmds/design-contracts/action-session";
 import { Button } from "@hjmds/react/actions";
+import { SegmentedControl } from "@hjmds/react/selection";
 import { Heading } from "@hjmds/react/heading";
 import { Container, Stack, Text } from "@hjmds/react/layout";
 
 const scopeKey = { cover: "share.scope.cover", group: "share.scope.group" } as const;
-const resultKey = { idle: "share.chooseScope", applied: "share.applied", failed: "share.applyFailed" } as const;
+const resultKey = { idle: "share.chooseScope", applying: "share.applying", applied: "share.applied", failed: "share.applyFailed" } as const;
 
 const [scope, setScope] = useState<"cover" | "group">("cover");
-const [result, setResult] = useState<"idle" | "applying" | "applied" | "failed">("idle");
+const [session] = useState(() => createActionSession<"cover" | "group" | null>(null));
+const snapshot = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+const result = snapshot.status === "pending" ? "applying" : snapshot.status === "error" ? "failed" : snapshot.status === "success" ? "applied" : "idle";
 const count = scope === "cover" ? 1 : group.items.length;
-const choose = (next: "cover" | "group") => { setScope(next); setResult("idle"); };
+// The owner also guards queued callbacks that arrive before disabled renders.
+const choose = (next: "cover" | "group") => { if (session.getSnapshot().status === "pending") return; setScope(next); session.reset(null); };
 const apply = async () => {
-  setResult("applying");
-  try { await onApply(scope); setResult("applied"); } catch { setResult("failed"); }
+  const submitted = scope;
+  await session.run(async () => { await onApply(submitted); return submitted; });
 };
 
 <Container size="reading">
   <Stack gap="md">
     <Heading level="level3" semanticLevel={2}>{t("share.scopeQuestion")}</Heading>
     <Text as="p">{t("share.groupSummary", { total: group.items.length })}</Text>
-    <Stack gap="sm">
-      <Button tone="secondary" selected={scope === "cover"} disabled={result === "applying"} onClick={() => choose("cover")}>
-        {t("share.coverOnly", { count: 1 })}
-      </Button>
-      <Button tone="secondary" selected={scope === "group"} disabled={result === "applying"} onClick={() => choose("group")}>
-        {t("share.wholeGroup", { count: group.items.length })}
-      </Button>
-    </Stack>
+    <SegmentedControl label={t("share.scopeQuestion")} value={scope} onValueChange={value => { if (value === "cover" || value === "group") choose(value); }}
+      presentation="pills" disabled={result === "applying"}
+      items={[{ value: "cover", label: t("share.coverOnly", { count: 1 }) },
+        { value: "group", label: t("share.wholeGroup", { count: group.items.length }) }]} />
     <Text as="p">{t("share.scopeSummary", { scope: t(scopeKey[scope]), count })}</Text>
     <Button loading={result === "applying"} onClick={() => void apply()}>{t("share.apply", { count })}</Button>
-    <Text as="p" role="status">{t(resultKey[result === "applying" ? "idle" : result], { count })}</Text>
+    <Text as="p" role="status">{t(resultKey[result], { count })}</Text>
   </Stack>
 </Container>
 ```
 
 ```tsx
 // Native
+import { StatusText } from "@hjmds/react-native/status-text";
 import { ScrollView, useWindowDimensions } from "react-native";
 import { Button } from "@hjmds/react-native/actions";
+import { SegmentedControl } from "@hjmds/react-native/inputs";
 import { Heading } from "@hjmds/react-native/heading";
 import { Container, Stack, Text } from "@hjmds/react-native/primitives";
 import { useHjmNativeTheme } from "@hjmds/react-native/provider";
@@ -141,23 +144,19 @@ const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "
     <Stack gap="md">
       <Heading level="level3" semanticLevel={2}>{t("share.scopeQuestion")}</Heading>
       <Text>{t("share.groupSummary", { total: group.items.length })}</Text>
-      <Stack gap="sm">
-        <Button tone="secondary" selected={scope === "cover"} disabled={result === "applying"} onPress={() => choose("cover")}>
-          {t("share.coverOnly", { count: 1 })}
-        </Button>
-        <Button tone="secondary" selected={scope === "group"} disabled={result === "applying"} onPress={() => choose("group")}>
-          {t("share.wholeGroup", { count: group.items.length })}
-        </Button>
-      </Stack>
+      <SegmentedControl label={t("share.scopeQuestion")} value={scope} onValueChange={value => { if (value === "cover" || value === "group") choose(value); }}
+      presentation="pills" disabled={result === "applying"}
+      items={[{ value: "cover", label: t("share.coverOnly", { count: 1 }) },
+        { value: "group", label: t("share.wholeGroup", { count: group.items.length }) }]} />
       <Text>{t("share.scopeSummary", { scope: t(scopeKey[scope]), count })}</Text>
       <Button loading={result === "applying"} onPress={() => void apply()}>{t("share.apply", { count })}</Button>
-      <StatusText>{t(resultKey[result === "applying" ? "idle" : result], { count })}</StatusText>
+      <StatusText>{t(resultKey[result], { count })}</StatusText>
     </Stack>
   </Container>
 </ScrollView>
 ```
 
-`group`·`onApply`는 제품 소유다. `StatusText`는 [저장과 재시도의 공통 절](action-recovery-save.md#공통-세션과-상태-알림)의 helper(Android live region + iOS 알림)다.
+`group`·`onApply`는 제품 소유다. `StatusText`는 [저장과 재시도의 공통 절](action-recovery-save.md#공통-세션과-상태-알림)에서 사용하는 공개 Text companion이다.
 
 ## 플랫폼 차이
 
@@ -165,10 +164,24 @@ const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "
 | --- | --- | --- |
 | 바깥 틀 | 문서 스크롤 + `Container` | `ScrollView`(위아래 `spacing.md`) + `Container` |
 | 이벤트 | `onClick` | `onPress` |
-| `selected` 알림 | `aria-pressed` | 접근성 state |
+| 단일 선택 의미 | 이름 있는 radiogroup, radio checked | 이름 있는 그룹과 radio checked |
 | 상태 알림 | `role="status"` | live region(Android) + iOS 알림 호출(`StatusText`) |
 
 ## 함정
 
 - 구획 제목은 Heading으로 표시한다. 이전 Text heading 예제는 2026-10-06 제목 의미 구조를 맞추면서 수정했다.
 - 스토리의 "다음 적용 실패시키기"(ghost)와 350ms 지연은 실패·진행 중을 확인하는 데모 전용이다. 제품에 넣지 않는다.
+
+## 단일 선택 계약
+
+2026-10-13 실행 예제는 대표/전체를 두 독립 토글 대신 `SegmentedControl presentation="pills"`로 묶었다. 둘 중 하나인 선택은 그룹 이름과 checked 의미를 전달한다. 위 골격과 같은 공개 선택 계약을 유지한다. 저장·실패·초안은 기존 세션을 유지한다.
+
+```tsx
+// Web: @hjmds/react/selection, Native: @hjmds/react-native/inputs
+<SegmentedControl label={t("share.scopeQuestion")} value={scope} onValueChange={value => { if (value === "cover" || value === "group") choose(value); }}
+  presentation="pills" disabled={result === "applying"}
+  items={[{ value: "cover", label: t("share.coverOnly", { count: 1 }) },
+    { value: "group", label: t("share.wholeGroup", { count: group.items.length }) }]} />
+```
+
+2026-10-13 실제 Story 검사에서 Native의 늦은 선택 callback이 pending 요청을 reset하는 경우를 재현했다. Web·Native 예제 모두 세션 snapshot으로 선택 변경과 실패 예약을 즉시 거부한다. 새 범위 선택은 이전 성공 문구를 지우고, 실패 후 재적용은 기존 선택 범위로 요청한다. 이 예제에는 별도 텍스트 초안이 없으며 선택값 자체가 적용 전 초안이다.