sellmate-design-system-react 9.0.0-beta.2 → 9.0.0-beta.21

package/README.md

@@ -186,6 +186,8 @@ export default [
 | `sellmate/component-group-gap`   | warn      | 같은 컴포넌트를 나열할 때의 그룹 간격 — 배열 방향에 따라 값이 다르다(체크박스 가로 24 / 세로 8)                                                                                                         |
 | `sellmate/table-numeric-align`   | warn      | 수량 컬럼(금액·수량 등)에 `align: 'right'` 누락 — **`--fix` 로 자동 교정**                                                                                                                              |
 | `sellmate/require-locale-number` | warn      | 수량 컬럼의 `toLocaleString()` 누락 — 세 자리 콤마                                                                                                                                                      |
+| `sellmate/field-width-grade`     | warn      | 필드 폭이 `maxLength`(스키마 상한)와 어긋남 — 등급 미지정 · 등급 밖 폭 · 상한 대비 과부족 · 등급 px 직접 지정(**`--fix` 로 등급 이름 치환**)                                                            |
+| `sellmate/table-column-width`    | warn      | 컬럼 폭 미지정(기본 120px 이 조용히 들어감) · px 아닌 폭(`%` `clamp()`) · 값을 그리는 열의 `autoWidth` 오용                                                                                             |
 | `sellmate/no-arbitrary-class`    | **off**   | 토큰이 있는 속성(색·타이포·간격·모서리)의 임의 값 — `text-[14px]`, `bg-[#eee]`. 앱 고유 화면에는 정당한 사용이 많아 기본값은 끕니다                                                                     |
 
 `className` 뿐 아니라 `cn()`/`clsx()` 인자, 템플릿 리터럴, 객체 키 안까지 검사합니다.
@@ -237,6 +239,105 @@ export default [
 'sellmate/table-numeric-align': ['error', { allow: ['rank'] }],
 ```
 
+### 필드 폭 등급 (`field-width-grade`)
+
+필드 너비는 **`maxLength`(= 스키마 상한)로 정합니다.** 상한이 등급 안에 들어오면 그 등급으로 고정하고,
+등급 상한(`xl`)을 넘거나 상한이 아예 없으면 행 전체(`width="100%"` 또는 생략)로 둡니다.
+
+**폭은 등급 이름으로 줍니다** — `width="md"` 처럼 씁니다. 등급은 `--cmp-field-width-*` 토큰으로
+풀리므로 토큰이 바뀌면 화면이 따라갑니다. 같은 값을 px 로 적으면 그 화면만 옛 값에 남습니다.
+
+| 등급 | 쓰는 곳       |
+| ---- | ------------- |
+| `xs` | 숫자 필드 전용 |
+| `sm` |               |
+| `md` |               |
+| `lg` |               |
+| `xl` | 정책상 상한    |
+
+```tsx
+// 상한이 등급 안에 들어온다 → 그 등급으로 고정
+<SInput name="code" label="코드" maxLength={10} width="md" />
+
+// 상한이 xl 로도 안 담긴다 → 행 전체
+<SInput name="desc" label="설명" maxLength={100} width="100%" />
+
+// 숫자 필드의 상한은 maxLength 가 아니라 max 다 (천단위 콤마도 폭을 먹는다)
+<SNumberInput name="qty" label="수량" max={99} width="xs" />
+
+// 등급 값과 같은 px 를 적으면 등급 이름으로 자동 수정됩니다 (--fix)
+<SInput name="code" label="코드" maxLength={10} width={160} />   // → width="md"
+```
+
+대상은 `SInput` · `SNumberInput` · `SBarcodeInput` 입니다. `STextarea` 는 여러 줄로 접혀 상한이 폭을
+정하지 않고, 셀렉트 계열은 상한 개념이 없어 목록 최장값으로 폭을 정하며, 날짜·시간 계열은 컴포넌트가
+자체 상한을 갖습니다.
+
+**상한도 폭도 변수로 넘기면 검사하지 않습니다.** 정적으로 알 수 없는 것을 위반으로 보고하지 않습니다.
+
+```tsx
+<SInput maxLength={LIMIT} width={fieldWidth} />   // 통과
+<SInput maxLength={10} {...rest} />               // 통과 (spread 안에 width 가 있을 수 있다)
+```
+
+#### 글자수 환산
+
+등급이 몇 글자를 담는지는 토큰 값(글꼴 크기 · 좌우 패딩 · 테두리 · 스테퍼)에서 계산합니다.
+한글은 전각이라 영숫자의 약 두 배를 먹으므로 **두 기준 사이에는 아무것도 보고하지 않습니다** —
+영숫자로 채워도 넘칠 때만 "좁다", 한글로 채워도 남을 때만 "넓다" 로 판정합니다.
+
+| 등급 | `SInput` (sm) | `SInput` (md) | `SNumberInput` (sm) | `SNumberInput` (sm, `useButton`) |
+| ---- | ------------- | ------------- | ------------------- | -------------------------------- |
+| `xs` | —             | —             | 영숫자 8            | 영숫자 2                         |
+| `sm` | 영숫자 14 / 한글 7  | 영숫자 11 / 한글 6  | 영숫자 14           | 영숫자 8                         |
+| `md` | 영숫자 20 / 한글 11 | 영숫자 16 / 한글 9  | 영숫자 20           | 영숫자 14                        |
+| `lg` | 영숫자 32 / 한글 17 | 영숫자 26 / 한글 14 | 영숫자 32           | 영숫자 26                        |
+| `xl` | 영숫자 68 / 한글 37 | 영숫자 57 / 한글 31 | 영숫자 68           | 영숫자 62                        |
+
+`SNumberInput` 은 `useButton` 여부로 글자 자리가 크게 갈립니다 — 스테퍼가 없으면 좌우 패딩이
+두 배가 되고(기본값), 있으면 버튼 두 개와 간격이 폭을 먹습니다. 규칙은 JSX 의 `useButton` 을 읽어
+둘을 구분합니다.
+
+등급 폭은 `--cmp-field-width-*` 토큰에서 읽으므로 규칙과 컴포넌트가 같은 값을 봅니다.
+글자수 환산 비율이 팀 기준과 다르면 옵션으로 덮습니다(등급 폭도 덮을 수 있지만, 토큰과 어긋나게 됩니다).
+
+```js
+'sellmate/field-width-grade': ['warn', {
+  charRatio: { narrow: 0.55, wide: 1 },
+}],
+```
+
+### 컬럼 폭 (`table-column-width`)
+
+`STable` 의 컬럼 폭은 `<colgroup>` 의 `<col width>` 로 들어가고 테이블이 `table-fixed` 라,
+**px 이 아닌 값은 에러 없이 화면만 틀어집니다** — `'30%'` 는 `30`(px)으로 읽히고, `clamp()` 같은
+함수형 값은 폭이 통째로 무효가 된 뒤 auto 로 떨어집니다.
+
+```tsx
+// 내용이 들어가는 열은 전부 폭을 명시한다 (생략하면 기본 120px 이 조용히 들어간다)
+{ name: 'name', label: '이름', field: 'name', width: 160 }
+{ name: 'code', label: '코드', field: 'code', width: '120px' }
+
+// autoWidth 는 남은 폭을 흡수하는 스페이서 열 하나에만 (값을 그리지 않으므로 field 도 없다)
+{ name: 'spacer', label: '', autoWidth: true }
+
+// ❌ 조용히 깨진다
+{ name: 'ratio', label: '비율', field: 'ratio', width: '30%' }
+// ❌ 값을 그리는 열의 autoWidth — 폭이 다른 열에 좌우돼 화면마다 달라진다
+{ name: 'title', label: '상품명', field: 'title', autoWidth: true, render: r => r.title }
+```
+
+검사 대상은 `name`(문자열 리터럴) · `label` 에 더해 **`field` 또는 `autoWidth` 를 가진 객체**입니다.
+검색 필터 필드나 상세 모달의 키-값 필드가 컬럼과 같은 `{ name, label, ... }` 모양이라, 그 둘만으로
+판정하면 표와 무관한 객체가 대부분 걸리기 때문입니다. 대신 `{ ...base, name, label }` 처럼 `field` 가
+스프레드로 들어오는 컬럼은 보고하지 않습니다 — 정적으로 필터 필드와 구분되지 않습니다.
+
+예외는 컬럼 `name` 을 `allow` 로 지정해 뺍니다.
+
+```js
+'sellmate/table-column-width': ['warn', { allow: ['spacer'] }],
+```
+
 ### 더 엄격하게 / 더 느슨하게
 
 `configs.strict` 는 전 규칙을 error 로 올리고, `<ul>` `<ol>` `<li>` `<svg>` `<label>` 까지 검사하며, 간격 유틸리티에 `sd-` 접두를 강제합니다(`requirePrefix`). 디자인 시스템 규칙을 처음부터 전면 적용하는 신규 프로젝트용입니다.

package/dist/components/SBadge/README.md

@@ -10,6 +10,30 @@
 |------|------|---------|-------------|
 | `color?` | `SBadgeColor` | `'blue'` | 뱃지 색상 |
 
+## Types
+
+### SBadgeColor
+
+```ts
+export type SBadgeColor = (typeof BADGE_COLORS)[number];
+```
+
+### BADGE_COLORS
+
+```ts
+export const BADGE_COLORS = [
+  'red',
+  'orange',
+  'yellow',
+  'green',
+  'lightblue',
+  'blue',
+  'darkblue',
+  'indigo',
+  'grey',
+] as const;
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SBadge/SBadge.d.ts

@@ -1,5 +1,5 @@
 import { type HTMLAttributes } from 'react';
-export declare const BADGE_COLORS: readonly ["red", "orange", "yellow", "green", "blue", "darkblue", "indigo", "grey"];
+export declare const BADGE_COLORS: readonly ["red", "orange", "yellow", "green", "lightblue", "blue", "darkblue", "indigo", "grey"];
 export type SBadgeColor = (typeof BADGE_COLORS)[number];
 export interface SBadgeProps extends HTMLAttributes<HTMLSpanElement> {
     /** 뱃지 색상 */

package/dist/components/SBarcodeInput/README.md

@@ -35,7 +35,7 @@
 | `hint?` | `string` | — |  |
 | `error?` | `boolean` | — |  |
 | `errorMessage?` | `string` | — |  |
-| `width?` | `number \| string` | — |  |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 등급은 `--cmp-field-width-*` 토큰으로 풀리며 `maxLength`(= 스키마 상한)로 고른다. 상한이 `xl` 을 넘거나 상한이 없으면 `"100%"`. (`sellmate/field-width-grade` 가 검사한다) |
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
 
@@ -47,6 +47,14 @@
 | `onFocus` | `() => void` |  |
 | `onBlur` | `() => void` |  |
 
+## Types
+
+### SBarcodeInputSize
+
+```ts
+export type SBarcodeInputSize = SFieldSize;
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/SBarcodeInput/SBarcodeInput.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 type SBarcodeInputSize = SFieldSize;
 export interface SBarcodeInputProps {
     value?: string | number | null;
@@ -39,7 +40,12 @@ export interface SBarcodeInputProps {
     hint?: string;
     error?: boolean;
     errorMessage?: string;
-    width?: number | string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 등급은 `--cmp-field-width-*` 토큰으로 풀리며 `maxLength`(= 스키마 상한)로 고른다.
+     * 상한이 `xl` 을 넘거나 상한이 없으면 `"100%"`. (`sellmate/field-width-grade` 가 검사한다)
+     */
+    width?: SFieldWidth;
     className?: string;
     style?: CSSProperties;
 }

package/dist/components/SButton/README.md

@@ -15,12 +15,47 @@
 | `rightIcon?` | `SIconName` | — | 레이블 오른쪽 아이콘 |
 | `label?` | `string` | — | 버튼 텍스트 (문자열만 — 아이콘은 icon/rightIcon 사용) |
 
+## Types
+
+### SButtonColor
+
+```ts
+export type SButtonColor = (typeof BUTTON_COLORS)[number];
+```
+
+### SButtonSize
+
+```ts
+export type SButtonSize = (typeof BUTTON_SIZES)[number];
+```
+
+### BUTTON_COLORS
+
+```ts
+/**
+ * SButton 색상/사이즈 설정 — sd-button(component.button 토큰) 충실 포팅.
+ * Stencil `name`(예: primary_sm)의 preset을 color + outline(boolean) + size 로 분리.
+ *  - primary / danger : solid·outline 모두 지원
+ *  - secondary        : solid 전용 (outline 스타일 없음 → outline 무시)
+ *  - neutral          : 흰 배경 고정, outline 은 회색 테두리만 추가(solid = 테두리 없는 흰 버튼)
+ * 색상은 theme.css의 `--cmp-button-*` CSS 변수를 참조한다.
+ */
+export const BUTTON_COLORS = ['primary', 'secondary', 'neutral', 'danger'] as const;
+```
+
+### BUTTON_SIZES
+
+```ts
+export const BUTTON_SIZES = ['xs', 'sm', 'md', 'lg'] as const;
+```
+
 ## Dependencies
 
 ### Used by
 
  - [SConfirmModal](../SConfirmModal)
  - [SDropdownButton](../SDropdownButton)
+ - [SEditor](../SEditor)
  - [SFooter](../SFooter)
  - [SKeyValueTable](../SKeyValueTable)
  - [SLoadingModal](../SLoadingModal)
@@ -38,6 +73,7 @@ graph TD;
   SButton --> SIcon
   SConfirmModal --> SButton
   SDropdownButton --> SButton
+  SEditor --> SButton
   SFooter --> SButton
   SKeyValueTable --> SButton
   SLoadingModal --> SButton

package/dist/components/SCalendar/README.md

@@ -22,6 +22,19 @@
 | `onValueChange` | `(date: string) => void` | 선택 변경 (sdUpdate) |
 | `onViewChange` | `(v: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
 
+## Types
+
+### SCalendarEventGroup
+
+```ts
+export interface SCalendarEventGroup {
+  /** 도트 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 */
+  color: SColor;
+  label: string;
+  dates: string[];
+}
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SCallout/README.md

@@ -14,6 +14,21 @@
 | `className?` | `string` | — |  |
 | `style?` | `CSSProperties` | — |  |
 
+## Types
+
+### SCalloutType
+
+```ts
+export type SCalloutType = 'default' | 'danger';
+```
+
+### SCalloutMessage
+
+```ts
+/** 중첩 메시지: 문자열 또는 (한 단계 더 들어간) 문자열 배열 */
+export type SCalloutMessage = string | SCalloutMessage[];
+```
+
 ## Dependencies
 
 ### Depends on

package/dist/components/SCard/README.md

@@ -9,4 +9,20 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `bordered?` | `boolean` | `false` | 테두리 표시 여부 |
+| `footerLeft?` | `ReactNode` | — | 하단 액션 영역 좌측 슬롯. 보조 버튼(취소·목록 등)이 오는 자리다. `footerLeft` 또는 `button` 중 하나라도 있으면 하단 액션 영역이 렌더된다. |
+| `button?` | `SFooterButton` | — | 하단 액션 영역 우측 주 액션 버튼 |
+| `footerClassName?` | `string` | — | 하단 액션 영역 클래스 |
 
+## Dependencies
+
+### Depends on
+
+- [SFooter](../SFooter)
+
+### Graph
+
+```mermaid
+graph TD;
+  SCard --> SFooter
+  style SCard fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SCard/SCard.d.ts

@@ -1,7 +1,22 @@
-import { type HTMLAttributes } from 'react';
+import { type HTMLAttributes, type ReactNode } from 'react';
+import { type SFooterButton } from '../SFooter';
 export interface SCardProps extends HTMLAttributes<HTMLDivElement> {
     /** 테두리 표시 여부 */
     bordered?: boolean;
+    /**
+     * 하단 액션 영역 좌측 슬롯. 보조 버튼(취소·목록 등)이 오는 자리다.
+     * `footerLeft` 또는 `button` 중 하나라도 있으면 하단 액션 영역이 렌더된다.
+     */
+    footerLeft?: ReactNode;
+    /** 하단 액션 영역 우측 주 액션 버튼 */
+    button?: SFooterButton;
+    /** 하단 액션 영역 클래스 */
+    footerClassName?: string;
 }
-/** SCard — sd-card 포팅. 라운드 8px, 흰 배경, 옵션 테두리. */
+/**
+ * SCard — sd-card 포팅. 라운드 8px, 흰 배경, 옵션 테두리. 콘텐츠는 라운드 경계에서 잘린다.
+ *
+ * 하단 액션은 `children` 에 직접 두지 않고 `footerLeft`·`button` 으로 넘긴다 — 배경·구분선·여백과
+ * 양끝 분리가 컴포넌트 규칙대로 잡히는 자리다.
+ */
 export declare const SCard: import("react").ForwardRefExoticComponent<SCardProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/SCheckbox/README.md

@@ -22,6 +22,14 @@
 |-------|------|-------------|
 | `onValueChange` | `(value: boolean \| unknown[]) => void` | 값 변경 (sdUpdate) |
 
+## Types
+
+### SCheckboxValue
+
+```ts
+export type SCheckboxValue = boolean | unknown[] | null;
+```
+
 ## Dependencies
 
 ### Used by