@cube-dev/ui-kit 0.114.0 → 0.116.0

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

@@ -0,0 +1,68 @@
+/** @license MIT | @cube-dev/ui-kit v0.116.0 | Cube Dev Team */
+import { NotificationContext, PersistentNotificationsContext, ToastContext, useNotificationContext, useToastContext } from "./NotificationContext.js";
+import { OverlayContainer } from "./OverlayContainer.js";
+import { useNotificationState } from "./use-notification-state.js";
+import { useOverlayTimers } from "./use-overlay-timers.js";
+import { usePersistentState } from "./use-persistent-state.js";
+import { useToastState } from "./use-toast-state.js";
+import { useMemo, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/components/overlays/Notifications/OverlayProvider.tsx
+const DEFAULT_MAX_PERSISTENT = 200;
+function OverlayProvider({ children, maxPersistentNotifications = DEFAULT_MAX_PERSISTENT }) {
+	const timersRef = useRef(null);
+	const persistent = usePersistentState(maxPersistentNotifications);
+	const toast = useToastState(timersRef);
+	const notification = useNotificationState(timersRef, persistent);
+	const timers = useOverlayTimers({
+		toastsRef: toast.toastsRef,
+		notificationsRef: notification.notificationsRef,
+		removeToast: toast.removeToast,
+		removeNotification: notification.removeNotification
+	});
+	timersRef.current = timers;
+	const toastContextValue = useMemo(() => ({
+		addToast: toast.addToast,
+		removeToast: toast.removeToast,
+		updateToast: toast.updateToast,
+		toasts: toast.toasts
+	}), [toast.toasts]);
+	const notificationContextValue = useMemo(() => ({
+		addNotification: notification.addNotification,
+		removeNotification: notification.removeNotification,
+		updateNotification: notification.updateNotification,
+		notifications: notification.notifications,
+		addPersistentItem: persistent.addPersistentItem,
+		removePersistentItem: persistent.removePersistentItem,
+		removePersistentItemsByOwner: persistent.removePersistentItemsByOwner,
+		removeByOwner: notification.removeByOwner
+	}), [notification.notifications]);
+	const persistentContextValue = useMemo(() => ({
+		persistentItems: persistent.persistentItems,
+		removePersistentItem: persistent.removePersistentItem,
+		clearPersistentItems: persistent.clearPersistentItems,
+		markAllAsRead: persistent.markAllAsRead
+	}), [persistent.persistentItems]);
+	return /* @__PURE__ */ jsx(ToastContext.Provider, {
+		value: toastContextValue,
+		children: /* @__PURE__ */ jsx(NotificationContext.Provider, {
+			value: notificationContextValue,
+			children: /* @__PURE__ */ jsxs(PersistentNotificationsContext.Provider, {
+				value: persistentContextValue,
+				children: [children, /* @__PURE__ */ jsx(OverlayContainer, {
+					toasts: toast.toasts,
+					notifications: notification.notifications,
+					onToastExitComplete: toast.finalizeToastRemoval,
+					onNotificationExitComplete: notification.finalizeNotificationRemoval,
+					onNotificationDismiss: notification.removeNotification,
+					onPauseChange: timers.handlePauseChange
+				})]
+			})
+		})
+	});
+}
+
+//#endregion
+export { OverlayProvider };
+//# sourceMappingURL=OverlayProvider.js.map

package/dist/components/overlays/Notifications/OverlayProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OverlayProvider.js","names":[],"sources":["../../../../src/components/overlays/Notifications/OverlayProvider.tsx"],"sourcesContent":["import { useMemo, useRef } from 'react';\n\nimport {\n  NotificationContext,\n  PersistentNotificationsContext,\n  ToastContext,\n} from './NotificationContext';\nimport { OverlayContainer } from './OverlayContainer';\nimport { useNotificationState } from './use-notification-state';\nimport { useOverlayTimers } from './use-overlay-timers';\nimport { usePersistentState } from './use-persistent-state';\nimport { useToastState } from './use-toast-state';\n\nimport type { ToastContextValue } from '../Toast/types';\nimport type {\n  InternalNotificationContextValue,\n  OverlayProviderProps,\n  PersistentNotificationsContextValue,\n} from './types';\nimport type { OverlayTimers } from './use-overlay-timers';\n\n// ─── Re-export context hooks for consumers ───────────────────────────\n\nexport { useToastContext, useNotificationContext } from './NotificationContext';\n\n// ─── Constants ───────────────────────────────────────────────────────\n\nconst DEFAULT_MAX_PERSISTENT = 200;\n\n// ─── OverlayProvider ─────────────────────────────────────────────────\n\nexport function OverlayProvider({\n  children,\n  maxPersistentNotifications = DEFAULT_MAX_PERSISTENT,\n}: OverlayProviderProps) {\n  // Shared ref that breaks the circular dependency between state hooks and timers.\n  // State hooks need timer methods (start/clear), timer hooks need remove methods.\n  // All consumers access the ref only inside useEvent/callbacks (never during\n  // render), so it is guaranteed to be populated before first use.\n  const timersRef = useRef<OverlayTimers>(null!);\n\n  // 1. Persistent state (no dependencies on other hooks)\n  const persistent = usePersistentState(maxPersistentNotifications);\n\n  // 2. Toast state — accesses timers through the shared ref\n  const toast = useToastState(timersRef);\n\n  // 3. Notification state — accesses timers through the shared ref\n  const notification = useNotificationState(timersRef, persistent);\n\n  // 4. Create timers and populate the ref\n  const timers = useOverlayTimers({\n    toastsRef: toast.toastsRef,\n    notificationsRef: notification.notificationsRef,\n    removeToast: toast.removeToast,\n    removeNotification: notification.removeNotification,\n  });\n\n  timersRef.current = timers;\n\n  // ─── Context Values ───────────────────────────────────────────────\n\n  // Only include actually-changing values in deps. All useEvent-based\n  // callbacks are referentially stable and omitted.\n  const toastContextValue = useMemo<ToastContextValue>(\n    () => ({\n      addToast: toast.addToast,\n      removeToast: toast.removeToast,\n      updateToast: toast.updateToast,\n      toasts: toast.toasts,\n    }),\n    [toast.toasts],\n  );\n\n  const notificationContextValue = useMemo<InternalNotificationContextValue>(\n    () => ({\n      addNotification: notification.addNotification,\n      removeNotification: notification.removeNotification,\n      updateNotification: notification.updateNotification,\n      notifications: notification.notifications,\n      addPersistentItem: persistent.addPersistentItem,\n      removePersistentItem: persistent.removePersistentItem,\n      removePersistentItemsByOwner: persistent.removePersistentItemsByOwner,\n      removeByOwner: notification.removeByOwner,\n    }),\n    [notification.notifications],\n  );\n\n  const persistentContextValue = useMemo<PersistentNotificationsContextValue>(\n    () => ({\n      persistentItems: persistent.persistentItems,\n      removePersistentItem: persistent.removePersistentItem,\n      clearPersistentItems: persistent.clearPersistentItems,\n      markAllAsRead: persistent.markAllAsRead,\n    }),\n    [persistent.persistentItems],\n  );\n\n  return (\n    <ToastContext.Provider value={toastContextValue}>\n      <NotificationContext.Provider value={notificationContextValue}>\n        <PersistentNotificationsContext.Provider value={persistentContextValue}>\n          {children}\n          <OverlayContainer\n            toasts={toast.toasts}\n            notifications={notification.notifications}\n            onToastExitComplete={toast.finalizeToastRemoval}\n            onNotificationExitComplete={\n              notification.finalizeNotificationRemoval\n            }\n            onNotificationDismiss={notification.removeNotification}\n            onPauseChange={timers.handlePauseChange}\n          />\n        </PersistentNotificationsContext.Provider>\n      </NotificationContext.Provider>\n    </ToastContext.Provider>\n  );\n}\n"],"mappings":";;;;;;;;;;;AA2BA,MAAM,yBAAyB;AAI/B,SAAgB,gBAAgB,EAC9B,UACA,6BAA6B,0BACN;CAKvB,MAAM,YAAY,OAAsB,KAAM;CAG9C,MAAM,aAAa,mBAAmB,2BAA2B;CAGjE,MAAM,QAAQ,cAAc,UAAU;CAGtC,MAAM,eAAe,qBAAqB,WAAW,WAAW;CAGhE,MAAM,SAAS,iBAAiB;EAC9B,WAAW,MAAM;EACjB,kBAAkB,aAAa;EAC/B,aAAa,MAAM;EACnB,oBAAoB,aAAa;EAClC,CAAC;AAEF,WAAU,UAAU;CAMpB,MAAM,oBAAoB,eACjB;EACL,UAAU,MAAM;EAChB,aAAa,MAAM;EACnB,aAAa,MAAM;EACnB,QAAQ,MAAM;EACf,GACD,CAAC,MAAM,OAAO,CACf;CAED,MAAM,2BAA2B,eACxB;EACL,iBAAiB,aAAa;EAC9B,oBAAoB,aAAa;EACjC,oBAAoB,aAAa;EACjC,eAAe,aAAa;EAC5B,mBAAmB,WAAW;EAC9B,sBAAsB,WAAW;EACjC,8BAA8B,WAAW;EACzC,eAAe,aAAa;EAC7B,GACD,CAAC,aAAa,cAAc,CAC7B;CAED,MAAM,yBAAyB,eACtB;EACL,iBAAiB,WAAW;EAC5B,sBAAsB,WAAW;EACjC,sBAAsB,WAAW;EACjC,eAAe,WAAW;EAC3B,GACD,CAAC,WAAW,gBAAgB,CAC7B;AAED,QACE,oBAAC,aAAa;EAAS,OAAO;YAC5B,oBAAC,oBAAoB;GAAS,OAAO;aACnC,qBAAC,+BAA+B;IAAS,OAAO;eAC7C,UACD,oBAAC;KACC,QAAQ,MAAM;KACd,eAAe,aAAa;KAC5B,qBAAqB,MAAM;KAC3B,4BACE,aAAa;KAEf,uBAAuB,aAAa;KACpC,eAAe,OAAO;MACtB;KACsC;IACb;GACT"}

package/dist/components/overlays/Notifications/PersistentNotificationsList.d.ts

@@ -0,0 +1,30 @@
+
+import { PersistentNotificationsListProps } from "./types.js";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/overlays/Notifications/PersistentNotificationsList.d.ts
+/**
+ * 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" />
+ * ```
+ */
+declare function PersistentNotificationsList({
+  onDismissItem,
+  onAction,
+  emptyState
+}: PersistentNotificationsListProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { PersistentNotificationsList };
+//# sourceMappingURL=PersistentNotificationsList.d.ts.map

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

@@ -0,0 +1,120 @@
+/** @license MIT | @cube-dev/ui-kit v0.116.0 | Cube Dev Team */
+import { tasty } from "../../../tasty/tasty.js";
+import { useEvent } from "../../../_internal/hooks/use-event.js";
+import { _Text } from "../../content/Text.js";
+import { NotificationActionInterceptorContext } from "./NotificationAction.js";
+import { NotificationCard } from "./NotificationCard.js";
+import { Divider } from "../../content/Divider.js";
+import { formatRelativeTime } from "./format-relative-time.js";
+import { usePersistentNotifications } from "./use-persistent-notifications.js";
+import { Fragment, useContext, useEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/components/overlays/Notifications/PersistentNotificationsList.tsx
+const MARK_READ_DELAY = 2e3;
+/** Interval (ms) at which relative timestamps refresh while the list is mounted. */
+const TIMESTAMP_REFRESH_INTERVAL = 1e4;
+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"
+} });
+/**
+* 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" />
+* ```
+*/
+function PersistentNotificationsList({ onDismissItem, onAction, emptyState }) {
+	const { items, remove, markAllAsRead } = usePersistentNotifications();
+	const handleDismiss = useEvent((item) => {
+		remove(item.id);
+		onDismissItem?.(item);
+	});
+	const markReadTimerRef = useRef(null);
+	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]);
+	useEffect(() => {
+		if (!items.some((i) => !i.isRead)) 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 /* @__PURE__ */ jsx(ListContainer, { children: /* @__PURE__ */ jsx(EmptyStateContainer, { children: emptyState ?? "No notifications" }) });
+	return /* @__PURE__ */ jsx(NotificationActionInterceptorContext.Provider, {
+		value: onAction ?? null,
+		children: /* @__PURE__ */ jsx(ListContainer, { children: items.map((item, index) => /* @__PURE__ */ jsxs(Fragment, { children: [index > 0 && /* @__PURE__ */ jsx(Divider, {}), /* @__PURE__ */ jsx(PersistentNotificationListItem, {
+			item,
+			onDismiss: handleDismiss
+		})] }, String(item.id))) })
+	});
+}
+function PersistentNotificationListItem({ item, onDismiss }) {
+	const suffix = /* @__PURE__ */ jsx(_Text, {
+		opacity: .5,
+		preset: "c2",
+		children: formatRelativeTime(item.createdAt)
+	});
+	const handleDismiss = useEvent((_id, _reason) => {
+		onDismiss?.(item);
+	});
+	const parentInterceptor = useContext(NotificationActionInterceptorContext);
+	const handleItemAction = useEvent(() => {
+		parentInterceptor?.();
+	});
+	return /* @__PURE__ */ jsx(NotificationActionInterceptorContext.Provider, {
+		value: handleItemAction,
+		children: /* @__PURE__ */ 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,
+			onDismiss: onDismiss ? handleDismiss : void 0
+		})
+	});
+}
+
+//#endregion
+export { PersistentNotificationsList };
+//# sourceMappingURL=PersistentNotificationsList.js.map

package/dist/components/overlays/Notifications/PersistentNotificationsList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersistentNotificationsList.js","names":["Text"],"sources":["../../../../src/components/overlays/Notifications/PersistentNotificationsList.tsx"],"sourcesContent":["import { Fragment, Key, useContext, useEffect, useRef, useState } from 'react';\n\nimport { useEvent } from '../../../_internal';\nimport { tasty } from '../../../tasty';\nimport { Divider } from '../../content/Divider';\nimport { Text } from '../../content/Text';\n\nimport { formatRelativeTime } from './format-relative-time';\nimport { NotificationActionInterceptorContext } from './NotificationAction';\nimport { NotificationCard } from './NotificationCard';\nimport { usePersistentNotifications } from './use-persistent-notifications';\n\nimport type {\n  DismissReason,\n  PersistentNotificationItem,\n  PersistentNotificationsListProps,\n} from './types';\n\n// ─── Constants ───────────────────────────────────────────────────────\n\nconst MARK_READ_DELAY = 2000;\n/** Interval (ms) at which relative timestamps refresh while the list is mounted. */\nconst TIMESTAMP_REFRESH_INTERVAL = 10_000;\n\n// ─── Styled Components ──────────────────────────────────────────────\n\nconst ListContainer = tasty({\n  qa: 'PersistentNotificationsList',\n  role: 'log',\n  'aria-label': 'Notifications',\n  styles: {\n    display: 'flex',\n    flow: 'column',\n  },\n});\n\nconst EmptyStateContainer = tasty({\n  styles: {\n    display: 'flex',\n    placeItems: 'center',\n    placeContent: 'center',\n    padding: '4x',\n    color: '#dark.5',\n    preset: 't3',\n  },\n});\n\n// ─── PersistentNotificationsList Component ───────────────────────────\n\n/**\n * Standardized rendering for archived/persistent notifications.\n * Always reads items from the notification context.\n * Composable with app-specific shells (popover, dialog, page section).\n *\n * Marks all items as read after being visible for 2 seconds.\n * Relative timestamps refresh every 10 seconds while the list is mounted.\n *\n * Items are always dismissible. Dismissing an item removes it from the\n * persistent list and marks its ID as \"fully dismissed\" — subsequent triggers\n * with the same ID will be completely ignored (no overlay, no re-archival).\n *\n * @example\n * ```tsx\n * <PersistentNotificationsList emptyState=\"No notifications\" />\n * ```\n */\nexport function PersistentNotificationsList({\n  onDismissItem,\n  onAction,\n  emptyState,\n}: PersistentNotificationsListProps) {\n  const { items, remove, markAllAsRead } = usePersistentNotifications();\n\n  // Default dismiss handler removes the item from the persistent list (which\n  // also marks the id as \"fully dismissed\" so it won't reappear).\n  // If a consumer provides `onDismissItem`, it is called *after* the built-in removal.\n  const handleDismiss = useEvent((item: PersistentNotificationItem) => {\n    remove(item.id);\n    onDismissItem?.(item);\n  });\n  const markReadTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n  // Tick counter that increments every TIMESTAMP_REFRESH_INTERVAL to force\n  // re-render so relative timestamps (e.g. \"5 min ago\") stay up to date.\n  const [, setTick] = useState(0);\n\n  useEffect(() => {\n    if (items.length === 0) return;\n\n    const interval = setInterval(() => {\n      setTick((t) => t + 1);\n    }, TIMESTAMP_REFRESH_INTERVAL);\n\n    return () => clearInterval(interval);\n  }, [items.length]);\n\n  // Mark all persistent notifications as read after a 2s delay.\n  // Re-starts the timer whenever items change (e.g. new unread items arrive\n  // while the list is already visible).\n  useEffect(() => {\n    const hasUnread = items.some((i) => !i.isRead);\n\n    if (!hasUnread) return;\n\n    markReadTimerRef.current = setTimeout(() => {\n      markAllAsRead();\n    }, MARK_READ_DELAY);\n\n    return () => {\n      if (markReadTimerRef.current) {\n        clearTimeout(markReadTimerRef.current);\n        markReadTimerRef.current = null;\n      }\n    };\n  }, [markAllAsRead, items]);\n\n  if (items.length === 0) {\n    return (\n      <ListContainer>\n        <EmptyStateContainer>\n          {emptyState ?? 'No notifications'}\n        </EmptyStateContainer>\n      </ListContainer>\n    );\n  }\n\n  return (\n    <NotificationActionInterceptorContext.Provider value={onAction ?? null}>\n      <ListContainer>\n        {items.map((item, index) => (\n          <Fragment key={String(item.id)}>\n            {index > 0 && <Divider />}\n            <PersistentNotificationListItem\n              item={item}\n              onDismiss={handleDismiss}\n            />\n          </Fragment>\n        ))}\n      </ListContainer>\n    </NotificationActionInterceptorContext.Provider>\n  );\n}\n\n// ─── List Item ───────────────────────────────────────────────────────\n\ninterface PersistentNotificationListItemProps {\n  item: PersistentNotificationItem;\n  onDismiss?: (item: PersistentNotificationItem) => void;\n}\n\nfunction PersistentNotificationListItem({\n  item,\n  onDismiss,\n}: PersistentNotificationListItemProps) {\n  const suffix = (\n    <Text opacity={0.5} preset=\"c2\">\n      {formatRelativeTime(item.createdAt)}\n    </Text>\n  );\n\n  // useEvent keeps the callback stable across re-renders regardless of\n  // item reference changes (avoids unnecessary NotificationCard re-renders).\n  const handleDismiss = useEvent((_id: Key, _reason: DismissReason) => {\n    onDismiss?.(item);\n  });\n\n  const parentInterceptor = useContext(NotificationActionInterceptorContext);\n\n  // Chains with the list-level interceptor (e.g. closing the parent popover).\n  // Dismissal itself is handled by NotificationAction via the dismiss context\n  // to avoid double-firing onDismiss.\n  const handleItemAction = useEvent(() => {\n    parentInterceptor?.();\n  });\n\n  return (\n    <NotificationActionInterceptorContext.Provider value={handleItemAction}>\n      <NotificationCard\n        qa=\"PersistentNotificationItem\"\n        theme={item.theme}\n        title={item.title}\n        description={item.description}\n        icon={item.icon}\n        actions={item.actions}\n        isDismissible={!!onDismiss}\n        elevated={false}\n        notificationId={item.id}\n        suffix={suffix}\n        onDismiss={onDismiss ? handleDismiss : undefined}\n      />\n    </NotificationActionInterceptorContext.Provider>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;AAoBA,MAAM,kBAAkB;;AAExB,MAAM,6BAA6B;AAInC,MAAM,gBAAgB,MAAM;CAC1B,IAAI;CACJ,MAAM;CACN,cAAc;CACd,QAAQ;EACN,SAAS;EACT,MAAM;EACP;CACF,CAAC;AAEF,MAAM,sBAAsB,MAAM,EAChC,QAAQ;CACN,SAAS;CACT,YAAY;CACZ,cAAc;CACd,SAAS;CACT,OAAO;CACP,QAAQ;CACT,EACF,CAAC;;;;;;;;;;;;;;;;;;AAqBF,SAAgB,4BAA4B,EAC1C,eACA,UACA,cACmC;CACnC,MAAM,EAAE,OAAO,QAAQ,kBAAkB,4BAA4B;CAKrE,MAAM,gBAAgB,UAAU,SAAqC;AACnE,SAAO,KAAK,GAAG;AACf,kBAAgB,KAAK;GACrB;CACF,MAAM,mBAAmB,OAA6C,KAAK;CAI3E,MAAM,GAAG,WAAW,SAAS,EAAE;AAE/B,iBAAgB;AACd,MAAI,MAAM,WAAW,EAAG;EAExB,MAAM,WAAW,kBAAkB;AACjC,YAAS,MAAM,IAAI,EAAE;KACpB,2BAA2B;AAE9B,eAAa,cAAc,SAAS;IACnC,CAAC,MAAM,OAAO,CAAC;AAKlB,iBAAgB;AAGd,MAAI,CAFc,MAAM,MAAM,MAAM,CAAC,EAAE,OAAO,CAE9B;AAEhB,mBAAiB,UAAU,iBAAiB;AAC1C,kBAAe;KACd,gBAAgB;AAEnB,eAAa;AACX,OAAI,iBAAiB,SAAS;AAC5B,iBAAa,iBAAiB,QAAQ;AACtC,qBAAiB,UAAU;;;IAG9B,CAAC,eAAe,MAAM,CAAC;AAE1B,KAAI,MAAM,WAAW,EACnB,QACE,oBAAC,2BACC,oBAAC,iCACE,cAAc,qBACK,GACR;AAIpB,QACE,oBAAC,qCAAqC;EAAS,OAAO,YAAY;YAChE,oBAAC,2BACE,MAAM,KAAK,MAAM,UAChB,qBAAC,uBACE,QAAQ,KAAK,oBAAC,YAAU,EACzB,oBAAC;GACO;GACN,WAAW;IACX,KALW,OAAO,KAAK,GAAG,CAMnB,CACX,GACY;GAC8B;;AAWpD,SAAS,+BAA+B,EACtC,MACA,aACsC;CACtC,MAAM,SACJ,oBAACA;EAAK,SAAS;EAAK,QAAO;YACxB,mBAAmB,KAAK,UAAU;GAC9B;CAKT,MAAM,gBAAgB,UAAU,KAAU,YAA2B;AACnE,cAAY,KAAK;GACjB;CAEF,MAAM,oBAAoB,WAAW,qCAAqC;CAK1E,MAAM,mBAAmB,eAAe;AACtC,uBAAqB;GACrB;AAEF,QACE,oBAAC,qCAAqC;EAAS,OAAO;YACpD,oBAAC;GACC,IAAG;GACH,OAAO,KAAK;GACZ,OAAO,KAAK;GACZ,aAAa,KAAK;GAClB,MAAM,KAAK;GACX,SAAS,KAAK;GACd,eAAe,CAAC,CAAC;GACjB,UAAU;GACV,gBAAgB,KAAK;GACb;GACR,WAAW,YAAY,gBAAgB;IACvC;GAC4C"}

package/dist/components/overlays/Notifications/format-relative-time.d.ts

@@ -0,0 +1,19 @@
+
+//#region src/components/overlays/Notifications/format-relative-time.d.ts
+/**
+ * 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)
+ */
+declare function formatRelativeTime(timestamp: number): string;
+//#endregion
+export { formatRelativeTime };
+//# sourceMappingURL=format-relative-time.d.ts.map

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

@@ -0,0 +1,36 @@
+/** @license MIT | @cube-dev/ui-kit v0.116.0 | Cube Dev Team */
+//#region src/components/overlays/Notifications/format-relative-time.ts
+/**
+* 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)
+*/
+function formatRelativeTime(timestamp) {
+	const diffMs = Date.now() - timestamp;
+	if (diffMs < 0) return "just now";
+	const diffSeconds = Math.floor(diffMs / 1e3);
+	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`;
+	return `${Math.floor(diffDays / 365)} y ago`;
+}
+
+//#endregion
+export { formatRelativeTime };
+//# sourceMappingURL=format-relative-time.js.map

package/dist/components/overlays/Notifications/format-relative-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-relative-time.js","names":[],"sources":["../../../../src/components/overlays/Notifications/format-relative-time.ts"],"sourcesContent":["/**\n * Lightweight relative time formatter.\n * No external dependencies.\n *\n * Output format:\n * - `just now` (< 1 minute)\n * - `N min ago` (1–59 minutes)\n * - `N h ago` (1–23 hours)\n * - `N d ago` (1–6 days)\n * - `N w ago` (1–4 weeks)\n * - `N mo ago` (1–11 months)\n * - `N y ago` (1+ years)\n */\nexport function formatRelativeTime(timestamp: number): string {\n  const now = Date.now();\n  const diffMs = now - timestamp;\n\n  if (diffMs < 0) {\n    return 'just now';\n  }\n\n  const diffSeconds = Math.floor(diffMs / 1000);\n  const diffMinutes = Math.floor(diffSeconds / 60);\n  const diffHours = Math.floor(diffMinutes / 60);\n  const diffDays = Math.floor(diffHours / 24);\n\n  if (diffMinutes < 1) {\n    return 'just now';\n  }\n\n  if (diffHours < 1) {\n    return `${diffMinutes} min ago`;\n  }\n\n  if (diffDays < 1) {\n    return `${diffHours} h ago`;\n  }\n\n  if (diffDays < 7) {\n    return `${diffDays} d ago`;\n  }\n\n  const diffWeeks = Math.floor(diffDays / 7);\n\n  if (diffDays < 30) {\n    return `${diffWeeks} w ago`;\n  }\n\n  const diffMonths = Math.floor(diffDays / 30);\n\n  if (diffDays < 365) {\n    return `${diffMonths} mo ago`;\n  }\n\n  const diffYears = Math.floor(diffDays / 365);\n\n  return `${diffYears} y ago`;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAaA,SAAgB,mBAAmB,WAA2B;CAE5D,MAAM,SADM,KAAK,KAAK,GACD;AAErB,KAAI,SAAS,EACX,QAAO;CAGT,MAAM,cAAc,KAAK,MAAM,SAAS,IAAK;CAC7C,MAAM,cAAc,KAAK,MAAM,cAAc,GAAG;CAChD,MAAM,YAAY,KAAK,MAAM,cAAc,GAAG;CAC9C,MAAM,WAAW,KAAK,MAAM,YAAY,GAAG;AAE3C,KAAI,cAAc,EAChB,QAAO;AAGT,KAAI,YAAY,EACd,QAAO,GAAG,YAAY;AAGxB,KAAI,WAAW,EACb,QAAO,GAAG,UAAU;AAGtB,KAAI,WAAW,EACb,QAAO,GAAG,SAAS;CAGrB,MAAM,YAAY,KAAK,MAAM,WAAW,EAAE;AAE1C,KAAI,WAAW,GACb,QAAO,GAAG,UAAU;CAGtB,MAAM,aAAa,KAAK,MAAM,WAAW,GAAG;AAE5C,KAAI,WAAW,IACb,QAAO,GAAG,WAAW;AAKvB,QAAO,GAFW,KAAK,MAAM,WAAW,IAAI,CAExB"}

package/dist/components/overlays/Notifications/index.d.ts

@@ -0,0 +1,43 @@
+
+import { DismissReason, NotificationActionProps, NotificationBaseOptions, NotificationHandle, NotificationOptions, NotificationProps, NotificationType, NotificationsApi, OverlayNotificationOptions, OverlayProviderProps, PersistentNotificationItem, PersistentNotificationsListProps, StoredNotificationOptions } from "./types.js";
+import { useToastContext } from "./NotificationContext.js";
+import { Notification as Notification$1 } from "./Notification.js";
+import { NotificationAction } from "./NotificationAction.js";
+import { NotificationCard, NotificationCardProps } from "./NotificationCard.js";
+import { NotificationItem, NotificationItemProps } from "./NotificationItem.js";
+import { PersistentNotificationsList } from "./PersistentNotificationsList.js";
+import { OverlayProvider } from "./OverlayProvider.js";
+import { useNotifications } from "./use-notifications.js";
+import { useNotificationsCount, usePersistentNotifications } from "./use-persistent-notifications.js";
+import { formatRelativeTime } from "./format-relative-time.js";
+
+//#region src/components/overlays/Notifications/index.d.ts
+/**
+ * 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>
+ *     </>
+ *   }
+ * />
+ * ```
+ */
+declare const Notification: typeof Notification$1 & {
+  Action: typeof NotificationAction;
+};
+type NotificationComponent = typeof Notification;
+//#endregion
+export { Notification, NotificationComponent };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,40 @@
+/** @license MIT | @cube-dev/ui-kit v0.116.0 | Cube Dev Team */
+import { useToastContext } from "./NotificationContext.js";
+import { NotificationAction } from "./NotificationAction.js";
+import { NotificationCard } from "./NotificationCard.js";
+import { NotificationItem } from "./NotificationItem.js";
+import { OverlayProvider } from "./OverlayProvider.js";
+import { Notification as Notification$1 } from "./Notification.js";
+import { formatRelativeTime } from "./format-relative-time.js";
+import { useNotificationsCount, usePersistentNotifications } from "./use-persistent-notifications.js";
+import { PersistentNotificationsList } from "./PersistentNotificationsList.js";
+import { useNotifications } from "./use-notifications.js";
+
+//#region src/components/overlays/Notifications/index.ts
+/**
+* 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>
+*     </>
+*   }
+* />
+* ```
+*/
+const Notification = Object.assign(Notification$1, { Action: NotificationAction });
+
+//#endregion
+export { Notification };
+//# sourceMappingURL=index.js.map

package/dist/components/overlays/Notifications/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["NotificationBase"],"sources":["../../../../src/components/overlays/Notifications/index.ts"],"sourcesContent":["// ─── Components ──────────────────────────────────────────────────────\n\nimport { Notification as NotificationBase } from './Notification';\nimport { NotificationAction } from './NotificationAction';\n\nexport { NotificationAction } from './NotificationAction';\nexport { NotificationCard } from './NotificationCard';\nexport type { NotificationCardProps } from './NotificationCard';\nexport { NotificationItem } from './NotificationItem';\nexport type { NotificationItemProps } from './NotificationItem';\nexport { PersistentNotificationsList } from './PersistentNotificationsList';\n\n// ─── Provider ────────────────────────────────────────────────────────\n\nexport { OverlayProvider } from './OverlayProvider';\n\n// useToastContext is re-exported for Toast module backward compatibility\nexport { useToastContext } from './NotificationContext';\n\n// ─── Hooks ───────────────────────────────────────────────────────────\n\nexport { useNotifications } from './use-notifications';\nexport {\n  usePersistentNotifications,\n  useNotificationsCount,\n} from './use-persistent-notifications';\n\n// ─── Utilities ───────────────────────────────────────────────────────\n\nexport { formatRelativeTime } from './format-relative-time';\n\n// ─── Types ───────────────────────────────────────────────────────────\n\nexport type {\n  NotificationType,\n  DismissReason,\n  NotificationBaseOptions,\n  OverlayNotificationOptions,\n  StoredNotificationOptions,\n  NotificationOptions,\n  NotificationActionProps,\n  NotificationHandle,\n  NotificationsApi,\n  PersistentNotificationItem,\n  PersistentNotificationsListProps,\n  OverlayProviderProps,\n  NotificationProps,\n} from './types';\n\n// ─── Compound Notification Component ─────────────────────────────────\n\n/**\n * Declarative Notification component with compound API.\n *\n * @example\n * ```tsx\n * // Declarative usage\n * <Notification\n *   id=\"release:new-version\"\n *   theme=\"warning\"\n *   title=\"New release available\"\n *   description=\"2.0.0 can be installed now.\"\n *   actions={\n *     <>\n *       <Notification.Action>Later</Notification.Action>\n *       <Notification.Action onPress={() => openUpgradeDialog()}>\n *         Upgrade\n *       </Notification.Action>\n *     </>\n *   }\n * />\n * ```\n */\nexport const Notification = Object.assign(NotificationBase, {\n  Action: NotificationAction,\n});\n\nexport type NotificationComponent = typeof Notification;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyEA,MAAa,eAAe,OAAO,OAAOA,gBAAkB,EAC1D,QAAQ,oBACT,CAAC"}

package/dist/components/overlays/Notifications/types.d.ts

@@ -0,0 +1,135 @@
+
+import { Key, ReactNode } from "react";
+
+//#region src/components/overlays/Notifications/types.d.ts
+type NotificationType = 'default' | 'success' | 'danger' | 'warning' | 'note';
+interface NotificationBaseOptions {
+  id?: Key;
+  theme?: NotificationType;
+  title?: ReactNode;
+  description?: ReactNode;
+  icon?: ReactNode;
+}
+interface OverlayNotificationOptions extends NotificationBaseOptions {
+  mode?: 'overlay';
+  /**
+   * Action buttons rendered below the notification description.
+   * A default "Dismiss" button is auto-appended unless any action has
+   * `isDismiss` set (detected automatically via context).
+   * When omitted, only the default "Dismiss" button is shown (if `isDismissible`).
+   */
+  actions?: ReactNode;
+  /**
+   * Whether the notification shows the default dismiss UI:
+   * - Auto-appended "Dismiss" button (suppressed when false)
+   * - Escape key dismissal (disabled when false)
+   *
+   * Actions with `closeOnPress` (default `true`) can still close the
+   * notification regardless of this setting.
+   *
+   * Default: true
+   */
+  isDismissible?: boolean;
+  /**
+   * Duration in ms before auto-dismiss.
+   * Default: 3000ms (non-persistent) or 5000ms (persistent).
+   * null = no auto-dismiss.
+   */
+  duration?: number | null;
+  /**
+   * Whether to retain in persistent list when dismissed.
+   * All user-visible dismissals (timeout, action, close) move the notification
+   * to the persistent list. Only programmatic cleanup (`'api'`, e.g. component
+   * unmount) skips persistence.
+   *
+   * Once archived, subsequent calls with the same `id` skip the overlay and
+   * update the persistent list directly.
+   *
+   * Default: false
+   */
+  persistent?: boolean;
+}
+interface StoredNotificationOptions extends NotificationBaseOptions {
+  mode: 'stored';
+  /** Action buttons (same ReactNode format as overlay notifications) */
+  actions?: ReactNode;
+  /**
+   * Timestamp (epoch ms) for when the notification was originally created.
+   * Use this when restoring server-sourced notifications to preserve the original time.
+   * Defaults to `Date.now()` if omitted.
+   */
+  createdAt?: number;
+}
+type NotificationOptions = OverlayNotificationOptions | StoredNotificationOptions;
+type DismissReason = 'close' | 'timeout' | 'action' | 'api';
+interface NotificationActionProps {
+  /** Action label */
+  children?: ReactNode;
+  /**
+   * Called when the action is pressed.
+   * Return `false` to prevent the auto-dismiss that would normally follow.
+   * Useful for async flows where the user may cancel (e.g. confirmation dialogs).
+   */
+  onPress?: () => void | false | Promise<void | false>;
+  /** Whether to auto-dismiss the notification after onPress. Default: true */
+  closeOnPress?: boolean;
+  /** Whether the action is disabled */
+  isDisabled?: boolean;
+  /**
+   * Marks this action as the notification's dismiss button.
+   * Detected automatically via context — when any action in the notification
+   * has `isDismiss` set, the auto-appended default "Dismiss" button is suppressed.
+   */
+  isDismiss?: boolean;
+}
+interface NotificationHandle {
+  id: Key;
+  dismiss: () => void;
+}
+interface NotificationsApi {
+  notify: (options: NotificationOptions) => NotificationHandle;
+  /**
+   * Shorthand for `notify({ mode: 'stored', ... })`.
+   * Stores a notification directly to the persistent list without showing an overlay.
+   * Kept as a separate method to make the "stored-only" intent explicit at call sites.
+   */
+  record: (options: Omit<StoredNotificationOptions, 'mode'>) => NotificationHandle;
+  dismiss: (id: Key) => void;
+}
+interface InternalNotification extends OverlayNotificationOptions {
+  internalId: string;
+  createdAt: number;
+  updatedAt: number;
+  isExiting?: boolean;
+  ownerId?: string;
+}
+interface PersistentNotificationItem {
+  id: Key;
+  theme?: NotificationType;
+  title?: ReactNode;
+  description?: ReactNode;
+  icon?: ReactNode;
+  /** Action buttons (ReactNode) */
+  actions?: ReactNode;
+  createdAt: number;
+  updatedAt: number;
+  /** Whether the notification has been seen in the persistent list */
+  isRead?: boolean;
+  /** Owner ID for cleanup on hook/component unmount */
+  ownerId?: string;
+}
+interface PersistentNotificationsListProps {
+  onDismissItem?: (item: PersistentNotificationItem) => void;
+  /** Called before any action's onPress handler fires. Useful for closing a parent popover. */
+  onAction?: () => void;
+  emptyState?: ReactNode;
+}
+interface OverlayProviderProps {
+  children: ReactNode;
+  /** Maximum number of persistent notifications to keep. Default: 200 */
+  maxPersistentNotifications?: number;
+}
+interface NotificationProps extends OverlayNotificationOptions {}
+//#endregion
+export { DismissReason, InternalNotification, NotificationActionProps, NotificationBaseOptions, NotificationHandle, NotificationOptions, NotificationProps, NotificationType, NotificationsApi, OverlayNotificationOptions, OverlayProviderProps, PersistentNotificationItem, PersistentNotificationsListProps, StoredNotificationOptions };
+//# sourceMappingURL=types.d.ts.map