[WC-2599] Add item description for Gallery (#1577)

Author: r0b1n

packages/pluggableWidgets/gallery-web/CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Added
+
+- We added an option to specify item descriptions in the gallery widget, improving accessibility for screen reader users.
+
 ## [1.13.0] - 2024-11-13
 
 ### Fixed

packages/pluggableWidgets/gallery-web/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@mendix/gallery-web",
     "widgetName": "Gallery",
-    "version": "1.14.0",
+    "version": "1.14.1",
     "description": "A flexible gallery widget that renders columns, rows and layouts.",
     "copyright": "© Mendix Technology BV 2025. All rights reserved.",
     "license": "Apache-2.0",

packages/pluggableWidgets/gallery-web/src/Gallery.tsx

@@ -13,6 +13,7 @@ import { useItemSelectHelper } from "./helpers/useItemSelectHelper";
 import { useRootGalleryStore } from "./helpers/useRootGalleryStore";
 import { RootGalleryStore } from "./stores/RootGalleryStore";
 import { HeaderContainer } from "./components/HeaderContainer";
+import { ObjectItem } from "mendix";
 
 interface RootAPI {
     rootStore: RootGalleryStore;
@@ -97,6 +98,7 @@ function Container(props: GalleryContainerProps & RootAPI): ReactElement {
             }
             headerTitle={props.filterSectionTitle?.value}
             ariaLabelListBox={props.ariaLabelListBox?.value}
+            ariaLabelItem={(item: ObjectItem) => props.ariaLabelItem?.get(item).value}
             showHeader={showHeader}
             hasMoreItems={props.datasource.hasMoreItems ?? false}
             items={items}

packages/pluggableWidgets/gallery-web/src/Gallery.xml

@@ -184,6 +184,10 @@
                     <caption>Content description</caption>
                     <description>Assistive technology will read this upon reaching gallery.</description>
                 </property>
+                <property key="ariaLabelItem" type="textTemplate" dataSource="datasource" required="false">
+                    <caption>Item description</caption>
+                    <description>Assistive technology will read this upon reaching each gallery item.</description>
+                </property>
             </propertyGroup>
         </propertyGroup>
     </properties>

packages/pluggableWidgets/gallery-web/src/components/Gallery.tsx

@@ -37,6 +37,7 @@ export interface GalleryProps<T extends ObjectItem> {
     tabletItems: number;
     tabIndex?: number;
     ariaLabelListBox?: string;
+    ariaLabelItem?: (item: T) => string | undefined;
     preview?: boolean;
 
     // Helpers
@@ -96,6 +97,7 @@ export function Gallery<T extends ObjectItem>(props: GalleryProps<T>): ReactElem
                                     eventsController={props.itemEventsController}
                                     getPosition={props.getPosition}
                                     itemIndex={index}
+                                    label={props.ariaLabelItem?.(item)}
                                 />
                             ))}
                         </KeyNavProvider>

packages/pluggableWidgets/gallery-web/src/components/ListItem.tsx

@@ -16,12 +16,13 @@ type ListItemProps = Omit<JSX.IntrinsicElements["div"], "ref" | "role"> & {
     itemIndex: number;
     selectHelper: SelectActionHandler;
     preview?: boolean;
+    label?: string;
 };
 
 export function ListItem(props: ListItemProps): ReactElement {
-    const { eventsController, getPosition, helper, item, itemIndex, selectHelper, ...rest } = props;
+    const { eventsController, getPosition, helper, item, itemIndex, selectHelper, label, ...rest } = props;
     const clickable = helper.hasOnClick(item) || selectHelper.selectionType !== "None";
-    const ariaProps = getAriaProps(item, selectHelper);
+    const ariaProps = getAriaProps(item, selectHelper, label);
     const { columnIndex, rowIndex } = getPosition(itemIndex);
     const keyNavProps = useFocusTargetProps({ columnIndex: columnIndex ?? -1, rowIndex });
     const handlers = useMemo(() => eventsController.getProps(item), [eventsController, item]);

packages/pluggableWidgets/gallery-web/src/components/__tests__/Gallery.spec.tsx

@@ -6,6 +6,7 @@ import { Gallery } from "../Gallery";
 import { ItemHelperBuilder } from "../../utils/builders/ItemHelperBuilder";
 import { mockProps, mockItemHelperWithAction, setup } from "../../utils/test-utils";
 import "./__mocks__/intersectionObserverMock";
+import { ObjectItem } from "mendix";
 
 describe("Gallery", () => {
     describe("DOM Structure", () => {
@@ -133,7 +134,7 @@ describe("Gallery", () => {
     });
 
     describe("with accessibility properties", () => {
-        it("renders correctly", () => {
+        it("renders correctly without items", () => {
             const { asFragment } = render(
                 <Gallery
                     {...mockProps()}
@@ -146,6 +147,21 @@ describe("Gallery", () => {
 
             expect(asFragment()).toMatchSnapshot();
         });
+
+        it("renders correctly with items", () => {
+            const { asFragment } = render(
+                <Gallery
+                    {...mockProps()}
+                    items={[{ id: "1" } as ObjectItem, { id: "2" } as ObjectItem, { id: "3" } as ObjectItem]}
+                    ariaLabelItem={(item: ObjectItem) => `title for '${item.id}'`}
+                    headerTitle="filter title"
+                    emptyMessageTitle="empty message"
+                    emptyPlaceholderRenderer={renderWrapper => renderWrapper(<span>No items found</span>)}
+                />
+            );
+
+            expect(asFragment()).toMatchSnapshot();
+        });
     });
 
     describe("without filters", () => {

packages/pluggableWidgets/gallery-web/src/components/__tests__/__snapshots__/Gallery.spec.tsx.snap

@@ -115,7 +115,60 @@ exports[`Gallery DOM Structure renders correctly with onclick event 1`] = `
 </DocumentFragment>
 `;
 
-exports[`Gallery with accessibility properties renders correctly 1`] = `
+exports[`Gallery with accessibility properties renders correctly with items 1`] = `
+<DocumentFragment>
+  <div
+    class="widget-gallery my-gallery"
+    data-focusindex="0"
+  >
+    <section
+      aria-label="filter title"
+      class="widget-gallery-header widget-gallery-filter"
+    >
+      <input />
+    </section>
+    <div
+      class="widget-gallery-content infinite-loading"
+    >
+      <div
+        aria-label="Mock props ListBox aria label"
+        class="widget-gallery-items widget-gallery-lg-4 widget-gallery-md-3 widget-gallery-sm-2"
+        role="list"
+      >
+        <div
+          aria-label="title for '1'"
+          class="widget-gallery-item item-class"
+          data-position="0,0"
+          role="listitem"
+          tabindex="0"
+        >
+          Item content
+        </div>
+        <div
+          aria-label="title for '2'"
+          class="widget-gallery-item item-class"
+          data-position="1,0"
+          role="listitem"
+          tabindex="-1"
+        >
+          Item content
+        </div>
+        <div
+          aria-label="title for '3'"
+          class="widget-gallery-item item-class"
+          data-position="2,0"
+          role="listitem"
+          tabindex="-1"
+        >
+          Item content
+        </div>
+      </div>
+    </div>
+  </div>
+</DocumentFragment>
+`;
+
+exports[`Gallery with accessibility properties renders correctly without items 1`] = `
 <DocumentFragment>
   <div
     class="widget-gallery my-gallery"

packages/pluggableWidgets/gallery-web/src/features/item-interaction/get-item-aria-props.ts

@@ -7,20 +7,23 @@ type ListItemAriaProps = {
     role: ListItemRole;
     "aria-selected": boolean | undefined;
     tabIndex: number | undefined;
+    "aria-label": string | undefined;
 };
 
-export function getAriaProps(item: ObjectItem, helper: SelectActionHandler): ListItemAriaProps {
+export function getAriaProps(item: ObjectItem, helper: SelectActionHandler, label?: string): ListItemAriaProps {
     if (helper.selectionType === "Single" || helper.selectionType === "Multi") {
         return {
             role: "option",
             "aria-selected": helper.isSelected(item),
-            tabIndex: 0
+            tabIndex: 0,
+            "aria-label": label
         };
     }
 
     return {
         role: "listitem",
         "aria-selected": undefined,
-        tabIndex: undefined
+        tabIndex: undefined,
+        "aria-label": label
     };
 }

packages/pluggableWidgets/gallery-web/src/package.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8" ?>
 <package xmlns="http://www.mendix.com/package/1.0/">
-    <clientModule name="Gallery" version="1.14.0" xmlns="http://www.mendix.com/clientModule/1.0/">
+    <clientModule name="Gallery" version="1.14.1" xmlns="http://www.mendix.com/clientModule/1.0/">
         <widgetFiles>
             <widgetFile path="Gallery.xml" />
         </widgetFiles>