@ncds/ui-admin-mcp 1.0.0-alpha.22 → 1.0.0-alpha.24

package/bin/definitions/instructions.md

@@ -47,6 +47,7 @@ You are an agent that builds UI using NCUA (NCDS UI Admin) design system compone
 
 ### Step 3: HTML Generation
 
+- **Canonical output verification**: For components with `coverageScore ≥ 0.7` (from list_composition_overrides in Step 1), call **render_to_html** with the canonical example props (including children) BEFORE composing the final page. Inspect the returned HTML to learn the actual DOM structure, class names, and attribute patterns. Use this real output as ground truth — do NOT assume or guess the component's HTML structure from memory or training data. This step prevents hallucinated class names, invented BEM elements, and wrong nesting order.
 - 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.

package/bin/definitions/js-api.json

@@ -428,5 +428,30 @@
     },
     "methods": ["toggle()", "open()", "close()", "closeAndRestoreFocus()", "destroy()"],
     "example": "const dropdown = new window.ncua.Dropdown(document.getElementById('my-host'), {\n  trigger: { type: 'button', text: '메뉴' },\n  groups: [{\n    items: [\n      { id: 'edit', text: '수정', onClick: () => console.log('edit') },\n      { id: 'delete', text: '삭제', type: 'danger', onClick: () => console.log('delete') },\n    ],\n  }],\n});"
+  },
+  "Draggable": {
+    "className": "Draggable",
+    "constructor": "new window.ncua.Draggable(tbodyElement, options)",
+    "constructorParams": {
+      "tbodyElement": "HTMLElement — 드래그 대상 컨테이너 (tbody)",
+      "options.selectAllEl": "HTMLInputElement (optional) — 전체선택 체크박스 요소. 전달 시 행 체크박스 change 위임·전체선택·indeterminate 상태를 Draggable이 자동 관리",
+      "options.moveButtons": "{ top?, up?, down?, bottom?: HTMLElement } (optional) — 이동 버튼 요소. 전달 시 클릭 핸들러와 disabled 상태를 Draggable이 자동 관리",
+      "options.draggable": "boolean (default: true) — 드래그 핸들 활성화 여부. false면 체크박스·이동버튼 기능은 유지되고 드래그만 비활성화",
+      "options.itemSelector": "string (default: '[data-draggable-id]') — 드래그 행 선택자",
+      "options.handleSelector": "string (default: '.ncua-table__drag-handle') — 드래그 핸들 선택자",
+      "options.onDrop": "(fromId: string, toId: string, edge: 'top' | 'bottom', selectedIds: string[]) => void (optional) — 드롭 완료 콜백. Draggable은 DOM을 이동하지 않으므로 페이지에서 직접 DOM 재배치 후 API 호출 등 비즈니스 로직 처리",
+      "options.onMove": "(direction: 'top' | 'up' | 'down' | 'bottom', selectedIds: string[]) => void (optional) — 이동 버튼 클릭 콜백. onDrop과 달리 Draggable이 DOM 행 이동을 자동 완료한 뒤 호출되므로 페이지에서 DOM 재배치 불필요 — 서버 API 호출 등 비즈니스 로직만 작성",
+      "options.onSelect": "(selectedIds: string[]) => void (optional) — 선택 변경 콜백. 선택 카운트 표시 등 UI 업데이트에 활용"
+    },
+    "methods": [
+      "setDraggable(enabled: boolean) — 드래그 핸들 on/off (체크박스·이동버튼 기능은 유지)",
+      "setMoveButtonsEnabled(enabled: boolean) — 이동 버튼 그룹 활성화/비활성화 (드래그·체크박스 기능은 유지)",
+      "getSelectedIds(): string[] — 현재 선택된 행 ID 목록 반환",
+      "clearSelection() — 선택 초기화",
+      "destroy()",
+      "Draggable.destroyAll()"
+    ],
+    "example": "const tbody = document.getElementById('main-tbody');\nconst draggable = new window.ncua.Draggable(tbody, {\n  selectAllEl: document.getElementById('select-all'),\n  moveButtons: {\n    bottom: document.getElementById('btn-move-bottom'),\n    down:   document.getElementById('btn-move-down'),\n    up:     document.getElementById('btn-move-up'),\n    top:    document.getElementById('btn-move-top'),\n  },\n  onDrop: function(fromId, toId, edge, selectedIds) {\n    // 페이지에서 DOM 행 이동 처리\n    const rows = Array.from(tbody.querySelectorAll('tr[data-draggable-id]'));\n    const toRow = rows.find(function(r) { return r.dataset.draggableId === toId; });\n    const anchor = edge === 'bottom' ? toRow.nextSibling || null : toRow;\n    if (selectedIds.length > 1) {\n      const idSet = new Set(selectedIds);\n      rows.filter(function(r) { return idSet.has(r.dataset.draggableId); })\n          .forEach(function(r) { tbody.insertBefore(r, anchor); });\n    } else {\n      const fromRow = rows.find(function(r) { return r.dataset.draggableId === fromId; });\n      if (fromRow) tbody.insertBefore(fromRow, anchor);\n    }\n  },\n  onMove: function(direction, selectedIds) {\n    // DOM 이동은 Draggable 내부에서 완료됨 — 서버 API 호출 등 비즈니스 로직만 작성\n    console.log('moved', direction, selectedIds);\n  },\n  onSelect: function(selectedIds) {\n    document.getElementById('selection-count').textContent =\n      selectedIds.length > 0 ? selectedIds.length + '개 선택됨' : '선택 없음';\n  },\n});\n\n// 드래그 비활성화 (체크박스·이동버튼은 유지)\ndraggable.setDraggable(false);\n\n// 이동 버튼 비활성화 (드래그·체크박스는 유지)\ndraggable.setMoveButtonsEnabled(false);\n\n// 해제\ndraggable.destroy();",
+    "cdnPattern": "D"
   }
 }

package/bin/definitions/rules.json

@@ -4,6 +4,7 @@
     "You MUST generate component HTML using the render_to_html tool. Never write HTML/CSS manually.",
     "Use the HTML returned by render_to_html as-is. Do NOT modify class names, structure, or attributes.",
     "MANDATORY in Phase 1: call list_composition_overrides before any render_to_html call. Components with coverageScore >= 0.7 have canonical examples — read them and use the matching scenario. Skipping this call is the leading cause of page-prefix BEM mimicry and placeholder-only output.",
+    "Canonical output verification: for components with coverageScore >= 0.7, call render_to_html with the canonical example props (including children) from list_composition_overrides BEFORE composing the final page. Inspect the returned HTML to learn the actual DOM structure, class names, and attributes. Use this real output as ground truth — never assume or guess component HTML from memory or training data.",
     "Use search_component to find the right component by Korean/English keywords before building any UI.",
     "Use list_components to browse available components by category and choose the appropriate one.",
     "When building a page with multiple components, use render_to_html_batch to render them all in one call instead of calling render_to_html repeatedly.",

package/bin/overrides/composition.json

@@ -2,7 +2,7 @@
   "_comment": "Composition Overrides — extract-mcp-data.ts 산출물(data/*.json) 위에 병합되는 추가 메타. 컴포넌트 디렉토리 무수정 원칙을 지키면서 P1-4(allowedChildren/Parents), P1-6(canonicalExample), P0-3c(bemClassesExtra) 를 한곳에서 관리.",
   "data-grid": {
     "_note": "P5/P10: DataGrid 는 compound — DataGrid.Table(필수) + DataGrid.Summary / DataGrid.Pagination / DataGrid.SearchFilter / DataGrid.FilterBar / DataGrid.ActionBar 자식. 검색결과 목록 화면 표준. forbiddenInContext: DataGrid.Table 안에 Table.Pagination 금지 — DataGrid.Pagination 슬롯 사용.",
-    "descriptionExtra": "[중요] 검색결과·관리자 목록 화면 표준 컴포넌트. DataGrid.Table(필수, NCDS Table 자동 감싸기) + Summary(건수 표시) + ActionBar(상단 일괄 액션) + Pagination(하단). DataGrid 안에서 Table 의 Pagination 슬롯은 사용 금지 — DataGrid.Pagination 으로 분리. variant: search-result(검색결과 페이지 표준) / simple(단순 목록) / readonly(편집 불가). Storybook DataGrid SearchResultDemo 의 children 트리와 동일 구조 유지.",
+    "descriptionExtra": "[중요] 검색결과·관리자 목록 화면 표준 컴포넌트. DataGrid.Table(필수, NCDS Table 자동 감싸기) + Summary(건수 표시) + ActionBar(상단 일괄 액션) + Pagination(하단). DataGrid 안에서 Table 의 Pagination 슬롯은 사용 금지 — DataGrid.Pagination 으로 분리. variant: search-result(검색결과 페이지 표준) / simple(단순 목록) / readonly(편집 불가). Storybook DataGrid SearchResultDemo 의 children 트리와 동일 구조 유지. ⚠️ CDN HTML 모드 전용 — DataGrid 안에 selectable Table이 있을 때 2가지를 반드시 수동 추가해야 한다: (1) ncua-table div에 ncua-table--in-data-grid 클래스 추가 — React는 DataGrid.Table이 자동으로 추가하지만 CDN 모드는 수동이다. 누락 시 DataGrid wrapper의 border-left 1px와 selectable의 box-shadow inset 1px이 겹쳐 좌측 2px 이중 테두리가 된다. (2) ncua-data-grid__table-wrapper의 마지막 자식으로 <div class='ncua-data-grid__action-bar ncua-data-grid__action-bar--bottom'></div> 추가 — React DataGrid는 selectable=true일 때 이 빈 div를 자동 생성하여 하단 여백/구분선을 처리한다. 누락 시 테이블 하단 여백이 사라진다. ⚠️ CDN DnD(draggable) 조합 시 추가 규칙: ncua-table div에 ncua-table--draggable 클래스 추가. ncua-table-wrapper에 --ncua-table-header-height: 40px CSS 변수 설정. 이동 버튼이 필요하면 ncua-data-grid__action-bar 안에 ncua-button-group--xs 패턴으로 배치. canonicalExamples.dnd-with-selectable 시나리오 참고.",
     "aliasesExtra": [
       "데이터 그리드",
       "데이터그리드",
@@ -797,6 +797,21 @@
           ]
         }
       },
+      "dnd-with-selectable": {
+        "description": "DataGrid + 체크박스 선택 + 행 드래그앤드롭 + 이동 버튼 조합. CDN HTML 모드 전용 완전 구조. ⚠️ 필수 규칙 — 아래 5가지를 모두 지켜야 올바른 렌더링이 보장된다: (1) ncua-table div에 ncua-table--selectable ncua-table--draggable ncua-table--in-data-grid 3개 클래스 모두 포함 — ncua-table--in-data-grid 누락 시 좌측 2px 이중 테두리 발생. (2) ncua-table-wrapper style에 --ncua-table-header-height:40px CSS 변수 설정 — 드래그 미리보기 오프셋 계산에 사용. (3) 이동 버튼(ButtonGroup)은 ncua-data-grid__action-bar 안에 배치, disabled 상태로 초기화. (4) ncua-data-grid__table-wrapper 마지막 자식으로 빈 ncua-data-grid__action-bar--bottom div 추가 — 누락 시 테이블 하단 여백 소멸. (5) CDN JS: const d = new window.ncua.Draggable(tbody, { onDrop, onSelect, onMove }); d.setMoveButtonsEnabled(true) 로 이동 버튼 연결. onDrop: 페이지가 서버 API 처리. onMove: Draggable이 DOM 이동 완료 후 호출하는 알림 — 페이지에서 DOM 조작 금지.",
+        "_htmlStructure": {
+          "_note": "CDN HTML 모드 전용 구조. React 모드에서는 DataGrid.Table + Table.DragHeaderCell + Table.DragCell + selectable 조합으로 대체.",
+          "outerStructure": "<div class='ncua-data-grid'><div class='ncua-data-grid__table-wrapper'>[action-bar--top][ncua-data-grid__table][action-bar--bottom(빈 div)]</div></div>",
+          "tableDivClasses": "ncua-table ncua-table--horizontal ncua-table--hoverable ncua-table--selectable ncua-table--draggable ncua-table--in-data-grid",
+          "tableWrapperStyle": "--ncua-table-header-height:40px",
+          "actionBarTop": "<div class='ncua-data-grid__action-bar ncua-data-grid__action-bar--top'><div class='ncua-button-group ncua-button-group--xs has-border'><button class='ncua-button-group__item is-only-icon' id='btn-move-bottom' disabled><!-- 맨아래 SVG --></button><button class='ncua-button-group__item is-only-icon' id='btn-move-down' disabled><!-- 아래 SVG --></button><button class='ncua-button-group__item is-only-icon' id='btn-move-up' disabled><!-- 위 SVG --></button><button class='ncua-button-group__item is-only-icon' id='btn-move-top' disabled><!-- 맨위 SVG --></button></div></div>",
+          "actionBarBottom": "<div class='ncua-data-grid__action-bar ncua-data-grid__action-bar--bottom'></div>",
+          "dragHeaderCell": "<th class='ncua-table__header-cell ncua-table__drag-header-cell'><span class='ncua-table__drag-cell-inner'><span class='ncua-table__drag-header-icon'><!-- 6점 grip SVG --></span><span class='ncua-checkbox-input ncua-checkbox-input--sm'><input id='select-all' type='checkbox' aria-label='전체 선택'></span></span></th>",
+          "dragDataCell": "<td class='ncua-table__drag-cell'><span class='ncua-table__drag-cell-inner'><button class='ncua-table__drag-handle' type='button' aria-label='행 순서 변경'><!-- 6점 grip SVG --></button><span class='ncua-checkbox-input ncua-checkbox-input--sm'><input type='checkbox' aria-label='행 선택'></span></span></td>",
+          "trAttr": "data-draggable-id='row-1'",
+          "cdnInit": "const tbody = document.querySelector('tbody'); const d = new window.ncua.Draggable(tbody, { onDrop: (fromId, toId, edge) => { /* 서버 API */ }, onSelect: (ids) => { /* 선택 변경 */ }, onMove: (dir, ids) => { /* 알림만 — DOM 이동은 Draggable 내부 처리 */ } }); d.setMoveButtonsEnabled(true);"
+        }
+      },
       "search-result-readonly": {
         "description": "검색결과 + 선택 없음(체크박스 없음, ActionBar 없음). Summary + Table + Pagination 만. 단순 조회 화면.",
         "props": {
@@ -879,7 +894,7 @@
   },
   "table": {
     "_note_required": "P7: ncua-table__required 는 NCDS Table SCSS([_table.scss:619]) 와 VanillaJS classNames 상수([classNames.ts:26])에는 정의되어 있으나 React Table.tsx 본체가 사용하지 않아 자동 추출되지 않음. Vertical Table 의 필수 라벨에 `<span class='ncua-table__required'>*</span>` 형태로 라벨 텍스트 앞에 prepend 하여 사용. validate_html 화이트리스트 통과를 위해 bemClassesExtra 에 명시 등록.",
-    "descriptionExtra": "[중요] table 컴포넌트는 두 가지 모드 지원: (1) type=horizontal — 데이터 그리드(thead+tbody, 컬럼별 헤더). (2) type=vertical — 폼 레이아웃(tbody only, 좌측 라벨-우측 값 2-cell row). 폼의 라벨-입력 쌍 구성 시 vertical 모드 사용 — 절대 BEM 수동 작성 금지. canonicalExamples 의 'vertical-form-label' / 'vertical-form-label-with-required' 시나리오 참고. ⚠️ <th class='ncua-table__header-cell'> 은 horizontal 컬럼 헤더 전용 — vertical 라벨에는 <th scope='row' class='ncua-table__cell'> 사용 (Table.Cell with isHeader=true). ⚠️ 테이블 스크롤(가로/세로)은 반드시 Table 컴포넌트의 내장 props 로만 처리 — 커스텀 scroll wrapper(예: pbp-table-scroll, page-table__scroll, sgr-table-scroll 등 프로젝트 prefix div) 절대 생성 금지. 올바른 스크롤 설정: horizontalScroll=true(가로 스크롤 활성화 → ncua-table__h-scroll-container 구조 자동 생성), fixedHeader=true(헤더 고정 → ncua-table--fixed-header), maxHeight=340(세로 스크롤 최대 높이 → ncua-table__scroll-container max-height), minWidth=1140(전체 테이블 최소 너비 → --ncua-table-min-width CSS 변수 자동 주입). Table.ColGroup의 widths/minWidths 배열로 각 컬럼 너비 지정. canonicalExamples 의 'horizontal-with-scroll' 시나리오 참고. ⚠️ ncua-table 외곽 wrapper div에 border·overflow:hidden 절대 적용 금지 — (1) border: ncua-table이 자체 border: 1px solid var(--gray-100)를 보유하므로 외부에 border를 추가하면 2px 이중 테두리가 된다. (2) overflow:hidden: 테이블 셀 안의 SelectBox·DatePicker·Tooltip 등 드롭다운이 컨테이너 경계에서 잘린다. 테이블을 감싸는 div가 필요한 경우 아무 CSS 없이 빈 wrapper만 사용할 것.",
+    "descriptionExtra": "[중요] table 컴포넌트는 두 가지 모드 지원: (1) type=horizontal — 데이터 그리드(thead+tbody, 컬럼별 헤더). (2) type=vertical — 폼 레이아웃(tbody only, 좌측 라벨-우측 값 2-cell row). 폼의 라벨-입력 쌍 구성 시 vertical 모드 사용 — 절대 BEM 수동 작성 금지. canonicalExamples 의 'vertical-form-label' / 'vertical-form-label-with-required' 시나리오 참고. ⚠️ <th class='ncua-table__header-cell'> 은 horizontal 컬럼 헤더 전용 — vertical 라벨에는 <th scope='row' class='ncua-table__cell'> 사용 (Table.Cell with isHeader=true). ⚠️ 테이블 스크롤(가로/세로)은 반드시 Table 컴포넌트의 내장 props 로만 처리 — 커스텀 scroll wrapper(예: pbp-table-scroll, page-table__scroll, sgr-table-scroll 등 프로젝트 prefix div) 절대 생성 금지. 올바른 스크롤 설정: horizontalScroll=true(가로 스크롤 활성화 → ncua-table__h-scroll-container 구조 자동 생성), fixedHeader=true(헤더 고정 → ncua-table--fixed-header), maxHeight=340(세로 스크롤 최대 높이 → ncua-table__scroll-container max-height), minWidth=1140(전체 테이블 최소 너비 → --ncua-table-min-width CSS 변수 자동 주입). Table.ColGroup의 widths/minWidths 배열로 각 컬럼 너비 지정. canonicalExamples 의 'horizontal-with-scroll' 시나리오 참고. ⚠️ ncua-table 외곽 wrapper div에 border·overflow:hidden 절대 적용 금지 — (1) border: ncua-table이 자체 border: 1px solid var(--gray-100)를 보유하므로 외부에 border를 추가하면 2px 이중 테두리가 된다. (2) overflow:hidden: 테이블 셀 안의 SelectBox·DatePicker·Tooltip 등 드롭다운이 컨테이너 경계에서 잘린다. 테이블을 감싸는 div가 필요한 경우 아무 CSS 없이 빈 wrapper만 사용할 것. ⚠️ ncua-table--in-data-grid (CDN HTML 모드 전용 수동 추가): selectable=true 테이블이 DataGrid(ncua-data-grid__table-wrapper) 안에 있을 때, React는 DataGrid.Table이 자동으로 ncua-table--in-data-grid 클래스를 추가해 첫 번째 열의 inset shadow(box-shadow: inset 1px 0 0 0 var(--gray-100))를 제거한다. CDN HTML 모드에서는 ncua-table div에 직접 ncua-table--in-data-grid 클래스를 추가해야 한다 — 누락 시 DataGrid wrapper의 border-left 1px와 selectable의 inset box-shadow 1px이 시각적으로 겹쳐 좌측 2px 이중 테두리가 된다.",
     "aliasesExtra": [
       "vertical-table",
       "form-table",
@@ -1176,6 +1191,58 @@
           ]
         }
       },
+      "dnd-row-sorting": {
+        "description": "Horizontal Table — 행 드래그앤드롭 정렬. [React 모드] draggable=true + Table.DragHeaderCell(헤더) + Table.DragCell(각 행) + Table.Row.dragId(문자열 식별자) + Table.Body.onRowDrop(콜백). 반드시 type='horizontal'. DragCell에는 CheckboxInput 등 공동 배치 가능. useState로 rows 배열을 관리하고 onRowDrop에서 배열 재정렬: const [rows, setRows] = useState(initialRows); const handleDrop = (fromId, toId, edge) => { setRows(prev => { const from = prev.findIndex(r => r.id === fromId); const to = prev.findIndex(r => r.id === toId); const next = [...prev]; const [item] = next.splice(from, 1); const insertAt = edge === 'top' ? to : to + 1; next.splice(insertAt > from ? insertAt - 1 : insertAt, 0, item); return next; }); }; [CDN 모드] React DnD props(draggable/dragId/onRowDrop) 대신 window.ncua.Draggable 사용. 각 <tr>에 data-draggable-id 속성 필수. CDN 초기화: const sortable = new window.ncua.Draggable(tbodyEl, { onDrop: function(fromId, toId, edge) { /* 서버 API 호출 — DOM 재정렬은 Draggable이 완료 후 호출 */ }, onSelect: function(selectedIds) { /* 선택 상태 변경 알림 */ }, onMove: function(direction, selectedIds) { /* 이동 버튼 클릭 알림 — DOM 이동은 Draggable 내부 처리 후 호출 */ } }); ⚠️ onDrop: 드래그 종료 시 페이지가 서버 API 등 비즈니스 로직 처리. ⚠️ onMove: 이동 버튼 클릭 시 Draggable이 DOM 행 이동을 완료한 후 호출되는 알림 — 페이지에서 DOM 재정렬 코드를 작성하지 말 것. ⚠️ DataGrid 안에 배치 시 CDN HTML 모드 필수 조건: (1) ncua-table div에 ncua-table--in-data-grid 클래스 추가(누락 시 2px 이중 테두리), (2) ncua-table-wrapper에 --ncua-table-header-height: 40px CSS 변수 설정. 이동 버튼 그룹은 ncua-data-grid__action-bar 안에 ncua-button-group--xs 패턴으로 배치 + Draggable.setMoveButtonsEnabled(true)로 활성화. data-grid.canonicalExamples.dnd-with-selectable 시나리오 참고.",
+        "props": {
+          "type": "horizontal",
+          "draggable": true,
+          "hoverable": true,
+          "children": [
+            {
+              "component": "table.header",
+              "children": [
+                {
+                  "component": "table.row",
+                  "children": [
+                    { "component": "table.drag-header-cell" },
+                    { "component": "table.header-cell", "children": ["상품명"] },
+                    { "component": "table.header-cell", "children": ["카테고리"] },
+                    { "component": "table.header-cell", "children": ["순서"] }
+                  ]
+                }
+              ]
+            },
+            {
+              "component": "table.body",
+              "props": {
+                "onRowDrop": "handleDrop"
+              },
+              "children": [
+                {
+                  "component": "table.row",
+                  "props": { "dragId": "row-1" },
+                  "children": [
+                    { "component": "table.drag-cell" },
+                    { "component": "table.cell", "children": ["프리미엄 노트북"] },
+                    { "component": "table.cell", "children": ["전자기기"] },
+                    { "component": "table.cell", "children": ["1"] }
+                  ]
+                },
+                {
+                  "component": "table.row",
+                  "props": { "dragId": "row-2" },
+                  "children": [
+                    { "component": "table.drag-cell" },
+                    { "component": "table.cell", "children": ["무선 마우스"] },
+                    { "component": "table.cell", "children": ["주변기기"] },
+                    { "component": "table.cell", "children": ["2"] }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      },
       "vertical-form-label": {
         "description": "Vertical Table — 폼 라벨 레이아웃 (필수 마크 없는 버전). 각 row 의 좌측 라벨 셀은 Table.Cell with isHeader=true (출력: <th scope='row' class='ncua-table__cell'>). Table.HeaderCell 사용 금지 — 그 클래스는 Horizontal Table 의 thead 컬럼 헤더 전용. thead 없이 tbody 만 사용하며, 각 row 는 [라벨 cell(isHeader), 값 cell] 의 2-cell 구조. 필수 라벨 표기가 필요하면 'vertical-form-label-with-required', 라벨 옆 안내 tooltip 이 필요하면 'vertical-form-label-with-tooltip' 시나리오 사용.",
         "props": {
@@ -2359,7 +2426,7 @@
   },
   "switch": {
     "_note": "P22: Switch 는 좌/우 두 옵션 토글 컴포넌트 (Apple segment-control 패턴). left/right props 로 두 옵션 정의, value 로 현재 선택. 사이즈: xxs/xs/sm/md. ⚠️ godomall5 페이지에서 'CDN 미제공 active/inactive 스타일' 이라 단언하고 fallback CSS 직접 작성한 hallucination 발생 — NCDS CDN CSS 가 .ncua-switch__option--active / --inactive 등 모든 modifier 완비. 반드시 render_to_html('switch', {left, right, value, size}) 호출해 정확한 BEM 출력 사용. ncua-switch__option--active 를 페이지 SCSS 에서 override 하지 말 것.",
-    "descriptionExtra": "[중요] 두 선택지 토글 컴포넌트 (좌/우 영역 선택). left/right props (각각 { id, label }) + value(선택된 id) + size(xxs/xs/sm/md) + disabled. 출력 BEM: ncua-switch + --{size} modifier + ncua-switch__option + --active/--inactive/--left/--right. ⚠️ 페이지 SCSS 에서 .ncua-switch__option--active 등 override CSS 작성 금지 — CDN CSS 가 완비. 발명 modifier(--toggled / --selected) 사용 금지.",
+    "descriptionExtra": "[중요] 두 선택지 토글 컴포넌트 (좌/우 영역 선택). left/right props (각각 { value, label }) + value(선택된 value) + size(xxs/xs/sm/md) + disabled. ⚠️ Switch HTML 은 반드시 render_to_html('switch', props) 로만 생성 — 수동 HTML 작성 시 ncua-switch__radio 클래스 누락으로 native radio 버튼이 그대로 노출됨. 페이지 SCSS 에서 .ncua-switch__option--active 등 override CSS 작성 금지 — CDN CSS 가 완비. 발명 modifier(--toggled / --selected) 사용 금지.",
     "aliasesExtra": [
       "스위치",
       "토글",
@@ -2380,15 +2447,15 @@
     "bemClassesExtra": [],
     "canonicalExamples": {
       "default": {
-        "description": "P22: 기본 토글 스위치 (좌/우 두 옵션). value 로 현재 선택, size='md' 기본. left/right 의 id 는 value 와 매칭.",
+        "description": "P22: 기본 토글 스위치 (좌/우 두 옵션). value 로 현재 선택, size='md' 기본. left/right 의 value 는 최상위 value 와 매칭.",
         "props": {
           "size": "md",
           "left": {
-            "id": "list",
+            "value": "list",
             "label": "목록"
           },
           "right": {
-            "id": "grid",
+            "value": "grid",
             "label": "그리드"
           },
           "value": "list"
@@ -2399,11 +2466,11 @@
         "props": {
           "size": "sm",
           "left": {
-            "id": "active",
+            "value": "active",
             "label": "활성"
           },
           "right": {
-            "id": "inactive",
+            "value": "inactive",
             "label": "비활성"
           },
           "value": "active"
@@ -2414,11 +2481,11 @@
         "props": {
           "size": "md",
           "left": {
-            "id": "yes",
+            "value": "yes",
             "label": "사용함"
           },
           "right": {
-            "id": "no",
+            "value": "no",
             "label": "사용 안 함"
           },
           "value": "yes",

package/bin/tools/renderToHtml.js

@@ -445,9 +445,30 @@ const buildPatternC = (id, className, options) => [
     '  });',
     '</script>',
 ].join('\n');
+/**
+ * 패턴 D: React 렌더 HTML을 wrapper로 감싼 뒤 Draggable init 스크립트를 append.
+ * 패턴 A/B/C와 달리 React 렌더링을 대체하지 않고 보완한다.
+ * wrapper div가 tbody를 찾아 window.ncua.Draggable을 초기화한다.
+ */
+const buildPatternD = (id, reactHtml, className) => [
+    `<div id="${id}">`,
+    reactHtml,
+    '<script>',
+    "  document.addEventListener('DOMContentLoaded', function () {",
+    `    const tbody = document.querySelector('#${id} tbody');`,
+    `    if (tbody) new window.ncua.${className}(tbody, {`,
+    '      onDrop: function(fromId, toId, edge) {',
+    '        // TODO: 순서 업데이트 처리 (fromId 행을 toId 행의 edge 방향으로 이동)',
+    '      }',
+    '    });',
+    '  });',
+    '</script>',
+    '</div>',
+].join('\n');
 /**
  * CDN init 스크립트 생성. 패턴은 `jsApi.cdnPattern` (A/B/C)으로 결정한다.
  * 호출자는 `cdnPattern` 부재 시 isCdnInput=false로 분기하여 React renderToStaticMarkup 경로를 사용한다.
+ * 패턴 D는 React 렌더 완료 후 buildPatternD를 별도 호출한다.
  */
 const buildCdnInitScript = (pattern, componentName, instanceId, className, options) => {
     const id = `ncua-${componentName}-${instanceId}`;
@@ -808,13 +829,21 @@ const renderToHtml = (params) => {
                 }
             }
         }
-        // HTML 출력: CDN-input은 init script, 그 외는 React 정적 HTML (renderToStaticMarkup은 필요할 때만 호출)
-        const cdnInitScript = isCdnInput && jsApi?.cdnPattern
+        // HTML 출력: 패턴별 분기
+        // - 패턴 A/B/C: CDN init 스크립트만 (renderToStaticMarkup 호출 안 함)
+        // - 패턴 D: React 정적 HTML + Draggable init 스크립트
+        // - cdnPattern 없음: React 정적 HTML
+        // renderToStaticMarkup은 필요한 분기(D, 패턴 없음)에서만 호출한다.
+        const isPatternD = jsApi?.cdnPattern === 'D';
+        const cdnInitScript = isCdnInput && jsApi?.cdnPattern && !isPatternD
             ? buildCdnInitScript(jsApi.cdnPattern, normalized, instanceId, jsApi.className, removeBlockedProps(mergedCdnProps))
             : null;
+        const buildReactHtml = () => `<!-- ncua:${normalized} start -->\n${reactRuntime.renderToStaticMarkup(reactRuntime.createElement(Component, resolvedProps))}\n<!-- ncua:${normalized} end -->`;
         const html = cdnInitScript !== null
             ? cdnInitScript
-            : `<!-- ncua:${normalized} start -->\n${reactRuntime.renderToStaticMarkup(reactRuntime.createElement(Component, resolvedProps))}\n<!-- ncua:${normalized} end -->`;
+            : isPatternD && jsApi
+                ? buildPatternD(`ncua-${normalized}-${instanceId}`, buildReactHtml(), jsApi.className)
+                : buildReactHtml();
         // Story 5.1-8: jsRequired 컴포넌트는 React data 의 default 무시 (vanilla 정의에 없는 React-only default 누수 차단).
         // React 컴포넌트는 기존 동작 유지.
         const isJsRequired = componentData.jsRequired === true;

package/bin/types.d.ts

@@ -124,9 +124,10 @@ export interface JsApiInfo {
      * - A: `new ncua.X(element, options)` — element가 곧 컨테이너
      * - B: `new ncua.X(options)` — options.container로 자동 append
      * - C: `new ncua.X(options)` — getElement() + 수동 append
+     * - D: React 렌더 HTML을 `<div id>` 래퍼로 감싸고, tbody 타겟 Draggable init `<script>` 를 append. Draggable 전용.
      * 부재 시 React 정적 HTML 경로로 fallback.
      */
-    cdnPattern?: 'A' | 'B' | 'C';
+    cdnPattern?: 'A' | 'B' | 'C' | 'D';
 }
 export interface ComplianceRuleHint {
     attr: string;

package/bin/utils/domEnvironment.js

@@ -59,6 +59,7 @@ const setupDomEnvironment = () => {
         'Node',
         'Event',
         'CustomEvent',
+        'Image',
     ]) {
         if (typeof globalThis[key] === 'undefined') {
             globalThis[key] = dom.window[key];

package/bin/version.d.ts

@@ -3,4 +3,4 @@
  * scripts/generate-version-ts.ts 가 ui-admin/package.json 의 version 으로부터 자동 생성한다.
  * 수동 편집 금지 — 빌드(`pnpm generate:version-ts` 또는 `pnpm build`) 시 덮어쓰여진다.
  */
-export declare const VERSION = "1.8.9";
+export declare const VERSION = "1.8.12";

package/bin/version.js

@@ -6,4 +6,4 @@ exports.VERSION = void 0;
  * scripts/generate-version-ts.ts 가 ui-admin/package.json 의 version 으로부터 자동 생성한다.
  * 수동 편집 금지 — 빌드(`pnpm generate:version-ts` 또는 `pnpm build`) 시 덮어쓰여진다.
  */
-exports.VERSION = '1.8.9';
+exports.VERSION = '1.8.12';

package/data/_icons.json

@@ -1,5 +1,5 @@
 {
-  "totalCount": 2542,
+  "totalCount": 2547,
   "fillCount": 1198,
   "icons": [
     {
@@ -3292,6 +3292,21 @@
       "kebab": "color-file-html-solid",
       "fill": false
     },
+    {
+      "name": "ColorFileHwpDefault",
+      "kebab": "color-file-hwp-default",
+      "fill": false
+    },
+    {
+      "name": "ColorFileHwpGray",
+      "kebab": "color-file-hwp-gray",
+      "fill": false
+    },
+    {
+      "name": "ColorFileHwpSolid",
+      "kebab": "color-file-hwp-solid",
+      "fill": false
+    },
     {
       "name": "ColorFileImageDefault",
       "kebab": "color-file-image-default",
@@ -8152,6 +8167,11 @@
       "kebab": "maximize02-fill",
       "fill": true
     },
+    {
+      "name": "Maximize03",
+      "kebab": "maximize03",
+      "fill": false
+    },
     {
       "name": "MedicalCircle",
       "kebab": "medical-circle",
@@ -8812,6 +8832,11 @@
       "kebab": "navigation-pointer-off02-fill",
       "fill": true
     },
+    {
+      "name": "New",
+      "kebab": "new",
+      "fill": false
+    },
     {
       "name": "NotificationBox",
       "kebab": "notification-box",

package/data/context-tab.json

@@ -0,0 +1,119 @@
+{
+  "name": "context-tab",
+  "exportName": "ContextTab",
+  "importPath": "@ncds/ui-admin",
+  "jsRequired": true,
+  "category": "navigation",
+  "description": "ContextTab은 페이지 전체의 작업 컨텍스트(scope)를 전환하는 가로 탭 컴포넌트입니다. 멀티 테넌트 어드민(다중 쇼핑몰·계정·워크스페이스 등)에서 좌측 ☰ 전체 목록 Dropdown과 우측 ← → Slider Navigation을 항상 통합 제공합니다.",
+  "aliases": [
+    "ContextTab",
+    "컨텍스트탭",
+    "컨텍스트 탭",
+    "다중쇼핑몰",
+    "쇼핑몰전환",
+    "워크스페이스전환",
+    "scope",
+    "1depth",
+    "Dropdown",
+    "Slider",
+    "multi-tenant",
+    "네비게이션",
+    "NCDS"
+  ],
+  "hasChildren": false,
+  "whenToUse": [
+    "페이지 전체 데이터/설정의 적용 대상(쇼핑몰·계정·워크스페이스 등)을 전환",
+    "다중 컨텍스트(2개 이상, 실 사용 무제한)를 한 탭 바에서 노출",
+    "컨텍스트 전환 시 페이지 데이터 재로드를 동반",
+    "모든 페이지의 PageTitle 외부 직하단 같은 자리에 고정 배치"
+  ],
+  "forbiddenRules": [
+    "PageTitle 카드 내부 배치 금지",
+    "블록 타이틀 하단·블록 내부 배치 금지(콘텐츠 영역 탭은 HorizontalTab 사용)",
+    "Size 변경 금지(md 단일)",
+    "Dropdown 또는 Slider Navigation 생략 금지",
+    "한 페이지에 ContextTab 복수 노출 금지",
+    "1개 컨텍스트 단독 노출 금지(PageTitle Title 영역에 컨텍스트명 표기로 대체)",
+    "콘텐츠 변경 없이 탭만 전환 금지(데이터 재로드 동반)",
+    "Dropdown Active 마커에 dot 형태 또는 Red 사용 금지(✓ Check icon 단일)",
+    "콘텐츠 영역 전환에 ContextTab 사용 금지(HorizontalTab 사용)",
+    "탭 높이 변형 금지(36px 고정)",
+    "활성 탭에 테두리 추가 금지(Shadow/sm 단독 raised)",
+    "Dropdown panel 헤더 영역 추가 금지"
+  ],
+  "seeAlso": [
+    "horizontal-tab",
+    "vertical-tab",
+    "badge"
+  ],
+  "props": {
+    "activeTab": {
+      "type": "string",
+      "required": false
+    },
+    "className": {
+      "type": "string",
+      "required": false
+    },
+    "menus": {
+      "type": "object",
+      "required": false,
+      "rawType": "import(\"/home/runner/_work/ncds/ncds/packages/ui-admin/src/components/navigation/context-tab/ContextTab\").ContextTabItemProps[] | undefined",
+      "isArray": true,
+      "properties": {
+        "id": {
+          "type": "string",
+          "required": true
+        },
+        "label": {
+          "type": "string",
+          "required": true
+        },
+        "isNew": {
+          "type": "boolean",
+          "required": false
+        },
+        "badgeLabel": {
+          "type": "string",
+          "required": false
+        },
+        "disabled": {
+          "type": "boolean",
+          "required": false
+        }
+      },
+      "default": "[]"
+    },
+    "onTabChange": {
+      "type": "function",
+      "required": false
+    },
+    "visibleTabsCount": {
+      "type": "number",
+      "required": false,
+      "default": "DEFAULT_VISIBLE_TABS_COUNT"
+    }
+  },
+  "html": {},
+  "bemClasses": [
+    "ncua-context-tab",
+    "ncua-context-tab__bar",
+    "ncua-context-tab__control ncua-context-tab__control--menu",
+    "ncua-context-tab__control ncua-context-tab__control--next",
+    "ncua-context-tab__control ncua-context-tab__control--prev",
+    "ncua-context-tab__nav",
+    "ncua-context-tab__option",
+    "ncua-context-tab__option-check",
+    "ncua-context-tab__option-label",
+    "ncua-context-tab__panel",
+    "ncua-context-tab__panel-column",
+    "ncua-context-tab__tab",
+    "ncua-context-tab__tab-label"
+  ],
+  "usage": {
+    "import": "import { ContextTab } from '@ncds/ui-admin';",
+    "react": {
+      "default": "<ContextTab />"
+    }
+  }
+}

package/data/data-grid.json

@@ -163,6 +163,10 @@
           "type": "string",
           "required": false
         },
+        "draggable": {
+          "type": "boolean",
+          "required": false
+        },
         "fixedHeader": {
           "type": "boolean",
           "required": false

package/data/table.json

@@ -53,7 +53,17 @@
     "Portal",
     "Floating UI",
     "스크롤 컨테이너",
-    "scrollbar token"
+    "scrollbar token",
+    "draggable",
+    "DnD",
+    "drag and drop",
+    "행 드래그",
+    "행 순서 변경",
+    "드래그앤드롭",
+    "Table.DragCell",
+    "Table.DragHeaderCell",
+    "dragId",
+    "onRowDrop"
   ],
   "hasChildren": true,
   "whenToUse": [
@@ -81,6 +91,11 @@
       "type": "ReactNode",
       "required": true
     },
+    "draggable": {
+      "type": "boolean",
+      "required": false,
+      "default": false
+    },
     "fixedHeader": {
       "type": "boolean",
       "required": false,
@@ -143,11 +158,19 @@
         "className": {
           "type": "string",
           "required": false
+        },
+        "onRowDrop": {
+          "type": "function",
+          "required": false
         }
       }
     },
     "Table.Row": {
       "props": {
+        "dragId": {
+          "type": "string",
+          "required": false
+        },
         "selected": {
           "type": "boolean",
           "required": false
@@ -162,6 +185,34 @@
         }
       }
     },
+    "Table.DragHeaderCell": {
+      "props": {
+        "children": {
+          "type": "ReactNode",
+          "required": false
+        },
+        "className": {
+          "type": "string",
+          "required": false
+        }
+      }
+    },
+    "Table.DragCell": {
+      "props": {
+        "children": {
+          "type": "ReactNode",
+          "required": false
+        },
+        "className": {
+          "type": "string",
+          "required": false
+        },
+        "disabled": {
+          "type": "boolean",
+          "required": false
+        }
+      }
+    },
     "Table.HeaderCell": {
       "props": {
         "minWidth": {
@@ -253,6 +304,8 @@
   "html": {},
   "bemClasses": [
     "ncua-table",
+    "ncua-table-",
+    "ncua-table--draggable",
     "ncua-table--fixed-header",
     "ncua-table--horizontal",
     "ncua-table--hoverable",
@@ -261,6 +314,11 @@
     "ncua-table-wrapper",
     "ncua-table__body",
     "ncua-table__cell",
+    "ncua-table__drag-cell",
+    "ncua-table__drag-cell-inner",
+    "ncua-table__drag-handle",
+    "ncua-table__drag-header-cell",
+    "ncua-table__drag-header-icon",
     "ncua-table__empty",
     "ncua-table__footer",
     "ncua-table__h-scroll-container",
@@ -274,6 +332,8 @@
     "ncua-table__header-cell-text",
     "ncua-table__pagination",
     "ncua-table__row",
+    "ncua-table__row--drag-over-bottom",
+    "ncua-table__row--drag-over-top",
     "ncua-table__row--error",
     "ncua-table__row--selected",
     "ncua-table__row--warning",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ncds/ui-admin-mcp",
-  "version": "1.0.0-alpha.22",
+  "version": "1.0.0-alpha.24",
   "description": "NCDS UI Admin MCP 서버 — AI 에이전트가 NCUA 컴포넌트를 조회하고 HTML을 검증할 수 있는 MCP 서버",
   "bin": {
     "ncua-mcp": "./bin/server.mjs"
@@ -44,7 +44,7 @@
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "1.1.0",
     "@atlaskit/pragmatic-drag-and-drop-react-accessibility": "1.1.4",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@ncds/ui-admin-icon": "0.1.9",
+    "@ncds/ui-admin-icon": "0.1.12",
     "classnames": "2.5.1",
     "dompurify": "3.4.1",
     "flatpickr": "4.6.13",