@cube-dev/ui-kit 0.114.0 → 0.115.0

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

@@ -0,0 +1,176 @@
+/** @license MIT | @cube-dev/ui-kit v0.115.0 | Cube Dev Team */
+import { useEvent } from "../../../_internal/hooks/use-event.js";
+import { useRef, useState } from "react";
+
+//#region src/components/overlays/Notifications/use-notification-state.ts
+const DEFAULT_NOTIFICATION_DURATION = 3e3;
+const DEFAULT_PERSISTENT_NOTIFICATION_DURATION = 5e3;
+const MAX_NOTIFICATIONS = 5;
+function getDuration(notif) {
+	if (notif.duration === null) return null;
+	if (notif.duration !== void 0) 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));
+}
+/**
+* @param timersRef - Ref to the shared OverlayTimers instance. Accessed only
+*   inside callbacks (never during render), so it is guaranteed to be populated.
+*/
+function useNotificationState(timersRef, persistent) {
+	const [notifications, setNotifications] = useState([]);
+	const notificationsRef = useRef(notifications);
+	notificationsRef.current = notifications;
+	const idCounter = useRef(0);
+	/**
+	* 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;
+		const oldest = active[0];
+		timersRef.current?.clearNotificationTimer(oldest.internalId);
+		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;
+	});
+	const removeNotification = useEvent((id, reason = "api") => {
+		const notif = findNotification(notificationsRef.current, id);
+		if (!notif || notif.isExiting) return;
+		timersRef.current?.clearNotificationTimer(notif.internalId);
+		if (notif.persistent) {
+			if (reason === "close" || 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: true,
+				ownerId: notif.ownerId
+			});
+			else if (reason === "action") persistent.removePersistentItem(notif.id ?? notif.internalId);
+		}
+		setNotifications((prev) => prev.map((n) => matchesNotificationId(n, id) ? {
+			...n,
+			isExiting: true
+		} : n));
+	});
+	const finalizeNotificationRemoval = useEvent((internalId) => {
+		setNotifications((prev) => prev.filter((n) => n.internalId !== internalId));
+	});
+	return {
+		notifications,
+		notificationsRef,
+		addNotification: useEvent((options, ownerId) => {
+			idCounter.current += 1;
+			const internalId = `notif-${idCounter.current}-${Date.now()}`;
+			const now = Date.now();
+			const id = options.id ?? internalId;
+			if (options.id != null && persistent.isFullyDismissedId(options.id)) return id;
+			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;
+			}
+			const existingNotif = options.id != null ? notificationsRef.current.find((n) => n.id === options.id && !n.isExiting) : void 0;
+			if (existingNotif) {
+				const returnId = existingNotif.id ?? existingNotif.internalId;
+				const prevTitle = existingNotif.title;
+				const prevDescription = existingNotif.description;
+				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;
+			}
+			const activeCount = notificationsRef.current.filter((n) => !n.isExiting).length;
+			const newNotification = {
+				...options,
+				id,
+				internalId,
+				createdAt: now,
+				updatedAt: now,
+				ownerId
+			};
+			let evictedInternalId = null;
+			if (activeCount >= MAX_NOTIFICATIONS) evictedInternalId = evictOldest();
+			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;
+		}),
+		removeNotification,
+		updateNotification: useEvent((id, options) => {
+			setNotifications((prev) => prev.map((n) => matchesNotificationId(n, id) ? {
+				...n,
+				...options,
+				updatedAt: Date.now()
+			} : n));
+		}),
+		finalizeNotificationRemoval,
+		removeByOwner: useEvent((ownerId) => {
+			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;
+			}));
+		})
+	};
+}
+
+//#endregion
+export { useNotificationState };
+//# sourceMappingURL=use-notification-state.js.map

package/dist/components/overlays/Notifications/use-notification-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-notification-state.js","names":[],"sources":["../../../../src/components/overlays/Notifications/use-notification-state.ts"],"sourcesContent":["import { Key, useRef, useState } from 'react';\n\nimport { useEvent } from '../../../_internal';\n\nimport type {\n  DismissReason,\n  InternalNotification,\n  OverlayNotificationOptions,\n  PersistentNotificationItem,\n} from './types';\nimport type { OverlayTimers } from './use-overlay-timers';\n\n// ─── Constants ───────────────────────────────────────────────────────\n\nconst DEFAULT_NOTIFICATION_DURATION = 3000;\nconst DEFAULT_PERSISTENT_NOTIFICATION_DURATION = 5000;\nconst MAX_NOTIFICATIONS = 5;\n\n// ─── Types ───────────────────────────────────────────────────────────\n\nexport interface PersistentCallbacks {\n  addPersistentItem: (item: PersistentNotificationItem) => void;\n  removePersistentItem: (id: Key) => void;\n  hasDismissedPersistentId: (id: Key) => boolean;\n  isFullyDismissedId: (id: Key) => boolean;\n}\n\nexport interface NotificationState {\n  notifications: InternalNotification[];\n  notificationsRef: ReturnType<typeof useRef<InternalNotification[]>>;\n  addNotification: (\n    options: OverlayNotificationOptions,\n    ownerId?: string,\n  ) => Key;\n  removeNotification: (id: Key, reason?: DismissReason) => void;\n  updateNotification: (\n    id: Key,\n    options: Partial<OverlayNotificationOptions>,\n  ) => void;\n  finalizeNotificationRemoval: (internalId: string) => void;\n  removeByOwner: (ownerId: string) => void;\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────\n\nfunction getDuration(\n  notif: OverlayNotificationOptions & { persistent?: boolean },\n): number | null {\n  if (notif.duration === null) return null;\n  if (notif.duration !== undefined) return notif.duration;\n  return notif.persistent\n    ? DEFAULT_PERSISTENT_NOTIFICATION_DURATION\n    : DEFAULT_NOTIFICATION_DURATION;\n}\n\nfunction matchesNotificationId(item: InternalNotification, id: Key): boolean {\n  return item.id === id || item.internalId === String(id);\n}\n\nfunction findNotification(\n  list: InternalNotification[],\n  id: Key,\n): InternalNotification | undefined {\n  return list.find((n) => matchesNotificationId(n, id));\n}\n\n// ─── Hook ────────────────────────────────────────────────────────────\n\n/**\n * @param timersRef - Ref to the shared OverlayTimers instance. Accessed only\n *   inside callbacks (never during render), so it is guaranteed to be populated.\n */\nexport function useNotificationState(\n  timersRef: ReturnType<typeof useRef<OverlayTimers>>,\n  persistent: PersistentCallbacks,\n): NotificationState {\n  const [notifications, setNotifications] = useState<InternalNotification[]>(\n    [],\n  );\n  const notificationsRef = useRef(notifications);\n  notificationsRef.current = notifications;\n\n  const idCounter = useRef(0);\n\n  // ─── Evict Helper ──────────────────────────────────────────────\n\n  /**\n   * Evict the oldest active notification to make room for a new one.\n   * Clears its timer and moves it to the persistent list if applicable.\n   * Must be called OUTSIDE setState updaters (StrictMode-safe).\n   */\n  const evictOldest = useEvent((): string | null => {\n    const active = notificationsRef.current.filter((n) => !n.isExiting);\n\n    if (active.length === 0) return null;\n\n    // Oldest by createdAt (active list preserves insertion order)\n    const oldest = active[0];\n\n    timersRef.current?.clearNotificationTimer(oldest.internalId);\n\n    // Eviction counts as a timeout dismissal — move to persistent list if applicable\n    if (oldest.persistent) {\n      persistent.addPersistentItem({\n        id: oldest.id ?? oldest.internalId,\n        theme: oldest.theme,\n        title: oldest.title,\n        description: oldest.description,\n        icon: oldest.icon,\n        actions: oldest.actions,\n        createdAt: oldest.createdAt,\n        updatedAt: oldest.updatedAt,\n        isRead: false,\n        ownerId: oldest.ownerId,\n      });\n    }\n\n    return oldest.internalId;\n  });\n\n  // ─── Remove ─────────────────────────────────────────────────────\n\n  const removeNotification = useEvent(\n    (id: Key, reason: DismissReason = 'api') => {\n      // Read from ref (synchronous) to perform side effects OUTSIDE the updater.\n      // This prevents double-fire in StrictMode and avoids calling setState\n      // (addPersistentItem) inside another setState updater.\n      const notif = findNotification(notificationsRef.current, id);\n\n      if (!notif || notif.isExiting) return;\n\n      timersRef.current?.clearNotificationTimer(notif.internalId);\n\n      if (notif.persistent) {\n        if (reason === 'close' || reason === 'timeout') {\n          // Dismiss button, Escape, or auto-dismiss timeout — move to persistent list.\n          // If the same id is triggered again, it skips the overlay and updates the\n          // persistent list directly.\n          persistent.addPersistentItem({\n            id: notif.id ?? notif.internalId,\n            theme: notif.theme,\n            title: notif.title,\n            description: notif.description,\n            icon: notif.icon,\n            actions: notif.actions,\n            createdAt: notif.createdAt,\n            updatedAt: notif.updatedAt,\n            isRead: true,\n            ownerId: notif.ownerId,\n          });\n        } else if (reason === 'action') {\n          // User clicked a regular action (not dismiss) — fully dismiss the\n          // notification so it never reappears (overlay or persistent list).\n          persistent.removePersistentItem(notif.id ?? notif.internalId);\n        }\n        // reason === 'api' — programmatic cleanup (e.g. component unmount).\n        // No persistence, no full-dismiss tracking.\n      }\n\n      setNotifications((prev) =>\n        prev.map((n) =>\n          matchesNotificationId(n, id) ? { ...n, isExiting: true } : n,\n        ),\n      );\n    },\n  );\n\n  // ─── Finalize ──────────────────────────────────────────────────\n\n  const finalizeNotificationRemoval = useEvent((internalId: string) => {\n    setNotifications((prev) => prev.filter((n) => n.internalId !== internalId));\n  });\n\n  // ─── Add ────────────────────────────────────────────────────────\n\n  const addNotification = useEvent(\n    (options: OverlayNotificationOptions, ownerId?: string): Key => {\n      idCounter.current += 1;\n      const internalId = `notif-${idCounter.current}-${Date.now()}`;\n      const now = Date.now();\n      const id = options.id ?? internalId;\n\n      // If the user explicitly removed this notification from the persistent\n      // list, completely ignore it — no overlay, no persistent storage.\n      if (options.id != null && persistent.isFullyDismissedId(options.id)) {\n        return id;\n      }\n\n      // If this persistent id was previously dismissed to the persistent list,\n      // skip the overlay and update the persistent item directly.\n      if (\n        options.persistent &&\n        options.id != null &&\n        persistent.hasDismissedPersistentId(options.id)\n      ) {\n        persistent.addPersistentItem({\n          id,\n          theme: options.theme,\n          title: options.title,\n          description: options.description,\n          icon: options.icon,\n          actions: options.actions,\n          createdAt: now,\n          updatedAt: now,\n          isRead: false,\n          ownerId,\n        });\n\n        return id;\n      }\n\n      // Check for existing notification with same id via the ref (synchronous read).\n      const existingNotif =\n        options.id != null\n          ? notificationsRef.current.find(\n              (n) => n.id === options.id && !n.isExiting,\n            )\n          : undefined;\n\n      if (existingNotif) {\n        // In-place update of an existing notification\n        const returnId = existingNotif.id ?? existingNotif.internalId;\n\n        const prevTitle = existingNotif.title;\n        const prevDescription = existingNotif.description;\n\n        // Timer reset on string title/description change\n        const titleChanged =\n          typeof options.title === 'string' &&\n          typeof prevTitle === 'string' &&\n          options.title !== prevTitle;\n        const descriptionChanged =\n          typeof options.description === 'string' &&\n          typeof prevDescription === 'string' &&\n          options.description !== prevDescription;\n\n        if (titleChanged || descriptionChanged) {\n          const duration = getDuration(options);\n\n          if (duration != null && duration > 0) {\n            timersRef.current?.startNotificationTimer(\n              existingNotif.internalId,\n              existingNotif.id ?? existingNotif.internalId,\n              duration,\n            );\n          }\n        }\n\n        setNotifications((prev) =>\n          prev.map((n) => {\n            if (n.internalId === existingNotif.internalId) {\n              return {\n                ...n,\n                ...options,\n                internalId: n.internalId,\n                createdAt: n.createdAt,\n                updatedAt: now,\n                ownerId: ownerId ?? n.ownerId,\n              };\n            }\n            return n;\n          }),\n        );\n\n        return returnId;\n      }\n\n      // New notification — always show immediately, evicting the oldest if at cap.\n      // Read from ref (synchronous) to perform side effects OUTSIDE the updater.\n      const activeCount = notificationsRef.current.filter(\n        (n) => !n.isExiting,\n      ).length;\n\n      const newNotification: InternalNotification = {\n        ...options,\n        id,\n        internalId,\n        createdAt: now,\n        updatedAt: now,\n        ownerId,\n      };\n\n      // Evict oldest if at cap (side effects outside updater)\n      let evictedInternalId: string | null = null;\n\n      if (activeCount >= MAX_NOTIFICATIONS) {\n        evictedInternalId = evictOldest();\n      }\n\n      // Start timer for the new notification\n      const duration = getDuration(options);\n\n      if (duration != null && duration > 0) {\n        timersRef.current?.startNotificationTimer(internalId, id, duration);\n      }\n\n      setNotifications((prev) => {\n        let next = prev;\n\n        if (evictedInternalId) {\n          next = next.map((n) =>\n            n.internalId === evictedInternalId ? { ...n, isExiting: true } : n,\n          );\n        }\n\n        return [...next, newNotification];\n      });\n\n      return id;\n    },\n  );\n\n  // ─── Update ─────────────────────────────────────────────────────\n\n  const updateNotification = useEvent(\n    (id: Key, options: Partial<OverlayNotificationOptions>) => {\n      setNotifications((prev) =>\n        prev.map((n) =>\n          matchesNotificationId(n, id)\n            ? { ...n, ...options, updatedAt: Date.now() }\n            : n,\n        ),\n      );\n    },\n  );\n\n  // ─── Owner Cleanup ──────────────────────────────────────────────\n\n  const removeByOwner = useEvent((ownerId: string) => {\n    // Clear timers outside the updater (StrictMode-safe).\n    const owned = notificationsRef.current.filter(\n      (n) => n.ownerId === ownerId && !n.isExiting,\n    );\n\n    for (const n of owned) {\n      timersRef.current?.clearNotificationTimer(n.internalId);\n    }\n\n    setNotifications((prev) =>\n      prev.map((n) => {\n        if (n.ownerId === ownerId && !n.isExiting) {\n          return { ...n, isExiting: true };\n        }\n        return n;\n      }),\n    );\n  });\n\n  return {\n    notifications,\n    notificationsRef,\n    addNotification,\n    removeNotification,\n    updateNotification,\n    finalizeNotificationRemoval,\n    removeByOwner,\n  };\n}\n"],"mappings":"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"}

package/dist/components/overlays/Notifications/use-notifications.d.ts

@@ -0,0 +1,42 @@
+
+import { NotificationsApi } from "./types.js";
+
+//#region src/components/overlays/Notifications/use-notifications.d.ts
+/**
+ * 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',
+ * });
+ * ```
+ */
+declare function useNotifications(): NotificationsApi;
+//#endregion
+export { useNotifications };
+//# sourceMappingURL=use-notifications.d.ts.map

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

@@ -0,0 +1,146 @@
+/** @license MIT | @cube-dev/ui-kit v0.115.0 | Cube Dev Team */
+import { useEvent } from "../../../_internal/hooks/use-event.js";
+import { useWarn } from "../../../_internal/hooks/use-warn.js";
+import { useNotificationContext } from "./NotificationContext.js";
+import { useEffect, useRef } from "react";
+
+//#region src/components/overlays/Notifications/use-notifications.ts
+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',
+* });
+* ```
+*/
+function useNotifications() {
+	const { addNotification, removeNotification, addPersistentItem, removePersistentItem, removeByOwner, removePersistentItemsByOwner } = useNotificationContext();
+	const ownerIdRef = useRef(generateOwnerId());
+	const isMountedRef = useRef(true);
+	const cleanupTimerRef = useRef(null);
+	const lastOptionsRef = useRef(null);
+	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."]
+	});
+	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;
+		addPersistentItem({
+			id,
+			theme: options.theme,
+			title: options.title,
+			description: options.description,
+			icon: options.icon,
+			actions: options.actions ?? void 0,
+			createdAt,
+			updatedAt: createdAt,
+			ownerId: ownerIdRef.current
+		});
+		return {
+			id,
+			dismiss: () => {
+				removePersistentItem(id);
+			}
+		};
+	});
+	const notify = useEvent((options) => {
+		if (!isMountedRef.current) return {
+			id: options.id ?? "",
+			dismiss: () => {}
+		};
+		lastOptionsRef.current = options;
+		if (isStoredMode(options)) return createStoredHandle(options);
+		const notificationId = addNotification({
+			...options,
+			mode: "overlay"
+		}, ownerIdRef.current);
+		return {
+			id: notificationId,
+			dismiss: () => {
+				if (isMountedRef.current) removeNotification(notificationId, "api");
+			}
+		};
+	});
+	const record = useEvent((options) => {
+		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");
+	});
+	useEffect(() => {
+		isMountedRef.current = true;
+		if (cleanupTimerRef.current) {
+			clearTimeout(cleanupTimerRef.current);
+			cleanupTimerRef.current = null;
+		}
+		return () => {
+			isMountedRef.current = false;
+			cleanupTimerRef.current = setTimeout(() => {
+				removeByOwner(ownerIdRef.current);
+				removePersistentItemsByOwner(ownerIdRef.current);
+			}, 0);
+		};
+	}, [removeByOwner, removePersistentItemsByOwner]);
+	return {
+		notify,
+		record,
+		dismiss
+	};
+}
+
+//#endregion
+export { useNotifications };
+//# sourceMappingURL=use-notifications.js.map

package/dist/components/overlays/Notifications/use-notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-notifications.js","names":[],"sources":["../../../../src/components/overlays/Notifications/use-notifications.ts"],"sourcesContent":["import { Key, useEffect, useRef } from 'react';\n\nimport { useEvent } from '../../../_internal';\nimport { useWarn } from '../../../_internal/hooks/use-warn';\n\nimport { useNotificationContext } from './NotificationContext';\n\nimport type {\n  NotificationHandle,\n  NotificationOptions,\n  NotificationsApi,\n  OverlayNotificationOptions,\n  PersistentNotificationItem,\n  StoredNotificationOptions,\n} from './types';\n\nlet ownerIdCounter = 0;\n\nfunction generateOwnerId(): string {\n  ownerIdCounter += 1;\n  return `notif-owner-${ownerIdCounter}-${Date.now()}`;\n}\n\nfunction isStoredMode(\n  options: NotificationOptions,\n): options is StoredNotificationOptions {\n  return options.mode === 'stored';\n}\n\n/**\n * Hook to display and manage notifications.\n *\n * Each hook instance acts as an owner scope:\n * - `notify()` created from this instance attaches ownership metadata.\n * - On unmount, all attached visible overlay notifications are dismissed.\n * - On unmount, all attached persistent records are also removed.\n * - `notify()`/`dismiss()` calls from stale closures after unmount are no-ops.\n *\n * @example\n * ```tsx\n * const { notify, record, dismiss } = useNotifications();\n *\n * notify({\n *   id: 'deploy:123',\n *   theme: 'success',\n *   title: 'Deployment completed',\n *   description: 'Version 1.4.2 is live.',\n *   actions: (\n *     <>\n *       <Notification.Action onPress={() => openLogs()}>View logs</Notification.Action>\n *       <Notification.Action onPress={() => openDeployment()}>Open</Notification.Action>\n *     </>\n *   ),\n * });\n *\n * // Store directly to persistent list (no overlay)\n * record({\n *   id: 'server:alert-1',\n *   theme: 'warning',\n *   title: 'Server alert',\n * });\n * ```\n */\nexport function useNotifications(): NotificationsApi {\n  const {\n    addNotification,\n    removeNotification,\n    addPersistentItem,\n    removePersistentItem,\n    removeByOwner,\n    removePersistentItemsByOwner,\n  } = useNotificationContext();\n\n  const ownerIdRef = useRef<string>(generateOwnerId());\n  const isMountedRef = useRef(true);\n  const cleanupTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n  // Track current options for validation\n  const lastOptionsRef = useRef<NotificationOptions | null>(null);\n\n  // ─── Validation Warnings ──────────────────────────────────────────\n\n  useWarn(\n    lastOptionsRef.current &&\n      'persistent' in lastOptionsRef.current &&\n      lastOptionsRef.current.persistent === true &&\n      lastOptionsRef.current.id == null,\n    {\n      once: false,\n      key: ['Notification', 'persistent-without-id'],\n      args: [\n        'Notification: `persistent: true` requires an explicit `id` for reliable dedupe/upsert.',\n      ],\n    },\n  );\n\n  useWarn(\n    lastOptionsRef.current?.mode === 'stored' &&\n      lastOptionsRef.current.id == null,\n    {\n      once: false,\n      key: ['Notification', 'stored-without-id'],\n      args: [\n        'Notification: `mode: \"stored\"` should have an explicit `id` for reliable upsert.',\n      ],\n    },\n  );\n\n  // ─── Helpers ─────────────────────────────────────────────────────\n\n  const storedIdCounter = useRef(0);\n\n  const createStoredHandle = useEvent(\n    (options: Omit<StoredNotificationOptions, 'mode'>): NotificationHandle => {\n      storedIdCounter.current += 1;\n      const now = Date.now();\n      const id = options.id ?? `stored-${storedIdCounter.current}-${now}`;\n      const createdAt = options.createdAt ?? now;\n\n      const persistentItem: PersistentNotificationItem = {\n        id,\n        theme: options.theme,\n        title: options.title,\n        description: options.description,\n        icon: options.icon,\n        actions: options.actions ?? undefined,\n        createdAt,\n        updatedAt: createdAt,\n        ownerId: ownerIdRef.current,\n      };\n\n      addPersistentItem(persistentItem);\n\n      return {\n        id,\n        dismiss: () => {\n          removePersistentItem(id);\n        },\n      };\n    },\n  );\n\n  // ─── API ──────────────────────────────────────────────────────────\n\n  const notify = useEvent(\n    (options: NotificationOptions): NotificationHandle => {\n      // Stale closure guard\n      if (!isMountedRef.current) {\n        return {\n          id: options.id ?? '',\n          dismiss: () => {},\n        };\n      }\n\n      lastOptionsRef.current = options;\n\n      if (isStoredMode(options)) {\n        return createStoredHandle(options);\n      }\n\n      // Overlay mode\n      const overlayOptions: OverlayNotificationOptions = {\n        ...options,\n        mode: 'overlay',\n      };\n\n      const notificationId = addNotification(\n        overlayOptions,\n        ownerIdRef.current,\n      );\n\n      return {\n        id: notificationId,\n        dismiss: () => {\n          if (isMountedRef.current) {\n            removeNotification(notificationId, 'api');\n          }\n        },\n      };\n    },\n  );\n\n  // `record()` is intentionally kept as a separate method from `notify()` to make\n  // the API more explicit: `record()` always stores directly to the persistent list\n  // (no overlay), while `notify()` defaults to overlay mode. Having both avoids\n  // the caller needing to remember to pass `mode: 'stored'` every time.\n  const record = useEvent(\n    (options: Omit<StoredNotificationOptions, 'mode'>): NotificationHandle => {\n      // Stale closure guard\n      if (!isMountedRef.current) {\n        return {\n          id: options.id ?? '',\n          dismiss: () => {},\n        };\n      }\n\n      lastOptionsRef.current = { ...options, mode: 'stored' };\n\n      return createStoredHandle(options);\n    },\n  );\n\n  const dismiss = useEvent((id: Key) => {\n    if (!isMountedRef.current) return;\n\n    removeNotification(id, 'api');\n  });\n\n  // ─── Ownership Cleanup ────────────────────────────────────────────\n\n  useEffect(() => {\n    isMountedRef.current = true;\n\n    // Cancel any pending cleanup (Strict Mode re-mount)\n    if (cleanupTimerRef.current) {\n      clearTimeout(cleanupTimerRef.current);\n      cleanupTimerRef.current = null;\n    }\n\n    return () => {\n      isMountedRef.current = false;\n\n      // Deferred cleanup — cancelled if owner re-mounts within same tick\n      // (Strict Mode / Suspense safe)\n      cleanupTimerRef.current = setTimeout(() => {\n        removeByOwner(ownerIdRef.current);\n        removePersistentItemsByOwner(ownerIdRef.current);\n      }, 0);\n    };\n  }, [removeByOwner, removePersistentItemsByOwner]);\n\n  return { notify, record, dismiss };\n}\n"],"mappings":";;;;;;;AAgBA,IAAI,iBAAiB;AAErB,SAAS,kBAA0B;AACjC,mBAAkB;AAClB,QAAO,eAAe,eAAe,GAAG,KAAK,KAAK;;AAGpD,SAAS,aACP,SACsC;AACtC,QAAO,QAAQ,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqC1B,SAAgB,mBAAqC;CACnD,MAAM,EACJ,iBACA,oBACA,mBACA,sBACA,eACA,iCACE,wBAAwB;CAE5B,MAAM,aAAa,OAAe,iBAAiB,CAAC;CACpD,MAAM,eAAe,OAAO,KAAK;CACjC,MAAM,kBAAkB,OAA6C,KAAK;CAG1E,MAAM,iBAAiB,OAAmC,KAAK;AAI/D,SACE,eAAe,WACb,gBAAgB,eAAe,WAC/B,eAAe,QAAQ,eAAe,QACtC,eAAe,QAAQ,MAAM,MAC/B;EACE,MAAM;EACN,KAAK,CAAC,gBAAgB,wBAAwB;EAC9C,MAAM,CACJ,yFACD;EACF,CACF;AAED,SACE,eAAe,SAAS,SAAS,YAC/B,eAAe,QAAQ,MAAM,MAC/B;EACE,MAAM;EACN,KAAK,CAAC,gBAAgB,oBAAoB;EAC1C,MAAM,CACJ,qFACD;EACF,CACF;CAID,MAAM,kBAAkB,OAAO,EAAE;CAEjC,MAAM,qBAAqB,UACxB,YAAyE;AACxE,kBAAgB,WAAW;EAC3B,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,KAAK,QAAQ,MAAM,UAAU,gBAAgB,QAAQ,GAAG;EAC9D,MAAM,YAAY,QAAQ,aAAa;AAcvC,oBAZmD;GACjD;GACA,OAAO,QAAQ;GACf,OAAO,QAAQ;GACf,aAAa,QAAQ;GACrB,MAAM,QAAQ;GACd,SAAS,QAAQ,WAAW;GAC5B;GACA,WAAW;GACX,SAAS,WAAW;GACrB,CAEgC;AAEjC,SAAO;GACL;GACA,eAAe;AACb,yBAAqB,GAAG;;GAE3B;GAEJ;CAID,MAAM,SAAS,UACZ,YAAqD;AAEpD,MAAI,CAAC,aAAa,QAChB,QAAO;GACL,IAAI,QAAQ,MAAM;GAClB,eAAe;GAChB;AAGH,iBAAe,UAAU;AAEzB,MAAI,aAAa,QAAQ,CACvB,QAAO,mBAAmB,QAAQ;EASpC,MAAM,iBAAiB,gBAL4B;GACjD,GAAG;GACH,MAAM;GACP,EAIC,WAAW,QACZ;AAED,SAAO;GACL,IAAI;GACJ,eAAe;AACb,QAAI,aAAa,QACf,oBAAmB,gBAAgB,MAAM;;GAG9C;GAEJ;CAMD,MAAM,SAAS,UACZ,YAAyE;AAExE,MAAI,CAAC,aAAa,QAChB,QAAO;GACL,IAAI,QAAQ,MAAM;GAClB,eAAe;GAChB;AAGH,iBAAe,UAAU;GAAE,GAAG;GAAS,MAAM;GAAU;AAEvD,SAAO,mBAAmB,QAAQ;GAErC;CAED,MAAM,UAAU,UAAU,OAAY;AACpC,MAAI,CAAC,aAAa,QAAS;AAE3B,qBAAmB,IAAI,MAAM;GAC7B;AAIF,iBAAgB;AACd,eAAa,UAAU;AAGvB,MAAI,gBAAgB,SAAS;AAC3B,gBAAa,gBAAgB,QAAQ;AACrC,mBAAgB,UAAU;;AAG5B,eAAa;AACX,gBAAa,UAAU;AAIvB,mBAAgB,UAAU,iBAAiB;AACzC,kBAAc,WAAW,QAAQ;AACjC,iCAA6B,WAAW,QAAQ;MAC/C,EAAE;;IAEN,CAAC,eAAe,6BAA6B,CAAC;AAEjD,QAAO;EAAE;EAAQ;EAAQ;EAAS"}

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

@@ -0,0 +1,128 @@
+/** @license MIT | @cube-dev/ui-kit v0.115.0 | Cube Dev Team */
+import { useEvent } from "../../../_internal/hooks/use-event.js";
+import { useEffect, useRef } from "react";
+
+//#region src/components/overlays/Notifications/use-overlay-timers.ts
+/**
+* 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
+	};
+}
+function useOverlayTimers(deps) {
+	const { toastsRef, notificationsRef, removeToast, removeNotification } = deps;
+	const toastTimersMap = useRef(/* @__PURE__ */ new Map()).current;
+	const notificationTimersMap = useRef(/* @__PURE__ */ new Map()).current;
+	const isPausedRef = useRef(false);
+	const pausedMap = useRef(/* @__PURE__ */ new Map()).current;
+	const toastManager = useRef(null);
+	const notifManager = useRef(null);
+	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));
+	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);
+	});
+	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();
+		}
+	});
+	useEffect(() => {
+		return () => {
+			toastManager.current.clearAll();
+			notifManager.current.clearAll();
+			pausedMap.clear();
+		};
+	}, []);
+	return {
+		startToastTimer,
+		clearToastTimer,
+		startNotificationTimer,
+		clearNotificationTimer,
+		handlePauseChange
+	};
+}
+
+//#endregion
+export { useOverlayTimers };
+//# sourceMappingURL=use-overlay-timers.js.map

package/dist/components/overlays/Notifications/use-overlay-timers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-overlay-timers.js","names":[],"sources":["../../../../src/components/overlays/Notifications/use-overlay-timers.ts"],"sourcesContent":["import { Key, useEffect, useRef } from 'react';\n\nimport { useEvent } from '../../../_internal';\n\nimport type { InternalToast } from '../Toast/types';\nimport type { DismissReason, InternalNotification } from './types';\n\n// ─── Types ───────────────────────────────────────────────────────────\n\nexport interface OverlayTimers {\n  /** Start a toast auto-dismiss timer */\n  startToastTimer: (internalId: string, id: Key, duration: number) => void;\n  /** Clear a toast timer */\n  clearToastTimer: (internalId: string) => void;\n  /** Start a notification auto-dismiss timer */\n  startNotificationTimer: (\n    internalId: string,\n    id: Key,\n    duration: number,\n  ) => void;\n  /** Clear a notification timer */\n  clearNotificationTimer: (internalId: string) => void;\n  /** Handle pause/resume of all timers (e.g. on hover/focus) */\n  handlePauseChange: (paused: boolean) => void;\n}\n\nexport interface OverlayTimersDeps {\n  /** Ref to current toasts (for resume lookup) */\n  toastsRef: ReturnType<typeof useRef<InternalToast[]>>;\n  /** Ref to current notifications (for resume lookup) */\n  notificationsRef: ReturnType<typeof useRef<InternalNotification[]>>;\n  /** Remove a toast by id */\n  removeToast: (id: Key) => void;\n  /** Remove a notification by id with reason (also invokes onDismiss callback) */\n  removeNotification: (id: Key, reason: DismissReason) => void;\n}\n\n// ─── Timer Manager Factory ───────────────────────────────────────────\n\ninterface TimerManager {\n  start: (internalId: string, id: Key, duration: number) => void;\n  clear: (internalId: string) => void;\n  pauseAll: () => void;\n  resumeAll: () => void;\n  clearAll: () => void;\n}\n\n/**\n * Creates a start/clear/pause/resume pair for a single timer category.\n * Eliminates duplication between toast and notification timer logic.\n */\nfunction createTimerManager(\n  timersMap: Map<string, ReturnType<typeof setTimeout>>,\n  pausedMap: Map<string, { remaining: number; startedAt: number }>,\n  isPausedRef: ReturnType<typeof useRef<boolean>>,\n  onTimeout: (id: Key) => void,\n  findItem: (\n    internalId: string,\n  ) => { id?: Key; internalId: string; isExiting?: boolean } | undefined,\n): TimerManager {\n  const clear = (internalId: string) => {\n    const timer = timersMap.get(internalId);\n\n    if (timer) {\n      clearTimeout(timer);\n      timersMap.delete(internalId);\n    }\n\n    pausedMap.delete(internalId);\n  };\n\n  const start = (internalId: string, id: Key, duration: number) => {\n    clear(internalId);\n\n    pausedMap.set(internalId, {\n      remaining: duration,\n      startedAt: Date.now(),\n    });\n\n    if (isPausedRef.current) {\n      return;\n    }\n\n    const timer = setTimeout(() => {\n      onTimeout(id);\n    }, duration);\n\n    timersMap.set(internalId, timer);\n  };\n\n  const pauseAll = () => {\n    timersMap.forEach((timer, internalId) => {\n      clearTimeout(timer);\n      timersMap.delete(internalId);\n\n      const info = pausedMap.get(internalId);\n\n      if (info) {\n        const elapsed = Date.now() - info.startedAt;\n        pausedMap.set(internalId, {\n          remaining: Math.max(0, info.remaining - elapsed),\n          startedAt: Date.now(),\n        });\n      }\n    });\n  };\n\n  const resumeAll = () => {\n    pausedMap.forEach((info, internalId) => {\n      const item = findItem(internalId);\n\n      if (info.remaining <= 0) {\n        pausedMap.delete(internalId);\n\n        if (item && !item.isExiting) {\n          onTimeout(item.id ?? item.internalId);\n        }\n\n        return;\n      }\n\n      if (item && !item.isExiting) {\n        const timer = setTimeout(() => {\n          onTimeout(item.id ?? item.internalId);\n        }, info.remaining);\n\n        timersMap.set(internalId, timer);\n        pausedMap.set(internalId, {\n          remaining: info.remaining,\n          startedAt: Date.now(),\n        });\n      }\n    });\n  };\n\n  const clearAll = () => {\n    timersMap.forEach((timer) => clearTimeout(timer));\n    timersMap.clear();\n  };\n\n  return { start, clear, pauseAll, resumeAll, clearAll };\n}\n\n// ─── Hook ────────────────────────────────────────────────────────────\n\nexport function useOverlayTimers(deps: OverlayTimersDeps): OverlayTimers {\n  const { toastsRef, notificationsRef, removeToast, removeNotification } = deps;\n\n  const toastTimersMap = useRef(\n    new Map<string, ReturnType<typeof setTimeout>>(),\n  ).current;\n  const notificationTimersMap = useRef(\n    new Map<string, ReturnType<typeof setTimeout>>(),\n  ).current;\n  const isPausedRef = useRef(false);\n\n  // Shared paused-timers map. Toast and notification internalIds use distinct prefixes\n  // ('toast-' and 'notif-') so they coexist safely in a single map.\n  const pausedMap = useRef(\n    new Map<string, { remaining: number; startedAt: number }>(),\n  ).current;\n\n  const toastManager = useRef<TimerManager | null>(null);\n  const notifManager = useRef<TimerManager | null>(null);\n\n  // Lazily create managers — deps are stable (useEvent / refs), so this runs once.\n  if (!toastManager.current) {\n    toastManager.current = createTimerManager(\n      toastTimersMap,\n      pausedMap,\n      isPausedRef,\n      (id) => removeToast(id),\n      (internalId) =>\n        toastsRef.current?.find((t) => t.internalId === internalId),\n    );\n  }\n\n  if (!notifManager.current) {\n    notifManager.current = createTimerManager(\n      notificationTimersMap,\n      pausedMap,\n      isPausedRef,\n      (id) => removeNotification(id, 'timeout'),\n      (internalId) =>\n        notificationsRef.current?.find((n) => n.internalId === internalId),\n    );\n  }\n\n  // ─── Stable callbacks ──────────────────────────────────────────────\n\n  const startToastTimer = useEvent(\n    (internalId: string, id: Key, duration: number) => {\n      toastManager.current!.start(internalId, id, duration);\n    },\n  );\n\n  const clearToastTimer = useEvent((internalId: string) => {\n    toastManager.current!.clear(internalId);\n  });\n\n  const startNotificationTimer = useEvent(\n    (internalId: string, id: Key, duration: number) => {\n      notifManager.current!.start(internalId, id, duration);\n    },\n  );\n\n  const clearNotificationTimer = useEvent((internalId: string) => {\n    notifManager.current!.clear(internalId);\n  });\n\n  // ─── Pause / Resume ─────────────────────────────────────────────\n\n  const handlePauseChange = useEvent((paused: boolean) => {\n    if (paused === isPausedRef.current) return;\n\n    isPausedRef.current = paused;\n\n    if (paused) {\n      toastManager.current!.pauseAll();\n      notifManager.current!.pauseAll();\n    } else {\n      toastManager.current!.resumeAll();\n      notifManager.current!.resumeAll();\n    }\n  });\n\n  // ─── Cleanup on unmount ─────────────────────────────────────────\n\n  useEffect(() => {\n    return () => {\n      toastManager.current!.clearAll();\n      notifManager.current!.clearAll();\n      pausedMap.clear();\n    };\n  }, []);\n\n  return {\n    startToastTimer,\n    clearToastTimer,\n    startNotificationTimer,\n    clearNotificationTimer,\n    handlePauseChange,\n  };\n}\n"],"mappings":"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"}

package/dist/components/overlays/Notifications/use-persistent-notifications.d.ts

@@ -0,0 +1,54 @@
+
+import { PersistentNotificationItem } from "./types.js";
+import { Key } from "react";
+
+//#region src/components/overlays/Notifications/use-persistent-notifications.d.ts
+/**
+ * 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>
+ * );
+ * ```
+ */
+declare function usePersistentNotifications(): {
+  items: PersistentNotificationItem[];
+  count: number;
+  remove: (id: Key) => void;
+  clear: () => void;
+  markAllAsRead: () => void;
+};
+/**
+ * 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} />;
+ * ```
+ */
+declare function useNotificationsCount(): {
+  total: number;
+  unread: number;
+};
+//#endregion
+export { useNotificationsCount, usePersistentNotifications };
+//# sourceMappingURL=use-persistent-notifications.d.ts.map