@cube-dev/ui-kit 0.114.0 → 0.116.0

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

@@ -1,120 +0,0 @@
-/**
- * @license MIT
- * author: Cube Dev Team
- * @cube-dev/ui-kit v0.114.0
- * Released under the MIT license.
- */
-
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useContext, useEffect, useRef, useState } from 'react';
-import { useEvent } from '../../../_internal/index.js';
-import { tasty } from '../../../tasty/index.js';
-import { Divider } from '../../content/Divider.js';
-import { Text } from '../../content/Text.js';
-import { formatRelativeTime } from './format-relative-time.js';
-import { NotificationActionInterceptorContext } from './NotificationAction.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',
-    },
-});
-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.
- *
- * Items are always dismissible. Dismissing an item removes it from the
- * persistent list and marks its ID as "fully dismissed" — subsequent triggers
- * with the same ID will be completely ignored (no overlay, no re-archival).
- *
- * @example
- * ```tsx
- * <PersistentNotificationsList emptyState="No notifications" />
- * ```
- */
-export function PersistentNotificationsList({ onDismissItem, onAction, emptyState, }) {
-    const { items, remove, markAllAsRead } = usePersistentNotifications();
-    // Default dismiss handler removes the item from the persistent list (which
-    // also marks the id as "fully dismissed" so it won't reappear).
-    // If a consumer provides `onDismissItem`, it is called *after* the built-in removal.
-    const handleDismiss = useEvent((item) => {
-        remove(item.id);
-        onDismissItem?.(item);
-    });
-    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(NotificationActionInterceptorContext.Provider, { value: onAction ?? null, children: _jsx(ListContainer, { children: items.map((item, index) => (_jsxs(Fragment, { children: [index > 0 && _jsx(Divider, {}), _jsx(PersistentNotificationListItem, { item: item, onDismiss: handleDismiss })] }, 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);
-    });
-    const parentInterceptor = useContext(NotificationActionInterceptorContext);
-    // Chains with the list-level interceptor (e.g. closing the parent popover).
-    // Dismissal itself is handled by NotificationAction via the dismiss context
-    // to avoid double-firing onDismiss.
-    const handleItemAction = useEvent(() => {
-        parentInterceptor?.();
-    });
-    return (_jsx(NotificationActionInterceptorContext.Provider, { value: handleItemAction, children: _jsx(NotificationCard, { qa: "PersistentNotificationItem", theme: item.theme, title: item.title, description: item.description, icon: item.icon, actions: item.actions, isDismissible: !!onDismiss, elevated: false, notificationId: item.id, suffix: suffix, onDismiss: onDismiss ? handleDismiss : undefined }) }));
-}
-
-        

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

@@ -1,55 +0,0 @@
-/**
- * @license MIT
- * author: Cube Dev Team
- * @cube-dev/ui-kit v0.114.0
- * 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

@@ -1,51 +0,0 @@
-/**
- * @license MIT
- * author: Cube Dev Team
- * @cube-dev/ui-kit v0.114.0
- * 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/Notifications/types.js

@@ -1,10 +0,0 @@
-/**
- * @license MIT
- * author: Cube Dev Team
- * @cube-dev/ui-kit v0.114.0
- * Released under the MIT license.
- */
-
-export {};
-
-        

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

@@ -1,239 +0,0 @@
-/**
- * @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

@@ -1,175 +0,0 @@
-/**
- * @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 };
-}
-
-