@cube-dev/ui-kit 0.113.1 → 0.114.0

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

@@ -0,0 +1,239 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.114.0
+ * Released under the MIT license.
+ */
+
+import { useRef, useState } from 'react';
+import { useEvent } from '../../../_internal/index.js';
+// ─── Constants ───────────────────────────────────────────────────────
+const DEFAULT_NOTIFICATION_DURATION = 3000;
+const DEFAULT_PERSISTENT_NOTIFICATION_DURATION = 5000;
+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 (notif.persistent) {
+            if (reason === 'close' || reason === 'timeout') {
+                // Dismiss button, Escape, or auto-dismiss timeout — move to persistent list.
+                // If the same id is triggered again, it skips the overlay and updates the
+                // persistent list directly.
+                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: true,
+                    ownerId: notif.ownerId,
+                });
+            }
+            else if (reason === 'action') {
+                // User clicked a regular action (not dismiss) — fully dismiss the
+                // notification so it never reappears (overlay or persistent list).
+                persistent.removePersistentItem(notif.id ?? notif.internalId);
+            }
+            // reason === 'api' — programmatic cleanup (e.g. component unmount).
+            // No persistence, no full-dismiss tracking.
+        }
+        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;
+        // If the user explicitly removed this notification from the persistent
+        // list, completely ignore it — no overlay, no persistent storage.
+        if (options.id != null && persistent.isFullyDismissedId(options.id)) {
+            return id;
+        }
+        // If this persistent id was previously dismissed to the persistent list,
+        // skip the overlay and update the persistent item directly.
+        if (options.persistent &&
+            options.id != null &&
+            persistent.hasDismissedPersistentId(options.id)) {
+            persistent.addPersistentItem({
+                id,
+                theme: options.theme,
+                title: options.title,
+                description: options.description,
+                icon: options.icon,
+                actions: options.actions,
+                createdAt: now,
+                updatedAt: now,
+                isRead: false,
+                ownerId,
+            });
+            return id;
+        }
+        // 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.114.0
+ * 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 };
+}
+
+        

package/es/components/overlays/Notifications/use-overlay-timers.js

@@ -0,0 +1,141 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.114.0
+ * Released under the MIT license.
+ */
+
+import { useEffect, useRef } from 'react';
+import { useEvent } from '../../../_internal/index.js';
+/**
+ * Creates a start/clear/pause/resume pair for a single timer category.
+ * Eliminates duplication between toast and notification timer logic.
+ */
+function createTimerManager(timersMap, pausedMap, isPausedRef, onTimeout, findItem) {
+    const clear = (internalId) => {
+        const timer = timersMap.get(internalId);
+        if (timer) {
+            clearTimeout(timer);
+            timersMap.delete(internalId);
+        }
+        pausedMap.delete(internalId);
+    };
+    const start = (internalId, id, duration) => {
+        clear(internalId);
+        pausedMap.set(internalId, {
+            remaining: duration,
+            startedAt: Date.now(),
+        });
+        if (isPausedRef.current) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            onTimeout(id);
+        }, duration);
+        timersMap.set(internalId, timer);
+    };
+    const pauseAll = () => {
+        timersMap.forEach((timer, internalId) => {
+            clearTimeout(timer);
+            timersMap.delete(internalId);
+            const info = pausedMap.get(internalId);
+            if (info) {
+                const elapsed = Date.now() - info.startedAt;
+                pausedMap.set(internalId, {
+                    remaining: Math.max(0, info.remaining - elapsed),
+                    startedAt: Date.now(),
+                });
+            }
+        });
+    };
+    const resumeAll = () => {
+        pausedMap.forEach((info, internalId) => {
+            const item = findItem(internalId);
+            if (info.remaining <= 0) {
+                pausedMap.delete(internalId);
+                if (item && !item.isExiting) {
+                    onTimeout(item.id ?? item.internalId);
+                }
+                return;
+            }
+            if (item && !item.isExiting) {
+                const timer = setTimeout(() => {
+                    onTimeout(item.id ?? item.internalId);
+                }, info.remaining);
+                timersMap.set(internalId, timer);
+                pausedMap.set(internalId, {
+                    remaining: info.remaining,
+                    startedAt: Date.now(),
+                });
+            }
+        });
+    };
+    const clearAll = () => {
+        timersMap.forEach((timer) => clearTimeout(timer));
+        timersMap.clear();
+    };
+    return { start, clear, pauseAll, resumeAll, clearAll };
+}
+// ─── Hook ────────────────────────────────────────────────────────────
+export function useOverlayTimers(deps) {
+    const { toastsRef, notificationsRef, removeToast, removeNotification } = deps;
+    const toastTimersMap = useRef(new Map()).current;
+    const notificationTimersMap = useRef(new Map()).current;
+    const isPausedRef = useRef(false);
+    // Shared paused-timers map. Toast and notification internalIds use distinct prefixes
+    // ('toast-' and 'notif-') so they coexist safely in a single map.
+    const pausedMap = useRef(new Map()).current;
+    const toastManager = useRef(null);
+    const notifManager = useRef(null);
+    // Lazily create managers — deps are stable (useEvent / refs), so this runs once.
+    if (!toastManager.current) {
+        toastManager.current = createTimerManager(toastTimersMap, pausedMap, isPausedRef, (id) => removeToast(id), (internalId) => toastsRef.current?.find((t) => t.internalId === internalId));
+    }
+    if (!notifManager.current) {
+        notifManager.current = createTimerManager(notificationTimersMap, pausedMap, isPausedRef, (id) => removeNotification(id, 'timeout'), (internalId) => notificationsRef.current?.find((n) => n.internalId === internalId));
+    }
+    // ─── Stable callbacks ──────────────────────────────────────────────
+    const startToastTimer = useEvent((internalId, id, duration) => {
+        toastManager.current.start(internalId, id, duration);
+    });
+    const clearToastTimer = useEvent((internalId) => {
+        toastManager.current.clear(internalId);
+    });
+    const startNotificationTimer = useEvent((internalId, id, duration) => {
+        notifManager.current.start(internalId, id, duration);
+    });
+    const clearNotificationTimer = useEvent((internalId) => {
+        notifManager.current.clear(internalId);
+    });
+    // ─── Pause / Resume ─────────────────────────────────────────────
+    const handlePauseChange = useEvent((paused) => {
+        if (paused === isPausedRef.current)
+            return;
+        isPausedRef.current = paused;
+        if (paused) {
+            toastManager.current.pauseAll();
+            notifManager.current.pauseAll();
+        }
+        else {
+            toastManager.current.resumeAll();
+            notifManager.current.resumeAll();
+        }
+    });
+    // ─── Cleanup on unmount ─────────────────────────────────────────
+    useEffect(() => {
+        return () => {
+            toastManager.current.clearAll();
+            notifManager.current.clearAll();
+            pausedMap.clear();
+        };
+    }, []);
+    return {
+        startToastTimer,
+        clearToastTimer,
+        startNotificationTimer,
+        clearNotificationTimer,
+        handlePauseChange,
+    };
+}
+
+        

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

@@ -0,0 +1,63 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.114.0
+ * Released under the MIT license.
+ */
+
+import { useMemo } from 'react';
+import { usePersistentNotificationsContext } from './NotificationContext.js';
+/**
+ * Hook to access the persistent notifications list.
+ *
+ * Items are ordered newest first (by `createdAt`, descending).
+ *
+ * @example
+ * ```tsx
+ * const { items, count, remove, clear } = usePersistentNotifications();
+ *
+ * return (
+ *   <div>
+ *     <span>Notifications ({count})</span>
+ *     {items.map(item => (
+ *       <div key={item.id}>
+ *         {item.title}
+ *         <button onClick={() => remove(item.id)}>Remove</button>
+ *       </div>
+ *     ))}
+ *     <button onClick={clear}>Clear all</button>
+ *   </div>
+ * );
+ * ```
+ */
+export function usePersistentNotifications() {
+    const { persistentItems, removePersistentItem, clearPersistentItems, markAllAsRead, } = usePersistentNotificationsContext();
+    return useMemo(() => ({
+        items: persistentItems,
+        count: persistentItems.length,
+        remove: removePersistentItem,
+        clear: clearPersistentItems,
+        markAllAsRead,
+    }), [persistentItems]);
+}
+/**
+ * Hook to get total and unread counts for persistent notifications.
+ *
+ * - `total` — number of items in the persistent list.
+ * - `unread` — items that haven't been seen in `PersistentNotificationsList` yet.
+ *
+ * @example
+ * ```tsx
+ * const { total, unread } = useNotificationsCount();
+ * return <Badge count={unread} />;
+ * ```
+ */
+export function useNotificationsCount() {
+    const { persistentItems } = usePersistentNotificationsContext();
+    return useMemo(() => ({
+        total: persistentItems.length,
+        unread: persistentItems.filter((i) => !i.isRead).length,
+    }), [persistentItems]);
+}
+
+