@ncds/ui-admin 1.8.3 → 1.8.5

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

@@ -1,19 +1,64 @@
 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'
 };
+/**
+ * `.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 = /*#__PURE__*/forwardRef((_ref, ref) => {
   let {
     title,
@@ -23,49 +68,65 @@ const FloatingNotification = /*#__PURE__*/forwardRef((_ref, ref) => {
     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", {
+  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: "alert",
-    ...rest,
+    role: role,
+    "aria-labelledby": titleId,
+    "aria-describedby": supportingText ? descId : undefined,
     children: [_jsx("div", {
       className: "ncua-floating-notification__content",
       children: _jsxs("div", {
@@ -78,10 +139,12 @@ const FloatingNotification = /*#__PURE__*/forwardRef((_ref, ref) => {
           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", {
@@ -102,5 +165,14 @@ const FloatingNotification = /*#__PURE__*/forwardRef((_ref, ref) => {
       onClick: onClose
     })]
   });
+  // 기본은 인라인 렌더 — 부모 JSX 트리에 카드를 그대로 둔다.
+  if (!portal) {
+    return card;
+  }
+  // portal=true 인데 SSR이거나 첫 렌더(호스트 미생성)에서는 null. useEffect 후 host 설정되면 재렌더되어 portal 마운트.
+  if (!host) {
+    return null;
+  }
+  return /*#__PURE__*/createPortal(card, host);
 });
 export { FloatingNotification };

package/dist/esm/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';
@@ -30,6 +31,12 @@ const Notification = /*#__PURE__*/forwardRef((_ref, ref) => {
       ref: ref
     });
   }
+  if (type === 'callout') {
+    return _jsx(CalloutNotification, {
+      color: color,
+      ...rest
+    });
+  }
   return null;
 });
 Notification.displayName = 'Notification';

package/dist/esm/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/esm/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';
@@ -70,6 +70,42 @@ const computePanelCoords = (prefer, anchor, panel) => {
     calculatedPosition
   };
 };
+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 = _ref => {
   let {
     tooltipType = 'white',
@@ -83,7 +119,9 @@ export const Tooltip = _ref => {
     iconColor = 'var(--gray-300)',
     iconStyle = 'help-circle',
     className,
-    zIndex
+    zIndex,
+    forceVisible,
+    disablePortal = false
   } = _ref;
   const iconSize = size === 'sm' ? ICON_SIZE_SM : ICON_SIZE_DEFAULT;
   const anchorRef = useRef(null);
@@ -97,6 +135,7 @@ export const Tooltip = _ref => {
   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 () => {
@@ -107,7 +146,7 @@ export const Tooltip = _ref => {
     };
   }, []);
   const updatePosition = useCallback(() => {
-    if (!anchorRef.current || !panelRef.current) return;
+    if (disablePortal || !anchorRef.current || !panelRef.current) return;
     const anchor = anchorRef.current.getBoundingClientRect();
     const panel = panelRef.current.getBoundingClientRect();
     const next = computePanelCoords(position, anchor, panel);
@@ -116,9 +155,9 @@ export const Tooltip = _ref => {
       left: next.left
     });
     setCalculatedPosition(next.calculatedPosition);
-  }, [position]);
+  }, [position, disablePortal]);
   useEffect(() => {
-    if (!isVisible) return;
+    if (!effectiveVisible || disablePortal) return;
     updatePosition();
     window.addEventListener('resize', updatePosition, {
       passive: true
@@ -133,13 +172,10 @@ export const Tooltip = _ref => {
         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(() => {
       rafIdRef.current = null;
@@ -163,18 +199,13 @@ export const Tooltip = _ref => {
     '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,
@@ -194,29 +225,11 @@ export const Tooltip = _ref => {
       "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 && /*#__PURE__*/createPortal(panel, portalTarget)]
+  return _jsxs("span", {
+    ref: anchorRef,
+    className: tooltipClassName,
+    onMouseEnter: handleMouseEnter,
+    onMouseLeave: handleMouseLeave,
+    children: [renderIcon(iconStyle, iconType, iconSize, iconColor), disablePortal ? panel : portalTarget && /*#__PURE__*/createPortal(panel, portalTarget)]
   });
 };

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

@@ -20,6 +20,7 @@ const SelectDropdown = /*#__PURE__*/forwardRef((_ref, ref) => {
     multiple = false,
     showFooterButtons = false,
     selectAllButtonText = '전체 선택',
+    showSelectAllAction = true,
     onSelectAll,
     onEdit,
     onComplete,
@@ -85,7 +86,7 @@ const SelectDropdown = /*#__PURE__*/forwardRef((_ref, ref) => {
         className: "ncua-select-dropdown__footer-buttons",
         children: [_jsx("div", {
           className: "ncua-select-dropdown__footer-left",
-          children: multiple && _jsx(Button, {
+          children: multiple && showSelectAllAction && _jsx(Button, {
             label: selectAllButtonText,
             hierarchy: "text",
             size: "xs",

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

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

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

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

package/dist/esm/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/esm/src/hooks/useFloatingPosition.js

@@ -0,0 +1,71 @@
+import { useLayoutEffect, useState } from 'react';
+const FLOATING_Z_INDEX = 1500;
+export const useFloatingPosition = _ref => {
+  let {
+    enabled,
+    isOpen,
+    triggerRef,
+    floatingRef,
+    direction,
+    offset = 4,
+    align = 'left',
+    matchTriggerWidth = false
+  } = _ref;
+  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/esm/src/hooks/usePortalState.js

@@ -0,0 +1,10 @@
+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/esm/src/utils/dropdown/maxSelection.js

@@ -0,0 +1,27 @@
+/**
+ * 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/esm/src/utils/dropdown/multiSelect.js

@@ -1,3 +1,5 @@
+import { useCallback, useMemo } from 'react';
+import { isMaxSelectionLimitActive, isMaxSelectionReached } from './maxSelection';
 /**
  * 전체 선택 상태를 확인하는 유틸 함수
  */
@@ -44,25 +46,79 @@ export const removeTagFromSelected = (selectedValues, tagIdToRemove) => {
   return selectedValues.filter(id => id !== tagIdToRemove);
 };
 /**
- * 전체 선택 관련 로직을 한 번에 처리하는 커스텀 훅
+ * 최대 선택 개수 관련 응집을 별도 훅으로 분리.
+ *
+ * - `isMaxSelectionActive`: 제한 활성 여부.
+ * - `isMaxReached`: 현재 선택 길이가 최대치에 도달했는지.
+ * - `canAdd(currentLength)`: 새 항목 추가가 허용되는지 (도달 시 `false`).
+ *
+ * 도메인 규칙(`>=` 비교 등)을 외부로 노출하지 않고 헬퍼를 통해 의미만 반환한다.
+ * `useMultiSelect`가 내부에서 사용하지만, 단독으로도 필요한 호출자가 쓸 수 있게 export한다.
  */
-export const useMultiSelect = (selectedValues, options, selectText, deselectText) => {
+export const useMaxSelection = (selectedValues, maxSelection) => {
+  const isMaxSelectionActive = isMaxSelectionLimitActive(maxSelection);
+  const isMaxReached = isMaxSelectionReached(selectedValues.length, maxSelection);
+  const canAdd = useCallback(currentLength => !isMaxSelectionReached(currentLength, maxSelection), [maxSelection]);
+  return {
+    isMaxSelectionActive,
+    isMaxReached,
+    canAdd
+  };
+};
+/**
+ * 전체 선택 관련 로직을 한 번에 처리하는 커스텀 훅.
+ *
+ * 시그니처는 호출자가 maxSelection만 지정하더라도 텍스트 라벨을 건너뛰지 않도록 옵션 객체로 받는다.
+ *
+ * **반환의 `tryToggle`**: multiple 토글 결과를 직접 돌려준다.
+ *  - 새 배열 반환: 정상 토글 (추가 또는 해제).
+ *  - `null` 반환: 최대 개수 도달로 추가가 차단됨 (호출자는 변경 없이 종료해야 함).
+ *
+ * 호출자가 `>= maxSelection` 같은 도메인 규칙을 직접 검사하지 않도록 결과만 노출한다.
+ */
+export const useMultiSelect = function (selectedValues, options) {
+  let config = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  const {
+    selectText,
+    deselectText,
+    maxSelection
+  } = config;
   const isAllSelected = isAllItemsSelected(selectedValues, options);
   const buttonText = getSelectAllButtonText(selectedValues, options, selectText, deselectText);
-  const toggleSelectAll = () => {
-    return handleSelectAllItems(selectedValues, options);
-  };
-  const getSelectedTagsData = () => {
-    return getSelectedTags(selectedValues, options);
-  };
-  const removeTag = tagId => {
-    return removeTagFromSelected(selectedValues, tagId);
-  };
-  return {
+  const {
+    isMaxSelectionActive,
+    isMaxReached,
+    canAdd
+  } = useMaxSelection(selectedValues, maxSelection);
+  const toggleSelectAll = useCallback(() => handleSelectAllItems(selectedValues, options), [selectedValues, options]);
+  const getSelectedTagsData = useCallback(() => getSelectedTags(selectedValues, options), [selectedValues, options]);
+  const removeTag = useCallback(tagId => removeTagFromSelected(selectedValues, tagId), [selectedValues]);
+  /**
+   * multiple 선택 토글을 한 번에 처리한다.
+   * - 이미 포함된 항목: 해제 (배열에서 제거하여 반환).
+   * - 미포함 항목: 추가 시도. 최대치 도달이면 `null` 반환(차단).
+   *
+   * 호출 측은 `null` 여부만 확인하면 되며 maxSelection 도메인 규칙을 알 필요가 없다.
+   */
+  const tryToggle = useCallback((optionId, currentArray) => {
+    const base = Array.isArray(currentArray) ? currentArray : [];
+    const idx = base.indexOf(optionId);
+    if (idx > -1) {
+      const next = [...base];
+      next.splice(idx, 1);
+      return next;
+    }
+    if (!canAdd(base.length)) return null;
+    return [...base, optionId];
+  }, [canAdd]);
+  return useMemo(() => ({
     isAllSelected,
     buttonText,
     toggleSelectAll,
     getSelectedTagsData,
-    removeTag
-  };
+    removeTag,
+    isMaxSelectionActive,
+    isMaxReached,
+    tryToggle
+  }), [isAllSelected, buttonText, toggleSelectAll, getSelectedTagsData, removeTag, isMaxSelectionActive, isMaxReached, tryToggle]);
 };

package/dist/temp/assets/scripts/featuredIcon.d.ts

@@ -0,0 +1,22 @@
+export type FeaturedIconTheme = 'light-circle' | 'dark-circle' | 'outline-circle' | 'square-outline';
+export type FeaturedIconColor = 'neutral' | 'error' | 'warning' | 'success';
+export type FeaturedIconSize = 'sm' | 'md' | 'lg' | 'xl';
+export interface FeaturedIconOptions {
+    svgString: string;
+    theme?: FeaturedIconTheme;
+    color?: FeaturedIconColor;
+    size?: FeaturedIconSize;
+    className?: string;
+}
+export declare class FeaturedIcon {
+    private element;
+    private options;
+    constructor(options: FeaturedIconOptions);
+    private createElement;
+    private addSizeToSvg;
+    getElement(): HTMLElement;
+    updateColor(color: FeaturedIconColor): void;
+    updateSize(size: FeaturedIconSize): void;
+    destroy(): void;
+    static create(options: FeaturedIconOptions): FeaturedIcon;
+}