isom-1898 image gallery slideshow #1298

adriangohjw · 2025-05-07T23:30:55Z

Problem

Closes https://linear.app/ogp/issue/ISOM-1898/image-gallery-slideshow

Solution

Breaking Changes

Yes - this PR contains breaking changes
- Details ...
No - this PR is backwards compatible

Features:

new image galley component
~~skipped the image preload optimization part - i feel like its not an issue at this point so decided to not overengineer~~ update: decided to still add it otherwise navigation can feel sluggish, and not somethign im proud of. And since we rarely update components after shipping it, I rather do it well now (isom-1898 image gallery slideshow #1298 (comment))

FYI @sehyunidaaa - lemme know otherwise

set number of images between 2 and 30.
there's only design for 3 or 5 preview images in Figma. I have standardized to use the height for 3 images if there's 1-3 preview images, and the height for 5 images if there's 4-5 preview images.
- Note: 1 preview image only happens in case someone saved an invalid schema directly via DB or from github->studio migration. it should NOT be possible on studio, but adding it to storybook nevertheless
i have skip the image preview in studio for now
side-note: im feeling half-half about transition animation after implementing it - it feels a bit more sluggish, but maybe we just have to lower the transition? just pointing out - leave it up to you to make the final call

Before & After Screenshots

Without transition

Screen.Recording.2025-05-08.at.7.25.36.AM.mov

With transition

Screen.Recording.2025-05-08.at.7.59.29.AM.mov

Tests

Go to Studio to create a new Image Gallery block in a Content page, and add more than 5 images

navigate with the left/right button -> it should navigate correctly
go to the first image and click left button -> you should be at the last image
go to the last image and click right button -> you should be at the first image
click any image directly via preview below -> it should navigate correctly
at any point of time, the image shown should be in the center of the preview, unless it's the first 2 images or last 2 images

…holder images and descriptions

…d placeholder images

…ality; add constants for arrow SVGs and maximum preview images

…ty; simplify preview logic and enhance readability. Add unit tests for getPreviewIndices functionality.

… styles for improved accessibility and visual consistency.

…r effects and disable state for active images.

… enhancing accessibility and SEO.

…eryClient for improved modularity and maintainability. Introduce ImageGalleryClientProps type for better prop management.

…on and button state, improving clarity and consistency in index handling.

…layout consistency in the preview section.

…nd styles for image previews, improve button focus states, and refactor preview index handling for better clarity and maintainability.

… sets with captions for enhanced visual representation and testing.

…ved layout and visual separation in the image gallery.

linear · 2025-05-07T23:30:58Z

ISOM-1898 Image gallery (slideshow)

datadog-opengovsg · 2025-05-07T23:36:08Z

Datadog Report

Branch report: adriangohjw/isom-1898-image-gallery-slideshow
Commit report: 2d4996f
Test service: isomer-studio

✅ 0 Failed, 566 Passed, 46 Skipped, 1m 35.05s Total Time
⬆️ Test Sessions change in coverage: 1 increased (+0.12%)

seaerchin · 2025-05-08T05:16:24Z

packages/components/src/interfaces/complex/ImageGallery.ts

+const SingleImageSchema = Type.Object({
+  src: ImageSrcSchema,
+  alt: AltTextSchema,
+  caption: Type.Optional(Type.String({ maxLength: 100 })),
+})


[comment, no actionable] i wonder if we should consolidate this together iwth our existing image schema to avoid an explosion of similar yet subtly different schemas

thought about it - felt a bit hard since it's aldy not standardized at this moment, from schema shape to name of fields e.g. src, imageSrc

packages/components/src/interfaces/complex/ImageGallery.ts

packages/components/src/templates/next/components/complex/ImageGallery/constants.tsx

packages/components/src/templates/next/components/complex/ImageGallery/ImageGalleryClient.tsx

packages/components/src/templates/next/components/complex/ImageGallery/index.ts

packages/components/src/templates/next/components/complex/ImageGallery/ImageGalleryClient.tsx

seaerchin · 2025-05-15T05:01:48Z

packages/components/src/templates/next/components/complex/ImageGallery/ImageGalleryClient.tsx

+      if (image.getAttribute("loading") === "lazy") {
+        image.removeAttribute("loading")
+        const src = image.src
+        image.src = ""
+        image.src = src
+      }


[comment] not sure if it's possible to do, but the lazy load appears to be a function of the current index and the maxPreviewImages - should be just pass in the logic here to the lazyLoad prop on ImageClient? feels abit clearer and saves us the trouble of dom manipulation

not sure if i understand correctly. maxPreviewImages is determined by the breakpoints and not a config, and we will only know when the component is rendering

To double check my understanding; my proposal was to do something like

<ImageClient shouldLazyLoad = {shouldLazyLoad(numberOfImages, currentIndex, maxPreviewImages)} />

because this is client component (use client directive at top), it seems like we'll already have access to the client sided APIs. this seems like a cleaner way (+ clearer) rather than having to do DOM manipulation

Ah, these are two unrelated sections.

The shouldLazyLoad logic in ImageClient controls whether an image should be lazy/eager-loaded during the initial render.

In contrast, the DOM manipulation above is explicitly forcing an eager load. This change (from lazy to eager) is necessary to ensure the image loads immediately. We do that through preloadImage, which is triggered by user interactions like hovering over buttons or preview images.

seaerchin · 2025-05-15T05:07:13Z

...ges/components/src/templates/next/components/complex/ImageGallery/utils/getPreviewIndices.ts

+    return Array.from({ length: numberOfImages }, (_, i) => i)
+  }
+
+  const numberOfImagesBeforeCurrent = Math.floor(maxPreviewImages / 2)


not sure i understand this line here. if i have an image array [0, 1, 2, 3, 4], and i'm at position 4, the number of images before current should be 4 isn't it? similarly if i'm at position 1, it's should be 0.

not sure i understand why it's maxPreviewImages / 2 rather than just the pos

ah this do some computes

What it does:

Creates a "sliding window" of image previews (e.g., 3 or 5 images).

How it works:

If we have fewer images than the window size, it shows all of them.

Otherwise (we have more images than the window size), it tries to center the currentIndex within this window

It smartly adjusts the window to ensure it doesn't go off the edges (e.g., showing negative indices or indices beyond the last image). So, if currentIndex is near the start or end, the window shifts to stay within bounds.

To your question:

You've got a good point - the name numberOfImagesBeforeCurrent is a bit confusing.

This line const numberOfImagesBeforeCurrent = Math.floor(maxPreviewImages / 2) isn't counting the actual images before currentIndex in the whole array. Instead, it's figuring out how many images should appear before the currentIndex within the small, visible preview window to keep the currentIndex roughly centered.

If maxPreviewImages is 5, it tries to put 2 images before the current one in the preview.

If maxPreviewImages is 3, it tries to put 1 image before the current one in the preview.

The rest of the function then uses this to position that "preview window" correctly within the full list of images, making sure it doesn't go out of bounds.

…image-gallery-slideshow

seaerchin

To make sure i'm understanding the behaviour of the pr correctly:

we have 2 forms of images

the big one shown when the user clicks in
the preview we see down below

the big one is eagerly preloaded when user is +/- 1 or 2 positions away (depending on the window size)

all the images in the preview we see down below is loaded when the user hovers over the preview (and we load in window size)?

seaerchin · 2025-05-16T03:42:27Z

packages/components/src/templates/next/components/complex/ImageGallery/ImageGalleryClient.tsx

+      if (image.getAttribute("loading") === "lazy") {
+        image.removeAttribute("loading")
+        const src = image.src
+        image.src = ""
+        image.src = src
+      }


To double check my understanding; my proposal was to do something like

<ImageClient shouldLazyLoad = {shouldLazyLoad(numberOfImages, currentIndex, maxPreviewImages)} />

because this is client component (use client directive at top), it seems like we'll already have access to the client sided APIs. this seems like a cleaner way (+ clearer) rather than having to do DOM manipulation

packages/components/src/templates/next/components/complex/ImageGallery/ImageGalleryClient.tsx

seaerchin · 2025-05-16T03:58:27Z

packages/components/src/templates/next/components/complex/ImageGallery/ImageGalleryClient.tsx

+            const shouldPreload =
+              // Preload the image if it is in the preview thumbnail sequence
+              previewIndices.includes(index) ||
+              // Preload the last image if currently displaying the first image
+              // to ensure smooth transitioning when navigating to the last image from the first
+              (currentIndex === 0 && index === images.length - 1) ||
+              // Preload the first image if currently displaying the last image
+              // to ensure smooth transitioning when navigating to the first image from the last
+              (currentIndex === images.length - 1 && index === 0)


[clarification] shouldn't the preview indices for currentIndex == 0 || currentIndex = 1 alr include the first/last index?

yes, but in the case wheres theres many images e.g. 20, the previewIndices won't include the first/last index

seaerchin · 2025-05-16T04:52:48Z

...ges/components/src/templates/next/components/complex/ImageGallery/utils/getPreviewIndices.ts

[comment] i can't help but feel like this is abit confusing and probably clearer expressed with modulo arithmetic, but given its narrow scope, i'm fine w/ just keeping this as is

actually i agree. Thought about it and decided to refactor it based on 51bdb44

its more hardcoded, but given that we are sure its gonna be 3/5, we can hardcode for the respective use case. More readable and maintanable

adriangohjw · 2025-05-26T10:53:36Z

@seaerchin

we have 2 forms of images

the big one shown when the user clicks in

the preview we see down below

correct

the big one is eagerly preloaded when user is +/- 1 or 2 positions away (depending on the window size)
all the images in the preview we see down below is loaded when the user hovers over the preview (and we load in window size)?

correct + also as they onMouseEnter the "next"/"previous" button

…ngohjw/isom-1898-image-gallery-slideshow

adriangohjw added 21 commits May 8, 2025 04:17

add ImageGallery component schema and types

1e51b88

add placeholder imagegallery display

bb64d85

update render

d693526

add IMAGE_GALLERY_TYPE to constants and update TYPE_TO_ICON mapping

0de4c10

add IMAGE_GALLERY_TYPE to DEFAULT_BLOCKS and BLOCK_TO_META with place…

6c84059

…holder images and descriptions

add ImageGallery stories for Storybook with various configurations an…

f6ab394

…d placeholder images

add shouldLazyLoad props

f2bc9e9

Implement ImageGallery component with navigation and preview function…

8493f65

…ality; add constants for arrow SVGs and maximum preview images

Refactor ImageGallery component by extracting getPreviewIndices utili…

de85338

…ty; simplify preview logic and enhance readability. Add unit tests for getPreviewIndices functionality.

Update ImageGallery styles: increase arrow SVG size and adjust button…

b4b0cab

… styles for improved accessibility and visual consistency.

Enhance ImageGallery button styles for better accessibility: add hove…

91603c2

…r effects and disable state for active images.

Update ImageGallery component to include alt text for preview images,…

e1b743e

… enhancing accessibility and SEO.

Refactor ImageGallery component: separate client logic into ImageGall…

1b625f6

…eryClient for improved modularity and maintainability. Introduce ImageGalleryClientProps type for better prop management.

Fix ImageGalleryClient to use currentIndex directly for image selecti…

fe931c1

…on and button state, improving clarity and consistency in index handling.

Update ImageGalleryClient styles: adjust margin and gap for improved …

01dad96

…layout consistency in the preview section.

Enhance ImageGalleryClient styles and functionality: introduce compou…

c6bf572

…nd styles for image previews, improve button focus states, and refactor preview index handling for better clarity and maintainability.

Add image gallery examples to Content stories: include multiple image…

f49a2b1

… sets with captions for enhanced visual representation and testing.

Update ImageGalleryClient styles: add top margin to section for impro…

918cb4c

…ved layout and visual separation in the image gallery.

change from focus to focus-visible

d2aaa41

update preview-tw

779eb7f

update to mt-6

00ebd15

adriangohjw self-assigned this May 7, 2025

adriangohjw requested a review from a team as a code owner May 7, 2025 23:30

adriangohjw added the enhancement New feature or request label May 7, 2025

adriangohjw temporarily deployed to staging May 7, 2025 23:31 — with GitHub Actions Inactive

fix transition

e38f049

seaerchin reviewed May 8, 2025

View reviewed changes

adriangohjw temporarily deployed to staging May 11, 2025 19:37 — with GitHub Actions Inactive

fix navbar

ba5fa85

adriangohjw temporarily deployed to staging May 11, 2025 19:55 — with GitHub Actions Inactive

fix timeout issue

8373419

adriangohjw temporarily deployed to staging May 11, 2025 21:05 — with GitHub Actions Inactive

adriangohjw requested a review from seaerchin May 14, 2025 05:10

seaerchin reviewed May 15, 2025

View reviewed changes

adriangohjw added 7 commits May 15, 2025 16:03

ue useTransition instead

8443e42

put inline transition duration

cb1c4b2

Merge remote-tracking branch 'origin/main' into adriangohjw/isom-1898-…

8804a2f

…image-gallery-slideshow

add reduced motion for transition

46c3487

update previewtw

076f345

update to be assets instead of constants

41f8538

remove isPending check

5b3ac18

adriangohjw temporarily deployed to staging May 15, 2025 08:27 — with GitHub Actions Inactive

seaerchin reviewed May 16, 2025

View reviewed changes

Merge branch 'main' of https://github.com/opengovsg/isomer into adria…

5f894c1

…ngohjw/isom-1898-image-gallery-slideshow

adriangohjw temporarily deployed to staging May 26, 2025 10:59 — with GitHub Actions Inactive

refactor: improve getPreviewIndices function for image gallery

51bdb44

adriangohjw temporarily deployed to staging May 26, 2025 11:07 — with GitHub Actions Inactive

adriangohjw requested a review from seaerchin May 27, 2025 05:01

seaerchin approved these changes May 30, 2025

View reviewed changes

adriangohjw merged commit 0415687 into main May 30, 2025
18 of 20 checks passed

adriangohjw deleted the adriangohjw/isom-1898-image-gallery-slideshow branch May 30, 2025 06:07

isom-1898 image gallery slideshow #1298

isom-1898 image gallery slideshow #1298

Conversation

adriangohjw commented May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Before & After Screenshots

Without transition

With transition

Tests

Uh oh!

linear bot commented May 7, 2025

Uh oh!

datadog-opengovsg bot commented May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Datadog Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

What it does:

How it works:

To your question:

Uh oh!

seaerchin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adriangohjw May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adriangohjw commented May 26, 2025

Uh oh!

Uh oh!

Uh oh!

adriangohjw commented May 7, 2025 •

edited

Loading

datadog-opengovsg bot commented May 7, 2025 •

edited

Loading

adriangohjw May 26, 2025 •

edited

Loading