stream-chat-react-native-core 9.2.0-beta.2 → 9.2.0-beta.4

package/src/components/Notifications/__tests__/notificationTarget.test.ts

@@ -0,0 +1,157 @@
+import type { Notification } from 'stream-chat';
+
+import {
+  addNotificationTargetTag,
+  getChannelNotificationHostId,
+  getNotificationTarget,
+  getNotificationTargetPanel,
+  getNotificationTargetPanels,
+  getNotificationTargetTag,
+  getThreadNotificationHostId,
+  isNotificationForPanel,
+  isNotificationForTarget,
+  registerActiveNotificationTarget,
+  registerNotificationActionTarget,
+  resolveNotificationTargetTagIfNeeded,
+} from '../notificationTarget';
+
+const notification = (overrides: Partial<Notification>): Notification =>
+  ({
+    createdAt: Date.now(),
+    id: 'notification-id',
+    message: 'Notification',
+    origin: { emitter: 'test' },
+    ...overrides,
+  }) as Notification;
+
+describe('notificationTarget', () => {
+  it('adds a target tag without duplicating existing tags', () => {
+    expect(addNotificationTargetTag('channel', ['target:channel', 'custom'])).toEqual([
+      'target:channel',
+      'custom',
+    ]);
+  });
+
+  it('reads exact host targets from tags', () => {
+    const result = notification({
+      tags: [getNotificationTargetTag('channel', 'channel:messaging:general')],
+    });
+
+    expect(getNotificationTarget(result)).toEqual({
+      hostId: 'channel:messaging:general',
+      panel: 'channel',
+    });
+    expect(
+      isNotificationForTarget(result, { hostId: 'channel:messaging:general', panel: 'channel' }),
+    ).toBe(true);
+    expect(
+      isNotificationForTarget(result, { hostId: 'channel:messaging:random', panel: 'channel' }),
+    ).toBe(false);
+  });
+
+  it('supports custom target panels', () => {
+    const result = notification({
+      tags: [getNotificationTargetTag('custom-panel', 'custom-host')],
+    });
+
+    expect(getNotificationTarget(result)).toEqual({
+      hostId: 'custom-host',
+      panel: 'custom-panel',
+    });
+    expect(isNotificationForTarget(result, { hostId: 'custom-host', panel: 'custom-panel' })).toBe(
+      true,
+    );
+  });
+
+  it('reads target panels from tags before origin context', () => {
+    const result = notification({
+      origin: { context: { panel: 'thread' }, emitter: 'test' },
+      tags: ['target:channel', 'target:thread-list'],
+    });
+
+    expect(getNotificationTargetPanel(result)).toBe('channel');
+    expect(getNotificationTargetPanels(result)).toEqual(['channel', 'thread-list']);
+  });
+
+  it('falls back to origin context panel', () => {
+    const result = notification({
+      origin: { context: { panel: 'thread' }, emitter: 'test' },
+    });
+
+    expect(getNotificationTargetPanel(result)).toBe('thread');
+    expect(getNotificationTargetPanels(result)).toEqual(['thread']);
+  });
+
+  it('infers exact targets from composer context', () => {
+    const channelResult = notification({
+      origin: {
+        context: { composer: { channel: { cid: 'messaging:general' }, threadId: null } },
+        emitter: 'MessageComposer',
+      },
+    });
+    const threadResult = notification({
+      origin: {
+        context: { composer: { channel: { cid: 'messaging:general' }, threadId: 'thread-id' } },
+        emitter: 'MessageComposer',
+      },
+    });
+
+    expect(getNotificationTarget(channelResult)).toEqual({
+      hostId: getChannelNotificationHostId('messaging:general'),
+      panel: 'channel',
+    });
+    expect(getNotificationTarget(threadResult)).toEqual({
+      hostId: getThreadNotificationHostId('thread-id'),
+      panel: 'thread',
+    });
+  });
+
+  it('does not fall back untagged notifications to the channel panel', () => {
+    const result = notification({});
+
+    expect(isNotificationForPanel(result, 'channel')).toBe(false);
+    expect(isNotificationForPanel(result, 'thread')).toBe(false);
+    expect(getNotificationTargetPanels(result)).toEqual([]);
+  });
+
+  it('adds an exact target tag to untagged notifications from the active target', () => {
+    const owner = {};
+    const target = { hostId: 'channel:messaging:general', panel: 'channel' } as const;
+    const unregister = registerActiveNotificationTarget(owner, target);
+    const result = notification({});
+
+    expect(resolveNotificationTargetTagIfNeeded(owner, result)).toBe(true);
+    expect(result.tags).toEqual(['target:channel:channel:messaging:general']);
+    expect(isNotificationForTarget(result, target)).toBe(true);
+
+    unregister();
+  });
+
+  it('prefers action target over active target when adding exact target tags', () => {
+    const owner = {};
+    const actionTarget = { hostId: 'channel:messaging:action', panel: 'channel' } as const;
+    const activeTarget = { hostId: 'channel:messaging:active', panel: 'channel' } as const;
+    const unregisterActive = registerActiveNotificationTarget(owner, activeTarget);
+    const unregisterAction = registerNotificationActionTarget(owner, actionTarget);
+    const result = notification({});
+
+    expect(resolveNotificationTargetTagIfNeeded(owner, result)).toBe(true);
+    expect(result.tags).toEqual(['target:channel:channel:messaging:action']);
+
+    unregisterAction();
+    unregisterActive();
+  });
+
+  it('does not exactify broad target tags', () => {
+    const owner = {};
+    const target = { hostId: 'channel:messaging:general', panel: 'channel' } as const;
+    const unregister = registerActiveNotificationTarget(owner, target);
+    const result = notification({ tags: ['target:channel'] });
+
+    expect(resolveNotificationTargetTagIfNeeded(owner, result)).toBe(false);
+    expect(result.tags).toEqual(['target:channel']);
+    expect(isNotificationForTarget(result, target)).toBe(true);
+
+    unregister();
+  });
+});

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,
+  };
+};