@hjmds/design-contracts 1.12.1 → 1.13.0

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

@@ -0,0 +1,126 @@
+# EditorScreen
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screens.tsx`·`src/screen-flows.tsx`; 기존 개별 지침을 새 규격으로 통합. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/화면/콘텐츠/작성과 수정`, `배포/화면/계정/프로필`
+
+## 언제 쓰나
+
+글쓰기·프로필 수정처럼 한 화면 전체가 편집 흐름일 때 쓴다. 닫기 버튼, 수정 중 닫기 확인
+(AlertDialog), 저장 버튼의 busy 표시, 초안 상태 안내를 ScreenLayout 위에 한 번에 묶어 준다.
+검증·초안 저장·저장 mutation·라우터/OS 뒤로가기 guard는 제품이 소유한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 편집 흐름이 없는 일반 화면 | [ScreenLayout](screen-layout.md) |
+| 화면 일부의 입력 묶음과 submit | [Form](form.md) |
+| 편집 없이 확인만 받기 | [AlertDialog](alert-dialog.md) |
+| 짧은 입력을 화면 위에 띄움 | [Sheet](sheet.md), [Dialog](dialog.md) |
+| 프로필 요약과 수정 진입 | [ProfileScreen](profile-screen.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `EditorScreen` | 편집 화면 흐름 | `/screen-flows` | `/screen-flows` |
+| `ScreenFlowAction` (타입) | `submit`·`cancel` 행동 | `/screen-flows` | `/screen-flows` |
+
+루트(`@hjmds/react`, `@hjmds/react-native`)에서는 import 할 수 없다. granular subpath만 쓴다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { EditorScreen } from "@hjmds/react/screen-flows";
+import { Text } from "@hjmds/react/layout";
+import { TextField } from "@hjmds/react/forms";
+
+<EditorScreen
+  title={t("post.edit.title")}
+  dirty={draft !== saved}
+  submit={{ label: t("post.edit.save"), pending: saving, disabled: !draft.trim(), onAction: save }}
+  cancel={{ label: t("post.edit.close"), onAction: close }}
+  discard={{
+    mode: "confirm",
+    title: t("post.discard.title"),
+    description: t("post.discard.description"),
+    confirmLabel: t("post.discard.confirm"),
+    cancelLabel: t("post.discard.keep"),
+    tone: "danger",
+    fallbackErrorMessage: t("common.error"),
+  }}
+  draftStatus={<Text variant="caption" tone="muted">{t("post.edit.draftSaved")}</Text>}
+>
+  <TextField label={t("post.edit.body")} value={draft} onValueChange={setDraft} />
+</EditorScreen>
+```
+
+```tsx
+// Native — props는 같다. 조각은 Native subpath에서 가져온다.
+import { EditorScreen } from "@hjmds/react-native/screen-flows";
+import { Text } from "@hjmds/react-native/primitives";
+import { TextField } from "@hjmds/react-native/inputs";
+
+<EditorScreen
+  title={t("post.edit.title")}
+  dirty={draft !== saved}
+  submit={{ label: t("post.edit.save"), pending: saving, disabled: !draft.trim(), onAction: save }}
+  cancel={{ label: t("post.edit.close"), onAction: close }}
+  discard={{
+    mode: "confirm",
+    title: t("post.discard.title"),
+    description: t("post.discard.description"),
+    confirmLabel: t("post.discard.confirm"),
+    cancelLabel: t("post.discard.keep"),
+    tone: "danger",
+    fallbackErrorMessage: t("common.error"),
+  }}
+  draftStatus={<Text variant="caption" tone="muted">{t("post.edit.draftSaved")}</Text>}
+>
+  <TextField label={t("post.edit.body")} value={draft} onValueChange={setDraft} />
+</EditorScreen>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `dirty` | `boolean` | 필수 | `true`에서 닫기를 누르면 `discard` 확인창을 띄우고, 확인하면 `cancel.onAction`을 부른다. `false`면 바로 부른다 |
+| `submit` | `ScreenFlowAction`(`{ label, onAction(), disabled?, pending? }`) | 필수 | `pending`이면 loading·비활성. 그동안 닫기 버튼도 비활성 |
+| `cancel` | `ScreenFlowAction` | 필수 | `leading` 자리의 ghost 닫기 버튼 |
+| `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 폭(최대 720) 안에 입력 본문; 저장·닫기는 `Button` 기본 크기 | `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` |
+| 좁은 폭·큰 글자 | 제목 열 최소 폭 120 × 글자 배율, 모자라면 header 저장 버튼이 다음 줄로 내려간다; 키보드·safe area는 host | `screenPatternRecipe.headerMinWidth` |
+
+## 꼭 지킬 것
+
+- 모든 문구(`label`, `discard`의 제목·설명·버튼)는 i18n 키로 넣는다. 컴포넌트는 기본 문구를 갖지 않는다.
+- `discard`는 `fallbackErrorMessage`까지 필수 타입이다. `onConfirm`은 EditorScreen이 채우므로 넘기지 않는다.
+- 확인 후 초안을 되돌리는 일은 `cancel.onAction` 안에서 제품이 한다.
+- 라우터 뒤로가기·Android back·브라우저 이탈은 이 컴포넌트가 막지 않는다. 제품이 `dirty`로 guard를 건다.
+- 저장 성공 판정·오류 표시는 제품 상태(`notice`, Toast 등)로 한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 화면 셸 전용 props | `as`, `className` | `testID`, `scrollRef`, `scrollProps` (`layoutStyle`은 양쪽 모두 받는다) |
+| 버튼 이벤트 | 내부에서 `onClick` → `onAction` | 내부에서 `onPress` → `onAction` |

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

@@ -0,0 +1,120 @@
+# EffectSurface
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Composable decorative surfaces](../../effect-surface.md), 별도 보조 기능(supplemental)
+- 스토리북: `배포/컴포넌트/시각 효과/배경 시각 효과`
+
+## 언제 쓰나
+
+환영·온보딩·빈 히어로처럼 분위기를 주는 배경이 필요할 때 내용 뒤에 장식 레이어(mesh·glow·grain)를
+깐다. 장식은 포커스·터치·접근성 이름을 갖지 않고, 내용은 일반 레이아웃에 그대로 남는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 일반 카드·패널 면 | [Surface](surface.md), [Card](card.md) |
+| 실제 작업(생성·분석) 진행 표시 | [ThinkingOrb](thinking-orb.md) |
+| 성공 순간의 축하 효과 | [Celebration](celebration.md) |
+| 로딩 자리 표시 | [Skeleton](skeleton.md), [Spinner](spinner.md) |
+| 목록의 여러 행마다 움직이는 배경 | 쓰지 않는다(동시에 움직이는 행을 늘리지 않는다) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `EffectSurface` | 기본 — 장식 배경 셸 | `/effect-surface` | `/effect-surface` |
+| `EffectSurfaceDescriptor` (타입) | 보조 — 레이어·seed·강도·주기·색 | `@hjmds/design-contracts/effect-surface` | 같음 |
+
+루트에서는 import 할 수 없다. granular subpath만 쓴다.
+
+**Native는 optional peer `react-native-svg`(정확히 `15.15.5`)가 앱에 설치돼 있어야 한다.**
+`/effect-surface`가 이 모듈을 파일 최상단에서 import 하므로, 없으면 tsc·단위 테스트는 통과하고 기기 Metro
+번들에서 `Unable to resolve module`로 크래시한다(2026-10 utilverse 사고, celebration·qr-code·thinking-orb·
+toast-liquid도 같은 유형). 쓰기 전에 앱 `package.json`에 peer가 있는지 확인한다. 움직임은 core `Animated`라
+Reanimated·Skia는 필요 없다. Web은 추가 peer가 없다(SVG·WAAPI).
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { EffectSurface } from "@hjmds/react/effect-surface";
+
+<EffectSurface descriptor={{ layers: ["mesh", "grain"], seed: "welcome", active: true }}>
+  <WelcomeContent />
+</EffectSurface>
+```
+
+```tsx
+// Native
+import { EffectSurface } from "@hjmds/react-native/effect-surface";
+
+<EffectSurface descriptor={{ layers: ["mesh", "grain"], seed: "welcome", active: true }} visible={isFocused}>
+  <WelcomeContent />
+</EffectSurface>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `descriptor.layers` | `mesh` · `glow` · `grain` | `["mesh"]` | 서로 다른 1~3개 |
+| `descriptor.intensity` | 0~1 | `0.22` | — |
+| `descriptor.period` | 2~120초 | `12` | — |
+| `descriptor.seed` | 문자열 | `"hjm"` | 빈 문자열 금지 |
+| `descriptor.active` | `true` · `false` | `false` | 켤 때만 천천히 움직인다. reduced motion이면 provider 설정에 따라 멈춘다 |
+| `descriptor.colors` | `ColorReference` 세 개 | `themeColor("primary")` · `themeColor("contentBrand")` · `themeColor("surfaceAccent")` | — |
+
+| `children` | `ReactNode` | — (필수) | 일반 레이아웃 내용 |
+| Native `visible` | `boolean` | `true` | 화면·목록 소유자가 가려짐을 알린다. `false`면 장식이 멈춘다 |
+| Web `layoutStyle` | 배치 전용 style | — | 루트 배치 |
+| Native `style` | `StyleProp<ViewStyle>` | — | 컨테이너 `View`. 정식 motion host 프레임이라 deprecated 대상이 아니다 |
+
+- 콜백 prop은 없다. `descriptor`는 생략할 수 있고(`{}`), 잘못된 값은 렌더 중 `TypeError`/`RangeError`를 던진다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 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` |
+| 순서·정렬 | children은 일반 레이아웃이다. [Stack](stack.md)으로 eyebrow → [Heading](heading.md) → 소개 → [Button](button.md)을 쌓는다(Showcase 랜딩 예는 `gap="lg"` 20, Heading `level1`) | `showcase/web/src/patterns/Landing.stories.tsx` |
+| 고정·스크롤 | 화면 위쪽 히어로 하나에만 둔다. 같은 화면에 여러 개를 겹치거나 목록 행마다 두지 않는다 | — |
+| 좁은 폭·큰 글자 | — | — |
+
+```text
+┌────────────────────────────┐ ← EffectSurface(배경 bg + mesh/glow/grain, 터치 없음)
+│  eyebrow                   │
+│  큰 제목(Heading level1)    │ ← children: 일반 레이아웃(Stack gap lg 20)
+│  소개 문장                  │
+│  [시작하기]  primary        │
+└────────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 색은 `@hjmds/design-contracts/color-references`의 `themeColor`·`accentColor` 참조로 넘겨 제품 테마를 따르게 한다.
+  hex를 하드코딩하거나 Showcase의 예시 색·seed를 제품 기본값으로 복사하지 않는다([테마](../../theming.md)).
+- 임의 브랜드 색·강도에서 글자 대비를 보장하지 않는다. 실제 조합을 확인하거나 중요한 글자·버튼은 불투명
+  [Surface](surface.md) 위에 둔다.
+- Native 화면·목록 소유자는 화면이 가려지거나 목록 창 밖이면 `visible={false}`를 넘긴다.
+- `active`는 효과가 의미 있을 때만 켠다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 컨테이너 배치 | `layoutStyle`(그 밖에 `className`) | `style`(컨테이너 `View`, `layoutStyle` 없음) |
+| 가시성 | IntersectionObserver·`document.hidden`로 자동 | `visible`(기본 `true`) + AppState |
+| 그리기 | 인라인 SVG + WAAPI | `react-native-svg` + core `Animated` |
+| 렌더 실패 | 애니메이션 생성 거부 시 정적 SVG 유지 | 장식만 제거하고 children은 유지(remount 전까지) |
+
+## 함정
+
+- Native의 장식 실패 대비(error boundary)는 **렌더 오류**만 잡는다. peer가 없어 모듈 해석이 실패하면 앱 번들 자체가
+  깨진다. `tsc` 통과를 설치 확인으로 보지 않는다.
+- descriptor 검증 오류는 대비 밖에 있어 그대로 던져진다. 값 범위를 지킨다.

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

@@ -0,0 +1,114 @@
+# EmptyState
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Result와의 경계](../../result.md#emptystate와의-경계), [ContentState 범위 축](../../content-state.md), recipe `emptyStateRecipe`(`src/component-recipes.ts`)
+- 스토리북: `배포/컴포넌트/상태와 알림/빈 상태`
+
+## 언제 쓰나
+
+목록이 비었거나 검색 결과가 0건이라 **아직 없음**을 알릴 때 쓴다. 조건이 바뀌면 다시 채워질 자리이고,
+사용자는 그 화면에 머물며 필터를 바꾸거나 첫 항목을 만든다. 아이콘은 항상 중립색이고 상태 tone이 없다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 흐름이 끝남(결제 성공·실패 등) | [Result](result.md) |
+| 불러오는 중 | [Skeleton](skeleton.md), [Spinner](spinner.md) |
+| 화면은 그대로 두고 알릴 문제 | [Notice](notice.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `EmptyState` | 기본 | `@hjmds/react`, `/feedback` | `@hjmds/react-native`, `/feedback` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Button } from "@hjmds/react/actions";
+import { EmptyState } from "@hjmds/react/feedback";
+
+<EmptyState
+  icon={<InboxGlyph />} // 제품 소유 아이콘
+  title={t("inbox.empty.title")}
+  description={t("inbox.empty.description")}
+  action={<Button tone="secondary" onClick={compose}>{t("inbox.empty.compose")}</Button>}
+/>
+```
+
+```tsx
+// Native
+import { Button } from "@hjmds/react-native/actions";
+import { EmptyState } from "@hjmds/react-native/feedback";
+
+<EmptyState
+  illustration={<InboxGlyph />} // 제품 소유 아이콘
+  title={t("inbox.empty.title")}
+  description={t("inbox.empty.description")}
+  action={<Button tone="secondary" onPress={compose}>{t("inbox.empty.compose")}</Button>}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `density` | `compact` · `regular` | `regular` | `compact`는 세로 여백이 작고 Native에서 남은 공간을 채우지 않는다 |
+| `align`(Native) | `center` · `upper` | `center` | `upper`는 `regular`일 때 내용을 위쪽(1:3 여백)에 둔다 |
+| `announcement`(Native) | `none` · `polite` · `assertive` | `none` | 상태가 바뀌어 빈 화면이 새로 나타날 때만 켠다 |
+| `titleRole`(Native) | 접근성 role | `"header"` | Web은 항상 `role="status"`로 그린다 |
+| `title` | Web `ReactNode`(필수) · Native `string` | — | — |
+| `description` | Web `ReactNode` · Native `string` | — | — |
+| `action` | `ReactNode`(Button 하나) | — | 콜백은 Button의 `onClick`·`onPress`가 갖는다 |
+| Web `icon` · Native `illustration` | `ReactNode` | — | 장식, 접근성에서 숨김 |
+| `layoutStyle` | 배치 전용 style | — | 루트 배치. Native `style`·`illustrationStyle`·`titleStyle`·`descriptionStyle`·`actionStyle`은 deprecated |
+
+EmptyState 자체에는 콜백 prop이 없다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 그림 슬롯은 `glyph.lg`(28) 정사각형이다(Native `illustration` 상자 고정 크기). 세로 여백: `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` |
+| 좁은 폭·큰 글자 | 카드·시트 안처럼 높이가 작은 자리는 `compact`(채우지 않음)를 쓴다 | `react-native/src/feedback.tsx` `EmptyState` |
+
+```text
+┌──────────────────────────┐
+│ TopBar / 검색칸 (그대로)  │
+├──────────────────────────┤
+│                          │ ← flexGrow 1(upper: 위 1)
+│          (그림)           │
+│          제목             │  gap xs 8
+│          설명             │
+│        [첫 항목 만들기]    │
+│                          │ ← (upper: 아래 3)
+└──────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 제목·설명·행동 문구는 i18n 키로 넣는다. "검색 0건"과 "아직 만든 것 없음"은 다른 문구로 구분한다.
+- 다음 행동이 있으면 `action`에 Button 하나를 둔다. 아이콘·일러스트는 장식이라 접근성에서 숨겨진다.
+- Native는 `title`·`description`·`accessibilityLabel` 중 하나는 있어야 한다. 모두 없으면 `TypeError`를 던진다.
+- 일러스트·아이콘 자산은 제품 소유다. 색은 recipe가 정하므로 슬롯 색을 덮지 않는다.
+- 배치는 `layoutStyle`로 한다. Native 슬롯 style(`style`·`illustrationStyle`·`titleStyle`·`descriptionStyle`·`actionStyle`)은
+  deprecated(개발 모드 1회 경고, 다음 major 제거)다 — 배치는 `layoutStyle`, 외형은 `density`·`align`으로 옮긴다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 그림 슬롯 | `icon`(ReactNode) | `illustration`(ReactNode, 아이콘 크기 상자) |
+| `title` | 필수, ReactNode | 선택, string |
+| `description` | ReactNode | string |
+| 정렬·알림 | 없음 | `align`, `announcement`, `accessibilityLabel`, `titleRole` |
+| 배치 | `layoutStyle`(그 밖에 `className`과 div 속성) | `layoutStyle`(슬롯 style 다섯 개는 deprecated) |

package/docs/usage/components/field.md

@@ -0,0 +1,129 @@
+# Field
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: recipe `fieldRecipe`(`src/base-recipes.ts`), GestureSheetInput: [Optional presentation adapters](../../optional-adapters.md)
+- 스토리북: `배포/컴포넌트/입력/입력 필드`
+
+## 언제 쓰나
+
+라벨·도움말·오류를 가진 입력 칸에 쓴다. 한 줄 텍스트 입력은 `TextField`를 쓰고, `Field`는 HJM에 없는
+제품 고유 컨트롤(예: 직접 만든 선택기)에 같은 라벨·도움말·오류 틀과 접근성 연결을 씌울 때 쓴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 여러 줄 입력 | [TextArea](text-area.md) |
+| 비밀번호·인증 코드·숫자 | [PasswordField](password-field.md), [OtpField](otp-field.md), [NumberField](number-field.md) |
+| 검색어 입력 | [SearchField](search-field.md) |
+| 목록에서 고르기·날짜 | [Select](select.md), [Combobox](combobox.md), [DatePicker](date-picker.md) |
+| 입력 묶음의 submit·오류 포커스 | [Form](form.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Field` | 기본 — 커스텀 컨트롤용 틀 | `@hjmds/react`, `/forms` | `@hjmds/react-native`, `/forms` |
+| `TextField` | 동반 — 한 줄 텍스트 입력 | `@hjmds/react`, `/forms` | `@hjmds/react-native`, `/inputs` |
+| `GestureSheetInput` | 확장 — GestureSheet 안의 키보드 추적 입력 | 없음 | `/sheet-gesture` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { TextField, Field } from "@hjmds/react/forms";
+
+<TextField
+  label={t("profile.nickname")}
+  description={t("profile.nicknameHint")}
+  error={nicknameError ? t(nicknameError) : undefined}
+  required
+  value={nickname}
+  onValueChange={setNickname}
+/>
+
+<Field controlId="profile-color" label={t("profile.color")} error={colorError}>
+  {(control) => <ProductColorPicker {...control} value={color} onChange={setColor} />}
+</Field>
+```
+
+```tsx
+// Native
+import { TextField } from "@hjmds/react-native/inputs";
+import { Field } from "@hjmds/react-native/forms";
+
+<TextField label={t("profile.nickname")} description={t("profile.nicknameHint")} required
+  value={nickname} onValueChange={setNickname} {...(nicknameError ? { error: t(nicknameError) } : {})} />
+
+<Field label={t("profile.color")} {...(colorError ? { error: t(colorError) } : {})}>
+  {(control) => <ProductColorPicker {...control} value={color} onChange={setColor} />}
+</Field>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `variant`(`TextField`) | `surface` · `inset` | `surface` | — |
+| `shape`(`TextField`) | `medium` · `large` · `full` | `medium` | — |
+| `align`(`TextField`) | `start` · `center` | `start` | `center`는 닉네임·코드처럼 짧은 한 값 |
+| `onValueChange`(`TextField`) | `(value: string) => void` | — | Web·Native 같은 이름·모양. Web은 DOM `onChange`(이벤트)도 함께 불린다. 공용 폼 코드는 `onValueChange`를 쓴다 |
+| `children`(`Field` render-prop) | `(control: FieldControlProps) => ReactNode` 또는 `ReactNode` | — | Web `FieldControlProps`는 `{ id, required, disabled, "aria-invalid"?: true, "aria-describedby"? }`, Native는 `{ accessibilityLabel, accessibilityHint?, accessibilityState: { disabled } }`(hint는 오류 우선) |
+| `busy`(Native `TextField`) | `boolean` | `false` | 편집을 막고 접근성 busy를 싣는다 |
+
+- 상태 테두리는 recipe가 정한다: 기본 `borderControl`, 포커스 `contentBrand`, 오류 `danger`.
+- 도움말은 오류가 생겨도 사라지지 않고 둘 다 보인다(Web은 `aria-describedby`로 둘 다 연결).
+- 비활성(`disabled`)은 라벨과 컨트롤만 흐리고 도움말·오류는 원래 대비 그대로 둔다(`fieldRecipe.disabledScope`).
+  흐림 정도는 컴포넌트 recipe에 `states.disabledOpacity`가 있으면 그 값(SearchField·PasswordField·OtpField·NumberField·Select
+  0.5), 없으면 `fieldRecipe.disabledOpacity` 0.6(TextField·TextArea·Mentions·Field·NativeSelect·Combobox·DatePicker·TagsInput)이다.
+  2026-10-06 전에는 틀 전체가 흐려져 잠긴 이유를 적은 도움말까지 대비가 떨어졌다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 컨트롤 최소 높이 44(`control.minTouchTarget`), 안쪽 여백 좌우 `spacing.md`(16)·위아래 `spacing.sm`(12), 테두리 1. 여러 줄 입력은 최소 80(`fieldRecipe.multilineMinHeight`)이고 `minVisibleLines`를 줘도 이 하한 아래로 내려가지 않는다(한 줄 시작은 MessageComposer 내부만). 폭은 부모를 채운다 | `base-recipes.ts` `fieldRecipe`, `styles.css` `.hjm-field__control` |
+| 간격 | 라벨과 컨트롤 사이 `spacing.xs`(8). 컨트롤과 도움말·오류 사이는 Web `spacing.xs`(8), Native 내장 필드 6(`fieldRecipe.support.gap`)이다. 필드 사이 간격은 [Form](form.md) `density`가 정한다(`comfortable` `spacing.lg` 20). Form 없이 쌓을 때는 Stack `gap`으로 같은 값을 쓴다 | `styles.css` `.hjm-field`, `react-native/src/internal/field-frame.tsx` |
+| 순서·정렬 | 위→아래 순서는 라벨 → 컨트롤 → 도움말 → 오류다. 필드 여러 개는 Form 안에 세로로 쌓는다 | `react-native/src/internal/field-frame.tsx` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 큰 글자에서는 컨트롤 높이가 줄 높이에 따라 커진다. 라벨·도움말은 줄바꿈하며 자르지 않는다 | `base-recipes.ts` `fieldRecipe` |
+
+## 꼭 지킬 것
+
+- 라벨·도움말·오류·placeholder는 i18n 키로 넣는다. 오류 문장에 도움말을 다시 쓰지 않는다.
+- 라벨을 숨기면 접근성 이름을 준다. Web `TextField`는 `label` 또는 `aria-label`, Native는 `label` 또는
+  `accessibilityLabel`이 없으면 `TypeError`를 던진다.
+- 정렬·높이는 `align`·`variant`·`shape` 축으로 바꾼다. Native `TextField`는 `style`을 받지 않고 배치는 `layoutStyle`로만 한다.
+- 커스텀 컨트롤에는 render-prop 값을 그대로 펼쳐 라벨 연결을 끊지 않는다. Web `Field`는 `controlId`가 필수다.
+- 비활성인 이유는 도움말(`description`)에 적는다. 도움말·오류는 흐려지지 않으므로 제품에서 따로 흐리게 하거나 색을 바꾸지 않는다.
+
+### GestureSheetInput (Native optional-extension)
+
+`GestureSheet` 안에서 키보드를 따라 움직이는 입력이다. `BottomSheetTextInput`의 props를 그대로 받고
+TextField와 같은 테두리·글꼴·placeholder 색을 입힌다. 라벨·도움말·오류 틀은 없으므로 접근성 이름을 직접 준다.
+`/sheet-gesture`만 이 optional peer를 요구한다: `@gorhom/bottom-sheet` `5.2.14`, `react-native-reanimated`(이 파일이
+직접 import), 그리고 문서 기준 Gesture Handler `2.32.0`·Worklets `0.10.1`과 `GestureHandlerRootView`·`GestureSheetProvider`
+설정. 없으면 tsc는 통과하고 기기 번들에서 실패한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 값 콜백 | `onValueChange`(+ DOM `onChange`) | `onValueChange` |
+| `TextField` 앞뒤 슬롯 | `leading`, `trailing` | 없음 |
+| `TextField` 진행 중 | 없음 | `busy`(편집 막음, 접근성 busy) |
+| `Field` 라벨 | `label` ReactNode + `controlId` | `label` string, `controlId` 없음 |
+| 비활성 커스텀 `Field` | 틀이 라벨과 자식 컨트롤을 함께 흐린다 | 라벨만 흐린다. 컨트롤은 감싸는 View 없이 틀의 직계 자식이라 `accessibilityState.disabled`를 보고 스스로 흐린다 |
+| 배치 | `layoutStyle`(틀 `.hjm-field`) · `fieldClassName`(틀) · `className`·`style`(안쪽 `<input>`) | `layoutStyle`(`Field`·`TextField` 모두). `TextField`는 `style`을 받지 않는다 |
+| 나머지 props·ref | `<input>` HTML 속성(`type`·`autoComplete`·`inputMode` 등)과 ref(`HTMLInputElement`) 전달 | RN `TextInput` props(`keyboardType`·`autoCapitalize`·`textContentType`·`returnKeyType`·`onSubmitEditing` 등)와 ref(`TextInput`) 전달. `style`·`onChangeText`는 받지 않는다 |
+
+## 함정
+
+- Web `TextField`의 `style`은 틀이 아니라 안쪽 `<input>`에 붙는다. 필드 전체의 바깥 여백·폭은 `layoutStyle`로 준다.
+- Native `TextField`·`Field`의 `error`·`description`은 `string`이라 `exactOptionalPropertyTypes`에서 `undefined`를 받지
+  않는다(TS2375). 위 예처럼 조건부 spread로 넘긴다. Web은 `ReactNode`라 `undefined`를 그대로 넘겨도 된다.
+- Web `Field`는 `controlId`가 필수이고, Native `Field`에는 `controlId`가 없다. 공용 코드에서 같은 props 객체를 넘기지 않는다.

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

@@ -0,0 +1,114 @@
+# FilePicker
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [FilePicker](../../file-picker.md), 판정 `resolveFilePickerSelection`(`@hjmds/design-contracts/components/file-picker`)
+- 스토리북: `배포/컴포넌트/입력/파일 선택`
+
+## 언제 쓰나
+
+사용자가 업로드할 로컬 파일을 고르게 할 때 쓴다. 받는 형식(`accept`), 최대 크기, 최대 개수를
+descriptor로 선언하면 선택 결과가 `{ accepted, rejected }`로 함께 돌아온다. FilePicker는 "무엇을
+골랐는가"까지만 소유한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 업로드 진행·성공·실패·재시도 표시 | [UploadItem](upload-item.md) |
+| 파일이 아닌 텍스트 값 입력 | [Field](field.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `FilePicker` | 기본 | `@hjmds/react`, `/file-picker`, `/forms` | `@hjmds/react-native`, `/file-picker`, `/inputs` |
+
+결과 타입(`FilePickerSelectionResult`, `FilePickerCandidate`)은 `@hjmds/design-contracts/components/file-picker`에 있다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { FilePicker } from "@hjmds/react/file-picker";
+
+<FilePicker
+  descriptor={{ mode: "multiple", accept: ["image/*", ".pdf"], maxSizeBytes: 10_000_000, maxCount: 5 }}
+  label={t("attach.label")}
+  buttonLabel={t("attach.choose")}
+  dropzoneLabel={t("attach.drop")}
+  existingCount={files.length}
+  onSelect={({ accepted, rejected }) => { addFiles(accepted); reportRejected(rejected); }}
+/>
+```
+
+```tsx
+// Native
+import { FilePicker } from "@hjmds/react-native/file-picker";
+
+<FilePicker
+  descriptor={{ accept: ["application/pdf"], maxSizeBytes: 10_000_000 }}
+  label={t("attach.label")}
+  buttonLabel={t("attach.choose")}
+  onPick={pickWithDocumentPicker} // 제품 adapter: 취소면 null, 아니면 FilePickerCandidate[]
+  onPickError={reportPickError}
+  onSelect={({ accepted, rejected }) => { addFiles(accepted); reportRejected(rejected); }}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `descriptor.mode` | `single` · `multiple` | `single` | `maxCount`는 `multiple`에서만 쓴다. `single`에 주면 던진다 |
+| `existingCount` | 0 이상 정수 | `0` | 여러 번 나눠 고르는 흐름은 이미 고른 개수를 넘겨야 `maxCount`가 누적으로 판정된다 |
+| `descriptor` | `{ mode?, accept?: readonly string[], maxSizeBytes?, maxCount? }` | — | `accept`는 MIME 패턴(`image/*`) 또는 확장자(`.pdf`). 비우면 제한 없음 |
+| `onSelect` | `(result: { accepted: readonly FilePickerCandidate[]; rejected: readonly FilePickerRejection[] }) => void` | 필수 | 받아들인 것과 거부한 것을 한 번에 준다 |
+| 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 규칙 |
+| `disabled` | `true` · `false` | `false` | — |
+| `hint`, `error` | 문구 | — | 선택 사항이다 |
+
+- `FilePickerCandidate`: `{ id, name, mimeType, sizeBytes }`(`mimeType`은 플랫폼이 못 정하면 `""`).
+- `FilePickerRejection`: `{ file, reason: "unsupported-type", accept }` · `{ file, reason: "too-large", maxSizeBytes }` ·
+  `{ file, reason: "count-exceeded", maxCount }`. 거부 문장은 `reason`과 함께 오는 한계값으로 만든다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | Web 진입부는 dropzone이다. 점선 테두리 1, radius `radius.lg`(16), 안쪽 여백 `spacing.xl`(24), 최소 높이 8rem(128). 폭은 부모를 채운다. 버튼(Native trigger 포함)은 최소 높이 44(`control.minTouchTarget`), 좌우 여백 `spacing.md`(16)다 | `file-picker.ts` `filePickerRecipe`, `styles.css` `.hjm-file-picker__dropzone` |
+| 간격 | 항목 간격은 Web `spacing.xs`(8), Native 6이다. dropzone 안 문구와 버튼 사이 간격은 `spacing.sm`(12)이다 | `styles.css` `.hjm-file-picker`, `react-native/src/file-picker.tsx` |
+| 순서·정렬 | 위→아래 순서는 라벨 → 진입부 → 도움말 → 오류다. dropzone 안에 문구와 버튼을 가운데 정렬로 쌓는다. Native trigger는 테두리 1·radius 12 상자로 시작 쪽에 붙고(`alignSelf: flex-start`) 내용 폭만큼만 차지한다. 고른 파일 목록은 FilePicker 아래에 [UploadItem](upload-item.md)으로 따로 쌓는다. FilePicker 안에 넣지 않는다 | `react/src/file-picker.tsx`, `react-native/src/file-picker.tsx` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | — | — |
+
+## 꼭 지킬 것
+
+- 라벨·버튼·dropzone 문구와 거부 문장은 제품이 i18n 키로 만든다. 거부 문장은 `reason`과 한계값으로
+  만들고 색으로만 알리지 않는다.
+- `rejected`가 있어도 `accepted`는 그대로 쓴다. 한 장이 막혔다고 전체 선택을 버리지 않는다.
+- FilePicker는 선택 목록을 쌓지 않는다. 고른 파일 목록·업로드 상태는 제품 상태와 UploadItem이 소유한다.
+- Native 실제 OS document/image picker 연결(`onPick`)은 제품 책임이다. 패키지는 이를 구현하거나
+  기기에서 검증하지 않는다. 제품 릴리스 QA에서 확인한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 파일 진입 | 숨긴 `<input type="file">` + 보이는 버튼 + dropzone | 제품 adapter `onPick`(비동기) |
+| 필수 prop 차이 | `dropzoneLabel` | `onPick`, `onPickError` |
+| 드래그 앤 드롭 | 있음(버튼과 항상 함께) | 없음 |
+| 진행 중 잠금 | 없음 | `onPick` 대기 중 버튼 `busy`·비활성 |
+| `label`·`hint`·`error` 타입 | `ReactNode` | `string` |
+| 후보 id | `getCandidateId`(기본 `name:size:lastModified:index`) | adapter가 `id`를 채움 |
+| 배치 | `layoutStyle`(루트), `className`과 div 속성 | `layoutStyle`. `style`은 deprecated(개발 모드 1회 경고, 다음 major 제거) — `layoutStyle` 또는 recipe |
+
+## 함정
+
+- Native `onPick`이 reject하면 `onSelect`는 불리지 않고 `onPickError`로만 전달된다. 빈 함수로 두면 피커 실패가 화면에 남지 않는다.
+- 브라우저 `accept`와 OS 피커 필터는 힌트일 뿐이다. 거부 판정은 반드시 `onSelect` 결과로 처리한다.