@hjmds/design-contracts 1.20.0 → 1.22.0

package/docs/usage/compositions/action-feedback.md

@@ -88,12 +88,12 @@ const feedback = resolveSaveFeedback({
 
 ```tsx
 // Web
-<Button loading={feedback.pending} disabled={!feedback.canSubmit} onClick={save}>{feedback.pending ? pendingLabel : saveLabel}</Button>
+<Button loading={feedback.pending} disabled={!feedback.canSubmit} completion={{ confirmed: feedback.currentSaved, label: savedLabel }} onClick={save}>{saveLabel}</Button>
 ```
 
 ```tsx
 // Native
-<Button loading={feedback.pending} disabled={!feedback.canSubmit} onPress={save}>{feedback.pending ? pendingLabel : saveLabel}</Button>
+<Button loading={feedback.pending} disabled={!feedback.canSubmit} completion={{ confirmed: feedback.currentSaved, label: savedLabel }} onPress={save}>{saveLabel}</Button>
 ```
 
 Web은 `@hjmds/react`의 해당 granular entry, Native는 `@hjmds/react-native` entry를 쓴다.
@@ -111,3 +111,19 @@ Button의 실행 콜백은 Web `onClick`, Native `onPress`로 연결한다. 위
 | --- | --- | --- |
 | 배치/테마 | Stack과 HjmProvider | Stack과 HjmNativeProvider |
 | 좁은 폭 | 줄바꿈·단일 내용 | 같은 순서, OS 화면 검증은 별도 |
+
+
+## 확정 라벨의 크기 예약 (npm 1.21.0 · 2026-10-15)
+
+Lucian 001의 저장→진행→완료 프레임 유지를 기존 Button의 `completion` 옵션으로 보완한다.
+기본 행동 문자열은 항상 같은 children으로 두고, 완료 문자열은 `completion.label`로 처음부터
+알린다. `confirmed`는 `resolveSaveFeedback.currentSaved`처럼 **현재 입력과 마지막 확정
+응답**을 비교한 결과다. 요청 진행 중 편집했다면 이전 응답이 성공해도 완료 라벨을 표시하지
+않는다. 저장 중에는 중앙 로딩만 보이고, 실패하면 같은 기본 행동 문자열로 돌아온다.
+서버가 확정하기 전에는 완료를 표시하지 않으며 자동 성공 타이머·중복 mutation 엔진을 넣지 않는다.
+
+Web은 두 라벨을 겹쳐 측정하고 Native는 두 라벨의 고유 폭과 최대 높이를 미리 예약한다.
+자세한 초기 Native 행 예약과 문자열 제한은 [Button](../components/button.md#저장-확정-라벨과-프레임-예약-npm-1210--2026-10-15)을 따른다.
+기존 결과 영역이 live region을 소유한다. Button이 별도 자동 알림을 만들지 않아 저장 중·완료
+안내가 중복 발표되지 않는다. Showcase는 같은 공개 Button API를 사용하며, 예제 요청임을
+계속 밝힌다. 실제 제품은 자신의 네트워크 요청·정규화된 확정 응답을 기존 session에 전달한다.

package/docs/usage/compositions/activity-status.md

@@ -1,12 +1,12 @@
 # 백그라운드 작업 상태
 
 - 단계: 구성
-- 상태: 실험
+- 상태: 배포
 - 지원: Web · Native
 - 적용: 미게시(1.17.2 이후)
 - 검토일: 2026-10-13
 - 근거: [ActivityChip 계약](../../activity-chip.md), [Toast 패널](../../toast.md#패널-toast--미게시1172-이후), 양 Showcase `activity-status-preview.tsx`, `showcase/shared/activity-status.ts`
-- 스토리북: `실험/구성/피드백과 복구/백그라운드 작업 상태`
+- 스토리북: `배포/구성/피드백과 복구/백그라운드 작업 상태`
 
 ## 언제 쓰나
 

package/docs/usage/compositions/authoring-tools.md

@@ -0,0 +1,90 @@
+# 베지어·단축키 편집 도구
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-15
+- 근거: [편집 도구 계약](../../authoring-tools.md), `src/authoring-tools.ts`, 양 renderer `src/authoring-tools.tsx`
+- 스토리북: `배포/구성/직접 조작과 모션/베지어 이징 편집`, Web `배포/구성/직접 조작과 모션/단축키 조합 기록`
+
+ShortcutRecorder는 Web 전용이다. Native는 BezierEditor만 지원한다.
+
+## 언제 쓰나
+
+제품 안의 모션 편집기에서 두 제어점의 곡선을 조정하거나 웹 앱의 사용자 단축키를 실제로 등록할 때 쓴다. 단순 조합 표시는 기존 TextFormat을 사용한다. 제품 토큰 저장·전역 키 등록 서비스는 소비 제품이 소유한다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| BezierEditor | 네 좌표 controlled 편집·실제 미리 보기 | [계약](../../authoring-tools.md) |
+| ShortcutRecorder | 실제 키 조합 기록·검사·등록 요청 | [계약](../../authoring-tools.md) |
+| Slider | 좌표별 값과 조절 동작 | [Slider](../components/slider.md) |
+| Button | 미리 보기·기록·등록·취소 | [Button](../components/button.md) |
+
+## 배치
+
+```text
+[곡선·두 제어점]
+[x1 Slider] [y1 Slider] [x2 Slider] [y2 Slider]
+[이동 미리 보기 영역]
+[미리 보기]
+
+[현재 등록값 / 기록 중 포커스 영역]
+[기록] [초안 등록] [취소]
+[상태 안내 / 중앙 등록 오류]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 편집 패널 본문 | md |
+| 곡선 | SVG | 좌표 위 | 본문 폭, 높이 180 |
+| 좌표 | Slider 4개 | 세로 흐름 | 기존 Slider 계약 |
+| 키 기록 | 포커스 group | 버튼 위 | 최소 높이 44, 내용 중앙 |
+| 오류 | Text alert | 구성 내부 | 가로·세로 중앙 |
+
+## 흐름과 상태
+
+1. BezierEditor는 controlled 초안을 네 좌표 모두 편집하고 버튼으로 현재 곡선의 움직임을 재생한다.
+2. 초안을 제품 토큰에 자동 기록하지 않는다. 별도 저장 흐름으로 연결한다.
+3. ShortcutRecorder 기록 버튼으로 실제 키를 받는다. 예약·충돌·잘못된 조합은 등록하지 않는다.
+4. 확인한 초안을 등록하면 실제 서비스 Promise를 기다린다. 실패 시 초안을 보존한다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | controlled 값 표시 | Slider·버튼 기존 동작 |
+| 키 기록 | 포커스 영역·기록 안내 | Escape 취소, Tab/blur 종료 |
+| 진행 중 | 등록 버튼 로딩 | 중복 등록 차단 |
+| 실패 | 기존 값과 초안 보존 | 중앙 alert |
+
+## 코드 골격
+
+```tsx
+// Web
+import { BezierEditor, ShortcutRecorder } from "@hjmds/react/authoring-tools";
+<BezierEditor value={curve} onValueChange={setCurve} labels={curveLabels} formatCoordinate={formatNumber} />;
+<ShortcutRecorder value={registeredShortcut} onRegister={registerActualShortcut} platform={platform}
+  conflicts={existingShortcuts} reserved={platformReservations} labels={shortcutLabels} formatShortcut={formatShortcut} />;
+```
+
+```tsx
+// Native
+import { BezierEditor } from "@hjmds/react-native/authoring-tools";
+<BezierEditor value={curve} onValueChange={setCurve} labels={curveLabels} formatCoordinate={formatNumber} />;
+// ShortcutRecorder is unsupported on Native.
+```
+
+실행 예제는 Web `showcase/web/src/patterns/AuthoringTools.previews.tsx`, Native `showcase/native/src/authoring-tools-preview.tsx`다. Web 예제는 등록 callback에서 실제 keydown listener를 설치하고 실행 횟수를 보여 준다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 곡선 | CSS cubic-bezier / WAAPI | Animated / Easing.bezier |
+| 단축키 | KeyboardEvent·제품 등록 callback | 지원하지 않음 |
+| 백그라운드 | visibilitychange로 재생 중단 | AppState로 중단 |
+
+## 접근성과 검증
+
+각 좌표의 이름·값·증감 안내를 제품이 제공한다. reduced motion에서는 preview 이동을 재생하지 않는다. 키 조합 표시도 제품의 언어·레이아웃을 따른다. 계약 계산, Web 키 이벤트와 Promise 실패, Native 좌표 변경·preview host 호출을 검사한다. 실제 Native 기기와 제품별 예약키·전역 키 서비스 검증은 소비 단계에서 확인한다.

package/docs/usage/compositions/collection-editing.md

@@ -0,0 +1,110 @@
+# 목록 편집과 복구
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-15
+- 근거: [목록 편집과 복구 계약](../../collection-editing.md), `src/collection-editing.ts`, 양 renderer의 `src/collection-editing.tsx`
+- 스토리북: `배포/구성/입력과 작성/제목 바로 편집`, `배포/구성/입력과 작성/반복 입력`, `배포/구성/선택과 필터/선택 항목 묶음 작업`, `배포/구성/피드백과 복구/검색 필터 완화`, `배포/구성/선택과 필터/표 열 설정`
+
+## 언제 쓰나
+
+목록의 제목을 바로 고치거나, 입력 행을 늘리거나, 여러 항목에 같은 행동을 하거나, 빈 검색에서 조건을 풀거나, 표의 열을 설정할 때 쓴다.
+Lucian 예제 전수 검토에서 재사용할 실익이 있는 다섯 작업을 기존 HJM 구성으로 연결했다.
+다섯 API를 한 화면에 모두 넣는 것이 아니라 사용자 과제에 해당하는 하나를 고른다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| InlineEdit | 값 표시 → 같은 자리 입력·저장·취소 | [계약](../../collection-editing.md) |
+| RepeatableFieldGroup | stable ID로 묶은 입력 행 추가·삭제 | [FieldGroup](field-group.md) |
+| SelectionActionBar | 선택 개수·묶음 행동·작업별 복구 | [보관과 실행 취소](action-recovery-undo.md) |
+| FilterRecovery | 실제 결과가 나오는 필터 완화 제안 | [검색 화면](../components/search-screen.md) |
+| TableColumnSettings | 보이는 열·순서를 제어 | [DataTable](../components/data-table.md) |
+
+## 배치
+
+```text
+제목 편집             반복 입력              묶음 행동
+값                    이름 [입력]            N개 선택
+[수정]                [이 행 삭제]           [보관] [해제]
+↓                     [사람 추가]           [방금 작업 복구]
+[입력]
+[취소] [저장]
+
+필터 완화: 자기 본문 영역 중앙        열 설정: 각 열의 선택 아래 앞/뒤 이동
+제목·설명                            [✓ 이름] (고정)
+[주제 해제 · 실제 N개 보기]           [✓ 점수] [앞으로] [뒤로]
+실패 안내                            제어된 실제 DataTable
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | 제품 화면 host | 기존 본문·시트·패널 안; host가 스크롤·safe area·키보드를 소유 | 기존 Container/ScreenLayout 규격 |
+| 입력/행 | TextField, FieldGroup | 값과 같은 자리; 반복 행은 위→아래 | `collectionEditingRecipe.gap` = `md` |
+| 행동 | Button | 입력 아래 취소→저장, 행 아래 삭제, 행 묶음 마지막 추가 | `collectionEditingRecipe.actionGap` = `sm`, 좁으면 줄바꿈 |
+| 선택 바 | SelectionActionBar | 대상 목록 바로 아래 또는 제품 footer 슬롯 | 제품이 고정 위치 결정; 화면 전체 좌표를 새로 소유하지 않음 |
+| 상태 | Text·Button | 해당 구성 영역 중앙 | 임의 상단 margin 없이 가로·세로 중앙 정렬 |
+
+## 흐름과 상태
+
+1. 제품이 ID·문구·확정 데이터와 callbacks를 전달한다.
+2. 편집·선택·제안 클릭에서만 변경을 시작한다. blur는 저장하지 않고 제안은 자동 적용하지 않는다.
+3. 비동기 callback의 resolve/reject를 기다린다. 성공 결과·선택 해제·항목 복구는 제품 데이터로 반영한다.
+4. 실패하면 기존 입력·필터·항목을 유지하고 같은 위치에서 다시 실행할 수 있다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 값/입력/선택 요약/제안/열 선택 | stable ID로 기존 입력 host 유지 |
+| 진행 중 | 실행한 버튼 내부 로딩, 경쟁 행동 잠금 | 중복 실행 차단; 카드 높이를 임의로 접지 않음 |
+| 실패 | 중앙 실패 문구, 재실행 가능한 행동 | Web alert / Native assertive live region; 초안 유지 |
+
+## 코드 골격
+
+```tsx
+// Web. Native는 @hjmds/react-native/collection-editing에서 같은 공개 이름을 가져온다.
+import { InlineEdit, TableColumnSettings } from "@hjmds/react/collection-editing";
+
+<InlineEdit id={note.id} value={note.title} label={t("note.title")}
+  editLabel={t("edit")} saveLabel={t("save")} cancelLabel={t("cancel")}
+  errorLabel={t("saveFailed")} onSave={saveConfirmedTitle} />
+
+<TableColumnSettings label={t("table.columns")} columns={settings}
+  earlierLabel={column => t("table.earlier", { name: column.label })}
+  laterLabel={column => t("table.later", { name: column.label })}
+  onColumnsChange={setSettings} />
+// DataTable: settings.filter(c => c.visible).map(c => originalColumnsById[c.id])
+```
+
+```tsx
+// Native
+import { InlineEdit } from "@hjmds/react-native/collection-editing";
+
+<InlineEdit id={note.id} value={note.title} label={t("note.title")}
+  editLabel={t("edit")} saveLabel={t("save")} cancelLabel={t("cancel")}
+  errorLabel={t("saveFailed")} onSave={saveConfirmedTitle} />
+```
+
+다섯 구성의 완전한 실행 원본:
+
+- Web: `showcase/web/src/patterns/CollectionEditing.previews.tsx`
+- Native: `showcase/native/src/collection-editing-preview.tsx`
+
+각 예제는 공개 import로 구성한다. 제품이 showcase 소스를 import하지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 제목 확정 | Enter(IME 제외)·저장, Escape·취소 | TextInput submit·저장, 취소 버튼 |
+| 행 포커스 | focusRef를 HTML 입력 ref에 연결 | focusRef를 TextInput ref에 연결 |
+| 다중 선택 공급원 | DataTable 또는 CheckboxGroup | CheckboxGroup 등; Native DataTable의 단일 행 강조와 구분 |
+
+## 함정
+
+- 원본 데모의 고정 성공·전체 복구를 복사하지 않는다. 실패를 callback에서 삼키면 HJM은 성공으로 해석한다.
+- `onAdd`가 반환한 ID와 새 field ID가 같아야 한다. 입력 값을 배열 index에 저장하지 않는다.
+- 표 원본 descriptor의 pinned·width·sort를 보존한다. 설정 화면의 잠금은 서버 권한 검증을 대체하지 않는다.
+- npm 1.21.0 API다. 소비 제품의 실제 설치 버전을 확인한다.

package/docs/usage/compositions/communication.md

@@ -0,0 +1,100 @@
+# 펼치는 검색과 실제 메시지 답장
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-15
+- 근거: [연결 계약](../../communication.md), `src/communication.ts`, 양 renderer `src/communication.tsx`, `src/screens.tsx`
+- 스토리북: `배포/구성/선택과 필터/펼치는 상단 검색`, `배포/구성/입력과 작성/메시지 답장 연결`
+
+## 언제 쓰나
+
+상단 검색 버튼에서 검색 영역을 펼치거나 채팅의 실제 메시지를 선택해 답장을 전송할 때 쓴다. 이미 전체 화면으로 제공하는 검색에는 SearchScreen을 바로 쓴다. 입력 자동 높이·채팅 swipe 엔진·최근 검색 저장을 새로 만들지 않는다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| ExpandableSearch | 펼침 상태·실제 요청 Promise·검색 화면 연결 | [계약](../../communication.md) |
+| SearchScreen | 제안·확정·최근 검색·debounce | [SearchScreen](../components/search-screen.md) |
+| ReplyMessage | 실제 ID와 기존 답장 동작 연결 | [계약](../../communication.md) |
+| ReplyComposer | 답장 대상·실제 전송 Promise·실패 보존 | [계약](../../communication.md) |
+| MessageComposer | 기존 자동 높이·선택적 near-limit ring/count | [MessageComposer](../components/message-composer.md) |
+
+## 배치
+
+```text
+[검색 펼치기] → [검색 닫기]
+                [기존 SearchScreen 검색어·제안·결과]
+                [오류: 검색 영역 중앙]
+
+[실제 메시지·답장 동작]
+[실제 답장 저자/발췌·취소]
+[자동 높이 MessageComposer · 전송]
+[임박한 길이 ring/count] [실패: 구성 내부 중앙]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 검색·입력 영역 | sm/md |
+| 펼침·닫기 | Button | 상단 | 기존 버튼 계약 |
+| 검색 | SearchScreen | 펼친 본문 | 기존 검색 영역 구조 |
+| 메시지 | ChatMessage | 기존 timeline | 기존 메시지 구조 |
+| 입력 | MessageComposer | timeline 아래 | 기존 자동 높이 유지 |
+| 실패 | Text alert | 해당 구성 안 | 내용 묶음 중앙 |
+
+## 흐름과 상태
+
+1. 제품은 펼침·query를 관리하고 실제 검색 Promise를 넘긴다. SearchScreen이 debounce와 제안 확정을 맡는다.
+2. 입력 변경·닫기는 이전 요청을 abort하고 늦은 응답을 무시한다. Enter/제안 확정에서만 최근 검색을 기록한다.
+3. ReplyMessage는 실제 ID를 제품에 전달한다. 제품은 그 ID를 replyTarget으로 보관한다.
+4. ReplyComposer는 전송 시작 시점의 ID와 초안을 실제 전송 callback에 넘긴다. 성공 확인과 controlled 값 삭제는 제품이 맡는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 검색 버튼 또는 메시지·입력 | 기존 버튼·메시지 계약 |
+| 펼침 | 기존 검색 화면 | 검색 입력 포커스 |
+| 진행 중 | 실제 검색/전송 로딩 | 중복 전송 차단, 동일 입력 보존 |
+| 실패 | 입력·대상 보존 | 영역 중앙 alert |
+| 임박한 길이 | 실제 ring/count | maxLength와 동일 단위 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { ExpandableSearch, ReplyMessage, ReplyComposer } from "@hjmds/react/communication";
+<ExpandableSearch expanded={expanded} onExpandedChange={setExpanded} query={query} onQueryChange={setQuery}
+  onSearch={searchActualDocuments} renderResult={renderDocuments} labels={searchLabels} />;
+<ReplyMessage messageId={message.id} direction="incoming" author={message.author} timestamp={message.time}
+  replyLabel={replyLabel} onReply={selectActualMessage} swipeAction="reply">{message.body}</ReplyMessage>;
+<ReplyComposer value={draft} onValueChange={setDraft} label={inputLabel} sendLabel={sendLabel}
+  replyTarget={selectedMessage} onReplyCancel={clearReply} cancelReplyLabel={cancelReplyLabel} errorLabel={errorLabel}
+  onSend={sendActualMessage} maxLength={limit} lengthFeedback={lengthLabels} />;
+```
+
+```tsx
+// Native
+import { ExpandableSearch, ReplyMessage, ReplyComposer } from "@hjmds/react-native/communication";
+<ExpandableSearch expanded={expanded} onExpandedChange={setExpanded} query={query} onQueryChange={setQuery}
+  onSearch={searchActualDocuments} renderResult={renderDocuments} labels={searchLabels} />;
+<ReplyMessage messageId={message.id} direction="incoming" author={message.author} timestamp={message.time}
+  replyLabel={replyLabel} onReply={selectActualMessage} swipeAction="timestamp">{message.body}</ReplyMessage>;
+<ReplyComposer value={draft} onValueChange={setDraft} label={inputLabel} sendLabel={sendLabel}
+  replyTarget={selectedMessage} onReplyCancel={clearReply} cancelReplyLabel={cancelReplyLabel} errorLabel={errorLabel}
+  onSend={sendActualMessage} maxLength={limit} lengthFeedback={lengthLabels} />;
+```
+
+실행 예제는 Web `showcase/web/src/patterns/Communication.previews.tsx`, Native `showcase/native/src/communication-preview.tsx`다. 검색은 실제 로컬 문서를 필터링하고 메시지는 로컬 수신 adapter에서 성공·실패를 확인한다. 원격 서버에 전송한 결과로 해석하지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 검색 포커스 | 펼침 입력·닫기 버튼으로 복원 | 입력 focus·닫기 키보드 해제 |
+| 답장 대안 | Alt+방향키 | 접근성 reply action |
+| 시간 swipe | reply drag 대신 시간 표시 | 동일 |
+
+## 접근성과 검증
+
+실제 메시지 ID와 보이는 발췌를 분리한다. 가로 swipe와 세로 timeline 스크롤은 기존 ChatMessage의 기준을 따른다. `swipeAction`으로 답장/시간 중 드래그 소유자를 정한다. 길이 안내는 선택 속성이고 기존 자동 높이를 대체하지 않는다. 실제 서버 receipt·기기 키보드·제품 데이터와 npm 게시 여부는 소비 단계에서 확인한다.

package/docs/usage/compositions/data-workflows.md

@@ -0,0 +1,91 @@
+# 데이터 해석과 가져오기
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-15
+- 근거: [데이터 구성 계약](../../data-workflows.md), `src/data-workflows.ts`, 양 renderer의 `src/data-workflows.tsx`
+- 스토리북: `배포/구성/입력과 작성/가져오기 열 연결`, `배포/구성/정보 표시/전환 퍼널`, `배포/구성/정보 표시/코호트 잔존율`, `배포/구성/정보 표시/상관 행렬`, `배포/구성/정보 표시/목표 달성 요약`, `배포/구성/정보 표시/분포 구간 탐색`
+
+## 언제 쓰나
+
+CSV 열 연결, 순차 퍼널, 가입 시점별 잔존율, 지표 상관, 목표, 분포 구간 탐색에 쓴다.
+단순 표/통계/막대 그래프만 필요하면 기존 DataTable/Statistic/BarChart를 직접 쓴다.
+같은 구성의 비율 계산과 검증을 제품마다 복사하지 않기 위해 도입했다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| ImportFieldMapping | Select, DataTable, Button | 제품 parser·실제 importer와 controlled mapping |
+| ConversionFunnel | BarChart, Button, Text | 제품 순차 count·이탈 사유 |
+| CohortRetentionTable / CorrelationMatrix | DataTable | 실제 분모/관측값·상관값 |
+| TargetSummary | Statistic, Progress | 실제값·목표 |
+| HistogramExplorer | BarChart, Button | 원본 samples·범위·선택 구간 수 |
+
+## 배치
+
+```text
+가져오기: 원본별 선택 → 검증 → 변환 미리보기 → 실제 가져오기
+퍼널: 실제 단계 막대 → 단계 선택 → 선택한 단계 설명
+표: 고정 행 제목 | 기간/변수 열 (가로 스크롤)
+목표: 실제 수치·설명 → 목표가 있을 때 진행 막대
+분포: 구간 수 선택 → 동일 y축 분포 → 관측/누락/범위 밖 요약
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 기존 본문·카드 안 | md, 목표는 sm |
+| 선택/행동 | Button/Select | 데이터 위 또는 연결 마지막 | Stack inline sm wrap |
+| 상태 | Text | 해당 구성 중앙 | 중앙 정렬, 임의 상단 margin 없음 |
+| 표 | DataTable | 본문 폭 안 스크롤 | 첫 열 pinned start; 대각선도 실제 셀 |
+
+## 흐름과 상태
+
+1. 제품이 실제 데이터와 formatter를 전달한다.
+2. 가져오기 연결/분포 구간 수는 제품의 controlled 상태로 반영한다.
+3. 중복 연결·필수 누락이면 미리보기/실행을 막고 실제 원인을 표시한다.
+4. 가져오기 resolve까지 중복 실행을 차단한다. reject하면 연결은 유지하고 오류 뒤 같은 행동으로 재시도한다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 실제 데이터와 controlled 선택 | 실제 표/차트의 기존 접근성 계약 |
+| 진행 중 | 가져오기 버튼 내부 로딩 | 중복 실행 차단, 연결 선택 잠금 |
+| 실패 | 연결 유지·중앙 오류 | Web alert / Native assertive, 같은 행동 재시도 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { TargetSummary } from "@hjmds/react/data-workflows";
+<TargetSummary label={t("goal.title")} actual={actual} target={target}
+  formatActual={formatCount} summaryLabel={formatGoalSummary} />;
+```
+
+```tsx
+// Native
+import { TargetSummary } from "@hjmds/react-native/data-workflows";
+<TargetSummary label={t("goal.title")} actual={actual} target={target}
+  formatActual={formatCount} summaryLabel={formatGoalSummary} />;
+```
+
+실행 예제는 Web `showcase/web/src/patterns/DataWorkflows.previews.tsx`, Native `showcase/native/src/data-workflows-preview.tsx`다.
+각각 공개 진입점을 소비한다. 제품에서 showcase 원본을 import하지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 계산·데이터 | 공유 contracts | 공유 contracts |
+| 연결 선택 | Select popover | Select 창, dismissLabel 필수 |
+| 차트 host | SVG | react-native-svg optional peer |
+Native 차트는 기존 react-native-svg optional peer를 사용한다. 새 제스처나 자체 차트 엔진을 추가하지 않는다.
+
+## 함정
+
+- null 미래 관측을 0%로 채우거나 목표 0을 100%로 만들지 않는다.
+- 순차가 아닌 지표를 퍼널에 넣지 않는다. 실제 원인 데이터 없이 이탈 사유를 생성하지 않는다.
+- 히스토그램 전체 선택에서 같은 domain을 유지한다. 누락값·범위 밖 count를 제품 summaryLabel에 표현한다.
+- mapping 변경만으로 저장을 실행하지 않는다. 서버 확정·권한·멱등성은 실제 importer 책임이다.
+- npm 1.21.0에서 제공하며 소비 앱의 실제 설치 버전을 확인한다.

package/docs/usage/compositions/media-transport.md

@@ -0,0 +1,87 @@
+# 미디어 재생 제어
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-15
+- 근거: [미디어 제어 계약](../../media-transport.md), `src/media-transport.ts`, 양 renderer `src/media-transport.tsx`
+- 스토리북: `배포/구성/직접 조작과 모션/미디어 재생 제어`
+
+## 언제 쓰나
+
+실제 오디오/영상 엔진의 재생·일시 정지·유한 길이 탐색을 같은 구조로 제공할 때 쓴다.
+모달에서 영상 host를 표시하는 Dialog나 실제 플레이어 엔진을 대체하지 않는다.
+단순 이동 버튼이나 일반 수치 입력은 기존 IconButton/Slider를 직접 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| MediaTransport | 관측 상태와 실제 callback 연결 | [계약](../../media-transport.md) |
+| IconButton | 실제 재생 상태로 모핑하는 제어 | [IconButton](../components/icon-button.md) |
+| Slider | 탐색 초안→실제 seek 확정 | [Slider](../components/slider.md) |
+
+## 배치
+
+```text
+[실제 재생/일시 정지]  현재 시간 / 실제 전체 길이
+[──── 실제 위치 탐색 ────] (길이를 알 때만)
+제어 실패: 해당 영역 중앙 → 같은 행동으로 재시도
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 기존 영상/오디오 host 아래 | md |
+| 제어·시간 | IconButton/Text | inline, 세로 중앙 | sm, 아이콘 24 |
+| 탐색 | Slider | 제어 아래 본문 폭 | 기존 Slider 규격 |
+| 실패 | Text | 구성 내부 중앙 | 임의 상단 여백 없음 |
+
+## 흐름과 상태
+
+1. 제품 엔진 이벤트에서 state를 갱신한다. 클릭은 실제 엔진 callback만 호출한다.
+2. 실제 playing 값에 따라 버튼 이름·모핑을 갱신한다.
+3. 탐색 초안은 드래그/키 입력이 끝나면 onSeek에 전달한다. 성공·실패 뒤 관측 위치로 돌아온다.
+4. 실패한 요청은 현재 상태를 유지한다. 중복 요청은 차단한다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 실제 playing 아이콘·시간·가능한 탐색 | 기존 버튼·Slider 계약 |
+| 진행 중 | 같은 버튼 내부 로딩·탐색 잠금 | 크기 유지, 중복 실행 차단 |
+| 실패 | 관측값 유지·중앙 오류 | Web alert / Native assertive |
+
+## 코드 골격
+
+```tsx
+// Web
+import { MediaTransport } from "@hjmds/react/media-transport";
+<MediaTransport state={observedMedia} labels={mediaLabels} formatTime={formatTime}
+  onPlay={playActualMedia} onPause={pauseActualMedia} onSeek={seekActualMedia} />;
+```
+
+```tsx
+// Native
+import { MediaTransport } from "@hjmds/react-native/media-transport";
+<MediaTransport state={observedMedia} labels={mediaLabels} formatTime={formatTime}
+  onPlay={playActualMedia} onPause={pauseActualMedia} onSeek={seekActualMedia} />;
+```
+
+실행 예제는 Web `showcase/web/src/patterns/media-transport-preview.tsx`, Native `showcase/native/src/media-transport-preview.tsx`다.
+제품에서 showcase 원본을 import하지 않고 자체 엔진 이벤트를 공개 API에 연결한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 실제 예제 엔진 | HTMLVideoElement | 기존 Expo Video |
+| 모핑 | SVG d 직접 반영 | react-native-svg host 직접 반영 |
+| 탐색 확정 | seeked/error | 엔진 setter/이벤트 계약 |
+| 숨김 | document visibility | AppState + host active |
+
+## 함정
+
+- 클릭만으로 playing을 바꾸거나 타이머로 시간을 더하지 않는다.
+- duration null/0에 가짜 분모나 임의 길이를 넣지 않는다.
+- active=false는 컨트롤 수명이다. 플레이어 pause/dispose도 제품 adapter에서 수행한다.
+- 다른 미디어 엔티티로 전환할 때 key를 바꾸고 이전 플레이어·요청을 정리한다.
+- Native 재생 모듈 없음 안내를 실제 재생 성공으로 기록하지 않는다. 새 API는 npm 1.21.0에서 제공한다.

package/docs/usage/compositions/social-compositions.md

@@ -0,0 +1,91 @@
+# 팔로우 프로필과 행사 참석 응답
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-15
+- 근거: [사회적 행동 계약](../../social-compositions.md), 양 renderer의 `src/social-compositions.tsx`
+- 스토리북: `배포/구성/정보 표시/팔로우 프로필`, `배포/구성/선택과 필터/행사 참석 응답`
+
+## 언제 쓰나
+
+프로필 팔로우나 행사 참석 응답의 실제 요청과 수치의 실패 복구가 필요할 때 사용한다.
+화면 틀이 필요하면 ProfileScreen의 summary/본문에 넣고, 단순 정보만 보여주면 기존 Card를 쓴다.
+Web은 기존 AnimatedStatistic과 같은 `@number-flow/react` peer가 필요하다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| FollowProfileCard | Card · Avatar · AnimatedStatistic · Button으로 프로필·팔로워·controlled follow 요청 | [Card](../components/card.md) |
+| EventAttendanceCard | Card · Avatar · AnimatedStatistic · Button으로 행사·참석·캘린더 연결 | [Avatar](../components/avatar.md) |
+
+## 배치
+
+```text
+팔로우 프로필                      행사 참석 응답
+[Avatar] 이름 · 소개               제목 · 소개
+팔로워 수                         날짜/시간
+[팔로우 / 팔로잉]                  참석 인원 → 확인된 참가자 Avatar + 이름
+                                  응답 제목 → [참석] [미정] [불참]
+                                  [캘린더 연결]
+오류: 해당 카드 내부 중앙          오류: 해당 카드 내부 중앙
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Card | 본문·목록·ProfileScreen 안 | 기존 Card recipe |
+| 프로필 header | Avatar · Card title/description | 상단 leading → 이름·소개 | 기존 Card와 Avatar 기본 크기 |
+| 본문 | AnimatedStatistic · Button · Text | 수치 → 주요 행동 → 오류 | Stack gap=md (`spacing.md`, 16px) |
+| 행사 | Text · AnimatedStatistic · Avatar · Button | 날짜 → 인원 → 참가자 → 응답 → 캘린더 → 오류 | Stack gap=md (`spacing.md`, 16px) |
+| 참가자·응답 행 | Stack | inline, 폭이 모자라면 wrap | gap=xs (`spacing.xs`, 8px) |
+| 오류 | Text | 자신의 안내 영역 가로·세로 중앙 | 임의 상단 margin 없음 |
+
+## 흐름과 상태
+
+1. 제품이 확인한 `state`, 선택지, 문구, locale과 실제 async callback을 전달한다.
+2. 요청 중에만 제안한 선택/수치를 표시하며 중복 mutation을 막는다.
+3. 제품은 callback에서 서버 확정 snapshot으로 state를 갱신한 뒤 resolve해야 한다. 성공 snapshot이 예측과 달라도 제품 값이 우선한다.
+4. 참가자 avatar 목록에는 서버가 확인한 사람만 넣으며 HJM이 가상의 참석자를 추가하지 않는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 확인된 선택·수치·참가자 | Button의 기존 선택·키보드 계약 |
+| 진행 중 | 캡처한 제안 선택·수치, 행동 잠금 | 로딩은 버튼 안, 수치 전환은 AnimatedStatistic |
+| 실패 | 현재 confirmed state로 복구, 중앙 오류 | Web alert / Native assertive, 같은 행동 재시도 |
+| 캘린더 완료 | 실제 callback fulfilled 후 완료 label | 같은 mount에서 중복 추가 차단 |
+| 엔티티 변경 | 새 profileId/eventId의 상태 | 이전 응답은 새 카드에 반영하지 않음 |
+
+캘린더 callback은 권한·실제 저장 결과를 책임진다. 기기 저장 전 완료를 반환하지 않는다.
+사용자 로그인, API idempotency, 캐시 갱신, 이전 엔티티 응답의 캐시 배치는 제품이 소유한다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { FollowProfileCard } from "@hjmds/react/social-compositions";
+<FollowProfileCard profileId={profile.id} name={profile.name} avatar={profileAvatar}
+  state={confirmedFollowState} locale={locale} labels={followLabels}
+  onFollowChange={async following => {
+    const confirmed = await api.setFollow(profile.id, following);
+    updateProfileCache(profile.id, confirmed);
+  }} />;
+```
+
+```tsx
+// Native
+import { EventAttendanceCard } from "@hjmds/react-native/social-compositions";
+<EventAttendanceCard eventId={event.id} title={event.title} dateLabel={dateLabel}
+  state={confirmedAttendance} choices={localizedResponseChoices}
+  participants={confirmedParticipants} locale={locale} labels={attendanceLabels}
+  onResponseChange={async responseId => {
+    const confirmed = await api.respond(event.id, responseId);
+    updateEventCache(event.id, confirmed);
+  }}
+  onAddToCalendar={async () => { await calendarAdapter.saveConfirmedEvent(event); }} />;
+```
+
+두 플랫폼은 같은 props와 shared resolver를 사용한다. `avatar` 슬롯만 플랫폼 이미지 host에 맞춘다.
+실행되는 전체 예제는 Web `showcase/web/src/patterns/social-compositions-preview.tsx`,
+Native `showcase/native/src/social-compositions-preview.tsx`에 있다. 예제 어댑터를 제품 API로 복사하지 않는다.