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

package/dist/components/SLogo/README.md

@@ -0,0 +1,103 @@
+# SLogo
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SLogo
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name?` | `SLogoName` | `'sellmate'` | 로고명 — 셀메이트 본체(`sellmate`) 또는 서비스(`wms` · `account` · `crm` …). 서비스 로고는 [셀메이트 워드마크 + 서비스 표기]가 한 덩어리로 나온다 — 앱이 표기를 잇지 않는다. |
+| `mode?` | `SLogoMode` | `'light'` | 로고가 서는 배경. 밝은 면에는 `light`(남색 워드마크), 어두운 면에는 `dark`(흰 워드마크). 서비스 표기 색도 원본이 모드마다 정한 값으로 바뀐다. |
+| `direction?` | `SLogoDirection` | `'horizontal'` | 배치. `horizontal` 은 워드마크 오른쪽에 서비스 표기, `vertical` 은 워드마크 아래 가운데에 표기 (로그인 카드처럼 폭이 좁고 로고가 가운데 서는 자리). `sellmate` 는 표기가 없어 어느 쪽이든 같다. 표기 색이 가로와 다른 로고도 있다(POS 세로는 light 에서도 `#4886FF`) — 원본을 따른다. |
+| `size?` | `number \| 'auto' \| (string & {})` | `LOGO_DEFAULT_SIZE` | **높이**(px 또는 CSS 길이). 폭은 주지 않는다 — 로고 비율에서 저절로 나온다. `SIcon` 의 `size` 와 달리 정사각이 아니다(로고는 가로로 길다). `vertical` 은 두 줄 전체의 높이다 — 같은 `size` 면 워드마크가 가로보다 작게 선다. `'auto'` 면 높이를 정하지 않는다 — **부모 폭을 꽉 채우고 높이는 비율로 따라온다.** 로고 자리의 폭이 정해진 곳(`SGnb` `header="fix"` 의 로고 칸)에서 쓴다. 부모에 폭이 없으면 기준을 잃어 브라우저 기본 크기(300px)로 그려진다. |
+| `color?` | `SColor` | — | 색. 팔레트 키(`grey_45`, `red_95` …) 또는 임의 CSS 색상. **워드마크와 서비스 표기가 모두 이 한 색이 된다.** 미지정 시 **브랜드 색**(`mode` 가 정한 워드마크 색 + 서비스 색)이다 — `SIcon` 과 달리 currentColor 를 상속하지 않는다. 로고가 주변 글자색을 따라 물들면 브랜드 색이 화면마다 달라지기 때문이다. 비활성처럼 물러나야 하는 자리에서만 색을 준다. |
+| `label?` | `string` | — | 접근성 라벨. 없으면 `aria-hidden` 이다 — 로고 옆에 서비스 이름이 이미 적혀 있는 자리 (런처 목록의 한 줄 등)에서는 이름이 두 번 읽히지 않도록 그대로 둔다. 로고가 그 자리의 유일한 이름이면(로그인 화면·상단바) 브랜드명을 넘긴다. |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Types
+
+### SLogoName
+
+```ts
+export type SLogoName = (typeof LOGO_NAMES)[number];
+```
+
+### SLogoMode
+
+```ts
+export type SLogoMode = (typeof LOGO_MODES)[number];
+```
+
+### SLogoDirection
+
+```ts
+export type SLogoDirection = (typeof LOGO_DIRECTIONS)[number];
+```
+
+### LOGO_NAMES
+
+```ts
+/**
+ * SLogo 설정.
+ *
+ * 로고는 브랜드 자산이라 **색·비율이 토큰을 따르지 않는다** — 테마가 바뀌어도 로고는 그대로여야
+ * 하고, 워드마크의 비율은 자산 자체가 정한다. 그래서 이 파일의 값은 토큰 참조가 아니다.
+ */
+
+/**
+ * 담고 있는 로고 — 셀메이트 본체와 서비스들, 그리고 통합 콘솔. 로고 한 벌은 [셀메이트 워드마크 + 표기]다.
+ * 늘어나면 여기와 `logos.tsx` 의 맵에 함께 추가한다.
+ */
+export const LOGO_NAMES = [
+  'sellmate',
+  'wms',
+  'chat',
+  'chatbot',
+  'plm',
+  'account',
+  'people',
+  'crm',
+  'work',
+  'pos',
+  'console',
+] as const;
+```
+
+### LOGO_MODES
+
+```ts
+/**
+ * 로고가 서는 배경. 밝은 면에는 `light`(남색 워드마크), 어두운 면에는 `dark`(흰 워드마크).
+ * 서비스 표기 색도 모드마다 원본이 정한 값으로 바뀐다(Account·POS 는 dark 에서 더 밝다).
+ */
+export const LOGO_MODES = ['light', 'dark'] as const;
+```
+
+### LOGO_DIRECTIONS
+
+```ts
+/**
+ * 로고의 배치. `horizontal` 은 워드마크 오른쪽에 서비스 표기, `vertical` 은 워드마크 아래 가운데에 표기.
+ * 모든 서비스 로고가 세로 원본을 갖는다. 셀메이트 본체는 표기가 없어 세로여도 모양이 같다.
+ */
+export const LOGO_DIRECTIONS = ['horizontal', 'vertical'] as const;
+```
+
+## Dependencies
+
+### Used by
+
+ - [SLauncherListBox](../SLauncherListBox)
+ - [SLoginCard](../SLoginCard)
+
+### Graph
+
+```mermaid
+graph TD;
+  SLauncherListBox --> SLogo
+  SLoginCard --> SLogo
+  style SLogo fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SLogo/SLogo.d.ts

@@ -0,0 +1,72 @@
+import { type CSSProperties } from 'react';
+import { type SColor } from '../../lib/color';
+import { type SLogoDirection, type SLogoMode, type SLogoName } from './logo.config';
+export interface SLogoProps {
+    /**
+     * 로고명 — 셀메이트 본체(`sellmate`) 또는 서비스(`wms` · `account` · `crm` …).
+     * 서비스 로고는 [셀메이트 워드마크 + 서비스 표기]가 한 덩어리로 나온다 — 앱이 표기를 잇지 않는다.
+     */
+    name?: SLogoName;
+    /**
+     * 로고가 서는 배경. 밝은 면에는 `light`(남색 워드마크), 어두운 면에는 `dark`(흰 워드마크).
+     * 서비스 표기 색도 원본이 모드마다 정한 값으로 바뀐다.
+     */
+    mode?: SLogoMode;
+    /**
+     * 배치. `horizontal` 은 워드마크 오른쪽에 서비스 표기, `vertical` 은 워드마크 아래 가운데에 표기
+     * (로그인 카드처럼 폭이 좁고 로고가 가운데 서는 자리). `sellmate` 는 표기가 없어 어느 쪽이든 같다.
+     * 표기 색이 가로와 다른 로고도 있다(POS 세로는 light 에서도 `#4886FF`) — 원본을 따른다.
+     */
+    direction?: SLogoDirection;
+    /**
+     * **높이**(px 또는 CSS 길이). 폭은 주지 않는다 — 로고 비율에서 저절로 나온다.
+     * `SIcon` 의 `size` 와 달리 정사각이 아니다(로고는 가로로 길다).
+     * `vertical` 은 두 줄 전체의 높이다 — 같은 `size` 면 워드마크가 가로보다 작게 선다.
+     *
+     * `'auto'` 면 높이를 정하지 않는다 — **부모 폭을 꽉 채우고 높이는 비율로 따라온다.**
+     * 로고 자리의 폭이 정해진 곳(`SGnb` `header="fix"` 의 로고 칸)에서 쓴다. 부모에 폭이 없으면
+     * 기준을 잃어 브라우저 기본 크기(300px)로 그려진다.
+     */
+    size?: number | 'auto' | (string & {});
+    /**
+     * 색. 팔레트 키(`grey_45`, `red_95` …) 또는 임의 CSS 색상. **워드마크와 서비스 표기가 모두
+     * 이 한 색이 된다.**
+     *
+     * 미지정 시 **브랜드 색**(`mode` 가 정한 워드마크 색 + 서비스 색)이다 — `SIcon` 과 달리
+     * currentColor 를 상속하지 않는다. 로고가 주변 글자색을 따라 물들면 브랜드 색이 화면마다
+     * 달라지기 때문이다. 비활성처럼 물러나야 하는 자리에서만 색을 준다.
+     */
+    color?: SColor;
+    /**
+     * 접근성 라벨. 없으면 `aria-hidden` 이다 — 로고 옆에 서비스 이름이 이미 적혀 있는 자리
+     * (런처 목록의 한 줄 등)에서는 이름이 두 번 읽히지 않도록 그대로 둔다.
+     * 로고가 그 자리의 유일한 이름이면(로그인 화면·상단바) 브랜드명을 넘긴다.
+     */
+    label?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * SLogo — 브랜드 로고를 아이콘처럼 쓰는 컴포넌트.
+ *
+ * `SIcon` 과 같은 손맛(`name` · `size` · `color`)이지만 두 가지가 다르다.
+ * - **`size` 는 높이다.** 로고는 가로로 길어 정사각으로 그리면 찌그러진다 — 폭은 비율에서 나온다.
+ *   `size="auto"` 면 거꾸로 부모 폭을 채우고 높이가 비율에서 나온다.
+ * - **색을 주지 않으면 브랜드 색이다.** currentColor 를 상속하지 않는다(위 `color` 참고).
+ *
+ * **서비스 이름을 넣으면 그 서비스 로고가 나온다.** 워드마크 오른쪽에 표기를 앱이 따로 잇지 않는다 —
+ * 원본 로고의 자간·색이 서비스마다 달라서, 이어 붙이면 원본과 어긋난다.
+ *
+ * 배경이 어두우면 `mode="dark"` 를 준다 — 워드마크가 흰색이 되고 서비스 표기도 원본의 dark 색으로 바뀐다.
+ *
+ * ```tsx
+ * <SLogo />                                  // 셀메이트, 브랜드 색, 높이 24
+ * <SLogo name="wms" size={12} />             // 런처 목록의 한 줄
+ * <SLogo name="account" mode="dark" />       // 어두운 면 위
+ * <SLogo name="wms" direction="vertical" size={48} />  // 워드마크 아래에 표기
+ * <SLogo name="account" mode="dark" size="auto" />  // 폭이 정해진 로고 칸(fix GNB)을 채운다
+ * <SLogo name="crm" color="grey_45" />       // 아직 못 쓰는 서비스 — 로고 전체가 한 색
+ * <SLogo size={32} label="Sellmate" />       // 로고가 그 자리의 유일한 이름일 때
+ * ```
+ */
+export declare const SLogo: import("react").ForwardRefExoticComponent<SLogoProps & import("react").RefAttributes<HTMLSpanElement>>;

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

@@ -0,0 +1,2 @@
+export { SLogo, type SLogoProps } from './SLogo';
+export { LOGO_DEFAULT_SIZE, LOGO_DIRECTIONS, LOGO_MODES, LOGO_NAMES, type SLogoDirection, type SLogoMode, type SLogoName, } from './logo.config';

package/dist/components/SLogo/logo.config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SLogo 설정.
+ *
+ * 로고는 브랜드 자산이라 **색·비율이 토큰을 따르지 않는다** — 테마가 바뀌어도 로고는 그대로여야
+ * 하고, 워드마크의 비율은 자산 자체가 정한다. 그래서 이 파일의 값은 토큰 참조가 아니다.
+ */
+/**
+ * 담고 있는 로고 — 셀메이트 본체와 서비스들, 그리고 통합 콘솔. 로고 한 벌은 [셀메이트 워드마크 + 표기]다.
+ * 늘어나면 여기와 `logos.tsx` 의 맵에 함께 추가한다.
+ */
+export declare const LOGO_NAMES: readonly ["sellmate", "wms", "chat", "chatbot", "plm", "account", "people", "crm", "work", "pos", "console"];
+export type SLogoName = (typeof LOGO_NAMES)[number];
+/**
+ * 로고가 서는 배경. 밝은 면에는 `light`(남색 워드마크), 어두운 면에는 `dark`(흰 워드마크).
+ * 서비스 표기 색도 모드마다 원본이 정한 값으로 바뀐다(Account·POS 는 dark 에서 더 밝다).
+ */
+export declare const LOGO_MODES: readonly ["light", "dark"];
+export type SLogoMode = (typeof LOGO_MODES)[number];
+/**
+ * 로고의 배치. `horizontal` 은 워드마크 오른쪽에 서비스 표기, `vertical` 은 워드마크 아래 가운데에 표기.
+ * 모든 서비스 로고가 세로 원본을 갖는다. 셀메이트 본체는 표기가 없어 세로여도 모양이 같다.
+ */
+export declare const LOGO_DIRECTIONS: readonly ["horizontal", "vertical"];
+export type SLogoDirection = (typeof LOGO_DIRECTIONS)[number];
+/**
+ * 기본 높이(px). `SIcon` 과 같은 값이라 나란히 쓸 때 손에 익은 크기가 같다.
+ * 폭은 주지 않는다 — 로고마다 다른 비율에서 저절로 나온다.
+ */
+export declare const LOGO_DEFAULT_SIZE = 24;

package/dist/components/SLogo/logos.d.ts

@@ -0,0 +1,16 @@
+import type { CSSProperties } from 'react';
+import type { SLogoDirection, SLogoMode, SLogoName } from './logo.config';
+interface LogoGlyphProps {
+    name: SLogoName;
+    mode: SLogoMode;
+    direction: SLogoDirection;
+    /** 로고 전체를 덮을 한 색. 비우면 원본 브랜드 색(워드마크 + 서비스 색)이다 */
+    color?: string;
+    style?: CSSProperties;
+}
+/**
+ * @internal
+ * 로고 글리프 하나. 높이는 `style` 로 받고 폭은 viewBox 비율에서 나온다. 접근성 이름은 `SLogo` 가 붙인다.
+ */
+export declare function LogoGlyph({ name, mode, direction, color, style }: LogoGlyphProps): import("react").JSX.Element | null;
+export {};

package/dist/components/SMeatballButton/README.md

@@ -0,0 +1,67 @@
+# SMeatballButton
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SMeatballButton
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size?` | `SMeatballButtonSize` | `'sm'` | 버튼 크기 |
+| `intent?` | `SMeatballButtonIntent` | `'default'` | 색상 의도. 어두운 배경 위에서는 inverse |
+| `items?` | `SMeatballButtonItem[]` | `[]` | 메뉴 항목 목록 |
+| `tooltipText?` | `string` | `'기능 더 보기'` | 호버 시 표시할 툴팁 텍스트. 빈 문자열이면 툴팁을 띄우지 않는다. 메뉴가 열려 있는 동안은 숨는다. |
+| `ariaLabel?` | `string` | — | 스크린리더용 접근성 레이블. 미지정 시 tooltipText, 그것도 비면 '기능 더 보기' |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `className?` | `string` | — | 버튼을 감싸는 요소의 클래스. 위치 조정(absolute 배치 등)용 |
+| `style?` | `CSSProperties` | — | 버튼을 감싸는 요소의 스타일. 위치 조정용 |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onItemClick` | `(value: string \| number) => void` | 메뉴 항목 선택 |
+| `onOpenChange` | `(open: boolean) => void` | 열림/닫힘 변경 |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `open` | `() => void` | 메뉴 열기 |
+| `close` | `() => void` | 메뉴 닫기 |
+
+## Types
+
+### SMeatballButtonSize
+
+```ts
+export type SMeatballButtonSize = SGhostButtonSize;
+```
+
+### SMeatballButtonIntent
+
+```ts
+export type SMeatballButtonIntent = 'default' | 'inverse';
+```
+
+### SMeatballButtonItem
+
+```ts
+/** 메뉴 항목 — SDropdownButton 과 같은 모양이다 */
+export type SMeatballButtonItem = SDropdownButtonItem;
+```
+
+## Dependencies
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+```mermaid
+graph TD;
+  SMeatballButton --> SGhostButton
+  style SMeatballButton fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SMeatballButton/SMeatballButton.d.ts

@@ -0,0 +1,36 @@
+import { type CSSProperties } from 'react';
+import { type SGhostButtonSize } from '../SGhostButton';
+import type { SDropdownButtonItem } from '../SDropdownButton';
+export type SMeatballButtonSize = SGhostButtonSize;
+export type SMeatballButtonIntent = 'default' | 'inverse';
+/** 메뉴 항목 — SDropdownButton 과 같은 모양이다 */
+export type SMeatballButtonItem = SDropdownButtonItem;
+export interface SMeatballButtonHandle {
+    /** 메뉴 열기 */
+    open: () => void;
+    /** 메뉴 닫기 */
+    close: () => void;
+}
+export interface SMeatballButtonProps {
+    /** 버튼 크기 */
+    size?: SMeatballButtonSize;
+    /** 색상 의도. 어두운 배경 위에서는 inverse */
+    intent?: SMeatballButtonIntent;
+    /** 메뉴 항목 목록 */
+    items?: SMeatballButtonItem[];
+    /** 호버 시 표시할 툴팁 텍스트. 빈 문자열이면 툴팁을 띄우지 않는다. 메뉴가 열려 있는 동안은 숨는다. */
+    tooltipText?: string;
+    /** 스크린리더용 접근성 레이블. 미지정 시 tooltipText, 그것도 비면 '기능 더 보기' */
+    ariaLabel?: string;
+    /** 비활성 */
+    disabled?: boolean;
+    /** 메뉴 항목 선택 */
+    onItemClick?: (value: string | number) => void;
+    /** 열림/닫힘 변경 */
+    onOpenChange?: (open: boolean) => void;
+    /** 버튼을 감싸는 요소의 클래스. 위치 조정(absolute 배치 등)용 */
+    className?: string;
+    /** 버튼을 감싸는 요소의 스타일. 위치 조정용 */
+    style?: CSSProperties;
+}
+export declare const SMeatballButton: import("react").ForwardRefExoticComponent<SMeatballButtonProps & import("react").RefAttributes<SMeatballButtonHandle>>;

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

@@ -0,0 +1 @@
+export { SMeatballButton, type SMeatballButtonProps, type SMeatballButtonHandle, type SMeatballButtonItem, type SMeatballButtonSize, type SMeatballButtonIntent, } from './SMeatballButton';

package/dist/components/SModal/README.md

@@ -47,7 +47,7 @@ import { SModalOutlet } from 'sellmate-design-system-react';
 
 ## SModal.confirm
 
-아이콘 + 제목 + 메시지 + 확인/취소 버튼. `type` 에 따라 아이콘·메인 버튼 색이 결정된다.
+아이콘 + 제목 + 메시지 + 확인 버튼. `type` 에 따라 아이콘·메인 버튼 색이 결정된다.
 
 ```tsx
 SModal.confirm({
@@ -55,13 +55,23 @@ SModal.confirm({
   modalTitle: '삭제하시겠습니까?',
   topMessage: ['이 작업은 되돌릴 수 없습니다.'],
   mainButtonLabel: '삭제',
-  subButtonLabel: '취소',
+}).onOk(() => deleteItem());
+```
+
+**`subButtonLabel` 은 기본이 비어 있고, 그대로 두는 것이 기본이다.** `onCancel` 이 닫는 것 말고 따로 할 일이 있을 때만 준다 — 눌러도 창만 닫힌다면 X 버튼이 이미 하는 일이라(백드롭·ESC 도 열려 있다) 같은 버튼을 하나 더 세우지 않는다. 되묻는 모달도 예외가 아니다. 서브 버튼이 설 자리는 확인과 대등한 두 번째 선택지일 때이고, 그때 글자는 `취소`·`닫기` 가 아니라 그 버튼이 하는 일의 이름이 된다.
+
+```tsx
+SModal.confirm({
+  type: 'negative',
+  modalTitle: '재고가 모자란 주문이 있습니다',
+  mainButtonLabel: '자동 취소',
+  subButtonLabel: '수동 처리',
 })
-  .onOk(() => deleteItem())
-  .onCancel(() => {});
+  .onOk(() => cancelShortOrders())
+  .onCancel(() => openManualFlow());
 ```
 
-**옵션 (`SConfirmOptions`)** — 선언형 `SConfirmModalProps` 에서 제어 흐름 props(`open`/`onOpenChange`/`onOk`/`onCancel`/`onClose`)를 제외한 전부. 주요 키: `type`, `modalTitle`, `topMessage`/`bottomMessage`, `mainButtonLabel`/`mainButtonName`, `subButtonLabel`, `tagSlot`/`optionSlot`/`contentSlot`, `persistent`.
+**옵션 (`SConfirmOptions`)** — 선언형 `SConfirmModalProps` 에서 제어 흐름 props(`open`/`onOpenChange`/`onOk`/`onCancel`/`onClose`)를 제외한 전부. 주요 키: `type`, `modalTitle`, `topMessage`/`bottomMessage`, `mainButtonLabel`/`mainButtonOutline`/`mainButtonDisabled`, `subButtonLabel`, `tagSlot`/`optionSlot`/`contentSlot`, `persistent`.
 
 ---
 

package/dist/components/SModal/SModal.d.ts

@@ -82,7 +82,7 @@ export interface SModalRef {
  *
  * @example
  * // 확인/취소
- * SModal.confirm({ type: 'negative', modalTitle: '삭제하시겠습니까?', mainButtonLabel: '삭제', subButtonLabel: '취소' })
+ * SModal.confirm({ type: 'negative', modalTitle: '삭제하시겠습니까?', mainButtonLabel: '삭제' })
  *   .onOk(() => deleteItem())
  *   .onCancel(() => {});
  *

package/dist/components/SNumberInput/README.md

@@ -10,15 +10,16 @@
 |------|------|---------|-------------|
 | `value?` | `string \| number \| null` | — | 입력 값 |
 | `size?` | `SNumberInputSize` | `'sm'` | 크기 |
-| `min?` | `number` | `Number.NEGATIVE_INFINITY` | 최솟값 |
-| `max?` | `number` | `Number.POSITIVE_INFINITY` | 최댓값 |
+| `min?` | `number` | `Number.NEGATIVE_INFINITY` | 최솟값 — **검증 경계**다 (`<input type="number">` 의 `min` 과 같다). 값을 고쳐 쓰지 않는다. 벗어나면 blur·제출 시 에러 상태가 서고 안내 문구가 자동으로 붙는다. 스테퍼(`showButton`)와 위/아래 화살표는 이 값을 한계로 삼는다. |
+| `max?` | `number` | `Number.POSITIVE_INFINITY` | 최댓값 — **검증 경계**다 (`<input type="number">` 의 `max` 와 같다). 값을 고쳐 쓰지 않는다. 벗어나면 blur·제출 시 에러 상태가 서고 안내 문구가 자동으로 붙는다. 스테퍼(`showButton`)와 위/아래 화살표는 이 값을 한계로 삼는다. |
+| `clampOnBlur?` | `boolean` | `false` | blur 시 값을 `[min, max]` 경계로 끌어당길지. 기본 `false`. 기본값에서는 사용자가 친 값이 그대로 보존되고, 범위를 벗어나면 에러 상태로 알린다 — 그래야 소비자의 범위 검증에 실제 입력값이 도달한다. `true` 로 켜면 범위 밖 값이 경계값으로 **말없이 바뀌고** `onValueChange` 로 되쏘아진다 (`min={1}` 인 칸에 `0` 을 넣고 blur 하면 `onValueChange(1)` 이 발화한다). 경계로 붙여도 사용자가 놀라지 않는 값에만 켠다. 켜면 범위 에러는 서지 않는다 — 고쳐 쓴 값은 언제나 범위 안이기 때문이다. |
 | `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,9 +28,11 @@
 | `readOnly?` | `boolean` | `false` |  |
 | `rules?` | `Rule[]` | — | 유효성 규칙 — blur 시 검증 |
 | `status?` | `SFieldStatus` | — |  |
-| `focused?` | `boolean` | — |  |
-| `hovered?` | `boolean` | — |  |
+| `focused?` | `boolean` | — | 포커스 상태를 밖에서 지정한다 — 강조 테두리·링이 즉시 걸린다 (SField 로 그대로 넘어간다) |
+| `hovered?` | `boolean` | — | 호버 상태를 밖에서 지정한다 — 강조는 `focused` 와 같다 (SField 로 그대로 넘어간다) |
 | `label?` | `string` | — |  |
+| `labelPosition?` | `SFieldLabelPosition` | — | 레이블 위치 — `top` 이면 라벨이 컨트롤 위에 선다 (SField 로 그대로 넘어간다). |
+| `subLabel?` | `string` | — | 보조 레이블 — 레이블 오른쪽 같은 줄에 붙는다 (SField 로 그대로 넘어간다). |
 | `labelWidth?` | `number \| string` | — |  |
 | `icon?` | `SIconName` | — |  |
 | `iconColor?` | `SColor` | — |  |
@@ -40,7 +43,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 +55,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

@@ -1,9 +1,10 @@
 import { type CSSProperties } from 'react';
-import { type SFieldSize, type SFieldAddonAlign, type SFieldStatus } from '../SField';
+import { type SFieldSize, type SFieldAddonAlign, type SFieldStatus, type SFieldLabelPosition } from '../SField';
 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 {
     /** 입력 값 */
@@ -12,16 +13,36 @@ export interface SNumberInputProps {
     onValueChange?: (value: number | null) => void;
     /** 크기 */
     size?: SNumberInputSize;
-    /** 최솟값 */
+    /**
+     * 최솟값 — **검증 경계**다 (`<input type="number">` 의 `min` 과 같다).
+     * 값을 고쳐 쓰지 않는다. 벗어나면 blur·제출 시 에러 상태가 서고 안내 문구가 자동으로 붙는다.
+     * 스테퍼(`showButton`)와 위/아래 화살표는 이 값을 한계로 삼는다.
+     */
     min?: number;
-    /** 최댓값 */
+    /**
+     * 최댓값 — **검증 경계**다 (`<input type="number">` 의 `max` 와 같다).
+     * 값을 고쳐 쓰지 않는다. 벗어나면 blur·제출 시 에러 상태가 서고 안내 문구가 자동으로 붙는다.
+     * 스테퍼(`showButton`)와 위/아래 화살표는 이 값을 한계로 삼는다.
+     */
     max?: number;
+    /**
+     * blur 시 값을 `[min, max]` 경계로 끌어당길지. 기본 `false`.
+     *
+     * 기본값에서는 사용자가 친 값이 그대로 보존되고, 범위를 벗어나면 에러 상태로 알린다 —
+     * 그래야 소비자의 범위 검증에 실제 입력값이 도달한다.
+     *
+     * `true` 로 켜면 범위 밖 값이 경계값으로 **말없이 바뀌고** `onValueChange` 로 되쏘아진다
+     * (`min={1}` 인 칸에 `0` 을 넣고 blur 하면 `onValueChange(1)` 이 발화한다).
+     * 경계로 붙여도 사용자가 놀라지 않는 값에만 켠다. 켜면 범위 에러는 서지 않는다 —
+     * 고쳐 쓴 값은 언제나 범위 안이기 때문이다.
+     */
+    clampOnBlur?: boolean;
     /** 스텝 단위 */
     step?: number;
     /** 증감 버튼 표시 */
-    useButton?: boolean;
+    showButton?: boolean;
     /** 소수점 입력 허용 */
-    useDecimal?: boolean;
+    allowDecimal?: boolean;
     /** 소수점 이하 최대 자리수 */
     maxDecimalLength?: number;
     /** 입력 앞 접두 텍스트 */
@@ -29,7 +50,7 @@ export interface SNumberInputProps {
     /** 입력 뒤 접미 텍스트 */
     inputSuffix?: string;
     /** 네이티브 input className */
-    inputClass?: string;
+    inputClassName?: string;
     /** 네이티브 input style */
     inputStyle?: CSSProperties;
     /** 마운트 시 자동 포커스 */
@@ -46,9 +67,25 @@ export interface SNumberInputProps {
     /** 유효성 규칙 — blur 시 검증 */
     rules?: Rule[];
     status?: SFieldStatus;
+    /** 포커스 상태를 밖에서 지정한다 — 강조 테두리·링이 즉시 걸린다 (SField 로 그대로 넘어간다) */
     focused?: boolean;
+    /** 호버 상태를 밖에서 지정한다 — 강조는 `focused` 와 같다 (SField 로 그대로 넘어간다) */
     hovered?: boolean;
     label?: string;
+    /**
+     * 레이블 위치 — `top` 이면 라벨이 컨트롤 위에 선다 (SField 로 그대로 넘어간다).
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    labelPosition?: SFieldLabelPosition;
+    /**
+     * 보조 레이블 — 레이블 오른쪽 같은 줄에 붙는다 (SField 로 그대로 넘어간다).
+     *
+     * @nodemo SField 에서 내려오는 공통 필드 옵션이다 — 같은 데모를 컨트롤마다 복제하지 않고
+     * 대표 컨트롤 `SInput` 과 `SField` 에 한 번 둔다 (scripts/check-docs-coverage.mjs 머리말).
+     */
+    subLabel?: string;
     labelWidth?: number | string;
     icon?: SIconName;
     iconColor?: SColor;
@@ -59,7 +96,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;
 }