@hjmds/design-contracts 1.13.1 → 1.14.0

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

@@ -118,3 +118,13 @@ import { SearchField } from "@hjmds/react-native/inputs";
 | 진행 중 입력 | 입력 가능(`aria-busy`) | 입력 가능(`accessibilityState.busy`). 2026-10-06까지 Native는 `busy`인 동안 입력을 무시했다(1.12.1 이후 미게시) |
 | 입력 요소 | `<input type="search">`, 원시 `onChange`도 전달 | `TextInput` |
 | 배치 | `layoutStyle`·`fieldClassName`(필드 틀), `style`은 안쪽 input | `layoutStyle` |
+
+
+### 고정 아이콘과 큰 글자
+
+2026-10-06 최근 검색 삭제 기호가 큰 글자에서 잘린 재현에 따라 Native 내장 삭제·메뉴 기호는 고정 아이콘 틀의 크기를 유지한다. 주변 제목·라벨은 계속 확대한다. Chip의 체크와 Toast 닫기는 기존 비확대 경로를 유지하며 회귀 검사에 포함한다. 제품이 전달한 아이콘 슬롯은 제품이 같은 조건을 검증한다.
+
+### 브라우저 지우기 중복 방지
+
+Web은 type=search를 유지하지만 브라우저 기본 cancel 장식은 숨긴다. 2026-10-07 빈 상태 복구
+실측에서 ×가 두 개 보였기 때문이다. 실제 지우기는 HJM 버튼의 clearLabel·onClear·초점 복귀로 한다.

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

@@ -219,3 +219,8 @@ import { SearchScreen } from "@hjmds/react-native/screen-flows";
   떨어졌다. utilverse는 `onSubmit`에서 `Keyboard.dismiss()`를 불렀다(2026-10-06). 1.13.1부터 SearchScreen이 닫으므로 그 호출을 지운다.
 - 1.13.0 이하에서는 `contentInset="none"`이면 `scroll` 줄이 전혀 넓어지지 않아 host 여백(Container·Sheet)에서 잘렸다. 1.13.1부터 `hostGutter`로 맞춘다.
 - 시트 안 SearchScreen은 Sheet `size`를 `auto` 밖으로 주고 `scrollable` 없이 넣는다. 1.13.0 이하 Native는 이때 화면이 0pt가 됐다([Sheet 함정](sheet.md#함정)).
+
+
+### 고정 아이콘과 큰 글자
+
+2026-10-06 최근 검색 삭제 기호가 큰 글자에서 잘린 재현에 따라 Native 내장 삭제·메뉴 기호는 고정 아이콘 틀의 크기를 유지한다. 주변 제목·라벨은 계속 확대한다. Chip의 체크와 Toast 닫기는 기존 비확대 경로를 유지하며 회귀 검사에 포함한다. 제품이 전달한 아이콘 슬롯은 제품이 같은 조건을 검증한다.

package/docs/usage/components/segmented-control.md

@@ -144,3 +144,20 @@ Native는 `@hjmds/react-native/inputs`에서 같은 prop을 사용한다. `prese
   1.13.1부터는 레일 안에서 한 줄로 남으므로 그 분기를 지운다. 1.13.0에 머무는 제품만 우회를 유지한다.
 - 레일(가로 스크롤)은 바깥이 만든다. SearchScreen 안이면 `filtersOverflow="scroll"`, 그 밖이면 제품의 가로 ScrollView다.
   `pills`가 스스로 스크롤하지 않는 이유는 레일 안에 두 번째 가로 스크롤을 겹치지 않기 위해서다.
+
+
+### 선택 배경 이동
+
+2026-10-07 Animated Background 비교에서 시각적 선택만 있는 외부 예제를 그대로 교체하면 radio/checked 의미를 잃는 것을 확인했다.
+`selectionMotion="slide"`는 기존 선택 엔진·키보드·접근성 이름·입력 위치를 유지하고 배경만 측정 위치로 이동한다.
+Web은 항목과 바깥 선택 영역의 크기를 함께 관찰한다. 2026-10-07 RTL pills에서 항목 너비는
+그대로인 채 부모 폭만 바뀌면 선택 배경이 이전 위치에 남는 오류를 수정했다. 크기 변경에는
+이동 모션을 재생하지 않고 새 위치에 맞춘다.
+기본은 `"none"`이며 opt-in 실험이다. 별도 버튼/선택 상태를 만들어 기존 라디오를 대체하지 않는다.
+
+- Web/Native 모두 `connected`와 `pills`에 적용한다. 큰 글자·RTL·줄바꿈에서는 실제 항목 위치를 측정한다.
+- 최초 배치와 resize는 즉시 맞추며 선택이 바뀔 때만 HJM `motion.normal` 시간으로 이동한다.
+- 모션 감소와 비활성 화면에서는 이동 효과를 중지한다. 동작 중인 입력·선택 값은 그대로다.
+- 조작 가능 영역·글자는 움직이거나 확대하지 않는다. 새 사용 예제는 [선택 배경 이동](../compositions/selection-motion.md)이다.
+
+2026-10-07 큰 글자 UI 확인에서 Web 2배 글자 줄은 40px인데 pill 배경은 28px였다. Native처럼 세로 padding에도 pills.inset(spacing.xs=8px)을 적용해 배경이 전체 줄을 감싸게 했다. 고정 높이를 늘리는 대신 줄 높이를 따라가므로 3배·줄바꿈도 유지한다.

package/docs/usage/components/statistic.md

@@ -121,3 +121,14 @@ import { Statistic } from "@hjmds/react-native/data-display";
 - Web `AnimatedStatistic`은 reduced motion, RTL, 라틴 숫자가 아닌 numbering system, `ar`·`fa`·`he`·`ur` locale,
   `scientific`·`engineering` 표기에서는 애니메이션 없이 `Intl` 결과 문자열만 그린다.
 - `AnimatedStatistic`의 `descriptor`에는 `value`를 넣지 않는다. 값은 `value` prop의 숫자로 받는다.
+
+### 외부 숫자 효과 대조
+
+2026-10-07 Number Ticker 공식 소스와 기본 데모를 대조했다. 진입 시 중간 숫자를 표시하는
+효과와 실제 값 변경은 구분한다. 현재 AnimatedStatistic의 Intl locale과 RTL·비라틴 숫자·
+지수 표기 fallback을 유지하며 별도 count-up 엔진을 추가하지 않는다. 숫자가 올라가는 효과를
+실제 집계 과정으로 오해시키지 않기 위해 제품은 확정한 값을 전달한다.
+
+양쪽 움직이는 수치 Storybook에 소수와 음수(de-DE), 비라틴 숫자(ar-EG), 지수 표기(en-US),
+동작 줄이기와 RTL 비교를 제공한다. 소수·음수 예제는 기록 개수가 아닌 측정값이다.
+Web은 자리 단위 전환, Native는 지표 전체 전환이며 같은 시각 효과를 보장하지 않는다.

package/docs/usage/components/tags-input.md

@@ -109,3 +109,8 @@ import { TagsInput } from "@hjmds/react-native/tags-input";
 | 후보 이동 | ArrowUp/Down(끝에서 순환) | 후보를 버튼으로 누름 |
 | ref | `forwardRef`(`input`) | 없음 |
 | 스타일 prop | `className`, `layoutStyle` | `layoutStyle`(`style`은 deprecated) |
+
+
+### 고정 아이콘과 큰 글자
+
+2026-10-06 최근 검색 삭제 기호가 큰 글자에서 잘린 재현에 따라 Native 내장 삭제·메뉴 기호는 고정 아이콘 틀의 크기를 유지한다. 주변 제목·라벨은 계속 확대한다. Chip의 체크와 Toast 닫기는 기존 비확대 경로를 유지하며 회귀 검사에 포함한다. 제품이 전달한 아이콘 슬롯은 제품이 같은 조건을 검증한다.

package/docs/usage/components/toast.md

@@ -143,3 +143,8 @@ function useProfileSavedToast() {
   어댑터는 render 밖에서 만들거나 memo한다.
 - ToastRegion 배치는 `layoutStyle={{ flex: 1 }}`로 쓴다. Native 예제도 이 경로를 사용한다.
 - Web `Toast` 단독 렌더는 나머지 HTML 속성(id·data-*·이벤트)을 루트에 전달한다(미게시(1.12.1 이후). 1.12.1은 `className`만 전달). `role`·`aria-labelledby`·`aria-describedby`·`data-tone`·`data-state`는 Toast가 정하므로 덮이지 않는다. 배치는 Provider를 쓴다.
+
+
+### 고정 아이콘과 큰 글자
+
+2026-10-06 최근 검색 삭제 기호가 큰 글자에서 잘린 재현에 따라 Native 내장 삭제·메뉴 기호는 고정 아이콘 틀의 크기를 유지한다. 주변 제목·라벨은 계속 확대한다. Chip의 체크와 Toast 닫기는 기존 비확대 경로를 유지하며 회귀 검사에 포함한다. 제품이 전달한 아이콘 슬롯은 제품이 같은 조건을 검증한다.

package/docs/usage/components/upload-item.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.12.1
-- 검토일: 2026-10-06
+- 검토일: 2026-10-07
 - 근거: [UploadItem](../../upload-item.md), `src/upload-item.ts`(`uploadItemRecipe`)
 - 스토리북: `배포/컴포넌트/데이터 표시/업로드 항목`
 
@@ -84,6 +84,8 @@ import { UploadItem } from "@hjmds/react-native/upload-item";
 
 ## 꼭 지킬 것
 
+- 이미 게시된 문서를 열거나 내려받는 목록에 `success` 상태를 전용하지 않는다. 이 API의 행동은 업로드 취소·재시도이며 다운로드 행동이 아니다. Web 다운로드는 [Link](link.md), 미리보기와 여러 행동은 [Card](card.md)를 대조한다. 2026-10-07 파일 사례 조사에서 다운로드와 업로드의 초기 대응표가 같은 계약으로 오인될 수 있어 구분했다.
+
 - `progress`에 100을 곱해 넘기지 않는다. renderer가 내부 Progress에 `value={progress * 100}`으로 바꾼다.
 - `uploading` 상태에서 `onCancel`이, `error` 상태에서 `onRetry`가 없으면 렌더 중 `TypeError`가 난다.
 - 바이트 포맷(`sizeLabel`)·상태 문구·`message`·업로드 요청·재시도 로직은 제품 소유다. 행 모양·상태 색·액션 결정은 HJM 소유다.

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

@@ -0,0 +1,77 @@
+# 버튼 완료 피드백
+
+- 단계: 구성
+- 상태: 배포
+- 지원: 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 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+입력을 유지하며 저장의 진행·성공·재시도 가능 실패를 보여 줄 때 쓴다. 별도 신규 wrapper API가 아니라 아래 공개 컴포넌트의 조합 규격이다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| Button · TextField · ContentTransition · action-session | 입력·표현·행동의 역할 분리 | [입력/동작](../components/button.md), [상태/전환](../components/content-transition.md) |
+
+## 배치
+
+```text
+[제목]
+[기록 제목 입력]
+[저장 / 다시 저장 버튼]
+[진행·실패·성공 결과]
+[실패 체험 스위치 + 서버 요청 없음 안내]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 화면의 본문 흐름 | gap md=16px, 전체 폭 |
+| 내용 | 해당 공개 API | 입력과 행동 사이 | 자체 recipe 크기, 줄바꿈 허용 |
+| 행동 | Button/기존 컨트롤 | 관련 항목 바로 뒤 | inline일 때 wrap, md=16px |
+
+## 흐름과 상태
+
+1. 입력→요청→실제 결과에 따라 성공/실패. 다시 저장은 클릭한 시점의 현재 초안을 새 요청으로 보낸다.
+   2026-10-07 실패 후 제목 수정·재저장 확인에서 기존 문서의 “같은 입력 재시도”와 구현이
+   다른 것을 확인했다. 편집 가능한 초안에 맞춰 현재 값 저장을 유지한다. 실패한 요청의
+   원래 값 재시도가 필요하면 별도 행동에서 action-session.retry를 연결하고 대상 값을 알린다.
+2. 서버 응답·파일 권한·문구·브랜드는 제품이 전달한다. Showcase의 예제 응답과 고정 데이터를 가져오지 않는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 입력과 사용 가능한 행동 | 조작 이름은 제품 언어 |
+| 진행 중 | 실제 작업 상태에 맞는 loading 또는 열린 도구 | 중복 요청 차단, 입력 유지 |
+| 실패 | 문구와 가능한 재시도 | 원래 입력/파일 유지, 결과 안내 |
+
+## 코드 골격
+
+```tsx
+// Web
+<Button loading={busy} onClick={save}>{busy ? pendingLabel : saveLabel}</Button>
+```
+
+```tsx
+// Native
+<Button loading={busy} onPress={save}>{busy ? pendingLabel : saveLabel}</Button>
+```
+
+Web은 `@hjmds/react`의 해당 granular entry, Native는 `@hjmds/react-native` entry를 쓴다.
+Button의 실행 콜백은 Web `onClick`, Native `onPress`로 연결한다. 위 골격의 도메인 함수·변수는 제품이 제공한다.
+
+예제 응답은 useDemoAction의 인위 지연이며 실제 네트워크·영구 저장이 아니다.
+완료 문구는 응답 확정 뒤 표시한다. 저장 중 입력 편집이 가능하므로, 저장 결과는 현재
+초안으로 바꿔 쓰지 말고 응답 값으로 표시한다. 실패 체험 설정은 요청 중 바꾸지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 배치/테마 | Stack과 HjmProvider | Stack과 HjmNativeProvider |
+| 큰 글자·좁은 폭 | 줄바꿈·단일 내용 | 같은 순서, OS 화면 검증은 별도 |

package/docs/usage/compositions/adaptive-content.md

@@ -0,0 +1,81 @@
+# 높이가 이어지는 패널
+
+- 단계: 구성
+- 상태: 배포
+- 지원: 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 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+패널의 길이가 달라질 때 아래 행동이 새 높이로 이동해야 하는 작은 내용 영역에 쓴다. 별도 신규 wrapper API가 아니라 아래 공개 컴포넌트의 조합 규격이다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| SegmentedControl · ContentTransition · Surface · TextField | 입력·표현·행동의 역할 분리 | [입력/동작](../components/segmented-control.md), [상태/전환](../components/content-transition.md) |
+
+## 배치
+
+```text
+[요약 / 상세 단일 선택]
+[높이가 바뀌는 콘텐츠 패널]
+[전환 바깥의 메모 입력: 유지]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 화면의 본문 흐름 | gap md=16px, 전체 폭 |
+| 내용 | 해당 공개 API | 입력과 행동 사이 | 자체 recipe 크기, 줄바꿈 허용 |
+| 행동 | Button/기존 컨트롤 | 관련 항목 바로 뒤 | inline일 때 wrap, md=16px |
+
+## 흐름과 상태
+
+1. 선택→내용 교체→입력은 바깥에서 유지
+2. 서버 응답·파일 권한·문구·브랜드는 제품이 전달한다. Showcase의 예제 응답과 고정 데이터를 가져오지 않는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 입력과 사용 가능한 행동 | 조작 이름은 제품 언어 |
+| 진행 중 | 실제 작업 상태에 맞는 loading 또는 열린 도구 | 중복 요청 차단, 입력 유지 |
+| 실패 | 문구와 가능한 재시도 | 원래 입력/파일 유지, 결과 안내 |
+
+## 코드 골격
+
+```tsx
+// Web
+<ContentTransition stateKey={panel} animateHeight><Panel /></ContentTransition>
+```
+
+```tsx
+// Native
+<ContentTransition stateKey={panel} animateHeight><Panel /></ContentTransition>
+```
+
+Web은 `@hjmds/react`의 해당 granular entry, Native는 `@hjmds/react-native` entry를 쓴다.
+선택은 SegmentedControl의 onValueChange로 연결한다. 패널 바깥 입력은 unmount하지 않는다.
+2026-10-07 Web 390px·큰 글자에서 상세→요약 방향키 연속 전환 뒤 단일 내용과 초안 보존을
+확인했다. 이 확인은 프레임 속도나 Native 성능 동등성의 근거가 아니다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 배치/테마 | Stack과 HjmProvider | Stack과 HjmNativeProvider |
+| 큰 글자·좁은 폭 | 줄바꿈·단일 내용 | 동일 순서와 스크롤 host 필요 |
+
+
+### Native 입력과 화면 끝
+
+2026-10-07 큰 글자에서 상세 패널이 늘어나면 키보드 아래로 메모가 밀려났고,
+스크롤 없는 Showcase canvas에서는 다시 접근할 수 없었다. Native 예제는
+ScreenLayout의 본문 스크롤과 바깥 KeyboardAvoiding으로 사용 가능한 높이를 확보한다.
+Storybook의 기존 gutter 때문에 contentInset=none을 쓰고, 마지막 입력의 테두리가
+스크롤 경계에 걸리지 않도록 본문 끝에 spacing.md(16) 여백을 둔다.
+본문 조합 자체에 두 번째 scroll view를 만들지 말고 제품의 기존 화면 host를 재사용한다.
+KeyboardAvoiding은 아래 여백을 제공하며 포커스된 필드를 자동 탐색하는 API는 아니다.

package/docs/usage/compositions/context-toolbar.md

@@ -0,0 +1,85 @@
+# 입력을 유지하는 도구
+
+- 단계: 구성
+- 상태: 배포
+- 지원: 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 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+작성 중인 입력을 보존한 채 선택적 도구를 펼쳐야 할 때 쓴다. 별도 신규 wrapper API가 아니라 아래 공개 컴포넌트의 조합 규격이다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| TextField · Collapsible · SegmentedControl | 입력·표현·행동의 역할 분리 | [입력](../components/field.md), [접기](../components/collapsible.md), [단일 선택](../components/segmented-control.md) |
+
+## 배치
+
+```text
+[작성 중인 입력: 항상 유지]
+[도구 펼침/접힘 버튼 · 현재 선택]
+  [기본 | 인용 | 강조] 열린 동안만 표시
+[선택한 표현 안내: 항상 유지]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 화면의 본문 흐름 | gap md=16px, 전체 폭 |
+| 도구 | Collapsible | 입력 바로 아래 | trigger 최소 높이44px, 공개 recipe 사용 |
+| 선택 | SegmentedControl presentation=pills | 열린 도구 내용 | 최소 높이44px, 항목 간8px, 좁으면 줄바꿈 |
+| 결과 안내 | Text | 도구 아래 | Web status/Native polite |
+
+## 흐름과 상태
+
+1. 입력→도구 펼침→단일 표현 선택→접힘; 입력은 도구 바깥에 유지. 선택 값도 접히는 내용의 바깥에서 소유한다.
+   2026-10-07 실제 조작에서 개별 selected Button이 독립 토글로 안내되는 것을 확인해,
+   묶음 이름·radio 의미·방향키 이동을 제공하는 SegmentedControl을 사용한다.
+   여러 서식을 동시에 켜는 편집기는 ToggleGroup을 쓰며 이 단일 선택 예제를 복사하지 않는다.
+2. 서버 응답·파일 권한·문구·브랜드는 제품이 전달한다. Showcase의 예제 응답과 고정 데이터를 가져오지 않는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 접힌 도구: 입력·펼침 버튼·현재 선택 안내 | 숨긴 선택지는 탐색 대상에서 제거 |
+| 진행 중 | 도구를 펼쳐 단일 선택; 비동기 pending 없음 | Web Tab으로 선택 진입, 방향키로 변경 |
+| 선택 변경 | 정확히 하나 선택, 안내 갱신 | 초안 유지, 선택 값은 바깥 상태에 저장 |
+| 다시 접힘/펼침 | 마지막 선택과 초안 복원 | Web 접기 버튼에 포커스 유지 |
+| 실패 | 예제에 서버 작업 없음; 제품 저장 실패는 별도 연결 | 실제 저장 실패 시에도 초안·선택은 보존 |
+
+## 코드 골격
+
+```tsx
+// Web
+<TextField label={draftLabel} value={draft} onValueChange={setDraft} />
+<Collapsible open={open} onOpenChange={setOpen} trigger={toolsLabel}>
+  <SegmentedControl label={formatLabel} presentation="pills" items={formats}
+    value={format} onValueChange={setFormat} />
+</Collapsible>
+```
+
+```tsx
+// Native
+<TextField label={draftLabel} value={draft} onValueChange={setDraft} />
+<Collapsible open={open} onOpenChange={setOpen} trigger={toolsLabel}>
+  <SegmentedControl label={formatLabel} presentation="pills" items={formats}
+    value={format} onValueChange={setFormat} />
+</Collapsible>
+```
+
+Web은 `@hjmds/react`의 해당 granular entry, Native는 `@hjmds/react-native` entry를 쓴다.
+초안과 선택 값은 접히는 내용 바깥에서 소유한다. 예제는 선택·입력 보존을 보여 주며,
+본문 서식 변환·영구 저장·실패 복구는 구현하지 않는다. 이 동작이 필요한 제품은
+실제 편집 모델과 저장 상태를 연결하고 따로 검증한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 배치/테마 | Stack과 HjmProvider | Stack과 HjmNativeProvider |
+| 큰 글자·좁은 폭 | 줄바꿈·단일 내용 | 같은 순서, OS 화면 검증은 별도 |

package/docs/usage/compositions/date-entry.md

@@ -0,0 +1,108 @@
+# 날짜 직접 입력
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.14.0
+- 검토일: 2026-10-07
+- 근거: [날짜 입력 조사](../../../../../docs/qa/2026-10-07-date-entry-reference.md), `src/date-entry.ts`
+- 스토리북: `배포/구성/입력과 작성/날짜 직접 입력`
+
+승급: 2026-10-07 사용자 승인, [검토 결과](../../../../../docs/qa/2026-10-07-experiment-promotion-release.md). Storybook 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+사용자가 알고 있는 날짜를 직접 입력할 때 쓴다. DatePicker는 달력에서 날짜를 선택하는 API이므로
+부분 연도·월 이름을 편집하는 초안을 담지 않는다. 새 DateEntry는 Field의 optional extension이며
+기존 TextField를 합성한다. 달력·언어·시간대 계산은 제품이 맡는 기존 Calendar 경계를 유지한다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| DateEntry | 날짜 초안·필드 순서·오류 연결 | 이 문서 |
+| TextField | 각 날짜 조각 입력·포커스·오류 | [Field](../components/field.md) |
+| Button | 제품의 확인/저장 | [Button](../components/button.md) |
+
+## 배치
+
+```text
+그룹 이름
+설명(선택)
+[연도]   [월]   [일]   ← 제품 order
+오류 안내 한 번         ← 입력 위, 해당 칸 테두리로 연결
+[확인]                ← 제품 행동
+결과/서버 상태         ← 제품 소유
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web fieldset / Native View | 제품 폼 안 | 최소 폭 0, 테두리 없는 그룹 |
+| 그룹 이름 | Web legend / Native Text label | 맨 위 | 아래 spacing.sm 12 |
+| 입력 | TextField 3개 | order 순서 | 간격 spacing.md 16, Web 최소 10ch 자동 줄바꿈, Native 기준 spacing.xxxl × 3 × textScale |
+| 오류 | 그룹 안내 + TextField invalid | 입력 위 한 번 | 해당 필드만 오류 테두리, Web 설명 ID·Native hint 연결 |
+| 확인 | 제품 Button | 그룹 다음 | DateEntry 내부에 저장 버튼을 넣지 않음 |
+
+## 흐름과 상태
+
+1. value는 `{year, month, day}` 원문 문자열이다. onValueChange는 한 필드만 바꾼 새 초안을 전달한다.
+2. order는 세 필드가 중복 없이 한 번씩 나온 배열이다. RTL만으로 날짜 순서를 추측하지 않는다.
+3. required 기본 false. 전체 공백은 optional이면 오류가 없고 일부만 비면 optional이어도 incomplete다.
+4. 모든 조각이 있으면 parse가 valid/value 또는 incomplete·invalid/code/fields를 반환한다. 입력을
+  자동 정규화하거나 다음 필드로 자동 이동하지 않는다. parse는 동결된 복사본을 받는다.
+5. showErrors 기본 false. 제품은 제출/blur 정책에 맞춰 켠다. 오류 문구는 formatIssue로 지역화한다.
+6. 목적이 birthdate일 때만 날짜 조각 자동완성을 요청한다. 일반 date는 off다. 실제 자동완성은 OS/브라우저 소유다.
+7. monthInput 기본 text는 월 이름 입력을 허용한다. 숫자만 받는 제품은 numeric을 명시한다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 세 입력과 설명 | 자동 초점 이동 없음 |
+| 진행 중 | 미완성 원문 유지 | 일반 Tab/터치로 이동, validation 노출은 제품 제어 |
+| 실패 | 그룹 오류 한 번과 해당 필드의 오류 테두리 | Web 연결된 오류 설명, Native 그룹+조각 이름·오류 hint, iOS 그룹 안내 한 번 |
+| 확인 | 제품에 전달한 valid 값 | 확인 UI/서버 저장은 제품 소유 |
+| 비활성·읽기 전용 | 편집 차단 | 호스트가 늦게 edit 이벤트를 보내도 callback 차단 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { DateEntry } from "@hjmds/react/date-entry";
+// Resolver: @hjmds/design-contracts/date-entry.
+<DateEntry value={draft} onValueChange={setDraft}
+  order={["year", "month", "day"]}
+  labels={{ label: t("date.label"), year: t("date.year"), month: t("date.month"), day: t("date.day") }}
+  required showErrors={submitted} parse={parseProductDate} formatIssue={formatDateIssue}
+  onBlur={part => markTouched(part)} />
+```
+
+```tsx
+// Native
+import { DateEntry } from "@hjmds/react-native/date-entry";
+<DateEntry value={draft} onValueChange={setDraft} order={["year", "month", "day"]}
+  labels={localizedLabels} parse={parseProductDate} formatIssue={formatDateIssue}
+  required showErrors={submitted} />
+```
+
+parse는 순수 함수다. 네트워크 요청·Date.now·초안 변경을 넣지 않는다. 날짜 체계·허용 범위·
+로케일별 숫자와 월 이름은 제품이 결정한다. valid.value는 제품이 정한 날짜 문자열이며
+resolveDateEntryDraft는 실제 날짜 유효성을 다시 계산하지 않는다. 저장 실패 시 draft를 유지한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 그룹 | fieldset/legend | 각 필드의 접근성 이름에 그룹 포함 |
+| 자동완성 | bday 조각 | Android birthdate 조각 + iOS 명시적 textContentType |
+
+
+Web은 fieldset/legend와 필드별 label·aria-describedby를 사용한다. Native는 그룹 이름을 각 입력의
+접근성 이름에 포함하며 세 입력을 하나의 접근성 노드로 합치지 않는다. Native 날짜 자동완성은
+Android의 `birthdate-year/month/day`와 iOS의 명시적 `birthdateYear/Month/Day` content type을 연결한다. Web은 `bday-year/month/day`다. Web className, 양쪽 layoutStyle을 지원한다.
+
+## 함정
+
+- 서버 저장 완료와 valid 초안을 구분한다. 편집하면 이전 확인 결과를 무효화한다.
+- Showcase의 Gregorian/영어 월 파서는 예제 정책이며 HJM 기본 파서가 아니다.
+- Calendar로 부분 입력을 강제로 변환하거나 NumberField로 교체하면 원문 보존 계약이 깨진다.
+- Web 390px 다크/RTL/2배 글자와 iOS 2배 글자에서 오류 복구를 확인했다. 제품 팔레트·스크린리더·자동완성 실제 검증은 남아 있다. 실험 등록은 승격·게시가 아니다.
+- Native 화면 호스트는 키보드 inset을 처리하는 ScrollView 등으로 하단 행동에 접근할 수 있어야 한다. DateEntry 내부에 중첩 스크롤을 만들지 않는다.

package/docs/usage/compositions/document-resource.md

@@ -0,0 +1,124 @@
+# 문서와 파일
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.14.0
+- 검토일: 2026-10-07
+- 근거: [파일 원본 대조](../../../../../docs/qa/2026-10-07-file-reference.md), `src/document-resource.ts`
+- 스토리북: `배포/구성/정보 표시/문서와 파일`
+
+승급: 2026-10-07 사용자 승인, [검토 결과](../../../../../docs/qa/2026-10-07-experiment-promotion-release.md). Storybook 분류이며 제품 적용 증거는 별도다.
+
+## 언제 쓰나
+
+이름·형식·크기와 미리보기·내보내기·별도 메뉴를 함께 제공하는 문서에 쓴다.
+단순 다운로드 링크는 Link, 업로드 진행은 UploadItem을 사용한다. 파일 읽기·저장·권한·공유와
+성공 영수증은 제품이 소유한다. DocumentResource는 controlled 상태의 배치와 버튼을 소유한다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| DocumentResource | metadata·상태·독립 행동 구성 | 이 문서 |
+| Surface/Stack | 바깥 틀·세로 배치 | [Surface](../components/surface.md), [Stack](../components/stack.md) |
+| Text | 파일명·형식·크기·오류 | [Text](../components/text.md) |
+| Button | 미리보기·저장·재시도 | [Button](../components/button.md) |
+
+## 배치
+
+```text
+┌────────────────────────────┐
+│ 파일명                     │
+│ 형식 / 크기(각 별도 줄)    │
+│ 설명                       │
+│ 미리보기 또는 상태 안내    │
+│ [본문 보기]                │
+│ [미리보기 재시도] — 오류 시 │
+│ [저장 / 재시도]            │
+│ 저장 상태·오류             │
+│ moreAction(선택)           │
+└────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Surface | 제품 목록/상세 안 | padding md, radius lg |
+| 모든 영역 | Stack | 위→아래 | gap sm, spacing.sm 12 |
+| 파일명 | Text | 최상단 | strong, heading 역할을 자동 부여하지 않음 |
+| 형식·크기 | Text | 이름 아래 | caption/muted, 제품 문자열 그대로 |
+| 행동 | Button | 미리보기 아래 | 세로 배치, Native growWithContent |
+
+파일명은 줄바꿈한다. 미리보기 크기와 내용은 제품 host가 공급하며, 카드 전체를 링크/버튼으로
+감싸지 않는다. `moreAction`도 독립 행동이다. 상위 화면이 스크롤을 소유한다.
+
+Web에서 초점을 가진 미리보기 재시도 버튼이 제거되면 같은 문서의 사용 가능한 미리보기
+버튼으로 복귀하며, 없으면 저장 버튼으로 옮긴다. 2026-10-07 실제 브라우저에서 제거된 버튼의
+초점이 body로 떨어진 회귀에 따른 규칙이다. 제품이 다른 문서로 바꾸거나 사용자가 이미 다른
+요소에 초점을 둔 경우에는 자동 이동하지 않는다. Native 스크린리더 복구는 별도 검증 대상이다.
+
+Showcase에는 긴 파일명 전환과 미리보기 준비 중·실패·없음 조작이 있다. 이름을 전환하면
+기존 action-session 결과를 reset한다. 미리보기 로딩은 저장을 자동으로 잠그지 않는다.
+저장 잠금 토글은 미리보기와 그 재시도를 유지하며 저장·저장 재시도만 잠근다.
+
+## 흐름과 상태
+
+1. 양 renderer의 `/document-resource`에서 DocumentResource를 import한다. root export는 없다.
+2. descriptor id는 파일 revision을 구분한다. name 필수, formatLabel/sizeLabel/description은 선택이다.
+3. preview는 none/loading/ready/error이며 error에는 message와 retryable을 준다. retryable이면
+   onRetryPreview도 필수다. ready일 때만 preview 노드를 표시한다. onPreview는 선택이다.
+4. save는 idle/pending/started/saved/cancelled/error다. error의 retryable이 true이면 onRetrySave가
+   필수이고 false면 일반 저장 버튼으로 우회하지 않는다. 새 시도 허용은 제품의 상태 판단이다.
+5. labels의 열 문구를 모두 현지화한다. 비어 있는 문구·잘못된 상태는 TypeError다.
+6. onSave/onRetrySave는 제품 action-session에 연결한다. 중복 실행은 session이 막으며 파일 교체·
+   unmount에서 reset으로 이전 결과를 분리한다. reset은 실제 OS/서버 작업 취소가 아니다.
+7. 브라우저 anchor 시작이나 Native 공유 sheet 완료만으로 saved를 넣지 않는다. 실제 host가
+   확인한 저장 결과만 saved다. 예제 Web은 Blob 다운로드 시작, Native는 텍스트 공유 예제다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | metadata·각 버튼 | 자동 초점 없음 |
+| 진행 중 | 저장 버튼 pending/loading | 같은 버튼 위치 유지, 제품 세션이 재실행 차단 |
+| 실패 | 해당 오류·허용된 재시도 | 미리보기 실패가 저장을 자동으로 막지 않음 |
+| 시작/완료/취소 | 각각 다른 상태 문구 | Web status, Native live region; iOS 실제 알림 검증 대기 |
+| 비활성 | 기본·재시도 행동 비활성 | 제품 moreAction도 같은 정책을 공급해야 함 |
+
+`saveDisabled`는 기본 false이며 저장·저장 재시도만 막는다. 결과를 읽고 검토해야 내보낼 수
+있는 제품에서 사용한다. `disabled`는 미리보기까지 막으므로 검토 대기 상태에 대신 쓰지 않는다.
+2026-10-07 Utilverse PhotoOutputCard 조사에서 이 구분이 필요했다. 잠금은 진행 중인 OS 작업의
+취소나 권한 검사를 대신하지 않는다. 제품은 onSave 실행 직전에도 유효한 권한·검토 상태를 확인하고,
+`moreAction`에 별도 공유 행동을 넣었다면 그 행동에도 제품의 잠금 정책을 연결한다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { DocumentResource } from "@hjmds/react/document-resource";
+<DocumentResource descriptor={documentState} labels={localizedLabels}
+  preview={previewHost} onPreview={openPreview} onSave={startExport}
+  onRetryPreview={retryPreview} onRetrySave={retryExport} />;
+```
+
+```tsx
+// Native
+import { DocumentResource } from "@hjmds/react-native/document-resource";
+<DocumentResource descriptor={documentState} labels={localizedLabels}
+  preview={previewHost} onPreview={openPreview} onSave={startExport}
+  onRetryPreview={retryPreview} onRetrySave={retryExport} />;
+```
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 바깥 의미 | group + 파일명 | accessible=false로 자식 조작 유지 |
+| 내보내기 host | anchor/download, 파일 API 등 제품 선택 | OS 저장·공유·권한 adapter를 제품이 공급 |
+| pending/error 알림 | status/alert | live region/alert, iOS 기기 낭독 미검증 |
+
+## 함정
+
+Showcase의 첫 실패는 합성 fixture이며 운영 서버 실패가 아니다. Native 텍스트 공유는 파일 저장
+검증을 대신하지 않는다. HJM이 제품의 실패를 저장 성공으로 해석하지 않도록 action-session의
+success와 host 결과 started/saved/cancelled를 따로 연결한다. 오류를 내부 상태로 기록하고
+resolve하는 제품 세션은 Promise 완료만으로 성공을 판단하지 말고 세션 snapshot의 결과·오류를 읽는다. 제품 metadata에 URL·서버 오류 원문을
+자동 노출하지 않는다. 아직 실험이며 전체 환경 검증·승격·npm 게시·소비 적용은 별도다.