@hjmds/design-contracts 1.12.0 → 1.13.0

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

@@ -0,0 +1,131 @@
+# NumberField
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [NumberField](../../number-field.md), [DurationField](../../compound-controls.md#durationfield), `src/number-field.ts`(`numberFieldRecipe`)
+- 스토리북: `배포/컴포넌트/입력/숫자 입력`, `배포/컴포넌트/입력/소요 시간 입력`
+
+## 언제 쓰나
+
+범위가 정해진 **정확한 수 하나**를 입력받을 때 쓴다. 예약 인원, 수량, 글자 수 제한처럼
+“이 숫자 그대로”가 중요한 입력이다. 직접 타이핑과 한 단계씩 증감하는 버튼을 함께 제공한다.
+경과 시간(정수 초)은 NumberField 세 개를 합성한 `DurationField`를 쓴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 대략적인 값을 끌어서 고름 | [Slider](slider.md) |
+| 전화번호·우편번호·카드번호처럼 숫자로 된 문자열 | [Field](field.md)의 TextField |
+| 인증번호 | [OtpField](otp-field.md) |
+| 시각(몇 시 몇 분)·날짜 | [DatePicker](date-picker.md) |
+| 수치를 보여 주기만 함 | [Statistic](statistic.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `NumberField` | 기본 | `@hjmds/react`, `/forms`, `/number-field` | `@hjmds/react-native`, `/inputs`, `/number-field` |
+| `DurationField` | 시·분·초 세 칸 합성(optional-extension, 추가 peer 없음) | `/duration-field` | `/duration-field` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { NumberField } from "@hjmds/react/number-field";
+
+<NumberField
+  label={t("booking.guests")}
+  min={1}
+  max={10}
+  value={guests}
+  onValueChange={setGuests}
+  decrementLabel={t("booking.guests.decrease")}
+  incrementLabel={t("booking.guests.increase")}
+/>
+```
+
+```tsx
+// Native
+import { NumberField } from "@hjmds/react-native/number-field";
+
+<NumberField
+  label={t("booking.guests")}
+  min={1}
+  max={10}
+  value={guests}
+  onValueChange={setGuests}
+  decrementLabel={t("booking.guests.decrease")}
+  incrementLabel={t("booking.guests.increase")}
+/>
+```
+
+```tsx
+// Web — DurationField(Native도 같은 props, import는 `@hjmds/react-native/duration-field`). value는 정수 초
+import { DurationField } from "@hjmds/react/duration-field";
+
+const increaseKey = { hours: "timer.increase.hours", minutes: "timer.increase.minutes", seconds: "timer.increase.seconds" } as const;
+const decreaseKey = { hours: "timer.decrease.hours", minutes: "timer.decrease.minutes", seconds: "timer.decrease.seconds" } as const;
+
+<DurationField
+  value={seconds}
+  max={3 * 3600}
+  onValueChange={setSeconds}
+  labels={{
+    label: t("timer.duration"), hours: t("unit.hours"), minutes: t("unit.minutes"), seconds: t("unit.seconds"),
+    increment: (unit) => t(increaseKey[unit]), decrement: (unit) => t(decreaseKey[unit]),
+  }}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` · `defaultValue` | `number \| null` | `null` | `null`은 아직 입력하지 않은 상태 |
+| `onValueChange` | `(value: number \| null) => void` | — | blur 확정·증감 때 호출. 지운 채 확정하면 `null` |
+| `min` · `max` | 숫자 | 필수 | |
+| `step` | 양수 | 1 | |
+| `size` | `medium` · `large` | `medium` | |
+| `decrementLabel` · `incrementLabel` | 문자열 | 필수 | 증감 버튼의 접근성 이름 |
+| `getValueText` | `(value: number) => string` | — | 보조기기용 값 문구(단위·통화 등). 편집 문자열은 바꾸지 않는다 |
+| `inputMode` | `decimal` · `numeric` · `text` | 자동 | 생략하면 `min < 0`이면 `text`, 정수 step이면 `numeric`, 아니면 `decimal` |
+| `layoutStyle` | 배치 전용 style 객체 | — | 필드 전체 배치. Web `style`은 안쪽 input에 붙는다 |
+| `value`(DurationField) | 정수 초 | 필수 | 제어형만 |
+| `onValueChange`(DurationField) | `(seconds: number) => void` | 필수 | 단위 하나를 바꿔도 합친 초로 넘긴다(범위로 clamp) |
+| `labels`(DurationField) | `{ label, hours, minutes, seconds, increment: (unit) => string, decrement: (unit) => string }` | 필수 | `unit`은 `"hours" \| "minutes" \| "seconds"`. 키는 위 예처럼 상수 표로 고른다 |
+| `min`(DurationField) | 정수 초 | 0 | |
+| `max`(DurationField) | 정수 초 | 필수 | 1시간 미만이면 시 칸이 비활성 |
+
+타이핑은 blur에서 clamp·step snap으로 확정되고, 증감 버튼과 ↑/↓는 즉시 확정된다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 높이 `medium` 44(`fieldFrameContract.minHeight`) · `large` 52(`control.buttonHeight.large`). 증감 버튼 각 44×44(`control.minTouchTarget`) | `numberFieldRecipe.sizes`, `.hjm-number-field__stepper` |
+| 간격 | 라벨·입력·설명·오류 사이 `spacing.xs` 8. 값 좌우 `medium` 16(`spacing.md`) · `large` 20(`spacing.lg`). 버튼과 값은 1px 구분선. DurationField 칸 사이 `spacing.md` 16, 라벨과 칸 사이 `spacing.sm` 12 | `formSupportContract.gap`, `.hjm-number-field__input`, `duration-field.tsx` |
+| 순서·정렬 | `[−] [  값  ] [+]`: 감소가 시작 쪽, 증가가 끝 쪽(RTL 반전). 값은 가운데 정렬·고정폭 숫자. DurationField는 시 → 분 → 초 | `.hjm-number-field__*`, `duration-field.tsx` |
+| 고정·스크롤 | 폼 안에서 다른 Field와 같은 열. 폭은 부모를 따르고, 짧은 값이면 `layoutStyle`/`className`으로 폭을 줄여 라벨 아래에 둔다 | — |
+| 좁은 폭·큰 글자 | DurationField는 줄바꿈된다(Web 칸 최소 `10ch`, Native 칸 기준 폭 `spacing.xxxl` × 3 × 글자 배율) | `duration-field.tsx`(Web·Native) |
+
+## 꼭 지킬 것
+
+- `decrementLabel`·`incrementLabel`은 필수이며 i18n 키로 넣는다. 화면에 보이지 않아도 접근성 이름이다.
+- 단위·통화·소수 자릿수 표시는 만들지 않는다. 보조기기용 문구가 필요하면 `getValueText`로 제품이 포맷한다.
+- 제어형과 비제어형을 렌더 사이에 바꾸지 않는다(`value`를 넣었다 뺐다 하면 던진다).
+- `min ≥ max`, `step ≤ 0`, 범위 밖 `value`는 던진다. DurationField도 범위 밖·정수 아닌 초를 던진다.
+- 색·높이를 덮지 않는다. 배치는 `layoutStyle`로 한다. Native `inputStyle`·`containerStyle`은 deprecated(개발 모드 경고, 다음 major 제거) — 높이·글꼴은 `size`, 배치는 `layoutStyle`.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 역할 | `spinbutton`, `type="text"` | 입력 + 증감 button, accessibility action |
+| label·description·error 타입 | `ReactNode` | `string` |
+| 추가 이름 | 없음 | `accessibilityLabel`, `accessibilityHint` |
+| 클래스·스타일 | `className`, `inputClassName`, `layoutStyle`(필드 전체). `style`은 안쪽 input | `layoutStyle`(필드 전체). `inputStyle`·`containerStyle`은 deprecated |
+| DurationField 배치 | `className`, `layoutStyle`(fieldset) | `layoutStyle`(미게시(1.12.1 이후), 1.12.1은 감싸는 View) |

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

@@ -0,0 +1,106 @@
+# OnboardingScreen
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: 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 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/화면/소개/온보딩`
+
+## 언제 쓰나
+
+첫 실행 소개·초기 설정처럼 **몇 단계를 차례로 넘기는 화면**에 쓴다. 현재 단계의 제목·설명·본문,
+진행 문구(“2/4”), 다음·이전·건너뛰기·완료 행동을 [ScreenLayout](screen-layout.md) 위에 조합한다.
+단계 범위가 틀리면 렌더 중 던진다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 단계 표시만 필요(본문은 자유 배치) | [Steps](steps.md) |
+| 화면 위에 겹치는 기능 안내 | [Tour](tour.md) |
+| 권한 하나를 요청하는 단계 | [PermissionScreen](permission-screen.md) |
+| 좌우로 넘기는 이미지 소개 | [Carousel](carousel.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `OnboardingScreen` | supplemental, 루트 barrel에 없음 | `/screen-flows` | `/screen-flows` |
+
+`@hjmds/react/screen-flows`, `@hjmds/react-native/screen-flows`로만 import한다. 추가 optional peer는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { OnboardingScreen } from "@hjmds/react/screen-flows";
+
+<OnboardingScreen
+  steps={[
+    { id: "welcome", title: t("onboarding.welcome.title"), description: t("onboarding.welcome.body"), content: welcomeArt },
+    { id: "goal", title: t("onboarding.goal.title"), description: t("onboarding.goal.body"), content: goalPicker },
+  ]}
+  index={index}
+  onIndexChange={setIndex}
+  nextLabel={t("common.next")}
+  backLabel={t("common.back")}
+  complete={{ label: t("onboarding.start"), onAction: finish, pending: saving }}
+  skip={{ label: t("common.skip"), onAction: finish }}
+  progressLabel={(current, total) => t("onboarding.progress", { current, total })}
+/>
+```
+
+```tsx
+// Native — props는 Web과 같다
+import { OnboardingScreen } from "@hjmds/react-native/screen-flows";
+
+<OnboardingScreen
+  steps={[
+    { id: "welcome", title: t("onboarding.welcome.title"), description: t("onboarding.welcome.body"), content: welcomeArt },
+    { id: "goal", title: t("onboarding.goal.title"), description: t("onboarding.goal.body"), content: goalPicker },
+  ]}
+  index={index}
+  onIndexChange={setIndex}
+  nextLabel={t("common.next")}
+  backLabel={t("common.back")}
+  complete={{ label: t("onboarding.start"), onAction: finish, pending: saving }}
+  skip={{ label: t("common.skip"), onAction: finish }}
+  progressLabel={(current, total) => t("onboarding.progress", { current, total })}
+/>
+```
+
+### 제품이 공급할 것
+
+| prop | 내용 |
+| --- | --- |
+| `steps` | `{ id, title, description, content }[]`. 1개 이상. 제목·설명은 지역화 문자열, `content`는 단계 본문 |
+| `index`, `onIndexChange` | 현재 단계(0부터, 제어형). 범위를 벗어나면 던진다 |
+| `nextLabel`, `backLabel` | 다음·이전 문구. 첫 단계에는 이전이 없다 |
+| `complete` | 마지막 단계의 주 행동 `{ label, onAction, disabled?, pending? }` |
+| `skip` | 선택. 상단 actions 자리에 보조 버튼으로 놓인다 |
+| `progressLabel(current, total)` | 1부터 센 현재 단계와 전체 수로 진행 문구를 만든다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 한 단계의 ScreenLayout 폭(최대 720); 다음·완료·이전은 `Button` 기본 크기 | `OnboardingScreen` |
+| 간격 | 화면 padding `spacing.md` 16(진행 문구 notice는 좌우만); footer 다음/완료–이전 `spacing.sm` 12; 단계 본문 안 간격은 `content`(제품) 소유 | Web·Native `OnboardingScreen` `Stack gap="sm"` |
+| 순서·정렬 | 헤더(단계 제목·설명 → 건너뛰기 ghost) → 진행 문구(caption) → 단계 `content` → footer(다음 또는 완료 primary → 이전 ghost, 첫 단계는 이전 없음) | 렌더 순서 |
+| 고정·스크롤 | 헤더·진행 문구·footer 고정, 단계 본문 화면 스크롤 | `ScreenLayout` |
+| 좁은 폭·큰 글자 | 제목 열 최소 폭 120 × 글자 배율, 모자라면 건너뛰기가 다음 줄로 내려간다; footer 버튼은 세로로 쌓인다 | `screenPatternRecipe.headerMinWidth` |
+
+## 꼭 지킬 것
+
+- 단계에서 고른 값의 저장, 완료 여부 저장, 다시 보여 주지 않기는 제품 소유다. `complete.onAction`에서 처리한다.
+- ScreenLayout의 `header`·`state`·`contentInset` 같은 화면 props는 받지 않는다. 화면 틀을 바꿔야 하면 ScreenLayout으로 직접 조합한다.
+  배치 prop은 `layoutStyle` 하나이며 Web·Native 모두 화면 루트(ScreenLayout)에 넘긴다.
+- 문구·일러스트·브랜드 이미지는 제품 소유다. `content`에 제품 자산을 넣는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 배치 prop | `layoutStyle`(ScreenLayout 루트, 미게시(1.12.1 이후)) | `layoutStyle`(ScreenLayout 루트, 미게시(1.12.1 이후)) |

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

@@ -0,0 +1,101 @@
+# OtpField
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [OtpField](../../otp-field.md), `src/otp-field.ts`(`otpFieldRecipe`)
+- 스토리북: `배포/컴포넌트/입력/인증번호 입력`
+
+## 언제 쓰나
+
+문자·메일로 받은 **숫자 인증번호**를 칸 모양으로 입력받을 때 쓴다. 화면에는 칸이 여러 개 보이지만
+실제 입력은 하나라서 붙여넣기·지우기·SMS 자동 채움이 플랫폼 기본 동작으로 처리된다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 비밀번호·PIN처럼 가려야 하는 값 | [PasswordField](password-field.md) |
+| 영문이 섞인 코드(쿠폰·초대 코드) | [Field](field.md)의 TextField (`align="center"`) |
+| 범위가 있는 수량 | [NumberField](number-field.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `OtpField` | 기본 | `@hjmds/react`, `/forms`, `/otp-field` | `@hjmds/react-native`, `/inputs`, `/otp-field` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { OtpField } from "@hjmds/react/otp-field";
+
+<OtpField
+  label={t("verify.code")}
+  length={6}
+  value={code}
+  onValueChange={setCode}
+  onComplete={submitCode}
+  busy={verifying}
+  error={codeError ? t("verify.code.invalid") : undefined}
+/>
+```
+
+```tsx
+// Native
+import { OtpField } from "@hjmds/react-native/otp-field";
+
+<OtpField
+  label={t("verify.code")}
+  length={6}
+  value={code}
+  onValueChange={setCode}
+  onComplete={submitCode}
+  busy={verifying}
+  {...(codeError ? { error: t("verify.code.invalid") } : {})}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `length` | 2 이상의 정수 | 필수 | 값은 숫자만 남기고 `length`로 자른다(붙여넣은 하이픈·공백 허용) |
+| `value` · `defaultValue` | 숫자 문자열 | 비제어 `""` | 숫자가 아니거나 `length`보다 긴 제어값은 던진다 |
+| `onValueChange` | `(value: string) => void` | — | 정리된 숫자 문자열 |
+| `onComplete` | `(value: string) => void` | — | 값이 `length`에 **도달하는 순간** 한 번 호출된다. 처음부터 꽉 찬 값으로 마운트하면 호출되지 않는다 |
+| `size` | `medium` · `large` | `medium` | |
+| `presentation` | `boxes` · `underline` | `boxes` | |
+| `busy` | `boolean` | `false` | 서버 확인 중. 입력은 포커스를 유지한 채 읽기 전용이 된다 |
+| `description` · `error` | Web `ReactNode` · Native `string` | — | Native는 `undefined`를 받지 않아 조건부 spread로 넘긴다(위 예) |
+| `layoutStyle` | 배치 전용 style 객체 | — | 필드 전체(라벨·칸) 배치. Native는 1.13부터 숨은 TextInput이 아니라 바깥 frame에 붙는다. Web `style`은 안쪽 input에 붙는다 |
+
+자동 채움은 고정이다: Web `autoComplete="one-time-code"`·`inputMode="numeric"`, Native `textContentType="oneTimeCode"`·`keyboardType="number-pad"`.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 칸 `medium` 44(`control.minTouchTarget`) · `large` 52(`control.buttonHeight.large`). 전체 폭 최대 칸 × `length` + 간격 × (`length` − 1)(6자리 `medium` 304), 부모가 좁으면 칸이 줄어든다 | `otpFieldRecipe.sizes`, `.hjm-otp-field__control`, Native `maxWidth` |
+| 간격 | 칸 사이 `medium` 8(`spacing.xs`) · `large` 12(`spacing.sm`). 라벨·칸·설명·오류 사이 `spacing.xs` 8 | `otpFieldRecipe`, `formSupportContract.gap` |
+| 순서·정렬 | 안내 문구 아래, 다시 보내기·확인 행동 위. 칸 묶음은 시작 쪽, 가운데 정렬은 부모가 한다. RTL에서도 숫자는 왼쪽→오른쪽(`direction: ltr`) | `.hjm-otp-field__control`, Native `direction: "ltr"` |
+| 고정·스크롤 | 본문 흐름 안. `onComplete`로 자동 확인하면 확인 버튼을 생략할 수 있다. 확인 버튼을 두면 단독 화면 폼은 [BottomCTA](bottom-cta.md), Card 안 구성은 [인증번호 확인과 다시 입력](../compositions/stea-otp-verify.md)처럼 필드 아래 본문에 둔다 | — |
+| 좁은 폭·큰 글자 | Native 칸 높이 = max(칸 크기, 줄 높이 × 글자 배율 + 위아래 `spacing.xs`) | `react-native/src/inputs.tsx`(`OtpField`) |
+
+## 꼭 지킬 것
+
+- 칸마다 별도 input을 만들거나 OtpField를 칸별로 쪼개 쓰지 않는다. 접근성 이름·값이 하나여야 한다([계약](../../otp-field.md)).
+- `onComplete`에서 확인 요청을 보내고 `busy`로 잠근다. 실패하면 `error`에 지역화 문구를 넣고 값 초기화 여부는 제품이 정한다.
+- 숫자가 아닌 `value`, `length`보다 긴 `value`를 제어값으로 넣으면 던진다.
+- 배치는 `layoutStyle`(Web은 `className`도)로만 한다. 칸 색·테두리는 recipe 소유다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 이름 | `label` | `label` 또는 `accessibilityLabel`만 |
+| 칸 스타일 통로 | 없음 | `slotStyle`, `slotTextStyle`은 deprecated(개발 모드 경고, 다음 major 제거). 외형은 `size`·`presentation` |
+| busy 표현 | read-only + `aria-busy` | `editable={false}` + `accessibilityState.busy` |

package/docs/usage/components/pagination.md

@@ -0,0 +1,82 @@
+# Pagination
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Pagination](../../pagination.md), `src/pagination.ts`(`paginationRecipe`)
+- 스토리북: `배포/컴포넌트/탐색/페이지 이동`
+
+## 언제 쓰나
+
+총 개수(또는 총 페이지 수)가 정해진 결과 집합에서 사용자가 **임의의 페이지로 바로 이동**해야 할 때
+Web에서 쓴다. 검색 결과, 관리자 테이블, 기록 목록이 여기에 속한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 총량을 모르거나 계속 이어지는 피드 | [LoadMore](load-more.md) |
+| Native 긴 목록 | [LoadMore](load-more.md), [VirtualList](virtual-list.md) (Pagination은 Web 전용) |
+| 단계형 흐름의 이전/다음 | [Steps](steps.md) |
+| 이미지·카드 넘기기 | [Carousel](carousel.md) |
+
+한 목록에는 Pagination과 LoadMore 중 하나의 탐색 모델만 쓴다.
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Pagination` | 기본 | `@hjmds/react`, `/navigation`, `/pagination` | — |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Pagination } from "@hjmds/react/pagination";
+
+<Pagination
+  label={t("records.pagination")}
+  descriptor={{ currentPage: page, totalCount: total, pageSize: 20 }}
+  labels={{ previous: t("pagination.previous"), next: t("pagination.next") }}
+  composeAccessibleName={({ page, totalPages, current }) =>
+    t(current ? "pagination.current" : "pagination.goTo", { page, totalPages })}
+  onPageChange={(next) => setPage(next)}
+/>
+```
+
+Native 예는 없다(renderer 없음).
+
+## 축과 기본값
+
+타입은 `@hjmds/design-contracts/components/pagination`에서 가져온다.
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | 문자열 | 필수 | `<nav>` 이름. 비면 던진다 |
+| `descriptor` | `{ currentPage, totalCount, pageSize, siblingCount?, boundaryCount? }` 또는 `{ currentPage, totalPages, siblingCount?, boundaryCount? }` | 필수 | 정확히 하나의 형태. `currentPage`는 1부터 시작하는 정수 |
+| `siblingCount` · `boundaryCount`(descriptor 안) | 정수 | 1 | 생략된 구간은 말줄임으로 표시한다 |
+| `labels` | `{ previous: string; next: string }` | 필수 | 이전·다음 버튼 문구 |
+| `composeAccessibleName` | `(info: { page: number; totalPages: number; current: boolean }) => string` | 필수 | 페이지 버튼마다 부른다. 어순은 제품 i18n이 정한다 |
+| `onPageChange` | `(page: number, reason: "previous" \| "next" \| "page") => void` | 필수 | 제품이 `currentPage`를 바꾼다 |
+| `className` · `layoutStyle` | 문자열 · 배치 전용 style 객체 | — | 루트 배치만 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 각 칸 최소 44×44(`control.minTouchTarget`), radius `radius.md` 12 | `paginationRecipe.item`, `.hjm-pagination__item` |
+| 간격 | 칸 안쪽 `spacing.xs` 8, 칸 사이 `spacing.xxs` 4 | `paginationRecipe.gap`, `.hjm-pagination__list` |
+| 순서·정렬 | `[‹ 이전] [1] … [4] [5] [6] … [20] [다음 ›]`. 이전·다음은 아이콘 버튼(문구는 접근성 이름), RTL에서 화살표 반전. 정렬은 놓는 레이아웃이 정한다(관리자 테이블은 끝, 검색 결과는 가운데가 흔하다) | `src/pagination.tsx`, `.hjm-pagination__previous`·`__next` |
+| 고정·스크롤 | 목록·테이블 **바로 아래** 한 번. 페이지를 바꾸면 목록 시작으로 스크롤·포커스를 옮기는 것은 제품이 한다 | — |
+| 좁은 폭·큰 글자 | 폭이 모자라면 줄바꿈된다(`flex-wrap`). 좁은 폭에서는 `siblingCount`·`boundaryCount`를 0~1로 줄여 한 줄을 유지한다 | `.hjm-pagination__list` |
+
+## 꼭 지킬 것
+
+- `label`(nav 이름)은 비어 있으면 던진다. `labels`와 `composeAccessibleName`이 만드는 페이지 이름까지 모두 제품 i18n에서 만든다.
+  어순·조사는 제품이 조립하고, 현재 페이지 여부·총 페이지 계산은 HJM이 넘겨 준다.
+- `currentPage`는 제어값이다. `onPageChange`에서 제품 상태를 바꾸고 데이터 요청·URL 동기화는 제품이 한다.
+- 범위 밖 `currentPage`(0 이하, 총 페이지 초과)는 던진다. 결과 개수가 줄면 페이지를 먼저 보정한다.
+- 페이지 크기 변경·페이지 번호 직접 입력은 없다. 필요하면 별도 컴포넌트로 옆에 합성한다.
+- `className`·`layoutStyle`은 배치에만 쓴다.

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

@@ -0,0 +1,137 @@
+# PasswordField
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [PasswordField](../../password-field.md), `src/password-field.ts`(`passwordFieldRecipe`)
+- 스토리북: `배포/컴포넌트/입력/비밀번호 입력`
+
+## 언제 쓰나
+
+비밀번호를 입력받고, 필요할 때만 값을 눈으로 확인하게 할 때 쓴다. 로그인, 가입,
+비밀번호 변경, 이메일 계정 연결 화면의 비밀번호 칸이 여기에 속한다.
+
+소셜 전용 제품의 이메일·비밀번호 칸은 스토어 심사자 폼뿐이다(루트 `docs/LOGIN_SCREEN_STANDARD.md` LS-07). 서버 env와
+`review=1`이 모두 맞을 때만 [AuthScreenLayout](auth-screen-layout.md) `main` 카드 안, 개발 버튼 다음에 제목
+(`Text variant="label"`)과 한 줄 설명을 붙여 그린다. 제출 버튼은 제공자 버튼보다 낮은 `tone="secondary"`, `size="medium"`이다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 문자로 받은 숫자 인증번호 | [OtpField](otp-field.md) |
+| 가릴 필요가 없는 일반 텍스트 | [Field](field.md)의 TextField |
+| 소셜 로그인 | [AuthProviderButton](auth-provider-button.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `PasswordField` | 기본 | `@hjmds/react`, `/forms`, `/password-field` | `@hjmds/react-native`, `/inputs`, `/password-field` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { PasswordField } from "@hjmds/react/password-field";
+
+<PasswordField
+  label={t("auth.password")}
+  autofillHint="current"
+  revealLabel={t("auth.password.show")}
+  concealLabel={t("auth.password.hide")}
+  value={password}
+  onValueChange={setPassword}
+  error={passwordError}
+/>
+```
+
+```tsx
+// Native — 로그인 폼: return 키로 아이디 → 비밀번호 → 제출(LS-10)
+import { useRef } from "react";
+import type { TextInput } from "react-native";
+import { TextField } from "@hjmds/react-native/inputs";
+import { PasswordField } from "@hjmds/react-native/password-field";
+
+const passwordRef = useRef<TextInput>(null);
+
+<>
+<TextField
+  label={t("auth.email")}
+  keyboardType="email-address"
+  autoCapitalize="none"
+  textContentType="username"
+  returnKeyType="next"
+  onSubmitEditing={() => passwordRef.current?.focus()}
+  value={email}
+  onValueChange={setEmail}
+/>
+<PasswordField
+  ref={passwordRef}
+  label={t("auth.password")}
+  autofillHint="current"
+  revealLabel={t("auth.password.show")}
+  concealLabel={t("auth.password.hide")}
+  returnKeyType="go"
+  onSubmitEditing={() => { if (canSubmit) void submit(); }}
+  value={password}
+  onValueChange={setPassword}
+  {...(passwordError ? { error: passwordError } : {})}
+/>
+</>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` · `defaultValue` | 문자열 | 비제어 `""` | |
+| `onValueChange` | `(value: string) => void` | — | Web은 DOM `onChange`도 함께 받는다 |
+| `autofillHint` | `current`(로그인) · `new`(가입·변경) | 필수 | Web은 `current-password`/`new-password`, Native는 iOS `textContentType` `password`/`newPassword`로 번역된다 |
+| `revealLabel` · `concealLabel` | 문자열 | 필수 | 토글의 접근성 이름. 각각 "누르면 보임"·"누르면 숨김" 행동 문구 |
+| `revealed` · `defaultRevealed` | `boolean` | `false` | 가림 상태(제어·비제어). 값과 독립된 축이다 |
+| `onRevealedChange` | `(revealed: boolean) => void` | — | 토글을 누를 때 |
+| `size` | `medium` · `large` | `medium` | |
+| `renderToggleIcon` | `(props: { name: "visibility" \| "visibilityOff"; color; size: number; revealed: boolean; disabled: boolean }) => ReactNode` | HJM 기본 아이콘 | 토글 아이콘을 바꿀 때 쓴다. `color`는 Web `"currentColor"`, Native 테마 색 문자열 |
+| `description` · `error` | Web `ReactNode` · Native `string` | — | 규칙 안내·검증 실패 문구 |
+| `layoutStyle` | 배치 전용 style 객체 | — | 필드 전체 배치. Web `style`은 안쪽 input에 붙는다 |
+| `ref` | Web `HTMLInputElement` · Native `TextInput` | — | return 키로 다음 칸 focus를 옮길 때 쓴다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 높이 `medium` 44(`fieldFrameContract.minHeight`) · `large` 52(`control.buttonHeight.large`). 토글 44×44 원형(`control.minTouchTarget`) | `passwordFieldRecipe.sizes`, `.hjm-password-field__toggle` |
+| 간격 | 라벨·입력·설명·오류 사이 `spacing.xs` 8. 입력 좌우 `medium` 16(`spacing.md`) · `large` 20(`spacing.lg`) | `formSupportContract.gap`, `passwordFieldRecipe.sizes` |
+| 순서·정렬 | 아이디(이메일) Field 바로 아래. 가입·변경은 새 비밀번호 → 확인. 토글은 입력 칸 **끝**(RTL에서는 시작) 안쪽 | `.hjm-password-field__toggle` |
+| 고정·스크롤 | 폼 흐름 안. 제출은 이 칸 아래, 같은 폼의 행동이다(Web [Form](form.md) `actions`, Native는 Form 내장 버튼 또는 `Stack` + `Button`). 로그인·심사자 폼은 AuthScreenLayout `main` 카드 안에 두고 하단에 고정하지 않는다. 그 안에서는 바깥 `ScrollView`·`Container`·`KeyboardAvoidingView`로 다시 감싸지 않는다(키보드 inset·드래그 내리기·탭 유지는 레이아웃이 가진다, LS-10) | LS-07, LS-10, `authScreenRecipe` |
+| 좁은 폭·큰 글자 | 폭은 같은 폼의 다른 Field와 맞춘다 | — |
+
+## 꼭 지킬 것
+
+- `revealLabel`(가려져 있을 때 = 누르면 보임)과 `concealLabel`(보일 때 = 누르면 숨김)은 **행동** 문구로 지역화한다. “숨겨짐” 같은 상태 문구를 넣지 않는다.
+- `autofillHint`는 화면 목적에 맞게 제품이 정한다. 로그인 화면에 `new`를 주면 OS·브라우저 자동 채움이 깨진다.
+- `type`·`autoComplete`(Web), `secureTextEntry`·`textContentType`(Native)은 Props에서 제외돼 있다. 직접 넘기지 않는다.
+- 비밀번호 규칙 문구는 `description`, 검증 실패는 `error`에 지역화해 넣는다. 규칙 자체는 제품 소유다.
+- 배치는 `layoutStyle`(Web은 `className`/`fieldClassName`도)로만 한다.
+- 토글에 눌림·선택 상태를 덧붙이지 않는다. 이름이 이미 다음 행동("비밀번호 보이기/숨기기")을 말하므로 상태를 더하면
+  "비밀번호 숨기기, 선택됨"처럼 두 답이 읽힌다(계약 [PasswordField](../../password-field.md) 2026-10-06 정정).
+- Native 로그인 폼은 return 키를 잇는다(LS-10). 아이디 칸은 `returnKeyType="next"` + `onSubmitEditing`에서 PasswordField
+  `ref.focus()`, PasswordField는 `returnKeyType="go"` + `onSubmitEditing`에서 제출하되 버튼의 disabled 조건을 그대로 따른다.
+  Native `Form`은 밖에서 제출을 부를 수 없으므로 return 제출이 필요한 폼은 Form 대신 `Stack` + `Button`(`loading`)으로 짠다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 이름 | `label` | `label` 또는 `accessibilityLabel`만 |
+| 토글 | 다음 행동을 이름으로 가진 `<button>`(상태 속성 `aria-pressed` 없음), 토글 후 선택 영역 복원 | `button` + 다음 행동 `accessibilityLabel`, `accessibilityState`는 `disabled`만(`selected` 없음) |
+| 이벤트 | `onValueChange`와 DOM `onChange` 둘 다 | `onValueChange` |
+| ref·나머지 props | `HTMLInputElement`, `<input>` HTML 속성(`type`·`autoComplete` 제외) | `TextInput`, RN `TextInput` props(`returnKeyType`·`onSubmitEditing` 등, `secureTextEntry`·`textContentType`·`style` 제외) |
+
+## 함정
+
+- Native `error`·`description`은 `string`이라 `exactOptionalPropertyTypes`에서 `undefined`를 받지 않는다(Web은 `ReactNode`라 통과).
+  값이 없을 수 있으면 위 예처럼 조건부 spread로 넘긴다.

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

@@ -0,0 +1,107 @@
+# PermissionScreen
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: 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 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/화면/소개/권한 안내`
+
+## 언제 쓰나
+
+카메라·위치·알림 같은 권한이 **왜 필요한지 설명하고 다음 행동을 고르게 하는** 화면에 쓴다.
+제품이 넘긴 권한 상태에 따라 하단 주 행동 하나를 고른다.
+
+| `status` | 주 행동 |
+| --- | --- |
+| `prompt` | `request` |
+| `denied` | `settings` |
+| `granted` | `continueAction` |
+| `unavailable` | 없음(`skip`만 표시 가능) |
+
+PermissionScreen은 **OS 권한을 요청하지도, 조회하지도 않는다.** 소스(`screen-flows.tsx`, 두 renderer)는
+`react`·`react-native`의 `View` 외에 권한·설정 API를 import하지 않고, 버튼은 넘겨받은 `onAction`만 호출한다.
+실제 권한 요청, 설정 앱 열기, 앱 복귀 후 권한 재조회와 `status` 갱신은 모두 제품이 한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 화면 일부에 “권한이 꺼져 있음” 안내 | [Notice](notice.md) |
+| 접근 제한으로 본문을 대체 | [ScreenLayout](screen-layout.md)의 `state={{ kind: "restricted", ... }}` |
+| 사진 앨범·촬영 선택 | [PhotoSourceSheet](photo-source-sheet.md) |
+| 여러 단계 첫 실행 소개 | [OnboardingScreen](onboarding-screen.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `PermissionScreen` | supplemental, 루트 barrel에 없음 | `/screen-flows` | `/screen-flows` |
+
+`@hjmds/react/screen-flows`, `@hjmds/react-native/screen-flows`로만 import한다. 추가 optional peer는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web — 브라우저는 설정 화면을 열 수 없으므로 settings는 브라우저 권한 안내로 연결한다
+import { Text } from "@hjmds/react/layout";
+import { PermissionScreen } from "@hjmds/react/screen-flows";
+
+<PermissionScreen
+  title={t("permission.camera.title")}
+  status={cameraStatus /* 제품이 navigator.permissions·getUserMedia 결과로 매핑 */}
+  illustration={cameraArt}
+  explanation={<Text>{t("permission.camera.why")}</Text>}
+  request={{ label: t("permission.allow"), onAction: requestCamera, pending: requesting }}
+  settings={{ label: t("permission.browserHelp"), onAction: openBrowserPermissionHelp }}
+  continueAction={{ label: t("common.continue"), onAction: goNext }}
+  skip={{ label: t("common.later"), onAction: goNext }}
+/>
+```
+
+```tsx
+// Native
+import { Text } from "@hjmds/react-native/primitives";
+import { PermissionScreen } from "@hjmds/react-native/screen-flows";
+import { Linking } from "react-native";
+
+<PermissionScreen
+  title={t("permission.camera.title")}
+  status={cameraStatus /* 제품이 OS에서 조회한 값 */}
+  illustration={cameraArt}
+  explanation={<Text>{t("permission.camera.why")}</Text>}
+  request={{ label: t("permission.allow"), onAction: requestCamera, pending: requesting }}
+  settings={{ label: t("permission.openSettings"), onAction: () => Linking.openSettings() }}
+  continueAction={{ label: t("common.continue"), onAction: goNext }}
+  skip={{ label: t("common.later"), onAction: goNext }}
+/>
+```
+
+### 제품이 공급할 것
+
+| prop | 내용 |
+| --- | --- |
+| `status` | `prompt` · `denied` · `granted` · `unavailable`. OS 조회 결과를 제품이 매핑한다 |
+| `explanation` | 권한이 필요한 이유(필수, 지역화) |
+| `illustration` | 선택. 제품 일러스트 |
+| `request`, `settings`, `continueAction` | 세 행동 모두 필수 `{ label, onAction, disabled?, pending? }`. 상태에 맞는 하나만 보인다 |
+| `skip` | 선택 보조 행동 |
+| ScreenLayout props | `title`, `description`, `header`, `leading`, `notice`, `state` 등(`footer` 제외) |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | ScreenLayout 폭(최대 720); 그림 크기는 `illustration`(제품) 소유; 행동은 `Button` 기본 크기 | `PermissionScreen` |
+| 간격 | 화면 padding `spacing.md` 16; 본문 그림–설명 `spacing.xl` 24(가운데 정렬); footer 주 행동–나중에 `spacing.sm` 12 | Web·Native `PermissionScreen` `Stack gap="xl" align="center"`·`gap="sm"` |
+| 순서·정렬 | 헤더(제목) → 본문(그림 → 설명, 가운데) → footer(상태별 주 행동 primary → 나중에 ghost) | 렌더 순서, `resolvePermissionAction` |
+| 고정·스크롤 | 헤더·footer 고정, 본문 화면 스크롤; OS 권한 창은 제품이 `request.onAction`에서 호출 | `ScreenLayout` |
+| 좁은 폭·큰 글자 | 설명은 줄바꿈되고 본문이 스크롤된다; footer 버튼은 세로로 쌓인다; `unavailable`이면 주 행동 없이 `skip`만 남는다 | `PermissionScreen` |
+
+## 꼭 지킬 것
+
+- 설정 앱에서 돌아온 뒤 권한을 다시 조회해 `status`를 갱신한다. HJM은 앱 복귀를 감지하지 않는다.
+- 렌더링만으로 권한 요청을 띄우지 않는다. 요청은 사용자가 `request` 버튼을 눌렀을 때만 제품이 실행한다.
+- 알 수 없는 `status` 값은 던진다.
+- 권한 설명 문구·스토어 심사용 사용 목적 문자열은 제품 소유다.