@hjmds/design-contracts 1.12.1 → 1.13.1

package/docs/usage/components/photo-source-sheet.md

@@ -0,0 +1,119 @@
+# PhotoSourceSheet
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: 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 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/구성/선택과 필터/사진 촬영과 앨범 선택`
+
+## 언제 쓰나
+
+사진 버튼 하나에서 **앨범에서 고르기 / 촬영하기**를 고르게 할 때 쓴다. [Sheet](sheet.md)와 Button 두 개의
+조합이며 출처 선택만 한다. 권한 요청·카메라 실행·파일 선택·업로드는 `onSelect`에서 제품이 한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 여러 사진 선택·순서·업로드 상태 | [MediaSelectionScreen](media-selection-screen.md) |
+| 파일 일반 선택 | [FilePicker](file-picker.md) |
+| 업로드 진행 한 건 | [UploadItem](upload-item.md) |
+| 사진을 받지 않는 입력(댓글 등) | 추가하지 않는다 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `PhotoSourceSheet` | supplemental, 루트 barrel에 없음 | `/screen-flows` | `/screen-flows` |
+
+`@hjmds/react/screen-flows`, `@hjmds/react-native/screen-flows`로만 import한다. 추가 optional peer는 없다.
+HJM은 Expo·브라우저 카메라 SDK에 의존하지 않는다.
+
+## 최소 사용 예
+
+```tsx
+// Web — 숨긴 file input을 onSelect 콜스택 안에서 클릭한다
+import { useRef, useState } from "react";
+import { PhotoSourceSheet } from "@hjmds/react/screen-flows";
+
+export function PhotoPicker() {
+  const [open, setOpen] = useState(false);
+  const library = useRef<HTMLInputElement>(null);
+  const camera = useRef<HTMLInputElement>(null);
+  return <>
+    <input ref={library} type="file" accept="image/*" multiple hidden onChange={addFiles} />
+    <input ref={camera} type="file" accept="image/*" capture="environment" hidden onChange={addFiles} />
+    <PhotoSourceSheet
+      open={open}
+      onOpenChange={setOpen}
+      labels={{
+        title: t("photo.source.title"),
+        library: t("photo.source.library"),
+        camera: t("photo.source.camera"),
+        cancel: t("common.cancel"),
+      }}
+      onSelect={(source) => (source === "camera" ? camera : library).current?.click()}
+    />
+  </>;
+}
+```
+
+```tsx
+// Native
+import { PhotoSourceSheet } from "@hjmds/react-native/screen-flows";
+
+<PhotoSourceSheet
+  open={open}
+  onOpenChange={setOpen}
+  labels={{
+    title: t("photo.source.title"),
+    library: t("photo.source.library"),
+    camera: t("photo.source.camera"),
+    cancel: t("common.cancel"),
+  }}
+  cameraAvailable={hasCamera}
+  onSelect={(source) => (source === "camera" ? takePhoto() : pickFromLibrary())}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `open` | `boolean` | 필수 | 제어형 열림 |
+| `onOpenChange` | `(open: boolean) => void` | 필수 | 닫기·선택 시 `false` |
+| `onSelect` | `(source: "library" \| "camera") => void` | 필수 | 고르면 시트를 닫고(`onOpenChange(false)`) 호출한다. 호출 시점은 플랫폼 차이 참고 |
+| `labels` | `{ title, library, camera, cancel }` | 필수 | `cancel`은 Sheet 닫기 버튼 이름 |
+| `cameraAvailable` | `boolean` | `true` | `false`면 촬영 버튼을 숨긴다. 기기 카메라 유무는 제품이 판단한다 |
+| `disabled` | `boolean` | `false` | 두 버튼을 막고 선택을 무시한다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | Sheet 기본 `placement="bottom"`·`size="auto"`(내용 높이, 화면 높이 0.9 상한), Web 최대 폭 640; 선택 버튼은 `tone="secondary"` `Button` 두 개 | `sheetRecipe`, `screen-flows.tsx` |
+| 간격 | 시트 안 여백은 Sheet 소유(두 플랫폼 좌우 `spacing.lg` 20 · 위아래 `spacing.sm` 12 + 하단 safe area); 두 버튼 사이 `spacing.sm` 12; 바깥에 padding을 더하지 않는다 | Web `.hjm-sheet__body`, Native `sheetRecipe.content`, `Stack gap="sm"` |
+| 순서·정렬 | Sheet 제목·닫기 → 앨범 → 촬영(`cameraAvailable`일 때만) | Web `screen-flows.tsx` 59–60행, Native 50–51행 |
+| 고정·스크롤 | 화면 하단에 뜨는 오버레이(배경 막) — 선택 뒤 picker 호출 시점은 플랫폼 차이 참고 | `Sheet` |
+| 좁은 폭·큰 글자 | 버튼 문구는 줄바꿈되고 Sheet 높이가 늘어난다(0.9 상한을 넘으면 본문 스크롤); 카메라가 없으면 버튼 하나만 남는다 | `sheetRecipe.content.maxHeightRatio` |
+
+## 꼭 지킬 것
+
+- `labels`의 네 문구는 모두 i18n 키로 넣는다. 색은 HJM Provider 테마를 따른다.
+- 취소·권한 거부·기기 없음일 때 기존 초안과 첨부를 지우지 않는다. 권한 거부에는 앨범 대안을 안내한다.
+- EXIF 제거·크기·개수 제한·업로드는 제품 계약을 따른다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `onSelect` 호출 시점 | 클릭 콜스택 안에서 즉시(브라우저 사용자 활성화 보존) | 시트가 실제로 닫힌 뒤(`Sheet`의 dismiss 완료) |
+| `onSelect`에서 할 일 | 숨긴 `input[type=file]` 클릭. 촬영은 `capture="environment"` input을 따로 둔다 | 카메라 권한 요청 후 촬영, 또는 앨범 선택기 실행 |
+
+## 함정
+
+- Web에서 `onSelect` 안의 file input 클릭을 `setTimeout`·애니메이션 뒤로 미루면 브라우저가 거부할 수 있다. 같은 콜스택에서 클릭한다.
+- Native에서 닫히는 Modal 위에 카메라·선택기를 띄우면 iOS가 표시하지 못한다. 그래서 dismiss 완료 뒤에 호출되며, 제품이 타이머로 다시 앞당기지 않는다.
+- `capture`를 지원하지 않는 브라우저·기기는 OS 파일 선택 화면으로 대체될 수 있어 실제 촬영을 보장하지 않는다. 앨범 input에는 `capture`를 붙이지 않는다.

package/docs/usage/components/popover.md

@@ -0,0 +1,108 @@
+# Popover
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Popover](../../popover.md), [ConfirmPopover 조합](../../confirm-popover.md), `src/popover.ts`(`popoverRecipe`)
+- 스토리북: `배포/컴포넌트/오버레이/팝오버`
+
+## 언제 쓰나
+
+트리거에 붙어 뜨는 비모달 표면 안에 **포커스를 받는 임의 콘텐츠**를 둘 때 쓴다.
+작은 폼, 링크가 섞인 설명, 여러 control이 섞인 필터 묶음, 되돌릴 수 있는 행동의 짧은 확인이 여기에 속한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| stable id를 가진 action·선택 항목 목록 | [Menu](menu.md) |
+| 포커스가 들어가지 않는 한 문장 보충 설명 | [Tooltip](tooltip.md) |
+| 되돌릴 수 없는 파괴적 행동의 확인 | [AlertDialog](alert-dialog.md) |
+| 사용자가 반드시 응답해야 하는 모달 작업 | [Dialog](dialog.md) |
+| Native 앱의 같은 자리 | [Sheet](sheet.md) (Popover는 Web 전용) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Popover` | 기본 | `@hjmds/react`, `/popover` | — |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Button } from "@hjmds/react/actions";
+import { Popover } from "@hjmds/react/popover";
+
+<Popover
+  trigger={<Button tone="secondary">{t("filter.open")}</Button>}
+  title={t("filter.title")}
+  closeLabel={t("common.close")}
+  descriptor={{ placement: "bottom", align: "start" }}
+>
+  {({ close }) => <FilterForm onApply={() => { apply(); close(); }} />}
+</Popover>
+```
+
+Native 예는 없다(renderer 없음).
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `trigger` | 요소 하나 | 필수 | 여는 버튼. Popover가 ref·aria 속성을 붙인다 |
+| `title` · `closeLabel` | 문자열 | 필수 | 비면 던진다 |
+| `description` | 문자열 | — | 제목 아래 설명 |
+| `children` | 노드 또는 `(actions: { close(): void }) => ReactNode` | — | 콘텐츠 안에서 닫을 때 함수형을 쓴다 |
+| `openOn` | `press` · `hover` | `press` | `hover`는 지연된 포인터 진입(열기 300ms·닫기 150ms)을 **더할** 뿐이고 click/Enter/Space 경로는 그대로다 |
+| `descriptor` | `{ placement?, align?, accessibilityLabel? }` | — | |
+| `descriptor.placement` | `top` · `bottom` · `start` · `end` | `bottom` | |
+| `descriptor.align` | `start` · `center` · `end` | `start` | |
+| `dismissPolicy`(부분 지정) | `{ dismissible?, outsideDismiss?, escapeDismiss?, focusOutDismiss? }`(`boolean`) | 모두 `true` | |
+| `open` · `defaultOpen` | `boolean` | 비제어 `false` | 제어하면 `onOpenChange` 필수 |
+| `onOpenChange` | `(open: boolean, details: { reason }) => void` | — | `reason`: `trigger` · `close-action` · `outside-pointer` · `outside-focus` · `escape` · `programmatic` |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | 첫 포커스 가능 요소 | 열릴 때 처음 포커스 |
+| `portalContainer` | `HTMLElement` | `document.body` | 표면을 붙일 곳 |
+| `className` | 문자열 | — | `layoutStyle`은 받지 않는다(아래 함정) |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 폭 기본 360(`popoverRecipe.maxWidth`), 화면이 좁으면 최소 240(`minWidth`)까지 줄어든다. radius `radius.md` 12 | `popoverRecipe`, `src/popover.tsx` |
+| 간격 | 트리거와 8(`sideOffset` = `spacing.xs`), 화면 가장자리 8(`collisionPadding` = `spacing.xs`). 안쪽 `spacing.sm` 12. 제목·닫기 사이 8, 설명 위 8 · 아래 16, 본문 위 8 | `popoverRecipe`, `.hjm-popover*` |
+| 순서·정렬 | 기본 `placement="bottom"` `align="start"`. 안쪽은 제목과 닫기(`ghost`)가 한 줄 양 끝 → 설명 → 본문. 본문 행동은 끝 정렬, 보조 → 주([Button](button.md)) | `popoverDescriptorDefaults`, `.hjm-popover__header` |
+| 고정·스크롤 | 트리거에 붙는 portal(`layer.dropdown` 400; 모달 내부는 소유 모달 + 1). 공간이 모자라면 반대쪽으로 뒤집고 그래도 안 되면 다른 축으로 옮긴다(`fallbackAxis`). 넘치는 내용은 표면 안 스크롤 | `src/popover.tsx`, `useAnchoredPopup` |
+| 좁은 폭·큰 글자 | 제목 줄은 좁으면 감긴다. 폭은 240까지만 줄고 화면 안으로 제한된다 | `.hjm-popover__header`, `src/popover.tsx` |
+
+계약에는 화살표(`arrow` 4) 슬롯이 있지만 현재 Web renderer는 화살표를 그리지 않는다.
+
+```text
+ [필터 ▾]  ← 트리거
+    ↓ 8
+ ┌──────────────────────────────┐
+ │ 필터            [닫기]       │ ← 제목·닫기(ghost)
+ │ 설명 문구                    │
+ │ ─ 본문(스크롤) ───────────── │
+ │ ☐ 옵션 A                     │
+ │ ☐ 옵션 B                     │
+ │              [초기화] [적용] │ ← 보조 → 주
+ └──────────────────────────────┘
+   240 ~ 360, 화면 가장자리 8
+```
+
+## 꼭 지킬 것
+
+- `title`과 `closeLabel`은 비어 있으면 안 된다(던진다). 둘 다 i18n 키로 넣는다.
+- 행동 목록을 띄우려는 것이면 Popover가 아니라 Menu다. Popover 안에 menuitem 목록을 직접 만들지 않는다.
+- 처음 포커스 대상을 바꿔야 하면 `initialFocusRef`를 쓴다.
+- 콘텐츠 안에서 닫기는 children 함수 인자의 `close()`로 한다.
+- `className`은 배치에만 쓴다. 표면의 색·radius·그림자를 덮지 않는다.
+
+## 함정
+
+- Popover는 `layoutStyle`을 받지 않는다(Web `layoutStyle` 제외 15개 중 하나). 렌더하는 것이 제품 trigger와 떠 있는 portal뿐이라
+  배치는 trigger 쪽(또는 감싼 요소)에서 한다.
+- 부모 Popover가 닫히면 안에 중첩된 Popover도 닫히고 `onOpenChange(false, { reason: "programmatic" })`가 온다. 제어형이면 이 reason도 처리한다.

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

@@ -0,0 +1,89 @@
+# ProfileScreen
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: 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 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/화면/계정/프로필`
+
+## 언제 쓰나
+
+내 프로필(또는 계정) 화면 틀에 쓴다. 상단 요약, 그 아래 “프로필 수정” 보조 버튼, 이어지는 본문,
+맨 아래 계정 행동(로그아웃·탈퇴) 슬롯을 [ScreenLayout](screen-layout.md) 위에 이 순서로 쌓는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 섹션별 설정 항목이 중심 | [SettingsScreen](settings-screen.md) |
+| 프로필 수정 폼 자체 | [EditorScreen](editor-screen.md) |
+| 다른 사용자 프로필의 신고·차단 | [ModerationScreen](moderation-screen.md) |
+| 아바타 한 개 | [Avatar](avatar.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ProfileScreen` | supplemental, 루트 barrel에 없음 | `/screen-flows` | `/screen-flows` |
+
+`@hjmds/react/screen-flows`, `@hjmds/react-native/screen-flows`로만 import한다. 추가 optional peer는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ProfileScreen } from "@hjmds/react/screen-flows";
+
+<ProfileScreen
+  title={t("profile.title")}
+  summary={<ProfileSummary user={user} />}
+  edit={{ label: t("profile.edit"), onAction: openEditor }}
+  accountActions={<AccountActions onSignOut={signOut} onDelete={confirmDelete} />}
+  state={user ? { kind: "ready" } : { kind: "loading", title: t("profile.loading") }}
+>
+  <MyPostsSection />
+</ProfileScreen>
+```
+
+```tsx
+// Native — props는 Web과 같다
+import { ProfileScreen } from "@hjmds/react-native/screen-flows";
+
+<ProfileScreen
+  title={t("profile.title")}
+  summary={<ProfileSummary user={user} />}
+  edit={{ label: t("profile.edit"), onAction: openEditor }}
+  accountActions={<AccountActions onSignOut={signOut} onDelete={confirmDelete} />}
+  state={user ? { kind: "ready" } : { kind: "loading", title: t("profile.loading") }}
+>
+  <MyPostsSection />
+</ProfileScreen>
+```
+
+### 제품이 공급할 것
+
+| 슬롯·prop | 내용 |
+| --- | --- |
+| `summary` | 아바타·닉네임·소개 등 요약(필수). Avatar·Heading·Text를 제품이 조합한다 |
+| `edit` | 수정 진입 행동 `{ label, onAction, disabled?, pending? }`(필수). ghost 버튼으로 요약 아래에 놓인다 |
+| `children` | 활동·통계 등 본문 |
+| `accountActions` | 로그아웃·탈퇴 버튼 등. 본문 맨 아래 |
+| ScreenLayout props | `title`, `description`, `header`, `leading`, `actions`, `notice`, `state`, `stateAction` 등(`footer` 제외) |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | ScreenLayout 폭(최대 720); 수정은 ghost `Button` 기본 크기 | `ProfileScreen` |
+| 간격 | 화면 padding `spacing.md` 16; summary–수정 `spacing.md` 16; (summary·수정 묶음)–`children`–`accountActions` `spacing.xl` 24 | Web·Native `ProfileScreen` `Stack gap="xl"`·`gap="md"` |
+| 순서·정렬 | 헤더(제목) → summary → 수정 → `children` → `accountActions` | 렌더 순서 |
+| 고정·스크롤 | 헤더 고정, 본문 전체 화면 스크롤(footer 없음); 계정 행동은 본문 끝 | `ScreenLayout` |
+| 좁은 폭·큰 글자 | 요약 줄바꿈·아바타 크기는 `summary`(제품) 소유; 제목 열 최소 폭 120 × 글자 배율 | `screenPatternRecipe.headerMinWidth` |
+
+## 꼭 지킬 것
+
+- 계정 정보 조회, 인증, 로그아웃·탈퇴 mutation과 그 확인([AlertDialog](alert-dialog.md))은 제품 소유다.
+- 프로필 이미지·닉네임 문구 등 표시 데이터는 제품이 넘긴다. HJM은 계정 모델을 모른다.
+- 요약 자리에 브랜드 색을 하드코딩하지 않고 HJM 토큰·제품 테마로 연결한다.

package/docs/usage/components/progress.md

@@ -0,0 +1,122 @@
+# Progress
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Progress](../../progress.md), [Scroll progress](../../scroll-progress.md), `src/progress-recipe.ts`(`progressRecipe`)
+- 스토리북: `배포/컴포넌트/상태와 알림/진행 표시`, `배포/컴포넌트/상태와 알림/읽기 진행 표시`
+
+## 언제 쓰나
+
+작업이 얼마나 진행됐는지 보여 줄 때 쓴다. 업로드·내보내기 진행, 목표 대비 달성률,
+온보딩 단계 비율이 여기에 속한다. 진행량을 모르면 `value`를 생략해 불확정 진행으로 표시한다.
+읽기 진행률(스크롤 위치)은 같은 계약을 합성한 `ScrollProgress`를 쓴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 진행량 없이 “기다리는 중”만 표시 | [Spinner](spinner.md) |
+| 버튼 안의 처리 중 상태 | [Button](button.md)의 `loading` |
+| 파일 하나의 업로드 상태·재시도 | [UploadItem](upload-item.md) |
+| 단계 이름이 있는 흐름 | [Steps](steps.md) |
+| 사용자가 값을 조절 | [Slider](slider.md) |
+| 수치 강조 | [Statistic](statistic.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Progress` | 기본 | `@hjmds/react`, `/feedback` | `@hjmds/react-native`, `/feedback` |
+| `ScrollProgress` | 확장(스크롤 위치를 Progress로 표시, optional-extension, 추가 peer 없음) | `/scroll-progress` | `/scroll-progress` |
+| `useScrollMetrics` | 보조(Web 스크롤 host 측정 hook) | `/scroll-progress` | — |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Progress } from "@hjmds/react/feedback";
+
+<Progress label={t("upload.progress")} value={64} />
+```
+
+```tsx
+// Native
+import { Progress } from "@hjmds/react-native/feedback";
+
+<Progress label={t("upload.progress")} value={64} />
+```
+
+```tsx
+// Web
+// ScrollProgress — 실제 세로 스크롤 요소를 callback ref로 넘긴다
+import { useState } from "react";
+import { ScrollProgress, useScrollMetrics } from "@hjmds/react/scroll-progress";
+
+const [host, setHost] = useState<HTMLElement | null>(null);
+const metrics = useScrollMetrics(host);
+<>
+  <ScrollProgress label={t("article.readProgress")} metrics={metrics} size="small" />
+  <div ref={setHost} style={{ overflowY: "auto" }}>{article}</div>
+</>
+```
+
+Native `ScrollProgress`는 제품 ScrollView의 `onScroll`(contentOffset.y)·`onContentSizeChange`(height)·`onLayout`(height)로
+`metrics={{ offset, contentSize, viewportSize }}`를 만들어 넘긴다. 기존 콜백과 제스처는 그대로 둔다.
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | Web `ReactNode`(필수) · Native `string` | — | Native는 `label` 또는 `accessibilityLabel` 중 하나가 필수 |
+| `max` | 양수 | `100` | 두 renderer 동일. 0–1 비율이면 `max={1}`을 함께 준다 |
+| `value` | `0`~`max` | — | 생략하면 불확정 진행 |
+| `size` | `small` · `medium` · `large` | `medium` | 두께 4 · 8 · 12, circular 지름 24 · 40 · 64 |
+| `tone` | `brand` · `success` · `warning` · `danger` | `brand` | — |
+| `shape` | `linear` · `circular` | `linear` | `circular`일 때만 `children`(링 안 내용)을 그린다 |
+| `valueText` | 지역화 문구 | 백분율 문구 | 단위가 다른 문구가 필요하면 지역화해 넘긴다 |
+| `layoutStyle` | 배치 전용 style 객체 | — | 바깥 여백·폭만 |
+| `metrics`(ScrollProgress) | `{ offset: number; contentSize: number; viewportSize: number }` | 필수 | 타입 `ScrollMetrics`(`@hjmds/design-contracts/scroll-progress`). `viewportSize` 0이면 0%, 내용이 화면보다 짧으면 100% |
+| `useScrollMetrics`(Web) | `(host: HTMLElement \| null) => ScrollMetrics` | — | host의 스크롤·크기·자식 변화를 rAF로 모아 잰다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 두께(linear) `small` 4 · `medium` 8 · `large` 12, 모서리 `radius.full`, 폭은 부모를 채운다. circular 지름 `small` 24 · `medium` 40 · `large` 64, 획 3 · 4 · 6 | `progressRecipe.sizes`·`circular`, `.hjm-progress__native` |
+| 간격 | 문구 줄(label·값)과 막대 사이 `spacing.xs` 8. Web은 label과 값 문구 사이 `spacing.md` 16. 여러 개를 쌓을 때 간격은 감싸는 [Stack](stack.md)이 준다 | `.hjm-progress`, `.hjm-progress__copy`, Native `gap: spacing.xs` |
+| 순서·정렬 | label은 시작 쪽, 값 문구는 끝 쪽, 둘 다 막대 **위** 한 줄. circular도 문구 줄을 링 위에 두고 링은 시작 쪽에 붙는다(두 플랫폼) | `.hjm-progress[data-shape="circular"]`, Native `Progress` |
+| 고정·스크롤 | 고정되지 않는다. 카드·목록 행 본문 아래에 둔다. 스크롤 위치 표시는 `ScrollProgress`를 스크롤 영역 위에 둔다 | — |
+| 좁은 폭·큰 글자 | 문구 줄은 Native `flexDirection: "row"`로 줄바꿈 없이 양 끝 정렬된다. 긴 label은 짧은 i18n 문구로 둔다 | Native `Progress` |
+
+```text
+linear                               circular (Web)          circular (Native)
+업로드 중               64%          업로드 중 64%  ◯         업로드 중   64%
+   └─ gap spacing.xs 8                                       ◯
+████████████░░░░░░░  ← 8 (medium)
+```
+
+## 꼭 지킬 것
+
+- `value`와 `max`는 같은 단위로 넘긴다. `value={0.64}`만 넘기면 0.64%다([단위 표](../../progress.md)).
+  `max ≤ 0`, 범위 밖 `value`는 던진다.
+- 이름은 지역화한 `label`로 준다. Native는 보이는 label 없이 `accessibilityLabel`만 줄 수도 있다(`ScrollProgress`는 `label` 필수).
+- 색은 `tone`, 두께는 `size`로만 바꾸고 배치는 `layoutStyle`로 한다. Native의 `style`·`labelStyle`·`valueStyle`·`trackStyle`·`indicatorStyle`은
+  deprecated(개발 모드 경고, 다음 major 제거)다.
+- `ScrollProgress`는 window에 자동으로 붙지 않는다. Web은 스크롤 host를, Native는 측정값을 반드시 넘긴다.
+- 작업 완료율에는 `ScrollProgress`가 아니라 `Progress`를 쓴다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `label` 타입 | `ReactNode`, 필수 | `string`, 또는 `accessibilityLabel`만 |
+| 요소 | `<progress>` (ref 전달) | `accessibilityRole="progressbar"` View |
+| 보조 문구 | 없음 | `accessibilityHint` |
+| 스크롤 측정 | `useScrollMetrics(host)` | 제품이 ScrollView 이벤트로 계산 |
+
+## 함정
+
+- 1.12.0 전 Native `max` 기본값은 1이었다. 분수 값을 넘기던 옛 코드는 `max={1}`을 명시해야 한다([이관표](../../migration-native-legacy-removal.md)).

package/docs/usage/components/qr-code.md

@@ -0,0 +1,122 @@
+# QRCode
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [QRCode](../../qr-code.md), `src/qr-code-recipe.ts`(`qrCodeRecipe`)
+- 스토리북: `배포/컴포넌트/데이터 표시/큐알 코드`
+
+## 언제 쓰나
+
+문자열(초대 링크, 연결 코드, 결제·체크인 URL)을 다른 기기의 카메라로 스캔하게 할 때 쓴다.
+QR을 찍을 수 없는 사용자를 위한 대체 행동(링크 복사, 코드 직접 입력)을 항상 같이 둔다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 서버가 만든 QR 이미지를 그대로 보여 줌 | [Image](image.md) |
+| 짧은 코드를 사람이 읽고 입력함 | [Text](text.md), 입력 쪽은 [OTPField](otp-field.md) |
+| 링크를 눌러 이동 | [Link](link.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `QRCode` | 기본(root에서는 내보내지 않는다) | `/qr-code` | `/qr-code` |
+
+granular subpath로만 가져온다. 이 subpath는 optional peer를 import 한다.
+
+### 필요한 peer
+
+정확한 버전, `peerDependenciesMeta` optional.
+
+- Web: `qrcode-generator` 2.0.4
+- Native: `qrcode-generator` 2.0.4, `react-native-svg` 15.15.5(native 모듈, dev client 재빌드 필요)
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Button } from "@hjmds/react/actions";
+import { QRCode } from "@hjmds/react/qr-code";
+import { Stack } from "@hjmds/react/layout";
+import { spacing } from "@hjmds/design-contracts/foundations";
+
+<QRCode
+  value={inviteUrl}
+  label={t("invite.qrLabel")}
+  fallback={<Stack layoutStyle={{ marginTop: spacing.md }}><Button tone="secondary" onClick={copyLink}>{t("invite.copyLink")}</Button></Stack>}
+/>
+```
+
+```tsx
+// Native
+import { Button } from "@hjmds/react-native/actions";
+import { QRCode } from "@hjmds/react-native/qr-code";
+import { Stack } from "@hjmds/react-native/primitives";
+import { spacing } from "@hjmds/design-contracts/foundations";
+
+<QRCode
+  value={inviteUrl}
+  label={t("invite.qrLabel")}
+  size={224}
+  fallback={<Stack layoutStyle={{ marginTop: spacing.md }}><Button tone="secondary" onPress={copyLink}>{t("invite.copyLink")}</Button></Stack>}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | 문자열 | 필수 | 비면 `TypeError`, 용량 초과는 `RangeError` |
+| `label` | 문자열 | 필수 | 접근성 이름 |
+| `fallback` | `ReactNode` | 필수 | QR 아래에 그려지는 대체 행동(`null`·`false`면 `TypeError`) |
+| `size` | 숫자(px) | `192` | 실제 크기는 모듈 수의 정수배로 내림된다. 모듈당 2px 미만이면 `TypeError` |
+| `level` | `L` · `M` · `Q` · `H` | `M` | 오류 정정 수준 |
+| `layoutStyle` | 배치 전용 style 객체 | — | 루트 배치만(Native는 미게시(1.12.1 이후)) |
+
+콜백은 없다. `style`·`className`은 두 renderer 모두 없다. 1.12.1 Native는 `layoutStyle`이 없어 감싸는 레이아웃에서 배치한다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 기본 192×192. 실제 변은 (모듈 수 + 여백 4모듈×2)의 정수배로 내림돼 `size`보다 조금 작을 수 있다. 모듈당 최소 2px. 흰 여백 4모듈이 그림 안에 포함되므로 바깥에 흰 테두리를 또 두르지 않는다 | `qrCodeRecipe.quietZone`·`minModuleSize`, `qr-code.tsx` |
+| 간격 | QR과 `fallback` 사이 간격을 컴포넌트가 주지 않는다(Web CSS 없음, Native는 감싼 `View`만). `fallback` 슬롯 안의 [Stack](stack.md)에 `layoutStyle={{ marginTop: spacing.md }}`로 16을 준다. QRCode 바깥 Stack은 내부 두 요소의 간격을 바꿀 수 없다 | `packages/react/src/qr-code.tsx`, `packages/react-native/src/qr-code.tsx` |
+| 순서·정렬 | QR 위, `fallback` 바로 아래. 가운데 정렬은 감싸는 레이아웃이 한다 | 같은 파일 |
+| 고정·스크롤 | 고정되지 않는다. 카드·시트 본문 안에 둔다 | — |
+| 좁은 폭·큰 글자 | 좁은 폭에서 `size`를 화면 폭보다 크게 두지 않는다. 큰 글자에서도 QR 크기는 그대로이고 `fallback`만 커진다 | — |
+
+```text
+┌──────────────────────┐
+│      ┌────────┐      │
+│      │ ▓▒▓▒▓▒ │ 192  │  ← 흰 여백 4모듈 포함
+│      └────────┘      │
+│    (fallback marginTop md)      │
+│    [ 링크 복사 ]     │  ← fallback (필수)
+└──────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 앱에 peer가 설치돼 있는지 먼저 확인한다. 없으면 tsc·lint·단위 테스트는 통과하지만 기기 Metro 번들에서
+  `Unable to resolve module`로 죽는다(2026-10 utilverse, celebration 등 같은 부류 subpath 포함).
+  확인: `grep 'from "' node_modules/@hjmds/react-native/dist/qr-code.js`와 앱 `package.json` 비교.
+- `label`이 비었거나 `fallback`이 없거나(`null`/`false`) `size`가 모듈당 2px 미만이면 렌더 중
+  `TypeError`를 던진다. 빈 `value`·잘못된 `level`도 `TypeError`, 용량 초과는 `RangeError`다.
+  사용자 입력을 그대로 넣는 화면이면 error boundary 또는 길이 제한을 둔다.
+- 색은 테마와 무관하게 검정 모듈·흰 배경·4모듈 여백으로 고정된다. 브랜드 색·로고를 얹지 않는다.
+- 만료·인증·목적지 권한은 서버(제품) 소유다. QR 컴포넌트는 인코딩만 보증한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 그리기 | 인라인 `<svg role="img">` | `react-native-svg`, 감싼 `View`가 `accessibilityRole="image"` |
+| 필요한 peer | `qrcode-generator` | `qrcode-generator`, `react-native-svg` |
+| 배치 | `layoutStyle` | `layoutStyle`(미게시(1.12.1 이후), 1.12.1은 감싸는 View) |
+
+- 2026-10-06 독립 재구현에서 QRCode 바깥 Stack의 gap으로 내부 QR–fallback 간격을 바꿀 수 없음을 확인해 슬롯 안 여백 예제로 수정했다.