stream-chat-react-native-core 10.0.0-rc.2 → 10.0.0-rc.4

package/src/ai-components/voice-visualization/useVoiceVisualization.ts

@@ -0,0 +1,153 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useColorScheme } from 'react-native';
+
+import {
+  type FrameInfo,
+  runOnUI,
+  useFrameCallback,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+
+import {
+  advanceDriver,
+  createDriverState,
+  hoverDriver,
+  tapDriver,
+  type VoiceDriverInput,
+} from './driver';
+import { audioLevelInput, expressivityInput } from './math';
+import { FALLBACK_COLOR, luminance, toHsvPalette } from './palette';
+import type { VoiceVisualizationStyle } from './styles';
+import type { VoiceVisualizationProps } from './types';
+import { useReduceMotion } from './useReduceMotion';
+
+import { useTheme } from '../contexts';
+
+/** How long the visualization takes to fade in once its first frame is drawn, as on iOS. */
+const FADE_IN_MS = 300;
+
+/** Whether to draw for a dark background: the theme's backdrop when readable, else the scheme. */
+const useDark = (backdropColor: string | undefined) => {
+  const scheme = useColorScheme();
+  return useMemo(() => {
+    const backdrop = backdropColor ? luminance(backdropColor) : null;
+    if (backdrop !== null) return backdrop < 0.5 ? 1 : 0;
+    return scheme === 'dark' ? 1 : 0;
+  }, [backdropColor, scheme]);
+};
+
+/**
+ * A voice visualization's motion, advanced once a frame on the UI thread.
+ *
+ * The driver lives in a shared value the renderers derive from, so a frame redraws without
+ * re-rendering React, and `audioLevel` is read in the frame callback, so a level changing many
+ * times a second re-renders nothing either.
+ */
+export const useVoiceVisualization = (
+  { audioLevel, colors, expressivity, state }: VoiceVisualizationProps,
+  style: VoiceVisualizationStyle,
+) => {
+  const { theme } = useTheme();
+  const reduceMotion = useReduceMotion();
+  const themeColors = theme.voiceVisualization?.colors;
+  const dark = useDark(theme.voiceVisualization?.backdropColor);
+
+  const colorsKey = (colors ?? []).join('|');
+  const themeKey = (themeColors ?? []).join('|');
+  const palette = useMemo(() => {
+    const own = toHsvPalette(colors ?? []);
+    if (own.length) return own;
+    const fromTheme = toHsvPalette(themeColors ?? []);
+    return fromTheme.length ? fromTheme : toHsvPalette([FALLBACK_COLOR]);
+    // Keyed by the colors themselves, so a new array of the same colors changes nothing.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [colorsKey, themeKey]);
+
+  const input: VoiceDriverInput = {
+    audioLevel: null,
+    colors: palette,
+    expressivity: expressivityInput(expressivity),
+    reduceMotion,
+    state,
+  };
+
+  // Starts settled on the first input, so the first frame shows it rather than easing into it.
+  const [initialDriver] = useState(() => createDriverState(input, style.levelResponse));
+  const driver = useSharedValue(initialDriver);
+  const inputValue = useSharedValue(input);
+  const darkValue = useSharedValue(dark);
+  const opacity = useSharedValue(0);
+  const fadingIn = useSharedValue(false);
+
+  useEffect(() => {
+    inputValue.value = {
+      audioLevel: null,
+      colors: palette,
+      expressivity: expressivityInput(expressivity),
+      reduceMotion,
+      state,
+    };
+  }, [expressivity, inputValue, palette, reduceMotion, state]);
+
+  useEffect(() => {
+    darkValue.value = dark;
+  }, [dark, darkValue]);
+
+  const onFrame = useCallback(
+    (frame: FrameInfo) => {
+      'worklet';
+      const seconds = (frame.timeSincePreviousFrame ?? 0) / 1000;
+      const current = inputValue.value;
+      const level = audioLevelInput(audioLevel ? audioLevel.value : null);
+      const next = level === current.audioLevel ? current : { ...current, audioLevel: level };
+      driver.modify((d) => {
+        'worklet';
+        advanceDriver(d, next, seconds);
+        return d;
+      });
+      // It fades in once it has something to show, rather than flashing empty while the first
+      // frame lands.
+      if (!fadingIn.value) {
+        fadingIn.value = true;
+        opacity.value = withTiming(1, { duration: FADE_IN_MS });
+      }
+    },
+    [audioLevel, driver, fadingIn, inputValue, opacity],
+  );
+  useFrameCallback(onFrame);
+
+  /** A tap at a point centred and normalized to the shorter side, y up. */
+  const tap = useCallback(
+    (x: number, y: number) => {
+      runOnUI((tapX: number, tapY: number) => {
+        'worklet';
+        driver.modify((d) => {
+          'worklet';
+          tapDriver(d, inputValue.value, tapX, tapY);
+          return d;
+        });
+      })(x, y);
+    },
+    [driver, inputValue],
+  );
+
+  /** Where a pointer hovers, or null once it has left. */
+  const hover = useCallback(
+    (x: number | null, y: number | null) => {
+      runOnUI((hoverX: number | null, hoverY: number | null) => {
+        'worklet';
+        driver.modify((d) => {
+          'worklet';
+          hoverDriver(d, inputValue.value, hoverX, hoverY);
+          return d;
+        });
+      })(x, y);
+    },
+    [driver, inputValue],
+  );
+
+  return { dark: darkValue, driver, hover, opacity, tap };
+};
+
+export type VoiceVisualization = ReturnType<typeof useVoiceVisualization>;

package/src/ai-components/voice-visualization/waveGeometry.ts

@@ -0,0 +1,137 @@
+import { Skia, type SkPath } from '@shopify/react-native-skia';
+
+import { driverReact, driverScale, type VoiceDriverState } from './driver';
+import { clamp, mix, saturate, smoothstep, speechEnv, vivid } from './math';
+
+const POINTS = 160;
+export const WAVE_STOPS = 13;
+export const WAVE_START = -0.42;
+export const WAVE_END = 0.42;
+
+/** The stops' positions along the gradient, evenly spaced. */
+export const WAVE_POSITIONS = Array.from({ length: WAVE_STOPS }, (_, s) => s / (WAVE_STOPS - 1));
+
+const sq = (x: number) => {
+  'worklet';
+  return x * x;
+};
+
+const bandCenter = (i: number, seg: number, t: number) => {
+  'worklet';
+  switch (i) {
+    case 0:
+      return 0.5 * seg + 0.12 * Math.sin(t * 0.13);
+    case 1:
+      return 1.5 * seg + 0.13 * Math.sin(t * 0.11 + 2.1);
+    case 2:
+      return 2.5 * seg + 0.12 * Math.sin(t * 0.17 + 4.2);
+    case 3:
+      return 3.5 * seg + 0.12 * Math.sin(t * 0.15 + 1);
+    default:
+      return 4.5 * seg + 0.12 * Math.sin(t * 0.1 + 3.3);
+  }
+};
+
+/** The string's height above its centre line at each point, centred and normalized, y up. */
+export const waveHeights = (d: VoiceDriverState) => {
+  'worklet';
+  const t = d.time;
+  const react = driverReact(d);
+  const center = d.load * 0.3 * Math.sin(t * 1.3);
+  const freq = 24 + 26 * react + 10 * d.flow;
+  const speak = smoothstep(0.6, 1, react);
+  const drive = mix(speak * 0.26 * speechEnv(t), 0.3 * d.mic, d.voice);
+  const reach = 0.018 + 0.022 * react + drive + 0.14 * d.flow + 0.1 * d.load;
+  const tapAlive = d.tapAge < 1.5;
+  const hovered = d.hoverAmount > 0.001;
+  const xs: number[] = [];
+  const ys: number[] = [];
+  for (let i = 0; i <= POINTS; i++) {
+    const x = WAVE_START + ((WAVE_END - WAVE_START) * i) / POINTS;
+    let y = Math.exp(-sq((x - center) / 0.18)) * reach * Math.sin(x * freq - t * 5);
+    if (tapAlive) {
+      y +=
+        Math.exp(-sq((x - d.tapX) / 0.12)) *
+        Math.sin((x - d.tapX) * 40 - d.tapAge * 24) *
+        Math.exp(-d.tapAge * 2.6) *
+        0.05;
+    }
+    if (hovered) {
+      y +=
+        Math.exp(-sq((x - d.hoverX) / 0.12)) *
+        Math.sin((x - d.hoverX) * 40 - t * 7) *
+        d.hoverAmount *
+        0.04;
+    }
+    xs.push(x);
+    ys.push(y);
+  }
+  return { xs, ys };
+};
+
+type LegacyPath = SkPath & {
+  lineTo: (x: number, y: number) => void;
+  moveTo: (x: number, y: number) => void;
+};
+
+/**
+ * The wave as a path in a `width` by `height` canvas. Newer Skia versions build immutable paths with
+ * `PathBuilder`; earlier 2.x versions mutate `SkPath` itself.
+ */
+export const wavePath = (d: VoiceDriverState, width: number, height: number): SkPath => {
+  'worklet';
+  const m = Math.min(width, height);
+  const scale = driverScale(d);
+  const { xs, ys } = waveHeights(d);
+  const px = (i: number) => width / 2 + xs[i] * m * scale;
+  const py = (i: number) => height / 2 - ys[i] * m * scale;
+  if (Skia.PathBuilder) {
+    const builder = Skia.PathBuilder.Make();
+    builder.moveTo(px(0), py(0));
+    for (let i = 1; i < xs.length; i++) builder.lineTo(px(i), py(i));
+    return builder.build();
+  }
+  const path = Skia.Path.Make() as LegacyPath;
+  path.moveTo(px(0), py(0));
+  for (let i = 1; i < xs.length; i++) path.lineTo(px(i), py(i));
+  return path;
+};
+
+/**
+ * The string's colors at its gradient stops, as RGBA from 0 to 1: up to five bands drifting along
+ * it, weighed by how near their centres are, its ends fading out.
+ */
+export const waveColors = (d: VoiceDriverState, dark: number) => {
+  'worklet';
+  const band: number[][] = [];
+  for (let i = 0; i < 5; i++) {
+    const rgb = [0, 0, 0];
+    vivid(d.colors[i], dark, rgb);
+    band.push(rgb);
+  }
+  const seg = 1 / Math.max(d.count, 1);
+  const bandWidth = seg * 0.7;
+  const stops: Float32Array[] = [];
+  for (let s = 0; s < WAVE_STOPS; s++) {
+    const x = WAVE_START + ((WAVE_END - WAVE_START) * s) / (WAVE_STOPS - 1);
+    const gx = clamp(x + 0.5, 0, 1);
+    const color = [0, 0, 0];
+    let total = 1e-4;
+    for (let i = 0; i < 5; i++) {
+      const present = i === 0 ? 1 : clamp(d.count - i, 0, 1);
+      const weight = Math.exp(-sq((gx - bandCenter(i, seg, d.time)) / bandWidth)) * present;
+      for (let j = 0; j < 3; j++) color[j] += band[i][j] * weight;
+      total += weight;
+    }
+    for (let j = 0; j < 3; j++) color[j] /= total;
+    saturate(color, 1.2);
+    saturate(color, d.sat);
+    const alpha = clamp(smoothstep(0.4, 0.24, Math.abs(x)) * d.bright, 0, 1);
+    stops.push(new Float32Array([color[0], color[1], color[2], alpha]));
+  }
+  return stops;
+};
+
+/** The line is 0.6% of the shorter side, and never under 1.5 device pixels, as on Android and iOS. */
+export const waveStrokeWidth = (width: number, height: number, pixelRatio: number) =>
+  Math.max(0.006 * Math.min(width, height), 1.5 / pixelRatio);

package/src/components/Channel/Channel.tsx

@@ -104,6 +104,7 @@ const ChannelWithContext = (props: PropsWithChildren<ChannelPropsWithContext>) =
       {...shellProps}
       channel={channel}
       hasPendingInitialTargetLoad={hasPendingInitialTargetLoad}
+      initializeOnMount={initializeOnMount}
     >
       {children}
     </ChannelShell>

package/src/components/Channel/ChannelShell.tsx

@@ -15,6 +15,7 @@ import { useCreateChannelContext } from './hooks/useCreateChannelContext';
 import { useCreateInputMessageInputContext } from './hooks/useCreateInputMessageInputContext';
 import { useCreateMessagesContext } from './hooks/useCreateMessagesContext';
 import { useCreateOwnCapabilitiesContext } from './hooks/useCreateOwnCapabilitiesContext';
+import { useJumpToLatestOnOpen } from './hooks/useJumpToLatestOnOpen';
 
 import {
   AttachmentPickerContextValue,
@@ -208,6 +209,8 @@ export type ChannelConfigProps = Partial<
 type ChannelShellProps = ChannelConfigProps & {
   channel: Channel;
   hasPendingInitialTargetLoad: () => boolean;
+  /** `<Channel>`'s `initializeOnMount`: when false, the app places the list's pages itself. */
+  initializeOnMount?: boolean;
   /** Set by `<Thread>`: the list and composer below show this thread's replies. */
   thread?: Thread;
 };
@@ -228,6 +231,13 @@ const channelStatusSelector = (state: ChannelDataState & ChannelLifecycleState)
   pendingDisposal: state.pendingDisposal,
 });
 
+// Renders nothing. It sits under the providers below so its hook can read the
+// channel and thread context this component provides.
+const JumpToLatestOnOpen = () => {
+  useJumpToLatestOnOpen();
+  return null;
+};
+
 /**
  * The providers a message list and composer need, shared by `<Channel>` and `<Thread>`, which each
  * own their lifecycle (watching, loading, marking read) and render this around their children.
@@ -288,6 +298,7 @@ export const ChannelShell = (props: PropsWithChildren<ChannelShellProps>) => {
     hasFilePicker = isDocumentPickerAvailable(),
     hasImagePicker = isImagePickerAvailable() || isImageMediaLibraryAvailable(),
     hasPendingInitialTargetLoad,
+    initializeOnMount = true,
     allowDateSeparatorForSystemMessages = false,
     hideDateSeparators = false,
     hideStickyDateHeader = false,
@@ -508,6 +519,7 @@ export const ChannelShell = (props: PropsWithChildren<ChannelShellProps>) => {
                 <MessageInputProvider value={inputMessageInputContext}>
                   <AudioPlayerProvider value={audioPlayerContext}>
                     <NotificationAnnouncer />
+                    {initializeOnMount ? <JumpToLatestOnOpen /> : null}
                     <View style={{ height: '100%' }}>{children}</View>
                     {shouldRenderAttachmentPicker ? <AttachmentPicker /> : null}
                   </AudioPlayerProvider>

package/src/components/Channel/__tests__/Channel.test.tsx

@@ -3,7 +3,7 @@ import { AppState, AppStateStatus, View } from 'react-native';
 
 import { act, cleanup, render, waitFor } from '@testing-library/react-native';
 import type { Channel as ChannelType, StreamChat as StreamChatType } from 'stream-chat';
-import { asTimestampNS, StreamChat } from 'stream-chat';
+import { asTimestampNS, ChannelWatchStatus, StreamChat } from 'stream-chat';
 
 import type { ChannelContextValue } from '../../../contexts/channelContext/ChannelContext';
 import { ChannelContext, ChannelProvider } from '../../../contexts/channelContext/ChannelContext';
@@ -153,7 +153,7 @@ describe('Channel', () => {
     } as never);
     draft.initialized = true;
     const watchSpy = jest.spyOn(draft, 'watch');
-    const reloadSpy = jest.spyOn(draft.messagePaginator, 'reload');
+    const seedSpy = jest.spyOn(draft.messagePaginator, 'reload');
 
     renderComponent({ channel: draft });
     // let the mount effect run to its end
@@ -163,7 +163,7 @@ describe('Channel', () => {
 
     expect(draft.isProvisional).toBe(true);
     expect(watchSpy).not.toHaveBeenCalled();
-    expect(reloadSpy).not.toHaveBeenCalled();
+    expect(seedSpy).not.toHaveBeenCalled();
   });
 
   it('should set an error if channel watch fails and render a LoadingErrorIndicator', async () => {
@@ -757,6 +757,147 @@ describe('Channel initial load useEffect', () => {
     await waitFor(() => expect(Object.keys(channel.state.members)).toHaveLength(10));
   });
 
+  describe('watch on mount for an initialized channel at the head', () => {
+    const mountLoadedChannel = async (watchStatus: ChannelWatchStatus) => {
+      const messages = Array.from({ length: 10 }, (_, i) => generateMessage({ id: String(i) }));
+      const mockedChannel = generateChannelResponse({ messages });
+      useMockedApis(chatClient, [getOrCreateChannelApi(mockedChannel)]);
+      const channel = chatClient.channel('messaging', mockedChannel.channel.id);
+      await channel.watch();
+      jest.spyOn(channel.messagePaginator, 'isActiveIntervalAtHead', 'get').mockReturnValue(true);
+      channel.watchStatus = watchStatus;
+      const watchSpy = jest.fn();
+      channel.watch = watchSpy;
+      const seedSpy = jest.spyOn(channel.messagePaginator, 'seedUnreadSnapshot');
+
+      renderComponent({ channel, markReadOnMount: false });
+      // The seed runs after the watch decision, so the mount effect has made it by then.
+      await waitFor(() => expect(seedSpy).toHaveBeenCalled());
+
+      return watchSpy;
+    };
+
+    it('watches a channel that was loaded without a watch, such as a search result', async () => {
+      const watchSpy = await mountLoadedChannel(ChannelWatchStatus.NotWatching);
+
+      expect(watchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not watch a channel that is already watched', async () => {
+      const watchSpy = await mountLoadedChannel(ChannelWatchStatus.Watching);
+
+      expect(watchSpy).not.toHaveBeenCalled();
+    });
+
+    it('leaves a channel whose watch dropped with the connection to the connection recovery', async () => {
+      const watchSpy = await mountLoadedChannel(ChannelWatchStatus.WasWatching);
+
+      expect(watchSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('reopening a channel left on an older page', () => {
+    const OLDER_PAGE_START = new Date('2020-01-01T00:00:00.000Z').getTime();
+
+    // A watched channel whose newest messages are loaded, but whose list shows an older page, as it
+    // does after a jump to a quoted, pinned or searched message.
+    const setUpChannelOnOlderPage = async () => {
+      const newestMessages = Array.from({ length: 10 }, (_, i) =>
+        generateMessage({ id: `newest-${i}` }),
+      );
+      const mockedChannel = generateChannelResponse({ messages: newestMessages });
+      useMockedApis(chatClient, [getOrCreateChannelApi(mockedChannel)]);
+      const channel = chatClient.channel('messaging', mockedChannel.channel.id);
+      await channel.watch();
+
+      const olderMessages = Array.from({ length: 5 }, (_, i) =>
+        generateMessage({ id: `older-${i}`, timestamp: OLDER_PAGE_START + i * 1000 }),
+      );
+      channel.messagePaginator.ingestPage({
+        page: olderMessages,
+        policy: 'strict-overlap-only',
+        setActive: true,
+      });
+      expect(channel.messagePaginator.isActiveIntervalAtHead).toBe(false);
+
+      return channel;
+    };
+
+    it('shows the newest messages again', async () => {
+      const channel = await setUpChannelOnOlderPage();
+
+      renderComponent({ channel, markReadOnMount: false });
+
+      await waitFor(() => expect(channel.messagePaginator.isActiveIntervalAtHead).toBe(true));
+      expect(channel.messagePaginator.items?.map((message) => message.id)).toContain('newest-9');
+    });
+
+    it('keeps a jump the integrator already made to a loaded message', async () => {
+      const channel = await setUpChannelOnOlderPage();
+      // A deep link from the screen: the target is loaded, so the jump lands at once.
+      await channel.messagePaginator.jumpToMessage('older-2', { focusReason: 'jump-to-message' });
+      const seedSpy = jest.spyOn(channel.messagePaginator, 'seedUnreadSnapshot');
+
+      renderComponent({ channel, markReadOnMount: false });
+
+      await waitFor(() => expect(seedSpy).toHaveBeenCalled());
+      expect(channel.messagePaginator.isActiveIntervalAtHead).toBe(false);
+      expect(channel.messagePaginator.messageFocusSignal.getLatestValue().signal?.messageId).toBe(
+        'older-2',
+      );
+    });
+
+    it('leaves a jump that is still in flight alone', async () => {
+      const channel = await setUpChannelOnOlderPage();
+      // A deep link to a message that is not loaded: its query is in flight.
+      jest.spyOn(channel.messagePaginator, 'isLoading', 'get').mockReturnValue(true);
+      const jumpToTheLatestMessageSpy = jest.spyOn(
+        channel.messagePaginator,
+        'jumpToTheLatestMessage',
+      );
+      const seedSpy = jest.spyOn(channel.messagePaginator, 'seedUnreadSnapshot');
+
+      renderComponent({ channel, markReadOnMount: false });
+
+      await waitFor(() => expect(seedSpy).toHaveBeenCalled());
+      expect(jumpToTheLatestMessageSpy).not.toHaveBeenCalled();
+    });
+
+    it('leaves the list alone when the app places its pages itself', async () => {
+      const channel = await setUpChannelOnOlderPage();
+      const jumpToTheLatestMessageSpy = jest.spyOn(
+        channel.messagePaginator,
+        'jumpToTheLatestMessage',
+      );
+
+      renderComponent({ channel, initializeOnMount: false, markReadOnMount: false });
+
+      expect(jumpToTheLatestMessageSpy).not.toHaveBeenCalled();
+      expect(channel.messagePaginator.isActiveIntervalAtHead).toBe(false);
+    });
+
+    it('leaves the jump to the first unread message to the initial load', async () => {
+      const channel = await setUpChannelOnOlderPage();
+      jest.spyOn(channel, 'countUnread').mockImplementation(() => 3);
+      const jumpToTheFirstUnreadMessageSpy = jest
+        .spyOn(channel.messagePaginator, 'jumpToTheFirstUnreadMessage')
+        .mockResolvedValue(undefined as never);
+      const jumpToTheLatestMessageSpy = jest.spyOn(
+        channel.messagePaginator,
+        'jumpToTheLatestMessage',
+      );
+
+      renderComponent({
+        channel,
+        initialScrollToFirstUnreadMessage: true,
+        markReadOnMount: false,
+      });
+
+      await waitFor(() => expect(jumpToTheFirstUnreadMessageSpy).toHaveBeenCalledTimes(1));
+      expect(jumpToTheLatestMessageSpy).not.toHaveBeenCalled();
+    });
+  });
+
   describe('message page size', () => {
     const mountChannel = async () => {
       const mockedChannel = generateChannelResponse({ messages: [] });
@@ -979,7 +1120,7 @@ describe('Channel initial load useEffect', () => {
     await channel.watch();
 
     // Call through to the real reload so the resync actually reconciles (and we can assert it ran).
-    const reloadSpy = jest.spyOn(channel, 'reload');
+    const seedSpy = jest.spyOn(channel, 'reload');
 
     renderComponent({ channel });
 
@@ -1007,7 +1148,7 @@ describe('Channel initial load useEffect', () => {
     // The reload re-watches and reconciles, but preserves the failed (locally-unsent) messages —
     // the 10 originals + 10 failed remain.
     await waitFor(() => {
-      expect(reloadSpy).toHaveBeenCalled();
+      expect(seedSpy).toHaveBeenCalled();
       expect(channel.messagePaginator.anchoredHeadItems.length).toBe(20);
     });
   });

package/src/components/Channel/hooks/useChannelLifecycle.ts

@@ -1,5 +1,6 @@
 import { useEffect } from 'react';
 
+import { ChannelWatchStatus } from 'stream-chat';
 import type { Channel, StreamChat } from 'stream-chat';
 
 import type { TranslationContextValue } from '../../../contexts/translationContext/TranslationContext';
@@ -107,7 +108,9 @@ export const useChannelLifecycle = ({
       }
 
       if (
-        (!channel.initialized || !channel.messagePaginator.isActiveIntervalAtHead) &&
+        (!channel.initialized ||
+          !channel.messagePaginator.isActiveIntervalAtHead ||
+          channel.watchStatus === ChannelWatchStatus.NotWatching) &&
         initializeOnMount
       ) {
         try {

package/src/components/Channel/hooks/useJumpToLatestOnOpen.ts

@@ -0,0 +1,42 @@
+import { useLayoutEffect } from 'react';
+
+import { useChannelContext } from '../../../contexts/channelContext/ChannelContext';
+import { useThreadContext } from '../../../contexts/threadContext/ThreadContext';
+import { useMessagePaginator } from '../../../hooks/useMessagePaginator';
+
+/**
+ * Shows the newest messages when a channel or thread is opened on an older page. Its paginator
+ * outlives the screen, so it keeps the page it was left on, such as one after a jump to a quoted,
+ * pinned or searched message. Runs before the first paint, so the old page never flashes.
+ *
+ * Stays out of the way of a jump that already landed or is in flight (a deep link from the screen)
+ * and of the jump to the first unread message. Runs once per channel or thread: its dependencies
+ * are stable, so nothing that changes while it is open moves the list.
+ *
+ * `<Channel>` and `<Thread>` already run it, unless `<Channel initializeOnMount={false}>`. Call it
+ * from a component inside `<Channel>` or `<Thread>` only when the app opted out that way and still
+ * wants the newest messages shown on open.
+ */
+export const useJumpToLatestOnOpen = () => {
+  const { channel, hasPendingInitialTargetLoad } = useChannelContext();
+  const { thread } = useThreadContext();
+  const paginator = useMessagePaginator();
+
+  useLayoutEffect(() => {
+    // A channel that is not loaded yet, or a draft, gets its first page from `<Channel>` itself.
+    const isChannelLoading = !thread && (!channel.initialized || channel.isProvisional);
+    if (
+      isChannelLoading ||
+      !paginator.items?.length ||
+      paginator.isActiveIntervalAtHead ||
+      paginator.isLoading ||
+      hasPendingInitialTargetLoad?.()
+    ) {
+      return;
+    }
+
+    paginator
+      .jumpToTheLatestMessage()
+      .catch((error: unknown) => console.warn('Jumping to the latest message failed:', error));
+  }, [channel, hasPendingInitialTargetLoad, paginator, thread]);
+};

package/src/components/ChannelDetails/__tests__/ChannelDetails.test.tsx

@@ -28,7 +28,7 @@ const Providers = ({ children }: PropsWithChildren) => (
       }}
     >
       <ChatContext.Provider
-        value={{ client: { notifications: new NotificationManager(), userID: 'me' } } as never}
+        value={{ client: { notifications: new NotificationManager(), userId: 'me' } } as never}
       >
         {children}
       </ChatContext.Provider>

package/src/components/ChannelDetails/__tests__/ChannelDetailsActionsSection.test.tsx

@@ -69,7 +69,7 @@ const sectionElement = () => (
               mutedUsers: [],
               mutedUsersStore,
               on: () => ({ unsubscribe: () => undefined }),
-              userID: 'me',
+              userId: 'me',
             },
           } as never
         }

package/src/components/ChannelDetails/__tests__/ChannelDetailsEditButton.test.tsx

@@ -63,7 +63,7 @@ const Providers = ({ children }: PropsWithChildren) => (
         }}
       >
         <ChatContext.Provider
-          value={{ client: { notifications: new NotificationManager(), userID: 'me' } } as never}
+          value={{ client: { notifications: new NotificationManager(), userId: 'me' } } as never}
         >
           {children}
         </ChatContext.Provider>

package/src/components/ChannelDetails/__tests__/ChannelDetailsMemberSection.test.tsx

@@ -99,7 +99,7 @@ const renderSection = ({
                   mutedUsers: [],
                   notifications: new NotificationManager(),
                   on: () => ({ unsubscribe: () => undefined }),
-                  userID: 'me',
+                  userId: 'me',
                 },
               } as never
             }

package/src/components/ChannelDetails/__tests__/ChannelDetailsNavHeader.test.tsx

@@ -39,7 +39,7 @@ const Providers = ({ children }: PropsWithChildren) => (
         }}
       >
         <ChatContext.Provider
-          value={{ client: { notifications: new NotificationManager(), userID: 'me' } } as never}
+          value={{ client: { notifications: new NotificationManager(), userId: 'me' } } as never}
         >
           {children}
         </ChatContext.Provider>

package/src/components/ChannelDetails/__tests__/ChannelDetailsProfile.test.tsx

@@ -31,7 +31,7 @@ const buildChannel = () =>
   ({
     cid: 'messaging:test',
     data: {},
-    getClient: () => ({ userID: OWN_USER_ID }),
+    getClient: () => ({ userId: OWN_USER_ID }),
     on: () => ({ unsubscribe: () => undefined }),
   }) as unknown as Channel;
 
@@ -45,7 +45,7 @@ const renderProfile = ({ channel = buildChannel() }: { channel?: Channel } = {})
           userLanguage: 'en',
         }}
       >
-        <ChatProvider value={{ client: { userID: OWN_USER_ID } } as never}>
+        <ChatProvider value={{ client: { userId: OWN_USER_ID } } as never}>
           <ChannelDetailsContextProvider channel={channel}>
             <ChannelDetailsProfile />
           </ChannelDetailsContextProvider>

package/src/components/ChannelDetails/__tests__/ChannelEditDetailsForm.test.tsx

@@ -73,7 +73,7 @@ const renderForm = ({ channel, onClose = jest.fn() }: { channel: Channel; onClos
           }}
         >
           <ChatContext.Provider
-            value={{ client: { notifications: new NotificationManager(), userID: 'me' } } as never}
+            value={{ client: { notifications: new NotificationManager(), userId: 'me' } } as never}
           >
             <ChannelDetailsContextProvider channel={channel}>
               <WithComponents overrides={{ ChannelEditDetailsFormContent: EditDetailsProbe }}>