sellmate-design-system-react 9.0.0-beta.43 → 9.0.0-beta.44

package/AGENTS.md

@@ -476,7 +476,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 여러 줄 텍스트를 받는다 | `STextarea` | §3-7-1 |
 | 제목·굵게·목록·색 같은 **서식이 남아야 하는** 글을 받는다 | `SEditor` | §3-7-1 |
 | 목록·결과를 검색어로 좁힌다 | `SSearchInput` | §3-7-1 |
-| 숫자(수량·금액)를 받는다 | `SNumberInput` | |
+| 숫자(수량·금액)를 받는다 | `SNumberInput` | §3-7-13 |
 | 바코드를 스캔해 받는다 | `SBarcodeInput` | |
 | 목록에서 하나 고르게 한다 | `SSelect` | §3-7-2 |
 | 선택지를 항상 펼쳐 두고 하나 고르게 한다 | `SRadioGroup` | §3-7-2 |
@@ -1462,6 +1462,23 @@ const [from, setFrom] = useState<string | null>(null);
 ❌ <SListItem title="일반 문의" selected />                        {/* clickable 없으면 선택 표시가 안 나온다 */}
 ```
 
+##### 행 안에 컨트롤을 둘 때
+
+`renderItem` 이 앱 몫이라 행 안에 입력·버튼이 들어오는 것은 예외가 아니다 — 순서를 정하는 목록은 대개 「몇 번째로 보낼지」를 숫자로도 받는다. 그냥 두면 된다.
+
+- **행 선택은 옵트인이다.** `selectedKey`·`defaultSelectedKey`·`onSelectedKeyChange` 중 하나라도 주면 행이 `role="button"` 이 되어 클릭·Enter·Space 로 선택된다. 하나도 주지 않으면 행은 아무 상호작용도 갖지 않는다. **순서만 바꾸는 목록에 선택 prop 을 습관적으로 붙이지 않는다** — 붙이지 않아야 행 안의 컨트롤이 중첩 인터랙티브가 되지 않고 스크린리더에 그대로 노출된다.
+- **선택을 함께 쓰더라도 자손 컨트롤의 이벤트를 끊지 않는다.** 입력·버튼·링크에서 난 클릭과 Enter·Space 는 선택으로 새지 않는다 — 행의 제목 텍스트를 눌러 고르는 것만 선택으로 간다. `stopPropagation` 을 직접 넣을 자리가 아니다.
+
+```tsx
+✅ <SDraggableList items={rows} getKey={r => r.id}                    {/* 선택을 안 쓰면 선택 prop 도 없다 */}
+     renderItem={(row, _i, { onDragHandleMouseDown }) => (
+       <SDraggableItem title={row.name} onDragHandleMouseDown={onDragHandleMouseDown}
+         trailing={<SNumberInput width={72} value={row.order} onValueChange={…} />} />
+     )} />
+
+❌ <div onKeyDown={e => { e.stopPropagation(); … }}>                   {/* 리스트가 이미 걸러 준다 */}
+```
+
 #### 3-7-7. 펼치는 셋 — SExpansionItem vs SExpansionList vs STree
 
 | 판별 | 사용 |
@@ -1569,6 +1586,29 @@ const [selectedId, setSelectedId] = useState<string>();
 ❌ {loading ? <SCircleProgress indeterminate /> : <SImage src={url} />}        {/* SImage 가 이미 한다 */}
 ```
 
+#### 3-7-13. 숫자 — SNumberInput 의 min·max 는 검증 경계다
+
+`min`·`max` 는 `<input type="number">` 의 그것과 같다 — **값을 고쳐 쓰지 않는 검증 경계**다. 범위를 벗어나면 blur·제출 시 에러 상태가 서고, 사용자가 친 값은 그대로 남아 앱의 범위 가드에 도달한다.
+
+- **문구를 앱이 대지 않아도 된다.** `rules` 도 `SForm` 도 없는 화면에서 `min`·`max` 만 주면 DS 가 「1~99 사이로 입력해 주세요.」 같은 기본 안내를 자동으로 붙인다. 범위 이탈이 아무 표시 없이 지나가는 경로가 없다.
+- **화면의 말로 바꾸려면 `rules` 를 준다.** 「우선순위는 1부터」처럼 그 화면에서만 통하는 문구가 있으면 `rules` 가 DS 기본 문구를 이긴다. 앱이 직접 준 `errorMessage` 도 마찬가지다.
+- **`SForm` 안에서는 범위 이탈이 제출을 막는다.** `rules` 를 따로 걸지 않아도 그렇다 — 네이티브 폼과 같다.
+- **빈 칸(`null`)은 범위 판정 대상이 아니다.** 필수 입력은 `min` 이 아니라 `rules` 로 막는다.
+- **경계로 붙여도 사용자가 놀라지 않는 값에서만 `clampOnBlur` 를 켠다.** 켜면 blur 시 값이 경계로 **말없이 바뀌고** `onValueChange` 로 되쏘아진다 — 그래서 앱의 범위 가드에는 범위 밖 값이 도달하지 않는다. 재고 조정 수량처럼 보정이 자연스러운 자리에만 쓰고, 업무 규칙(최소 주문 수량·우선순위 시작값)에는 쓰지 않는다.
+- 스테퍼(`showButton`)와 위/아래 화살표는 `clampOnBlur` 와 무관하게 언제나 `min`·`max` 를 한계로 삼는다.
+
+```tsx
+✅ <SNumberInput label="우선순위" min={1} max={99} value={v} onValueChange={setV} />
+   {/* 0 을 넣고 blur 하면 0 이 남고 에러가 선다 — 저장 가드의 v < 1 이 그대로 걸린다 */}
+
+✅ <SNumberInput label="우선순위" min={1} max={99} value={v} onValueChange={setV}
+     rules={[v => (typeof v === 'number' && (v < 1 || v > 99) ? '우선순위는 1부터 99까지입니다.' : true)]} />
+   {/* 문구만 화면의 말로 바꾼다 */}
+
+❌ <SNumberInput label="우선순위" min={1} clampOnBlur value={v} onValueChange={setV} />
+   {/* 0 이 1 로 바뀐 뒤 도착하므로 저장 직전의 v < 1 가드는 영원히 걸리지 않는다 */}
+```
+
 ---
 
 ## 4. 페이지 레시피 — 표준 골격

package/dist/components/SDraggableList/README.md

@@ -25,8 +25,8 @@
 | `items` | `T[]` | — | 현재 순서대로 렌더링할 아이템 목록 |
 | `getKey` | `(item: T, index: number) => string` | — | 아이템을 식별할 안정적인 key |
 | `renderItem` | `(item: T, index: number, state: SDraggableListRenderState) => ReactNode` | — | 아이템 렌더링 함수 |
-| `selectedKey?` | `string` | — | 외부에서 제어하는 selected 아이템 key |
-| `defaultSelectedKey?` | `string` | — | 초기 selected 아이템 key |
+| `selectedKey?` | `string` | — | 외부에서 제어하는 selected 아이템 key. 이 셋(`selectedKey`·`defaultSelectedKey`·`onSelectedKeyChange`) 중 하나라도 주면 **행 선택이 켜진다** — 행이 `role="button"` 이 되어 클릭·Enter·Space 로 선택된다. 아무것도 주지 않으면 행은 아무 상호작용도 갖지 않는다. |
+| `defaultSelectedKey?` | `string` | — | 초기 selected 아이템 key. 주면 행 선택이 켜진다 (`selectedKey` 참조) |
 | `getDisabled?` | `(item: T, index: number) => boolean` | — | disabled 아이템은 선택 및 드래그에서 제외 |
 | `getDepth?` | `(item: T, index: number) => number` | — | 아이템의 중첩 단계. 기본값은 1 |
 | `setDepth?` | `(item: T, depth: number) => T` | — | depth 변경이 필요한 드롭에서 다음 아이템을 만드는 함수 |
@@ -40,7 +40,7 @@
 | Event | Type | Description |
 |-------|------|-------------|
 | `onChange` | `(items: T[]) => void` | 단독 리스트에서 드래그가 끝난 뒤 변경된 순서 |
-| `onSelectedKeyChange` | `(key: string) => void` | selected 아이템이 변경될 때 호출 |
+| `onSelectedKeyChange` | `(key: string) => void` | selected 아이템이 변경될 때 호출. 주면 행 선택이 켜진다 (`selectedKey` 참조) |
 
 ### SDraggableProvider
 

package/dist/components/SDraggableList/SDraggableList.d.ts

@@ -16,11 +16,15 @@ export interface SDraggableListProps<T> extends Omit<SListProps, 'children' | 'o
     renderItem: (item: T, index: number, state: SDraggableListRenderState) => ReactNode;
     /** 단독 리스트에서 드래그가 끝난 뒤 변경된 순서 */
     onChange?: (items: T[]) => void;
-    /** 외부에서 제어하는 selected 아이템 key */
+    /**
+     * 외부에서 제어하는 selected 아이템 key.
+     * 이 셋(`selectedKey`·`defaultSelectedKey`·`onSelectedKeyChange`) 중 하나라도 주면 **행 선택이 켜진다** —
+     * 행이 `role="button"` 이 되어 클릭·Enter·Space 로 선택된다. 아무것도 주지 않으면 행은 아무 상호작용도 갖지 않는다.
+     */
     selectedKey?: string;
-    /** 초기 selected 아이템 key */
+    /** 초기 selected 아이템 key. 주면 행 선택이 켜진다 (`selectedKey` 참조) */
     defaultSelectedKey?: string;
-    /** selected 아이템이 변경될 때 호출 */
+    /** selected 아이템이 변경될 때 호출. 주면 행 선택이 켜진다 (`selectedKey` 참조) */
     onSelectedKeyChange?: (key: string) => void;
     /** disabled 아이템은 선택 및 드래그에서 제외 */
     getDisabled?: (item: T, index: number) => boolean;

package/dist/components/SNumberInput/README.md

@@ -10,8 +10,9 @@
 |------|------|---------|-------------|
 | `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` | 스텝 단위 |
 | `showButton?` | `boolean` | `false` | 증감 버튼 표시 |
 | `allowDecimal?` | `boolean` | `false` | 소수점 입력 허용 |

package/dist/components/SNumberInput/SNumberInput.d.ts

@@ -13,10 +13,30 @@ 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;
     /** 증감 버튼 표시 */

package/dist/components/STable/README.md

@@ -25,7 +25,7 @@
 | `emptySlot?` | `ReactNode` | — | 데이터가 없을 때 body 영역 전체를 대체하는 슬롯. 지정하면 `emptyLabel` 대신 이 콘텐츠가 헤더 아래 영역을 채우며, 버튼 등 인터랙션도 동작한다. |
 | `loading?` | `boolean` | `false` |  |
 | `dense?` | `boolean` | `false` | 행 높이를 좁게 (세로 여백만 줄인다 — 좌우 패딩은 그대로). **시작 밀도이자 밀도 토글의 스위치다.** 켜면 하단 바 우측에 `좁게 보기` · `넓게 보기` 토글이 붙는다 — 페이지네이션이 없으면 이 바를 토글만 담아 그린다. 누른 뒤의 밀도는 테이블이 내부 상태로 들고 가므로 `onDenseChange` 를 받지 않아도 토글은 동작하고, 넓게 본 뒤에도 토글은 그대로 남는다(붙일지는 이 prop 이 정한다). 이 prop 값이 바뀌면 내부 밀도도 그 값으로 맞춰진다. |
-| `hoverable?` | `boolean` | `true` | true면 행에 마우스를 올려도 hover 배경(grey_05)을 표시하지 않는다 |
+| `hoverable?` | `boolean` | `true` | 행에 마우스를 올렸을 때 hover 배경(grey_05)을 표시할지. 기본 `true` — `false` 면 표시하지 않는다 |
 | `pagination?` | `STablePagination` | — | 페이지네이션 (있으면 하단 표시) |
 | `internalPagination?` | `boolean` | `false` | 테이블 내부에서 페이지네이션을 직접 관리 (rows를 내부 슬라이싱) |
 | `showRowsPerPageSelect?` | `boolean` | `false` | 페이지당 행 수 셀렉트 표시 |

package/dist/components/STable/STable.d.ts

@@ -244,7 +244,7 @@ export interface STableProps {
      * 사용자가 고른 밀도를 다음 방문까지 기억해 두려는(로컬 저장 등) 페이지만 받으면 된다.
      */
     onDenseChange?: (dense: boolean) => void;
-    /** true면 행에 마우스를 올려도 hover 배경(grey_05)을 표시하지 않는다 */
+    /** 행에 마우스를 올렸을 때 hover 배경(grey_05)을 표시할지. 기본 `true` — `false` 면 표시하지 않는다 */
     hoverable?: boolean;
     /** 페이지네이션 (있으면 하단 표시) */
     pagination?: STablePagination;

package/dist/index.cjs

@@ -4293,6 +4293,13 @@ function SDraggableProvider({ children }) {
 function SDraggableGroup({ children, onMove, ...rest }) {
   return /* @__PURE__ */ jsxRuntime.jsx(SDraggableProviderInternal, { defaultGroup: "__legacy", legacyOnMove: onMove, children: /* @__PURE__ */ jsxRuntime.jsx("div", { ...rest, children }) });
 }
+var INTERACTIVE_DESCENDANT_SELECTOR = 'input,textarea,select,button,a[href],label,[contenteditable="true"],[role="button"],[role="checkbox"],[role="radio"],[role="switch"],[role="tab"],[role="menuitem"]';
+function isFromInteractiveDescendant(event) {
+  const target = event.target;
+  if (target == null || target === event.currentTarget) return false;
+  const interactive = target.closest?.(INTERACTIVE_DESCENDANT_SELECTOR);
+  return interactive != null && interactive !== event.currentTarget;
+}
 function reorder(items, fromIndex, toIndex) {
   if (fromIndex === toIndex) return items;
   const nextItems = [...items];
@@ -4376,6 +4383,7 @@ function SDraggableListInner({
   const listRef = react.useRef(null);
   const fromIndexRef = react.useRef(null);
   const currentSelectedKey = selectedKey ?? internalSelectedKey;
+  const selectable = selectedKey !== void 0 || defaultSelectedKey !== void 0 || onSelectedKeyChange != null;
   const usesDepth = getDepth != null;
   const depthEnabled = usesDepth && !gap;
   const groupDragging = dragContext?.dragging;
@@ -4535,20 +4543,28 @@ function SDraggableListInner({
           setInternalSelectedKey(itemKey);
           onSelectedKeyChange?.(itemKey);
         };
+        const handleItemClick = (event) => {
+          if (isFromInteractiveDescendant(event)) return;
+          selectItem();
+        };
         const handleItemKeyDown = (event) => {
+          if (event.target !== event.currentTarget) return;
           if (event.key !== "Enter" && event.key !== " ") return;
           event.preventDefault();
           selectItem();
         };
+        const selectionProps = selectable ? {
+          role: "button",
+          tabIndex: disabled ? -1 : 0,
+          onClick: handleItemClick,
+          onKeyDown: handleItemKeyDown
+        } : {};
         return /* @__PURE__ */ jsxRuntime.jsxs(
           "div",
           {
             "data-draggable-list-item": true,
-            role: "button",
-            tabIndex: disabled ? -1 : 0,
             "aria-disabled": disabled || void 0,
-            onClick: selectItem,
-            onKeyDown: handleItemKeyDown,
+            ...selectionProps,
             className: "relative",
             children: [
               showBefore && /* @__PURE__ */ jsxRuntime.jsx(
@@ -14684,6 +14700,16 @@ var formatInputWithCommas = (value) => {
   const formattedInt = addCommas(intPart === "" ? "0" : intPart);
   return `${isNeg ? "-" : ""}${formattedInt}${hasDecimal ? `.${decPart}` : ""}`;
 };
+var getRangeError = (value, min, max) => {
+  if (value === null) return "";
+  const belowMin = value < min;
+  const aboveMax = value > max;
+  if (!belowMin && !aboveMax) return "";
+  if (Number.isFinite(min) && Number.isFinite(max)) {
+    return `${formatWithCommas(min)}~${formatWithCommas(max)} \uC0AC\uC774\uB85C \uC785\uB825\uD574 \uC8FC\uC138\uC694.`;
+  }
+  return belowMin ? `${formatWithCommas(min)} \uC774\uC0C1\uC73C\uB85C \uC785\uB825\uD574 \uC8FC\uC138\uC694.` : `${formatWithCommas(max)} \uC774\uD558\uB85C \uC785\uB825\uD574 \uC8FC\uC138\uC694.`;
+};
 var getDecimalLimit = (allowDecimal, maxDecimalLength) => {
   if (!allowDecimal || maxDecimalLength === void 0 || !Number.isFinite(maxDecimalLength)) {
     return void 0;
@@ -14714,6 +14740,7 @@ var SNumberInput = /* @__PURE__ */ react.forwardRef(function SNumberInput2({
   min = Number.NEGATIVE_INFINITY,
   max = Number.POSITIVE_INFINITY,
   step = 1,
+  clampOnBlur = false,
   showButton = false,
   allowDecimal = false,
   maxDecimalLength,
@@ -14753,6 +14780,7 @@ var SNumberInput = /* @__PURE__ */ react.forwardRef(function SNumberInput2({
   const numValue = applyDecimalLimit(toNumber(value), decimalLimit);
   const [display, setDisplay] = react.useState(() => formatWithCommas(numValue));
   const [ruleError, setRuleError] = react.useState("");
+  const [rangeError, setRangeError] = react.useState("");
   const innerRef = react.useRef(null);
   const valueTooltip = useTruncatedValueTooltip({ enabled: readOnly && !disabled, text: display });
   const setRefs2 = (el) => {
@@ -14770,12 +14798,19 @@ var SNumberInput = /* @__PURE__ */ react.forwardRef(function SNumberInput2({
     validate: () => {
       const msg = runRules(numValue, rules);
       setRuleError(msg);
-      return msg === "";
+      const range = clampOnBlur ? "" : getRangeError(numValue, min, max);
+      setRangeError(range);
+      return msg === "" && range === "";
     },
-    resetValidation: () => setRuleError("")
+    resetValidation: () => {
+      setRuleError("");
+      setRangeError("");
+    }
   });
-  const resolvedError = error || ruleError !== "";
-  const resolvedStatus = status ?? (rules && rules.length > 0 ? ruleError !== "" ? "error" : void 0 : void 0);
+  const autoError = ruleError !== "" ? ruleError : rangeError;
+  const resolvedError = error || autoError !== "";
+  const resolvedStatus = status ?? (autoError !== "" ? "error" : void 0);
+  const resolvedErrorMessage = ruleError !== "" ? ruleError : (errorMessage ?? "") !== "" ? errorMessage : rangeError;
   const restoreCaret = (nextDisplay, logicalCaret) => {
     const input = innerRef.current;
     if (logicalCaret === void 0 || !input || document.activeElement !== input) return;
@@ -14907,7 +14942,7 @@ var SNumberInput = /* @__PURE__ */ react.forwardRef(function SNumberInput2({
       status: resolvedStatus,
       focused,
       hovered,
-      errorMessage: ruleError !== "" ? ruleError : errorMessage,
+      errorMessage: resolvedErrorMessage,
       width,
       disabled,
       readOnly,
@@ -14953,10 +14988,11 @@ var SNumberInput = /* @__PURE__ */ react.forwardRef(function SNumberInput2({
                 onBlur: (e) => {
                   const cleaned = display.replace(/,/g, "");
                   const n = toNumber(cleaned);
-                  const clamped = n === null ? null : Math.min(Math.max(n, min), max);
+                  const clamped = !clampOnBlur || n === null ? n : Math.min(Math.max(n, min), max);
                   if (clamped !== n) emit3(clamped);
                   else setDisplay(n === null ? "" : formatInputWithCommas(cleaned));
                   if (rules && rules.length > 0) setRuleError(runRules(clamped, rules));
+                  setRangeError(clampOnBlur ? "" : getRangeError(clamped, min, max));
                   onBlur?.(e);
                 },
                 className: cn(