@opsnow-mcp/opsnow-mcp-common-ui-server 1.0.40 → 1.0.41

package/build/components/opsnow-common-grid.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { jsxAttrs, jsxTag, jsxResult } from "./opsnow-common-jsx-helper.js";
 const gridOptionsSchema = z.object({
     animateRows: z.boolean().optional().describe('행 애니메이션 사용 여부'),
     rowSelection: z.object({
@@ -9,7 +10,7 @@ const gridOptionsSchema = z.object({
         enableSelectionWithoutKeys: z.boolean().optional().describe('키 없이 선택 허용'),
     }).optional().describe('행 선택 옵션'),
     tooltipShowDelay: z.number().optional().describe('툴팁 표시 지연 시간'),
-    domLayout: z.enum(['normal', 'autoHeight', 'print']).optional().describe('그리드 레이아웃 방식'),
+    domLayout: z.enum(['autoHeight', 'print']).optional().describe("그리드 레이아웃 방식 — 'autoHeight' 권장(최대 maxGridHeight까지 콘텐츠 맞춤). 고정 높이는 이 키를 빼고 gridHeight. ⚠️ 'normal'은 쓰지 말 것: 컨테이너 높이가 비워져 그리드가 0px로 사라짐(부모 높이와 무관, grid 2.0.7 브라우저 실측)"),
     suppressCellFocus: z.boolean().optional().describe('셀 포커스 비활성화 (셀 클릭 이벤트 사용 시 필수: true)'),
     suppressPaginationPanel: z.boolean().optional().describe('페이지네이션 패널 숨김'),
     masterDetail: z.boolean().optional().describe('마스터/디테일 모드 사용'),
@@ -38,18 +39,20 @@ const columnDefsSchema = z.lazy(() => z.object({
     colId: z.string().optional().describe('컬럼 고유 ID'),
     groupId: z.string().optional().describe('컬럼 그룹 고유 ID'),
     width: z.number().optional().describe('컬럼 너비'),
-    minWidth: z.number().describe('컬럼 최소 너비'),
+    minWidth: z.number().optional().describe('컬럼 최소 너비'),
     maxWidth: z.number().optional().describe('컬럼 최대 너비'),
     pinned: z.enum(['left', 'right']).optional().describe('컬럼 고정 위치'),
     type: z.array(z.enum([
+        'default',
         'number',
+        'integer',
         'cost',
         'ratio',
-        'mixFormat',
         'numberTooltip',
+        'mixFormat',
         'ratioBar',
         'dataBar',
-        'value'
+        'date'
     ])).optional().describe(`컬럼 타입.
     - ratioBar: 여러 색상/세그먼트로 구성 비율을 보여주는 스택 차트 스타일 바. 여러 필드의 비율을 시각화할 때 사용 (예: Cost Composition by Type). 'Ratio Bar' 예제 참고.
     - dataBar: 단일 색상으로 셀 배경을 값에 비례하여 채우는 Excel 스타일 바. 단일 값의 크기를 시각화할 때 사용 (예: 월별 비용 트렌드). 'Data Bar' 예제 참고.`),
@@ -60,6 +63,8 @@ const columnDefsSchema = z.lazy(() => z.object({
             digits: z.number().optional().describe('소수점 자리수'),
             iconRight: z.boolean().optional().describe('오른쪽 아이콘 표시'),
             isPercent: z.boolean().optional().describe('퍼센트 표시 여부'),
+            vendor: z.string().optional().describe('cost 타입: 벤더별 통화·포맷 (예: \'aws\')'),
+            isNegative: z.boolean().optional().describe('cost 타입: 음수 표시 처리'),
             fields: z.array(z.string()).optional().describe('비율바 등에서 여러 필드'),
             label: z.object({
                 postfix: z.string().optional().describe('라벨 접미사'),
@@ -123,9 +128,6 @@ const defaultColDefSchema = z.object({
 });
 // ag-grid 기반 OpsnowCommonDataGrid 스키마 정의
 export const DataGridSchema = z.object({
-    totalPage: z.number().optional().describe('전체 페이지 수'),
-    initPageNum: z.number().optional().describe('초기 페이지 번호'),
-    dropdownSearchDefaultValue: z.string().optional().describe('드롭다운 검색 기본값'),
     gridOptions: gridOptionsSchema.optional().describe('ag-grid 옵션'),
     columnDefs: z.array(columnDefsSchema).describe("ag-grid 컬럼 정의").min(1),
     defaultColDef: defaultColDefSchema.optional().describe('ag-grid 기본 컬럼 옵션'),
@@ -153,11 +155,12 @@ export const DataGridSchema = z.object({
           setStatus(CommonConst.GRID_STATUS.ERROR)
         })
     }, [])`),
-    gridHeight: z.number().optional().describe('그리드 높이'),
+    gridHeight: z.number().optional().describe("고정 높이(px, 기본 483). gridOptions.domLayout을 지정하지 않았을 때만 적용 — domLayout에 값이 있으면 무시됨 ('normal'이면 그리드가 0px로 사라짐)"),
+    maxGridHeight: z.number().optional().describe("domLayout:'autoHeight'일 때 최대 높이(px, 헤더 42px 포함, 기본 600). 넘치면 본문 세로 스크롤. grid ≥2.0.6"),
+    unlimitedHeight: z.boolean().optional().describe("true면 autoHeight 높이 제한 해제(모든 행 펼침). 기본 false. 짧은 고정 목록에만 사용"),
     setClass: z.string().optional().describe('그리드 클래스명'),
-    localRowClass: z.string().optional().describe('로컬 행 클래스명'),
     pagination: z.boolean().optional().describe('페이지네이션 사용 여부 (true로 설정 시 내부적으로 opsnow-common-pagination 컴포넌트 사용)'),
-    paginationPageSize: z.number().optional().describe('페이지당 행 수'),
+    paginationPageSize: z.number().optional().describe('페이지당 행 수 (기본값: 10)'),
     textNoData: z.string().optional().describe('데이터 없음 텍스트'),
     noDataDescription: z.string().optional().describe('데이터 없음 설명'),
     textLoading: z.string().optional().describe('로딩 중 텍스트'),
@@ -166,25 +169,24 @@ export const DataGridSchema = z.object({
     filterSearchText: z.string().optional().describe('필터 검색 텍스트'),
     searchTextNoData: z.string().optional().describe('검색 결과 없음 텍스트'),
     searchTextNoDataDescription: z.string().optional().describe('검색 결과 없음 설명'),
-    pagingFromServer: z.boolean().optional().describe('서버 페이징 사용 여부'),
     pageSizeList: z.array(z.object({
         label: z.string().describe('페이지 사이즈 라벨'),
         value: z.number().describe('페이지 사이즈 값')
-    })).optional().describe('페이지 사이즈 리스트 (예: [{ label: "5", value: 5 }, { label: "10", value: 10 }])'),
+    })).optional().describe('페이지 사이즈 리스트 (기본값: 10/20/50, 예: [{ label: "5", value: 5 }, { label: "10", value: 10 }])'),
     placeholderText: z.string().optional().describe('플레이스홀더 텍스트'),
-    usedRowClass: z.boolean().optional().describe('행 클래스 사용 여부 (셀 클릭 이벤트 사용 시 필수: true)'),
+    usedRowClass: z.boolean().optional().describe('클릭 가능한 행 스타일(hover·커서) 적용 여부 — onCellClick이 있으면 자동 적용되므로 보통 지정 불필요'),
     usedSearch: z.boolean().optional().describe('검색창 사용 여부'),
     usedSearchAndDropdown: z.boolean().optional().describe('검색+드롭다운 동시 사용'),
     useOpsnowUs: z.boolean().optional().describe('Opsnow US 스타일 사용'),
     inTile: z.boolean().optional().describe('타일 내 그리드 여부'),
     noDataCustomComponent: z.any().optional().describe('커스텀 No Data 컴포넌트'),
-    rowModelType: z.string().optional().describe('행 모델 타입'),
+    rowModelType: z.enum(['clientSide', 'serverSide']).optional().describe("행 모델 타입 (기본값: 'clientSide')"),
     serverSideDatasource: z.record(z.any()).optional().describe('서버사이드 데이터소스'),
     cacheBlockSize: z.number().optional().describe('서버사이드 캐시 블록 크기'),
     usedMenuItem: z.boolean().optional().describe('메뉴 아이템 사용 여부'),
     showSelectedRowCount: z.boolean().optional().describe('선택 행 개수 표시'),
-    isAutoSizeAllColumns: z.boolean().optional().describe('모든 컬럼 자동 크기 조정'),
-    langCd: z.string().optional().describe('언어 코드'),
+    isAutoSizeAllColumns: z.boolean().optional().describe('모든 컬럼 자동 크기 조정. 모바일(≤767.95px)에서는 자동으로 true — 컬럼이 내용 폭에 맞춰지고, 컨테이너보다 넓으면 가로 스크롤이 생김 (flex/sizeColumnsToFit 전제 레이아웃은 모바일에서 달라질 수 있음)'),
+    langCd: z.string().optional().describe("언어 코드 (기본값: 'ko') — 보통 i18n.getLocale()"),
     useTreeDataDragDrop: z.boolean().optional().describe('트리 데이터 드래그 사용'),
     getDropTargetNode: z.string().optional().describe('드롭 타겟 노드 반환 함수(stringified)'),
     emitQuickFilterChange: z.boolean().optional().describe('빠른 필터 변경 이벤트 발생'),
@@ -201,6 +203,12 @@ export const DataGridSchema = z.object({
     onSetPage: z.string().optional().describe('페이지 변경 이벤트 핸들러(stringified)'),
     serverSideTotalPageSize: z.number().optional().describe('서버사이드 전체 페이지 수')
 });
+export const HeaderFilterSchema = z.object({
+    gridData: z.string().describe("AG Grid가 headerComponent에 넘기는 header params 변수명 (column, displayName, enableSorting, setSort, context) (필수)"),
+    textRight: z.boolean().optional().describe("헤더 텍스트 우측 정렬 (숫자 컬럼)"),
+    isUsedMenuFilter: z.boolean().optional().describe("헤더 필터 메뉴 사용 여부"),
+    children: z.string().optional().describe("헤더 텍스트 옆에 넣을 JSX (예: 툴팁 아이콘)"),
+});
 // DataGrid 컴포넌트 함수 - 배열 반환
 export function createDataGridComponent() {
     return [
@@ -242,18 +250,19 @@ export function createDataGridComponent() {
 
       ⚠️ defaultColDef에 wrapText, autoHeight가 없으면 텍스트가 넘칩니다!
 
-      **CRITICAL: 행 수가 많을 수 있으면 - 높이 분기 필수**
-      autoHeight(domLayout:'autoHeight')는 모든 행을 펼쳐서 그리드가 무한정 길어짐.
-      행 수가 가변적이거나 많아질 수 있으면 행 수 기준으로 분기:
+      **그리드 높이 정책 (grid ≥2.0.6) — 행 수로 분기하지 말 것**
+      - 기본: gridOptions.domLayout: 'autoHeight' 하나만. 행이 적으면 콘텐츠 높이에 맞추고,
+        maxGridHeight(기본 600px, 헤더 42px 포함)를 넘으면 본문에 세로 스크롤이 자동으로 생긴다.
+      - 상한 변경: maxGridHeight={800} / 상한 해제(모든 행 펼침): unlimitedHeight (짧은 고정 목록에만)
+      - 고정 높이: gridOptions에서 domLayout 키를 아예 빼고 gridHeight={N} (기본 483)
+      - ⚠️ domLayout: 'normal'을 명시하면 컨테이너 높이가 비워져 그리드가 0px로 사라진다 (gridHeight·부모 높이와 무관 — 브라우저 실측).
+        isScroll ? 'normal' : 'autoHeight' 같은 행 수 분기 패턴 금지.
+      - 상한은 헤더 1줄(42px) 기준이라 헤더가 여러 줄이면 그만큼 커지고, 페이지네이션 영역은 상한 밖이다.
+      - 모바일(≤767.95px)에서는 컬럼을 autoSizeAllColumns로 맞추므로 가로 스크롤이 생길 수 있다.
 
-      const ROW_LIMIT = 10;
-      const isScroll = rowData.length > ROW_LIMIT;
-      const gridOptions = {
-        // ... 다른 설정들
-        domLayout: isScroll ? 'normal' : 'autoHeight',  // 10행 이하: 콘텐츠 맞춤 / 초과: 고정+스크롤
-      };
-      // 10행 초과 시에만 고정 높이 부여 (autoHeight 셀은 가변이라 픽셀 고정값 사용)
-      <OpsnowCommonDataGrid gridOptions={gridOptions} gridHeight={isScroll ? 600 : undefined} />
+      const gridOptions = { /* ... */ domLayout: 'autoHeight' };
+      <OpsnowCommonDataGrid gridOptions={gridOptions} />                      // 최대 600px, 넘치면 스크롤
+      <OpsnowCommonDataGrid gridOptions={gridOptions} maxGridHeight={800} />  // 상한 변경
 
       **셀·행 단위 부분 로딩 (Partial Loading) — status로 하지 말 것**
       status={GRID_STATUS.LOADING}은 그리드 전체를 가립니다. "이 셀만 재계산 중", "선택한 행만 동기화 중" 같은 부분 로딩은
@@ -264,7 +273,8 @@ export function createDataGridComponent() {
       4. 인디케이터로 셀 콘텐츠를 치환하지 말고, 원래 콘텐츠를 visibility: hidden 으로 남기고 인디케이터를 position: absolute 로 겹친다 (autoHeight라 치환하면 행 높이가 바뀜)
       5. columnDefs/셀 렌더러는 useMemo/useCallback 으로 고정 — 매 렌더마다 새로 만들면 그리드가 통째로 다시 그려진다
       6. 선택 노드 수집: forEachNode + node.isSelected() (getSelectedNodes는 ref API에 없음). onSelectionChanged는 top-level prop (인자 = 선택 노드 배열)
-      ref API 요약: refreshCells / redrawRows / forEachNode / node.setDataValue(field, value) / downloadExcel / downloadCsv
+      ref API (gridRef.current.*, 26종): getColumnState, applyColumnState, setColumnDefs, setAutoGroupColumnDef, sizeColumnsToFit / setRowData, applyTransaction, getGridData, getDisplayedRowAtIndex, forEachNode, forEachNodeAfterFilter, refreshCells, redrawRows / setNodesSelected, checkBoxSelectAll, saveSelectionState, loadSelectionState, setSelectionState, clearSelectionState / updateFilter / downloadExcel, downloadCsv / getRowDropZoneParams, addRowDropZone / setServerSideDatasource, setServerSideFilterList (노드 값 변경은 node.setDataValue(field, value))
+      ⚠️ DataGrid는 AG Grid 옵션을 최상위 prop으로 받지 않습니다 (rowHeight, getRowId, context, onRowClicked 등) — 모두 gridOptions 안에 넣으세요.
       rowModelType: 'serverSide' 그리드는 AG Grid 내장 loadingCellRenderer를 쓰는 것이 맞습니다.
 
       **import:**
@@ -375,6 +385,24 @@ export function createDataGridComponent() {
                     ]
                 };
             }
-        }
+        },
+        {
+            name: "createHeaderFilter",
+            description: `HeaderFilter 컴포넌트 - DataGrid 컬럼 헤더에 정렬·필터 메뉴를 붙이는 커스텀 헤더
+      JSX로 직접 배치하지 않고 columnDefs의 headerComponent로 등록합니다. gridData에는 AG Grid가 넘기는 header params를 그대로 전달합니다.
+      예: { field: 'cost', headerComponent: (params) => <OpsnowCommonHeaderFilter gridData={params} textRight /> }
+
+      **import:**
+      \`\`\`javascript
+      import { useCommonComponents } from '@opsnow-common/opsnow-finops-common-ui-loader';
+      const { OpsnowCommonHeaderFilter } = useCommonComponents();
+      \`\`\``,
+            parameters: HeaderFilterSchema,
+            handler: async (args) => {
+                const { children, ...rest } = args;
+                const tag = jsxTag("OpsnowCommonHeaderFilter", jsxAttrs(rest, { exprKeys: ["gridData"] }), children);
+                return jsxResult(`const headerFilterColumn = {\n  field: 'fieldName',\n  headerComponent: (${args.gridData}) => (\n${tag}\n  ),\n}\n// columnDefs={[ ..., headerFilterColumn ]}`);
+            },
+        },
     ];
 }

package/build/components/opsnow-common-icons.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { jsxAttrs, jsxTag, jsxResult } from "./opsnow-common-jsx-helper.js";
 import { IconNamesMap, generateIconDescription } from "./data/icon-names.js";
 export const IconSchema = z.object({
     iconName: z.enum(Object.keys(IconNamesMap)).describe(generateIconDescription({ format: 'nested' })),
@@ -8,21 +9,20 @@ export const IconSchema = z.object({
     onClick: z.string().optional().describe("클릭 이벤트 핸들러 함수명 (HTMLAttributes 상속으로 span에 적용됨)"),
 });
 export const MuiIconSchema = z.object({
-    theme: z.string().optional().describe("테마명"),
+    theme: z.enum(["mixed-circle-line-legend", "mixed-stack-line-legend", "diagonal-legend"]).optional().describe("레전드 마커 모양 (범례용일 때만) — 아이콘 이름은 theme이 아니라 label"),
     hexColor: z.string().optional().describe("HEX 색상"),
     size: z.number().optional().default(24).describe("아이콘 크기(px)"),
     noCircle: z.boolean().optional().describe("원형 배경 없음"),
     alpha: z.number().optional().describe("투명도"),
-    color: z.string().optional().describe("MUI 색상"),
-    label: z.string().optional().describe("MUI 아이콘 이름")
+    color: z.enum(["primary", "secondary", "success", "error", "info", "warning", "inherit"]).optional().describe("MUI 색상"),
+    label: z.string().optional().describe("MUI(Material) 아이콘 이름 (예: 'close', 'menu') — 기본값 add_icon")
+});
+export const MarkersSchema = z.object({
+    theme: z.enum(["square", "line-graph", "line-trend", "line-dashed", "mixed-line-stack"]).optional().describe("마커 모양 — square(사각), line-graph/line-trend/line-dashed(선), mixed-line-stack(선+막대)"),
+    hexColor: z.string().optional().describe("마커 색상 HEX (미지정 시 primary.main)"),
+    lineAlpha: z.number().optional().describe("선 부분 투명도 (0~1)"),
+    shapesAlpha: z.number().optional().describe("도형 부분 투명도 (0~1). mixed-line-stack이면 0.3으로 고정"),
 });
-// export const MarkersSchema = z.object({
-//   theme: z.string().describe("마커 테마"),
-//   hexColor: z.string().optional().describe("HEX 색상"),
-//   lineAlpha: z.number().optional().describe("선 투명도"),
-//   size: z.number().optional().default(24).describe("마커 크기(px)")
-// });
-// export type MarkersProps = z.infer<typeof MarkersSchema>;
 export function createIconsComponent() {
     return [
         {
@@ -103,34 +103,18 @@ export function createIconsComponent() {
                 };
             }
         },
-        // {
-        //   name: "createMarkers",
-        //   description: `마커 컴포넌트 - 그래프/차트용 심볼
-        //   - 그래프, 차트 등에서 포인트/마커로 활용
-        //   - theme(마커 테마), hexColor, lineAlpha, size 등 다양한 옵션 지원
-        //   - 아이콘은 useOpsnowCommonIcons 훅을 통해 생성해야 합니다.
-        //   **import 예시:**
-        //   \`\`\`javascript
-        //   import { useOpsnowCommonIcons } from '@opsnow-common/opsnow-finops-common-ui-loader';
-        //   const { OpsnowCommonMarkers } = useOpsnowCommonIcons();
-        //   \`\`\``,
-        //   parameters: MarkersSchema,
-        //   handler: async (args: MarkersProps) => {
-        //     const props: string[] = [];
-        //     props.push(`theme="${args.theme}"`);
-        //     if (args.hexColor) props.push(`hexColor="${args.hexColor}"`);
-        //     if (args.lineAlpha) props.push(`lineAlpha={${args.lineAlpha}}`);
-        //     if (args.size) props.push(`size={${args.size}}`);
-        //     const code = `<OpsnowCommonMarkers ${props.join(" ")} />`;
-        //     return {
-        //       content: [
-        //         {
-        //           type: "text" as const,
-        //           text: `\`\`\`jsx\n${code}\n\`\`\``
-        //         }
-        //       ]
-        //     };
-        //   }
-        // }
+        {
+            name: "createMarkers",
+            description: `Markers 컴포넌트 - 차트 범례·커스텀 레전드에 쓰는 시리즈 마커 (선/도형 조합)
+      크기는 고정이라 size prop이 없습니다.
+
+      **import:**
+      \`\`\`javascript
+      import { useOpsnowCommonIcons } from '@opsnow-common/opsnow-finops-common-ui-loader';
+      const { OpsnowCommonMarkers } = useOpsnowCommonIcons();
+      \`\`\``,
+            parameters: MarkersSchema,
+            handler: async (args) => jsxResult(jsxTag("OpsnowCommonMarkers", jsxAttrs(args))),
+        },
     ];
 }

package/build/components/opsnow-common-jsx-helper.js

@@ -0,0 +1,36 @@
+// 생성기 공용: 툴 입력(args)을 JSX 속성 문자열로 변환
+// - exprKeys에 든 키(상태 변수명·함수명·JSX)는 {값}으로, 그 외 문자열은 "값"으로 출력
+// - true → 속성만, false → {false}, 숫자 → {n}, 객체/배열 → {JSON}
+// - skipKeys는 출력하지 않음 (생성기 입력 전용 키 등)
+export function jsxAttrs(args, opts = {}) {
+    const exprKeys = new Set(opts.exprKeys ?? []);
+    const skipKeys = new Set(opts.skipKeys ?? []);
+    const out = [];
+    for (const [k, v] of Object.entries(args)) {
+        if (v === undefined || v === null || skipKeys.has(k))
+            continue;
+        if (typeof v === "string")
+            out.push(exprKeys.has(k) ? `${k}={${v}}` : `${k}="${v}"`);
+        else if (typeof v === "boolean")
+            out.push(v ? k : `${k}={false}`);
+        else if (typeof v === "number")
+            out.push(`${k}={${v}}`);
+        else
+            out.push(`${k}={${JSON.stringify(v)}}`);
+    }
+    return out;
+}
+// 여러 줄 JSX 태그 조립 (children 없으면 self-closing)
+export function jsxTag(tag, attrs, children) {
+    const open = attrs.length ? `<${tag}\n  ${attrs.join("\n  ")}\n` : `<${tag}`;
+    if (!children)
+        return attrs.length ? `${open}/>` : `${open} />`;
+    return `${attrs.length ? open : open + " "}>\n  ${children}\n</${tag}>`.replace(`<${tag} >`, `<${tag}>`);
+}
+// JSX 표현식 값: 문자열은 변수명·함수·JSX로 보고 그대로, 그 외(객체·배열·숫자·불리언)는 JSON 리터럴로
+export function jsxExpr(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+export function jsxResult(code) {
+    return { content: [{ type: "text", text: `\`\`\`jsx\n${code}\n\`\`\`` }] };
+}

package/build/components/opsnow-common-layout.js

@@ -1,21 +1,19 @@
 import { z } from "zod";
+import { jsxAttrs, jsxTag, jsxResult } from "./opsnow-common-jsx-helper.js";
+// MUI 9 Grid size 값: 컬럼 수(1~12) | 'auto'(콘텐츠 폭) | 'grow'(남은 폭 채움)
+const GridSizeValue = z.union([z.number(), z.enum(["auto", "grow"])]);
+const GridBreakpointSize = z.object({
+    xs: GridSizeValue.optional(),
+    sm: GridSizeValue.optional(),
+    md: GridSizeValue.optional(),
+    lg: GridSizeValue.optional(),
+    xl: GridSizeValue.optional(),
+});
 const GridLayoutSchema = z.object({
     items: z.array(z.string()).describe("렌더링할 JSX 문자열 배열 (각 항목은 컴포넌트 호출 코드)"),
-    layout: z.array(z.object({
-        xs: z.number().optional(),
-        sm: z.number().optional(),
-        md: z.number().optional(),
-        lg: z.number().optional(),
-        xl: z.number().optional(),
-    }).partial()).optional().describe("각 항목별 브레이크포인트 레이아웃 배열"),
-    defaultLayout: z.object({
-        xs: z.number().optional(),
-        sm: z.number().optional(),
-        md: z.number().optional(),
-        lg: z.number().optional(),
-        xl: z.number().optional(),
-    }).optional().describe("기본 브레이크포인트 레이아웃"),
-    spacing: z.number().optional().describe("Grid 간격 (MUI spacing 단위)"),
+    layout: z.array(GridBreakpointSize.partial()).optional().describe("각 항목별 브레이크포인트 size 배열 (MUI 9 Grid size prop으로 출력, 예: { xs: 12, md: 6 })"),
+    defaultLayout: GridBreakpointSize.optional().describe("기본 브레이크포인트 size (기본 { xs: 'grow' })"),
+    spacing: z.number().optional().describe("Grid 간격 (MUI spacing 단위). 미지정 시 섹션 간격 토큰(sectionGap 24px) 사용"),
     tileProps: z.record(z.any()).optional().describe("OpsnowCommonTile에 전달할 추가 props"),
 });
 const MegaFilterSchema = z.object({
@@ -23,10 +21,12 @@ const MegaFilterSchema = z.object({
     vendors: z.string().optional().describe("벤더 옵션 배열 변수명"),
     selectedVendor: z.string().optional().describe("선택된 벤더 상태 변수명"),
     onVendorChange: z.string().optional().describe("벤더 변경 이벤트 핸들러"),
-    onFilterChange: z.string().optional().describe("필터 변경 이벤트 핸들러"),
+    onFilterChange: z.string().describe("필터 변경 이벤트 핸들러 (필수)"),
     selectedDateRange: z.string().optional().describe("선택된 날짜 범위 상태 변수명"),
     onDateRangeChange: z.string().optional().describe("날짜 범위 변경 이벤트 핸들러"),
-    locale: z.enum(["en", "ko"]).optional().describe("로케일 설정"),
+    locale: z.enum(["en", "ko", "ja", "zh"]).optional().describe("로케일 설정"),
+    chipStateOptions: z.string().optional().describe("필터 칩 상태 옵션 배열 변수명"),
+    filterCountText: z.string().optional().describe("선택 개수 텍스트 함수명 ((selected, total) => string)"),
     title: z.string().optional().describe("필터 제목"),
     clearAllText: z.string().optional().describe("전체 초기화 버튼 텍스트"),
     clearText: z.string().optional().describe("개별 초기화 버튼 텍스트"),
@@ -36,6 +36,17 @@ const MegaFilterSchema = z.object({
     noItemsText: z.string().optional().describe("검색 결과 없음 텍스트"),
     addText: z.string().optional().describe("개별 필터 추가 버튼 텍스트"),
 });
+export const TileSchema = z.object({
+    size: z.union([z.number(), z.enum(["auto", "grow"])]).optional().describe("flex 크기 — 'grow'(남은 폭 채움, 기본값) | 'auto'(콘텐츠 폭) | 숫자(flex 비율)"),
+    theme: z.enum(["selectable", "gray", "white", "blue", "dash", "special"]).optional().describe("타일 테마 (dash = 점선 테두리)"),
+    borderColor: z.string().optional().describe("테두리 색상"),
+    borderStyle: z.string().optional().describe("테두리 스타일 (기본값: solid)"),
+    height: z.string().optional().describe("높이 (CSS 값, 예: '240px')"),
+    className: z.string().optional().describe("클래스명 — Tile은 sx를 받지 않으므로 스타일은 className으로"),
+    onClick: z.string().optional().describe("클릭 핸들러 함수명 (selectable 테마와 함께)"),
+    header: z.string().optional().describe("Tile.Header 안에 넣을 JSX (생성기 입력 — <OpsnowCommonTile.Header>로 출력)"),
+    content: z.string().optional().describe("Tile.Content 안에 넣을 JSX (생성기 입력 — <OpsnowCommonTile.Content>로 출력)"),
+});
 export function createGridLayoutComponent() {
     return [
         {
@@ -44,7 +55,8 @@ export function createGridLayoutComponent() {
 
         **간격 규칙 (px 하드코딩 금지, 색상 토큰처럼 theme.commonSpacing 참조):**
         - 페이지/그리드 컨테이너 패딩: theme.commonSpacing.pagePadding (24px)
-        - 섹션(카드 그룹) 사이 간격: theme.commonSpacing.sectionGap (24px) — Grid container의 gap
+        - 섹션(카드 그룹) 사이 간격: sectionGap (24px) — Grid container의 spacing="var(--opsnow-spacing-section-gap)" (sx gap 금지: size 폭 계산에 안 들어가 줄바꿈이 깨짐)
+        - MUI 9 Grid: <Grid size={{ xs: 12, md: 6 }}> (item/xs/md prop 금지)
         - 카드(Box) 내부 패딩: theme.commonSpacing.cardPadding ('16px 20px')
         - 카드 내부 요소 간 간격: theme.commonSpacing.cardGap (16px)
         - 값이 여러 개이므로 sx는 콜백 형태로: sx={theme => ({ padding: theme.commonSpacing.pagePadding, gap: theme.commonSpacing.sectionGap })}
@@ -56,13 +68,13 @@ export function createGridLayoutComponent() {
         `,
             parameters: GridLayoutSchema,
             handler: async (args) => {
-                const { items, layout = [], defaultLayout = { xs: true }, spacing = 2, } = args;
+                const { items, layout = [], defaultLayout = { xs: 'grow' }, spacing, } = args;
                 const gridItems = items.map((item, i) => {
                     const bp = layout[i] || defaultLayout;
-                    const bpProps = Object.entries(bp)
-                        .map(([k, v]) => `${k}={${v}}`)
-                        .join(" ");
-                    return `  <Grid item ${bpProps} key={${i}}>` +
+                    const sizeObj = Object.entries(bp)
+                        .map(([k, v]) => `${k}: ${typeof v === "string" ? `'${v}'` : v}`)
+                        .join(", ");
+                    return `  <Grid size={{ ${sizeObj} }} key={${i}}>` +
                         `\n    <Box sx={theme => ({` +
                         `\n      border: '1px solid #ddd',` +
                         `\n      borderRadius: '12px',` +
@@ -77,7 +89,8 @@ export function createGridLayoutComponent() {
                         `\n  </Grid>`;
                 }).join("\n");
                 const code = [
-                    `<Grid container wrap="nowrap" spacing={0} sx={theme => ({ padding: theme.commonSpacing.pagePadding, gap: theme.commonSpacing.sectionGap })}>`,
+                    // 간격은 sx gap이 아니라 spacing으로 (gap은 size 폭 계산에 안 들어감)
+                    `<Grid container spacing={${spacing !== undefined ? spacing : '"var(--opsnow-spacing-section-gap)"'}} sx={theme => ({ padding: theme.commonSpacing.pagePadding })}>`,
                     gridItems,
                     `</Grid>`,
                 ].join("\n");
@@ -112,6 +125,10 @@ export function createGridLayoutComponent() {
                     props.push(`onVendorChange={${args.onVendorChange}}`);
                 if (args.onFilterChange)
                     props.push(`onFilterChange={${args.onFilterChange}}`);
+                if (args.chipStateOptions)
+                    props.push(`chipStateOptions={${args.chipStateOptions}}`);
+                if (args.filterCountText)
+                    props.push(`filterCountText={${args.filterCountText}}`);
                 if (args.selectedDateRange)
                     props.push(`selectedDateRange={${args.selectedDateRange}}`);
                 if (args.onDateRangeChange)
@@ -144,6 +161,30 @@ export function createGridLayoutComponent() {
                     ]
                 };
             },
-        }
+        },
+        {
+            name: "createTile",
+            description: `Tile 컴포넌트 - 카드형 컨테이너 (헤더 + 본문)
+      <OpsnowCommonTile>
+        <OpsnowCommonTile.Header>제목</OpsnowCommonTile.Header>   // props: paddingX, paddingY (기본 16), borderColor
+        <OpsnowCommonTile.Content>본문</OpsnowCommonTile.Content> // props: paddingX, paddingY (기본 16)
+      </OpsnowCommonTile>
+      ⚠️ Tile은 sx를 받지 않습니다 (rest props 미전달) — 스타일은 className 또는 감싸는 Box의 sx로.
+      ⚠️ layout 패키지는 로더 의존성이 아니라 앱 package.json에 @opsnow-common/opsnow-common-layout@^2 를 직접 설치해야 합니다.
+
+      **import:**
+      \`\`\`javascript
+      import { OpsnowCommonTile } from '@opsnow-common/opsnow-common-layout';
+      \`\`\``,
+            parameters: TileSchema,
+            handler: async (args) => {
+                const { header, content, ...rest } = args;
+                const children = [
+                    header ? `<OpsnowCommonTile.Header>${header}</OpsnowCommonTile.Header>` : "",
+                    `<OpsnowCommonTile.Content>${content ?? ""}</OpsnowCommonTile.Content>`,
+                ].filter(Boolean).join("\n  ");
+                return jsxResult(jsxTag("OpsnowCommonTile", jsxAttrs(rest, { exprKeys: ["onClick"] }), children));
+            },
+        },
     ];
 }

package/build/components/opsnow-common-notification.js

@@ -11,6 +11,7 @@ export const NotificationSchema = z.object({
         "warning",
         "info",
     ])
+        .optional()
         .describe(`알림 타입(색상/스타일):
     - "info": 회색/ 흰색 배경 + 배경과 동일한 색상의 아이콘 + 컬러 라인 없음
     - "infoSuccess": 흰/회색 배경 + 왼쪽 초록 컬러 라인 + 초록 아이콘(placement: page 전용)
@@ -32,7 +33,7 @@ export const NotificationSchema = z.object({
   - "card": 배경색 자체가 타입(success/ error/ warning/ info)에 따라 컬러풀하게 채워짐. 
   ※ infoSuccess/infoWarning/infoError는 "page"에서만 사용 가능(배경 흰색, 컬러 라인 색상만 변함).
   ※ "card"는 배경색이 타입에 따라 바뀌며, infoSuccess/infoWarning/infoError는 지원하지 않음.`),
-    closable: z.boolean().optional().describe("수동 닫기 가능 여부"),
+    closable: z.boolean().optional().describe("수동 닫기 가능 여부 — 생성기 입력 (실제 prop 아님, 생성 코드에서 onClose + 상태로 변환)"),
     bgWhite: z
         .boolean()
         .default(false)
@@ -42,7 +43,7 @@ export const NotificationSchema = z.object({
     isCustom: z
         .boolean()
         .default(false)
-        .describe("커스텀 action 버튼 사용 여부 - action랑 같이 사용, default 버튼이 아닌 custom시 사용"),
+        .describe("커스텀 action 버튼 사용 여부 - action랑 같이 사용 — 생성기 입력 (실제 prop 아님, 생성 코드에서 customActionBtn으로 변환)"),
 }).describe("알림 컴포넌트 - 박스 형태로 알림을 제공하는 컴포넌트. 알림 컴포넌트 내에 버튼 사용 시 (action, isCustom 옵션 사용 시) 반드시 버튼 컴포넌트 동시 호출 하여 action에 OpsnowCommonButton 컴포넌트를 string으로 전달");
 // Notification 컴포넌트 함수 - 배열 반환
 export function createNotificationComponent() {

package/build/components/opsnow-common-pagination.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 // Pagination 컴포넌트 관련 스키마 정의
 export const PaginationSchema = z.object({
-    page: z.number().describe("현재 페이지 번호"),
+    page: z.number().optional().describe("현재 페이지 번호 (기본값: 1)"),
     rowsPerPage: z.number().optional().default(10).describe("페이지당 항목 수"),
     size: z
         .enum(["medium", "small", "large"])
@@ -18,7 +18,7 @@ export const PaginationSchema = z.object({
         .string()
         .optional()
         .describe("rowsPerPage가 변경될 때 호출되는 핸들러 함수명 - 함수명만 필요함"),
-    isLocale: z.boolean().default(true).describe("locale(언어) 설정 여부"),
+    isLocale: z.boolean().default(true).describe("locale(언어) 설정 여부 — 생성기 입력 (실제 prop 아님, true면 locale={i18n.getLocale()}로 출력. 실제 prop locale 기본값은 'en')"),
     onChangePageNum: z
         .string()
         .optional()
@@ -26,7 +26,7 @@ export const PaginationSchema = z.object({
     onChangePageSize: z
         .string()
         .optional()
-        .describe("페이지당 항목수 변경(pageSize) 및 현재 페이지(pageNum) 변경되었을때 핸들러 함수. 함수 내부 코드(문자열)로 전달하세요. 예시: console.log('페이지당 항목 수가',pageSize,'로 변경되고, 현재 페이지는',pageNum,'입니다.')"),
+        .describe("페이지당 항목수 변경(pageSize) 및 현재 페이지(pageNum) 변경되었을때 핸들러 함수. 콜백 인자 순서는 (pageNum, pageSize). 함수 내부 코드(문자열)로 전달하세요. 예시: console.log('페이지당 항목 수가',pageSize,'로 변경되고, 현재 페이지는',pageNum,'입니다.')"),
     onNext: z
         .string()
         .optional()
@@ -130,7 +130,7 @@ export function createPaginationComponent() {
           }}`);
                 }
                 if (args.onChangePageSize) {
-                    props.push(`onChangePageSize={(pageSize, pageNum) => {
+                    props.push(`onChangePageSize={(pageNum, pageSize) => {
             ${args.onChangePageSize}
           }}`);
                 }

package/build/components/opsnow-common-popup.js

@@ -2,19 +2,20 @@ import { z } from "zod";
 // Popup 컴포넌트 관련 스키마 정의
 export const PopupSchema = z.object({
     title: z.string().describe("팝업 제목"),
-    visible: z.boolean().optional().default(false).describe("팝업 표시 여부"),
+    visible: z.boolean().optional().default(false).describe("팝업 표시 여부 — 생성기 입력. 실제 prop은 open (생성 코드에서 open={...}으로 출력)"),
     closable: z.boolean().optional().default(true).describe("닫기 버튼 표시 여부 - false 시 생성 코드에서 hideHeaderClose로 변환 출력됨 (lib에 closable prop 없음). 크기 조절은 width/height 대신 size(sm/md/lg) 사용"),
-    disableEscapeKeyDown: z.boolean().optional().default(false).describe('ESC 키 입력으로 닫기 방지 여부'),
     type: z.enum(['wing', 'standard', 'bottom']).optional().default('standard').describe("팝업 타입"),
-    size: z.enum(['sm', 'md', 'lg']).optional().describe('팝업 크기 (sm, md, lg)'),
+    size: z.enum(['sm', 'md', 'lg']).optional().describe("팝업 크기 (sm, md, lg) — 기본값: wing 'md', standard 'sm'"),
     confirmButton: z.object({
-        color: z.string().describe('확인 버튼 색상'),
-        variant: z.string().describe('확인 버튼 변형'),
-    }).optional().describe('확인 버튼 설정'),
+        text: z.string().optional().describe('확인 버튼 텍스트'),
+        variant: z.enum(['text', 'outlined', 'contained']).optional().describe('확인 버튼 변형'),
+        disabled: z.boolean().optional().describe('확인 버튼 비활성화 여부'),
+        color: z.string().optional().describe('확인 버튼 색상'),
+    }).optional().describe('확인 버튼 설정 객체 - { text, variant, disabled, color }'),
     onConfirm: z.string().optional().describe('확인(Confirm) 버튼 클릭 시 실행할 함수명 (() => void 타입) - 예시: handleConfirm'),
     onAction: z.string().optional().describe('액션(Action) 버튼 클릭 시 실행할 함수명 (() => void 타입) - 예시: handleAction'),
     useSpecialTitle: z.boolean().optional().describe('특수 타이틀 스타일 사용 여부 (boolean, 기본값 없음)'),
-    useFooterCancelBtn: z.boolean().optional().describe('푸터에 취소 버튼 표시 여부 (boolean)'),
+    useFooterCancelBtn: z.boolean().optional().describe('푸터에 취소 버튼 표시 여부 (boolean, 기본값: true — 숨기려면 false)'),
     useFooterActionBtn: z.boolean().optional().describe('푸터에 액션 버튼 표시 여부 (boolean)'),
     cancelButton: z.object({
         text: z.string().optional().describe('취소 버튼 텍스트'),
@@ -50,20 +51,20 @@ export function createPopupComponent() {
             parameters: PopupSchema,
             handler: async (args) => {
                 // <OpsnowCommonPopup ...> 코드만 동적으로 생성
-                const { title = 'Example Popup', visible = false, closable = true, disableEscapeKeyDown = false, size, confirmButton, onConfirm, onAction, useSpecialTitle, useFooterCancelBtn, useFooterActionBtn, cancelButton, actionButton, hideHeaderClose, hideFooter, useCustomHeader = false, useCustomFooter = false, headerContent, footerContent, type = 'standard', } = args;
+                const { title = 'Example Popup', visible = false, closable = true, size, confirmButton, onConfirm, onAction, useSpecialTitle, useFooterCancelBtn, useFooterActionBtn, cancelButton, actionButton, hideHeaderClose, hideFooter, useCustomHeader = false, useCustomFooter = false, headerContent, footerContent, type = 'standard', } = args;
                 // prop 문자열 생성
                 const propStr = [
                     `title=\"${title}\"`,
                     `open={${visible}}`,
                     `onClose={handleClose}`,
-                    disableEscapeKeyDown ? 'disableEscapeKeyDown' : '',
                     `type=\"${type}\"`,
-                    `size=\"${size}\"`,
+                    size ? `size=\"${size}\"` : '',
                     confirmButton ? `confirmButton={${JSON.stringify(confirmButton)}}` : '',
                     onConfirm ? `onConfirm={${onConfirm}}` : '',
                     onAction ? `onAction={${onAction}}` : '',
                     useSpecialTitle ? 'useSpecialTitle' : '',
-                    useFooterCancelBtn ? 'useFooterCancelBtn' : '',
+                    // useFooterCancelBtn은 런타임 기본값이 true → false일 때만 명시
+                    useFooterCancelBtn === false ? 'useFooterCancelBtn={false}' : '',
                     useFooterActionBtn ? 'useFooterActionBtn' : '',
                     cancelButton ? `cancelButton={${JSON.stringify(cancelButton)}}` : '',
                     actionButton ? `actionButton={${JSON.stringify(actionButton)}}` : '',