stream-chat-react-native-core 9.12.1 → 10.0.0-beta.2

package/src/components/ImageGallery/ImageGallery.tsx

@@ -81,10 +81,8 @@ type ImageGalleryWithContextProps = Pick<
   };
 
 /**
- * Number of slides mounted on each side of the current one. Kept one wider
- * than AnimatedGalleryImage's +-3 load window so an edge slide is already
- * mounted (as the empty placeholder) before it ever needs to load its
- * image - paging never reveals an unmounted slot.
+ * Number of slides mounted on each side of the current one. One more than the image load window in
+ * `AnimatedGalleryImage`, so an edge slide is already mounted as a placeholder before it loads.
  */
 const PAGER_WINDOW_RADIUS = 4;
 
@@ -104,18 +102,12 @@ type GalleryPagerProps = {
 };
 
 /**
- * Windowed pager body. Subscribes to `currentIndex` itself (rather than the
- * parent doing so) so a page change rerenders only this small slide list and
- * never the parent - keeping the gesture objects/`GestureDetector` stable.
+ * The windowed slide list. It subscribes to `currentIndex` itself, so a page change re-renders only
+ * this list and not the parent, which keeps the gesture objects stable.
  *
- * Only the slides within +-{@link PAGER_WINDOW_RADIUS} of the current index are
- * mounted; a single leading spacer occupies the flex width of all preceding
- * slides so the rendered ones keep their exact natural positions. The slide
- * transforms in `useAnimatedGalleryStyle` are a pure function of each slide's
- * `index` and that natural flex position, so windowing the mount leaves every
- * slide pixelidentical while dropping the mounted component/view count to O(window)
- * instead of it being O(N). This way, less React fibers are reconciled and less
- * shadow nodes are rendered as well.
+ * Only slides within {@link PAGER_WINDOW_RADIUS} of the current index are mounted. A leading spacer
+ * takes the width of the skipped slides, so the mounted ones keep the natural positions that the
+ * transforms in `useAnimatedGalleryStyle` depend on.
  */
 const GalleryPager = (props: GalleryPagerProps) => {
   const { fullWindowHeight, fullWindowWidth, offsetScale, scale, slide, translateX, translateY } =
@@ -209,10 +201,7 @@ export const ImageGalleryWithContext = (props: ImageGalleryWithContextProps) =>
   const halfScreenHeight = fullWindowHeight / 2;
   const quarterScreenHeight = fullWindowHeight / 4;
 
-  /**
-   * Fade animation for screen, it is always rendered with pointerEvents
-   * set to none for fast opening
-   */
+  // Vertical offset of the whole screen: starts below the viewport and animates to 0.
   const screenTranslateY = useSharedValue(fullWindowHeight);
   const showScreen = useCallback(() => {
     'worklet';
@@ -222,20 +211,13 @@ export const ImageGalleryWithContext = (props: ImageGalleryWithContextProps) =>
     });
   }, [screenTranslateY]);
 
-  /**
-   * Run the fade animation on visible change
-   */
   useEffect(() => {
     dismissKeyboard();
     showScreen();
   }, [showScreen]);
 
-  /**
-   * Image height for the currently selected asset. SharedValue so worklet
-   * consumers (gesture math, header/footer opacity) read it directly on the
-   * UI thread so updating it doesn't trigger a parent rerender. The hook
-   * owns the value and updates it via a store subscription.
-   */
+  // Height of the current image. A SharedValue so worklets read it on the UI thread and updating
+  // it does not re-render this component.
   const currentImageHeight = useCurrentImageHeight({
     assets,
     fullWindowHeight,
@@ -243,14 +225,9 @@ export const ImageGalleryWithContext = (props: ImageGalleryWithContextProps) =>
     imageGalleryStateStore,
   });
 
-  /**
-   * Header visible value for animating in out
-   */
+  // Header and footer visibility: 1 shown, 0 hidden, animated between.
   const headerFooterVisible = useSharedValue(1);
 
-  /**
-   * Shared values for movement
-   */
   const translateX = useSharedValue(0);
   const translateY = useSharedValue(0);
   const offsetScale = useSharedValue(1);
@@ -284,12 +261,8 @@ export const ImageGalleryWithContext = (props: ImageGalleryWithContextProps) =>
     translationX,
   });
 
-  /**
-   * If the header is visible we scale down the opacity of it as the
-   * image is swiped downward. Reads currentImageHeight from a SharedValue so
-   * the worklet doesn't need to be re-registered when the image dimensions
-   * change between slides.
-   */
+  // Fades the header and footer as the image is dragged down. The height is read from a SharedValue
+  // so the worklet is not re-registered when the image dimensions change between slides.
   const headerFooterOpacity = useDerivedValue(() => {
     const imageHeight = currentImageHeight.value;
     return imageHeight * scale.value < fullWindowHeight && translateY.value > 0
@@ -302,9 +275,7 @@ export const ImageGalleryWithContext = (props: ImageGalleryWithContextProps) =>
         : 1;
   }, []);
 
-  /**
-   * This transition and scaleX reverse lets use scroll right
-   */
+  // Offsets the pager horizontally to the current slide.
   const pagerStyle = useAnimatedStyle<ImageStyle>(
     () => ({
       transform: [
@@ -317,9 +288,7 @@ export const ImageGalleryWithContext = (props: ImageGalleryWithContextProps) =>
     [],
   );
 
-  /**
-   * Simple background color animation on Y movement
-   */
+  // Background that fades as the image is dragged down.
   const containerBackground = useAnimatedStyle<ViewStyle>(
     () => ({
       backgroundColor: backgroundColor || semantics.backgroundCoreApp,
@@ -328,10 +297,7 @@ export const ImageGalleryWithContext = (props: ImageGalleryWithContextProps) =>
     [headerFooterOpacity],
   );
 
-  /**
-   * Show screen style as component is always rendered we hide it
-   * down and up and set opacity to 0 for good measure
-   */
+  // Slides the screen in from below the viewport.
   const showScreenStyle = useAnimatedStyle<ViewStyle>(
     () => ({
       transform: [
@@ -343,16 +309,10 @@ export const ImageGalleryWithContext = (props: ImageGalleryWithContextProps) =>
     [],
   );
 
-  /**
-   * Functions toclose BottomSheetModal with image grid
-   */
   const closeGridView = () => {
     setIsGridViewVisible(false);
   };
 
-  /**
-   * Function to open BottomSheetModal with image grid
-   */
   const openGridView = () => {
     setIsGridViewVisible(true);
   };
@@ -364,11 +324,8 @@ export const ImageGalleryWithContext = (props: ImageGalleryWithContextProps) =>
       const handle = imageGalleryStateStore.requesterNode;
       if (handle == null) return;
       imageGalleryStateStore.requesterNode = null;
-      // Because of the fact that iOS and Android handle supressing
-      // the content underneath differently, we have to wait a frame
-      // before iOS is allowed to attempt to refocus (it takes a frame
-      // for the native a11y tree to become aware that it no longer has
-      // an accessibilityViewIsModal sibling).
+      // iOS must wait a frame before refocusing: the native a11y tree takes a frame to notice that
+      // the `accessibilityViewIsModal` sibling is gone. Android refocuses immediately.
       if (Platform.OS === 'android') {
         AccessibilityInfo.setAccessibilityFocus(handle);
       } else {
@@ -458,7 +415,12 @@ export const ImageGallery = (props: ImageGalleryProps) => {
 };
 
 /**
- * Clamping worklet to clamp the scaling
+ * Clamps a value between two bounds. Runs as a worklet.
+ *
+ * @param value The value to clamp.
+ * @param lowerBound The minimum result.
+ * @param upperBound The maximum result.
+ * @returns The clamped value.
  */
 export const clamp = (value: number, lowerBound: number, upperBound: number) => {
   'worklet';

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

@@ -115,6 +115,32 @@ describe('ImageGallery', () => {
     });
   });
 
+  it('renders a labelled placeholder for a video outside the playback window', async () => {
+    render(
+      <ImageGalleryComponent
+        message={generateMessage({
+          // Index 2 is inside the pager window but outside the video window (`shouldRender < 2`).
+          attachments: [
+            generateImageAttachment(),
+            generateImageAttachment(),
+            generateVideoAttachment({ type: 'video' }),
+          ],
+        })}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(
+        screen.queryAllByLabelText('Image Gallery Video Placeholder', {
+          includeHiddenElements: true,
+        }),
+      ).toHaveLength(1);
+    });
+    expect(
+      screen.queryAllByLabelText('Image Gallery Video', { includeHiddenElements: true }),
+    ).toHaveLength(0);
+  });
+
   it('keeps the pager in ltr coordinates when rtl is enabled', async () => {
     setRTL(true);
 

package/src/components/ImageGallery/__tests__/ImageGalleryFooter.test.tsx

@@ -176,7 +176,7 @@ describe('ImageGalleryFooter', () => {
     const shareImageMock = jest.spyOn(NativeHandlers, 'shareImage');
     const deleteFileMock = jest.spyOn(NativeHandlers, 'deleteFile');
 
-    const attachment = { ...generateImageAttachment(), mime_type: 'image/png' };
+    const attachment = { ...generateImageAttachment(), custom: { mime_type: 'image/png' } };
 
     render(<ImageGalleryComponentImage attachment={attachment} />);
 
@@ -206,8 +206,8 @@ describe('ImageGalleryFooter', () => {
 
     const attachment = {
       ...generateImageAttachment(),
+      custom: { mime_type: 'image/png' },
       image_url: 'https://my-image-service/image/123456',
-      mime_type: 'image/png',
     };
 
     render(<ImageGalleryComponentImage attachment={attachment} />);

package/src/components/ImageGallery/components/AnimatedGalleryImage.tsx

@@ -75,23 +75,17 @@ export const AnimatedGalleryImage = React.memo(
       translateY,
     });
 
-    /**
-     * An empty view is rendered for images not close to the currently
-     * selected in order to maintain spacing while reducing the image
-     * load on memory.
-     */
+    // Slides far from the current one render an empty view that keeps the spacing and holds no
+    // image.
     if (!shouldRender) {
       return <View style={[style, { transform: [{ scale: oneEighth }] }]} />;
     }
 
     if (isSvg) {
-      // The outer Animated.View is sized at 8× screen so raster images stay
-      // crisp under pinch zoom (see useAnimatedGalleryStyle). rn-svg on
-      // Android rasterizes the SVG to a bitmap at its layout size and an
-      // 8x screen bitmap exceeds RecordingCanvas's per draw byte limit. The
-      // inner SvgAwareImage is sized at 1x screen with a counter scale of 8 so
-      // the bitmap stays small while the composed visible scale (1/8 × 8 === 1)
-      // is unchanged.
+      // The outer view is 8x screen so raster images stay crisp under pinch zoom (see
+      // `useAnimatedGalleryStyle`). On Android, rn-svg rasterizes at layout size and an 8x screen
+      // bitmap exceeds RecordingCanvas's per-draw byte limit, so the inner `SvgAwareImage` is 1x
+      // screen with a counter scale of 8, which leaves the visible scale unchanged.
       return (
         <Animated.View
           accessibilityLabel={accessibilityLabel}

package/src/components/ImageGallery/components/AnimatedGalleryVideo.tsx

@@ -125,27 +125,22 @@ const AnimatedGalleryVideoComponent = (props: AnimatedGalleryVideoType) => {
 
   const onPlayBackStatusUpdate = (playbackStatus: PlaybackStatus) => {
     if (!playbackStatus.isLoaded) {
-      // Update your UI for the unloaded state
       setOpacity(1);
       if (playbackStatus.error) {
         console.error(`Encountered a fatal error during playback: ${playbackStatus.error}`);
       }
     } else {
-      // Update your UI for the loaded state
       setOpacity(0);
       videoPlayer.duration = playbackStatus.durationMillis;
       if (playbackStatus.isPlaying) {
-        // Update your UI for the playing state
         videoPlayer.progress = playbackStatus.positionMillis / playbackStatus.durationMillis;
       }
 
       if (playbackStatus.isBuffering) {
-        // Update your UI for the buffering state
         setOpacity(1);
       }
 
       if (playbackStatus.didJustFinish && !playbackStatus.isLooping) {
-        // The player has just finished playing and will stop. Maybe you want to play something else?
         videoPlayer.stop();
       }
     }
@@ -161,15 +156,11 @@ const AnimatedGalleryVideoComponent = (props: AnimatedGalleryVideoType) => {
     translateY,
   });
 
-  /**
-   * An empty view is rendered for images not close to the currently
-   * selected in order to maintain spacing while reducing the image
-   * load on memory.
-   */
+  // Slides far from the current one render an empty view that keeps the spacing and holds no video.
   if (!shouldRender) {
     return (
       <View
-        accessibilityLabel='Empty View Image Gallery'
+        accessibilityLabel='Image Gallery Video Placeholder'
         style={[style, { transform: [{ scale: oneEighth }] }]}
       />
     );

package/src/components/ImageGallery/components/ImageGalleryA11yProbe.tsx

@@ -17,15 +17,12 @@ type Props = {
 };
 
 /**
- * Accessibility-enabled variant of the gallery's background fade view. Wires
- * the "X of N" announcement and the VoiceOver/TalkBack increment/decrement
- * actions. Subscribes locally to currentIndex + assets so the parent
- * ImageGallery doesn't need that subscription itself — only this small sibling
- * re-renders to refresh the accessibilityValue text on each swipe.
+ * Accessible variant of the gallery's background view. It announces "X of N" and handles the
+ * VoiceOver/TalkBack increment and decrement actions. It subscribes to `currentIndex` and `assets`
+ * itself, so a swipe re-renders only this view and not `ImageGallery`.
  *
- * Caller is responsible for gating this on whether accessibility is enabled.
- * When disabled, the parent renders a plain Animated.View with the same
- * background style and no a11y attributes.
+ * The caller renders it only when accessibility is enabled; otherwise the parent renders a plain
+ * `Animated.View` with the same background style.
  */
 export const ImageGalleryA11yProbe = ({ containerBackground }: Props) => {
   const { imageGalleryStateStore } = useImageGalleryContext();
@@ -37,7 +34,7 @@ export const ImageGalleryA11yProbe = ({ containerBackground }: Props) => {
     [currentIndex, assetsCount],
   );
   const accessibilityValueText = useA11yLabel(
-    'a11y/{{position}} of {{count}}',
+    'imageGallery.position.accessibilityLabel',
     accessibilityValueParams,
   );
   const accessibilityValue = useMemo(

package/src/components/ImageGallery/components/ImageGalleryFooter.tsx

@@ -17,17 +17,15 @@ import { FileTypes } from '../../../types/types';
 import { Button } from '../../ui/Button/Button';
 import { SafeAreaView } from '../../UIComponents/SafeAreaViewWrapper';
 
-// Never called - it exists only so `ReturnType` below can name the animated component's type.
-// Spelling it as `ReturnType<typeof Animated.createAnimatedComponent<typeof SafeAreaView>>`
-// directly resolves against the wrong overload (the `FlatList` one).
+// Never called: it only lets `ReturnType` below name the animated component's type, because
+// spelling out `Animated.createAnimatedComponent<typeof SafeAreaView>` picks the wrong overload.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- used in type position only
 const createAnimatedSafeAreaViewType = () => Animated.createAnimatedComponent(SafeAreaView);
 
 /**
  * `createAnimatedComponent` is guarded because a stripped-down Reanimated mock may not provide it.
- * The result is asserted back to the animated component type on purpose: written as a bare ternary
- * this types as the *union* of the animated and the plain component, so its `style` prop becomes
- * their intersection - which from React Native 0.87 no longer accepts an animated style.
+ * The cast keeps the animated component type: a bare ternary types as the union with the plain
+ * component, whose `style` prop then rejects animated styles (React Native 0.87 and later).
  */
 const ReanimatedSafeAreaView = (
   Animated.createAnimatedComponent ? Animated.createAnimatedComponent(SafeAreaView) : SafeAreaView
@@ -88,8 +86,7 @@ export const ImageGalleryFooterWithContext = (props: ImageGalleryFooterProps) =>
       const extension = asset.mime_type?.split('/')[1] || 'jpg';
       const shouldDownload = asset.uri && asset.uri.includes('http');
       let localFile;
-      // If the file is already uploaded to a CDN, create a local reference to
-      // it first; otherwise just use the local file
+      // Remote files are saved locally first; local files are shared as they are.
       if (shouldDownload) {
         setSavingInProgress(true);
         localFile = await NativeHandlers.saveFile({
@@ -103,9 +100,9 @@ export const ImageGalleryFooterWithContext = (props: ImageGalleryFooterProps) =>
         localFile = asset.uri;
       }
 
-      // `image/jpeg` is added for the case where the mime_type isn't available for a file/image
+      // Falls back to `image/jpeg` when the asset has no `mime_type`.
       await NativeHandlers.shareImage({ type: asset.mime_type || 'image/jpeg', url: localFile });
-      // Only delete the file if a local reference has been created beforehand
+      // Only the downloaded copy is deleted.
       if (shouldDownload) {
         await NativeHandlers.deleteFile({ uri: localFile });
       }
@@ -140,14 +137,14 @@ export const ImageGalleryFooterWithContext = (props: ImageGalleryFooterProps) =>
           <ShareButton savingInProgress={savingInProgress} share={share} />
           <View style={styles.centerContainer} accessibilityLabel='Center element'>
             <Text style={styles.imageCountText}>
-              {t('{{ index }} of {{ photoLength }}', {
+              {t('imageGallery.footer.position.text', '{{ index }} of {{ photoLength }}', {
                 index: currentIndex + 1,
                 photoLength: imageGalleryStateStore.assets.length,
               })}
             </Text>
           </View>
           <Button
-            accessibilityLabelKey='a11y/Grid Icon'
+            accessibilityLabelKey='imageGallery.footer.grid.accessibilityLabel'
             variant='secondary'
             type='ghost'
             size='md'
@@ -169,7 +166,7 @@ type ShareButtonProps = {
 const ShareButton = ({ share, savingInProgress }: ShareButtonProps) => {
   const styles = useStyles();
   const { icons } = useComponentsContext();
-  // If the shareImage, saveFile or deleteFile is null, we don't want to render the share button
+  // Hidden when the native share or file system handlers are not registered.
   if (!isShareImageAvailable() || !isFileSystemAvailable()) {
     return null;
   }
@@ -180,7 +177,7 @@ const ShareButton = ({ share, savingInProgress }: ShareButtonProps) => {
     </View>
   ) : (
     <Button
-      accessibilityLabelKey='a11y/Share Button'
+      accessibilityLabelKey='imageGallery.footer.share.accessibilityLabel'
       variant='secondary'
       type='ghost'
       size='md'

package/src/components/ImageGallery/components/ImageGalleryHeader.tsx

@@ -14,21 +14,20 @@ import { useTheme } from '../../../contexts/themeContext/ThemeContext';
 import { useTranslationContext } from '../../../contexts/translationContext/TranslationContext';
 import { useStateStore } from '../../../hooks/useStateStore';
 
+import { getDateString } from '../../../i18n/utils';
 import { ImageGalleryState } from '../../../state-store/image-gallery-state-store';
 import { primitives } from '../../../theme';
-import { getDateString } from '../../../utils/i18n/getDateString';
 import { Button } from '../../ui/Button/Button';
 import { SafeAreaView } from '../../UIComponents/SafeAreaViewWrapper';
 
-// Never called - it exists only so `ReturnType` below can name the animated component's type.
+// Never called: it only lets `ReturnType` below name the animated component's type.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- used in type position only
 const createAnimatedSafeAreaViewType = () => Animated.createAnimatedComponent(SafeAreaView);
 
 /**
- * A frame-aware wrapper, matching `ImageGalleryFooter`. `SafeAreaView` compares the window inset
- * against its own measured frame, so a nested instance contributes nothing once an ancestor has
- * already narrowed the subtree - unlike `useSafeAreaInsets`, which is window-global and would
- * double-pad this header inside `ChannelDetailsModal`, which insets its own root.
+ * Animated `SafeAreaView`, as in `ImageGalleryFooter`. It compares the window inset against its own
+ * frame, so a nested instance adds no padding when an ancestor has already inset the subtree.
+ * `useSafeAreaInsets` is window-global and would double-pad inside `ChannelDetailsModal`.
  *
  * `createAnimatedComponent` is guarded because a stripped-down Reanimated mock may not provide it.
  */
@@ -54,10 +53,10 @@ export const ImageGalleryHeader = (props: ImageGalleryHeaderProps) => {
   const date = useMemo(
     () =>
       getDateString({
-        date: asset?.created_at,
+        messageCreatedAt: asset?.created_at,
         t,
         tDateTimeParser,
-        timestampTranslationKey: 'timestamp/ImageGalleryHeader',
+        timestampTranslationKey: 'timestamp.ImageGalleryHeader',
       }),
     [asset?.created_at, t, tDateTimeParser],
   );
@@ -93,7 +92,7 @@ export const ImageGalleryHeader = (props: ImageGalleryHeaderProps) => {
         <View style={styles.innerContainer}>
           <View style={styles.leftContainer}>
             <Button
-              accessibilityLabelKey='a11y/Hide Overlay'
+              accessibilityLabelKey='imageGallery.header.hideOverlay.accessibilityLabel'
               variant='secondary'
               type='ghost'
               size='md'
@@ -104,7 +103,9 @@ export const ImageGalleryHeader = (props: ImageGalleryHeaderProps) => {
           </View>
           <View style={styles.centerContainer} accessibilityLabel='Center element'>
             <Text style={styles.userName}>
-              {asset?.user?.name || asset?.user?.id || t('Unknown User')}
+              {asset?.user?.name ||
+                asset?.user?.id ||
+                t('common.unknownUser.label', 'Unknown User')}
             </Text>
             {date ? <Text style={styles.date}>{date}</Text> : null}
           </View>

package/src/components/ImageGallery/components/ImageGalleryVideoControl.tsx

@@ -38,9 +38,9 @@ export const ImageGalleryVideoControl = React.memo((props: ImageGalleryVideoCont
 
   const videoDuration = getDurationLabelFromDuration(duration);
 
-  const progressValueInSeconds = progress * duration;
+  const progressValueInMilliseconds = progress * duration;
 
-  const progressDuration = getDurationLabelFromDuration(progressValueInSeconds);
+  const progressDuration = getDurationLabelFromDuration(progressValueInMilliseconds);
 
   const { icons } = useComponentsContext();
   const {
@@ -71,12 +71,10 @@ export const ImageGalleryVideoControl = React.memo((props: ImageGalleryVideoCont
     await videoPlayer.changePlaybackRate();
   };
 
-  // Remember whether playback was ongoing so it can be resumed once the user
-  // finishes scrubbing.
+  // Whether playback was ongoing, so it resumes when scrubbing ends.
   const wasPlayingBeforeSeek = useRef(false);
 
-  // Pause while scrubbing so the incoming progress updates don't fight the
-  // user's finger on the seek bar.
+  // Pauses while scrubbing so progress updates do not fight the seek bar.
   const handleStartDrag = useStableCallback(() => {
     wasPlayingBeforeSeek.current = videoPlayer.isPlaying;
     videoPlayer.pause();
@@ -93,7 +91,7 @@ export const ImageGalleryVideoControl = React.memo((props: ImageGalleryVideoCont
     <View style={[styles.container, container]}>
       <View style={styles.leftContainer}>
         <Button
-          accessibilityLabelKey='a11y/Play Pause Button'
+          accessibilityLabelKey='imageGallery.videoControl.playPause.accessibilityLabel'
           variant='secondary'
           type='ghost'
           size='md'
@@ -117,7 +115,6 @@ export const ImageGalleryVideoControl = React.memo((props: ImageGalleryVideoCont
           onStartDrag={handleStartDrag}
           progress={progress}
           testID={'progress-control'}
-          width={180}
         />
       </View>
 

package/src/components/ImageGallery/components/__tests__/ImageGalleryVideoControl.test.tsx

@@ -104,4 +104,13 @@ describe('ImageGalleryVideoControl', () => {
     expect(seekSpy).toHaveBeenCalledWith(0.5 * DURATION);
     expect(playSpy).not.toHaveBeenCalled();
   });
+
+  it('labels the progress from the duration in milliseconds', () => {
+    const { videoPlayer } = setup();
+    act(() => {
+      videoPlayer.progress = 0.5;
+    });
+
+    expect(screen.getByText('0:05')).toBeTruthy();
+  });
 });

package/src/components/ImageGallery/hooks/useAnimatedGalleryStyle.tsx

@@ -16,9 +16,9 @@ type Props = {
 const oneEighth = 1 / 8;
 
 /**
- * Named via `ReturnType` because Reanimated does not export `AnimatedStyleHandle` from its root.
- * Without an explicit annotation the inferred return type inlines React Native's internal style
- * helper types, which cannot be written into the emitted declarations (TS2883).
+ * Named via `ReturnType` because Reanimated does not export `AnimatedStyleHandle` from its root. An
+ * inferred return type would inline React Native's internal style types, which cannot be written
+ * into the emitted declarations (TS2883).
  */
 type GalleryAnimatedStyle = ReturnType<typeof useAnimatedStyle<ImageStyle>>;
 
@@ -36,14 +36,9 @@ export const useAnimatedGalleryStyle = ({
   const screenWidth = vw(100);
   const halfScreenWidth = vw(50);
 
-  /**
-   * The current image, designated by selected is scaled and translated
-   * based on the gestures. The rendered images before and after the
-   * currently selected image also translated in X if the scale is
-   * greater than one so they keep the same distance from the selected
-   * image as it is scaled. If the scale is less than one they stay in
-   * place as to not come into the screen when the image shrinks.
-   */
+  // The selected image is scaled and translated by the gestures. Its neighbors shift in X when the
+  // scale is above 1 to keep their distance from it, and stay in place below 1 so they do not
+  // enter the screen as the image shrinks.
   const animatedGalleryStyle = useAnimatedStyle<ImageStyle>(() => {
     const selected = currentIndexShared.value === index;
     const previous = currentIndexShared.value > index;

package/src/components/ImageGallery/hooks/useCurrentImageHeight.ts

@@ -9,19 +9,14 @@ import type {
 import { FileTypes } from '../../../types/types';
 
 /**
- * Owns a SharedValue tracking the visible height of the currently selected
- * gallery asset and keeps it in lockstep with the gallery store's
- * currentIndex. Worklet consumers read `.value` on the UI thread.
+ * A SharedValue with the visible height of the currently selected asset, kept in sync with the
+ * gallery store's `currentIndex`. Worklets read `.value` on the UI thread.
  *
- * The store is subscribed via `subscribeWithSelector` (not `useStateStore`),
- * so currentIndex changes never go through React state so no rerender is
- * triggered in the calling component. The callback writes directly into the
- * SharedValue.
+ * The store is subscribed with `subscribeWithSelector`, not `useStateStore`, so an index change
+ * writes the SharedValue without re-rendering the caller.
  *
- * Sync path uses the attachment's intrinsic `original_height`/`original_width`
- * when present. Async fallback via `Image.getSize` handles assets that don't
- * carry dimensions; a token guards against the closure-race where the user
- * swipes past a slide before its dimensions resolve.
+ * The height comes from `original_height` and `original_width` when present, otherwise from
+ * `Image.getSize`, whose result is discarded when the user has already swiped to another slide.
  */
 export const useCurrentImageHeight = ({
   assets,
@@ -53,7 +48,7 @@ export const useCurrentImageHeight = ({
         Image.getSize(
           photo.uri,
           (width, height) => {
-            // Stale result, currentIndex moved on before getSize resolved.
+            // Stale result: `currentIndex` moved on before `getSize` resolved.
             if (currentToken !== latestToken) return;
             if (!width || !height) {
               currentImageHeight.value = fullWindowHeight;