@ncds/ui-admin-mcp 1.0.0-alpha.2 → 1.0.0-alpha.20

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

@@ -0,0 +1,50 @@
+/**
+ * Story 5.10: editor 외부 분기 정의
+ *
+ * froala 기반 에디터(`@ncds/editor-html`)의 응답 메타·CDN URL·props·cdnDefaults·methods.
+ * `tools/external/editor.ts` 의 `buildEditorResponse` 가 본 정의를 읽어 응답 조립.
+ * (json 대신 ts — tsconfig `module: Node16` 환경에서 import 단순화. 빌드 시 자동 포함.)
+ */
+export declare const editorDefinition: {
+    readonly name: "editor";
+    readonly className: "NcdsEditor";
+    readonly category: "form";
+    readonly description: "froala 기반 WYSIWYG 에디터. textarea 를 in-place 변환.";
+    readonly cdn: {
+        readonly version: "0.0";
+        readonly css: "https://fe-sdk.cdn-nhncommerce.com/@ncds/editor/0.0/ncds-editor.css";
+        readonly js: "https://fe-sdk.cdn-nhncommerce.com/@ncds/editor/0.0/ncds-editor.js";
+    };
+    readonly props: readonly [{
+        readonly name: "heightMin";
+        readonly type: "number";
+        readonly default: 300;
+        readonly description: "최소 높이 (px)";
+    }, {
+        readonly name: "heightMax";
+        readonly type: "number";
+        readonly default: 600;
+        readonly description: "최대 높이 (px)";
+    }, {
+        readonly name: "heightResize";
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "높이 조정 가능 여부";
+    }, {
+        readonly name: "placeholderText";
+        readonly type: "string";
+        readonly default: "내용을 입력하세요.";
+        readonly description: "플레이스홀더 텍스트";
+    }, {
+        readonly name: "imageUploadCallback";
+        readonly type: "function";
+        readonly description: "이미지 업로드 콜백 함수명 (전역 함수). 외부 분기에서 stripFunctionProps 로 자동 제외 — data-* 직렬화 대상 아님";
+    }];
+    readonly cdnDefaults: {
+        heightMin: number;
+        heightMax: number;
+        heightResize: boolean;
+        placeholderText: string;
+    };
+    readonly methods: readonly ["getHTML()", "setHTML(html)", "getText()", "focus()", "blur()", "enable()", "disable()", "destroy()", "insertImage(src, alt, link)", "insertLink(href, text)", "insertTable(rows, cols)", "on(event, handler)", "off(event)"];
+};

package/bin/definitions/external/editor.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Story 5.10: editor 외부 분기 정의
+ *
+ * froala 기반 에디터(`@ncds/editor-html`)의 응답 메타·CDN URL·props·cdnDefaults·methods.
+ * `tools/external/editor.ts` 의 `buildEditorResponse` 가 본 정의를 읽어 응답 조립.
+ * (json 대신 ts — tsconfig `module: Node16` 환경에서 import 단순화. 빌드 시 자동 포함.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editorDefinition = void 0;
+exports.editorDefinition = {
+    name: 'editor',
+    className: 'NcdsEditor',
+    category: 'form',
+    description: 'froala 기반 WYSIWYG 에디터. textarea 를 in-place 변환.',
+    cdn: {
+        version: '0.0',
+        css: 'https://fe-sdk.cdn-nhncommerce.com/@ncds/editor/0.0/ncds-editor.css',
+        js: 'https://fe-sdk.cdn-nhncommerce.com/@ncds/editor/0.0/ncds-editor.js',
+    },
+    props: [
+        { name: 'heightMin', type: 'number', default: 300, description: '최소 높이 (px)' },
+        { name: 'heightMax', type: 'number', default: 600, description: '최대 높이 (px)' },
+        { name: 'heightResize', type: 'boolean', default: false, description: '높이 조정 가능 여부' },
+        { name: 'placeholderText', type: 'string', default: '내용을 입력하세요.', description: '플레이스홀더 텍스트' },
+        {
+            name: 'imageUploadCallback',
+            type: 'function',
+            description: '이미지 업로드 콜백 함수명 (전역 함수). 외부 분기에서 stripFunctionProps 로 자동 제외 — data-* 직렬화 대상 아님',
+        },
+    ],
+    cdnDefaults: {
+        heightMin: 300,
+        heightMax: 600,
+        heightResize: false,
+        placeholderText: '내용을 입력하세요.',
+    },
+    methods: [
+        'getHTML()',
+        'setHTML(html)',
+        'getText()',
+        'focus()',
+        'blur()',
+        'enable()',
+        'disable()',
+        'destroy()',
+        'insertImage(src, alt, link)',
+        'insertLink(href, text)',
+        'insertTable(rows, cols)',
+        'on(event, handler)',
+        'off(event)',
+    ],
+};

package/bin/definitions/external/step-guide.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Story 6.1: step-guide 외부 분기 정의
+ *
+ * vanilla JS 함수 기반 step-by-step 가이드 투어(`step-guide`)의 응답 메타·CDN URL·props·cdnDefaults·methods.
+ * `tools/external/step-guide.ts`의 `buildStepGuideResponse`가 본 정의를 읽어 응답 조립.
+ * 5-10 editor 패턴 답습 — 단, step-guide는 함수 호출(`window.stepGuide({el, options})`) 형식.
+ * (json 대신 ts — tsconfig `module: Node16` 환경에서 import 단순화. 빌드 시 자동 포함.)
+ */
+export declare const stepGuideDefinition: {
+    readonly name: "step-guide";
+    readonly exportName: "stepGuide";
+    readonly category: "overlays";
+    readonly description: "vanilla JS 함수 기반 step-by-step 가이드 투어. CDN 로드 후 window.stepGuide({el, options}) 호출.";
+    readonly cdn: {
+        readonly version: "2.0";
+        readonly css: "https://fe-sdk.cdn-nhncommerce.com/@ncds/step-guide/2.0/step-guide.min.css";
+        readonly js: "https://fe-sdk.cdn-nhncommerce.com/@ncds/step-guide/2.0/step-guide.min.js";
+    };
+    readonly props: readonly [{
+        readonly name: "steps";
+        readonly type: "Step[]";
+        readonly required: true;
+        readonly description: "단계 배열";
+    }, {
+        readonly name: "useAnimation";
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "애니메이션 사용 여부";
+    }, {
+        readonly name: "buttonLabel";
+        readonly type: "{ prev, next, done, skip }";
+        readonly description: "버튼 라벨 (v2 default: 이전/다음/완료/나중에 하기)";
+    }, {
+        readonly name: "hideSkip";
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "스킵 버튼 숨김 여부";
+    }, {
+        readonly name: "hideStepCount";
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "스텝 카운트 숨김 여부";
+    }, {
+        readonly name: "hideStepPrefix";
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "STEP N prefix 숨김 여부. 단계 1개일 때는 옵션과 무관하게 자동 생략";
+    }, {
+        readonly name: "exitOnOverlayClick";
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "오버레이 클릭 시 종료 여부";
+    }];
+    readonly cdnDefaults: {
+        useAnimation: boolean;
+        hideSkip: boolean;
+        hideStepCount: boolean;
+        exitOnOverlayClick: boolean;
+    };
+    readonly methods: readonly ["goToStep(index)", "previousStep(e)", "nextStep(e)", "onChange(callback)", "onExit(callback)", "exit(e)"];
+};

package/bin/definitions/external/step-guide.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Story 6.1: step-guide 외부 분기 정의
+ *
+ * vanilla JS 함수 기반 step-by-step 가이드 투어(`step-guide`)의 응답 메타·CDN URL·props·cdnDefaults·methods.
+ * `tools/external/step-guide.ts`의 `buildStepGuideResponse`가 본 정의를 읽어 응답 조립.
+ * 5-10 editor 패턴 답습 — 단, step-guide는 함수 호출(`window.stepGuide({el, options})`) 형식.
+ * (json 대신 ts — tsconfig `module: Node16` 환경에서 import 단순화. 빌드 시 자동 포함.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepGuideDefinition = void 0;
+exports.stepGuideDefinition = {
+    name: 'step-guide',
+    exportName: 'stepGuide', // CDN UMD default export = 함수 (소문자, class 아님)
+    category: 'overlays',
+    description: 'vanilla JS 함수 기반 step-by-step 가이드 투어. CDN 로드 후 window.stepGuide({el, options}) 호출.',
+    cdn: {
+        version: '2.0',
+        css: 'https://fe-sdk.cdn-nhncommerce.com/@ncds/step-guide/2.0/step-guide.min.css',
+        js: 'https://fe-sdk.cdn-nhncommerce.com/@ncds/step-guide/2.0/step-guide.min.js',
+    },
+    props: [
+        { name: 'steps', type: 'Step[]', required: true, description: '단계 배열' },
+        { name: 'useAnimation', type: 'boolean', default: true, description: '애니메이션 사용 여부' },
+        {
+            name: 'buttonLabel',
+            type: '{ prev, next, done, skip }',
+            description: '버튼 라벨 (v2 default: 이전/다음/완료/나중에 하기)',
+        },
+        { name: 'hideSkip', type: 'boolean', default: true, description: '스킵 버튼 숨김 여부' },
+        { name: 'hideStepCount', type: 'boolean', default: true, description: '스텝 카운트 숨김 여부' },
+        {
+            name: 'hideStepPrefix',
+            type: 'boolean',
+            default: false,
+            description: 'STEP N prefix 숨김 여부. 단계 1개일 때는 옵션과 무관하게 자동 생략',
+        },
+        {
+            name: 'exitOnOverlayClick',
+            type: 'boolean',
+            default: true,
+            description: '오버레이 클릭 시 종료 여부',
+        },
+    ],
+    cdnDefaults: {
+        useAnimation: true,
+        hideSkip: true,
+        hideStepCount: true,
+        exitOnOverlayClick: true,
+    },
+    methods: ['goToStep(index)', 'previousStep(e)', 'nextStep(e)', 'onChange(callback)', 'onExit(callback)', 'exit(e)'],
+};

package/bin/definitions/instructions.md

@@ -2,12 +2,15 @@
 
 You are an agent that builds UI using NCUA (NCDS UI Admin) design system components from NHN Commerce.
 
-## Absolute Rules
+## Absolute Rules (VIOLATION = CRITICAL FAILURE)
 
-1. You MUST generate NCUA component HTML using the render_to_html tool only. Never write HTML/CSS manually.
-2. Do NOT define or guess CSS variables (--ncua-\*), color values, or BEM classes. They are all included in the CDN CSS.
-3. Do NOT write SVG icons manually. Use search_icon or list_icons to find icons.
-4. If an NCUA component exists for the use case, you MUST use it. Do NOT recreate it manually.
+1. Call ping ONCE at the start of every session before using any other tool. This loads version info and usage rules.
+2. NEVER define or guess NCUA CSS variables (--ncua-\*). NCUA component styles are controlled by CDN CSS only.
+3. NEVER write SVG icons or icon markup manually. ALL icons MUST come from search_icon or list_icons. If you write a single svg tag by hand, you have FAILED.
+4. NEVER use emoji in generated HTML, CSS, or any output. No exceptions.
+5. You MUST generate NCUA component HTML using render_to_html or render_to_html_batch only. Never write component HTML/CSS manually.
+6. If an NCUA component exists for the use case, you MUST use it. Do NOT recreate it manually.
+7. For custom areas, call get_design_tokens FIRST and prefer NCUA tokens for colors, spacing, typography, and shadows to maintain visual consistency. If no suitable token exists, you may use standard CSS values (hex, rgb, px).
 
 ## Required Workflow (follow this order strictly)
 
@@ -27,30 +30,62 @@ You are an agent that builds UI using NCUA (NCDS UI Admin) design system compone
 
 ### Step 1: Component Discovery
 
+- Call **list_components** first to see all available components and their categories. This prevents reinventing components that already exist.
 - Use **search_component** with Korean/English keywords to find the right component
 - Example: "비밀번호" → password-input, "모달" → modal
 - **IMPORTANT**: input is for plain text only. For passwords, always use password-input.
 
 ### Step 2: Props Check
 
-- Use **get_component_props** to see available properties
+- Use **get_component_props** to see available properties BEFORE calling render_to_html.
 - Pass all required props. Choose enum values only from the allowed list.
+- Check `type: "object"` props carefully — they often expect arrays or structured objects. Read the `rawType` field for the actual TypeScript type.
+- For icon props (`leadingIcon`, `trailingIcon`, `icon`), pass `{ type: "icon", icon: "IconName" }` where IconName is a PascalCase name from search_icon.
 
 ### Step 3: HTML Generation
 
-- Use **render_to_html** to get the exact HTML for each component
+- When building a page with multiple components, use **render_to_html_batch** to render them all in one call (max 30). This is much more efficient than calling render_to_html repeatedly.
+- For a single component, use **render_to_html**.
 - Use the returned html as-is. Do NOT modify class names, structure, or attributes.
+- Check the `warnings` field in the response — it reports invalid enum values and missing required props.
+- **If render returns empty or minimal HTML**, the component likely needs data props (e.g. `menus` for HorizontalTab, `items` for BreadCrumb). Check get_component_props and retry with proper data.
+- **Empty result recovery** (max 3 attempts):
+  1. Call get_component_props to identify required/data props
+  2. Retry render_to_html with meaningful prop values
+  3. If still empty after 3 attempts, report the issue to the user
 
-### Step 4: CDN Inclusion
+### Step 4: CDN & JS Initialization
 
 - Get CSS/JS URLs from the **cdn** field in the render_to_html response
-- Include them in <head>/<body> of the final HTML
-- When **js.required is true**, include the CDN JS <script> tag. This is mandatory.
+- Include them in `<head>`/`<body>` of the final HTML
+- When **js.required is true**:
+  1. Include the CDN JS `<script>` tag — this is mandatory
+  2. Check the **js.api** field — it contains the initialization code pattern
+  3. Write a `<script>` block that initializes the component using `js.api.constructor` and `js.api.constructorParams`
+  4. Use `js.api.example` as a reference for the initialization code
+  5. Common pattern: `new window.ncua.ClassName(element, options)` — called after DOMContentLoaded
+
+Example: DatePicker with JS initialization:
+
+```html
+<script>
+  document.addEventListener('DOMContentLoaded', function () {
+    // js.api.constructor: new window.ncua.DatePicker(wrapper, options)
+    // js.api.constructorParams shows required params
+    new window.ncua.DatePicker(document.getElementById('my-datepicker'), {
+      datePickerOptions: [{ element: 'start-date', options: { dateFormat: 'Y-m-d' } }],
+    });
+  });
+</script>
+```
 
 ### Step 5: Composition
 
 - Combine render_to_html results to build the final page
 - Do NOT modify NCUA component styles
+- Apply spacing between components using NCUA design tokens: call **get_design_tokens** with category "spacing" to get available spacing values (e.g. var(--spacing-4), var(--spacing-8))
+- When deciding component size or hierarchy, document your reasoning in an HTML comment (e.g. `<!-- size:sm chosen for compact sidebar layout -->`)
+- If a commerce-rag MCP server is available, query it for page layout patterns and spacing guidelines specific to the project
 
 ## Building Custom Areas (not covered by NCUA)
 
@@ -86,6 +121,21 @@ After composing the final HTML, validate design system compliance:
 
 **Note:** `compliance.score` is independent from `valid`. `valid=true` with `score<1.0` means BEM classes are correct but design system usage can be improved.
 
+## Props Usage Guide
+
+When calling `get_component_props`, the response includes:
+
+- `props`: Full props specification with types, defaults, and allowed values
+- `usageExamples` (if available): Ready-to-use props objects for `render_to_html`
+
+For components with complex object/array props (e.g., dropdown, range-date-picker), always check `usageExamples` first. Copy the example and modify values as needed — this avoids required prop omission errors.
+
+If you call `render_to_html` with missing required props:
+
+- The server auto-fills safe defaults (empty string, empty array, etc.) to prevent crashes
+- `warnings` field lists what was missing and what was auto-filled
+- The rendered HTML may be incomplete — check warnings and retry with proper values
+
 ## Component Selection Guide
 
 - Password → **password-input** (never use input)
@@ -93,4 +143,138 @@ After composing the final HTML, validate design system compliance:
 - File upload → **file-input**
 - Image upload → **image-file-input**
 - Plain text → **input**
+- Dropdown/Select → **select-box** (default choice for all dropdown selections). Use **select** only when native HTML select is explicitly required (e.g., react-hook-form direct binding)
+- Searchable dropdown → **combo-box**
+- Custom trigger dropdown → **dropdown**
+- Date single → **date-picker**
+- Date range → **range-date-picker**
+- Date range with period buttons → **range-date-picker-with-buttons**
 - Each component's description includes usage guidance and alternatives.
+
+### Icon Usage
+
+Icons are rendered as inline SVG by the MCP server — NOT via CDN JS or custom tags. There is NO `<ncua-icon>` tag.
+
+- Use `search_icon` to find icon names (PascalCase, e.g., "RefreshCw01", "SearchLg", "ChevronDown")
+- Pass icon names to component props via `render_to_html`:
+  - Button leadingIcon/trailingIcon: `{ "type": "icon", "icon": "RefreshCw01" }`
+  - FeaturedIcon icon: `"CheckCircle"` (bare string)
+- The server resolves icon names to actual SVG at render time
+- NEVER write `<ncua-icon>`, `<svg>`, or emoji. If you need a standalone icon, use **featured-icon** component
+
+Example — Button with icon:
+
+```json
+{
+  "name": "button",
+  "props": {
+    "label": "Refresh",
+    "leadingIcon": { "type": "icon", "icon": "RefreshCw01" }
+  }
+}
+```
+
+### Children Composition
+
+When a component needs child components (e.g., ButtonGroup with Buttons, Modal with form elements), pass children as component descriptors:
+
+```json
+{
+  "name": "button-group",
+  "props": {
+    "children": [
+      { "component": "button", "props": { "label": "Save", "hierarchy": "primary" } },
+      { "component": "button", "props": { "label": "Cancel" } }
+    ]
+  }
+}
+```
+
+This works recursively — children can contain their own children up to 5 levels deep.
+
+### Compound Components (dot notation)
+
+Some components have sub-components accessed via dot notation. Use `"parent.sub"` format:
+
+- `modal.header` — Modal header with title and close button
+- `modal.content` — Modal body content area
+- `modal.actions` — Modal footer with action buttons
+
+Example — Modal with full structure:
+
+```json
+{
+  "name": "modal",
+  "props": { "isOpen": true, "size": "md" },
+  "children": [
+    { "component": "modal.header", "props": { "title": "Product Detail", "align": "left" } },
+    {
+      "component": "modal.content",
+      "children": [{ "component": "input-base", "props": { "placeholder": "Product name" } }]
+    },
+    {
+      "component": "modal.actions",
+      "props": { "layout": "horizontal", "align": "stretch" },
+      "children": [
+        { "component": "button", "props": { "label": "Cancel", "hierarchy": "secondary-gray", "size": "sm" } },
+        { "component": "button", "props": { "label": "Confirm", "hierarchy": "primary", "size": "sm" } }
+      ]
+    }
+  ]
+}
+```
+
+Always check `usageExamples` in `get_component_props` for compound component patterns. You can freely omit or reorder sub-components to customize the layout.
+
+`get_component_props` on a compound parent (e.g. `modal`, `button-group`) also returns a `subComponents` field:
+
+```json
+{
+  "props": { "isOpen": {...}, "size": {...}, ... },
+  "subComponents": {
+    "Modal.Header": { "props": { "title": {...}, "align": {...}, "featuredIcon": {...} } },
+    "Modal.Content": { "props": { "children": {...}, "className": {...} } },
+    "Modal.Actions": { "props": { "layout": {...}, "align": {...} } }
+  },
+  "usageExamples": { ... }
+}
+```
+
+Use `subComponents[parent.sub].props` to learn valid props (types, enums, defaults) for each sub-component without calling `get_component_props` again. This prevents recursive tool calls when composing compound components.
+
+## Rules Schema
+
+The `rules` array in ping response is a flat list of strings grouped by category. Categories:
+
+| Category           | Purpose                                            |
+| ------------------ | -------------------------------------------------- |
+| workflow           | Required tool call order and HTML generation rules |
+| componentSelection | Which component to use for each use case           |
+| version            | MCP↔project version comparison rules               |
+| cdn                | CDN CSS/JS inclusion rules                         |
+| react              | React-specific package and import rules            |
+| forbidden          | Actions that must never be performed               |
+| customArea         | Rules for building areas not covered by NCUA       |
+| compliance         | validate_html self-correction loop rules           |
+| category           | Component category naming standard                 |
+
+## Error Response Format
+
+All tool errors follow a consistent JSON structure:
+
+```json
+{ "code": "ERROR_CODE", "message": "Human-readable description", "suggestion": "What to do next" }
+```
+
+Error codes:
+
+| Code                    | When                                                                 |
+| ----------------------- | -------------------------------------------------------------------- |
+| COMPONENT_NOT_FOUND     | Component name does not exist                                        |
+| EXPORT_NAME_MISSING     | Component data is corrupted — re-extract needed                      |
+| COMPONENT_NOT_IN_BUNDLE | Component exists in data but not in runtime bundle — re-build needed |
+| RENDER_FAILED           | React rendering threw an error — check props                         |
+| INVALID_TOKEN_CATEGORY  | get_design_tokens called with unknown category                       |
+| ICON_NOT_FOUND          | Icon name does not exist in the icon library                         |
+| INVALID_PARAMS          | Tool called with invalid or missing parameters                       |
+| INTERNAL_ERROR          | Unexpected server error                                              |