sellmate-design-system-react 9.0.0-beta.75 → 9.0.0-beta.76

package/AGENTS.md

@@ -1053,6 +1053,25 @@ const columns: STableColumn[] = [
 - **계산값은 픽셀 단위까지 맞추면 어긋난다** — 서브픽셀 반올림 때문이다. 여유 8px 을 얹고 8 단위로 올림한다.
 - 좌우 패딩은 `STable` 이 토큰으로 넣으므로 직접 주지 않는다. 그만큼을 뺀 나머지가 요소 몫이라는 점만 계산에 넣는다.
 
+#### 행 타입을 알면 넘긴다
+
+`STable`·`STableColumn` 은 행 타입을 받는다. 넘기면 `render`·`format`·`onRowClick`·`selected` 가 그 타입으로 좁혀져, 없는 키나 오타가 컴파일에서 잡힌다. 넘기지 않으면 행은 `SRow`(키만 아는 느슨한 레코드)다 — 기존 코드는 그대로 동작한다.
+
+```tsx
+interface Order { id: number; orderNo: string; qty: number }
+
+const columns: STableColumn<Order>[] = [
+  { name: 'orderNo', label: '주문번호', field: 'orderNo', width: 140, align: 'center' },
+  { name: 'qty', label: '수량', field: 'qty', width: 80, align: 'right',
+    format: v => `${Number(v).toLocaleString()}개` },
+];
+
+<STable<Order> columns={columns} rows={orders} onRowClick={order => open(order.id)} />
+```
+
+- 행 타입을 넘기면 `format`·`render` 의 **셀 값은 `unknown`** 이다. `field` 가 접근 함수일 수도 있어 행 타입만으로는 값의 타입이 정해지지 않으므로, `Number(v)`·`String(v)` 로 받는 쪽에서 확인한다. 행이 필요하면 두 번째 인자(`format`)·첫 번째 인자(`render`)의 행을 쓴다.
+- `SSelect` 도 같은 방식으로 `onValueChange` 의 값 타입을 받는다 — `<SSelect<string> valueAsPrimitive … />`. 실제 모양은 `type`·`valueAsPrimitive` 조합이 정하므로 그 조합에 맞는 타입을 넘긴다.
+
 #### 컨트롤이 들어가는 컬럼
 
 `<td>` 는 폭을 넘는 내용을 잘라낸다(`overflow: hidden`). 텍스트라면 말줄임으로 끝나지만, 셀에 `STag` · `SButton` · `SGhostButton` · `SSelect` · `SInput` · `SNumberInput` 처럼 **자기 폭을 가진 요소**를 넣으면 요소 자체가 잘려 **누르거나 읽거나 입력할 수 없게 된다.**
@@ -1733,6 +1752,11 @@ tableRef.current.scrollToRow(row);                  // 복원
 - 카드 안에 상태 배지를 넣으려면 `tag` 슬롯에 `STag` 를 준다. 라벨 문자열에 "(추천)" 처럼 섞어 쓰지 않는다.
 - **카드처럼 생겼다고 `SCard`/`SSectionHeaderCard` 로 감싸지 않는다.** `SRadioCard` 자체가 완결된 요소이고, 나열 간격은 `SRadioCardGroup` 의 `direction` 이 맞춘다 (§2-2).
 
+##### 옵션을 서버에서 받는 동안 — `loading`
+
+- **받는 동안 `loading` 을 켠다.** 트리거의 펼침 아이콘 자리에 스피너가, 드롭다운에 로딩 행이 뜬다. 첫 조회든 다음 페이지든 같은 prop 이다.
+- **셀렉트 옆에 따로 스피너를 두거나 `disabled` 로 잠가 로딩을 표현하지 않는다.** 로딩 중에도 열 수 있고, 열면 "표시할 항목이 없습니다." 대신 로딩 행이 나온다. `disabled` 와 `loading` 을 함께 주지 않는다 — 비활성이면 `loading` 을 무시해 스피너가 뜨지 않는다. 잠긴 셀렉트의 옵션은 잠금이 풀릴 때 받는다.
+
 ##### 옵션이 수백~수천 개면 — `onReachEnd`
 
 **렌더는 걱정하지 않아도 된다.** `SSelect` 는 언제나 보이는 범위의 행만 그린다 — 켜고 끄는 prop 이 없고, 옵션이 5개든 5,000개든 여는 비용이 같다. 행 높이가 균일하다고 가정하지도 않으므로 계층 목록이나 큰 글씨가 섞인 라벨도 그대로 넘기면 된다.
@@ -1993,6 +2017,17 @@ const [selectedId, setSelectedId] = useState<string>();
 
 `SCircleProgress` 는 `indeterminate` 로 두면 스피너가 된다. **다만 화면이나 영역을 막아야 하는 상황이면 progress 가 아니라 `SLoadingModal`·`SLoadingContainer` 다** (§3-2) — 진행 표시와 입력 차단은 다른 일이고, 막지 않으면 사용자가 로딩 중에 또 누른다.
 
+`type` 은 진행 **상태**로 고른다. 색이 아니라 상태가 기준이다.
+
+| 상태 | `type` |
+| --- | --- |
+| 정상 진행 중 | `primary` |
+| 진행은 계속되지만 제품이 정한 기준에 미달해 주의가 필요하다 | `warning` |
+| 실패·중단 등 더 이상 정상적으로 진행되지 않는다 | `error` |
+| 완료 | `complete` |
+
+**`warning` 과 `error` 는 "아직 진행 중인가" 로 가른다.** 기준 미달이어도 진행이 계속되면 `warning` 이다 — `error` 로 칠하면 멈춘 작업으로 읽힌다. 미달 기준은 디자인 시스템이 정하지 않으므로 제품 코드에서 판정해 `type` 을 넘긴다.
+
 #### 3-7-10. SPortal — 직접 쓸 일이 거의 없다
 
 `STooltip`·`SPopover`·`SSelect`·날짜 피커가 내부에서 쓰는 저수준 레이어다. 앵커에 붙여 띄우는 동작이 필요하면 **먼저 §3-3 에서 대응 컴포넌트를 찾는다.** `SPortal` 을 직접 쓰는 것은 그 넷 중 어느 것도 아닌 새로운 부착형 레이어를 만들 때뿐이고, 그때도 모달 안에서 열릴 수 있다면 소속 컨테이너를 맞춰야 한다.

package/README.md

@@ -261,12 +261,12 @@ export default [
 **폭은 등급 이름으로 줍니다** — `width="md"` 처럼 씁니다. 등급은 `--cmp-field-width-*` 토큰으로
 풀리므로 토큰이 바뀌면 화면이 따라갑니다. 같은 값을 px 로 적으면 그 화면만 옛 값에 남습니다.
 
-| 등급 | 쓰는 곳       |
-| ---- | ------------- |
+| 등급 | 쓰는 곳        |
+| ---- | -------------- |
 | `xs` | 숫자 필드 전용 |
-| `sm` |               |
-| `md` |               |
-| `lg` |               |
+| `sm` |                |
+| `md` |                |
+| `lg` |                |
 | `xl` | 정책상 상한    |
 
 ```tsx

package/bin/sellmate-ds.mjs

@@ -12,23 +12,28 @@
  *  - 안전하게 고칠 수 없는 파일은 손대지 않고 붙여넣을 스니펫을 출력한다.
  *  - 무엇을 바꿨는지 전부 보고한다.
  */
-import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
-import { join, relative, dirname, sep } from "node:path";
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, dirname, sep } from 'node:path';
 
-const PKG = "sellmate-design-system-react";
+const PKG = 'sellmate-design-system-react';
 const LLMS_PATH = `node_modules/${PKG}/dist/llms.txt`;
 
 const args = process.argv.slice(2);
-const command = args.find((a) => !a.startsWith("-")) ?? "init";
-const dryRun = args.includes("--dry-run") || args.includes("-n");
+const command = args.find(a => !a.startsWith('-')) ?? 'init';
+const dryRun = args.includes('--dry-run') || args.includes('-n');
 
 const cwd = process.cwd();
 
 /* ─────────────────────────── 출력 ─────────────────────────── */
 
 const c = {
-  reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
-  green: "\x1b[32m", yellow: "\x1b[33m", cyan: "\x1b[36m", red: "\x1b[31m",
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
 };
 const paint = (color, s) => (process.stdout.isTTY ? `${c[color]}${s}${c.reset}` : s);
 
@@ -38,7 +43,7 @@ const add = (status, file, detail, snippet) => results.push({ status, file, deta
 
 /* ─────────────────────────── 유틸 ─────────────────────────── */
 
-const read = (p) => readFileSync(p, "utf8");
+const read = p => readFileSync(p, 'utf8');
 
 function write(path, content) {
   if (dryRun) return;
@@ -47,14 +52,14 @@ function write(path, content) {
 
 /** node_modules 가 있는 프로젝트 루트인지 확인 */
 function assertProjectRoot() {
-  if (!existsSync(join(cwd, "package.json"))) {
-    console.error(paint("red", "package.json 이 없습니다. 프로젝트 루트에서 실행하세요."));
+  if (!existsSync(join(cwd, 'package.json'))) {
+    console.error(paint('red', 'package.json 이 없습니다. 프로젝트 루트에서 실행하세요.'));
     process.exit(1);
   }
 }
 
 /** 후보 경로 중 처음 존재하는 것 */
-const firstExisting = (candidates) => candidates.find((p) => existsSync(join(cwd, p)));
+const firstExisting = candidates => candidates.find(p => existsSync(join(cwd, p)));
 
 /* ────────────────── 1. 에이전트 지침 파일 ────────────────── */
 
@@ -73,24 +78,24 @@ UI 작업 전 \`${LLMS_PATH}\` 를 **반드시 먼저 읽는다.**
 `;
 
 function stepAgentInstructions() {
-  const existing = ["CLAUDE.md", "AGENTS.md"].filter((f) => existsSync(join(cwd, f)));
-  const targets = existing.length ? existing : ["CLAUDE.md"];
+  const existing = ['CLAUDE.md', 'AGENTS.md'].filter(f => existsSync(join(cwd, f)));
+  const targets = existing.length ? existing : ['CLAUDE.md'];
 
   for (const file of targets) {
     const path = join(cwd, file);
-    const current = existsSync(path) ? read(path) : "";
+    const current = existsSync(path) ? read(path) : '';
 
     if (current.includes(LLMS_PATH)) {
-      add("skipped", file, "이미 llms.txt 참조가 있습니다");
+      add('skipped', file, '이미 llms.txt 참조가 있습니다');
       continue;
     }
 
     const next = current
-      ? `${current.replace(/\s*$/, "")}\n${AGENT_SECTION}`
+      ? `${current.replace(/\s*$/, '')}\n${AGENT_SECTION}`
       : `# 프로젝트 지침\n${AGENT_SECTION}`;
 
     write(path, next);
-    add("added", file, existsSync(path) ? "디자인 시스템 지침 섹션 추가" : "생성 후 지침 추가");
+    add('added', file, existsSync(path) ? '디자인 시스템 지침 섹션 추가' : '생성 후 지침 추가');
   }
 }
 
@@ -105,8 +110,8 @@ function matchingBracket(src, openIndex) {
   let depth = 0;
   for (let i = openIndex; i < src.length; i++) {
     const ch = src[i];
-    if (ch === "[") depth++;
-    else if (ch === "]") {
+    if (ch === '[') depth++;
+    else if (ch === ']') {
       depth--;
       if (depth === 0) return i;
     }
@@ -116,11 +121,19 @@ function matchingBracket(src, openIndex) {
 
 function stepEslint() {
   const file = firstExisting([
-    "eslint.config.mjs", "eslint.config.js", "eslint.config.ts", "eslint.config.cjs",
+    'eslint.config.mjs',
+    'eslint.config.js',
+    'eslint.config.ts',
+    'eslint.config.cjs',
   ]);
 
   if (!file) {
-    add("manual", "eslint.config.mjs", "설정 파일이 없습니다 — 아래 내용으로 만드세요", ESLINT_SNIPPET);
+    add(
+      'manual',
+      'eslint.config.mjs',
+      '설정 파일이 없습니다 — 아래 내용으로 만드세요',
+      ESLINT_SNIPPET,
+    );
     return;
   }
 
@@ -128,7 +141,7 @@ function stepEslint() {
   const src = read(path);
 
   if (src.includes(`${PKG}/eslint`)) {
-    add("skipped", file, "이미 ESLint 프리셋이 연결되어 있습니다");
+    add('skipped', file, '이미 ESLint 프리셋이 연결되어 있습니다');
     return;
   }
 
@@ -136,14 +149,14 @@ function stepEslint() {
   // 배열 경계를 확신할 수 없으므로 손대지 않고 스니펫을 안내한다.
   const exportMatch = src.match(/export\s+default\s*\[/);
   if (!exportMatch) {
-    add("manual", file, "자동 삽입이 어려운 형태입니다 — 아래를 직접 추가하세요", ESLINT_SNIPPET);
+    add('manual', file, '자동 삽입이 어려운 형태입니다 — 아래를 직접 추가하세요', ESLINT_SNIPPET);
     return;
   }
 
-  const openIndex = src.indexOf("[", exportMatch.index);
+  const openIndex = src.indexOf('[', exportMatch.index);
   const closeIndex = matchingBracket(src, openIndex);
   if (closeIndex === -1) {
-    add("manual", file, "배열 끝을 찾지 못했습니다 — 아래를 직접 추가하세요", ESLINT_SNIPPET);
+    add('manual', file, '배열 끝을 찾지 못했습니다 — 아래를 직접 추가하세요', ESLINT_SNIPPET);
     return;
   }
 
@@ -164,11 +177,13 @@ function stepEslint() {
   const before = withImport.slice(0, close);
   const needsComma = /[^[\s,]\s*$/.test(before);
   const next =
-    before.replace(/\s*$/, "") + (needsComma ? "," : "") + `\n${ESLINT_SPREAD}\n` +
+    before.replace(/\s*$/, '') +
+    (needsComma ? ',' : '') +
+    `\n${ESLINT_SPREAD}\n` +
     withImport.slice(close);
 
   write(path, next);
-  add("added", file, "프리셋(configs.recommended) 연결");
+  add('added', file, '프리셋(configs.recommended) 연결');
 }
 
 /* ────────────────── 3. 전역 CSS ────────────────── */
@@ -176,14 +191,19 @@ function stepEslint() {
 /** 앱의 전역 CSS 를 찾는다 */
 function findGlobalCss() {
   const candidates = [
-    "app/globals.css", "src/app/globals.css", "src/styles/globals.css",
-    "styles/globals.css", "src/index.css", "src/main.css", "src/global.css",
+    'app/globals.css',
+    'src/app/globals.css',
+    'src/styles/globals.css',
+    'styles/globals.css',
+    'src/index.css',
+    'src/main.css',
+    'src/global.css',
   ];
   const found = firstExisting(candidates);
   if (found) return found;
 
   // 후보에 없으면 @import "tailwindcss" 가 있는 css 를 얕게 탐색
-  const roots = ["src", "app", "styles"].filter((d) => existsSync(join(cwd, d)));
+  const roots = ['src', 'app', 'styles'].filter(d => existsSync(join(cwd, d)));
   for (const root of roots) {
     const hit = walkCss(join(cwd, root), 3);
     if (hit) return relative(cwd, hit);
@@ -200,7 +220,7 @@ function walkCss(dir, depth) {
     return null;
   }
   for (const name of entries) {
-    if (name === "node_modules" || name.startsWith(".")) continue;
+    if (name === 'node_modules' || name.startsWith('.')) continue;
     const p = join(dir, name);
     let st;
     try {
@@ -211,9 +231,9 @@ function walkCss(dir, depth) {
     if (st.isDirectory()) {
       const hit = walkCss(p, depth - 1);
       if (hit) return hit;
-    } else if (name.endsWith(".css")) {
+    } else if (name.endsWith('.css')) {
       try {
-        if (read(p).includes("tailwindcss")) return p;
+        if (read(p).includes('tailwindcss')) return p;
       } catch {
         /* 읽기 실패는 무시 */
       }
@@ -227,9 +247,9 @@ function stepGlobalCss() {
 
   if (!file) {
     add(
-      "manual",
-      "전역 CSS",
-      "전역 CSS 를 찾지 못했습니다 — 앱의 전역 CSS 에 아래를 추가하세요",
+      'manual',
+      '전역 CSS',
+      '전역 CSS 를 찾지 못했습니다 — 앱의 전역 CSS 에 아래를 추가하세요',
       `@import 'tailwindcss';\n@import '${PKG}/theme.css';\n@source "<상대경로>/node_modules/${PKG}/dist";`,
     );
     return;
@@ -239,14 +259,14 @@ function stepGlobalCss() {
   const src = read(path);
 
   // CSS 파일 기준 상대경로로 @source 를 계산한다 (README 주의사항)
-  const toNodeModules = relative(dirname(path), join(cwd, "node_modules", PKG, "dist"));
-  const sourcePath = toNodeModules.split(sep).join("/");
+  const toNodeModules = relative(dirname(path), join(cwd, 'node_modules', PKG, 'dist'));
+  const sourcePath = toNodeModules.split(sep).join('/');
 
   const hasTheme = src.includes(`${PKG}/theme.css`);
   const hasSource = src.includes(`node_modules/${PKG}/dist`);
 
   if (hasTheme && hasSource) {
-    add("skipped", file, "theme.css · @source 가 이미 설정되어 있습니다");
+    add('skipped', file, 'theme.css · @source 가 이미 설정되어 있습니다');
     return;
   }
 
@@ -258,28 +278,28 @@ function stepGlobalCss() {
   const tw = src.match(/@import\s+["']tailwindcss["'];?/);
   if (!tw) {
     add(
-      "manual",
+      'manual',
       file,
       "@import 'tailwindcss' 를 찾지 못했습니다 — 아래를 직접 추가하세요",
-      lines.join("\n"),
+      lines.join('\n'),
     );
     return;
   }
 
   const insertAt = tw.index + tw[0].length;
-  const next = src.slice(0, insertAt) + "\n" + lines.join("\n") + src.slice(insertAt);
+  const next = src.slice(0, insertAt) + '\n' + lines.join('\n') + src.slice(insertAt);
   write(path, next);
-  add("added", file, lines.length === 2 ? "theme.css import · @source 추가" : "누락분 추가");
+  add('added', file, lines.length === 2 ? 'theme.css import · @source 추가' : '누락분 추가');
 }
 
 /* ─────────────────────────── 실행 ─────────────────────────── */
 
 function printHelp() {
   console.log(`
-${paint("bold", "sellmate-ds")} — ${PKG} 소비 앱 설정
+${paint('bold', 'sellmate-ds')} — ${PKG} 소비 앱 설정
 
-  ${paint("cyan", "npx sellmate-ds init")}             설정을 자동으로 연결합니다
-  ${paint("cyan", "npx sellmate-ds init --dry-run")}   무엇이 바뀔지만 보여줍니다
+  ${paint('cyan', 'npx sellmate-ds init')}             설정을 자동으로 연결합니다
+  ${paint('cyan', 'npx sellmate-ds init --dry-run')}   무엇이 바뀔지만 보여줍니다
 
 연결하는 것
   · CLAUDE.md / AGENTS.md   AI 에이전트가 규칙(llms.txt)을 읽도록 지침 추가
@@ -290,13 +310,13 @@ ${paint("bold", "sellmate-ds")} — ${PKG} 소비 앱 설정
 `);
 }
 
-if (command === "help" || args.includes("--help") || args.includes("-h")) {
+if (command === 'help' || args.includes('--help') || args.includes('-h')) {
   printHelp();
   process.exit(0);
 }
 
-if (command !== "init") {
-  console.error(paint("red", `알 수 없는 명령: ${command}`));
+if (command !== 'init') {
+  console.error(paint('red', `알 수 없는 명령: ${command}`));
   printHelp();
   process.exit(1);
 }
@@ -304,34 +324,46 @@ if (command !== "init") {
 assertProjectRoot();
 
 console.log(
-  `\n${paint("bold", `${PKG} 설정`)}${dryRun ? paint("yellow", "  (dry-run — 파일을 바꾸지 않습니다)") : ""}\n`,
+  `\n${paint('bold', `${PKG} 설정`)}${dryRun ? paint('yellow', '  (dry-run — 파일을 바꾸지 않습니다)') : ''}\n`,
 );
 
 stepAgentInstructions();
 stepEslint();
 stepGlobalCss();
 
-const icon = { added: paint("green", "✓"), skipped: paint("dim", "·"), manual: paint("yellow", "!"), error: paint("red", "✗") };
+const icon = {
+  added: paint('green', '✓'),
+  skipped: paint('dim', '·'),
+  manual: paint('yellow', '!'),
+  error: paint('red', '✗'),
+};
 
 for (const r of results) {
-  console.log(`  ${icon[r.status]} ${paint("bold", r.file)}  ${paint("dim", r.detail)}`);
+  console.log(`  ${icon[r.status]} ${paint('bold', r.file)}  ${paint('dim', r.detail)}`);
   if (r.snippet) {
-    console.log(r.snippet.split("\n").map((l) => `      ${paint("cyan", l)}`).join("\n"));
+    console.log(
+      r.snippet
+        .split('\n')
+        .map(l => `      ${paint('cyan', l)}`)
+        .join('\n'),
+    );
   }
 }
 
-const added = results.filter((r) => r.status === "added").length;
-const manual = results.filter((r) => r.status === "manual").length;
+const added = results.filter(r => r.status === 'added').length;
+const manual = results.filter(r => r.status === 'manual').length;
 
 console.log();
 if (dryRun) {
-  console.log(paint("yellow", `  ${added}개 항목이 변경됩니다. --dry-run 을 빼고 다시 실행하세요.`));
+  console.log(
+    paint('yellow', `  ${added}개 항목이 변경됩니다. --dry-run 을 빼고 다시 실행하세요.`),
+  );
 } else if (added) {
-  console.log(paint("green", `  ${added}개 항목을 설정했습니다.`));
+  console.log(paint('green', `  ${added}개 항목을 설정했습니다.`));
 } else if (!manual) {
-  console.log(paint("dim", "  이미 모두 설정되어 있습니다."));
+  console.log(paint('dim', '  이미 모두 설정되어 있습니다.'));
 }
 if (manual) {
-  console.log(paint("yellow", `  ${manual}개 항목은 위 내용을 직접 추가해야 합니다.`));
+  console.log(paint('yellow', `  ${manual}개 항목은 위 내용을 직접 추가해야 합니다.`));
 }
 console.log();

package/dist/components/SCircleProgress/README.md

@@ -9,9 +9,9 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `value?` | `number` | `0` | 진행률 (0–100) |
-| `type?` | `SCircleProgressType` | `'primary'` | 색상 테마 |
+| `type?` | `SCircleProgressType` | `'primary'` | 진행 상태 - `primary`: 정상 진행 중 - `warning`: 진행 중이지만 설정된 기준에 미달해 주의가 필요하다 (기준은 제품이 정한다) - `error`: 실패·중단 등 더 이상 정상적으로 진행되지 않는다 - `complete`: 완료 - `inverse`: 어두운 배경 위에 놓을 때 - `neutral`: 콘텐츠가 아직 없는 자리를 채울 때 (대기) |
 | `indeterminate?` | `boolean` | `false` | 불확정(스피너) 모드 — value 무시 |
-| `size?` | `number \| string` | `DEFAULT_SIZE` | 링의 지름. 숫자는 px 로 해석한다. 부모 크기에 비례시키려면 컨테이너 쿼리 단위(`'45cqh'`)를 쓴다 — 퍼센트는 부모가 inline-flex 라 기준 폭이 정해지지 않아 해석되지 않는다. |
+| `size?` | `number \| string` | — | 링의 지름. 숫자는 px 로 해석한다. 주지 않으면 `--cmp-progress-circular-size` 를 쓴다. 부모 크기에 비례시키려면 컨테이너 쿼리 단위(`'45cqh'`)를 쓴다 — 퍼센트는 부모가 inline-flex 라 기준 폭이 정해지지 않아 해석되지 않는다. |
 | `label?` | `string` | — | 하단 레이블 |
 | `innerValue?` | `boolean` | `false` | true면 퍼센트를 원 아래가 아닌 원 가운데에 표시 |
 | `className?` | `string` | — |  |
@@ -22,7 +22,8 @@
 ### SCircleProgressType
 
 ```ts
-export type SCircleProgressType = 'primary' | 'inverse' | 'error' | 'complete' | 'neutral';
+export type SCircleProgressType =
+  'primary' | 'inverse' | 'warning' | 'error' | 'complete' | 'neutral';
 ```
 
 ## Dependencies
@@ -32,6 +33,7 @@ export type SCircleProgressType = 'primary' | 'inverse' | 'error' | 'complete' |
  - [SImage](../SImage)
  - [SLoadingContainer](../SLoadingContainer)
  - [SLoadingModal](../SLoadingModal)
+ - [SSelect](../SSelect)
  - [STable](../STable)
 
 ### Graph
@@ -41,6 +43,7 @@ graph TD;
   SImage --> SCircleProgress
   SLoadingContainer --> SCircleProgress
   SLoadingModal --> SCircleProgress
+  SSelect --> SCircleProgress
   STable --> SCircleProgress
   style SCircleProgress fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/components/SCircleProgress/SCircleProgress.d.ts

@@ -1,14 +1,22 @@
 import { type CSSProperties } from 'react';
-export type SCircleProgressType = 'primary' | 'inverse' | 'error' | 'complete' | 'neutral';
+export type SCircleProgressType = 'primary' | 'inverse' | 'warning' | 'error' | 'complete' | 'neutral';
 export interface SCircleProgressProps {
     /** 진행률 (0–100) */
     value?: number;
-    /** 색상 테마 */
+    /**
+     * 진행 상태
+     * - `primary`: 정상 진행 중
+     * - `warning`: 진행 중이지만 설정된 기준에 미달해 주의가 필요하다 (기준은 제품이 정한다)
+     * - `error`: 실패·중단 등 더 이상 정상적으로 진행되지 않는다
+     * - `complete`: 완료
+     * - `inverse`: 어두운 배경 위에 놓을 때
+     * - `neutral`: 콘텐츠가 아직 없는 자리를 채울 때 (대기)
+     */
     type?: SCircleProgressType;
     /** 불확정(스피너) 모드 — value 무시 */
     indeterminate?: boolean;
     /**
-     * 링의 지름. 숫자는 px 로 해석한다.
+     * 링의 지름. 숫자는 px 로 해석한다. 주지 않으면 `--cmp-progress-circular-size` 를 쓴다.
      * 부모 크기에 비례시키려면 컨테이너 쿼리 단위(`'45cqh'`)를 쓴다 — 퍼센트는 부모가
      * inline-flex 라 기준 폭이 정해지지 않아 해석되지 않는다.
      */

package/dist/components/SLinearProgress/README.md

@@ -9,7 +9,7 @@
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `value?` | `number` | `0` | 진행률 (0–100) |
-| `type?` | `SLinearProgressType` | `'primary'` | 색상 타입 |
+| `type?` | `SLinearProgressType` | `'primary'` | 진행 상태 - `primary`: 정상 진행 중 - `warning`: 진행 중이지만 설정된 기준에 미달해 주의가 필요하다 (기준은 제품이 정한다) - `error`: 실패·중단 등 더 이상 정상적으로 진행되지 않는다 - `complete`: 완료 |
 | `size?` | `SLinearProgressSize` | `'sm'` | 바 높이. xs 는 바 안에 퍼센트 텍스트를 넣지 않는다 |
 | `indeterminate?` | `boolean` | `false` | 진행률 없이 무한 애니메이션 |
 | `label?` | `string` | — | 하단 레이블 |
@@ -21,7 +21,7 @@
 ### SLinearProgressType
 
 ```ts
-export type SLinearProgressType = 'primary' | 'error' | 'complete';
+export type SLinearProgressType = 'primary' | 'warning' | 'error' | 'complete';
 ```
 
 ### SLinearProgressSize

package/dist/components/SLinearProgress/SLinearProgress.d.ts

@@ -1,10 +1,16 @@
 import { type CSSProperties } from 'react';
-export type SLinearProgressType = 'primary' | 'error' | 'complete';
+export type SLinearProgressType = 'primary' | 'warning' | 'error' | 'complete';
 export type SLinearProgressSize = 'xs' | 'sm' | 'md';
 export interface SLinearProgressProps {
     /** 진행률 (0–100) */
     value?: number;
-    /** 색상 타입 */
+    /**
+     * 진행 상태
+     * - `primary`: 정상 진행 중
+     * - `warning`: 진행 중이지만 설정된 기준에 미달해 주의가 필요하다 (기준은 제품이 정한다)
+     * - `error`: 실패·중단 등 더 이상 정상적으로 진행되지 않는다
+     * - `complete`: 완료
+     */
     type?: SLinearProgressType;
     /** 바 높이. xs 는 바 안에 퍼센트 텍스트를 넣지 않는다 */
     size?: SLinearProgressSize;

package/dist/components/SSelect/README.md

@@ -28,7 +28,7 @@
 | `virtualBuffer?` | `number` | `DEFAULT_VIRTUAL_BUFFER` | 화면 위·아래로 더 그려둘 여유 행 수 — 빠르게 스크롤할 때 빈 칸이 보이지 않게 한다. 목록은 **언제나 보이는 범위만 렌더한다**(끄는 prop 은 없다). 그래서 여는 비용이 옵션 수와 무관하고, 이 값만이 DOM 에 남는 행 수를 정한다 — 한 화면 분량 + 앞뒤로 이만큼. |
 | `reachEndThreshold?` | `number` | `DEFAULT_REACH_END_THRESHOLD` | 목록 끝에서 이만큼 행이 남았을 때 `onReachEnd` 를 부른다 — 스크롤이 바닥에 닿기 전에 미리 받아 둔다. **한 페이지 크기보다 충분히 작게 잡는다.** 한 페이지가 드롭다운을 채우고도 이 문턱만큼 남기지 못하면, 페이지가 도착하는 족족 다음 페이지를 다시 청하게 된다 — 사용자가 스크롤을 하지 않아도 목록 전체를 받아 오므로 페이징을 한 의미가 사라진다. (한 페이지 50개 · 드롭다운에 20행이 보인다면 남는 것은 30행이므로, 문턱은 그보다 작아야 한다) |
 | `hasMore?` | `boolean` | `false` | 더 받아올 페이지가 남았는가. `false` 면 `onReachEnd` 를 더 부르지 않는다 |
-| `loading?` | `boolean` | `false` | 다음 페이지를 받는 중 — 목록 하단에 로딩 표시를 내고, 그동안 `onReachEnd` 를 다시 부르지 않는다 |
+| `loading?` | `boolean` | `false` | 옵션을 받는 중 — 트리거의 펼침 아이콘 자리에 스피너를, 드롭다운 하단에 로딩 행을 낸다. 첫 조회(옵션이 아직 없을 때)든 다음 페이지든 같은 prop 이고, 그동안 `onReachEnd` 를 다시 부르지 않는다. 로딩 중에도 열 수 있다 — 서버 검색·페이징은 열린 채로 로딩을 오가므로, 열기를 막으면 닫았다 다시 연 사용자에게 클릭이 먹지 않는 고장으로 보인다. 받는 중에는 "표시할 항목이 없습니다."를 내지 않는다. 비활성이면 트리거 스피너를 내지 않는다 — 열 수 없는데 스피너가 돌면 "기다리면 열린다"로 읽힌다. |
 | `serverSearch?` | `boolean` | `false` | 검색을 서버로 넘긴다 — 내부 필터링을 하지 않고 `options` 를 받은 그대로 보여준다. `onSearchChange` 로 온 검색어에 맞는 목록을 소비 앱이 다시 내려줘야 한다. 켜면 검색바가 옵션 수와 무관하게 항상 나온다 — 검색 결과가 줄었다고 검색바가 사라지면 검색어를 지울 수단이 없어지기 때문이다. |
 | `searchDebounce?` | `number` | `DEFAULT_SEARCH_DEBOUNCE` | `serverSearch` 에서 검색어를 서버로 넘기기 전 기다리는 시간(ms) |
 | `label?` | `string` | — |  |
@@ -50,7 +50,7 @@
 
 | Event | Type | Description |
 |-------|------|-------------|
-| `onValueChange` | `(value: any) => void` | 값 변경. 기본은 SSelectOption(들)이 오고, `valueAsPrimitive` 면 원시값이 온다 |
+| `onValueChange` | `(value: TValue) => void` | 값 변경. 기본은 SSelectOption(들)이 오고, `valueAsPrimitive` 면 원시값이 온다 |
 | `onOpenChange` | `(open: boolean) => void` | 열림/닫힘 변경 (sdDropDownShow) |
 | `onReachEnd` | `() => void` | 목록 끝이 가까워지면 부른다 — 다음 페이지를 받아 `options` 뒤에 이어붙이라는 신호다. `hasMore` 가 `false` 이거나 `loading` 중이면 부르지 않고, 같은 목록 길이로 두 번 부르지 않는다. **`options` 는 갈아끼우지 말고 이어붙인다.** depth 타입이면 이미 있는 그룹의 `children` 에 이어야 한다 — 같은 그룹을 새 항목으로 또 밀어 넣으면 목록에 같은 헤더가 두 번 뜬다. 아직 받지 않은 옵션은 라벨을 알 수 없다. 그래서 이 prop 을 쓰는 화면은 `valueAsPrimitive` 를 켜지 않는 편이 안전하다 — 기본값(옵션 객체)이면 선택값이 라벨을 함께 들고 다녀서, 그 옵션이 목록에서 사라져도 트리거에 이름이 그대로 남는다. |
 | `onSearchChange` | `(query: string) => void` | 검색어 변경. `serverSearch` 면 `searchDebounce` 만큼 묶어서 온다 |
@@ -64,6 +64,20 @@
 
 ## Types
 
+### SSelectChangeValue
+
+```ts
+/**
+ * `onValueChange` 로 오는 값의 기본 타입.
+ *
+ * 실제 모양은 `type`(단일/multi)과 `valueAsPrimitive`(옵션 객체/원시값)의 조합으로 정해져 한 타입으로
+ * 적을 수 없다. 화면이 안다면 `<SSelect<string> valueAsPrimitive … />` 처럼 넘겨 좁힌다 — 넘기지 않은
+ * 기존 코드는 이 기본값으로 예전처럼 동작한다.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- 값 타입을 넘기지 않은 화면의 의도된 탈출구
+export type SSelectChangeValue = any;
+```
+
 ### SSelectOption
 
 ```ts
@@ -90,6 +104,7 @@ export type SSelectType = 'default' | 'multi' | 'default_depth' | 'multi_depth';
 
 ### Depends on
 
+- [SCircleProgress](../SCircleProgress)
 - [SField](../SField)
 - [SIcon](../SIcon)
 - [SPortal](../SPortal)
@@ -99,6 +114,7 @@ export type SSelectType = 'default' | 'multi' | 'default_depth' | 'multi_depth';
 
 ```mermaid
 graph TD;
+  SSelect --> SCircleProgress
   SSelect --> SField
   SSelect --> SIcon
   SSelect --> SPortal

package/dist/components/SSelect/SSelect.d.ts

@@ -1,4 +1,4 @@
-import { type CSSProperties } from 'react';
+import { type CSSProperties, type ForwardedRef, type ReactElement } from 'react';
 import { type Rule } from '../../lib/form';
 import { type SFieldAddonAlign, type SFieldLabelPosition } from '../SField';
 import { type SIconName } from '../SIcon';
@@ -13,11 +13,19 @@ export interface SSelectHandle {
     /** 드롭다운 열기 (sdOpen) */
     open: () => void;
 }
-export interface SSelectProps {
+/**
+ * `onValueChange` 로 오는 값의 기본 타입.
+ *
+ * 실제 모양은 `type`(단일/multi)과 `valueAsPrimitive`(옵션 객체/원시값)의 조합으로 정해져 한 타입으로
+ * 적을 수 없다. 화면이 안다면 `<SSelect<string> valueAsPrimitive … />` 처럼 넘겨 좁힌다 — 넘기지 않은
+ * 기존 코드는 이 기본값으로 예전처럼 동작한다.
+ */
+export type SSelectChangeValue = any;
+export interface SSelectProps<TValue extends SSelectChangeValue = SSelectChangeValue> {
     /** 선택 값. multi 타입이면 배열. 기본(valueAsPrimitive=false) 라운드트립을 위해 SSelectOption 객체도 허용 */
     value?: (string | number | SSelectOption) | (string | number | SSelectOption)[] | null;
     /** 값 변경. 기본은 SSelectOption(들)이 오고, `valueAsPrimitive` 면 원시값이 온다 */
-    onValueChange?: (value: any) => void;
+    onValueChange?: (value: TValue) => void;
     /** 열림/닫힘 변경 (sdDropDownShow) */
     onOpenChange?: (open: boolean) => void;
     /**
@@ -93,7 +101,16 @@ export interface SSelectProps {
     reachEndThreshold?: number;
     /** 더 받아올 페이지가 남았는가. `false` 면 `onReachEnd` 를 더 부르지 않는다 */
     hasMore?: boolean;
-    /** 다음 페이지를 받는 중 — 목록 하단에 로딩 표시를 내고, 그동안 `onReachEnd` 를 다시 부르지 않는다 */
+    /**
+     * 옵션을 받는 중 — 트리거의 펼침 아이콘 자리에 스피너를, 드롭다운 하단에 로딩 행을 낸다.
+     * 첫 조회(옵션이 아직 없을 때)든 다음 페이지든 같은 prop 이고, 그동안 `onReachEnd` 를 다시 부르지 않는다.
+     *
+     * 로딩 중에도 열 수 있다 — 서버 검색·페이징은 열린 채로 로딩을 오가므로, 열기를 막으면
+     * 닫았다 다시 연 사용자에게 클릭이 먹지 않는 고장으로 보인다. 받는 중에는 "표시할 항목이
+     * 없습니다."를 내지 않는다.
+     *
+     * 비활성이면 트리거 스피너를 내지 않는다 — 열 수 없는데 스피너가 돌면 "기다리면 열린다"로 읽힌다.
+     */
     loading?: boolean;
     /**
      * 검색을 서버로 넘긴다 — 내부 필터링을 하지 않고 `options` 를 받은 그대로 보여준다.
@@ -144,4 +161,10 @@ export interface SSelectProps {
     className?: string;
     style?: CSSProperties;
 }
-export declare const SSelect: import("react").ForwardRefExoticComponent<SSelectProps & import("react").RefAttributes<SSelectHandle>>;
+/**
+ * 값 타입을 받는 제네릭 컴포넌트로 내보낸다 — `forwardRef` 는 타입 파라미터를 지워 버리므로
+ * 바깥 시그니처만 다시 씌운다(STable·SDraggableList 와 같은 방식).
+ */
+export declare const SSelect: <TValue extends SSelectChangeValue = SSelectChangeValue>(props: SSelectProps<TValue> & {
+    ref?: ForwardedRef<SSelectHandle>;
+}) => ReactElement | null;