@ncds/ui-admin 1.8.1 → 1.8.2

package/dist/temp/src/components/switch/index.d.ts

@@ -1,2 +1 @@
-export type { SwitchProps } from './Switch';
-export { Switch } from './Switch';
+export * from './Switch';

package/dist/temp/src/components/switch/index.js

@@ -1 +1 @@
-export { Switch } from './Switch';
+export * from './Switch';

package/dist/temp/src/components/tag/Tag.d.ts

@@ -1,7 +1,7 @@
 import { type MouseEventHandler } from 'react';
 import type { Size } from '../../../constant/size';
 import type { SideSlotType } from '../../types/side-slot';
-interface TagProps {
+export interface TagProps {
     size?: Extract<Size, 'sm' | 'md'>;
     icon?: SideSlotType;
     text: string;
@@ -11,7 +11,5 @@ interface TagProps {
     onButtonClick?: MouseEventHandler<HTMLButtonElement>;
     maxLength?: number;
 }
-type CalculatedPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-declare const Tag: ({ size, icon, text, count, close, onButtonClick, maxLength }: TagProps) => import("react/jsx-runtime").JSX.Element;
-export type { CalculatedPosition };
-export { Tag };
+export type CalculatedPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export declare const Tag: ({ size, icon, text, count, close, onButtonClick, maxLength }: TagProps) => import("react/jsx-runtime").JSX.Element;

package/dist/temp/src/components/tag/Tag.js

@@ -41,7 +41,7 @@ const calculateOptimalPosition = (triggerElement, tooltipElement) => {
     const fallbackPosition = hasTopSpace ? 'top-right' : 'bottom-right';
     return fallbackPosition;
 };
-const Tag = ({ size = 'sm', icon, text, count, close, onButtonClick, maxLength = 20 }) => {
+export const Tag = ({ size = 'sm', icon, text, count, close, onButtonClick, maxLength = 20 }) => {
     const [isTooltipVisible, setIsTooltipVisible] = useState(false);
     const [calculatedPosition, setCalculatedPosition] = useState('top-right');
     const tagRef = useRef(null);
@@ -93,4 +93,3 @@ const Tag = ({ size = 'sm', icon, text, count, close, onButtonClick, maxLength =
             'ncua-tag--truncated': shouldTruncate,
         }), onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: [icon && sideSlotRender(icon), _jsx("span", { className: "ncua-tag__text", children: displayText }), count && _jsx("span", { className: "ncua-tag__count", children: count }), close && (_jsx("button", { type: "button", className: "ncua-tag__close", onClick: onButtonClick, children: _jsx(XClose, { color: COLOR.gray300, width: iconSize[size], height: iconSize[size] }) })), shouldTruncate && isTooltipVisible && (_jsx("span", { ref: tooltipRef, className: classNames('ncua-tag__tooltip', `ncua-tag__tooltip--${calculatedPosition}`), children: _jsx("span", { className: "ncua-tag__tooltip-content", children: text }) }))] }));
 };
-export { Tag };

package/dist/temp/src/components/tooltip/Tooltip.d.ts

@@ -1,7 +1,8 @@
+type CalculatedPosition = 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 interface TooltipProps {
     tooltipType?: 'white' | 'black';
     iconType?: 'stroke' | 'fill';
-    position?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'auto';
+    position?: CalculatedPosition | 'auto';
     size?: 'sm' | 'md';
     hideArrow?: boolean;
     title?: string;
@@ -10,6 +11,7 @@ interface TooltipProps {
     className?: string;
     iconColor?: string;
     iconStyle?: 'help-circle' | 'alert-circle';
+    zIndex?: number;
 }
-export declare const Tooltip: ({ tooltipType, iconType, position, size, title, content, hideArrow, type, iconColor, iconStyle, className, }: TooltipProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Tooltip: ({ tooltipType, iconType, position, size, title, content, hideArrow, type, iconColor, iconStyle, className, zIndex, }: TooltipProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/temp/src/components/tooltip/Tooltip.js

@@ -1,82 +1,133 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { AlertCircle, AlertCircleFill, HelpCircle, HelpCircleFill } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
 import { ButtonCloseX } from '../button/ButtonCloseX';
 const ICON_SIZE_SM = 14;
 const ICON_SIZE_DEFAULT = 16;
-const MARGIN = 10;
-const DEFAULT_TOOLTIP_WIDTH = 200;
-const DEFAULT_TOOLTIP_HEIGHT = 60;
-const POSITION_PRIORITY = ['bottom', 'top', 'right', 'left'];
-// 수직 위치(top/bottom)일 때 수평 정렬 보정
-const resolveVerticalAlignment = (position, triggerRect, tooltipWidth, viewportWidth) => {
-    const centerX = triggerRect.left + triggerRect.width / 2;
-    const tooltipHalfWidth = tooltipWidth / 2;
-    if (centerX - tooltipHalfWidth < MARGIN) {
-        return `${position}-left`;
+// HTML 구현체(assets/scripts/tooltip)와 동일한 상수
+const TOOLTIP_OFFSET = 6;
+const VIEWPORT_MARGIN = 8;
+const EDGE_ALIGN_OFFSET = 12;
+const OFFSCREEN = -99999;
+// HTML 구현체(TooltipLayerManager)가 body에 만드는 `#tooltip-global-layer`와 동일 id.
+// 둘 중 한쪽만 바뀌면 포털이 body로 fallback되며 사일런트 동작 이상이 날 수 있으므로 함께 유지한다.
+const GLOBAL_LAYER_ID = 'tooltip-global-layer';
+// body 하위의 전역 레이어를 찾거나 없으면 body로 fallback
+const resolvePortalTarget = () => {
+    if (typeof document === 'undefined')
+        return null;
+    return document.getElementById(GLOBAL_LAYER_ID) ?? document.body;
+};
+// 앵커 rect와 패널 rect를 기반으로 viewport 고정 좌표 계산
+const computePanelCoords = (prefer, anchor, panel) => {
+    let resolved = prefer;
+    if (resolved === 'auto') {
+        const enoughTop = anchor.top - TOOLTIP_OFFSET - panel.height >= VIEWPORT_MARGIN;
+        resolved = enoughTop ? 'top' : 'bottom';
     }
-    if (centerX + tooltipHalfWidth > viewportWidth - MARGIN) {
-        return `${position}-right`;
+    let top = 0;
+    let left = 0;
+    let calculatedPosition = 'bottom';
+    if (resolved === 'bottom') {
+        top = anchor.bottom + TOOLTIP_OFFSET;
+        left = anchor.left + anchor.width / 2 - panel.width / 2;
+        calculatedPosition = 'bottom';
     }
-    return position;
-};
-// 해당 위치에 툴팁을 배치할 충분한 공간이 있는지 확인
-const hasEnoughSpace = (position, spaces, tooltipWidth, tooltipHeight) => {
-    const isVertical = position === 'bottom' || position === 'top';
-    const requiredSpace = isVertical ? tooltipHeight : tooltipWidth;
-    return spaces[position] >= requiredSpace + MARGIN;
-};
-// 위치 계산 position='auto' 일 때 사용
-const calculateOptimalPosition = (triggerElement, tooltipElement, preferredPosition = 'bottom') => {
-    const triggerRect = triggerElement.getBoundingClientRect();
-    const tooltipRect = tooltipElement.getBoundingClientRect();
-    const { innerWidth: viewportWidth, innerHeight: viewportHeight } = window;
-    const spaces = {
-        top: triggerRect.top,
-        bottom: viewportHeight - triggerRect.bottom,
-        left: triggerRect.left,
-        right: viewportWidth - triggerRect.right,
-    };
-    const tooltipWidth = tooltipRect.width || DEFAULT_TOOLTIP_WIDTH;
-    const tooltipHeight = tooltipRect.height || DEFAULT_TOOLTIP_HEIGHT;
-    for (const position of POSITION_PRIORITY) {
-        if (!hasEnoughSpace(position, spaces, tooltipWidth, tooltipHeight)) {
-            continue;
-        }
-        const isVertical = position === 'bottom' || position === 'top';
-        if (isVertical) {
-            return resolveVerticalAlignment(position, triggerRect, tooltipWidth, viewportWidth);
-        }
-        return position;
+    else if (resolved === 'top') {
+        top = anchor.top - panel.height - TOOLTIP_OFFSET;
+        left = anchor.left + anchor.width / 2 - panel.width / 2;
+        calculatedPosition = 'top';
+    }
+    else if (resolved === 'left') {
+        top = anchor.top + anchor.height / 2 - panel.height / 2;
+        left = anchor.left - panel.width - TOOLTIP_OFFSET;
+        calculatedPosition = 'left';
+    }
+    else if (resolved === 'right') {
+        top = anchor.top + anchor.height / 2 - panel.height / 2;
+        left = anchor.right + TOOLTIP_OFFSET;
+        calculatedPosition = 'right';
+    }
+    else if (resolved === 'top-left') {
+        top = anchor.top - panel.height - TOOLTIP_OFFSET;
+        left = anchor.left - EDGE_ALIGN_OFFSET;
+        calculatedPosition = 'top-left';
     }
-    return preferredPosition;
+    else if (resolved === 'top-right') {
+        top = anchor.top - panel.height - TOOLTIP_OFFSET;
+        left = anchor.right - panel.width + EDGE_ALIGN_OFFSET;
+        calculatedPosition = 'top-right';
+    }
+    else if (resolved === 'bottom-left') {
+        top = anchor.bottom + TOOLTIP_OFFSET;
+        left = anchor.left - EDGE_ALIGN_OFFSET;
+        calculatedPosition = 'bottom-left';
+    }
+    else if (resolved === 'bottom-right') {
+        top = anchor.bottom + TOOLTIP_OFFSET;
+        left = anchor.right - panel.width + EDGE_ALIGN_OFFSET;
+        calculatedPosition = 'bottom-right';
+    }
+    left = Math.max(VIEWPORT_MARGIN, Math.min(left, window.innerWidth - panel.width - VIEWPORT_MARGIN));
+    top = Math.max(VIEWPORT_MARGIN, Math.min(top, window.innerHeight - panel.height - VIEWPORT_MARGIN));
+    return { top: Math.round(top), left: Math.round(left), calculatedPosition };
 };
-export const Tooltip = ({ tooltipType = 'white', iconType = 'stroke', position = 'auto', size = 'sm', title, content, hideArrow = false, type = 'short', iconColor = 'var(--gray-300)', iconStyle = 'help-circle', className, }) => {
+export const Tooltip = ({ tooltipType = 'white', iconType = 'stroke', position = 'auto', size = 'sm', title, content, hideArrow = false, type = 'short', iconColor = 'var(--gray-300)', iconStyle = 'help-circle', className, zIndex, }) => {
     const iconSize = size === 'sm' ? ICON_SIZE_SM : ICON_SIZE_DEFAULT;
-    const tooltipRef = useRef(null);
-    const tooltipBgRef = useRef(null);
+    const anchorRef = useRef(null);
+    const panelRef = useRef(null);
+    const rafIdRef = useRef(null);
+    const [mounted, setMounted] = useState(false);
+    const [coords, setCoords] = useState({ top: OFFSCREEN, left: OFFSCREEN });
     const [calculatedPosition, setCalculatedPosition] = useState(position === 'auto' ? 'bottom' : position);
     const [isVisible, setIsVisible] = useState(false);
     const [isManuallyClose, setIsManuallyClose] = useState(false);
-    const [isMeasuring, setIsMeasuring] = useState(false);
+    useEffect(() => {
+        setMounted(true);
+        return () => {
+            if (rafIdRef.current !== null) {
+                cancelAnimationFrame(rafIdRef.current);
+                rafIdRef.current = null;
+            }
+        };
+    }, []);
+    const updatePosition = useCallback(() => {
+        if (!anchorRef.current || !panelRef.current)
+            return;
+        const anchor = anchorRef.current.getBoundingClientRect();
+        const panel = panelRef.current.getBoundingClientRect();
+        const next = computePanelCoords(position, anchor, panel);
+        setCoords({ top: next.top, left: next.left });
+        setCalculatedPosition(next.calculatedPosition);
+    }, [position]);
+    useEffect(() => {
+        if (!isVisible)
+            return;
+        updatePosition();
+        window.addEventListener('resize', updatePosition, { passive: true });
+        window.addEventListener('scroll', updatePosition, { passive: true, capture: true });
+        return () => {
+            window.removeEventListener('resize', updatePosition);
+            window.removeEventListener('scroll', updatePosition, { capture: true });
+        };
+    }, [isVisible, updatePosition]);
     const handleMouseEnter = useCallback(() => {
         if (isManuallyClose)
             return;
+        // opacity 전환 전에 좌표 확정 (ref 가드는 updatePosition 내부)
+        updatePosition();
+        // 웹폰트 로드·max-content 재계산 등 비동기 layout 안정화 후 한 번 더 보정
+        // 빠른 hover in/out 시 이전 프레임 요청은 취소해 중복/unmount 후 실행 방지
+        if (rafIdRef.current !== null)
+            cancelAnimationFrame(rafIdRef.current);
+        rafIdRef.current = requestAnimationFrame(() => {
+            rafIdRef.current = null;
+            updatePosition();
+        });
         setIsVisible(true);
-        if (position === 'auto' && tooltipRef.current && tooltipBgRef.current) {
-            // 크기 측정을 위해 임시로 measuring 클래스 추가
-            setIsMeasuring(true);
-            // 다음 렌더링 사이클에서 크기 측정
-            setTimeout(() => {
-                if (tooltipRef.current && tooltipBgRef.current) {
-                    const optimalPosition = calculateOptimalPosition(tooltipRef.current, tooltipBgRef.current, 'bottom');
-                    setCalculatedPosition(optimalPosition);
-                    setIsMeasuring(false);
-                }
-            }, 0);
-        }
-    }, [position, isManuallyClose]);
+    }, [isManuallyClose, updatePosition]);
     const handleMouseLeave = useCallback(() => {
         if (type === 'short') {
             setIsVisible(false);
@@ -93,12 +144,19 @@ export const Tooltip = ({ tooltipType = 'white', iconType = 'stroke', position =
         'ncua-tooltip--stroke': iconType === 'stroke',
         'ncua-tooltip--auto': position === 'auto',
     }, className), [size, type, hideArrow, iconType, position, className]);
-    const tooltipBgClassName = useMemo(() => classNames('ncua-tooltip__bg', `ncua-tooltip__bg--${tooltipType}`, `ncua-tooltip__bg--${finalPosition}`, {
+    const panelClassName = useMemo(() => classNames('ncua-tooltip-panel', 'ncua-tooltip__bg', `ncua-tooltip__bg--${tooltipType}`, `ncua-tooltip__bg--${finalPosition}`, {
         'ncua-tooltip__bg--visible': isVisible,
-        'ncua-tooltip__bg--measuring': isMeasuring,
         'ncua-tooltip__bg--force-hidden': isManuallyClose,
-    }), [tooltipType, finalPosition, isVisible, isMeasuring, isManuallyClose]);
-    return (_jsxs("span", { ref: tooltipRef, className: tooltipClassName, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: [iconStyle === 'help-circle' &&
-                (iconType === 'stroke' ? (_jsx(HelpCircle, { width: iconSize, height: iconSize, color: iconColor })) : (_jsx(HelpCircleFill, { width: iconSize, height: iconSize, color: iconColor }))), iconStyle === 'alert-circle' &&
-                (iconType === 'stroke' ? (_jsx(AlertCircle, { width: iconSize, height: iconSize, color: iconColor })) : (_jsx(AlertCircleFill, { width: iconSize, height: iconSize, color: iconColor }))), _jsxs("span", { ref: tooltipBgRef, className: tooltipBgClassName, children: [title && _jsx("span", { className: "ncua-tooltip__title", children: title }), content && _jsx("span", { className: "ncua-tooltip__content", children: content }), type === 'long' && (_jsx(ButtonCloseX, { className: "ncua-tooltip__close-button", size: "xs", theme: tooltipType === 'white' ? 'dark' : 'light', onClick: handleCloseClick, "aria-label": "\uD234\uD301 \uB2EB\uAE30" }))] })] }));
+    }), [tooltipType, finalPosition, isVisible, isManuallyClose]);
+    const panelStyle = {
+        top: `${coords.top}px`,
+        left: `${coords.left}px`,
+        opacity: isVisible ? 1 : 0,
+        ...(zIndex && { zIndex }),
+    };
+    const portalTarget = mounted ? resolvePortalTarget() : null;
+    const panel = (_jsxs("span", { ref: panelRef, className: panelClassName, style: panelStyle, children: [title && _jsx("span", { className: "ncua-tooltip__title", children: title }), content && _jsx("span", { className: "ncua-tooltip__content", children: content }), type === 'long' && (_jsx(ButtonCloseX, { className: "ncua-tooltip__close-button", size: "xs", theme: tooltipType === 'white' ? 'dark' : 'light', onClick: handleCloseClick, "aria-label": "\uD234\uD301 \uB2EB\uAE30" }))] }));
+    return (_jsxs(_Fragment, { children: [_jsxs("span", { ref: anchorRef, className: tooltipClassName, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: [iconStyle === 'help-circle' &&
+                        (iconType === 'stroke' ? (_jsx(HelpCircle, { width: iconSize, height: iconSize, color: iconColor })) : (_jsx(HelpCircleFill, { width: iconSize, height: iconSize, color: iconColor }))), iconStyle === 'alert-circle' &&
+                        (iconType === 'stroke' ? (_jsx(AlertCircle, { width: iconSize, height: iconSize, color: iconColor })) : (_jsx(AlertCircleFill, { width: iconSize, height: iconSize, color: iconColor })))] }), portalTarget && createPortal(panel, portalTarget)] }));
 };

package/dist/temp/src/hooks/dropdown/index.d.ts

@@ -1,6 +1,6 @@
-export { useDropdown } from './useDropdown';
-export { useDropdownKeyboard } from './useDropdownKeyboard';
-export { useDropdownPosition } from './useDropdownPosition';
-export { useOutsideClick } from './useOutsideClick';
-export { useScrollLock } from './useScrollLock';
-export { useWindowResize } from './useWindowResize';
+export * from './useDropdown';
+export * from './useDropdownKeyboard';
+export * from './useDropdownPosition';
+export * from './useOutsideClick';
+export * from './useScrollLock';
+export * from './useWindowResize';

package/dist/temp/src/hooks/dropdown/index.js

@@ -1,6 +1,6 @@
-export { useDropdown } from './useDropdown';
-export { useDropdownKeyboard } from './useDropdownKeyboard';
-export { useDropdownPosition } from './useDropdownPosition';
-export { useOutsideClick } from './useOutsideClick';
-export { useScrollLock } from './useScrollLock';
-export { useWindowResize } from './useWindowResize';
+export * from './useDropdown';
+export * from './useDropdownKeyboard';
+export * from './useDropdownPosition';
+export * from './useOutsideClick';
+export * from './useScrollLock';
+export * from './useWindowResize';

package/dist/temp/src/hooks/index.d.ts

@@ -1,4 +1,4 @@
 export * from './dropdown';
-export { useCallbackRef } from './useCallbackRef';
-export { useMediaQuery } from './useMediaQuery';
-export { useMergeRefs } from './useMergeRefs';
+export * from './useCallbackRef';
+export * from './useMediaQuery';
+export * from './useMergeRefs';

package/dist/temp/src/hooks/index.js

@@ -1,6 +1,6 @@
 // 기존 공통 hooks
 // 드롭다운 관련 hooks
 export * from './dropdown';
-export { useCallbackRef } from './useCallbackRef';
-export { useMediaQuery } from './useMediaQuery';
-export { useMergeRefs } from './useMergeRefs';
+export * from './useCallbackRef';
+export * from './useMediaQuery';
+export * from './useMergeRefs';

package/dist/temp/src/types/component-meta.d.ts

@@ -0,0 +1,26 @@
+/** AI 에이전트용 컴포넌트 메타데이터 타입 */
+/** DES INDEX §3-1~§3-8 기준 카테고리 (commerce-rag design 네임스페이스) */
+export type ComponentCategory = 'action' | 'input' | 'icon' | 'overlay' | 'navigation' | 'feedback' | 'layout' | 'data-display';
+export interface ComponentMeta {
+    category: ComponentCategory;
+    aliases: string[];
+    hasChildren: boolean;
+    description: string;
+    whenToUse: string[];
+    forbiddenRules: string[];
+    seeAlso: string[];
+    jsRequired: boolean;
+    /** Props가 확장하는 HTML 요소 — 에이전트가 표준 HTML 속성 사용 가능 여부를 판단 */
+    htmlElement?: string;
+    /**
+     * render_to_html에 전달할 실제 사용 예시 props.
+     *
+     * 작성 규칙 (props-type-guide.md § usageExamples 참조):
+     * - key: 시나리오 이름 (예: "default", "withIcon", "rangePicker")
+     * - value: render_to_html의 props 파라미터에 그대로 전달 가능한 객체
+     * - 모든 required prop 포함 필수. optional은 시나리오에 필요한 것만.
+     * - 에이전트가 복사해서 바로 사용할 수 있는 수준의 실제 데이터.
+     * - 빈 문자열(""), 빈 객체({}) 금지. 의미 있는 값을 넣을 것.
+     */
+    usageExamples?: Record<string, Record<string, unknown>>;
+}

package/dist/temp/src/types/component-meta.js

@@ -0,0 +1,2 @@
+/** AI 에이전트용 컴포넌트 메타데이터 타입 */
+export {};

package/dist/temp/src/types/dropdown/option.d.ts

@@ -1,13 +1,11 @@
+import type { SlotIconComponent } from '../side-slot';
 /**
  * 기본 옵션 타입
  */
 export type OptionType = {
     id: string | number;
     label: string;
-    icon?: React.ComponentType<{
-        width?: number;
-        height?: number;
-    }>;
+    icon?: SlotIconComponent;
 };
 /**
  * 옵션 값 타입 (단일 또는 다중 선택)

package/dist/temp/src/types/side-slot.d.ts

@@ -1,12 +1,20 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { COLOR } from '../../constant/color';
 import type { DotProps } from '../components';
+/**
+ * 아이콘 컴포넌트 자리에 쓰이는 타입. MCP가 props 추출 시 이 타입의 정체성을 감지하여
+ * 문자열 이름을 실제 아이콘 컴포넌트로 치환할 수 있도록 nominal brand를 부착한다.
+ *
+ * 런타임 영향 없음 (브랜드 필드는 optional never, 실제로 할당할 수 없음).
+ */
 export type SlotIconComponent = ComponentType<{
     height?: number;
     width?: number;
     color?: string;
     className?: string;
-}>;
+}> & {
+    readonly __ncuaSlotIconBrand?: never;
+};
 export type IconSlotType = {
     type: 'icon';
     icon: SlotIconComponent;

package/dist/temp/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/temp/vitest.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        include: ['scripts/**/__tests__/**/*.test.ts'],
+        environment: 'node',
+    },
+});

package/dist/types/src/components/badge/index.d.ts

@@ -1 +1,2 @@
 export * from './Badge';
+export * from './utils';

package/dist/types/src/components/date-picker/index.d.ts

@@ -1,2 +1,3 @@
 export * from './DatePicker';
+export * from './CustomInput';
 export * from './utils';

package/dist/types/src/components/empty-state/EmptyState.d.ts

@@ -1,14 +1,12 @@
 import { type ButtonProps } from '../button/Button';
-interface ButtonOptions extends Pick<ButtonProps, 'hierarchy' | 'size' | 'leadingIcon' | 'trailingIcon'> {
+export interface ButtonOptions extends Pick<ButtonProps, 'hierarchy' | 'size' | 'leadingIcon' | 'trailingIcon'> {
     label: string;
     onClick?: () => void;
     disabled?: boolean;
 }
-interface EmptyStateProps {
+export interface EmptyStateProps {
     title: string;
     description: string;
     buttons?: ButtonOptions | ButtonOptions[];
 }
-declare const EmptyState: ({ title, description, buttons }: EmptyStateProps) => import("react/jsx-runtime").JSX.Element;
-export type { ButtonOptions };
-export { EmptyState };
+export declare const EmptyState: ({ title, description, buttons }: EmptyStateProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/src/components/image-file-input/components/index.d.ts

@@ -0,0 +1 @@
+export * from './ImagePreview';

package/dist/types/src/components/image-file-input/index.d.ts

@@ -1 +1,2 @@
 export * from './ImageFileInput';
+export * from './components';

package/dist/types/src/components/progress-bar/components/index.d.ts

@@ -0,0 +1,2 @@
+export * from './SegmentBar';
+export * from './SegmentLabels';

package/dist/types/src/components/progress-bar/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from './useProgressBar';

package/dist/types/src/components/progress-bar/index.d.ts

@@ -1,2 +1,5 @@
 export * from './ProgressBar';
+export * from './components';
+export * from './hooks';
 export * from './types';
+export * from './utils';

package/dist/types/src/components/select-dropdown/index.d.ts

@@ -1 +1 @@
-export { type DropdownDirection, SelectDropdown, type SelectDropdownProps } from './SelectDropdown';
+export * from './SelectDropdown';

package/dist/types/src/components/spinner/Spinner.d.ts

@@ -1,9 +1,8 @@
 import type { ElementType, ReactNode } from 'react';
-interface SpinnerProps {
+export interface SpinnerProps {
     as?: ElementType;
     size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
     children?: ReactNode;
     backdrop?: boolean;
 }
 export declare const Spinner: ({ as, size, children, backdrop }: SpinnerProps) => import("react/jsx-runtime").JSX.Element;
-export {};

package/dist/types/src/components/switch/index.d.ts

@@ -1,2 +1 @@
-export type { SwitchProps } from './Switch';
-export { Switch } from './Switch';
+export * from './Switch';

package/dist/types/src/components/tag/Tag.d.ts

@@ -1,7 +1,7 @@
 import { type MouseEventHandler } from 'react';
 import type { Size } from '../../../constant/size';
 import type { SideSlotType } from '../../types/side-slot';
-interface TagProps {
+export interface TagProps {
     size?: Extract<Size, 'sm' | 'md'>;
     icon?: SideSlotType;
     text: string;
@@ -11,7 +11,5 @@ interface TagProps {
     onButtonClick?: MouseEventHandler<HTMLButtonElement>;
     maxLength?: number;
 }
-type CalculatedPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-declare const Tag: ({ size, icon, text, count, close, onButtonClick, maxLength }: TagProps) => import("react/jsx-runtime").JSX.Element;
-export type { CalculatedPosition };
-export { Tag };
+export type CalculatedPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export declare const Tag: ({ size, icon, text, count, close, onButtonClick, maxLength }: TagProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/src/components/tooltip/Tooltip.d.ts

@@ -1,7 +1,8 @@
+type CalculatedPosition = 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 interface TooltipProps {
     tooltipType?: 'white' | 'black';
     iconType?: 'stroke' | 'fill';
-    position?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'auto';
+    position?: CalculatedPosition | 'auto';
     size?: 'sm' | 'md';
     hideArrow?: boolean;
     title?: string;
@@ -10,6 +11,7 @@ interface TooltipProps {
     className?: string;
     iconColor?: string;
     iconStyle?: 'help-circle' | 'alert-circle';
+    zIndex?: number;
 }
-export declare const Tooltip: ({ tooltipType, iconType, position, size, title, content, hideArrow, type, iconColor, iconStyle, className, }: TooltipProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Tooltip: ({ tooltipType, iconType, position, size, title, content, hideArrow, type, iconColor, iconStyle, className, zIndex, }: TooltipProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/src/hooks/dropdown/index.d.ts

@@ -1,6 +1,6 @@
-export { useDropdown } from './useDropdown';
-export { useDropdownKeyboard } from './useDropdownKeyboard';
-export { useDropdownPosition } from './useDropdownPosition';
-export { useOutsideClick } from './useOutsideClick';
-export { useScrollLock } from './useScrollLock';
-export { useWindowResize } from './useWindowResize';
+export * from './useDropdown';
+export * from './useDropdownKeyboard';
+export * from './useDropdownPosition';
+export * from './useOutsideClick';
+export * from './useScrollLock';
+export * from './useWindowResize';

package/dist/types/src/hooks/index.d.ts

@@ -1,4 +1,4 @@
 export * from './dropdown';
-export { useCallbackRef } from './useCallbackRef';
-export { useMediaQuery } from './useMediaQuery';
-export { useMergeRefs } from './useMergeRefs';
+export * from './useCallbackRef';
+export * from './useMediaQuery';
+export * from './useMergeRefs';

package/dist/types/src/types/component-meta.d.ts

@@ -0,0 +1,26 @@
+/** AI 에이전트용 컴포넌트 메타데이터 타입 */
+/** DES INDEX §3-1~§3-8 기준 카테고리 (commerce-rag design 네임스페이스) */
+export type ComponentCategory = 'action' | 'input' | 'icon' | 'overlay' | 'navigation' | 'feedback' | 'layout' | 'data-display';
+export interface ComponentMeta {
+    category: ComponentCategory;
+    aliases: string[];
+    hasChildren: boolean;
+    description: string;
+    whenToUse: string[];
+    forbiddenRules: string[];
+    seeAlso: string[];
+    jsRequired: boolean;
+    /** Props가 확장하는 HTML 요소 — 에이전트가 표준 HTML 속성 사용 가능 여부를 판단 */
+    htmlElement?: string;
+    /**
+     * render_to_html에 전달할 실제 사용 예시 props.
+     *
+     * 작성 규칙 (props-type-guide.md § usageExamples 참조):
+     * - key: 시나리오 이름 (예: "default", "withIcon", "rangePicker")
+     * - value: render_to_html의 props 파라미터에 그대로 전달 가능한 객체
+     * - 모든 required prop 포함 필수. optional은 시나리오에 필요한 것만.
+     * - 에이전트가 복사해서 바로 사용할 수 있는 수준의 실제 데이터.
+     * - 빈 문자열(""), 빈 객체({}) 금지. 의미 있는 값을 넣을 것.
+     */
+    usageExamples?: Record<string, Record<string, unknown>>;
+}

package/dist/types/src/types/dropdown/option.d.ts

@@ -1,13 +1,11 @@
+import type { SlotIconComponent } from '../side-slot';
 /**
  * 기본 옵션 타입
  */
 export type OptionType = {
     id: string | number;
     label: string;
-    icon?: React.ComponentType<{
-        width?: number;
-        height?: number;
-    }>;
+    icon?: SlotIconComponent;
 };
 /**
  * 옵션 값 타입 (단일 또는 다중 선택)

package/dist/types/src/types/side-slot.d.ts

@@ -1,12 +1,20 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { COLOR } from '../../constant/color';
 import type { DotProps } from '../components';
+/**
+ * 아이콘 컴포넌트 자리에 쓰이는 타입. MCP가 props 추출 시 이 타입의 정체성을 감지하여
+ * 문자열 이름을 실제 아이콘 컴포넌트로 치환할 수 있도록 nominal brand를 부착한다.
+ *
+ * 런타임 영향 없음 (브랜드 필드는 optional never, 실제로 할당할 수 없음).
+ */
 export type SlotIconComponent = ComponentType<{
     height?: number;
     width?: number;
     color?: string;
     className?: string;
-}>;
+}> & {
+    readonly __ncuaSlotIconBrand?: never;
+};
 export type IconSlotType = {
     type: 'icon';
     icon: SlotIconComponent;