sellmate-design-system-react 9.0.0-beta.8 → 9.0.0-beta.80

package/dist/components/SPage/README.md

@@ -9,10 +9,10 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `title` | `string` | — | 타이틀 (필수) |
-| `subText?` | `string` | — | 서브 텍스트. fix=true 면 타이틀 오른쪽에, fix=false(기본) 면 타이틀 아래에 놓인다. |
-| `fix?` | `boolean` | `false` | true: 높이 56 고정 + 흰 배경 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄. false(기본): 최소 높이 66(상하 패딩 20/16 안에서 타이틀 한 줄 높이로 결정) + 투명 배경, 서브 텍스트가 타이틀 아래로 내려간다. |
+| `subText?` | `string` | — | 서브 텍스트. `bar` 면 타이틀 오른쪽에, `plain` 이면 타이틀 아래에 놓인다. |
+| `variant` | `SPageHeaderVariant` | — | 제목 영역의 모양 — **필수다.** - `plain`: 최소 높이(상하 패딩 안에서 타이틀 한 줄 높이로 결정) + 구분선 없음, 서브 텍스트가 타이틀 아래로 내려간다. - `bar`: 높이 고정 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄. 기본값을 두지 않는 이유는 이 값이 **앱 전체에서 하나로 고정돼야 하는 값**이기 때문이다. 기본값이 있으면 안 준 페이지만 조용히 다른 모양이 되어, 메뉴를 옮길 때 제목 줄의 높이와 구분선이 페이지마다 튄다. 셸을 한 번 감싸 쓰면(§4-1 AppShell) 지정하는 자리도 한 곳이다. 배경은 두 베리에이션 모두 흰 면이다. `SLayout` 의 `header`(`'fix' | 'full'`)와는 다른 축이다 — 그쪽은 상단바가 GNB 컬럼 안에 있는지 화면 전폭인지를 정한다. |
 | `slot?` | `ReactNode` | — | 오른쪽 끝 커스텀 슬롯. 가이드 링크·액션 버튼 등 페이지마다 다른 것이 온다. |
-| `scrolled?` | `boolean` | `false` | `<SPage>` 가 스크롤 여부를 보고 자동으로 넣어준다 — 직접 주지 않는다. fix=false 일 때만 의미가 있다: 스크롤이 시작되면 그림자(floating)가 들어가 스크롤되는 콘텐츠 위에 뜬 것처럼 보인다. 배경은 그대로 페이지 배경을 따라간다 — 배경을 바꾸는 건 scrolled 가 아니라 fix 다. |
+| `scrolled?` | `boolean` | — | 아래 콘텐츠가 스크롤을 시작했는지. `plain` 일 때만 의미가 있다: 스크롤이 시작되면 그림자(floating)가 들어가 스크롤되는 콘텐츠 위에 뜬 것처럼 보인다. 배경은 흰 면 그대로다 — scrolled 가 더하는 것은 그림자뿐이다. `SLayout` 안에 놓았으면 **주지 않는다** — 같은 열의 `SPage` 가 자기 스크롤 상태를 올려 자동으로 들어온다. 스크롤 컨테이너를 앱이 직접 쥔 단독 배치에서만 `onScroll` 에서 준다. |
 
 #### Events
 
@@ -27,13 +27,112 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `background?` | `SPageBackground` | `'frame'` | 페이지 배경 표면. frame=흰 콘텐츠 면, neutral=옅은 회색 면, screen=앱 바탕. 스크롤바 처리도 여기 묶여 있다 — 셋 다 구분선+트랙 배경이고, 트랙 색만 neutral 에서 흰색이 된다. |
-| `scrollEndSpacing?` | `boolean` | `true` | 스크롤 끝 여백. 마지막 항목이 창 하단에 붙어 "여기서 끝"이 안 읽히는 것을 막는다. 기본으로 켜져 있고, 페이지네이션처럼 끝을 알려주는 것이 이미 있으면 끈다(목록 페이지). |
+| `scrollEndSpacing?` | `boolean` | `false` | 스크롤 끝 여백. 마지막 항목이 창 하단에 붙어 "여기서 끝"이 안 읽히는 것을 막는다. **기본은 꺼져 있다.** 페이지 스크롤 자체가 예외이기 때문이다 — 대부분의 화면은 본문이 창을 꽉 채우고 스크롤은 각 영역 안에서 일어난다. 여백을 조건 없이 붙이면 내용이 화면에 거의 딱 맞는 페이지까지 그 여백 때문에 스크롤되게 만든다. 페이지가 실제로 스크롤되는 화면(`contentHeight="auto"` + 내용이 창보다 김)에서만 켠다. 페이지네이션처럼 끝을 알려주는 것이 이미 있으면 켜지 않는다. |
+| `padding?` | `SPagePadding` | `'default'` | 본문 안쪽 여백. 기본은 `default` — `--cmp-pageBody-padding-default` 를 사방에 넣는다. `none` 은 필터 바처럼 **가장자리까지 차는 블록이 맨 위에 서는** 화면용이다. 패딩을 끄면 그 아래 블록이 `p-[var(--cmp-pageBody-padding-default)]` 로 같은 토큰의 여백을 직접 잡는다 — `p-sd-*` 로 적으면 토큰이 바뀌어도 따라가지 않는다. 사방 패딩만 끄고 `scrollEndSpacing` 은 그대로다. (`SPopup`·`SSectionHeaderCard` 의 `padding="none"` 과 같은 관용구) |
 | `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 유무와 무관하게 같은 자리에 같은 뜻으로 들어간다. |
+| `contentWidth?` | `SPageContentWidth` | `'full'` | 본문 가로 폭 모드. 기본은 `full` — 창이 넓어지면 본문도 같이 넓어진다(반응형). `fixed`·`fixedCenter` 는 본문을 **레이아웃 최소 폭일 때의 폭**으로 고정한다. 최소 폭 기준으로 그린 시안이 넓은 모니터에서 늘어나 성기어지는 것을 막는 모드다. 남는 폭은 `fixed` 면 오른쪽에, `fixedCenter` 면 좌우로 나뉘어 페이지 배경으로 남는다. 고정 폭은 GNB 폭·접힘을 반영해 저절로 따라오므로 앱이 숫자를 쓸 일은 없다. 창이 최소 폭보다 좁아지면 세 모드가 모두 같다 — 남는 폭이 없어 규칙이 꺼지고, 모자란 몫을 지금까지처럼 이 영역이 가로 스크롤로 삼킨다. 같은 열에 `SPageHeader` 가 있으면 헤더도 같은 폭·정렬을 따른다(제목과 본문의 좌우 끝이 맞는다). `SLayout` 밖에서는 기준이 될 최소 폭이 없으므로 무시된다. |
+
+## Types
+
+### SPageHeaderVariant
+
+```ts
+export type SPageHeaderVariant = (typeof PAGE_HEADER_VARIANTS)[number];
+```
+
+### SPageBackground
+
+```ts
+export type SPageBackground = (typeof PAGE_BACKGROUNDS)[number];
+```
+
+### SPagePadding
+
+```ts
+export type SPagePadding = (typeof PAGE_PADDINGS)[number];
+```
+
+### SPageContentHeight
+
+```ts
+export type SPageContentHeight = (typeof PAGE_CONTENT_HEIGHTS)[number];
+```
+
+### SPageContentWidth
+
+```ts
+export type SPageContentWidth = (typeof PAGE_CONTENT_WIDTHS)[number];
+```
+
+### PAGE_HEADER_VARIANTS
+
+```ts
+/**
+ * 페이지 제목 영역의 모양 — 문서와 디자인이 부르는 이름을 그대로 쓴다.
+ * 기본값은 없다. 앱 전체에서 하나로 고정할 값이라 `SPageHeader` 가 매번 지정하게 한다.
+ * - plain: 최소 높이(상하 패딩 안에서 타이틀 한 줄), 구분선 없음, 서브 텍스트가 타이틀 아래
+ * - bar:   높이 고정 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄
+ */
+export const PAGE_HEADER_VARIANTS = ['plain', 'bar'] as const;
+```
+
+### PAGE_BACKGROUNDS
+
+```ts
+/**
+ * 페이지 배경 — 표면의 역할로 이름을 붙인다(리터럴 색이 아니다).
+ * - frame:   콘텐츠를 얹는 흰 표면 (sys.color.bg.frame)
+ * - neutral: 한 단계 눌러앉은 회색 표면 (sys.color.bg.neutralLight)
+ * - screen:  카드·패널이 떠 있는 앱 바탕 (sys.color.bg.screen)
+ */
+export const PAGE_BACKGROUNDS = ['frame', 'neutral', 'screen'] as const;
+```
+
+### PAGE_PADDINGS
+
+```ts
+/**
+ * 본문 안쪽 여백 모드.
+ * - default: SPage 가 --cmp-pageBody-padding-default 로 사방 패딩을 넣는다
+ * - none:    패딩을 끈다. 가장자리까지 차는 블록(필터 바 등)이 맨 위에 서고, 그 아래 블록이
+ *            같은 토큰으로 여백을 직접 잡는 화면용. SPopup·SSectionHeaderCard 의 padding="none" 과 같은 관용구.
+ */
+export const PAGE_PADDINGS = ['default', 'none'] as const;
+```
+
+### PAGE_CONTENT_HEIGHTS
+
+```ts
+/**
+ * 본문 높이 모드 — 페이지가 스크롤할지, 본문이 남은 높이를 채울지.
+ * - auto: 콘텐츠가 흐르고, 넘치면 페이지가 스크롤한다
+ * - fill: 본문이 남은 높이를 정확히 채우고 페이지는 스크롤하지 않는다.
+ *         표가 자기 안에서 스크롤하고 페이지네이션이 하단에 고정되는 목록 화면용.
+ */
+export const PAGE_CONTENT_HEIGHTS = ['auto', 'fill'] as const;
+```
+
+### PAGE_CONTENT_WIDTHS
+
+```ts
+/**
+ * 본문 가로 폭 모드 — 창이 레이아웃 최소 폭보다 **넓을 때** 본문이 어떻게 설지.
+ * - full:        남는 폭을 본문이 다 쓴다 (반응형)
+ * - fixed:       창이 최소 폭일 때의 본문 폭 그대로 고정하고 왼쪽에 붙인다
+ * - fixedCenter: 같은 폭으로 고정하고 가운데 놓는다
+ *
+ * 창이 최소 폭보다 좁아지면 세 모드가 모두 같다 — 모자란 몫은 SPage 가 가로 스크롤로 삼킨다.
+ */
+export const PAGE_CONTENT_WIDTHS = ['full', 'fixed', 'fixedCenter'] as const;
+```
 
 ## Dependencies
 
+### Used by
+
+ - [SLayout](../SLayout)
+
 ### Depends on
 
 - [SGhostButton](../SGhostButton)
@@ -45,5 +144,6 @@
 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';
+import type { SPageBackground, SPageContentHeight, SPageContentWidth, SPagePadding } from './page.config';
 export interface SPageProps extends HTMLAttributes<HTMLElement> {
     /**
      * 페이지 배경 표면. frame=흰 콘텐츠 면, neutral=옅은 회색 면, screen=앱 바탕.
@@ -9,9 +8,24 @@ export interface SPageProps extends HTMLAttributes<HTMLElement> {
     background?: SPageBackground;
     /**
      * 스크롤 끝 여백. 마지막 항목이 창 하단에 붙어 "여기서 끝"이 안 읽히는 것을 막는다.
-     * 기본으로 켜져 있고, 페이지네이션처럼 끝을 알려주는 것이 이미 있으면 끈다(목록 페이지).
+     *
+     * **기본은 꺼져 있다.** 페이지 스크롤 자체가 예외이기 때문이다 — 대부분의 화면은 본문이
+     * 창을 꽉 채우고 스크롤은 각 영역 안에서 일어난다. 여백을 조건 없이 붙이면 내용이 화면에
+     * 거의 딱 맞는 페이지까지 그 여백 때문에 스크롤되게 만든다.
+     *
+     * 페이지가 실제로 스크롤되는 화면(`contentHeight="auto"` + 내용이 창보다 김)에서만 켠다.
+     * 페이지네이션처럼 끝을 알려주는 것이 이미 있으면 켜지 않는다.
      */
     scrollEndSpacing?: boolean;
+    /**
+     * 본문 안쪽 여백. 기본은 `default` — `--cmp-pageBody-padding-default` 를 사방에 넣는다.
+     *
+     * `none` 은 필터 바처럼 **가장자리까지 차는 블록이 맨 위에 서는** 화면용이다. 패딩을 끄면
+     * 그 아래 블록이 `p-[var(--cmp-pageBody-padding-default)]` 로 같은 토큰의 여백을 직접 잡는다 —
+     * `p-sd-*` 로 적으면 토큰이 바뀌어도 따라가지 않는다. 사방 패딩만 끄고 `scrollEndSpacing` 은
+     * 그대로다. (`SPopup`·`SSectionHeaderCard` 의 `padding="none"` 과 같은 관용구)
+     */
+    padding?: SPagePadding;
     /**
      * true면 네이티브 스크롤바를 숨기고 SPage 위에 오버레이 스크롤바를 얹는다.
      * 스크롤바가 레이아웃 폭을 차지하지 않아 내부 콘텐츠 폭이 줄어들지 않는다.
@@ -29,23 +43,33 @@ export interface SPageProps extends HTMLAttributes<HTMLElement> {
      */
     contentHeight?: SPageContentHeight;
     /**
-     * 페이지 타이틀 영역(pageHeader 포팅). 주면 스크롤·페이지 패딩 밖으로 빼내 상단에 고정 배치한다.
-     * `children` 은 항상 본문이다 — header 유무와 무관하게 같은 자리에 같은 뜻으로 들어간다.
+     * 본문 가로 폭 모드. 기본은 `full` — 창이 넓어지면 본문도 같이 넓어진다(반응형).
+     *
+     * `fixed`·`fixedCenter` 는 본문을 **레이아웃 최소 폭일 때의 폭**으로 고정한다. 최소 폭 기준으로
+     * 그린 시안이 넓은 모니터에서 늘어나 성기어지는 것을 막는 모드다. 남는 폭은 `fixed` 면 오른쪽에,
+     * `fixedCenter` 면 좌우로 나뉘어 페이지 배경으로 남는다. 고정 폭은 GNB 폭·접힘을 반영해
+     * 저절로 따라오므로 앱이 숫자를 쓸 일은 없다.
+     *
+     * 창이 최소 폭보다 좁아지면 세 모드가 모두 같다 — 남는 폭이 없어 규칙이 꺼지고, 모자란 몫을
+     * 지금까지처럼 이 영역이 가로 스크롤로 삼킨다.
+     *
+     * 같은 열에 `SPageHeader` 가 있으면 헤더도 같은 폭·정렬을 따른다(제목과 본문의 좌우 끝이 맞는다).
+     * `SLayout` 밖에서는 기준이 될 최소 폭이 없으므로 무시된다.
      */
-    header?: SPageHeaderProps;
+    contentWidth?: SPageContentWidth;
 }
 /**
  * SPage — SLayout 안에서 남은 공간을 채우는 스크롤 콘텐츠 영역.
  * 스크롤은 SLayout(overflow:hidden)이 잡아둔 경계 안에서 이 영역에만 생긴다.
  * 창이 SLayout 의 최소 폭보다 좁을 때 생기는 가로 스크롤도 여기 걸린다(문서는 스크롤되지 않는다).
- * 패딩은 className 으로, 배경은 background 로 정한다(className 으로도 덮어쓸 수 있다).
+ * 패딩은 padding 으로, 배경은 background 로 정한다(둘 다 className 으로도 덮어쓸 수 있다).
  *
  * - header="fix": flex 자식으로 남은 가로 공간을 채운다.
  * - 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

@@ -1,32 +1,50 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
+import type { SPageHeaderVariant } from './page.config';
 export interface SPageHeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'slot' | 'title'> {
     /** 타이틀 (필수) */
     title: string;
-    /** 서브 텍스트. fix=true 면 타이틀 오른쪽에, fix=false(기본) 면 타이틀 아래에 놓인다. */
+    /** 서브 텍스트. `bar` 면 타이틀 오른쪽에, `plain` 이면 타이틀 아래에 놓인다. */
     subText?: string;
     /**
-     * true: 높이 56 고정 + 흰 배경 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄.
-     * false(기본): 최소 높이 66(상하 패딩 20/16 안에서 타이틀 한 줄 높이로 결정) + 투명 배경,
-     * 서브 텍스트가 타이틀 아래로 내려간다.
+     * 제목 영역의 모양 — **필수다.**
+     *
+     * - `plain`: 최소 높이(상하 패딩 안에서 타이틀 한 줄 높이로 결정) + 구분선 없음,
+     *   서브 텍스트가 타이틀 아래로 내려간다.
+     * - `bar`: 높이 고정 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄.
+     *
+     * 기본값을 두지 않는 이유는 이 값이 **앱 전체에서 하나로 고정돼야 하는 값**이기 때문이다.
+     * 기본값이 있으면 안 준 페이지만 조용히 다른 모양이 되어, 메뉴를 옮길 때 제목 줄의 높이와
+     * 구분선이 페이지마다 튄다. 셸을 한 번 감싸 쓰면(§4-1 AppShell) 지정하는 자리도 한 곳이다.
+     *
+     * 배경은 두 베리에이션 모두 흰 면이다. `SLayout` 의 `header`(`'fix' | 'full'`)와는 다른 축이다 —
+     * 그쪽은 상단바가 GNB 컬럼 안에 있는지 화면 전폭인지를 정한다.
      */
-    fix?: boolean;
+    variant: SPageHeaderVariant;
     /** 뒤로가기 클릭 핸들러. 지정하면 왼쪽에 뒤로가기 버튼이 나타난다. */
     onBack?: () => void;
     /** 오른쪽 끝 커스텀 슬롯. 가이드 링크·액션 버튼 등 페이지마다 다른 것이 온다. */
     slot?: ReactNode;
     /**
-     * `<SPage>` 가 스크롤 여부를 보고 자동으로 넣어준다 — 직접 주지 않는다.
-     * fix=false 일 때만 의미가 있다: 스크롤이 시작되면 그림자(floating)가 들어가 스크롤되는
-     * 콘텐츠 위에 뜬 것처럼 보인다. 배경은 그대로 페이지 배경을 따라간다 — 배경을 바꾸는 건
-     * scrolled 가 아니라 fix 다.
-     * @nodemo SPage 가 스크롤 이벤트로 넣어준다 — 사용자가 직접 시연할 값이 아니다.
+     * 아래 콘텐츠가 스크롤을 시작했는지. `plain` 일 때만 의미가 있다: 스크롤이 시작되면
+     * 그림자(floating)가 들어가 스크롤되는 콘텐츠 위에 뜬 것처럼 보인다. 배경은 흰 면 그대로다 —
+     * scrolled 가 더하는 것은 그림자뿐이다.
+     *
+     * `SLayout` 안에 놓았으면 **주지 않는다** — 같은 열의 `SPage` 가 자기 스크롤 상태를 올려
+     * 자동으로 들어온다. 스크롤 컨테이너를 앱이 직접 쥔 단독 배치에서만 `onScroll` 에서 준다.
      */
     scrolled?: boolean;
 }
 /**
- * SPage 위에 얹는 페이지 타이틀 영역(pageHeader 포팅). `SPage` 가 `header` prop 값으로
- * 내부적으로만 렌더한다 — 직접 임포트해 쓰지 않는다 (SPage.tsx 참고).
- * fix 로 bar(높이 고정·흰 배경) / plain(투명·최소 높이) 두 베리에이션을 고른다.
+ * 페이지 타이틀 영역(pageHeader 포팅).
+ * `variant` 로 bar(높이 고정·하단 구분선) / plain(최소 높이) 두 베리에이션을 고른다 — 배경은 둘 다 흰 면이다.
  * 뒤로가기 버튼은 onBack 유무로 나타나며, 없을 때는 타이틀 쪽에 4px 여백이 대신 들어간다.
+ *
+ * **셸 안에서는 `SLayout` 의 자식으로 `SGnb` 와 `SPage` 사이에 놓는다.** SLayout 이 이 헤더부터
+ * 뒤를 하나의 페이지 열로 묶어(page-column.tsx) 스크롤·페이지 패딩 밖 상단에 고정하고,
+ * plain 일 때 `SPage` 가 올린 스크롤 상태를 열이 대신 물려준다. 같은 경로로 `SPage` 의
+ * `contentWidth` 도 물려받아, 본문이 고정 폭이면 제목 줄도 같은 폭·정렬로 선다(면은 늘 전폭이다).
+ *
+ * 셸 밖에 직접 놓을 수도 있다 — 스크롤 컨테이너를 앱이 쥐고 있는 단독 화면이다. 그때는 그림자만
+ * 앱 몫이 된다: 스크롤 컨테이너의 `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 { PAGE_BACKGROUNDS, type SPageBackground, PAGE_CONTENT_HEIGHTS, type SPageContentHeight, PAGE_CONTENT_WIDTHS, type SPageContentWidth, PAGE_PADDINGS, type SPagePadding, PAGE_HEADER_VARIANTS, type SPageHeaderVariant, } from './page.config';
+export { SPageHeader, type SPageHeaderProps } from './SPageHeader';

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

@@ -0,0 +1,34 @@
+import { type ReactNode } from 'react';
+import type { SPageContentWidth } from './page.config';
+/**
+ * 페이지 열이 `SPageHeader` 와 `SPage` 사이에서 중개하는 것.
+ *
+ * 둘은 형제라 서로를 볼 수 없는데, 헤더의 그림자는 페이지의 스크롤에서, 헤더의 가로 정렬은
+ * 페이지의 폭 모드에서 나온다. 열이 그 사이에 서서 값을 옮긴다 —
+ * 아래(SPage)가 올리고 위(SPageHeader)가 읽는다.
+ */
+export interface SPageColumnValue {
+    /** 페이지가 스크롤을 시작했는지. `SPage` 가 올리고 `SPageHeader` 가 그림자로 쓴다. */
+    scrolled: boolean;
+    /** `SPage` 가 자기 스크롤 상태를 올린다. */
+    setScrolled: (scrolled: boolean) => void;
+    /**
+     * 페이지 본문의 가로 폭 모드. `SPage` 가 올리고 `SPageHeader` 가 자기 내용물을 같은 폭·정렬로 맞춘다.
+     * 헤더는 페이지 위에 서는 같은 열의 일부라, 본문만 가운데로 가면 제목과 본문 좌우 끝이 어긋난다.
+     */
+    contentWidth: SPageContentWidth;
+    /** `SPage` 가 자기 폭 모드를 올린다. */
+    setContentWidth: (contentWidth: SPageContentWidth) => 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;

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

@@ -0,0 +1,23 @@
+import type { CSSProperties } from 'react';
+import type { SPageContentWidth } from './page.config';
+/**
+ * 콘텐츠 상자의 최소 폭 — SLayout 이 보장하는 레이아웃 최소 폭을 이 상자가 대신 삼킨다.
+ *
+ * `100cqw` 는 SLayout 프레임의 폭, `100%` 는 이 상자를 담은 영역의 콘텐츠 폭이다.
+ * "프레임이 최소 폭보다 좁은 만큼" 콘텐츠를 넓히므로, GNB 폭·접힘·header 구성이 어떻든
+ * [GNB + 스크롤 끝까지 민 페이지] 합이 정확히 최소 폭이 된다. 패딩을 덮어써도 100% 가 따라온다.
+ *
+ * SLayout 밖이면 변수가 없어(폴백 0) 값이 음수가 되고, 음수 min-width 는 0 으로 클램프돼 규칙이 꺼진다.
+ */
+export declare const MIN_CONTENT_WIDTH = "calc(var(--s-layout-min-width, 0px) - 100cqw + 100%)";
+/**
+ * 고정 폭 모드가 남는 폭을 어디로 미는지 — 폭을 직접 주지 않고 여백으로 민다.
+ * 그래서 남는 폭이 0 인 구간(창이 최소 폭 이하)에서는 아무 일도 하지 않고,
+ * 넓어진 만큼만 상자가 "최소 폭일 때의 폭"으로 되돌아간다.
+ *
+ * `full` 은 아무것도 하지 않는다 — 남는 폭을 본문이 그대로 쓴다.
+ *
+ * **SLayout 밖에서는 호출하지 않는다.** 최소 폭 변수가 없으면 남는 폭이 프레임 폭 전체가 되어
+ * 본문이 사라진다. 호출하는 쪽이 SLayout 안임을 확인하고 부른다.
+ */
+export declare const contentWidthStyle: (mode: SPageContentWidth) => CSSProperties | undefined;

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

@@ -14,3 +14,29 @@ export type SPageBackground = (typeof PAGE_BACKGROUNDS)[number];
  */
 export declare const PAGE_CONTENT_HEIGHTS: readonly ["auto", "fill"];
 export type SPageContentHeight = (typeof PAGE_CONTENT_HEIGHTS)[number];
+/**
+ * 본문 안쪽 여백 모드.
+ * - default: SPage 가 --cmp-pageBody-padding-default 로 사방 패딩을 넣는다
+ * - none:    패딩을 끈다. 가장자리까지 차는 블록(필터 바 등)이 맨 위에 서고, 그 아래 블록이
+ *            같은 토큰으로 여백을 직접 잡는 화면용. SPopup·SSectionHeaderCard 의 padding="none" 과 같은 관용구.
+ */
+export declare const PAGE_PADDINGS: readonly ["default", "none"];
+export type SPagePadding = (typeof PAGE_PADDINGS)[number];
+/**
+ * 본문 가로 폭 모드 — 창이 레이아웃 최소 폭보다 **넓을 때** 본문이 어떻게 설지.
+ * - full:        남는 폭을 본문이 다 쓴다 (반응형)
+ * - fixed:       창이 최소 폭일 때의 본문 폭 그대로 고정하고 왼쪽에 붙인다
+ * - fixedCenter: 같은 폭으로 고정하고 가운데 놓는다
+ *
+ * 창이 최소 폭보다 좁아지면 세 모드가 모두 같다 — 모자란 몫은 SPage 가 가로 스크롤로 삼킨다.
+ */
+export declare const PAGE_CONTENT_WIDTHS: readonly ["full", "fixed", "fixedCenter"];
+export type SPageContentWidth = (typeof PAGE_CONTENT_WIDTHS)[number];
+/**
+ * 페이지 제목 영역의 모양 — 문서와 디자인이 부르는 이름을 그대로 쓴다.
+ * 기본값은 없다. 앱 전체에서 하나로 고정할 값이라 `SPageHeader` 가 매번 지정하게 한다.
+ * - plain: 최소 높이(상하 패딩 안에서 타이틀 한 줄), 구분선 없음, 서브 텍스트가 타이틀 아래
+ * - bar:   높이 고정 + 하단 구분선, 서브 텍스트가 타이틀과 같은 줄
+ */
+export declare const PAGE_HEADER_VARIANTS: readonly ["plain", "bar"];
+export type SPageHeaderVariant = (typeof PAGE_HEADER_VARIANTS)[number];

package/dist/components/SPieChart/README.md

@@ -0,0 +1,93 @@
+# SPieChart
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SPieChart
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `SPieChartSlice[]` | — | 조각 목록. 주는 순서대로 12시에서 시계 방향으로 그린다 — 보통 큰 순으로 준다 |
+| `title?` | `string` | — | 차트 제목 — 왼쪽 위에 놓인다 |
+| `unit?` | `string` | — | 단위 — 오른쪽 위에 "단위 : " 를 붙여 놓는다 |
+| `palette?` | `SPieChartPalette` | `'multi'` | 색 팔레트. `custom` 일 때만 `colors` 를 본다 |
+| `colors?` | `SPieChartColor[]` | — | `palette='custom'` 에서 쓸 색 이름을 조각 순서대로. 조각보다 짧으면 앞에서부터 순환하고, 비어 있으면 `multi` 로 그린다 |
+| `showValueLabel?` | `boolean` | `false` | 조각 안에 몫(%)을 적는다. 좁은 조각은 글자가 넘치므로 적지 않는다 |
+| `showLegend?` | `boolean` | `true` | 범례를 보인다 |
+| `legendPosition?` | `SPieChartLegendPosition` | `'top'` | 범례 위치 |
+| `showTooltip?` | `boolean` | `true` | 조각에 마우스를 올리면 값 상자를 띄운다 |
+| `formatValue?` | `(value: number) => string` | — | 값 표시 형식 |
+| `tooltipFooter?` | `(slice: SPieChartSlicePoint) => ReactNode` | — | 툴팁의 값 아래에 덧붙일 내용. 짚은 조각을 받아 그린다 — 몫·값만으로 모자란 맥락 (전월 대비, 건수 등)을 적는다. 툴팁은 누를 수 없으므로 버튼·링크는 넣지 않는다 |
+| `className?` | `string` | — | 폭은 기본 100% 다. 폭을 정하려면 여기에 준다 — 그림은 그 폭의 정사각형이 된다 |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onSliceClick` | `(slice: SPieChartSlicePoint) => void` | 조각을 눌렀을 때 |
+
+## Types
+
+### SPieChartSlice
+
+```ts
+/** 조각 하나 — 범례 한 줄에 대응한다. */
+export interface SPieChartSlice {
+  /** 범례·툴팁에 표시할 이름 */
+  name: string;
+  /** 값. 0·음수는 그리지 않는다 — 원은 전체에 대한 몫만 나타낼 수 있다 */
+  value: number;
+}
+```
+
+### SPieChartPalette
+
+```ts
+/**
+ * 색 팔레트. 조각마다 색이 달라야 하므로 한 색(`default`)은 없다.
+ * - `multi` 서로 무관한 항목(11색)을 순서대로
+ * - `gradation` 한 지표의 단계(6색)를 진한 쪽부터 순서대로 — 조각을 큰 순으로 줄 때
+ * - `custom` `colors` 로 고른 색을 순서대로
+ */
+export type SPieChartPalette = 'multi' | 'gradation' | 'custom';
+```
+
+### SPieChartColor
+
+```ts
+/**
+ * `palette='custom'` 에서 고를 수 있는 색 이름.
+ * positive=늘어남 · negative=줄어듦 · neutral=변화 없음 을 뜻하므로 뜻에 맞게 고른다.
+ */
+export type SPieChartColor =
+  | 'positivePrimary'
+  | 'positiveSecondary'
+  | 'negativePrimary'
+  | 'negativeSecondary'
+  | 'neutralPrimary'
+  | 'neutralSecondary';
+```
+
+### SPieChartLegendPosition
+
+```ts
+/** 범례 위치. */
+export type SPieChartLegendPosition = 'top' | 'bottom';
+```
+
+### SPieChartSlicePoint
+
+```ts
+/** 클릭이 가리키는 조각. */
+export interface SPieChartSlicePoint {
+  /** `data` 안에서의 인덱스 */
+  index: number;
+  name: string;
+  value: number;
+  /** 그려진 조각 전체의 합에 대한 몫(0~1) */
+  ratio: number;
+}
+```
+

package/dist/components/SPieChart/SPieChart.d.ts

@@ -0,0 +1,73 @@
+import { type CSSProperties, type ReactNode } from 'react';
+/** 범례 위치. */
+export type SPieChartLegendPosition = 'top' | 'bottom';
+/**
+ * 색 팔레트. 조각마다 색이 달라야 하므로 한 색(`default`)은 없다.
+ * - `multi` 서로 무관한 항목(11색)을 순서대로
+ * - `gradation` 한 지표의 단계(6색)를 진한 쪽부터 순서대로 — 조각을 큰 순으로 줄 때
+ * - `custom` `colors` 로 고른 색을 순서대로
+ */
+export type SPieChartPalette = 'multi' | 'gradation' | 'custom';
+/**
+ * `palette='custom'` 에서 고를 수 있는 색 이름.
+ * positive=늘어남 · negative=줄어듦 · neutral=변화 없음 을 뜻하므로 뜻에 맞게 고른다.
+ */
+export type SPieChartColor = 'positivePrimary' | 'positiveSecondary' | 'negativePrimary' | 'negativeSecondary' | 'neutralPrimary' | 'neutralSecondary';
+/** 조각 하나 — 범례 한 줄에 대응한다. */
+export interface SPieChartSlice {
+    /** 범례·툴팁에 표시할 이름 */
+    name: string;
+    /** 값. 0·음수는 그리지 않는다 — 원은 전체에 대한 몫만 나타낼 수 있다 */
+    value: number;
+}
+/** 클릭이 가리키는 조각. */
+export interface SPieChartSlicePoint {
+    /** `data` 안에서의 인덱스 */
+    index: number;
+    name: string;
+    value: number;
+    /** 그려진 조각 전체의 합에 대한 몫(0~1) */
+    ratio: number;
+}
+export interface SPieChartProps {
+    /** 조각 목록. 주는 순서대로 12시에서 시계 방향으로 그린다 — 보통 큰 순으로 준다 */
+    data: SPieChartSlice[];
+    /** 차트 제목 — 왼쪽 위에 놓인다 */
+    title?: string;
+    /** 단위 — 오른쪽 위에 "단위 : " 를 붙여 놓는다 */
+    unit?: string;
+    /** 색 팔레트. `custom` 일 때만 `colors` 를 본다 */
+    palette?: SPieChartPalette;
+    /** `palette='custom'` 에서 쓸 색 이름을 조각 순서대로. 조각보다 짧으면 앞에서부터 순환하고, 비어 있으면 `multi` 로 그린다 */
+    colors?: SPieChartColor[];
+    /** 조각 안에 몫(%)을 적는다. 좁은 조각은 글자가 넘치므로 적지 않는다 */
+    showValueLabel?: boolean;
+    /** 범례를 보인다 */
+    showLegend?: boolean;
+    /** 범례 위치 */
+    legendPosition?: SPieChartLegendPosition;
+    /** 조각에 마우스를 올리면 값 상자를 띄운다 */
+    showTooltip?: boolean;
+    /** 값 표시 형식 */
+    formatValue?: (value: number) => string;
+    /** 조각을 눌렀을 때 */
+    onSliceClick?: (slice: SPieChartSlicePoint) => void;
+    /**
+     * 툴팁의 값 아래에 덧붙일 내용. 짚은 조각을 받아 그린다 — 몫·값만으로 모자란 맥락
+     * (전월 대비, 건수 등)을 적는다. 툴팁은 누를 수 없으므로 버튼·링크는 넣지 않는다
+     */
+    tooltipFooter?: (slice: SPieChartSlicePoint) => ReactNode;
+    /** 폭은 기본 100% 다. 폭을 정하려면 여기에 준다 — 그림은 그 폭의 정사각형이 된다 */
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * SPieChart — 원그래프.
+ *
+ * **한 시점의 전체를 몇 개의 몫으로 나눈 것**을 보여줄 때 쓴다. 조각이 대여섯 개를 넘거나
+ * 몫끼리 크기를 견주는 것이 목적이면 `SBarChart` 가 맞다 — 사람은 각도보다 길이를
+ * 훨씬 정확하게 견준다. 합계를 함께 강조하려면 `SDonutChart` 를 쓴다.
+ *
+ * 폭은 부모를 따르고(기본 100%), 그림은 그 폭을 한 변으로 하는 정사각형이다.
+ */
+export declare const SPieChart: import("react").ForwardRefExoticComponent<SPieChartProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1 @@
+export { SPieChart, type SPieChartProps, type SPieChartSlice, type SPieChartSlicePoint, type SPieChartPalette, type SPieChartColor, type SPieChartLegendPosition, } from './SPieChart';

package/dist/components/SPopover/README.md

@@ -33,6 +33,21 @@
 | `onLeftLinkClick` | `() => void` | 하단 좌측 링크 클릭 |
 | `onButtonClick` | `() => void` | 하단 우측 버튼 클릭 |
 
+## Types
+
+### SPopoverPlacement
+
+```ts
+export type SPopoverPlacement = 'top' | 'bottom' | 'left' | 'right';
+```
+
+### SPopoverType
+
+```ts
+/** 색상 타입 — default: 다크 배경 / danger·warning·accent: 라이트 배경 (component.popover 토큰) */
+export type SPopoverType = 'default' | 'danger' | 'warning' | 'accent';
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/SPopup/README.md

@@ -10,10 +10,10 @@
 |------|------|---------|-------------|
 | `popupTitle?` | `string` | `''` | 헤더 제목 |
 | `type?` | `SPopupType` | `'default'` | 타입 (헤더 색상) |
-| `useFooter?` | `boolean` | `false` | 하단 footer 표시 여부 |
+| `showFooter?` | `boolean` | `false` | 하단 footer 표시 여부 |
 | `submitButton?` | `SPopupSubmitButton` | — | 확인 버튼 설정 |
 | `footerLeft?` | `ReactNode` | — | footer 좌측 영역 |
-| `noPadding?` | `boolean` | `false` | 본문 기본 패딩을 없앱니다. 표를 가장자리까지 채우는 등 본문이 직접 여백을 다룰 때만 사용합니다. |
+| `padding?` | `SPopupBodyPadding` | `'default'` | 본문 안쪽 여백. 기본은 `default` — 표를 가장자리까지 채우는 등 본문이 여백을 직접 다룰 때만 `none`. (`SList` 의 `padding` 과 같은 이름이지만 기본값이 반대다 — 각 면의 성격이 다르다) |
 | `children?` | `ReactNode` | — | 본문 |
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
@@ -24,6 +24,30 @@
 |-------|------|-------------|
 | `onSubmit` | `() => void` | 확인 버튼 클릭 (sdSubmit) |
 
+## Types
+
+### SPopupType
+
+```ts
+export type SPopupType = 'default' | 'light';
+```
+
+### SPopupSubmitButton
+
+```ts
+/**
+ * 확인 버튼 설정 — `SButton` 의 prop 을 그대로 받되 `onClick` 만 뺀다.
+ * 클릭은 `onSubmit` 이 전담하므로, 여기로도 받으면 조용히 덮어써지는 prop 이 생긴다.
+ */
+export type SPopupSubmitButton = Omit<SFooterButton, 'onClick'>;
+```
+
+### SPopupBodyPadding
+
+```ts
+export type SPopupBodyPadding = 'default' | 'none';
+```
+
 ## Dependencies
 
 ### Depends on