sellmate-design-system-react 3.0.0 → 3.2.0

package/README.md

@@ -13,8 +13,23 @@ Sellmate 디자인 시스템의 React 컴포넌트 라이브러리 (React + Type
 
 ```bash
 npm install sellmate-design-system-react
+npx sellmate-ds init
 ```
 
+`init` 이 소비 앱 설정을 자동으로 연결합니다.
+
+| 대상 | 하는 일 |
+| --- | --- |
+| `CLAUDE.md` / `AGENTS.md` | AI 에이전트가 규칙(`llms.txt`)을 먼저 읽도록 지침 추가 |
+| `eslint.config.mjs` | 디자인 시스템 ESLint 프리셋 연결 |
+| 전역 CSS | `theme.css` import 와 `@source` 경로(파일 기준 상대경로) 추가 |
+
+- **이미 되어 있는 항목은 건너뜁니다** — 여러 번 실행해도 안전합니다.
+- 무엇이 바뀌는지 먼저 보려면 `npx sellmate-ds init --dry-run`.
+- 자동으로 고치기 어려운 형태(예: `defineConfig(...)` 로 감싼 ESLint 설정)는 **파일을 건드리지 않고** 붙여넣을 스니펫을 출력합니다.
+
+수동으로 설정하려면 아래 절을 따르세요.
+
 ## 설정 (방식 1 — 권장, Tailwind v4)
 
 소비 앱의 전역 CSS에 다음을 추가합니다.
@@ -105,6 +120,97 @@ export function Example() {
 
 `SButton` 은 텍스트를 **`label`(문자열)로만** 받습니다 — `children` 은 받지 않으며, 아이콘은 `icon`/`rightIcon` 을 씁니다. 색상 prop 은 `color` 입니다(`variant` 아님).
 
+## 화면 작성 규칙 (AI 에이전트 포함)
+
+컴포넌트 조합·간격·타이포 등 **화면을 만들 때 지켜야 할 규칙**은 패키지에 함께 배포됩니다.
+
+| 파일 | 용도 |
+| --- | --- |
+| `node_modules/sellmate-design-system-react/AGENTS.md` | 사람이 읽는 사용 규칙서 |
+| `node_modules/sellmate-design-system-react/dist/llms.txt` | **AI 가 항상 읽는 문서** — 규칙 + 토큰 어휘 + 컴포넌트 인덱스 (약 32KB) |
+| `node_modules/sellmate-design-system-react/dist/components/<이름>/README.md` | 컴포넌트별 Props/Events — 쓸 컴포넌트만 골라서 읽습니다 |
+| `node_modules/sellmate-design-system-react/dist/llms-full.txt` | 위 둘을 한 파일에 합친 판본 (약 106KB) — 단일 파일만 물릴 수 있는 도구용 |
+
+Props 를 `llms.txt` 에서 뺀 이유: 전체 컴포넌트 Props 가 분량의 70% 를 차지하는데,
+prop 오류는 TypeScript 가 잡아주지만 **디자인 규칙은 아무도 잡아주지 않습니다.**
+한정된 컨텍스트를 규칙에 쓰고, Props 는 필요한 것만 정확히 읽게 하는 편이 낫습니다.
+
+Claude 등 AI 에이전트를 쓴다면 소비 앱의 `CLAUDE.md` 에 다음 한 줄을 넣어두면 됩니다.
+
+```md
+UI 작업 전 `node_modules/sellmate-design-system-react/dist/llms.txt` 를 먼저 읽을 것.
+```
+
+## ESLint 설정
+
+위 규칙 중 **정적으로 검출 가능한 것**은 린트로 강제할 수 있습니다. 소비 앱의 `eslint.config.mjs` 에 추가하세요.
+
+```js
+// eslint.config.mjs
+import sellmate from 'sellmate-design-system-react/eslint';
+
+export default [
+  // ... 기존 설정
+  ...sellmate.configs.recommended,
+];
+```
+
+| 규칙 | 기본 | 검출 대상 |
+| --- | --- | --- |
+| `sellmate/no-raw-html-control` | error | 대응 컴포넌트가 있는 생 HTML (`<button>` `<input>` `<select>` `<textarea>` `<table>` `<form>` `<dialog>` `<hr>` `<details>` `<progress>`), `alert()`/`confirm()` |
+| `sellmate/no-arbitrary-class` | error | **토큰이 있는 속성**(색·타이포·간격·모서리)의 임의 값 — `text-[14px]`, `bg-[#eee]`, `gap-[13px]`, `rounded-[5px]` |
+| `sellmate/no-off-scale-spacing` | error | 스케일 밖 간격 (`gap-13`, `p-15`) — Tailwind v4 에서 **조용히 무시되는** 값이라 눈으로 찾기 어렵다 |
+| `sellmate/table-numeric-align` | error | 숫자 컬럼(금액·수량 등)에 `align: 'right'` 누락 — **`--fix` 로 자동 교정** |
+| `sellmate/require-locale-number` | error | 숫자 컬럼의 `toLocaleString()` 누락 — 세 자리 콤마는 필수 |
+| `sellmate/component-group-gap` | error | 같은 컴포넌트를 나열할 때의 그룹 간격 — 배열 방향에 따라 값이 다르다(체크박스 가로 24 / 세로 8) |
+| `sellmate/prefer-typo-preset` | warn | `text-14 font-bold` 같은 낱개 조합 → `typo-*` 프리셋 |
+
+`className` 뿐 아니라 `cn()`/`clsx()` 인자, 템플릿 리터럴, 객체 키 안까지 검사합니다.
+
+### 일부러 잡지 않는 것
+
+과검출을 피하려고 다음은 기본 설정에서 **통과**시킵니다.
+
+```tsx
+// 디자인 토큰이 없는 앱 고유 레이아웃 치수 — 정당한 사용
+<div className="w-[280px] max-w-[1200px] grid-cols-[200px_1fr] top-[64px]" />
+
+// 토큰을 var() 로 참조하는 형태
+<div className="h-[var(--sys-size-control-md-height)]" />
+
+// 시각 요소가 없어 대체 컴포넌트가 없다
+<input type="hidden" name="csrf" />
+
+// 로고 SVG·본문 안 시맨틱 목록·DS 밖 컨트롤의 레이블
+<svg viewBox="0 0 24 24" />
+<ul><li>…</li></ul>
+```
+
+핵심은 **"디자인 토큰을 하드코딩하지 마라"** 이지 "임의 값을 절대 쓰지 마라" 가 아닙니다.
+
+### 더 엄격하게 / 더 느슨하게
+
+`configs.strict` 는 전 규칙을 error 로 올리고 `<ul>` `<ol>` `<li>` `<svg>` `<label>` 까지 검사합니다.
+
+```js
+export default [...sellmate.configs.strict];
+```
+
+규칙별 예외도 줄 수 있습니다.
+
+```js
+{
+  rules: {
+    // strict 를 쓰되 로고 SVG 는 허용
+    'sellmate/no-raw-html-control': ['error', { strict: true, allow: ['svg'] }],
+    // 그림자만 임의 값 허용
+    'sellmate/no-arbitrary-class': ['error', { ignorePrefixes: ['shadow'] }],
+  },
+}
+```
+
+허용 값 스케일은 `theme.css` 에서 **빌드 시 자동 추출**되므로 토큰이 바뀌면 규칙도 따라갑니다.
+
 ## 제공 컴포넌트
 
 분류는 `src/index.ts` 의 export 그룹과 동일합니다.

package/bin/sellmate-ds.mjs

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/**
+ * sellmate-ds — 소비 앱 설정 자동화 CLI.
+ *
+ *   npx sellmate-ds init [--dry-run]
+ *
+ * 라이브러리를 설치해도 규칙(AGENTS.md·llms.txt)과 ESLint 프리셋은 소비 앱이
+ * 직접 연결해야 동작한다. 이 CLI 가 그 연결을 대신 해준다.
+ *
+ * 원칙
+ *  - 덮어쓰지 않는다. 추가/삽입만 하고, 이미 있으면 건너뛴다 (몇 번 실행해도 안전).
+ *  - 안전하게 고칠 수 없는 파일은 손대지 않고 붙여넣을 스니펫을 출력한다.
+ *  - 무엇을 바꿨는지 전부 보고한다.
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative, dirname, sep } from "node:path";
+
+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 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",
+};
+const paint = (color, s) => (process.stdout.isTTY ? `${c[color]}${s}${c.reset}` : s);
+
+/** @type {Array<{status: 'added'|'skipped'|'manual'|'error', file: string, detail: string, snippet?: string}>} */
+const results = [];
+const add = (status, file, detail, snippet) => results.push({ status, file, detail, snippet });
+
+/* ─────────────────────────── 유틸 ─────────────────────────── */
+
+const read = (p) => readFileSync(p, "utf8");
+
+function write(path, content) {
+  if (dryRun) return;
+  writeFileSync(path, content);
+}
+
+/** node_modules 가 있는 프로젝트 루트인지 확인 */
+function assertProjectRoot() {
+  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)));
+
+/* ────────────────── 1. 에이전트 지침 파일 ────────────────── */
+
+const AGENT_SECTION = `
+## 디자인 시스템 (${PKG})
+
+UI 작업 전 \`${LLMS_PATH}\` 를 **반드시 먼저 읽는다.**
+컴포넌트 선택 규칙 · 토큰 어휘 · 페이지 표준 골격 · 컴포넌트 인덱스가 들어 있다.
+
+**컴포넌트 Props 는 위 문서에 없다.** 쓸 컴포넌트를 정했으면 그 컴포넌트의 README 를 읽는다 —
+\`node_modules/${PKG}/dist/components/<이름>/README.md\`. prop 을 추측해서 쓰지 않는다.
+
+- 화면 요소를 만들기 전에 대응 컴포넌트가 있는지 먼저 확인한다 (생 \`<button>\`·\`<table>\` 금지).
+- 색·타이포·간격·모서리는 토큰 유틸리티만 쓴다 (\`text-[14px]\`·\`bg-[#eee]\` 금지).
+- 숫자는 \`toLocaleString()\` 으로 세 자리 콤마를 넣는다.
+`;
+
+function stepAgentInstructions() {
+  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) : "";
+
+    if (current.includes(LLMS_PATH)) {
+      add("skipped", file, "이미 llms.txt 참조가 있습니다");
+      continue;
+    }
+
+    const next = current
+      ? `${current.replace(/\s*$/, "")}\n${AGENT_SECTION}`
+      : `# 프로젝트 지침\n${AGENT_SECTION}`;
+
+    write(path, next);
+    add("added", file, existsSync(path) ? "디자인 시스템 지침 섹션 추가" : "생성 후 지침 추가");
+  }
+}
+
+/* ────────────────── 2. ESLint 설정 ────────────────── */
+
+const ESLINT_IMPORT = `import sellmate from '${PKG}/eslint';`;
+const ESLINT_SPREAD = `  ...sellmate.configs.recommended,`;
+const ESLINT_SNIPPET = `${ESLINT_IMPORT}\n\nexport default [\n  // ... 기존 설정\n${ESLINT_SPREAD}\n];`;
+
+/** 배열 리터럴의 닫는 대괄호 위치를 균형 계산으로 찾는다 */
+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 === "]") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function stepEslint() {
+  const file = firstExisting([
+    "eslint.config.mjs", "eslint.config.js", "eslint.config.ts", "eslint.config.cjs",
+  ]);
+
+  if (!file) {
+    add("manual", "eslint.config.mjs", "설정 파일이 없습니다 — 아래 내용으로 만드세요", ESLINT_SNIPPET);
+    return;
+  }
+
+  const path = join(cwd, file);
+  const src = read(path);
+
+  if (src.includes(`${PKG}/eslint`)) {
+    add("skipped", file, "이미 ESLint 프리셋이 연결되어 있습니다");
+    return;
+  }
+
+  // `export default [` 형태만 자동 삽입한다. 그 외(defineConfig(...), tseslint.config(...) 등)는
+  // 배열 경계를 확신할 수 없으므로 손대지 않고 스니펫을 안내한다.
+  const exportMatch = src.match(/export\s+default\s*\[/);
+  if (!exportMatch) {
+    add("manual", file, "자동 삽입이 어려운 형태입니다 — 아래를 직접 추가하세요", ESLINT_SNIPPET);
+    return;
+  }
+
+  const openIndex = src.indexOf("[", exportMatch.index);
+  const closeIndex = matchingBracket(src, openIndex);
+  if (closeIndex === -1) {
+    add("manual", file, "배열 끝을 찾지 못했습니다 — 아래를 직접 추가하세요", ESLINT_SNIPPET);
+    return;
+  }
+
+  // import 는 마지막 최상위 import 뒤에 붙인다
+  const importMatches = [...src.matchAll(/^import .*?;?\s*$/gm)];
+  const lastImport = importMatches.at(-1);
+  const withImport = lastImport
+    ? src.slice(0, lastImport.index + lastImport[0].length) +
+      `\n${ESLINT_IMPORT}` +
+      src.slice(lastImport.index + lastImport[0].length)
+    : `${ESLINT_IMPORT}\n${src}`;
+
+  // import 삽입으로 밀린 만큼 닫는 괄호 위치를 보정
+  const shift = withImport.length - src.length;
+  const close = closeIndex + shift;
+
+  // 배열 마지막 항목 뒤에 삽입한다 (DS 프리셋이 뒤에 와야 앞선 설정을 덮는다)
+  const before = withImport.slice(0, close);
+  const needsComma = /[^[\s,]\s*$/.test(before);
+  const next =
+    before.replace(/\s*$/, "") + (needsComma ? "," : "") + `\n${ESLINT_SPREAD}\n` +
+    withImport.slice(close);
+
+  write(path, next);
+  add("added", file, "프리셋(configs.recommended) 연결");
+}
+
+/* ────────────────── 3. 전역 CSS ────────────────── */
+
+/** 앱의 전역 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",
+  ];
+  const found = firstExisting(candidates);
+  if (found) return found;
+
+  // 후보에 없으면 @import "tailwindcss" 가 있는 css 를 얕게 탐색
+  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);
+  }
+  return null;
+}
+
+function walkCss(dir, depth) {
+  if (depth < 0) return null;
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  for (const name of entries) {
+    if (name === "node_modules" || name.startsWith(".")) continue;
+    const p = join(dir, name);
+    let st;
+    try {
+      st = statSync(p);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      const hit = walkCss(p, depth - 1);
+      if (hit) return hit;
+    } else if (name.endsWith(".css")) {
+      try {
+        if (read(p).includes("tailwindcss")) return p;
+      } catch {
+        /* 읽기 실패는 무시 */
+      }
+    }
+  }
+  return null;
+}
+
+function stepGlobalCss() {
+  const file = findGlobalCss();
+
+  if (!file) {
+    add(
+      "manual",
+      "전역 CSS",
+      "전역 CSS 를 찾지 못했습니다 — 앱의 전역 CSS 에 아래를 추가하세요",
+      `@import 'tailwindcss';\n@import '${PKG}/theme.css';\n@source "<상대경로>/node_modules/${PKG}/dist";`,
+    );
+    return;
+  }
+
+  const path = join(cwd, file);
+  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 hasTheme = src.includes(`${PKG}/theme.css`);
+  const hasSource = src.includes(`node_modules/${PKG}/dist`);
+
+  if (hasTheme && hasSource) {
+    add("skipped", file, "theme.css · @source 가 이미 설정되어 있습니다");
+    return;
+  }
+
+  const lines = [];
+  if (!hasTheme) lines.push(`@import '${PKG}/theme.css';`);
+  if (!hasSource) lines.push(`@source "${sourcePath}";`);
+
+  // @import 'tailwindcss' 바로 뒤에 넣는다 (theme.css 는 tailwindcss 를 import 하지 않는다)
+  const tw = src.match(/@import\s+["']tailwindcss["'];?/);
+  if (!tw) {
+    add(
+      "manual",
+      file,
+      "@import 'tailwindcss' 를 찾지 못했습니다 — 아래를 직접 추가하세요",
+      lines.join("\n"),
+    );
+    return;
+  }
+
+  const insertAt = tw.index + tw[0].length;
+  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 추가" : "누락분 추가");
+}
+
+/* ─────────────────────────── 실행 ─────────────────────────── */
+
+function printHelp() {
+  console.log(`
+${paint("bold", "sellmate-ds")} — ${PKG} 소비 앱 설정
+
+  ${paint("cyan", "npx sellmate-ds init")}             설정을 자동으로 연결합니다
+  ${paint("cyan", "npx sellmate-ds init --dry-run")}   무엇이 바뀔지만 보여줍니다
+
+연결하는 것
+  · CLAUDE.md / AGENTS.md   AI 에이전트가 규칙(llms.txt)을 읽도록 지침 추가
+  · eslint.config.mjs       디자인 시스템 ESLint 프리셋 연결
+  · 전역 CSS                theme.css import 와 @source 경로 추가
+
+이미 되어 있는 항목은 건너뛰므로 여러 번 실행해도 안전합니다.
+`);
+}
+
+if (command === "help" || args.includes("--help") || args.includes("-h")) {
+  printHelp();
+  process.exit(0);
+}
+
+if (command !== "init") {
+  console.error(paint("red", `알 수 없는 명령: ${command}`));
+  printHelp();
+  process.exit(1);
+}
+
+assertProjectRoot();
+
+console.log(
+  `\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", "✗") };
+
+for (const r of results) {
+  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"));
+  }
+}
+
+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 을 빼고 다시 실행하세요.`));
+} else if (added) {
+  console.log(paint("green", `  ${added}개 항목을 설정했습니다.`));
+} else if (!manual) {
+  console.log(paint("dim", "  이미 모두 설정되어 있습니다."));
+}
+if (manual) {
+  console.log(paint("yellow", `  ${manual}개 항목은 위 내용을 직접 추가해야 합니다.`));
+}
+console.log();

package/dist/components/SActionModal/README.md

@@ -0,0 +1,41 @@
+# SActionModal
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SActionModal
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | — |  |
+| `persistent?` | `boolean` | — | true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent) |
+| `modalTitle?` | `string` | `''` |  |
+| `button?` | `SActionModalButton` | — | 하단 액션 버튼 (주 액션 1개). 의도적으로 단수다 — 보조 버튼(취소·삭제 등)은 `footerLeft` 슬롯에 직접 배치한다. |
+| `footerLeft?` | `ReactNode` | — | footer 좌측 영역 (sd-action-modal 의 bottom-sub-content 슬롯). 보조 버튼이나 안내 문구를 넣는다. 버튼을 하나 더 쓰고 싶을 때 여기에 SButton 을 넣는다. |
+| `width?` | `number \| string` | — |  |
+| `height?` | `number \| string` | — |  |
+| `children?` | `ReactNode` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onOpenChange` | `(open: boolean) => void` |  |
+| `onClose` | `() => void` | 닫기(X) 버튼 클릭 (sdClose) |
+
+## Dependencies
+
+### Depends on
+
+- [SButton](../SButton)
+- [SModalContainer](../SModalContainer)
+
+### Graph
+
+```mermaid
+graph TD;
+  SActionModal --> SButton
+  SActionModal --> SModalContainer
+  style SActionModal fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SBadge/README.md

@@ -0,0 +1,25 @@
+# SBadge
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SBadge
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color?` | `SBadgeColor` | `'blue'` | 뱃지 색상 |
+
+## Dependencies
+
+### Used by
+
+ - [SList](../SList)
+
+### Graph
+
+```mermaid
+graph TD;
+  SList --> SBadge
+  style SBadge fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SBarcodeInput/README.md

@@ -0,0 +1,64 @@
+# SBarcodeInput
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SBarcodeInput
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| number \| null` | — |  |
+| `size?` | `SBarcodeInputSize` | `'sm'` |  |
+| `clearable?` | `boolean` | `false` |  |
+| `autoFocus?` | `boolean` | — |  |
+| `name?` | `string` | — |  |
+| `placeholder?` | `string` | `'입력해 주세요.'` |  |
+| `disabled?` | `boolean` | `false` |  |
+| `readOnly?` | `boolean` | `false` |  |
+| `rules?` | `Rule[]` | — |  |
+| `status?` | `SFieldStatus` | — |  |
+| `focused?` | `boolean` | — |  |
+| `hovered?` | `boolean` | — |  |
+| `prefix?` | `ReactNode` | — | 입력 앞 슬롯 |
+| `suffix?` | `ReactNode` | — | 입력 뒤 슬롯 |
+| `inputClass?` | `string` | — |  |
+| `inputStyle?` | `CSSProperties` | — |  |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — |  |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — |  |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | — |  |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `width?` | `number \| string` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string) => void` | 값 변경 (sdUpdate) |
+| `onFocus` | `() => void` |  |
+| `onBlur` | `() => void` |  |
+
+## Dependencies
+
+### Depends on
+
+- [SField](../SField)
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+```mermaid
+graph TD;
+  SBarcodeInput --> SField
+  SBarcodeInput --> SGhostButton
+  style SBarcodeInput fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SButton/README.md

@@ -0,0 +1,49 @@
+# SButton
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SButton
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color?` | `SButtonColor` | `'primary'` | 색상 — sd-button preset의 색 계열 |
+| `outline?` | `boolean` | `false` | 아웃라인(테두리) 스타일. primary·neutral·danger 만 지원 (secondary 는 무시) |
+| `size?` | `SButtonSize` | `'sm'` | 크기 |
+| `icon?` | `SIconName` | — | 레이블 왼쪽 아이콘 |
+| `rightIcon?` | `SIconName` | — | 레이블 오른쪽 아이콘 |
+| `label?` | `string` | — | 버튼 텍스트 (문자열만 — 아이콘은 icon/rightIcon 사용) |
+
+## Dependencies
+
+### Used by
+
+ - [SActionModal](../SActionModal)
+ - [SConfirmModal](../SConfirmModal)
+ - [SDropdownButton](../SDropdownButton)
+ - [SKeyValueTable](../SKeyValueTable)
+ - [SLoadingModal](../SLoadingModal)
+ - [SPopover](../SPopover)
+ - [SPopup](../SPopup)
+ - [SToast](../SToast)
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+```mermaid
+graph TD;
+  SButton --> SIcon
+  SActionModal --> SButton
+  SConfirmModal --> SButton
+  SDropdownButton --> SButton
+  SKeyValueTable --> SButton
+  SLoadingModal --> SButton
+  SPopover --> SButton
+  SPopup --> SButton
+  SToast --> SButton
+  style SButton fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SCalendar/README.md

@@ -0,0 +1,42 @@
+# SCalendar
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SCalendar
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| null` | — | 선택 날짜 (YYYY-MM-DD) |
+| `selectable?` | `[string, string]` | — | 선택 가능 범위 [시작, 종료] (빈 문자열이면 제한 없음) |
+| `events?` | `SCalendarEventGroup[]` | — | 이벤트 그룹 (날짜별 점) |
+| `elevated?` | `boolean` | `false` | 카드 그림자 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(date: string) => void` | 선택 변경 (sdUpdate) |
+| `onViewChange` | `(v: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
+
+## Dependencies
+
+### Used by
+
+ - [SDatePicker](../SDatePicker)
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+```mermaid
+graph TD;
+  SCalendar --> SGhostButton
+  SDatePicker --> SCalendar
+  style SCalendar fill:#f9f,stroke:#333,stroke-width:4px
+```