stream-chat-react-native-core 9.2.0-beta.1 → 9.2.0-beta.3

package/src/components/Notifications/hooks/__tests__/useNotificationApi.test.tsx

@@ -0,0 +1,172 @@
+import React, { PropsWithChildren } from 'react';
+
+import { act, renderHook } from '@testing-library/react-native';
+
+import { ChannelProvider } from '../../../../contexts/channelContext/ChannelContext';
+import { ChatProvider } from '../../../../contexts/chatContext/ChatContext';
+import { NotificationTargetProvider } from '../../NotificationTargetContext';
+import { useNotificationApi } from '../useNotificationApi';
+
+const createWrapper =
+  (client: unknown, channelContext: Record<string, unknown> = {}) =>
+  ({ children }: PropsWithChildren) => (
+    <ChatProvider value={{ client } as never}>
+      <ChannelProvider
+        value={
+          {
+            channel: { cid: 'messaging:general' },
+            ...channelContext,
+          } as never
+        }
+      >
+        <NotificationTargetProvider hostId='channel:messaging:general' panel='channel'>
+          {children}
+        </NotificationTargetProvider>
+      </ChannelProvider>
+    </ChatProvider>
+  );
+
+describe('useNotificationApi', () => {
+  it('adds inferred exact target tags and incident-derived types', () => {
+    const add = jest.fn(() => 'notification-id');
+    const client = {
+      notifications: {
+        add,
+        remove: jest.fn(),
+        startTimeout: jest.fn(),
+      },
+    };
+    const { result } = renderHook(() => useNotificationApi(), {
+      wrapper: createWrapper(client),
+    });
+
+    act(() => {
+      result.current.addNotification(
+        {
+          message: 'Could not send message',
+          options: { severity: 'error' },
+          origin: { emitter: 'MessageComposer' },
+        },
+        { incident: { domain: 'api', entity: 'message', operation: 'send' } },
+      );
+    });
+
+    expect(add).toHaveBeenCalledWith({
+      message: 'Could not send message',
+      options: {
+        severity: 'error',
+        tags: ['target:channel:channel:messaging:general'],
+        type: 'api:message:send:failed',
+      },
+      origin: { emitter: 'MessageComposer' },
+    });
+  });
+
+  it('uses explicit target panels instead of inferred panel', () => {
+    const add = jest.fn();
+    const client = {
+      notifications: {
+        add,
+        remove: jest.fn(),
+        startTimeout: jest.fn(),
+      },
+    };
+    const { result } = renderHook(() => useNotificationApi(), {
+      wrapper: createWrapper(client),
+    });
+
+    act(() => {
+      result.current.addNotification(
+        {
+          message: 'Poll ended',
+          options: { severity: 'success' },
+          origin: { emitter: 'Poll' },
+        },
+        { targetPanels: ['channel', 'thread'] },
+      );
+    });
+
+    expect(add).toHaveBeenCalledWith({
+      message: 'Poll ended',
+      options: {
+        severity: 'success',
+        tags: ['target:channel', 'target:thread'],
+      },
+      origin: { emitter: 'Poll' },
+    });
+  });
+
+  it('adds system notifications with the system tag', () => {
+    const add = jest.fn(() => 'notification-id');
+    const client = {
+      notifications: {
+        add,
+        remove: jest.fn(),
+        startTimeout: jest.fn(),
+      },
+    };
+    const { result } = renderHook(() => useNotificationApi(), {
+      wrapper: createWrapper(client, { threadList: true }),
+    });
+
+    const id = result.current.addSystemNotification({
+      message: 'Reconnecting',
+      options: {
+        severity: 'warning',
+        tags: ['network'],
+      },
+      origin: { emitter: 'Connection' },
+    });
+
+    expect(id).toBe('notification-id');
+    expect(add).toHaveBeenCalledWith({
+      message: 'Reconnecting',
+      options: {
+        severity: 'warning',
+        tags: ['system', 'network'],
+      },
+      origin: { emitter: 'Connection' },
+    });
+  });
+
+  it('removes non-system notifications for a panel', () => {
+    const remove = jest.fn();
+    const client = {
+      notifications: {
+        add: jest.fn(),
+        notifications: [
+          {
+            id: 'channel-id',
+            origin: { emitter: 'test' },
+            tags: ['target:channel'],
+          },
+          {
+            id: 'fallback-channel-id',
+            origin: { emitter: 'test' },
+          },
+          {
+            id: 'thread-id',
+            origin: { emitter: 'test' },
+            tags: ['target:thread'],
+          },
+          {
+            id: 'system-id',
+            origin: { emitter: 'test' },
+            tags: ['system', 'target:channel'],
+          },
+        ],
+        remove,
+        startTimeout: jest.fn(),
+      },
+    };
+    const { result } = renderHook(() => useNotificationApi(), {
+      wrapper: createWrapper(client),
+    });
+
+    act(() => {
+      result.current.removeNotificationsForCurrentPanel();
+    });
+
+    expect(remove.mock.calls.map(([id]) => id)).toEqual(['channel-id']);
+  });
+});

package/src/components/Notifications/hooks/__tests__/useNotificationTarget.test.tsx

@@ -0,0 +1,85 @@
+import React, { PropsWithChildren } from 'react';
+
+import { renderHook } from '@testing-library/react-native';
+
+import { ChannelProvider } from '../../../../contexts/channelContext/ChannelContext';
+import { ChannelsProvider } from '../../../../contexts/channelsContext/ChannelsContext';
+import { ThreadProvider } from '../../../../contexts/threadContext/ThreadContext';
+import { ThreadsProvider } from '../../../../contexts/threadsContext/ThreadsContext';
+import { useNotificationTarget } from '../useNotificationTarget';
+
+const channelContext = { channel: { cid: 'messaging:channel' } } as never;
+const channelsContext = { channels: [] } as never;
+const threadsContext = { threads: [] } as never;
+
+describe('useNotificationTarget', () => {
+  it('returns undefined outside notification target providers', () => {
+    const { result } = renderHook(() => useNotificationTarget());
+
+    expect(result.current).toBeUndefined();
+  });
+
+  it('targets the channel when rendered inside Channel', () => {
+    const wrapper = ({ children }: PropsWithChildren) => (
+      <ChannelProvider value={channelContext}>{children}</ChannelProvider>
+    );
+
+    const { result } = renderHook(() => useNotificationTarget(), { wrapper });
+
+    expect(result.current).toBe('channel');
+  });
+
+  it('prioritizes channel over surrounding list providers', () => {
+    const wrapper = ({ children }: PropsWithChildren) => (
+      <ChannelsProvider value={channelsContext}>
+        <ThreadsProvider value={threadsContext}>
+          <ChannelProvider value={channelContext}>{children}</ChannelProvider>
+        </ThreadsProvider>
+      </ChannelsProvider>
+    );
+
+    const { result } = renderHook(() => useNotificationTarget(), { wrapper });
+
+    expect(result.current).toBe('channel');
+  });
+
+  it('targets thread when Channel is in thread-list mode', () => {
+    const wrapper = ({ children }: PropsWithChildren) => (
+      <ChannelProvider value={{ ...(channelContext as object), threadList: true } as never}>
+        {children}
+      </ChannelProvider>
+    );
+
+    const { result } = renderHook(() => useNotificationTarget(), { wrapper });
+
+    expect(result.current).toBe('thread');
+  });
+
+  it('prioritizes thread over channel', () => {
+    const wrapper = ({ children }: PropsWithChildren) => (
+      <ChannelProvider value={channelContext}>
+        <ThreadProvider value={{ threadInstance: {} } as never}>{children}</ThreadProvider>
+      </ChannelProvider>
+    );
+
+    const { result } = renderHook(() => useNotificationTarget(), { wrapper });
+
+    expect(result.current).toBe('thread');
+  });
+
+  it('targets list providers when no Channel provider is present', () => {
+    const channelListWrapper = ({ children }: PropsWithChildren) => (
+      <ChannelsProvider value={channelsContext}>{children}</ChannelsProvider>
+    );
+    const threadListWrapper = ({ children }: PropsWithChildren) => (
+      <ThreadsProvider value={threadsContext}>{children}</ThreadsProvider>
+    );
+
+    expect(
+      renderHook(() => useNotificationTarget(), { wrapper: channelListWrapper }).result.current,
+    ).toBe('channel-list');
+    expect(
+      renderHook(() => useNotificationTarget(), { wrapper: threadListWrapper }).result.current,
+    ).toBe('thread-list');
+  });
+});

package/src/components/Notifications/hooks/index.ts

@@ -0,0 +1,5 @@
+export * from './useNotificationApi';
+export * from './useNotificationListController';
+export * from './useNotifications';
+export * from './useNotificationTarget';
+export * from './useSystemNotifications';

package/src/components/Notifications/hooks/useNotificationApi.ts

@@ -0,0 +1,248 @@
+import { useCallback } from 'react';
+
+import type { AddNotificationPayload, Notification } from 'stream-chat';
+
+import { useChatContext } from '../../../contexts/chatContext/ChatContext';
+import {
+  addExactNotificationTargetTag,
+  getNotificationTargetTag,
+  hasNotificationTargetTag,
+  isNotificationForTarget,
+  registerNotificationActionTarget,
+  type NotificationTarget,
+  type NotificationTargetPanel,
+} from '../notificationTarget';
+import { useNotificationTargetContext } from '../NotificationTargetContext';
+
+export const SYSTEM_NOTIFICATION_TAG = 'system' as const;
+
+/** Returns whether a notification is reserved for system-level consumers instead of snackbars. */
+export const hasSystemNotificationTag = (notification: Notification) =>
+  notification.tags?.includes(SYSTEM_NOTIFICATION_TAG) ?? false;
+
+/** Structured descriptor used to derive stable notification `type` values. */
+export type NotificationIncidentDescriptor = {
+  /** Product or SDK area where the notification originated, for example `message` or `poll`. */
+  domain: string;
+  /** Entity affected by the incident, for example `attachment` or `vote`. */
+  entity: string;
+  /** Operation being reported, for example `upload` or `create`. */
+  operation: string;
+  /** Optional explicit status. Falls back to severity-derived status when omitted. */
+  status?: string;
+};
+
+export type AddNotificationOptions = {
+  /** Incident metadata used to derive `options.type` when the payload does not provide one. */
+  incident?: NotificationIncidentDescriptor;
+  /** Exact host target for this notification. Defaults to the nearest notification target provider. */
+  target?: NotificationTarget;
+  /** Broad panel targets. Use for notifications that should appear in every host of a panel. */
+  targetPanels?: NotificationTargetPanel[];
+};
+
+export type AddSystemNotificationOptions = Omit<AddNotificationOptions, 'target' | 'targetPanels'>;
+
+/** Adds a snackbar notification scoped to a target host or panel. */
+export type AddNotification = (
+  payload: AddNotificationPayload,
+  options?: AddNotificationOptions,
+) => void;
+/** Adds a system notification that is excluded from the default snackbar list. */
+export type AddSystemNotification = (
+  payload: AddNotificationPayload,
+  options?: AddSystemNotificationOptions,
+) => string;
+/** Removes a notification by id. */
+export type RemoveNotification = (id: string) => void;
+/** Removes non-system notifications that belong to the current target provider. */
+export type RemoveNotificationsForCurrentPanel = () => void;
+/** Starts the manager timeout for a notification, optionally overriding the stored duration. */
+export type StartNotificationTimeout = (id: string, durationOverride?: number) => void;
+/** Runs an action while temporarily making its target available to untagged notifications. */
+export type RunWithNotificationTarget = <T>(
+  callback: () => T | Promise<T>,
+  target?: NotificationTarget,
+) => Promise<T>;
+
+export type NotificationApi = {
+  addNotification: AddNotification;
+  addSystemNotification: AddSystemNotification;
+  removeNotification: RemoveNotification;
+  removeNotificationsForCurrentPanel: RemoveNotificationsForCurrentPanel;
+  runWithNotificationTarget: RunWithNotificationTarget;
+  startNotificationTimeout: StartNotificationTimeout;
+};
+
+const getTargetTags = (
+  target: NotificationTarget | undefined,
+  targetPanels: NotificationTargetPanel[] | undefined,
+  tags: string[] | undefined,
+) => {
+  if (targetPanels) {
+    return Array.from(
+      new Set([...targetPanels.map((panel) => getNotificationTargetTag(panel)), ...(tags ?? [])]),
+    );
+  }
+
+  if (target) {
+    return addExactNotificationTargetTag(target, tags);
+  }
+
+  return tags ?? [];
+};
+
+const getTypeFromIncident = ({
+  incident,
+  severity,
+  type,
+}: {
+  incident?: NotificationIncidentDescriptor;
+  severity?: NonNullable<AddNotificationPayload['options']>['severity'];
+  type?: NonNullable<AddNotificationPayload['options']>['type'];
+}) => {
+  if (type) return type;
+  if (!incident) return undefined;
+
+  const status =
+    incident.status ??
+    (severity === 'error' ? 'failed' : severity === 'success' ? 'success' : severity);
+
+  return [incident.domain, incident.entity, incident.operation, status]
+    .filter((segment): segment is string => !!segment)
+    .join(':');
+};
+
+const mergeNotificationOptions = (
+  payload: AddNotificationPayload,
+  options: NonNullable<AddNotificationPayload['options']>,
+): AddNotificationPayload => {
+  const mergedOptions = { ...payload.options, ...options };
+
+  if (!payload.options && Object.keys(mergedOptions).length === 0) {
+    return payload;
+  }
+
+  return {
+    ...payload,
+    options: mergedOptions,
+  };
+};
+
+/** Returns imperative helpers for dispatching, targeting and dismissing client notifications. */
+export const useNotificationApi = (): NotificationApi => {
+  const { client } = useChatContext();
+  const contextTarget = useNotificationTargetContext();
+  const notificationManager = client?.notifications;
+
+  const addNotification: AddNotification = useCallback(
+    (payload, options) => {
+      if (!notificationManager) return;
+
+      const target =
+        options?.target ??
+        (options?.targetPanels || hasNotificationTargetTag(payload.options?.tags)
+          ? undefined
+          : contextTarget);
+      const notificationTags = getTargetTags(target, options?.targetPanels, payload.options?.tags);
+      const resolvedType = getTypeFromIncident({
+        incident: options?.incident,
+        severity: payload.options?.severity,
+        type: payload.options?.type,
+      });
+
+      notificationManager.add(
+        mergeNotificationOptions(payload, {
+          ...(notificationTags.length > 0 ? { tags: notificationTags } : {}),
+          ...(resolvedType ? { type: resolvedType } : {}),
+        }),
+      );
+    },
+    [contextTarget, notificationManager],
+  );
+
+  const addSystemNotification: AddSystemNotification = useCallback(
+    (payload, options) => {
+      if (!notificationManager) return '';
+
+      const notificationTags = Array.from(
+        new Set([SYSTEM_NOTIFICATION_TAG, ...(payload.options?.tags ?? [])]),
+      );
+      const resolvedType = getTypeFromIncident({
+        incident: options?.incident,
+        severity: payload.options?.severity,
+        type: payload.options?.type,
+      });
+
+      return notificationManager.add(
+        mergeNotificationOptions(payload, {
+          ...(notificationTags.length > 0 ? { tags: notificationTags } : {}),
+          ...(resolvedType ? { type: resolvedType } : {}),
+        }),
+      );
+    },
+    [notificationManager],
+  );
+
+  const removeNotification: RemoveNotification = useCallback(
+    (id) => {
+      if (!notificationManager) return;
+
+      notificationManager.remove(id);
+    },
+    [notificationManager],
+  );
+
+  const removeNotificationsForCurrentPanel: RemoveNotificationsForCurrentPanel = useCallback(() => {
+    if (!contextTarget || !notificationManager) return;
+
+    const notificationIds = notificationManager.notifications
+      .filter(
+        (notification) =>
+          !hasSystemNotificationTag(notification) &&
+          isNotificationForTarget(notification, contextTarget),
+      )
+      .map(({ id }) => id);
+
+    notificationIds.forEach(removeNotification);
+  }, [contextTarget, notificationManager, removeNotification]);
+
+  const runWithNotificationTarget: RunWithNotificationTarget = useCallback(
+    async (callback, target = contextTarget) => {
+      if (!target || !notificationManager) {
+        return await callback();
+      }
+
+      const unregisterActionTarget = registerNotificationActionTarget(notificationManager, target);
+      try {
+        return await callback();
+      } finally {
+        unregisterActionTarget();
+      }
+    },
+    [contextTarget, notificationManager],
+  );
+
+  const startNotificationTimeout: StartNotificationTimeout = useCallback(
+    (id, durationOverride) => {
+      if (!notificationManager) return;
+
+      if (typeof durationOverride === 'number') {
+        notificationManager.startTimeout(id, durationOverride);
+        return;
+      }
+
+      notificationManager.startTimeout(id);
+    },
+    [notificationManager],
+  );
+
+  return {
+    addNotification,
+    addSystemNotification,
+    removeNotification,
+    removeNotificationsForCurrentPanel,
+    runWithNotificationTarget,
+    startNotificationTimeout,
+  };
+};

package/src/components/Notifications/hooks/useNotificationListController.ts

@@ -0,0 +1,160 @@
+import { useEffect } from 'react';
+
+import type { Notification as NotificationType } from 'stream-chat';
+
+import { hasSystemNotificationTag, useNotificationApi } from './useNotificationApi';
+import { useNotifications, type UseNotificationsFilter } from './useNotifications';
+
+import { useChatContext } from '../../../contexts/chatContext/ChatContext';
+import { useLazyRef } from '../../../hooks/useLazyRef';
+import { useStableCallback } from '../../../hooks/useStableCallback';
+import {
+  isNotificationForTarget,
+  registerActiveNotificationTarget,
+  resolveNotificationTargetTagIfNeeded,
+  type NotificationTargetPanel,
+} from '../notificationTarget';
+import { useResolvedNotificationTarget } from '../NotificationTargetContext';
+
+export type UseNotificationListControllerParams = {
+  filter?: UseNotificationsFilter;
+  hostId?: string;
+  panel?: NotificationTargetPanel;
+};
+
+export type UseNotificationListControllerResult = {
+  dismissNotification: () => void;
+  notification: NotificationType | null;
+};
+
+const ACTION_NOTIFICATION_DURATION = 5000;
+
+const getNewestNotification = (notifications: NotificationType[]) =>
+  notifications.reduce<NotificationType | null>(
+    (newest, notification) =>
+      !newest || notification.createdAt >= newest.createdAt ? notification : newest,
+    null,
+  );
+
+const isPersistentNotification = (notification: NotificationType) => !notification.duration;
+
+const getActiveNotification = (notifications: NotificationType[]) => {
+  const persistentNotifications = notifications.filter(isPersistentNotification);
+  return getNewestNotification(
+    persistentNotifications.length > 0 ? persistentNotifications : notifications,
+  );
+};
+
+const getNotificationDurationOverride = (notification: NotificationType) => {
+  if (isPersistentNotification(notification)) return undefined;
+  if (!notification.actions?.length) return undefined;
+
+  return Math.max(notification.duration ?? 0, ACTION_NOTIFICATION_DURATION);
+};
+
+export const useNotificationListController = ({
+  filter,
+  hostId,
+  panel,
+}: UseNotificationListControllerParams = {}): UseNotificationListControllerResult => {
+  const { client } = useChatContext();
+  const { removeNotification, startNotificationTimeout } = useNotificationApi();
+  const target = useResolvedNotificationTarget({ hostId, panel });
+  const startedTimeoutIdsRef = useLazyRef<Set<string>>(() => new Set());
+
+  const combinedFilter = useStableCallback((notification: NotificationType) => {
+    if (hasSystemNotificationTag(notification)) return false;
+    return filter ? filter(notification) : true;
+  });
+
+  const notifications = useNotifications({
+    filter: combinedFilter,
+    requireTarget: true,
+    target,
+  });
+  const notification = getActiveNotification(notifications);
+
+  const dismissNotification = useStableCallback(() => {
+    if (!notification) return;
+
+    startedTimeoutIdsRef.current.delete(notification.id);
+    removeNotification(notification.id);
+  });
+
+  const removeCurrentPanelNotifications = useStableCallback(() => {
+    if (!target) return;
+
+    startedTimeoutIdsRef.current.clear();
+    client.notifications.notifications
+      .filter(
+        (notification) =>
+          !hasSystemNotificationTag(notification) && isNotificationForTarget(notification, target),
+      )
+      .forEach(({ id }) => removeNotification(id));
+  });
+
+  useEffect(() => {
+    return client.notifications.store.addPreprocessor((nextState, previousState) => {
+      const previousNotificationIds = new Set(
+        previousState?.notifications.map(({ id }) => id) ?? [],
+      );
+
+      nextState.notifications.forEach((notification) => {
+        if (previousNotificationIds.has(notification.id)) return;
+        if (hasSystemNotificationTag(notification)) return;
+
+        resolveNotificationTargetTagIfNeeded(client.notifications, notification);
+      });
+    });
+  }, [client.notifications]);
+
+  useEffect(() => {
+    if (!target) return;
+
+    return registerActiveNotificationTarget(client.notifications, target);
+  }, [client.notifications, target]);
+
+  useEffect(() => {
+    const notificationIds = new Set(notifications.map(({ id }) => id));
+    startedTimeoutIdsRef.current.forEach((id) => {
+      if (!notificationIds.has(id)) {
+        startedTimeoutIdsRef.current.delete(id);
+      }
+    });
+  }, [notifications, startedTimeoutIdsRef]);
+
+  useEffect(() => {
+    if (!notification || notifications.length <= 1) return;
+
+    notifications.forEach(({ id }) => {
+      if (id === notification.id) return;
+
+      startedTimeoutIdsRef.current.delete(id);
+      removeNotification(id);
+    });
+  }, [notification, notifications, removeNotification, startedTimeoutIdsRef]);
+
+  useEffect(() => {
+    if (!notification) return;
+    if (startedTimeoutIdsRef.current.has(notification.id)) return;
+
+    startedTimeoutIdsRef.current.add(notification.id);
+    const durationOverride = getNotificationDurationOverride(notification);
+    if (typeof durationOverride === 'number') {
+      startNotificationTimeout(notification.id, durationOverride);
+    } else {
+      startNotificationTimeout(notification.id);
+    }
+  }, [notification, startNotificationTimeout, startedTimeoutIdsRef]);
+
+  useEffect(() => {
+    return () => {
+      removeCurrentPanelNotifications();
+    };
+  }, [removeCurrentPanelNotifications]);
+
+  return {
+    dismissNotification,
+    notification,
+  };
+};