@ncds/ui-admin 1.8.0 → 1.8.2

package/dist/temp/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/temp/src/components/progress-bar/index.js

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

package/dist/temp/src/components/select/Select.js

@@ -6,5 +6,5 @@ export const Select = forwardRef(({ placeholder, disabledPlaceholder = false, id
     return (_jsxs("span", { className: classNames('ncua-select', {
             destructive: destructive,
             'ncua-select--simple': type === 'simple',
-        }, className, `ncua-select--${size}`), children: [_jsx("span", { className: "ncua-select__content", children: _jsxs("select", { value: value, ref: ref, id: id, className: classNames('ncua-select__tag', className), disabled: disabled, ...register, ...props, children: [placeholder && (_jsx("option", { value: "", selected: true, disabled: disabledPlaceholder, children: placeholder })), optionItems?.map((item) => (_jsx("option", { value: item.id, children: item.label }, item.id))), children] }) }), hintText && (_jsx(HintText, { destructive: destructive, className: "ncua-hint-text", children: hintText }))] }));
+        }, className, `ncua-select--${size}`), children: [_jsx("span", { className: "ncua-select__content", children: _jsxs("select", { value: value, ref: ref, id: id, className: classNames('ncua-select__tag', className), disabled: disabled, ...register, ...props, children: [placeholder && (_jsx("option", { value: "", disabled: disabledPlaceholder, children: placeholder })), optionItems?.map((item) => (_jsx("option", { value: item.id, children: item.label }, item.id))), children] }) }), hintText && (_jsx(HintText, { destructive: destructive, className: "ncua-hint-text", children: hintText }))] }));
 });

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

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

package/dist/temp/src/components/select-dropdown/index.js

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

package/dist/temp/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/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/table/Table.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from 'react';
-import type { SortDirection, TableBodyProps, TableCellProps, TableColGroupProps, TableEmptyProps, TableFooterProps, TableHeaderProps, TablePaginationProps } from './types';
+import type { SortDirection, TableBodyProps, TableColGroupProps, TableEmptyProps, TableFooterProps, TableHeaderProps, TablePaginationProps } from './types';
 export declare const Table: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
     type?: import("./types").TableType | undefined;
     fixedHeader?: boolean | undefined;
@@ -25,7 +25,9 @@ export declare const Table: import("react").ForwardRefExoticComponent<Omit<impor
         onSort?: (() => void) | undefined;
         width?: string | number | undefined;
     } & import("react").RefAttributes<HTMLTableCellElement>>;
-    Cell: import("react").ForwardRefExoticComponent<TableCellProps & import("react").RefAttributes<HTMLTableCellElement>>;
+    Cell: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").TdHTMLAttributes<HTMLTableDataCellElement>, HTMLTableDataCellElement>, "ref"> & {
+        isHeader?: boolean | undefined;
+    } & import("react").RefAttributes<HTMLTableCellElement>>;
     Footer: {
         ({ children, className }: TableFooterProps): import("react/jsx-runtime").JSX.Element;
         displayName: string;

package/dist/temp/src/components/table/Table.js

@@ -1,8 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ChevronDown, ChevronSelectorVertical, ChevronUp } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
-import { Children, forwardRef } from 'react';
+import { Children, forwardRef, useEffect, useRef, } from 'react';
 // ──────────────────────────────────────────────
+// $table-header-height 와 동기화 — sticky thead가 차지하는 높이를 maxHeight에 보상
+const TABLE_HEADER_HEIGHT = 40;
+// 스크롤바 트랙 상하 여백 합계 (top 8px + bottom 8px) — SCSS &--fixed-header &__scrollbar 오프셋과 동기화
+const SCROLLBAR_TRACK_OFFSET = 16;
+const SCROLLBAR_THUMB_MIN_HEIGHT = 40;
 // Sort Icons (@ncds/ui-admin-icon)
 // ──────────────────────────────────────────────
 const SORT_ICONS = {
@@ -36,7 +41,12 @@ const HeaderCell = forwardRef(({ children, className, sortDirection, onSort, wid
         }), style: { ...style, width }, "aria-sort": isSortable ? ARIA_SORT_MAP[sortDirection] : undefined, onClick: isSortable ? onSort : undefined, ...rest, children: isSortable && SortIcon ? (_jsxs("span", { className: "ncua-table__header-cell-inner", children: [_jsx("span", { className: "ncua-table__header-cell-text", children: children }), _jsx("span", { className: "ncua-table__sort-icon", children: _jsx(SortIcon, { width: 16, height: 16 }) })] })) : (children) }));
 });
 HeaderCell.displayName = 'Table.HeaderCell';
-const Cell = forwardRef(({ children, className, ...rest }, ref) => (_jsx("td", { ref: ref, className: classNames('ncua-table__cell', className), ...rest, children: children })));
+const Cell = forwardRef(({ children, className, isHeader, ...rest }, ref) => {
+    if (isHeader) {
+        return (_jsx("th", { ref: ref, scope: "row", className: classNames('ncua-table__cell', className), ...rest, children: children }));
+    }
+    return (_jsx("td", { ref: ref, className: classNames('ncua-table__cell', className), ...rest, children: children }));
+});
 Cell.displayName = 'Table.Cell';
 const Footer = ({ children, className }) => (_jsx("div", { className: classNames('ncua-table__footer', className), children: children }));
 Footer.displayName = 'Table.Footer';
@@ -50,10 +60,9 @@ const ColGroup = ({ widths }) => {
             return `${width}px`;
         return width;
     };
-    return (_jsx("colgroup", { children: widths.map((width, index) => {
-            const duplicateCount = widths.slice(0, index).filter((v) => v === width).length;
-            return _jsx("col", { style: { width: resolveColWidth(width) } }, `col-${width}-${duplicateCount}`);
-        }) }));
+    return (_jsx("colgroup", { children: widths.map((width, index) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: colgroup columns never reorder or change
+        _jsx("col", { style: { width: resolveColWidth(width) } }, index))) }));
 };
 ColGroup.displayName = 'Table.ColGroup';
 const Empty = ({ colSpan, children }) => (_jsx("tr", { children: _jsx("td", { colSpan: colSpan, className: "ncua-table__empty", role: "status", "aria-live": "polite", children: children || '등록된 게시물이 없습니다.' }) }));
@@ -69,12 +78,24 @@ const categorizeChild = (child, result) => {
     else if (child.type === Pagination) {
         result.paginationContent.push(child);
     }
+    else if (child.type === Header) {
+        result.headerContent.push(child);
+    }
+    else if (child.type === ColGroup) {
+        result.colGroupContent.push(child);
+    }
     else {
         result.tableContent.push(child);
     }
 };
 const sortChildren = (children) => {
-    const result = { tableContent: [], footerContent: [], paginationContent: [] };
+    const result = {
+        headerContent: [],
+        colGroupContent: [],
+        tableContent: [],
+        footerContent: [],
+        paginationContent: [],
+    };
     Children.forEach(children, (child) => {
         categorizeChild(child, result);
     });
@@ -91,12 +112,75 @@ const TableComponent = forwardRef(({ type = 'horizontal', fixedHeader = false, m
         'ncua-table--hoverable': hoverable && type === 'horizontal',
         'ncua-table--selectable': selectable,
     });
-    const { tableContent, footerContent, paginationContent } = sortChildren(children);
+    const { headerContent, colGroupContent, tableContent, footerContent, paginationContent } = sortChildren(children);
     const scrollStyle = fixedHeader && maxHeight
-        ? { maxHeight: typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight }
+        ? {
+            maxHeight: typeof maxHeight === 'number'
+                ? `${maxHeight + TABLE_HEADER_HEIGHT}px`
+                : `calc(${maxHeight} + ${TABLE_HEADER_HEIGHT}px)`,
+        }
         : undefined;
-    const tableElement = (_jsx("table", { className: "ncua-table__table", role: "table", children: tableContent }));
-    return (_jsxs("div", { ref: ref, className: "ncua-table-wrapper", children: [_jsxs("div", { className: tableClasses, ...rest, children: [fixedHeader && maxHeight ? (_jsx("div", { className: "ncua-table__scroll-container", style: scrollStyle, children: tableElement })) : (tableElement), footerContent] }), paginationContent] }));
+    // Custom scrollbar refs (used only in fixed-header mode)
+    const scrollContainerRef = useRef(null);
+    const scrollAreaRef = useRef(null);
+    const thumbRef = useRef(null);
+    useEffect(() => {
+        if (!fixedHeader || !maxHeight)
+            return;
+        const scrollEl = scrollContainerRef.current;
+        const thumbEl = thumbRef.current;
+        if (!scrollEl || !thumbEl)
+            return;
+        const update = () => {
+            const { scrollTop, scrollHeight, clientHeight } = scrollEl;
+            if (scrollHeight <= clientHeight) {
+                thumbEl.style.height = '0';
+                return;
+            }
+            const trackHeight = (scrollAreaRef.current?.clientHeight ?? clientHeight) - TABLE_HEADER_HEIGHT - SCROLLBAR_TRACK_OFFSET;
+            const thumbHeight = Math.max(SCROLLBAR_THUMB_MIN_HEIGHT, (clientHeight / scrollHeight) * trackHeight);
+            const thumbTop = (scrollTop / (scrollHeight - clientHeight)) * (trackHeight - thumbHeight);
+            thumbEl.style.height = `${thumbHeight}px`;
+            thumbEl.style.transform = `translateY(${thumbTop}px)`;
+        };
+        scrollEl.addEventListener('scroll', update, { passive: true });
+        const observer = new ResizeObserver(update);
+        observer.observe(scrollEl);
+        update();
+        return () => {
+            scrollEl.removeEventListener('scroll', update);
+            observer.disconnect();
+        };
+    }, [fixedHeader, maxHeight]);
+    const handleThumbMouseDown = (e) => {
+        e.preventDefault();
+        const scrollEl = scrollContainerRef.current;
+        const thumbEl = thumbRef.current;
+        const areaEl = scrollAreaRef.current;
+        if (!scrollEl || !thumbEl)
+            return;
+        areaEl?.setAttribute('data-dragging', '');
+        const startY = e.clientY;
+        const startScrollTop = scrollEl.scrollTop;
+        const { scrollHeight, clientHeight } = scrollEl;
+        const thumbHeight = thumbEl.offsetHeight;
+        const scrollRatio = (scrollHeight - clientHeight) / (clientHeight - thumbHeight);
+        const onMove = (ev) => {
+            scrollEl.scrollTop = startScrollTop + (ev.clientY - startY) * scrollRatio;
+        };
+        const onUp = () => {
+            areaEl?.removeAttribute('data-dragging');
+            document.removeEventListener('mousemove', onMove);
+            document.removeEventListener('mouseup', onUp);
+        };
+        document.addEventListener('mousemove', onMove);
+        document.addEventListener('mouseup', onUp);
+    };
+    if (fixedHeader && maxHeight) {
+        return (_jsxs("div", { ref: ref, className: "ncua-table-wrapper", children: [_jsxs("div", { className: tableClasses, ...rest, children: [_jsxs("div", { ref: scrollAreaRef, className: "ncua-table__scroll-area", children: [_jsx("div", { ref: scrollContainerRef, className: "ncua-table__scroll-container", style: scrollStyle, children: _jsxs("table", { className: "ncua-table__table", role: "table", children: [colGroupContent, headerContent, tableContent] }) }), _jsx("div", { className: "ncua-table__scrollbar", "aria-hidden": "true", children: _jsx("div", { ref: thumbRef, className: "ncua-table__scrollbar-thumb", onMouseDown: handleThumbMouseDown }) })] }), footerContent] }), paginationContent] }));
+    }
+    const tableElement = (_jsxs("table", { className: "ncua-table__table", role: "table", children: [colGroupContent, headerContent, tableContent] }));
+    return (_jsxs("div", { ref: ref, className: "ncua-table-wrapper", children: [_jsxs("div", { className: tableClasses, ...rest, children: [tableElement, footerContent] }), paginationContent] }));
 });
 TableComponent.displayName = 'Table';
 // ──────────────────────────────────────────────

package/dist/temp/src/components/table/types.d.ts

@@ -27,7 +27,9 @@ export type TableHeaderCellProps = Omit<ComponentProps<'th'>, 'ref'> & {
     onSort?: () => void;
     width?: string | number;
 };
-export type TableCellProps = Omit<ComponentProps<'td'>, 'ref'>;
+export type TableCellProps = Omit<ComponentProps<'td'>, 'ref'> & {
+    isHeader?: boolean;
+};
 export type TableFooterProps = {
     children: ReactNode;
     className?: string;

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;
 };
 /**
  * 옵션 값 타입 (단일 또는 다중 선택)