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

package/bin/overrides/composition.json

@@ -879,7 +879,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).",
+    "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만 사용할 것.",
     "aliasesExtra": [
       "vertical-table",
       "form-table",
@@ -898,9 +898,15 @@
     "bemClassesExtra": [
       "ncua-table--in-data-grid",
       "ncua-table__required",
-      "ncua-table__cell--with-tooltip",
-      "ncua-table__cell-inner",
-      "ncua-table__cell-label"
+      "ncua-table--fixed-header",
+      "ncua-table__h-scroll-container",
+      "ncua-table__h-scroll-inner",
+      "ncua-table__scroll-area",
+      "ncua-table__scroll-container",
+      "ncua-table__h-scrollbar",
+      "ncua-table__h-scrollbar-thumb",
+      "ncua-table__scrollbar",
+      "ncua-table__scrollbar-thumb"
     ],
     "allowedChildren": {
       "Table": ["Table.Header", "Table.Body", "Table.Footer", "Table.ColGroup", "Table.Empty"],
@@ -960,30 +966,38 @@
     },
     "canonicalExamples": {
       "_note": "P6: NCDS Table 은 같은 <th> 태그를 두 컨텍스트로 사용한다. Horizontal=컬럼 헤더(Table.HeaderCell→ncua-table__header-cell), Vertical=행 라벨(Table.Cell with isHeader=true→<th scope='row' class='ncua-table__cell'>). 두 시나리오를 분리 등록하여 AI 가 정확히 분기 학습하도록 한다. 절대 vertical 에 Table.HeaderCell 을 사용하지 말 것.",
-      "horizontal-with-page-scroll-wrapper": {
-        "description": "P10: 컬럼 수가 많아 페이지 너비 초과 시 NCDS Table 외곽을 페이지 prefix wrapper 로 감싸 가로 스크롤 처리. 표준 wrapper 이름은 'page-table__scroll' (또는 프로젝트 prefix 통일, 예: 'shop-table__scroll'). wrapper 안에 'page-table__scroll-inner' (min-width 적용) 한 단계 더, 그 안에 ncua-table-wrapper. CSS: .page-table__scroll { overflow-x: auto; } .page-table__scroll-inner { min-width: 1200px; }. 동일 프로젝트 내에서 같은 wrapper 이름 사용 — 매번 다른 이름(sgr-comb-scroll/opt-scroll 등) 생성 금지. 트리 내부의 Table 구조는 horizontal-with-header-cell 과 동일.",
+      "horizontal-with-scroll": {
+        "description": "컬럼 수가 많아 가로 스크롤이 필요하거나 행 수가 많아 세로 스크롤이 필요한 경우 — Table 컴포넌트의 내장 props 사용. horizontalScroll=true → ncua-table__h-scroll-container 구조 자동 생성(커스텀 wrapper 불필요). fixedHeader=true → 헤더 고정(ncua-table--fixed-header). maxHeight → 세로 스크롤 높이 제한. minWidth → 전체 테이블 최소 너비(--ncua-table-min-width CSS 변수). Table.ColGroup widths/minWidths 배열로 각 컬럼 너비 명시. ⚠️ pbp-table-scroll / page-table__scroll 같은 커스텀 CSS wrapper 절대 생성 금지 — NCDS가 모든 scroll DOM을 자동 생성한다.",
         "props": {
           "type": "horizontal",
+          "horizontalScroll": true,
+          "fixedHeader": true,
           "hoverable": true,
+          "maxHeight": 340,
+          "minWidth": 1140,
           "children": [
+            {
+              "component": "table.col-group",
+              "props": {
+                "widths": [80, 160, 80, 80, 64, 80, 80, 80, 80],
+                "minWidths": [80, 160, 80, 80, 64, 80, 80, 80, 80]
+              }
+            },
             {
               "component": "table.header",
               "children": [
                 {
                   "component": "table.row",
                   "children": [
-                    {
-                      "component": "table.header-cell",
-                      "children": ["컬럼 1"]
-                    },
-                    {
-                      "component": "table.header-cell",
-                      "children": ["컬럼 2"]
-                    },
-                    {
-                      "component": "table.header-cell",
-                      "children": ["컬럼 3"]
-                    }
+                    { "component": "table.header-cell", "children": ["ID"] },
+                    { "component": "table.header-cell", "children": ["상품명"] },
+                    { "component": "table.header-cell", "children": ["카테고리"] },
+                    { "component": "table.header-cell", "children": ["가격"] },
+                    { "component": "table.header-cell", "children": ["상태"] },
+                    { "component": "table.header-cell", "children": ["재고"] },
+                    { "component": "table.header-cell", "children": ["등록일"] },
+                    { "component": "table.header-cell", "children": ["담당자"] },
+                    { "component": "table.header-cell", "children": ["메모"] }
                   ]
                 }
               ]
@@ -1049,7 +1063,7 @@
         }
       },
       "vertical-form-label-with-required": {
-        "description": "P7/P12: Vertical Table 필수 라벨 표기 표준. ⚠️ ncua-table__required 는 NCDS Table SCSS 에서 font-size: var(--font-size-sm) (14px) 로 정의되는데 라벨 텍스트는 var(--font-size-xs) (13px) — baseline 이 어긋남. 정렬 보정을 위해 페이지 prefix wrapper 로 inline-flex + align-items: center 적용 권장. wrapper 클래스명은 페이지 prefix 통일 (예: 'page-vlabel') — 페이지 SCSS 에 .page-vlabel { display: inline-flex; align-items: center; gap: 4px; } .page-vlabel .ncua-table__required { line-height: 1; } 정의. component descriptor 트리로는 wrapper + raw span 을 한 번에 표현 불가 → render_to_html 출력 후 페이지 코드에서 wrapper 추가하거나, 라벨 텍스트 자체에 markup 포함 string 으로 전달. P16: 안내 Tooltip 이 필요하면 본 시나리오 대신 'vertical-form-label-with-tooltip' 을 사용하거나, 본 시나리오의 라벨 Cell 에 `tooltip: TooltipProps` prop 을 추가하면 된다 (Cell 내부 ncua-table__cell-inner / ncua-table__cell-label 로 자동 wrapping — 별도 페이지 wrapper 불필요).",
+        "description": "P7/P12: Vertical Table 필수 라벨 표기 표준. ncua-table__required 는 라벨 텍스트 앞에 `<span class='ncua-table__required'>*</span>` 형태로 prepend. 라벨 셀(Table.Cell with isHeader=true) 의 children 첫 자식이 raw markup string, 두 번째가 라벨 텍스트. ⚠️ component descriptor 트리로 페이지 prefix wrapper(예: page-vlabel) + raw span 을 한 번에 표현 불가 → render_to_html 출력 후 페이지 코드에서 추가하거나, 본 시나리오처럼 markup 을 children string 으로 전달. P16: 안내 Tooltip 이 필요하면 'vertical-form-label-with-tooltip' 시나리오 사용 — Table.Cell 은 tooltip prop 을 받지 않으며 라벨 셀의 children 에 합성한다.",
         "props": {
           "type": "vertical",
           "children": [
@@ -1112,7 +1126,7 @@
         }
       },
       "vertical-form-label-with-tooltip": {
-        "description": "P16/P23: Vertical Table 라벨 + 안내 Tooltip 표준. 라벨 옆 안내 아이콘은 Table.Cell.tooltip prop 으로 전달 — Cell 내부에 ncua-table__cell-inner / ncua-table__cell-label / .ncua-tooltip 구조로 자동 wrapping (ncua-table__cell--with-tooltip modifier 적용). 페이지 prefix wrapper(예: page-vlabel, sgr-tooltip-wrapper) 또는 라벨 셀 외부에 별도 Tooltip 컴포넌트 배치 금지 — 정렬 어긋남 + 발명 클래스 hallucination 의 주원인. tooltip 값은 NCDS Tooltip 의 React props 그대로 (type='short'/'long', tooltipType='black'/'white', content/title 등). ⚠️ P23: 출력 BEM 은 반드시 `<th scope='row' class='ncua-table__cell ncua-table__cell--with-tooltip'>` — `<th class='ncua-required'>` 같은 발명 클래스 사용 금지 (NCDS 미제공). 필수 마크는 `<span class='ncua-table__required'>*</span>` 을 라벨 텍스트 앞에 prepend. ⚠️ CDN HTML 모드에서는 tooltip 영역이 placeholder + script — CDN JS 마운트 후 anchor span 에 `<div data-tooltip-seq data-tooltip-initialized>` wrapper + `<span class='ncua-tooltip__icon'>` SVG wrapper + inline style 자동 부착. 이 결과 DOM 을 보고 '정적 출력 = NCDS 표준' 으로 오인해 페이지에서 직접 작성하지 말 것.",
+        "description": "P16/P23: Vertical Table 라벨 + 안내 Tooltip 표준 합성 패턴. Table.Cell 의 children 에 div wrapper 한 단계를 두고 그 안에 [필수 마크 span(필요 시), 라벨 텍스트, Tooltip 컴포넌트] 순으로 합성한다. NCDS Table SCSS 의 vertical 모드 룰이 Tooltip 앵커 span 을 자식으로 가진 div(셀렉터: `th:first-child > div:has(> .ncua-tooltip)`)에 한해 inline-flex 정렬을 자동 적용하므로 라벨과 합성 자식이 같은 선상에 배치된다. Tooltip 앵커 박스와 CDN JS 마운트 후 자동 생성되는 icon wrapper span(`.ncua-tooltip__icon`) 모두 SVG 크기(14px)로 수축되어 React 출력과 CDN HTML 출력 양쪽에서 동일한 박스 메트릭으로 정렬된다. spacing 은 자식별 margin 으로 관리(Required: margin-right 4px, Tooltip: margin-left 4px) — wrapper 에 flex gap 미사용. ⚠️ 사용 금지: (a) Table.Cell 에 tooltip prop 전달(시그니처에 없음). (b) ncua-table__cell--with-tooltip 모디파이어(NCDS 미정의). (c) ncua-table__cell-inner / ncua-table__cell-label 자동 wrapper(생성 안 됨). (d) 페이지 prefix wrapper(page-vlabel, sgr-tooltip-wrapper 등) 외부 배치 — 정렬 어긋남 + hallucination 주원인. ⚠️ 출력 BEM 표준은 라벨 셀이 모디파이어 없는 `<th scope='row' class='ncua-table__cell'><div>...<span class='ncua-tooltip ...'>...</span></div></th>` — th 에 추가 클래스 없음, div wrapper 가 정렬 책임. ⚠️ CDN HTML 모드의 tooltip 영역은 정적 placeholder + script — CDN JS 마운트 후 anchor span 에 `<div data-tooltip-seq data-tooltip-initialized>` wrapper + `<span class='ncua-tooltip__icon'>` SVG wrapper + inline style 자동 부착. 정적 출력을 그대로 페이지 코드로 작성하지 말고 render_to_html 출력 + CDN 스크립트 마운트 흐름을 따를 것. Tooltip 의 props 는 render_to_html 의 tooltip 컴포넌트 spec 그대로 사용(type 'short'|'long', tooltipType 'black'|'white', title, content, position 등).",
         "props": {
           "type": "vertical",
           "children": [
@@ -1121,19 +1135,16 @@
               "children": [
                 {
                   "component": "table.row",
-                  "_note": "필수 + 안내 tooltip 라벨. children 첫 자식은 ncua-table__required span raw markup, 두 번째는 라벨 텍스트. tooltip 은 props.tooltip 으로 전달 — Cell 내부에서 라벨과 함께 inline-flex wrapping.",
+                  "_note": "필수 + 안내 tooltip 라벨. Table.Cell 의 children 트리는 div wrapper 한 단계 안에 [필수 마크 span raw markup, 라벨 텍스트, Tooltip 컴포넌트] 순으로 합성. tree 표현 한계로 div 와 Tooltip 자식을 한 markup string 으로 묶고 anchor 만 placeholder 로 표시 — render_to_html 출력이 사용 환경에 맞춰 실제 Tooltip 마크업으로 채운다.",
                   "children": [
                     {
                       "component": "table.cell",
                       "props": {
-                        "isHeader": true,
-                        "tooltip": {
-                          "type": "short",
-                          "tooltipType": "black",
-                          "content": "외부에 노출되는 상품명입니다. 50자 이내로 입력하세요."
-                        }
+                        "isHeader": true
                       },
-                      "children": ["<span class=\"ncua-table__required\">*</span>", "상품명"]
+                      "children": [
+                        "<div><span class=\"ncua-table__required\">*</span>상품명<span class=\"ncua-tooltip ncua-tooltip--sm ncua-tooltip--short ncua-tooltip--stroke\"></span></div>"
+                      ]
                     },
                     {
                       "component": "table.cell",
@@ -1143,20 +1154,16 @@
                 },
                 {
                   "component": "table.row",
-                  "_note": "비필수 + 안내 tooltip. required span 없이 텍스트 + tooltip prop.",
+                  "_note": "비필수 + 안내 tooltip. 필수 마크 span 없이 div wrapper 안에 [라벨 텍스트, Tooltip 컴포넌트] 합성. children 트리는 위 row 와 동일 구조에서 Required span 만 빠진 형태.",
                   "children": [
                     {
                       "component": "table.cell",
                       "props": {
-                        "isHeader": true,
-                        "tooltip": {
-                          "type": "long",
-                          "tooltipType": "white",
-                          "title": "카테고리 안내",
-                          "content": "상품을 분류하는 최상위 카테고리입니다. 변경 시 검색·노출 영역에 영향."
-                        }
+                        "isHeader": true
                       },
-                      "children": ["카테고리"]
+                      "children": [
+                        "<div>카테고리<span class=\"ncua-tooltip ncua-tooltip--sm ncua-tooltip--long ncua-tooltip--stroke\"></span></div>"
+                      ]
                     },
                     {
                       "component": "table.cell",
@@ -1446,7 +1453,7 @@
   },
   "block-container": {
     "_note": "P10: BlockContainer 는 페이지 블록의 외곽 컨테이너. children 으로 block-header + 본문 컴포넌트(table/data-grid/자유영역) 조합. AI 가 sgr-block / sgr-block-container 로 우회하지 않도록 다중 시나리오 등록.",
-    "descriptionExtra": "[중요] 페이지 블록 외곽 컨테이너. 표준 자식 구조: BlockHeader + BlockContainer.Body(필수 wrapping — P14 룰). 본문은 Body 안에 table/data-grid/form 컴포넌트 배치. 직접 <section class='ncua-block-container'> 마크업 금지 — overflow:hidden / border-radius 등 CDN CSS 보호 받지 못함. 페이지 prefix wrapper (sgr-block / page-section) 우회 절대 금지.",
+    "descriptionExtra": "[중요] 페이지 블록 외곽 컨테이너. 표준 자식 구조: BlockHeader + BlockContainer.Body(필수 wrapping — P14 룰). 본문은 Body 안에 table/data-grid/form 컴포넌트 배치. 직접 <section class='ncua-block-container'> 마크업 금지 — overflow:hidden / border-radius 등 CDN CSS 보호 받지 못함. ⚠️ 페이지에 필요한 모든 '섹션/박스/블록/패널' 영역은 block-container로 구현한다 — 페이지 고유 prefix를 붙인 커스텀 wrapper({page}-block / {page}-section / {page}-panel 등 어떤 이름이든)를 따로 만들지 말 것. 접을 수 있는(collapsible) 블록도 동일하게 block-container 사용.",
     "aliasesExtra": [
       "블록 컨테이너",
       "블록",
@@ -1465,7 +1472,11 @@
       "흰 박스",
       "정보 블록",
       "폼 블록",
-      "데이터 블록"
+      "데이터 블록",
+      "collapsible block",
+      "접을 수 있는 블록",
+      "지표 블록",
+      "kpi 블록"
     ],
     "bemClassesExtra": [],
     "allowedChildren": {
@@ -1827,7 +1838,7 @@
   },
   "page-title": {
     "_note": "P7: PageTitle 은 props 기반 (subComponents 없음). breadcrumbItems / title / primaryAction / secondaryAction / guideButton / onBack / variant prop 으로 구성. AI 가 sgr-page-title 같은 페이지-prefix 로 우회하지 않도록 명시적 canonicalExamples 등록. 출력은 ncua-page-title__page-header / __title-container / __title-row / __title / __action-area 등 정밀 BEM.",
-    "descriptionExtra": "[중요] 페이지 최상단 타이틀 영역 표준. breadcrumbItems + title + primaryAction(우측 강조 버튼) + secondaryAction(취소/목록) + guideButton + onBack + variant(default/detail/fixed). detail variant 는 onBack 으로 좌측 back button 노출. fixed variant 는 스크롤 시 상단 고정. 페이지 prefix(sgr-page-title / page-header) 우회 금지.",
+    "descriptionExtra": "[중요] 페이지 최상단 타이틀 영역 표준. breadcrumbItems + title + primaryAction(우측 강조 버튼) + secondaryAction(취소/목록) + guideButton + onBack + variant(default/detail/fixed). detail variant 는 onBack 으로 좌측 back button 노출. fixed variant 는 스크롤 시 상단 고정. 페이지 prefix(sgr-page-title / page-header) 우회 금지. ⚠️ ReactNode props(guideButton / primaryAction / secondaryAction)는 반드시 {component: 'button', props: {...}} 형태로 전달 — {label:..., size:..., hierarchy:...} raw 객체를 직접 넘기면 React child 오류로 렌더링 전체 실패(breadcrumb 포함). canonicalExamples 의 구조를 반드시 따를 것.",
     "aliasesExtra": [
       "페이지 타이틀",
       "페이지 제목",
@@ -1938,14 +1949,20 @@
           "title": "상품 상세",
           "onBack": "noop",
           "secondaryAction": {
-            "label": "삭제",
-            "size": "md",
-            "hierarchy": "destructive-secondary"
+            "component": "button",
+            "props": {
+              "label": "삭제",
+              "size": "md",
+              "hierarchy": "destructive-secondary"
+            }
           },
           "primaryAction": {
-            "label": "수정",
-            "size": "md",
-            "hierarchy": "primary"
+            "component": "button",
+            "props": {
+              "label": "수정",
+              "size": "md",
+              "hierarchy": "primary"
+            }
           }
         }
       },
@@ -2414,21 +2431,7 @@
   "notification": {
     "_note": "P20/P22: Notification 은 비차단 알림 컴포넌트. type ∈ {floating, full-width, message} × color ∈ {neutral, error, warning, success, info} 매트릭스 (단, floating 은 info 색상 미지원). props 기반 — subComponents 없음. ⚠️⚠️ BEM prefix 는 type 별로 분리: type='floating' → `ncua-floating-notification__*`, type='full-width' → `ncua-full-width-notification__*`, type='message' → `ncua-message-notification__*`. **generic 한 `ncua-notification__*` prefix 는 존재하지 않음** — godomall5 페이지에서 발견된 가짜 BEM. floating 은 페이지 우측 영역 자동 노출(autoClose 지원), full-width 는 화면 상단 가로 배너, message 는 인라인 메시지 박스. onHidePermanently 는 message / full-width 에서만 동작. React 컴포넌트 + CDN CSS 완비 — 반드시 render_to_html('notification', {...}) 호출해 정확한 type-prefix BEM 출력을 받아 그대로 사용.",
     "descriptionExtra": "[중요] 비차단 알림 컴포넌트. type 으로 표현 형태(floating/full-width/message) 결정, color 로 상태(neutral/error/warning/success/info) 결정. ⚠️ BEM prefix 가 type 별로 다름: floating→ncua-floating-notification__*, full-width→ncua-full-width-notification__*, message→ncua-message-notification__*. generic ncua-notification__* prefix 는 존재하지 않으니 절대 직접 작성 금지 — render_to_html 출력 그대로 사용. type='floating' 은 color='info' 미지원. autoClose 는 floating 전용 (밀리초). onHidePermanently 는 message / full-width 전용. 페이지 prefix wrapper(toast-wrapper, alert-banner 등) 우회 금지.",
-    "bemClassesExtra": [
-      "ncua-floating-notification",
-      "ncua-floating-notification__container",
-      "ncua-floating-notification__content",
-      "ncua-floating-notification__title",
-      "ncua-floating-notification__icon",
-      "ncua-full-width-notification",
-      "ncua-full-width-notification__container",
-      "ncua-full-width-notification__content",
-      "ncua-full-width-notification__title",
-      "ncua-message-notification",
-      "ncua-message-notification__container",
-      "ncua-message-notification__content",
-      "ncua-message-notification__title"
-    ],
+    "bemClassesExtra": ["ncua-floating-notification__icon"],
     "aliasesExtra": [
       "알림",
       "알림창",
@@ -2496,5 +2499,278 @@
         }
       }
     }
+  },
+  "date-picker": {
+    "descriptionExtra": "[중요] 단일 날짜 또는 날짜+시간 입력에 사용하는 DatePicker. CDN에서는 window.ncua.DatePicker 단일 클래스로 동작한다. datePickerOptions 배열에 1개를 전달하면 single 모드, 2개를 전달하면 range 모드가 된다. ⚠️ datePickerOptions 각 요소의 options.static:true 절대 생략 금지 — 누락 시 flatpickr-wrapper div 가 생성되지 않아 flatpickr-calendar 가 input 필드 밖으로 밀려나 레이아웃이 파괴된다. options 객체는 canonicalExample 을 그대로 복사할 것: { mode:'single', static:true, dateFormat:'Y-m-d', clickOpens:true, allowInvalidPreload:true, locale:'ko' }. ⚠️ .ncua-date-picker__input 에 border·shadow·padding 을 직접 적용하는 커스텀 CSS 절대 금지 — 이 스타일들은 CDN CSS 가 .flatpickr-wrapper 에 자동 적용하며, __input 에 덮어쓰면 JS 초기화 후 이중 border 등 시각적 충돌이 발생한다. DatePicker 컨테이너는 JS 초기화 전 빈 div 이며, JS 가 .flatpickr-wrapper → .ncua-date-picker__input 구조를 동적으로 생성한다. width 조정이 필요하다면 컨테이너 div 에만 적용할 것(xs 기준 138px 은 CDN CSS 기본값). ⚠️ rangeMode 클래스는 range-date-picker(기간 범위) 전용 — 단일 DatePicker 의 flatpickr-calendar 에 rangeMode 를 참조하거나 추가 금지. JS 초기화 후 올바른 DOM 구조: .flatpickr-wrapper(input + flatpickr-calendar 래핑) 이후 .ncua-date-picker__ico label 이 flatpickr-wrapper 밖에 위치한다. ⚠️ 캘린더 아이콘 SVG 직접 작성 절대 금지 — ncua-date-picker__ico label 안의 SVG 는 컴포넌트가 stroke='currentColor' 로 자동 렌더링하며, stroke='black' 등 하드코딩하면 다크 테마/CDN 스타일 충돌 발생.",
+    "aliasesExtra": [
+      "날짜 선택",
+      "단일 날짜",
+      "date input",
+      "flatpickr",
+      "날짜 입력",
+      "datepicker",
+      "date picker",
+      "single date",
+      "날짜+시간",
+      "time picker"
+    ],
+    "bemClassesExtra": [],
+    "notApplicableAreas": ["allowedChildren", "bemClassesExtra"],
+    "canonicalExamples": {
+      "single": {
+        "description": "단일 날짜 선택 (기본)",
+        "props": {
+          "size": "xs",
+          "datePickerOptions": [
+            {
+              "element": "date-input",
+              "placeholder": "날짜 선택",
+              "options": {
+                "mode": "single",
+                "static": true,
+                "dateFormat": "Y-m-d",
+                "clickOpens": true,
+                "allowInvalidPreload": true,
+                "locale": "ko"
+              }
+            }
+          ]
+        }
+      },
+      "with-time": {
+        "description": "날짜+시간 선택",
+        "props": {
+          "size": "xs",
+          "datePickerOptions": [
+            {
+              "element": "datetime-input",
+              "placeholder": "날짜·시간 선택",
+              "options": {
+                "mode": "single",
+                "static": true,
+                "dateFormat": "Y-m-d H:i",
+                "enableTime": true,
+                "clickOpens": true,
+                "allowInvalidPreload": true,
+                "locale": "ko"
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  "range-date-picker": {
+    "descriptionExtra": "[중요] 시작일·종료일 기간 범위 선택. CDN에서는 window.ncua.DatePicker 에 datePickerOptions 2개를 전달해 range 모드로 동작한다. 빠른 기간 버튼이 필요하면 range-date-picker-with-buttons 를 사용한다. ⚠️ datePickerOptions 각 요소의 options.static:true 절대 생략 금지 — 누락 시 flatpickr-wrapper div 가 생성되지 않아 flatpickr-calendar 가 input 필드 밖으로 밀려나 레이아웃이 파괴된다. options 객체는 canonicalExample 을 그대로 복사할 것: { mode:'range', static:true, dateFormat:'Y-m-d', clickOpens:true, allowInvalidPreload:true, locale:'ko' }. ⚠️ .ncua-date-picker__input 에 border·shadow·padding 을 직접 적용하는 커스텀 CSS 절대 금지 — CDN CSS 가 .flatpickr-wrapper 에 자동 적용하며 __input 에 덮어쓰면 이중 border 충돌 발생. flatpickr 가 range 모드 캘린더에 rangeMode 클래스를 자동 부가 — 직접 작성 불필요. ⚠️ 캘린더 아이콘 SVG 직접 작성 절대 금지 — stroke='black' 등 하드코딩 금지, 컴포넌트가 stroke='currentColor' 로 자동 처리한다.",
+    "aliasesExtra": [
+      "기간 선택",
+      "시작일 종료일",
+      "날짜 범위",
+      "range date",
+      "date range",
+      "start end date",
+      "기간 입력",
+      "범위 날짜"
+    ],
+    "bemClassesExtra": [],
+    "notApplicableAreas": ["allowedChildren", "bemClassesExtra"],
+    "canonicalExamples": {
+      "range": {
+        "description": "시작일~종료일 기간 범위 선택 (xs 사이즈, 기본)",
+        "props": {
+          "size": "xs",
+          "datePickerOptions": [
+            {
+              "element": "start-date",
+              "placeholder": "시작일",
+              "options": {
+                "mode": "range",
+                "static": true,
+                "dateFormat": "Y-m-d",
+                "clickOpens": true,
+                "allowInvalidPreload": true,
+                "locale": "ko"
+              }
+            },
+            {
+              "element": "end-date",
+              "placeholder": "종료일",
+              "options": {
+                "mode": "range",
+                "static": true,
+                "dateFormat": "Y-m-d",
+                "clickOpens": true,
+                "allowInvalidPreload": true,
+                "locale": "ko"
+              }
+            }
+          ]
+        }
+      },
+      "range-sm": {
+        "description": "시작일~종료일 기간 범위 선택 (sm 사이즈)",
+        "props": {
+          "size": "sm",
+          "datePickerOptions": [
+            {
+              "element": "start-date",
+              "placeholder": "시작일",
+              "options": {
+                "mode": "range",
+                "static": true,
+                "dateFormat": "Y-m-d",
+                "clickOpens": true,
+                "allowInvalidPreload": true,
+                "locale": "ko"
+              }
+            },
+            {
+              "element": "end-date",
+              "placeholder": "종료일",
+              "options": {
+                "mode": "range",
+                "static": true,
+                "dateFormat": "Y-m-d",
+                "clickOpens": true,
+                "allowInvalidPreload": true,
+                "locale": "ko"
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  "range-date-picker-with-buttons": {
+    "descriptionExtra": "[중요] 시작일·종료일 기간 범위 선택 + 빠른 기간 버튼 내장. CDN에서는 window.ncua.DatePicker 에 datePickerOptions 2개 + buttons 배열을 전달한다. buttons의 권장 세트: 오늘/7일/15일/1개월/3개월/1년. ENTIRE(전체) 및 1주일(unit='weeks') 은 CDN 미지원이므로 제외한다. ⚠️ datePickerOptions 각 요소의 options.static:true 절대 생략 금지 — 누락 시 flatpickr-wrapper div 가 생성되지 않아 flatpickr-calendar 가 input 필드 밖으로 밀려나 레이아웃이 파괴된다. options 객체는 canonicalExample 을 그대로 복사할 것: { mode:'range', static:true, dateFormat:'Y-m-d', clickOpens:true, allowInvalidPreload:true, locale:'ko' }. ⚠️ .ncua-date-picker__input 에 border·shadow·padding 을 직접 적용하는 커스텀 CSS 절대 금지 — CDN CSS 가 .flatpickr-wrapper 에 자동 적용하며 __input 에 덮어쓰면 이중 border 충돌 발생. flatpickr 가 range 모드 캘린더에 rangeMode 클래스를 자동 부가 — 직접 작성 불필요. ⚠️ 캘린더 아이콘 SVG 직접 작성 절대 금지 — stroke='black' 등 하드코딩 금지, 컴포넌트가 stroke='currentColor' 로 자동 처리한다.",
+    "aliasesExtra": [
+      "기간 선택 버튼",
+      "빠른 기간",
+      "기간 버튼",
+      "date range buttons",
+      "period buttons",
+      "오늘 버튼",
+      "1개월 버튼",
+      "기간 프리셋",
+      "date preset"
+    ],
+    "bemClassesExtra": [],
+    "notApplicableAreas": ["allowedChildren", "bemClassesExtra"],
+    "canonicalExamples": {
+      "range-with-buttons": {
+        "description": "시작일~종료일 + 빠른 기간 버튼 (권장 세트: 오늘/7일/15일/1개월/3개월/1년)",
+        "props": {
+          "size": "xs",
+          "datePickerOptions": [
+            {
+              "element": "start-date",
+              "placeholder": "시작일",
+              "options": {
+                "mode": "range",
+                "static": true,
+                "dateFormat": "Y-m-d",
+                "clickOpens": true,
+                "allowInvalidPreload": true,
+                "locale": "ko"
+              }
+            },
+            {
+              "element": "end-date",
+              "placeholder": "종료일",
+              "options": {
+                "mode": "range",
+                "static": true,
+                "dateFormat": "Y-m-d",
+                "clickOpens": true,
+                "allowInvalidPreload": true,
+                "locale": "ko"
+              }
+            }
+          ],
+          "buttons": [
+            { "text": "오늘", "period": 0, "unit": "days", "isCurrent": false },
+            { "text": "7일", "period": 7, "unit": "days", "isCurrent": false },
+            { "text": "15일", "period": 15, "unit": "days", "isCurrent": false },
+            { "text": "1개월", "period": 1, "unit": "months", "isCurrent": false },
+            { "text": "3개월", "period": 3, "unit": "months", "isCurrent": false },
+            { "text": "1년", "period": 1, "unit": "years", "isCurrent": false }
+          ]
+        }
+      },
+      "range-with-buttons-sm": {
+        "description": "시작일~종료일 + 빠른 기간 버튼 (sm 사이즈, 최소 세트: 오늘/1개월/3개월)",
+        "props": {
+          "size": "sm",
+          "datePickerOptions": [
+            {
+              "element": "start-date",
+              "placeholder": "시작일",
+              "options": {
+                "mode": "range",
+                "static": true,
+                "dateFormat": "Y-m-d",
+                "clickOpens": true,
+                "allowInvalidPreload": true,
+                "locale": "ko"
+              }
+            },
+            {
+              "element": "end-date",
+              "placeholder": "종료일",
+              "options": {
+                "mode": "range",
+                "static": true,
+                "dateFormat": "Y-m-d",
+                "clickOpens": true,
+                "allowInvalidPreload": true,
+                "locale": "ko"
+              }
+            }
+          ],
+          "buttons": [
+            { "text": "오늘", "period": 0, "unit": "days", "isCurrent": true },
+            { "text": "1개월", "period": 1, "unit": "months", "isCurrent": false },
+            { "text": "3개월", "period": 3, "unit": "months", "isCurrent": false }
+          ]
+        }
+      }
+    }
+  },
+  "bread-crumb": {
+    "_note": "BreadCrumb 는 items 배열(label + href?) 로 동작. 첫 항목은 Home 아이콘 자동 렌더 — icon prop 불필요. 마지막 항목은 current(href 없음). page-title 의 breadcrumbItems 와 별개 — page-title 안 breadcrumb 를 BreadCrumb 로 중복 사용 금지.",
+    "descriptionExtra": "[중요] 경로 탐색 네비게이션 컴포넌트. items 배열에 {label, href?} 전달: 첫 항목은 Home 아이콘 자동 표시(href 지정 권장), 마지막 항목은 현재 페이지(href 생략). ⚠️ guideButton / primaryAction 같은 ReactNode 슬롯 없음 — items 배열과 className만 허용. ⚠️ page-title 내부에 breadcrumbItems prop 으로 이미 breadcrumb 가 내장되므로, PageTitle 과 BreadCrumb 를 동시에 사용하면 breadcrumb 이 중복된다. 단독 nav 영역이나 page-title 없이 breadcrumb 만 필요한 경우에만 사용.",
+    "aliasesExtra": [
+      "브레드크럼",
+      "브레드크럼바",
+      "경로 탐색",
+      "breadcrumb",
+      "breadcrumbs",
+      "navigation trail",
+      "페이지 경로",
+      "계층 탐색",
+      "현재 위치",
+      "홈 > 카테고리",
+      "네비게이션 경로"
+    ],
+    "bemClassesExtra": [],
+    "notApplicableAreas": ["allowedChildren", "bemClassesExtra"],
+    "canonicalExamples": {
+      "basic": {
+        "description": "3단계 경로. 첫 항목 Home 아이콘 자동, 중간 항목은 링크, 마지막 항목은 현재 페이지(href 없음).",
+        "props": {
+          "items": [
+            { "label": "홈", "href": "/" },
+            { "label": "상품 관리", "href": "/goods" },
+            { "label": "상품 간편 등록" }
+          ]
+        }
+      },
+      "two-level": {
+        "description": "2단계 경로. Home + 현재 페이지만 있는 최소 구성.",
+        "props": {
+          "items": [{ "label": "홈", "href": "/" }, { "label": "대시보드" }]
+        }
+      }
+    }
   }
 }

package/bin/server.js

@@ -90,6 +90,12 @@ const main = async () => {
     const instructions = (0, dataLoader_js_1.loadInstructions)(definitionsDir);
     const complianceRules = (0, dataLoader_js_1.loadComplianceRules)(definitionsDir);
     const jsApiMap = (0, dataLoader_js_1.loadJsApi)(definitionsDir);
+    // ── DOM + React 런타임 초기화 — 번들 로드 전에 실행해야 unifyModuleResolution 이 적용됨 ──
+    // setupDomEnvironment()가 Module._resolveFilename 을 override 하여 react / @ncds/ui-admin-icon 경로를
+    // MCP 기준으로 pin 한다. 번들 로드 이후에 실행하면 번들 내 require() 가 pin 이전 경로로 캐시되어
+    // React 인스턴스 불일치($$typeof Symbol mismatch) 가 발생한다.
+    const reactRuntime = (0, domEnvironment_js_1.setupDomEnvironment)();
+    logger_js_1.logger.info('DOM + React 런타임 초기화 완료');
     // ── 데이터 로딩 ──
     const { map: componentMap, compositionOverrides } = (0, dataLoader_js_1.loadComponentsFromDir)(dataLoader_js_1.DEFAULT_DATA_DIR);
     const { cdn: cdnMeta, icon: iconMeta } = (0, dataLoader_js_1.loadMeta)(dataLoader_js_1.DEFAULT_DATA_DIR);
@@ -109,9 +115,6 @@ const main = async () => {
     catch {
         logger_js_1.logger.warn('아이콘 번들 로딩 실패 — 아이콘 resolve 비활성화');
     }
-    // ── DOM + React 런타임 초기화 (유틸로 추출 § 3.9) ──
-    const reactRuntime = (0, domEnvironment_js_1.setupDomEnvironment)();
-    logger_js_1.logger.info('DOM + React 런타임 초기화 완료');
     // ── 파생 데이터 사전 계산 (code-guide § 5.1 반복 계산 제거) ──
     const rootClassMap = (0, validateHtml_js_1.buildRootClassMap)(componentMap);
     const tokenValueMap = (0, validateHtml_js_1.buildTokenValueMap)(tokenData);

package/bin/tools/renderToHtml.js

@@ -537,7 +537,8 @@ const mergeCdnDefaults = (componentName, cdnDefaults, userProps) => {
         return { merged: userProps, defaultsApplied: [] };
     const userPropsClean = (0, exports.stripFunctionProps)(userProps);
     const baseMerged = (0, lodash_1.merge)((0, lodash_1.cloneDeep)(cdnDefaults), userPropsClean);
-    const merged = componentName === 'date-picker' && Array.isArray(userPropsClean.datePickerOptions)
+    const DATE_PICKER_FAMILY = ['date-picker', 'range-date-picker', 'range-date-picker-with-buttons'];
+    const merged = DATE_PICKER_FAMILY.includes(componentName) && Array.isArray(userPropsClean.datePickerOptions)
         ? {
             ...baseMerged,
             datePickerOptions: userPropsClean.datePickerOptions.map((item) => {

package/bin/types.d.ts

@@ -7,6 +7,8 @@ export interface PropSpec {
     default?: unknown;
     values?: string[];
     rawType?: string;
+    /** 배열 타입임을 명시 — type: 'object'로 분류되어도 이 필드가 true면 반드시 배열([])로 전달해야 함 */
+    isArray?: boolean;
     properties?: Record<string, PropSpec>;
     /** 타입의 의미적 정체성 — 예: 'icon-component'는 SlotIconComponent 계열 아이콘 컴포넌트. renderer가 iconBundle resolve 대상 판정에 사용 */
     semantic?: 'icon-component';