@hjmds/design-contracts 1.13.0 → 1.14.0

package/docs/usage/compositions/field-group.md

@@ -0,0 +1,104 @@
+# 관련 입력 묶음
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.14.0
+- 검토일: 2026-10-07
+- 근거: [입력 그룹 조사](../../../../../docs/plans/field-group-experiment.md), `src/field-group.ts`
+- 스토리북: `배포/구성/입력과 작성/관련 입력 묶음`
+
+승급: 2026-10-07 사용자 승인, [검토 결과](../../../../../docs/qa/2026-10-07-experiment-promotion-release.md). Storybook 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+주소·연락처처럼 여러 입력이 하나의 질문에 답할 때 쓴다. FieldGroup은 관련성·도움말·오류·잠금을
+소유하고 값·검증 시점·제출은 제품이 소유한다. Form 안에 여러 그룹을 둘 수 있다. 선택만 묶으면
+CheckboxGroup/RadioGroup, 날짜 조각이면 DateEntry를 먼저 사용한다. 공통 제출 세션은 Form의 몫이다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| FieldGroup | 그룹 이름·설명·오류와 입력 연결 | 이 문서 |
+| TextField 등 | renderField로 공급하는 개별 입력 | [Field](../components/field.md) |
+| Form | 제품 제출 경계 | [Form](../components/form.md) |
+
+## 배치
+
+```text
+그룹 이름
+그룹 설명(선택)
+그룹 오류(선택, 한 번)
+[입력 1]
+필드 설명 / 필드 오류
+[입력 2]
+필드 설명 / 필드 오류
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web fieldset / Native View | 기존 폼 안 | 테두리 없음, Web 최소 폭 0 |
+| 그룹 이름 | Web legend / Native Text label | 맨 위 | Web 아래 spacing.sm 12, Native 그룹 간격 spacing.sm 12 |
+| 입력 묶음 | renderField | descriptor.fields 순서 | 세로 간격 spacing.md 16 |
+| 개별 도움말 | FieldGroup | 해당 입력 바로 아래 | Native 간격 spacing.xs 8, 글자 크기는 Text 기본 |
+
+## 흐름과 상태
+
+1. descriptor에 label과 fields를 넣는다. 필드 id는 그룹 안에서 고유하며 재정렬에도 유지한다.
+2. description·error는 이미 현지화한 문구다. 빈 문자열은 허용하지 않는다. 표시할 오류가 없으면 생략한다.
+3. 그룹 error는 message와 fieldIds를 받는다. 영향을 받는 필드만 invalid가 되고, 빈 배열은 그룹 전용 오류다.
+4. renderField의 controlProps를 개별 입력에 전달한다. FieldGroup이 도움말·오류를 이미 그리므로 같은 내용을
+   TextField description/error에 다시 넣지 않는다. Web id·aria 연결을 덮어쓰지 않는다.
+5. 값 변경에는 guardChange로 감싼 callback을 전달한다. 그룹 잠금·개별 잠금·필드 제거·언마운트 후
+   남은 callback을 차단한다. 잠금 해제 시 원래 disabled인 필드는 계속 잠긴다. 제거가 commit된
+   필드를 같은 id로 다시 추가해도 이전 callback은 복구하지 않는다. 새 renderField의 guardChange를
+   사용한다. 2026-10-07 회귀에서 enabled id만 검사하면 이전 이벤트가 새 초안을 바꾸는 것을 확인했다.
+6. dynamic 필드 제거 시 해당 그룹 오류 대상도 함께 갱신한다. 사라진 id나 중복 오류 대상은 TypeError다.
+7. 제품이 값과 검증을 유지한다. 입력 순서·그룹 잠금 변경은 값을 초기화하지 않는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 그룹 설명과 독립 입력 | 자동 포커스 없음 |
+| 진행 중 | 제품 값 편집 | 일반 Tab·터치 이동 |
+| 실패 | 그룹 오류 한 번, 해당 입력 invalid, 개별 오류 보존 | Web 연결된 설명, Native hint에 그룹/개별 설명과 오류 |
+| 비활성 | 각 입력 disabled | guardChange가 늦은 값 변경도 차단 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { FieldGroup } from "@hjmds/react/field-group";
+import { TextField } from "@hjmds/react/forms";
+<FieldGroup descriptor={group} renderField={({ id, controlProps, guardChange }) =>
+  <TextField {...controlProps} value={values[id] ?? ""}
+    onValueChange={guardChange((value: string) => updateField(id, value))} />} />
+```
+
+```tsx
+// Native
+import { FieldGroup } from "@hjmds/react-native/field-group";
+import { TextField } from "@hjmds/react-native/inputs";
+<FieldGroup descriptor={group} renderField={({ id, controlProps, guardChange }) =>
+  <TextField {...controlProps} value={values[id] ?? ""}
+    onValueChange={guardChange((value: string) => updateField(id, value))} />} />
+```
+
+공통 descriptor/resolver/edit session은 `@hjmds/design-contracts/field-group`에 있다.
+사용자 정의 입력은 label·disabled·invalid·도움말을 자신의 실제 입력 host에 연결해야 한다.
+controlProps는 TextField에 바로 연결되는 형태이며 Checkbox/Select 등 다른 공개 API와 호환되는지
+확인 없이 그대로 펼치지 않는다. renderField의 반환값 안에 독립 제출 버튼을 넣지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 그룹 의미 | fieldset의 첫 legend | 개별 입력 accessibilityLabel에 그룹 이름 포함, 부모 accessible=false |
+| 필드 연결 | id·aria-invalid·aria-describedby | label·invalid·accessibilityLabel·accessibilityHint |
+| 그룹 오류 | role=alert | assertive live region, iOS 별도 announcement |
+| 화면 스크롤 | 제품 host | 제품 ScrollView·키보드 회피 host |
+
+## 함정
+
+- 실제 스크린리더·Native 기기·제품 팔레트 검증은 아직 남았다. 자동 검사 통과를 승격 근거로 단독 사용하지 않는다.
+- 국가·주소·연락처의 필드 순서와 autocomplete는 제품별로 정한다. 예제의 한국 주소 순서를 공통 규칙으로 복사하지 않는다.

package/docs/usage/compositions/illustrated-outcome.md

@@ -0,0 +1,91 @@
+# 그림과 시작 안내
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.14.0
+- 검토일: 2026-10-07
+- 근거: `showcase/web/src/patterns/illustrated-outcome-preview.tsx`, `showcase/native/src/illustrated-outcome-preview.tsx`
+- 스토리북: `배포/구성/피드백과 복구/그림과 시작 안내`
+
+승급: 2026-10-07 사용자 승인, [검토 결과](../../../../../docs/qa/2026-10-07-experiment-promotion-release.md). Storybook 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+빈 목록에서 시작을 안내하고 짧은 온보딩을 거쳐 결과를 보여 줄 때 쓴다. 3D 그림은 제품 자산이며
+공통 컴포넌트의 의미·초점·버튼을 대체하지 않는다. 별도 wrapper 없이 기존 공개 API를 사용한다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| EmptyState | 채울 수 있는 빈 목록과 첫 행동 | [빈 상태](../components/empty-state.md) |
+| OnboardingScreen | 단계·이전·다음·완료 배치 | [시작 안내](../screens/flow-onboarding.md) |
+| Result | 흐름이 끝난 결과와 다음 행동 | [결과](../components/result.md) |
+| TextField | 제품이 소유하는 입력 초안 | [텍스트 필드](../components/field.md) |
+
+## 배치
+
+```text
+[장식 그림]
+[제목 + 설명]
+[단계 본문: 그림 또는 입력]
+[다음 / 완료]
+[이전: 두 번째 단계부터]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 본문 전체 | gap lg=20px |
+| 빈 상태 그림 | EmptyState 제품 슬롯 | 제목 위 | 120×120, Asset xlarge와 같은 크기 |
+| 단계 본문 | OnboardingScreen | 제목과 하단 행동 사이 | 그림 120×120 또는 TextField |
+| 완료 | Result | 흐름 종료 자리 | 체크 32×32, 공통 56px 아이콘 영역 안 |
+| 버튼 | 각 공개 컴포넌트 | 화면의 기존 footer 또는 action 영역 | 기존 recipe 최소 터치 크기 유지 |
+
+## 흐름과 상태
+
+1. EmptyState 행동으로 시작 안내를 연다. 화면의 현재 단계는 제품이 제어한다.
+2. 다음→입력→이전→다음에서도 초안은 상위 제품 상태에 남긴다.
+3. 예제는 제목이 공백이면 완료를 비활성화한다. 실제 앱의 저장 결과는 서버 응답으로만 확정한다.
+4. 그림 로딩 실패는 그림만 제거한다. 설명·입력·버튼은 유지하며 오류를 성공으로 바꾸지 않는다.
+5. 완료 후 다시 시작해도 초안을 유지한다. 초안 삭제는 제품의 명시적인 정책이 있을 때만 한다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 빈 상태 제목·장식 그림·첫 행동 | 제목으로 의미를 전달하고 그림은 장식으로 숨김 |
+| 진행 중 | 단계 안내·입력·이전/다음 행동 | 초안을 유지하며 실제 저장 중에는 제품 pending 연결 |
+| 실패 | 그림 실패 시 본문·행동 유지 | 장식 실패를 저장 실패와 혼동하지 않음 |
+| 완료 | 결과 제목·입력 내용·다시 시작 | Result의 기본 status 의미 유지 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { EmptyState, Result } from "@hjmds/react/feedback";
+import { OnboardingScreen } from "@hjmds/react/screen-flows";
+<EmptyState title={title} description={description} icon={decorativeArtwork} action={startButton} />
+<Result status="success" title={completedTitle} icon={decorativeCheck} actions={actions} />
+```
+
+```tsx
+// Native
+import { EmptyState, Result } from "@hjmds/react-native/feedback";
+import { OnboardingScreen } from "@hjmds/react-native/screen-flows";
+<EmptyState title={title} description={description} illustration={decorativeArtwork} action={startButton} />
+<Result status="success" title={completedTitle} renderIcon={() => decorativeCheck} actions={actions} />
+```
+
+OnboardingScreen에는 `steps`, `index`, `onIndexChange`, `nextLabel`, `backLabel`, `complete`,
+`progressLabel`을 전달한다. 단계 구조·버튼 위치는 기존 화면 지침을 따른다. 제품 코드에서
+Showcase를 import하지 않는다. 그림 호스트는 Web img의 빈 alt, Native Image의 accessible=false로 장식임을 명시한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 파일 | 로컬 파일 URL | Metro 정적 require |
+| 그림 접근성 | 빈 alt | accessible=false |
+| 장식 슬롯 | EmptyState.icon / Result.icon | EmptyState.illustration / Result.renderIcon |
+| 실패 | 그림만 숨김 | 그림만 숨김 |
+
+실제 기기의 자산 디코딩·큰 글자·접근성 검증은 타입 검사와 별도다.

package/docs/usage/compositions/live-list.md

@@ -0,0 +1,104 @@
+# 추가해도 유지되는 목록
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.14.0
+- 검토일: 2026-10-07
+- 근거: `showcase/web/src/patterns/live-list-preview.tsx`, `showcase/native/src/live-list-preview.tsx`
+- 스토리북: `배포/구성/정보 표시/추가해도 유지되는 목록`
+
+승급: 2026-10-07 사용자 승인, [검토 결과](../../../../../docs/qa/2026-10-07-experiment-promotion-release.md). Storybook 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+입력 중인 목록에 새 데이터가 추가되거나 순서가 바뀌어도 기존 초안과 항목의 정체성을 유지할 때 쓴다.
+Magic UI Animated List의 소개 페이지 순차 노출에서 새 항목의 등장 표현만 흡수한다. 이미 도착한
+데이터를 타이머로 늦추지 않고, 실제 알림 수신과 데모 재생을 혼동하지 않는다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| List · ListRow | stable key 항목의 목록 의미·제목·구분선 | [목록](../components/list.md), [행](../components/list-row.md) |
+| ContentTransition | 새 항목 등장과 바깥 높이 전환 | [내용 전환](../components/content-transition.md) |
+| TextField | 제품이 항목 id별로 보존하는 메모 | [필드](../components/field.md) |
+| Button · Text | 명시적 데이터 변경과 변경 결과 | [버튼](../components/button.md), [글자](../components/text.md) |
+
+## 배치
+
+```text
+[안내]
+[기록 추가] [3개 함께 추가]
+[순서 뒤집기] [첫 기록 삭제]
+[움직임 멈추기]
+[변경 결과]
+┌ 기록 목록 ────────────┐
+│ 제목·설명              │
+│ 메모 입력              │
+├───────────────────────┤
+│ 다음 기록·메모         │
+└───────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 위에서 아래 | gap lg=20px |
+| 변경 행동 | inline Stack · Button | 목록 위, 좁으면 감김 | 기본 Stack/Button recipe |
+| 데이터 | List | 변경 결과 아래 | separator full, 공통 ListRow/TextField 크기 |
+| 등장 | ContentTransition | 각 stable id 항목 | rise=12px, motion.normal, easing.enter |
+| 높이 | ContentTransition animateHeight | 목록 바깥 | 같은 stateKey를 유지하며 실제 측정 높이만 전환 |
+
+## 흐름과 상태
+
+1. 초기 데이터는 바로 표시하고 최초 등장 모션은 끈다.
+2. 추가된 항목은 고유 id를 부여해 즉시 배열에 반영한다. 해당 항목만 enterOnMount를 켠다.
+3. 기존 id의 React key와 stateKey를 유지한다. 전체 목록 stateKey를 항목 개수로 바꾸지 않는다.
+4. 순서 변경은 데이터 배열 순서만 바꾸며 초안은 id에 연결한다. 순서 변경 자체의 이동 애니메이션은 제공하지 않는다.
+5. 삭제는 즉시 반영한다. 삭제된 입력·버튼을 담은 퇴장 사본을 남기지 않는다.
+6. 움직임 멈추기는 데이터 처리를 멈추지 않는다. 다시 켜도 기존 항목은 재생하지 않는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 기존 목록과 입력 | 초기 데이터 즉시 표시 |
+| 진행 중 | 새 행만 짧게 등장 | 기존 입력 노드와 초안 유지 |
+| 실패 | 서버 실패가 있는 제품은 기존 목록·초안을 보존하고 오류를 별도 표시 | 이 로컬 실험에는 네트워크 요청 없음 |
+| 삭제 | 해당 행 즉시 제거 | 삭제 행동은 목록 밖에 두어 초점 유실 방지 |
+| 비어 있음 | 기록 없음과 추가 안내 | 추가 버튼 유지 |
+| 모션 감소·정지 | 같은 데이터, 공간 전환 없음 | 의미·입력 순서 동일 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { ContentTransition } from "@hjmds/react/content-transition";
+<ContentTransition stateKey="records" animateHeight motion={paused ? 'none' : 'system'}>
+  <List label={listLabel}>
+    {items.map(item => <ContentTransition key={item.id} stateKey={item.id}
+      enterOnMount={item.justAdded} preset="rise" motion={paused ? 'none' : 'system'}>
+      <RecordEditor item={item} onChange={changeById} />
+    </ContentTransition>)}
+  </List>
+</ContentTransition>
+```
+
+```tsx
+// Native
+import { ContentTransition } from "@hjmds/react-native/content-transition";
+
+<ContentTransition stateKey={item.id} enterOnMount={item.justAdded} preset="rise">
+  <RecordEditor item={item} onChange={changeById} />
+</ContentTransition>
+```
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 등장 | 기존 framer-motion optional peer | 기존 RN Animated native driver |
+| 높이 | ResizeObserver + WAAPI | onLayout + JS driver |
+| 변경 알림 | status | accessibilityLiveRegion polite |
+| 접근성 | 기존 입력 초점·list 의미 | 기존 입력과 Native list 의미 |
+
+데이터·중복 제거·정렬·서버 확정은 제품 소유다. 긴 목록은 VirtualList 선택을 먼저 검토하고
+재활용 mount를 새 데이터로 오인해 enterOnMount를 켜지 않는다. 큰 글자·제품 팔레트·성능은 승격 전 검증한다.

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

@@ -165,5 +165,5 @@ const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "
 - KeyboardDock은 window 기준 좌표를 쓴다. Storybook 캔버스처럼 아래에 다른 영역이 남는 host에서는 위치가 어긋나 스토리가 전체 화면 `Modal`로 띄운다. 제품도 앱 크기 host에서 쓴다.
 - NativeContextMenu 패치(Zeego 3.0.6 관련)는 HJM 설치로 적용되지 않는다. `@hjmds/react-native/docs/patches/`를 제품에 복사해 등록한다.
 - 필요한 optional peer(`react-native-zoom-toolkit` 5.1.1, `react-native-keyboard-controller` 1.22.5, `@gorhom/bottom-sheet` 5.2.14, `zeego` 3.0.6 등)가 없으면 기기 Metro 번들이 실패한다.
-- 현재 `ImageViewer`는 로딩 문구만 live region이고 실패 문구(`errorLabel`)는 알리지 않는다. 실패를 낭독해야 하면 제품이 따로 알린다(renderer 수정 후보).
+- `ImageViewer` 실패는 Android assertive live region과 iOS announceForAccessibility로 알린다. 제품이 같은 오류를 다시 낭독하지 않는다. 제품 이미지 host와 상태 이벤트 연결은 [Image 사용 지침](../components/image.md)의 Native ImageViewer 절을 따른다.
 - 2026-10-06 예제 검수에서 머리·본문·하단의 좌우 여백을 Container compact로 맞추고 본문 간격은 Stack md로 옮겼다. 안전 영역·키보드 좌표는 바깥 host가 유지한다. 메뉴 결과는 상태 문구와 iOS/Android 알림을 함께 갱신한다.

package/docs/usage/compositions/origin-dialog.md

@@ -0,0 +1,108 @@
+# 버튼에서 이어지는 편집
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.14.0
+- 검토일: 2026-10-07
+- 근거: `showcase/web/src/patterns/origin-dialog-preview.tsx`, `showcase/native/src/origin-dialog-preview.tsx`
+- 스토리북: `배포/구성/입력과 작성/버튼에서 이어지는 편집`
+
+승급: 2026-10-07 사용자 승인, [검토 결과](../../../../../docs/qa/2026-10-07-experiment-promotion-release.md). Storybook 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+현재 화면의 항목을 짧게 편집하고 돌아올 때 출발 위치를 시각적으로 연결한다. 별도 상태
+엔진 없이 Dialog의 선택적 motionOrigin과 제품 소유 초안을 사용한다. 원본의 닫기 후
+초점·초안 손실을 그대로 가져오지 않기 위한 구성이다. 긴 편집은 전용 화면을 사용한다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| Button | 측정할 열기 버튼과 저장 | [버튼](../components/button.md) |
+| Popover | Web에서 페이지를 계속 볼 수 있는 비모달 편집 변형 | [팝오버](../components/popover.md) |
+| Dialog | 기존 모달 상태·닫기·초점 복귀와 선택적인 공간 전환 | [대화상자](../components/dialog.md) |
+| TextField | 제품 상태에 보존하는 초안 | [필드](../components/field.md) |
+| Text | 확정한 결과 표시 | [텍스트](../components/text.md) |
+
+## 배치
+
+```text
+[안내]
+[메모 편집] ──→ [여행 메모             닫기]
+[저장 결과]       [메모 입력]
+                 [저장]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 원래 화면 | gap lg=20px |
+| 진행 중 | Dialog | 기본 overlay 중앙 | 기본 Dialog recipe |
+| 입력 | TextField | Dialog 본문 | 공통 Field 크기·간격 |
+| 확정 | Button | Web footer / Native primaryAction | 공통 Dialog 행동 영역 |
+
+## 흐름과 상태
+
+1. 열기 직전에 트리거를 실제 viewport/window 좌표로 측정한다. 측정 불가 시 일반 Dialog를 연다.
+2. 제품이 open·draft·saved를 각각 소유한다. 저장 전 닫기는 draft를 지우지 않는다.
+3. 저장 시 draft를 결과로 확정하고 닫는다. 실패 체험을 예약하면 첫 저장만 실패하고
+   오류·초안을 유지한다. 다시 저장은 성공한다. 실제 서버가 있으면 busy와 확정 응답을 연결한다.
+4. 닫기 전환이 끝난 뒤 트리거로 초점을 돌린다. 빠른 재열기는 이전 종료 결과를 무시한다.
+5. 모션 감소·잘못된 측정에서는 공간 전환을 생략한다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 열기 버튼과 마지막 저장 결과 | draft 유지 |
+| 진행 중 | 제목·닫기·입력·저장 | 제품 상태로 갱신 |
+| 결과 | 결과 갱신 후 닫기 | 트리거로 복귀 |
+| 실패 | 오류 설명·입력·다시 저장 | 오류 알림, 초안 유지 |
+| 측정 없음 | 일반 Dialog | 같음 |
+
+## 코드 골격
+
+```tsx
+// Web: origin은 trigger.getBoundingClientRect()의 측정값
+<Dialog open={open} onOpenChange={setOpen} title={title} closeLabel={closeLabel}
+  motionOrigin={origin} returnFocusRef={triggerRef} footer={saveButton}>
+  <TextField label={label} value={draft} onValueChange={setDraft} />
+</Dialog>
+```
+
+```tsx
+// Native: origin은 trigger.measureInWindow 콜백의 측정값
+<Dialog open={open} onOpenChange={setOpen} title={title} closeLabel={closeLabel}
+  motionOrigin={origin} returnFocusRef={triggerRef} primaryAction={saveAction}>
+  <TextField label={label} value={draft} onValueChange={setDraft} />
+</Dialog>
+```
+
+문구·초안·저장 로직·트리거 측정은 제품 소유다. Showcase를 앱에서 import하지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 원점 | getBoundingClientRect | measureInWindow |
+| 전환 | WAAPI, 종료까지 한 subtree 유지 | 실제 modal 측정 + 기존 Animated progress |
+| 모션 감소 | 공간 전환 없음 | 공간 전환 없음, 기존 opacity |
+| 닫기 | Escape·바깥·닫기 | Back·바깥·닫기 |
+
+키보드·회전·스크롤에 의한 목적지 변화, 실제 기기와 제품 테마 비교는 승격 전 검증한다.
+
+
+### Web의 페이지 안에서 편집 변형
+
+`Contextual`·`ContextualDark`·`ContextualLargeText`는 기존 Popover의 선택적인 `motionOrigin`을
+사용한다. 기본 360px 표면이 버튼 아래 8px 간격으로 열리고 viewport 충돌에 따라 배치가 바뀐다.
+본문은 Stack gap md=16px 안에 오류 → TextField → 저장 순서다. Native는 모달 편집 변형을 쓴다.
+
+```tsx
+<Popover title={title} closeLabel={closeLabel} motionOrigin={origin}
+  trigger={<Button ref={triggerRef} onClick={() => setOrigin(triggerRef.current?.getBoundingClientRect())}>{openLabel}</Button>}>
+  {({ close }) => <Editor draft={draft} onDraftChange={setDraft} onSave={() => save(draft).then(close)} />}
+</Popover>
+```
+
+비모달에서는 Escape/닫기 직후 기존 규칙대로 초점을 복귀한다. 바깥 클릭이나 Tab으로 이동한
+초점은 되가져오지 않는다. 저장 실패는 초안·열림을 유지하고, 닫았다 다시 열어도 제품 draft는 남는다.

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

@@ -0,0 +1,73 @@
+# 선택 배경 이동
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.14.0
+- 검토일: 2026-10-07
+- 근거: 공개 API를 사용하는 `showcase/*/reference-adoption-previews.tsx`
+- 스토리북: `배포/구성/직접 조작과 모션/선택 배경 이동`
+
+승급: 2026-10-07 사용자 승인, [검토 결과](../../../../../docs/qa/2026-10-07-experiment-promotion-release.md). Storybook 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+짧은 단일 선택의 현재 항목을 이어지는 배경으로 보여 줄 때 쓴다. 선택 값·키보드·초점은 기존 SegmentedControl이 소유한다. 별도 신규 wrapper API가 아니라 아래 공개 컴포넌트의 조합 규격이다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| SegmentedControl · Text · TextField | 입력·표현·행동의 역할 분리 | [입력/동작](../components/segmented-control.md), [상태/전환](../components/content-transition.md) |
+
+## 배치
+
+```text
+[제목 또는 현재 입력]
+[상태/내용 영역]
+[관련 행동과 결과]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 화면의 본문 흐름 | gap lg=20px, 전체 폭 |
+| 선택 | SegmentedControl 2개 | 제목 아래, 연결형 다음 필터형 | 기본 44px 터치 영역, 실제 글자에 따른 높이 |
+| 결과·메모 | Text · TextField | 선택 컨트롤 아래 | 선택 변경 시 필드 재생성 없음 |
+| Native 화면 host | ScreenLayout · KeyboardAvoiding | 본문 스크롤과 바깥 키보드 여백 | flex 1, 끝 여백 spacing.md=16 |
+
+2026-10-07 iOS 2배 글자에서 Stack만 사용한 예제의 메모가 키보드 뒤에 가려졌다.
+글자나 선택 항목을 줄이지 않고 위 화면 host를 연결해 입력·선택을 스크롤로 오가게 한다.
+선택 배경 이동은 입력 초점·스크롤을 소유하지 않으므로 제품 화면도 이 경계를 연결해야 한다.
+
+## 흐름과 상태
+
+1. 현재 선택 측정→사용자가 선택→배경만 이동. 메모 필드는 유지한다.
+2. 서버 응답·파일 권한·문구·브랜드는 제품이 전달한다. Showcase의 예제 응답과 고정 데이터를 가져오지 않는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 입력과 사용 가능한 행동 | 조작 이름은 제품 언어 |
+| 진행 중 | 실제 작업 상태에 맞는 loading 또는 열린 도구 | 중복 요청 차단, 입력 유지 |
+| 실패 | 문구와 가능한 재시도 | 원래 입력/파일 유지, 결과 안내 |
+
+## 코드 골격
+
+```tsx
+// Web
+<SegmentedControl label={t("period")} items={items} value={value} onValueChange={setValue} selectionMotion="slide" />
+```
+
+```tsx
+// Native
+<SegmentedControl label={t("period")} items={items} value={value} onValueChange={setValue} selectionMotion="slide" />
+```
+
+Web은 `@hjmds/react`의 해당 granular entry, Native는 `@hjmds/react-native` entry를 쓴다.
+선택 콜백은 두 플랫폼 모두 `onValueChange`다. 위 골격의 번역·항목·값은 제품이 제공한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 배치/테마 | Stack과 HjmProvider | Stack과 HjmNativeProvider |
+| 큰 글자·좁은 폭 | 줄바꿈·단일 내용 | 같은 순서, OS 화면 검증은 별도 |

package/docs/usage/compositions/texture-comparison.md

@@ -0,0 +1,86 @@
+# 질감 비교
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.14.0
+- 검토일: 2026-10-07
+- 근거: [EffectSurface 계약](../../effect-surface.md), `showcase/*/texture-comparison-preview.tsx`
+- 스토리북: `배포/구성/정보 표시/질감 비교`
+
+승급: 2026-10-07 사용자 승인, [검토 결과](../../../../../docs/qa/2026-10-07-experiment-promotion-release.md). Storybook 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+기존 반복 점 grain과 불규칙한 정적 noise를 같은 배경·강도로 비교할 때 쓴다.
+독립 NoiseTexture API를 추가하지 않고 기존 EffectSurface의 선택 레이어를 사용한다.
+일반 입력·데이터 패널은 불투명 Surface, 작업 진행·성공은 Progress·Result를 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| EffectSurface | 질감·테마·장식 수명주기 | [배경 효과](../components/effect-surface.md) |
+| SegmentedControl | 두 영역의 강도를 함께 선택 | [단일 선택](../components/segmented-control.md) |
+| TextField·Button·Text | 읽기·입력·행동·결과 확인 | [입력](../components/field.md) |
+
+noise는 생성된64×64 PNG alpha mask이며 자체 런타임 픽셀 생성·외부 요청이 없다.
+기본 intensity0.22, 실험의 비교 강도0.6은 가독성 스트레스 조건이며 제품 기본 권장이 아니다.
+seed는 고정 타일의 위상만 이동한다. 새 타일 픽셀을 생성하지 않는다.
+
+## 배치
+
+```text
+[강도 선택: 두 영역에 함께 적용]
+[grain: 제목 → 설명 → 입력 → 버튼]
+[noise: 제목 → 설명 → 입력 → 버튼]
+[선택 결과와 비교 한계]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 화면 본문 세로 | gap lg20 |
+| 비교 영역 | EffectSurface | grain 다음 noise | 내부 padding spacing.lg20, Stack gap md16 |
+| 질감 | SVG mask | absolute 배경 | viewBox 밖64×64 CSS pixel/Native logical point 타일 반복 |
+| 본문 | TextField·Button | 장식 앞 일반 레이아웃 | 기존 recipe |
+| Native 화면 | ScreenLayout·KeyboardAvoiding | 본문 스크롤과 바깥 키보드 여백 | 긴 내용·큰 글자 접근용 |
+
+## 흐름과 상태
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 두 질감과 기본22% 강도 | 입력·버튼 활성 |
+| 진행 중 | 강도 선택을 두 질감에 함께 반영 | 입력 유지, 인위 대기 없음 |
+| 실패 | 장식 host 실패는 기존 EffectSurface fallback | 제품 입력·행동은 유지 |
+
+1. 강도를 바꾸고 두 영역의 문장을 읽고 타이핑한다.
+2. 영역별 버튼을 눌러 결과 안내를 비교한다. 결과는 예제 내부 선택일 뿐 저장하지 않는다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { EffectSurface } from "@hjmds/react/effect-surface";
+<EffectSurface descriptor={{ layers: ["noise"], active: false }}><Content /></EffectSurface>
+```
+
+```tsx
+// Native
+import { EffectSurface } from "@hjmds/react-native/effect-surface";
+<EffectSurface descriptor={{ layers: ["noise"], active: false }}><Content /></EffectSurface>
+```
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 장식 | SVG image·mask | react-native-svg Image·Mask |
+| peer | 없음 | 기존 react-native-svg15.15.5 필요 |
+| 동작 | 가시성·document visibility | visible·AppState |
+
+Native FeTurbulence는 미구현이라 공유 PNG mask를 택했다. 새 GPU peer나 Native 무표시
+fallback을 동일 구현으로 세지 않는다. noise는 theme.text 색의 alpha mask다. 임의 브랜드/강도에서
+대비를 보장하지 않는다. 기본은 정적이며 active를 켜면 기존 모션 감소·숨김 수명주기를 유지한다.
+Web/RN rasterization·비율 차이로 픽셀 일치를 보장하지 않는다. 원본 SVG Perlin noise와 달리
+자체 생성한6 octave value noise이며 원본 자산을 복사하지 않았다. 실제 기기 표시·비용·VoiceOver
+검증은 따로 한다.

package/docs/usage/compositions/upload-recovery.md

@@ -0,0 +1,80 @@
+# 선택과 오류 복구
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.14.0
+- 검토일: 2026-10-07
+- 근거: 공개 API를 사용하는 `showcase/*/reference-adoption-previews.tsx`
+- 스토리북: `배포/구성/피드백과 복구/선택과 오류 복구`
+
+2026-10-07 사용자 승인으로 승급. [검토 결과](../../../../../docs/qa/2026-10-07-experiment-promotion-release.md).
+
+## 언제 쓰나
+
+파일 선택과 전송 상태의 취소·재시도를 연결할 때 쓴다. 별도 신규 wrapper API가 아니라 아래 공개 컴포넌트의 조합 규격이다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| FilePicker · UploadItem · Button | 입력·표현·행동의 역할 분리 | [입력/동작](../components/file-picker.md), [상태/전환](../components/upload-item.md) |
+
+## 배치
+
+```text
+[제목 또는 현재 입력]
+[상태/내용 영역]
+[관련 행동과 결과]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 화면의 본문 흐름 | gap md=16px, 전체 폭 |
+| 내용 | 해당 공개 API | 입력과 행동 사이 | 자체 recipe 크기, 줄바꿈 허용 |
+| 행동 | Button/기존 컨트롤 | 관련 항목 바로 뒤 | inline일 때 wrap, md=16px |
+
+## 흐름과 상태
+
+1. 선택→중복 제거→전송→성공 또는 실패→취소/재시도
+2. 서버 응답·파일 권한·문구·브랜드는 제품이 전달한다. Showcase의 예제 응답과 고정 데이터를 가져오지 않는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 입력과 사용 가능한 행동 | 조작 이름은 제품 언어 |
+| 진행 중 | 실제 작업 상태에 맞는 loading 또는 열린 도구 | 중복 요청 차단, 입력 유지 |
+| 실패 | 문구와 가능한 재시도 | 원래 입력/파일 유지, 결과 안내 |
+
+## 코드 골격
+
+```tsx
+// Web
+<UploadItem descriptor={item} labels={labels} onCancel={cancel} onRetry={retry} />
+```
+
+```tsx
+// Native
+<UploadItem descriptor={item} labels={labels} onCancel={cancel} onRetry={retry} />
+```
+
+Web은 `@hjmds/react`의 해당 granular entry, Native는 `@hjmds/react-native` entry를 쓴다.
+Button의 실행 콜백은 Web `onClick`, Native `onPress`로 연결한다. 위 골격의 도메인 함수·변수는 제품이 제공한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 배치/테마 | Stack과 HjmProvider | Stack과 HjmNativeProvider |
+| 큰 글자·좁은 폭 | 줄바꿈·단일 내용 | 같은 순서, OS 화면 검증은 별도 |
+
+### 예제의 제한과 초점 복구
+
+2026-10-07 실제 복구 흐름에서 상태 버튼이 사라질 때 Web 초점이 body로 빠졌다.
+예제는 상태 변경 전에 해당 파일의 이름 있는 영역으로 초점을 옮기고, 제거 후에는 예제 추가
+버튼으로 복귀한다. 이후 Tab으로 취소·재시도 등 현재 가능한 행동을 선택한다.
+제품도 비동기 상태 전환으로 사라지는 행동의 초점 목적지를 정한다.
+
+양쪽 예제는 이미지3개·파일당5MB 제한을 선언한다. Web은 실제 file chooser를 사용하며,
+Native onPick은 예제 후보를 반환하는 fixture다. Native 시스템 사진 선택기 검증으로 세지 않는다.
+서버 비전송 안내는 성공·거부 상태와 별도로 항상 표시한다. 실제 제품은 서버 확정·취소 시
+늦게 도착하는 응답·전송 ticket의 소유권을 제품 업로드 계층에 연결해야 한다.