Merge pull request #6213 from limaagabriel/LPD-55597

feat(@clayui/autocomplete): LPD-55597 Improve infinite scrolling accessibility with SR announcements and visual feedback

Author: ethib137

packages/clay-autocomplete/package.json

@@ -31,6 +31,7 @@
 	],
 	"dependencies": {
 		"@clayui/core": "^3.155.0",
+		"@clayui/data-provider": "^3.151.0",
 		"@clayui/drop-down": "^3.155.0",
 		"@clayui/form": "^3.151.0",
 		"@clayui/loading-indicator": "^3.144.1",

packages/clay-autocomplete/src/Autocomplete.tsx

@@ -29,6 +29,7 @@ import React, {useCallback, useEffect, useMemo, useRef, useState} from 'react';
 
 import {AutocompleteContext} from './Context';
 import Item from './Item';
+import {useInfiniteScroll} from './useInfiniteScroll';
 
 import type {AnnouncerAPI, ICollectionProps} from '@clayui/core';
 import type {Locator} from '@clayui/shared';
@@ -45,6 +46,18 @@ type ItemProps<T extends Item> = {
 	keyValue: React.Key;
 };
 
+export type AutocompleteMessages = {
+	infiniteScrollInitialLoad?: string;
+	infiniteScrollInitialLoadPlural?: string;
+	infiniteScrollOnLoad?: string;
+	infiniteScrollOnLoaded?: string;
+	infiniteScrollOnLoadedPlural?: string;
+	listCount?: string;
+	listCountPlural?: string;
+	loading: string;
+	notFound: string;
+};
+
 export interface IProps<T>
 	extends Omit<
 			React.HTMLAttributes<HTMLInputElement>,
@@ -120,12 +133,7 @@ export interface IProps<T>
 	/**
 	 * Messages for the Autocomplete.
 	 */
-	messages?: {
-		listCount?: string;
-		listCountPlural?: string;
-		loading: string;
-		notFound: string;
-	};
+	messages?: AutocompleteMessages;
 
 	/**
 	 * Callback for when the active state changes (controlled).
@@ -203,7 +211,14 @@ function hasItem<T extends Item>(
 
 const ESCAPE_REGEXP = /[.*+?^${}()|[\]\\]/g;
 
-const defaultMessages = {
+const defaultMessages: Required<AutocompleteMessages> = {
+	infiniteScrollInitialLoad:
+		'{0} item loaded. Reach the last item to load more.',
+	infiniteScrollInitialLoadPlural:
+		'{0} items loaded. Reach the last item to load more.',
+	infiniteScrollOnLoad: 'Loading more items.',
+	infiniteScrollOnLoaded: '{0} item loaded.',
+	infiniteScrollOnLoadedPlural: '{0} items loaded.',
 	listCount: '{0} option available.',
 	listCountPlural: '{0} options available.',
 	loading: 'Loading...',
@@ -227,7 +242,7 @@ function AutocompleteInner<T extends Item>(
 		items: externalItems,
 		loadingState,
 		menuTrigger = 'input',
-		messages,
+		messages: externalMessages,
 		onActiveChange,
 		onChange,
 		onItemsChange,
@@ -239,9 +254,9 @@ function AutocompleteInner<T extends Item>(
 	}: IProps<T>,
 	ref: React.Ref<HTMLInputElement>
 ) {
-	messages = {
+	const messages = {
 		...defaultMessages,
-		...(messages ?? {}),
+		...(externalMessages ?? {}),
 	};
 
 	const [items, , isItemsUncontrolled] = useControlledState({
@@ -513,6 +528,15 @@ function AutocompleteInner<T extends Item>(
 	const optionCount = collection.getItems().length;
 	const lastSize = useRef(optionCount);
 
+	const InfiniteScrollFeedback = useInfiniteScroll({
+		active,
+		announcer: announcerAPI,
+		collection,
+		loadingState,
+		messages,
+		onLoadMore,
+	});
+
 	useEffect(() => {
 		// Only announces the number of options available when the menu is open
 		// if there is no item with focus, with the exception of Voice Over
@@ -736,6 +760,8 @@ function AutocompleteInner<T extends Item>(
 								)}
 							</Collection>
 						</AutocompleteContext.Provider>
+
+						<InfiniteScrollFeedback />
 					</div>
 				</Overlay>
 			)}

packages/clay-autocomplete/src/__tests__/IncrementalInteractions.tsx

@@ -4,7 +4,8 @@
  */
 
 import ClayAutocomplete from '..';
-import {cleanup, fireEvent, render} from '@testing-library/react';
+import {NetworkStatus} from '@clayui/data-provider';
+import {cleanup, fireEvent, render, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import React from 'react';
 
@@ -753,4 +754,107 @@ describe('Autocomplete incremental interactions', () => {
 			expect(onClickMock).toHaveBeenCalled();
 		});
 	});
+
+	describe('Infinite scroll interactions', () => {
+		it('calls onLoadMore when last item is active using keyboard', async () => {
+			const onLoadMore = jest.fn();
+
+			const {getByRole} = render(
+				<ClayAutocomplete onLoadMore={onLoadMore}>
+					{Array(20)
+						.fill(0)
+						.map((_, index) => (
+							<ClayAutocomplete.Item
+								key={index}
+								textValue={`Item ${index + 1}`}
+							>
+								Item {index + 1}
+							</ClayAutocomplete.Item>
+						))}
+				</ClayAutocomplete>
+			);
+
+			const combobox = getByRole('combobox');
+
+			userEvent.click(combobox);
+
+			expect(onLoadMore).not.toHaveBeenCalled();
+
+			// Navigates to the last item
+			userEvent.type(combobox, '{arrowup}');
+
+			await waitFor(() => {
+				expect(onLoadMore).toHaveBeenCalled();
+			});
+		});
+
+		it('announces count of initially loaded items and when more items are loaded', async () => {
+			const initialCount = 10;
+			const step = 5;
+
+			const TestComponent = () => {
+				const [count, setCount] = React.useState(initialCount);
+				const [networkStatus, setNetworkStatus] =
+					React.useState<NetworkStatus>(NetworkStatus.Unused);
+
+				const onLoadMore = jest.fn().mockImplementation(() => {
+					return new Promise<void>((resolve) => {
+						setNetworkStatus(NetworkStatus.Loading);
+
+						setTimeout(() => {
+							setCount((count) => count + step);
+							setNetworkStatus(NetworkStatus.Unused);
+							resolve();
+						}, 100);
+					});
+				});
+
+				return (
+					<ClayAutocomplete
+						loadingState={networkStatus}
+						onLoadMore={onLoadMore}
+					>
+						{Array(count)
+							.fill(0)
+							.map((_, index) => (
+								<ClayAutocomplete.Item
+									key={index}
+									textValue={`Item ${index + 1}`}
+								>
+									Item {index + 1}
+								</ClayAutocomplete.Item>
+							))}
+					</ClayAutocomplete>
+				);
+			};
+
+			const {getAllByRole, getByRole} = render(<TestComponent />);
+
+			const combobox = getByRole('combobox');
+
+			userEvent.click(combobox);
+
+			// Display the listbox
+			userEvent.type(combobox, '{arrowdown}');
+
+			const [announcer] = getAllByRole('log');
+
+			await waitFor(() => {
+				expect(announcer?.innerHTML).toContain(
+					`${initialCount} items loaded. Reach the last item to load more.`
+				);
+			});
+
+			// Navigates to the last item
+			userEvent.type(combobox, '{arrowup}');
+
+			await waitFor(() => {
+				expect(announcer?.innerHTML).toContain(`Loading more items.`);
+
+				expect(announcer?.innerHTML).toContain(
+					`${initialCount + step} items loaded.`
+				);
+			});
+		});
+	});
 });

packages/clay-autocomplete/src/useInfiniteScroll.tsx

@@ -0,0 +1,100 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Liferay, Inc. <https://liferay.com>
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+import {AnnouncerAPI} from '@clayui/core';
+import {CollectionState} from '@clayui/core/src/collection/types';
+import {NetworkStatus} from '@clayui/data-provider';
+import LoadingIndicator from '@clayui/loading-indicator';
+import {sub} from '@clayui/shared';
+import React, {RefObject, useCallback, useEffect, useRef} from 'react';
+
+import {AutocompleteMessages} from './Autocomplete';
+
+interface IProps {
+	/**
+	 * Reference to the announcer API.
+	 */
+	announcer: RefObject<AnnouncerAPI>;
+
+	/**
+	 * Flag to indicate if the autocomplete is active (i.e., the menu is open)
+	 */
+	active: boolean;
+
+	/**
+	 * The collection state of the autocomplete items.
+	 */
+	collection: CollectionState;
+
+	/**
+	 * Loading state of the autocomplete.
+	 */
+	loadingState?: number;
+
+	/**
+	 * Localized messages for the autocomplete.
+	 */
+	messages: Required<AutocompleteMessages>;
+
+	/**
+	 * Callback function to load more items.
+	 */
+	onLoadMore?: () => Promise<any> | null;
+}
+
+export function useInfiniteScroll({
+	active,
+	announcer,
+	collection,
+	loadingState = NetworkStatus.Unused,
+	messages,
+	onLoadMore,
+}: IProps) {
+	const currentCount = collection.getSize();
+	const isInfiniteScrollEnabled = Boolean(onLoadMore);
+	const isLoading = Boolean(loadingState < NetworkStatus.Unused);
+
+	const isInitialLoadAnnouncementPending = useRef<boolean>(
+		isInfiniteScrollEnabled
+	);
+	const lastCountAnnounced = useRef<number | null>(null);
+
+	useEffect(() => {
+		if (active) {
+			if (isLoading) {
+				announcer.current?.announce(messages.infiniteScrollOnLoad);
+				lastCountAnnounced.current = null;
+			} else if (lastCountAnnounced.current !== currentCount) {
+				const singular = isInitialLoadAnnouncementPending.current
+					? messages.infiniteScrollInitialLoad
+					: messages.infiniteScrollOnLoaded;
+
+				const plural = isInitialLoadAnnouncementPending.current
+					? messages.infiniteScrollInitialLoadPlural
+					: messages.infiniteScrollOnLoadedPlural;
+
+				const message = sub(currentCount === 1 ? singular : plural, [
+					currentCount,
+				]);
+
+				announcer.current?.announce(message);
+				lastCountAnnounced.current = currentCount;
+				isInitialLoadAnnouncementPending.current = false;
+			}
+		} else {
+			isInitialLoadAnnouncementPending.current = isInfiniteScrollEnabled;
+		}
+	}, [active, isLoading, currentCount]);
+
+	const InfiniteScrollFeedback = useCallback(
+		() =>
+			isInfiniteScrollEnabled && isLoading ? (
+				<LoadingIndicator className="my-2" size="sm" />
+			) : null,
+		[isInfiniteScrollEnabled, isLoading]
+	);
+
+	return InfiniteScrollFeedback;
+}