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

package/dist/components/STag/README.md

@@ -11,11 +11,59 @@
 | `shape?` | `STagShape` | `'square'` | 모양 |
 | `size?` | `STagSize` | `'sm'` | 크기 |
 | `color?` | `STagColor` | `'grey'` | 색상 |
+| `deep?` | `boolean` | `false` | 진한 배경(deep) 버전. 배경에 강조색을 채우고 텍스트·아이콘을 반전색으로 쓴다 |
 | `label?` | `string` | `''` | 레이블 텍스트 |
 | `icon?` | `SIconName` | — | 아이콘명 |
 | `iconLeft?` | `boolean` | `true` | 아이콘을 레이블 왼쪽에 배치 |
 | `width?` | `string \| number` | — | 태그 너비 (숫자면 px, 문자열이면 그대로 적용). 미지정 시 콘텐츠 크기 |
 
+## Types
+
+### STagShape
+
+```ts
+export type STagShape = (typeof TAG_SHAPES)[number];
+```
+
+### STagSize
+
+```ts
+export type STagSize = (typeof TAG_SIZES)[number];
+```
+
+### STagColor
+
+```ts
+export type STagColor = (typeof TAG_COLORS)[number];
+```
+
+### TAG_SHAPES
+
+```ts
+export const TAG_SHAPES = ['square', 'pill'] as const;
+```
+
+### TAG_SIZES
+
+```ts
+export const TAG_SIZES = ['xs', 'sm', 'md'] as const;
+```
+
+### TAG_COLORS
+
+```ts
+export const TAG_COLORS = [
+  'grey',
+  'red',
+  'orange',
+  'yellow',
+  'green',
+  'blue',
+  'darkblue',
+  'indigo',
+] as const;
+```
+
 ## Dependencies
 
 ### Used by
@@ -24,6 +72,8 @@
  - [SConfirmModal](../SConfirmModal)
  - [SGhostButton](../SGhostButton)
  - [SGnb](../SGnb)
+ - [SRadioCard](../SRadioCard)
+ - [SSystemActionButton](../SSystemActionButton)
  - [STabs](../STabs)
  - [STextLink](../STextLink)
 
@@ -40,6 +90,8 @@ graph TD;
   SConfirmModal --> STag
   SGhostButton --> STag
   SGnb --> STag
+  SRadioCard --> STag
+  SSystemActionButton --> STag
   STabs --> STag
   STextLink --> STag
   style STag fill:#f9f,stroke:#333,stroke-width:4px

package/dist/components/STag/STag.d.ts

@@ -8,6 +8,8 @@ export interface STagProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'
     size?: STagSize;
     /** 색상 */
     color?: STagColor;
+    /** 진한 배경(deep) 버전. 배경에 강조색을 채우고 텍스트·아이콘을 반전색으로 쓴다 */
+    deep?: boolean;
     /** 레이블 텍스트 */
     label?: string;
     /** 아이콘명 */
@@ -20,6 +22,6 @@ export interface STagProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'
 /**
  * STag — sd-tag 포팅.
  * Stencil의 `name`(예: square_sm_grey) 프리셋을 shape/size/color 세 prop으로 분리.
- * 색상은 컴포넌트 토큰 `--cmp-tag-<color>-{bg,content}` 참조.
+ * 색상은 컴포넌트 토큰 `--cmp-tag-<color>-{bg,content}`, deep 은 `--cmp-tag-<color>-deep-*` 참조.
  */
 export declare const STag: import("react").ForwardRefExoticComponent<STagProps & import("react").RefAttributes<HTMLSpanElement>>;

package/dist/components/STextLink/README.md

@@ -11,8 +11,10 @@
 | `label?` | `string` | `''` | 레이블 |
 | `icon?` | `SIconName` | — | 좌측 아이콘 |
 | `iconColor?` | `SColor` | — | 좌측 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 |
+| `iconRotate?` | `0 \| 90 \| 180 \| 270` | — | 좌측 아이콘 회전 각도. 같은 아이콘을 방향만 바꿔 쓸 때 (`SIcon` 의 `rotate` 로 그대로 간다) |
 | `labelClass?` | `string` | — | 레이블 span에 추가할 클래스 |
 | `rightArrow?` | `STextLinkArrow` | `'none'` | 우측 화살표 |
+| `rightArrowRotate?` | `0 \| 90 \| 180 \| 270` | — | 우측 화살표 회전 각도. 같은 화살표를 방향만 바꿔 쓸 때 (`SIcon` 의 `rotate` 로 그대로 간다) |
 | `underline?` | `boolean` | `false` | 밑줄 여부 |
 | `disabled?` | `boolean` | `false` | 비활성 |
 | `size?` | `STextLinkSize` | `'sm'` | 크기 |
@@ -24,6 +26,20 @@
 |-------|------|-------------|
 | `onClick` | `() => void` |  |
 
+## Types
+
+### STextLinkArrow
+
+```ts
+export type STextLinkArrow = 'none' | 'chevron' | 'caret';
+```
+
+### STextLinkSize
+
+```ts
+export type STextLinkSize = 'sm' | 'md' | 'lg';
+```
+
 ## Dependencies
 
 ### Used by
@@ -31,6 +47,7 @@
  - [SChipFilter](../SChipFilter)
  - [SChipInput](../SChipInput)
  - [SPopover](../SPopover)
+ - [STable](../STable)
 
 ### Depends on
 
@@ -46,5 +63,6 @@ graph TD;
   SChipFilter --> STextLink
   SChipInput --> STextLink
   SPopover --> STextLink
+  STable --> STextLink
   style STextLink fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/STextLink/STextLink.d.ts

@@ -10,10 +10,14 @@ export interface STextLinkProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'o
     icon?: SIconName;
     /** 좌측 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 */
     iconColor?: SColor;
+    /** 좌측 아이콘 회전 각도. 같은 아이콘을 방향만 바꿔 쓸 때 (`SIcon` 의 `rotate` 로 그대로 간다) */
+    iconRotate?: 0 | 90 | 180 | 270;
     /** 레이블 span에 추가할 클래스 */
     labelClass?: string;
     /** 우측 화살표 */
     rightArrow?: STextLinkArrow;
+    /** 우측 화살표 회전 각도. 같은 화살표를 방향만 바꿔 쓸 때 (`SIcon` 의 `rotate` 로 그대로 간다) */
+    rightArrowRotate?: 0 | 90 | 180 | 270;
     /** 밑줄 여부 */
     underline?: boolean;
     /** 비활성 */

package/dist/components/STextarea/README.md

@@ -27,7 +27,7 @@
 | `hint?` | `string` | — |  |
 | `error?` | `boolean` | — |  |
 | `errorMessage?` | `string` | — |  |
-| `width?` | `number \| string` | — |  |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다. 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다. |
 | `disabled?` | `boolean` | `false` |  |
 | `readOnly?` | `boolean` | `false` |  |
 | `className?` | `string` | — |  |

package/dist/components/STextarea/STextarea.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 interface STextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange'> {
     /** 값 (제어) */
     value?: string;
@@ -41,7 +42,12 @@ export interface STextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextArea
     hint?: string;
     error?: boolean;
     errorMessage?: string;
-    width?: number | string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다.
+     * 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다.
+     */
+    width?: SFieldWidth;
     disabled?: boolean;
     readOnly?: boolean;
     className?: string;

package/dist/components/STimePicker/README.md

@@ -16,7 +16,7 @@
 | `clearable?` | `boolean` | `false` |  |
 | `useMeridiem?` | `boolean` | — | 오전/오후 선택 표시 여부. 지정하지 않으면 type="midday"일 때만 켜집니다. |
 | `minuteStep?` | `number` | `1` |  |
-| `width?` | `number \| string` | — |  |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다. 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다. |
 | `name?` | `string` | — |  |
 | `rules?` | `Rule[]` | — |  |
 | `status?` | `SFieldStatus` | — |  |
@@ -41,6 +41,20 @@
 | `onValueChange` | `(time: string \| null) => void` | 선택 변경 (sdUpdate) |
 | `onOpenChange` | `(open: boolean) => void` | 열림/닫힘 변경 (sdDropDownShow) |
 
+## Types
+
+### STimePickerType
+
+```ts
+export type STimePickerType = 'default' | 'midday';
+```
+
+### STimePickerSize
+
+```ts
+export type STimePickerSize = 'sm' | 'md';
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/STimePicker/STimePicker.d.ts

@@ -5,6 +5,7 @@ import { type SColor } from '../../lib/color';
 import { type Rule } from '../../lib/form';
 import { type STooltipProps } from '../STooltip';
 import { type STimePickerSize, type STimePickerType } from './timepicker.config';
+import { type SFieldWidth } from '../../lib/field-width';
 export type { STimePickerSize, STimePickerType } from './timepicker.config';
 export interface STimePickerProps {
     /** 선택 시간 (HH:mm) */
@@ -22,7 +23,12 @@ export interface STimePickerProps {
     /** 오전/오후 선택 표시 여부. 지정하지 않으면 type="midday"일 때만 켜집니다. */
     useMeridiem?: boolean;
     minuteStep?: number;
-    width?: number | string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다.
+     * 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다.
+     */
+    width?: SFieldWidth;
     name?: string;
     rules?: Rule[];
     status?: SFieldStatus;

package/dist/components/STimePicker/timepicker.config.d.ts

@@ -1,3 +1,4 @@
+import { type SFieldWidthGrade } from '../../lib/field-width';
 export type STimePickerSize = 'sm' | 'md';
 export type STimePickerType = 'default' | 'midday';
 export type STimePickerMeridiem = 'AM' | 'PM';
@@ -13,10 +14,11 @@ export declare const TIMEPICKER_SIZE_CONFIG: Record<STimePickerSize, {
     minWidth: number;
     fieldMinWidth: number;
     /**
-     * 필드 상한. 값 길이가 HH:mm 으로 정해져 있어, width="100%" 를 받아도 행 전체로
+     * 필드 상한(폭 등급). 값 길이가 HH:mm 으로 정해져 있어, width="100%" 를 받아도 행 전체로
      * 늘어나지 않게 막는다 (SKeyValueTable 이 모든 컨트롤에 100% 를 넘긴다).
+     * px 가 아니라 등급으로 두어 `--cmp-field-width-*` 가 바뀌면 함께 따라가게 한다.
      */
-    fieldMaxWidth: number;
+    fieldMaxWidth: SFieldWidthGrade;
 }>;
 export declare function clampTimePart(value: number, min: number, max: number): number;
 export declare function padTimePart(value: number): string;

package/dist/components/STimeRangePicker/README.md

@@ -17,7 +17,7 @@
 | `useMeridiem?` | `boolean` | — | 오전/오후 선택 표시 여부. 지정하지 않으면 type="midday"일 때만 켜집니다. |
 | `minuteStep?` | `number` | `1` |  |
 | `rangeOrder?` | `STimeRangePickerRangeOrder` | `'strict'` | 범위 순서 정책. strict는 시작 시간이 종료 시간보다 늦어지지 않도록 보정합니다. |
-| `width?` | `number \| string` | — |  |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다. 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다. |
 | `name?` | `string` | — |  |
 | `rules?` | `Rule[]` | — |  |
 | `status?` | `SFieldStatus` | — |  |
@@ -42,6 +42,32 @@
 | `onValueChange` | `(range: STimeRangeValue) => void` | 선택 변경 (sdUpdate) |
 | `onOpenChange` | `(open: boolean) => void` | 열림/닫힘 변경 (sdDropDownShow) |
 
+## Types
+
+### STimeRangeValue
+
+```ts
+export type STimeRangeValue = [string, string] | null;
+```
+
+### STimeRangePickerType
+
+```ts
+export type STimeRangePickerType = STimePickerType;
+```
+
+### STimeRangePickerSize
+
+```ts
+export type STimeRangePickerSize = STimePickerSize;
+```
+
+### STimeRangePickerRangeOrder
+
+```ts
+export type STimeRangePickerRangeOrder = 'strict' | 'allow-cross-day';
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/STimeRangePicker/STimeRangePicker.d.ts

@@ -6,6 +6,7 @@ import { type Rule } from '../../lib/form';
 import { type STooltipProps } from '../STooltip';
 import { type STimeRangePickerRangeOrder, type STimeRangePickerSize, type STimeRangePickerType, type STimeRangeValue } from './time-range-picker.config';
 export type { STimeRangePickerSize, STimeRangePickerRangeOrder, STimeRangePickerType, STimeRangeValue, } from './time-range-picker.config';
+import { type SFieldWidth } from '../../lib/field-width';
 export interface STimeRangePickerProps {
     /** 선택 시간 범위 [시작, 종료] (HH:mm) */
     value?: STimeRangeValue;
@@ -24,7 +25,12 @@ export interface STimeRangePickerProps {
     minuteStep?: number;
     /** 범위 순서 정책. strict는 시작 시간이 종료 시간보다 늦어지지 않도록 보정합니다. */
     rangeOrder?: STimeRangePickerRangeOrder;
-    width?: number | string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다.
+     * 값 길이에 상한이 없으면 `"100%"` 로 두어 행 전체를 쓴다.
+     */
+    width?: SFieldWidth;
     name?: string;
     rules?: Rule[];
     status?: SFieldStatus;

package/dist/components/SToast/README.md

@@ -51,6 +51,30 @@
 | `onClose` | `() => void` | 닫기 (sdClose) |
 | `onButtonClick` | `(e: MouseEvent) => void` | 버튼 클릭 (sdButtonClick) |
 
+## Types
+
+### SToastPosition
+
+```ts
+export type SToastPosition =
+  'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+```
+
+### SToastNotifyOptions
+
+```ts
+export interface SToastNotifyOptions extends Omit<SToastProps, 'onClose'> {
+  /** 자동 닫힘 지연(ms). 0이면 자동 닫힘 없음 (없으면 defaultDuration) */
+  duration?: number;
+}
+```
+
+### SToastType
+
+```ts
+export type SToastType = 'default' | 'danger' | 'caution' | 'complete' | 'accent' | 'info';
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/SToggle/README.md

@@ -21,3 +21,11 @@
 |-------|------|-------------|
 | `onValueChange` | `(value: boolean) => void` | 변경 (sdUpdate) |
 
+## Types
+
+### SToggleSize
+
+```ts
+export type SToggleSize = 'xs' | 'sm';
+```
+

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

@@ -1 +1 @@
-export { SToggle, type SToggleProps } from './SToggle';
+export { SToggle, type SToggleProps, type SToggleSize } from './SToggle';

package/dist/components/STooltip/README.md

@@ -40,15 +40,37 @@
 | `show` | `() => void` | 툴팁을 표시합니다. |
 | `hide` | `() => void` | 툴팁을 숨깁니다. |
 
+## Types
+
+### STooltipTrigger
+
+```ts
+export type STooltipTrigger = 'hover' | 'click' | 'none';
+```
+
+### STooltipPlacement
+
+```ts
+export type STooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+```
+
+### STooltipType
+
+```ts
+export type STooltipType = 'default' | 'danger' | 'warning' | 'accent';
+```
+
 ## Dependencies
 
 ### Used by
 
  - [SChipFilter](../SChipFilter)
  - [SField](../SField)
+ - [SGnbSystem](../SGnbSystem)
  - [SKeyValueTable](../SKeyValueTable)
  - [SSectionHeaderCard](../SSectionHeaderCard)
  - [SStepper](../SStepper)
+ - [STable](../STable)
 
 ### Depends on
 
@@ -63,8 +85,10 @@ graph TD;
   STooltip --> SIcon
   SChipFilter --> STooltip
   SField --> STooltip
+  SGnbSystem --> STooltip
   SKeyValueTable --> STooltip
   SSectionHeaderCard --> STooltip
   SStepper --> STooltip
+  STable --> STooltip
   style STooltip fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/STree/README.md

@@ -18,6 +18,7 @@
 | `border?` | `boolean` | `true` | 아이템 하단 border 표시 여부 |
 | `indeterminate?` | `boolean` | `false` | 일부 선택 상태 |
 | `selectable?` | `boolean` | `true` | 체크박스 표시 여부 |
+| `size?` | `STreeSize` | `'sm'` | 타이포그래피 크기 |
 | `leading?` | `ReactNode \| ((state: STreeItemRenderState) => ReactNode)` | — | 사용자 지정 leading 콘텐츠 |
 | `trailing?` | `ReactNode \| ((state: STreeItemRenderState) => ReactNode)` | — | 사용자 지정 trailing 콘텐츠 |
 
@@ -40,6 +41,8 @@
 | `expandedIds?` | `string[]` | — | 펼쳐진 노드 ID 목록 |
 | `defaultExpandedIds?` | `string[]` | — | 비제어 펼침 초기값 |
 | `selectable?` | `boolean` | `true` | 체크박스 표시 여부 |
+| `size?` | `STreeSize` | `'sm'` | 타이포그래피 크기 |
+| `useAll?` | `boolean` | `false` | 체크박스 사용 시 최상단 전체 선택 아이템 표시 여부 |
 | `guideline?` | `boolean` | `true` | depth 연결선 표시 여부 |
 | `border?` | `boolean` | `true` | 아이템 하단 border 표시 여부 |
 | `cascadeSelection?` | `boolean` | `true` | 부모 선택 시 하위 노드까지 함께 토글 |
@@ -53,6 +56,44 @@
 | `onValueChange` | `(value: string[], node: STreeNode) => void` | 선택 변경 |
 | `onExpandedChange` | `(expandedIds: string[], node: STreeNode) => void` | 펼침 변경 |
 
+## Types
+
+### STreeNode
+
+```ts
+export interface STreeNode {
+  /** 노드 고유 ID */
+  id: string;
+  /** 노드 라벨 */
+  label: ReactNode;
+  /** 하위 노드 */
+  children?: STreeNode[];
+  /** 비활성 상태 */
+  disabled?: boolean;
+}
+```
+
+### STreeSize
+
+```ts
+export type STreeSize = 'sm' | 'md';
+```
+
+### STreeItemRenderState
+
+```ts
+export interface STreeItemRenderState {
+  node: STreeNode;
+  depth: number;
+  size: STreeSize;
+  expanded: boolean;
+  selected: boolean;
+  indeterminate: boolean;
+  disabled: boolean;
+  hasChildren: boolean;
+}
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/STree/STree.d.ts

@@ -1,4 +1,5 @@
 import { type HTMLAttributes, type MouseEvent, type ReactNode } from 'react';
+export type STreeSize = 'sm' | 'md';
 export interface STreeNode {
     /** 노드 고유 ID */
     id: string;
@@ -12,6 +13,7 @@ export interface STreeNode {
 export interface STreeItemRenderState {
     node: STreeNode;
     depth: number;
+    size: STreeSize;
     expanded: boolean;
     selected: boolean;
     indeterminate: boolean;
@@ -39,6 +41,8 @@ export interface STreeItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'ch
     indeterminate?: boolean;
     /** 체크박스 표시 여부 */
     selectable?: boolean;
+    /** 타이포그래피 크기 */
+    size?: STreeSize;
     /** 사용자 지정 leading 콘텐츠 */
     leading?: ReactNode | ((state: STreeItemRenderState) => ReactNode);
     /** 사용자 지정 trailing 콘텐츠 */
@@ -61,6 +65,10 @@ export interface STreeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'childr
     defaultExpandedIds?: string[];
     /** 체크박스 표시 여부 */
     selectable?: boolean;
+    /** 타이포그래피 크기 */
+    size?: STreeSize;
+    /** 체크박스 사용 시 최상단 전체 선택 아이템 표시 여부 */
+    useAll?: boolean;
     /** depth 연결선 표시 여부 */
     guideline?: boolean;
     /** 아이템 하단 border 표시 여부 */

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

@@ -1 +1 @@
-export { STree, STreeItem, type STreeItemProps, type STreeItemRenderState, type STreeNode, type STreeProps, } from './STree';
+export { STree, STreeItem, type STreeItemProps, type STreeItemRenderState, type STreeNode, type STreeProps, type STreeSize, } from './STree';

package/dist/docs/Gallery.d.ts

@@ -0,0 +1,9 @@
+/**
+ * "한눈에 보기" 그리드.
+ *
+ * 이 파일은 **나열 규칙만** 갖는다 — 분류·순서는 `categories.ts`(SSOT)가, 미리보기는
+ * `gallery-previews.tsx` 가, 링크 대상은 스토리의 `title` 이 정한다. 새 컴포넌트는
+ * 여기를 고치지 않고 그 셋만 채우면 자리를 잡는다.
+ */
+import type { ReactNode } from 'react';
+export default function Gallery(): ReactNode;

package/dist/docs/gallery-previews.d.ts

@@ -0,0 +1,24 @@
+/**
+ * "한눈에 보기" 페이지가 쓰는 컴포넌트별 미리보기.
+ *
+ * 이 저장소에서 **손으로 유지하는 유일한 문서 자산**이다. 그래서 두 가지를 지킨다.
+ *
+ * 1. **설명을 쓰지 않는다.** 카드에는 미리보기와 이름과 링크만 있다. "언제 쓰나" 는
+ *    AGENTS.md §3(Guide/컴포넌트 선택)이, Props 는 각 컴포넌트 Docs 탭이 갖는다.
+ *    여기에 한 줄 설명을 붙이는 순간 그 둘과 어긋나기 시작한다.
+ * 2. **빠지면 CI 가 잡는다.** 스토리가 있는 컴포넌트는 전부 여기 키가 있어야 한다 —
+ *    `npm run check:categories` 가 강제한다.
+ *
+ * 미리보기 상자는 `pointer-events-none` 이라 눌리지 않는다(Gallery.tsx). 갤러리는 보는
+ * 자리이고 만지는 자리는 각 컴포넌트의 Docs 탭이다 — 덕분에 오버레이가 열리거나 포커스를
+ * 뺏는 일 없이 수십 개를 한 화면에 살아 있는 채로 둘 수 있다.
+ *
+ * 화면 골격(앱 셸·모달·드로어)처럼 카드에 담기지 않는 것은 {@link note} 로 둔다.
+ * 억지로 축소해 알아볼 수 없는 그림을 넣느니 무엇인지 한 줄로 적는 편이 낫다.
+ */
+import type { ReactNode } from 'react';
+/**
+ * 컴포넌트 이름 → 미리보기.
+ * 키는 스토리 파일이 있는 컴포넌트와 정확히 같아야 한다 (check:categories).
+ */
+export declare const GALLERY_PREVIEWS: Record<string, ReactNode>;