@hjmds/design-contracts 1.29.0 → 1.31.0

package/docs/usage/components/typing-indicator.md

@@ -0,0 +1,89 @@
+# TypingIndicator
+
+- 단계: 컴포넌트
+- 상태: 실험
+- 지원: Web · Native
+- 적용: 미게시(1.30.0 이후)
+- 검토일: 2026-10-18
+- 근거: [반복 화면 조합](../../screen-patterns.md), `src/screen-patterns.ts`의 `typingIndicatorRecipe`·`chatMessageRecipe`; Web·Native `src/screens.tsx`
+- 스토리북: `실험/컴포넌트/상태와 알림/입력 중 표시`
+
+## 언제 쓰나
+
+대화 타임라인에서 상대가 지금 입력 중임을 보여 줄 때 쓴다. 수신 말풍선 자리에 점 세 개가 차례로 깜박이는 말풍선을 그리고,
+보조기술에는 제품이 준 문구("서연님이 입력 중")를 한 번 알린다. 입력 중 여부(presence) 판단과 표시 시점은 제품이 정한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 내 메시지 전송 중 | [ChatMessage](chat-message.md) `deliveryLabel` |
+| 화면·영역 로딩 | [Spinner](spinner.md), ScreenLayout `state` |
+| AI 답변 생성 중 | [StreamingAnswer](streaming-answer.md)·[ThinkingOrb](thinking-orb.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `TypingIndicator` | 기본 | `@hjmds/react/screens` | `@hjmds/react-native/screens` |
+
+루트 barrel에는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ChatMessage, ChatScreen, TypingIndicator } from "@hjmds/react/screens";
+
+<ChatScreen title={peer.name} composer={composer}>
+  <div>
+    {messages.map(m => <ChatMessage key={m.id} {...toMessageProps(m)}>{m.text}</ChatMessage>)}
+    {peerTyping ? <TypingIndicator label={t("chat.typing", { name: peer.name })} /> : null}
+  </div>
+</ChatScreen>
+```
+
+```tsx
+// Native — 가상화 목록의 ListFooterComponent로 둔다
+import { FlatList } from "react-native";
+import { TypingIndicator } from "@hjmds/react-native/screens";
+
+<FlatList data={messages} renderItem={renderMessage}
+  ListFooterComponent={peerTyping ? <TypingIndicator label={t("chat.typing", { name: peer.name })} /> : null} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | `string` | 필수 | 지역화한 상태 문구. 화면에는 보이지 않고 보조기술 이름·알림이 된다. 빈 문자열은 `TypeError` |
+| `avatar` | `ReactNode` | 없음 | 단톡방에서 입력 중인 사람 사진. ChatMessage 아바타와 같은 32(`chatMessageRecipe.avatarSize`)로 넘긴다 |
+| `layoutStyle` | `HjmCompositionStyleProp` | 없음 | 행 배치 전용. 색·여백을 덮지 않는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 점 `dotSize` 6(원), 말풍선 최소 높이 = 본문 줄 높이 + 위아래 `bubblePaddingBlock` 6 — 한 줄 수신 말풍선과 같은 높이; radius `bubbleRadius` 14, 표면 `surface` | `typingIndicatorRecipe`, `chatMessageRecipe` |
+| 간격 | 점 사이 `dotGap`(`spacing.xxs`) 4, 말풍선 안 좌우 10; 위 `groupGap` 12(새 묶음처럼 떨어진다); 아바타–말풍선 `avatarGap` 8 | `typingIndicatorRecipe`, `chatMessageRecipe` |
+| 순서·정렬 | 수신 쪽(시작 쪽) 정렬, 마지막 메시지 뒤. 아바타가 없으면 꼬리 폭 `tailWidth` 7만큼 들여 수신 말풍선과 가장자리를 맞춘다 | Web·Native `TypingIndicator` |
+| 고정·스크롤 | 자체 고정 없음. 타임라인 목록 안에서 함께 스크롤한다 | — |
+| 좁은 폭·큰 글자 | 점 크기는 고정. 글자 배율과 무관하다 | Web·Native `TypingIndicator` |
+
+## 꼭 지킬 것
+
+- 상대가 실제로 입력 중일 때만 렌더하고, 멈추면 제품이 제거한다. 표시 시간을 HJM이 정하지 않는다.
+- 문구는 제품 i18n으로 넘긴다. 점 표시 옆에 같은 문구를 보이는 글자로 다시 쓰지 않는다.
+- 움직임: 한 주기 `cycleMs` 1200 동안 점마다 `restOpacity` 0.35 ↔ 1로 깜박이고 점 사이 시작 간격은 `staggerMs` 160이다. 동작 줄이기(Provider `reducedMotion`, Web은 `prefers-reduced-motion`도)에서는 점이 깜박이지 않고 불투명하게 멈춘다.
+- 알림은 정중(polite)하다. 나타날 때 한 번 읽고 진행 중인 낭독을 끊지 않는다. 타임라인 전체를 live region으로 감싸지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 알림 | `role="status"` + 숨긴 문구 | 접근성 요소 하나(`accessibilityLabel`), Android polite live region, iOS는 나타날 때 `announceForAccessibilityWithOptions(queue)` |
+| 움직임 | CSS keyframes(`hjm-typing-pulse`) | `Animated.loop`(native driver) |
+
+## 근거
+
+- 공통 입력 중 표시: 2026-10-18 번뚝 DM. Web·Native가 각자 점(●●●)과 문구 말풍선을 만들었다(Web `role="status"` 문구, Native 별도 컴포넌트와 Animated 깜박임). 공통 타임라인 구조는 HJM 소유라는 2026-10-15 원칙에 따라 공개 조각으로 옮겼다.

package/docs/usage/screens/common-login.md

@@ -18,12 +18,13 @@ AuthScreenLayout을 사용해 로그인 흐름을 구성한다. 제품이 데이
 
 ```text
 host: 남은 높이·safe area·키보드
-└─ 히어로 → 제공자 카드 → 하단 동의
+└─ (머리 띠: [뒤로/닫기] 로그인) → 히어로 → 제공자 카드 → 하단 동의
 ```
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
 | 바깥 틀 | AuthScreenLayout | route 본문 | [API 배치 규칙](../components/auth-screen-layout.md#배치), host 남은 높이 |
+| 머리(선택) | AuthScreenLayout `title`·`exit`(1.31.0) | 맨 위 고정, 화면 가장자리까지 | ScreenLayout 가운데 머리 띠(최소 52). 바깥에 TopBar를 따로 얹지 않는다 |
 | 내용 | 공개 슬롯 | 히어로 → 제공자 카드 → 하단 동의 | 화면 recipe의 sectionGap·itemGap; 슬롯 안은 각 지침 토큰 |
 | 상태 | pendingLabel 또는 main 안 Notice | 제공자 카드 내부 | 카드 크기를 유지하고 동의 고지를 남긴다 |
 
@@ -33,6 +34,7 @@ host: 남은 높이·safe area·키보드
 | --- | --- | --- | --- |
 | 작업 | AuthScreenLayout 공개 행동 슬롯 | 제공자 버튼에는 이름만; 로그인 중 카드 중앙 스피너 하나 | 같은 표면에 경쟁하는 primary 하나만 |
 | 복구 | Button·secondary | 오류 근처 | 재시도할 대상과 범위를 표시 |
+| 나가기 | AuthScreenLayout `exit`(아이콘 뒤로/닫기) | 머리 띠 시작 끝 | 0~1. 로그인 진행 중에는 제품이 `disabled` |
 
 ## 상태
 

package/docs/usage/screens/common-profile.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 구성 API 지침 참조
-- 검토일: 2026-10-17
+- 검토일: 2026-10-18
 - 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screen-flows.tsx`(`ProfileScreen`·`EditorScreen`), 예제 `showcase/*/screen-flow-previews.tsx`(`AccountFlowPreview`)·`saved-profile-previews.tsx`(`ProfileEditFields`), 기본 얼굴 `showcase/web/src/patterns/ProfileStudio.previews.tsx`·`showcase/native/src/profile-face-preview.tsx`·`showcase/shared/profile-studio.ts`. 2026-10-06 사용자 승인으로 실험 `공통 화면/프로필`을 배포하면서 같은 프로필 수정을 직접 조립으로 보이던 배포 `화면/프로필 편집`과 합쳤다(API 기반 우선, Web id `patterns-profile-studio` 보존, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/계정/프로필`
 
@@ -53,7 +53,7 @@
 | 바깥 틀 | ProfileScreen · EditorScreen(둘 다 ScreenLayout) | route 본문, host가 남은 높이·safe area·키보드를 준다 | 폭 최대 720, 바깥 padding `spacing.md` 16([ScreenLayout 배치](../components/screen-layout.md#배치)), 본문 스크롤 |
 | 머리 | `title` + `actions`(IconButton ghost 계정 메뉴) | 맨 위, 고정 | 제목 열 최소 120 × 글자 배율 |
 | 요약 | `summary`(제품) | 본문 맨 위 | 요약 안 배치는 제품 소유 |
-| 수정 진입 | `edit` → Button ghost | 요약 아래 | 요약과 `spacing.md` 16 |
+| 수정 진입 | `edit` → Button ghost | 요약 아래 | 요약과 `spacing.md` 16. 프로필 카드 안에 두는 제품은 `editPlacement="summary"`(ProfileSummary 행동 줄 맨 앞, `secondary` `small`, 1.31.0) |
 | 게시물 | `children` > Stack `gap="md"` > 탭 Button 줄 + Grid `columns={{ compact: 3 }}` | 수정 아래 | 요약 묶음과 `spacing.xl` 24, 격자 간격 `spacing.xxs` |
 | 계정 메뉴 | Sheet > ListRow, `footer` > Button ghost 로그아웃 → AlertDialog | 오버레이 | footer 고정 |
 | 수정 화면 | EditorScreen `submitPlacement="footer"` > 사진·이름·소개 필드 | 같은 route에서 보기 대신 | footer: 초안 상태 → 저장 primary, 사이 `spacing.sm` 12 |
@@ -77,7 +77,7 @@
 
 | 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
 | --- | --- | --- | --- |
-| 프로필 수정 | `edit` → Button ghost | 요약 아래 | 1 |
+| 프로필 수정 | `edit` → Button ghost(`editPlacement="summary"`면 ProfileSummary 안 `secondary` `small`) | 요약 아래(또는 요약 카드 안 행동 줄 맨 앞) | 1 |
 | 계정 메뉴 | IconButton ghost(접근성 이름 "계정 메뉴") | 머리 끝(`actions`) | 1. 로그아웃·연결 계정은 메뉴 안 |
 | 게시물·저장됨 전환 | [SegmentedControl](../components/segmented-control.md)(label "프로필 보기") | 게시물 영역 맨 위 | 2개 항목, 단일 선택. 선택 상태를 ghost Button으로 흉내 내지 않는다 |
 | 게시물 열기 | 사진 칸 전체 | 격자 | 칸마다 1. 상세는 ScreenLayout + `exit` 뒤로 아이콘 |

package/docs/usage/screens/flow-editor.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 구성 API 지침 참조
-- 검토일: 2026-10-17
+- 검토일: 2026-10-18
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/작성과 수정`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/콘텐츠/작성과 수정`
 
@@ -31,7 +31,7 @@ host: 남은 높이·safe area·키보드
 
 | 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
 | --- | --- | --- | --- |
-| 작업 | EditorScreen 공개 행동 슬롯 | 취소는 헤더; 저장은 footer; 수정한 채 이탈하면 확인 | 같은 표면에 경쟁하는 primary 하나만 |
+| 작업 | EditorScreen 공개 행동 슬롯 | 취소는 헤더(단계형은 두 번째 단계부터 `stepBack` 뒤로); 저장은 footer; 수정한 채 이탈하면 확인 | 같은 표면에 경쟁하는 primary 하나만 |
 | 복구 | Button·secondary | 오류 근처 | 재시도할 대상과 범위를 표시 |
 
 ## 상태
@@ -54,6 +54,17 @@ host: 남은 높이·safe area·키보드
 | 저장 성공 | 제출 snapshot을 saved로 갱신 | 요청 후 새로 쓴 내용까지 saved로 처리하지 않는다. draftStatus는 실제 임시 저장 성공 때만 표시한다 |
 | 브라우저·OS 뒤로 | 제품 router의 이탈 가드 | EditorScreen cancel의 discard와 같은 제품 결정을 공유한다 |
 
+### 단계형 작성(1.31.0)
+
+색 → 이모지 → 글처럼 단계가 나뉜 작성은 같은 EditorScreen 안에서 단계를 바꾼다. 앞 단계로 돌아가는 길은 둘이다.
+
+| 행동 | 연결 | 규칙 |
+| --- | --- | --- |
+| 헤더 뒤로 | EditorScreen `stepBack`(두 번째 단계부터) | 헤더 시작 끝이 × 대신 뒤로 화살표가 된다. 단계를 되돌릴 뿐 이탈이 아니라 `discard` 확인을 띄우지 않는다. 첫 단계에서는 `stepBack`을 빼 × 닫기(`cancel`·`discard`)로 돌아간다. 저장 중에는 잠긴다 |
+| 지난 단계 누르기 | 본문 맨 위 [Steps](../components/steps.md) `onStepPress` | 커서 앞 단계만 버튼이다. 현재·다음 단계는 누를 수 없다(검증을 건너뛰지 않는다). 제출 중처럼 흐름이 잠긴 동안은 `onStepPress`를 빼면 모두 표시 전용이 된다 |
+
+2026-10-18 spint 작성 화면이 이 두 행동 때문에 EditorScreen 머리를 제품 TopBar로 바꾸고 단계 표시를 직접 그렸다.
+
 본문이 ready가 아닌 최초 조회·오류·제한 상태에서는 헤더/하단 어느 위치의 저장도 비활성이다. 실패한 저장은
 본문을 오류 화면으로 교체하지 않고 위 표처럼 ready + notice로 유지한다.
 

package/docs/usage/screens/flow-moderation.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 구성 API 지침 참조
-- 검토일: 2026-10-17
+- 검토일: 2026-10-18
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/신고와 차단`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/소통/신고와 차단`
 
@@ -32,7 +32,7 @@ host: 남은 높이·safe area·키보드
 | 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
 | --- | --- | --- | --- |
 | 닫기 | ScreenLayout `exit` `kind="close"` | 헤더 시작 끝 아이콘 버튼 | 1. 신고하지 않고 화면을 닫는다 |
-| 작업 | ModerationScreen 공개 행동 슬롯 | 신고는 footer; 차단은 별도 확인 후 실행 | 같은 표면에 경쟁하는 primary 하나만 |
+| 작업 | ModerationScreen 공개 행동 슬롯 | 신고는 footer; 차단은 별도 확인 후 실행. 운영자 검토(`variant="review"`)는 결정 버튼을 footer에 세로로 쌓는다 | 같은 표면에 경쟁하는 primary 하나만 |
 | 복구 | Button·secondary | 오류 근처 | 재시도할 대상과 범위를 표시 |
 
 ## 상태
@@ -55,11 +55,39 @@ host: 남은 높이·safe area·키보드
 | 차단 실패 | AlertDialog 유지 | Promise 실패를 전달한다. 확인창을 먼저 닫고 성공 처리하지 않는다 |
 | 대상 변경 | 대상 id와 초안·요청 묶음 갱신 | 이전 대상의 늦은 응답이 새 대상 상태를 덮지 않게 한다 |
 
+### 편지·카드·Sheet 안에서 신고(1.31.0)
+
+신고가 별도 route가 아니라 편지 아래에 펼쳐지거나 Sheet 안에 열리면 [ModerationForm](../components/moderation-screen.md#moderationform-화면-틀-없는-신고-폼)을 쓴다.
+ModerationScreen과 같은 사유 선택·추가 설명·신고/차단 버튼과 규칙을 화면 머리·바깥 여백 없이 그린다.
+
+```text
+편지(제품 Surface)
+└─ [신고] 제목(선택) → 사유 선택 → 추가 설명 → [신고하기] → [차단] → [취소]
+```
+
+| 행동 | 연결 | 규칙 |
+| --- | --- | --- |
+| 펼친 신고 접기 | `cancel` → 마지막 ghost 버튼 | Sheet 안에서는 Sheet 닫기가 있으므로 생략 가능 |
+| 제목 | `title`(구성 제목 `level3`) | 제목 줄이 있는 Sheet·Dialog 안에서는 생략한다 |
+| 화면 틀 | ModerationScreen에 `contentInset="none"`·`scroll="content"`를 주어 끄지 않는다 | 머리 띠와 footer 표면이 남는다 |
+
+### 운영자 검토(1.31.0)
+
+신고·이의 신청 처리 화면은 ModerationScreen `variant="review"`다. 신고된 내용(`children`) → 처리 사유 자유 입력 → 결정 버튼(기각·숨기기·유지·번복 등, 문구는 제품) 순이다.
+
+| 상황 | 연결 | 유지·복구 |
+| --- | --- | --- |
+| 사유 미입력 | 모든 결정 비활성(`decisionReason.required` 기본 `true`) | 공백만 있는 사유는 입력하지 않은 것으로 본다 |
+| 되돌리기 어려운 결정 | 결정의 `confirmation`(AlertDialog `confirm`, 보통 `tone: "danger"`) | 버튼은 확인창만 열고 `onConfirm`이 실행한다. 실패는 Promise로 넘겨 확인창을 유지한다 |
+| 결정 진행 중 | 그 결정 `pending` | 다른 결정과 사유 입력을 HJM이 잠근다 |
+| 이미 처리됨 | `resolution`(예: Notice `success` + 처리 사유) | 사유 입력과 결정 버튼 자리를 대체한다 |
+| 처리 결과·충돌 | `notice` 또는 `children` 안 Notice | 서버 확정 후에만 성공을 표시한다 |
+
 ## 사용하는 지침
 
 | 지침 | 쓰는 곳 |
 | --- | --- |
-| [ModerationScreen](../components/moderation-screen.md) | 필수 props·슬롯·플랫폼 차이 |
+| [ModerationScreen](../components/moderation-screen.md) | 필수 props·슬롯·플랫폼 차이, 운영자 검토 `variant="review"`, 화면 틀 없는 `ModerationForm` |
 | [Button](../components/button.md) | 동작·로딩·보조 행동 |
 | [ScreenLayout](../components/screen-layout.md) | 화면 높이·본문 교체·스크롤 소유 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hjmds/design-contracts",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "description": "Renderer-neutral design contracts, tokens, recipes, and behaviors shared by HJM products.",
   "license": "MIT",
   "repository": {
@@ -801,6 +801,7 @@
     },
     "./conversation-row": {
       "types": "./dist/conversation-row.d.ts",
+      "react-native": "./dist/conversation-row.js",
       "import": "./dist/conversation-row.js",
       "default": "./dist/conversation-row.js"
     }