Stepper accessibility fixes

docs/src/documentation/03-components/07-interaction/stepper/03-accessibility.mdx

@@ -0,0 +1,55 @@
+---
+title: Accessibility
+redirect_from:
+  - /components/stepper/accessibility/
+---
+
+## Accessibility
+
+The Stepper component has been designed with accessibility in mind. It can be used with keyboard navigation and includes properties that enhance the experience for users of assistive technologies.
+
+The following props provide additional information to screen readers, enhancing the accessibility of the respective component. By using them, you can ensure that users who rely on assistive technologies receive the necessary context and information about the component's purpose and functionality.
+
+- The `ariaLabel` prop allows you to specify an `aria-label` attribute of the component.
+
+- The `titleDecrement` prop allows you to specify an `aria-label` attribute for the decrement icon button in the Stepper (StepperStateless) component.
+
+- The `titleIncrement` prop allows you to specify an `aria-label` attribute for the increment icon button in the Stepper (StepperStateless) component.
+
+- The `ariaLabelledBy` prop allows you to specify an `aria-labelledby` attribute for the Stepper component. This attribute references the ID of the element that labels the Stepper, ensuring that screen readers announce the label correctly.
+
+Although these props are optional for the Stepper (StepperStateless) component itself, it is recommended to fill them in to ensure that the component can be perceived by assistive technologies.
+
+### Example
+
+```jsx
+<Stepper
+  step={1}
+  minValue={0}
+  minValue={10}
+  ariaLabel="Number of passengers"
+  titleDecrement="Remove a passenger"
+  titleIncrement="Add a passenger"
+/>
+```
+
+The screen reader will announce the input title (`Number of passengers`) and buttons title (`Add a passenger`, `Remove a passenger`) once they are focused by the screen reader.
+
+```jsx
+<Stack>
+  <Stack>
+    <Text id="passengers">Passengers</Text>
+  </Stack>
+  <Stepper
+    step={1}
+    minValue={0}
+    minValue={10}
+    ariaLabel="Number of passengers"
+    aria-labelledby="passengers"
+    titleDecrement="Remove a passenger"
+    titleIncrement="Add a passenger"
+  />
+</Stack>
+```
+
+This example includes `ariaLabelledby` prop. In this case, `ariaLabelledBy` prop is prioritized over `ariaLabel`, so the screen reader will announce the input title (`Passengers`) and buttons title (`Add a passenger`, `Remove a passenger`) once they are focused by the screen reader.

packages/orbit-components/src/Stepper/README.md

@@ -31,15 +31,10 @@ Table below contains all types of the props available in Stepper component.
 | onChange       | `number => void \| Promise` |         | Function for handling onClick event.                                          |
 | onFocus        | `event => void \| Promise`  |         | Function for handling onFocus event.                                          |
 | step           | `number`                    | `1`     | Specifies the value of step to increment and decrement.                       |
-| titleDecrement | `string \| (any => string)` |         | Specifies `title` property on decrement `Button`.                             |
-| titleIncrement | `string \| (any => string)` |         | Specifies `title` property on increment `Button`.                             |
-
-### size
-
-| size       |
-| :--------- |
-| `"small"`  |
-| `"normal"` |
+| titleDecrement | `string \| (any => string)` |         | Specifies `ariaLabel` property on decrement `Button`.                         |
+| titleIncrement | `string \| (any => string)` |         | Specifies `ariaLabel` property on increment `Button`.                         |
+| ariaLabel      | `string`                    |         | Optional prop for `aria-label` value.                                         |
+| ariaLabelledBy | `string`                    |         | Optional prop for `aria-labelledby` value.                                    |
 
 ## Functional specs
 
@@ -77,9 +72,11 @@ Table below contains all types of the props available in `StepperStateless` comp
 | onIncrement       | `event => void \| Promise`  |         | Function for handling increment event.                  |
 | onKeyDown         | `event => void \| Promise`  |         | Function for handling onKeyDown event present on input. |
 | step              | `number`                    | `1`     | Specifies the value of step to increment and decrement. |
-| titleDecrement    | `string \| (any => string)` |         | Specifies `title` property on decrement `Button`.       |
-| titleIncrement    | `string \| (any => string)` |         | Specifies `title` property on increment `Button`.       |
+| titleDecrement    | `string \| (any => string)` |         | Specifies `ariaLabel` property on decrement `Button`.   |
+| titleIncrement    | `string \| (any => string)` |         | Specifies `ariaLabel` property on increment `Button`.   |
 | value             | `number \| string`          |         | Specifies the value of the StepperStateless.            |
+| ariaLabel         | `string`                    |         | Optional prop for `aria-label` value.                   |
+| ariaLabelledBy    | `string`                    |         | Optional prop for `aria-labelledby` value.              |
 
 ### Usage:
 

packages/orbit-components/src/Stepper/Stepper.stories.tsx

@@ -23,21 +23,26 @@ export const Default: Story = {
       disable: true,
     },
   },
+
+  args: {
+    ariaLabel: "Number of passengers",
+    titleIncrement: "Add a passenger",
+    titleDecrement: "Remove a passenger",
+  },
 };
 
 export const Playground: Story = {
   args: {
+    ...Default.args,
     id: "stepper-ID",
-    name: "Passengers number",
+    name: "Number of passengers",
     step: 1,
     minValue: 0,
     maxValue: 20,
     defaultValue: 0,
     active: false,
     disabled: false,
     maxWidth: 120,
-    titleIncrement: "Add a passenger",
-    titleDecrement: "Remove a passenger",
     onChange: action("onChange"),
     onFocus: action("onFocus"),
     onBlur: action("onBlur"),
@@ -83,9 +88,9 @@ export const Stateless: Story & StoryObj<typeof StatelessStepper> = {
 };
 
 export const Rtl: Story = {
-  render: () => (
+  render: args => (
     <RenderInRtl>
-      <Stepper />
+      <Stepper {...args} />
     </RenderInRtl>
   ),
 
@@ -95,4 +100,8 @@ export const Rtl: Story = {
       disable: true,
     },
   },
+
+  args: {
+    ...Default.args,
+  },
 };

packages/orbit-components/src/Stepper/StepperStateless/index.tsx

@@ -48,6 +48,8 @@ const StepperStateless = ({
   titleDecrement,
   disabledIncrement,
   disabledDecrement,
+  ariaLabel,
+  ariaLabelledBy,
 }: Props) => {
   const theme = useTheme();
 
@@ -77,8 +79,8 @@ const StepperStateless = ({
             onDecrement(ev);
           }
         }}
-        title={titleDecrement}
         icons={iconStyles}
+        title={titleDecrement}
       />
       <input
         className={cx(
@@ -103,6 +105,8 @@ const StepperStateless = ({
         }}
         onBlur={onBlur}
         onFocus={onFocus}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
         readOnly
       />
       <ButtonPrimitive
@@ -115,8 +119,8 @@ const StepperStateless = ({
             onIncrement(ev);
           }
         }}
-        title={titleIncrement}
         icons={iconStyles}
+        title={titleIncrement}
       />
     </div>
   );

packages/orbit-components/src/Stepper/index.tsx

@@ -46,6 +46,8 @@ const Stepper = ({ onChange, defaultValue = 0, maxWidth = 108, ...props }: Props
     titleIncrement,
     titleDecrement,
     active,
+    ariaLabel,
+    ariaLabelledBy,
   } = props;
   return (
     <StepperStateless
@@ -63,8 +65,10 @@ const Stepper = ({ onChange, defaultValue = 0, maxWidth = 108, ...props }: Props
       id={id}
       value={value}
       name={name}
+      ariaLabel={ariaLabel}
       titleIncrement={titleIncrement}
       titleDecrement={titleDecrement}
+      ariaLabelledBy={ariaLabelledBy}
     />
   );
 };

packages/orbit-components/src/Stepper/types.d.ts

@@ -15,6 +15,8 @@ export interface SharedProps extends Common.Globals {
   readonly maxWidth?: string | number;
   readonly maxValue?: number;
   readonly minValue?: number;
+  readonly ariaLabel?: string;
+  readonly ariaLabelledBy?: string;
   // Deviation from other stepper properties
   readonly titleIncrement?: string;
   readonly titleDecrement?: string;