@hjmds/design-contracts 1.13.1 → 1.15.0

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/date-time-selection.md

@@ -0,0 +1,110 @@
+# 날짜와 시각 선택
+
+- 단계: 구성
+- 상태: 실험
+- 지원: Web · Native
+- 적용: 미게시(1.14.0 이후)
+- 검토일: 2026-10-07
+- 근거: [Magic 조사](../../../../../docs/qa/2026-10-07-reference-parallel-b.md), 양 Showcase `date-time-selection-preview.tsx`, shared `date-time-selection.ts`
+- 스토리북: `실험/구성/선택과 필터/날짜와 시각 선택`
+
+## 언제 쓰나
+
+기록·알림의 날짜 하나와 하루 안의 시각을 함께 고를 때 쓴다. [기존 시간 선택](time-selection.md)에
+날짜 선택을 붙이는 구성이다. 서버 예약·시간대 변환을 담당하는 새 DateTimePicker API가 아니다.
+[Magic 글](https://magicui.design/blog/time-and-date-picker)은 공개 interface와 설명을 제공하며
+동작하는 picker 구현은 제공하지 않는다. 설명의 구성 아이디어만 기존 API에 연결했다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| Provider | 10개 테마 순회와 필드 표현 상속 | [프로필 계약](../../design-profile.md) |
+| DatePicker | ISO 날짜 하나와 표시 달, 접근 가능한 달력 표면 | [날짜 선택](../components/date-picker.md) |
+| Select ×2 | 시·분 선택 | [선택 목록](../components/select.md) |
+| Section·Container·Stack | 제목·전체 흐름·폭 | [구역](../components/section.md) · [컨테이너](../components/container.md) · [스택](../components/stack.md) |
+| Button | 확인·다시 선택 | [버튼](../components/button.md) |
+| Text·Notice | 선택값·진행·실패·확인 결과 | [텍스트](../components/text.md) · [알림](../components/notice.md) |
+| Collapsible | Storybook의 결정적 응답/실패 검증 도구 | [접기](../components/collapsible.md) |
+
+## 배치
+
+```text
+Section 제목/설명 → 선택 테마/다음 테마
+날짜 트리거 → 달력(선택/지우기/이전·다음 달/닫기)
+시 Select → 분 Select
+같은 선택값 → 시간대/서버는 제품 소유 안내
+확인(주 행동) → 다시 고르기(보조)
+실패/확인 결과
+검증 도구: 미리보기 응답 받기 → 다음 확인 실패
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Container·Section·Stack | 세로 문서 흐름; Native ScrollView | `gutter="compact"` 16, `spacing.md` 16. Native 위아래 `spacing.lg` 20 |
+| 날짜 | DatePicker | 제목 아래 | 기존 [날짜 필드 배치](../components/date-picker.md#배치); Web popover/Native Sheet |
+| 시각 | Select | 날짜 아래, 시→분 | `control.fieldHeight` 44, 사이 `spacing.md` 16 |
+| 주·보조 행동 | Button | 선택 상태 아래 | 확인→다시 고르기, `control.buttonHeight.medium` 44 기본. 고정하지 않음 |
+| 결과 | Notice | 행동 아래 | 실패는 danger, 확인은 success. 위 `spacing.md` 16 |
+
+## 흐름과 상태
+
+1. 날짜를 고른다. 테마를 순회해도 같은 값·표시 달·진행 요청을 유지한다. 달 이동은 표시 달만 바꾸며 이미 고른 날짜·시각을 지우지 않는다.
+2. 시0–23와 분0–59를 고른다. 셋 중 하나라도 없으면 확인은 비활성이다. 어느 값을 바꾸면 이전 결과를 지운다.
+3. 선택 확인 후 진행 상태 동안 날짜·시·분·재설정·실패 예약을 잠근다. 진행 상태는 제품 mutation이 소유한다.
+4. 미리보기에서는 응답 받기로 현재 요청의 선택값을 확정한다. 실패를 예약했다면 값이 남은 실패 상태가 된다.
+5. 실패 후 다시 확인하고 응답 받기로 복구한다. 다시 고르기는 모든 선택과 결과를 비운다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 세 선택값 없음·확인 비활성 | 날짜·시·분 모두 필수 이름. 셀 disabled는 API 계약으로 제어 |
+| 진행 중 | 확인 버튼 loading·입력/재설정 잠김 | placeholder를 서버 성공으로 바꾸지 않음; 이미 고른 값 유지 |
+| 실패 | danger Notice·다시 확인 | 같은 날짜·시·분 보존; Web alert·Native assertive; Web 응답 뒤 확인 버튼으로 포커스 복귀 |
+| 성공 | success Notice·확정한 날짜와 시각 | 값 변경 시 이전 결과 제거. 실제 예약·서버 저장을 뜻하지 않음 |
+| 비활성 | 선택 트리거/행동 비활성 | CSS pointer-events로만 차단하지 않음 |
+
+## 코드 골격
+
+```tsx
+// Web: 날짜·시각·시간대 정책과 서버 응답은 제품 소유다.
+import { DatePicker } from "@hjmds/react/date-picker";
+import { Select } from "@hjmds/react/forms";
+<DatePicker descriptor={{ grid, label: dateLabel, placeholder, displayValue: date,
+  selectedDate: date, onSelectionChange: setDate, focusedMonth: month,
+  onFocusedMonthChange: setMonth, disabled: busy }} monthLabel={monthLabel}
+  composeAccessibleName={composeAccessibleName} clearLabel={clearLabel} closeLabel={closeLabel} />
+<Select label={hourLabel} placeholder={hourPlaceholder} emptySelectionLabel={hourClearLabel}
+  items={hours} selectedKey={hour} onSelectionChange={setHour} disabled={busy} />
+<Select label={minuteLabel} placeholder={minutePlaceholder} emptySelectionLabel={minuteClearLabel}
+  items={minutes} selectedKey={minute} onSelectionChange={setMinute} disabled={busy} />
+```
+
+```tsx
+// Native: 같은 날짜 descriptor, 시간 목록은 닫기 문구도 공급한다.
+import { DatePicker } from "@hjmds/react-native/date-picker";
+import { Select } from "@hjmds/react-native/forms";
+<DatePicker descriptor={descriptor} monthLabel={monthLabel} composeAccessibleName={composeAccessibleName}
+  clearLabel={clearLabel} closeLabel={closeLabel} />
+<Select label={hourLabel} placeholder={hourPlaceholder} dismissLabel={hourDismissLabel}
+  items={hours} selectedKey={hour} onSelectionChange={setHour} disabled={busy} />
+```
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 날짜 표면 | 필드에 붙은 popover | Sheet |
+| 시각 표면 | listbox popover | modal sheet |
+| 상태 | Text role=status | Showcase PatternStatus의 Android live region/iOS announce 보완. 제품은 공개Text/Notice와 같은 정책을 연결 |
+| 날짜 키보드 | Calendar roving focus, 달 경계 callback은 제품 설정 | touch/AT, 실기기 확인 별도 |
+
+## 함정
+
+제품 문구는 제품의 i18n으로 공급한다.
+Showcase shared fixture/검증 도구를 제품에서 import하지 않는다. 이 화면은 날짜를 기기 시간대의
+Date timestamp로 암묵 변환하지 않는다. 민간 날짜·시간대·DST·예약 허용 범위·로캘·전송 값은
+제품 계약에서 결정한다. 직접 CSS 색/모서리나 새 날짜 라이브러리를 이 구성에 추가하지 않는다.
+
+ISO 날짜와 시각을 한 줄에 표시할 때는 제품 display 문자열에 LTR isolate를 적용해 RTL에서도
+날짜→시각 순서를 유지한다. 표시용 Unicode 제어 문자를 원래 civil/전송 값에 넣지 않는다.
+이는 이 실험의 ISO 표시 선택이며 실제 제품은 자신의 locale format을 공급한다.

package/docs/usage/compositions/design-profile-comparison.md

@@ -0,0 +1,114 @@
+# 테마 조합
+
+- 단계: 구성
+- 상태: 실험
+- 지원: Web · Native
+- 적용: 미게시(1.14.0 이후)
+- 검토일: 2026-10-07
+- 근거: [프로필 계약](../../design-profile.md), [조사와 QA](../../../../../docs/qa/2026-10-07-design-profile-research.md), 두 Showcase `design-profile-preview.tsx`
+- 스토리북: `실험/구성/비교와 검증/테마 조합`
+
+## 언제 쓰나
+
+같은 기능에 10가지 표현을 적용하고, 앱 소유 테마 설정을 넣었을 때 네 단계의 전파와 상태 유지를 검토할 때 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| Provider | 한 번 선택한 프로필 상속 | [프로필 계약](../../design-profile.md) |
+| SegmentedControl | 테마/기간 선택 | [선택 입력](../components/segmented-control.md) |
+| OverviewScreen | 도구·목록·주 행동 | [목록 화면](../components/overview-screen.md) |
+| Tabs | 프로필 상속/명시 표시와 방문한 패널의 초안 유지 | [탭](../components/tabs.md) |
+| Card | 무늬 위의 표면 질감과 초안 | [카드](../components/card.md) |
+| Asset | 같은 그림의 프로필 둥근 액자와 명시한 정사각·원형 비교 | [자산](../components/asset.md) |
+| Heading | 선택 테마의 5단계 제목 크기 | [제목](../components/heading.md) |
+| BottomCTA | 저장·실패 재현과 위쪽 그림자 | [하단 행동](../components/bottom-cta.md) |
+| Popover(Web) | 비모달 초안과 같은 프로필 순회 | [팝오버](../components/popover.md) |
+| Dialog·Sheet | 열린 초안과 같은 프로필 순회 | [대화상자](../components/dialog.md) · [패널](../components/sheet.md) |
+| Notice·Skeleton·Toast | 알림·로딩·확정 후 피드백의 모서리/그림자 | [알림](../components/notice.md) · [로딩](../components/skeleton.md) · [토스트](../components/toast.md) |
+| ContentTransition | 실제 저장 상태 전환 | [내용 전환](../components/content-transition.md) |
+| Collapsible | 전체 비교 접기 | [접기](../components/collapsible.md) |
+
+## 배치
+
+```text
+설명 → 앱 테마 적용(참고 테마/산책 노트/문장 모음) → 표현 선택(기존 10종)
+선택한 프로필: 헤더 → 저장 상태 → 이름/기간 → 같은 기록 3개 → 저장/실패 재현
+선택한 프로필: 제목 크기 비교(5단계, 문서 단계 h3 유지)
+표면 질감 비교: 장식 무늬 → Card 제목/설명 → 같은 초안 → 다음 테마
+탭 선택 표시 비교: 테마 따르기/밑줄/이동/늘어남 → 기록/보관함 → 같은 초안 → 다음 테마
+자산 액자 비교(기본 접힘): 같은 기존 Tick 그림 → 둥근/정사각/원형 → 다음 테마
+입력·알림·오버레이 비교: Notice → Skeleton → Toast → Dialog/Sheet 열기
+오버레이: 제목/닫기 → 같은 초안 → 다음 테마(현재 10종 순환)
+10종 비교: 각 이름 → 같은 화면(현재 앱 설정도 함께 적용)
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 세로 | `spacing.xl` 24 |
+| 앱/참고 테마 | SegmentedControl | 선택 화면 위 | 앱 설정 3개 후 참고 테마 10개; `presentation="pills"`, 큰 선택 목록의 좁은 폭 배치는 공개 선택 계약을 따른다 |
+| 이름/기간 | TextField·SegmentedControl | 도구 | `spacing.md` 16 |
+| 목록 | OverviewScreen | 본문 | [목록 배치](../components/overview-screen.md#배치) |
+| 저장/실패 | BottomCTA | footer | `spacing.sm` 12; 주 행동 후 ghost 실패 재현 |
+| 자산 비교 | Asset·Stack | 탭 비교 아래 | `xlarge` 120px, `spacing.md` 16, 좁으면 줄바꿈. rounded는 프로필 radius.md, square 0, circle foundation full 유지 |
+
+## 흐름과 상태
+
+1. 기록 이름·기간을 바꾼다. 앱 설정과 표현을 바꿔도 같은 선택 화면의 초안/선택을 유지한다.
+   산책 노트는 녹색 잉크·cards/collapsible·landscape·slide/rise를, 문장 모음은 보라 잉크·rows/inline·editorial·none/fade를 지정한다.
+   나머지 표면/모서리/글자/질감은 고른 참고 테마를 상속한다. 두 설정은 제품 소유 설정 파일을 보여 주는 fixture이며 새 HJM 프리셋이 아니다.
+2. 도구 접기/펼치기를 확인한다. 항상 펼친 테마로 가면 내용이 보인다.
+3. 무늬 배경의 카드에 입력하고 다음 테마를 누른다. 유리·클레이 질감과 같은 초안 유지를 확인한다. Native 지원/접근성 설정에 따라 불투명 대체 경로도 확인한다.
+4. 대화상자/패널을 열고 초안을 바꾼 뒤 다음 테마를 누른다. 열린 오버레이 안에서 프로필을 바꾸며 초안/문서 역할을 유지한다. 닫고 다시 열어도 제어 초안은 남는다.
+5. 미리보기 저장 또는 실패 재현을 누른다. 실패 후 같은 입력을 재시도한다.
+6. 자산 액자 비교를 펼쳐 다음 테마를 누른다. 같은 기존 CC0 그림과 120px 액자를 유지하며
+   rounded만 프로필을 따른다. 이 예제는 그림 재질·각도 자동 선택이나 Native 이미지 decode 검증의 완료 근거가 아니다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 저장 전 | 입력·선택 가능 |
+| 진행 중 | 저장 버튼 pending | 입력을 제거하지 않음 |
+| 실패 | 실패 문구·다시 저장 | 초안 유지·상태 알림 |
+| 성공 | 미리보기 저장 문구 | 서버 저장으로 안내하지 않음 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { HjmProvider } from "@hjmds/react/provider";
+import { OverviewScreen } from "@hjmds/react/design-profile";
+import { defineHjmDesignProfile } from "@hjmds/design-contracts/design-profile";
+const design = defineHjmDesignProfile({ extends: "paper", id: "my-app",
+  compositions: { collection: "cards", toolbar: "collapsible" }, screens: { overview: "landscape" } });
+<HjmProvider designProfile={design}><OverviewScreen title={title} toolbarLabel={toolsLabel} toolbar={tools} items={items} footer={save} /></HjmProvider>
+```
+
+```tsx
+// Native
+import { HjmNativeProvider } from "@hjmds/react-native/provider";
+import { OverviewScreen } from "@hjmds/react-native/design-profile";
+import { defineHjmDesignProfile } from "@hjmds/design-contracts/design-profile";
+const design = defineHjmDesignProfile({ extends: "paper", id: "my-app",
+  compositions: { collection: "cards", toolbar: "collapsible" }, screens: { overview: "landscape" } });
+<HjmNativeProvider designProfile={design}><OverviewScreen title={title} toolbarLabel={toolsLabel} toolbar={tools} items={items} footer={save} /></HjmNativeProvider>
+```
+
+제품은 Showcase를 import하지 않고 공개 API에 제품 문구/데이터를 넣는다. 유리 blur·클레이 inset shadow의 플랫폼 조건과 기기 미확인 범위는 [QA](../../../../../docs/qa/2026-10-07-design-profile-research.md)에 남긴다.
+
+`showcase/shared/product-design.ts`는 순수 설정과 fixture 조합만 공유한다. 양 renderer가 자신의 workspace에서
+공개 `defineHjmDesignProfile`을 주입한다. 루트에 renderer peer를 설치하거나 TypeScript alias로 소비 경계를 우회하지 않는다.
+실제 앱은 이 fixture를 import하지 않고 자신의 `theme.ts`에서 같은 공개 helper를 사용한다. 테마 저장/URL/계정 동기화와 폰트/자산 로딩은 앱이 소유한다.
+
+두 앱 변형은 같은 항목의 `ProductNotes`(앱 테마 · 산책)·`ProductReading`(앱 테마 · 문장) 스토리다.
+새 테마마다 폴더나 상태 엔진을 만들지 않으며 Provider/RecordSample/입력/탭/오버레이에 product/preset key를 달아 교체하지 않는다.
+OS 최대 글자와 최대값을 모사한 확대는 이번 추가의 설계·검증·후속·완료/릴리스 조건에서 제외한다.
+
+코드 비교는 양 플랫폼의 공개 `CodeBlock`을 사용한다. 같은 원문에 프로필 code font·body metrics를 적용하며 RTL에서도 코드 본문은 LTR로 읽는다.
+
+탭 비교는 공개 `Tabs`·`TextField`와 `mountPolicy="visited"`를 사용한다. 테마/표시 방식 변경은
+선택한 탭과 같은 입력 호스트를 유지한다. forest·glass·aurora·clay는 생략한 appearance가
+slide로 해석되고 나머지 6종은 standard다. 명시 값은 프로필보다 우선한다. 실제 제품은
+이 샘플의 패널 수명을 기본값으로 복사하지 않고 초안과 탭의 사용 목적에 맞춰 선택한다.
+
+Web의 팝오버는 비모달 편집 초안과 테마 순회를 추가 비교한다. Native의 같은 용도는 기존 Sheet 경로다. 저장/실패 샘플은 두 플랫폼 공개 BottomCTA이며 브랜드가 바뀌어도 같은 저장 상태·초안·재시도 callback을 유지한다.

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 게시·소비 적용은 별도다.

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는 제품별로 정한다. 예제의 한국 주소 순서를 공통 규칙으로 복사하지 않는다.