sellmate-design-system-react 9.0.0-beta.9 → 9.0.0-beta.91

package/dist/components/SLineChart/README.md

@@ -0,0 +1,131 @@
+# SLineChart
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SLineChart
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `categories` | `string[]` | — | 가로축에 놓일 항목 이름 |
+| `series` | `SLineChartSeries[]` | — | 계열 목록. 각 `data` 는 `categories` 와 같은 순서다 |
+| `title?` | `string` | — | 차트 제목 — 왼쪽 위에 놓인다 |
+| `unit?` | `string` | — | 단위 — 오른쪽 위에 "단위 : " 를 붙여 놓는다 |
+| `curve?` | `SLineChartCurve` | `'linear'` | 점을 잇는 방식. `smooth` 는 값을 넘어가 부풀지 않는 곡선이다 |
+| `lineStyle?` | `SLineChartLineStyle` | `'solid'` | 선 모양. `dashed` 는 차트의 모든 선을 점선으로 그린다 |
+| `area?` | `boolean` | `false` | 선 아래를 계열 색으로 채운다. 크기의 변화를 함께 보여줄 때 쓴다 |
+| `stacked?` | `boolean` | `false` | 계열을 겹쳐 그리는 대신 **아래 계열 위에 쌓는다**. 전체의 크기와 그 안의 구성을 함께 볼 때 쓴다 — 맨 위 선이 곧 합계다. 툴팁은 쌓기 전 각 계열의 값을 보여준다 |
+| `palette?` | `SLineChartPalette` | `'default'` | 색 팔레트. `custom` 일 때만 `colors` 를 본다 |
+| `colors?` | `SLineChartColor[]` | — | `palette='custom'` 에서 쓸 색 이름을 계열 순서대로. 계열보다 짧으면 앞에서부터 순환한다 |
+| `max?` | `number` | — | 값 축의 최댓값. 주지 않으면 데이터에서 읽기 좋은 값으로 정한다 |
+| `tickCount?` | `number` | `8` | 값 축 눈금 개수 |
+| `showPoint?` | `boolean` | `true` | 데이터 지점마다 점을 찍는다. 꺼도 짚은 항목의 점은 뜬다 |
+| `showValueLabel?` | `boolean` | `false` | 점마다 값을 적는다. 기본은 끔 — 선 그래프는 항목이 많은 데이터에 쓰는 일이 잦아 숫자가 서로 붙는다. 항목이 대여섯 개 안쪽일 때만 켠다 |
+| `showLegend?` | `boolean` | `true` | 범례를 보인다 |
+| `legendPosition?` | `SLineChartLegendPosition` | `'top'` | 범례 위치 |
+| `showTooltip?` | `boolean` | `true` | 항목에 마우스를 올리면 값 상자를 띄운다 |
+| `formatValue?` | `(value: number) => string` | `defaultFormat` | 값 표시 형식 |
+| `height?` | `number \| string` | — | 차트 높이. **아래 축 텍스트까지 포함한 값**이다 — 그림은 그만큼 줄어든다 |
+| `tooltipFooter?` | `(category: SLineChartTooltipCategory) => ReactNode` | — | 툴팁의 값 아래에 덧붙일 내용. 짚은 항목을 받아 그린다 — 계열 값만으로 모자란 맥락 (합계, 전월 대비 등)을 적는다. 툴팁은 누를 수 없으므로 버튼·링크는 넣지 않는다 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onPointClick` | `(point: SLineChartPoint) => void` | 점을 눌렀을 때 |
+
+## Types
+
+### SLineChartSeries
+
+```ts
+/** 한 계열 — 선 하나, 범례 한 줄에 대응한다. */
+export interface SLineChartSeries {
+  /** 범례·툴팁에 표시할 이름 */
+  name: string;
+  /** `categories` 와 같은 순서의 값. 빠진 자리(`null`·짧은 배열)에서는 선이 끊긴다 */
+  data: (number | null)[];
+}
+```
+
+### SLineChartCurve
+
+```ts
+/** 점과 점을 잇는 방식. */
+export type SLineChartCurve = 'linear' | 'smooth';
+```
+
+### SLineChartLineStyle
+
+```ts
+/** 선 모양. `dashed` 는 차트의 모든 선에 적용된다 — 일부 계열만 점선으로 구분하려면 쓰지 않는다 */
+export type SLineChartLineStyle = 'solid' | 'dashed';
+```
+
+### SLineChartPalette
+
+```ts
+/**
+ * 색 팔레트.
+ * - `default` 파랑 한 색. 계열이 하나거나 색으로 나눌 것이 없을 때
+ * - `multi` 서로 무관한 항목(11색)을 순서대로
+ * - `gradation` 한 지표의 단계(6색)를 진한 쪽부터 순서대로
+ * - `custom` `colors` 로 고른 색을 순서대로
+ */
+export type SLineChartPalette = 'default' | 'multi' | 'gradation' | 'custom';
+```
+
+### SLineChartColor
+
+```ts
+/**
+ * `palette='custom'` 에서 고를 수 있는 색 이름.
+ * positive=늘어남 · negative=줄어듦 · neutral=변화 없음 을 뜻하므로 뜻에 맞게 고른다.
+ */
+export type SLineChartColor =
+  | 'positivePrimary'
+  | 'positiveSecondary'
+  | 'negativePrimary'
+  | 'negativeSecondary'
+  | 'neutralPrimary'
+  | 'neutralSecondary';
+```
+
+### SLineChartLegendPosition
+
+```ts
+/** 범례 위치. */
+export type SLineChartLegendPosition = 'top' | 'bottom';
+```
+
+### SLineChartPoint
+
+```ts
+/** 툴팁·클릭이 가리키는 지점. */
+export interface SLineChartPoint {
+  /** 계열 인덱스 */
+  seriesIndex: number;
+  /** 카테고리 인덱스 */
+  categoryIndex: number;
+  /** 그 지점의 값. 누적이어도 **그 계열이 제 몫으로 가진 값**이다 */
+  value: number;
+}
+```
+
+### SLineChartTooltipCategory
+
+```ts
+/** 툴팁 하단(`tooltipFooter`)이 받는 짚은 항목. */
+export interface SLineChartTooltipCategory {
+  /** 카테고리 인덱스 */
+  categoryIndex: number;
+  /** 카테고리 이름 */
+  name: string;
+  /** 툴팁에 값이 뜬 지점들 — 값이 없는 계열은 빠진다. 누적이어도 각 계열이 제 몫으로 가진 값이다 */
+  points: SLineChartPoint[];
+}
+```
+

package/dist/components/SLineChart/SLineChart.d.ts

@@ -0,0 +1,110 @@
+import { type CSSProperties, type ReactNode } from 'react';
+/** 점과 점을 잇는 방식. */
+export type SLineChartCurve = 'linear' | 'smooth';
+/** 선 모양. `dashed` 는 차트의 모든 선에 적용된다 — 일부 계열만 점선으로 구분하려면 쓰지 않는다 */
+export type SLineChartLineStyle = 'solid' | 'dashed';
+/** 범례 위치. */
+export type SLineChartLegendPosition = 'top' | 'bottom';
+/**
+ * 색 팔레트.
+ * - `default` 파랑 한 색. 계열이 하나거나 색으로 나눌 것이 없을 때
+ * - `multi` 서로 무관한 항목(11색)을 순서대로
+ * - `gradation` 한 지표의 단계(6색)를 진한 쪽부터 순서대로
+ * - `custom` `colors` 로 고른 색을 순서대로
+ */
+export type SLineChartPalette = 'default' | 'multi' | 'gradation' | 'custom';
+/**
+ * `palette='custom'` 에서 고를 수 있는 색 이름.
+ * positive=늘어남 · negative=줄어듦 · neutral=변화 없음 을 뜻하므로 뜻에 맞게 고른다.
+ */
+export type SLineChartColor = 'positivePrimary' | 'positiveSecondary' | 'negativePrimary' | 'negativeSecondary' | 'neutralPrimary' | 'neutralSecondary';
+/** 툴팁·클릭이 가리키는 지점. */
+export interface SLineChartPoint {
+    /** 계열 인덱스 */
+    seriesIndex: number;
+    /** 카테고리 인덱스 */
+    categoryIndex: number;
+    /** 그 지점의 값. 누적이어도 **그 계열이 제 몫으로 가진 값**이다 */
+    value: number;
+}
+/** 툴팁 하단(`tooltipFooter`)이 받는 짚은 항목. */
+export interface SLineChartTooltipCategory {
+    /** 카테고리 인덱스 */
+    categoryIndex: number;
+    /** 카테고리 이름 */
+    name: string;
+    /** 툴팁에 값이 뜬 지점들 — 값이 없는 계열은 빠진다. 누적이어도 각 계열이 제 몫으로 가진 값이다 */
+    points: SLineChartPoint[];
+}
+/** 한 계열 — 선 하나, 범례 한 줄에 대응한다. */
+export interface SLineChartSeries {
+    /** 범례·툴팁에 표시할 이름 */
+    name: string;
+    /** `categories` 와 같은 순서의 값. 빠진 자리(`null`·짧은 배열)에서는 선이 끊긴다 */
+    data: (number | null)[];
+}
+export interface SLineChartProps {
+    /** 가로축에 놓일 항목 이름 */
+    categories: string[];
+    /** 계열 목록. 각 `data` 는 `categories` 와 같은 순서다 */
+    series: SLineChartSeries[];
+    /** 차트 제목 — 왼쪽 위에 놓인다 */
+    title?: string;
+    /** 단위 — 오른쪽 위에 "단위 : " 를 붙여 놓는다 */
+    unit?: string;
+    /** 점을 잇는 방식. `smooth` 는 값을 넘어가 부풀지 않는 곡선이다 */
+    curve?: SLineChartCurve;
+    /** 선 모양. `dashed` 는 차트의 모든 선을 점선으로 그린다 */
+    lineStyle?: SLineChartLineStyle;
+    /** 선 아래를 계열 색으로 채운다. 크기의 변화를 함께 보여줄 때 쓴다 */
+    area?: boolean;
+    /**
+     * 계열을 겹쳐 그리는 대신 **아래 계열 위에 쌓는다**. 전체의 크기와 그 안의 구성을
+     * 함께 볼 때 쓴다 — 맨 위 선이 곧 합계다. 툴팁은 쌓기 전 각 계열의 값을 보여준다
+     */
+    stacked?: boolean;
+    /** 색 팔레트. `custom` 일 때만 `colors` 를 본다 */
+    palette?: SLineChartPalette;
+    /** `palette='custom'` 에서 쓸 색 이름을 계열 순서대로. 계열보다 짧으면 앞에서부터 순환한다 */
+    colors?: SLineChartColor[];
+    /** 값 축의 최댓값. 주지 않으면 데이터에서 읽기 좋은 값으로 정한다 */
+    max?: number;
+    /** 값 축 눈금 개수 */
+    tickCount?: number;
+    /** 데이터 지점마다 점을 찍는다. 꺼도 짚은 항목의 점은 뜬다 */
+    showPoint?: boolean;
+    /**
+     * 점마다 값을 적는다. 기본은 끔 — 선 그래프는 항목이 많은 데이터에 쓰는 일이 잦아
+     * 숫자가 서로 붙는다. 항목이 대여섯 개 안쪽일 때만 켠다
+     */
+    showValueLabel?: boolean;
+    /** 범례를 보인다 */
+    showLegend?: boolean;
+    /** 범례 위치 */
+    legendPosition?: SLineChartLegendPosition;
+    /** 항목에 마우스를 올리면 값 상자를 띄운다 */
+    showTooltip?: boolean;
+    /** 값 표시 형식 */
+    formatValue?: (value: number) => string;
+    /** 차트 높이. **아래 축 텍스트까지 포함한 값**이다 — 그림은 그만큼 줄어든다 */
+    height?: number | string;
+    /** 점을 눌렀을 때 */
+    onPointClick?: (point: SLineChartPoint) => void;
+    /**
+     * 툴팁의 값 아래에 덧붙일 내용. 짚은 항목을 받아 그린다 — 계열 값만으로 모자란 맥락
+     * (합계, 전월 대비 등)을 적는다. 툴팁은 누를 수 없으므로 버튼·링크는 넣지 않는다
+     */
+    tooltipFooter?: (category: SLineChartTooltipCategory) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * SLineChart — 꺾은선 그래프.
+ *
+ * 항목의 순서에 뜻이 있을 때(기간별 추이) 쓴다. 순서가 없는 항목끼리 크기를 견주는
+ * 것이 목적이면 `SBarChart` 가 맞다 — 선은 "이어진다" 는 뜻을 덤으로 얹는다.
+ *
+ * 값 축은 막대 차트와 마찬가지로 **항상 0 을 포함한다.** 0 을 잘라 확대하면 같은 데이터가
+ * 훨씬 가파른 변화로 보인다.
+ */
+export declare const SLineChart: import("react").ForwardRefExoticComponent<SLineChartProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1 @@
+export { SLineChart, type SLineChartProps, type SLineChartSeries, type SLineChartPoint, type SLineChartTooltipCategory, type SLineChartCurve, type SLineChartPalette, type SLineChartColor, type SLineChartLegendPosition, } from './SLineChart';

package/dist/components/SLineChart/lineChart.config.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SLineChart 의 치수·색 상수와 선·영역 경로 계산.
+ *
+ * 선·점 고유의 값은 `chart.line.*` 토큰이 정한다. 두 차트가 공유하는 것
+ * (눈금·격자·툴팁·범례·팔레트·값 라벨)은 새로 정하지 않고 바 차트와 `lib/chart` 에서
+ * 그대로 가져온다 — 같은 데이터를 막대에서 선으로 바꿨을 때 눈금이 어긋나면 두 차트를
+ * 견줄 수 없다. 단 항목 축 양끝 여백(`AXIS_EDGE_PADDING`)은 쓰지 않는다 — 선은
+ * 첫·마지막 점이 그림 양끝에 선다.
+ *
+ * **점의 치수는 토큰을 `var()` 로 넘기지 못하고 숫자로 베껴 둔다.** 점 자리가 툴팁이
+ * 비켜설 거리·값 라벨의 높이·스크롤 컨테이너의 여유 폭을 정하는 데 쓰여, 그리기 전에
+ * JS 가 그 수를 알아야 하기 때문이다. 막대의 `BAR_RADIUS` 와 같은 규칙으로, 각 상수에
+ * 어느 토큰을 베꼈는지 적어 둔다. 색·불투명도처럼 그리기만 하는 것은 토큰을 직접 참조한다.
+ *
+ * **토큰 이름이 `bar` 로 시작하는 것을 그대로 쓰는 자리가 남아 있다** — 짚은 항목의
+ * 바탕(`--cmp-chart-barContainer-*`)이 그렇다. 이름만 막대 것이고 뜻은 "짚은 항목의
+ * 바탕" 이라, 선 차트에서 값을 따로 정하면 같은 자리가 차트마다 달라진다.
+ *
+ * 값 라벨의 색·타이포는 `chart.dataLabel.*` 로 막대 밖으로 나와 이제 공용 토큰이다.
+ */
+/** 선 두께 — 토큰 `chart.line.width`. SVG 표현 속성은 `var()` 를 못 풀어 `style` 로 넘긴다. */
+export declare const LINE_WIDTH = "var(--cmp-chart-line-width)";
+/**
+ * 선의 불투명도 — 토큰 `chart.line.opacity`.
+ *
+ * 선은 한 겹 물러나 있고 점이 앞에 선다. 차트 공용 기본값(`chart.opacity.default`)이
+ * "라인 제외" 라고 못박은 것도 이 때문이다 — 선만 다른 값을 쓴다. 짚었을 때도 그대로다:
+ * 선이 진해지면 굵기 탓에 짚지 않은 이웃 계열까지 덮는다.
+ */
+export declare const LINE_OPACITY = "var(--cmp-chart-line-opacity)";
+/**
+ * 점선 패턴(SVG `stroke-dasharray`, px) — dash 11·gap 11.
+ *
+ * `chart.line.*` 에 점선 토큰이 없어 시안 SVG 실측값을 그대로 옮긴다(선 두께 4px 기준
+ * dash:gap = 1:1). 토큰이 아니므로 두께가 바뀌면 이 값도 함께 검토해야 한다.
+ */
+export declare const LINE_DASH = "11 11";
+/** 점의 반지름(px) — 토큰 `chart.line.point.size.default`(지름 10)의 절반. */
+export declare const POINT_RADIUS = 5;
+/** 짚은 항목의 점 — 토큰 `chart.line.point.size.hover`(지름 12)의 절반. 색은 그대로고 커지기만 한다. */
+export declare const POINT_HOVER_RADIUS = 6;
+/**
+ * 짚은 점을 감싸는 바탕 원의 반지름(px) — 토큰 `chart.line.point.size.bg`(지름 24)의 절반.
+ *
+ * 계열 색을 옅게 깐 원이다(`chart.line.point.opacity.bg`). 점 둘레를 비우는 것이 아니라
+ * **점보다 넓은 같은 색 자리**를 만들어, 계열이 여럿이어도 어느 선의 점을 짚었는지가 색으로 읽힌다.
+ */
+export declare const POINT_HALO_RADIUS = 12;
+export declare const POINT_HALO_OPACITY = "var(--cmp-chart-line-point-opacity-bg)";
+/**
+ * 짚은 점이 실제로 차지하는 반지름 — 바탕 원까지다. 툴팁이 이만큼 비켜서고,
+ * 양끝 점이 잘리지 않게 스크롤 컨테이너도 이만큼 넓어진다.
+ */
+export declare const POINT_HOVER_EXTENT = 12;
+/**
+ * 항목 하나가 가져야 할 최소 폭(px).
+ *
+ * 막대 차트의 최소 band(여백 8 + 막대 24 + 여백 8)와 같은 값이다 — 같은 데이터에서
+ * 두 차트의 스크롤 시점이 같아야 한다. 이보다 좁아지면 점이 서로 붙고 항목 이름이
+ * 겹치므로, 좁히는 대신 가로로 스크롤한다.
+ */
+export declare const BAND_MIN = 40;
+/** 점과 값 라벨 사이 간격(px) — 토큰 `chart.line.point.gap`. 막대(6)와 달리 선은 4 다. */
+export declare const VALUE_LABEL_GAP = 4;
+/**
+ * 영역 채움의 불투명도 — 선 바로 아래가 가장 진하고 바닥으로 갈수록 옅어진다.
+ *
+ * 선은 또렷하게 두고 영역만 물리는 값이다. 세로 그라데이션이라 채움이 바닥에서 거의
+ * 사라져, 계열이 여럿일 때 채움끼리 겹쳐 색이 탁해지는 것도 덜하다. 그래도 겹쳐 그리는
+ * 것 자체의 한계는 남으므로, 계열이 많으면 `area` 를 끄거나 `stacked` 로 쌓는다.
+ *
+ * 위·아래 값은 `chart.line.area.gradation.start|end` 가 정한다.
+ */
+export declare const AREA_OPACITY_TOP = "var(--cmp-chart-line-area-gradation-start)";
+export declare const AREA_OPACITY_BOTTOM = "var(--cmp-chart-line-area-gradation-end)";
+export declare const LINE_DATA_LABEL_COLOR = "var(--cmp-chart-dataLabel-color-default)";
+/** 값 라벨의 타이포 — 짚은 항목만 굵고 크게 뜬다(막대 차트와 같은 규칙). */
+export declare const LINE_DATA_LABEL_TYPO = "typo-body-sm-medium";
+export declare const LINE_DATA_LABEL_TYPO_HOVER = "typo-body-md-bold";
+/** 그림 좌표계의 한 점(px). */
+export interface ChartPoint {
+    x: number;
+    y: number;
+}
+/**
+ * 이어진 점들을 지나는 선. 점이 하나뿐이면 그릴 선이 없다(점만 남는다).
+ */
+export declare function linePath(points: ChartPoint[], smooth: boolean): string;
+/**
+ * 위 선과 아래 선 사이를 채우는 영역.
+ *
+ * 아래 선을 **역순으로** 이어 닫는다. 곡선일 때 아래 선도 같은 방식으로 휘어야 하므로
+ * 직선으로 질러가지 않고 다시 보간한다 — 안 그러면 채움이 곡선 아래로 삐져나온다.
+ */
+export declare function areaPath(top: ChartPoint[], bottom: ChartPoint[], smooth: boolean): string;

package/dist/components/SLinearProgress/README.md

@@ -9,9 +9,24 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `value?` | `number` | `0` | 진행률 (0–100) |
-| `type?` | `SLinearProgressType` | `'primary'` | 색상 타입 |
+| `type?` | `SLinearProgressType` | `'primary'` | 진행 상태 - `primary`: 정상 진행 중 - `warning`: 진행 중이지만 설정된 기준에 미달해 주의가 필요하다 (기준은 제품이 정한다) - `error`: 실패·중단 등 더 이상 정상적으로 진행되지 않는다 - `complete`: 완료 |
+| `size?` | `SLinearProgressSize` | `'sm'` | 바 높이. xs 는 바 안에 퍼센트 텍스트를 넣지 않는다 |
 | `indeterminate?` | `boolean` | `false` | 진행률 없이 무한 애니메이션 |
 | `label?` | `string` | — | 하단 레이블 |
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
 
+## Types
+
+### SLinearProgressType
+
+```ts
+export type SLinearProgressType = 'primary' | 'warning' | 'error' | 'complete';
+```
+
+### SLinearProgressSize
+
+```ts
+export type SLinearProgressSize = 'xs' | 'sm' | 'md';
+```
+

package/dist/components/SLinearProgress/SLinearProgress.d.ts

@@ -1,10 +1,19 @@
 import { type CSSProperties } from 'react';
-export type SLinearProgressType = 'primary' | 'error' | 'complete';
+export type SLinearProgressType = 'primary' | 'warning' | 'error' | 'complete';
+export type SLinearProgressSize = 'xs' | 'sm' | 'md';
 export interface SLinearProgressProps {
     /** 진행률 (0–100) */
     value?: number;
-    /** 색상 타입 */
+    /**
+     * 진행 상태
+     * - `primary`: 정상 진행 중
+     * - `warning`: 진행 중이지만 설정된 기준에 미달해 주의가 필요하다 (기준은 제품이 정한다)
+     * - `error`: 실패·중단 등 더 이상 정상적으로 진행되지 않는다
+     * - `complete`: 완료
+     */
     type?: SLinearProgressType;
+    /** 바 높이. xs 는 바 안에 퍼센트 텍스트를 넣지 않는다 */
+    size?: SLinearProgressSize;
     /** 진행률 없이 무한 애니메이션 */
     indeterminate?: boolean;
     /** 하단 레이블 */

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

@@ -1 +1 @@
-export { SLinearProgress, type SLinearProgressProps, type SLinearProgressType, } from './SLinearProgress';
+export { SLinearProgress, type SLinearProgressProps, type SLinearProgressType, type SLinearProgressSize, } from './SLinearProgress';

package/dist/components/SList/README.md

@@ -9,8 +9,16 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `children?` | `ReactNode` | — | 리스트 컨테이너 내부에 렌더링할 내용 |
-| `useGap?` | `boolean` | `false` | 리스트 아이템 사이 gap 토큰 적용 여부 |
-| `usePadding?` | `boolean` | `false` | 리스트 컨테이너 padding 토큰 적용 여부 |
+| `gap?` | `boolean` | `false` | 리스트 아이템 사이 gap 토큰 적용 여부 |
+| `padding?` | `SListPadding` | `'none'` | 컨테이너 안쪽 여백. 기본은 `none` — 목록이 담긴 면이 이미 여백을 쥔 경우가 많다. 목록이 배경 위에 직접 얹혀 스스로 여백을 쥐어야 할 때만 `default`. |
+
+## Types
+
+### SListPadding
+
+```ts
+export type SListPadding = 'default' | 'none';
+```
 
 ## Dependencies
 
@@ -19,10 +27,15 @@
  - [SDraggableList](../SDraggableList)
  - [SExpansionList](../SExpansionList)
 
+### Depends on
+
+- [SDivider](../SDivider)
+
 ### Graph
 
 ```mermaid
 graph TD;
+  SList --> SDivider
   SDraggableList --> SList
   SExpansionList --> SList
   style SList fill:#f9f,stroke:#333,stroke-width:4px

package/dist/components/SList/SList.d.ts

@@ -1,10 +1,14 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
+export type SListPadding = 'default' | 'none';
 export interface SListProps extends HTMLAttributes<HTMLDivElement> {
     /** 리스트 컨테이너 내부에 렌더링할 내용 */
     children?: ReactNode;
     /** 리스트 아이템 사이 gap 토큰 적용 여부 */
-    useGap?: boolean;
-    /** 리스트 컨테이너 padding 토큰 적용 여부 */
-    usePadding?: boolean;
+    gap?: boolean;
+    /**
+     * 컨테이너 안쪽 여백. 기본은 `none` — 목록이 담긴 면이 이미 여백을 쥔 경우가 많다.
+     * 목록이 배경 위에 직접 얹혀 스스로 여백을 쥐어야 할 때만 `default`.
+     */
+    padding?: SListPadding;
 }
 export declare const SList: import("react").ForwardRefExoticComponent<SListProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -1 +1 @@
-export { SList, type SListProps } from './SList';
+export { SList, type SListPadding, type SListProps } from './SList';

package/dist/components/SListItem/README.md

@@ -11,18 +11,59 @@
 | `title` | `SListItemSlot` | — | 리스트 아이템 제목 |
 | `supportingText?` | `SListItemSlot` | — | 제목을 보조하는 텍스트 |
 | `supportingTextPosition?` | `SListItemSupportingTextPosition` | `'right'` | 보조 텍스트 위치 |
-| `depth?` | `1 \| 2 \| 3` | `1` | 중첩 단계. Figma 기준 1~3단계 |
+| `depth?` | `1 \| 2 \| 3` | `1` | 중첩 단계. Figma 기준 1~3단계. `SExpansionList` 안에서는 주지 않아도 중첩에서 정해진다 — 직접 주면 그 값이 우선한다. |
 | `leading?` | `SListItemSlot` | — | 타이틀 앞에 표시할 아이콘/콘텐츠 |
 | `trailing?` | `SListItemSlot` | — | 타이틀 뒤에 표시할 태그/콘텐츠 |
 | `bordered?` | `boolean` | `false` | 외곽 테두리 사용 여부 |
 | `selected?` | `boolean` | `false` | 선택 상태 여부. `clickable` 이 false 면 무시된다 |
-| `clickable?` | `boolean` | `false` | 클릭 가능 상태 여부. hover·selected·chevron 등 인터랙션 표현이 여기에 딸린다 |
+| `clickable?` | `boolean` | `false` | 클릭 가능 상태 여부. hover·selected·chevron 등 인터랙션 표현이 여기에 딸린다. `SExpansionList` 안에서는 기본으로 켜진다 — 표시 전용이면 `false` 를 준다. **`onClick` 까지 주면 키보드로도 누를 수 있다** — 항목이 `role="button"` 으로 Tab 순서에 들고, Enter·Space 가 `onClick` 을 부른다. 앱이 `role`·`tabIndex` 를 직접 주면 그 값이 우선한다. `onClick` 이 없으면 눌러도 일어날 일이 없으므로 Tab 순서에 넣지 않는다. |
 | `interaction?` | `SListItemInteraction` | — | hover/selected 상태에서 적용할 인터랙션 preset |
 | `accentStripe?` | `boolean` | `false` | 아이템 왼쪽 accent stripe 표시 여부 |
 | `dense?` | `boolean` | `false` | 조밀한 높이 사용 여부 |
 | `size?` | `SListItemSize` | `'sm'` | 타이포그래피 크기 |
 | `disabled?` | `boolean` | `false` | 비활성 상태 여부 |
 
+## Types
+
+### SListItemSlot
+
+```ts
+export type SListItemSlot = ReactNode | SListItemRenderProp;
+```
+
+### SListItemSupportingTextPosition
+
+```ts
+export type SListItemSupportingTextPosition = 'right' | 'bottom';
+```
+
+### SListItemInteraction
+
+```ts
+export type SListItemInteraction = 'chevron';
+```
+
+### SListItemSize
+
+```ts
+export type SListItemSize = 'sm' | 'md';
+```
+
+### SListItemRenderProp
+
+```ts
+export type SListItemRenderProp = (state: SListItemRenderState) => ReactNode;
+```
+
+### SListItemRenderState
+
+```ts
+export interface SListItemRenderState {
+  hovered: boolean;
+  disabled: boolean;
+}
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SListItem/SListItem.d.ts

@@ -15,7 +15,10 @@ export interface SListItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'ch
     supportingText?: SListItemSlot;
     /** 보조 텍스트 위치 */
     supportingTextPosition?: SListItemSupportingTextPosition;
-    /** 중첩 단계. Figma 기준 1~3단계 */
+    /**
+     * 중첩 단계. Figma 기준 1~3단계.
+     * `SExpansionList` 안에서는 주지 않아도 중첩에서 정해진다 — 직접 주면 그 값이 우선한다.
+     */
     depth?: 1 | 2 | 3;
     /** 타이틀 앞에 표시할 아이콘/콘텐츠 */
     leading?: SListItemSlot;
@@ -25,7 +28,14 @@ export interface SListItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'ch
     bordered?: boolean;
     /** 선택 상태 여부. `clickable` 이 false 면 무시된다 */
     selected?: boolean;
-    /** 클릭 가능 상태 여부. hover·selected·chevron 등 인터랙션 표현이 여기에 딸린다 */
+    /**
+     * 클릭 가능 상태 여부. hover·selected·chevron 등 인터랙션 표현이 여기에 딸린다.
+     * `SExpansionList` 안에서는 기본으로 켜진다 — 표시 전용이면 `false` 를 준다.
+     *
+     * **`onClick` 까지 주면 키보드로도 누를 수 있다** — 항목이 `role="button"` 으로 Tab 순서에 들고,
+     * Enter·Space 가 `onClick` 을 부른다. 앱이 `role`·`tabIndex` 를 직접 주면 그 값이 우선한다.
+     * `onClick` 이 없으면 눌러도 일어날 일이 없으므로 Tab 순서에 넣지 않는다.
+     */
     clickable?: boolean;
     /** hover/selected 상태에서 적용할 인터랙션 preset */
     interaction?: SListItemInteraction;

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

@@ -1 +1 @@
-export { SListItem, type SListItemProps, type SListItemSupportingTextPosition } from './SListItem';
+export { SListItem, type SListItemInteraction, type SListItemProps, type SListItemRenderProp, type SListItemRenderState, type SListItemSize, type SListItemSlot, type SListItemSupportingTextPosition, } from './SListItem';

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

@@ -1,2 +1,2 @@
 export { SLoadingContainer, type SLoadingContainerProps } from './SLoadingContainer';
-export { loading, SLoadingViewport } from './loading';
+export { loading, type SLoadingHandle } from './loading';

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

@@ -1,10 +1,45 @@
-/** 오버레이 뷰포트 — 스토어를 구독해 SLoadingContainer 를 렌더한다. 직접 배치도 가능. */
-export declare function SLoadingViewport(): import("react").JSX.Element;
+/**
+ * `show()` 가 돌려주는 핸들 — **이 호출 하나**만 걷고 갱신한다.
+ * 부르면 걷고, `update()` 로 이 호출의 메시지만 바꾼다. 둘 다 id 기준이라 겹친 다른 작업의
+ * 항목은 건드리지 않는다. (Quasar `Loading.show()` 가 돌려주는 그룹 함수와 같은 자리다.)
+ */
+export interface SLoadingHandle {
+    (): void;
+    update(options: {
+        message?: string;
+    }): void;
+}
 export declare const loading: {
-    /** 로딩 오버레이 표시 (메시지 갱신도 동일 호출) */
+    /**
+     * 로딩 오버레이 표시. 겹쳐 부르면 그만큼 쌓이고 **마지막 하나가 걷힐 때** 닫힌다.
+     * 반환값은 이 호출 하나를 걷고 갱신하는 핸들이다(두 번 걷어도 한 번만 걷힌다).
+     *
+     * **걷는 것은 `finally` 에 둔다.** 빠뜨리면 그 즉시 화면이 갇히고, 정상 경로에서는 아무
+     * 표시가 없다.
+     *
+     * ```ts
+     * const done = loading.show({ message: '1/2 ...' });
+     * try {
+     *   done.update({ message: '2/2 ...' });   // 이 호출의 메시지만 바뀐다
+     *   await api.submit(payload);
+     * } finally {
+     *   done();                                // 이 호출만 걷는다
+     * }
+     * ```
+     *
+     * ⚠️ **메시지를 바꾸려고 `show()` 를 다시 부르지 않는다.** 하나 더 쌓여 한 번 걷는 것으로는
+     * 닫히지 않는다. 핸들의 `update()` 를 쓴다. (참조 카운트 이전에는 `show()` 를 다시 부르는
+     * 것이 갱신이었다 — Quasar 도 같은 그룹에 다시 show 하면 갱신이다. 그 시절 관행대로 쓰인
+     * 코드는 지금 오버레이를 하나 남긴다.)
+     */
     show(options?: {
         message?: string;
-    }): void;
-    /** 로딩 오버레이 숨김 */
-    hide(): void;
+    }): SLoadingHandle;
+    /**
+     * 쌓인 것을 모두 걷고 즉시 닫는다. **원본(Quasar)의 인자 없는 `hide()` 가 이것이다.**
+     * 화면 전환·에러 복구처럼 진행 중이던 작업의 짝을 더는 맞출 수 없을 때만 쓴다 — 평소에는
+     * `show()` 가 준 핸들로 걷는다.
+     * 이걸로 걷힌 항목의 주인이 뒤늦게 자기 핸들을 불러도 아무 일도 일어나지 않는다.
+     */
+    hideAll(): void;
 };

package/dist/components/SLoadingModal/README.md

@@ -10,10 +10,10 @@
 |------|------|---------|-------------|
 | `open?` | `boolean` | — |  |
 | `persistent?` | `boolean` | — | 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). **기본값 true** |
-| `state?` | `LoadingModalState` | `'loading'` | 상태 (loading: 스피너, error: 경고 아이콘) |
+| `state?` | `SLoadingModalState` | `'loading'` | 상태 (loading: 스피너, error: 경고 아이콘) |
 | `progress?` | `number` | — | 진행률 (0–100) — 지정 시 determinate 스피너 |
 | `message?` | `string \| string[]` | — | 메시지 (없으면 state 기본값) |
-| `useButton?` | `boolean` | `false` | 하단 버튼 표시 |
+| `showButton?` | `boolean` | `false` | 하단 버튼 표시 |
 | `buttonLabel?` | `string` | — | 버튼 레이블 (없으면 state 기본값) |
 | `width?` | `number \| string` | `520` |  |
 | `height?` | `number \| string` | `320` |  |
@@ -26,6 +26,14 @@
 | `onClose` | `() => void` | 닫기(X) 버튼 클릭 (sdClose) — error 상태에서만 노출 |
 | `onButtonClick` | `() => void` | 버튼 클릭 (sdClick) |
 
+## Types
+
+### SLoadingModalState
+
+```ts
+export type SLoadingModalState = 'loading' | 'error';
+```
+
 ## Dependencies
 
 ### Used by