@hjmds/design-contracts 1.26.1 → 1.27.1

package/docs/usage/components/editor-screen.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.17.1
-- 검토일: 2026-10-13
+- 검토일: 2026-10-17
 - 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screens.tsx`·`src/screen-flows.tsx`; 기존 개별 지침을 새 규격으로 통합. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
 - 스토리북: `배포/화면/콘텐츠/작성과 수정`, `배포/화면/계정/프로필`
 
@@ -93,18 +93,18 @@ import { TextField } from "@hjmds/react-native/inputs";
 | --- | --- | --- | --- |
 | `dirty` | `boolean` | 필수 | `true`에서 닫기를 누르면 `discard` 확인창을 띄우고, 확인하면 `cancel.onAction`을 부른다. `false`면 바로 부른다 |
 | `submit` | `ScreenFlowAction`(`{ label, onAction(), disabled?, pending? }`) | 필수 | `pending`이면 loading·비활성. 그동안 닫기 버튼도 비활성. 본문 `state`가 `ready`가 아니면 저장 비활성 |
-| `cancel` | `ScreenFlowAction` | 필수 | `leading` 자리의 ghost 닫기 버튼 |
+| `cancel` | `ScreenFlowAction` | 필수 | 헤더 시작 쪽 × 아이콘 닫기 버튼(`ScreenLayout` `exit` `close`). `label`은 보조기술 이름이다. 2026-10-17부터 글자 버튼 대신 아이콘 |
 | `discard` | AlertDialog confirm 요청에서 `onConfirm`을 뺀 것 + `fallbackErrorMessage: string` | 필수 | `onConfirm`은 EditorScreen이 채운다 |
 | `submitPlacement` | `"footer"` · `"header"` | `"footer"` | `header`면 저장이 상단 `actions` 자리로 가고 footer에는 `draftStatus`만 남는다 |
 | `draftStatus` | `ReactNode` | 없음 | 초안 저장 상태 안내. footer에 놓인다 |
 | `children` | `ReactNode` | 필수 | 편집 본문 |
-| 나머지 | `ScreenLayout`과 같음(`children`·`footer` 제외) | — | `leading`은 닫기 버튼으로 덮인다. `submitPlacement="footer"`일 때만 `actions`가 그대로 전달된다 |
+| 나머지 | `ScreenLayout`과 같음(`children`·`footer` 제외) | — | `leading`·`exit`은 받지 않는다(닫기가 그 자리를 소유).  `submitPlacement="footer"`일 때만 `actions`가 그대로 전달된다 |
 
 ## 배치
 
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
-| 크기 | ScreenLayout 폭(최대 720) 안에 입력 본문; 저장·닫기는 `Button` 기본 크기 | `ScreenLayout`, `screen-flows.tsx` `Action` |
+| 크기 | ScreenLayout 폭(최대 720) 안에 입력 본문; 저장은 `Button` 기본 크기, 닫기는 `IconButton` | `ScreenLayout`, `screen-flows.tsx` `Action` |
 | 간격 | 화면 padding `spacing.md` 16; footer 안 `draftStatus`–저장 `spacing.sm` 12(`Stack gap="sm"`); 본문 안 입력 간격은 제품(Form 등) 소유 | Web·Native `EditorScreen` |
 | 순서·정렬 | 헤더(닫기 → 제목 → [저장: header 배치]) → 본문 → footer(`draftStatus` → 저장) | `EditorScreen` 렌더 순서 |
 | 고정·스크롤 | 헤더·footer 고정, 본문 스크롤(`scroll` 기본 `"screen"`); 이탈 확인은 AlertDialog 오버레이 | `ScreenLayout`, `AlertDialog` |
@@ -115,7 +115,7 @@ import { TextField } from "@hjmds/react-native/inputs";
 - 모든 문구(`label`, `discard`의 제목·설명·버튼)는 i18n 키로 넣는다. 컴포넌트는 기본 문구를 갖지 않는다.
 - `discard`는 `fallbackErrorMessage`까지 필수 타입이다. `onConfirm`은 EditorScreen이 채우므로 넘기지 않는다.
 - 확인 후 초안을 되돌리는 일은 `cancel.onAction` 안에서 제품이 한다.
-- 저장 시작 또는 `cancel.disabled`/`cancel.pending` 전환은 이미 열린 초안 버리기 확인도 종료한다. 잠금이 풀렸다고 확인창이 다시 열리지는 않는다. 2026-10-13 이전 확인창으로 저장 중 이탈 잠금을 우회할 수 있던 경로를 수정했다.
+- 저장 시작 또는 `cancel.disabled`/`cancel.pending` 전환은 이미 열린 초안 버리기 확인도 종료한다. 잠금이 풀렸다고 확인창이 다시 열리지는 않는다.
 - 최초 조회·오류·권한 제한 등 본문 대체 상태에서는 저장을 잠근다. 새 문서의 빈 초안은 `state="empty"`가 아니라 `ready`와 빈 입력으로 표현하고 제품 validation은 `submit.disabled`에 연결한다.
 - 라우터 뒤로가기·Android back·브라우저 이탈은 이 컴포넌트가 막지 않는다. 제품이 `dirty`로 guard를 건다.
 - 저장 성공 판정·오류 표시는 제품 상태(`notice`, Toast 등)로 한다.
@@ -126,3 +126,7 @@ import { TextField } from "@hjmds/react-native/inputs";
 | --- | --- | --- |
 | 화면 셸 전용 props | `as`, `className` | `testID`, `scrollRef`, `scrollProps` (`layoutStyle`은 양쪽 모두 받는다) |
 | 버튼 이벤트 | 내부에서 `onClick` → `onAction` | 내부에서 `onPress` → `onAction` |
+
+## 근거
+
+- 저장 시작 시 열린 버리기 확인 종료: 2026-10-13 이전 확인창으로 저장 중 이탈 잠금을 우회할 수 있던 경로를 수정했다.

package/docs/usage/components/effect-surface.md

@@ -71,6 +71,8 @@ import { EffectSurface } from "@hjmds/react-native/effect-surface";
 | `descriptor.colors` | `ColorReference` 세 개 | `themeColor("primary")` · `themeColor("contentBrand")` · `themeColor("surfaceAccent")` | — |
 
 | `children` | `ReactNode` | — (필수) | 일반 레이아웃 내용 |
+| `padding` | `none` · spacing 이름(Surface와 같은 척도) | `none` | 장식 영역 안쪽 내용 여백. 장식 레이어는 여백까지 덮는다 |
+| `radius` | `none` · radius 이름(Surface와 같은 척도) | Surface 기본 `lg` 16 | 루트 모서리. 장식은 이 모서리 안에서 잘린다. 화면 전체 배경(design profile canvas)은 `none` |
 | Native `visible` | `boolean` | `true` | 화면·목록 소유자가 가려짐을 알린다. `false`면 장식이 멈춘다 |
 | Web `layoutStyle` | 배치 전용 style | — | 루트 배치 |
 | Native `style` | `StyleProp<ViewStyle>` | — | 컨테이너 `View`. 정식 motion host 프레임이라 deprecated 대상이 아니다 |
@@ -81,8 +83,8 @@ import { EffectSurface } from "@hjmds/react-native/effect-surface";
 
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
-| 크기 | EffectSurface는 여백을 갖지 않는다. 크기는 children이 정하고 장식 레이어가 그 영역 전체(`absolute`, inset 0)를 덮는다. 넘치는 장식은 잘린다(`overflow: hidden`). 배경은 테마 `bg`다. 높이를 늘리려면 children 높이, Web `layoutStyle`·Native `style`의 높이로 정한다. 장식 레이어는 배치에 참여하지 않는다 | `react/src/effect-surface.tsx`, `react-native/src/effect-surface.tsx` |
-| 간격 | 내용 여백·간격은 children 쪽 [Stack](stack.md) 등으로 준다 | `react/src/effect-surface.tsx` |
+| 크기 | 기본 여백은 없다(`padding="none"`). 크기는 children과 `padding`이 정하고 장식 레이어가 그 영역 전체(`absolute`, inset 0)를 덮는다. 넘치는 장식은 `radius` 모서리 안에서 잘린다(`overflow: hidden`). 안에 둔 Surface와 같은 기본 radius라 둥근 카드 모서리 밖으로 장식이 비치지 않는다. 배경은 테마 `bg`다. 높이를 늘리려면 children 높이, Web `layoutStyle`·Native `style`의 높이로 정한다. 장식 레이어는 배치에 참여하지 않는다 | `react/src/effect-surface.tsx`, `react-native/src/effect-surface.tsx` |
+| 간격 | 안쪽 여백은 `padding`(예: `lg` 20), 내용 사이 간격은 children 쪽 [Stack](stack.md)으로 준다. raw 요소에 padding을 직접 주지 않는다 | `react/src/effect-surface.tsx` |
 | 순서·정렬 | children은 일반 레이아웃이다. [Stack](stack.md)으로 eyebrow → [Heading](heading.md) → 소개 → [Button](button.md)을 쌓는다(Showcase 랜딩 예는 `gap="lg"` 20, Heading `level1`) | `showcase/web/src/patterns/Landing.stories.tsx` |
 | 고정·스크롤 | 화면 위쪽 히어로 하나에만 둔다. 같은 화면에 여러 개를 겹치거나 목록 행마다 두지 않는다 | — |
 | 좁은 폭·큰 글자 | — | — |

package/docs/usage/components/empty-state.md

@@ -59,7 +59,7 @@ import { EmptyState } from "@hjmds/react-native/feedback";
 
 | prop | 값 | 기본값 | 설명 |
 | --- | --- | --- | --- |
-| `density` | `compact` · `regular` | `regular` | `compact`는 세로 여백이 작고 Native에서 남은 공간을 채우지 않는다 |
+| `density` | `compact` · `regular` | `regular` | `compact`는 세로 여백이 작고 남은 공간을 채우지 않는다 |
 | `align`(Native) | `center` · `upper` | `center` | `upper`는 `regular`일 때 내용을 위쪽(1:3 여백)에 둔다 |
 | `announcement`(Native) | `none` · `polite` · `assertive` | `none` | 상태가 바뀌어 빈 화면이 새로 나타날 때만 켠다 |
 | `titleRole`(Native) | 접근성 role | `"header"` | Web은 항상 `role="status"`로 그린다 |
@@ -80,7 +80,7 @@ EmptyState 자체에는 콜백 prop이 없다. 2026-10-07 기존 예제의 생
 | 크기 | Native 그림 슬롯은 최소 `glyph.lg`(28) 폭·높이를 확보하고 큰 일러스트의 자체 크기를 존중한다. Web 그림 슬롯에는 고정 크기가 없다. 세로 여백: `compact` `spacing.xl`(24). `regular` `spacing.xxxl`(40, 두 플랫폼) | `component-recipes.ts` `emptyStateRecipe`, `styles.css` `.hjm-empty-state` |
 | 간격 | 항목 사이 간격 `spacing.xs`(8), 좌우 여백 `spacing.xl`(24) | `component-recipes.ts` `emptyStateRecipe` |
 | 순서·정렬 | 위→아래 순서는 그림 → 제목 → 설명 → 행동이고 가운데 정렬이다. 행동은 Button 하나(`tone="secondary"` 또는 `primary`)를 내용 폭만큼 둔다 | `react-native/src/feedback.tsx` `EmptyState` |
-| 고정·스크롤 | 비어 있는 목록·검색 결과 영역 **안**에 둔다. 위 TopBar·검색칸·필터는 그대로 남기고 그 아래 내용 영역만 EmptyState로 바꾼다. Native `regular`는 남은 높이를 채우고(`flexGrow: 1`) 세로 가운데에 놓는다. `align="upper"`는 위:아래 빈 공간을 1:3으로 나눠 내용이 위쪽에 온다. 화면 하단 고정 행동이 필요하면 [BottomCTA](bottom-cta.md)로 따로 둔다 | `react-native/src/feedback.tsx` `EmptyState` |
+| 고정·스크롤 | 비어 있는 목록·검색 결과 영역 **안**에 둔다. 위 TopBar·검색칸·필터는 그대로 남기고 그 아래 내용 영역만 EmptyState로 바꾼다. `regular`는 flex 부모의 남은 높이를 채우고(Web `flex-grow: 1`, Native `flexGrow: 1`) 세로 가운데에 놓는다. 높이가 내용만큼인 부모에서는 늘어나지 않는다. `align="upper"`는 위:아래 빈 공간을 1:3으로 나눠 내용이 위쪽에 온다. 화면 하단 고정 행동이 필요하면 [BottomCTA](bottom-cta.md)로 따로 둔다 | `react/src/styles.css` `.hjm-empty-state`, `react-native/src/feedback.tsx` `EmptyState` |
 | 좁은 폭·큰 글자 | 카드·시트 안처럼 높이가 작은 자리는 `compact`(채우지 않음)를 쓴다 | `react-native/src/feedback.tsx` `EmptyState` |
 
 ```text

package/docs/usage/components/event-attendance-card.md

@@ -0,0 +1,104 @@
+# EventAttendanceCard
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: `src/social-compositions.ts`의 `resolveAttendanceProposal`·`resolveAttendanceChoice`, 양 renderer `src/social-compositions.tsx`, [소셜 구성](../compositions/social-compositions.md)
+- 스토리북: `배포/구성/선택과 필터/행사 참석 응답`
+
+## 언제 쓰나
+
+행사·모임 카드에서 일정, 참석자 수, 참석자 목록을 보여 주고 참석 응답(참석·미정·불참 등)과 캘린더 추가를
+실제 요청으로 처리할 때 쓴다. 응답 요청 중에는 제안한 응답과 참석자 수를 먼저 보여 주고, 실패하면 제품이
+확인한 `state`로 되돌린다. 네트워크·인증·저장은 제품이 소유한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 프로필 팔로우 | `FollowProfileCard`([소셜 구성](../compositions/social-compositions.md)) |
+| 요청 없이 선택만 하는 응답 | [SegmentedControl](segmented-control.md) 또는 [RadioGroup](radio-group.md) |
+| 일반 정보 카드 | [Card](card.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `EventAttendanceCard` | 행사 참석 응답·캘린더 추가 카드 | `@hjmds/react/social-compositions` | `@hjmds/react-native/social-compositions` |
+
+`AttendanceChoice`·`EventAttendanceState` 타입과 `resolveAttendanceProposal`은 `@hjmds/design-contracts/social-compositions`에서 import한다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { EventAttendanceCard } from "@hjmds/react/social-compositions";
+
+<EventAttendanceCard eventId={event.id} title={event.title} dateLabel={formatEventDate(event)}
+  locale={locale} state={attendance} choices={choices} participants={participants}
+  labels={{ response: t("rsvp.title"), pending: t("common.pending"), count: t("rsvp.count"),
+    calendar: t("rsvp.calendar"), calendarAdded: t("rsvp.calendarAdded"), error: t("rsvp.error") }}
+  onResponseChange={async id => setAttendance(await saveResponse(event.id, id))}
+  onAddToCalendar={() => addEventToCalendar(event)} />
+```
+
+```tsx
+// Native
+import { EventAttendanceCard } from "@hjmds/react-native/social-compositions";
+
+<EventAttendanceCard eventId={event.id} title={event.title} dateLabel={formatEventDate(event)}
+  locale={locale} state={attendance} choices={choices} participants={participants}
+  labels={{ response: t("rsvp.title"), pending: t("common.pending"), count: t("rsvp.count"),
+    calendar: t("rsvp.calendar"), calendarAdded: t("rsvp.calendarAdded"), error: t("rsvp.error") }}
+  onResponseChange={async id => setAttendance(await saveResponse(event.id, id))}
+  onAddToCalendar={() => addEventToCalendar(event)} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| eventId | string | 필수 | 비어 있으면 오류. 바뀌면 내부 요청 상태를 새로 시작한다 |
+| title / description | string / ReactNode | title 필수 | Card 제목·설명 |
+| dateLabel | string | 필수 | 제품이 현지화한 일정 문구 |
+| state | `{ responseId: string \| null; count: number }` | 필수 | 서버가 확인한 응답과 참석자 수. 참석 응답인데 수가 0이면 오류 |
+| choices | `readonly AttendanceChoice[]`(`id`·`label`·`attending`·`disabled?`) | 필수 | 비어 있거나 id 중복이면 오류 |
+| participants | `{ id; name; avatar? }[]` | 필수 | 아바타가 없으면 이름 Avatar를 장식으로 표시 |
+| locale | string | 필수 | 참석자 수 `AnimatedStatistic` 숫자 형식 |
+| labels | `response`·`pending`·`count`·`calendar`·`calendarAdded`·`error` | 필수 | 문구 |
+| onResponseChange | `(responseId) => void \| Promise<void>` | 필수 | 실제 응답 저장. 끝나면 `state` 갱신 |
+| onAddToCalendar | `() => void \| Promise<void>` | 필수 | 기기 캘린더·권한 어댑터. reject하면 재시도 가능 |
+| disabled | boolean | false | 모든 행동 비활성 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 부모 폭을 채우는 Card, 높이는 내용 | [Card](card.md) |
+| 간격 | 본문 요소 사이 `spacing.md` 16, 참석자 사이·아바타–이름·응답 버튼 사이 `spacing.xs` 8 | `Stack gap="md"`, `Stack axis="inline" gap="xs"` |
+| 순서·정렬 | Card 제목·설명 → 일정 → 참석자 수 → 참석자 목록 → 응답 제목(strong) → 응답 버튼 행 → 캘린더 버튼(secondary) → 실패 문구(중앙) | 양 renderer |
+| 고정·스크롤 | 자체 스크롤 없음. 카드 목록 스크롤은 부모 | [Card](card.md) |
+| 좁은 폭·큰 글자 | 참석자 목록과 응답 버튼 행은 줄바꿈(`wrap`) | `Stack wrap` |
+
+## 꼭 지킬 것
+
+- `onResponseChange`는 실제 저장이 끝난 뒤 resolve하고, 서버가 확인한 `state`를 다시 넘긴다. 참석자 수를 제품에서 따로 더하지 않는다(제안 수는 요청 시작 때 한 번 계산한다).
+- 캘린더 추가는 실제 기기·계정 캘린더 어댑터를 연결한다. 성공하면 버튼이 `calendarAdded` 문구로 바뀌고 비활성된다.
+- 참석자 목록·권한·알림은 제품 데이터다. 카드 안 배치를 제품 레이아웃으로 다시 조립하지 않는다.
+
+## 상태와 상호작용
+
+| 상태 | 모습 | 동작 |
+| --- | --- | --- |
+| 기본 | 현재 응답 버튼 `selected` | 같은 응답·비활성 응답 누름은 무시 |
+| 진행 중 | 제안 응답 선택·수 반영, 해당 버튼 로딩, 모든 행동 잠금 | 캘린더 요청 중에는 캘린더 버튼만 로딩, 응답·수는 `state` 그대로 |
+| 실패 | `state`로 복귀, `labels.error` 중앙 표시 | Web `role="alert"`, Native `accessibilityRole="alert"`·assertive. 같은 행동으로 재시도 |
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 진행 중 이름 | `aria-label={labels.pending}` | `loadingLabel={labels.pending}` |
+| 기본 아바타 | `Avatar aria-hidden` | `Avatar decorative` |

package/docs/usage/components/expandable-search.md

@@ -0,0 +1,105 @@
+# ExpandableSearch
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: [검색·메시지 연결 계약](../../communication.md), `src/communication.ts`의 `SearchResponse`, 양 renderer `src/communication.tsx`
+- 스토리북: `배포/구성/선택과 필터/펼치는 상단 검색`
+
+## 언제 쓰나
+
+평소에는 검색 열기 버튼 하나만 두고, 누르면 그 자리에서 검색 입력·제안·최근 검색·결과를 펼칠 때 쓴다.
+Lucian 027의 펼침 검색을 기존 `SearchScreen`의 두 단계 검색·debounce·AbortSignal에 연결한 구성이다.
+펼침 상태·검색어·최근 검색은 제품이 소유하고, 현재 검색어와 맞는 최신 응답만 표시한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 검색이 화면의 본문 전체 | `SearchScreen` |
+| 입력란 하나만 필요 | `SearchField` |
+| 명령 실행 팔레트 | `CommandPalette` |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ExpandableSearch` | 열기 버튼 ↔ 펼친 검색(입력·제안·결과) | `@hjmds/react/communication` | `@hjmds/react-native/communication` |
+
+`SearchResponse<T>` 타입은 `@hjmds/design-contracts/communication`에 있다. root barrel에는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ExpandableSearch } from "@hjmds/react/communication";
+
+<ExpandableSearch<Doc[]> expanded={expanded} onExpandedChange={setExpanded} query={query} onQueryChange={setQuery}
+  onSearch={(value, { signal }) => api.searchDocs(value, { signal })} // { result, suggestions }
+  renderResult={docs => <DocList docs={docs} />}
+  onSubmit={value => saveRecent(value)} recentQueries={recentQueries}
+  labels={{ title: t("search.title"), open: t("search.open"), cancel: t("search.close"), query: t("search.query"),
+    clear: t("search.clear"), searching: t("search.searching"), error: t("search.failed"),
+    commit: value => t("search.commit", { value }), suggestionCount: count => t("search.suggestions", { count }) }} />
+```
+
+```tsx
+// Native
+import { ExpandableSearch } from "@hjmds/react-native/communication";
+
+<ExpandableSearch<Doc[]> expanded={expanded} onExpandedChange={setExpanded} query={query} onQueryChange={setQuery}
+  onSearch={(value, { signal }) => api.searchDocs(value, { signal })}
+  renderResult={docs => <DocList docs={docs} />}
+  onSubmit={value => saveRecent(value)} recentQueries={recentQueries}
+  labels={searchLabels} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| expanded / onExpandedChange | boolean / fn | 필수 | 펼침 상태(제품 소유) |
+| query / onQueryChange | string / fn | 필수 | 검색어(제품 소유) |
+| onSearch | (query, { signal }) => Promise\<SearchResponse\<T\>\> | 필수 | 실제 결과와 `suggestions`. 빈 입력은 호출하지 않음 |
+| renderResult | (result: T) => ReactNode | 필수 | 현재 검색어의 결과 렌더 |
+| onSubmit | (query) => void | 없음 | Enter·제안·최근 검색 확정 시 trim된 값 |
+| recentQueries | SearchRecentQueries | 없음 | SearchScreen 최근 검색 슬롯 |
+| debounceMs | number | 300 | SearchScreen `searchScreenRecipe.debounceMs` |
+| disabled | boolean | false | 열기 버튼 비활성 |
+| labels | object | 필수 | title·open·cancel·query·clear·searching·error·commit·suggestionCount |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 접힘: Button(primary) 하나. 펼침: SearchScreen 규격 | 양 renderer |
+| 간격 | 세로 sm | 양 renderer |
+| 순서·정렬 | 접힘: 열기 버튼. 펼침: 닫기(ghost) → SearchScreen(제목 숨김, 입력·제안·결과) → 오류(가로 중앙) | 양 renderer |
+| 고정·스크롤 | 결과 스크롤은 SearchScreen·바깥 host 소유 | 별도 scroller 없음 |
+| 좁은 폭·큰 글자 | SearchScreen 입력·제안 규칙을 그대로 따름 | SearchScreen |
+
+## 꼭 지킬 것
+
+- `onSearch`는 `signal`을 실제 요청에 전달한다. 신호를 무시해도 늦은 응답은 표시되지 않지만 서버 부하는 남는다.
+- 최근 검색 저장·분석은 `onSubmit`에서만 한다. 타이핑 중 자동 기록하지 않는다.
+- 닫아도 검색어는 지우지 않는다. 지울지는 제품이 `query`로 정한다.
+
+## 상태와 상호작용
+
+| 상태 | 모습 |
+| --- | --- |
+| 접힘 | 열기 버튼만 표시. 진행 중 요청은 abort |
+| 펼침 | 검색 입력으로 포커스. 입력 변경마다 debounce 뒤 검색 |
+| 검색 중 | SearchScreen `searching` 표시 |
+| 실패 | 입력 유지, 아래 중앙 오류. 편집·재검색으로 재시도 |
+| 닫기 | 요청 abort 후 `onExpandedChange(false)` |
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 닫은 뒤 | 열기 버튼으로 포커스 복원 | 키보드를 내림 |
+| 입력 | SearchScreen 기본 입력 | `SearchField`(busy 표시, return 키 `search`로 확정) |
+| 실패 알림 | `role="alert"` | `accessibilityRole="alert"`·assertive |

package/docs/usage/components/file-picker.md

@@ -67,6 +67,7 @@ import { FilePicker } from "@hjmds/react-native/file-picker";
 | `existingCount` | 0 이상 정수 | `0` | 여러 번 나눠 고르는 흐름은 이미 고른 개수를 넘겨야 `maxCount`가 누적으로 판정된다 |
 | `descriptor` | `{ mode?, accept?: readonly string[], maxSizeBytes?, maxCount? }` | — | `accept`는 MIME 패턴(`image/*`) 또는 확장자(`.pdf`). 비우면 제한 없음 |
 | `onSelect` | `(result: { accepted: readonly FilePickerCandidate[]; rejected: readonly FilePickerRejection[] }) => void` | 필수 | 받아들인 것과 거부한 것을 한 번에 준다 |
+| Web `onSelect` 두 번째 인자 `files` | `ReadonlyMap<string, File>` | — | 받아들인 후보 id → 브라우저 `File`. 제품이 내용을 읽거나 올릴 때 쓴다. 거부된 파일은 들어 있지 않다. 미게시(1.18.0 이후). Native는 `onPick` adapter가 파일 참조를 소유한다 |
 | Native `onPick` | `() => Promise<readonly FilePickerCandidate[] \| null>` | 필수 | 제품 adapter. 취소면 `null` |
 | Native `onPickError` | `(error: unknown) => void` | 필수 | `onPick`이 reject하면 이쪽으로만 온다 |
 | Web `getCandidateId` | `(file: File, index: number) => string` | `name:size:lastModified:index` | 후보 id 규칙 |
@@ -121,3 +122,7 @@ import { FilePicker } from "@hjmds/react-native/file-picker";
 2026-10-07 소비 감사에서 Native 선택 버튼의 모서리 12가 프로필을 우회했다. Web 버튼의 기존 `radius.md`와 같은 역할을 Native도 가까운 프로필에서 읽으며, 프로필이 없으면 기존 12를 유지한다. 선택 어댑터·비활성/진행 상태·파일 검증은 바꾸지 않는다.
 
 프로필 연결은 1.16.0 변경이며, 기본 배포 계약과 실제 Native 기기 검증은 구분한다.
+
+## 근거
+
+- Web `onSelect`의 `files` 인자: 2026-10-17 목업 편집 화면 검토 — 제품이 고른 `File`을 받을 방법이 없어 화면이 브라우저 기본 `<input type="file">`(영어 "Choose File")로 조립돼 있었다.

package/docs/usage/components/filter-recovery.md

@@ -0,0 +1,97 @@
+# FilterRecovery
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: [목록 편집 계약](../../collection-editing.md), `src/collection-editing.ts`의 `recoverableFilters`, 양 renderer `src/collection-editing.tsx`
+- 스토리북: `배포/구성/피드백과 복구/검색 필터 완화`
+
+## 언제 쓰나
+
+검색·필터 결과가 비었을 때 실제로 결과가 생기는 필터 완화 제안을 보여 주고, 사용자가 고른 하나를 명시적으로 적용할 때 쓴다.
+`resultCount`가 0인 제안은 숨긴다. 적용 실패 시 현재 필터를 유지하고 같은 버튼으로 재시도한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 완화 제안 없는 단순 빈 결과 | `EmptyState` |
+| 검색 화면 전체 틀과 결과 없음 이유 | `SearchScreen` |
+| 적용된 필터 목록 해제 | `SearchScreen`의 `appliedFilters` |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `FilterRecovery` | 결과가 있는 필터 완화 제안과 적용 | `@hjmds/react/collection-editing` | `@hjmds/react-native/collection-editing` |
+
+`FilterRecoveryOption` 타입과 `recoverableFilters`는 `@hjmds/design-contracts/collection-editing`에 있다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { FilterRecovery } from "@hjmds/react/collection-editing";
+
+{results.length === 0 ? <FilterRecovery title={t("search.noMatch")} description={t("search.relaxHint")}
+  options={relaxOptions /* 서버가 센 resultCount */}
+  optionLabel={option => t("search.relaxOption", { label: option.label, count: option.resultCount })}
+  errorLabel={t("search.applyFailed")} onApply={async id => { await applyRelaxation(id); }} /> : resultList}
+```
+
+```tsx
+// Native
+import { FilterRecovery } from "@hjmds/react-native/collection-editing";
+
+{results.length === 0 ? <FilterRecovery title={t("search.noMatch")} description={t("search.relaxHint")}
+  options={relaxOptions}
+  optionLabel={option => t("search.relaxOption", { label: option.label, count: option.resultCount })}
+  errorLabel={t("search.applyFailed")} onApply={async id => { await applyRelaxation(id); }} /> : resultList}
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| title | string | 필수 | 결과 없음 제목(강조) |
+| description | string | 없음 | 보조 설명(muted) |
+| options | FilterRecoveryOption[] | 필수 | `{ id, label, resultCount }`. id는 서로 다르고 비지 않아야 함 |
+| optionLabel | (option) => string | 필수 | 제안 버튼 문구 |
+| onApply | (id) => void \| Promise | 필수 | 실제 필터 변경. 실패하면 reject |
+| errorLabel | string | 필수 | 적용 실패 안내 |
+| disabled | boolean | false | 모든 제안 비활성 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 기존 Button(secondary)·Text 규격 | 양 renderer |
+| 간격 | 세로 sm | 양 renderer |
+| 순서·정렬 | 제목 → 설명 → 제안 버튼들(`options` 순서) → 오류, 모두 가로·세로 중앙 | 양 renderer, VQ-09 |
+| 고정·스크롤 | 결과 영역 host 소유 | 별도 scroller 없음 |
+| 좁은 폭·큰 글자 | 버튼을 세로로 쌓아 각 행 전체 문구 유지 | 양 renderer |
+
+빈 결과 영역 안에 그대로 넣는다. 앱이 임의 상단 여백으로 위치를 맞추지 않는다.
+
+## 꼭 지킬 것
+
+- `resultCount`는 제품 데이터에서 센 음이 아닌 안전 정수다. 어기면 렌더 중 `RangeError`가 난다. 추정치를 넣지 않는다.
+- 중복·빈 `id`는 `TypeError`다.
+- 적용 결과로 생긴 실제 목록은 제품이 다시 그린다. 이 구성은 결과를 만들지 않는다.
+
+## 상태와 상호작용
+
+| 상태 | 모습 |
+| --- | --- |
+| 기본 | 결과가 있는 제안만 secondary 버튼으로 표시 |
+| 적용 중 | 누른 버튼 로딩, 다른 제안 비활성 |
+| 실패 | 필터 유지, 중앙 오류, 같은 버튼으로 재시도 |
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 그룹 | `role="group"`, 이름은 `title` | 접근성 그룹 없음 |
+| 실패 알림 | `role="alert"` | `accessibilityRole="alert"`·assertive, iOS는 announce |

package/docs/usage/components/follow-profile-card.md

@@ -0,0 +1,100 @@
+# FollowProfileCard
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: [팔로우 프로필과 행사 참석 계약](../../social-compositions.md), `src/social-compositions.ts`의 `resolveFollowProposal`, 양 renderer `src/social-compositions.tsx`
+- 스토리북: `배포/구성/정보 표시/팔로우 프로필`
+
+## 언제 쓰나
+
+프로필 카드에서 팔로우·팔로잉 전환과 팔로워 수를 실제 mutation 결과와 함께 보여 줄 때 쓴다.
+Lucian 054를 소비 앱마다 다시 조립하지 않도록 Card·Avatar·Button·AnimatedStatistic과 action-session을 합성했다.
+요청 중에는 제안 상태와 수치를 한 번 캡처해 낙관적으로 보여 주고, 실패하면 확정 상태로 돌아간다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 팔로우 행동이 없는 프로필 정보 | `Card` + `Avatar` 또는 `ProfileSummary` |
+| 프로필 화면 전체 틀 | `ProfileScreen`(이 카드를 본문에 넣을 수 있음) |
+| 행사 참석 응답 | `EventAttendanceCard` |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `FollowProfileCard` | 프로필·팔로워 수·팔로우 전환 | `@hjmds/react/social-compositions` | `@hjmds/react-native/social-compositions` |
+
+`FollowProfileState`와 `resolveFollowProposal`은 `@hjmds/design-contracts/social-compositions`에 있다. root barrel에는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { FollowProfileCard } from "@hjmds/react/social-compositions";
+
+<FollowProfileCard profileId={profile.id} name={profile.name} description={profile.bio}
+  avatar={<ProfileImage src={profile.avatarUrl} />} locale={locale} state={{ following, count }}
+  labels={{ follow: t("follow"), following: t("following"), pending: t("followPending"),
+    count: t("followers"), error: t("followFailed") }}
+  onFollowChange={async next => { const confirmed = await api.setFollow(profile.id, next); setFollowState(confirmed); }} />
+```
+
+```tsx
+// Native
+import { FollowProfileCard } from "@hjmds/react-native/social-compositions";
+
+<FollowProfileCard profileId={profile.id} name={profile.name} description={profile.bio}
+  avatar={<ProfileImage source={{ uri: profile.avatarUrl }} />} locale={locale} state={{ following, count }}
+  labels={followLabels}
+  onFollowChange={async next => { const confirmed = await api.setFollow(profile.id, next); setFollowState(confirmed); }} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| profileId | string | 필수 | 비면 `TypeError`. 바뀌면 작업 범위를 remount |
+| name | string | 필수 | Card 제목, 기본 Avatar 이름 |
+| description | ReactNode | 없음 | Card 설명 |
+| avatar | ReactNode | 이름 기반 `Avatar`(장식) | 제품 이미지 host |
+| state | `{ following, count }` | 필수 | 서버가 확정한 상태. count는 현재 사용자 포함 |
+| locale | string | 필수 | 수치 형식 |
+| labels | follow·following·pending·count·error | 필수 | 현지화 문구 |
+| onFollowChange | (following) => void \| Promise | 필수 | 실제 요청. 성공 전에 확정 state로 갱신, 실패는 reject |
+| disabled | boolean | false | 버튼 비활성 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | Card·Avatar·Button 기본 규격 | 양 renderer |
+| 간격 | 카드 본문 세로 md | 양 renderer |
+| 순서·정렬 | Card(leading 아바타, 제목, 설명) → 팔로워 수(AnimatedStatistic) → 팔로우 버튼 → 오류(가로 중앙) | 양 renderer |
+| 고정·스크롤 | 바깥 화면 host 소유 | 별도 scroller 없음 |
+| 좁은 폭·큰 글자 | Card 기본 배치를 따름 | Card |
+
+## 꼭 지킬 것
+
+- `state`는 서버 확정값만 전달한다. `following: true`인데 `count: 0`이면 `RangeError`다.
+- 성공 callback 안에서 서버 snapshot으로 state를 갱신한 뒤 resolve한다. HJM이 성공 수치를 만들지 않는다.
+- 다른 프로필로 바뀌면 `profileId`를 바꾼다. 이전 프로필의 늦은 응답은 새 카드의 오류를 바꾸지 않지만, 제품 캐시 기록은 제품이 맞춘다.
+
+## 상태와 상호작용
+
+| 상태 | 모습 |
+| --- | --- |
+| 기본 | 확정 수치, `following`이면 selected 버튼과 following 문구 |
+| 진행 중 | 제안 상태·수치(±1)를 한 번 캡처해 표시, 버튼 로딩. 같은 요청 중복은 session이 직렬화 |
+| 실패 | 확정 props로 복원, 중앙 오류, 같은 버튼으로 재시도 |
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 진행 중 이름 | 버튼 `aria-label`=pending | Button `loadingLabel`=pending |
+| 기본 아바타 | `Avatar aria-hidden` | `Avatar decorative` |
+| 수치 전환 의존성 | `statistic-motion`의 `@number-flow/react` peer 필요 | 기존 ContentTransition |

package/docs/usage/components/heading.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.12.1
-- 검토일: 2026-10-07
+- 검토일: 2026-10-17
 - 근거: [Heading](../../heading.md), recipe `headingRecipe`(`src/heading.ts`)
 - 스토리북: `배포/컴포넌트/글자와 아이콘/제목`
 
@@ -48,7 +48,7 @@ import { Heading } from "@hjmds/react-native/heading";
 
 | prop | 값 | 기본값 | 설명 |
 | --- | --- | --- | --- |
-| `level`(필수) | `level1` 40px · `level2` 32px · `level3` 24px · `level4` 20px · `level5` 18px | — | recipe 기본은 `level3`이지만 두 renderer 모두 prop을 필수로 받는다 |
+| `level`(필수) | `level1` 40px/700 · `level2` 32px/700 · `level3` 24px/600 · `level4` 20px/600 · `level5` 18px/600 | — | recipe 기본은 `level3`이지만 두 renderer 모두 prop을 필수로 받는다 |
 | `semanticLevel` | 1~6 | `level`의 숫자 | 크게 보이지만 구조상 h4인 카드 제목처럼 시각 크기와 문서 단계가 다르면 둘을 따로 적는다 |
 | `layoutStyle` | 배치 key(margin·폭·정렬 등) | — | 바깥 배치만. 크기·줄 높이·굵기·색은 받지 않는다 |
 
@@ -86,6 +86,10 @@ import { Heading } from "@hjmds/react-native/heading";
 | 배치 | `layoutStyle`. `style`도 합쳐진다(크기 변수는 덮이지 않음) | `layoutStyle`. `style`(TextStyle)은 제거된 속성 — `layoutStyle` 또는 `level` |
 | 글자 배율 | `--hjm-text-scale`로 확대 | Native `Text`의 글자 배율 |
 
+## 근거
+
+2026-10-17 사용자 결정: `level1`·`level2`는 Pretendard 800이 큰 크기에서 무겁고 거칠어 700(bold)으로 낮췄다. 같은 날 600으로 낮춘 `level3`~`level5`보다 한 단계 굵게 유지한다. Native는 `fonts="pretendard"`일 때 `Pretendard-Bold` face로 그린다. `Top size="large"` 제목도 `heading.level2`라 함께 700이 된다. 브루탈리즘 프리셋은 level1·2를 800으로 명시한다.
+
 ## 함정
 
 - Web `style`은 이제 버려지지 않고 합쳐진다. 다만 크기·줄 높이·굵기 변수(`--hjm-heading-*`)는 recipe가 마지막에 덮으므로

package/docs/usage/components/histogram-explorer.md

@@ -0,0 +1,89 @@
+# HistogramExplorer
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: [데이터 해석과 가져오기 계약](../../data-workflows.md), `src/data-workflows.ts`의 `binHistogram`, 양 renderer `src/data-workflows.tsx`
+- 스토리북: `배포/구성/정보 표시/분포 구간 탐색`
+
+## 언제 쓰나
+
+실제 관측값 배열의 분포를 동폭 구간 막대로 보여 주고, 사용자가 구간 수를 바꿔 볼 때 쓴다.
+Lucian 130·160–164 검토에서 별도 차트 엔진 대신 BarChart를 합성하기로 한 데이터 구성의 하나다.
+구간 수를 바꿔도 모든 선택지의 최대 count로 y축을 고정해 막대 높이의 의미가 바뀌지 않는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 이미 집계된 범주 값 | `BarChart` |
+| 시간에 따른 추이 | `LineChart` |
+| 단계별 감소 | `ConversionFunnel` |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `HistogramExplorer` | 구간 수 선택 + 분포 막대 + 요약 | `@hjmds/react/data-workflows` | `@hjmds/react-native/data-workflows` |
+
+`binHistogram`·`HistogramBin`은 `@hjmds/design-contracts/data-workflows`에 있다. root barrel에는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { HistogramExplorer } from "@hjmds/react/data-workflows";
+
+<HistogramExplorer label={t("stats.duration")} samples={durations /* null = 미관측 */} domain={[0, 10]}
+  binCounts={[2, 4, 8]} binCount={binCount} onBinCountChange={setBinCount}
+  binLabel={bin => `${format(bin.lower)}–${format(bin.upper)}`} binCountLabel={count => t("stats.bins", { count })}
+  formatCount={String} missingLabel={t("stats.unobserved")}
+  summaryLabel={h => t("stats.summary", { observed: h.observed, missing: h.missing, outside: h.underflow + h.overflow })} />
+```
+
+```tsx
+// Native
+import { HistogramExplorer } from "@hjmds/react-native/data-workflows";
+
+<HistogramExplorer label={t("stats.duration")} samples={durations} domain={[0, 10]}
+  binCounts={[2, 4, 8]} binCount={binCount} onBinCountChange={setBinCount}
+  binLabel={binLabel} binCountLabel={binCountLabel} formatCount={String}
+  missingLabel={t("stats.unobserved")} summaryLabel={summaryLabel} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| label | string | 필수 | 제목, 차트 접근성 이름 |
+| samples | (number \| null)[] | 필수 | 유한 값 또는 null(미관측) |
+| binCounts | number[] | 필수 | 서로 다른 구간 수 선택지(각 1–100), `binCount` 포함 |
+| binCount / onBinCountChange | number / fn | 필수 | 선택한 구간 수(제품 소유) |
+| domain | [number, number] | 관측 최소·최대 | 지정하면 범위 밖 값을 underflow/overflow로 셈 |
+| binLabel / binCountLabel / formatCount | fn | 필수 | 구간·선택지·count 문구 |
+| missingLabel | string | 필수 | 관측값이 없을 때와 차트 결측 문구 |
+| summaryLabel | (histogram) => string | 필수 | observed·missing·underflow·overflow 요약 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | BarChart 기본 규격, 값 표시(`showValues`) | 양 renderer |
+| 간격 | 세로 md, 구간 선택 버튼 sm | 양 renderer |
+| 순서·정렬 | 제목 → 구간 수 버튼(secondary, 선택 강조) → 막대 → 요약 | 양 renderer |
+| 고정·스크롤 | 바깥 화면 host 소유 | 별도 scroller 없음 |
+| 좁은 폭·큰 글자 | 구간 수 버튼 `wrap` 줄바꿈 | 양 renderer |
+
+관측값이 하나도 없으면 막대 대신 `missingLabel`을 가로 중앙에 둔다.
+
+## 꼭 지킬 것
+
+- `binCounts`가 비었거나, `binCount`를 포함하지 않거나, 중복이 있으면 `RangeError`다.
+- 구간은 동폭이며 마지막 구간만 상한을 포함한다. 무한대·NaN 샘플은 `RangeError`다.
+- y축은 모든 선택지의 최대 count로 고정된다. 앱이 구간마다 다시 정규화하지 않는다.
+
+## 상태와 상호작용
+
+구간 수 버튼은 `onBinCountChange`만 호출한다. 요약은 Web `role="status"`, Native polite live region으로 갱신을 알린다.