@ncds/ui-admin 1.8.3 → 1.8.5

package/dist/temp/src/components/overlays/notification/FloatingNotification.js

@@ -1,56 +1,124 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { AlertCircle, AlertTriangle, CheckCircle, Pin02 } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
-import { forwardRef, useEffect, useRef, useState } from 'react';
+import { forwardRef, useEffect, useId, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
 import { MEDIA_QUERY } from '../../../constant/breakpoint';
 import { useMediaQuery } from '../../../hooks/useMediaQuery';
 import { Button } from '../../action/button';
 import { ButtonCloseX } from '../../action/button/ButtonCloseX';
 import { FeaturedIcon, } from '../../image-and-icons/featured-icon/FeaturedIcon';
+// 호스트 싱글톤은 vanilla/React 양쪽이 동일한 함수를 공유한다 — host.ts 가 가까운 진입점 역할을
+// 하므로 React 컴포넌트는 deep relative path 로 vanilla internals 를 직접 import 하지 않는다.
+import { mountFloatingNotificationHost } from './host';
+/**
+ * 색상별 a11y role.
+ *   - error/warning → role="alert"  (implicit aria-live="assertive": 즉시 발화)
+ *   - 그 외       → role="status" (implicit aria-live="polite": 현재 발화 끝난 후 발화)
+ * role 이 implicit live-region 을 가져오므로 호스트 컨테이너에는 aria-live 를 두지 않는다.
+ */
+const ASSERTIVE_COLORS = {
+    error: true,
+    warning: true,
+};
 const iconMap = {
     neutral: Pin02,
     error: AlertTriangle,
     warning: AlertCircle,
     success: CheckCircle,
-    // info는 floating에서는 지원하지 않음
+    // info 는 full-width 전용이라 floating 아이콘 매핑 없음.
+};
+/**
+ * NotificationColor → FeaturedIconColor 매핑.
+ * `info` 는 FeaturedIconColor 에 존재하지 않으므로 `neutral` 로 안전 fallback.
+ * `satisfies` 가 매핑 누락을 컴파일 타임에 강제하므로 향후 색상이 추가되면 즉시 타입 에러로 잡힌다.
+ */
+const iconColorMap = {
+    neutral: 'neutral',
+    error: 'error',
+    warning: 'warning',
+    success: 'success',
+    info: 'neutral',
 };
-const FloatingNotification = forwardRef(({ title, supportingText, color = 'neutral', onClose, className, actions, autoClose = 0, ...rest }, ref) => {
+/**
+ * `.ncua-floating-notification-host` 싱글톤을 보장하고 반환하는 훅.
+ *
+ * 이름의 `useMount...` 는 단순 조회가 아닌 **DOM 부수효과** 를 동반함을 신호한다 —
+ * 내부적으로 `mountFloatingNotificationHost()` 를 호출해 document.body 에 호스트를 append 하고
+ * (없으면) 글로벌 scroll/resize/MutationObserver 까지 부착한다. 호스트는 페이지 lifetime
+ * 싱글톤이므로 언마운트 시 제거하지 않는다.
+ *
+ * `mountFloatingNotificationHost` 는 **동기 함수** 이므로 effect 안의 호출 → setHost 가 같은 tick
+ * 에 끝나 cancellation race 가 없다. cancel flag 는 의미 없어 두지 않는다.
+ */
+function useMountFloatingNotificationHost(enabled) {
+    const [host, setHost] = useState(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        setHost(mountFloatingNotificationHost());
+    }, [enabled]);
+    return host;
+}
+const FloatingNotification = forwardRef(({ title, supportingText, color = 'neutral', onClose, className, actions, autoClose = 0, portal = false, ...rest }, ref) => {
     const [shouldRemove, setShouldRemove] = useState(false);
-    const iconColor = color;
     const featuredIconProps = {
         icon: iconMap[color] || Pin02,
         size: 'sm',
-        color: iconColor,
+        color: iconColorMap[color],
         theme: 'dark-circle',
     };
     const isMobile = useMediaQuery(MEDIA_QUERY.mobile, {
         onMatched: onClose,
     });
+    // onClose 는 매 렌더 새 함수 ref 일 수 있으므로 ref 로 latest 만 보관.
+    // → autoClose 타이머 effect 의 deps 에서 onClose 를 빼서 타이머 재시작 회피.
+    // render 본문에서 직접 할당 — useEffect 로 미루면 같은 commit 안에서 fire 되는 타이머가 stale onClose 를 볼 위험.
+    const onCloseRef = useRef(onClose);
+    onCloseRef.current = onClose;
     // autoClose 타이머 관리
     const timerRef = useRef(null);
+    // onClose 는 onCloseRef 로 latest 만 추적하므로 deps 에서 제외 (의도된 패턴).
     useEffect(() => {
-        // autoClose가 0보다 크면 무조건 타이머 설정
+        // autoClose 가 0 보다 크면 타이머 설정.
         if (autoClose > 0) {
             timerRef.current = setTimeout(() => {
-                if (onClose) {
-                    onClose();
-                }
-                // DOM에서 바로 제거
+                onCloseRef.current?.();
+                // DOM 에서 바로 제거
                 setShouldRemove(true);
             }, autoClose);
         }
-        // cleanup 함수: 컴포넌트 언마운트 시 타이머 정리
+        // cleanup: 컴포넌트 언마운트 또는 autoClose 변경 시 타이머 정리
         return () => {
             if (timerRef.current) {
                 clearTimeout(timerRef.current);
                 timerRef.current = null;
             }
         };
-    }, [autoClose, onClose]);
+    }, [autoClose]);
+    // portal=true 일 때만 호스트가 필요하다.
+    const host = useMountFloatingNotificationHost(portal);
+    // a11y — 카드 root 의 role 과 제목/본문 ID. 색상에 따라 alert(error/warning) / status(나머지) 로 분기.
+    const reactId = useId();
+    const titleId = `${reactId}-title`;
+    const descId = `${reactId}-desc`;
+    const role = ASSERTIVE_COLORS[color] ? 'alert' : 'status';
     // DOM에서 완전히 제거
     if (shouldRemove) {
         return null;
     }
-    return (_jsxs("div", { ref: ref, className: classNames('ncua-floating-notification', `ncua-floating-notification--${color}`, className), role: "alert", ...rest, children: [_jsx("div", { className: "ncua-floating-notification__content", children: _jsxs("div", { className: "ncua-floating-notification__container", children: [iconMap[color] && _jsx(FeaturedIcon, { ...featuredIconProps, size: isMobile ? 'md' : 'sm' }), _jsxs("div", { className: "ncua-floating-notification__text-container", children: [_jsx("div", { className: "ncua-floating-notification__title-wrapper", children: _jsx("span", { className: "ncua-floating-notification__title", children: title }) }), supportingText && _jsx("span", { className: "ncua-floating-notification__supporting-text", children: supportingText }), actions && (_jsx("div", { className: "ncua-floating-notification__actions", children: actions.map((action) => (_jsx(Button, { size: "xs", hierarchy: action.hierarchy || 'text', label: action.label, onClick: action?.onClick }, `${action.label}-${action.hierarchy}`))) }))] })] }) }), onClose && (_jsx(ButtonCloseX, { theme: "light", className: "ncua-floating-notification__close-button", size: isMobile ? 'sm' : 'xs', onClick: onClose }))] }));
+    const card = (
+    // a11y/예측가능성 — caller 가 className/id 등 일부는 덮어쓸 수 있게 {...rest} 를 먼저 펼치고,
+    // role/aria-labelledby/aria-describedby 같은 컴포넌트 본질 prop 은 그 뒤에 두어 우선 적용.
+    _jsxs("div", { ...rest, ref: ref, className: classNames('ncua-floating-notification', `ncua-floating-notification--${color}`, className), role: role, "aria-labelledby": titleId, "aria-describedby": supportingText ? descId : undefined, children: [_jsx("div", { className: "ncua-floating-notification__content", children: _jsxs("div", { className: "ncua-floating-notification__container", children: [iconMap[color] && _jsx(FeaturedIcon, { ...featuredIconProps, size: isMobile ? 'md' : 'sm' }), _jsxs("div", { className: "ncua-floating-notification__text-container", children: [_jsx("div", { className: "ncua-floating-notification__title-wrapper", children: _jsx("span", { id: titleId, className: "ncua-floating-notification__title", children: title }) }), supportingText && (_jsx("span", { id: descId, className: "ncua-floating-notification__supporting-text", children: supportingText })), actions && (_jsx("div", { className: "ncua-floating-notification__actions", children: actions.map((action) => (_jsx(Button, { size: "xs", hierarchy: action.hierarchy || 'text', label: action.label, onClick: action?.onClick }, `${action.label}-${action.hierarchy}`))) }))] })] }) }), onClose && (_jsx(ButtonCloseX, { theme: "light", className: "ncua-floating-notification__close-button", size: isMobile ? 'sm' : 'xs', onClick: onClose }))] }));
+    // 기본은 인라인 렌더 — 부모 JSX 트리에 카드를 그대로 둔다.
+    if (!portal) {
+        return card;
+    }
+    // portal=true 인데 SSR이거나 첫 렌더(호스트 미생성)에서는 null. useEffect 후 host 설정되면 재렌더되어 portal 마운트.
+    if (!host) {
+        return null;
+    }
+    return createPortal(card, host);
 });
 export { FloatingNotification };

package/dist/temp/src/components/overlays/notification/Notification.d.ts

@@ -2,7 +2,8 @@ import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
 import type { ColorTone } from '../../../../constant/color';
 import type { SlotIconComponent } from '../../../types/side-slot';
 import type { ButtonTheme } from '../../action/button';
-type NotificationType = 'floating' | 'full-width' | 'message';
+import { type CalloutNotificationProps } from './CalloutNotification';
+type NotificationType = 'floating' | 'full-width' | 'message' | 'callout';
 type NotificationColor = Extract<ColorTone, 'neutral' | 'error' | 'warning' | 'success' | 'info'>;
 type NotificationSize = 'desktop' | 'mobile';
 interface NotificationAction {
@@ -26,9 +27,9 @@ interface NotificationProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title
      */
     type?: NotificationType;
     /**
-     * 알림 제목 텍스트
+     * 알림 제목 텍스트 (callout 유형에서는 안내 텍스트로 사용)
      */
-    title: ReactNode;
+    title?: ReactNode;
     /**
      * 알림 본문 텍스트 (선택사항)
      */
@@ -66,7 +67,21 @@ interface NotificationProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title
      * message, full-width 타입에서 사용 가능
      */
     onHidePermanently?: () => void;
+    /**
+     * Portal 마운트 여부. `floating` 타입에서만 동작한다.
+     *
+     * 기본값 `false`에서는 부모 JSX 트리 안에 카드로 그대로 렌더된다.
+     * `true`로 설정하면 자동으로 document.body의 `.ncua-floating-notification-host`
+     * 호스트에 createPortal로 마운트되어 우측 상단에 노출되고 LIFO로 스택된다
+     * — 최신 토스트가 상단에 노출되고 이전 토스트들이 아래로 12px씩 겹쳐 쌓인다
+     * (vanilla `Notification.show()`와 동일, `--ncua-floating-notification-stack-overlap`
+     * 변수로 조정 가능).
+     *
+     * @default false
+     */
+    portal?: boolean;
 }
 declare const Notification: import("react").ForwardRefExoticComponent<NotificationProps & import("react").RefAttributes<HTMLDivElement>>;
 export type { NotificationType, NotificationColor, NotificationSize, NotificationAction, NotificationProps };
+export type { CalloutNotificationProps };
 export { Notification };

package/dist/temp/src/components/overlays/notification/Notification.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from 'react';
+import { CalloutNotification } from './CalloutNotification';
 import { FloatingNotification } from './FloatingNotification';
 import { FullWidthNotification } from './FullWidthNotification';
 import { MessageNotification } from './MessageNotification';
@@ -13,6 +14,9 @@ const Notification = forwardRef(({ type = 'floating', color = 'neutral', ...rest
     if (type === 'message') {
         return _jsx(MessageNotification, { color: color, ...rest, ref: ref });
     }
+    if (type === 'callout') {
+        return _jsx(CalloutNotification, { color: color, ...rest });
+    }
     return null;
 });
 Notification.displayName = 'Notification';

package/dist/temp/src/components/overlays/notification/host.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Floating Notification 호스트 관리 — React 측 진입점.
+ *
+ * 실제 구현은 vanilla/React 가 공유하는 `assets/scripts/notification/positionSync.ts` 에 있고,
+ * 외부 노출은 그 폴더의 public barrel(`assets/scripts/notification/index.ts`)이 담당한다.
+ * 이 모듈은 React 컴포넌트가 vanilla 내부 파일을 직접 참조하지 않도록 barrel 을 경유하는
+ * 한 단계 re-export 만 제공한다 — positionSync.ts 의 위치/이름이 바뀌어도 host.ts 만 영향.
+ */
+export { mountFloatingNotificationHost } from '../../../../assets/scripts/notification';

package/dist/temp/src/components/overlays/notification/host.js

@@ -0,0 +1,9 @@
+/**
+ * Floating Notification 호스트 관리 — React 측 진입점.
+ *
+ * 실제 구현은 vanilla/React 가 공유하는 `assets/scripts/notification/positionSync.ts` 에 있고,
+ * 외부 노출은 그 폴더의 public barrel(`assets/scripts/notification/index.ts`)이 담당한다.
+ * 이 모듈은 React 컴포넌트가 vanilla 내부 파일을 직접 참조하지 않도록 barrel 을 경유하는
+ * 한 단계 re-export 만 제공한다 — positionSync.ts 의 위치/이름이 바뀌어도 host.ts 만 영향.
+ */
+export { mountFloatingNotificationHost } from '../../../../assets/scripts/notification';

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

@@ -12,6 +12,10 @@ interface TooltipProps {
     iconColor?: string;
     iconStyle?: 'help-circle' | 'alert-circle';
     zIndex?: number;
+    /** 외부에서 직접 패널 표시 여부를 제어 */
+    forceVisible?: boolean;
+    /** true이면 Portal 없이 앵커 내부에 패널을 인라인 렌더링. CSS 기반 위치 지정이 필요한 경우 사용 */
+    disablePortal?: boolean;
 }
-export declare const Tooltip: ({ tooltipType, iconType, position, size, title, content, hideArrow, type, iconColor, iconStyle, className, zIndex, }: TooltipProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Tooltip: ({ tooltipType, iconType, position, size, title, content, hideArrow, type, iconColor, iconStyle, className, zIndex, forceVisible, disablePortal, }: TooltipProps) => import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { AlertCircle, AlertCircleFill, HelpCircle, HelpCircleFill } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
@@ -74,7 +74,19 @@ const computePanelCoords = (prefer, anchor, panel) => {
     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, zIndex, }) => {
+const buildPanelStyle = (disablePortal, coords, visible, zIndex) => {
+    const opacity = visible ? 1 : 0;
+    if (disablePortal)
+        return { opacity };
+    return { top: `${coords.top}px`, left: `${coords.left}px`, opacity, ...(zIndex && { zIndex }) };
+};
+const renderIcon = (iconStyle, iconType, iconSize, iconColor) => {
+    if (iconStyle === 'help-circle') {
+        return iconType === 'stroke' ? (_jsx(HelpCircle, { width: iconSize, height: iconSize, color: iconColor })) : (_jsx(HelpCircleFill, { width: iconSize, height: iconSize, color: iconColor }));
+    }
+    return iconType === 'stroke' ? (_jsx(AlertCircle, { width: iconSize, height: iconSize, color: iconColor })) : (_jsx(AlertCircleFill, { width: iconSize, height: iconSize, color: iconColor }));
+};
+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, forceVisible, disablePortal = false, }) => {
     const iconSize = size === 'sm' ? ICON_SIZE_SM : ICON_SIZE_DEFAULT;
     const anchorRef = useRef(null);
     const panelRef = useRef(null);
@@ -84,6 +96,7 @@ export const Tooltip = ({ tooltipType = 'white', iconType = 'stroke', position =
     const [calculatedPosition, setCalculatedPosition] = useState(position === 'auto' ? 'bottom' : position);
     const [isVisible, setIsVisible] = useState(false);
     const [isManuallyClose, setIsManuallyClose] = useState(false);
+    const effectiveVisible = forceVisible ?? isVisible;
     useEffect(() => {
         setMounted(true);
         return () => {
@@ -94,16 +107,16 @@ export const Tooltip = ({ tooltipType = 'white', iconType = 'stroke', position =
         };
     }, []);
     const updatePosition = useCallback(() => {
-        if (!anchorRef.current || !panelRef.current)
+        if (disablePortal || !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]);
+    }, [position, disablePortal]);
     useEffect(() => {
-        if (!isVisible)
+        if (!effectiveVisible || disablePortal)
             return;
         updatePosition();
         window.addEventListener('resize', updatePosition, { passive: true });
@@ -112,14 +125,11 @@ export const Tooltip = ({ tooltipType = 'white', iconType = 'stroke', position =
             window.removeEventListener('resize', updatePosition);
             window.removeEventListener('scroll', updatePosition, { capture: true });
         };
-    }, [isVisible, updatePosition]);
+    }, [effectiveVisible, updatePosition, disablePortal]);
     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(() => {
@@ -144,19 +154,12 @@ 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 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--force-hidden': isManuallyClose,
-    }), [tooltipType, finalPosition, isVisible, isManuallyClose]);
-    const panelStyle = {
-        top: `${coords.top}px`,
-        left: `${coords.left}px`,
-        opacity: isVisible ? 1 : 0,
-        ...(zIndex && { zIndex }),
-    };
+    const panelClassName = useMemo(() => classNames({ 'ncua-tooltip-panel': !disablePortal }, 'ncua-tooltip__bg', `ncua-tooltip__bg--${tooltipType}`, `ncua-tooltip__bg--${finalPosition}`, {
+        'ncua-tooltip__bg--visible': effectiveVisible,
+        'ncua-tooltip__bg--force-hidden': isManuallyClose && !forceVisible,
+    }), [tooltipType, finalPosition, effectiveVisible, isManuallyClose, forceVisible, disablePortal]);
+    const panelStyle = buildPanelStyle(disablePortal, coords, effectiveVisible, 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)] }));
+    return (_jsxs("span", { ref: anchorRef, className: tooltipClassName, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: [renderIcon(iconStyle, iconType, iconSize, iconColor), disablePortal ? panel : portalTarget && createPortal(panel, portalTarget)] }));
 };

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

@@ -17,6 +17,12 @@ type SelectDropdownProps = ComponentPropsWithRef<'div'> & {
     multiple?: boolean;
     showFooterButtons?: boolean;
     selectAllButtonText?: string;
+    /**
+     * footer의 "전체 선택" Link 노출 여부 (default: `true`).
+     * footer 자체(편집/선택 완료 버튼)는 영향받지 않는다.
+     * 호출자가 도메인 조건(예: 최대 선택 개수 제한)에 따라 `false`로 내리면 Link만 숨겨진다.
+     */
+    showSelectAllAction?: boolean;
     onSelectAll?: () => void;
     onEdit?: () => void;
     onComplete?: () => void;

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

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import classNames from 'classnames';
 import { forwardRef } from 'react';
 import { Button } from '../action/button';
-const SelectDropdown = forwardRef(({ isOpen, direction = 'down', size = 'xs', options, value, focusedIndex, maxHeight, listboxId = 'selectbox-options-default', onOptionSelect, onMouseMove, isKeyboardNavigation, onOptionHover, children, multiple = false, showFooterButtons = false, selectAllButtonText = '전체 선택', onSelectAll, onEdit, onComplete, className, activeDescendantId, componentType, align = 'left', ...props }, ref) => {
+const SelectDropdown = forwardRef(({ isOpen, direction = 'down', size = 'xs', options, value, focusedIndex, maxHeight, listboxId = 'selectbox-options-default', onOptionSelect, onMouseMove, isKeyboardNavigation, onOptionHover, children, multiple = false, showFooterButtons = false, selectAllButtonText = '전체 선택', showSelectAllAction = true, onSelectAll, onEdit, onComplete, className, activeDescendantId, componentType, align = 'left', ...props }, ref) => {
     if (!isOpen)
         return null;
     return (_jsxs("div", { ref: ref, className: classNames('ncua-select-dropdown', `ncua-select-dropdown--${direction}`, `ncua-select-dropdown--${size}`, {
@@ -20,7 +20,7 @@ const SelectDropdown = forwardRef(({ isOpen, direction = 'down', size = 'xs', op
                                     'ncua-select-dropdown__option--selected': isSelected,
                                     'ncua-select-dropdown__option--focused': isFocused,
                                 }), onClick: () => onOptionSelect(option), onMouseEnter: handleMouseEnter, role: "option", "aria-selected": isSelected, children: [option.icon && (_jsx("span", { className: "ncua-select-dropdown__option-icon", children: _jsx(option.icon, { width: 16, height: 16 }) })), _jsx("span", { className: "ncua-select-dropdown__option-text", children: option.label })] }, option.id));
-                        }), children] }) }), showFooterButtons && (_jsx("div", { className: "ncua-select-dropdown__footer", children: _jsxs("div", { className: "ncua-select-dropdown__footer-buttons", children: [_jsx("div", { className: "ncua-select-dropdown__footer-left", children: multiple && (_jsx(Button, { label: selectAllButtonText, hierarchy: "text", size: "xs", onClick: onSelectAll, underline: true })) }), _jsxs("div", { className: "ncua-select-dropdown__footer-right", children: [_jsx(Button, { label: "\uD3B8\uC9D1", hierarchy: "secondary-gray", size: "xs", onClick: onEdit }), multiple && _jsx(Button, { label: "\uC120\uD0DD \uC644\uB8CC", hierarchy: "secondary", size: "xs", onClick: onComplete })] })] }) }))] }));
+                        }), children] }) }), showFooterButtons && (_jsx("div", { className: "ncua-select-dropdown__footer", children: _jsxs("div", { className: "ncua-select-dropdown__footer-buttons", children: [_jsx("div", { className: "ncua-select-dropdown__footer-left", children: multiple && showSelectAllAction && (_jsx(Button, { label: selectAllButtonText, hierarchy: "text", size: "xs", onClick: onSelectAll, underline: true })) }), _jsxs("div", { className: "ncua-select-dropdown__footer-right", children: [_jsx(Button, { label: "\uD3B8\uC9D1", hierarchy: "secondary-gray", size: "xs", onClick: onEdit }), multiple && _jsx(Button, { label: "\uC120\uD0DD \uC644\uB8CC", hierarchy: "secondary", size: "xs", onClick: onComplete })] })] }) }))] }));
 });
 SelectDropdown.displayName = 'SelectDropdown';
 export { SelectDropdown };

package/dist/temp/src/contexts/FloatingContext.d.ts

@@ -0,0 +1,6 @@
+export type FloatingContextValue = {
+    preferPortal: boolean;
+    portalContainer?: HTMLElement | null;
+};
+export declare const FloatingProvider: import("react").Provider<FloatingContextValue | null>;
+export declare const useFloatingContext: () => FloatingContextValue | null;

package/dist/temp/src/contexts/FloatingContext.js

@@ -0,0 +1,4 @@
+import { createContext, useContext } from 'react';
+const FloatingContext = createContext(null);
+export const FloatingProvider = FloatingContext.Provider;
+export const useFloatingContext = () => useContext(FloatingContext);

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

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

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

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

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

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

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

@@ -2,5 +2,6 @@
 // 드롭다운 관련 hooks
 export * from './dropdown';
 export * from './useCallbackRef';
+export * from './useFloatingPosition';
 export * from './useMediaQuery';
 export * from './useMergeRefs';

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

@@ -0,0 +1,19 @@
+import { type CSSProperties, type RefObject } from 'react';
+type FloatingDirection = 'up' | 'down';
+type UseFloatingPositionParams = {
+    enabled: boolean;
+    isOpen: boolean;
+    triggerRef: RefObject<HTMLElement | null>;
+    floatingRef: RefObject<HTMLElement | null>;
+    direction: FloatingDirection;
+    offset?: number;
+    align?: 'left' | 'right';
+    /**
+     * true면 floating 요소의 width를 trigger 너비에 맞춘다.
+     * Portal 모드에서 부모가 body로 바뀌면서 min-width: 100% 같은 CSS가 viewport 너비로
+     * 폭주하는 것을 막는다 (예: SelectBox 옵션 패널).
+     */
+    matchTriggerWidth?: boolean;
+};
+export declare const useFloatingPosition: ({ enabled, isOpen, triggerRef, floatingRef, direction, offset, align, matchTriggerWidth, }: UseFloatingPositionParams) => CSSProperties | null;
+export {};

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

@@ -0,0 +1,55 @@
+import { useLayoutEffect, useState } from 'react';
+const FLOATING_Z_INDEX = 1500;
+export const useFloatingPosition = ({ enabled, isOpen, triggerRef, floatingRef, direction, offset = 4, align = 'left', matchTriggerWidth = false, }) => {
+    const [style, setStyle] = useState(null);
+    useLayoutEffect(() => {
+        if (!enabled || !isOpen) {
+            setStyle(null);
+            return;
+        }
+        const trigger = triggerRef.current;
+        if (!trigger)
+            return;
+        const calculatePosition = (trigger, floatingHeight, floatingWidth) => {
+            const top = direction === 'up' ? trigger.top - floatingHeight - offset : trigger.bottom + offset;
+            const left = align === 'right' ? trigger.right - floatingWidth : trigger.left;
+            return { top, left };
+        };
+        const update = () => {
+            const t = triggerRef.current;
+            const f = floatingRef.current;
+            if (!t)
+                return;
+            const r = t.getBoundingClientRect();
+            const floatingHeight = f?.offsetHeight ?? 0;
+            const floatingWidth = matchTriggerWidth ? r.width : (f?.offsetWidth ?? r.width);
+            const { top, left } = calculatePosition(r, floatingHeight, floatingWidth);
+            // matchTriggerWidth=true: width는 max-content(콘텐츠 자연 너비), min-width만 trigger 너비로 보장.
+            // 옵션이 짧으면 trigger 너비, 길면 자연 확장 — 기존 absolute 모드와 동일한 UX.
+            setStyle({
+                position: 'fixed',
+                top,
+                left,
+                zIndex: FLOATING_Z_INDEX,
+                ...(matchTriggerWidth ? { minWidth: r.width } : {}),
+            });
+        };
+        update();
+        window.addEventListener('scroll', update, true);
+        window.addEventListener('resize', update);
+        const triggerObserver = new ResizeObserver(update);
+        triggerObserver.observe(trigger);
+        let floatingObserver;
+        if (floatingRef.current) {
+            floatingObserver = new ResizeObserver(update);
+            floatingObserver.observe(floatingRef.current);
+        }
+        return () => {
+            window.removeEventListener('scroll', update, true);
+            window.removeEventListener('resize', update);
+            triggerObserver.disconnect();
+            floatingObserver?.disconnect();
+        };
+    }, [enabled, isOpen, direction, offset, align, matchTriggerWidth, triggerRef, floatingRef]);
+    return style;
+};

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

@@ -0,0 +1,6 @@
+type UsePortalStateResult = {
+    shouldPortal: boolean;
+    portalContainer: HTMLElement | null;
+};
+export declare const usePortalState: (usePortalProp?: boolean) => UsePortalStateResult;
+export {};

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

@@ -0,0 +1,7 @@
+import { useFloatingContext } from '../contexts/FloatingContext';
+export const usePortalState = (usePortalProp) => {
+    const floatingContext = useFloatingContext();
+    const shouldPortal = usePortalProp ?? floatingContext?.preferPortal ?? false;
+    const portalContainer = floatingContext?.portalContainer ?? (typeof document !== 'undefined' ? document.body : null);
+    return { shouldPortal, portalContainer };
+};

package/dist/temp/src/utils/dropdown/maxSelection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SelectBox / ComboBox 공통 — 최대 선택 개수 제한 활성 여부 판정.
+ *
+ * React 훅(`useMultiSelect`)과 vanilla 드롭다운(`DropdownModel`)가 동일 로직을 공유하므로
+ * 두 곳에 정의가 갈라지지 않도록 단일 source-of-truth로 둔다.
+ *
+ * **계약**
+ * - `0` 이상의 정수 → 활성 (단, `0`은 모든 새 선택을 차단하는 의미)
+ * - 음수 / 비정수 / `undefined` / `null` → 비활성 (제한 없는 것과 동일)
+ *
+ * `0`을 활성으로 보는 이유: 호출자가 `maxSelection={0}`을 명시적으로 전달했을 때
+ * "선택 자체를 막겠다"는 의도로 해석하기 위함. 음수는 일반적으로 "값 없음"의 sentinel이므로 비활성.
+ */
+export declare const isMaxSelectionLimitActive: (maxSelection?: number | null) => maxSelection is number;
+/**
+ * 현재 선택 길이가 최대치에 도달했는지 단일 함수로 판정.
+ *
+ * 호출 측에서 `>=`을 직접 작성하지 않도록 의미를 노출하고, type predicate가 내부에서 적용되어
+ * `maxSelection`의 narrowing이 보장된다 (외부 predicate 호출로 인한 narrowing 누락 방지).
+ *
+ * - 제한 비활성(음수 / null / undefined / 비정수): 항상 `false`.
+ * - 활성: `currentLength >= maxSelection`.
+ */
+export declare const isMaxSelectionReached: (currentLength: number, maxSelection?: number | null) => boolean;

package/dist/temp/src/utils/dropdown/maxSelection.js

@@ -0,0 +1,28 @@
+/**
+ * SelectBox / ComboBox 공통 — 최대 선택 개수 제한 활성 여부 판정.
+ *
+ * React 훅(`useMultiSelect`)과 vanilla 드롭다운(`DropdownModel`)가 동일 로직을 공유하므로
+ * 두 곳에 정의가 갈라지지 않도록 단일 source-of-truth로 둔다.
+ *
+ * **계약**
+ * - `0` 이상의 정수 → 활성 (단, `0`은 모든 새 선택을 차단하는 의미)
+ * - 음수 / 비정수 / `undefined` / `null` → 비활성 (제한 없는 것과 동일)
+ *
+ * `0`을 활성으로 보는 이유: 호출자가 `maxSelection={0}`을 명시적으로 전달했을 때
+ * "선택 자체를 막겠다"는 의도로 해석하기 위함. 음수는 일반적으로 "값 없음"의 sentinel이므로 비활성.
+ */
+export const isMaxSelectionLimitActive = (maxSelection) => typeof maxSelection === 'number' && Number.isInteger(maxSelection) && maxSelection >= 0;
+/**
+ * 현재 선택 길이가 최대치에 도달했는지 단일 함수로 판정.
+ *
+ * 호출 측에서 `>=`을 직접 작성하지 않도록 의미를 노출하고, type predicate가 내부에서 적용되어
+ * `maxSelection`의 narrowing이 보장된다 (외부 predicate 호출로 인한 narrowing 누락 방지).
+ *
+ * - 제한 비활성(음수 / null / undefined / 비정수): 항상 `false`.
+ * - 활성: `currentLength >= maxSelection`.
+ */
+export const isMaxSelectionReached = (currentLength, maxSelection) => {
+    if (!isMaxSelectionLimitActive(maxSelection))
+        return false;
+    return currentLength >= maxSelection;
+};

package/dist/temp/src/utils/dropdown/multiSelect.d.ts

@@ -19,13 +19,53 @@ export declare const getSelectedTags: (selectedValues: (string | number)[], opti
  * 태그 제거 시 선택값에서 해당 ID를 제거하는 유틸 함수
  */
 export declare const removeTagFromSelected: (selectedValues: (string | number)[], tagIdToRemove: string | number) => (string | number)[];
+export interface UseMultiSelectOptions {
+    /** 전체 선택 버튼의 라벨 (default: '전체 선택') */
+    selectText?: string;
+    /** 전체 해제 버튼의 라벨 (default: '전체 해제') */
+    deselectText?: string;
+    /**
+     * 최대 선택 가능 개수 (선택).
+     *  - `0` 이상의 정수: 제한 활성 (`isMaxSelectionActive: true`).
+     *    - `0`은 모든 새 선택을 차단한다 (이미 선택된 항목 해제는 정상 동작).
+     *    - 양수는 해당 개수 도달 후 추가 선택을 무시한다.
+     *  - 음수 / 비정수 / `null` / `undefined`: 제한 없음.
+     */
+    maxSelection?: number | null;
+}
 /**
- * 전체 선택 관련 로직을 한 번에 처리하는 커스텀 훅
+ * 최대 선택 개수 관련 응집을 별도 훅으로 분리.
+ *
+ * - `isMaxSelectionActive`: 제한 활성 여부.
+ * - `isMaxReached`: 현재 선택 길이가 최대치에 도달했는지.
+ * - `canAdd(currentLength)`: 새 항목 추가가 허용되는지 (도달 시 `false`).
+ *
+ * 도메인 규칙(`>=` 비교 등)을 외부로 노출하지 않고 헬퍼를 통해 의미만 반환한다.
+ * `useMultiSelect`가 내부에서 사용하지만, 단독으로도 필요한 호출자가 쓸 수 있게 export한다.
  */
-export declare const useMultiSelect: (selectedValues: (string | number)[], options: MultiSelectOption[], selectText?: string, deselectText?: string) => {
+export declare const useMaxSelection: (selectedValues: (string | number)[], maxSelection?: number | null) => {
+    isMaxSelectionActive: boolean;
+    isMaxReached: boolean;
+    canAdd: (currentLength: number) => boolean;
+};
+/**
+ * 전체 선택 관련 로직을 한 번에 처리하는 커스텀 훅.
+ *
+ * 시그니처는 호출자가 maxSelection만 지정하더라도 텍스트 라벨을 건너뛰지 않도록 옵션 객체로 받는다.
+ *
+ * **반환의 `tryToggle`**: multiple 토글 결과를 직접 돌려준다.
+ *  - 새 배열 반환: 정상 토글 (추가 또는 해제).
+ *  - `null` 반환: 최대 개수 도달로 추가가 차단됨 (호출자는 변경 없이 종료해야 함).
+ *
+ * 호출자가 `>= maxSelection` 같은 도메인 규칙을 직접 검사하지 않도록 결과만 노출한다.
+ */
+export declare const useMultiSelect: (selectedValues: (string | number)[], options: MultiSelectOption[], config?: UseMultiSelectOptions) => {
     isAllSelected: boolean;
     buttonText: string;
     toggleSelectAll: () => (string | number)[];
     getSelectedTagsData: () => SelectedTag[];
     removeTag: (tagId: string | number) => (string | number)[];
+    isMaxSelectionActive: boolean;
+    isMaxReached: boolean;
+    tryToggle: (optionId: string | number, currentArray: (string | number)[] | undefined) => (string | number)[] | null;
 };