sellmate-design-system-react 9.0.0-beta.4 → 9.0.0-beta.41

package/dist/components/SNumberInput/README.md

@@ -13,12 +13,12 @@
 | `min?` | `number` | `Number.NEGATIVE_INFINITY` | 최솟값 |
 | `max?` | `number` | `Number.POSITIVE_INFINITY` | 최댓값 |
 | `step?` | `number` | `1` | 스텝 단위 |
-| `useButton?` | `boolean` | `false` | 증감 버튼 표시 |
-| `useDecimal?` | `boolean` | `false` | 소수점 입력 허용 |
+| `showButton?` | `boolean` | `false` | 증감 버튼 표시 |
+| `allowDecimal?` | `boolean` | `false` | 소수점 입력 허용 |
 | `maxDecimalLength?` | `number` | — | 소수점 이하 최대 자리수 |
 | `inputPrefix?` | `string` | `''` | 입력 앞 접두 텍스트 |
 | `inputSuffix?` | `string` | `''` | 입력 뒤 접미 텍스트 |
-| `inputClass?` | `string` | — | 네이티브 input className |
+| `inputClassName?` | `string` | — | 네이티브 input className |
 | `inputStyle?` | `CSSProperties` | — | 네이티브 input style |
 | `autoFocus?` | `boolean` | — | 마운트 시 자동 포커스 |
 | `name?` | `string` | — | 폼 연동 name |
@@ -27,8 +27,8 @@
 | `readOnly?` | `boolean` | `false` |  |
 | `rules?` | `Rule[]` | — | 유효성 규칙 — blur 시 검증 |
 | `status?` | `SFieldStatus` | — |  |
-| `focused?` | `boolean` | — |  |
-| `hovered?` | `boolean` | — |  |
+| `focused?` | `boolean` | — | 포커스 상태를 밖에서 지정한다 — 강조 테두리·링이 즉시 걸린다 (SField 로 그대로 넘어간다) |
+| `hovered?` | `boolean` | — | 호버 상태를 밖에서 지정한다 — 강조는 `focused` 와 같다 (SField 로 그대로 넘어간다) |
 | `label?` | `string` | — |  |
 | `labelWidth?` | `number \| string` | — |  |
 | `icon?` | `SIconName` | — |  |
@@ -40,7 +40,7 @@
 | `hint?` | `string` | — |  |
 | `error?` | `boolean` | — |  |
 | `errorMessage?` | `string` | — |  |
-| `width?` | `number \| string` | — |  |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리며 `max`(= 스키마 상한)로 고른다. 상한이 `xl` 을 넘거나 상한이 없으면 `"100%"`. (`sellmate/field-width-grade` 가 검사한다) |
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
 
@@ -52,6 +52,14 @@
 | `onFocus` | `(e: React.FocusEvent<HTMLInputElement>) => void` | 포커스 이벤트 (sdFocus) |
 | `onBlur` | `(e: React.FocusEvent<HTMLInputElement>) => void` | 블러 이벤트 (sdBlur) |
 
+## Types
+
+### SNumberInputSize
+
+```ts
+export type SNumberInputSize = SFieldSize;
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SNumberInput/SNumberInput.d.ts

@@ -4,6 +4,7 @@ import { type SIconName } from '../SIcon';
 import { type SColor } from '../../lib/color';
 import { type Rule } from '../../lib/form';
 import { type STooltipProps } from '../STooltip';
+import { type SFieldWidth } from '../../lib/field-width';
 export type SNumberInputSize = SFieldSize;
 export interface SNumberInputProps {
     /** 입력 값 */
@@ -19,9 +20,9 @@ export interface SNumberInputProps {
     /** 스텝 단위 */
     step?: number;
     /** 증감 버튼 표시 */
-    useButton?: boolean;
+    showButton?: boolean;
     /** 소수점 입력 허용 */
-    useDecimal?: boolean;
+    allowDecimal?: boolean;
     /** 소수점 이하 최대 자리수 */
     maxDecimalLength?: number;
     /** 입력 앞 접두 텍스트 */
@@ -29,7 +30,7 @@ export interface SNumberInputProps {
     /** 입력 뒤 접미 텍스트 */
     inputSuffix?: string;
     /** 네이티브 input className */
-    inputClass?: string;
+    inputClassName?: string;
     /** 네이티브 input style */
     inputStyle?: CSSProperties;
     /** 마운트 시 자동 포커스 */
@@ -46,7 +47,9 @@ export interface SNumberInputProps {
     /** 유효성 규칙 — blur 시 검증 */
     rules?: Rule[];
     status?: SFieldStatus;
+    /** 포커스 상태를 밖에서 지정한다 — 강조 테두리·링이 즉시 걸린다 (SField 로 그대로 넘어간다) */
     focused?: boolean;
+    /** 호버 상태를 밖에서 지정한다 — 강조는 `focused` 와 같다 (SField 로 그대로 넘어간다) */
     hovered?: boolean;
     label?: string;
     labelWidth?: number | string;
@@ -59,7 +62,12 @@ export interface SNumberInputProps {
     hint?: string;
     error?: boolean;
     errorMessage?: string;
-    width?: number | string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리며 `max`(= 스키마 상한)로 고른다.
+     * 상한이 `xl` 을 넘거나 상한이 없으면 `"100%"`. (`sellmate/field-width-grade` 가 검사한다)
+     */
+    width?: SFieldWidth;
     className?: string;
     style?: CSSProperties;
 }

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,12 +27,93 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `background?` | `SPageBackground` | `'frame'` | 페이지 배경 표면. frame=흰 콘텐츠 면, neutral=옅은 회색 면, screen=앱 바탕. 스크롤바 처리도 여기 묶여 있다 — 셋 다 구분선+트랙 배경이고, 트랙 색만 neutral 에서 흰색이 된다. |
-| `scrollEndSpacing?` | `boolean` | `true` | 스크롤 끝 여백. 마지막 항목이 창 하단에 붙어 "여기서 끝"이 안 읽히는 것을 막는다. 기본으로 켜져 있고, 페이지네이션처럼 끝을 알려주는 것이 이미 있으면 끈다(목록 페이지). |
+| `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 유무와 무관하게 같은 자리에 같은 뜻으로 들어간다. |
+| `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];
+```
+
+### 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_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)
@@ -44,5 +125,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 } from './page.config';
 export interface SPageProps extends HTMLAttributes<HTMLElement> {
     /**
      * 페이지 배경 표면. frame=흰 콘텐츠 면, neutral=옅은 회색 면, screen=앱 바탕.
@@ -9,9 +8,20 @@ export interface SPageProps extends HTMLAttributes<HTMLElement> {
     background?: SPageBackground;
     /**
      * 스크롤 끝 여백. 마지막 항목이 창 하단에 붙어 "여기서 끝"이 안 읽히는 것을 막는다.
-     * 기본으로 켜져 있고, 페이지네이션처럼 끝을 알려주는 것이 이미 있으면 끈다(목록 페이지).
+     *
+     * **기본은 꺼져 있다.** 페이지 스크롤 자체가 예외이기 때문이다 — 대부분의 화면은 본문이
+     * 창을 꽉 채우고 스크롤은 각 영역 안에서 일어난다. 여백을 조건 없이 붙이면 내용이 화면에
+     * 거의 딱 맞는 페이지까지 그 여백 때문에 스크롤되게 만든다.
+     *
+     * 페이지가 실제로 스크롤되는 화면(`contentHeight="auto"` + 내용이 창보다 김)에서만 켠다.
+     * 페이지네이션처럼 끝을 알려주는 것이 이미 있으면 켜지 않는다.
      */
     scrollEndSpacing?: boolean;
+    /**
+     * true면 네이티브 스크롤바를 숨기고 SPage 위에 오버레이 스크롤바를 얹는다.
+     * 스크롤바가 레이아웃 폭을 차지하지 않아 내부 콘텐츠 폭이 줄어들지 않는다.
+     */
+    overlayScrollbar?: boolean;
     /**
      * 본문 높이 모드. 기본은 `auto` — 콘텐츠가 흐르고 넘치면 페이지가 스크롤한다.
      *
@@ -24,10 +34,20 @@ 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 안에서 남은 공간을 채우는 스크롤 콘텐츠 영역.
@@ -39,8 +59,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

@@ -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_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,21 @@ export type SPageBackground = (typeof PAGE_BACKGROUNDS)[number];
  */
 export declare const PAGE_CONTENT_HEIGHTS: readonly ["auto", "fill"];
 export type SPageContentHeight = (typeof PAGE_CONTENT_HEIGHTS)[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/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,31 @@
 |-------|------|-------------|
 | `onSubmit` | `() => void` | 확인 버튼 클릭 (sdSubmit) |
 
+## Types
+
+### SPopupType
+
+```ts
+export type SPopupType = 'default' | 'light';
+```
+
+### SPopupSubmitButton
+
+```ts
+export interface SPopupSubmitButton {
+  label?: string;
+  color?: SButtonColor;
+  outline?: boolean;
+  size?: SButtonSize;
+}
+```
+
+### SPopupBodyPadding
+
+```ts
+export type SPopupBodyPadding = 'default' | 'none';
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/SPopup/SPopup.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode, type CSSProperties } from 'react';
 import { type SButtonColor, type SButtonSize } from '../SButton';
 export type SPopupType = 'default' | 'light';
+export type SPopupBodyPadding = 'default' | 'none';
 export interface SPopupSubmitButton {
     label?: string;
     color?: SButtonColor;
@@ -13,15 +14,18 @@ export interface SPopupProps {
     /** 타입 (헤더 색상) */
     type?: SPopupType;
     /** 하단 footer 표시 여부 */
-    useFooter?: boolean;
+    showFooter?: boolean;
     /** 확인 버튼 설정 */
     submitButton?: SPopupSubmitButton;
     /** 확인 버튼 클릭 (sdSubmit) */
     onSubmit?: () => void;
     /** footer 좌측 영역 */
     footerLeft?: ReactNode;
-    /** 본문 기본 패딩을 없앱니다. 표를 가장자리까지 채우는 등 본문이 직접 여백을 다룰 때만 사용합니다. */
-    noPadding?: boolean;
+    /**
+     * 본문 안쪽 여백. 기본은 `default` — 표를 가장자리까지 채우는 등 본문이 여백을 직접
+     * 다룰 때만 `none`. (`SList` 의 `padding` 과 같은 이름이지만 기본값이 반대다 — 각 면의 성격이 다르다)
+     */
+    padding?: SPopupBodyPadding;
     /** 본문 */
     children?: ReactNode;
     className?: string;

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

@@ -1 +1 @@
-export { SPopup, type SPopupProps, type SPopupType, type SPopupSubmitButton } from './SPopup';
+export { SPopup, type SPopupBodyPadding, type SPopupProps, type SPopupType, type SPopupSubmitButton, } from './SPopup';

package/dist/components/SPortal/README.md

@@ -34,18 +34,36 @@
 | `onCloseAutoFocus` | `(event: Event) => void` | 닫힐 때 포커스 복귀 처리 (기본은 Radix가 앵커로 포커스를 되돌림). e.preventDefault()로 막을 수 있다. |
 | `onPointerDownOutside` | `(event: Event) => void` | 바깥 영역 pointerdown 으로 닫힘이 시작될 때 (앵커 위 클릭·persistent 는 제외). |
 
+## Types
+
+### SPortalPlacement
+
+```ts
+export type SPortalPlacement = 'top' | 'bottom' | 'left' | 'right';
+```
+
+### SPortalAlign
+
+```ts
+export type SPortalAlign = 'start' | 'center' | 'end';
+```
+
 ## Dependencies
 
 ### Used by
 
+ - [SAccountListBox](../SAccountListBox)
  - [SChipInput](../SChipInput)
+ - [SGnbSystem](../SGnbSystem)
  - [SSelect](../SSelect)
 
 ### Graph
 
 ```mermaid
 graph TD;
+  SAccountListBox --> SPortal
   SChipInput --> SPortal
+  SGnbSystem --> SPortal
   SSelect --> SPortal
   style SPortal fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/SRadio/README.md

@@ -42,6 +42,26 @@
 |-------|------|-------------|
 | `onValueChange` | `(val: SRadioValue) => void` | 선택 변경 (sdUpdate) — 선택된 val 전달 |
 
+## Types
+
+### SRadioOption
+
+```ts
+export interface SRadioOption {
+  /** 옵션 값 (sd-radio-group SRadioOption.value) */
+  value: SRadioValue;
+  label: string;
+  disabled?: boolean;
+}
+```
+
+### SRadioValue
+
+```ts
+/** 라디오 값 타입 (sd-radio SRadioValue) */
+export type SRadioValue = string | number | boolean;
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SRadioButton/README.md

@@ -22,6 +22,24 @@
 |-------|------|-------------|
 | `onValueChange` | `(value: string \| number) => void` | 변경 (sdUpdate) |
 
+## Types
+
+### SRadioButtonOption
+
+```ts
+export interface SRadioButtonOption {
+  value: string | number;
+  label: string;
+  disabled?: boolean;
+}
+```
+
+### SRadioButtonSize
+
+```ts
+export type SRadioButtonSize = 'xs' | 'sm' | 'md';
+```
+
 ## Dependencies
 
 ### Used by