From 4f54f47a6253c9a7c38892a8532c45a9ad474d43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20Parram=C3=B3n=20Teixid=C3=B3?=
 <mparramon@palo-it.com>
Date: Wed, 15 Apr 2026 14:53:01 +0800
Subject: [PATCH 01/10] [DCUBESDQLR-2356][MPT] add custom content slot for
 fullscreen-image-carousel

- Add discriminated union FullscreenCarouselItemProps (ImageCarouselItemProps | CustomCarouselItemProps)
- Add renderContent per-item render prop for custom slide content
- Add itemLabel per-item prop for accessible aria-label overrides
- Hide magnifier button for custom content slides
- Fall back to SlidePlaceholderImage in thumbnail strip when no src available
- Update carousel-level aria-labels to generic wording when any item uses itemLabel
---
 .../fullscreen-image-carousel.tsx             | 111 ++++++++++++------
 src/fullscreen-image-carousel/types.ts        |  23 +++-
 2 files changed, 94 insertions(+), 40 deletions(-)

diff --git a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
index 5dfe7ad3b..3f5225bec 100644
--- a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
+++ b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
@@ -48,11 +48,20 @@ import {
     TopActionButtons,
 } from "./fullscreen-image-carousel.style";
 import {
+    CustomCarouselItemProps,
+    FullscreenCarouselItemProps,
     FullscreenImageCarouselProps,
     FullscreenImageCarouselRef,
     ImageDimension,
 } from "./types";
 
+const isCustomItem = (
+    item: FullscreenCarouselItemProps | undefined
+): item is CustomCarouselItemProps =>
+    !!item &&
+    "renderContent" in item &&
+    typeof item.renderContent === "function";
+
 export const Component = (
     {
         items,
@@ -87,14 +96,20 @@ export const Component = (
     const imageRef = useRef<HTMLDivElement>(null);
     const diff = startX && endX ? startX - endX : 0;
     const currentItem = items[currentSlide];
+    const hasCustomItemLabel = items.some(
+        (item) => item.itemLabel !== undefined
+    );
+    const carouselItemNoun = hasCustomItemLabel ? "item" : "image";
 
     const getImageAriaLabel = useCallback(
         (index: number) => {
             const item = items[index];
-            const altText = item.alt?.trim() || "";
-            return `${altText}. Image ${index + 1} of ${items.length}.`;
+            const altText = isCustomItem(item) ? "" : item.alt?.trim() || "";
+            return `${altText}. ${hasCustomItemLabel ? "Item" : "Image"} ${
+                index + 1
+            } of ${items.length}.`;
         },
-        [items]
+        [items, hasCustomItemLabel]
     );
 
     useImperativeHandle<FullscreenImageCarouselRef, FullscreenImageCarouselRef>(
@@ -208,7 +223,7 @@ export const Component = (
     };
 
     const getZoomRatio = () => {
-        if (!currentItem) {
+        if (!currentItem || isCustomItem(currentItem)) {
             return;
         }
 
@@ -285,29 +300,35 @@ export const Component = (
                                 ref={isActive ? imageRef : null}
                                 tabIndex={isActive ? 0 : -1}
                             >
-                                <TransformWrapper
-                                    ref={(el) => (zoomRefs.current[index] = el)}
-                                    panning={{
-                                        disabled: zoom <= 1,
-                                    }}
-                                    initialScale={1}
-                                    onZoom={handleZoom}
-                                    onZoomStop={handleZoom}
-                                    onWheel={handleZoom}
-                                >
-                                    <TransformComponent>
-                                        <SlideImage
-                                            src={item.src}
-                                            alt={getImageAriaLabel(index)}
-                                            placeholder={
-                                                <SlidePlaceholderImage />
-                                            }
-                                            fit="scale-down"
-                                            retrieveImageDimension
-                                            setDimension={setDimension}
-                                        />
-                                    </TransformComponent>
-                                </TransformWrapper>
+                                {isCustomItem(item) ? (
+                                    item.renderContent()
+                                ) : (
+                                    <TransformWrapper
+                                        ref={(el) =>
+                                            (zoomRefs.current[index] = el)
+                                        }
+                                        panning={{
+                                            disabled: zoom <= 1,
+                                        }}
+                                        initialScale={1}
+                                        onZoom={handleZoom}
+                                        onZoomStop={handleZoom}
+                                        onWheel={handleZoom}
+                                    >
+                                        <TransformComponent>
+                                            <SlideImage
+                                                src={item.src}
+                                                alt={getImageAriaLabel(index)}
+                                                placeholder={
+                                                    <SlidePlaceholderImage />
+                                                }
+                                                fit="scale-down"
+                                                retrieveImageDimension
+                                                setDimension={setDimension}
+                                            />
+                                        </TransformComponent>
+                                    </TransformWrapper>
+                                )}
                             </FocusableImageRegion>
                         </ImageGallerySlide>
                     );
@@ -324,7 +345,9 @@ export const Component = (
             >
                 <ThumbnailWrapper>
                     {items.map((item, index) => {
-                        const src = item.thumbnailSrc ?? item.src;
+                        const src =
+                            item.thumbnailSrc ??
+                            (isCustomItem(item) ? undefined : item.src);
                         return (
                             <ThumbnailItemContainer key={index}>
                                 <ThumbnailItem
@@ -335,11 +358,15 @@ export const Component = (
                                         (thumbnailRefs.current[index] = el)
                                     }
                                 >
-                                    <ThumbnailImage
-                                        src={src}
-                                        alt={`Thumbnail ${index + 1}`}
-                                        fit="cover"
-                                    />
+                                    {src ? (
+                                        <ThumbnailImage
+                                            src={src}
+                                            alt={`Thumbnail ${index + 1}`}
+                                            fit="cover"
+                                        />
+                                    ) : (
+                                        <SlidePlaceholderImage />
+                                    )}
                                 </ThumbnailItem>
                             </ThumbnailItemContainer>
                         );
@@ -353,7 +380,7 @@ export const Component = (
         <ModalV2
             {...otherProps}
             data-testid="image-carousel-modal"
-            aria-label="Image carousel"
+            aria-label={hasCustomItemLabel ? "Carousel" : "Image carousel"}
             show={show}
             disableInitialFocus
         >
@@ -372,7 +399,7 @@ export const Component = (
                         {!hideNavigation && (
                             <>
                                 <ArrowButton
-                                    aria-label="Previous image"
+                                    aria-label={`Previous ${carouselItemNoun}`}
                                     data-testid="prev-btn"
                                     $position="left"
                                     onClick={goToPrevSlide}
@@ -382,7 +409,7 @@ export const Component = (
                                     <ChevronLeftIcon aria-hidden />
                                 </ArrowButton>
                                 <ArrowButton
-                                    aria-label="Next image"
+                                    aria-label={`Next ${carouselItemNoun}`}
                                     data-testid="forward-btn"
                                     $position="right"
                                     onClick={goToNextSlide}
@@ -410,7 +437,7 @@ export const Component = (
                     $insetTop={insets?.top}
                     $insetRight={insets?.right}
                 >
-                    {!hideMagnifier && (
+                    {!hideMagnifier && !isCustomItem(currentItem) && (
                         <MagnifierButton
                             aria-label={zoom === 1 ? "Zoom in" : "Zoom out"}
                             onClick={handleMagnifier}
@@ -425,7 +452,9 @@ export const Component = (
 
                     {onDelete && (
                         <DeleteButton
-                            aria-label="Delete image"
+                            aria-label={`Delete ${
+                                currentItem?.itemLabel ?? "image"
+                            }`}
                             data-testid="delete-btn"
                             onClick={handleDelete}
                         >
@@ -434,7 +463,11 @@ export const Component = (
                     )}
 
                     <CloseButton
-                        aria-label="Close image carousel"
+                        aria-label={
+                            hasCustomItemLabel
+                                ? "Close carousel"
+                                : "Close image carousel"
+                        }
                         onClick={onClose}
                     >
                         <CrossIcon aria-hidden />
diff --git a/src/fullscreen-image-carousel/types.ts b/src/fullscreen-image-carousel/types.ts
index 70cbb3105..2d7fb6cee 100644
--- a/src/fullscreen-image-carousel/types.ts
+++ b/src/fullscreen-image-carousel/types.ts
@@ -27,12 +27,33 @@ export interface FullscreenImageCarouselProps
     insets?: Insets | undefined;
 }
 
-export interface FullscreenCarouselItemProps {
+export interface ImageCarouselItemProps {
     src: string;
     alt?: string | undefined;
     thumbnailSrc?: string | undefined;
+    fileName?: string | undefined;
+    fileSize?: string | undefined;
+    /** Label for this item used in aria-labels (e.g. "PDF"). Defaults to "image". When any item sets this, carousel-level aria-labels use generic "item" wording. */
+    itemLabel?: string | undefined;
+    renderContent?: never;
 }
 
+export interface CustomCarouselItemProps {
+    /** Optional src used as thumbnail fallback. If omitted, a placeholder is shown in the thumbnail strip. */
+    src?: string | undefined;
+    thumbnailSrc?: string | undefined;
+    fileName?: string | undefined;
+    fileSize?: string | undefined;
+    /** Label for this item used in aria-labels (e.g. "PDF"). Defaults to "image". When any item sets this, carousel-level aria-labels use generic "item" wording. */
+    itemLabel?: string | undefined;
+    /** Render prop for the full slide area. Consumer is responsible for the entire slide content (e.g. an iframe, embed, or custom viewer). */
+    renderContent: () => React.ReactNode;
+}
+
+export type FullscreenCarouselItemProps =
+    | ImageCarouselItemProps
+    | CustomCarouselItemProps;
+
 export interface ImageDimension {
     width: number;
     height: number;

From 10c355454920fa6a20242b145a9a0840c8f6da89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20Parram=C3=B3n=20Teixid=C3=B3?=
 <mparramon@palo-it.com>
Date: Wed, 15 Apr 2026 15:25:38 +0800
Subject: [PATCH 02/10] [DCUBESDQLR-2356][MPT] add tests, story, and docs for
 custom content slot

- Add WithCustomContent story with PDF iframe and pdf-icon thumbnail
- Update props-table with renderContent and itemLabel docs
- Add tests for renderContent, itemLabel aria-labels, magnifier hide, thumbnail placeholder
- Remove fileName/fileSize from this branch (belongs to file-info-bar branch)
- Add pdf-icon.svg asset from sgw-dl
---
 public/img/pdf-icon.svg                       |   8 ++
 src/fullscreen-image-carousel/types.ts        |   4 -
 .../fullscreen-image-carousel.mdx             |   6 +
 .../fullscreen-image-carousel.stories.tsx     |  41 +++++++
 .../fullscreen-image-carousel/props-table.tsx |  48 +++++++-
 .../fullscreen-image-carousel.spec.tsx        | 105 ++++++++++++++++++
 6 files changed, 203 insertions(+), 9 deletions(-)
 create mode 100644 public/img/pdf-icon.svg

diff --git a/public/img/pdf-icon.svg b/public/img/pdf-icon.svg
new file mode 100644
index 000000000..6e78f081f
--- /dev/null
+++ b/public/img/pdf-icon.svg
@@ -0,0 +1,8 @@
+<svg width="110" height="125" viewBox="0 0 110 125" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M10.2135 1.15715C11.3561 0.0314522 12.8795 0.0195312 12.8795 0.0195312H82.7188L95.2188 13.8203L109.175 29.3203V119.996C109.175 119.996 109.184 121.759 108.046 122.882C106.909 124.005 105.164 124.02 105.164 124.02H13.0682C13.0682 124.02 11.3687 124.004 10.2356 122.882C9.1026 121.76 9.11588 120.038 9.11588 120.038L9.09378 4.00118C9.09378 4.00118 9.07104 2.28284 10.2135 1.15715Z" fill="#DDE1E2"/>
+<path d="M82.7188 0L96.2188 14.8203L109.219 29.3197H87.5082C87.5082 29.3197 85.4556 29.3197 84.0872 27.9388C82.7188 26.5578 82.7188 24.4864 82.7188 24.4864V0Z" fill="#EDEFEF"/>
+<rect y="60.334" width="84.159" height="35.2558" rx="4" fill="#D43328"/>
+<path d="M30.7099 73.5392C30.7099 75.7443 30.044 77.4293 28.7186 78.5944C27.3932 79.7595 25.497 80.3453 23.0491 80.3453H21.2544V87.6254H17.0625V67.1543H23.3725C25.7697 67.1543 27.5897 67.6875 28.839 68.7604C30.0884 69.8267 30.7099 71.4262 30.7099 73.5458V73.5392ZM21.248 76.7909H22.6242C23.9116 76.7909 24.8755 76.5276 25.516 76.001C26.1565 75.4744 26.4736 74.7042 26.4736 73.6971C26.4736 72.69 26.2072 71.9265 25.6682 71.4394C25.1291 70.9523 24.292 70.7088 23.1442 70.7088H21.2353V76.7843L21.248 76.7909Z" fill="white"/>
+<path d="M50.0346 77.2C50.0346 80.5726 49.2005 83.1496 47.5324 84.9399C45.8644 86.7303 43.4567 87.6254 40.3015 87.6254H35.2578V67.1543H40.8522C43.7556 67.1543 46.0138 68.0404 47.6269 69.8036C49.232 71.5668 50.0425 74.0353 50.0425 77.2H50.0346ZM46.1083 77.3175C46.1083 72.9231 44.4166 70.7259 41.041 70.7259H39.0347V84.0538H40.6555C44.2907 84.0538 46.1162 81.8114 46.1162 77.3175H46.1083Z" fill="white"/>
+<path d="M58.733 87.6254H54.5938V67.1543H65.9666V70.7108H58.733V75.9896H65.4645V79.5322H58.733V87.6254Z" fill="white"/>
+</svg>
diff --git a/src/fullscreen-image-carousel/types.ts b/src/fullscreen-image-carousel/types.ts
index 2d7fb6cee..ee6e19d4b 100644
--- a/src/fullscreen-image-carousel/types.ts
+++ b/src/fullscreen-image-carousel/types.ts
@@ -31,8 +31,6 @@ export interface ImageCarouselItemProps {
     src: string;
     alt?: string | undefined;
     thumbnailSrc?: string | undefined;
-    fileName?: string | undefined;
-    fileSize?: string | undefined;
     /** Label for this item used in aria-labels (e.g. "PDF"). Defaults to "image". When any item sets this, carousel-level aria-labels use generic "item" wording. */
     itemLabel?: string | undefined;
     renderContent?: never;
@@ -42,8 +40,6 @@ export interface CustomCarouselItemProps {
     /** Optional src used as thumbnail fallback. If omitted, a placeholder is shown in the thumbnail strip. */
     src?: string | undefined;
     thumbnailSrc?: string | undefined;
-    fileName?: string | undefined;
-    fileSize?: string | undefined;
     /** Label for this item used in aria-labels (e.g. "PDF"). Defaults to "image". When any item sets this, carousel-level aria-labels use generic "item" wording. */
     itemLabel?: string | undefined;
     /** Render prop for the full slide area. Consumer is responsible for the entire slide content (e.g. an iframe, embed, or custom viewer). */
diff --git a/stories/fullscreen-image-carousel/fullscreen-image-carousel.mdx b/stories/fullscreen-image-carousel/fullscreen-image-carousel.mdx
index 414ba190f..eb0391d74 100644
--- a/stories/fullscreen-image-carousel/fullscreen-image-carousel.mdx
+++ b/stories/fullscreen-image-carousel/fullscreen-image-carousel.mdx
@@ -32,6 +32,12 @@ import { FullscreenImageCarousel } from "@lifesg/react-design-system/fullscreen-
 
 <Canvas of={FullscreenImageCarouselStories.Configurable} />
 
+## With custom content
+
+Slides can render arbitrary content via `renderContent`. When `itemLabel` is set, carousel aria-labels switch to generic wording.
+
+<Canvas of={FullscreenImageCarouselStories.WithCustomContent} />
+
 ## Component API
 
 <PropsTable />
diff --git a/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx b/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx
index 4e47dcb60..f9a87694e 100644
--- a/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx
+++ b/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx
@@ -135,3 +135,44 @@ export const Configurable: StoryObj<Component> = {
         );
     },
 };
+
+export const WithCustomContent: StoryObj<Component> = {
+    render: (_args) => {
+        const [show, setShow] = useState(false);
+        return (
+            <>
+                <Button.Default
+                    onClick={() => {
+                        setShow((old) => !old);
+                    }}
+                >
+                    Show carousel
+                </Button.Default>
+                <FullscreenImageCarousel
+                    items={[
+                        { src: "https://picsum.photos/id/157/1600/900" },
+                        {
+                            itemLabel: "PDF",
+                            thumbnailSrc: "/img/pdf-icon.svg",
+                            renderContent: () => (
+                                <iframe
+                                    src="https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf"
+                                    title="PDF preview"
+                                    style={{
+                                        width: "100%",
+                                        height: "100%",
+                                        border: "none",
+                                    }}
+                                />
+                            ),
+                        },
+                        { src: "https://picsum.photos/id/369/1000/1000" },
+                    ]}
+                    show={show}
+                    onDelete={() => undefined}
+                    onClose={() => setShow(false)}
+                />
+            </>
+        );
+    },
+};
diff --git a/stories/fullscreen-image-carousel/props-table.tsx b/stories/fullscreen-image-carousel/props-table.tsx
index f7b30a1ad..a28b13fa0 100644
--- a/stories/fullscreen-image-carousel/props-table.tsx
+++ b/stories/fullscreen-image-carousel/props-table.tsx
@@ -113,14 +113,25 @@ const DATA: ApiTableSectionProps[] = [
         attributes: [
             {
                 name: "src",
-                description: "The image src",
+                description: (
+                    <>
+                        The image src. Required for{" "}
+                        <code>ImageCarouselItemProps</code>, optional for{" "}
+                        <code>CustomCarouselItemProps</code> (used as thumbnail
+                        fallback)
+                    </>
+                ),
                 propTypes: ["string"],
-                mandatory: true,
             },
             {
                 name: "alt",
-                description:
-                    "Descriptive text to be set on the image for screen readers",
+                description: (
+                    <>
+                        Descriptive text to be set on the image for screen
+                        readers. Only applicable for{" "}
+                        <code>ImageCarouselItemProps</code>
+                    </>
+                ),
                 propTypes: ["string"],
             },
             {
@@ -128,11 +139,38 @@ const DATA: ApiTableSectionProps[] = [
                 description: (
                     <>
                         The thumbnail image src. If not specified, the image{" "}
-                        <code>src</code> will be used
+                        <code>src</code> will be used. If neither is available,
+                        a placeholder is shown
                     </>
                 ),
                 propTypes: ["string"],
             },
+            {
+                name: "itemLabel",
+                description: (
+                    <>
+                        Label for this item used in aria-labels (e.g.{" "}
+                        <code>&quot;PDF&quot;</code>). Defaults to{" "}
+                        <code>&quot;image&quot;</code>. When any item sets this,
+                        carousel-level aria-labels switch to generic wording
+                    </>
+                ),
+                propTypes: ["string"],
+            },
+            {
+                name: "renderContent",
+                description: (
+                    <>
+                        Render prop for the full slide area. When provided, the
+                        item is treated as a{" "}
+                        <code>CustomCarouselItemProps</code> and the consumer
+                        owns the entire slide content (e.g. an iframe, embed, or
+                        custom viewer). Zoom controls are hidden for custom
+                        slides
+                    </>
+                ),
+                propTypes: ["() => React.ReactNode"],
+            },
         ],
     },
 ];
diff --git a/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx b/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx
index f70868724..013c5494e 100644
--- a/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx
+++ b/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx
@@ -111,6 +111,103 @@ describe("Fullscreen Image Carousel", () => {
             expect(screen.getByText("1/4")).toBeInTheDocument();
         });
     });
+
+    describe("Custom content (renderContent)", () => {
+        it("should render custom content from renderContent", () => {
+            render(
+                <FullscreenImageCarousel
+                    items={MIXED_ITEMS}
+                    show={true}
+                    initialActiveItemIndex={1}
+                />
+            );
+
+            expect(
+                screen.getByTestId("custom-slide-content")
+            ).toBeInTheDocument();
+        });
+
+        it("should hide magnifier button when current item is custom", () => {
+            render(
+                <FullscreenImageCarousel
+                    items={MIXED_ITEMS}
+                    show={true}
+                    initialActiveItemIndex={1}
+                />
+            );
+
+            expect(screen.queryByLabelText("Zoom in")).not.toBeInTheDocument();
+        });
+
+        it("should show magnifier button when current item is an image", () => {
+            render(
+                <FullscreenImageCarousel
+                    items={MIXED_ITEMS}
+                    show={true}
+                    initialActiveItemIndex={0}
+                />
+            );
+
+            expect(screen.getByLabelText("Zoom in")).toBeInTheDocument();
+        });
+
+        it("should render placeholder thumbnail when custom item has no src", () => {
+            render(<FullscreenImageCarousel items={MIXED_ITEMS} show={true} />);
+
+            const thumbnails = screen.getAllByTestId("thumbnail-item");
+            // Second thumbnail (custom item) should not have an img
+            const imgs = thumbnails[1].querySelectorAll("img");
+            expect(imgs.length).toBe(0);
+        });
+    });
+
+    describe("itemLabel aria-labels", () => {
+        it("should use generic wording when any item has itemLabel", () => {
+            render(<FullscreenImageCarousel items={MIXED_ITEMS} show={true} />);
+
+            expect(screen.getByLabelText("Carousel")).toBeInTheDocument();
+            expect(screen.getByLabelText("Close carousel")).toBeInTheDocument();
+            expect(screen.getByLabelText("Previous item")).toBeInTheDocument();
+            expect(screen.getByLabelText("Next item")).toBeInTheDocument();
+        });
+
+        it("should use image-specific wording when no item has itemLabel", () => {
+            render(<FullscreenImageCarousel items={IMAGES} show={true} />);
+
+            expect(screen.getByLabelText("Image carousel")).toBeInTheDocument();
+            expect(
+                screen.getByLabelText("Close image carousel")
+            ).toBeInTheDocument();
+            expect(screen.getByLabelText("Previous image")).toBeInTheDocument();
+            expect(screen.getByLabelText("Next image")).toBeInTheDocument();
+        });
+
+        it("should use per-item itemLabel for the delete button", () => {
+            render(
+                <FullscreenImageCarousel
+                    items={MIXED_ITEMS}
+                    show={true}
+                    initialActiveItemIndex={1}
+                    onDelete={jest.fn()}
+                />
+            );
+
+            expect(screen.getByLabelText("Delete PDF")).toBeInTheDocument();
+        });
+
+        it("should default delete label to 'image' when no itemLabel", () => {
+            render(
+                <FullscreenImageCarousel
+                    items={MIXED_ITEMS}
+                    show={true}
+                    initialActiveItemIndex={0}
+                    onDelete={jest.fn()}
+                />
+            );
+
+            expect(screen.getByLabelText("Delete image")).toBeInTheDocument();
+        });
+    });
 });
 
 // =============================================================================
@@ -122,3 +219,11 @@ const IMAGES = [
     { src: "https://picsum.photos/id/369/1000/1000" },
     { src: "https://picsum.photos/id/445/300/300" },
 ];
+
+const MIXED_ITEMS = [
+    { src: "https://picsum.photos/id/157/1600/900" },
+    {
+        itemLabel: "PDF",
+        renderContent: () => <div data-testid="custom-slide-content">PDF</div>,
+    },
+];

From 574212c067da9cdfd3ff0fc0ff31d11716b7b307 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20Parram=C3=B3n=20Teixid=C3=B3?=
 <mparramon@palo-it.com>
Date: Wed, 15 Apr 2026 15:51:12 +0800
Subject: [PATCH 03/10] [DCUBESDQLR-2356][MPT] remove redundant src from
 CustomCarouselItemProps

- Custom items only need thumbnailSrc for the thumbnail strip
---
 src/fullscreen-image-carousel/fullscreen-image-carousel.tsx | 6 +++---
 src/fullscreen-image-carousel/types.ts                      | 3 +--
 stories/fullscreen-image-carousel/props-table.tsx           | 5 ++---
 3 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
index 3f5225bec..bfa76b718 100644
--- a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
+++ b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
@@ -345,9 +345,9 @@ export const Component = (
             >
                 <ThumbnailWrapper>
                     {items.map((item, index) => {
-                        const src =
-                            item.thumbnailSrc ??
-                            (isCustomItem(item) ? undefined : item.src);
+                        const src = isCustomItem(item)
+                            ? item.thumbnailSrc
+                            : item.thumbnailSrc ?? item.src;
                         return (
                             <ThumbnailItemContainer key={index}>
                                 <ThumbnailItem
diff --git a/src/fullscreen-image-carousel/types.ts b/src/fullscreen-image-carousel/types.ts
index ee6e19d4b..73b7530dd 100644
--- a/src/fullscreen-image-carousel/types.ts
+++ b/src/fullscreen-image-carousel/types.ts
@@ -37,8 +37,7 @@ export interface ImageCarouselItemProps {
 }
 
 export interface CustomCarouselItemProps {
-    /** Optional src used as thumbnail fallback. If omitted, a placeholder is shown in the thumbnail strip. */
-    src?: string | undefined;
+    /** The thumbnail image src. If omitted, a placeholder is shown in the thumbnail strip. */
     thumbnailSrc?: string | undefined;
     /** Label for this item used in aria-labels (e.g. "PDF"). Defaults to "image". When any item sets this, carousel-level aria-labels use generic "item" wording. */
     itemLabel?: string | undefined;
diff --git a/stories/fullscreen-image-carousel/props-table.tsx b/stories/fullscreen-image-carousel/props-table.tsx
index a28b13fa0..fd529255a 100644
--- a/stories/fullscreen-image-carousel/props-table.tsx
+++ b/stories/fullscreen-image-carousel/props-table.tsx
@@ -116,9 +116,8 @@ const DATA: ApiTableSectionProps[] = [
                 description: (
                     <>
                         The image src. Required for{" "}
-                        <code>ImageCarouselItemProps</code>, optional for{" "}
-                        <code>CustomCarouselItemProps</code> (used as thumbnail
-                        fallback)
+                        <code>ImageCarouselItemProps</code>. Not available on{" "}
+                        <code>CustomCarouselItemProps</code>
                     </>
                 ),
                 propTypes: ["string"],

From c0287f3a8deb555f25ebb314af97a8bff0e79030 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20Parram=C3=B3n=20Teixid=C3=B3?=
 <mparramon@palo-it.com>
Date: Wed, 15 Apr 2026 15:54:09 +0800
Subject: [PATCH 04/10] [DCUBESDQLR-2356][MPT] add custom item without
 thumbnailSrc to story

---
 .../fullscreen-image-carousel.stories.tsx      | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx b/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx
index f9a87694e..13c4fbcf8 100644
--- a/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx
+++ b/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx
@@ -166,6 +166,24 @@ export const WithCustomContent: StoryObj<Component> = {
                                 />
                             ),
                         },
+                        {
+                            itemLabel: "document",
+                            renderContent: () => (
+                                <div
+                                    style={{
+                                        display: "flex",
+                                        alignItems: "center",
+                                        justifyContent: "center",
+                                        width: "100%",
+                                        height: "100%",
+                                        color: "#fff",
+                                        fontSize: 24,
+                                    }}
+                                >
+                                    No thumbnail provided
+                                </div>
+                            ),
+                        },
                         { src: "https://picsum.photos/id/369/1000/1000" },
                     ]}
                     show={show}

From b908e6ac9090b9d64f41e6e2a9fd79195044ea70 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20Parram=C3=B3n=20Teixid=C3=B3?=
 <mparramon@palo-it.com>
Date: Wed, 15 Apr 2026 16:08:11 +0800
Subject: [PATCH 05/10] [DCUBESDQLR-2356][MPT] restrict itemLabel to
 CustomCarouselItemProps only

---
 src/fullscreen-image-carousel/fullscreen-image-carousel.tsx | 6 ++++--
 src/fullscreen-image-carousel/types.ts                      | 2 --
 stories/fullscreen-image-carousel/props-table.tsx           | 3 ++-
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
index bfa76b718..7a49ed818 100644
--- a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
+++ b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
@@ -97,7 +97,7 @@ export const Component = (
     const diff = startX && endX ? startX - endX : 0;
     const currentItem = items[currentSlide];
     const hasCustomItemLabel = items.some(
-        (item) => item.itemLabel !== undefined
+        (item) => isCustomItem(item) && item.itemLabel !== undefined
     );
     const carouselItemNoun = hasCustomItemLabel ? "item" : "image";
 
@@ -453,7 +453,9 @@ export const Component = (
                     {onDelete && (
                         <DeleteButton
                             aria-label={`Delete ${
-                                currentItem?.itemLabel ?? "image"
+                                (isCustomItem(currentItem) &&
+                                    currentItem.itemLabel) ||
+                                "image"
                             }`}
                             data-testid="delete-btn"
                             onClick={handleDelete}
diff --git a/src/fullscreen-image-carousel/types.ts b/src/fullscreen-image-carousel/types.ts
index 73b7530dd..3ee33a44e 100644
--- a/src/fullscreen-image-carousel/types.ts
+++ b/src/fullscreen-image-carousel/types.ts
@@ -31,8 +31,6 @@ export interface ImageCarouselItemProps {
     src: string;
     alt?: string | undefined;
     thumbnailSrc?: string | undefined;
-    /** Label for this item used in aria-labels (e.g. "PDF"). Defaults to "image". When any item sets this, carousel-level aria-labels use generic "item" wording. */
-    itemLabel?: string | undefined;
     renderContent?: never;
 }
 
diff --git a/stories/fullscreen-image-carousel/props-table.tsx b/stories/fullscreen-image-carousel/props-table.tsx
index fd529255a..95fee4e8b 100644
--- a/stories/fullscreen-image-carousel/props-table.tsx
+++ b/stories/fullscreen-image-carousel/props-table.tsx
@@ -151,7 +151,8 @@ const DATA: ApiTableSectionProps[] = [
                         Label for this item used in aria-labels (e.g.{" "}
                         <code>&quot;PDF&quot;</code>). Defaults to{" "}
                         <code>&quot;image&quot;</code>. When any item sets this,
-                        carousel-level aria-labels switch to generic wording
+                        carousel-level aria-labels switch to generic wording.
+                        Only applicable for <code>CustomCarouselItemProps</code>
                     </>
                 ),
                 propTypes: ["string"],

From d90b3cb2f313ab5a19b3120e8735286df13a3102 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20Parram=C3=B3n=20Teixid=C3=B3?=
 <mparramon@palo-it.com>
Date: Wed, 15 Apr 2026 16:17:07 +0800
Subject: [PATCH 06/10] [DCUBESDQLR-2356][MPT] address PR review comments

- fix leading punctuation in aria-labels when alt/itemLabel is empty
- lazy-render custom content only for active and adjacent slides
- trim empty itemLabel in delete button aria-label
- rename hasCustomItemLabel to hasAnyItemLabel
- keep FullscreenCarouselItemProps as base interface for backward compat
---
 .../fullscreen-image-carousel.tsx             | 47 ++++++++++++-------
 src/fullscreen-image-carousel/types.ts        | 18 ++++---
 .../fullscreen-image-carousel/props-table.tsx |  8 ++--
 .../fullscreen-image-carousel.spec.tsx        | 26 ++++++++++
 4 files changed, 71 insertions(+), 28 deletions(-)

diff --git a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
index 7a49ed818..c8c494e9c 100644
--- a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
+++ b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
@@ -48,15 +48,15 @@ import {
     TopActionButtons,
 } from "./fullscreen-image-carousel.style";
 import {
+    CarouselItemProps,
     CustomCarouselItemProps,
-    FullscreenCarouselItemProps,
     FullscreenImageCarouselProps,
     FullscreenImageCarouselRef,
     ImageDimension,
 } from "./types";
 
 const isCustomItem = (
-    item: FullscreenCarouselItemProps | undefined
+    item: CarouselItemProps | undefined
 ): item is CustomCarouselItemProps =>
     !!item &&
     "renderContent" in item &&
@@ -96,20 +96,25 @@ export const Component = (
     const imageRef = useRef<HTMLDivElement>(null);
     const diff = startX && endX ? startX - endX : 0;
     const currentItem = items[currentSlide];
-    const hasCustomItemLabel = items.some(
+    const hasAnyItemLabel = items.some(
         (item) => isCustomItem(item) && item.itemLabel !== undefined
     );
-    const carouselItemNoun = hasCustomItemLabel ? "item" : "image";
+    const carouselItemNoun = hasAnyItemLabel ? "item" : "image";
 
-    const getImageAriaLabel = useCallback(
+    const getItemAriaLabel = useCallback(
         (index: number) => {
             const item = items[index];
-            const altText = isCustomItem(item) ? "" : item.alt?.trim() || "";
-            return `${altText}. ${hasCustomItemLabel ? "Item" : "Image"} ${
-                index + 1
-            } of ${items.length}.`;
+            const itemTypeLabel = hasAnyItemLabel ? "Item" : "Image";
+            const prefix = isCustomItem(item)
+                ? item.itemLabel?.trim() || ""
+                : item.alt?.trim() || "";
+            const positionLabel = `${itemTypeLabel} ${index + 1} of ${
+                items.length
+            }.`;
+
+            return prefix ? `${prefix}. ${positionLabel}` : positionLabel;
         },
-        [items, hasCustomItemLabel]
+        [items, hasAnyItemLabel]
     );
 
     useImperativeHandle<FullscreenImageCarouselRef, FullscreenImageCarouselRef>(
@@ -258,7 +263,7 @@ export const Component = (
             (prev) => (prev === 0 ? items.length - 1 : prev - 1),
             (slide) => {
                 clearAnnouncer("polite");
-                announce(getImageAriaLabel(slide), "polite");
+                announce(getItemAriaLabel(slide), "polite");
             }
         );
     };
@@ -269,7 +274,7 @@ export const Component = (
             (prev) => (prev === items.length - 1 ? 0 : prev + 1),
             (slide) => {
                 clearAnnouncer("polite");
-                announce(getImageAriaLabel(slide), "polite");
+                announce(getItemAriaLabel(slide), "polite");
             }
         );
     };
@@ -293,6 +298,10 @@ export const Component = (
             >
                 {items.map((item, index) => {
                     const isActive = index === currentSlide;
+                    const isAdjacent =
+                        Math.abs(index - currentSlide) <= 1 ||
+                        (currentSlide === 0 && index === items.length - 1) ||
+                        (currentSlide === items.length - 1 && index === 0);
 
                     return (
                         <ImageGallerySlide key={index} data-testid="slide-item">
@@ -301,7 +310,11 @@ export const Component = (
                                 tabIndex={isActive ? 0 : -1}
                             >
                                 {isCustomItem(item) ? (
-                                    item.renderContent()
+                                    isAdjacent ? (
+                                        item.renderContent()
+                                    ) : (
+                                        <SlidePlaceholderImage />
+                                    )
                                 ) : (
                                     <TransformWrapper
                                         ref={(el) =>
@@ -318,7 +331,7 @@ export const Component = (
                                         <TransformComponent>
                                             <SlideImage
                                                 src={item.src}
-                                                alt={getImageAriaLabel(index)}
+                                                alt={getItemAriaLabel(index)}
                                                 placeholder={
                                                     <SlidePlaceholderImage />
                                                 }
@@ -380,7 +393,7 @@ export const Component = (
         <ModalV2
             {...otherProps}
             data-testid="image-carousel-modal"
-            aria-label={hasCustomItemLabel ? "Carousel" : "Image carousel"}
+            aria-label={hasAnyItemLabel ? "Carousel" : "Image carousel"}
             show={show}
             disableInitialFocus
         >
@@ -454,7 +467,7 @@ export const Component = (
                         <DeleteButton
                             aria-label={`Delete ${
                                 (isCustomItem(currentItem) &&
-                                    currentItem.itemLabel) ||
+                                    currentItem.itemLabel?.trim()) ||
                                 "image"
                             }`}
                             data-testid="delete-btn"
@@ -466,7 +479,7 @@ export const Component = (
 
                     <CloseButton
                         aria-label={
-                            hasCustomItemLabel
+                            hasAnyItemLabel
                                 ? "Close carousel"
                                 : "Close image carousel"
                         }
diff --git a/src/fullscreen-image-carousel/types.ts b/src/fullscreen-image-carousel/types.ts
index 3ee33a44e..3fcd56734 100644
--- a/src/fullscreen-image-carousel/types.ts
+++ b/src/fullscreen-image-carousel/types.ts
@@ -13,24 +13,30 @@ export interface FullscreenImageCarouselProps
         ModalProps,
         "show" | "rootComponentId" | "animationFrom" | "zIndex"
     > {
-    items: FullscreenCarouselItemProps[];
+    items: CarouselItemProps[];
     /** The index of the visible item, starts from 0 */
     initialActiveItemIndex?: number | undefined;
     hideThumbnail?: boolean | undefined;
     hideNavigation?: boolean | undefined;
     hideCounter?: boolean | undefined;
     hideMagnifier?: boolean | undefined;
-    onDelete?:
-        | ((item: FullscreenCarouselItemProps, index: number) => void)
-        | undefined;
+    onDelete?: ((item: CarouselItemProps, index: number) => void) | undefined;
     onClose?: (() => void) | undefined;
     insets?: Insets | undefined;
 }
 
-export interface ImageCarouselItemProps {
+/**
+ * Base item props shared by all carousel items.
+ * Kept as a standalone interface for backward compatibility
+ * (consumers may extend it).
+ */
+export interface FullscreenCarouselItemProps {
     src: string;
     alt?: string | undefined;
     thumbnailSrc?: string | undefined;
+}
+
+export interface ImageCarouselItemProps extends FullscreenCarouselItemProps {
     renderContent?: never;
 }
 
@@ -43,7 +49,7 @@ export interface CustomCarouselItemProps {
     renderContent: () => React.ReactNode;
 }
 
-export type FullscreenCarouselItemProps =
+export type CarouselItemProps =
     | ImageCarouselItemProps
     | CustomCarouselItemProps;
 
diff --git a/stories/fullscreen-image-carousel/props-table.tsx b/stories/fullscreen-image-carousel/props-table.tsx
index 95fee4e8b..256c4684b 100644
--- a/stories/fullscreen-image-carousel/props-table.tsx
+++ b/stories/fullscreen-image-carousel/props-table.tsx
@@ -46,7 +46,7 @@ const DATA: ApiTableSectionProps[] = [
             {
                 name: "items",
                 description: "List of carousel items",
-                propTypes: ["FullscreenCarouselItemProps[]"],
+                propTypes: ["CarouselItemProps[]"],
                 mandatory: true,
             },
             {
@@ -82,9 +82,7 @@ const DATA: ApiTableSectionProps[] = [
                 name: "onDelete",
                 description:
                     "Called when the current image delete button is clicked. When provided, the delete button will be shown. If called, do not reorder the items array while a delete is in flight.",
-                propTypes: [
-                    "(item: FullscreenCarouselItemProps, index: number) => void",
-                ],
+                propTypes: ["(item: CarouselItemProps, index: number) => void"],
             },
             {
                 name: "onClose",
@@ -109,7 +107,7 @@ const DATA: ApiTableSectionProps[] = [
         ],
     },
     {
-        name: "FullscreenCarouselItemProps",
+        name: "CarouselItemProps",
         attributes: [
             {
                 name: "src",
diff --git a/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx b/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx
index 013c5494e..5cb03aa60 100644
--- a/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx
+++ b/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx
@@ -159,6 +159,20 @@ describe("Fullscreen Image Carousel", () => {
             const imgs = thumbnails[1].querySelectorAll("img");
             expect(imgs.length).toBe(0);
         });
+
+        it("should not render custom content for non-adjacent slides", () => {
+            render(
+                <FullscreenImageCarousel
+                    items={SPACED_ITEMS}
+                    show={true}
+                    initialActiveItemIndex={0}
+                />
+            );
+
+            expect(
+                screen.queryByTestId("custom-slide-content")
+            ).not.toBeInTheDocument();
+        });
     });
 
     describe("itemLabel aria-labels", () => {
@@ -227,3 +241,15 @@ const MIXED_ITEMS = [
         renderContent: () => <div data-testid="custom-slide-content">PDF</div>,
     },
 ];
+
+// Custom item at index 3 with images padding both ends, so index 0 is not adjacent
+const SPACED_ITEMS = [
+    { src: "https://picsum.photos/id/157/1600/900" },
+    { src: "https://picsum.photos/id/163/900/300" },
+    { src: "https://picsum.photos/id/369/1000/1000" },
+    {
+        itemLabel: "PDF",
+        renderContent: () => <div data-testid="custom-slide-content">PDF</div>,
+    },
+    { src: "https://picsum.photos/id/445/300/300" },
+];

From c4178956ca23b8e3ba98164c071e6bd9eac48a97 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20Parram=C3=B3n=20Teixid=C3=B3?=
 <mparramon@palo-it.com>
Date: Wed, 15 Apr 2026 17:43:39 +0800
Subject: [PATCH 07/10] [DCUBESDQLR-2356][MPT] trim itemLabel in
 hasAnyItemLabel check

---
 src/fullscreen-image-carousel/fullscreen-image-carousel.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
index c8c494e9c..1a57ab405 100644
--- a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
+++ b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
@@ -97,7 +97,7 @@ export const Component = (
     const diff = startX && endX ? startX - endX : 0;
     const currentItem = items[currentSlide];
     const hasAnyItemLabel = items.some(
-        (item) => isCustomItem(item) && item.itemLabel !== undefined
+        (item) => isCustomItem(item) && !!item.itemLabel?.trim()
     );
     const carouselItemNoun = hasAnyItemLabel ? "item" : "image";
 

From a5eadcbfcb24b5b68ed6703953efc7e77e06197d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20Parram=C3=B3n=20Teixid=C3=B3?=
 <mparramon@palo-it.com>
Date: Thu, 16 Apr 2026 17:53:45 +0800
Subject: [PATCH 08/10] [DCUBESDQLR-2356][MPT] address PR review comments

- rename types: CarouselItemProps -> FullscreenImageCarouselItemProps, CustomCarouselItemProps -> FullscreenImageCarouselCustomItemProps
- deprecate FullscreenCarouselItemProps in favour of FullscreenCarouselImageItemProps
- add type discriminants (type?: "image" | type: "custom")
- rename isAdjacent to isActiveOrAdjacent
- update story: remove first image item, fix thumbnail URL
- update mdx docs wording for itemLabel
- fix test name, add src fallback thumbnail test
- update props-table with new type names and type field
---
 .../fullscreen-image-carousel.tsx             | 16 +++----
 src/fullscreen-image-carousel/types.ts        | 29 ++++++------
 .../fullscreen-image-carousel.mdx             |  2 +-
 .../fullscreen-image-carousel.stories.tsx     |  7 +--
 .../fullscreen-image-carousel/props-table.tsx | 38 ++++++++++-----
 .../fullscreen-image-carousel.spec.tsx        | 46 ++++++++++++++++++-
 6 files changed, 97 insertions(+), 41 deletions(-)

diff --git a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
index 1a57ab405..e721400c0 100644
--- a/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
+++ b/src/fullscreen-image-carousel/fullscreen-image-carousel.tsx
@@ -48,19 +48,17 @@ import {
     TopActionButtons,
 } from "./fullscreen-image-carousel.style";
 import {
-    CarouselItemProps,
-    CustomCarouselItemProps,
+    FullscreenImageCarouselCustomItemProps,
+    FullscreenImageCarouselItemProps,
     FullscreenImageCarouselProps,
     FullscreenImageCarouselRef,
     ImageDimension,
 } from "./types";
 
 const isCustomItem = (
-    item: CarouselItemProps | undefined
-): item is CustomCarouselItemProps =>
-    !!item &&
-    "renderContent" in item &&
-    typeof item.renderContent === "function";
+    item: FullscreenImageCarouselItemProps | undefined
+): item is FullscreenImageCarouselCustomItemProps =>
+    !!item && item.type === "custom";
 
 export const Component = (
     {
@@ -298,7 +296,7 @@ export const Component = (
             >
                 {items.map((item, index) => {
                     const isActive = index === currentSlide;
-                    const isAdjacent =
+                    const isActiveOrAdjacent =
                         Math.abs(index - currentSlide) <= 1 ||
                         (currentSlide === 0 && index === items.length - 1) ||
                         (currentSlide === items.length - 1 && index === 0);
@@ -310,7 +308,7 @@ export const Component = (
                                 tabIndex={isActive ? 0 : -1}
                             >
                                 {isCustomItem(item) ? (
-                                    isAdjacent ? (
+                                    isActiveOrAdjacent ? (
                                         item.renderContent()
                                     ) : (
                                         <SlidePlaceholderImage />
diff --git a/src/fullscreen-image-carousel/types.ts b/src/fullscreen-image-carousel/types.ts
index 3fcd56734..6352069f2 100644
--- a/src/fullscreen-image-carousel/types.ts
+++ b/src/fullscreen-image-carousel/types.ts
@@ -13,34 +13,33 @@ export interface FullscreenImageCarouselProps
         ModalProps,
         "show" | "rootComponentId" | "animationFrom" | "zIndex"
     > {
-    items: CarouselItemProps[];
+    items: FullscreenImageCarouselItemProps[];
     /** The index of the visible item, starts from 0 */
     initialActiveItemIndex?: number | undefined;
     hideThumbnail?: boolean | undefined;
     hideNavigation?: boolean | undefined;
     hideCounter?: boolean | undefined;
     hideMagnifier?: boolean | undefined;
-    onDelete?: ((item: CarouselItemProps, index: number) => void) | undefined;
+    onDelete?:
+        | ((item: FullscreenImageCarouselItemProps, index: number) => void)
+        | undefined;
     onClose?: (() => void) | undefined;
     insets?: Insets | undefined;
 }
 
-/**
- * Base item props shared by all carousel items.
- * Kept as a standalone interface for backward compatibility
- * (consumers may extend it).
- */
-export interface FullscreenCarouselItemProps {
+export interface FullscreenCarouselImageItemProps {
+    type?: "image" | undefined;
     src: string;
     alt?: string | undefined;
     thumbnailSrc?: string | undefined;
-}
-
-export interface ImageCarouselItemProps extends FullscreenCarouselItemProps {
     renderContent?: never;
 }
 
-export interface CustomCarouselItemProps {
+/** @deprecated Use FullscreenCarouselImageItemProps instead */
+export type FullscreenCarouselItemProps = FullscreenCarouselImageItemProps;
+
+export interface FullscreenImageCarouselCustomItemProps {
+    type: "custom";
     /** The thumbnail image src. If omitted, a placeholder is shown in the thumbnail strip. */
     thumbnailSrc?: string | undefined;
     /** Label for this item used in aria-labels (e.g. "PDF"). Defaults to "image". When any item sets this, carousel-level aria-labels use generic "item" wording. */
@@ -49,9 +48,9 @@ export interface CustomCarouselItemProps {
     renderContent: () => React.ReactNode;
 }
 
-export type CarouselItemProps =
-    | ImageCarouselItemProps
-    | CustomCarouselItemProps;
+export type FullscreenImageCarouselItemProps =
+    | FullscreenCarouselImageItemProps
+    | FullscreenImageCarouselCustomItemProps;
 
 export interface ImageDimension {
     width: number;
diff --git a/stories/fullscreen-image-carousel/fullscreen-image-carousel.mdx b/stories/fullscreen-image-carousel/fullscreen-image-carousel.mdx
index eb0391d74..723cd4fb6 100644
--- a/stories/fullscreen-image-carousel/fullscreen-image-carousel.mdx
+++ b/stories/fullscreen-image-carousel/fullscreen-image-carousel.mdx
@@ -34,7 +34,7 @@ import { FullscreenImageCarousel } from "@lifesg/react-design-system/fullscreen-
 
 ## With custom content
 
-Slides can render arbitrary content via `renderContent`. When `itemLabel` is set, carousel aria-labels switch to generic wording.
+Slides can render arbitrary content via `renderContent`. If the content is not an image, you are recommended to set `itemLabel` so that the type of content can be described accurately to screen readers.
 
 <Canvas of={FullscreenImageCarouselStories.WithCustomContent} />
 
diff --git a/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx b/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx
index 13c4fbcf8..014d8db83 100644
--- a/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx
+++ b/stories/fullscreen-image-carousel/fullscreen-image-carousel.stories.tsx
@@ -150,10 +150,11 @@ export const WithCustomContent: StoryObj<Component> = {
                 </Button.Default>
                 <FullscreenImageCarousel
                     items={[
-                        { src: "https://picsum.photos/id/157/1600/900" },
                         {
+                            type: "custom",
                             itemLabel: "PDF",
-                            thumbnailSrc: "/img/pdf-icon.svg",
+                            thumbnailSrc:
+                                "https://assets.life.gov.sg/react-design-system/img/upload/pdf.svg",
                             renderContent: () => (
                                 <iframe
                                     src="https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf"
@@ -167,6 +168,7 @@ export const WithCustomContent: StoryObj<Component> = {
                             ),
                         },
                         {
+                            type: "custom",
                             itemLabel: "document",
                             renderContent: () => (
                                 <div
@@ -184,7 +186,6 @@ export const WithCustomContent: StoryObj<Component> = {
                                 </div>
                             ),
                         },
-                        { src: "https://picsum.photos/id/369/1000/1000" },
                     ]}
                     show={show}
                     onDelete={() => undefined}
diff --git a/stories/fullscreen-image-carousel/props-table.tsx b/stories/fullscreen-image-carousel/props-table.tsx
index 256c4684b..588cdeabb 100644
--- a/stories/fullscreen-image-carousel/props-table.tsx
+++ b/stories/fullscreen-image-carousel/props-table.tsx
@@ -46,7 +46,7 @@ const DATA: ApiTableSectionProps[] = [
             {
                 name: "items",
                 description: "List of carousel items",
-                propTypes: ["CarouselItemProps[]"],
+                propTypes: ["FullscreenImageCarouselItemProps[]"],
                 mandatory: true,
             },
             {
@@ -82,7 +82,9 @@ const DATA: ApiTableSectionProps[] = [
                 name: "onDelete",
                 description:
                     "Called when the current image delete button is clicked. When provided, the delete button will be shown. If called, do not reorder the items array while a delete is in flight.",
-                propTypes: ["(item: CarouselItemProps, index: number) => void"],
+                propTypes: [
+                    "(item: FullscreenImageCarouselItemProps, index: number) => void",
+                ],
             },
             {
                 name: "onClose",
@@ -107,15 +109,28 @@ const DATA: ApiTableSectionProps[] = [
         ],
     },
     {
-        name: "CarouselItemProps",
+        name: "FullscreenImageCarouselItemProps",
         attributes: [
+            {
+                name: "type",
+                description: (
+                    <>
+                        Discriminant for the item type.{" "}
+                        <code>&quot;image&quot;</code> (or omitted) for image
+                        items, <code>&quot;custom&quot;</code> for custom
+                        content items
+                    </>
+                ),
+                propTypes: [`"image" | "custom"`],
+            },
             {
                 name: "src",
                 description: (
                     <>
                         The image src. Required for{" "}
-                        <code>ImageCarouselItemProps</code>. Not available on{" "}
-                        <code>CustomCarouselItemProps</code>
+                        <code>FullscreenCarouselImageItemProps</code>. Not
+                        available on{" "}
+                        <code>FullscreenImageCarouselCustomItemProps</code>
                     </>
                 ),
                 propTypes: ["string"],
@@ -126,7 +141,7 @@ const DATA: ApiTableSectionProps[] = [
                     <>
                         Descriptive text to be set on the image for screen
                         readers. Only applicable for{" "}
-                        <code>ImageCarouselItemProps</code>
+                        <code>FullscreenCarouselImageItemProps</code>
                     </>
                 ),
                 propTypes: ["string"],
@@ -150,7 +165,8 @@ const DATA: ApiTableSectionProps[] = [
                         <code>&quot;PDF&quot;</code>). Defaults to{" "}
                         <code>&quot;image&quot;</code>. When any item sets this,
                         carousel-level aria-labels switch to generic wording.
-                        Only applicable for <code>CustomCarouselItemProps</code>
+                        Only applicable for{" "}
+                        <code>FullscreenImageCarouselCustomItemProps</code>
                     </>
                 ),
                 propTypes: ["string"],
@@ -161,10 +177,10 @@ const DATA: ApiTableSectionProps[] = [
                     <>
                         Render prop for the full slide area. When provided, the
                         item is treated as a{" "}
-                        <code>CustomCarouselItemProps</code> and the consumer
-                        owns the entire slide content (e.g. an iframe, embed, or
-                        custom viewer). Zoom controls are hidden for custom
-                        slides
+                        <code>FullscreenImageCarouselCustomItemProps</code> and
+                        the consumer owns the entire slide content (e.g. an
+                        iframe, embed, or custom viewer). Zoom controls are
+                        hidden for custom slides
                     </>
                 ),
                 propTypes: ["() => React.ReactNode"],
diff --git a/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx b/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx
index 5cb03aa60..5411abdb0 100644
--- a/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx
+++ b/tests/fullscreen-image-carousel/fullscreen-image-carousel.spec.tsx
@@ -151,15 +151,47 @@ describe("Fullscreen Image Carousel", () => {
             expect(screen.getByLabelText("Zoom in")).toBeInTheDocument();
         });
 
-        it("should render placeholder thumbnail when custom item has no src", () => {
+        it("should render placeholder thumbnail when custom item has no thumbnailSrc", () => {
             render(<FullscreenImageCarousel items={MIXED_ITEMS} show={true} />);
 
             const thumbnails = screen.getAllByTestId("thumbnail-item");
-            // Second thumbnail (custom item) should not have an img
+            // The placeholder renders an SVG icon instead of an <img>,
+            // so querying for img elements should return none
             const imgs = thumbnails[1].querySelectorAll("img");
             expect(imgs.length).toBe(0);
         });
 
+        it("should use src as fallback thumbnail when image item has no thumbnailSrc", async () => {
+            const OriginalImage = global.Image;
+            // Simulate image load completing in jsdom (onload never fires natively)
+            (global as any).Image = class {
+                width = 100;
+                height = 100;
+                onload: (() => void) | null = null;
+                set src(_: string) {
+                    Promise.resolve().then(() => this.onload?.());
+                }
+            };
+
+            render(
+                <FullscreenImageCarousel
+                    items={IMAGES_WITHOUT_THUMBNAIL}
+                    show={true}
+                />
+            );
+
+            await waitFor(() => {
+                const img = screen
+                    .getAllByTestId("thumbnail-item")[0]
+                    .querySelector("img");
+                expect(img?.getAttribute("src")).toBe(
+                    "https://picsum.photos/id/157/1600/900"
+                );
+            });
+
+            global.Image = OriginalImage;
+        });
+
         it("should not render custom content for non-adjacent slides", () => {
             render(
                 <FullscreenImageCarousel
@@ -237,6 +269,7 @@ const IMAGES = [
 const MIXED_ITEMS = [
     { src: "https://picsum.photos/id/157/1600/900" },
     {
+        type: "custom" as const,
         itemLabel: "PDF",
         renderContent: () => <div data-testid="custom-slide-content">PDF</div>,
     },
@@ -248,8 +281,17 @@ const SPACED_ITEMS = [
     { src: "https://picsum.photos/id/163/900/300" },
     { src: "https://picsum.photos/id/369/1000/1000" },
     {
+        type: "custom" as const,
         itemLabel: "PDF",
         renderContent: () => <div data-testid="custom-slide-content">PDF</div>,
     },
     { src: "https://picsum.photos/id/445/300/300" },
 ];
+
+const IMAGES_WITHOUT_THUMBNAIL = [
+    { src: "https://picsum.photos/id/157/1600/900" },
+    {
+        src: "https://picsum.photos/id/163/900/300",
+        thumbnailSrc: "https://picsum.photos/id/163/100/100",
+    },
+];

From 6d818330fc187029a3aa7afd632f847ae5513412 Mon Sep 17 00:00:00 2001
From: Quek Ruo Ling <ruoling.quek@ufinity.com>
Date: Fri, 17 Apr 2026 00:54:57 +0800
Subject: [PATCH 09/10] [MISC][RL] Remove unused file

---
 public/img/pdf-icon.svg | 8 --------
 1 file changed, 8 deletions(-)
 delete mode 100644 public/img/pdf-icon.svg

diff --git a/public/img/pdf-icon.svg b/public/img/pdf-icon.svg
deleted file mode 100644
index 6e78f081f..000000000
--- a/public/img/pdf-icon.svg
+++ /dev/null
@@ -1,8 +0,0 @@
-<svg width="110" height="125" viewBox="0 0 110 125" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M10.2135 1.15715C11.3561 0.0314522 12.8795 0.0195312 12.8795 0.0195312H82.7188L95.2188 13.8203L109.175 29.3203V119.996C109.175 119.996 109.184 121.759 108.046 122.882C106.909 124.005 105.164 124.02 105.164 124.02H13.0682C13.0682 124.02 11.3687 124.004 10.2356 122.882C9.1026 121.76 9.11588 120.038 9.11588 120.038L9.09378 4.00118C9.09378 4.00118 9.07104 2.28284 10.2135 1.15715Z" fill="#DDE1E2"/>
-<path d="M82.7188 0L96.2188 14.8203L109.219 29.3197H87.5082C87.5082 29.3197 85.4556 29.3197 84.0872 27.9388C82.7188 26.5578 82.7188 24.4864 82.7188 24.4864V0Z" fill="#EDEFEF"/>
-<rect y="60.334" width="84.159" height="35.2558" rx="4" fill="#D43328"/>
-<path d="M30.7099 73.5392C30.7099 75.7443 30.044 77.4293 28.7186 78.5944C27.3932 79.7595 25.497 80.3453 23.0491 80.3453H21.2544V87.6254H17.0625V67.1543H23.3725C25.7697 67.1543 27.5897 67.6875 28.839 68.7604C30.0884 69.8267 30.7099 71.4262 30.7099 73.5458V73.5392ZM21.248 76.7909H22.6242C23.9116 76.7909 24.8755 76.5276 25.516 76.001C26.1565 75.4744 26.4736 74.7042 26.4736 73.6971C26.4736 72.69 26.2072 71.9265 25.6682 71.4394C25.1291 70.9523 24.292 70.7088 23.1442 70.7088H21.2353V76.7843L21.248 76.7909Z" fill="white"/>
-<path d="M50.0346 77.2C50.0346 80.5726 49.2005 83.1496 47.5324 84.9399C45.8644 86.7303 43.4567 87.6254 40.3015 87.6254H35.2578V67.1543H40.8522C43.7556 67.1543 46.0138 68.0404 47.6269 69.8036C49.232 71.5668 50.0425 74.0353 50.0425 77.2H50.0346ZM46.1083 77.3175C46.1083 72.9231 44.4166 70.7259 41.041 70.7259H39.0347V84.0538H40.6555C44.2907 84.0538 46.1162 81.8114 46.1162 77.3175H46.1083Z" fill="white"/>
-<path d="M58.733 87.6254H54.5938V67.1543H65.9666V70.7108H58.733V75.9896H65.4645V79.5322H58.733V87.6254Z" fill="white"/>
-</svg>

From 8915b725ab81cc2e0914a0f6b7f240d2e3dff483 Mon Sep 17 00:00:00 2001
From: Quek Ruo Ling <ruoling.quek@ufinity.com>
Date: Fri, 17 Apr 2026 01:12:06 +0800
Subject: [PATCH 10/10] [MISC][RL] Update prop tables for clarity

---
 src/fullscreen-image-carousel/types.ts        |  8 +-
 .../fullscreen-image-carousel/props-table.tsx | 78 +++++++++++--------
 2 files changed, 48 insertions(+), 38 deletions(-)

diff --git a/src/fullscreen-image-carousel/types.ts b/src/fullscreen-image-carousel/types.ts
index 6352069f2..3cb19d334 100644
--- a/src/fullscreen-image-carousel/types.ts
+++ b/src/fullscreen-image-carousel/types.ts
@@ -27,7 +27,7 @@ export interface FullscreenImageCarouselProps
     insets?: Insets | undefined;
 }
 
-export interface FullscreenCarouselImageItemProps {
+export interface FullscreenImageCarouselImageItemProps {
     type?: "image" | undefined;
     src: string;
     alt?: string | undefined;
@@ -35,8 +35,8 @@ export interface FullscreenCarouselImageItemProps {
     renderContent?: never;
 }
 
-/** @deprecated Use FullscreenCarouselImageItemProps instead */
-export type FullscreenCarouselItemProps = FullscreenCarouselImageItemProps;
+/** @deprecated Use FullscreenImageCarouselImageItemProps instead */
+export type FullscreenCarouselItemProps = FullscreenImageCarouselImageItemProps;
 
 export interface FullscreenImageCarouselCustomItemProps {
     type: "custom";
@@ -49,7 +49,7 @@ export interface FullscreenImageCarouselCustomItemProps {
 }
 
 export type FullscreenImageCarouselItemProps =
-    | FullscreenCarouselImageItemProps
+    | FullscreenImageCarouselImageItemProps
     | FullscreenImageCarouselCustomItemProps;
 
 export interface ImageDimension {
diff --git a/stories/fullscreen-image-carousel/props-table.tsx b/stories/fullscreen-image-carousel/props-table.tsx
index 588cdeabb..f51824caa 100644
--- a/stories/fullscreen-image-carousel/props-table.tsx
+++ b/stories/fullscreen-image-carousel/props-table.tsx
@@ -112,38 +112,39 @@ const DATA: ApiTableSectionProps[] = [
         name: "FullscreenImageCarouselItemProps",
         attributes: [
             {
-                name: "type",
+                name: "",
                 description: (
                     <>
-                        Discriminant for the item type.{" "}
-                        <code>&quot;image&quot;</code> (or omitted) for image
-                        items, <code>&quot;custom&quot;</code> for custom
-                        content items
+                        One of
+                        <code>FullscreenImageCarouselImageItemProps</code> or
+                        <code>FullscreenImageCarouselCustomItemProps</code>
                     </>
                 ),
-                propTypes: [`"image" | "custom"`],
             },
+        ],
+    },
+    {
+        name: "FullscreenImageCarouselImageItemProps",
+        attributes: [
             {
-                name: "src",
+                name: "type",
                 description: (
                     <>
-                        The image src. Required for{" "}
-                        <code>FullscreenCarouselImageItemProps</code>. Not
-                        available on{" "}
-                        <code>FullscreenImageCarouselCustomItemProps</code>
+                        Discriminant for the item type. Must be{" "}
+                        <code>&quot;image&quot;</code> or omitted
                     </>
                 ),
+            },
+            {
+                name: "src",
+                description: "The image src",
+                mandatory: true,
                 propTypes: ["string"],
             },
             {
                 name: "alt",
-                description: (
-                    <>
-                        Descriptive text to be set on the image for screen
-                        readers. Only applicable for{" "}
-                        <code>FullscreenCarouselImageItemProps</code>
-                    </>
-                ),
+                description:
+                    "Descriptive text to be set on the image for screen readers",
                 propTypes: ["string"],
             },
             {
@@ -151,38 +152,47 @@ const DATA: ApiTableSectionProps[] = [
                 description: (
                     <>
                         The thumbnail image src. If not specified, the image{" "}
-                        <code>src</code> will be used. If neither is available,
-                        a placeholder is shown
+                        <code>src</code> will be used. If neither are valid, a
+                        placeholder is shown
                     </>
                 ),
                 propTypes: ["string"],
             },
+        ],
+    },
+    {
+        name: "FullscreenImageCarouselCustomItemProps",
+        attributes: [
             {
-                name: "itemLabel",
+                name: "type",
                 description: (
                     <>
-                        Label for this item used in aria-labels (e.g.{" "}
-                        <code>&quot;PDF&quot;</code>). Defaults to{" "}
-                        <code>&quot;image&quot;</code>. When any item sets this,
-                        carousel-level aria-labels switch to generic wording.
-                        Only applicable for{" "}
-                        <code>FullscreenImageCarouselCustomItemProps</code>
+                        Discriminant for the item type. Must be{" "}
+                        <code>&quot;custom&quot;</code>
                     </>
                 ),
+                mandatory: true,
+            },
+            {
+                name: "thumbnailSrc",
+                description:
+                    "The thumbnail image src. If not specified, a placeholder is shown",
                 propTypes: ["string"],
             },
             {
-                name: "renderContent",
+                name: "itemLabel",
                 description: (
                     <>
-                        Render prop for the full slide area. When provided, the
-                        item is treated as a{" "}
-                        <code>FullscreenImageCarouselCustomItemProps</code> and
-                        the consumer owns the entire slide content (e.g. an
-                        iframe, embed, or custom viewer). Zoom controls are
-                        hidden for custom slides
+                        Label to describe the type of content (e.g.{" "}
+                        <code>&quot;PDF&quot;</code>)
                     </>
                 ),
+                propTypes: ["string"],
+            },
+            {
+                name: "renderContent",
+                description: "Custom render prop for the full slide area",
+                mandatory: true,
                 propTypes: ["() => React.ReactNode"],
             },
         ],