Add new props to readers on StepperNumber component

Kubit · Kubit · commit 8d7be367f487 · 2024-10-12T10:15:24.000+02:00
diff --git a/src/components/stepperNumber/__test__/stepperNumber.test.tsx b/src/components/stepperNumber/__test__/stepperNumber.test.tsx
@@ -123,4 +123,45 @@ describe('StepperNumber component', () => {
     const firstStep = screen.getAllByText(StepperNumberSteps[0]);
     expect(firstStep.length).not.toBe(0);
   });
+
+  it('screenReaderTitle can be used as hidden title section of the stepper number', () => {
+    const screenReaderTitle = {
+      content: 'Stepper number title',
+    };
+
+    renderProvider(
+      <StepperNumber
+        {...mockProps}
+        orientation={StepperNumberOrientationType.VERTICAL}
+        screenReaderTextBuilder={undefined}
+        screenReaderTitle={screenReaderTitle}
+      />
+    );
+
+    const section = screen.getByLabelText(screenReaderTitle.content);
+    expect(section).toBeInTheDocument();
+  });
+
+  it('screenReaderCompletedStep, when vertical and no screenReaderTextBuilder, is used as screen reader text for the completed steps', () => {
+    const screenReaderTitle = {
+      content: 'Stepper number title',
+    };
+    const screenReaderCompletedStep = {
+      content: 'Completed step',
+    };
+
+    renderProvider(
+      <StepperNumber
+        {...mockProps}
+        currentStep={3}
+        orientation={StepperNumberOrientationType.VERTICAL}
+        screenReaderCompletedStep={screenReaderCompletedStep}
+        screenReaderTextBuilder={undefined}
+        screenReaderTitle={screenReaderTitle}
+      />
+    );
+
+    const completeSteps = screen.getAllByText(screenReaderCompletedStep.content);
+    expect(completeSteps.length).toBe(3);
+  });
 });
diff --git a/src/components/stepperNumber/stepperNumber.styled.ts b/src/components/stepperNumber/stepperNumber.styled.ts
@@ -1,5 +1,6 @@
 import styled, { css } from 'styled-components';
 
+import { srOnlyMixin } from '@/styles';
 import { getStyles } from '@/utils';
 
 import {
@@ -15,11 +16,11 @@ export const StepsContainerStyled = styled.ol<{ styles?: StepperNumberStateStyle
 `;
 
 export const BuilStepContainerStyled = styled.li<{
-  orientation: StepperNumberOrientationType;
+  $orientation: StepperNumberOrientationType;
   horizontalOrientationWidth?: string;
 }>`
-  ${({ orientation, horizontalOrientationWidth }) =>
-    orientation === StepperNumberOrientationType.VERTICAL
+  ${({ $orientation, horizontalOrientationWidth }) =>
+    $orientation === StepperNumberOrientationType.VERTICAL
       ? css`
           display: flex;
         `
@@ -28,36 +29,38 @@ export const BuilStepContainerStyled = styled.li<{
         `}
 `;
 
-export const StepContainerStyled = styled.div<{
+export const StepContainerStyled = styled.span<{
   styles?: StepperNumberStateStylesType;
   state: StepperNumberStateType;
 }>`
   ${({ styles, state }) => getStyles(styles?.[state]?.stepContainer)};
 `;
 
-export const StepCircleBarWrapperStyled = styled.div<{ orientation: StepperNumberOrientationType }>`
+export const StepCircleBarWrapperStyled = styled.span<{
+  $orientation: StepperNumberOrientationType;
+}>`
   display: flex;
-  flex-direction: ${({ orientation }) =>
-    orientation === StepperNumberOrientationType.VERTICAL ? 'column' : 'row'};
+  flex-direction: ${({ $orientation }) =>
+    $orientation === StepperNumberOrientationType.VERTICAL ? 'column' : 'row'};
   align-items: center;
   flex: 1;
 `;
 
-export const StepCircleStyled = styled.div<{
+export const StepCircleStyled = styled.span<{
   styles?: StepperNumberStateStylesType;
   state: StepperNumberStateType;
 }>`
   ${({ styles, state }) => getStyles(styles?.[state]?.stepCircle)};
 `;
 
-export const StepBarStyled = styled.div<{
+export const StepBarStyled = styled.span<{
   styles?: StepperNumberStateStylesType;
   state: StepperNumberStateType;
 }>`
   ${({ styles, state }) => getStyles(styles?.[state]?.stepBar)};
 `;
 
-export const StepperNumberContainerVerticalStep = styled.div<{
+export const StepperNumberContainerVerticalStep = styled.span<{
   styles?: StepperNumberStateStylesType;
   state: StepperNumberStateType;
   isLastStep: boolean;
@@ -66,3 +69,11 @@ export const StepperNumberContainerVerticalStep = styled.div<{
   ${({ styles, state, isLastStep }) =>
     isLastStep && getStyles(styles?.[state]?.stepNameContainer?.isLast)};
 `;
+
+export const ScreenReaderTitle = styled.h2`
+  ${srOnlyMixin}
+`;
+
+export const ScreenReaderCompletedStep = styled.span`
+  ${srOnlyMixin}
+`;
diff --git a/src/components/stepperNumber/stepperNumberStandAlone.tsx b/src/components/stepperNumber/stepperNumberStandAlone.tsx
@@ -3,11 +3,14 @@ import * as React from 'react';
 import { ScreenReaderOnly } from '@/components/screenReaderOnly';
 import { Text } from '@/components/text/text';
 import { TextComponentType } from '@/components/text/types/component';
+import { useId } from '@/hooks';
 
 import { ElementOrIcon } from '../elementOrIcon';
 import { buildAriaCurrent, buildScreenReaderText, mapToStepState } from './helpers';
 import {
   BuilStepContainerStyled,
+  ScreenReaderCompletedStep,
+  ScreenReaderTitle,
   StepBarStyled,
   StepCircleBarWrapperStyled,
   StepCircleStyled,
@@ -28,45 +31,69 @@ const StepperNumberStandAloneComponent = (
   { currentStep = defaultStep, ...props }: IStepperNumberStandAlone,
   ref: React.ForwardedRef<HTMLElement> | undefined | null
 ): JSX.Element => {
+  const id = useId('stepperNumber');
+  const screenReaderTitleId = `${id}ScreenReaderTitle`;
+  const ariaLabelledBy = props.screenReaderTitle?.content ? screenReaderTitleId : undefined;
   const steps = mapToStepState(props.steps, currentStep);
   const isVertical = props.orientation === StepperNumberOrientationType.VERTICAL;
 
+  const usingScreenReaderTextBuilder = Boolean(props.screenReaderTextBuilder);
+
   return (
     <StepperNumberContainerStyled
       ref={ref}
       aria-hidden={!isVertical}
       aria-label={props['aria-label']}
+      aria-labelledby={ariaLabelledBy}
       data-testid={`${props.dataTestId}StepsSection`}
     >
+      {props.screenReaderTitle?.content && (
+        <ScreenReaderTitle
+          as={props.screenReaderTitle.component}
+          data-testid={props.screenReaderTitle.dataTestId ?? `${props.dataTestId}ScreenReaderTitle`}
+          id={screenReaderTitleId}
+        >
+          {props.screenReaderTitle?.content}
+        </ScreenReaderTitle>
+      )}
       <StepsContainerStyled data-testid={`${props.dataTestId}StepsContainer`} styles={props.styles}>
         {steps.map((step, index) => {
           const isLastStep = index === steps.length - 1;
           return (
             <BuilStepContainerStyled
               key={'stepContainer' + index}
+              $orientation={props.orientation}
               aria-current={buildAriaCurrent(currentStep, index, props.orientation)}
               data-testid={`${props.dataTestId}Li${index}`}
               horizontalOrientationWidth={isLastStep ? 'auto' : props.horizontalOrientationWidth}
-              orientation={props.orientation}
             >
-              <ScreenReaderOnly dataTestId={`${props.dataTestId}ScreenReaderText${index}`}>
-                {buildScreenReaderText(
-                  index,
-                  currentStep,
-                  steps.length,
-                  props.screenReaderTextBuilder,
-                  step.name,
-                  isVertical
-                )}
-              </ScreenReaderOnly>
-              <StepContainerStyled aria-hidden={true} state={step.state} styles={props.styles}>
-                <StepCircleBarWrapperStyled orientation={props.orientation}>
+              {usingScreenReaderTextBuilder && (
+                <ScreenReaderOnly dataTestId={`${props.dataTestId}ScreenReaderText${index}`}>
+                  {buildScreenReaderText(
+                    index,
+                    currentStep,
+                    steps.length,
+                    props.screenReaderTextBuilder,
+                    step.name,
+                    isVertical
+                  )}
+                </ScreenReaderOnly>
+              )}
+              <StepContainerStyled
+                aria-hidden={!isVertical || usingScreenReaderTextBuilder ? true : undefined}
+                state={step.state}
+                styles={props.styles}
+              >
+                <StepCircleBarWrapperStyled $orientation={props.orientation}>
                   <StepCircleStyled state={step.state} styles={props.styles}>
                     {step.state === StepperNumberStateType.COMPLETED ? (
-                      <ElementOrIcon
-                        customIconStyles={props.styles?.[step.state]?.iconSelected}
-                        {...props.completedStepIcon}
-                      />
+                      <React.Fragment>
+                        <ElementOrIcon
+                          customIconStyles={props.styles?.[step.state]?.iconSelected}
+                          {...props.completedStepIcon}
+                        />
+                        <ScreenReaderOnly>{index + 1}</ScreenReaderOnly>
+                      </React.Fragment>
                     ) : (
                       <Text
                         component={TextComponentType.SPAN}
@@ -82,7 +109,7 @@ const StepperNumberStandAloneComponent = (
                 </StepCircleBarWrapperStyled>
                 {isVertical && (
                   <StepperNumberContainerVerticalStep
-                    aria-hidden={true}
+                    aria-hidden={usingScreenReaderTextBuilder ? true : undefined}
                     isLastStep={isLastStep}
                     state={step.state}
                     styles={props.styles}
@@ -94,6 +121,16 @@ const StepperNumberStandAloneComponent = (
                     >
                       {step.name}
                     </Text>
+                    {!usingScreenReaderTextBuilder &&
+                      step.state === StepperNumberStateType.COMPLETED &&
+                      props.screenReaderCompletedStep?.content && (
+                        <ScreenReaderCompletedStep
+                          as={props.screenReaderCompletedStep.component}
+                          data-testid={props.screenReaderCompletedStep.dataTestId}
+                        >
+                          &nbsp;{props.screenReaderCompletedStep.content}
+                        </ScreenReaderCompletedStep>
+                      )}
                   </StepperNumberContainerVerticalStep>
                 )}
               </StepContainerStyled>
diff --git a/src/components/stepperNumber/stories/argtypes.ts b/src/components/stepperNumber/stories/argtypes.ts
@@ -108,7 +108,28 @@ export const argtypes = (variants: IThemeObjectVariants, themeSelected: string):
         category: CATEGORY_CONTROL.ACCESIBILITY,
       },
     },
-
+    screenReaderTitle: {
+      description: 'Stepper number section title',
+      control: { type: 'object' },
+      type: { name: 'object' },
+      table: {
+        type: {
+          summary: 'StepperNumberScreenReaderTextType',
+        },
+        category: CATEGORY_CONTROL.ACCESIBILITY,
+      },
+    },
+    screenReaderCompletedStep: {
+      description: 'Screen reader text for completed step',
+      control: { type: 'object' },
+      type: { name: 'object' },
+      table: {
+        type: {
+          summary: 'StepperNumberScreenReaderTextType',
+        },
+        category: CATEGORY_CONTROL.ACCESIBILITY,
+      },
+    },
     dataTestId: {
       description: 'String used for testing',
       control: { type: 'text' },
diff --git a/src/components/stepperNumber/stories/stepperNumber.stories.tsx b/src/components/stepperNumber/stories/stepperNumber.stories.tsx
@@ -29,12 +29,13 @@ type Story = StoryObj<typeof meta> & { args: { themeArgs?: object } };
 
 const commonArgs: IStepperNumber = {
   variant: Object.values(variantsObject[themeSelected].StepperNumberVariantType || {})[0] as string,
-  orientation: StepperNumberOrientationType.HORIZONTAL,
+  orientation: StepperNumberOrientationType.VERTICAL,
   horizontalOrientationWidth: '5.75rem',
   completedStepIcon: { icon: ICONS.ICON_PLACEHOLDER },
-  steps: ['Step 1', 'Step 2', 'Step 3'],
+  steps: ['User Registration', 'Role Validation', 'Tutorial'],
   currentStep: 0,
-  ['aria-label']: 'ariaLabel',
+  screenReaderTitle: { content: 'Screen reader title' },
+  screenReaderCompletedStep: { content: 'COMPLETED' },
 };
 
 export const StepperNumber: Story = {
diff --git a/src/components/stepperNumber/types/stepperNumber.ts b/src/components/stepperNumber/types/stepperNumber.ts
@@ -1,4 +1,5 @@
 import { IElementOrIcon } from '@/components/elementOrIcon';
+import { IText } from '@/components/text';
 import { CustomTokenTypes } from '@/types';
 
 import { StepperNumberOrientationType } from './orientation';
@@ -14,6 +15,10 @@ export interface StepStateType {
   state: StepperNumberStateType;
 }
 
+export type StepperNumberScreenReaderTextType = Pick<IText<string>, 'component' | 'dataTestId'> & {
+  content?: string;
+};
+
 export interface IStepperNumberStandAlone {
   styles?: StepperNumberStateStylesType;
   orientation: StepperNumberOrientationType;
@@ -22,7 +27,12 @@ export interface IStepperNumberStandAlone {
   steps?: string[];
   currentStep?: number;
   ['aria-label']?: string;
+  /**
+   * @deprecated use screenReaderTitle and screenReaderCompletedStep instead
+   */
   screenReaderTextBuilder?: StepperNumberprefixSuffixType;
+  screenReaderTitle?: StepperNumberScreenReaderTextType;
+  screenReaderCompletedStep?: StepperNumberScreenReaderTextType;
   dataTestId?: string;
 }
 
