@hjmds/design-contracts 1.12.1 → 1.13.1

package/docs/usage/components/toast.md

@@ -0,0 +1,145 @@
+# Toast
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Toast](../../toast.md), [Liquid Toast](../../../../react-native/docs/liquid-toast.md), `src/component-recipes.ts`(`toastRecipe`)
+- 스토리북: `배포/컴포넌트/상태와 알림/토스트`, `배포/컴포넌트/상태와 알림/리퀴드 토스트`
+
+## 언제 쓰나
+
+방금 한 행동의 결과처럼 **무시해도 안전한 짧은 알림**에 쓴다. 저장 완료, 복사 완료, 백그라운드 작업 완료
+알림이 여기에 속한다. 화면 흐름 밖에 떠서 3초 뒤 스스로 닫히고, 큐에 쌓인 다음 알림이 이어서 뜬다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 화면 안에 계속 남아야 하는 안내·경고(점검 예정, 권한 없음, 폼 오류 요약) | [Notice](notice.md) |
+| 사용자가 응답해야 진행되는 확인·삭제 확인·필수 선택 | [AlertDialog](alert-dialog.md) |
+| 작업 결과를 화면 전체로 보여 줌 | [Result](result.md) |
+
+선택 기준: 사용자가 놓쳐도 되고 자리를 차지하면 안 되면 Toast, 그 화면을 보는 동안 계속 보여야 하거나
+읽지 않으면 다음 행동을 잘못할 수 있으면 Notice다. Toast에는 그 알림에서만 할 수 있는 행동을 두지 않는다.
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Toast` | 기본(알림 한 장, controlled) | `@hjmds/react`, `/toast` | `@hjmds/react-native`, `/feedback` |
+| `ToastProvider`·`useToast` | 동반(Web 큐·viewport) | `@hjmds/react`, `/toast` | — |
+| `ToastRegion`·`useToastRegion` | 동반(Native 큐·영역) | — | `@hjmds/react-native`, `/feedback` |
+| `createLiquidToastPresentation` | 확장(선택형 리퀴드 표현) | — | `/toast-liquid`만(root 재노출 없음) |
+
+## 최소 사용 예
+
+```tsx
+// Web: 앱 루트에 한 번
+import { ToastProvider, useToast } from "@hjmds/react/toast";
+
+<ToastProvider label={t("common.notifications")}>{children}</ToastProvider>;
+
+// 화면 컴포넌트 안에서 알림을 낸다
+function useProfileSavedToast() {
+  const toast = useToast();
+  return () =>
+    toast.publish({
+      id: "profile-save",
+      description: t("profile.saved"),
+      tone: "success",
+      closeLabel: t("common.closeNotification"),
+    });
+}
+```
+
+```tsx
+// Native: 앱 루트에 한 번
+import { ToastRegion, useToastRegion } from "@hjmds/react-native/feedback";
+
+<ToastRegion safeAreaInsets={insets} accessibilityLabel={t("common.notifications")}>
+  {children}
+</ToastRegion>;
+
+function useProfileSavedToast() {
+  const toast = useToastRegion();
+  return () =>
+    toast.publish({
+      id: "profile-save",
+      description: t("profile.saved"),
+      tone: "success",
+      closeLabel: t("common.closeNotification"),
+    });
+}
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| descriptor | `id`·`description`·`closeLabel` 필수, `title`·`tone`·`priority`·`durationMs`·`action`·`announcement`·`presentation` 선택 | — | 모두 `string`(ReactNode 아님) |
+| `action` | `{ label, accessibilityLabel?, onAction: () => void, dismissOnAction? }` | — | 누르면 `onAction`, 기본으로 알림이 닫힌다 |
+| `tone` | `neutral` · `info` · `success` · `warning` · `danger` | `neutral` | — |
+| `priority` | `normal` · `high` | — | 낭독 순서, 색과 무관 |
+| `durationMs` | ms · `null` | 3000 | 더 짧게 줘도 3000으로 올라간다. `null`은 수동으로 닫을 때까지 유지, `action`이 있으면 기본 유지 |
+| `placement` | `bottom` · `top` · `top-start` · `top-end` · `bottom-start` · `bottom-end` | `bottom` | — |
+| 큐 | `maxVisible` · `maxQueued` · `duplicatePolicy` · `timerUpdatePolicy` · `overflowPolicy` | 1 · 20 · `update` · `preserve` · `discard-oldest` | — |
+| `publish` | Web `(descriptor, options?) => ToastPublishResult`, Native `(descriptor) => ToastPublishResult` | — | 결과는 `{ outcome: "added" \| "updated", id, position: "visible" \| "queued" }`, `{ outcome: "ignored", id, reason: "duplicate" \| "closing" }`, `{ outcome: "discarded", id, reason: "queue-overflow" }` 중 하나 |
+| `dismiss` | Web `(id, reason) => boolean`, Native `(id, reason?) => boolean` | — | 닫았으면 `true`. Web은 `close(id)`도 있다. Native는 `pause`·`resume(id, reason?)`도 있다 |
+| 닫힘 사유 `ToastDismissReason` | `timeout` · `action` · `close-action` · `escape` · `swipe` · `programmatic` · `queue-overflow` · `interrupted` | — | Web `Toast` `onDismissRequest`·Native `onDismiss`가 받는다 |
+| `toasts`/`defaultToasts` + `onToastsChange`(Native `ToastRegion`) | `readonly ToastDescriptor[]`, `(toasts) => void` | — | 큐를 제품 상태로 제어할 때 |
+| `safeAreaInsets`(Native) | `{ top?, bottom?, left?, right?, start?, end? }` | `{}` | — |
+| `layoutStyle`(Native `Toast`·`ToastRegion`) | `HjmCompositionStyleProp` | — | Web Toast·ToastProvider에는 없다(떠 있는 층이라 배치 대상이 아님) |
+| `style`·`toastStyle`(Native) | `StyleProp<ViewStyle>` | — | deprecated — `layoutStyle` 또는 `placement`·`safeAreaInsets`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 카드 최대 폭 420(Web `min(420px, 100vw − 2×spacing.md)`, Native 화면 폭 − 안전 영역 − 2×16에서 420으로 자름). 최소 높이 56(`layout.rowHeight.singleLine`). 열은 [아이콘 배지 32][문구][닫기 44]. `action`은 높이 44(`control.minTouchTarget`), 좌우 여백 `spacing.md` 16의 pill | `toastRecipe.viewport`·`surface`·`icon`·`action`, `.hjm-toast`, `react-native/src/feedback.tsx` |
+| 간격 | 화면 가장자리에서 `spacing.md` 16 + 안전 영역(`safeAreaMode: "additive"`). 여러 장 사이 `spacing.sm` 12. 카드 안 열 간격 `spacing.sm` 12 | `toastRecipe.viewport`, `.hjm-toast-viewport` |
+| 순서·정렬 | 기본은 아래 가운데(`placement="bottom"`). 위쪽 배치는 위에서 아래로, 아래쪽 배치는 가장자리부터 위로 쌓인다. `action`은 둘째 줄 끝 | `toastRecipe.placements`, `.hjm-toast__action` |
+| 고정·스크롤 | 화면 흐름 밖에 떠 있는 층이라 본문 레이아웃에 자리를 만들지 않는다. 하단 고정 바(BottomNavigation·BottomCTA)가 있으면 Web `bottomOffset`(px 또는 CSS 길이), Native `keyboardOffset`으로 그 위에 띄운다. Native 아래쪽 배치는 `avoidKeyboard`(기본 true)로 키보드 위에 선다 | `react/src/toast.tsx`, `react-native/src/feedback.tsx`(`ToastRegion`) |
+| 좁은 폭·큰 글자 | 폭이 줄고 문구가 줄바꿈되어 카드가 세로로 자란다. 잘라 내지 않는다 | `.hjm-toast__content`(`overflow-wrap: anywhere`) |
+
+```text
+아래 배치(기본)                         하단 바가 있을 때
+┌──────────────────────────────┐      ┌──────────────────────────────┐
+│ 본문(스크롤)                 │      │ 본문(스크롤)                 │
+│                              │      │ ┌──────────────────────────┐ │
+│ ┌──────────────────────────┐ │      │ │(●) 저장했어요        [×] │ │
+│ │(●) 저장했어요        [×] │ │      │ │              [되돌리기]  │ │ ← action(선택)
+│ └──────────────────────────┘ │      │ └──────────────────────────┘ │
+│   ↑ 16 + 안전 영역           │      │   ↑ bottomOffset/keyboardOffset
+└──────────────────────────────┘      │ [홈] [검색] [내 정보]        │ ← 고정 바
+  좌우 16, 최대 폭 420, 가운데         └──────────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- Provider/Region은 앱에 하나만 두고 화면마다 새로 만들지 않는다. 진행 상태를 바꿀 때는 같은 `id`로 다시 `publish`한다.
+- 문구는 모두 i18n 키로 만든 일반 문자열이다(ReactNode 아님). 아이콘만 있는 닫기 버튼 때문에 `closeLabel`이 필수다.
+- 색·모양은 tone이 정한다. 카드에 브랜드 색을 덮지 않는다. 문구·id·action은 제품 소유, 카드 모양·큐·타이머는 HJM 소유다.
+- Native는 `safeAreaInsets`를 제품이 넘긴다(기본 `{}`). 하단 고정 바가 있으면 Web `bottomOffset`, Native `keyboardOffset`으로 띄운다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 영역 이름 | `label` 필수(빈 문자열이면 throw) | `accessibilityLabel` 선택 |
+| 키보드 | `hotkey`+`hotkeyHelp`(둘 다 주거나 둘 다 생략), Escape로 닫기 | `avoidKeyboard`(기본 true) |
+| `Toast` 단독 닫힘 콜백 | `onDismissRequest` 필수 | `onDismiss` 선택 |
+| tone 아이콘 교체 | 없음 | `renderToneIcon` |
+| 모달 위 가림 | 없음 | `occluded` |
+| `presentation: "liquid"` | 무시하고 기본 카드 | `presentationAdapter`가 있을 때만 리퀴드 |
+
+## 함정
+
+- `/toast-liquid`는 앱에 없을 수 있는 optional native peer `@shopify/react-native-skia`·`react-native-reanimated`·
+  `react-native-worklets`를 import한다(peerDependenciesMeta에서 모두 optional). 2026-10에 이런 subpath가
+  tsc·테스트는 통과했는데 기기 Metro에서 크래시가 났다. 세 peer가 개발 클라이언트 바이너리에 들어 있을 때만 import한다.
+- 리퀴드는 `placement="top"`과 `maxVisible={1}`일 때만 동작하고, 아니면 `ToastRegion`이 `TypeError`를 던진다.
+  어댑터는 render 밖에서 만들거나 memo한다.
+- ToastRegion 배치는 `layoutStyle={{ flex: 1 }}`로 쓴다. Native 예제도 이 경로를 사용한다.
+- Web `Toast` 단독 렌더는 나머지 HTML 속성(id·data-*·이벤트)을 루트에 전달한다(미게시(1.12.1 이후). 1.12.1은 `className`만 전달). `role`·`aria-labelledby`·`aria-describedby`·`data-tone`·`data-state`는 Toast가 정하므로 덮이지 않는다. 배치는 Provider를 쓴다.

package/docs/usage/components/toggle-group.md

@@ -0,0 +1,95 @@
+# ToggleGroup
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [ToggleGroup](../../toggle-group.md), `src/toggle-group.ts`(`toggleGroupRecipe`)
+- 스토리북: `배포/컴포넌트/입력/토글 그룹`
+
+## 언제 쓰나
+
+여러 개를 동시에 켜고 끄는 짧은 버튼 묶음에 쓴다. 굵게·기울임·밑줄 같은 서식 토글,
+함께 거는 필터 몇 개가 여기에 속한다. 아무것도 켜지지 않은 상태도 유효한 값이다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 여러 개 중 정확히 하나를 고름(어떤 화면을 볼지) | [SegmentedControl](segmented-control.md) |
+| 목록 안에서 항목마다 줄·설명이 있는 다중 선택 | [CheckboxGroup](checkbox-group.md) |
+| 단독 켜고 끄기 설정 | [Switch](switch.md), 토글 버튼 하나는 [Button](button.md) `selected` |
+| 많은 필터를 칩으로 나열 | [Chip](chip.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ToggleGroup` | 기본 | `@hjmds/react`, `/toggle-group` | `@hjmds/react-native`, `/toggle-group` |
+
+descriptor 타입과 helper는 `@hjmds/design-contracts/components/toggle-group`에 있다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ToggleGroup } from "@hjmds/react/toggle-group";
+
+const descriptor = {
+  accessibilityLabel: t("editor.format.group"),
+  items: [
+    { id: "bold", label: t("editor.format.bold") },
+    { id: "italic", label: t("editor.format.italic") },
+  ],
+} as const;
+
+<ToggleGroup descriptor={descriptor} pressedIds={formats} onPressedIdsChange={setFormats} />
+```
+
+```tsx
+// Native
+import { ToggleGroup } from "@hjmds/react-native/toggle-group";
+
+<ToggleGroup descriptor={descriptor} pressedIds={formats} onPressedIdsChange={setFormats} size="small" />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `pressedIds` / `defaultPressedIds` | `ReadonlySet<Id>` | 빈 집합 | 제어 또는 비제어 |
+| `onPressedIdsChange` | `(ids: ReadonlySet<Id>) => void` | — | 다음 눌림 집합 전체를 받는다 |
+| `descriptor` | `{ accessibilityLabel: string, items: readonly { id, label, disabled? }[] }` | — (필수) | — |
+| `size` | `small` · `medium` | `medium` | medium은 최소 높이 44 |
+| `items[].disabled` | `boolean` | `false` | `disabled` 항목은 켜지지 않고 눌림 집합에도 들어가지 않는다. 사라진 id의 눌림 상태는 렌더 때 버려진다(`reconcileToggleGroupSelection`) |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 묶음 컨테이너 배치. Web·Native 모두 |
+| `style`(Native) | `StyleProp<ViewStyle>` | — | deprecated — `layoutStyle` 또는 `size`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 항목 높이는 두 size 모두 최소 44(`control.minTouchTarget`). 좌우 여백 `small` `spacing.sm` 12, `medium` `spacing.md` 16, 모서리 `radius.md` 12 | `toggleGroupRecipe.sizes`·`radius` |
+| 간격 | 항목 사이 `spacing.xxs` 4 | `toggleGroupRecipe.gap` |
+| 순서·정렬 | `items` 배열 순서 그대로, 시작 쪽(왼쪽)에 붙는다. 편집 도구 줄·필터 줄처럼 적용될 내용 바로 위에 가로로 놓는다 | `.hjm-toggle-group`, `react-native/src/toggle-group.tsx` |
+| 고정·스크롤 | 가로 스크롤로 바꾸지 않는다 | — |
+| 좁은 폭·큰 글자 | 폭이 모자라면 다음 줄로 넘어간다(Web·Native 모두 wrap) | `.hjm-toggle-group`(`flex-wrap`), `react-native/src/toggle-group.tsx` |
+
+## 꼭 지킬 것
+
+- `descriptor.accessibilityLabel`은 필수다. 묶음 이름이며 개별 버튼 라벨로 대신할 수 없다.
+  비거나 `items`가 비었거나 id가 겹치면 렌더 중 예외가 난다.
+- 라벨은 i18n 키로 넣고 짧게 둔다. 단일 선택 모드는 없다. 하나만 고르게 하려고 변환하지 않는다.
+- 눌림 표시 색은 recipe(`idle`/`pressed`)가 소유한다. 상태는 Web `aria-pressed`, Native `selected`로
+  알리므로 색만으로 상태를 바꿔 그리지 않는다.
+- 배치는 `layoutStyle`(묶음 컨테이너)로 한다. Web `className`·Native의 deprecated `style`로 항목 모양을 덮지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 컨테이너 | `role="group"` + `aria-label` | `View` + `accessibilityLabel`(role 없음) |
+| 배치 | CSS(`hjm-toggle-group`) | 가로 `flexWrap: "wrap"` |
+| 외부 꾸밈 | `className`, `ref`, `layoutStyle` | `layoutStyle`(`style`은 deprecated) |
+| 키보드 | 항목마다 tab stop(roving 없음) | 해당 없음 |

package/docs/usage/components/tooltip.md

@@ -0,0 +1,103 @@
+# Tooltip
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Tooltip](../../tooltip.md), [Popover의 Tooltip·Menu·Popover 판정](../../popover.md), `src/component-recipes.ts`(`tooltipRecipe`)
+- 스토리북: `배포/컴포넌트/오버레이/툴팁`
+
+## 언제 쓰나
+
+Web에서 이미 이름과 focus를 가진 컨트롤(대개 [IconButton](icon-button.md))에 **짧은 보충 설명 한 문장**을
+붙일 때 쓴다. 마우스를 올리면 500ms 뒤, 키보드 focus면 바로 열리고 Escape로 닫힌다.
+브라우저 `title` 속성 툴팁 대신 쓴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 버튼·링크·입력처럼 사용자가 눌러야 하는 내용이 들어감 | [Popover](popover.md) |
+| 행동 항목 목록 | [Menu](menu.md), [ContextMenu](context-menu.md) |
+| 오류·필수 정보처럼 놓치면 안 되는 내용 | [Field](field.md)의 설명·오류, [Notice](notice.md) |
+| 처음 쓰는 사용자에게 순서대로 기능 소개 | [Tour](tour.md) |
+| 컨트롤의 접근성 이름 자체 | 컨트롤의 `label`(Tooltip은 이름을 대신하지 않는다) |
+
+Tooltip과 Popover의 구분: 안에 focus가 들어가야 하면(눌러야 할 것이 있으면) Popover다. Tooltip은 plain
+string만 받고 focus를 받지 않으며, hover·focus가 풀리면 닫힌다. Popover는 click으로 열고 안의 컨트롤로
+focus가 이동하며 `title`·`closeLabel`이 필수다.
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Tooltip` | 기본 | `@hjmds/react`, `/overlays` | — |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { IconButton } from "@hjmds/react/actions";
+import { Tooltip } from "@hjmds/react/overlays";
+
+<Tooltip
+  content={t("notifications.tooltip")}
+  trigger={
+    <IconButton label={t("notifications.open")} onClick={openInbox}>
+      <BellIcon />
+    </IconButton>
+  }
+/>
+```
+
+Native: 없음. 계약상 Native는 `unsupported`이고 hover UI를 흉내 내지 않는다.
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `content` | 현지화된 비어 있지 않은 문자열 | — | ReactNode·링크·버튼은 받지 않는다 |
+| `placement` | `top` · `bottom` · `start` · `end` | `top` | 공간이 모자라면 renderer가 반대쪽으로 뒤집는다 |
+| `align` | `center` · `start` · `end` | `center` | — |
+| `pointerOpenDelayMs` | ms | 500 | 최근 Tooltip이 닫힌 뒤 300ms 안의 이웃은 바로 열린다 |
+| `focusOpenDelayMs` | ms | 0 | — |
+| `open` / `defaultOpen` | `boolean` | `defaultOpen` `false` | controlled(`open`+`onOpenChange` 필수)·uncontrolled 중 하나 |
+| `onOpenChange` | `(open: boolean, detail: { reason }) => void` | — | `reason`은 `pointer` · `focus` · `pointer-leave` · `blur` · `escape` · `trigger-activation` · `another-tooltip` |
+| `trigger` | `ReactElement`(focus 가능한 단일 요소) | — (필수) | — |
+| `portalContainer` | `HTMLElement` | `document.body` | 말풍선을 붙일 곳 |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | trigger를 감싼 바깥 `span`의 배치(margin·`alignSelf` 등). 말풍선 위치에는 영향이 없다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 말풍선 안쪽 여백 사방 `spacing.xs` 8(`tooltipRecipe.surface.padding`; 2026-10-06까지 Web은 좌우 12였다, 1.12.1 이후 미게시), 모서리 `radius.sm` 8, 최대 폭 280(`tooltipRecipe.content.maxWidth`, 화면 폭 − 24를 넘지 않음). trigger는 그 자체로 최소 터치 영역 44를 지켜야 한다(Tooltip은 영역을 넓히지 않는다). 보통 [IconButton](icon-button.md) | `tooltipRecipe.surface`, `.hjm-tooltip__content` |
+| 간격 | trigger와 4(`positioning.sideOffset` = `spacing.xxs`), 뷰포트 가장자리와 최소 12(`positioning.collisionPadding` = `spacing.sm`) | `tooltipRecipe.positioning`, `react/src/overlays.tsx`(`Tooltip`) |
+| 순서·정렬 | trigger 바로 옆에 붙는다. 한 줄에 Tooltip 달린 아이콘 버튼이 여럿이면 하나만 보이고, 300ms 안에 옆으로 옮기면 바로 열린다 | `react/src/overlays.tsx`(`Tooltip`) |
+| 고정·스크롤 | 떠 있는 층(`position: fixed`)이라 문서 흐름에 자리를 만들지 않고 trigger 크기도 바꾸지 않는다. 공간이 모자라면 반대쪽으로 뒤집힌다 | `.hjm-tooltip__content`, `react/src/portal.tsx` |
+| 좁은 폭·큰 글자 | 넘치면 줄바꿈하고 자르지 않는다(`overflow-wrap: anywhere`) | `.hjm-tooltip__content` |
+
+```text
+placement="top"(기본), align="center"
+          ┌──────────────────┐
+          │ 알림 보기        │  ← 말풍선(최대 280)
+          └────────┬─────────┘
+                   │ 4
+                [ 🔔 ]          ← trigger(IconButton, 44)
+뷰포트 가장자리와 12 미만이면 아래로 뒤집힌다.
+```
+
+## 꼭 지킬 것
+
+- `trigger`는 focus 가능한 단일 interactive 요소다. Tooltip은 role·tabIndex·접근성 이름을 만들지 않으므로
+  클릭되는 `span` 같은 것을 trigger로 쓰지 않는다.
+- Tooltip 없이도 컨트롤의 이름과 결과를 이해할 수 있어야 한다. 핵심 정보를 Tooltip에만 두지 않는다.
+- trigger 자리의 배치는 `layoutStyle`로 한다. 말풍선 위치는 `placement`·`align`으로만 정하고 `className`으로 말풍선 모양을 덮지 않는다.
+- `HjmProvider` 안에서는 한 번에 하나만 보인다. Provider 밖이면 이 조정이 없다.
+
+## 함정
+
+- 터치에는 hover가 없어서, 터치 탭은 trigger의 원래 click을 실행하면서 Tooltip도 연다(두 번째 탭이나 바깥
+  누름으로 닫힘). 탭이 곧 행동이므로 모바일 Web에서 Tooltip을 미리 읽고 누르는 흐름을 기대하지 않는다.
+- 접근성 이름 구실을 하는 속성(`iframe title` 등)은 Tooltip으로 바꾸지 않는다.

package/docs/usage/components/top-bar.md

@@ -0,0 +1,124 @@
+# TopBar
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [화면 제목과 마지막 행동](../../screen-chrome.md), [NavigationBar](../../navigation-bar.md), `src/component-recipes.ts`(`topBarRecipe`)
+- 스토리북: `배포/컴포넌트/탐색/상단 탐색 막대`, `배포/컴포넌트/탐색/검색·메뉴가 있는 상단 바`, `배포/컴포넌트/탐색/내비게이션 바`
+
+## 언제 쓰나
+
+화면 맨 위에 붙는 **크롬**에 쓴다. 뒤로가기·닫기(`leading`), 짧은 화면 이름(`title`), 소수의 행동
+(`actions`/`trailing`)을 담는다. 스크롤과 무관한 자리이며 safe area 위쪽 여백을 처리한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 본문 첫 블록의 제목·설명(스크롤과 함께 움직임) | [Top](top.md) |
+| 최상위 route 전환 탭 | [BottomNavigation](bottom-navigation.md) |
+| 웹 사이드 탐색 | [Sidebar](sidebar.md) |
+| 화면 하단 주 행동 | [BottomCTA](bottom-cta.md) |
+| 행동이 많아 줄에 다 안 들어감 | 하나만 남기고 [Menu](menu.md)로 묶는다 |
+
+Top과 TopBar의 구분: TopBar는 고정 크롬(이동·화면 이름·액션), [Top](top.md)은 그 아래 본문의 첫 제목이다.
+브랜드·탐색 항목·검색/계정이 여러 개 들어가는 사이트 헤더는 TopBar가 아니라 `NavigationBar`다.
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `TopBar` | 기본 | `@hjmds/react`, `/top-bar` | `@hjmds/react-native`, `/navigation`, `/top-bar` |
+| `TopBarAction` | 동반(아이콘 위 짧은 라벨 행동) | — | `@hjmds/react-native`, `/navigation`, `/top-bar` |
+| `NavigationBar` | 확장(사이트 탐색 다중 슬롯 조합) | `/navigation-bar` | `/navigation-bar` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { IconButton } from "@hjmds/react/actions";
+import { TopBar } from "@hjmds/react/top-bar";
+
+<TopBar
+  title={t("settings.title")}
+  leading={<IconButton label={t("common.back")} onClick={goBack}><BackIcon /></IconButton>}
+/>
+```
+
+```tsx
+// Native
+import { TopBar, TopBarAction } from "@hjmds/react-native/top-bar";
+
+<TopBar
+  title={t("settings.title")}
+  safeAreaTop={insets.top}
+  leading={
+    <TopBarAction label={t("common.back")} labelVisibility="accessibility-only" onPress={goBack}>
+      <BackIcon />
+    </TopBarAction>
+  }
+  actions={<TopBarAction label={t("common.save")} onPress={save}><SaveIcon /></TopBarAction>}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `centered` | `boolean` | `true` | 남은 제목 영역 안에서의 정렬이며 좌우 열을 같은 폭으로 맞추지 않는다 |
+| `safeAreaTop` | 0 이상 유한수 | 0 | Web은 `env(safe-area-inset-top)`과 큰 값을 쓴다 |
+| `headingLevel` | 1~6 | 1 | Web만. 페이지 구조에 맞춘다 |
+| `onTitleClick`(Web) | `(event: MouseEvent<HTMLButtonElement>) => void` | — | 제목을 버튼으로 만든다 |
+| `onTitlePress`(Native) | `(event: GestureResponderEvent) => void` | — | 제목을 버튼으로 만든다 |
+| `titleLeading` | `ReactNode` | — | 제목 앞 작은 시각 요소 |
+| `leading` / `actions`(별칭 `trailing`) | `ReactNode` | — | 둘 중 한 이름만 쓴다 |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 루트 배치. Web·Native 모두 |
+| Native `style`·`leadingStyle`·`titleStyle`·`trailingStyle` | `StyleProp` | — | deprecated — `layoutStyle` 또는 `centered`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+| `TopBarAction` `intent` | `button` · `link` | `button` | `button`은 `onPress: (event) => void`, `link`는 `destination` + `onNavigate?: (destination: LinkDestination) => void \| Promise<void>` 또는 `renderLink` |
+| `TopBarAction` `labelVisibility` | `visible` · `accessibility-only` | `visible` | — |
+| `TopBarAction` `layoutStyle` | `HjmCompositionStyleProp` | — | `style`·`labelStyle`은 deprecated |
+| `NavigationBar` | `label`·`brand`·`children` 필수, `actions` 선택 | — | Web만 `layoutStyle`도 받는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 최소 높이 `control.buttonHeight.large` 52 + 위쪽 안전 영역. Web은 `max(env(safe-area-inset-top), safeAreaTop)`을 위 여백으로, Native는 `safeAreaTop`을 `paddingTop`과 `minHeight`(52 + `safeAreaTop`)에 더한다. 좌우 열 최소 폭 `control.minTouchTarget` 44, Native `TopBarAction` 최소 44×44 | `topBarRecipe.minHeight`·`sideMinWidth`·`action`, `.hjm-top-bar` |
+| 간격 | 좌우 여백 `spacing.md` 16, 슬롯 사이·슬롯 안 행동 사이 `spacing.xs` 8. `TopBarAction` 아이콘–라벨 `spacing.xxs` 4, 좌우 여백 4. 배경 `canvas` | `topBarRecipe.paddingHorizontal`·`gap`·`action` |
+| 순서·정렬 | 세 열: `leading`(뒤로·닫기) · 제목 · `actions`(끝 정렬). `centered`(기본)는 남은 제목 영역 안에서만 가운데 정렬. 행동은 1~2개만 끝 열에, 넘치면 하나만 남기고 [Menu](menu.md)로 묶는다. 주 행동(저장·완료)은 끝 열의 마지막 | `.hjm-top-bar` grid, Native `TopBar` |
+| 고정·스크롤 | 화면 맨 위, 스크롤 영역 **밖**에 둔다. TopBar 자체는 `position: sticky`/고정을 걸지 않으므로 화면 골격이 그 아래에 스크롤 영역을 둬야 고정된다. 바로 아래 본문 첫 블록은 [Top](top.md) | `.hjm-top-bar`(position 없음) |
+| 좁은 폭·큰 글자 | 글자 배율 ≥ `largeTextThreshold` 1.6: Web은 첫 행 leading·행동, 둘째 행 제목(시작 정렬, 위아래 `spacing.xs` 8). Native는 첫 행 leading+제목, 둘째 행 행동(끝 정렬, 줄바꿈 허용) | `.hjm-top-bar[data-large-text]`, `react-native/src/navigation.tsx` `TopBar` |
+
+```text
+기본                                   큰 글자 Web               큰 글자 Native
+┌──────────── safe area ───────────┐   ┌──────────────────────┐   ┌──────────────────────┐
+│ [<]        화면 이름       [⋯][✓]│   │ [<]           [⋯][✓] │   │ [<] 화면 이름        │
+└──────────────────────────────────┘   │ 화면 이름            │   │          [⋯][✓]      │
+  leading 44+  title(1fr)  actions 44+ └──────────────────────┘   └──────────────────────┘
+───────────── 아래부터 스크롤 영역 ─────────────
+```
+
+## 꼭 지킬 것
+
+- `actions`와 `trailing`은 같은 슬롯의 두 이름이다. 둘을 함께 주면 `TypeError`다.
+- `title` 없이 `titleLeading`·`onTitleClick`/`onTitlePress`·`titleAccessibilityLabel`을 주면 `TypeError`다.
+- 이동은 슬롯 안의 Link(Native는 `intent="link"`)로, 제목 클릭은 실제 버튼으로 표현한다.
+- 화면 이름·행동 라벨은 i18n 키로, 아이콘은 제품 소유다. 높이·간격·제목 색은 recipe가 정한다.
+  배치는 `layoutStyle`로만 하고 Native의 deprecated 슬롯 스타일로 덮지 않는다.
+- 큰 글자에서 Native는 슬롯 구조를 다시 만들어 슬롯 안 로컬 상태·포커스가 초기화될 수 있다.
+  유지할 상태는 TopBar 밖에 둔다.
+- `NavigationBar`는 `label`(빈 문자열이면 throw)·`brand`·`children` 필수, `actions` 선택이다.
+  메뉴·검색 동작은 그 안의 [Menu](menu.md)·[SearchField](search-field.md)가 소유한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 루트 | `div`(Dialog 안에서도 landmark를 추가하지 않음), ref·HTML 속성 전달 | `accessibilityRole="toolbar"` `View`, ref 없음 |
+| 제목 접근성 | `h1`~`h6` | `accessibilityRole="header"`, `titleAccessibilityHint`(`onTitlePress` 필수) |
+| 슬롯 스타일 | `className`·`style`, 배치는 `layoutStyle` | 배치는 `layoutStyle`(`style`·`leadingStyle`·`titleStyle`·`trailingStyle`은 deprecated) |
+| 큰 글자 | CSS가 제목을 다음 행으로 | 글자 배율이 `largeTextThreshold` 이상이면 leading+제목 행 아래에 행동 행 |
+| 행동 컴포넌트 | 일반 `IconButton`·`Link` | `TopBarAction`(아이콘 + 마이크로 라벨, 44pt) |
+| `NavigationBar` 배경 | 지원 시 blur + 92% 불투명 | 불투명 surface(blur 없음) |

package/docs/usage/components/top.md

@@ -0,0 +1,89 @@
+# Top
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Top](../../top.md), `src/top.ts`(`topRecipe`)
+- 스토리북: `배포/컴포넌트/레이아웃/화면 제목과 설명`
+
+## 언제 쓰나
+
+화면 **본문의 첫 블록**에 쓴다. 사용자가 "이 화면이 무엇을 묻는지" 읽는 제목과 보조 문장이며, 스크롤과
+함께 올라간다. 화면당 하나다. 시트·모달 안 화면의 첫 제목에는 `size: "medium"`을 쓴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 화면 위에 고정된 뒤로가기·화면 이름·행동 | [TopBar](top-bar.md) |
+| 본문 중간의 묶음 제목 | [Section](section.md) |
+| 제목 글자만 필요 | [Heading](heading.md) |
+| 사이트 전체 탐색 바 | [TopBar](top-bar.md)의 `NavigationBar` |
+
+Top과 TopBar의 구분: TopBar는 화면에 붙어 있는 크롬(safe area, 뒤로가기, 액션)이고 Top은 그 아래에서 스크롤되는
+본문 제목이다. 한 화면에 둘을 같이 써도 된다. 이때 TopBar `title`을 생략하거나 Top과 다른 짧은 이름으로 둔다.
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Top` | 기본 | `@hjmds/react`, `/top` | `@hjmds/react-native`, `/top` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Link } from "@hjmds/react/actions";
+import { Top } from "@hjmds/react/top";
+
+<Top
+  descriptor={{ title: t("signup.title"), description: t("signup.description") }}
+  trailing={<Link href="/help">{t("common.help")}</Link>}
+/>
+```
+
+```tsx
+// Native
+import { Top } from "@hjmds/react-native/top";
+
+<Top descriptor={{ eyebrow: t("signup.step", { n: 1 }), title: t("signup.title") }} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `descriptor` | `{ title: string, eyebrow?: string, description?: string, size?, headingLevel? }` | — | 값을 주면 공백만 있는 문자열은 `TypeError` |
+| `descriptor.size` | `large` · `medium` | `large` | `large`는 화면 첫 제목, `medium`은 시트·모달 안. 세 번째 크기는 없다 |
+| `descriptor.headingLevel` | `1` · `2` · `3` | `1` | 한 라우트가 여러 화면을 담을 때만 낮춘다(Web만 반영) |
+| `trailing` | `ReactNode`(요소 하나) | — | 제목 줄을 같이 쓰는 보조 행동. 공간이 모자라거나 큰 글자면 아래로 내려간다 |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 루트 배치. Web·Native 모두 |
+| `style`(Native) | `StyleProp<ViewStyle>` | — | deprecated — `layoutStyle`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 좌우 여백 없음. 위·아래 여백 `large` `spacing.xl` 24 / `spacing.md` 16, `medium` `spacing.md` 16 / `spacing.sm` 12 | `topRecipe.sizes`, `.hjm-top` |
+| 간격 | Web은 eyebrow 아래 `spacing.xxs` 4, description 위 `spacing.xs` 8. Native는 세 줄 사이 `spacing.xs` 8. 제목–`trailing` `spacing.xs` 8. 아래 본문 첫 블록과는 아래 여백으로 떨어진다 | `topRecipe.eyebrow`·`description`·`gap`, `.hjm-top__row` |
+| 순서·정렬 | eyebrow → 제목 줄 → description. 제목 줄은 제목(남은 폭) + `trailing`(끝 정렬) | `.hjm-top__row`, `react-native/src/top.tsx` |
+| 고정·스크롤 | 스크롤 영역의 맨 처음, [TopBar](top-bar.md) 바로 아래. 화면 페이지 여백(`layout.pagePadding`, 보통 `regular` 20) 안에 넣는다 | `foundations.ts` `layout.pagePadding` |
+| 좁은 폭·큰 글자 | Web은 폭이 모자라면 줄바꿈으로, Native는 글자 배율 1.6 이상이면 `trailing`을 제목 아래로 내린다 | `.hjm-top__row`(flex-wrap), `react-native/src/top.tsx` |
+
+## 꼭 지킬 것
+
+- 문구는 모두 i18n 키로 만든 문자열이다. `description`은 잘리지 않고 줄바꿈되므로 말줄임을 덧대지 않는다.
+- `eyebrow`에는 제목을 한정하는 짧은 말(카테고리·단계)만 넣고 제목에 없는 새 정보를 넣지 않는다.
+- 주 행동을 `trailing`에 두지 않는다. 화면의 주 행동은 [BottomCTA](bottom-cta.md)나 본문 [Button](button.md)이다.
+- 상태가 없다. 제목을 바꾸려면 다른 문자열을 넘긴다.
+- 배치는 `layoutStyle`로 한다(Web `className`도 받는다). Native `style`은 deprecated다. 글자 크기·색은 recipe가 정하므로 덮지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 제목 요소 | 실제 `h1`~`h3`(`headingLevel`) | `accessibilityRole="header"`(단계 없음, `headingLevel` 미사용) |
+| `trailing` 내림 기준 | CSS 줄바꿈 | 글자 배율 1.6 이상이면 세로로 쌓음 |
+| ref | `forwardRef`(`header` 요소) | 없음 |