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

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

@@ -0,0 +1,56 @@
+/**
+ * 직교 좌표 차트(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;
+/**
+ * 항목 축 양끝에 두는 여백(px).
+ *
+ * 항목들이 나눠 갖는 자리(band) 바깥에 따로 붙는다 — 첫 항목과 마지막 항목이 차트
+ * 경계에 붙어 잘린 것처럼 보이지 않게 한다. 세로 차트는 좌우, 가로 차트는 위아래다.
+ *
+ * **선 차트(`SLineChart`)는 쓰지 않는다.** 선은 첫 점이 왼쪽 끝, 마지막 점이 오른쪽
+ * 끝에 서서 추이를 그림 폭 전체에 펼친다.
+ */
+export declare const AXIS_EDGE_PADDING = 24;
+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,21 @@
+/**
+ * 차트 바깥 틀 — 패딩·배경과 "제목·단위 / 범례 / 그림" 칸의 세로 배치.
+ * 그림이 무엇인지(막대·선·파이)는 알지 않는다.
+ */
+import { type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+import type { SChartLegendPosition } from './types';
+export interface ChartFrameProps extends HTMLAttributes<HTMLDivElement> {
+    /** 차트 제목 — 왼쪽 위에 놓인다 */
+    title?: string;
+    /** 단위 — 오른쪽 위에 "단위 : " 를 붙여 놓는다. `title` 이 없어도 홀로 놓일 수 있다 */
+    unit?: string;
+    /** 범례 — 없으면 칸 자체가 사라진다 */
+    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/hover-dim.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 한 항목을 짚으면 나머지가 물러나는 전환 — 막대·조각·점·값 라벨·범례가 **같은 속도로** 움직인다.
+ *
+ * 속도가 갈리면 같은 손짓 하나에 그림이 여러 번 나뉘어 반응하는 것처럼 보인다.
+ * 그래서 값을 각 차트에 두지 않고 여기 한 곳에 둔다.
+ *
+ * **전환 대상은 「흐려지는 것」뿐이다.** 짚은 항목이 커지는 것(막대·선의 값 라벨이 `typo-*` 로
+ * 굵어지는 것, 파이·도넛 조각이 부푸는 것)은 일부러 즉시 바꾼다 — 글자가 늘어나거나 도형이
+ * 자라는 중간 상태가 오히려 읽기 나쁘기 때문이다.
+ *
+ * ⚠️ **둘로 나뉜 이유**: 차트마다 흐려지는 방식이 다르다. 막대·조각·범례는 불투명도를 낮추지만,
+ * 선 차트의 점은 선 위에 앉아 있어 불투명도를 낮추면 밑의 선이 비쳐 지저분해진다. 그래서 점은
+ * 옅은 **색으로 갈아끼운다**(`linePointDimmedColor`). 전환할 속성이 다르니 클래스도 나뉜다 —
+ * 점에 `transition-opacity` 를 붙이면 아무 일도 일어나지 않는다.
+ */
+/** 불투명도로 물러나는 것 — 막대 · 파이/도넛 조각 · 값 라벨 · 범례 */
+export declare const CHART_DIM_OPACITY_TRANSITION = "transition-opacity duration-200 ease-out motion-reduce:transition-none";
+/** 색으로 물러나는 것 — 선 차트의 점 (`transition-colors` 가 `fill` 을 포함한다) */
+export declare const CHART_DIM_COLOR_TRANSITION = "transition-colors duration-200 ease-out motion-reduce:transition-none";

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

@@ -0,0 +1,21 @@
+export interface ChartLegendItem {
+    /** 계열 이름 */
+    name: string;
+    /** 점 색 (CSS 색 문자열) */
+    color: string;
+    /** `default` 변형에서만 쓰는 값 텍스트. `simple` 에서는 무시한다 */
+    value?: string;
+    /** `value` 글자색 (CSS 색 문자열). 없으면 이름과 같은 기본색을 쓴다 */
+    valueColor?: string;
+}
+export interface ChartLegendProps {
+    items: ChartLegendItem[];
+    /** 가로 정렬 — 시안은 그림 위 가운데다. `default` 변형에는 적용하지 않는다 */
+    align?: 'start' | 'center' | 'end';
+    /** 지금 강조 중인 계열. 나머지는 흐려진다 */
+    activeIndex?: number | null;
+    className?: string;
+    /** 범례 모양. `simple` 가로 나열(값 없음) · `default` 이름+값을 세로로 쌓는 목록 */
+    variant?: 'simple' | 'default';
+}
+export declare function ChartLegend({ items, align, activeIndex, className, variant, }: ChartLegendProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,28 @@
+/**
+ * 차트 팔레트 — `--cmp-chart-palette-*` 를 계열 인덱스로 고르는 규칙.
+ *
+ * 계열이 팔레트 색 수보다 많으면 앞에서부터 **순환**한다. 색이 반복되면 범례로만
+ * 구분되므로, 계열이 많을 때는 `multi`(11색) 를 쓰는 편이 낫다.
+ *
+ * 같은 모양의 팔레트가 하나 더 있다 — 선 그래프의 흐린 점
+ * (`--cmp-chart-line-point-dimmed-palette-*`). 잎 이름(`single` · `multi-*` ·
+ * `gradation-*` · `variation-*`)이 본 팔레트와 1:1 이라 고르는 규칙을 그대로 쓰고
+ * 변수 접두어만 바꾼다. 둘을 따로 적어 두면 팔레트에 색이 늘 때 한쪽만 고치게 된다.
+ */
+import type { SChartColor, SChartPalette } from './types';
+export declare const CHART_COLORS: Record<SChartColor, string>;
+export declare const CHART_PALETTES: Record<"default" | "multi" | "gradation", readonly string[]>;
+export declare function paletteColor(palette: SChartPalette, index: number, colors?: readonly SChartColor[]): string;
+/**
+ * 선 그래프에서 **짚지 않은 항목의 점** 색.
+ *
+ * 막대·원형은 흐릴 때 불투명도를 낮추지만, 선 그래프의 점은 옅은 색을 따로 갖는다
+ * (`chart.line.point.dimmed.palette.*`). 점이 선 위에 앉아 있어 불투명도를 낮추면
+ * 아래의 선이 비쳐 점이 탁해지기 때문이다 — 색을 바꾸면 점은 끝까지 또렷한 원으로 남는다.
+ */
+export declare function linePointDimmedColor(palette: SChartPalette, index: number, colors?: readonly SChartColor[]): string;
+/**
+ * 계열 인덱스 → 값 텍스트 색. `paletteColor` 와 같은 규칙으로 고르되
+ * `chart.dataValue.palette.*`(위 주석 참조)를 쓴다.
+ */
+export declare function dataValueColor(palette: SChartPalette, index: number, colors?: readonly SChartColor[]): string;

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

@@ -0,0 +1,99 @@
+/**
+ * 원형 차트(파이·도넛)의 공용 구현 — 조각 계산과 그림.
+ *
+ * `SPieChart`·`SDonutChart` 는 이 위의 얇은 껍데기다. 두 차트는 가운데를 비우는지
+ * (`innerRatio`)만 다르다. 도넛의 빈 가운데에는 글자를 두지 않는다.
+ *
+ * 원형 고유의 치수는 `chart.doughnut.*` 토큰이 정한다 — 이름은 도넛이지만 **파이도 같이
+ * 쓴다.** 두 차트가 한 구현이라 값을 따로 두면 구멍 유무만 달라야 할 것이 색·움직임까지
+ * 달라진다. 다만 조각은 SVG 경로를 좌표로 계산하므로 `var(--cmp-…)` 문자열을 넣을 수 없는
+ * 자리가 있다 — 그런 상수는 막대의 `BAR_RADIUS` 와 같은 규칙으로, 토큰과 **같은 값을 손으로
+ * 맞춰** 두고 어느 토큰을 베꼈는지 각 상수에 적는다. 불투명도처럼 CSS 로 넘길 수 있는 것은
+ * 토큰을 직접 참조한다.
+ */
+import { type CSSProperties, type ReactNode } from 'react';
+import type { SChartColor, SChartLegendPosition, SChartPalette } from './types';
+/**
+ * 도넛 안쪽 반지름 / 바깥 반지름. 너비에 따라 구멍과 고리 두께가 함께 늘고 준다.
+ * 폭이 반응형이라 구멍을 px 로 고정하지 않고 비율로 둔다 — 토큰
+ * `chart.doughnut.innerRatio`(`--cmp-chart-doughnut-innerRatio`)도 px 이 아닌 배수다.
+ * 반지름 계산에 곱하는 수라 CSS 변수로 넘기지 못하고 같은 값을 손으로 맞춰 둔다.
+ */
+export declare const DONUT_INNER_RATIO = 0.4;
+/**
+ * 비율 라벨을 적는 최소 몫. 이보다 좁은 조각은 글자가 조각 밖으로 넘쳐 이웃 조각의
+ * 라벨과 겹치므로 적지 않는다 — 값은 툴팁으로 읽는다.
+ */
+export declare const LABEL_MIN_RATIO = 0.05;
+/** 파이의 비율 라벨이 놓이는 반지름(바깥 반지름에 대한 비). 가운데는 조각이 좁아 바깥쪽에 둔다. */
+export declare const PIE_LABEL_RADIUS_RATIO = 0.65;
+/**
+ * 짚은 조각이 자라는 길이(px). 각도는 그대로 두고 **안팎 양쪽으로** 자라, 이웃 조각을 덮지
+ * 않고 고리만 두꺼워진다. 배율이 아니라 px 이라 차트가 커져도 자라는 양은 늘 같게 보인다.
+ *
+ * 토큰 `chart.doughnut.hover.grow` 와 같은 값 — 경로 좌표라 숫자여야 해서 손으로 맞춰 둔다.
+ */
+export declare const HOVER_GROW = 4;
+/**
+ * 짚은 조각의 모서리 둥글기(px). 자란 조각만 네 모서리를 둥글린다.
+ * 토큰 `chart.doughnut.hover.radius` 와 같은 값 — 위와 같은 이유로 숫자다.
+ */
+export declare const HOVER_CORNER = 2;
+/** 조각 하나. */
+export interface RadialSlice {
+    name: string;
+    value: number;
+}
+/** 클릭·툴팁이 가리키는 조각. */
+export interface RadialSlicePoint {
+    /** `data` 안에서의 인덱스 */
+    index: number;
+    name: string;
+    value: number;
+    /** 그려진 조각 전체의 합에 대한 몫(0~1) */
+    ratio: number;
+}
+export interface RadialChartProps {
+    data: RadialSlice[];
+    /** 차트 제목 — 왼쪽 위에 놓인다 */
+    title?: string;
+    /** 단위 — 오른쪽 위에 "단위 : " 를 붙여 놓는다 */
+    unit?: string;
+    palette?: Exclude<SChartPalette, 'default'>;
+    colors?: SChartColor[];
+    showValueLabel?: boolean;
+    showLegend?: boolean;
+    legendPosition?: SChartLegendPosition;
+    /** 범례 모양. `simple` 이름만 가로로 · `default` 이름+값을 세로로 쌓는 목록. 도넛 전용 — 파이는 항상 `simple` 이다 */
+    legendVariant?: 'simple' | 'default';
+    showTooltip?: boolean;
+    formatValue?: (value: number) => string;
+    onSliceClick?: (slice: RadialSlicePoint) => void;
+    tooltipFooter?: (slice: RadialSlicePoint) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** 가운데를 비우는 비율. 0 이면 파이다 */
+    innerRatio: number;
+    /** 스크린 리더가 읽는 그래프 종류 */
+    kind: string;
+}
+/** 몫 → 퍼센트 문자열. 1% 가 안 되는 조각을 0% 로 적으면 없는 조각처럼 읽힌다. */
+export declare function formatRatio(ratio: number): string;
+/**
+ * 조각 경로. 바깥 호를 시계 방향으로 돌고, 도넛이면 안쪽 호를 거꾸로 돌아 닫는다.
+ *
+ * 한 바퀴 전체(조각이 하나)는 호 하나로 그릴 수 없다 — 시작점과 끝점이 같으면 SVG 가
+ * 호를 그리지 않는다. 그래서 반원 둘로 나눠 그리고, 도넛은 `evenodd` 로 가운데를 뚫는다.
+ *
+ * `corner` 를 주면 네 모서리를 그 반지름으로 둥글린다. 모서리는 반지름 방향 변과 호에
+ * 동시에 닿는 원이라, 변은 접점까지 짧아지고 호는 접점까지 각도가 줄어든다. 한 바퀴
+ * 전체는 반지름 방향 변이 없어 둥글릴 모서리도 없다.
+ */
+export declare function slicePath(center: number, outer: number, inner: number, start: number, end: number, corner?: number): string;
+/**
+ * 파이·도넛 공용 그림.
+ *
+ * 폭은 부모를 따르고(기본 100%), 그림 영역은 그 폭을 한 변으로 하는 **정사각형**이다.
+ * 원의 지름은 잰 폭이라 부모가 줄면 원도 함께 준다. 범례는 정사각형 바깥에 붙는다.
+ */
+export declare const RadialChart: import("react").ForwardRefExoticComponent<RadialChartProps & import("react").RefAttributes<HTMLDivElement>>;

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,60 @@
+/**
+ * 차트 툴팁 — 기준 막대 옆에 서는 값 상자.
+ *
+ * 커서를 따라다니지 않는다. 커서를 따라가면 상자가 막대를 가리는 자리로 계속 밀려들고,
+ * 같은 값을 읽는 동안에도 상자가 흔들려 눈이 따라가야 한다. 대신 호출 쪽이 정한
+ * **기준 막대**(`anchor`)에 붙여 한자리에 세운다.
+ *
+ * 차트 컨테이너 **안에** absolute 로 뜬다. Portal 을 쓰지 않는 이유: 차트는 카드·모달
+ * 안에 들어가는 일이 많은데, 상자가 차트 밖으로 나갈 만큼 크지 않아 굳이 부모를
+ * 벗어날 이유가 없다. 대신 부모가 `relative` 여야 한다.
+ */
+import type { ReactNode } from 'react';
+export interface ChartTooltipItem {
+    /** 계열 점 색 */
+    color: string;
+    /** 계열 이름 */
+    label: string;
+    /** 표시할 값 (이미 포맷된 문자열) */
+    value: string;
+}
+/** 상자가 붙을 기준 막대의 자리 — 컨테이너 기준 px. */
+export interface ChartTooltipAnchor {
+    /** 막대의 왼쪽 끝 */
+    left: number;
+    /** 막대의 오른쪽 끝 */
+    right: number;
+    /** 막대의 위쪽 끝 */
+    top: number;
+}
+/**
+ * 기준 자리에서 상자를 띄우는 가로 거리(px). 오른쪽에 설 때와 왼쪽으로 넘길 때가 다를 수 있어
+ * 두 값을 따로 받는다 — **음수면 그만큼 기준 자리 안으로 물린다.**
+ */
+export interface ChartTooltipGapX {
+    /** 오른쪽에 세울 때 — 기준 자리의 오른쪽 끝에서 상자 왼쪽 변까지 */
+    after: number;
+    /** 왼쪽으로 넘길 때 — 상자 오른쪽 변에서 기준 자리의 왼쪽 끝까지 */
+    before: number;
+}
+export interface ChartTooltipProps {
+    /** 상자 제목 — 보통 카테고리 이름 */
+    title: string;
+    items: ChartTooltipItem[];
+    /** 상자를 붙일 기준 막대 */
+    anchor: ChartTooltipAnchor;
+    /** 상자가 넘치면 안 되는 범위(px). 보통 그림 영역 크기다 */
+    bounds?: {
+        width: number;
+        height: number;
+    };
+    /** 기준 자리에서 띄우는 가로 거리. 기본값은 양쪽 다 4px */
+    gapX?: ChartTooltipGapX;
+    /**
+     * 값 목록 아래에 붙이는 내용 — 차트의 `tooltipFooter` 가 짚은 항목을 받아 그린 것이다.
+     * 상자가 마우스를 통과시키므로 누를 수 있는 것은 넣지 못한다.
+     */
+    footer?: ReactNode;
+    className?: string;
+}
+export declare function ChartTooltip({ title, items, anchor, bounds, gapX, footer, 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,39 @@
+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;
+};
+/** SVG `<text>` 가 실제로 차지하는 글자 상자. */
+export interface SvgTextMetrics {
+    /** 기준선에서 글자 윗변까지 — 위쪽이라 음수다 */
+    top: number;
+    /** 글자 상자의 폭 */
+    width: number;
+}
+/**
+ * SVG `<text>` 의 글자 상자를 잰다. **기준선(y=0)에 놓고 써야** `top` 이 뜻을 갖는다.
+ *
+ * HTML 사본으로 재면 줄 상자(`line-height`)가 잡혀 글자 윗변보다 한참 위가 나온다 —
+ * `body.md.bold` 는 글자 14px 에 줄 24px 이라 10px 이 뜬다. `getBBox()` 는 그린 글자에
+ * 딱 맞는 상자를 주므로 폰트가 바뀌어도 따로 맞출 값이 없다.
+ *
+ * 글자가 바뀌면 상자도 바뀌므로 **매 렌더 뒤에** 다시 잰다. ResizeObserver 를 쓰지
+ * 않는 이유는 SVG 도형 요소 지원이 브라우저마다 갈리기 때문이다. 값이 그대로면 상태를
+ * 바꾸지 않으므로 렌더가 되풀이되지 않는다.
+ */
+export declare function useSvgTextMetrics(): {
+    ref: import("react").RefObject<SVGTextElement | null>;
+    metrics: SvgTextMetrics;
+};

package/dist/lib/date.d.ts

@@ -1,7 +1,8 @@
 /** 로컬 기준 오늘 YYYY-MM-DD */
 export declare function todayStr(): string;
 export declare function formatDate(year: number, month: number, day: number): string;
-export declare function calcYearMonth(year: number, month: number, dir: 'prev' | 'next'): {
+/** year/month(1-12) 에서 dir 방향으로 step 달 이동한 연·월 (기본 1달) */
+export declare function calcYearMonth(year: number, month: number, dir: 'prev' | 'next', step?: number): {
     year: number;
     month: number;
 };

package/dist/lib/depth-filter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 계층 목록(그룹 헤더 + 리프가 한 줄로 펴진 배열)을 검색어로 좁힌다.
+ * SSelect 의 드롭다운과 SChipFilter 의 편집 팝오버가 같은 규칙을 쓰도록 여기 한 곳에 둔다 —
+ * 같은 계층 목록이 두 컴포넌트에서 다르게 검색되면 소비 앱이 어느 쪽을 믿어야 할지 알 수 없다.
+ */
+/** 펴진 목록의 한 줄이 갖춰야 하는 최소 정보 — 값의 형태는 컴포넌트마다 달라 여기서 보지 않는다 */
+export interface DepthRow {
+    /** 최상위가 1 */
+    depth: number;
+    /** children 을 가진 노드 — 그 자체는 값이 되지 않는다 */
+    isGroup: boolean;
+}
+/**
+ * **그룹 이름도 검색 대상이다.** 사용자가 화면에서 읽은 말은 리프 이름만이 아니라 그 위 분류
+ * 이름이기도 해서, 분류명을 쳤는데 아무것도 안 나오면 목록에 없는 것으로 읽힌다.
+ *
+ * - 리프가 걸리면 그 리프와 **위로 이어지는 헤더**를 남긴다 — 어느 분류 밑인지 알아야 고른다
+ * - 그룹이 걸리면 그 그룹과 **아래 전부**를 남긴다 — 분류를 좁혀 그 안을 훑는 조작이다
+ * - 자기도 안 걸리고 걸린 자손도 없는 헤더는 걷어낸다 — 헤더만 덩그러니 남으면 결과가 없는데도
+ *   목록이 차 있는 것처럼 보인다
+ *
+ * 계층이 아닌 목록(그룹이 하나도 없는 평평한 배열)에서는 `matches` 를 그대로 통과시킨 것과 같다.
+ *
+ * @param rows   화면 순서(DFS)대로 펴진 목록
+ * @param matches 그 줄이 검색어에 걸리는가 — 라벨을 어떻게 읽을지(HTML 제거 등)는 부르는 쪽이 정한다
+ */
+export declare function filterDepthRows<T extends DepthRow>(rows: T[], matches: (row: T) => boolean): T[];

package/dist/lib/doc-sections.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Storybook 의 Guide 문서 페이지가 쓰는 마크다운 슬라이서.
+ *
+ * Guide 페이지는 **자기 원문을 갖지 않는다.** AGENTS.md·README.md 를 `?raw` 로 읽어
+ * 필요한 `## ` 섹션만 잘라 {@link https://storybook.js.org/docs/writing-docs/doc-blocks Markdown 블록}에 넘긴다.
+ * 문서를 Storybook 에 복사해 두면 AGENTS.md 가 바뀔 때마다 조용히 낡고,
+ * 이 저장소는 이미 한 변경이 네 곳(README·stories·playground·AGENTS.md)에 흩어져 있다 —
+ * 다섯 번째 사본을 만들지 않는 것이 이 파일의 존재 이유다.
+ *
+ * @example
+ * import agents from '../../AGENTS.md?raw';
+ * <Markdown>{mdSections(agents, '2.')}</Markdown>
+ */
+/**
+ * `## ` 섹션을 제목 접두어로 잘라 이어 붙인다. 접두어는 번호(`'2.'`)든 제목(`'설치'`)이든 된다.
+ *
+ * 넘긴 순서가 아니라 **원문 순서**로 이어 붙인다 — 문서 안의 "위에서 말한" 류의 참조가
+ * 순서를 뒤집으면 거짓이 되기 때문이다.
+ *
+ * 찾지 못한 접두어가 하나라도 있으면 던진다. 조용히 빈 페이지가 되면
+ * AGENTS.md 의 절 번호가 바뀐 것을 아무도 모른 채 배포된다.
+ */
+export declare function mdSections(md: string, ...prefixes: string[]): string;
+/**
+ * 원문의 저장소 상대 링크(`./README.md`)를 Storybook 문서 경로로 바꾼다.
+ *
+ * 원문은 npm 패키지에 그대로 실려 소비 앱의 `node_modules` 에서 읽히는 것이 1차 용도라
+ * 링크가 파일 경로다. Storybook 안에서는 그 경로가 404 이므로 여기서만 갈아 끼운다 —
+ * 원문은 손대지 않는다.
+ *
+ * 표에 없는 링크는 그대로 둔다.
+ */
+export declare function relinkToDocs(md: string): string;
+/** {@link mdSections} + {@link relinkToDocs} — Guide 페이지가 쓰는 기본 조합 */
+export declare function guideSections(md: string, ...prefixes: string[]): string;

package/dist/lib/dropdown-menu.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentPropsWithoutRef } from 'react';
+import * as RDropdown from '@radix-ui/react-dropdown-menu';
+import { type SIconName } from '../components/SIcon';
+/**
+ * 버튼에 매달린 액션 메뉴(SDropdownButton · SMeatballButton)의 공용 층.
+ * 두 컴포넌트가 **같은 메뉴로 그려져야** 해서 한 곳에 둔다 — Root/Trigger 는 트리거 모양이
+ * 달라 각 컴포넌트가 갖고, 여기는 Portal + Content + Item 만 맡는다.
+ */
+export interface DropdownMenuItem {
+    value: string | number;
+    label: string;
+    icon?: SIconName;
+    disabled?: boolean;
+}
+export interface DropdownMenuContentProps extends Omit<ComponentPropsWithoutRef<typeof RDropdown.Content>, 'children'> {
+    items: readonly DropdownMenuItem[];
+    onItemClick?: (value: string | number) => void;
+}
+export declare function DropdownMenuContent({ items, onItemClick, align, className, ...contentProps }: DropdownMenuContentProps): import("react").JSX.Element;

package/dist/lib/field-width.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 필드 폭 등급 — 폼 컨트롤의 너비를 정하는 공용 어휘.
+ *
+ * 폭은 `maxLength`(= 스키마 상한)로 정한다. 상한이 등급 안에 들어오면 그 등급을 주고,
+ * 상한이 `xl` 을 넘거나 상한 자체가 없으면 행 전체(`"100%"`)로 둔다.
+ * 이 판단은 `sellmate/field-width-grade` 린트 규칙이 자동으로 검사한다 — 규칙과 이 타입은
+ * 같은 토큰(`--cmp-field-width-*`)을 근거로 삼는다.
+ *
+ * px 를 직접 적는 것보다 등급을 쓰는 편이 낫다. 토큰 값이 바뀌면 등급은 따라가지만
+ * 화면에 박아 둔 px 는 그 자리에 남는다.
+ */
+/** 폭 등급 이름. 값은 `--cmp-field-width-<grade>` 토큰이 갖는다. */
+export declare const FIELD_WIDTH_GRADES: readonly ["xs", "sm", "md", "lg", "xl"];
+export type SFieldWidthGrade = (typeof FIELD_WIDTH_GRADES)[number];
+/**
+ * 폭 prop 이 받는 값.
+ *
+ * `(string & {})` 는 유니온 리터럴 자동완성을 유지하기 위한 관용 표현이다 — 이게 없으면
+ * `string` 이 등급 리터럴을 흡수해 편집기가 등급을 제안하지 못한다. (`SColor` 와 같은 방식)
+ */
+export type SFieldWidth = SFieldWidthGrade | number | (string & {});
+export declare const isFieldWidthGrade: (v: unknown) => v is SFieldWidthGrade;
+/**
+ * 폭 값을 CSS 길이로 바꾼다.
+ *   등급   → `var(--cmp-field-width-<grade>)`
+ *   숫자   → px
+ *   그 외  → 그대로 (`"100%"` · `"20rem"`)
+ *
+ * 빈 값(`undefined` · `''` · `0`)은 "지정하지 않음" 으로 본다.
+ */
+export declare const fieldWidthValue: (v?: SFieldWidth) => string | undefined;

package/dist/lib/floating-height.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Radix Floating Content 를 창 높이 안에 가두기 위한 헬퍼 — floating-width.ts 의 높이 버전.
+ *
+ * Radix 는 충돌이 나면 위치만 밀 뿐(shift) 높이는 줄이지 않는다 — 콘텐츠가 창보다 높으면
+ * 밀려난 자리에서 그대로 화면 밖으로 삐져나간다. 실제로 줄이려면 size 미들웨어가 계산해
+ * 두는 available-height 를 상한으로 직접 걸어야 한다.
+ */
+/** Radix Popover 계열(SPortal·SSelect·SChipInput·SPopover·STooltip 등)이 노출하는 가용 높이. */
+export declare const POPOVER_AVAILABLE_HEIGHT = "var(--radix-popover-content-available-height)";
+/** Radix DropdownMenu 계열(SDropdownButton)이 노출하는 가용 높이. */
+export declare const DROPDOWN_AVAILABLE_HEIGHT = "var(--radix-dropdown-menu-content-available-height)";
+/**
+ * 높이 제약을 가용 높이 안으로 가둔다. 값이 없으면 가용 높이 자체가 상한이 된다.
+ */
+export declare function clampToAvailableHeight(value: string | number | undefined, availableHeight: string): string;

package/dist/lib/global-overlay.d.ts

@@ -13,5 +13,10 @@ export declare const globalOverlayProps: {
 /**
  * Radix 의 outside 이벤트(pointerDownOutside/focusOutside/interactOutside)가
  * 전역 레이어에서 비롯됐는지 판별한다. Radix 는 원본 이벤트를 `detail.originalEvent` 에 담는다.
+ *
+ * 요소인지는 `instanceof` 가 아니라 `nodeType` 으로 본다. `instanceof` 는 그 realm 의 전역
+ * 생성자와 견주는 것이라 두 곳에서 어긋난다 — `Element` 가 전역에 없는 환경(테스트 DOM)에서는
+ * 그대로 터지고, iframe 처럼 realm 이 다른 문서에서 온 요소는 거짓이 되어 가드가 조용히
+ * 빗나간다. `nodeType` 은 어느 realm 의 노드에도 같은 값으로 있다.
  */
 export declare function isFromGlobalOverlay(event: Event): boolean;

package/dist/lib/hover-preview.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 호버 미리보기(`SImage previewOnHover`)가 뜨는 자리를 계산한다.
+ *
+ * **시작점은 썸네일의 한가운데**다 — 미리보기의 좌상단 모서리가 썸네일 중앙에 놓인다.
+ * 그래서 미리보기는 늘 오른쪽 아래로 펼쳐지고, 원래 보던 썸네일을 가리지 않는다.
+ *
+ * 창 오른쪽·아래로 넘치면 **넘친 만큼만 왼쪽·위로 되민다**. 반대편으로 뒤집지 않는다 —
+ * 뒤집으면 커서와 미리보기의 관계가 순간 바뀌어 어느 썸네일의 미리보기인지 읽기 어렵다.
+ * (Radix 의 `avoidCollisions` 는 shift 와 flip 을 함께 켜므로 쓰지 않고, 이 계산으로 대신한다.)
+ */
+/** 위치 계산에 필요한 만큼만 추린 사각형 — DOMRect 을 그대로 받을 수 있다 */
+export interface HoverPreviewAnchorRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface HoverPreviewOriginInput {
+    /** 썸네일의 viewport 기준 사각형 */
+    anchor: HoverPreviewAnchorRect;
+    /** 미리보기 상자의 한 변(px). 정사각형이다 */
+    size: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    /** 창 가장자리와 띄울 최소 간격 */
+    padding?: number;
+}
+/** 미리보기 상자의 좌상단 좌표 (viewport 기준) */
+export declare function hoverPreviewOrigin({ anchor, size, viewportWidth, viewportHeight, padding, }: HoverPreviewOriginInput): {
+    x: number;
+    y: number;
+};

package/dist/lib/inert.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 접힌 영역을 tab 순서에서 빼는 ref.
+ *
+ * 접기·펴기를 `grid-template-rows` 로 애니메이션하는 영역은 접힌 뒤에도 DOM 에 남는다.
+ * `aria-hidden` 은 스크린리더에서만 지우므로, 그것만으로는 Tab 이 보이지 않는 체크박스·버튼에
+ * 계속 멈춘다. `inert` 는 그 안쪽 전체를 포커스·포인터 대상에서 빼며 자손까지 함께 적용된다.
+ *
+ * JSX 의 `inert` prop 은 React 19 부터라, peer 가 `>=18` 인 이 패키지에서는 DOM 속성으로 직접
+ * 넣는다. 브라우저는 속성이 붙어 있는지만 보므로 값은 상관없다.
+ */
+export declare function useInertRef<T extends HTMLElement>(inert: boolean): import("react").RefObject<T | null>;

package/dist/lib/overlay-scrollbar.d.ts

@@ -0,0 +1,32 @@
+import { type RefObject } from 'react';
+/**
+ * 오버레이 스크롤바 — 스크롤 요소 **위에** 얹는 막대.
+ *
+ * 네이티브 스크롤바는 레이아웃 폭을 실제로 차지해서, 스크롤이 생기는 순간 안쪽 콘텐츠
+ * 폭이 그만큼 줄어든다. 표처럼 폭이 고정된 것이 들어 있으면 그 한 번의 흔들림이 그대로
+ * 보인다. 그래서 네이티브 막대를 숨기고(`SCROLLBAR_HIDDEN_CLASS`) 같은 자리에 그림만
+ * 얹는다 — 자리를 차지하지 않으므로 콘텐츠 폭이 변하지 않는다.
+ *
+ * **부모가 `relative` 여야 한다.** 막대는 그 상자를 기준으로 절대 배치된다.
+ */
+/** 막대가 도는 트랙의 폭(px). 세로·가로 막대가 만나는 모서리를 비우는 데도 쓴다. */
+export declare const OVERLAY_SCROLLBAR_SIZE = 12;
+export interface OverlayScrollbarsProps {
+    /** 실제로 스크롤하는 요소. 이 컴포넌트는 그 요소의 형제로 선다 */
+    scrollRef: RefObject<HTMLElement | null>;
+    /**
+     * 세로 막대를 그릴지. **스크롤이 실제로 걸린 축만 켠다** — `overflow-y: hidden` 인데
+     * 켜 두면 넘친 콘텐츠 때문에 못 움직이는 막대가 뜬다.
+     */
+    vertical?: boolean;
+    /** 가로 막대를 그릴지. 위와 같다 */
+    horizontal?: boolean;
+    /**
+     * true면 **스크롤하는 동안에만** 막대를 보인다. 멎으면 페이드로 사라진다.
+     *
+     * 끄고 두면 막대가 늘 서서 "여기는 스크롤된다"를 알린다 — 그 신호를 포기하는 대신
+     * 화면이 조용해진다. 끌고 있는 동안에는 손에서 사라지면 안 되므로 시간을 재지 않는다.
+     */
+    autoHide?: boolean;
+}
+export declare function OverlayScrollbars({ scrollRef, vertical: showVertical, horizontal: showHorizontal, autoHide, }: OverlayScrollbarsProps): import("react").JSX.Element;