@ncds/ui-admin-mcp 1.0.0-alpha.12 → 1.0.0-alpha.14

package/bin/definitions/js-api.json

@@ -13,6 +13,7 @@
   },
   "SelectBox": {
     "className": "SelectBox",
+    "cdnPattern": "A",
     "constructor": "new window.ncua.SelectBox(element, config?)",
     "constructorParams": {
       "element": "HTMLElement — target container",
@@ -25,10 +26,15 @@
       "config.disabled": "boolean"
     },
     "methods": ["getValues()", "setValues(options[])", "getSelectedCount()"],
-    "example": "const select = new window.ncua.SelectBox(document.getElementById('my-select'), {\n  options: [{ id: '1', text: 'Option 1' }],\n  onChange: (value) => console.log(value)\n});"
+    "example": "const select = new window.ncua.SelectBox(document.getElementById('my-select'), {\n  options: [{ id: '1', text: 'Option 1' }],\n  onChange: (value) => console.log(value)\n});",
+    "cdnDefaults": {
+      "size": "xs",
+      "placeholder": "선택하세요"
+    }
   },
   "ComboBox": {
     "className": "ComboBox",
+    "cdnPattern": "A",
     "constructor": "new window.ncua.ComboBox(element, config?)",
     "constructorParams": {
       "element": "HTMLElement — target container",
@@ -41,23 +47,45 @@
       "config.multiple": "boolean"
     },
     "methods": ["getValues()", "setValues(options[])", "clearInput()", "getSelectedCount()"],
-    "example": "const combo = new window.ncua.ComboBox(document.getElementById('my-combo'), {\n  options: [{ id: '1', label: 'React' }],\n  onSearch: (q) => console.log(q)\n});"
+    "example": "const combo = new window.ncua.ComboBox(document.getElementById('my-combo'), {\n  options: [{ id: '1', label: 'React' }],\n  onSearch: (q) => console.log(q)\n});",
+    "cdnDefaults": {
+      "size": "xs",
+      "placeholder": "검색하세요"
+    }
   },
   "DatePicker": {
     "className": "DatePicker",
+    "cdnPattern": "A",
     "constructor": "new window.ncua.DatePicker(wrapper, options)",
     "constructorParams": {
       "wrapper": "HTMLElement — container element",
       "options.size": "'xs' | 'sm'",
+      "options.static": "boolean",
       "options.datePickerOptions": "Array<{ element: string, placeholder?: string, options: FlatpickrOptions }>",
       "options.buttons": "Array<{ text: string, period: number, unit: 'days'|'months', isCurrent: boolean }>",
       "options.onValidationError": "(error) => void"
     },
     "methods": ["getDates()", "setDate(dates: string[])", "setMultipleDates(dates: string[])"],
-    "example": "const dp = new window.ncua.DatePicker(document.getElementById('my-dp'), {\n  size: 'xs',\n  datePickerOptions: [{ element: 'date-input', placeholder: 'Select date', options: { dateFormat: 'Y-m-d' } }]\n});"
+    "example": "const dp = new window.ncua.DatePicker(document.getElementById('my-dp'), {\n  size: 'xs',\n  datePickerOptions: [{ element: 'date-input', placeholder: 'Select date', options: { dateFormat: 'Y-m-d' } }]\n});",
+    "cdnDefaults": {
+      "size": "xs",
+      "datePickerOptions": [
+        {
+          "options": {
+            "mode": "single",
+            "static": true,
+            "dateFormat": "Y-m-d",
+            "clickOpens": true,
+            "allowInvalidPreload": true,
+            "locale": "ko"
+          }
+        }
+      ]
+    }
   },
   "Slider": {
     "className": "Slider",
+    "cdnPattern": "A",
     "constructor": "new window.ncua.Slider(element, options)",
     "constructorParams": {
       "element": "HTMLElement — container",
@@ -69,7 +97,13 @@
       "options.disabled": "boolean"
     },
     "methods": ["getValue()", "setValue(value)", "enable()", "disable()", "destroy()"],
-    "example": "const slider = new window.ncua.Slider(document.getElementById('my-slider'), {\n  min: 0, max: 100, value: 50,\n  onChange: (v) => console.log(v)\n});"
+    "example": "const slider = new window.ncua.Slider(document.getElementById('my-slider'), {\n  min: 0, max: 100, value: 50,\n  onChange: (v) => console.log(v)\n});",
+    "cdnDefaults": {
+      "min": 0,
+      "max": 100,
+      "step": 1,
+      "labelPosition": "top-floating"
+    }
   },
   "Tab": {
     "className": "Tab",
@@ -82,6 +116,7 @@
   },
   "Tooltip": {
     "className": "Tooltip",
+    "cdnPattern": "C",
     "constructor": "window.ncua.Tooltip.createShort(title, content?, options?)",
     "constructorParams": {
       "title": "string",
@@ -89,11 +124,25 @@
       "options.position": "'top' | 'bottom' | 'left' | 'right' (default: 'top')"
     },
     "methods": ["getElement()", "showTooltip()", "hideTooltip()", "destroy()"],
-    "example": "const tip = window.ncua.Tooltip.createShort('Help', 'Tooltip content');\ndocument.getElementById('container').appendChild(tip.getElement());"
+    "example": "const tip = window.ncua.Tooltip.createShort('Help', 'Tooltip content');\ndocument.getElementById('container').appendChild(tip.getElement());",
+    "cdnDefaults": {
+      "type": "short",
+      "tooltipType": "black",
+      "iconType": "stroke",
+      "iconStyle": "help-circle",
+      "position": "auto",
+      "size": "sm"
+    }
   },
   "Notification": {
     "className": "Notification",
+    "cdnPattern": "C",
     "constructor": "window.ncua.Notification.success(title, supportingText?, options?)",
+    "cdnDefaults": {
+      "type": "floating",
+      "color": "neutral",
+      "autoClose": 0
+    },
     "constructorParams": {
       "title": "string",
       "supportingText": "string",
@@ -105,16 +154,21 @@
   },
   "ProgressBar": {
     "className": "ProgressBar",
+    "cdnPattern": "C",
     "constructor": "new window.ncua.ProgressBar(options?)",
     "constructorParams": {
       "options.value": "number (0-100)",
       "options.label": "'right' | 'bottom' | 'top-float' | 'bottom-float'"
     },
     "methods": ["getElement()", "updateOptions(newOptions)", "toHTML()"],
-    "example": "const bar = new window.ncua.ProgressBar({ value: 65, label: 'right' });\ndocument.getElementById('container').appendChild(bar.getElement());"
+    "example": "const bar = new window.ncua.ProgressBar({ value: 65, label: 'right' });\ndocument.getElementById('container').appendChild(bar.getElement());",
+    "cdnDefaults": {
+      "label": "right"
+    }
   },
   "Tag": {
     "className": "Tag",
+    "cdnPattern": "C",
     "constructor": "new window.ncua.Tag(options)",
     "constructorParams": {
       "options.text": "string",
@@ -123,10 +177,14 @@
       "options.onButtonClick": "() => void — close handler"
     },
     "methods": ["getElement()", "setText(text)", "setCount(count)", "destroy()"],
-    "example": "const tag = new window.ncua.Tag({ text: 'Label', close: true, onButtonClick: () => tag.destroy() });\ndocument.getElementById('container').appendChild(tag.getElement());"
+    "example": "const tag = new window.ncua.Tag({ text: 'Label', close: true, onButtonClick: () => tag.destroy() });\ndocument.getElementById('container').appendChild(tag.getElement());",
+    "cdnDefaults": {
+      "size": "sm"
+    }
   },
   "FileInput": {
     "className": "FileInput",
+    "cdnPattern": "B",
     "constructor": "new window.ncua.FileInput(options)",
     "constructorParams": {
       "options.container": "HTMLElement | string — auto-append target",
@@ -135,10 +193,14 @@
       "options.disabled": "boolean"
     },
     "methods": ["getElement()", "setDisabled(boolean)", "destroy()"],
-    "example": "const fi = new window.ncua.FileInput({\n  container: 'file-container',\n  onChange: (files) => console.log(files)\n});"
+    "example": "const fi = new window.ncua.FileInput({\n  container: 'file-container',\n  onChange: (files) => console.log(files)\n});",
+    "cdnDefaults": {
+      "buttonLabel": "파일 찾기"
+    }
   },
   "ImageFileInput": {
     "className": "ImageFileInput",
+    "cdnPattern": "B",
     "constructor": "new window.ncua.ImageFileInput(options)",
     "constructorParams": {
       "options.container": "HTMLElement | string — auto-append target",
@@ -147,6 +209,9 @@
       "options.acceptedFileTypes": "string[]",
       "options.maxFileSize": "number"
     },
+    "cdnDefaults": {
+      "buttonLabel": "파일 찾기"
+    },
     "methods": ["getElement()", "getFiles()", "clearFiles()", "setDisabled(boolean)", "destroy()"],
     "example": "const img = new window.ncua.ImageFileInput({\n  container: 'image-container',\n  maxFileCount: 5,\n  onChange: (files) => console.log(files)\n});"
   },

package/bin/server.d.ts

@@ -1 +1,6 @@
+/**
+ * MCP 서버 진입점 — 모든 데이터 소유, tool 등록, transport 연결
+ *
+ * 이 파일만 Action(부수효과)을 포함한다. tool 핸들러는 모두 Calculation.
+ */
 export {};

package/bin/server.js

@@ -1,32 +1,36 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * MCP 서버 진입점 — 모든 데이터 소유, tool 등록, transport 연결
  *
  * 이 파일만 Action(부수효과)을 포함한다. tool 핸들러는 모두 Calculation.
  */
-const path_1 = __importDefault(require("path"));
-const fs_1 = __importDefault(require("fs"));
+// biome-ignore-all lint/complexity/useLiteralKeys: descriptions['key'] 형태가 tool 이름과 일관성 (Story 5.8 scope 외)
+// biome-ignore-all lint/style/noMagicNumbers: 기존 코드의 zod .max(N) 등 (Story 5.8 scope 외)
+// biome-ignore-all lint/complexity/noExcessiveCognitiveComplexity: main() 진입점 (Story 5.8 scope 외, 별도 refactor 스토리)
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_crypto_1 = require("node:crypto");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const zod_1 = require("zod");
-const dataLoader_js_1 = require("./utils/dataLoader.js");
-const logger_js_1 = require("./utils/logger.js");
-const listComponents_js_1 = require("./tools/listComponents.js");
-const searchComponent_js_1 = require("./tools/searchComponent.js");
 const getComponentProps_js_1 = require("./tools/getComponentProps.js");
-const validateHtml_js_1 = require("./tools/validateHtml.js");
-const ping_js_1 = require("./tools/ping.js");
+const getDesignTokens_js_1 = require("./tools/getDesignTokens.js");
+const listComponents_js_1 = require("./tools/listComponents.js");
 const listIcons_js_1 = require("./tools/listIcons.js");
-const searchIcon_js_1 = require("./tools/searchIcon.js");
+const ping_js_1 = require("./tools/ping.js");
 const renderToHtml_js_1 = require("./tools/renderToHtml.js");
+const searchComponent_js_1 = require("./tools/searchComponent.js");
+const searchIcon_js_1 = require("./tools/searchIcon.js");
+const validateHtml_js_1 = require("./tools/validateHtml.js");
+const dataLoader_js_1 = require("./utils/dataLoader.js");
+const domEnvironment_js_1 = require("./utils/domEnvironment.js");
+const logger_js_1 = require("./utils/logger.js");
 const response_js_1 = require("./utils/response.js");
-const getDesignTokens_js_1 = require("./tools/getDesignTokens.js");
 const version_js_1 = require("./version.js");
-const domEnvironment_js_1 = require("./utils/domEnvironment.js");
 // ── definitions/ 로딩 헬퍼 (Action) ─────────────────────────────────────────
 /** tool-definitions.json을 1회 로딩하여 descriptions + capabilities를 분리 반환 */
 const loadToolDefinitions = (definitionsDir) => {
@@ -167,6 +171,7 @@ const main = async () => {
         jsApiMap,
         name,
         props: props,
+        instanceId: (0, node_crypto_1.randomUUID)().slice(0, 6),
     })));
     server.registerTool('render_to_html_batch', {
         description: descriptions['render_to_html_batch'],
@@ -191,6 +196,7 @@ const main = async () => {
             jsApiMap,
             name,
             props: props,
+            instanceId: (0, node_crypto_1.randomUUID)().slice(0, 6),
         }));
         const parsed = results.map((r) => {
             const text = r.content[0].text;

package/bin/tools/external/editor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Story 5.10: editor 외부 분기 모듈
+ *
+ * froala 기반 에디터(`@ncds/editor-html`)는 ui-admin 외부 패키지라
+ * ui-admin 흐름(componentMap / data/{name}.json / cdnAssets) 을 거치지 않고
+ * 본 모듈에서 응답을 직접 조립한다. ui-admin 코드 미수정 → 5-8/5-9 회귀 위험 0.
+ *
+ * 호출 진입점: `renderToHtml` 함수 시작부 (Task 1 결정).
+ */
+import { type McpToolResponse } from '../../utils/response.js';
+/** `normalizeName` 적용된 컴포넌트 이름이 editor alias 인지 검사 */
+export declare const isEditorAlias: (normalizedName: string) => boolean;
+/**
+ * editor 응답 조립 — ui-admin 흐름 우회.
+ * 5-9 helper(`mergeCdnDefaults` / `stripFunctionProps`) import 재사용 (코드 중복 0).
+ */
+export declare const buildEditorResponse: (props: Record<string, unknown>, instanceId: string) => McpToolResponse;

package/bin/tools/external/editor.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Story 5.10: editor 외부 분기 모듈
+ *
+ * froala 기반 에디터(`@ncds/editor-html`)는 ui-admin 외부 패키지라
+ * ui-admin 흐름(componentMap / data/{name}.json / cdnAssets) 을 거치지 않고
+ * 본 모듈에서 응답을 직접 조립한다. ui-admin 코드 미수정 → 5-8/5-9 회귀 위험 0.
+ *
+ * 호출 진입점: `renderToHtml` 함수 시작부 (Task 1 결정).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEditorResponse = exports.isEditorAlias = void 0;
+const editor_js_1 = require("../../definitions/external/editor.js");
+const response_js_1 = require("../../utils/response.js");
+const renderToHtml_js_1 = require("../renderToHtml.js");
+/** editor 컴포넌트로 매칭할 alias 집합 (Task 1 결정 — 보수적 5개) */
+const EDITOR_ALIASES = new Set(['editor', 'ncds-editor', 'ncdseditor', 'ncuaeditor', 'editor-html']);
+/** `normalizeName` 적용된 컴포넌트 이름이 editor alias 인지 검사 */
+const isEditorAlias = (normalizedName) => EDITOR_ALIASES.has(normalizedName);
+exports.isEditorAlias = isEditorAlias;
+/** camelCase → kebab-case (heightMin → height-min) */
+const camelToKebab = (s) => s.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+/** HTML attribute 값 escape (` " ` / ` & ` / ` < ` / ` > `) */
+const escapeHtmlAttr = (s) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/**
+ * options → data-* 속성 직렬화.
+ * - camelCase → kebab-case
+ * - 값 String(v) (boolean → "true"/"false", number → 숫자 문자열)
+ * - null / undefined / function skip (함수는 stripFunctionProps 로 사전 제거되지만 방어적 추가 필터)
+ */
+const serializeDataAttributes = (options) => Object.entries(options)
+    .filter(([, v]) => v !== null && v !== undefined && typeof v !== 'function')
+    .map(([k, v]) => `data-${camelToKebab(k)}="${escapeHtmlAttr(String(v))}"`)
+    .join(' ');
+/**
+ * patternD: textarea + data-* + element-only init script.
+ * 5-8 의 buildPatternA/B/C 와 동일 시그니처 `(id, className, options) => string`.
+ * patternA/B/C 와 차이:
+ *   - 컨테이너: `<div>` → `<textarea>` (froala 가 textarea 를 in-place 변환)
+ *   - options 위치: `new X(wrapper, options)` 두번째 인자 → textarea 의 `data-*` 속성
+ *   - 글로벌: `ncua.X` → `window.NcdsEditor`
+ *   - 호출 위치: ui-admin 의 `PATTERN_BY_COMPONENT` 분기 → 외부 분기 모듈 안 (이 함수)
+ */
+const buildPatternD = (id, className, options) => {
+    const dataAttrs = serializeDataAttributes(options);
+    const tagBody = dataAttrs ? `id="${id}" ${dataAttrs}` : `id="${id}"`;
+    return [
+        `<textarea ${tagBody}></textarea>`,
+        '<script>',
+        "  document.addEventListener('DOMContentLoaded', function () {",
+        `    new window.${className}(document.querySelector('#${id}'));`,
+        '  });',
+        '</script>',
+    ].join('\n');
+};
+/**
+ * editor 응답 조립 — ui-admin 흐름 우회.
+ * 5-9 helper(`mergeCdnDefaults` / `stripFunctionProps`) import 재사용 (코드 중복 0).
+ */
+const buildEditorResponse = (props, instanceId) => {
+    // 5-9: 함수 prop 사전 제거 + cdnDefaults deep merge (사용자 props 우선)
+    const cleanedProps = (0, renderToHtml_js_1.stripFunctionProps)(props);
+    const { merged, defaultsApplied } = (0, renderToHtml_js_1.mergeCdnDefaults)('editor', editor_js_1.editorDefinition.cdnDefaults, cleanedProps);
+    const id = `ed-${instanceId}`;
+    const html = buildPatternD(id, editor_js_1.editorDefinition.className, merged);
+    // cdnDefaults 적용된 키 → defaultsUsed 응답
+    const defaultsUsed = Object.fromEntries(defaultsApplied.map((key) => [key, editor_js_1.editorDefinition.cdnDefaults[key]]));
+    return (0, response_js_1.successResponse)({
+        html,
+        component: editor_js_1.editorDefinition.name,
+        exportName: editor_js_1.editorDefinition.className,
+        importPath: '@ncds/editor-html',
+        appliedProps: merged,
+        ...(Object.keys(defaultsUsed).length > 0 && { defaultsUsed }),
+        js: {
+            required: true,
+            description: '이 컴포넌트는 인터랙션을 위해 CDN JS가 필요합니다',
+            api: {
+                className: editor_js_1.editorDefinition.className,
+                methods: editor_js_1.editorDefinition.methods,
+            },
+        },
+        cdn: editor_js_1.editorDefinition.cdn,
+        dataVersion: { '@ncds/editor': editor_js_1.editorDefinition.cdn.version },
+        react: { notes: 'React not supported in editor (vanilla JS only)' },
+    });
+};
+exports.buildEditorResponse = buildEditorResponse;

package/bin/tools/renderToHtml.d.ts

@@ -1,10 +1,4 @@
-/**
- * render_to_html tool — 컴포넌트 속성을 전달하면 정확한 HTML + React 매핑을 반환 (순수 함수)
- *
- * DOM 환경과 React/ReactDOM은 server.ts에서 초기화하고 파라미터로 전달한다.
- * 이 파일에는 fs, path, require, let이 없다.
- */
-import type { ComponentData, ReactRuntime, JsApiInfo } from '../types.js';
+import type { ComponentData, JsApiInfo, ReactRuntime } from '../types.js';
 import type { CdnMeta, IconMeta } from '../utils/dataLoader.js';
 import { type McpToolResponse } from '../utils/response.js';
 /** render_to_html tool 파라미터 */
@@ -18,6 +12,12 @@ export interface RenderToHtmlParams {
     jsApiMap: Map<string, JsApiInfo>;
     name: string;
     props?: Record<string, unknown>;
+    /**
+     * CDN init 패턴(Story 5.8) 생성 시 `<div id>` 접미사로 사용되는 고유 식별자.
+     * server.ts가 매 호출마다 `crypto.randomUUID().slice(0, 6)` 방식으로 생성해 주입한다.
+     * renderToHtml.ts는 순수 함수 원칙(파일 헤더 주석)을 위해 내부에서 랜덤을 생성하지 않는다.
+     */
+    instanceId: string;
 }
 /** render_to_html tool — props로 React 컴포넌트를 렌더링하여 HTML + React 매핑 반환 */
 export declare const renderToHtml: (params: RenderToHtmlParams) => McpToolResponse;