@ncds/ui-admin 1.8.4 → 1.8.6

package/dist/types/assets/scripts/utils/sanitize.d.ts

@@ -0,0 +1,22 @@
+/**
+ * HTML 문자열을 DOMPurify 기본 설정으로 sanitize한다.
+ *
+ * 제거되는 항목 (기본 설정):
+ * - `<script>`, `<iframe>`, `<object>` 등 실행 위험 태그
+ * - `onclick`, `onerror` 등 inline 이벤트 핸들러 속성
+ * - `href="javascript:..."` 같은 javascript: URL
+ *
+ * 유지되는 항목:
+ * - `<svg>`, `<button>`, `<div>`, `<span>`, `<input>` 등 일반 HTML/SVG 태그
+ * - `class`, `style`, `role`, `aria-*`, `data-*` 등 표현용 속성
+ * - SVG 표현 속성 (`viewBox`, `stroke`, `fill` 등)
+ *
+ * 이벤트 바인딩은 addEventListener로 별도 처리할 것.
+ */
+export declare function sanitizeHtml(dirty: string): string;
+/**
+ * 엘리먼트에 콘텐츠를 안전하게 설정한다.
+ * - string: sanitize 후 innerHTML 교체
+ * - HTMLElement: 기존 자식 제거 후 appendChild
+ */
+export declare function setSafeInnerHTML(element: HTMLElement, content: string | HTMLElement): void;

package/dist/types/src/components/data-display/data-grid/DataGrid.types.d.ts

@@ -29,6 +29,13 @@ export type DataGridTableProps = {
     maxHeight?: string | number;
     hoverable?: boolean;
     selectable?: boolean;
+    /**
+     * 가로 스크롤 활성화 시 외부 wrapper에 overflow-x: auto를 적용하고,
+     * 내부의 SelectBox·Dropdown이 FloatingProvider를 통해 자동으로 Portal 렌더로 전환된다.
+     */
+    horizontalScroll?: boolean;
+    /** 가로 스크롤 트리거 임계 너비. horizontalScroll=true 일 때만 의미가 있다. */
+    minWidth?: string | number;
 };
 export type DataGridPaginationProps = ComponentProps<'div'> & {
     children: ReactNode;

package/dist/types/src/components/data-display/table/Table.d.ts

@@ -6,6 +6,8 @@ export declare const Table: import("react").ForwardRefExoticComponent<Omit<impor
     maxHeight?: string | number | undefined;
     hoverable?: boolean | undefined;
     selectable?: boolean | undefined;
+    horizontalScroll?: boolean | undefined;
+    minWidth?: string | number | undefined;
     children: ReactNode;
 } & import("react").RefAttributes<HTMLDivElement>> & {
     Header: {
@@ -24,6 +26,7 @@ export declare const Table: import("react").ForwardRefExoticComponent<Omit<impor
         sortDirection?: SortDirection | undefined;
         onSort?: (() => void) | undefined;
         width?: string | number | undefined;
+        minWidth?: string | number | undefined;
     } & import("react").RefAttributes<HTMLTableCellElement>>;
     Cell: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").TdHTMLAttributes<HTMLTableDataCellElement>, HTMLTableDataCellElement>, "ref"> & {
         isHeader?: boolean | undefined;
@@ -37,7 +40,7 @@ export declare const Table: import("react").ForwardRefExoticComponent<Omit<impor
         displayName: string;
     };
     ColGroup: {
-        ({ widths }: TableColGroupProps): import("react/jsx-runtime").JSX.Element;
+        ({ widths, minWidths }: TableColGroupProps): import("react/jsx-runtime").JSX.Element;
         displayName: string;
     };
     Empty: {

package/dist/types/src/components/data-display/table/types.d.ts

@@ -8,6 +8,17 @@ export type TableProps = Omit<ComponentProps<'div'>, 'ref'> & {
     maxHeight?: string | number;
     hoverable?: boolean;
     selectable?: boolean;
+    /**
+     * 가로 스크롤 활성화. 외곽에 overflow-x: auto wrapper가 추가되며,
+     * 내부의 SelectBox·Dropdown 등 floating 컴포넌트가 FloatingProvider를 통해
+     * 자동으로 React Portal 렌더로 전환된다.
+     */
+    horizontalScroll?: boolean;
+    /**
+     * 가로 스크롤 트리거 임계 너비. horizontalScroll=true 일 때만 의미가 있으며,
+     * 기본값은 1140 (14인치 모니터 + LNB 기준 디자인 권장 너비).
+     */
+    minWidth?: string | number;
     children: ReactNode;
 };
 export type TableHeaderProps = {
@@ -26,6 +37,11 @@ export type TableHeaderCellProps = Omit<ComponentProps<'th'>, 'ref'> & {
     sortDirection?: SortDirection;
     onSort?: () => void;
     width?: string | number;
+    /**
+     * 셀 최소 너비. 가로 스크롤 정책에 따라 글자수 기준으로 설정한다.
+     * 예: 제목·메인 10자 ≈ 160px, 이름·일자 5자 ≈ 80px, 버튼 xxs ≈ 40~60px, 기타 2자 ≈ 32px.
+     */
+    minWidth?: string | number;
 };
 export type TableCellProps = Omit<ComponentProps<'td'>, 'ref'> & {
     isHeader?: boolean;
@@ -40,6 +56,8 @@ export type TablePaginationProps = {
 };
 export type TableColGroupProps = {
     widths: (string | number)[];
+    /** 컬럼별 최소 너비. 가로 스크롤 시 셀이 더 좁아지지 않도록 강제한다. */
+    minWidths?: (string | number)[];
 };
 export type TableEmptyProps = {
     colSpan: number;

package/dist/types/src/components/data-display/table/useTableScrollbars.d.ts

@@ -0,0 +1,25 @@
+import { type MouseEvent, type RefObject } from 'react';
+export declare const TABLE_HEADER_HEIGHT = 40;
+export declare const SCROLLBAR_THUMB_MIN_HEIGHT = 40;
+export declare const H_SCROLLBAR_THUMB_MIN_WIDTH = 40;
+export declare const H_SCROLLBAR_SIDE_GAP = 8;
+export declare const SCROLLBAR_TRACK_OFFSET = 16;
+type VerticalScrollbarOptions = {
+    enabled: boolean;
+    scrollContainerRef: RefObject<HTMLDivElement | null>;
+    scrollAreaRef: RefObject<HTMLDivElement | null>;
+    thumbRef: RefObject<HTMLDivElement | null>;
+};
+export declare const useTableVerticalScrollbar: ({ enabled, scrollContainerRef, scrollAreaRef, thumbRef, }: VerticalScrollbarOptions) => {
+    handleThumbMouseDown: (e: MouseEvent<HTMLDivElement>) => void;
+};
+type HorizontalScrollbarOptions = {
+    enabled: boolean;
+    hScrollContainerRef: RefObject<HTMLDivElement | null>;
+    hScrollbarRef: RefObject<HTMLDivElement | null>;
+    hThumbRef: RefObject<HTMLDivElement | null>;
+};
+export declare const useTableHorizontalScrollbar: ({ enabled, hScrollContainerRef, hScrollbarRef, hThumbRef, }: HorizontalScrollbarOptions) => {
+    handleHThumbMouseDown: (e: MouseEvent<HTMLDivElement>) => void;
+};
+export {};

package/dist/types/src/components/forms-and-input/combo-box/ComboBox.d.ts

@@ -21,6 +21,14 @@ interface ComboBoxProps extends Omit<ComponentPropsWithRef<'div'>, 'size' | 'onC
     required?: boolean;
     multiple?: boolean;
     showFooterButtons?: boolean;
+    /**
+     * 최대 선택 가능 개수 (multiple=true에서만 유효).
+     *  - `0` 이상의 정수: 제한 활성 → footer의 "전체선택" Link 미노출 (DES-SPEC-009 §3.10.1).
+     *    - `0`은 모든 새 선택을 차단한다.
+     *    - 양수는 도달 후 추가 선택을 무시한다 (이미 선택된 항목 해제는 정상).
+     *  - 음수 / 비정수 / `null` / `undefined`: 제한 없음.
+     */
+    maxSelection?: number | null;
     onEdit?: () => void;
 }
 declare const ComboBox: import("react").ForwardRefExoticComponent<Omit<ComboBoxProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;

package/dist/types/src/components/forms-and-input/select-box/SelectBox.d.ts

@@ -19,8 +19,21 @@ type SelectBoxProps = Omit<ComponentPropsWithRef<'div'>, 'size' | 'onChange'> &
     register?: UseFormRegisterReturn;
     maxHeight?: number;
     multiple?: boolean;
+    /**
+     * 최대 선택 가능 개수 (multiple=true에서만 유효).
+     *  - `0` 이상의 정수: 제한 활성 → footer "전체선택" Link 미노출.
+     *    - `0`은 모든 새 선택을 차단한다.
+     *    - 양수는 도달 후 추가 선택을 무시한다 (이미 선택된 항목 해제는 정상).
+     *  - 음수 / 비정수 / `null` / `undefined`: 제한 없음.
+     */
+    maxSelection?: number | null;
     onEdit?: () => void;
     align?: 'left' | 'right';
+    /**
+     * 옵션 패널을 React Portal로 body에 렌더한다.
+     * 미지정 시 FloatingContext.preferPortal 값을 따른다 (DataGrid.Table horizontalScroll 내부에서는 자동 true).
+     */
+    usePortal?: boolean;
 };
 declare const SelectBox: import("react").ForwardRefExoticComponent<Omit<SelectBoxProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 export type { SelectBoxProps };

package/dist/types/src/components/forms-and-input/slider/Slider.d.ts

@@ -11,4 +11,3 @@ export interface SliderProps {
     className?: string;
 }
 export declare const Slider: ({ min, max, step, value, onChange, labelPosition, disabled, className, }: SliderProps) => import("react/jsx-runtime").JSX.Element;
-export default Slider;

package/dist/types/src/components/overlays/dropdown/Dropdown.d.ts

@@ -49,6 +49,11 @@ export type DropdownBaseProps = {
     className?: string;
     opened?: boolean;
     closeOnClickOutside?: boolean;
+    /**
+     * 메뉴를 React Portal로 body에 렌더한다.
+     * 미지정 시 FloatingContext.preferPortal 값을 따른다 (DataGrid.Table horizontalScroll 내부에서는 자동 true).
+     */
+    usePortal?: boolean;
 };
 export type ActionDropdownProps = DropdownBaseProps & {
     variant?: 'action';

package/dist/types/src/components/overlays/notification/CalloutNotification.d.ts

@@ -0,0 +1,9 @@
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import type { NotificationColor } from './Notification';
+interface CalloutNotificationProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title'> {
+    color?: NotificationColor;
+    title?: ReactNode;
+}
+declare const CalloutNotification: import("react").ForwardRefExoticComponent<CalloutNotificationProps & import("react").RefAttributes<HTMLDivElement>>;
+export type { CalloutNotificationProps };
+export { CalloutNotification };

package/dist/types/src/components/overlays/notification/FloatingNotification.d.ts

@@ -31,6 +31,21 @@ interface FloatingNotificationProps extends Omit<ComponentPropsWithoutRef<'div'>
      * @default 0
      */
     autoClose?: number;
+    /**
+     * Portal 마운트 여부.
+     *
+     * - `false` (기본값): 부모 JSX 트리 안에 카드로 그대로 렌더된다.
+     *   특정 컨테이너 안에서 표시하거나, 인라인 미리보기 (docs/스토리북) 용도.
+     *
+     * - `true`: document.body의 `.ncua-floating-notification-host` 싱글톤에
+     *   `createPortal`로 마운트되어 우측 상단에 노출. 다중 발생 시 최신 토스트가
+     *   상단에 노출되고 이전 토스트들이 아래로 12px씩 겹쳐 쌓인다 (LIFO,
+     *   `--ncua-floating-notification-stack-overlap` 변수로 조정 가능).
+     *   Vanilla(CDN) 측 `new ncua.Notification({type:'floating'}).show()` 와 동일한 동작.
+     *
+     * @default false
+     */
+    portal?: boolean;
 }
 declare const FloatingNotification: import("react").ForwardRefExoticComponent<FloatingNotificationProps & import("react").RefAttributes<HTMLDivElement>>;
 export type { FloatingNotificationProps };

package/dist/types/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/types/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/types/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/types/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/types/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/types/src/contexts/index.d.ts

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

package/dist/types/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/types/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/types/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/types/src/types/component-meta.d.ts

@@ -1,6 +1,10 @@
 /** AI 에이전트용 컴포넌트 메타데이터 타입 */
-/** 컴포넌트 카테고리 — `src/components/` 하위 디렉토리명과 동일 */
-export type ComponentCategory = 'action' | 'data-display' | 'feedback-and-status' | 'forms-and-input' | 'image-and-icons' | 'layout' | 'navigation' | 'overlays';
+/**
+ * 컴포넌트 카테고리 — `src/components/` 하위 디렉토리명과 동일.
+ * 타입과 런타임 값을 한 곳에서 정의해 추가/변경 시 동기화 누락을 막는다.
+ */
+export declare const COMPONENT_CATEGORIES: readonly ["action", "data-display", "feedback-and-status", "forms-and-input", "image-and-icons", "layout", "navigation", "overlays"];
+export type ComponentCategory = (typeof COMPONENT_CATEGORIES)[number];
 export interface ComponentMeta {
     category: ComponentCategory;
     aliases: string[];

package/dist/types/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/types/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;
 };