@hjmds/design-contracts 1.17.2 → 1.19.0

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

@@ -3,7 +3,7 @@
 - 단계: 화면
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
+- 적용: 구성 API 지침 참조
 - 검토일: 2026-10-08
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/공통 화면/설정`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/설정/앱 설정`
@@ -41,6 +41,18 @@ host: 남은 높이·safe area·키보드
 | 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
 | 오류 | 저장 실패는 notice로 알리고 마지막 확인값으로 복구 | 실패 원인과 재시도 경로 제공 |
 
+
+### 즉시 저장과 일괄 저장 선택
+
+2026-10-13 전수 점검에서 최초 조회와 변경 요청의 상태를 같은 골격으로 설명하던 부분을 구체화했다.
+
+| 상황 | 연결 | 유지·복구 |
+| --- | --- | --- |
+| 즉시 저장 | 각 Switch 행의 pending·오류 | 실패하면 마지막 확인값으로 복구하고 다른 설정은 유지한다 |
+| 일괄 저장 | 하단 저장 + 별도의 draft/saved | 실패하면 초안을 유지한다. 즉시 저장 방식의 되돌리기를 그대로 적용하지 않는다 |
+| 새로 받은 값 | 초안 수정 여부를 비교 | 편집 중 재조회 응답으로 초안을 덮지 않는다 |
+| 파괴 행동 | 일반 설정 묶음 뒤 별도 영역 | 로그아웃·탈퇴를 일반 토글과 같은 즉시 실행으로 연결하지 않는다 |
+
 ## 사용하는 지침
 
 | 지침 | 쓰는 곳 |
@@ -51,57 +63,17 @@ host: 남은 높이·safe area·키보드
 
 ## 코드 골격
 
-```tsx
-// Web
-import { SettingsScreen } from "@hjmds/react/screens";
-import { Switch } from "@hjmds/react/selection";
-import { ListRow } from "@hjmds/react/display";
-
-<SettingsScreen
-  title={t("settings.title")}
-  sections={[
-    { id: "notifications", title: t("settings.notifications"), children: (
-      <Switch
-        presentation="row"
-        label={t("settings.push.label")}
-        description={t("settings.push.description")}
-        checked={pushEnabled}
-        onCheckedChange={setPushEnabled}
-      />
-    ) },
-    { id: "account", title: t("settings.account"), children: (
-      <ListRow title={t("settings.language")} description={currentLanguageName} onClick={openLanguageSheet} />
-    ) },
-  ]}
-/>
-```
+문서와 Storybook은 같은 실행 예제를 참조한다. 제품 데이터·문구·저장·라우팅은 제품에서 연결하고,
+아래 preview의 메모리 상태를 서버 저장으로 취급하지 않는다. 예제는 읽기용이며 제품에서 showcase를 import하지 않는다.
 
-```tsx
-// Native
-import { SettingsScreen } from "@hjmds/react-native/screens";
-import { Switch } from "@hjmds/react-native/inputs";
-import { ListRow } from "@hjmds/react-native/data-display";
-
-<SettingsScreen
-  title={t("settings.title")}
-  sections={[
-    { id: "notifications", title: t("settings.notifications"), children: (
-      <Switch
-        presentation="row"
-        label={t("settings.push.label")}
-        description={t("settings.push.description")}
-        checked={pushEnabled}
-        onCheckedChange={setPushEnabled}
-      />
-    ) },
-    { id: "account", title: t("settings.account"), children: (
-      <ListRow title={t("settings.language")} description={currentLanguageName} onPress={openLanguageSheet} />
-    ) },
-  ]}
-/>
-```
+<!-- usage-example: Web ../../../../../showcase/web/src/patterns/settings-page-preview.tsx -->
+- [Web 실행 예제](../../../../../showcase/web/src/patterns/settings-page-preview.tsx): 공개 SettingsScreen·행·Sheet 조합과 로컬 설정 상태.
+<!-- usage-example: Native ../../../../../showcase/native/src/settings-page-preview.tsx -->
+- [Native 실행 예제](../../../../../showcase/native/src/settings-page-preview.tsx): 같은 흐름의 Native 공개 API와 이벤트 연결.
 
-콜백·데이터·지역화 함수는 제품에서 공급한다. 필수 props와 플랫폼별 차이는 위 API 지침에서 확인한다.
+설치 패키지에서 소스 링크를 열 수 없다면 [Web 원본](https://github.com/jim1286/hjm-design-system/blob/v1.17.1/showcase/web/src/patterns/settings-page-preview.tsx)과
+[Native 원본](https://github.com/jim1286/hjm-design-system/blob/v1.17.1/showcase/native/src/settings-page-preview.tsx)을 참고한다.
+고정 버전 예제와 현재 checkout의 후속 변경은 구분하며 설치된 타입을 기준으로 사용한다.
 
 ## 큰 글자·다크·좁은 폭
 

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

@@ -3,8 +3,8 @@
 - 단계: 화면
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
-- 검토일: 2026-10-06
+- 적용: 구성 API 지침 참조
+- 검토일: 2026-10-13
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/공통 화면/화면 골격`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/화면 틀과 도구/화면 골격과 상태`
 
@@ -41,6 +41,18 @@ host: 남은 높이·safe area·키보드
 | 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
 | 오류 | 초기 로딩만 본문 교체; 갱신 실패는 notice로 본문 유지 | 실패 원인과 재시도 경로 제공 |
 
+
+### 상태를 바꾸는 기준
+
+2026-10-13 전수 점검에서 최초 조회와 변경 요청의 상태를 같은 골격으로 설명하던 부분을 구체화했다.
+
+| 상황 | 연결 | 유지·복구 |
+| --- | --- | --- |
+| 첫 조회 | 데이터가 아직 없으면 state=loading; 실패하면 state=error + stateAction | 본문의 실제 남은 영역에서 중앙 정렬한다 |
+| 재조회 | 기존 데이터가 있으면 ready + notice | 스크롤·선택·입력을 유지하고 재시도 버튼만 pending |
+| 권한 제한 | restricted + stateAction | 서버 권한을 확인하기 전에는 민감한 children을 보이지 않는다 |
+| 행동 진행 | footer 버튼에 pending | ScreenLayout은 footer를 자동 잠그지 않으므로 제품이 중복 요청을 막는다 |
+
 ## 사용하는 지침
 
 | 지침 | 쓰는 곳 |

package/docs/usage/screens/dashboard.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.12.1
-- 검토일: 2026-10-06
+- 검토일: 2026-10-13
 - 근거: `showcase/web/src/patterns/Dashboard.stories.tsx`, `showcase/native/src/Dashboard.stories.tsx`, `showcase/shared/dashboard-pattern.ts`, `showcase/native/src/pattern-status.tsx`, `packages/react/src/styles.css`(`.hjm-statistic`, `.hjm-text`)
 - 스토리북: `배포/화면/콘텐츠/대시보드`
 
@@ -24,7 +24,7 @@
 │ ① 머리                                                     │
 │   제목 Heading level3 · semanticLevel 1                    │
 │   소개 Text (Web as="p")                                   │  직계 요소 사이 spacing.xl 24
-│   [최근 7일] [9월] [8월]  ← 기간 선택                        │  ghost + selected, wrap gap sm 12
+│   [최근 7일] [9월] [8월]  ← 기간 선택                        │  SegmentedControl pills, 단일 선택
 │ ② "2026-09-01 — 2026-09-30"  (상태 알림)                    │
 │ (오류면 여기 Notice danger + [다시 시도])                    │
 │ ┌ ③ 요약 Surface padding lg 20 ─────────────────────────┐ │
@@ -52,7 +52,7 @@
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
 | 바깥 틀 | Web `main` > [Container](../components/container.md) `size="content"` `gutter` > Stack `gap="xl"`, 문서 스크롤 · Native `ScrollView` > Container `size="content"` `gutter` > Stack `gap="xl"` | 화면 전체, 세로 스크롤 하나 | 좌우 Container gutter: 폭 < 600 `compact` 16, 이상 `regular` 20([화면 여백](../tokens/layout.md)). Native ScrollView 위아래 `spacing.lg` 20(`paddingVertical`). 직계 요소 사이 `spacing.xl` 24. 위 안전 영역은 내비게이션 헤더·[TopBar](../components/top-bar.md) `safeAreaTop`이 맡고, 헤더 없이 띄울 때만 제품이 감싼다. 아래 고정 영역이 없어 inset은 스크롤로 지나간다. 입력이 없어 키보드 처리는 없다 |
-| ① 머리 | [Heading](../components/heading.md) `level="level3"` `semanticLevel={1}` · Text(소개) · Stack `axis="inline" wrap gap="sm"` > Button `ghost` | 맨 위 | 제목 24/32 heavy. 버튼 높이 44(`control.buttonHeight.medium`), 사이 `spacing.sm` 12 |
+| ① 머리 | [Heading](../components/heading.md) `level="level3"` `semanticLevel={1}` · Text(소개) · SegmentedControl `presentation="pills"` | 맨 위 | 제목 24/32 heavy. 버튼 높이 44(`control.buttonHeight.medium`), 사이 `spacing.sm` 12 |
 | ② 기간 표시 | Text `role="status"`(Web) · `accessibilityLiveRegion="polite"` Text(Native) | ① 아래 | 위아래 24 |
 | ③ 요약 | Surface `padding="lg"` > Stack `gap="lg"` > AnimatedStatistic ×3 | ② 아래 | 안쪽 `spacing.lg` 20, 수치 사이 20, 라벨-값 `spacing.xxs` 4 |
 | ④ 활동 | Text `emphasis="strong"` · Button `ghost` · ActivityHeatmap `view` | ③ 아래, 세 요소가 바깥 Stack 직계 | 요소 사이 24 |
@@ -78,9 +78,9 @@
 | 상태 | 화면 모습 | 행동 |
 | --- | --- | --- |
 | 기본 | ①~⑤ 모두. AnimatedStatistic이 이전 값에서 새 값으로 굴러간다(모션 줄이기면 즉시) | 기간 선택·보기 전환 |
-| 로딩 | 스토리에 없음. ①② 그대로, ③ Surface 안에 수치 3개 모양의 [Skeleton](../components/skeleton.md)(라벨 `shape="text"` 40% + 값 `shape="block"` 30%, 사이 `spacing.xxs` 4), ④⑤는 그리지 않는다. 로딩 사실은 영역 단위로 한 번 알린다(Web 감싼 Surface `aria-busy`·`aria-label`, Native 첫 Skeleton `accessibilityLabel`) | 기간 선택은 그대로 둔다 |
-| 빈 | ③ 수치는 0, ④⑤ 자리에 EmptyState(제목·설명) | [9월 보기] 같은 기록 있는 기간으로 |
-| 오류 | 스토리에 없음. ② 바로 아래 [Notice](../components/notice.md) `tone="danger"`(Native `announcement="assertive"` — 기본 `none`). 문구는 원인별 키(`errorKey`: 네트워크 `dashboard.error.network`, 서버 `dashboard.error.server`). 이전 데이터가 있으면 ③④⑤를 유지하고, 첫 로딩 실패면 ③④⑤를 그리지 않는다. 다시 시도가 또 실패하면 같은 Notice를 같은 자리에 두고 버튼 `loading`만 푼다(Notice를 쌓지 않는다) | Notice `action` 다시 시도 1개(`tone="secondary" size="small"`, 요청 중 `loading`) |
+| 로딩 | 동기 스토리에 없음. 제품 최초 조회는 ScreenLayout `state=loading`으로 본문 중앙 spinner 하나를 표시하고 라벨은 접근성 이름으로 전달한다. 재조회는 기존 본문을 유지한다 | 기간 선택 유지, 같은 요청 중복 실행 방지 |
+| 빈 | 동기 스토리는 수치 0과 인라인 EmptyState를 시연한다. 제품의 전체 빈 상태는 ScreenLayout `state=empty`로 본문 중앙에 두고 기간 선택은 actions에 유지한다 | 기록 있는 기간으로 |
+| 오류 | 스토리에 없음. ② 바로 아래 [Notice](../components/notice.md) `tone="danger"`(Native `announcement="assertive"` — 기본 `none`). 문구는 원인별 키(`errorKey`: 네트워크 `dashboard.error.network`, 서버 `dashboard.error.server`). 이전 데이터가 있으면 ③④⑤를 유지하고, 첫 로딩 실패면 ScreenLayout `state=error`와 `stateAction`으로 본문 중앙에 오류·재시도를 함께 둔다. 다시 시도가 또 실패하면 같은 Notice를 같은 자리에 두고 버튼 `loading`만 푼다(Notice를 쌓지 않는다) | Notice `action` 다시 시도 1개(`tone="secondary" size="small"`, 요청 중 `loading`) |
 | 기간 변경 | ② 기간 문구가 바뀌어 읽히고 ③④⑤가 같이 바뀐다 | — |
 | 날짜 값 모름 | 히트맵 값 `null`은 `formatDay`로 "확인되지 않음"이라 읽힌다. 0과 구분해 넘긴다 | — |
 
@@ -99,125 +99,67 @@
 | [ActivityHeatmap](../components/activity-heatmap.md) | ④ 날짜별 활동 |
 | [List](../components/list.md) · [ListRow](../components/list-row.md) | ⑤ 기록 |
 | [EmptyState](../components/empty-state.md) | 기록 없음 |
-| [Skeleton](../components/skeleton.md) | 로딩 |
+| [Skeleton](../components/skeleton.md) | 로딩 | 동기 스토리에 없음. 제품 최초 조회는 ScreenLayout `state=loading`으로 본문 중앙 spinner 하나를 표시하고 라벨은 접근성 이름으로 전달한다. 재조회는 기존 본문을 유지한다 | 기간 선택 유지, 같은 요청 중복 실행 방지 |
 | [Notice](../components/notice.md) | 오류 |
 | [화면 여백과 너비](../tokens/layout.md) | gutter·최대 폭 |
 | [간격](../tokens/spacing.md) | `spacing.xxs`·`sm`·`lg`·`xl` |
 
 ## 코드 골격
 
-수치 라벨·기간 목록·`formatDay` 문구는 제품 소유다. 상태마다 다른 문구는 키를 문자열로 조립하지 않고
-상태→키 상수 표로 고른다. 그래야 상태 표와 키 목록이 한 곳에서 맞는다. 아래 두 예는 설치 버전 타입으로
-검사했다(`period`·`data`·`error` 등 상태 값은 제품이 둔다).
+완성된 동기 fixture의 배치·기간 계산 원본은 `showcase/web/src/patterns/Dashboard.stories.tsx`,
+`showcase/native/src/Dashboard.stories.tsx`, `showcase/shared/dashboard-pattern.ts`다.
+이 스토리는 공개 DashboardScreen API가 아니며 서버 최초 조회·재조회 실패를 구현한 증거도 아니다.
+제품은 아래 공개 ScreenLayout의 상태 경로를 사용하고 기존 요약·활동·목록을 children으로 둔다.
+`periodControls`는 위에서 설명한 SegmentedControl, `summaryAndRecords`는 같은 기간 데이터로 만든 세 영역이다.
 
 ```tsx
 // Web
-import { Container, Stack, Surface, Text } from "@hjmds/react/layout";
-import { Heading } from "@hjmds/react/heading";
+import { ScreenLayout } from "@hjmds/react/screens";
 import { Button } from "@hjmds/react/actions";
-import { SegmentedControl } from "@hjmds/react/selection";
-import { EmptyState, Notice, Skeleton } from "@hjmds/react/feedback";
-import { AnimatedStatistic } from "@hjmds/react/statistic-motion";
-import { ActivityHeatmap } from "@hjmds/react/activity-heatmap";
-import { List, ListRow } from "@hjmds/react/display";
-import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
-
-type Period = "week" | "month" | "lastMonth";
-type LoadError = "network" | "server";
-const periods: readonly Period[] = ["week", "month", "lastMonth"];
-const periodKey = { week: "dashboard.period.week", month: "dashboard.period.month", lastMonth: "dashboard.period.lastMonth" } as const satisfies Record<Period, string>;
-const errorKey = { network: "dashboard.error.network", server: "dashboard.error.server" } as const satisfies Record<LoadError, string>;
-// 라벨은 지금 보기가 아니라 바뀔 보기를 말한다.
-const viewToggleKey = { grid: "dashboard.showList", list: "dashboard.showGrid" } as const;
-const gutter = resolveWindowClass(window.innerWidth) === "compact" ? "compact" : "regular";
-
-<main><Container size="content" gutter={gutter}><Stack gap="xl">
-  <Heading level="level3" semanticLevel={1}>{t("dashboard.title")}</Heading>
-  <Text as="p">{t("dashboard.intro")}</Text>
-  <SegmentedControl label={t("dashboard.period")} presentation="pills"
-      items={periods.map(id => ({ value: id, label: t(periodKey[id]) }))} value={period} onValueChange={setPeriod} />
-  <Text role="status">{t("dashboard.range", range)}</Text>
-  {error ? <Notice tone="danger" title={t(errorKey[error])}
-    action={<Button tone="secondary" size="small" loading={retrying} onClick={retry}>{t("common.retry")}</Button>} /> : null}
-  {loading && !data ? (
-    <Surface padding="lg" aria-busy="true" aria-label={t("dashboard.loading")}><Stack gap="lg">
-      {[0, 1, 2].map(i => <Stack key={i} gap="xxs"><Skeleton shape="text" width="40%" /><Skeleton shape="block" width="30%" /></Stack>)}
-    </Stack></Surface>
-  ) : data ? <>
-    <Surface padding="lg"><Stack gap="lg">
-      <AnimatedStatistic descriptor={{ id: "count", label: t("dashboard.count") }} value={data.count} locale={locale} />
-      <AnimatedStatistic descriptor={{ id: "days", label: t("dashboard.activeDays") }} value={data.activeDays} locale={locale} />
-      <AnimatedStatistic descriptor={{ id: "minutes", label: t("dashboard.minutes") }} value={data.minutes} locale={locale} />
-    </Stack></Surface>
-    {data.count ? <>
-      <Text emphasis="strong">{t("dashboard.activity")}</Text>
-      <Button tone="ghost" onClick={() => setList(v => !v)}>{t(viewToggleKey[list ? "list" : "grid"])}</Button>
-      <ActivityHeatmap descriptor={data.heatmap} label={t("dashboard.activity")} formatDay={formatDay} view={list ? "list" : "grid"} />
-      <List label={t("dashboard.records")}>{data.records.map(r =>
-        <ListRow key={r.id} title={r.title} description={t("dashboard.recordMeta", { date: r.date, minutes: r.minutes })} />)}</List>
-    </> : <EmptyState title={t("dashboard.empty.title")} description={t("dashboard.empty.body")}
-        action={<Button onClick={() => setPeriod("month")}>{t("dashboard.reset")}</Button>} />}
-  </> : null}
-</Stack></Container></main>
+import { Notice } from "@hjmds/react/feedback";
+
+const initial = data === undefined;
+<ScreenLayout title={t("dashboard.title")} actions={periodControls}
+  state={initial
+    ? error ? { kind: "error", title: t(errorKey[error]) } : { kind: "loading", title: t("dashboard.loading") }
+    : data.count === 0 ? { kind: "empty", title: t("dashboard.empty.title") } : { kind: "ready" }}
+  stateAction={initial && error ? <Button loading={retrying} onClick={retry}>{t("common.retry")}</Button>
+    : !initial && data.count === 0 ? <Button onClick={() => setPeriod("month")}>{t("dashboard.reset")}</Button> : null}
+  notice={!initial && error ? <Notice tone="danger" title={t(errorKey[error])}
+    action={<Button tone="secondary" loading={retrying} onClick={retry}>{t("common.retry")}</Button>} /> : null}>
+  {summaryAndRecords}
+</ScreenLayout>
 ```
 
 ```tsx
 // Native
-import { ScrollView, useWindowDimensions } from "react-native";
-import { spacing } from "@hjmds/design-contracts/foundations";
-import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
-import { Container, Stack, Surface, Text } from "@hjmds/react-native/primitives";
-import { Heading } from "@hjmds/react-native/heading";
+import { ScreenLayout } from "@hjmds/react-native/screens";
 import { Button } from "@hjmds/react-native/actions";
-import { SegmentedControl } from "@hjmds/react-native/inputs";
-import { EmptyState, Notice, Skeleton } from "@hjmds/react-native/feedback";
-import { AnimatedStatistic } from "@hjmds/react-native/statistic-motion";
-import { ActivityHeatmap } from "@hjmds/react-native/activity-heatmap";
-import { List, ListRow } from "@hjmds/react-native/data-display";
-
-// periods·periodKey·errorKey·viewToggleKey는 Web과 같다.
-const { width } = useWindowDimensions();
-const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
-
-<ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
-  <Container size="content" gutter={gutter}><Stack gap="xl">
-    <Heading level="level3" semanticLevel={1}>{t("dashboard.title")}</Heading>
-    <Text>{t("dashboard.intro")}</Text>
-    <SegmentedControl label={t("dashboard.period")} presentation="pills"
-      items={periods.map(id => ({ value: id, label: t(periodKey[id]) }))} value={period} onValueChange={setPeriod} />
-    <Text accessibilityLiveRegion="polite">{t("dashboard.range", range)}</Text>
-    {error ? <Notice tone="danger" announcement="assertive" title={t(errorKey[error])}
-      action={<Button tone="secondary" size="small" loading={retrying} onPress={retry}>{t("common.retry")}</Button>} /> : null}
-    {loading && !data ? (
-      <Surface padding="lg"><Stack gap="lg">
-        {[0, 1, 2].map(i => <Stack key={i} gap="xxs">
-          <Skeleton shape="text" width="40%" {...(i === 0 ? { accessibilityLabel: t("dashboard.loading") } : {})} />
-          <Skeleton shape="block" width="30%" />
-        </Stack>)}
-      </Stack></Surface>
-    ) : data ? <>
-      <Surface padding="lg"><Stack gap="lg">
-        <AnimatedStatistic descriptor={{ id: "count", label: t("dashboard.count") }} value={data.count} locale={locale} />
-        {/* activeDays · minutes — Web과 같다 */}
-      </Stack></Surface>
-      {data.count ? <>
-        <Text emphasis="strong">{t("dashboard.activity")}</Text>
-        <Button tone="ghost" onPress={() => setList(v => !v)}>{t(viewToggleKey[list ? "list" : "grid"])}</Button>
-        <ActivityHeatmap descriptor={data.heatmap} label={t("dashboard.activity")} formatDay={formatDay} view={list ? "list" : "grid"} />
-        <List label={t("dashboard.records")}>{data.records.map(r =>
-          <ListRow key={r.id} title={r.title} description={t("dashboard.recordMeta", { date: r.date, minutes: r.minutes })} />)}</List>
-      </> : <EmptyState title={t("dashboard.empty.title")} description={t("dashboard.empty.body")}
-          action={<Button onPress={() => setPeriod("month")}>{t("dashboard.reset")}</Button>} />}
-    </> : null}
-  </Stack></Container>
-</ScrollView>
+import { Notice } from "@hjmds/react-native/feedback";
+
+const initial = data === undefined;
+<ScreenLayout title={t("dashboard.title")} actions={periodControls}
+  state={initial
+    ? error ? { kind: "error", title: t(errorKey[error]) } : { kind: "loading", title: t("dashboard.loading") }
+    : data.count === 0 ? { kind: "empty", title: t("dashboard.empty.title") } : { kind: "ready" }}
+  stateAction={initial && error ? <Button loading={retrying} onPress={retry}>{t("common.retry")}</Button>
+    : !initial && data.count === 0 ? <Button onPress={() => setPeriod("month")}>{t("dashboard.reset")}</Button> : null}
+  notice={!initial && error ? <Notice tone="danger" announcement="assertive" title={t(errorKey[error])}
+    action={<Button tone="secondary" loading={retrying} onPress={retry}>{t("common.retry")}</Button>} /> : null}>
+  {summaryAndRecords}
+</ScreenLayout>
 ```
 
+최초 로딩·실패·빈 상태는 host가 확보한 본문 영역의 가로·세로 중앙에 둔다. 별도 ScrollView로
+ScreenLayout을 감싸지 않는다. 재조회는 기존 데이터와 기간 설명을 유지하고 `ready` 상태에서
+해당 재조회 행동만 pending으로 표시한다. 새 기간 요청 중 이전 기간 자료를 새 기간 자료처럼 표시하지 않는다.
+요청 취소 또는 request key 대조로 오래된 응답이 최신 선택을 덮지 못하게 한다.
+
 ## 큰 글자·다크·좁은 폭
 
 | 조건 | 바뀌는 것 |
 | --- | --- |
-| 큰 글자(`textScale` 2) | 기간 선택은 큰 글자에서 세로로 쌓인다. Statistic 값은 Web에서 `type.title` 크기 × 글자 배율로 커지고 `overflow-wrap: anywhere`로 꺾인다. 긴 제목은 Heading이 줄바꿈한다 |
+| 큰 글자(`textScale` 2) | 기간 선택 pills는 가로 순서를 유지하며 공간이 부족하면 감긴다. Statistic 값은 Web에서 `type.title` 크기 × 글자 배율로 커지고 `overflow-wrap: anywhere`로 꺾인다. 긴 제목은 Heading이 줄바꿈한다 |
 | 다크 | 테마 토큰만 쓰므로 바꿀 것이 없다 |
 | 좁은 폭 | 구조 동일, gutter가 `compact` 16으로 준다. ActivityHeatmap 격자가 좁으면 보기 전환으로 목록을 쓴다 |
 | 넓은 폭 Web | 한 열 유지, Container `content`가 1200으로 폭을 묶고 gutter `regular` 20 |
@@ -228,18 +170,19 @@ const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
 | --- | --- | --- |
 | 바깥 스크롤 | 문서 스크롤 | `ScrollView` 위아래 `spacing.lg` 20, 좌우는 안쪽 Container gutter |
 | 상단 안전 영역 | 브라우저 | 화면이 소유하지 않는다. 내비게이션 헤더 또는 [TopBar](../components/top-bar.md) `safeAreaTop`이 맡고, 헤더 없이 띄울 때만 제품이 감싼다 |
-| 기간 표시 알림 | `role="status"` | `accessibilityLiveRegion="polite"`(Android만), iOS는 제품이 직접 알림(함정 참고) |
-| 로딩 알림 | 감싼 영역 `aria-busy` + `aria-label`(Skeleton은 항상 `aria-hidden`) | 첫 Skeleton `accessibilityLabel` 하나 |
+| 기간 표시 알림 | `role="status"` | 공개 StatusText(Android live region + iOS 변경 알림) |
+| 로딩 알림 | ScreenLayout 본문 busy와 Spinner 접근성 이름 | ScreenLayout 내부 Spinner 접근성 이름 |
 | 오류 Notice 알림 | `tone="danger"`가 알림 영역 | `announcement="assertive"`를 명시(기본 `none`) |
 | EmptyState 기본 위아래 여백 | `spacing.xxl` 32(`styles.css`) | `spacing.xxxl` 40(`emptyStateRecipe.density.regular`) |
 
 ## 함정
 
 - ActivityHeatmap은 1~366일만 받는다(범위 밖이면 `RangeError`). 1년 넘는 기록은 제품이 기간을 나눈다.
-- 스토리의 `PatternStatus`는 showcase 전용이다. iOS 알림은 `AccessibilityInfo.announceForAccessibilityWithOptions(text, { queue: true })`로
-  제품이 두되, **기간 문구가 이전과 달라졌을 때만** 보내고 첫 렌더·같은 문구 재렌더·빈 문자열·앱이 active가 아닐 때(`AppState.currentState`)는
-  보내지 않는다(`showcase/native/src/pattern-status.tsx`).
+- 기간·결과 문구는 공개 [StatusText](../components/text.md#statustext)를 쓴다. iOS에서는 active 중 바뀐 비어 있지 않은 문구만 알리고, 최초 안내·동일 문구·배경 변경은 재생하지 않는다.
 - 구획 제목은 Heading으로 표시한다. 이전 Text heading 예제는 2026-10-06 제목 의미 구조를 맞추면서 수정했다.
   Text의 기본 `emphasis="regular"`가 굵기를 덮어 24px 보통 굵기로 나오고(`.hjm-text[data-emphasis="regular"]`), Native는 제목 단계가 없다.
   [Text](../components/text.md) 규칙대로 새 제품은 Heading `level3`·`semanticLevel={1}`(24/32 heavy)을 쓴다.
 - 예제는 양 플랫폼 모두 Container로 감싼다. 예제의 compact gutter 16과 제품이 폭에 따라 선택하는 regular gutter 20을 구분한다.
+
+
+2026-10-13 행동 검수에서 제거/복구 뒤 키보드 문맥 유실을 확인해 보강했다. Web 빈 기간 복구는 선택된 기간 컨트롤로 초점을 돌린다. 기간을 바꿔도 목록/격자 보기 선택은 유지한다.