@hjmds/design-contracts 1.12.1 → 1.13.0

package/docs/usage/components/menubar.md

@@ -0,0 +1,93 @@
+# Menubar
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Menubar](../../menubar.md), `src/menubar.ts`(`menubarRecipe`)
+- 스토리북: `배포/컴포넌트/탐색/메뉴 막대`
+
+## 언제 쓰나
+
+데스크톱 Web 앱 상단에 항상 같은 자리에 있는 가로 메뉴 막대(파일·편집·보기)에 쓴다.
+막대 전체가 tab stop 하나이고, 한 번에 메뉴 하나만 열리며, 열린 상태에서 ←/→로 옆 메뉴로 넘어간다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 버튼 하나에 붙는 action 목록 | [Menu](menu.md) |
+| 포인터 위치에서 여는 메뉴 | [ContextMenu](context-menu.md) |
+| 화면(페이지)을 바꾸는 상단 탐색 | [Tabs](tabs.md), [TopBar](top-bar.md) |
+| 모바일·Native 앱 | 없음. 앱 바는 OS 소유이고 Native renderer가 없다 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Menubar` | 기본 | `@hjmds/react`, `/menubar` | — |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Menubar } from "@hjmds/react/menubar";
+
+<Menubar
+  descriptor={{
+    accessibilityLabel: t("editor.menubar"),
+    menus: [
+      { id: "file", label: t("menu.file"), items: [
+        { id: "save", label: t("menu.save"), textValue: t("menu.save"), shortcut: "⌘S" },
+      ] },
+      { id: "edit", label: t("menu.edit"), items: [
+        { id: "undo", label: t("menu.undo"), textValue: t("menu.undo") },
+      ] },
+    ],
+  }}
+  onAction={(itemId, menuId) => run(menuId, itemId)}
+/>
+```
+
+Native 예는 없다(renderer 없음).
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `descriptor` | `{ accessibilityLabel: string; menus: readonly { id, label: string, items, disabled? }[] }` | 필수 | 타입 `MenubarDescriptor`(`@hjmds/design-contracts/components/menubar`) |
+| 항목 | `{ id, label: string, textValue: string, description?, shortcut?, tone?, disabled? }`(`MenuItemDescriptor`) | — | `textValue` 필수. `shortcut`은 표시 문구일 뿐 키를 등록하지 않는다 |
+| `onAction` | `(id: Key, menuId: MenuKey) => void` | 필수 | 항목 id가 먼저, 메뉴 id가 두 번째 |
+| `openMenuId` · `onOpenMenuIdChange` | `MenuKey \| null` · `(id: MenuKey \| null) => void` | — | 제어형 열린 메뉴 |
+| `defaultOpenMenuId` | `MenuKey \| null` | `null`(닫힘) | 비제어형 열린 메뉴 |
+| 메뉴 `disabled` | `boolean` | `false` | 키보드 이동에서 건너뛴다 |
+| `className` · `layoutStyle` | 문자열 · 배치 전용 style 객체 | — | 막대 루트 배치. 색·높이 변수는 덮이지 않는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 막대 높이 최소 44(`control.minTouchTarget`). 라벨 높이 44 이상, radius `radius.sm` 8. 패널 폭 `13.75rem`~`min(24rem, 90vw)`. 항목 높이 44 이상 | `menubarRecipe`, `.hjm-menubar*` |
+| 간격 | 막대 좌우 `spacing.xs` 8, 라벨 사이 `spacing.xxs` 4, 라벨 좌우 `spacing.sm` 12. 패널 안쪽 4, radius `radius.md` 12. 항목 위아래 8 · 좌우 12, 단축키와 12 | `menubarRecipe`, `.hjm-menubar__panel`·`__item` |
+| 순서·정렬 | 메뉴는 데스크톱 관례(파일 → 편집 → 보기 → … → 도움말). 패널은 해당 라벨 바로 아래 시작 쪽에 붙는다. 단축키 문구는 항목 끝(`space-between`) | `.hjm-menubar__panel` |
+| 고정·스크롤 | 화면 맨 위(앱 제목·TopBar 아래나 같은 줄 시작 쪽). sticky 여부는 놓는 레이아웃이 정한다. 패널은 Menu와 같은 portal·fixed 배치(`layer.dropdown` 400)로 공간이 부족하면 뒤집고 화면 안으로 민다. 모달 안에서는 소유 모달 + 1이다 | `useAnchoredPopup`, `.hjm-menubar__panel` |
+| 좁은 폭·큰 글자 | 폭이 모자라면 라벨이 다음 줄로 감긴다(`flex-wrap`). 모바일 폭은 대상이 아니다 | `.hjm-menubar` |
+
+```text
+┌ 화면 (Web, 데스크톱) ─────────────────────────────────────┐
+│ [파일] [편집] [보기]                         ← 막대 ≥44   │
+│  └┬───────────────────┐                                   │
+│   │ 저장          ⌘S  │  ← 패널: 라벨 바로 아래, 시작 정렬 │
+│   │ 다른 이름…   ⇧⌘S  │     13.75rem ~ 24rem               │
+│   └───────────────────┘                                   │
+│ 본문(스크롤)                                              │
+└───────────────────────────────────────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- `descriptor.accessibilityLabel`, 각 메뉴 `id`·`label`은 비어 있으면 안 되고, 메뉴마다 항목이 하나 이상 있어야 한다. 어기면 던진다.
+- 항목 `textValue`는 계약 타입상 필수다. 지역화한 문구를 그대로 넣는다.
+- 메뉴 구성과 단축키 문구는 제품 소유다. 단축키 자체의 키 바인딩은 Menubar가 등록하지 않으므로 제품이 따로 연결한다.
+- `className`·`layoutStyle`은 배치에만 쓴다. 색·높이를 덮지 않는다.

package/docs/usage/components/message-composer.md

@@ -0,0 +1,124 @@
+# MessageComposer
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: 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 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/구성/입력과 작성/메시지 작성`, `배포/구성/입력과 작성/댓글 작성`, `배포/화면/소통/채팅`
+
+## 언제 쓰나
+
+채팅·DM·댓글 입력창에 쓴다. 1~5줄로 자라는 TextArea와 전송 버튼, 선택적으로 사진 첨부 미리보기,
+답장 대상 표시, 첨부 버튼을 하나로 조합한다. 값은 완전 제어형이고 HJM은 초안을 지우지 않는다.
+
+용도별 조합은 [댓글 작성](../compositions/purpose-input-comment.md)과 [메시지 작성](../compositions/purpose-input-message.md)을 먼저 선택한다. 입력·전송 엔진은 같고 답글·첨부·문구만 목적에 맞게 연결한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 일반 폼의 여러 줄 입력 | [TextArea](text-area.md) |
+| @멘션 자동완성 입력 | [Mentions](mentions.md) |
+| 채팅 화면 전체 틀(타임라인 + 작성창 자리) | [ChatScreen](chat-screen.md)의 `composer` 슬롯에 이 컴포넌트를 넣는다 |
+| 댓글 화면 전체 | [CommentThreadScreen](comment-thread-screen.md)의 `composer` 슬롯 |
+| 키보드 위에 붙이기 | [KeyboardDock](keyboard-dock.md) 등 keyboard 계열과 합성 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `MessageComposer` | supplemental, 루트 barrel에 없음 | `/screens` | `/screens` |
+
+`@hjmds/react/screens`, `@hjmds/react-native/screens`로만 import한다. 추가 optional peer는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { MessageComposer } from "@hjmds/react/screens";
+
+<MessageComposer
+  label={t("chat.input")}
+  sendLabel={t("chat.send")}
+  value={draft}
+  onValueChange={setDraft}
+  pending={sending}
+  onSend={async (text) => { const ok = await send(text, photos); if (ok) { setDraft(""); setPhotos([]); } }}
+/>
+```
+
+```tsx
+// Native
+import { MessageComposer } from "@hjmds/react-native/screens";
+import { Image } from "react-native";
+
+<MessageComposer
+  label={t("chat.input")}
+  sendLabel={t("chat.send")}
+  value={draft}
+  onValueChange={setDraft}
+  pending={sending}
+  sendIcon={<ArrowUpIcon />}
+  sendPresentation="circle"
+  attachmentAction={{ label: t("chat.attachPhoto"), icon: <PhotoIcon />, onPress: openPhotoSource }}
+  attachments={photos.map((p) => ({ id: p.id, preview: <Image source={{ uri: p.uri }} />, removeLabel: t("chat.removePhoto") }))}
+  onRemoveAttachment={removePhoto}
+  onSend={sendDraft}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `string` | 필수 | 완전 제어형. HJM은 초안을 지우지 않는다 |
+| `label` | `string` | 필수 | placeholder 겸 접근성 이름 |
+| `sendLabel` | `string` | 필수 | 전송 버튼 문구·접근성 이름 |
+| `onValueChange` | `(value: string) => void` | 필수 | 입력 변경 |
+| `onSend` | `(value: string) => void` | 필수 | 현재 문자열만 넘긴다 |
+| `disabled` · `pending` | `boolean` | `false` | 둘 중 하나면 입력·첨부·삭제·답장 취소가 모두 잠긴다. `pending`은 전송 버튼 loading |
+| `sendDisabled` | `boolean` | `false` | 전송만 막고 편집은 열어 둔다 |
+| `additionalContent` | `boolean` | `false` | 글·첨부 밖에 보낼 내용이 있으면 `true`. 전송 가능 판정에 더한다 |
+| `maxLength` | `number` | 없음 | 입력 최대 글자 수 |
+| `leadingAction` | `ReactNode` | 없음 | 입력 테두리 **안** 글자 앞 시작 쪽 도구 버튼. 자라는 입력의 세로 가운데에 맞춘다(Web `.hjm-field__leading` `align-self: center`, Native `alignSelf: "center"`). 행동이라 흐린 affix 색을 쓰지 않는다 |
+| `inputRef` | Web `Ref<HTMLTextAreaElement>` · Native `Ref<TextInput>` | 없음 | 답글 선택 뒤 포커스 유지 |
+| `context` | `ReactNode` | 없음 | 답장 대상 위 임의 슬롯 |
+| `replyTo` | `{ author, excerpt, cancelLabel, onCancel() }` | 없음 | 입력창 위 답장 대상과 취소 버튼 |
+| `sendIcon` | `ReactNode` | 없음 | 주면 아이콘 모드: 빈 입력에서는 입력창 안에 `attachmentAction`, 내용이 있거나 `pending`이면 전송 아이콘. 없으면 입력창 옆 텍스트 `Button` |
+| `sendPresentation` | `"inline"` · `"circle"` | `"inline"` | `circle`은 primary 원형 `IconButton size="small"`(댓글·DM 레퍼런스). `sendIcon`이 있을 때만 의미가 있다 |
+| `attachmentAction` | `{ label, icon, onPress(), disabled? }` | 없음 | 첨부 버튼(ghost `IconButton`) |
+| `attachments` | `readonly { id, removeLabel, preview }[]` | `[]` | 첨부 미리보기. 있으면 `onRemoveAttachment` 필수 |
+| `onRemoveAttachment` | `(id: string) => void` | 없음 | 첨부 제거 |
+| Web `layoutStyle` | `HjmCompositionStyleProp` | 없음 | 작성창 루트 배치(margin·width·flex 등). 미게시(1.12.1 이후) |
+
+전송 가능 조건: `disabled`·`pending`·`sendDisabled`가 아니고, 글(공백 제외)·첨부·`additionalContent` 중 하나가 있을 때(`canSubmitMessage`).
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 입력 `composerMinLines` 1 ~ `composerMaxLines` 5줄(넘으면 입력 안에서 스크롤), `shape="large"`; 첨부 썸네일 `attachmentSize` 80(radius `radius.md`); 제거 버튼은 `IconButton size="small"` 36 + 사방 hit 4(실제 타깃 44), 그 안 보이는 원 `attachmentRemoveSize` 24; circle 전송은 `IconButton size="small"` 36 | `screen-patterns.ts`, `icon-button-recipe.ts` `sizes.small`, Web `styles.css`, Native `MessageComposer` |
+| 간격 | 세로 묶음(context·답장 대상·첨부·입력 줄) 사이와 입력–텍스트 전송 버튼 사이 `screenPatternRecipe.itemGap`(`spacing.sm` 12, 두 플랫폼. 2026-10-06까지 Web은 8, 1.12.1 이후 미게시); 답장 대상 줄·첨부 사이 `spacing.sm` 12; circle 전송은 입력 글자와 `spacing.sm` 12, 오른쪽 끝 8 | `screenPatternRecipe.itemGap`, Web `.hjm-message-composer`·`__row`(`--hjm-message-composer-gap`), Native `Stack gap="sm"`·`itemGap` |
+| 순서·정렬 | `context` → 답장 대상(작성자·발췌 → 취소) → 첨부 썸네일(→ 첨부 버튼) → 입력·전송 한 줄, 전송은 입력 아래쪽(`flex-end`)에 맞춘다. 입력 줄 안은 `leadingAction` → 글자 → (아이콘 모드) 전송/첨부 | 렌더 순서, Web `forms.tsx` `hjm-field__leading` |
+| 고정·스크롤 | 자체 고정 없음: 화면 composer 슬롯(footer)에 넣는다; 첨부는 가로 스크롤; 키보드 adapter는 host 하나만 | ChatScreen·CommentThreadScreen `composer` |
+| 좁은 폭·큰 글자 | 입력이 남은 폭을 채우고(`flex: 1`, 최소 폭 0) 전송 버튼은 줄지 않는다; 큰 글자에서도 5줄 상한 뒤 입력 안 스크롤로 기록을 가리지 않는다 | Web `.hjm-message-composer__row`, Native `layoutStyle={{ flex: 1 }}` |
+
+## 꼭 지킬 것
+
+- 문구(`label`은 placeholder 겸 접근성 이름, `sendLabel`, `removeLabel`, `cancelLabel`)는 모두 i18n 키로 넣는다.
+- `onSend(value)`는 현재 문자열만 넘긴다. 첨부 목록은 제품 상태에서 읽고, **서버 성공 뒤에만** 제품이 글·첨부·답장 대상을 지운다.
+- 첨부 `id`는 비어 있지 않고 유일해야 하며 `removeLabel`이 필요하다. 첨부가 있으면 `onRemoveAttachment`가 필수다. 어기면 던진다.
+- 사진 권한·선택기·업로드·개수 제한은 제품 소유다. 출처 선택 UI는 [PhotoSourceSheet](photo-source-sheet.md)를 쓴다.
+- Enter는 줄바꿈이다(IME 조합 보호). Enter 전송을 덧붙이지 않는다.
+- Web 배치는 `layoutStyle`로 한다. Native는 스타일 통로가 없어 감싸는 레이아웃에서 배치한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `inputRef` 타입 | `HTMLTextAreaElement` | `TextInput` |
+| 첨부 목록 | CSS 클래스 `hjm-message-composer__attachments` | 가로 ScrollView |
+| 이벤트 이름 | `attachmentAction.onPress`(내부에서 onClick으로 연결) | `onPress` |
+| 배치 prop | `layoutStyle`(루트) | 없음 |

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

@@ -0,0 +1,113 @@
+# ModerationScreen
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: 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) 위에 조합한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 차단·삭제 확인만 필요 | [AlertDialog](alert-dialog.md) |
+| 신고 진입 메뉴(⋯) | [Menu](menu.md) |
+| 자유 입력 위주의 문의 폼 | [Form](form.md), [EditorScreen](editor-screen.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ModerationScreen` | supplemental, 루트 barrel에 없음 | `/screen-flows` | `/screen-flows` |
+
+`@hjmds/react/screen-flows`, `@hjmds/react-native/screen-flows`로만 import한다. 추가 optional peer는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ModerationScreen } from "@hjmds/react/screen-flows";
+
+<ModerationScreen
+  title={t("report.title")}
+  reasonLabel={t("report.reason")}
+  reasons={[
+    { value: "spam", label: t("report.reason.spam") },
+    { value: "abuse", label: t("report.reason.abuse") },
+  ]}
+  reason={reason}
+  onReasonChange={setReason}
+  submit={{ label: t("report.submit"), onAction: submitReport, pending: reporting }}
+  block={{
+    action: { label: t("report.block"), onAction: () => {} },
+    confirmation: {
+      mode: "confirm", tone: "danger",
+      title: t("block.confirm.title"), description: t("block.confirm.body"),
+      confirmLabel: t("block.confirm"), cancelLabel: t("common.cancel"),
+      onConfirm: blockUser, fallbackErrorMessage: t("block.error"),
+    },
+  }}
+/>
+```
+
+```tsx
+// Native — props는 Web과 같다
+import { ModerationScreen } from "@hjmds/react-native/screen-flows";
+
+<ModerationScreen
+  title={t("report.title")}
+  reasonLabel={t("report.reason")}
+  reasons={[
+    { value: "spam", label: t("report.reason.spam") },
+    { value: "abuse", label: t("report.reason.abuse") },
+  ]}
+  reason={reason}
+  onReasonChange={setReason}
+  submit={{ label: t("report.submit"), onAction: submitReport, pending: reporting }}
+  block={{
+    action: { label: t("report.block"), onAction: () => {} },
+    confirmation: {
+      mode: "confirm", tone: "danger",
+      title: t("block.confirm.title"), description: t("block.confirm.body"),
+      confirmLabel: t("block.confirm"), cancelLabel: t("common.cancel"),
+      onConfirm: blockUser, fallbackErrorMessage: t("block.error"),
+    },
+  }}
+/>
+```
+
+### 제품이 공급할 것
+
+| 슬롯·prop | 내용 |
+| --- | --- |
+| `reasons`, `reasonLabel` | 지역화한 사유 목록과 그룹 이름. 기본으로 세로 RadioGroup을 그린다 |
+| `reason`, `onReasonChange` | 선택된 사유(제어형, 없으면 `null`) |
+| `reasonPicker` | 단계형 사유 목록 등 다른 선택 UI. 주면 기본 RadioGroup 대신 그린다 |
+| `children` | 상세 설명 입력 등 추가 내용 |
+| `submit` | 신고 행동 `{ label, onAction, disabled?, pending? }` |
+| `block` | 차단 버튼 행동과 `AlertDialog` 확인 요청(`mode: "confirm"`) |
+| ScreenLayout props | `title`, `description`, `header`, `leading`, `actions`, `notice`, `state`, `stateAction` 등(`footer` 제외) |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | ScreenLayout 폭(최대 720); 사유는 세로 `RadioGroup`, 신고·차단은 `Button` 기본 크기 | `ModerationScreen`, `screen-flows.tsx` `Action` |
+| 간격 | 화면 padding `spacing.md` 16; 본문 사유 선택–`children` `spacing.lg` 20; footer 신고–차단 `spacing.sm` 12 | Web·Native `ModerationScreen` `Stack gap="lg"`·`gap="sm"` |
+| 순서·정렬 | 헤더(제목) → 본문(사유 → 추가 설명 `children`) → footer(신고 primary → 차단 ghost) | 렌더 순서 |
+| 고정·스크롤 | 헤더·footer 고정, 본문 화면 스크롤; 차단 확인은 AlertDialog 오버레이 | `ScreenLayout`, `AlertDialog` |
+| 좁은 폭·큰 글자 | 사유 문구는 줄바꿈되고 항목이 세로로 늘어난다; footer 버튼은 세로로 쌓여 좁은 폭에서도 나란히 줄지 않는다 | `RadioGroup orientation="vertical"`, `Stack` |
+
+## 꼭 지킬 것
+
+- 신고 버튼은 `reason`이 `reasons` 안의 값이 아니거나 `state`가 `ready`가 아니면 자동으로 막힌다. `reasonPicker`를 쓸 때도 `reasons`에 유효한 값을 넣어야 버튼이 열린다.
+- 차단 버튼의 `block.action.onAction`은 호출되지 않는다. 버튼은 확인 대화상자만 열고, 실제 차단은 `confirmation.onConfirm`에서 한다.
+- 서버 신고·권한·차단 mutation, 완료 후 이동은 제품 소유다. 사유 목록과 정책 문구도 제품이 정한다.
+- 확인 대화상자의 성공 후 닫힘·실패 문구는 [AlertDialog](alert-dialog.md) 계약을 따른다.

package/docs/usage/components/notice.md

@@ -0,0 +1,106 @@
+# Notice
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/component-recipes.ts`(`noticeRecipe`), BottomInfo와의 경계 [BottomInfo](../../bottom-info.md), Toast와의 경계 [Toast](../../toast.md)
+- 스토리북: `배포/컴포넌트/상태와 알림/안내 메시지`
+
+## 언제 쓰나
+
+화면 흐름 안 **제자리에 남아 있는** 상태 알림에 쓴다. 저장 실패, 오프라인, 권한 제한,
+결제 수단 만료처럼 사용자가 읽고 필요하면 행동(`action`)할 때까지 사라지면 안 되는 내용이 여기에 속한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 무시해도 안전하고 잠시 뒤 사라지는 짧은 결과 알림(“저장했어요”) | [Toast](toast.md) |
+| 반드시 응답해야 진행되는 확인 | [AlertDialog](alert-dialog.md) |
+| 주 행동 아래 늘 있는 조건 안내(약관 동의 등) | [BottomInfo](bottom-info.md) |
+| 화면 전체가 빈 상태·오류 상태 | [EmptyState](empty-state.md), [Result](result.md) |
+| 입력 하나의 오류 | [Field](field.md)의 `error` |
+
+선택 기준: 사라져도 되는가(Toast) / 남아야 하는가(Notice) / 응답이 필수인가(AlertDialog).
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Notice` | 기본 | `@hjmds/react`, `/feedback` | `@hjmds/react-native`, `/feedback` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Button } from "@hjmds/react/actions";
+import { Notice } from "@hjmds/react/feedback";
+
+<Notice
+  tone="warning"
+  title={t("sync.offline.title")}
+  description={t("sync.offline.body")}
+  action={<Button tone="secondary" size="small" onClick={retry}>{t("common.retry")}</Button>}
+/>
+```
+
+```tsx
+// Native
+import { Button } from "@hjmds/react-native/actions";
+import { Notice } from "@hjmds/react-native/feedback";
+
+<Notice
+  tone="warning"
+  announcement="polite"
+  title={t("sync.offline.title")}
+  description={t("sync.offline.body")}
+  action={<Button tone="secondary" size="small" onPress={retry}>{t("common.retry")}</Button>}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` | Web `ReactNode` · Native `string` | 필수 | 현지화 |
+| `description` | Web `ReactNode` · Native `string` | — | 현지화 |
+| `tone` | `info` · `success` · `warning` · `attention` · `danger` | `info` | 도메인 상태는 제품 어댑터에서 tone으로 매핑한다 |
+| `action` | 노드 | — | 보조 행동 하나(`Button` `tone="secondary"` `size="small"`) |
+| `icon` | 노드 | — | 장식이다(Web은 `aria-hidden`) |
+| `renderIcon`(Native) | `(props: { tone, color: string, size: number }) => ReactNode` | — | tone 색과 recipe 크기를 받아 그린다 |
+| `announcement`(Native) | `none` · `polite` · `assertive` | `none` | 새로 나타나는 상태만 발표한다(아래 플랫폼 차이) |
+| `layoutStyle` | 배치 전용 style 객체 | — | 바깥 여백·폭만 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 본문 폭을 꽉 채운다. 아이콘 20(`glyph.sm`), 테두리 1(`stroke.default`), radius `radius.md` 12 | `noticeRecipe` |
+| 간격 | 안쪽 `spacing.md` 16, 아이콘·문구·행동 사이 `spacing.sm` 12, 제목·설명 사이 `spacing.xxs` 4. 이웃 블록과는 `layout.contentGap` 16 | `noticeRecipe`, `.hjm-notice*` |
+| 순서·정렬 | 아이콘 — 제목·설명 — 행동. 행동은 하나, `Button` `size="small"` `tone="secondary"`(또는 `ghost`), `primary` 금지. Web은 행동이 같은 줄 끝, Native는 행동이 문구 줄 **아래** | `.hjm-notice__action`, `react-native/src/feedback.tsx` |
+| 고정·스크롤 | 본문 흐름 안. 먼저 읽어야 하는 경고·입력 오류는 영향을 받는 내용 바로 위(화면 상태는 제목 아래, 폼 검증은 제출 버튼 위). 제출 후 성공·실패 결과는 구성 지침이 지정한 행동 인접 위치에 둔다. 떠 있거나 고정되지 않고 함께 스크롤되며 여러 개 쌓지 않는다 | — |
+| 좁은 폭·큰 글자 | Web은 문구 칸이 60% 아래로 줄면 행동이 다음 줄로 감긴다. 제목·설명은 줄바꿈된다 | `.hjm-notice__content`(`flex: 1 1 60%`) |
+
+## 꼭 지킬 것
+
+- 제목·설명·행동 문구는 i18n 키로 넣는다. 아이콘은 제품 소유 자산이고 색은 tone이 정한다.
+- 배치는 `layoutStyle`로만 한다. 색·padding·radius를 `style`/`className`으로 덮지 않는다. Native `style`은 deprecated(개발 모드 경고, 다음 major 제거)다.
+- 같은 화면에 같은 내용의 Notice와 Toast를 동시에 띄우지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 발표 | 항상 live region. `danger`는 `role="alert"`+assertive, 나머지는 `role="status"`+polite | `announcement`: `none`(기본) · `polite` · `assertive`. 지정해야 발표한다 |
+| title/description 타입 | `ReactNode` | `string` |
+| 아이콘 렌더 함수 | 없음 | `renderIcon` |
+| 배치 | `className`, `layoutStyle`(HTML `style`도 받음) | `layoutStyle`(`style`은 deprecated) |
+
+## 함정
+
+- Native는 기본이 `announcement="none"`이라, 새로 생긴 오류 Notice를 화면에 넣기만 하면 스크린 리더가 알리지 않는다. 새로 나타나는 상태에는 `polite`/`assertive`를 준다.
+- Web은 반대로 항상 발표되므로, 화면 진입 때부터 늘 있는 안내를 Notice로 두면 매번 읽힌다. 그런 조건 안내는 BottomInfo다.
+
+- 2026-10-06 독립 재구현에서 입력 전 경고 위치와 시간 선택의 확정 후 결과 위치가 충돌했다. 시간 선택의 결과는 행동 아래, 입력 시트의 저장 실패는 본문 입력 위로 각 구성에 명시한다. Notice 자체가 결과 위치를 강제하지 않는다.

package/docs/usage/components/notification-inbox-screen.md

@@ -0,0 +1,97 @@
+# NotificationInboxScreen
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: 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) 위에 필터 슬롯을 `notice` 영역에 고정해,
+로딩·빈 상태·오류로 본문이 바뀌어도 필터는 남게 한다. 본문 행은 [NotificationItem](notification-item.md)을 쓴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 알림 한 행 | [NotificationItem](notification-item.md) |
+| 상단 바의 알림 진입 아이콘·개수 | `NotificationBell`([IconButton](icon-button.md) 확장, `/notification-bell`) |
+| 필터 없는 일반 목록 화면 | [ScreenLayout](screen-layout.md), [ListDetailScreen](list-detail-screen.md) |
+| 일시적인 결과 알림 | [Toast](toast.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `NotificationInboxScreen` | supplemental, 루트 barrel에 없음 | `/screens` | `/screens` |
+
+`@hjmds/react/screens`, `@hjmds/react-native/screens`로만 import한다. 추가 optional peer는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { NotificationInboxScreen, NotificationItem } from "@hjmds/react/screens";
+
+<NotificationInboxScreen
+  title={t("inbox.title")}
+  filters={filterControl}
+  state={items.length ? { kind: "ready" } : { kind: "empty", title: t("inbox.empty") }}
+>
+  {items.map((n) => <NotificationItem key={n.id} {...toItemProps(n)} />)}
+</NotificationInboxScreen>
+```
+
+```tsx
+// Native
+import { FlatList } from "react-native";
+import { NotificationInboxScreen } from "@hjmds/react-native/screens";
+
+<NotificationInboxScreen
+  title={t("inbox.title")}
+  filters={filterControl}
+  scroll="content"
+  state={query.isPending ? { kind: "loading", title: t("inbox.loading") } : { kind: "ready" }}
+>
+  <FlatList data={items} renderItem={renderNotification} />
+</NotificationInboxScreen>
+```
+
+### 제품이 공급할 것
+
+| 슬롯·prop | 내용 |
+| --- | --- |
+| `title`, `description` | 지역화 제목 |
+| `filters` | 필터 control(SegmentedControl·Chip 등). 상태가 바뀌어도 유지된다 |
+| `notice` | 새로고침 실패 같은 안내. `filters` 위에 함께 놓인다 |
+| `state` | `ready` · `loading` · `empty` · `error` · `restricted`. ready 외에는 지역화 `title` 필수 |
+| `stateAction` | 재시도·로그인 같은 실제 행동 |
+| `children` | 알림 목록(데이터·페이지 합치기·더 보기는 제품) |
+| `header`, `leading`, `actions` | 기존 내비게이션 헤더, 뒤로 가기, “모두 읽음” 같은 행동 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | ScreenLayout 폭(최대 720) 안에서 알림 행이 폭을 채운다 | `ScreenLayout`, `NotificationItem`(ListRow) |
+| 간격 | 화면 padding `spacing.md` 16(notice 영역은 좌우만); `notice`–`filters` `spacing.sm` 12; 행 사이 간격은 목록(제품) 소유 | Web·Native `NotificationInboxScreen` `Stack gap="sm"` |
+| 순서·정렬 | 헤더(`leading` → 제목 → `actions`) → `notice` → `filters` → 알림 목록 | 렌더 순서 |
+| 고정·스크롤 | `notice`·`filters`는 헤더 아래 고정되고 상태 교체 중에도 남는다; 목록은 기본 화면 스크롤(`scroll="screen"`), 가상화 목록이면 `scroll="content"` | `ScreenLayout` `notice`·`scroll` |
+| 좁은 폭·큰 글자 | 제목 열 최소 폭 120 × 글자 배율, 모자라면 `actions`(모두 읽음 등)가 다음 줄로 내려간다; 필터 줄바꿈·가로 스크롤은 `filters` 소유 | `screenPatternRecipe.headerMinWidth` |
+
+## 꼭 지킬 것
+
+- 읽음 처리·계정 scope·요청 취소·라우팅·focus 복구는 제품 소유다. 화면 표시만으로 읽음 처리하지 않는다.
+- 새로고침 실패는 `state="error"`가 아니라 `ready` + `notice`로 알린다. 오류로 바꾸면 목록이 내려간다.
+- FlatList 같은 가상화 목록은 `scroll="content"`로 넣는다. 스크롤 컨테이너를 이중으로 만들지 않는다.
+- 이미 `<main>` 안이면 Web은 `as="section"`, 라우트가 여백을 이미 주면 `contentInset="none"`.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 배치·식별 | `layoutStyle`, `className`, `as` | `layoutStyle`, `testID` |
+| 스크롤 | 없음 | `scrollRef`, `scrollProps`(`refreshControl` 등) |

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

@@ -0,0 +1,98 @@
+# NotificationItem
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: 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 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/구성/정보 표시/알림 항목`, `배포/화면/소통/알림함`
+
+## 언제 쓰나
+
+알림함의 알림 한 행에 쓴다. [ListRow](list-row.md)에 읽음 여부(제목 굵기)와
+지역화한 “상태 · 시각” 줄을 더한 조합이다. 탭 동작·링크는 ListRow 그대로다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 알림이 아닌 일반 목록 행 | [ListRow](list-row.md) |
+| 알림함 화면 전체 틀 | [NotificationInboxScreen](notification-inbox-screen.md) |
+| 화면 위에 잠시 뜨는 알림 | [Toast](toast.md) |
+| 화면 안에 남는 상태 안내 | [Notice](notice.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `NotificationItem` | supplemental, 루트 barrel에 없음 | `/screens` | `/screens` |
+
+`@hjmds/react/screens`, `@hjmds/react-native/screens`로만 import한다. 추가 optional peer는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { NotificationItem } from "@hjmds/react/screens";
+
+<NotificationItem
+  read={n.read}
+  statusLabel={n.read ? t("inbox.read") : t("inbox.unread")}
+  timestamp={formatRelative(n.createdAt)}
+  title={n.title}
+  description={n.body}
+  leading={senderAvatar}
+  href={n.url}
+/>
+```
+
+```tsx
+// Native
+import { NotificationItem } from "@hjmds/react-native/screens";
+
+<NotificationItem
+  read={n.read}
+  statusLabel={n.read ? t("inbox.read") : t("inbox.unread")}
+  timestamp={formatRelative(n.createdAt)}
+  title={n.title}
+  description={n.body}
+  onPress={() => openNotification(n)}
+/>
+```
+
+### 제품이 공급할 것
+
+| prop | 내용 |
+| --- | --- |
+| `read` | 읽음 여부(필수). 안 읽음이면 제목이 굵어진다 |
+| `statusLabel` | 지역화 읽음 상태 문구(필수). 굵기만으로 상태를 전하지 않도록 글로도 표시한다 |
+| `timestamp` | 제품이 포맷한 상대·절대 시각 문자열(필수) |
+| `title`, `description` | 알림 내용 |
+| 나머지 ListRow props | `leading`·`trailing`·`density`·`disabled` 등, 이동은 `href`/`onClick`(Web), `onPress`(Native) |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | ListRow 크기·density와 내용 높이를 따른다; 모서리 radius 0(Web) | Web `.hjm-notification-item`, `ListRow` |
+| 간격 | ListRow 내부 간격; Web은 `description`–상태·시각 줄 `spacing.xxs` 4, Native는 같은 description 문자열 안 줄바꿈; 행을 카드 padding으로 다시 감싸지 않는다 | Web `Stack gap="xxs"`, Native `description` join |
+| 순서·정렬 | leading → 제목(안 읽음은 굵게) → `description` → `statusLabel · timestamp` → trailing | Web·Native `NotificationItem` |
+| 고정·스크롤 | 목록이 스크롤; 행 자체는 고정하지 않는다 | `NotificationInboxScreen` |
+| 좁은 폭·큰 글자 | 제목·설명·상태 줄이 줄바꿈되며 행 높이가 늘어난다; 읽음 여부는 굵기만이 아니라 `statusLabel` 문구로도 전한다 | `NotificationItem` |
+
+## 꼭 지킬 것
+
+- 표시·탭·스크롤이 읽음 처리를 하지 않는다. 읽음 mutation은 제품이 `onPress`/`onClick` 또는 화면 정책에서 실행하고 `read`를 갱신한다.
+- `selected`는 받지 않는다(타입에서 제외). 선택 목록이 필요하면 ListRow를 쓴다.
+- 시각 포맷·상대시간은 제품 i18n에서 만든다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `title`, `description` 타입 | `ReactNode` | `string` |
+| 상태·시각 줄 | 설명 아래 caption `Text` | `description`과 줄바꿈(`\n`)으로 합친 한 문자열 |
+| 이동 | `href`, `onClick` | `onPress` |
+| 추가 슬롯 | `className`, `layoutStyle` | `titleMetadata`, `trailingAction`, `trailingText`, `layoutStyle` |
+| 제목 굵기 조정 | `Text emphasis` | 렌더러 비공개 입력(`hjmTitleEmphasis`)으로 안 읽음 700(`fontWeight.bold`)·읽음 400(`fontWeight.regular`). deprecated `ListRow.titleStyle`을 쓰지 않으므로 HJM이 `titleStyle` 경고를 내지 않는다. `NotificationItemProps`에는 `titleStyle`이 없다(미게시(1.12.1 이후)) |