@ncds/ui-admin 1.8.4 → 1.8.5

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/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;
 };