@opsnow-mcp/opsnow-mcp-common-ui-server 1.0.28 → 1.0.29

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

@@ -6,6 +6,7 @@ import { TooltipExamples } from "./examples/opsnow-common-tooltip-examples-data.
 import { CoachMarkExamples } from "./examples/opsnow-common-coach-mark-examples-data.js";
 import { DataGridExamples } from "./examples/opsnow-common-grid-examples-data.js";
 import { PopupExamples } from "./examples/opsnow-common-popup-examples-data.js";
+import { ToastPopupExamples } from "./examples/opsnow-common-toast-popup-examples-data.js";
 import { StepperExamples } from "./examples/opsnow-common-stepper-examples-data.js";
 import { StorageExamples } from "./examples/opsnow-common-storage-examples-data.js";
 import { SelectExamples } from "./examples/opsnow-common-select-examples-data.js";
@@ -19,7 +20,7 @@ import { GridLayoutExamples, MegaFilterExamples } from "./examples/opsnow-common
 import { TypographyExamples } from "./examples/opsnow-common-typography-examples-data.js";
 import { AutocompleteExamples } from "./examples/opsnow-common-select-examples-data.js";
 import { z } from "zod";
-const EXAMPLES_MAP = {
+export const EXAMPLES_MAP = {
     Button: ButtonExamples,
     Badge: BadgeExamples,
     Textarea: TextareaExamples,
@@ -51,6 +52,7 @@ const EXAMPLES_MAP = {
     CoachMark: CoachMarkExamples,
     DataGrid: DataGridExamples,
     Popup: PopupExamples,
+    ToastPopup: ToastPopupExamples,
     Stepper: StepperExamples,
     Storage: StorageExamples,
     Select: SelectExamples,
@@ -65,48 +67,130 @@ const EXAMPLES_MAP = {
     Typography: TypographyExamples,
     Autocomplete: AutocompleteExamples,
 };
+// ============= 토큰 절감: 대형 예제는 목록 모드 =============
+// 예제 전문 합계가 이 바이트를 넘으면 제목 목록을 먼저 반환 (keyword로 필요한 것만 조회)
+// 크기는 예제 개수가 아니라 코드 분량이 좌우하므로 바이트 기준 (HeatmapChart: 4개=17KB)
+const FULL_RESPONSE_BYTES = 12_000;
+// 목록 모드에서도 항상 전문으로 포함할 규칙 필수 예제 (제목 부분 일치)
+// DataGrid: 서버 instructions가 이름까지 지목하는 슬롯/페이지네이션 규칙 예제
+// (build-skill.ts가 스킬 examples 분할 시에도 사용)
+export const PRIORITY_EXAMPLES = {
+    DataGrid: ["Search + Pagination", "Insert Button Inside the Common Grid Search Section"],
+};
+// 'data-grid', 'DATAGRID' 등도 매칭되도록 정규화
+function normalize(s) {
+    return s.toLowerCase().replace(/[-_\s]/g, "");
+}
+function resolveUiType(uiType) {
+    const target = normalize(uiType);
+    return Object.keys(EXAMPLES_MAP).find(k => normalize(k) === target);
+}
+function asCall(uiType, keyword) {
+    return keyword
+        ? `getUIExamples({ uiType: "${uiType}", keyword: "${keyword}" })`
+        : `getUIExamples({ uiType: "${uiType}" })`;
+}
+function sizeOf(examples) {
+    return examples.reduce((a, e) => a + e.title.length + e.code.length + e.description.length + (e.code_props_usage?.length ?? 0), 0);
+}
+// 기존 응답 포맷 유지 (예제 1개당 content 항목 1개)
+function exampleToContent(example) {
+    return {
+        type: "text",
+        text: `**${example.title}** 예제:\n` +
+            "```jsx\n" +
+            `${example.code}\n` +
+            "```\n" +
+            `${example.code_props_usage ? `\n**속성 사용 예제:**\n\`\`\`jsx\n${example.code_props_usage}\n\`\`\`\n` : ''}` +
+            `${example.description}`,
+    };
+}
+// 목록 모드: 규칙 필수 예제는 전문 + 나머지는 제목 목록 + 복붙 가능한 재호출 예시
+function buildListResponse(resolvedType, examples, header) {
+    const priorityTitles = PRIORITY_EXAMPLES[resolvedType] ?? [];
+    const priority = examples.filter(ex => priorityTitles.some(t => ex.title.includes(t)));
+    const rest = examples.filter(ex => !priority.includes(ex));
+    const lines = rest.map((ex, i) => `${i + 1}. ${ex.title} — ${ex.description.split('\n')[0].slice(0, 80)}`);
+    const firstWord = rest[0]?.title.split(/[\s-]/)[0] || "검색어";
+    let text = `${header ? header + '\n\n' : ''}`;
+    text += `'${resolvedType}' 예제 ${examples.length}개 중 ${priority.length > 0 ? `필수 예제 ${priority.length}개는 아래 전문으로 포함했고, ` : ''}나머지는 제목 목록입니다:\n\n`;
+    text += lines.join('\n');
+    text += `\n\n---\n필요한 예제를 keyword로 조회하세요 (제목/설명/코드 내용 부분 일치). 호출 예시:\n`;
+    text += `${asCall(resolvedType, firstWord)}\n`;
+    text += `전체 예제가 모두 필요하면: ${asCall(resolvedType, "*")}`;
+    return {
+        content: [
+            ...(priority.length > 0 ? priority.map(exampleToContent) : []),
+            { type: "text", text },
+        ],
+    };
+}
 export const UIExamplesSchema = z.object({
     uiType: z
-        .enum(Object.keys(EXAMPLES_MAP))
-        .describe(`UI 컴포넌트 예제명 (예: 'Button', 'Icon') 호출 가능한 예제 항목: ${Object.keys(EXAMPLES_MAP).join(", ")}`)
+        .string()
+        .describe(`UI 컴포넌트 예제명 (예: 'Button', 'Icon') 호출 가능한 예제 항목: ${Object.keys(EXAMPLES_MAP).join(", ")}`),
+    keyword: z
+        .string()
+        .optional()
+        .describe("예제 제목/설명/코드에서 검색할 키워드 (부분 일치, 대소문자 무시). 예제가 큰 컴포넌트에서 특정 패턴만 조회할 때 사용. '*'를 넣으면 전체 예제 반환"),
 });
 export function createCommonExamplesComponent() {
     return [
         {
             name: "getUIExamples",
-            description: `OpsNow 공통 UI 컴포넌트 예제 목록을 반환합니다.
-uiType: string (예: 'Button', 'Icon')
-호출 가능한 예제 항목: ${Object.keys(EXAMPLES_MAP).join(', ')}
-uiType은 필수값입니다.`,
+            description: `OpsNow 공통 UI 컴포넌트 예제를 반환합니다.
+uiType: string (예: 'Button', 'Icon') - 필수
+keyword: string - 선택. 예제 분량이 큰 컴포넌트는 핵심 예제 전문 + 제목 목록이 먼저 반환되며, 목록에서 고른 키워드로 다시 호출하면 해당 예제 전문을 받습니다. '*'는 전체 반환.
+호출 가능한 예제 항목: ${Object.keys(EXAMPLES_MAP).join(', ')}`,
             parameters: UIExamplesSchema,
             handler: async (args) => {
-                // 허용된 key만 있는지 검사
-                const allowedKeys = ["uiType"];
-                const extraKeys = Object.keys(args).filter(k => !allowedKeys.includes(k));
-                if (extraKeys.length > 0) {
-                    return { content: [], error: `허용되지 않은 파라미터가 포함되어 있습니다: ${extraKeys.join(", ")}` };
-                }
                 const type = args.uiType;
                 if (!type) {
-                    return { content: [] };
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `uiType은 필수입니다. 호출 예시: ${asCall("DataGrid")}\n사용 가능: ${Object.keys(EXAMPLES_MAP).join(", ")}`,
+                            }],
+                    };
+                }
+                // 1. 정규화 매칭 ('datagrid', 'data-grid' → 'DataGrid')
+                const resolvedType = resolveUiType(type);
+                // 2. 매칭 실패 → 빈 응답 대신 복붙 가능한 대안 호출문 반환
+                if (!resolvedType) {
+                    const target = normalize(type);
+                    const candidates = Object.keys(EXAMPLES_MAP).filter(k => normalize(k).includes(target) || target.includes(normalize(k)));
+                    const listed = (candidates.length > 0 ? candidates : Object.keys(EXAMPLES_MAP))
+                        .map(k => asCall(k))
+                        .join('\n');
+                    const intro = candidates.length > 0
+                        ? `'${type}' 예제를 찾을 수 없습니다. 아래 중 하나로 다시 호출하세요:`
+                        : `'${type}' 예제를 찾을 수 없습니다. 사용 가능한 전체 목록입니다:`;
+                    return { content: [{ type: "text", text: `${intro}\n${listed}` }] };
                 }
-                // 단일 예제만 반환
-                const result = [];
-                const examples = EXAMPLES_MAP[type];
-                if (examples) {
-                    for (const example of examples) {
-                        result.push({
-                            type: "text",
-                            text: `**${example.title}** 예제:\n` +
-                                "```jsx\n" +
-                                `${example.code}\n` +
-                                "```\n" +
-                                `${'code_props_usage' in example && example.code_props_usage ? `\n**속성 사용 예제:**\n\`\`\`jsx\n${example.code_props_usage}\n\`\`\`\n` : ''}` +
-                                `${example.description}`,
-                        });
+                const examples = EXAMPLES_MAP[resolvedType];
+                const keyword = args.keyword?.trim();
+                // 3. keyword 있음 → 필터링해서 전문 반환 ('*'는 전체)
+                if (keyword) {
+                    if (keyword === "*") {
+                        return { content: examples.map(exampleToContent) };
                     }
+                    const kw = keyword.toLowerCase();
+                    // 1차: 제목/설명 매칭, 2차: 코드 내용 매칭 (기술 용어로 찍는 경우 대응)
+                    let matched = examples.filter(ex => ex.title.toLowerCase().includes(kw) || ex.description.toLowerCase().includes(kw));
+                    if (matched.length === 0) {
+                        matched = examples.filter(ex => ex.code.toLowerCase().includes(kw) || (ex.code_props_usage ?? "").toLowerCase().includes(kw));
+                    }
+                    if (matched.length > 0) {
+                        return { content: matched.map(exampleToContent) };
+                    }
+                    // 매칭 0건 → 빈 응답 금지, 목록으로 폴백
+                    return buildListResponse(resolvedType, examples, `'${keyword}'와 일치하는 예제가 없습니다.`);
+                }
+                // 4. keyword 없음 → 예제 분량에 따라 전문/목록 분기
+                if (sizeOf(examples) <= FULL_RESPONSE_BYTES) {
+                    return { content: examples.map(exampleToContent) };
                 }
-                return { content: result };
+                return buildListResponse(resolvedType, examples);
             }
         }
     ];

package/build/components/opsnow-common-file-upload.js

@@ -13,6 +13,7 @@ export const FileUploaderSchema = z.object({
     loadingText: z.string().optional().describe("로딩 텍스트"),
     browseText: z.string().optional().describe("찾아보기 버튼 텍스트"),
     placeholder: z.string().optional().describe("플레이스홀더 텍스트"),
+    dropPlaceholder: z.string().optional().describe("파일을 드래그하여 업로드 영역 위로 올렸을 때 표시되는 안내 텍스트 (string). 미지정 시 라이브러리 기본 문구 사용"),
     onChange: z.string().optional().describe("onChange 핸들러 함수명"),
 });
 // FileUploader MCP 툴 함수 - Stepper MCP 툴 구조 참고

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

@@ -40,6 +40,8 @@ export const SwitchSchema = z.object({
     color: z.enum(["primary", "secondary", "error", "warning", "info", "success", "default"]).optional().describe("스위치 색상"),
     size: z.enum(["small", "medium"]).optional().describe("스위치 크기 ('small' 또는 'medium')"),
     disabled: z.boolean().optional().describe("비활성화 여부"),
+    label: z.string().optional().describe("스위치 옆에 표시될 라벨 텍스트"),
+    labelPlacement: z.enum(["bottom", "top", "start", "end"]).optional().describe("라벨 위치 ('bottom' | 'top' | 'start' | 'end', 기본값: 'end'). label과 함께 사용"),
 });
 // Chip 컴포넌트 관련 스키마 정의
 export const ChipSchema = z.object({
@@ -118,7 +120,18 @@ export const TextFieldSchema = z.object({
     adornmentLabel: z.string().optional().describe("입력 필드 시작 또는 끝 부분에 표시될 텍스트 장식"),
     adornmentIconName: z.enum(Object.keys(IconNamesMap)).optional().describe(generateIconDescription({ format: 'nested' })),
     adornmentPosition: z.enum(["start", "end"]).optional().describe("장식(adornment)의 위치"),
-    readOnly: z.boolean().optional().describe("읽기 전용 상태 여부"),
+    readOnly: z.boolean().optional().describe("읽기 전용 상태 여부 - 생성 코드에서 inputProps={{ readOnly: true }}로 변환되어 출력됨 (톱레벨 readOnly prop은 lib에 없음). inputProps를 직접 지정하는 경우 이 파라미터 대신 inputProps에 readOnly를 포함할 것"),
+    adornmentLabelColor: z.string().optional().describe("장식(adornment) 라벨 텍스트의 색상 (CSS 색상 문자열, 예: '#666666', 'red')"),
+    adornmentUnit: z.boolean().optional().describe("장식(adornment) 라벨을 단위(unit) 스타일로 표시할지 여부 (boolean, 기본값: false)"),
+    adornmentIconColor: z.string().optional().describe("장식(adornment) 아이콘의 색상 (CSS 색상 문자열, 예: '#1976d2')"),
+    withBtnVoice: z.boolean().optional().describe("입력 필드 우측에 음성 입력(마이크) 버튼 표시 여부 (boolean, 기본값: false)"),
+    voiceOn: z.boolean().optional().describe("음성 입력 활성(녹음 중) 상태 여부 (boolean). withBtnVoice와 함께 사용하며 보통 상태 변수로 제어"),
+    disabledVoice: z.boolean().optional().describe("음성 입력 버튼 비활성화 여부 (boolean, 기본값: false)"),
+    voiceSupported: z.boolean().optional().describe("브라우저의 음성 인식 지원 여부 (boolean). false면 음성 버튼이 미지원 상태로 표시됨"),
+    onVoice: z.string().optional().describe("음성 입력 버튼 클릭 시 호출될 함수명 (예: 'handleVoice'). () => void 형태"),
+    withBtnIconName: z.enum(Object.keys(IconNamesMap)).optional().describe("입력 필드 우측 확인(withBtn) 버튼에 표시할 아이콘 이름"),
+    withBtnDisabled: z.boolean().optional().describe("우측 확인(withBtn) 버튼 비활성화 여부 (boolean, 기본값: false)"),
+    onConfirm: z.string().optional().describe("우측 확인(withBtn) 버튼 클릭 시 호출될 함수명 (예: 'handleConfirm'). () => void 형태"),
 });
 // Avatar 컴포넌트 관련 스키마 정의
 export const AvatarSchema = z.object({
@@ -130,6 +143,9 @@ export const AvatarSchema = z.object({
     sx: z.string().optional().describe('MUI sx 스타일 객체(JSX/문자열)'),
     onClick: z.string().optional().describe('클릭 이벤트 핸들러'),
     children: z.string().optional().describe('아바타 내부에 표시할 텍스트/JSX (예: 이름, 아이콘 등)'),
+    badgeVariant: z.enum(['standard', 'dot']).optional().describe("뱃지 스타일 ('standard' | 'dot'). showBadge와 함께 사용"),
+    badgeOverlap: z.enum(['circular', 'rectangular']).optional().describe("뱃지가 아바타에 겹쳐지는 방식 ('circular' | 'rectangular'). showBadge와 함께 사용"),
+    fontSize: z.number().optional().describe('아바타 내부 텍스트의 폰트 크기 (숫자, px 단위, 예: 14)'),
 });
 // Checkbox 컴포넌트 관련 스키마 정의
 export const CheckboxSchema = z.object({
@@ -156,6 +172,9 @@ export const CollapseSchema = z.object({
     label: z.string().describe("토글 라벨 텍스트"),
     defaultExpanded: z.boolean().optional().describe("기본 확장 여부"),
     children: z.string().describe("Collapse 내부에 들어갈 JSX/텍스트"),
+    btnClass: z.string().optional().describe("토글 버튼에 적용할 커스텀 CSS 클래스명"),
+    btnToggleClass: z.string().optional().describe("확장(펼침) 상태일 때 토글 버튼에 적용할 커스텀 CSS 클래스명"),
+    contentsClass: z.string().optional().describe("콘텐츠 영역에 적용할 커스텀 CSS 클래스명"),
 });
 // Slider 컴포넌트 관련 스키마 정의
 export const SliderSchema = z.object({
@@ -242,6 +261,9 @@ export const TreeViewSchema = z.object({
     renderRightContent: z.string().optional().describe("각 노드 우측에 표시할 JSX 코드 문자열 (함수 형태, node 파라미터 사용)"),
     onNodeClick: z.string().optional().describe("노드 클릭 이벤트 핸들러 함수명 (예: handleNodeClick)"),
     selectedNodeId: z.string().optional().describe("선택된 노드 ID 상태 변수명 (예: selectedNode?.id)"),
+    searchPlaceholder: z.string().optional().describe("검색 입력 필드의 플레이스홀더 텍스트 (searchable이 true일 때 표시, 예: 'Search...')"),
+    className: z.string().optional().describe("트리뷰 최상위 컨테이너에 적용할 커스텀 CSS 클래스명"),
+    totalMuiIconName: z.string().optional().describe("최상단 Total 라벨에 표시할 Material-UI 아이콘 이름 (예: 'folder', 'settings')"),
 });
 // InsightCard 컴포넌트 관련 스키마 정의
 export const InsightCardSchema = z.object({
@@ -253,6 +275,10 @@ export const InsightCardSchema = z.object({
     subtitle: z.string().optional().describe("타일 부제목 (기본값: 'AI-powered analysis and recommendations')"),
     onDownload: z.string().optional().describe("커스텀 다운로드 콜백 함수명 (예: handleDownload)"),
     sx: z.string().optional().describe("MUI sx 스타일 객체(JSX/문자열)"),
+    onDownloadHandlerReady: z.string().optional().describe("다운로드 핸들러를 외부(예: 팝업 버튼)에서 사용할 수 있도록 전달받는 콜백 함수명 (예: handleDownloadReady). (downloadHandler: () => void) => void 형태"),
+    onToggleHandlerReady: z.string().optional().describe("접기/펼치기 토글 핸들러를 외부에서 사용할 수 있도록 전달받는 콜백 함수명 (예: handleToggleReady). (toggleHandler: () => void) => void 형태"),
+    hideDownloadButton: z.boolean().optional().describe("타일 헤더의 다운로드 버튼 숨김 여부 (boolean, 기본값: false)"),
+    hideToggleButton: z.boolean().optional().describe("타일 헤더의 접기/펼치기 버튼 숨김 여부 (boolean, 기본값: false)"),
 });
 // InsightContent 컴포넌트 관련 스키마 정의 (타일 없이 콘텐츠만)
 export const InsightContentSchema = z.object({
@@ -412,6 +438,10 @@ export function createFormsComponent() {
                     props.push(`size="${args.size}"`);
                 if (args.disabled)
                     props.push(`disabled`);
+                if (args.label)
+                    props.push(`label="${args.label}"`);
+                if (args.labelPlacement)
+                    props.push(`labelPlacement="${args.labelPlacement}"`);
                 const code = `<OpsnowCommonSwitch ${props.join(' ')} />`;
                 return {
                     content: [
@@ -509,8 +539,31 @@ export function createFormsComponent() {
                     props.push(`adornmentIconName=\"${args.adornmentIconName}\"`);
                 if (args.adornmentPosition)
                     props.push(`adornmentPosition=\"${args.adornmentPosition}\"`);
-                if (args.readOnly)
-                    props.push(`readOnly`);
+                // readOnly는 톱레벨 prop이 아니라 inputProps 경로로만 동작 (MUI 7: rest prop은 FormControl로 가서 input에 미도달)
+                if (args.readOnly && !args.inputProps)
+                    props.push(`inputProps={{ readOnly: true }}`);
+                if (args.adornmentLabelColor)
+                    props.push(`adornmentLabelColor=\"${args.adornmentLabelColor}\"`);
+                if (args.adornmentUnit)
+                    props.push(`adornmentUnit`);
+                if (args.adornmentIconColor)
+                    props.push(`adornmentIconColor=\"${args.adornmentIconColor}\"`);
+                if (args.withBtnVoice)
+                    props.push(`withBtnVoice`);
+                if (args.voiceOn !== undefined)
+                    props.push(`voiceOn={${args.voiceOn}}`);
+                if (args.disabledVoice)
+                    props.push(`disabledVoice`);
+                if (args.voiceSupported !== undefined)
+                    props.push(`voiceSupported={${args.voiceSupported}}`);
+                if (args.onVoice)
+                    props.push(`onVoice={${args.onVoice}}`);
+                if (args.withBtnIconName)
+                    props.push(`withBtnIconName=\"${args.withBtnIconName}\"`);
+                if (args.withBtnDisabled)
+                    props.push(`withBtnDisabled`);
+                if (args.onConfirm)
+                    props.push(`onConfirm={${args.onConfirm}}`);
                 // inputProps, InputProps 멀티라인/JSX 대응
                 if (args.inputProps) {
                     if (args.inputProps.trim().startsWith('{') && args.inputProps.includes('\n')) {
@@ -554,6 +607,12 @@ export function createFormsComponent() {
                     props.push(`variant=\"${args.variant}\"`);
                 if (args.showBadge)
                     props.push(`showBadge`);
+                if (args.badgeVariant)
+                    props.push(`badgeVariant=\"${args.badgeVariant}\"`);
+                if (args.badgeOverlap)
+                    props.push(`badgeOverlap=\"${args.badgeOverlap}\"`);
+                if (args.fontSize !== undefined)
+                    props.push(`fontSize={${args.fontSize}}`);
                 if (args.sx)
                     props.push(`sx={${args.sx}}`);
                 if (args.onClick)
@@ -673,6 +732,12 @@ export function createFormsComponent() {
                     props.push(`label=\"${args.label}\"`);
                 if (args.defaultExpanded)
                     props.push(`defaultExpanded`);
+                if (args.btnClass)
+                    props.push(`btnClass=\"${args.btnClass}\"`);
+                if (args.btnToggleClass)
+                    props.push(`btnToggleClass=\"${args.btnToggleClass}\"`);
+                if (args.contentsClass)
+                    props.push(`contentsClass=\"${args.contentsClass}\"`);
                 let code = '';
                 if (args.children && args.children.trim().startsWith('<')) {
                     code = `<OpsnowCommonCollapse ${props.join(' ')}>` + `\n  ${args.children}\n</OpsnowCommonCollapse>`;
@@ -918,6 +983,12 @@ export function createFormsComponent() {
                     props.push(`onNodeClick={${args.onNodeClick}}`);
                 if (args.selectedNodeId)
                     props.push(`selectedNodeId={${args.selectedNodeId}}`);
+                if (args.searchPlaceholder)
+                    props.push(`searchPlaceholder=\"${args.searchPlaceholder}\"`);
+                if (args.className)
+                    props.push(`className=\"${args.className}\"`);
+                if (args.totalMuiIconName)
+                    props.push(`totalMuiIconName=\"${args.totalMuiIconName}\"`);
                 const code = `<OpsnowCommonTreeView\n  ${props.join('\n  ')}\n/>`;
                 return {
                     content: [
@@ -957,6 +1028,14 @@ export function createFormsComponent() {
                     props.push(`onDownload={${args.onDownload}}`);
                 if (args.sx)
                     props.push(`sx={${args.sx}}`);
+                if (args.onDownloadHandlerReady)
+                    props.push(`onDownloadHandlerReady={${args.onDownloadHandlerReady}}`);
+                if (args.onToggleHandlerReady)
+                    props.push(`onToggleHandlerReady={${args.onToggleHandlerReady}}`);
+                if (args.hideDownloadButton)
+                    props.push(`hideDownloadButton`);
+                if (args.hideToggleButton)
+                    props.push(`hideToggleButton`);
                 const code = `<OpsnowCommonInsightCard\n  ${props.join('\n  ')}\n/>`;
                 return {
                     content: [

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

@@ -4,9 +4,8 @@ export const IconSchema = z.object({
     iconName: z.enum(Object.keys(IconNamesMap)).describe(generateIconDescription({ format: 'nested' })),
     size: z.number().optional().default(24).describe("아이콘 크기(px)"),
     color: z.string().optional().describe("아이콘 색상"),
-    className: z.string().optional().describe("추가 CSS 클래스"),
-    onClick: z.string().optional().describe("클릭 이벤트 핸들러 함수명"),
-    disabled: z.boolean().optional().default(false).describe("비활성화 여부")
+    className: z.string().optional().describe("추가 CSS 클래스 (HTMLAttributes 상속 + rest 스프레드로 span에 적용. 기본 클래스 'opsnow-common-icon'을 덮어쓰므로 주의)"),
+    onClick: z.string().optional().describe("클릭 이벤트 핸들러 함수명 (HTMLAttributes 상속으로 span에 적용됨)"),
 });
 export const MuiIconSchema = z.object({
     theme: z.string().optional().describe("테마명"),
@@ -52,8 +51,6 @@ export function createIconsComponent() {
                     props.push(`className="${args.className}"`);
                 if (args.onClick)
                     props.push(`onClick={${args.onClick}}`);
-                if (args.disabled)
-                    props.push(`disabled`);
                 const code = `<OpsnowCommonIcon ${props.join(" ")} />`;
                 return {
                     content: [

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

@@ -38,6 +38,7 @@ export const NotificationSchema = z.object({
         .default(false)
         .describe("배경 흰색 여부 - severity :  info 일때만 사용(true시 사용 예시 : bgWhite (bgWhite={true}처럼 쓰지 않음.)"),
     action: z.string().optional().describe("액션 버튼 코드 - 예시: <OpsnowCommonButton label='확인' />"),
+    customActionBtn: z.string().optional().describe("커스텀 액션 버튼 JSX 코드 문자열 (React.ReactNode) - 예시: <OpsnowCommonButton label='확인' onClick={handleAction} />. action + isCustom 조합 대신 직접 커스텀 버튼을 지정할 때 사용"),
     isCustom: z
         .boolean()
         .default(false)
@@ -76,16 +77,17 @@ export function createNotificationComponent() {
                     props.push("bgWhite");
                 }
                 if (args.action) {
-                    if (args.isCustom && args.closable && args.placement === `card`) {
-                        props.push(`customActionBtn={${args.action}}`);
-                    }
-                    else if (args.isCustom && !args.placement) {
+                    // isCustom이면 placement와 무관하게 customActionBtn으로 출력 (커스텀 버튼 분기 스위치)
+                    if (args.isCustom) {
                         props.push(`customActionBtn={${args.action}}`);
                     }
                     else {
                         props.push(`action={${args.action}}`);
                     }
                 }
+                if (args.customActionBtn && !args.action) {
+                    props.push(`customActionBtn={${args.customActionBtn}}`);
+                }
                 if (args.closable) {
                     props.push(`onClose={() => {\n  // 닫힐때 실행할 함수\n  // 예시: setOpen(${!args.closable}})\n}}`);
                 }

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

@@ -35,14 +35,12 @@ export const PaginationSchema = z.object({
         .string()
         .optional()
         .describe("pageNum이 이전페이지로 이동할때 핸들러 함수 코드. 함수 내부 코드(문자열)로 전달하세요. 예시: console.log('이전 페이지로 이동, 현재 페이지:', pageNum)"),
-    pagingFromServer: z
-        .boolean()
-        .default(false)
-        .describe("서버에서 페이지네이션 정보를 받아오는 여부"),
     onPageChange: z
         .string()
         .optional()
         .describe("pageData가 변경 되었을때 사용하는 핸들러 함수 코드. 함수 내부 코드(문자열)로 전달하세요. 예시: setCurrentPageData(pageData); console.log('Current Page Data:', pageData)"),
+    count: z.number().optional().describe("전체 항목(행) 수 (숫자). 라이브러리가 페이지 수 계산에 사용하는 필수 prop. list를 전달하면 list.length로 자동 설정되므로 생략 가능하며, 서버 페이징 등 list 없이 사용할 때 직접 지정"),
+    locale: z.string().optional().describe("표시 언어 로케일 문자열 (예: 'ko', 'en'). isLocale이 true(기본값)면 i18n.getLocale()이 자동 적용되므로, isLocale을 false로 두고 특정 언어로 고정할 때만 지정"),
 });
 // Pagination 컴포넌트 함수 - 배열 반환
 export function createPaginationComponent() {
@@ -103,8 +101,13 @@ export function createPaginationComponent() {
                 if (args.size) {
                     props.push(`size="${args.size}"`);
                 }
-                if (args.pagingFromServer) {
-                    props.push(`pagingFromServer={${args.pagingFromServer}}`);
+                // count: list가 있으면 위에서 list.length로 이미 push되므로 중복 방지
+                if (args.count !== undefined && !(args.list && Array.isArray(args.list))) {
+                    props.push(`count={${args.count}}`);
+                }
+                // locale: isLocale이 true면 위에서 i18n.getLocale()로 이미 push되므로 중복 방지
+                if (args.locale && !args.isLocale) {
+                    props.push(`locale="${args.locale}"`);
                 }
                 // rowsPerPage 관련 props
                 if (args.rowsPerPageOptions) {

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

@@ -3,10 +3,7 @@ import { z } from "zod";
 export const PopupSchema = z.object({
     title: z.string().describe("팝업 제목"),
     visible: z.boolean().optional().default(false).describe("팝업 표시 여부"),
-    width: z.number().optional().describe("팝업 너비 (px)"),
-    height: z.number().optional().describe("팝업 높이 (px)"),
-    closable: z.boolean().optional().default(true).describe("닫기 버튼 표시 여부"),
-    maskClosable: z.boolean().optional().default(true).describe("마스크 클릭으로 닫기 가능 여부"),
+    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)'),
@@ -14,6 +11,25 @@ export const PopupSchema = z.object({
         color: z.string().describe('확인 버튼 색상'),
         variant: z.string().describe('확인 버튼 변형'),
     }).optional().describe('확인 버튼 설정'),
+    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)'),
+    useFooterActionBtn: z.boolean().optional().describe('푸터에 액션 버튼 표시 여부 (boolean)'),
+    cancelButton: z.object({
+        text: z.string().optional().describe('취소 버튼 텍스트'),
+        variant: z.enum(['text', 'outlined', 'contained']).optional().describe('취소 버튼 변형 (text | outlined | contained)'),
+        disabled: z.boolean().optional().describe('취소 버튼 비활성화 여부'),
+        color: z.string().optional().describe('취소 버튼 색상'),
+    }).optional().describe('취소 버튼 설정 객체 - { text, variant, disabled, color }'),
+    actionButton: z.object({
+        text: z.string().optional().describe('액션 버튼 텍스트'),
+        variant: z.enum(['text', 'outlined', 'contained']).optional().describe('액션 버튼 변형 (text | outlined | contained)'),
+        disabled: z.boolean().optional().describe('액션 버튼 비활성화 여부'),
+        color: z.string().optional().describe('액션 버튼 색상'),
+    }).optional().describe('액션 버튼 설정 객체 - { text, variant, disabled, color }'),
+    hideHeaderClose: z.boolean().optional().describe('헤더의 닫기(X) 버튼 숨김 여부 (boolean)'),
+    hideFooter: z.boolean().optional().describe('푸터 전체 숨김 여부 (boolean)'),
     useCustomHeader: z.boolean().optional().default(false).describe('커스텀 헤더 사용 여부'),
     useCustomFooter: z.boolean().optional().default(false).describe('커스텀 푸터 사용 여부'),
     headerContent: z.any().optional().describe('커스텀 헤더 내용 (JSX)'),
@@ -34,20 +50,25 @@ export function createPopupComponent() {
             parameters: PopupSchema,
             handler: async (args) => {
                 // <OpsnowCommonPopup ...> 코드만 동적으로 생성
-                const { title = 'Example Popup', visible = false, width, height, closable = true, maskClosable = true, disableEscapeKeyDown = false, size, confirmButton, useCustomHeader = false, useCustomFooter = false, headerContent, footerContent, type = 'standard', } = args;
+                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;
                 // prop 문자열 생성
                 const propStr = [
                     `title=\"${title}\"`,
                     `open={${visible}}`,
                     `onClose={handleClose}`,
-                    width ? `width={${width}}` : '',
-                    height ? `height={${height}}` : '',
-                    closable === false ? 'closable={false}' : '',
-                    maskClosable === false ? 'maskClosable={false}' : '',
                     disableEscapeKeyDown ? 'disableEscapeKeyDown' : '',
                     `type=\"${type}\"`,
                     `size=\"${size}\"`,
                     confirmButton ? `confirmButton={${JSON.stringify(confirmButton)}}` : '',
+                    onConfirm ? `onConfirm={${onConfirm}}` : '',
+                    onAction ? `onAction={${onAction}}` : '',
+                    useSpecialTitle ? 'useSpecialTitle' : '',
+                    useFooterCancelBtn ? 'useFooterCancelBtn' : '',
+                    useFooterActionBtn ? 'useFooterActionBtn' : '',
+                    cancelButton ? `cancelButton={${JSON.stringify(cancelButton)}}` : '',
+                    actionButton ? `actionButton={${JSON.stringify(actionButton)}}` : '',
+                    (hideHeaderClose || closable === false) ? 'hideHeaderClose' : '',
+                    hideFooter ? 'hideFooter' : '',
                     useCustomHeader ? 'useCustomHeader' : '',
                     useCustomFooter ? 'useCustomFooter' : '',
                     headerContent ? `headerContent={${headerContent}}` : '',

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

@@ -12,8 +12,7 @@ export const SelectSchema = z.object({
     variant: z.enum(["standard", "outlined", "filled", "noLine"]).optional().describe("셀렉트 variant"),
     size: z.enum(["small", "medium"]).optional().describe("셀렉트 크기"),
     error: z.boolean().optional().default(false).describe("에러 상태"),
-    disabled: z.boolean().optional().default(false).describe("비활성화 여부"),
-    searchable: z.boolean().optional().default(false).describe("검색 가능 여부")
+    disabled: z.boolean().optional().default(false).describe("비활성화 여부")
 });
 // Autocomplete Select 컴포넌트 관련 스키마 정의
 export const AutocompleteSelectSchema = z.object({
@@ -32,7 +31,18 @@ export const AutocompleteSelectSchema = z.object({
     loading: z.boolean().optional().default(false).describe("로딩 상태 표시 여부"),
     label: z.string().optional().describe("라벨 텍스트"),
     placeholder: z.string().optional().describe("플레이스홀더 텍스트"),
-    disabled: z.boolean().optional().default(false).describe("전체 비활성화 여부")
+    disabled: z.boolean().optional().default(false).describe("전체 비활성화 여부"),
+    textFieldProps: z.object({
+        error: z.boolean().optional().describe("에러 상태 표시 여부"),
+        helperText: z.string().optional().describe("입력창 하단 도움말 텍스트"),
+        required: z.boolean().optional().describe("필수 입력 표시 여부"),
+        size: z.enum(["small", "medium"]).optional().describe("입력창 크기"),
+        variant: z.enum(["standard", "outlined", "filled"]).optional().describe("입력창 variant")
+    }).passthrough().optional().describe("내부 입력창(OpsnowCommonTextField)에 전달할 props 객체. error/helperText/required/size/variant 등 MUI TextField props 사용 가능. 기본값 없음(미지정 시 기본 TextField 사용)"),
+    groupBy: z.string().optional().describe("옵션 그룹핑 함수명 또는 인라인 화살표 함수. (option) => string 형태로 각 옵션이 속할 그룹 라벨을 반환 (예: (option) => option.group). 기본값 없음(그룹핑 안 함)"),
+    fitDropdownWidth: z.boolean().optional().describe("드롭다운 너비를 입력 필드 폭에 고정하고 긴 라벨은 줄바꿈 (boolean, 기본 false). false(기본)면 드롭다운이 옵션 라벨 폭에 맞게 확장되며, 화면 오른쪽 공간이 부족하면 잘리는 대신 왼쪽으로 이동. 좁은 레이아웃에서 드롭다운이 넓어지면 안 될 때 사용"),
+    dropdownMaxWidth: z.number().optional().describe("확장 모드(fitDropdownWidth=false)에서 드롭다운 최대 너비(px, number). 미지정(기본) 시 고정 상한 없이 뷰포트 폭까지 확장하고 그보다 긴 라벨만 줄바꿈 (예: 360)"),
+    onChange: z.string().optional().describe("선택 값 변경 콜백 함수명. (value, event?, reason?, details?) => void 형태이며 value는 multiple 여부에 따라 배열 또는 단일 아이템(null 가능). 기본값 없음(미지정 시 생성 코드에 onChange={setValue} 사용)")
 });
 // Select 컴포넌트 함수 - 배열 반환
 export function createSelectComponent() {
@@ -42,7 +52,7 @@ export function createSelectComponent() {
             description: `기본 셀렉트 컴포넌트 예제입니다.
 
       - items: 옵션 배열 (value, label, disabled 등 지원)
-      - multiple, placeholder, variant, size, error, disabled, searchable 등 다양한 props 지원
+      - multiple, placeholder, variant, size, error, disabled 등 다양한 props 지원
       - value/onChange는 단일/다중 선택에 따라 배열 또는 단일 값
 
       **import:**
@@ -69,8 +79,6 @@ export function createSelectComponent() {
                     props.push(`error`);
                 if (args.disabled)
                     props.push(`disabled`);
-                if (args.searchable)
-                    props.push(`searchable`);
                 props.push(`onChange={e => setValue(e.target.value)}`);
                 const code = `<OpsnowCommonSelect ${props.join(' ')} />`;
                 return {
@@ -119,7 +127,15 @@ export function createSelectComponent() {
                     props.push(`placeholder=\"${args.placeholder}\"`);
                 if (args.disabled)
                     props.push(`disabled`);
-                props.push(`onChange={setValue}`);
+                if (args.textFieldProps)
+                    props.push(`textFieldProps={${JSON.stringify(args.textFieldProps)}}`);
+                if (args.groupBy)
+                    props.push(`groupBy={${args.groupBy}}`);
+                if (args.fitDropdownWidth)
+                    props.push(`fitDropdownWidth`);
+                if (args.dropdownMaxWidth)
+                    props.push(`dropdownMaxWidth={${args.dropdownMaxWidth}}`);
+                props.push(`onChange={${args.onChange ?? "setValue"}}`);
                 const code = `<OpsnowCommonAutocomplete ${props.join(' ')} />`;
                 return {
                     content: [