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

package/README.md

@@ -50,6 +50,19 @@ npx sellmate-ds init
   `sd-` 접두로 씁니다: `p-sd-16`(16px) · `gap-sd-8`(8px). 자세한 규칙은 `AGENTS.md` §2-2.
 - `@source` — 라이브러리 `dist`를 Tailwind 스캔 대상에 포함시켜 컴포넌트 클래스가 생성되게 합니다. **경로는 여러분의 CSS 파일 위치 기준 상대경로**이며, `node_modules` 전체가 아니라 반드시 이 패키지 `dist`만 지정하세요.
 
+## 글꼴
+
+`theme.css` 가 문서 전역 글꼴을 디자인 토큰 `--font-base`(Pretendard 스택)로 깝니다. 앱은 **글꼴 클래스를 붙이지 않습니다** — `font-sans` 도 같은 스택을 가리키므로 붙일 이유가 없습니다.
+
+**글꼴 파일도 패키지에 들어 있습니다.** Pretendard Variable 다이내믹 서브셋을 `theme.css` 가 함께 싣기 때문에, 앱은 CDN 을 걸거나 폰트를 따로 설치할 필요가 없습니다. 위 **방식 1**(또는 방식 2) 설정만 하면 끝입니다.
+
+- **CDN 을 쓰지 않습니다.** 사내망·오프라인·폐쇄망에서도 그대로 동작하고, 외부로 나가는 요청이 없습니다.
+- **버전이 이 패키지에 고정됩니다.** CDN 최신 추적으로 글꼴이 말없이 바뀌는 일이 없습니다.
+- 다이내믹 서브셋이라 브라우저는 화면에 실제 쓰인 글자 범위의 조각만 내려받습니다. 한글 전체 폰트(약 1MB)를 통째로 받지 않습니다. 패키지 용량은 약 3MB 늘지만 **앱 JS 번들에는 전혀 들어가지 않습니다.**
+- 폰트 자산은 `dist/fonts/` 에 있고 라이선스(SIL OFL 1.1)는 `dist/fonts/LICENSE.txt` 입니다.
+
+앱이 Pretendard 를 이미 자체 호스팅하고 있어도 문제되지 않습니다 — `@font-face` 선언이 겹칠 뿐, 브라우저가 실제로 내려받는 파일은 한 벌입니다.
+
 ## 설정 (방식 2 — 폴백, Tailwind 미사용)
 
 Tailwind를 쓰지 않는 앱은 컴파일된 CSS를 직접 import 합니다.
@@ -178,16 +191,18 @@ export default [
 
 **`error` 는 "지키지 않으면 깨지는 것" 에만 씁니다.** 앱 화면을 Tailwind 로 자유롭게 만드는 것은 정상이고, 디자인 시스템이 그 자유까지 막지 않습니다. 나머지는 권고(`warn`)입니다.
 
-| 규칙                             | 기본      | 검출 대상                                                                                                                                                                                               |
-| -------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `sellmate/no-off-scale-spacing`  | **error** | 스케일 밖 디자인 시스템 간격 (`gap-sd-13`) — Tailwind v4 에서 **조용히 무시되어** 스타일이 사라진다                                                                                                     |
-| `sellmate/no-raw-html-control`   | **error** | 대응 컴포넌트가 있는 생 HTML (`<button>` `<input>` `<select>` `<textarea>` `<table>` `<form>` `<dialog>` `<hr>` `<details>` `<progress>`), `alert()`/`confirm()` — 디자인 시스템을 통째로 우회하는 경우 |
-| `sellmate/prefer-typo-preset`    | warn      | `text-14 font-bold` 같은 낱개 조합 → `typo-*` 프리셋                                                                                                                                                    |
-| `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`(스키마 상한)와 어긋남 — 등급 미지정 · 등급 밖 폭 · 상한 대비 과부족                                                                                                               |
-| `sellmate/no-arbitrary-class`    | **off**   | 토큰이 있는 속성(색·타이포·간격·모서리)의 임의 값 — `text-[14px]`, `bg-[#eee]`. 앱 고유 화면에는 정당한 사용이 많아 기본값은 끕니다                                                                     |
+| 규칙                               | 기본      | 검출 대상                                                                                                                                                                                               |
+| ---------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sellmate/no-off-scale-spacing`    | **error** | 스케일 밖 디자인 시스템 간격 (`gap-sd-13`) — Tailwind v4 에서 **조용히 무시되어** 스타일이 사라진다                                                                                                     |
+| `sellmate/no-raw-html-control`     | **error** | 대응 컴포넌트가 있는 생 HTML (`<button>` `<input>` `<select>` `<textarea>` `<table>` `<form>` `<dialog>` `<hr>` `<details>` `<progress>`), `alert()`/`confirm()` — 디자인 시스템을 통째로 우회하는 경우 |
+| `sellmate/divider-vertical-height` | **error** | 세로 `SDivider` 의 높이를 `className="h-*"` 로 준 경우 — `align-self: stretch` 가 무효가 되어 선이 줄 맨 위에 붙는다. `height` prop 으로 준다(**`--fix` 로 치환**)                                      |
+| `sellmate/prefer-typo-preset`      | warn      | `text-14 font-bold` 같은 낱개 조합 → `typo-*` 프리셋                                                                                                                                                    |
+| `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()` 인자, 템플릿 리터럴, 객체 키 안까지 검사합니다.
 
@@ -243,23 +258,29 @@ export default [
 필드 너비는 **`maxLength`(= 스키마 상한)로 정합니다.** 상한이 등급 안에 들어오면 그 등급으로 고정하고,
 등급 상한(`xl`)을 넘거나 상한이 아예 없으면 행 전체(`width="100%"` 또는 생략)로 둡니다.
 
-| 등급 | 폭    |                          |
-| ---- | ----- | ------------------------ |
-| `xs` | 80px  | 숫자 필드 전용           |
-| `sm` | 120px |                          |
-| `md` | 160px |                          |
-| `lg` | 240px |                          |
-| `xl` | 480px | 정책상 상한              |
+**폭은 등급 이름으로 줍니다** — `width="md"` 처럼 씁니다. 등급은 `--cmp-field-width-*` 토큰으로
+풀리므로 토큰이 바뀌면 화면이 따라갑니다. 같은 값을 px 로 적으면 그 화면만 옛 값에 남습니다.
+
+| 등급 | 쓰는 곳        |
+| ---- | -------------- |
+| `xs` | 숫자 필드 전용 |
+| `sm` |                |
+| `md` |                |
+| `lg` |                |
+| `xl` | 정책상 상한    |
 
 ```tsx
 // 상한이 등급 안에 들어온다 → 그 등급으로 고정
-<SInput name="code" label="코드" maxLength={10} width={160} />
+<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={80} />
+<SNumberInput name="qty" label="수량" max={99} width="xs" />
+
+// 등급 값과 같은 px 를 적으면 등급 이름으로 자동 수정됩니다 (--fix)
+<SInput name="code" label="코드" maxLength={10} width={160} />   // → width="md"
 ```
 
 대상은 `SInput` · `SNumberInput` · `SBarcodeInput` 입니다. `STextarea` 는 여러 줄로 접혀 상한이 폭을
@@ -279,9 +300,9 @@ export default [
 한글은 전각이라 영숫자의 약 두 배를 먹으므로 **두 기준 사이에는 아무것도 보고하지 않습니다** —
 영숫자로 채워도 넘칠 때만 "좁다", 한글로 채워도 남을 때만 "넓다" 로 판정합니다.
 
-| 등급 | `SInput` (sm) | `SInput` (md) | `SNumberInput` (sm) | `SNumberInput` (sm, `useButton`) |
-| ---- | ------------- | ------------- | ------------------- | -------------------------------- |
-| `xs` | —             | —             | 영숫자 8            | 영숫자 2                         |
+| 등급 | `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                        |
@@ -291,15 +312,46 @@ export default [
 두 배가 되고(기본값), 있으면 버튼 두 개와 간격이 폭을 먹습니다. 규칙은 JSX 의 `useButton` 을 읽어
 둘을 구분합니다.
 
-값이 팀 기준과 다르면 옵션으로 덮습니다.
+등급 폭은 `--cmp-field-width-*` 토큰에서 읽으므로 규칙과 컴포넌트가 같은 값을 봅니다.
+글자수 환산 비율이 팀 기준과 다르면 옵션으로 덮습니다(등급 폭도 덮을 수 있지만, 토큰과 어긋나게 됩니다).
 
 ```js
 'sellmate/field-width-grade': ['warn', {
-  grades: { sm: 120, md: 160, lg: 240, xl: 480 },
   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/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/SAccountListBox/AccountListBoxPortal.d.ts

@@ -0,0 +1,31 @@
+import { type RefObject } from 'react';
+import { type SAccountListBoxContent } from './SAccountListBox';
+/**
+ * 계정 행이 놓인 자리. 리스트박스가 어느 방향으로 펼쳐질지를 **이것만** 정한다.
+ * - `panel` — GNB 바닥의 세로 판(접힌 레일 포함). 계정 행이 맨 아래라 위로 편다.
+ * - `top` — 전폭 상단바 오른쪽 끝. 줄이 화면 맨 위라 아래로 편다.
+ */
+type AccountListBoxAnchor = 'panel' | 'top';
+export declare const AccountListBoxAnchorProvider: import("react").Provider<AccountListBoxAnchor>;
+/**
+ * 계정 리스트박스를 앵커에 붙여 띄우는 내부 래퍼.
+ *
+ * 계정 행은 GNB 판(펼침)·레일(접힘)·상단바 세 자리에 서고, 세 자리 모두 "누르면 같은 패널이
+ * 뜬다". 그 여는 방식(위치 · SPortal 설정 · 행을 고르면 닫기)을 한 곳에 모아 두어야 자리마다
+ * 동작이 갈리지 않는다. 공개 API 가 아니므로 index.ts 로 내보내지 않는다 —
+ * 앱은 `SSystemActionButton` 의 `option` 이나 `SGnbSystem` 의 `account.listBox` 로 닿는다.
+ */
+interface AccountListBoxPortalOptions {
+    /** 표시 여부 */
+    open: boolean;
+    /** 표시 상태 변경 */
+    onOpenChange: (open: boolean) => void;
+    /** 붙을 트리거 엘리먼트 */
+    anchorRef: RefObject<HTMLElement | null>;
+    /** 접근성 이름 */
+    ariaLabel?: string;
+    /** 패널에 담기는 내용 */
+    content: SAccountListBoxContent;
+}
+export declare function AccountListBoxPortal({ open, onOpenChange, anchorRef, ariaLabel, content, }: AccountListBoxPortalOptions): import("react").JSX.Element;
+export {};

package/dist/components/SAccountListBox/README.md

@@ -0,0 +1,86 @@
+# SAccountListBox
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SAccountListBox
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `email?` | `string` | — | 로그인한 계정의 이메일 |
+| `name?` | `string` | — | 로그인한 계정의 이름 |
+| `authority?` | `string` | — | 권한. 이름 오른쪽 끝에 붙는다. 없으면 이름만 남는다. (`role` 이 아닌 이유 — 그 이름은 DOM 의 ARIA 속성이라 소비 앱의 a11y lint 가 값을 ARIA 롤로 읽는다) |
+| `accountSetting?` | `SAccountListBoxItem` | — | 계정 설정 행. 주지 않으면 행이 빠진다 |
+| `language?` | `SAccountListBoxLanguage` | — | 언어 변경 행. 주지 않으면 행이 빠진다 |
+| `logout?` | `SAccountListBoxItem` | — | 로그아웃 행. 이 행은 늘 있고, 라벨과 클릭만 받는다 |
+
+## Types
+
+### SAccountListBoxItem
+
+```ts
+/** 리스트박스의 한 행 — 라벨은 기본값이 있고 클릭만 앱이 준다 */
+export interface SAccountListBoxItem {
+  /** 라벨 텍스트. 행마다 기본값이 있다 */
+  label?: string;
+  /** 클릭 */
+  onClick?: () => void;
+}
+```
+
+### SAccountListBoxLanguage
+
+```ts
+/** 언어 변경 행 — 지금 쓰는 언어가 우측에 붙고, 고를 것이 있으면 눌러서 편다 */
+export interface SAccountListBoxLanguage extends SAccountListBoxItem {
+  /**
+   * 지금 선택돼 있는 언어. 우측에 브랜드색으로 붙는다.
+   * `options` 를 함께 주면 그 목록에서 같은 `value` 를 찾아 `label` 로 적는다.
+   */
+  value?: string;
+  /**
+   * 고를 수 있는 언어. 주면 행을 눌렀을 때 **하위 메뉴가 우측 아래로 펼쳐지고**,
+   * 그동안 계정 패널은 닫히지 않는다. 주지 않으면 행을 누르는 것 자체가 액션이라
+   * `onClick` 만 돌고 패널이 닫힌다 — 언어 화면을 따로 두는 앱이 그렇다.
+   */
+  options?: SAccountListBoxLanguageOption[];
+  /** 하위 메뉴에서 언어를 고름. 고르면 하위 메뉴와 계정 패널이 함께 닫힌다 */
+  onChange?: (value: string) => void;
+}
+```
+
+### SAccountListBoxLanguageOption
+
+```ts
+/** 언어 변경 하위 메뉴의 한 칸 */
+export interface SAccountListBoxLanguageOption {
+  /** 값. `SAccountListBoxLanguage.value` 와 맞춰 지금 언어를 가린다 */
+  value: string;
+  /** 화면에 적히는 언어명 */
+  label: string;
+}
+```
+
+## Dependencies
+
+### Used by
+
+ - [SGnbSystem](../SGnbSystem)
+ - [SSystemActionButton](../SSystemActionButton)
+
+### Depends on
+
+- [SIcon](../SIcon)
+- [SPortal](../SPortal)
+
+### Graph
+
+```mermaid
+graph TD;
+  SAccountListBox --> SIcon
+  SAccountListBox --> SPortal
+  SGnbSystem --> SAccountListBox
+  SSystemActionButton --> SAccountListBox
+  style SAccountListBox fill:#f9f,stroke:#333,stroke-width:4px
+```