@mezzanine-ui/react 1.0.0-canary.2 → 1.0.0-canary.3

package/InlineMessage/InlineMessage.d.ts

@@ -0,0 +1,33 @@
+import { InlineMessageSeverity } from '@mezzanine-ui/core/inline-message';
+import { IconDefinition } from '@mezzanine-ui/icons';
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+export interface InlineMessageProps extends NativeElementPropsWithoutKeyAndRef<'div'> {
+    /**
+     * The content of the inline message value(only string is supported).
+     */
+    content: string;
+    /**
+     * The class name of the inline message element.
+     */
+    className?: string;
+    /**
+     * The icon of the inline message.
+     */
+    icon?: IconDefinition;
+    /**
+     * Called when user clicks the close button.
+     */
+    onClose?: () => void;
+    /**
+     * The inline message severity (`'info' | 'warning' | 'error'`).
+     */
+    severity: InlineMessageSeverity;
+}
+/**
+ * The react component for `mezzanine` inline message.
+ *
+ * Use `InlineMessage` directly in your layout to display contextual feedback,
+ * and provide `onClose` callback when you need to react to dismiss events.
+ */
+declare const InlineMessage: import("react").ForwardRefExoticComponent<InlineMessageProps & import("react").RefAttributes<HTMLDivElement>>;
+export default InlineMessage;

package/InlineMessage/InlineMessage.js

@@ -0,0 +1,37 @@
+'use client';
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { forwardRef, useState, useCallback, useMemo } from 'react';
+import { inlineMessageClasses, inlineMessageIcons } from '@mezzanine-ui/core/inline-message';
+import DismissButton from '../DismissButton/DismissButton.js';
+import Icon from '../Icon/Icon.js';
+import cx from 'clsx';
+
+/**
+ * The react component for `mezzanine` inline message.
+ *
+ * Use `InlineMessage` directly in your layout to display contextual feedback,
+ * and provide `onClose` callback when you need to react to dismiss events.
+ */
+const InlineMessage = forwardRef(function InlineMessage(props, ref) {
+    const { content, className, icon, onClose, severity } = props;
+    const [visible, setVisible] = useState(true);
+    const handleClose = useCallback(() => {
+        setVisible(false);
+        if (onClose) {
+            onClose();
+        }
+    }, [onClose]);
+    const iconNode = useMemo(() => {
+        if (icon) {
+            return jsx(Icon, { className: inlineMessageClasses.icon, icon: icon });
+        }
+        const severityIcon = inlineMessageIcons[severity];
+        return jsx(Icon, { className: inlineMessageClasses.icon, icon: severityIcon });
+    }, [icon, severity]);
+    if (!visible) {
+        return null;
+    }
+    return (jsxs("div", { ref: ref, "aria-live": "polite", className: cx(inlineMessageClasses.host, inlineMessageClasses.severity(severity), className), role: "status", children: [jsxs("div", { className: inlineMessageClasses.contentContainer, children: [iconNode, jsx("span", { className: inlineMessageClasses.content, children: content })] }), severity === 'info' ? (jsx(DismissButton, { onClick: handleClose, type: "standard", variant: "base" })) : null] }));
+});
+
+export { InlineMessage as default };

package/InlineMessage/InlineMessageGroup.d.ts

@@ -0,0 +1,24 @@
+import { Key, ReactNode } from 'react';
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+import { InlineMessageProps } from './InlineMessage';
+export interface InlineMessageGroupItem extends Omit<InlineMessageProps, 'content'> {
+    key: Key;
+    content: string;
+}
+export interface InlineMessageGroupProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>, 'children'> {
+    /**
+     * The inline messages within the group.
+     * Ignored when `children` provided.
+     */
+    items?: InlineMessageGroupItem[];
+    /**
+     * Custom inline message nodes.
+     */
+    children?: ReactNode;
+    /**
+     * Callback invoked when any item triggers `onClose`.
+     */
+    onItemClose?: (key: Key) => void;
+}
+declare const InlineMessageGroup: import("react").ForwardRefExoticComponent<InlineMessageGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export default InlineMessageGroup;

package/InlineMessage/InlineMessageGroup.js

@@ -0,0 +1,21 @@
+import { jsx } from 'react/jsx-runtime';
+import { inlineMessageGroupClasses } from '@mezzanine-ui/core/inline-message';
+import { forwardRef, useMemo } from 'react';
+import InlineMessage from './InlineMessage.js';
+import cx from 'clsx';
+
+const mapItemsToMessages = (items, onItemClose) => items === null || items === void 0 ? void 0 : items.map(({ key, content, onClose, ...restItemProps }) => (jsx(InlineMessage, { ...restItemProps, content: content, onClose: () => {
+        if (onClose) {
+            onClose();
+        }
+        if (onItemClose) {
+            onItemClose(key);
+        }
+    } }, key)));
+const InlineMessageGroup = forwardRef(function InlineMessageGroup(props, ref) {
+    const { children: childrenProp, className, items, onItemClose, ...rest } = props;
+    const children = useMemo(() => childrenProp !== null && childrenProp !== void 0 ? childrenProp : mapItemsToMessages(items, onItemClose), [childrenProp, items, onItemClose]);
+    return (jsx("div", { ...rest, ref: ref, className: cx(inlineMessageGroupClasses.host, className), "aria-live": "polite", role: "region", children: children }));
+});
+
+export { InlineMessageGroup as default };

package/InlineMessage/index.d.ts

@@ -0,0 +1,4 @@
+export { default } from './InlineMessage';
+export type { InlineMessageProps } from './InlineMessage';
+export { default as InlineMessageGroup } from './InlineMessageGroup';
+export type { InlineMessageGroupItem, InlineMessageGroupProps, } from './InlineMessageGroup';

package/InlineMessage/index.js

@@ -0,0 +1,2 @@
+export { default } from './InlineMessage.js';
+export { default as InlineMessageGroup } from './InlineMessageGroup.js';

package/Message/Message.d.ts

@@ -1,6 +1,6 @@
 import { MessageSeverity } from '@mezzanine-ui/core/message';
 import { IconDefinition } from '@mezzanine-ui/icons';
-import { FC, Key } from 'react';
+import type { FC, Key } from 'react';
 import { Notifier, NotifierData, NotifierConfig } from '../Notifier';
 import { SlideFadeProps } from '../Transition';
 export interface MessageConfigProps extends Pick<NotifierConfig, 'duration'>, Pick<SlideFadeProps, 'onEnter' | 'onEntering' | 'onEntered' | 'onExit' | 'onExiting' | 'onExited' | 'easing' | 'direction'> {
@@ -25,7 +25,9 @@ export interface MessageData extends Omit<NotifierData, 'onClose'>, MessageConfi
      */
     severity?: MessageSeverity;
 }
-export type MessageType = FC<MessageData> & Notifier<MessageData, MessageConfigProps> & Record<string, (message: MessageData['children'], props?: Omit<MessageData, 'children' | 'severity' | 'icon'>) => Key>;
+export type MessageType = FC<MessageData> & Notifier<MessageData, MessageConfigProps> & Record<string, (message: MessageData['children'], props?: Omit<MessageData, 'children' | 'severity' | 'icon'> & {
+    key?: Key;
+}) => Key>;
 /**
  * The react component for `mezzanine` message.
  *

package/Message/Message.js

@@ -1,6 +1,8 @@
-import { useState, useEffect, createElement } from 'react';
+'use client';
+import { useState, useRef, useCallback, useEffect, createElement } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { messageClasses, messageIcons } from '@mezzanine-ui/core/message';
+import { messageTimerController } from './MessageTimerController.js';
 import SlideFade from '../Transition/SlideFade.js';
 import Icon from '../Icon/Icon.js';
 import { createNotifier } from '../Notifier/createNotifier.js';
@@ -15,16 +17,72 @@ import cx from 'clsx';
 const Message = ((props) => {
     const { children, duration, icon, reference, severity, onExited: onExitedProp, ...restTransitionProps } = props;
     const [open, setOpen] = useState(true);
+    const timerRef = useRef(null);
+    const remainingTimeRef = useRef(duration || 0);
+    const startTimeRef = useRef(Date.now());
+    // 清理計時器
+    const clearTimer = useCallback(() => {
+        if (timerRef.current) {
+            window.clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+    }, []);
+    // 開始計時器
+    const startTimer = useCallback((time) => {
+        clearTimer();
+        if (time > 0) {
+            startTimeRef.current = Date.now();
+            remainingTimeRef.current = time;
+            timerRef.current = window.setTimeout(() => {
+                setOpen(false);
+            }, time);
+        }
+    }, [clearTimer]);
+    // 暫停計時器
+    const pauseTimer = useCallback(() => {
+        if (timerRef.current) {
+            clearTimer();
+            const elapsed = Date.now() - startTimeRef.current;
+            remainingTimeRef.current = Math.max(0, remainingTimeRef.current - elapsed);
+        }
+    }, [clearTimer]);
+    // 恢復計時器
+    const resumeTimer = useCallback(() => {
+        if (remainingTimeRef.current > 0) {
+            startTimer(remainingTimeRef.current);
+        }
+    }, [startTimer]);
+    // 初始設定計時器
     useEffect(() => {
         if (open && duration) {
-            const timer = window.setTimeout(() => {
-                setOpen(false);
-            }, duration);
+            startTimer(duration);
+        }
+        else if (open && duration === false) {
+            // duration 為 false 時，清除計時器（不自動關閉）
+            clearTimer();
+        }
+        return () => {
+            clearTimer();
+        };
+    }, [open, duration, clearTimer, startTimer]);
+    // 註冊到全域控制器
+    useEffect(() => {
+        if (reference && duration) {
+            messageTimerController.register(reference, {
+                pause: pauseTimer,
+                resume: resumeTimer,
+            });
             return () => {
-                window.clearTimeout(timer);
+                messageTimerController.unregister(reference);
             };
         }
-    }, [open, duration]);
+    }, [reference, duration, pauseTimer, resumeTimer]);
+    // 清理計時器（組件卸載時）
+    useEffect(() => {
+        return () => {
+            clearTimer();
+        };
+    }, [clearTimer]);
     const onExited = (node) => {
         if (onExitedProp) {
             onExitedProp(node);
@@ -32,11 +90,24 @@ const Message = ((props) => {
         if (reference)
             Message.remove(reference);
     };
-    return (jsx(SlideFade, { in: open, appear: true, onExited: onExited, ...restTransitionProps, children: jsxs("div", { className: cx(messageClasses.host, severity ? messageClasses.severity(severity) : ''), children: [icon ? jsx(Icon, { className: messageClasses.icon, icon: icon }) : null, jsx("span", { className: messageClasses.content, children: children })] }) }));
+    const handleMouseEnter = () => {
+        messageTimerController.pause();
+    };
+    const handleMouseLeave = () => {
+        messageTimerController.resume();
+    };
+    const handleFocus = () => {
+        messageTimerController.pause();
+    };
+    const handleBlur = () => {
+        messageTimerController.resume();
+    };
+    return (jsx(SlideFade, { in: open, appear: true, onExited: onExited, direction: "up", ...restTransitionProps, children: jsxs("div", { className: cx(messageClasses.host, severity ? messageClasses.severity(severity) : ''), onBlur: handleBlur, onFocus: handleFocus, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, role: "status", children: [icon ? (jsx(Icon, { className: messageClasses.icon, icon: icon, spin: severity === 'loading' })) : null, jsx("span", { className: messageClasses.content, children: children })] }) }));
 });
 const { add, config, destroy, remove } = createNotifier({
     duration: 3000,
-    render: (message) => createElement(Message, { ...message, key: undefined }),
+    maxCount: 4,
+    render: (message) => (createElement(Message, { ...message, reference: message.key, key: undefined })),
     setRoot: (root) => {
         root === null || root === void 0 ? void 0 : root.setAttribute('class', messageClasses.root);
     },
@@ -62,12 +133,17 @@ const severities = [
         key: 'info',
         icon: messageIcons.info,
     },
+    {
+        key: 'loading',
+        icon: messageIcons.loading,
+    },
 ];
 const validSeverities = [
     'success',
     'warning',
     'error',
     'info',
+    'loading',
 ];
 severities.forEach((severity) => {
     Message[severity.key] = (message, props) => Message.add({
@@ -77,6 +153,7 @@ severities.forEach((severity) => {
             ? severity.key
             : undefined,
         icon: severity.icon,
+        duration: severity.key === 'loading' ? false : props === null || props === void 0 ? void 0 : props.duration,
     });
 });
 

package/Message/MessageTimerController.d.ts

@@ -0,0 +1,14 @@
+import type { Key } from 'react';
+declare class MessageTimerController {
+    private isPaused;
+    private timers;
+    pause(): void;
+    register(key: Key, callbacks: {
+        pause: () => void;
+        resume: () => void;
+    }): void;
+    resume(): void;
+    unregister(key: Key): void;
+}
+export declare const messageTimerController: MessageTimerController;
+export {};

package/Message/MessageTimerController.js

@@ -0,0 +1,27 @@
+class MessageTimerController {
+    constructor() {
+        this.isPaused = false;
+        this.timers = new Map();
+    }
+    pause() {
+        if (this.isPaused)
+            return;
+        this.isPaused = true;
+        this.timers.forEach((timer) => timer.pause());
+    }
+    register(key, callbacks) {
+        this.timers.set(key, callbacks);
+    }
+    resume() {
+        if (!this.isPaused)
+            return;
+        this.isPaused = false;
+        this.timers.forEach((timer) => timer.resume());
+    }
+    unregister(key) {
+        this.timers.delete(key);
+    }
+}
+const messageTimerController = new MessageTimerController();
+
+export { messageTimerController };

package/Modal/Modal.js

@@ -11,13 +11,13 @@ import cx from 'clsx';
  * The react component for `mezzanine` modal.
  */
 const Modal = forwardRef(function Modal(props, ref) {
-    const { children, className, container, direction = 'down', disableCloseOnBackdropClick = false, disableCloseOnEscapeKeyDown = false, disablePortal = false, fullScreen = false, hideBackdrop = false, hideCloseIcon = false, invisibleBackdrop = false, loading = false, onBackdropClick, onClose, open, severity = 'info', size = 'medium', ...rest } = props;
+    const { children, className, container, direction = 'down', disableCloseOnBackdropClick = false, disableCloseOnEscapeKeyDown = false, disablePortal = false, fullScreen = false, hideCloseIcon = false, loading = false, onBackdropClick, onClose, open, severity = 'info', size = 'medium', ...rest } = props;
     const modalControl = useMemo(() => ({
         loading,
         severity,
     }), [loading, severity]);
     const { Container: ModalContainer } = useModalContainer();
-    return (jsx(ModalControlContext.Provider, { value: modalControl, children: jsx(ModalContainer, { className: modalClasses.overlay, container: container, direction: direction, disableCloseOnBackdropClick: disableCloseOnBackdropClick, disableCloseOnEscapeKeyDown: disableCloseOnEscapeKeyDown, disablePortal: disablePortal, hideBackdrop: hideBackdrop, invisibleBackdrop: invisibleBackdrop, onBackdropClick: onBackdropClick, onClose: onClose, open: open, ref: ref, children: jsxs("div", { ...rest, className: cx(modalClasses.host, modalClasses.severity(severity), modalClasses.size(size), {
+    return (jsx(ModalControlContext.Provider, { value: modalControl, children: jsx(ModalContainer, { className: modalClasses.overlay, container: container, direction: direction, disableCloseOnBackdropClick: disableCloseOnBackdropClick, disableCloseOnEscapeKeyDown: disableCloseOnEscapeKeyDown, disablePortal: disablePortal, onBackdropClick: onBackdropClick, onClose: onClose, open: open, ref: ref, children: jsxs("div", { ...rest, className: cx(modalClasses.host, modalClasses.severity(severity), modalClasses.size(size), {
                     [modalClasses.fullScreen]: fullScreen,
                     [modalClasses.withCloseIcon]: !hideCloseIcon,
                 }, className), role: "dialog", children: [children, !hideCloseIcon && (jsx(Icon, { className: modalClasses.closeIcon, icon: TimesIcon, onClick: onClose }))] }) }) }));

package/Modal/useModalContainer.d.ts

@@ -1,5 +1,5 @@
 import { SlideFadeOverlayProps } from '../_internal/SlideFadeOverlay';
 export default function useModalContainer(): {
     Container: import("react").ForwardRefExoticComponent<SlideFadeOverlayProps & import("react").RefAttributes<HTMLDivElement>>;
-    defaultOptions: Pick<SlideFadeOverlayProps, "className" | "open" | "disablePortal" | "direction" | "disableCloseOnBackdropClick" | "hideBackdrop" | "invisibleBackdrop" | "disableCloseOnEscapeKeyDown">;
+    defaultOptions: Pick<SlideFadeOverlayProps, "className" | "open" | "disablePortal" | "direction" | "disableCloseOnBackdropClick" | "disableCloseOnEscapeKeyDown">;
 };

package/Modal/useModalContainer.js

@@ -9,13 +9,11 @@ const defaultOptions = {
     disableCloseOnBackdropClick: false,
     disableCloseOnEscapeKeyDown: false,
     disablePortal: false,
-    hideBackdrop: false,
-    invisibleBackdrop: false,
     open: false,
 };
 const ModalContainer = forwardRef((props, ref) => {
-    const { className = defaultOptions.className, children, container, direction = defaultOptions.direction, disableCloseOnBackdropClick = defaultOptions.disableCloseOnBackdropClick, disableCloseOnEscapeKeyDown = defaultOptions.disableCloseOnEscapeKeyDown, disablePortal = defaultOptions.disablePortal, hideBackdrop = defaultOptions.hideBackdrop, invisibleBackdrop = defaultOptions.invisibleBackdrop, onBackdropClick, onClose, open = defaultOptions.open, } = props;
-    return (jsx(SlideFadeOverlay, { className: className, container: container, direction: direction, disableCloseOnBackdropClick: disableCloseOnBackdropClick, disableCloseOnEscapeKeyDown: disableCloseOnEscapeKeyDown, disablePortal: disablePortal, hideBackdrop: hideBackdrop, invisibleBackdrop: invisibleBackdrop, onBackdropClick: onBackdropClick, onClose: onClose, open: open, ref: ref, children: children }));
+    const { className = defaultOptions.className, children, container, direction = defaultOptions.direction, disableCloseOnBackdropClick = defaultOptions.disableCloseOnBackdropClick, disableCloseOnEscapeKeyDown = defaultOptions.disableCloseOnEscapeKeyDown, disablePortal = defaultOptions.disablePortal, onBackdropClick, onClose, open = defaultOptions.open, } = props;
+    return (jsx(SlideFadeOverlay, { className: className, container: container, direction: direction, disableCloseOnBackdropClick: disableCloseOnBackdropClick, disableCloseOnEscapeKeyDown: disableCloseOnEscapeKeyDown, disablePortal: disablePortal, onBackdropClick: onBackdropClick, onClose: onClose, open: open, ref: ref, children: children }));
 });
 function useModalContainer() {
     return {

package/Navigation/NavigationSubMenu.js

@@ -3,6 +3,7 @@ import { jsx, jsxs } from 'react/jsx-runtime';
 import { forwardRef, useState, useRef, useContext } from 'react';
 import { navigationSubMenuClasses } from '@mezzanine-ui/core/navigation';
 import { ChevronUpIcon, ChevronDownIcon } from '@mezzanine-ui/icons';
+import { offset, size } from '@floating-ui/react-dom';
 import { useClickAway } from '../hooks/useClickAway.js';
 import { useComposeRefs } from '../hooks/useComposeRefs.js';
 import NavigationItem from './NavigationItem.js';
@@ -12,31 +13,14 @@ import Popper from '../Popper/Popper.js';
 import Collapse from '../Transition/Collapse.js';
 import cx from 'clsx';
 
-/* istanbul ignore next */
-const popperOptions = {
-    modifiers: [
-        {
-            name: 'offset',
-            options: {
-                offset: [0, 0],
-            },
-        },
-        {
-            name: 'sameWidth',
-            enabled: true,
-            phase: 'beforeWrite',
-            requires: ['computeStyles'],
-            fn: ({ state }) => {
-                const reassignState = state;
-                reassignState.styles.popper.width = `${state.rects.reference.width}px`;
-            },
-            effect: ({ state }) => {
-                const reassignState = state;
-                reassignState.elements.popper.style.width = `${state.elements.reference.getBoundingClientRect().width}px`;
-            },
-        },
-    ],
-};
+// Middleware to make the submenu have the same width as the reference element
+const sameWidthMiddleware = size({
+    apply({ rects, elements }) {
+        Object.assign(elements.floating.style, {
+            width: `${rects.reference.width}px`,
+        });
+    },
+});
 const NavigationSubMenu = forwardRef((props, ref) => {
     const { active, className, children = [], defaultOpen = false, icon, title, ...rest } = props;
     const [open, setOpen] = useState(defaultOpen);
@@ -53,7 +37,12 @@ const NavigationSubMenu = forwardRef((props, ref) => {
         };
     }, nodeRef, [open, orientation]);
     const WrapChildren = jsx("ul", { className: navigationSubMenuClasses.group, children: children });
-    return (jsxs(NavigationItem, { ...rest, ref: composedNodeRef, className: cx(navigationSubMenuClasses.host, active && navigationSubMenuClasses.active, open && navigationSubMenuClasses.open, icon && orientation === 'vertical' && navigationSubMenuClasses.indent, className), onClick: () => setOpen(!open), children: [jsxs("div", { className: navigationSubMenuClasses.title, children: [icon && jsx(Icon, { className: navigationSubMenuClasses.icon, icon: icon }), title, jsx(Icon, { className: navigationSubMenuClasses.toggleIcon, icon: GroupToggleIcon })] }), orientation === 'horizontal' && (jsx(Popper, { anchor: nodeRef, disablePortal: true, open: !!open, options: popperOptions, children: WrapChildren })), orientation === 'vertical' && (jsx(Collapse, { style: {
+    return (jsxs(NavigationItem, { ...rest, ref: composedNodeRef, className: cx(navigationSubMenuClasses.host, active && navigationSubMenuClasses.active, open && navigationSubMenuClasses.open, icon && orientation === 'vertical' && navigationSubMenuClasses.indent, className), onClick: () => setOpen(!open), children: [jsxs("div", { className: navigationSubMenuClasses.title, children: [icon && jsx(Icon, { className: navigationSubMenuClasses.icon, icon: icon }), title, jsx(Icon, { className: navigationSubMenuClasses.toggleIcon, icon: GroupToggleIcon })] }), orientation === 'horizontal' && (jsx(Popper, { anchor: nodeRef, disablePortal: true, open: !!open, options: {
+                    middleware: [
+                        offset({ mainAxis: 0, crossAxis: 0 }),
+                        sameWidthMiddleware,
+                    ],
+                }, children: WrapChildren })), orientation === 'vertical' && (jsx(Collapse, { style: {
                     width: '100%',
                 }, in: !!open, children: WrapChildren }))] }));
 });

package/Notifier/NotifierManager.d.ts

@@ -1,5 +1,6 @@
+import type { ReactNode } from 'react';
 import { Key, RefObject } from 'react';
-import { NotifierData, NotifierConfig, RenderNotifier } from './typings';
+import { NotifierConfig, NotifierData, RenderNotifier } from './typings';
 export interface NotifierController<N extends NotifierData> {
     add: (notifier: N & {
         key: Key;
@@ -12,6 +13,18 @@ export interface NotifierManagerProps<N extends NotifierData> extends Pick<Notif
         key: Key;
     })[];
     render: RenderNotifier<N>;
+    /**
+     * Custom wrapper for rendered notifiers (e.g. AlertBanner group container).
+     */
+    renderContainer?: (children: ReactNode) => ReactNode;
+    /**
+     * Sorting hook to enforce display/queue ordering before updates.
+     */
+    sortBeforeUpdate?: (notifiers: (N & {
+        key: Key;
+    })[]) => (N & {
+        key: Key;
+    })[];
 }
-declare function NotifierManager<N extends NotifierData>(props: NotifierManagerProps<N>): import("react/jsx-runtime").JSX.Element;
+declare function NotifierManager<N extends NotifierData>(props: NotifierManagerProps<N>): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
 export default NotifierManager;

package/Notifier/NotifierManager.js

@@ -1,31 +1,73 @@
-import { jsx, Fragment } from 'react/jsx-runtime';
-import { useState, useMemo, useImperativeHandle, Fragment as Fragment$1 } from 'react';
+import { jsx, Fragment as Fragment$1 } from 'react/jsx-runtime';
+import { useCallback, useState, useEffect, useMemo, useImperativeHandle, Fragment } from 'react';
 
 function NotifierManager(props) {
-    const { controllerRef, defaultNotifiers = [], maxCount, render } = props;
-    const [notifiers, setNotifiers] = useState(defaultNotifiers);
-    const notifiersShouldRendered = typeof maxCount === 'number' && notifiers.length > maxCount
-        ? notifiers.slice(0, maxCount)
-        : notifiers;
+    const { controllerRef, defaultNotifiers = [], maxCount, render, renderContainer, sortBeforeUpdate, } = props;
+    // 只有在呼叫端有提供 sortBeforeUpdate 時才執行排序，否則維持原本順序。
+    const sortNotifiers = useCallback((notifiers) => sortBeforeUpdate ? sortBeforeUpdate(notifiers) : notifiers, [sortBeforeUpdate]);
+    const [displayedNotifiers, setDisplayedNotifiers] = useState(() => sortNotifiers(defaultNotifiers));
+    const [queuedNotifiers, setQueuedNotifiers] = useState([]);
+    // 當有空位時，從 queue 中補上
+    useEffect(() => {
+        if (queuedNotifiers.length > 0) {
+            const hasMaxCount = typeof maxCount === 'number';
+            const availableSlots = hasMaxCount
+                ? maxCount - displayedNotifiers.length
+                : Infinity;
+            if (availableSlots > 0) {
+                const notifiersToDisplay = queuedNotifiers.slice(0, availableSlots);
+                setDisplayedNotifiers((prev) => sortNotifiers([...prev, ...notifiersToDisplay]));
+                setQueuedNotifiers((prev) => prev.slice(availableSlots));
+            }
+        }
+    }, [displayedNotifiers.length, queuedNotifiers, maxCount, sortNotifiers]);
     const controller = useMemo(() => ({
         add(notifier) {
-            setNotifiers((prev) => {
+            setDisplayedNotifiers((prev) => {
                 const notifierIndex = prev.findIndex(({ key }) => key === notifier.key);
-                return ~notifierIndex
-                    ? [
-                        ...prev.slice(0, notifierIndex),
-                        notifier,
-                        ...prev.slice(notifierIndex + 1, prev.length),
-                    ]
-                    : [...prev, notifier];
+                // 如果已存在，則更新該訊息
+                if (~notifierIndex) {
+                    const next = [...prev];
+                    next[notifierIndex] = notifier;
+                    return sortNotifiers(next);
+                }
+                // 新訊息：檢查是否超過 maxCount
+                const hasMaxCount = typeof maxCount === 'number';
+                if (hasMaxCount && prev.length >= maxCount) {
+                    if (sortBeforeUpdate) {
+                        // 需要排序時，先把舊有與新增併在一起排序，
+                        // 取前 maxCount 個顯示，其餘補進 queue。
+                        const allNotifiers = sortNotifiers([...prev, notifier]);
+                        const toDisplay = allNotifiers.slice(0, maxCount);
+                        const toQueue = allNotifiers.slice(maxCount);
+                        if (toQueue.length > 0) {
+                            setQueuedNotifiers((queue) => [...queue, ...toQueue]);
+                        }
+                        return toDisplay;
+                    }
+                    // 超過上限，加入 queue
+                    setQueuedNotifiers((queue) => [...queue, notifier]);
+                    return prev;
+                }
+                // 未超過上限，直接加到最後
+                // 直接加入並依需求排序。
+                return sortNotifiers([...prev, notifier]);
             });
         },
         remove(key) {
-            setNotifiers((prev) => prev.filter((m) => m.key !== key));
+            setDisplayedNotifiers((prev) => prev.filter((m) => m.key !== key));
+            setQueuedNotifiers((prev) => prev.filter((m) => m.key !== key));
         },
-    }), []);
+    }), [maxCount, sortBeforeUpdate, sortNotifiers]);
     useImperativeHandle(controllerRef, () => controller, [controller]);
-    return (jsx(Fragment, { children: notifiersShouldRendered.map((notifier) => (jsx(Fragment$1, { children: render(notifier) }, notifier.key))) }));
+    const renderedNotifiers = displayedNotifiers.map((notifier) => (jsx(Fragment, { children: render(notifier) }, notifier.key)));
+    if (renderContainer) {
+        if (!renderedNotifiers.length) {
+            return null;
+        }
+        return renderContainer(renderedNotifiers);
+    }
+    return (jsx(Fragment$1, { children: renderedNotifiers }));
 }
 
 export { NotifierManager as default };

package/Notifier/createNotifier.d.ts

@@ -1,3 +1,4 @@
+import { type NotifierManagerProps } from './NotifierManager';
 import { Notifier, NotifierConfig, NotifierData, RenderNotifier } from './typings';
 export interface CreateNotifierProps<N extends NotifierData, C extends NotifierConfig> extends NotifierConfig {
     /**
@@ -12,6 +13,14 @@ export interface CreateNotifierProps<N extends NotifierData, C extends NotifierC
      * The method to set attributes or listeners to root.
      */
     setRoot?: (root: HTMLDivElement) => void;
+    /**
+     * Custom wrapper for rendered notifiers (e.g. AlertBanner group container).
+     */
+    renderContainer?: NotifierManagerProps<N>['renderContainer'];
+    /**
+     * Sorting hook to enforce display/queue ordering before updates.
+     */
+    sortBeforeUpdate?: NotifierManagerProps<N>['sortBeforeUpdate'];
 }
 /**
  * The utility factory for `mezzanine` to create a notifier.

package/Notifier/createNotifier.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx } from 'react/jsx-runtime';
 import { createRef } from 'react';
 import { createRoot } from 'react-dom/client';
@@ -9,7 +10,7 @@ import NotifierManager from './NotifierManager.js';
  * When APIs are called, Notifier will dynamically render a new react instance by `ReactDOM.render` method.
  */
 function createNotifier(props) {
-    const { config: configProp, render: renderNotifier, setRoot, duration, maxCount, ...restNotifierProps } = props;
+    const { config: configProp, render: renderNotifier, setRoot, duration, maxCount, renderContainer, sortBeforeUpdate, ...restNotifierProps } = props;
     const container = typeof document === 'undefined' ? null : document.createElement('div');
     const root = container ? createRoot(container) : null;
     const controllerRef = createRef();
@@ -40,7 +41,7 @@ function createNotifier(props) {
                 controllerRef.current.add(resolvedNotifier);
             }
             else {
-                root === null || root === void 0 ? void 0 : root.render(jsx(NotifierManager, { controllerRef: controllerRef, defaultNotifiers: [resolvedNotifier], maxCount: currentConfig.maxCount, render: renderNotifier }));
+                root === null || root === void 0 ? void 0 : root.render(jsx(NotifierManager, { controllerRef: controllerRef, defaultNotifiers: [resolvedNotifier], maxCount: currentConfig.maxCount, render: renderNotifier, renderContainer: renderContainer, sortBeforeUpdate: sortBeforeUpdate }));
             }
             return resolvedNotifier.key;
         },

package/Notifier/typings.d.ts

@@ -16,7 +16,9 @@ export interface NotifierData extends Pick<NotifierConfig, 'duration'> {
      */
     onClose?: (key: Key) => void;
 }
-export type RenderNotifier<N extends NotifierData> = (notifier: N) => ReactNode;
+export type RenderNotifier<N extends NotifierData> = (notifier: N & {
+    key: Key;
+}) => ReactNode;
 export interface Notifier<N extends NotifierData, C extends NotifierConfig = NotifierConfig> {
     add: (notifier: N & {
         key?: Key;