diff --git a/packages/pluggableWidgets/intro-screen-native/CHANGELOG.md b/packages/pluggableWidgets/intro-screen-native/CHANGELOG.md index beb7e5f2e..dad5a80ec 100644 --- a/packages/pluggableWidgets/intro-screen-native/CHANGELOG.md +++ b/packages/pluggableWidgets/intro-screen-native/CHANGELOG.md @@ -10,6 +10,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - The IntroScreen is now presented through the shared MxOverlay component. Its appearance and behaviour, including blocking the Android back button, are unchanged. +### Added + +- We added an "Accessibility" group with a label for the slide position announcement, and an accessibility label for each of the Skip, Previous, Next and Done buttons, so screen reader text can be translated. + ### Fixed - We fixed an issue where the IntroScreen did not show the slide set by the active slide attribute, and where swiping between slides did not work reliably on slower Android devices. @@ -19,6 +23,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - Updated react-native from version v0.84.1 to v0.88.0. +- We fixed an issue where screen readers (TalkBack and VoiceOver) read out every pagination dot as a separate button. The dots are now announced once as a page indicator (for example "Slide 2 of 4"), which can be adjusted to change slide. + ## [4.4.1] - 2026-6-10 ### Changed diff --git a/packages/pluggableWidgets/intro-screen-native/package.json b/packages/pluggableWidgets/intro-screen-native/package.json index 23901140a..db4290617 100644 --- a/packages/pluggableWidgets/intro-screen-native/package.json +++ b/packages/pluggableWidgets/intro-screen-native/package.json @@ -1,7 +1,7 @@ { "name": "intro-screen-native", "widgetName": "IntroScreen", - "version": "4.6.0", + "version": "4.6.1", "license": "Apache-2.0", "repository": { "type": "git", diff --git a/packages/pluggableWidgets/intro-screen-native/src/IntroScreen.tsx b/packages/pluggableWidgets/intro-screen-native/src/IntroScreen.tsx index 0bed8ea0e..2770b7e0b 100644 --- a/packages/pluggableWidgets/intro-screen-native/src/IntroScreen.tsx +++ b/packages/pluggableWidgets/intro-screen-native/src/IntroScreen.tsx @@ -100,12 +100,17 @@ export function IntroScreen(props: IntroScreenProps): JSX.Elem hidePagination={props.slideIndicators === "never"} skipLabel={checkLabel(props.skipCaption)} skipIcon={props.skipIcon} + skipAccessibilityLabel={checkLabel(props.skipAccessibilityLabel)} previousLabel={checkLabel(props.previousCaption)} previousIcon={props.previousIcon} + previousAccessibilityLabel={checkLabel(props.previousAccessibilityLabel)} nextLabel={checkLabel(props.nextCaption)} nextIcon={props.nextIcon} + nextAccessibilityLabel={checkLabel(props.nextAccessibilityLabel)} doneLabel={checkLabel(props.doneCaption)} doneIcon={props.doneIcon} + doneAccessibilityLabel={checkLabel(props.doneAccessibilityLabel)} + slidePositionLabel={checkLabel(props.slidePositionLabel)} styles={styles} activeSlide={props.activeSlideAttribute} hideIndicatorLastSlide={props.hideIndicatorLastSlide} diff --git a/packages/pluggableWidgets/intro-screen-native/src/IntroScreen.xml b/packages/pluggableWidgets/intro-screen-native/src/IntroScreen.xml index d06966b31..08b11ef72 100644 --- a/packages/pluggableWidgets/intro-screen-native/src/IntroScreen.xml +++ b/packages/pluggableWidgets/intro-screen-native/src/IntroScreen.xml @@ -1,8 +1,5 @@ - + Intro screen Display @@ -21,7 +18,7 @@ Content - + @@ -47,7 +44,7 @@ Show indicator - + Between buttons Above buttons @@ -63,50 +60,72 @@ If this value is set, the intro screens will automatically be shown the first time the user opens the current page. This identifier is used to store locally whether the intro screen with this identifier is already shown. When the identifier is changed, the intro screen will be shown again for one time. + + + Slide position label + Read out by screen readers for the slide indicator and when the slide changes. If left empty, the current slide number and the total number of slides are read out. + + - + Caption - + Icon - + + + + Accessibility label + Read out by screen readers. Defaults to the caption, or to "Skip" when there is no caption. Caption - + Icon - + + + + Accessibility label + Read out by screen readers. Defaults to the caption, or to "Previous" when there is no caption. Caption - + Icon - + + + + Accessibility label + Read out by screen readers. Defaults to the caption, or to "Next" when there is no caption. Caption - + Icon - + + + + Accessibility label + Read out by screen readers. Defaults to the caption, or to "Done" when there is no caption. diff --git a/packages/pluggableWidgets/intro-screen-native/src/SwipeableContainer.tsx b/packages/pluggableWidgets/intro-screen-native/src/SwipeableContainer.tsx index f2d3272ba..7775a9d5b 100644 --- a/packages/pluggableWidgets/intro-screen-native/src/SwipeableContainer.tsx +++ b/packages/pluggableWidgets/intro-screen-native/src/SwipeableContainer.tsx @@ -1,5 +1,7 @@ import { Fragment, ReactElement, ReactNode, useCallback, useEffect, useRef, useState } from "react"; import { + AccessibilityActionEvent, + AccessibilityInfo, I18nManager, LayoutChangeEvent, Platform, @@ -20,12 +22,17 @@ interface SwipeableContainerProps { testID?: string; skipLabel?: string; skipIcon?: DynamicValue; + skipAccessibilityLabel?: string; doneLabel?: string; doneIcon?: DynamicValue; + doneAccessibilityLabel?: string; nextLabel?: string; nextIcon?: DynamicValue; + nextAccessibilityLabel?: string; previousLabel?: string; previousIcon?: DynamicValue; + previousAccessibilityLabel?: string; + slidePositionLabel?: string; showDoneButton: boolean; showSkipButton: boolean; showNextButton: boolean; @@ -54,6 +61,10 @@ const VIEWABILITY_CONFIG = { minimumViewTime: 250 } as const; +// A configured label is spoken as-is; otherwise the position is spelled out +const getSlidePositionLabel = (label: Option, current: number, total: number): string => + label || `Slide ${current} of ${total}`; + const refreshActiveSlideAttribute = (slides: SlidesType[], activeSlide?: EditableValue): number => { if (activeSlide && activeSlide.value !== undefined && slides && slides.length > 0) { const slide = Number(activeSlide.value) - 1; @@ -76,6 +87,7 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement const flashList = useRef>(null); const pendingWrite = useRef<{ replaced: number } | null>(null); const isUserScrolling = useRef(false); + const [reduceMotion, setReduceMotion] = useState(false); const activeSlidePending = props.activeSlide?.status === ValueStatus.Loading && props.activeSlide.value === undefined; @@ -91,6 +103,16 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement } }, [listMounted, activeSlidePending, props.slides, props.activeSlide, activeIndex]); + useEffect(() => { + let isMounted = true; + AccessibilityInfo.isReduceMotionEnabled().then(enabled => isMounted && setReduceMotion(enabled)); + const subscription = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduceMotion); + return () => { + isMounted = false; + subscription.remove(); + }; + }, []); + const rtlSafeIndex = useCallback( (i: number): number => (isAndroidRTL ? props.slides.length - 1 - i : i), [props.slides.length] @@ -101,11 +123,12 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement setActiveIndex(pageNum); if (width > 0 && flashList && flashList.current) { flashList.current.scrollToOffset({ - offset: rtlSafeIndex(pageNum) * width + offset: rtlSafeIndex(pageNum) * width, + animated: !reduceMotion }); } }, - [rtlSafeIndex, width] + [rtlSafeIndex, width, reduceMotion] ); useEffect(() => { @@ -132,14 +155,22 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement } }, [props.activeSlide, activeIndex, width, props.slides, rtlSafeIndex]); + // Focus stays on the pressed button, so the new slide is announced explicitly for screen reader users + const announceSlide = (index: number): void => + AccessibilityInfo.announceForAccessibility( + getSlidePositionLabel(props.slidePositionLabel, index + 1, props.slides.length) + ); + const onNextPress = (): void => { goToSlide(activeIndex + 1); onSlideChange(activeIndex + 1, activeIndex); + announceSlide(activeIndex + 1); }; const onPrevPress = (): void => { goToSlide(activeIndex - 1); onSlideChange(activeIndex - 1, activeIndex); + announceSlide(activeIndex - 1); }; const onPaginationPress = (index: number): void => { @@ -166,6 +197,7 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement const renderButton = ( caption: Option, + accessibilityLabel: string, icon: Option>, defaultIcon: string, style: ButtonStyle, @@ -202,7 +234,12 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement : {}; return ( - + {iconContent} {caption && {caption}} @@ -228,12 +265,14 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement const renderNextButton = ({ showNextButton = true, nextLabel, + nextAccessibilityLabel, nextIcon, styles }: SwipeableContainerProps): ReactNode => showNextButton && renderButton( nextLabel, + nextAccessibilityLabel || nextLabel || "Next", nextIcon, "chevron-right", props.bottomButton ? styles.paginationAbove.buttonNext : styles.paginationBetween.buttonNext, @@ -244,12 +283,14 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement const renderPrevButton = ({ showPreviousButton, previousLabel, + previousAccessibilityLabel, previousIcon, styles }: SwipeableContainerProps): ReactNode => showPreviousButton && renderButton( previousLabel, + previousAccessibilityLabel || previousLabel || "Previous", previousIcon, "chevron-left", props.bottomButton ? styles.paginationAbove.buttonPrevious : styles.paginationBetween.buttonPrevious, @@ -260,6 +301,7 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement const renderDoneButton = ({ showDoneButton = true, doneLabel, + doneAccessibilityLabel, doneIcon, onDone, styles @@ -267,6 +309,7 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement showDoneButton && renderButton( doneLabel, + doneAccessibilityLabel || doneLabel || "Done", doneIcon, "ok", props.bottomButton ? styles.paginationAbove.buttonDone : styles.paginationBetween.buttonDone, @@ -277,6 +320,7 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement const renderSkipButton = ({ showSkipButton, skipLabel, + skipAccessibilityLabel, skipIcon, onSkip, slides, @@ -285,6 +329,7 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement showSkipButton && renderButton( skipLabel, + skipAccessibilityLabel || skipLabel || "Skip", skipIcon, "remove", props.bottomButton ? styles.paginationAbove.buttonSkip : styles.paginationBetween.buttonSkip, @@ -300,34 +345,59 @@ export const SwipeableContainer = (props: SwipeableContainerProps): ReactElement const rightButton = isLastSlide ? renderDoneButton(props) : renderNextButton(props); const paginationOverflow = props.slides.length > 5; const hidePagination = props.hidePagination || (isLastSlide && props.hideIndicatorLastSlide); + const showDots = !hidePagination && !paginationOverflow && props.slides.length > 1; + // The dots are exposed to screen readers as one adjustable element instead of one button per dot, + // so Next/Previous are reached directly. Swiping up/down on it still changes slide. + // The position is the label only: min/max/now would make TalkBack read the bare number as well. + const indicatorAccessibilityProps = { + accessible: true, + accessibilityRole: "adjustable" as const, + accessibilityLabel: getSlidePositionLabel(props.slidePositionLabel, activeIndex + 1, props.slides.length), + accessibilityActions: [{ name: "increment" }, { name: "decrement" }], + onAccessibilityAction: (event: AccessibilityActionEvent): void => { + const target = event.nativeEvent.actionName === "increment" ? activeIndex + 1 : activeIndex - 1; + if (target >= 0 && target < props.slides.length) { + onPaginationPress(target); + } + } + }; return ( {!props.bottomButton && leftButton} - - {!hidePagination && - !paginationOverflow && - props.slides.length > 1 && - props.slides.map((_, i) => ( - onPaginationPress(i)} - accessibilityRole="button" - accessibilityLabel={`Go to slide ${i + 1}`} - accessibilityState={{ selected: rtlSafeIndex(i) === activeIndex }} - /> - ))} - {!hidePagination && paginationOverflow && ( - - {activeIndex + 1}/{props.slides.length} - + + + {showDots && + props.slides.map((_, i) => ( + onPaginationPress(i)} + accessible={false} + // accessible={false} alone does not stop TalkBack from focusing a pressable dot + importantForAccessibility="no-hide-descendants" + accessibilityElementsHidden + /> + ))} + {!hidePagination && paginationOverflow && ( + + {activeIndex + 1}/{props.slides.length} + + )} + + {showDots && ( + // Screen reader node on its own, with no children, so TalkBack has nothing to step into + )} {!props.bottomButton && rightButton} diff --git a/packages/pluggableWidgets/intro-screen-native/src/__tests__/IntroScreen.spec.tsx b/packages/pluggableWidgets/intro-screen-native/src/__tests__/IntroScreen.spec.tsx index 123875a91..5f4eb794f 100644 --- a/packages/pluggableWidgets/intro-screen-native/src/__tests__/IntroScreen.spec.tsx +++ b/packages/pluggableWidgets/intro-screen-native/src/__tests__/IntroScreen.spec.tsx @@ -2,9 +2,10 @@ import { render, act, fireEvent, RenderAPI } from "@testing-library/react-native import { IntroScreen } from "../IntroScreen"; import { IntroScreenProps } from "../../typings/IntroScreenProps"; import { IntroScreenStyle } from "../ui/Styles"; -import { Modal, View } from "react-native"; +import { AccessibilityInfo, Modal, ScrollView, View } from "react-native"; import { EditableValueBuilder } from "@mendix/piw-utils-internal"; import { Big } from "big.js"; +import { DynamicValue, ValueStatus } from "mendix"; jest.mock("react-native-device-info", () => ({ hasNotch: jest.fn(), @@ -16,6 +17,8 @@ jest.mock("@react-native-async-storage/async-storage", () => ({ setItem: jest.fn().mockResolvedValue(null) })); +const dynamicValue = (value: string): DynamicValue => ({ status: ValueStatus.Available, value }); + const layout = (component: RenderAPI, name: string): void => { fireEvent(component.getByTestId(name), "layout", { nativeEvent: { layout: { width: 400, height: 800 } } @@ -340,4 +343,123 @@ describe("Intro Screen", () => { expect(component.getByTestId("intro-screen-test").props.initialScrollIndex).toBe(0); }); }); + + describe("page indicator accessibility", () => { + const slides = [1, 2, 3].map(n => ({ name: `Page ${n}`, content: })); + const adjust = (component: RenderAPI, actionName: string): void => { + fireEvent(component.getByRole("adjustable"), "accessibilityAction", { + nativeEvent: { actionName } + }); + }; + + it("exposes the dots as one adjustable element and hides the individual dots", () => { + const component = render(); + layout(component, "intro-screen-test"); + + const indicator = component.getByRole("adjustable"); + expect(indicator.props.accessibilityRole).toBe("adjustable"); + expect(indicator.props.accessibilityLabel).toBe("Slide 1 of 3"); + expect(indicator.props.accessibilityValue).toBeUndefined(); + [0, 1, 2].forEach(i => { + const dot = component.getByTestId(`intro-screen-test$dot${i}`, { hidden: true }); + expect(dot.props.accessible).toBe(false); + expect(dot.props.importantForAccessibility).toBe("no-hide-descendants"); + expect(dot.props.accessibilityElementsHidden).toBe(true); + }); + }); + + it("changes slide on increment and decrement and stays within range", () => { + const component = render(); + layout(component, "intro-screen-test"); + + adjust(component, "decrement"); + expect(component.getByRole("adjustable").props.accessibilityLabel).toBe("Slide 1 of 3"); + + adjust(component, "increment"); + expect(component.getByRole("adjustable").props.accessibilityLabel).toBe("Slide 2 of 3"); + + adjust(component, "increment"); + adjust(component, "increment"); + expect(component.getByRole("adjustable").props.accessibilityLabel).toBe("Slide 3 of 3"); + + adjust(component, "decrement"); + expect(component.getByRole("adjustable").props.accessibilityLabel).toBe("Slide 2 of 3"); + }); + + it("speaks a configured label as-is", () => { + const component = render( + + ); + layout(component, "intro-screen-test"); + + expect(component.getByRole("adjustable").props.accessibilityLabel).toBe("Onboarding progress"); + }); + }); + + describe("buttons accessibility", () => { + const slides = [1, 2, 3].map(n => ({ name: `Page ${n}`, content: })); + + it("labels icon-only buttons with a default and prefers a configured label or caption", () => { + const component = render( + + ); + layout(component, "intro-screen-test"); + + const next = component.getByTestId("intro-screen-test$buttonNext"); + expect(next.props.accessibilityRole).toBe("button"); + expect(next.props.accessibilityLabel).toBe("Volgende slide"); + expect(component.getByTestId("intro-screen-test$buttonSkip").props.accessibilityLabel).toBe("Overslaan"); + + fireEvent.press(next); + expect(component.getByTestId("intro-screen-test$buttonPrevious").props.accessibilityLabel).toBe("Previous"); + }); + }); + + describe("screen reader announcements and reduce motion", () => { + const slides = [1, 2, 3].map(n => ({ name: `Page ${n}`, content: })); + + afterEach(() => jest.restoreAllMocks()); + + it("announces the new slide after Next and Previous, but not after using the indicator", () => { + const announce = jest.spyOn(AccessibilityInfo, "announceForAccessibility"); + const component = render(); + layout(component, "intro-screen-test"); + + fireEvent.press(component.getByTestId("intro-screen-test$buttonNext")); + expect(announce).toHaveBeenLastCalledWith("Slide 2 of 3"); + + fireEvent.press(component.getByTestId("intro-screen-test$buttonPrevious")); + expect(announce).toHaveBeenLastCalledWith("Slide 1 of 3"); + + announce.mockClear(); + fireEvent(component.getByRole("adjustable"), "accessibilityAction", { + nativeEvent: { actionName: "increment" } + }); + expect(announce).not.toHaveBeenCalled(); + }); + + it.each([ + [false, true], + [true, false] + ])("with reduce motion %s scrolls with animated %s", async (reduceMotion, animated) => { + jest.spyOn(AccessibilityInfo, "isReduceMotionEnabled").mockResolvedValue(reduceMotion); + const scrollTo = jest.spyOn(ScrollView.prototype, "scrollTo").mockImplementation(() => undefined); + const component = render(); + await act(async () => {}); + layout(component, "intro-screen-test"); + + fireEvent.press(component.getByTestId("intro-screen-test$buttonNext")); + + expect(scrollTo).toHaveBeenCalledWith(expect.objectContaining({ animated })); + }); + }); }); diff --git a/packages/pluggableWidgets/intro-screen-native/src/__tests__/__snapshots__/IntroScreen.notch.spec.tsx.snap b/packages/pluggableWidgets/intro-screen-native/src/__tests__/__snapshots__/IntroScreen.notch.spec.tsx.snap index 599e5a00e..f12e9f15b 100644 --- a/packages/pluggableWidgets/intro-screen-native/src/__tests__/__snapshots__/IntroScreen.notch.spec.tsx.snap +++ b/packages/pluggableWidgets/intro-screen-native/src/__tests__/__snapshots__/IntroScreen.notch.spec.tsx.snap @@ -223,19 +223,26 @@ exports[`Intro Screen renders 1`] = ` > + + } + } + /> + + + } + } + /> + + + } + } + /> + + + } + } + /> + + + } + } + /> + + + } + } + /> + + + } + } + /> + + + } + } + /> + + + } + } + /> + + + } + } + /> + - + diff --git a/packages/pluggableWidgets/intro-screen-native/typings/IntroScreenProps.d.ts b/packages/pluggableWidgets/intro-screen-native/typings/IntroScreenProps.d.ts index 1ad02ea17..70820c459 100644 --- a/packages/pluggableWidgets/intro-screen-native/typings/IntroScreenProps.d.ts +++ b/packages/pluggableWidgets/intro-screen-native/typings/IntroScreenProps.d.ts @@ -32,14 +32,19 @@ export interface IntroScreenProps