@mezzanine-ui/react 1.0.0-rc.5 → 1.0.0-rc.7

package/Navigation/NavigationOverflowMenu.js

@@ -1,4 +1,4 @@
-import { useState, useRef, useCallback, createElement, useMemo } from 'react';
+import { useState, use, useRef, useCallback, createElement, useMemo } from 'react';
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import { navigationOverflowMenuClasses } from '@mezzanine-ui/core/navigation';
 import NavigationIconButton from './NavigationIconButton.js';
@@ -6,13 +6,16 @@ import { DotHorizontalIcon } from '@mezzanine-ui/icons';
 import NavigationOverflowMenuOption from './NavigationOverflowMenuOption.js';
 import { TransitionGroup } from 'react-transition-group';
 import { MOTION_EASING, MOTION_DURATION } from '@mezzanine-ui/system/motion';
-import { NavigationOptionLevelContext } from './context.js';
+import { NavigationActivatedContext, NavigationOptionLevelContext } from './context.js';
 import { useDocumentEvents } from '../hooks/useDocumentEvents.js';
 import Popper from '../Popper/Popper.js';
 import Translate from '../Transition/Translate.js';
+import Scrollbar from '../Scrollbar/Scrollbar.js';
 
 const NavigationOverflowMenu = ({ items, }) => {
     const [menuOpen, setMenuOpen] = useState(false);
+    const { activatedPath, collapsedHiddenKeys } = use(NavigationActivatedContext);
+    const isActive = activatedPath.length > 0 && collapsedHiddenKeys.has(activatedPath[0]);
     const targetRef = useRef(null);
     const popperRef = useRef(null);
     const [level1path, setLevel1path] = useState([]);
@@ -75,16 +78,16 @@ const NavigationOverflowMenu = ({ items, }) => {
             touchend: handleClickAway,
         };
     }, [menuOpen]);
-    return (jsxs(Fragment, { children: [jsx(NavigationIconButton, { ref: targetRef, icon: DotHorizontalIcon, onClick: () => setMenuOpen(!menuOpen) }), jsx(Popper, { anchor: targetRef.current, disablePortal: true, open: menuOpen, options: {
+    return (jsxs(Fragment, { children: [jsx(NavigationIconButton, { active: isActive, ref: targetRef, icon: DotHorizontalIcon, onClick: () => setMenuOpen(!menuOpen) }), jsx(Popper, { anchor: targetRef.current, disablePortal: true, open: menuOpen, options: {
                     placement: 'right-end',
                 }, ref: popperRef, children: jsx(TransitionGroup, { component: null, children: menuOpen && (createElement(Translate, { ...translateProps, from: 'bottom', key: "popper-list", in: true },
-                        jsx("li", { className: navigationOverflowMenuClasses.host, children: jsxs("span", { className: navigationOverflowMenuClasses.content, "aria-haspopup": "true", "aria-expanded": menuOpen, children: [jsx("ul", { className: navigationOverflowMenuClasses.subMenu, children: renderedItems }), jsx(NavigationOptionLevelContext.Provider, { value: {
+                        jsx("li", { className: navigationOverflowMenuClasses.host, children: jsxs("span", { className: navigationOverflowMenuClasses.content, "aria-haspopup": "true", "aria-expanded": menuOpen, children: [jsx(Scrollbar, { className: navigationOverflowMenuClasses.subMenu, children: jsx("ul", { children: renderedItems }) }), jsx(NavigationOptionLevelContext.Provider, { value: {
                                             level: 1,
                                             path: level1path,
-                                        }, children: level2Items.length > 0 && (jsx("ul", { className: navigationOverflowMenuClasses.subMenu, children: renderedItems2 })) }), jsx(NavigationOptionLevelContext.Provider, { value: {
+                                        }, children: level2Items.length > 0 && (jsx(Scrollbar, { className: navigationOverflowMenuClasses.subMenu, children: jsx("ul", { children: renderedItems2 }) })) }), jsx(NavigationOptionLevelContext.Provider, { value: {
                                             level: 2,
                                             path: level2path,
-                                        }, children: level3Items.length > 0 && (jsx("ul", { className: navigationOverflowMenuClasses.subMenu, children: renderedItems3 })) })] }) }))) }) })] }));
+                                        }, children: level3Items.length > 0 && (jsx(Scrollbar, { className: navigationOverflowMenuClasses.subMenu, children: jsx("ul", { children: renderedItems3 }) })) })] }) }))) }) })] }));
 };
 
 export { NavigationOverflowMenu };

package/Navigation/NavigationUserMenu.js

@@ -37,7 +37,9 @@ const NavigationUserMenu = forwardRef((props, ref) => {
         }, onClose: () => {
             setOpen(false);
             onClose === null || onClose === void 0 ? void 0 : onClose();
-        }, children: jsx("button", { className: cx(navigationUserMenuClasses.host, open && navigationUserMenuClasses.open, className), ref: ref, type: "button", children: jsx(Tooltip, { disablePortal: false, options: {
+        }, children: jsx("button", { className: cx(navigationUserMenuClasses.host, open && navigationUserMenuClasses.open, className), ref: ref, type: "button", children: jsx(Tooltip, { disablePortal: false, offsetMainAxis: collapsed
+                    ? 8 + 6 /* 6 is the padding of the item */
+                    : 8 + 8 /* 8 is the padding of the item and avatar */, options: {
                     placement: collapsed ? 'right' : 'top',
                 }, title: (collapsed || userNameOverflow) && !open ? children : undefined, children: ({ onMouseEnter, onMouseLeave, ref: tooltipRef }) => (jsxs("span", { className: navigationUserMenuClasses.content, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, ref: tooltipRef, children: [jsx("span", { className: navigationUserMenuClasses.avatar, children: imgError || !imgSrc ? (jsx(Icon, { icon: UserIcon })) : (jsx("img", { alt: "User avatar", className: navigationUserMenuClasses.avatar, src: imgSrc, onError: () => setImgError(true) })) }), children && (jsx("span", { className: navigationUserMenuClasses.userName, children: jsx("span", { ref: userNameRef, children: children }) })), jsx(Icon, { className: navigationUserMenuClasses.icon, icon: ChevronDownIcon })] })) }) }) }));
 });

package/Navigation/context.d.ts

@@ -10,6 +10,7 @@ export declare const NavigationActivatedContext: import("react").Context<{
     activatedPath: string[];
     activatedPathKey: string;
     collapsed: boolean;
+    collapsedHiddenKeys: Set<string>;
     currentPathname: string | null;
     filterText: string;
     handleCollapseChange: (newCollapsed: boolean) => void;

package/NotificationCenter/NotificationCenter.d.ts

@@ -1,10 +1,10 @@
-import { FC, Key } from 'react';
+import { FC, Key, PropsWithChildren } from 'react';
 import { DropdownOption } from '@mezzanine-ui/core/dropdown/dropdown';
 import { NotificationSeverity, NotificationType } from '@mezzanine-ui/core/notification-center';
 import { ButtonProps } from '../Button';
-import { Notifier, NotifierConfig, NotifierData } from '../Notifier';
-import { SlideProps } from '../Transition';
-export interface NotificationConfigProps extends Pick<NotifierConfig, 'duration'>, Pick<SlideProps, 'onEnter' | 'onEntered' | 'onExit' | 'onExited' | 'easing'> {
+import { NotifierConfig, NotifierData } from '../Notifier';
+import { type SlideProps } from '../Transition';
+export interface NotificationConfigProps extends Pick<NotifierConfig, 'duration'>, Pick<SlideProps, 'easing' | 'from' | 'onEnter' | 'onEntered' | 'onExit' | 'onExited'> {
     /**
      * Callback function when "View All" button is clicked.
      * This will be called after closing all notifications.
@@ -112,13 +112,63 @@ export interface NotificationData extends NotifierData, NotificationConfigProps
      */
     type?: NotificationType;
 }
-export interface NotificationCenter extends FC<NotificationData>, Notifier<NotificationData, NotificationConfigProps>, Record<NotificationSeverity, (props?: Omit<NotificationData, 'severity'>) => Key> {
+/** Props accepted by NotificationCenter severity shorthand methods such as `NotificationCenter.success`. */
+export type NotificationCenterShorthandProps = Omit<NotificationData, 'severity'>;
+/** Static severity shorthand methods attached to the {@link NotificationCenter} component. */
+export interface NotificationCenterSeverityMethods {
+    /** Display an error notification. */
+    error: (props?: NotificationCenterShorthandProps) => Key;
+    /** Display an informational notification. */
+    info: (props?: NotificationCenterShorthandProps) => Key;
+    /** Display a success notification. */
+    success: (props?: NotificationCenterShorthandProps) => Key;
+    /** Display a warning notification. */
+    warning: (props?: NotificationCenterShorthandProps) => Key;
 }
 /**
- * The react component for `mezzanine` notification center.
+ * 通知中心元件，支援即時提示（`notification`）與抽屜清單（`drawer`）兩種呈現模式。
  *
- * Use the API from the NotificationCenter instance such as `NotificationCenter.success` and `NotificationCenter.error`
- * to display a notification globally.
+ * 以 `<NotificationCenter type="notification" />` 宣告式渲染單筆浮動通知；
+ * 或使用靜態方法 `NotificationCenter.add()`、`.success()`、`.error()` 等命令式 API
+ * 觸發通知，並可透過回傳的 key 呼叫 `remove()` 收回。
+ * `type: 'drawer'` 模式下，請搭配 `NotificationCenterDrawer` 以清單方式顯示。
+ *
+ * @example
+ * ```tsx
+ * import NotificationCenter from '@mezzanine-ui/react/NotificationCenter';
+ *
+ * // 宣告式：嵌入畫面中的通知
+ * <NotificationCenter
+ *   reference="notify-1"
+ *   severity="success"
+ *   title="儲存成功"
+ *   type="notification"
+ * />
+ *
+ * // 命令式：觸發浮動通知
+ * NotificationCenter.success({ title: '儲存成功', description: '資料已更新。' });
+ * NotificationCenter.error({ title: '操作失敗', description: '請稍後再試。' });
+ *
+ * // 手動控制生命週期
+ * const key = NotificationCenter.add({ severity: 'info', title: '處理中…', type: 'notification' });
+ * NotificationCenter.remove(key);
+ * ```
+ *
+ * @see {@link NotificationData} 所有可用的通知設定項
+ * @see {@link NotificationCenterDrawer} 抽屜清單模式的容器元件
  */
-declare const NotificationCenter: NotificationCenter;
+declare const NotificationCenter: FC<PropsWithChildren<NotificationData>> & {
+    add: (notif: NotificationData & {
+        key?: Key;
+    }) => Key;
+    config: (configs: NotificationConfigProps) => void;
+    destroy: VoidFunction;
+    remove: (key: Key) => void;
+    error: (props?: NotificationCenterShorthandProps) => Key;
+    info: (props?: NotificationCenterShorthandProps) => Key;
+    success: (props?: NotificationCenterShorthandProps) => Key;
+    warning: (props?: NotificationCenterShorthandProps) => Key;
+};
+/** Full type of the {@link NotificationCenter} component including all static notification API methods. */
+export type NotificationCenterType = typeof NotificationCenter;
 export default NotificationCenter;

package/NotificationCenter/NotificationCenter.js

@@ -1,21 +1,57 @@
 'use client';
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
-import { useState, useRef, useMemo, useEffect, useCallback, Children, isValidElement, Fragment as Fragment$1 } from 'react';
+import { useState, useRef, useMemo, useEffect, useCallback, cloneElement, Children, isValidElement, Fragment as Fragment$1 } from 'react';
 import { offset, flip } from '@floating-ui/react-dom';
 import { notificationIcons, notificationClasses } from '@mezzanine-ui/core/notification-center';
-import { DotVerticalIcon, CloseIcon } from '@mezzanine-ui/icons';
+import { DotHorizontalIcon, CloseIcon } from '@mezzanine-ui/icons';
+import { MOTION_DURATION, MOTION_EASING } from '@mezzanine-ui/system/motion';
 import Button from '../Button/Button.js';
 import ButtonGroup from '../Button/ButtonGroup.js';
+import { reflow } from '../Transition/reflow.js';
+import { useSetNodeTransition } from '../Transition/useSetNodeTransition.js';
 import Typography from '../Typography/Typography.js';
+import { useComposeRefs } from '../hooks/useComposeRefs.js';
 import Icon from '../Icon/Icon.js';
 import Popper from '../Popper/Popper.js';
 import Dropdown from '../Dropdown/Dropdown.js';
 import Badge from '../Badge/Badge.js';
-import Slide from '../Transition/Slide.js';
-import cx from 'clsx';
+import Transition from '../Transition/Transition.js';
 import { createNotifier } from '../Notifier/createNotifier.js';
+import cx from 'clsx';
 
 const DEFAULT_MAX_VISIBLE_NOTIFICATIONS = 3;
+const NOTIFICATION_SLIDE_FADE_DURATION = {
+    enter: MOTION_DURATION.slow,
+    exit: MOTION_DURATION.moderate,
+};
+const NOTIFICATION_SLIDE_FADE_EASING = {
+    enter: MOTION_EASING.standard,
+    exit: MOTION_EASING.exit,
+};
+function getNotificationSlideFadeStyle(state, inProp, from) {
+    if (state === 'entering' || state === 'entered') {
+        return {
+            opacity: 1,
+            transform: 'translate3d(0, 0, 0)',
+        };
+    }
+    const style = state === 'exiting'
+        ? {
+            opacity: 0,
+            transform: 'translate3d(0, 0, 0)',
+        }
+        : {
+            opacity: 0,
+            transform: {
+                top: 'translate3d(0, -100%, 0)',
+                right: 'translate3d(100%, 0, 0)',
+            }[from],
+        };
+    if (state === 'exited' && !inProp) {
+        style.visibility = 'hidden';
+    }
+    return style;
+}
 const NotificationCenterContainer = ({ children }) => {
     const notificationItems = useMemo(() => Children.toArray(children), [children]);
     // Helper function to extract NotificationCenter component from Fragment or direct element
@@ -42,7 +78,7 @@ const NotificationCenterContainer = ({ children }) => {
             .map(extractNotificationCenter)
             .find((notification) => notification !== null);
         if (firstNotification) {
-            return (_a = firstNotification.props.maxVisibleNotifications) !== null && _a !== void 0 ? _a : DEFAULT_MAX_VISIBLE_NOTIFICATIONS;
+            return ((_a = firstNotification.props.maxVisibleNotifications) !== null && _a !== void 0 ? _a : DEFAULT_MAX_VISIBLE_NOTIFICATIONS);
         }
         return DEFAULT_MAX_VISIBLE_NOTIFICATIONS;
     }, [notificationItems]);
@@ -70,23 +106,36 @@ const NotificationCenterContainer = ({ children }) => {
     if (!notificationItems.length) {
         return null;
     }
-    return (jsxs(Fragment, { children: [visibleItems, hasOverflow
-                ? (jsx("div", { className: notificationClasses.viewAllButton, children: jsx(Button, { onClick: handleViewAll, size: "main", variant: "base-secondary", className: notificationClasses.viewAllButtonText, children: viewAllButtonText }) }))
-                : null] }));
+    return (jsxs(Fragment, { children: [visibleItems, hasOverflow ? (jsx("div", { className: notificationClasses.viewAllButton, children: jsx(Button, { onClick: handleViewAll, size: "main", variant: "base-secondary", className: notificationClasses.viewAllButtonText, children: viewAllButtonText }) })) : null] }));
 };
-/**
- * The react component for `mezzanine` notification center.
- *
- * Use the API from the NotificationCenter instance such as `NotificationCenter.success` and `NotificationCenter.error`
- * to display a notification globally.
- */
-const NotificationCenter = ((props) => {
-    const { type = 'notification', cancelButtonProps = {}, cancelButtonText = 'Cancel', confirmButtonProps = {}, confirmButtonText = 'Confirm', description, duration, onCancel: onCancelProp, onClose: onCloseProp, onConfirm: onConfirmProp, onExited: onExitedProp, reference, severity = 'info', title, timeStamp = new Date().toLocaleTimeString(), timeStampLocale = 'zh-TW', showBadge, onBadgeClick: onBadgeClickProp, options, onBadgeSelect: onBadgeSelectProp, prependTips, appendTips, ...restTransitionProps } = props;
+/** @internal Underlying React element rendered by the NotificationCenter notifier. */
+const NotificationCenterFC = (props) => {
+    var _a;
+    const { type = 'notification', cancelButtonProps = {}, cancelButtonText = 'Cancel', confirmButtonProps = {}, confirmButtonText = 'Confirm', description, duration, onCancel: onCancelProp, onClose: onCloseProp, onConfirm: onConfirmProp, onExited: onExitedProp, reference, severity = 'info', title, timeStamp = new Date().toLocaleTimeString(), timeStampLocale = 'zh-TW', showBadge, onBadgeClick: onBadgeClickProp, options, onBadgeSelect: onBadgeSelectProp, prependTips, appendTips, from = 'top', ...restTransitionProps } = props;
     const targetIcon = notificationIcons[severity];
     const [openDropdown, setOpenDropdown] = useState(false);
     const [open, setOpen] = useState(true);
     const [timeStampAnchor, setTimeStampAnchor] = useState(null);
     const timeStampRef = useRef(null);
+    const notificationSlideFadeNodeRef = useRef(null);
+    const slideFadeResolvedDuration = NOTIFICATION_SLIDE_FADE_DURATION;
+    const slideFadeEasing = (_a = restTransitionProps.easing) !== null && _a !== void 0 ? _a : NOTIFICATION_SLIDE_FADE_EASING;
+    const slideFadeDelay = 0;
+    const [setSlideTransition, resetSlideTransition] = useSetNodeTransition({
+        delay: slideFadeDelay,
+        duration: slideFadeResolvedDuration,
+        easing: slideFadeEasing,
+        properties: ['transform'],
+    }, undefined);
+    const [setFadeTransition, resetFadeTransition] = useSetNodeTransition({
+        delay: slideFadeDelay,
+        duration: slideFadeResolvedDuration,
+        easing: slideFadeEasing,
+        properties: ['opacity'],
+    }, undefined);
+    const notificationSlideFadeComposedRef = useComposeRefs([
+        notificationSlideFadeNodeRef,
+    ]);
     const isToday = useMemo(() => {
         try {
             const timestampDate = new Date(timeStamp);
@@ -120,7 +169,9 @@ const NotificationCenter = ((props) => {
             if (isToday) {
                 const diffInMs = timestampDate.getTime() - now;
                 const diffInSeconds = Math.round(diffInMs / 1000);
-                const rtf = new Intl.RelativeTimeFormat(timeStampLocale, { numeric: 'always' });
+                const rtf = new Intl.RelativeTimeFormat(timeStampLocale, {
+                    numeric: 'always',
+                });
                 const units = [
                     { unit: 'hour', seconds: 3600 },
                     { unit: 'minute', seconds: 60 },
@@ -178,7 +229,7 @@ const NotificationCenter = ((props) => {
     }, [onBadgeClickProp, setOpenDropdown, options]);
     const onClose = () => {
         setOpen(false);
-        if (onCloseProp) {
+        if (onCloseProp && reference !== undefined) {
             onCloseProp(reference);
         }
     };
@@ -198,7 +249,9 @@ const NotificationCenter = ((props) => {
         if (onExitedProp) {
             onExitedProp(node);
         }
-        NotificationCenter.remove(reference);
+        if (reference) {
+            NotificationCenter.remove(reference);
+        }
     };
     const onSelect = useCallback((option) => {
         if (onBadgeSelectProp) {
@@ -221,14 +274,9 @@ const NotificationCenter = ((props) => {
     };
     const showConfirmButton = Boolean(confirmButtonText && onConfirmProp);
     const showCancelButton = Boolean(cancelButtonText && (onCancelProp || onCloseProp));
-    const hideButtons = !(type === 'notification' && (showConfirmButton || showCancelButton));
-    const notificationContent = (jsxs("div", { className: cx(notificationClasses.host, notificationClasses.severity(severity), notificationClasses.type(type)), onMouseEnter: handleNotificationMouseEnter, onMouseLeave: handleNotificationMouseLeave, children: [targetIcon
-                ? (jsx("div", { className: notificationClasses.iconContainer, children: jsx(Icon, { icon: targetIcon, className: notificationClasses.severityIcon }) }))
-                : null, jsxs("div", { className: notificationClasses.body, children: [jsxs("div", { className: notificationClasses.bodyContent, children: [jsx("h4", { className: notificationClasses.title, children: title }), jsx(Typography, { className: notificationClasses.content, children: description })] }), !hideButtons && (jsxs(ButtonGroup, { className: notificationClasses.action, children: [showConfirmButton
-                                ? (jsx(Button, { onClick: onConfirm, size: "minor", ...confirmButtonProps, children: confirmButtonText }))
-                                : jsx(Fragment, {}), showCancelButton
-                                ? (jsx(Button, { onClick: onCancel || onClose, size: "minor", variant: "base-secondary", ...cancelButtonProps, children: cancelButtonText }))
-                                : jsx(Fragment, {})] })), type === 'drawer' && (jsxs(Fragment, { children: [isToday && (jsx(Popper, { anchor: timeStampAnchor, open: Boolean(timeStampAnchor), arrow: {
+    const hideButtons = !(type === 'notification' &&
+        (showConfirmButton || showCancelButton));
+    const notificationContent = (jsxs("div", { className: cx(notificationClasses.host, notificationClasses.severity(severity), notificationClasses.type(type)), onMouseEnter: handleNotificationMouseEnter, onMouseLeave: handleNotificationMouseLeave, children: [targetIcon ? (jsx("div", { className: notificationClasses.iconContainer, children: jsx(Icon, { icon: targetIcon, className: notificationClasses.severityIcon, size: 32 }) })) : null, jsxs("div", { className: notificationClasses.body, children: [jsxs("div", { className: notificationClasses.bodyContent, children: [jsx("h4", { className: notificationClasses.title, children: title }), jsx(Typography, { className: notificationClasses.content, children: description })] }), !hideButtons && (jsxs(ButtonGroup, { className: notificationClasses.action, children: [showCancelButton ? (jsx(Button, { onClick: onCancel || onClose, size: "minor", variant: "base-secondary", ...cancelButtonProps, children: cancelButtonText })) : null, showConfirmButton ? (jsx(Button, { onClick: onConfirm, size: "minor", ...confirmButtonProps, children: confirmButtonText })) : null] })), type === 'drawer' && (jsxs(Fragment, { children: [isToday && (jsx(Popper, { anchor: timeStampAnchor, open: Boolean(timeStampAnchor), arrow: {
                                     className: notificationClasses.timeStampPopperArrow,
                                     enabled: true,
                                     padding: 0,
@@ -236,44 +284,92 @@ const NotificationCenter = ((props) => {
                                     zIndex: 'var(--mzn-z-index-popover)',
                                 }, options: {
                                     placement: 'bottom',
-                                    middleware: [
-                                        offset({ mainAxis: 8 }),
-                                        flip(),
-                                    ],
-                                }, children: jsx("div", { className: notificationClasses.timeStampPopper, children: jsx(Typography, { className: notificationClasses.timeStampText, children: timeStamp }) }) })), jsx(Typography, { ref: timeStampRef, className: notificationClasses.timeStamp, children: formattedTimeStamp })] }))] }), type === 'drawer'
-                ? (jsx(Dropdown, { open: openDropdown, onClose: () => setOpenDropdown(false), onVisibilityChange: (open) => setOpenDropdown(open), options: options !== null && options !== void 0 ? options : [], onSelect: onSelect, placement: "bottom-end", zIndex: 'var(--mzn-z-index-popover)', children: jsxs(Button, { variant: "base-ghost", size: "minor", onClick: onClose, children: [showBadge && jsx(Badge, { variant: "dot-error" }), jsx(Icon, { icon: DotVerticalIcon, className: notificationClasses.closeIcon, size: 16, onClick: onBadgeClick })] }) }))
-                : (jsx(Icon, { icon: CloseIcon, className: notificationClasses.closeIcon, size: 16, onClick: onClose }))] }));
+                                    middleware: [offset({ mainAxis: 8 }), flip()],
+                                }, children: jsx("div", { className: notificationClasses.timeStampPopper, children: jsx(Typography, { className: notificationClasses.timeStampText, children: timeStamp }) }) })), jsx(Typography, { className: notificationClasses.timeStamp, ref: timeStampRef, variant: "label-secondary", children: formattedTimeStamp })] }))] }), type === 'drawer' ? (jsx(Dropdown, { open: openDropdown, onClose: () => setOpenDropdown(false), onVisibilityChange: (open) => setOpenDropdown(open), options: options !== null && options !== void 0 ? options : [], onSelect: onSelect, placement: "bottom-end", zIndex: 'var(--mzn-z-index-popover)', children: jsxs(Button, { variant: "base-ghost", onClick: onClose, className: notificationClasses.dotIconButton, children: [showBadge && jsx(Badge, { variant: "dot-error" }), jsx(Icon, { icon: DotHorizontalIcon, className: notificationClasses.closeIcon, size: 16, onClick: onBadgeClick })] }) })) : (jsx(Icon, { icon: CloseIcon, className: notificationClasses.closeIcon, size: 16, onClick: onClose }))] }));
     if (type === 'notification') {
-        return (jsx(Slide, { in: open, appear: true, onExited: onExited, ...restTransitionProps, children: notificationContent }));
+        return (jsx(Transition, { ...restTransitionProps, appear: true, duration: slideFadeResolvedDuration, in: open, nodeRef: notificationSlideFadeNodeRef, onEnter: (node, isAppearing) => {
+                var _a;
+                setSlideTransition(node, 'enter');
+                reflow(node);
+                (_a = restTransitionProps.onEnter) === null || _a === void 0 ? void 0 : _a.call(restTransitionProps, node, isAppearing);
+            }, onEntered: (node, isAppearing) => {
+                var _a;
+                resetSlideTransition(node);
+                (_a = restTransitionProps.onEntered) === null || _a === void 0 ? void 0 : _a.call(restTransitionProps, node, isAppearing);
+            }, onExited: (node) => {
+                resetFadeTransition(node);
+                onExited(node);
+            }, onExit: (node) => {
+                var _a;
+                setFadeTransition(node, 'exit');
+                (_a = restTransitionProps.onExit) === null || _a === void 0 ? void 0 : _a.call(restTransitionProps, node);
+            }, children: (state) => cloneElement(notificationContent, {
+                ref: notificationSlideFadeComposedRef,
+                style: {
+                    ...getNotificationSlideFadeStyle(state, open, from),
+                    ...notificationContent.props.style,
+                },
+            }) }));
     }
-    return (jsxs(Fragment, { children: [prependTips && jsx(Typography, { className: notificationClasses.prependTips, children: prependTips }), notificationContent, appendTips && jsx(Typography, { className: notificationClasses.appendTips, children: appendTips })] }));
-});
-const { add: addNotifier, config, destroy, remove } = createNotifier({
+    return (jsxs(Fragment, { children: [prependTips && (jsx(Typography, { className: notificationClasses.prependTips, children: prependTips })), notificationContent, appendTips && (jsx(Typography, { className: notificationClasses.appendTips, children: appendTips }))] }));
+};
+const { add: addNotifier, config, destroy, remove, } = createNotifier({
     duration: false,
     render: (notif) => {
         const { key, ...restNotif } = notif;
-        return (jsx(NotificationCenter, { ...restNotif, reference: key }, key));
+        return jsx(NotificationCenterFC, { ...restNotif, reference: key }, key);
     },
     renderContainer: (children) => (jsx(NotificationCenterContainer, { children: children })),
     setRoot: (root) => {
         root === null || root === void 0 ? void 0 : root.setAttribute('class', notificationClasses.root);
     },
 });
-NotificationCenter.add = (notif) => {
-    if (notif.type === 'drawer') {
-        return 'NOT_SET';
-    }
-    return addNotifier(notif);
-};
-NotificationCenter.config = config;
-NotificationCenter.destroy = destroy;
-NotificationCenter.remove = remove;
-['success', 'warning', 'error', 'info'].forEach((severity) => {
-    NotificationCenter[severity] = (props) => NotificationCenter.add({
-        ...props,
-        severity: severity || 'info',
-        type: 'notification',
-    });
+/**
+ * 通知中心元件，支援即時提示（`notification`）與抽屜清單（`drawer`）兩種呈現模式。
+ *
+ * 以 `<NotificationCenter type="notification" />` 宣告式渲染單筆浮動通知；
+ * 或使用靜態方法 `NotificationCenter.add()`、`.success()`、`.error()` 等命令式 API
+ * 觸發通知，並可透過回傳的 key 呼叫 `remove()` 收回。
+ * `type: 'drawer'` 模式下，請搭配 `NotificationCenterDrawer` 以清單方式顯示。
+ *
+ * @example
+ * ```tsx
+ * import NotificationCenter from '@mezzanine-ui/react/NotificationCenter';
+ *
+ * // 宣告式：嵌入畫面中的通知
+ * <NotificationCenter
+ *   reference="notify-1"
+ *   severity="success"
+ *   title="儲存成功"
+ *   type="notification"
+ * />
+ *
+ * // 命令式：觸發浮動通知
+ * NotificationCenter.success({ title: '儲存成功', description: '資料已更新。' });
+ * NotificationCenter.error({ title: '操作失敗', description: '請稍後再試。' });
+ *
+ * // 手動控制生命週期
+ * const key = NotificationCenter.add({ severity: 'info', title: '處理中…', type: 'notification' });
+ * NotificationCenter.remove(key);
+ * ```
+ *
+ * @see {@link NotificationData} 所有可用的通知設定項
+ * @see {@link NotificationCenterDrawer} 抽屜清單模式的容器元件
+ */
+const NotificationCenter = Object.assign(NotificationCenterFC, {
+    add: (notif) => {
+        if (notif.type === 'drawer') {
+            return 'NOT_SET';
+        }
+        return addNotifier(notif);
+    },
+    config,
+    destroy,
+    remove,
+    error: (props) => addNotifier({ ...props, severity: 'error', type: 'notification' }),
+    info: (props) => addNotifier({ ...props, severity: 'info', type: 'notification' }),
+    success: (props) => addNotifier({ ...props, severity: 'success', type: 'notification' }),
+    warning: (props) => addNotifier({ ...props, severity: 'warning', type: 'notification' }),
 });
 
 export { NotificationCenter as default };

package/NotificationCenter/NotificationCenterDrawer.d.ts

@@ -1,13 +1,63 @@
 import { type ComponentProps, type Key, type ReactElement } from 'react';
 import { DrawerSize } from '@mezzanine-ui/core/drawer';
-import { type IconDefinition } from '@mezzanine-ui/icons';
 import { type DrawerProps } from '../Drawer';
 import NotificationCenter, { type NotificationData } from './NotificationCenter';
 type NotificationDataForDrawer = NotificationData & {
     key: Key;
     type: 'drawer';
 };
-type NotificationCenterDrawerPropsBase = Pick<DrawerProps, 'controlBarAllRadioLabel' | 'controlBarCustomButtonLabel' | 'controlBarDefaultValue' | 'controlBarOnCustomButtonClick' | 'controlBarOnRadioChange' | 'controlBarReadRadioLabel' | 'controlBarShow' | 'controlBarShowUnreadButton' | 'controlBarUnreadRadioLabel' | 'controlBarValue' | 'onClose' | 'open' | 'renderControlBar'> & {
+type NotificationCenterDrawerPropsBase = Pick<DrawerProps, 'onClose' | 'open'> & {
+    /**
+     * Label for the "all" filter option in the filter bar.
+     */
+    filterBarAllRadioLabel?: DrawerProps['filterAreaAllRadioLabel'];
+    /**
+     * Label for the custom action button in the filter bar.
+     */
+    filterBarCustomButtonLabel?: DrawerProps['filterAreaCustomButtonLabel'];
+    /**
+     * Default selected filter value in the filter bar.
+     */
+    filterBarDefaultValue?: DrawerProps['filterAreaDefaultValue'];
+    /**
+     * Callback fired when the custom action button is clicked.
+     */
+    filterBarOnCustomButtonClick?: DrawerProps['filterAreaOnCustomButtonClick'];
+    /**
+     * Callback fired when the filter option changes.
+     */
+    filterBarOnRadioChange?: DrawerProps['filterAreaOnRadioChange'];
+    /**
+     * Label for the "read" filter option in the filter bar.
+     */
+    filterBarReadRadioLabel?: DrawerProps['filterAreaReadRadioLabel'];
+    /**
+     * Whether to show the filter bar.
+     */
+    filterBarShow?: DrawerProps['filterAreaShow'];
+    /**
+     * Whether to show the "unread only" shortcut button.
+     */
+    filterBarShowUnreadButton?: DrawerProps['filterAreaShowUnreadButton'];
+    /**
+     * Label for the "unread" filter option in the filter bar.
+     */
+    filterBarUnreadRadioLabel?: DrawerProps['filterAreaUnreadRadioLabel'];
+    /**
+     * Controlled selected filter value in the filter bar.
+     */
+    filterBarValue?: DrawerProps['filterAreaValue'];
+    /**
+     * Options for the filter bar dropdown.
+     * When non-empty, the right-side filter area button is replaced by a Dropdown
+     * triggered by a `DotHorizontalIcon` icon button.
+     */
+    filterBarOptions?: DrawerProps['filterAreaOptions'];
+    /**
+     * Callback fired when a filter bar dropdown option is selected.
+     * Only used when `filterBarOptions` is non-empty.
+     */
+    filterBarOnSelect?: DrawerProps['filterAreaOnSelect'];
     /**
      * The size of the drawer.
      * @default 'narrow'
@@ -18,14 +68,14 @@ type NotificationCenterDrawerPropsBase = Pick<DrawerProps, 'controlBarAllRadioLa
      * @default '更早'
      */
     earlierLabel?: string;
-    /**
-     * The icon of the empty notification.
-     */
-    emptyNotificationIcon?: IconDefinition;
     /**
      * The title of the empty notification.
      */
     emptyNotificationTitle?: string;
+    /**
+     * The description of the empty notification.
+     */
+    emptyNotificationDescription?: string;
     /**
      * The label for the "past 7 days" time group.
      * @default '過去七天'

package/NotificationCenter/NotificationCenterDrawer.js

@@ -1,12 +1,10 @@
 'use client';
-import { jsx, jsxs } from 'react/jsx-runtime';
+import { jsx } from 'react/jsx-runtime';
 import { useMemo } from 'react';
 import { notificationClasses } from '@mezzanine-ui/core/notification-center';
-import { NotificationIcon } from '@mezzanine-ui/icons';
-import Typography from '../Typography/Typography.js';
 import NotificationCenter from './NotificationCenter.js';
 import Drawer from '../Drawer/Drawer.js';
-import Icon from '../Icon/Icon.js';
+import Empty from '../Empty/Empty.js';
 
 const isValidTime = (timestamp) => {
     if (!timestamp)
@@ -57,7 +55,7 @@ const getTimeGroup = (timestamp, now) => {
     return 'earlier';
 };
 const NotificationCenterDrawer = (props) => {
-    const { children, controlBarAllRadioLabel, controlBarCustomButtonLabel, controlBarDefaultValue, controlBarOnCustomButtonClick, controlBarOnRadioChange, controlBarReadRadioLabel, controlBarShow, controlBarShowUnreadButton, controlBarUnreadRadioLabel, controlBarValue, drawerSize = 'narrow', earlierLabel, emptyNotificationIcon = NotificationIcon, emptyNotificationTitle = '目前沒有新的通知', notificationList, onClose, open, past7DaysLabel, renderControlBar, title, todayLabel, yesterdayLabel, ...restDrawerProps } = props;
+    const { children, filterBarAllRadioLabel, filterBarCustomButtonLabel, filterBarDefaultValue, filterBarOnCustomButtonClick, filterBarOnRadioChange, filterBarOnSelect, filterBarReadRadioLabel, filterBarShow, filterBarShowUnreadButton, filterBarUnreadRadioLabel, filterBarValue, filterBarOptions, drawerSize = 'narrow', earlierLabel, emptyNotificationTitle = '目前沒有新的通知', emptyNotificationDescription = '當有新的系統通知時，將會顯示在這裡。', notificationList, onClose, open, past7DaysLabel, title, todayLabel, yesterdayLabel, ...restDrawerProps } = props;
     const isEmpty = useMemo(() => {
         if (notificationList) {
             return notificationList.length === 0;
@@ -69,7 +67,7 @@ const NotificationCenterDrawer = (props) => {
     }, [notificationList, children]);
     const renderNotifications = useMemo(() => {
         const renderEmptyNotifications = () => {
-            return (jsxs("div", { className: notificationClasses.emptyNotifications, children: [jsx(Icon, { icon: emptyNotificationIcon, size: 28 }), jsx(Typography, { children: emptyNotificationTitle })] }));
+            return (jsx("div", { className: notificationClasses.emptyNotifications, children: jsx(Empty, { type: "notification", size: "main", title: emptyNotificationTitle, description: emptyNotificationDescription }) }));
         };
         if (isEmpty) {
             return renderEmptyNotifications();
@@ -115,14 +113,14 @@ const NotificationCenterDrawer = (props) => {
         isEmpty,
         notificationList,
         children,
-        emptyNotificationIcon,
         emptyNotificationTitle,
+        emptyNotificationDescription,
         earlierLabel,
         past7DaysLabel,
         todayLabel,
         yesterdayLabel,
     ]);
-    return (jsx(Drawer, { className: notificationClasses.drawer, controlBarAllRadioLabel: controlBarAllRadioLabel, controlBarCustomButtonLabel: controlBarCustomButtonLabel, controlBarDefaultValue: controlBarDefaultValue, controlBarIsEmpty: isEmpty, controlBarOnCustomButtonClick: controlBarOnCustomButtonClick, controlBarOnRadioChange: controlBarOnRadioChange, controlBarReadRadioLabel: controlBarReadRadioLabel, controlBarShow: controlBarShow, controlBarShowUnreadButton: controlBarShowUnreadButton, controlBarUnreadRadioLabel: controlBarUnreadRadioLabel, controlBarValue: controlBarValue, headerTitle: title, isHeaderDisplay: Boolean(title), onClose: onClose, open: open, renderControlBar: renderControlBar, size: drawerSize, ...restDrawerProps, children: renderNotifications }));
+    return (jsx(Drawer, { className: notificationClasses.drawer, filterAreaAllRadioLabel: filterBarAllRadioLabel, filterAreaCustomButtonLabel: filterBarCustomButtonLabel, filterAreaDefaultValue: filterBarDefaultValue, filterAreaIsEmpty: isEmpty, filterAreaOnCustomButtonClick: filterBarOnCustomButtonClick, filterAreaOnRadioChange: filterBarOnRadioChange, filterAreaOnSelect: filterBarOnSelect, filterAreaReadRadioLabel: filterBarReadRadioLabel, filterAreaShow: filterBarShow, filterAreaShowUnreadButton: filterBarShowUnreadButton, filterAreaUnreadRadioLabel: filterBarUnreadRadioLabel, filterAreaValue: filterBarValue, filterAreaOptions: filterBarOptions, headerTitle: title, isHeaderDisplay: Boolean(title), onClose: onClose, open: open, size: drawerSize, ...restDrawerProps, children: jsx("div", { className: notificationClasses.notificationsContainer, children: renderNotifications }) }));
 };
 
 export { NotificationCenterDrawer as default };

package/NotificationCenter/index.d.ts

@@ -1,5 +1,5 @@
 export type { NotificationSeverity } from '@mezzanine-ui/core/notification-center';
 export { default } from './NotificationCenter';
-export type { NotificationConfigProps, NotificationData, } from './NotificationCenter';
+export type { NotificationCenterShorthandProps, NotificationCenterSeverityMethods, NotificationCenterType, NotificationConfigProps, NotificationData, } from './NotificationCenter';
 export { default as NotificationCenterDrawer } from './NotificationCenterDrawer';
 export type { NotificationCenterDrawerProps } from './NotificationCenterDrawer';