sellmate-design-system-react 9.0.0-beta.35 → 9.0.0-beta.37

package/AGENTS.md

@@ -30,7 +30,7 @@
 | **입력 (폼)** | `SForm` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SRadioCard` `SRadioCardGroup` `SChip` `SChipInput` `SBarcodeInput` `SFilePicker` |
 | **날짜·시간** | `SCalendar` `SCalendarBoard`(한 달치 일정 판) `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `SDateRangePicker` `STimePicker` `STimeRangePicker` |
 | **표·목록** | `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SListItem` `SExpansionList` `SDraggableList` `SDraggableItem` `STree` |
-| **레이아웃** | `SLayout` `SGnb` `SGnbSystem` `SAccountListBox`(계정 행을 눌러 뜨는 계정 패널) `SPage`(제목 영역은 `header` prop) `SSectionHeaderCard` `SCard` `SDivider` `SSplitter` `SScrollArea` `SExpansionItem` |
+| **레이아웃** | `SLayout` `SGnb` `SGnbSystem` `SAccountListBox`(계정 행을 눌러 뜨는 계정 패널) `SPage` `SPageHeader`(페이지 제목 영역 — `SLayout` 안에서 `SPage` 앞에 둔다) `SSectionHeaderCard` `SCard` `SDivider` `SSplitter` `SScrollArea` `SExpansionItem` |
 | **내비게이션** | `STabs` `SPagination` `SStepper` |
 | **표시·상태** | `STag` `SBadge` `SIcon` `SImage` `SCallout` `SGuide` |
 | **진행·로딩** | `SLinearProgress` `SCircleProgress` `SLoadingContainer` `SLoadingModal` |
@@ -150,7 +150,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 | 층 | 무엇인가 | 컴포넌트 |
 | --- | --- | --- |
-| **셸** | 앱 전체 뼈대. 페이지가 바뀌어도 남는다 | `SLayout` `SGnb` `SGnbSystem`(GNB 맨 아래 판 · 전폭 상단바 오른쪽 끝) `SPage`(제목 영역은 `header` prop) |
+| **셸** | 앱 전체 뼈대. 페이지가 바뀌어도 남는다 | `SLayout` `SGnb` `SGnbSystem`(GNB 맨 아래 판 · 전폭 상단바 오른쪽 끝) `SPage` `SPageHeader`(`SLayout` 안에서 `SPage` 앞에 둔다) |
 | **블록** | `SPage` 의 직계 자식. 페이지를 세로로 쌓는 단위 | `SSectionHeaderCard` `SCard` `SForm` `SSplitter` `SScrollArea` `SCalendarBoard` `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SExpansionList` `SDraggableList` `STree` `SCallout` `STabs` `SStepper` `SPagination` `SDivider` |
 | **요소** | 블록 **안에** 놓이는 컨트롤. 혼자 페이지에 서지 않는다 | `SButton` `SGhostButton` `SDropdownButton` `SSystemActionButton` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SRadioCard` `SRadioCardGroup` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `SDateRangePicker` `STimePicker` `STimeRangePicker` `SCalendar` `SListItem` `SExpansionItem` `SDraggableItem` `SImage` `SLinearProgress` `SCircleProgress` |
 | **인라인** | 텍스트 흐름·셀·라벨 안에 섞인다. 혼자 블록이 되지 않는다 | `STag` `SBadge` `SIcon` `STextLink` `SChip` |
@@ -200,7 +200,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 블록 순서는 화면 종류와 무관하게 같다. **필요한 것만 남기되 순서를 바꾸지 않는다.**
 
 ```text
-1. 페이지 제목        `SPage` 의 `header` prop (+ 가이드·매뉴얼 링크는 slot. 액션 버튼은 오지 않는다 §4-2)
+1. 페이지 제목        `SPageHeader`  (SGnb 와 SPage 사이. 가이드·매뉴얼 링크는 slot, 액션 버튼은 오지 않는다 §4-2)
 2. 상시 안내          SCallout
 3. 필터               SKeyValueTable · SChipFilter (§3-7-11)
 4. 툴바               STableBar   (건수 요약 + 액션)
@@ -228,7 +228,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 | 층 (§2-0) | 역할 | 클래스 | 크기 |
 | --- | --- | --- | --- |
-| 셸 | 페이지 제목 (`SPage` 의 `header.title`) | `typo-heading-lg` | 18px |
+| 셸 | 페이지 제목 (`SPageHeader` 의 `title`) | `typo-heading-lg` | 18px |
 | 블록 | 섹션 제목 | `typo-heading-sm` | 14px |
 | 블록 내부 | 하위 제목 (섹션 안을 더 나눌 때) | `typo-heading-xs` | 12px |
 | — | 본문 | `typo-body-sm-default` | 12px |
@@ -236,7 +236,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 페이지 제목만 18px 로 크게 두고 그 아래는 14 / 12 로 촘촘하게 간다. 중간 크기(16px)는 기본 골격에서 쓰지 않는다.
 
-- **페이지·섹션 제목의 타이포를 직접 주지 않는다.** `SPage` 의 `header.title`, `SSectionHeaderCard` 의 `header.title` 이 이미 넣는다 — 그 위에 `typo-heading-lg`/`typo-heading-sm` 을 또 씌우지 않는다.
+- **페이지·섹션 제목의 타이포를 직접 주지 않는다.** `SPageHeader` 의 `title`, `SSectionHeaderCard` 의 `header.title` 이 이미 넣는다 — 그 위에 `typo-heading-lg`/`typo-heading-sm` 을 또 씌우지 않는다.
 - **하위 제목이 필요하면 먼저 섹션을 나눌 수 없는지 본다.** 한 섹션 안에서 제목이 두 단으로 갈린다는 것은 대개 섹션이 둘이라는 뜻이다 (§3-7-8).
 - 본문 안에서 한 단어를 강조할 때는 `typo-body-sm-medium` 을 쓴다. `typo-body-sm-bold` 는 제목 성격의 짧은 라벨에만 쓴다. <!-- TODO(디자인): 강조 굵기 기준 확정 -->
 
@@ -539,7 +539,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 앱 상단바 오른쪽 끝에 알림 벨·계정 이름을 둔다 | `SGnbSystem` (`SGnb` 의 `system` 슬롯 — 직접 만들지 않는다) | §4-1 |
 | 계정 이름을 눌러 이메일·권한·계정 설정·언어 변경·로그아웃을 띄운다 | `SAccountListBox` (`SGnbSystem` 의 `account.listBox` 로 넘긴다 — 직접 띄우지 않는다) | §4-1 |
 | 페이지 본문을 담는다 (패딩·스크롤) | `SPage` | §4-1 |
-| 페이지 제목(+ 서브 텍스트·뒤로가기·우측 슬롯)을 만든다 | `SPage` 의 `header` prop | §4-1 |
+| 페이지 제목(+ 서브 텍스트·뒤로가기·우측 슬롯)을 만든다 | `SPageHeader` (`SLayout` 안에서 `SPage` 앞에 둔다) | §4-1 |
 | 제목 있는 섹션으로 묶는다 | `SSectionHeaderCard` | §3-7-8 |
 | 제목 없이 흰 면으로만 묶는다 | `SCard` | §3-7-8 |
 | 가로선으로 끊는다 | `SDivider` | §3-6 |
@@ -615,6 +615,14 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 특정 UI 요소에 대한 **온보딩·기능 안내** | `SGuide` |
 | 로딩 중 화면 잠금 | `SLoadingModal` / 영역 로딩은 `SLoadingContainer` |
 
+**`SCallout` 의 `type` 은 놓이는 면이 정한다.** 안내의 강도가 아니라 배경 대비의 문제다.
+
+| `type` | 언제 |
+| --- | --- |
+| `default` | 흰 면 위 (`SPage background="frame"`) — 옅은 회색 면이라 페이지와 구분된다 |
+| `white` | 회색 면 위 (`background="neutral"`·`"screen"`) — 그 위에서는 `default` 가 배경에 묻힌다 |
+| `danger` | 경고. 좌측에 "주의사항" 타이틀이 붙으므로 단순 안내에는 쓰지 않는다 |
+
 ### 3-3. 플로팅/오버레이류
 
 | 상황 | 사용 |
@@ -1576,7 +1584,7 @@ const [selectedId, setSelectedId] = useState<string>();
 ### 4-1. 앱 셸 (모든 페이지 공통)
 
 ```tsx
-import { SLayout, SGnb, SPage, type SGnbMenuItem, type SPageHeaderProps } from 'sellmate-design-system-react';
+import { SLayout, SGnb, SPage, SPageHeader, type SGnbMenuItem, type SPageHeaderProps } from 'sellmate-design-system-react';
 
 const MENU: SGnbMenuItem[] = [
   { label: '주문', value: 'orders', icon: 'bill' },
@@ -1598,16 +1606,13 @@ export default function AppShell({
     <SLayout type="box" header="fix">
       {/* type/header/folded 는 SLayout 에만 준다 — SGnb 는 context 에서 읽는다 */}
       <SGnb items={MENU} value={current} onValueChange={navigate} logo={<Logo />} />
+      {/* 페이지 제목은 SPage 앞에 형제로 둔다 — SLayout 이 헤더부터 뒤를 한 열로 묶는다.
+          header 는 페이지마다 달라 AppShell 이 그대로 받아 넘긴다 — 여기서 만들지 않는다 */}
+      {header && <SPageHeader {...header} />}
       {/* 콘텐츠 패딩은 SPage 가 토큰으로 넣는다 — p-sd-* 로 덮어쓰지 않는다 */}
       {/* 높이 모드는 페이지가 정한다 — 대부분 contentHeight="fill" 이다 (§2-2) */}
       {/* 스크롤 끝 여백도 SPage 가 넣는다. 페이지가 실제로 스크롤되는 화면에서만 켠다 */}
-      {/* header 는 페이지마다 달라 AppShell 이 그대로 받아 넘긴다 — 페이지 제목은 여기서 만들지 않는다 */}
-      <SPage
-        background="frame"
-        scrollEndSpacing={scrollEndSpacing}
-        contentHeight={contentHeight}
-        header={header}
-      >
+      <SPage background="frame" scrollEndSpacing={scrollEndSpacing} contentHeight={contentHeight}>
         {children}
       </SPage>
     </SLayout>
@@ -1615,14 +1620,38 @@ export default function AppShell({
 }
 ```
 
-**페이지는 `AppShell` 을 직접 호출하며 자기 `header` 를 넘긴다** — SPage 는 셸 안에 하나뿐이므로, 페이지 제목이 페이지마다 다르다는 사실은 이렇게 프레임 컴포넌트를 통해 흘려보낸다(§4-2·§4-3·§4-4 참고).
+**페이지는 `AppShell` 을 직접 호출하며 자기 `header` 를 넘긴다** — 셸은 앱에 하나뿐이므로, 페이지 제목이 페이지마다 다르다는 사실은 이렇게 프레임 컴포넌트를 통해 흘려보낸다(§4-2·§4-3·§4-4 참고).
+
+**자식 순서는 `SGnb` → `SPageHeader` → `SPage` 다.** `SLayout` 은 `SPageHeader` 자식을 보면 **그 자식부터 뒤를** 하나의 페이지 열로 묶어 헤더를 페이지 위에 고정한다 — 스크롤도 페이지 패딩도 그 아래 `SPage` 안에서만 일어난다. 그래서 순서가 규칙이다: 헤더를 `SGnb` 앞에 두면 GNB 까지 페이지 열로 딸려 들어가고, `SPage` 의 `children` 안에 넣으면 본문 패딩 안으로 들어가 스크롤과 함께 밀려 올라간다.
+
+**`scrolled` 를 직접 주지 않는다.** plain 헤더의 그림자는 같은 열의 `SPage` 가 올린 스크롤 상태로 켜진다 — 손으로 준 값은 그 자동 동작을 덮어써 스크롤과 어긋난 그림자를 남긴다.
 
-**페이지 헤더(`header`) 사용 규칙 — 이 앱에서는 값이 아니라 값의 일관성이 규칙이다.**
+**페이지 헤더 사용 규칙 — 이 앱에서는 값이 아니라 값의 일관성이 규칙이다.**
 
-- **`fix` 는 앱 전체에서 하나로 고정한다.** 어떤 페이지는 `fix: true`(바), 다른 페이지는 `fix: false`(투명) 로 섞어 쓰지 않는다. 프로젝트에서 하나를 고르면(예: 전부 `fix: true`) 모든 `header` 가 그 값을 쓴다.
+- **`fix` 는 앱 전체에서 하나로 고정한다.** 어떤 페이지는 `fix`(높이 고정 바), 다른 페이지는 기본형으로 섞어 쓰지 않는다. 프로젝트에서 하나를 고르면(예: 전부 `fix`) 모든 페이지 헤더가 그 값을 쓴다.
 - **`slot`·`onBack` 도 페이지 성격이 실제로 다른 경우가 아니면 있는 대로 통일한다.** "목록 페이지엔 없고 상세·등록 페이지엔 있다"처럼 화면 종류에 따라 갈리는 것은 허용되지만, 같은 종류의 화면끼리는 임의로 넣었다 뺐다 하지 않는다.
 - **`slot` 은 `ReactNode` 를 그대로 받지만, 원칙은 `size="sm"` 버튼 위주로만 채운다.** `STextLink`·복잡한 커스텀 마크업을 슬롯에 넣지 않는다 — 그 이상이 필요하면 페이지 헤더가 아니라 §4-2 의 `STableBar` 처럼 본문 쪽 액션 자리를 쓴다.
 
+**셸 밖의 단독 화면(로그인·온보딩 등)에서도 같은 제목 영역을 쓸 수 있다.** 이때는 페이지 열이 없으므로 `scrolled` 가 앱 몫이 된다.
+
+```tsx
+import { SPageHeader } from 'sellmate-design-system-react';
+
+const [scrolled, setScrolled] = useState(false);
+
+{/* 헤더는 자기 흰 면을 스스로 칠한다 — 감싸는 쪽은 본문이 놓일 면만 정하면 된다 */}
+<div className="flex h-full min-h-0 flex-col bg-[var(--sys-color-bg-frame)]">
+  <SPageHeader title="상품 목록" subText="판매 중인 상품을 관리합니다." scrolled={scrolled} />
+  {/* 스크롤을 앱이 쥐므로 scrolled 도 앱이 넣는다 — 패딩은 SPage 가 없으니 여기서 준다 */}
+  <div
+    className="min-h-0 flex-1 overflow-auto p-sd-16"
+    onScroll={e => setScrolled(e.currentTarget.scrollTop > 0)}
+  >
+    …본문…
+  </div>
+</div>;
+```
+
 **GNB 폭을 사용자가 조절하게 하려면 `SGnb` 에 `resizable` 을 준다.** 메뉴 오른쪽 경계가 조절선이 되고, 레일 폭은 고정된 채 메뉴 컬럼만 늘고 준다. 범위는 컴포넌트가 정하므로 숫자를 직접 주지 않는다.
 
 ```tsx

package/dist/components/SCallout/README.md

@@ -8,7 +8,7 @@
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `type?` | `SCalloutType` | `'default'` | 콜아웃 타입 (색상·아이콘·타이틀 결정) |
+| `type?` | `SCalloutType` | `'default'` | 콜아웃 타입 (색상·아이콘·타이틀 결정). - `default` — 옅은 회색 면. 흰 페이지(`background="frame"`) 위의 기본 안내. - `white` — 같은 안내인데 배경만 흰 면. 회색 면(`neutral`·`screen`) 위에서 default 가 묻힐 때. - `danger` — 좌측에 주의사항 타이틀이 붙는 경고. |
 | `message?` | `SCalloutMessage[]` | `[]` | 표시할 메시지 목록 (배열 중첩으로 depth 표현). 각 문자열은 인라인 HTML(`<b>`, `<a>` 등)을 허용하며 sanitizeInlineHtml 로 살균 후 렌더된다. |
 | `children?` | `ReactNode` | — | message 대신 직접 본문을 넣을 때 |
 | `className?` | `string` | — |  |
@@ -19,7 +19,7 @@
 ### SCalloutType
 
 ```ts
-export type SCalloutType = 'default' | 'danger';
+export type SCalloutType = 'default' | 'danger' | 'white';
 ```
 
 ### SCalloutMessage

package/dist/components/SCallout/SCallout.d.ts

@@ -1,9 +1,14 @@
 import { type CSSProperties, type ReactNode } from 'react';
-export type SCalloutType = 'default' | 'danger';
+export type SCalloutType = 'default' | 'danger' | 'white';
 /** 중첩 메시지: 문자열 또는 (한 단계 더 들어간) 문자열 배열 */
 export type SCalloutMessage = string | SCalloutMessage[];
 export interface SCalloutProps {
-    /** 콜아웃 타입 (색상·아이콘·타이틀 결정) */
+    /**
+     * 콜아웃 타입 (색상·아이콘·타이틀 결정).
+     * - `default` — 옅은 회색 면. 흰 페이지(`background="frame"`) 위의 기본 안내.
+     * - `white` — 같은 안내인데 배경만 흰 면. 회색 면(`neutral`·`screen`) 위에서 default 가 묻힐 때.
+     * - `danger` — 좌측에 주의사항 타이틀이 붙는 경고.
+     */
     type?: SCalloutType;
     /**
      * 표시할 메시지 목록 (배열 중첩으로 depth 표현).
@@ -17,8 +22,8 @@ export interface SCalloutProps {
 }
 /**
  * SCallout — sd-callout 포팅.
- * default/danger 타입, 중첩 리스트(불릿은 span으로 렌더), danger는 좌측 타이틀 표시.
- * 색상은 `--cmp-callout-*` 토큰 참조.
+ * default/white/danger 타입, 중첩 리스트(불릿은 span으로 렌더), danger는 좌측 타이틀 표시.
+ * 색상은 `--cmp-callout-*` 토큰 참조(white 만 예외 — SURFACE 주석 참고).
  * message 각 항목은 sanitizeInlineHtml 로 살균한 뒤 innerHTML 로 렌더한다 (원본 sd-callout 과 동일).
  */
 export declare const SCallout: import("react").ForwardRefExoticComponent<SCalloutProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/SLayout/README.md

@@ -43,10 +43,15 @@ export type SLayoutHeader = SGnbHeader;
  - [SGnb](../SGnb)
  - [SPage](../SPage)
 
+### Depends on
+
+- [SPage](../SPage)
+
 ### Graph
 
 ```mermaid
 graph TD;
+  SLayout --> SPage
   SGnb --> SLayout
   SPage --> SLayout
   style SLayout fill:#f9f,stroke:#333,stroke-width:4px

package/dist/components/SLayout/SLayout.d.ts

@@ -106,5 +106,9 @@ export interface SLayoutProps extends HTMLAttributes<HTMLDivElement> {
  *     "header header"  ← 전폭 상단바 (1행, 높이 = 등록된 topHeight)
  *     "nav    page"    ← 메뉴 열(등록된 columnWidth) | 페이지
  *   접으면 nav 열을 0 으로 접어 페이지가 전폭을 쓴다.
+ *
+ * 자식 순서는 `SGnb` → (선택) `SPageHeader` → `SPage` 다. `SPageHeader` 를 두면 **그 자식부터 뒤가**
+ * 하나의 페이지 열로 묶여(page-column.tsx) 헤더가 페이지 위에 고정되고, 그 아래에서만 스크롤이 일어난다.
+ * 헤더를 두지 않으면 아무것도 감싸지 않는다 — `SPage` 가 예전처럼 프레임의 자식으로 남는다.
  */
 export declare const SLayout: import("react").ForwardRefExoticComponent<SLayoutProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/SLoadingContainer/loading.d.ts

@@ -1,10 +1,26 @@
 /** 오버레이 뷰포트 — 스토어를 구독해 SLoadingContainer 를 렌더한다. 직접 배치도 가능. */
 export declare function SLoadingViewport(): import("react").JSX.Element;
 export declare const loading: {
-    /** 로딩 오버레이 표시 (메시지 갱신도 동일 호출) */
+    /**
+     * 로딩 오버레이 표시. 겹쳐 부르면 그만큼 쌓이고 **마지막 하나가 걷힐 때** 닫힌다.
+     * 반환값은 이 호출 하나만 걷는 함수다(두 번 불러도 한 번만 걷힌다) — `hide()` 대신 이것을
+     * 쓰면 짝이 어긋나지 않는다.
+     *
+     * ⚠️ 메시지만 바꾸려면 `update()` 를 쓴다. `show()` 를 다시 부르면 하나 더 쌓여
+     * `hide()` 한 번으로는 닫히지 않는다.
+     */
     show(options?: {
         message?: string;
+    }): () => void;
+    /** 표시 중인 메시지 갱신 — 쌓인 수는 그대로다 */
+    update(options: {
+        message?: string;
     }): void;
-    /** 로딩 오버레이 숨김 */
+    /** 가장 나중의 show 하나를 걷는다. 남은 것이 없을 때만 오버레이가 닫힌다 */
     hide(): void;
+    /**
+     * 쌓인 것을 모두 걷고 즉시 닫는다. 화면 전환·에러 복구처럼 진행 중이던 작업의 짝을 더는
+     * 맞출 수 없을 때만 쓴다 — 평소에는 `hide()` 나 `show()` 가 준 함수로 하나씩 걷는다.
+     */
+    hideAll(): void;
 };

package/dist/components/SPage/README.md

@@ -10,9 +10,9 @@
 |------|------|---------|-------------|
 | `title` | `string` | — | 타이틀 (필수) |
 | `subText?` | `string` | — | 서브 텍스트. fix=true 면 타이틀 오른쪽에, fix=false(기본) 면 타이틀 아래에 놓인다. |
-| `fix?` | `boolean` | `false` | true: 높이 56 고정 + 흰 배경 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄. false(기본): 최소 높이 66(상하 패딩 20/16 안에서 타이틀 한 줄 높이로 결정) + 투명 배경, 서브 텍스트가 타이틀 아래로 내려간다. |
+| `fix?` | `boolean` | `false` | true: 높이 56 고정 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄. false(기본): 최소 높이 66(상하 패딩 20/16 안에서 타이틀 한 줄 높이로 결정) + 구분선 없음, 서브 텍스트가 타이틀 아래로 내려간다. 배경은 두 베리에이션 모두 흰 면이다. |
 | `slot?` | `ReactNode` | — | 오른쪽 끝 커스텀 슬롯. 가이드 링크·액션 버튼 등 페이지마다 다른 것이 온다. |
-| `scrolled?` | `boolean` | `false` | `<SPage>` 가 스크롤 여부를 보고 자동으로 넣어준다 — 직접 주지 않는다. fix=false 일 때만 의미가 있다: 스크롤이 시작되면 그림자(floating)가 들어가 스크롤되는 콘텐츠 위에 뜬 것처럼 보인다. 배경은 그대로 페이지 배경을 따라간다 — 배경을 바꾸는 건 scrolled 가 아니라 fix 다. |
+| `scrolled?` | `boolean` | — | 아래 콘텐츠가 스크롤을 시작했는지. fix=false 일 때만 의미가 있다: 스크롤이 시작되면 그림자(floating)가 들어가 스크롤되는 콘텐츠 위에 뜬 것처럼 보인다. 배경은 흰 면 그대로다 — scrolled 가 더하는 것은 그림자뿐이다. `SLayout` 안에 놓았으면 **주지 않는다** — 같은 열의 `SPage` 가 자기 스크롤 상태를 올려 자동으로 들어온다. 스크롤 컨테이너를 앱이 직접 쥔 단독 배치에서만 `onScroll` 에서 준다. |
 
 #### Events
 
@@ -30,7 +30,6 @@
 | `scrollEndSpacing?` | `boolean` | `false` | 스크롤 끝 여백. 마지막 항목이 창 하단에 붙어 "여기서 끝"이 안 읽히는 것을 막는다. **기본은 꺼져 있다.** 페이지 스크롤 자체가 예외이기 때문이다 — 대부분의 화면은 본문이 창을 꽉 채우고 스크롤은 각 영역 안에서 일어난다. 여백을 조건 없이 붙이면 내용이 화면에 거의 딱 맞는 페이지까지 그 여백 때문에 스크롤되게 만든다. 페이지가 실제로 스크롤되는 화면(`contentHeight="auto"` + 내용이 창보다 김)에서만 켠다. 페이지네이션처럼 끝을 알려주는 것이 이미 있으면 켜지 않는다. |
 | `overlayScrollbar?` | `boolean` | `false` | true면 네이티브 스크롤바를 숨기고 SPage 위에 오버레이 스크롤바를 얹는다. 스크롤바가 레이아웃 폭을 차지하지 않아 내부 콘텐츠 폭이 줄어들지 않는다. |
 | `contentHeight?` | `SPageContentHeight` | `'auto'` | 본문 높이 모드. 기본은 `auto` — 콘텐츠가 흐르고 넘치면 페이지가 스크롤한다. `fill` 은 본문이 남은 높이를 정확히 채우고 페이지는 스크롤하지 않는다. 표가 자기 안에서 스크롤하고 페이지네이션이 하단에 고정되는 목록 화면용이다. 본문 루트에 `h-full` 이 먹으므로 `<div className="flex h-full min-h-0 flex-col">` + `<STable className="min-h-0 flex-1" />` 구성이 성립한다. `fill` 에서는 페이지가 스크롤하지 않으므로 `scrollEndSpacing` 이 무시된다. |
-| `header?` | `SPageHeaderProps` | — | 페이지 타이틀 영역(pageHeader 포팅). 주면 스크롤·페이지 패딩 밖으로 빼내 상단에 고정 배치한다. `children` 은 항상 본문이다 — header 유무와 무관하게 같은 자리에 같은 뜻으로 들어간다. |
 
 ## Types
 
@@ -72,6 +71,10 @@ export const PAGE_CONTENT_HEIGHTS = ['auto', 'fill'] as const;
 
 ## Dependencies
 
+### Used by
+
+ - [SLayout](../SLayout)
+
 ### Depends on
 
 - [SGhostButton](../SGhostButton)
@@ -83,5 +86,6 @@ export const PAGE_CONTENT_HEIGHTS = ['auto', 'fill'] as const;
 graph TD;
   SPage --> SGhostButton
   SPage --> SLayout
+  SLayout --> SPage
   style SPage fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/SPage/SPage.d.ts

@@ -1,6 +1,5 @@
 import { type HTMLAttributes } from 'react';
 import type { SPageBackground, SPageContentHeight } from './page.config';
-import { type SPageHeaderProps } from './SPageHeader';
 export interface SPageProps extends HTMLAttributes<HTMLElement> {
     /**
      * 페이지 배경 표면. frame=흰 콘텐츠 면, neutral=옅은 회색 면, screen=앱 바탕.
@@ -34,11 +33,6 @@ export interface SPageProps extends HTMLAttributes<HTMLElement> {
      * `fill` 에서는 페이지가 스크롤하지 않으므로 `scrollEndSpacing` 이 무시된다.
      */
     contentHeight?: SPageContentHeight;
-    /**
-     * 페이지 타이틀 영역(pageHeader 포팅). 주면 스크롤·페이지 패딩 밖으로 빼내 상단에 고정 배치한다.
-     * `children` 은 항상 본문이다 — header 유무와 무관하게 같은 자리에 같은 뜻으로 들어간다.
-     */
-    header?: SPageHeaderProps;
 }
 /**
  * SPage — SLayout 안에서 남은 공간을 채우는 스크롤 콘텐츠 영역.
@@ -50,8 +44,8 @@ export interface SPageProps extends HTMLAttributes<HTMLElement> {
  * - header="full": SLayout 이 깐 grid 의 "page" 영역 = 상단바 아래·메뉴 오른쪽 자리를 차지한다.
  *   좌표가 아니라 이름으로 잡으므로 프레임의 열·행 구성이 바뀌어도 여기는 그대로다.
  *
- * **`header` prop 을 주면** 스크롤·페이지 패딩 밖으로 빼내 상단에 고정 배치한다(fix 베리에이션이
- * 늘 보이는 높이 56 바가 되도록). 주지 않으면 이전과 동일하게 동작한다 — ref·className·style·
- * 나머지 속성이 전부 스크롤 영역 자체(`<main>`)에 그대로 붙는다.
+ * **페이지 제목은 `SLayout` 안에서 앞에 놓은 `SPageHeader` 가 만든다.** 그때 SLayout 이 헤더와
+ * 이 페이지를 한 열로 묶으므로(page-column.tsx) 여기서는 자리를 잡지 않고, 대신 자기 스크롤
+ * 상태를 그 열에 올린다 — 헤더가 그 값으로 floating 그림자를 켠다.
  */
 export declare const SPage: import("react").ForwardRefExoticComponent<SPageProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/SPage/SPageHeader.d.ts

@@ -5,9 +5,9 @@ export interface SPageHeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'slo
     /** 서브 텍스트. fix=true 면 타이틀 오른쪽에, fix=false(기본) 면 타이틀 아래에 놓인다. */
     subText?: string;
     /**
-     * true: 높이 56 고정 + 흰 배경 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄.
-     * false(기본): 최소 높이 66(상하 패딩 20/16 안에서 타이틀 한 줄 높이로 결정) + 투명 배경,
-     * 서브 텍스트가 타이틀 아래로 내려간다.
+     * true: 높이 56 고정 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄.
+     * false(기본): 최소 높이 66(상하 패딩 20/16 안에서 타이틀 한 줄 높이로 결정) + 구분선 없음,
+     * 서브 텍스트가 타이틀 아래로 내려간다. 배경은 두 베리에이션 모두 흰 면이다.
      */
     fix?: boolean;
     /** 뒤로가기 클릭 핸들러. 지정하면 왼쪽에 뒤로가기 버튼이 나타난다. */
@@ -15,18 +15,25 @@ export interface SPageHeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'slo
     /** 오른쪽 끝 커스텀 슬롯. 가이드 링크·액션 버튼 등 페이지마다 다른 것이 온다. */
     slot?: ReactNode;
     /**
-     * `<SPage>` 가 스크롤 여부를 보고 자동으로 넣어준다 — 직접 주지 않는다.
-     * fix=false 일 때만 의미가 있다: 스크롤이 시작되면 그림자(floating)가 들어가 스크롤되는
-     * 콘텐츠 위에 뜬 것처럼 보인다. 배경은 그대로 페이지 배경을 따라간다 — 배경을 바꾸는 건
-     * scrolled 가 아니라 fix 다.
-     * @nodemo SPage 가 스크롤 이벤트로 넣어준다 — 사용자가 직접 시연할 값이 아니다.
+     * 아래 콘텐츠가 스크롤을 시작했는지. fix=false 일 때만 의미가 있다: 스크롤이 시작되면
+     * 그림자(floating)가 들어가 스크롤되는 콘텐츠 위에 뜬 것처럼 보인다. 배경은 흰 면 그대로다 —
+     * scrolled 가 더하는 것은 그림자뿐이다.
+     *
+     * `SLayout` 안에 놓았으면 **주지 않는다** — 같은 열의 `SPage` 가 자기 스크롤 상태를 올려
+     * 자동으로 들어온다. 스크롤 컨테이너를 앱이 직접 쥔 단독 배치에서만 `onScroll` 에서 준다.
      */
     scrolled?: boolean;
 }
 /**
- * SPage 위에 얹는 페이지 타이틀 영역(pageHeader 포팅). `SPage` 가 `header` prop 값으로
- * 내부적으로만 렌더한다 — 직접 임포트해 쓰지 않는다 (SPage.tsx 참고).
- * fix 로 bar(높이 고정·흰 배경) / plain(투명·최소 높이) 두 베리에이션을 고른다.
+ * 페이지 타이틀 영역(pageHeader 포팅).
+ * fix 로 bar(높이 고정·하단 구분선) / plain(최소 높이) 두 베리에이션을 고른다 — 배경은 둘 다 흰 면이다.
  * 뒤로가기 버튼은 onBack 유무로 나타나며, 없을 때는 타이틀 쪽에 4px 여백이 대신 들어간다.
+ *
+ * **셸 안에서는 `SLayout` 의 자식으로 `SGnb` 와 `SPage` 사이에 놓는다.** SLayout 이 이 헤더부터
+ * 뒤를 하나의 페이지 열로 묶어(page-column.tsx) 스크롤·페이지 패딩 밖 상단에 고정하고,
+ * plain 일 때 `SPage` 가 올린 스크롤 상태를 열이 대신 물려준다.
+ *
+ * 셸 밖에 직접 놓을 수도 있다 — 스크롤 컨테이너를 앱이 쥐고 있는 단독 화면이다. 그때는 그림자만
+ * 앱 몫이 된다: 스크롤 컨테이너의 `onScroll` 에서 `scrolled` 를 넣어야 뜬다.
  */
 export declare const SPageHeader: import("react").ForwardRefExoticComponent<SPageHeaderProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/SPage/index.d.ts

@@ -1,3 +1,3 @@
 export { SPage, type SPageProps } from './SPage';
 export { PAGE_BACKGROUNDS, type SPageBackground, PAGE_CONTENT_HEIGHTS, type SPageContentHeight, } from './page.config';
-export { type SPageHeaderProps } from './SPageHeader';
+export { SPageHeader, type SPageHeaderProps } from './SPageHeader';

package/dist/components/SPage/page-column.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from 'react';
+/**
+ * 페이지 열이 `SPageHeader` 와 `SPage` 사이에서 중개하는 것.
+ *
+ * 둘은 형제라 서로를 볼 수 없는데, 헤더의 그림자는 페이지의 스크롤에서 나온다.
+ * 열이 그 사이에 서서 값을 옮긴다 — 아래(SPage)가 올리고 위(SPageHeader)가 읽는다.
+ */
+export interface SPageColumnValue {
+    /** 페이지가 스크롤을 시작했는지. `SPage` 가 올리고 `SPageHeader` 가 그림자로 쓴다. */
+    scrolled: boolean;
+    /** `SPage` 가 자기 스크롤 상태를 올린다. */
+    setScrolled: (scrolled: boolean) => void;
+}
+export declare const SPageColumnContext: import("react").Context<SPageColumnValue | null>;
+/**
+ * 페이지 열 — `SLayout` 이 `SPageHeader` 자식을 보면 그 자식부터 뒤를 이 열로 묶는다.
+ * 헤더는 위에 고정되고(자기 shrink-0) 그 아래 `SPage` 가 남은 높이를 먹는다.
+ *
+ * 자리(그리드 area)는 프레임이 정한다. 열 자체는 배경을 칠하지 않는다 — 헤더도 `SPage` 도
+ * 자기 면을 스스로 칠하므로 열의 배경은 어디에서도 드러나지 않는다.
+ */
+export declare function SPageColumn({ full, children }: {
+    full: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;