(feat): Improve the image viewer

Changelog: enhancement

Author: markharding

apps/polycentric/app/image-viewer.tsx

@@ -1 +1 @@
-export { default } from '@/src/features/post/ImageViewer/ImageViewerScreen';
+export { default } from '@/src/common/components/ImageViewer/ImageViewerScreen';

…eatures/post/ImageViewer/ImageViewer.tsx …n/components/ImageViewer/ImageViewer.tsxapps/polycentric/src/features/post/ImageViewer/ImageViewer.tsx renamed to apps/polycentric/src/common/components/ImageViewer/ImageViewer.tsx apps/polycentric/src/features/post/ImageViewer/ImageViewer.tsx renamed to apps/polycentric/src/common/components/ImageViewer/ImageViewer.tsx

@@ -1,12 +1,10 @@
 import { Text } from '@/src/common/components/primitives';
-import {
-  pickImageVariant,
-  usePolycentric,
-} from '@/src/common/lib/polycentric-hooks';
+import { usePolycentric } from '@/src/common/lib/polycentric-hooks';
 import { Atoms, useTheme, withHexOpacity } from '@/src/common/theme';
 import Icon from '@/src/common/components/Icon';
-import { v2 } from '@polycentric/react-native';
 import { useCallback, useEffect, useMemo, useState } from 'react';
+import { resolveImageSources } from './resolveImageSources';
+import { ImageViewerInput } from './useImageViewerStore';
 import {
   Image,
   Platform,
@@ -39,16 +37,9 @@ const MAX_SCALE = 5;
 /** Releasing a pinch below this scale dismisses the viewer. */
 const PINCH_CLOSE_SCALE = 0.8;
 
-/** Pull the largest available variant for the viewer. */
-const VIEWER_TARGET = 2048;
-
-type ViewerSource = {
-  uri: string;
-  aspectRatio: number;
-};
-
 /**
- * Full-screen image viewer for post attachments. Tap the backdrop or
+ * Full-screen viewer for any `ImageSet`s (post attachments, avatars,
+ * ...). Tap the backdrop or
  * the close button to dismiss; pinch in or swipe up/down to close;
  * left/right arrows (and keyboard arrows on web) navigate between images
  * when there's more than one.
@@ -58,28 +49,16 @@ export function ImageViewer({
   initialIndex,
   onClose,
 }: {
-  images: v2.ImageSet[];
+  images: ImageViewerInput[];
   initialIndex: number;
   onClose: () => void;
 }) {
   const client = usePolycentric();
   const { theme } = useTheme();
   const insets = useSafeAreaInsets();
 
-  const sources = useMemo<ViewerSource[]>(
-    () =>
-      images
-        .map((imageSet) => {
-          const variant = pickImageVariant(imageSet, VIEWER_TARGET);
-          const digest = variant?.blob?.digest;
-          if (!digest) return null;
-          const uri = client.blobUrl(digest);
-          if (!uri) return null;
-          const w = variant.width || 1;
-          const h = variant.height || 1;
-          return { uri, aspectRatio: w / h };
-        })
-        .filter((s): s is ViewerSource => s != null),
+  const sources = useMemo(
+    () => resolveImageSources(images, (digest) => client.blobUrl(digest)),
     [client, images],
   );
 
@@ -286,7 +265,7 @@ export function ImageViewer({
               onPress={(e) => e.stopPropagation?.()}
               style={[
                 Atoms.w_full,
-                { aspectRatio: current.aspectRatio, maxHeight: '100%' },
+                { aspectRatio: current.aspectRatio ?? 1, maxHeight: '100%' },
               ]}
             >
               <Image

…s/post/ImageViewer/ImageViewerScreen.tsx …onents/ImageViewer/ImageViewerScreen.tsxapps/polycentric/src/features/post/ImageViewer/ImageViewerScreen.tsx renamed to apps/polycentric/src/common/components/ImageViewer/ImageViewerScreen.tsx apps/polycentric/src/features/post/ImageViewer/ImageViewerScreen.tsx renamed to apps/polycentric/src/common/components/ImageViewer/ImageViewerScreen.tsx

@@ -0,0 +1,9 @@
+export { ImageViewer } from './ImageViewer';
+export { default as ImageViewerScreen } from './ImageViewerScreen';
+export { resolveImageSources } from './resolveImageSources';
+export { useImageViewer } from './useImageViewer';
+export { useImageViewerStore } from './useImageViewerStore';
+export type {
+  ImageViewerInput,
+  ImageViewerSource,
+} from './useImageViewerStore';

apps/polycentric/src/common/components/ImageViewer/index.ts

@@ -0,0 +1,91 @@
+import { resolveImageSources, VIEWER_TARGET } from './resolveImageSources';
+import type { ImageViewerInput } from './useImageViewerStore';
+
+// `v2` is only used as types here and in the helpers; a stub keeps the
+// real (native-backed) package out of the test.
+jest.mock('@polycentric/react-native', () => ({ v2: {} }));
+
+type BlobUrl = Parameters<typeof resolveImageSources>[1];
+
+// Fake ImageSet variants use string digests so blobUrl results are easy
+// to assert against.
+const variant = (width: number, height: number, digest?: string) => ({
+  width,
+  height,
+  ...(digest ? { blob: { digest } } : {}),
+});
+
+const imageSet = (
+  ...variants: ReturnType<typeof variant>[]
+): ImageViewerInput => ({ images: variants }) as unknown as ImageViewerInput;
+
+const blobUrl: BlobUrl = (digest) => `blob://${digest}`;
+
+describe('resolveImageSources', () => {
+  it('passes plain-uri sources through unchanged', () => {
+    const plain = { uri: 'https://example.com/identicon.png' };
+    expect(resolveImageSources([plain], blobUrl)).toEqual([plain]);
+  });
+
+  it('keeps an explicit aspect ratio on plain sources', () => {
+    const plain = { uri: 'https://example.com/banner.png', aspectRatio: 3 };
+    expect(resolveImageSources([plain], blobUrl)).toEqual([plain]);
+  });
+
+  it('resolves an ImageSet to the smallest variant at or above the target', () => {
+    const set = imageSet(
+      variant(512, 256, 'small'),
+      variant(VIEWER_TARGET, 1024, 'fit'),
+      variant(4096, 2048, 'huge'),
+    );
+    expect(resolveImageSources([set], blobUrl)).toEqual([
+      { uri: 'blob://fit', aspectRatio: 2 },
+    ]);
+  });
+
+  it('falls back to the largest variant when none reach the target', () => {
+    const set = imageSet(variant(512, 512, 'small'), variant(1024, 512, 'big'));
+    expect(resolveImageSources([set], blobUrl)).toEqual([
+      { uri: 'blob://big', aspectRatio: 2 },
+    ]);
+  });
+
+  it('defaults zero dimensions instead of dividing by zero', () => {
+    const set = imageSet(variant(0, 0, 'broken'));
+    expect(resolveImageSources([set], blobUrl)).toEqual([
+      { uri: 'blob://broken', aspectRatio: 1 },
+    ]);
+  });
+
+  it('drops a set whose chosen variant has no digest', () => {
+    expect(
+      resolveImageSources([imageSet(variant(2048, 1024))], blobUrl),
+    ).toEqual([]);
+  });
+
+  it('drops a set when the blob CDN is not known yet', () => {
+    const set = imageSet(variant(2048, 1024, 'x'));
+    expect(resolveImageSources([set], () => null)).toEqual([]);
+  });
+
+  it('drops empty image sets', () => {
+    expect(resolveImageSources([imageSet()], blobUrl)).toEqual([]);
+  });
+
+  it('preserves order across mixed inputs and skips unresolvable ones', () => {
+    const sources = resolveImageSources(
+      [
+        { uri: 'plain://first' },
+        imageSet(variant(2048, 2048, 'second')),
+        imageSet(), // unresolvable
+        { uri: 'plain://third', aspectRatio: 0.5 },
+      ],
+      blobUrl,
+    );
+    expect(sources.map((s) => s.uri)).toEqual([
+      'plain://first',
+      'blob://second',
+      'plain://third',
+    ]);
+  });
+});

apps/polycentric/src/common/components/ImageViewer/resolveImageSources.test.ts

@@ -0,0 +1,32 @@
+import { pickImageVariant } from '@/src/common/lib/polycentric-hooks/helpers';
+import { v2 } from '@polycentric/react-native';
+import { ImageViewerInput, ImageViewerSource } from './useImageViewerStore';
+
+/** Pull the largest available variant for the viewer. */
+export const VIEWER_TARGET = 2048;
+
+type BlobDigest = NonNullable<NonNullable<v2.Image['blob']>['digest']>;
+
+/**
+ * Resolve the image source from an array of mixed inputs
+ */
+export function resolveImageSources(
+  images: ImageViewerInput[],
+  blobUrl: (digest: BlobDigest) => string | null,
+): ImageViewerSource[] {
+  return images
+    .map((image) => {
+      if ('uri' in image) {
+        return image;
+      }
+      const variant = pickImageVariant(image, VIEWER_TARGET);
+      const digest = variant?.blob?.digest;
+      if (!digest) return null;
+      const uri = blobUrl(digest);
+      if (!uri) return null;
+      const w = variant.width || 1;
+      const h = variant.height || 1;
+      return { uri, aspectRatio: w / h };
+    })
+    .filter((s): s is ImageViewerSource => s != null);
+}

apps/polycentric/src/common/components/ImageViewer/resolveImageSources.ts

@@ -0,0 +1,60 @@
+import * as React from 'react';
+import { act } from 'react';
+import TestRenderer from 'react-test-renderer';
+import { router } from 'expo-router';
+import { useImageViewer } from './useImageViewer';
+import { useImageViewerStore } from './useImageViewerStore';
+
+jest.mock('@polycentric/react-native', () => ({ v2: {} }));
+
+jest.mock('expo-router', () => ({
+  router: { push: jest.fn() },
+}));
+
+/** Render the hook in a throwaway component and hand back its callback. */
+function renderUseImageViewer() {
+  let open!: ReturnType<typeof useImageViewer>;
+  function Harness() {
+    open = useImageViewer();
+    return null;
+  }
+  act(() => {
+    TestRenderer.create(React.createElement(Harness));
+  });
+  return open;
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  useImageViewerStore.setState({ images: [], index: 0 });
+});
+
+describe('useImageViewer', () => {
+  it('stores the images and pushes the image-viewer route', () => {
+    const open = renderUseImageViewer();
+    const images = [{ uri: 'a' }, { uri: 'b' }];
+
+    act(() => open(images, 1));
+
+    expect(useImageViewerStore.getState().images).toBe(images);
+    expect(useImageViewerStore.getState().index).toBe(1);
+    expect(router.push).toHaveBeenCalledWith('/image-viewer');
+  });
+
+  it('defaults the starting index to 0', () => {
+    const open = renderUseImageViewer();
+
+    act(() => open([{ uri: 'a' }]));
+
+    expect(useImageViewerStore.getState().index).toBe(0);
+  });
+
+  it('does nothing for an empty image list', () => {
+    const open = renderUseImageViewer();
+
+    act(() => open([]));
+
+    expect(router.push).not.toHaveBeenCalled();
+    expect(useImageViewerStore.getState().images).toEqual([]);
+  });
+});

apps/polycentric/src/common/components/ImageViewer/useImageViewer.test.ts

@@ -0,0 +1,20 @@
+import { router } from 'expo-router';
+import { useCallback } from 'react';
+import { useImageViewerStore, ImageViewerInput } from './useImageViewerStore';
+
+/**
+ * Opens the full-screen image viewer from anywhere in the app: stashes
+ * the images in {@link useImageViewerStore} and pushes the
+ * `image-viewer` route that reads them back out.
+ */
+export function useImageViewer() {
+  const show = useImageViewerStore((s) => s.show);
+  return useCallback(
+    (images: ImageViewerInput[], index = 0) => {
+      if (images.length === 0) return;
+      show(images, index);
+      router.push('/image-viewer');
+    },
+    [show],
+  );
+}

apps/polycentric/src/common/components/ImageViewer/useImageViewer.ts

@@ -0,0 +1,31 @@
+import { useImageViewerStore } from './useImageViewerStore';
+
+jest.mock('@polycentric/react-native', () => ({ v2: {} }));
+
+// Plain zustand store: drive it via getState()/setState() without React.
+const get = () => useImageViewerStore.getState();
+
+beforeEach(() => {
+  useImageViewerStore.setState({ images: [], index: 0 });
+});
+
+describe('useImageViewerStore', () => {
+  it('starts empty at index 0', () => {
+    expect(get().images).toEqual([]);
+    expect(get().index).toBe(0);
+  });
+
+  it('show() sets the images and starting index', () => {
+    const images = [{ uri: 'a' }, { uri: 'b' }];
+    get().show(images, 1);
+    expect(get().images).toBe(images);
+    expect(get().index).toBe(1);
+  });
+
+  it('show() replaces a previous set entirely', () => {
+    get().show([{ uri: 'a' }, { uri: 'b' }], 1);
+    get().show([{ uri: 'c' }], 0);
+    expect(get().images).toEqual([{ uri: 'c' }]);
+    expect(get().index).toBe(0);
+  });
+});

apps/polycentric/src/common/components/ImageViewer/useImageViewerStore.test.ts

@@ -0,0 +1,29 @@
+import { v2 } from '@polycentric/react-native';
+import { create } from 'zustand';
+
+/** A directly renderable image; aspectRatio defaults to square. */
+export type ImageViewerSource = { uri: string; aspectRatio?: number };
+
+/**
+ * Anything the viewer can display: a Polycentric `ImageSet` (resolved
+ * to the largest blob variant) or a plain URI (e.g. an identicon).
+ */
+export type ImageViewerInput = v2.ImageSet | ImageViewerSource;
+
+type ImageViewerState = {
+  images: ImageViewerInput[];
+  index: number;
+};
+
+type ImageViewerActions = {
+  /** Set the images + starting index for the image-viewer route to read. */
+  show: (images: ImageViewerInput[], index: number) => void;
+};
+
+export const useImageViewerStore = create<
+  ImageViewerState & ImageViewerActions
+>((set) => ({
+  images: [],
+  index: 0,
+  show: (images, index) => set({ images, index }),
+}));