@cube-dev/ui-kit 0.0.0-canary-b46ab85 → 0.0.0-canary-6b0df31

package/es/components/overlays/Notifications/OverlayProvider.js

@@ -0,0 +1,69 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-6b0df31
+ * Released under the MIT license.
+ */
+
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useRef } from 'react';
+import { NotificationContext, PersistentNotificationsContext, ToastContext, } from './NotificationContext.js';
+import { OverlayContainer } from './OverlayContainer.js';
+import { useNotificationState } from './use-notification-state.js';
+import { useOverlayTimers } from './use-overlay-timers.js';
+import { usePersistentState } from './use-persistent-state.js';
+import { useToastState } from './use-toast-state.js';
+// ─── Re-export context hooks for consumers ───────────────────────────
+export { useToastContext, useNotificationContext } from './NotificationContext.js';
+// ─── Constants ───────────────────────────────────────────────────────
+const DEFAULT_MAX_PERSISTENT = 200;
+// ─── OverlayProvider ─────────────────────────────────────────────────
+export function OverlayProvider({ children, maxPersistentNotifications = DEFAULT_MAX_PERSISTENT, }) {
+    // Shared ref that breaks the circular dependency between state hooks and timers.
+    // State hooks need timer methods (start/clear), timer hooks need remove methods.
+    // All consumers access the ref only inside useEvent/callbacks (never during
+    // render), so it is guaranteed to be populated before first use.
+    const timersRef = useRef(null);
+    // 1. Persistent state (no dependencies on other hooks)
+    const persistent = usePersistentState(maxPersistentNotifications);
+    // 2. Toast state — accesses timers through the shared ref
+    const toast = useToastState(timersRef);
+    // 3. Notification state — accesses timers through the shared ref
+    const notification = useNotificationState(timersRef, persistent);
+    // 4. Create timers and populate the ref
+    const timers = useOverlayTimers({
+        toastsRef: toast.toastsRef,
+        notificationsRef: notification.notificationsRef,
+        removeToast: toast.removeToast,
+        removeNotification: notification.removeNotification,
+    });
+    timersRef.current = timers;
+    // ─── Context Values ───────────────────────────────────────────────
+    // Only include actually-changing values in deps. All useEvent-based
+    // callbacks are referentially stable and omitted.
+    const toastContextValue = useMemo(() => ({
+        addToast: toast.addToast,
+        removeToast: toast.removeToast,
+        updateToast: toast.updateToast,
+        toasts: toast.toasts,
+    }), [toast.toasts]);
+    const notificationContextValue = useMemo(() => ({
+        addNotification: notification.addNotification,
+        removeNotification: notification.removeNotification,
+        updateNotification: notification.updateNotification,
+        notifications: notification.notifications,
+        addPersistentItem: persistent.addPersistentItem,
+        removePersistentItem: persistent.removePersistentItem,
+        removePersistentItemsByOwner: persistent.removePersistentItemsByOwner,
+        removeByOwner: notification.removeByOwner,
+    }), [notification.notifications]);
+    const persistentContextValue = useMemo(() => ({
+        persistentItems: persistent.persistentItems,
+        removePersistentItem: persistent.removePersistentItem,
+        clearPersistentItems: persistent.clearPersistentItems,
+        markAllAsRead: persistent.markAllAsRead,
+    }), [persistent.persistentItems]);
+    return (_jsx(ToastContext.Provider, { value: toastContextValue, children: _jsx(NotificationContext.Provider, { value: notificationContextValue, children: _jsxs(PersistentNotificationsContext.Provider, { value: persistentContextValue, children: [children, _jsx(OverlayContainer, { toasts: toast.toasts, notifications: notification.notifications, onToastExitComplete: toast.finalizeToastRemoval, onNotificationExitComplete: notification.finalizeNotificationRemoval, onNotificationDismiss: notification.removeNotification, onPauseChange: timers.handlePauseChange })] }) }) }));
+}
+
+        

package/es/components/overlays/Notifications/PersistentNotificationsList.js

@@ -0,0 +1,104 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-6b0df31
+ * Released under the MIT license.
+ */
+
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { useEvent } from '../../../_internal/index.js';
+import { tasty } from '../../../tasty/index.js';
+import { Text } from '../../content/Text.js';
+import { formatRelativeTime } from './format-relative-time.js';
+import { NotificationCard } from './NotificationCard.js';
+import { usePersistentNotifications } from './use-persistent-notifications.js';
+// ─── Constants ───────────────────────────────────────────────────────
+const MARK_READ_DELAY = 2000;
+/** Interval (ms) at which relative timestamps refresh while the list is mounted. */
+const TIMESTAMP_REFRESH_INTERVAL = 10_000;
+// ─── Styled Components ──────────────────────────────────────────────
+const ListContainer = tasty({
+    qa: 'PersistentNotificationsList',
+    role: 'log',
+    'aria-label': 'Notifications',
+    styles: {
+        display: 'flex',
+        flow: 'column',
+        gap: '.5x',
+    },
+});
+const EmptyStateContainer = tasty({
+    styles: {
+        display: 'flex',
+        placeItems: 'center',
+        placeContent: 'center',
+        padding: '4x',
+        color: '#dark.5',
+        preset: 't3',
+    },
+});
+// ─── PersistentNotificationsList Component ───────────────────────────
+/**
+ * Standardized rendering for archived/persistent notifications.
+ * Always reads items from the notification context.
+ * Composable with app-specific shells (popover, dialog, page section).
+ *
+ * Marks all items as read after being visible for 2 seconds.
+ * Relative timestamps refresh every 10 seconds while the list is mounted.
+ *
+ * @example
+ * ```tsx
+ * <PersistentNotificationsList
+ *   onDismissItem={(item) => remove(item.id)}
+ *   emptyState="No notifications"
+ * />
+ * ```
+ */
+export function PersistentNotificationsList({ onDismissItem, emptyState, }) {
+    const { items, markAllAsRead } = usePersistentNotifications();
+    const markReadTimerRef = useRef(null);
+    // Tick counter that increments every TIMESTAMP_REFRESH_INTERVAL to force
+    // re-render so relative timestamps (e.g. "5 min ago") stay up to date.
+    const [, setTick] = useState(0);
+    useEffect(() => {
+        if (items.length === 0)
+            return;
+        const interval = setInterval(() => {
+            setTick((t) => t + 1);
+        }, TIMESTAMP_REFRESH_INTERVAL);
+        return () => clearInterval(interval);
+    }, [items.length]);
+    // Mark all persistent notifications as read after a 2s delay.
+    // Re-starts the timer whenever items change (e.g. new unread items arrive
+    // while the list is already visible).
+    useEffect(() => {
+        const hasUnread = items.some((i) => !i.isRead);
+        if (!hasUnread)
+            return;
+        markReadTimerRef.current = setTimeout(() => {
+            markAllAsRead();
+        }, MARK_READ_DELAY);
+        return () => {
+            if (markReadTimerRef.current) {
+                clearTimeout(markReadTimerRef.current);
+                markReadTimerRef.current = null;
+            }
+        };
+    }, [markAllAsRead, items]);
+    if (items.length === 0) {
+        return (_jsx(ListContainer, { children: _jsx(EmptyStateContainer, { children: emptyState ?? 'No notifications' }) }));
+    }
+    return (_jsx(ListContainer, { children: items.map((item) => (_jsx(PersistentNotificationListItem, { item: item, onDismiss: onDismissItem }, String(item.id)))) }));
+}
+function PersistentNotificationListItem({ item, onDismiss, }) {
+    const suffix = (_jsx(Text, { opacity: 0.5, preset: "c2", children: formatRelativeTime(item.createdAt) }));
+    // useEvent keeps the callback stable across re-renders regardless of
+    // item reference changes (avoids unnecessary NotificationCard re-renders).
+    const handleDismiss = useEvent((_id, _reason) => {
+        onDismiss?.(item);
+    });
+    return (_jsx(NotificationCard, { qa: "PersistentNotificationItem", theme: item.theme, title: item.title, description: item.description, icon: item.icon, actions: item.actions, isDismissible: !!onDismiss, notificationId: item.id, suffix: suffix, onDismiss: onDismiss ? handleDismiss : undefined }));
+}
+
+        

package/es/components/overlays/Notifications/format-relative-time.js

@@ -0,0 +1,55 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-6b0df31
+ * Released under the MIT license.
+ */
+
+/**
+ * Lightweight relative time formatter.
+ * No external dependencies.
+ *
+ * Output format:
+ * - `just now` (< 1 minute)
+ * - `N min ago` (1–59 minutes)
+ * - `N h ago` (1–23 hours)
+ * - `N d ago` (1–6 days)
+ * - `N w ago` (1–4 weeks)
+ * - `N mo ago` (1–11 months)
+ * - `N y ago` (1+ years)
+ */
+export function formatRelativeTime(timestamp) {
+    const now = Date.now();
+    const diffMs = now - timestamp;
+    if (diffMs < 0) {
+        return 'just now';
+    }
+    const diffSeconds = Math.floor(diffMs / 1000);
+    const diffMinutes = Math.floor(diffSeconds / 60);
+    const diffHours = Math.floor(diffMinutes / 60);
+    const diffDays = Math.floor(diffHours / 24);
+    if (diffMinutes < 1) {
+        return 'just now';
+    }
+    if (diffHours < 1) {
+        return `${diffMinutes} min ago`;
+    }
+    if (diffDays < 1) {
+        return `${diffHours} h ago`;
+    }
+    if (diffDays < 7) {
+        return `${diffDays} d ago`;
+    }
+    const diffWeeks = Math.floor(diffDays / 7);
+    if (diffDays < 30) {
+        return `${diffWeeks} w ago`;
+    }
+    const diffMonths = Math.floor(diffDays / 30);
+    if (diffDays < 365) {
+        return `${diffMonths} mo ago`;
+    }
+    const diffYears = Math.floor(diffDays / 365);
+    return `${diffYears} y ago`;
+}
+
+        

package/es/components/overlays/Notifications/index.js

@@ -0,0 +1,51 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-6b0df31
+ * Released under the MIT license.
+ */
+
+// ─── Components ──────────────────────────────────────────────────────
+import { Notification as NotificationBase } from './Notification.js';
+import { NotificationAction } from './NotificationAction.js';
+export { NotificationAction } from './NotificationAction.js';
+export { NotificationCard } from './NotificationCard.js';
+export { NotificationItem } from './NotificationItem.js';
+export { PersistentNotificationsList } from './PersistentNotificationsList.js';
+// ─── Provider ────────────────────────────────────────────────────────
+export { OverlayProvider } from './OverlayProvider.js';
+// useToastContext is re-exported for Toast module backward compatibility
+export { useToastContext } from './NotificationContext.js';
+// ─── Hooks ───────────────────────────────────────────────────────────
+export { useNotifications } from './use-notifications.js';
+export { usePersistentNotifications, useNotificationsCount, } from './use-persistent-notifications.js';
+// ─── Utilities ───────────────────────────────────────────────────────
+export { formatRelativeTime } from './format-relative-time.js';
+// ─── Compound Notification Component ─────────────────────────────────
+/**
+ * Declarative Notification component with compound API.
+ *
+ * @example
+ * ```tsx
+ * // Declarative usage
+ * <Notification
+ *   id="release:new-version"
+ *   theme="warning"
+ *   title="New release available"
+ *   description="2.0.0 can be installed now."
+ *   actions={
+ *     <>
+ *       <Notification.Action>Later</Notification.Action>
+ *       <Notification.Action onPress={() => openUpgradeDialog()}>
+ *         Upgrade
+ *       </Notification.Action>
+ *     </>
+ *   }
+ * />
+ * ```
+ */
+export const Notification = Object.assign(NotificationBase, {
+    Action: NotificationAction,
+});
+
+        

package/es/components/overlays/{NewNotifications/NotificationsList → Notifications}/types.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-b46ab85
+ * @cube-dev/ui-kit v0.0.0-canary-6b0df31
  * Released under the MIT license.
  */
 

package/es/components/overlays/Notifications/use-notification-state.js

@@ -0,0 +1,205 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-6b0df31
+ * Released under the MIT license.
+ */
+
+import { useRef, useState } from 'react';
+import { useEvent } from '../../../_internal/index.js';
+// ─── Constants ───────────────────────────────────────────────────────
+const DEFAULT_NOTIFICATION_DURATION = 5000;
+const DEFAULT_PERSISTENT_NOTIFICATION_DURATION = 10000;
+const MAX_NOTIFICATIONS = 5;
+// ─── Helpers ─────────────────────────────────────────────────────────
+function getDuration(notif) {
+    if (notif.duration === null)
+        return null;
+    if (notif.duration !== undefined)
+        return notif.duration;
+    return notif.persistent
+        ? DEFAULT_PERSISTENT_NOTIFICATION_DURATION
+        : DEFAULT_NOTIFICATION_DURATION;
+}
+function matchesNotificationId(item, id) {
+    return item.id === id || item.internalId === String(id);
+}
+function findNotification(list, id) {
+    return list.find((n) => matchesNotificationId(n, id));
+}
+// ─── Hook ────────────────────────────────────────────────────────────
+/**
+ * @param timersRef - Ref to the shared OverlayTimers instance. Accessed only
+ *   inside callbacks (never during render), so it is guaranteed to be populated.
+ */
+export function useNotificationState(timersRef, persistent) {
+    const [notifications, setNotifications] = useState([]);
+    const notificationsRef = useRef(notifications);
+    notificationsRef.current = notifications;
+    const idCounter = useRef(0);
+    // ─── Evict Helper ──────────────────────────────────────────────
+    /**
+     * Evict the oldest active notification to make room for a new one.
+     * Clears its timer and moves it to the persistent list if applicable.
+     * Must be called OUTSIDE setState updaters (StrictMode-safe).
+     */
+    const evictOldest = useEvent(() => {
+        const active = notificationsRef.current.filter((n) => !n.isExiting);
+        if (active.length === 0)
+            return null;
+        // Oldest by createdAt (active list preserves insertion order)
+        const oldest = active[0];
+        timersRef.current?.clearNotificationTimer(oldest.internalId);
+        // Eviction counts as a timeout dismissal — move to persistent list if applicable
+        if (oldest.persistent) {
+            persistent.addPersistentItem({
+                id: oldest.id ?? oldest.internalId,
+                theme: oldest.theme,
+                title: oldest.title,
+                description: oldest.description,
+                icon: oldest.icon,
+                actions: oldest.actions,
+                createdAt: oldest.createdAt,
+                updatedAt: oldest.updatedAt,
+                isRead: false,
+                ownerId: oldest.ownerId,
+            });
+        }
+        return oldest.internalId;
+    });
+    // ─── Remove ─────────────────────────────────────────────────────
+    const removeNotification = useEvent((id, reason = 'api') => {
+        // Read from ref (synchronous) to perform side effects OUTSIDE the updater.
+        // This prevents double-fire in StrictMode and avoids calling setState
+        // (addPersistentItem) inside another setState updater.
+        const notif = findNotification(notificationsRef.current, id);
+        if (!notif || notif.isExiting)
+            return;
+        timersRef.current?.clearNotificationTimer(notif.internalId);
+        // If persistent and dismissed by timeout, move to persistent list.
+        // User-initiated dismissals (action, close) intentionally skip persistence.
+        if (notif.persistent && reason === 'timeout') {
+            persistent.addPersistentItem({
+                id: notif.id ?? notif.internalId,
+                theme: notif.theme,
+                title: notif.title,
+                description: notif.description,
+                icon: notif.icon,
+                actions: notif.actions,
+                createdAt: notif.createdAt,
+                updatedAt: notif.updatedAt,
+                isRead: false,
+                ownerId: notif.ownerId,
+            });
+        }
+        setNotifications((prev) => prev.map((n) => matchesNotificationId(n, id) ? { ...n, isExiting: true } : n));
+    });
+    // ─── Finalize ──────────────────────────────────────────────────
+    const finalizeNotificationRemoval = useEvent((internalId) => {
+        setNotifications((prev) => prev.filter((n) => n.internalId !== internalId));
+    });
+    // ─── Add ────────────────────────────────────────────────────────
+    const addNotification = useEvent((options, ownerId) => {
+        idCounter.current += 1;
+        const internalId = `notif-${idCounter.current}-${Date.now()}`;
+        const now = Date.now();
+        const id = options.id ?? internalId;
+        // Check for existing notification with same id via the ref (synchronous read).
+        const existingNotif = options.id != null
+            ? notificationsRef.current.find((n) => n.id === options.id && !n.isExiting)
+            : undefined;
+        if (existingNotif) {
+            // In-place update of an existing notification
+            const returnId = existingNotif.id ?? existingNotif.internalId;
+            const prevTitle = existingNotif.title;
+            const prevDescription = existingNotif.description;
+            // Timer reset on string title/description change
+            const titleChanged = typeof options.title === 'string' &&
+                typeof prevTitle === 'string' &&
+                options.title !== prevTitle;
+            const descriptionChanged = typeof options.description === 'string' &&
+                typeof prevDescription === 'string' &&
+                options.description !== prevDescription;
+            if (titleChanged || descriptionChanged) {
+                const duration = getDuration(options);
+                if (duration != null && duration > 0) {
+                    timersRef.current?.startNotificationTimer(existingNotif.internalId, existingNotif.id ?? existingNotif.internalId, duration);
+                }
+            }
+            setNotifications((prev) => prev.map((n) => {
+                if (n.internalId === existingNotif.internalId) {
+                    return {
+                        ...n,
+                        ...options,
+                        internalId: n.internalId,
+                        createdAt: n.createdAt,
+                        updatedAt: now,
+                        ownerId: ownerId ?? n.ownerId,
+                    };
+                }
+                return n;
+            }));
+            return returnId;
+        }
+        // New notification — always show immediately, evicting the oldest if at cap.
+        // Read from ref (synchronous) to perform side effects OUTSIDE the updater.
+        const activeCount = notificationsRef.current.filter((n) => !n.isExiting).length;
+        const newNotification = {
+            ...options,
+            id,
+            internalId,
+            createdAt: now,
+            updatedAt: now,
+            ownerId,
+        };
+        // Evict oldest if at cap (side effects outside updater)
+        let evictedInternalId = null;
+        if (activeCount >= MAX_NOTIFICATIONS) {
+            evictedInternalId = evictOldest();
+        }
+        // Start timer for the new notification
+        const duration = getDuration(options);
+        if (duration != null && duration > 0) {
+            timersRef.current?.startNotificationTimer(internalId, id, duration);
+        }
+        setNotifications((prev) => {
+            let next = prev;
+            if (evictedInternalId) {
+                next = next.map((n) => n.internalId === evictedInternalId ? { ...n, isExiting: true } : n);
+            }
+            return [...next, newNotification];
+        });
+        return id;
+    });
+    // ─── Update ─────────────────────────────────────────────────────
+    const updateNotification = useEvent((id, options) => {
+        setNotifications((prev) => prev.map((n) => matchesNotificationId(n, id)
+            ? { ...n, ...options, updatedAt: Date.now() }
+            : n));
+    });
+    // ─── Owner Cleanup ──────────────────────────────────────────────
+    const removeByOwner = useEvent((ownerId) => {
+        // Clear timers outside the updater (StrictMode-safe).
+        const owned = notificationsRef.current.filter((n) => n.ownerId === ownerId && !n.isExiting);
+        for (const n of owned) {
+            timersRef.current?.clearNotificationTimer(n.internalId);
+        }
+        setNotifications((prev) => prev.map((n) => {
+            if (n.ownerId === ownerId && !n.isExiting) {
+                return { ...n, isExiting: true };
+            }
+            return n;
+        }));
+    });
+    return {
+        notifications,
+        notificationsRef,
+        addNotification,
+        removeNotification,
+        updateNotification,
+        finalizeNotificationRemoval,
+        removeByOwner,
+    };
+}
+
+        

package/es/components/overlays/Notifications/use-notifications.js

@@ -0,0 +1,175 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-6b0df31
+ * Released under the MIT license.
+ */
+
+import { useEffect, useRef } from 'react';
+import { useEvent } from '../../../_internal/index.js';
+import { useWarn } from '../../../_internal/hooks/use-warn.js';
+import { useNotificationContext } from './NotificationContext.js';
+let ownerIdCounter = 0;
+function generateOwnerId() {
+    ownerIdCounter += 1;
+    return `notif-owner-${ownerIdCounter}-${Date.now()}`;
+}
+function isStoredMode(options) {
+    return options.mode === 'stored';
+}
+/**
+ * Hook to display and manage notifications.
+ *
+ * Each hook instance acts as an owner scope:
+ * - `notify()` created from this instance attaches ownership metadata.
+ * - On unmount, all attached visible overlay notifications are dismissed.
+ * - On unmount, all attached persistent records are also removed.
+ * - `notify()`/`dismiss()` calls from stale closures after unmount are no-ops.
+ *
+ * @example
+ * ```tsx
+ * const { notify, record, dismiss } = useNotifications();
+ *
+ * notify({
+ *   id: 'deploy:123',
+ *   theme: 'success',
+ *   title: 'Deployment completed',
+ *   description: 'Version 1.4.2 is live.',
+ *   actions: (
+ *     <>
+ *       <Notification.Action onPress={() => openLogs()}>View logs</Notification.Action>
+ *       <Notification.Action onPress={() => openDeployment()}>Open</Notification.Action>
+ *     </>
+ *   ),
+ * });
+ *
+ * // Store directly to persistent list (no overlay)
+ * record({
+ *   id: 'server:alert-1',
+ *   theme: 'warning',
+ *   title: 'Server alert',
+ * });
+ * ```
+ */
+export function useNotifications() {
+    const { addNotification, removeNotification, addPersistentItem, removePersistentItem, removeByOwner, removePersistentItemsByOwner, } = useNotificationContext();
+    const ownerIdRef = useRef(generateOwnerId());
+    const isMountedRef = useRef(true);
+    const cleanupTimerRef = useRef(null);
+    // Track current options for validation
+    const lastOptionsRef = useRef(null);
+    // ─── Validation Warnings ──────────────────────────────────────────
+    useWarn(lastOptionsRef.current &&
+        'persistent' in lastOptionsRef.current &&
+        lastOptionsRef.current.persistent === true &&
+        lastOptionsRef.current.id == null, {
+        once: false,
+        key: ['Notification', 'persistent-without-id'],
+        args: [
+            'Notification: `persistent: true` requires an explicit `id` for reliable dedupe/upsert.',
+        ],
+    });
+    useWarn(lastOptionsRef.current?.mode === 'stored' &&
+        lastOptionsRef.current.id == null, {
+        once: false,
+        key: ['Notification', 'stored-without-id'],
+        args: [
+            'Notification: `mode: "stored"` should have an explicit `id` for reliable upsert.',
+        ],
+    });
+    // ─── Helpers ─────────────────────────────────────────────────────
+    const storedIdCounter = useRef(0);
+    const createStoredHandle = useEvent((options) => {
+        storedIdCounter.current += 1;
+        const now = Date.now();
+        const id = options.id ?? `stored-${storedIdCounter.current}-${now}`;
+        const createdAt = options.createdAt ?? now;
+        const persistentItem = {
+            id,
+            theme: options.theme,
+            title: options.title,
+            description: options.description,
+            icon: options.icon,
+            actions: options.actions ?? undefined,
+            createdAt,
+            updatedAt: createdAt,
+            ownerId: ownerIdRef.current,
+        };
+        addPersistentItem(persistentItem);
+        return {
+            id,
+            dismiss: () => {
+                removePersistentItem(id);
+            },
+        };
+    });
+    // ─── API ──────────────────────────────────────────────────────────
+    const notify = useEvent((options) => {
+        // Stale closure guard
+        if (!isMountedRef.current) {
+            return {
+                id: options.id ?? '',
+                dismiss: () => { },
+            };
+        }
+        lastOptionsRef.current = options;
+        if (isStoredMode(options)) {
+            return createStoredHandle(options);
+        }
+        // Overlay mode
+        const overlayOptions = {
+            ...options,
+            mode: 'overlay',
+        };
+        const notificationId = addNotification(overlayOptions, ownerIdRef.current);
+        return {
+            id: notificationId,
+            dismiss: () => {
+                if (isMountedRef.current) {
+                    removeNotification(notificationId, 'api');
+                }
+            },
+        };
+    });
+    // `record()` is intentionally kept as a separate method from `notify()` to make
+    // the API more explicit: `record()` always stores directly to the persistent list
+    // (no overlay), while `notify()` defaults to overlay mode. Having both avoids
+    // the caller needing to remember to pass `mode: 'stored'` every time.
+    const record = useEvent((options) => {
+        // Stale closure guard
+        if (!isMountedRef.current) {
+            return {
+                id: options.id ?? '',
+                dismiss: () => { },
+            };
+        }
+        lastOptionsRef.current = { ...options, mode: 'stored' };
+        return createStoredHandle(options);
+    });
+    const dismiss = useEvent((id) => {
+        if (!isMountedRef.current)
+            return;
+        removeNotification(id, 'api');
+    });
+    // ─── Ownership Cleanup ────────────────────────────────────────────
+    useEffect(() => {
+        isMountedRef.current = true;
+        // Cancel any pending cleanup (Strict Mode re-mount)
+        if (cleanupTimerRef.current) {
+            clearTimeout(cleanupTimerRef.current);
+            cleanupTimerRef.current = null;
+        }
+        return () => {
+            isMountedRef.current = false;
+            // Deferred cleanup — cancelled if owner re-mounts within same tick
+            // (Strict Mode / Suspense safe)
+            cleanupTimerRef.current = setTimeout(() => {
+                removeByOwner(ownerIdRef.current);
+                removePersistentItemsByOwner(ownerIdRef.current);
+            }, 0);
+        };
+    }, [removeByOwner, removePersistentItemsByOwner]);
+    return { notify, record, dismiss };
+}
+
+