sellmate-design-system-react 9.0.0-beta.48 → 9.0.0-beta.49

package/dist/lib/chart/cartesian.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 직교 좌표 차트(bar·line)의 눈금 장치 — 격자선·기준선·눈금 라벨.
+ * 파이·도넛은 이 파일을 쓰지 않는다.
+ *
+ * 격자선은 그림과 같은 좌표계에 있어야 하므로 **SVG 안**에, 눈금 라벨은 글자 폭이
+ * 열 너비를 정해야 하므로 **SVG 밖 HTML** 에 둔다. 둘은 같은 비율(`ratioOf`)로
+ * 위치를 계산하므로 어긋나지 않는다.
+ */
+import type { CSSProperties, Ref } from 'react';
+import { type ChartScale } from './scale';
+import type { SChartDirection } from './types';
+/** 눈금 라벨과 그림 사이 간격 — 시안 실측 8px. */
+export declare const AXIS_LABEL_GAP = 8;
+export interface ChartGridProps {
+    scale: ChartScale;
+    direction: SChartDirection;
+    /** 그림 영역 크기(px) */
+    width: number;
+    height: number;
+}
+/**
+ * 격자선 + 기준선. `<svg>` 안에 넣는다.
+ *
+ * 기준선(0)은 격자선보다 진하다 — 막대가 어디서 자라기 시작하는지가 눈금 하나보다
+ * 중요한 정보라서다. 음수가 없으면 기준선은 자연히 축의 끝에 놓인다.
+ */
+export declare function ChartGrid({ scale, direction, width, height }: ChartGridProps): import("react").JSX.Element;
+export interface ChartAxisLabelsProps {
+    scale: ChartScale;
+    direction: SChartDirection;
+    /** 값 → 표시 문자열 */
+    format: (value: number) => string;
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * 자리를 잡아 주는 사본 라벨. 이 크기가 곧 **가장 큰 라벨의 크기**라, 호출 쪽은
+     * 이걸 재서 그림을 그만큼 안으로 물린다 — 끝 눈금이 차트 밖으로 나가지 않는다.
+     */
+    sampleRef?: Ref<HTMLSpanElement>;
+}
+/**
+ * 눈금 라벨.
+ * - 세로 차트: 세로 열 하나(그림 왼쪽). 각 라벨이 자기 격자선 높이에 중앙 정렬된다.
+ * - 가로 차트: 가로 행 하나(그림 아래). 각 라벨이 자기 격자선 x 에 중앙 정렬된다.
+ */
+export declare function ChartAxisLabels({ scale, direction, format, className, style, sampleRef, }: ChartAxisLabelsProps): import("react").JSX.Element;

package/dist/lib/chart/frame.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 차트 바깥 틀 — 패딩·배경과 "범례 / 그림" 두 칸의 세로 배치.
+ * 그림이 무엇인지(막대·선·파이)는 알지 않는다.
+ */
+import { type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+import type { SChartLegendPosition } from './types';
+export interface ChartFrameProps extends HTMLAttributes<HTMLDivElement> {
+    /** 범례 — 없으면 칸 자체가 사라진다 */
+    legend?: ReactNode;
+    /** 범례 위치 */
+    legendPosition?: SChartLegendPosition;
+    /** 그림 영역 */
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+export declare const ChartFrame: import("react").ForwardRefExoticComponent<ChartFrameProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/lib/chart/legend.d.ts

@@ -0,0 +1,15 @@
+export interface ChartLegendItem {
+    /** 계열 이름 */
+    name: string;
+    /** 점 색 (CSS 색 문자열) */
+    color: string;
+}
+export interface ChartLegendProps {
+    items: ChartLegendItem[];
+    /** 가로 정렬 — 시안은 그림 위 가운데다 */
+    align?: 'start' | 'center' | 'end';
+    /** 지금 강조 중인 계열. 나머지는 흐려진다 */
+    activeIndex?: number | null;
+    className?: string;
+}
+export declare function ChartLegend({ items, align, activeIndex, className }: ChartLegendProps): import("react").JSX.Element | null;

package/dist/lib/chart/palette.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 차트 팔레트 — `--cmp-chart-palette-*` 를 계열 인덱스로 고르는 규칙.
+ *
+ * 계열이 팔레트 색 수보다 많으면 앞에서부터 **순환**한다. 색이 반복되면 범례로만
+ * 구분되므로, 계열이 많을 때는 `multi`(11색) 를 쓰는 편이 낫다.
+ */
+import type { SChartColor, SChartPalette } from './types';
+/**
+ * `custom` 팔레트에서 고를 수 있는 색. 이름이 뜻을 갖고 있으므로
+ * (positive=늘어남, negative=줄어듦, neutral=변화 없음) 뜻에 맞게 고른다.
+ */
+export declare const CHART_COLORS: Record<SChartColor, string>;
+/**
+ * 색을 고르지 않는 팔레트들의 색 목록. 순서가 곧 계열 순서다.
+ *
+ * `gradation` 은 진한 쪽(1)부터 옅은 쪽(6)으로 간다 — 계열 순서가 크기 순서를
+ * 나타내는 팔레트라 첫 계열이 가장 진해야 눈에 먼저 들어온다.
+ */
+export declare const CHART_PALETTES: Record<Exclude<SChartPalette, 'custom'>, readonly string[]>;
+/**
+ * 계열 인덱스 → 색.
+ *
+ * `custom` 은 `colors` 로 받은 이름 배열을 순서대로 쓴다. 배열이 비어 있으면
+ * 고를 것이 없으므로 `default` 로 떨어진다 — 색이 없어 아무것도 안 보이는 것보다 낫다.
+ */
+export declare function paletteColor(palette: SChartPalette, index: number, colors?: readonly SChartColor[]): string;

package/dist/lib/chart/scale.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 값 축 스케일 — 데이터 범위를 "읽기 좋은 눈금"으로 바꾸고, 값을 픽셀로 옮긴다.
+ * 직교 좌표를 쓰는 차트(bar·line)가 공유한다.
+ */
+export interface ChartScale {
+    /** 눈금 최솟값 (음수가 있으면 0보다 작다) */
+    min: number;
+    /** 눈금 최댓값 */
+    max: number;
+    /** 축에 그릴 눈금값 — 작은 값부터 */
+    ticks: number[];
+}
+/**
+ * 데이터 범위에서 눈금을 만든다.
+ *
+ * - 0 은 항상 범위에 포함한다. 막대는 0 에서 자라므로 기준선이 축 안에 있어야 한다.
+ * - `fixedMax` 를 주면 위쪽 끝을 그 값으로 고정한다(데이터가 넘으면 넘은 채로 그린다).
+ * - 값이 전부 0 이거나 데이터가 없으면 `0..tickCount-1` 의 밋밋한 축을 돌려준다 —
+ *   축이 통째로 사라지는 것보다 빈 격자가 남는 편이 "데이터가 없다" 를 더 잘 보여 준다.
+ */
+export declare function niceScale(values: number[], tickCount: number, fixedMax?: number): ChartScale;
+/**
+ * 값 → 축 위의 비율(0~1). `min` 이 0, `max` 가 1 이다.
+ * 픽셀 변환은 방향(위로 자라는지 오른쪽으로 자라는지)을 아는 쪽에서 한다.
+ */
+export declare function ratioOf(value: number, scale: ChartScale): number;

package/dist/lib/chart/tooltip.d.ts

@@ -0,0 +1,23 @@
+export interface ChartTooltipItem {
+    /** 계열 점 색 */
+    color: string;
+    /** 계열 이름 */
+    label: string;
+    /** 표시할 값 (이미 포맷된 문자열) */
+    value: string;
+}
+export interface ChartTooltipProps {
+    /** 상자 제목 — 보통 카테고리 이름 */
+    title: string;
+    items: ChartTooltipItem[];
+    /** 컨테이너 기준 좌표(px) */
+    x: number;
+    y: number;
+    /** 상자가 넘치면 안 되는 범위(px). 보통 그림 영역 크기다 */
+    bounds?: {
+        width: number;
+        height: number;
+    };
+    className?: string;
+}
+export declare function ChartTooltip({ title, items, x, y, bounds, className }: ChartTooltipProps): import("react").JSX.Element;

package/dist/lib/chart/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 차트 공용 타입.
+ *
+ * `src/lib/chart/*` 는 차트 컴포넌트들이 나눠 쓰는 **비공개 구현**이다 — `src/index.ts`
+ * 로 내보내지 않는다. 소비자가 쓰는 이름(`SBarChartPalette` 등)은 각 컴포넌트가 같은
+ * 값을 **다시 선언**한다: docs:gen 이 컴포넌트 디렉토리만 훑기 때문에, 여기 둔 타입은
+ * README 에 뜻이 실리지 않는다. 두 선언이 어긋나면 컴파일이 깨진다.
+ *
+ * `src/components/chart/` 가 아니라 lib 에 두는 이유: components 아래 폴더는 전부
+ * "스토리·playground 를 가진 공개 컴포넌트" 로 취급돼 `check:docs` 가 데모 누락을
+ * 지적한다. 여기는 그런 대상이 아니다.
+ */
+/**
+ * 색 팔레트.
+ * - `default` 파랑 한 색. 계열이 하나거나 색으로 나눌 것이 없을 때
+ * - `multi` 서로 무관한 항목(11색)을 순서대로
+ * - `gradation` 한 지표의 단계(6색)를 진한 쪽부터 순서대로
+ * - `custom` `colors` 로 고른 색을 순서대로
+ */
+export type SChartPalette = 'default' | 'multi' | 'gradation' | 'custom';
+/**
+ * `custom` 팔레트에서 고를 수 있는 색 이름.
+ * positive=늘어남 · negative=줄어듦 · neutral=변화 없음 을 뜻한다.
+ */
+export type SChartColor = 'positivePrimary' | 'positiveSecondary' | 'negativePrimary' | 'negativeSecondary' | 'neutralPrimary' | 'neutralSecondary';
+/** 막대가 자라는 방향 */
+export type SChartDirection = 'vertical' | 'horizontal';
+/** 범례 위치 */
+export type SChartLegendPosition = 'top' | 'bottom';

package/dist/lib/chart/use-element-size.d.ts

@@ -0,0 +1,17 @@
+export interface ElementSize {
+    width: number;
+    height: number;
+}
+/**
+ * 요소의 실제 픽셀 크기를 관찰한다.
+ *
+ * 차트는 막대 두께·간격이 px 고정값이라 그림을 픽셀 좌표로 그려야 한다 — viewBox 로
+ * 늘려 맞추면 막대만 굵어지고 글자가 찌그러진다. 그래서 그릴 면적을 먼저 재고,
+ * 그 안에 1:1 로 그린다.
+ *
+ * 첫 렌더에서는 `{0, 0}` 이다. 크기가 0 인 동안은 그리지 않는 쪽이 안전하다.
+ */
+export declare function useElementSize<T extends HTMLElement>(): {
+    ref: import("react").RefObject<T | null>;
+    size: ElementSize;
+};

package/dist/llms-full.txt

@@ -26,6 +26,19 @@
 
 "비슷하게 생긴 것을 직접 만드는 것"이 어색함의 가장 큰 원인이다. 대응 컴포넌트를 쓰면 색·간격·상태·접근성이 전부 따라온다.
 
+### 0-0. 화면을 짜기 전에 — 세 가지 질문
+
+**컴포넌트를 고르기 전에 이 세 가지에 답한다.** 요청에 답이 없으면 추측해서 채우지 말고 **되묻는다.**
+
+1. 이 화면에서 사용자가 하려는 **단 하나의 일**은 무엇인가
+2. 그 일을 끝내는 데 **없어도 되는 것**은 무엇인가 — 컬럼·버튼·안내 문구 중 빼도 되는 것
+3. **실패하면** 어디로 돌아가는가 — 오류·빈 목록·권한 없음일 때 무엇을 보여줄지
+
+요청받은 것을 그대로 다 넣지 않는다. **"있을 법한 필드를 빠짐없이 채우는 것"이 화면을 망치는 가장 흔한 방식이다.**
+목록에 컬럼을, 폼에 입력란을, 툴바에 버튼을 하나 더 넣기는 쉽고 나중에 빼기는 어렵다. 2번은 그래서 있다.
+
+2번에 답이 하나도 없으면 아직 화면을 이해하지 못한 것이다. 그 상태로 코드를 쓰면 미정 상태가 그대로 화면이 된다.
+
 ### 0-1. 전체 컴포넌트 인덱스
 
 무엇을 만들지 정했으면 **이 표에서 먼저 찾는다.** 상세 Props·Types 는 `dist/components/<이름>/README.md` 참조.
@@ -40,6 +53,7 @@
 | **표·목록** | `SChatMessage`(대화의 메시지 한 건) `SChatAttachedFile`(입력창 위, 아직 보내지 않은 첨부 한 칸) `SChatFile`(대화 흐름에 선, 보낸 파일 한 칸) `SChatSystemMessage`(대화 흐름 가운데 서는 시스템 안내) `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SListItem` `SExpansionList` `SDraggableList` `SDraggableItem` `STree` |
 | **레이아웃** | `SLayout` `SGnb` `SGnbSystem` `SSystemActionButton`(GNB system 패널에 한 줄씩 쌓는 액션 행 — 버튼 고르기는 §3-5) `SAccountListBox`(계정 행을 눌러 뜨는 계정 패널) `SPage` `SPageHeader`(페이지 제목 영역 — `SLayout` 안에서 `SPage` 앞에 둔다) `SSectionHeaderCard` `SCard` `SLoginCard`(통합 계정 로그인 화면의 카드) `SDivider` `SSplitter` `SScrollArea` `SExpansionItem` |
 | **내비게이션** | `STabs` `SPagination` `SStepper` |
+| **차트** | `SBarChart`(막대 그래프 — 항목끼리 크기를 견준다) |
 | **표시·상태** | `STag` `SBadge` `SIcon` `SImage` `SCallout` `SGuide` |
 | **진행·로딩** | `SLinearProgress` `SCircleProgress` `SLoadingContainer` `SLoadingModal` |
 | **오버레이** | `STooltip` `SPopover` `SPopup` `SDrawer` `SPortal` |
@@ -161,7 +175,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 층 | 무엇인가 | 컴포넌트 |
 | --- | --- | --- |
 | **셸** | 앱 전체 뼈대. 페이지가 바뀌어도 남는다 | `SLayout` `SGnb` `SGnbSystem`(GNB 맨 아래 판 · 전폭 상단바 오른쪽 끝) `SPage` `SPageHeader`(`SLayout` 안에서 `SPage` 앞에 둔다) |
-| **블록** | `SPage` 의 직계 자식. 페이지를 세로로 쌓는 단위 | `SSectionHeaderCard` `SCard` `SChatMessage` `SChatSystemMessage` `SChatInput` `SLoginCard`(유일하게 `SPage` 밖에 선다 — 로그인 화면 자체가 자기 자리다, §4-6) `SForm` `SSplitter` `SScrollArea` `SCalendarBoard` `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SExpansionList` `SDraggableList` `STree` `SCallout` `STabs` `SStepper` `SPagination` `SDivider` |
+| **블록** | `SPage` 의 직계 자식. 페이지를 세로로 쌓는 단위 | `SSectionHeaderCard` `SCard` `SChatMessage` `SChatSystemMessage` `SChatInput` `SLoginCard`(유일하게 `SPage` 밖에 선다 — 로그인 화면 자체가 자기 자리다, §4-6) `SForm` `SSplitter` `SScrollArea` `SCalendarBoard` `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SExpansionList` `SDraggableList` `STree` `SCallout` `SBarChart` `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` `SChatAttachedFile` `SChatFile` `SImage` `SLinearProgress` `SCircleProgress` |
 | **인라인** | 텍스트 흐름·셀·라벨 안에 섞인다. 혼자 블록이 되지 않는다 | `STag` `SBadge` `SIcon` `STextLink` `SChip` |
 | **레이어** | 문서 흐름 **밖**에 떠서 그려진다. 어느 층에서 띄우든 레이아웃에 영향이 없다 | `SModal` `SActionModal` `SConfirmModal` `SPopup` `SDrawer` `SPopover` `STooltip` `SPortal` `SAccountListBox`(계정 행에 붙어 뜬다 — 직접 띄우지 않는다) `SToast` `SLoadingModal` `SLoadingContainer` `SGuide` |
@@ -535,6 +549,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 부모-자식 계층을 들여쓰기로 보여준다 | `STree` | §3-7-7 |
 | 사용자가 순서를 드래그로 바꾸게 한다 | `SDraggableList` + `SDraggableItem` | §3-7-6 |
 | 날짜별 일정을 한 달치 격자로 펼쳐 보여준다 | `SCalendarBoard` | §3-7-4 |
+| 항목끼리 크기를 눈으로 견주게 한다 (기간별 추이·채널별 비중) | `SBarChart` | 정확한 값을 읽어야 하면 `STable` — 그래프는 "어느 쪽이 큰가" 를 답하지 "얼마인가" 를 답하지 않는다 |
 | 표 위에 건수 요약과 액션을 얹는다 | `STableBar` | §4-2 |
 | 상태·분류를 라벨로 찍는다 | `STag` | §3-1 |
 | 색 점만으로 상태를 찍는다 | `SBadge` | §3-1 |
@@ -2406,7 +2421,7 @@ Tailwind 유틸리티는 아래 스케일에 있는 값만 사용한다. 리터
 - steelblue: 10 25 45 60 65 70 75 80 85 90 95 99
 - oceanblue: 15 25 50 60 65 70 75 80 85 90 95 99
 - brilliantblue: 10 20 25 40 50 60 70 75 80 85 90 95 99 05
-- bg: screen frame brand subtle accent accentLight accentBright accentFaint deep danger dangerLight warning caution progress success successLight neutralLight neutralBright tableHeader
+- bg: screen frame brand subtle accent accentLight accentBright accentFaint deep danger dangerLight warning caution progress success neutralLight neutralBright tableHeader
 - fg: primary secondary tertiary quaternary brand subtleWarm subtleCool deep success successLight dangerLight accent accentLight danger warning inverse
 - border: default strong bold accent accentLight danger warning success
 - disabled: bg text icon border
@@ -2501,7 +2516,6 @@ Tailwind 유틸리티는 아래 스케일에 있는 값만 사용한다. 리터
 --sys-color-bg-screen
 --sys-color-bg-subtle
 --sys-color-bg-success
---sys-color-bg-successLight
 --sys-color-bg-tableHeader
 --sys-color-bg-warning
 --sys-color-blue-strong
@@ -2726,6 +2740,112 @@ export const BADGE_COLORS = [
 
 ---
 
+# SBarChart
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SBarChart
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `categories` | `string[]` | — | 가로축(가로 막대면 세로축)에 놓일 항목 이름 |
+| `series` | `SBarChartSeries[]` | — | 계열 목록. 각 `data` 는 `categories` 와 같은 순서다 |
+| `direction?` | `SBarChartDirection` | `'vertical'` | 막대가 자라는 방향 |
+| `palette?` | `SBarChartPalette` | `'default'` | 색 팔레트. 계열이 하나면 계열 대신 **항목**마다 색이 바뀐다. `custom` 일 때만 `colors` 를 본다 |
+| `colors?` | `SBarChartColor[]` | — | `palette='custom'` 에서 쓸 색 이름을 계열 순서대로. 계열보다 짧으면 앞에서부터 순환한다 |
+| `max?` | `number` | — | 값 축의 최댓값. 주지 않으면 데이터에서 읽기 좋은 값으로 정한다 |
+| `tickCount?` | `number` | `8` | 값 축 눈금 개수 |
+| `barSize?` | `number` | `BAR_SIZE_MAX` | 막대 두께 상한(px, 24~80). 낮추면 좌우 여백 상한도 같은 비율로 따라 내려온다 |
+| `showValueLabel?` | `boolean` | `true` | 막대마다 값을 적는다 |
+| `showLegend?` | `boolean` | `true` | 범례를 보인다 |
+| `legendPosition?` | `SBarChartLegendPosition` | `'top'` | 범례 위치 |
+| `showTooltip?` | `boolean` | `true` | 막대에 마우스를 올리면 값 상자를 띄운다 |
+| `formatValue?` | `(value: number) => string` | `defaultFormat` | 값 표시 형식 |
+| `height?` | `number \| string` | — | 차트 높이. **아래 축 텍스트까지 포함한 값**이다 — 그림은 그만큼 줄어든다 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onBarClick` | `(point: SBarChartPoint) => void` | 막대를 눌렀을 때 |
+
+## Types
+
+### SBarChartSeries
+
+```ts
+/** 한 계열 — 범례 한 줄에 대응한다. */
+export interface SBarChartSeries {
+  /** 범례·툴팁에 표시할 이름 */
+  name: string;
+  /** `categories` 와 같은 순서의 값. 짧으면 남는 항목은 막대를 그리지 않는다 */
+  data: number[];
+}
+```
+
+### SBarChartDirection
+
+```ts
+/** 막대가 자라는 방향. */
+export type SBarChartDirection = 'vertical' | 'horizontal';
+```
+
+### SBarChartPalette
+
+```ts
+/**
+ * 색 팔레트.
+ * - `default` 파랑 한 색. 계열이 하나거나 색으로 나눌 것이 없을 때
+ * - `multi` 서로 무관한 항목(11색)을 순서대로
+ * - `gradation` 한 지표의 단계(6색)를 진한 쪽부터 순서대로
+ * - `custom` `colors` 로 고른 색을 순서대로
+ */
+export type SBarChartPalette = 'default' | 'multi' | 'gradation' | 'custom';
+```
+
+### SBarChartColor
+
+```ts
+/**
+ * `palette='custom'` 에서 고를 수 있는 색 이름.
+ * positive=늘어남 · negative=줄어듦 · neutral=변화 없음 을 뜻하므로 뜻에 맞게 고른다.
+ */
+export type SBarChartColor =
+  | 'positivePrimary'
+  | 'positiveSecondary'
+  | 'negativePrimary'
+  | 'negativeSecondary'
+  | 'neutralPrimary'
+  | 'neutralSecondary';
+```
+
+### SBarChartLegendPosition
+
+```ts
+/** 범례 위치. */
+export type SBarChartLegendPosition = 'top' | 'bottom';
+```
+
+### SBarChartPoint
+
+```ts
+/** 툴팁·클릭이 가리키는 지점. */
+export interface SBarChartPoint {
+  /** 계열 인덱스 */
+  seriesIndex: number;
+  /** 카테고리 인덱스 */
+  categoryIndex: number;
+  /** 그 지점의 값 */
+  value: number;
+}
+```
+
+---
+
 # SBarcodeInput
 
 > 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
@@ -3232,7 +3352,7 @@ export type SCalloutMessage = string | SCalloutMessage[];
 | `avatarSrc?` | `string` | — | 아바타 이미지 경로. 없으면 사람 아이콘 자리표시가 선다. **받은 메시지에만 쓰인다** — 보낸 메시지에는 아바타가 서지 않는다(`direction` 참고). |
 | `avatarAlt?` | `string` | — | 아바타 대체 텍스트 |
 | `continued?` | `boolean` | `false` | 같은 사람이 이어서 말한 묶음인지. 켜면 **아바타와 `sender` 를 그리지 않는다** — 말풍선이 위 묶음과 같은 선에서 시작해 한 사람의 말로 이어 읽힌다. 받은 메시지에서는 아바타 자리를 비워 둔 채 남긴다 — 안 남기면 말풍선이 44px 왼쪽으로 밀려 위 묶음과 어긋난다. 보낸 메시지는 아바타가 없으므로 이름만 숨긴다. `time`·`readStatus` 는 그대로 나온다. 시간이 벌어져 묶음을 나눴어도 얼굴은 한 번만 보이면 되고 시각은 묶음마다 필요하기 때문이다. **얼마나 벌어져야 묶음을 나눌지는 앱이 정한다** — 30분이든 하루든 대화의 성격에 달렸으므로 컴포넌트는 기준을 갖지 않고 스위치만 연다. |
-| `variant?` | `SChatMessageVariant` | `'default'` | 말풍선 종류. `template` 이면 말풍선이 옅은 파랑 면으로 서서 미리 등록된 서식으로 보내진 메시지임을 드러낸다. **보낸 메시지(`direction="outgoing"`)에만 쓰인다** — 받은 메시지에는 넘겨도 그리지 않는다. 템플릿은 사업자가 보내는 것이라 받은 쪽에는 뜻이 없다. 앱이 메시지를 한 번만 매핑해 방향과 무관하게 넘길 수 있도록 막지 않고 무시한다. |
+| `variant?` | `SChatMessageVariant` | `'default'` | 말풍선 종류. `template` 은 미리 등록된 서식으로, `admin` 은 관리자·시스템이 보낸 메시지임을 각각 다른 면으로 드러낸다. 면 색은 토큰이 정하므로 여기서 색을 정하지 않는다. **보낸 메시지(`direction="outgoing"`)에만 쓰인다** — 받은 메시지에는 넘겨도 그리지 않는다. 셋 다 사업자 쪽이 보내는 것이라 받은 쪽에는 뜻이 없다. 앱이 메시지를 한 번만 매핑해 방향과 무관하게 넘길 수 있도록 막지 않고 무시한다. |
 | `actions?` | `ReactNode` | — | 시각 아래에 붙는 동작 슬롯. 없으면 그 줄이 통째로 빠진다. 「상담원 연결」처럼 **이 메시지에 이어서 할 수 있는 동작**이 오는 자리다. 무엇을 놓을지는 앱이 정하고, 메시지는 줄로 세우고 방향에 맞춰 정렬하는 것까지만 한다. 시각과 같은 선에서 시작한다 — 말풍선 끝에서 한 칸 안이다. |
 | `messages?` | `ReactNode[]` | — | 말풍선 목록. **한 항목이 말풍선 하나**가 되어 위에서 아래로 쌓인다. 한 사람이 연달아 말하면 아바타·이름·시각은 한 번만 서고 말풍선만 늘어난다 — 그 묶음이 이 컴포넌트 한 개다. 말풍선 안에는 글뿐 아니라 버튼 같은 요소도 올 수 있다. |
 | `attachments?` | `ReactNode[]` | — | 말풍선 아래에 붙는 파일 목록. **한 항목이 칸 하나**가 되어 위에서 아래로 쌓인다. `SChatFile` 을 넣는 자리다 — 말풍선과 달리 면으로 감싸지 않고 넘긴 것을 그대로 세운다. 파일 칸은 제 면·선·라운드를 이미 갖고 있어 한 번 더 감싸면 칸이 두 겹으로 보인다. **`messages` 대신 여기로 넘긴다.** `messages` 로 넘기면 말풍선 면에 감싸여 그렇게 된다. 아바타·이름·시각·읽음 표시는 글 메시지와 똑같이 이 컴포넌트가 그린다 — 파일을 보낸 것도 대화의 한 줄이므로 행 규칙을 따로 갖지 않는다. |
@@ -3275,12 +3395,15 @@ export const CHAT_MESSAGE_READ_STATUSES = ['read', 'unread'] as const;
 
 ```ts
 /**
- * 말풍선의 종류. `template` 은 미리 등록된 서식으로 보내진 메시지다.
+ * 말풍선의 종류.
+ * - `default` 사람이 직접 쓴 메시지
+ * - `template` 미리 등록된 서식으로 보내진 메시지
+ * - `admin` 관리자·시스템이 보낸 메시지
  *
- * **보낸 메시지에서만 면이 갈린다.** 템플릿은 사업자가 보내는 것이라 받은 메시지에는
- * 뜻이 없고, 받은 메시지는 템플릿이든 아니든 같은 면으로 선다.
+ * **보낸 메시지에서만 면이 갈린다.** 셋 다 사업자 쪽이 보내는 것이라 받은 메시지에는
+ * 뜻이 없고, 받은 메시지는 무엇으로 보냈든 같은 면으로 선다.
  */
-export const CHAT_MESSAGE_VARIANTS = ['default', 'template'] as const;
+export const CHAT_MESSAGE_VARIANTS = ['default', 'template', 'admin'] as const;
 ```
 
 ## Dependencies

package/dist/llms.txt

@@ -27,6 +27,19 @@
 
 "비슷하게 생긴 것을 직접 만드는 것"이 어색함의 가장 큰 원인이다. 대응 컴포넌트를 쓰면 색·간격·상태·접근성이 전부 따라온다.
 
+### 0-0. 화면을 짜기 전에 — 세 가지 질문
+
+**컴포넌트를 고르기 전에 이 세 가지에 답한다.** 요청에 답이 없으면 추측해서 채우지 말고 **되묻는다.**
+
+1. 이 화면에서 사용자가 하려는 **단 하나의 일**은 무엇인가
+2. 그 일을 끝내는 데 **없어도 되는 것**은 무엇인가 — 컬럼·버튼·안내 문구 중 빼도 되는 것
+3. **실패하면** 어디로 돌아가는가 — 오류·빈 목록·권한 없음일 때 무엇을 보여줄지
+
+요청받은 것을 그대로 다 넣지 않는다. **"있을 법한 필드를 빠짐없이 채우는 것"이 화면을 망치는 가장 흔한 방식이다.**
+목록에 컬럼을, 폼에 입력란을, 툴바에 버튼을 하나 더 넣기는 쉽고 나중에 빼기는 어렵다. 2번은 그래서 있다.
+
+2번에 답이 하나도 없으면 아직 화면을 이해하지 못한 것이다. 그 상태로 코드를 쓰면 미정 상태가 그대로 화면이 된다.
+
 ### 0-1. 전체 컴포넌트 인덱스
 
 무엇을 만들지 정했으면 **이 표에서 먼저 찾는다.** 상세 Props·Types 는 `dist/components/<이름>/README.md` 참조.
@@ -41,6 +54,7 @@
 | **표·목록** | `SChatMessage`(대화의 메시지 한 건) `SChatAttachedFile`(입력창 위, 아직 보내지 않은 첨부 한 칸) `SChatFile`(대화 흐름에 선, 보낸 파일 한 칸) `SChatSystemMessage`(대화 흐름 가운데 서는 시스템 안내) `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SListItem` `SExpansionList` `SDraggableList` `SDraggableItem` `STree` |
 | **레이아웃** | `SLayout` `SGnb` `SGnbSystem` `SSystemActionButton`(GNB system 패널에 한 줄씩 쌓는 액션 행 — 버튼 고르기는 §3-5) `SAccountListBox`(계정 행을 눌러 뜨는 계정 패널) `SPage` `SPageHeader`(페이지 제목 영역 — `SLayout` 안에서 `SPage` 앞에 둔다) `SSectionHeaderCard` `SCard` `SLoginCard`(통합 계정 로그인 화면의 카드) `SDivider` `SSplitter` `SScrollArea` `SExpansionItem` |
 | **내비게이션** | `STabs` `SPagination` `SStepper` |
+| **차트** | `SBarChart`(막대 그래프 — 항목끼리 크기를 견준다) |
 | **표시·상태** | `STag` `SBadge` `SIcon` `SImage` `SCallout` `SGuide` |
 | **진행·로딩** | `SLinearProgress` `SCircleProgress` `SLoadingContainer` `SLoadingModal` |
 | **오버레이** | `STooltip` `SPopover` `SPopup` `SDrawer` `SPortal` |
@@ -162,7 +176,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 층 | 무엇인가 | 컴포넌트 |
 | --- | --- | --- |
 | **셸** | 앱 전체 뼈대. 페이지가 바뀌어도 남는다 | `SLayout` `SGnb` `SGnbSystem`(GNB 맨 아래 판 · 전폭 상단바 오른쪽 끝) `SPage` `SPageHeader`(`SLayout` 안에서 `SPage` 앞에 둔다) |
-| **블록** | `SPage` 의 직계 자식. 페이지를 세로로 쌓는 단위 | `SSectionHeaderCard` `SCard` `SChatMessage` `SChatSystemMessage` `SChatInput` `SLoginCard`(유일하게 `SPage` 밖에 선다 — 로그인 화면 자체가 자기 자리다, §4-6) `SForm` `SSplitter` `SScrollArea` `SCalendarBoard` `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SExpansionList` `SDraggableList` `STree` `SCallout` `STabs` `SStepper` `SPagination` `SDivider` |
+| **블록** | `SPage` 의 직계 자식. 페이지를 세로로 쌓는 단위 | `SSectionHeaderCard` `SCard` `SChatMessage` `SChatSystemMessage` `SChatInput` `SLoginCard`(유일하게 `SPage` 밖에 선다 — 로그인 화면 자체가 자기 자리다, §4-6) `SForm` `SSplitter` `SScrollArea` `SCalendarBoard` `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SExpansionList` `SDraggableList` `STree` `SCallout` `SBarChart` `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` `SChatAttachedFile` `SChatFile` `SImage` `SLinearProgress` `SCircleProgress` |
 | **인라인** | 텍스트 흐름·셀·라벨 안에 섞인다. 혼자 블록이 되지 않는다 | `STag` `SBadge` `SIcon` `STextLink` `SChip` |
 | **레이어** | 문서 흐름 **밖**에 떠서 그려진다. 어느 층에서 띄우든 레이아웃에 영향이 없다 | `SModal` `SActionModal` `SConfirmModal` `SPopup` `SDrawer` `SPopover` `STooltip` `SPortal` `SAccountListBox`(계정 행에 붙어 뜬다 — 직접 띄우지 않는다) `SToast` `SLoadingModal` `SLoadingContainer` `SGuide` |
@@ -536,6 +550,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 부모-자식 계층을 들여쓰기로 보여준다 | `STree` | §3-7-7 |
 | 사용자가 순서를 드래그로 바꾸게 한다 | `SDraggableList` + `SDraggableItem` | §3-7-6 |
 | 날짜별 일정을 한 달치 격자로 펼쳐 보여준다 | `SCalendarBoard` | §3-7-4 |
+| 항목끼리 크기를 눈으로 견주게 한다 (기간별 추이·채널별 비중) | `SBarChart` | 정확한 값을 읽어야 하면 `STable` — 그래프는 "어느 쪽이 큰가" 를 답하지 "얼마인가" 를 답하지 않는다 |
 | 표 위에 건수 요약과 액션을 얹는다 | `STableBar` | §4-2 |
 | 상태·분류를 라벨로 찍는다 | `STag` | §3-1 |
 | 색 점만으로 상태를 찍는다 | `SBadge` | §3-1 |
@@ -2407,7 +2422,7 @@ Tailwind 유틸리티는 아래 스케일에 있는 값만 사용한다. 리터
 - steelblue: 10 25 45 60 65 70 75 80 85 90 95 99
 - oceanblue: 15 25 50 60 65 70 75 80 85 90 95 99
 - brilliantblue: 10 20 25 40 50 60 70 75 80 85 90 95 99 05
-- bg: screen frame brand subtle accent accentLight accentBright accentFaint deep danger dangerLight warning caution progress success successLight neutralLight neutralBright tableHeader
+- bg: screen frame brand subtle accent accentLight accentBright accentFaint deep danger dangerLight warning caution progress success neutralLight neutralBright tableHeader
 - fg: primary secondary tertiary quaternary brand subtleWarm subtleCool deep success successLight dangerLight accent accentLight danger warning inverse
 - border: default strong bold accent accentLight danger warning success
 - disabled: bg text icon border
@@ -2502,7 +2517,6 @@ Tailwind 유틸리티는 아래 스케일에 있는 값만 사용한다. 리터
 --sys-color-bg-screen
 --sys-color-bg-subtle
 --sys-color-bg-success
---sys-color-bg-successLight
 --sys-color-bg-tableHeader
 --sys-color-bg-warning
 --sys-color-blue-strong
@@ -2559,7 +2573,7 @@ Tailwind 유틸리티는 아래 스케일에 있는 값만 사용한다. 리터
 --sys-color-navigation-gnb-bg-dark
 --sys-color-navigation-gnb-bg-system
 
-## 3. 컴포넌트 인덱스 (78종)
+## 3. 컴포넌트 인덱스 (79종)
 
 **Props 는 이 문서에 없다.** 쓸 컴포넌트를 정했으면 그 컴포넌트의 README 를 읽는다.
 
@@ -2568,4 +2582,4 @@ Tailwind 유틸리티는 아래 스케일에 있는 값만 사용한다. 리터
 예) SButton 을 쓴다면 `dist/components/SButton/README.md`.
 prop 을 추측해서 쓰지 말고 반드시 README 로 확인한다 (분류별 용도는 §1 의 "전체 컴포넌트 인덱스" 참조).
 
-SAccountListBox · SActionModal · SBadge · SBarcodeInput · SButton · SCalendar · SCalendarBoard · SCallout · SCard · SChatAttachedFile · SChatFile · SChatInput · SChatMessage · SChatSystemMessage · SCheckbox · SChip · SChipFilter · SChipInput · SCircleProgress · SConfirmModal · SDatePicker · SDateRangePicker · SDivider · SDraggableItem · SDraggableList · SDrawer · SDropdownButton · SEditor · SExpansionItem · SExpansionList · SField · SFilePicker · SForm · SGhostButton · SGnb · SGnbSystem · SGuide · SIcon · SImage · SInput · SKeyValueTable · SLayout · SLinearProgress · SList · SListItem · SLoadingContainer · SLoadingModal · SLoginCard · SModal · SNumberInput · SPage · SPagination · SPopover · SPopup · SPortal · SRadio · SRadioButton · SRadioCard · SScrollArea · SSearchInput · SSectionHeaderCard · SSelect · SSplitter · SStepper · SSwitch · SSystemActionButton · STable · STableBar · STabs · STag · STextLink · STextarea · STimePicker · STimeRangePicker · SToast · SToggle · STooltip · STree
+SAccountListBox · SActionModal · SBadge · SBarChart · SBarcodeInput · SButton · SCalendar · SCalendarBoard · SCallout · SCard · SChatAttachedFile · SChatFile · SChatInput · SChatMessage · SChatSystemMessage · SCheckbox · SChip · SChipFilter · SChipInput · SCircleProgress · SConfirmModal · SDatePicker · SDateRangePicker · SDivider · SDraggableItem · SDraggableList · SDrawer · SDropdownButton · SEditor · SExpansionItem · SExpansionList · SField · SFilePicker · SForm · SGhostButton · SGnb · SGnbSystem · SGuide · SIcon · SImage · SInput · SKeyValueTable · SLayout · SLinearProgress · SList · SListItem · SLoadingContainer · SLoadingModal · SLoginCard · SModal · SNumberInput · SPage · SPagination · SPopover · SPopup · SPortal · SRadio · SRadioButton · SRadioCard · SScrollArea · SSearchInput · SSectionHeaderCard · SSelect · SSplitter · SStepper · SSwitch · SSystemActionButton · STable · STableBar · STabs · STag · STextLink · STextarea · STimePicker · STimeRangePicker · SToast · SToggle · STooltip · STree