diff --git a/docs/src/documentation/03-components/07-interaction/stepper/03-accessibility.mdx b/docs/src/documentation/03-components/07-interaction/stepper/03-accessibility.mdx new file mode 100644 index 0000000000..e9487f48ce --- /dev/null +++ b/docs/src/documentation/03-components/07-interaction/stepper/03-accessibility.mdx @@ -0,0 +1,34 @@ +--- +title: Accessibility +redirect_from: + - /components/stepper/accessibility/ +--- + +## Accessibility + +### Stepper + +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. + +Although the `ariaLabel` and `ariaLive` 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. This ensures that the Stepper (StepperStateless) component is accessible. + +Also, it is highly recommended to fill the `titleDecrement` and `titleIncrement` props in to provide a description of the decrement and increment buttons for screen readers. + +#### Example + +The content of children component is text, so it is read by screen reader. + +```jsx + +``` + +The screen reader will announce stepper title (`Passengers number`) and buttons title (`Add a passenger`, `Remove a passenger`) once they are focused by screen reader. +In case of changing the stepper value, the screen reader will announce the new value (`ariaLive` is set to `assertive` value). diff --git a/packages/orbit-components/src/Stepper/README.md b/packages/orbit-components/src/Stepper/README.md index 664b196b0f..60ded54799 100644 --- a/packages/orbit-components/src/Stepper/README.md +++ b/packages/orbit-components/src/Stepper/README.md @@ -31,15 +31,9 @@ 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. [See Accessibility](#accessibility). | ## Functional specs @@ -61,25 +55,27 @@ import StepperStateless from "@kiwicom/orbit-components/lib/Stepper/StepperState Table below contains all types of the props available in `StepperStateless` component. -| Name | Type | Default | Description | -| :---------------- | :-------------------------- | :------ | :------------------------------------------------------ | -| dataTest | `string` | | Optional prop for testing purposes. | -| disabled | `boolean` | `false` | If `true`, the Stepper will be disabled. | -| disabledIncrement | `boolean` | | If `true`, the increment `Button` will be disabled. | -| disabledDecrement | `boolean` | | If `true`, the decrement `Button` will be disabled. | -| maxValue | `number` | `∞` | Specifies the maximum value for the Stepper. | -| minValue | `number` | `-∞` | Specifies the minimum value for the Stepper. | -| name | `string` | | The name for the Stepper. | -| onBlur | `event => void \| Promise` | | Function for handling onBlur event. | -| onChange | `number => void \| Promise` | | Function for handling onClick event. | -| onDecrement | `event => void \| Promise` | | Function for handling decrement event.l | -| onFocus | `event => void \| Promise` | | Function for handling onFocus event. | -| 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`. | -| value | `number \| string` | | Specifies the value of the StepperStateless. | +| Name | Type | Default | Description | +| :---------------- | :--------------------------------- | :------ | :------------------------------------------------------------------------- | +| dataTest | `string` | | Optional prop for testing purposes. | +| disabled | `boolean` | `false` | If `true`, the Stepper will be disabled. | +| disabledIncrement | `boolean` | | If `true`, the increment `Button` will be disabled. | +| disabledDecrement | `boolean` | | If `true`, the decrement `Button` will be disabled. | +| maxValue | `number` | `∞` | Specifies the maximum value for the Stepper. | +| minValue | `number` | `-∞` | Specifies the minimum value for the Stepper. | +| name | `string` | | The name for the Stepper. | +| onBlur | `event => void \| Promise` | | Function for handling onBlur event. | +| onChange | `number => void \| Promise` | | Function for handling onClick event. | +| onDecrement | `event => void \| Promise` | | Function for handling decrement event. | +| onFocus | `event => void \| Promise` | | Function for handling onFocus event. | +| 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 `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. [See Accessibility](#accessibility). | +| ariaLive | `"off" \| "assertive" \| "polite"` | | Optional prop for `aria-live` value. [See Accessibility](#accessibility). | ### Usage: @@ -131,3 +127,19 @@ Helper function for validating decrement. Can be used with Stateless Stepper to ```js validateDecrement({ value, minValue, step }); ``` + +## Accessibility + +- The `ariaLabel` prop allows you to specify an `aria-label` attribute for the Stepper input component. This attribute provides additional information to screen readers, enhancing the accessibility of the component. By using `ariaLabel`, you can ensure that users who rely on assistive technologies receive the necessary context and information about the component's purpose and functionality. + +- The `titleDecrement` prop allows you to specify an `aria-label` attribute for the decrement icon button in the Stepper (StepperStateless) component. This attribute helps screen readers to announce the purpose of the decrement button, making it clear that it decreases the value. + +- The `titleIncrement` prop allows you to specify an `aria-label` attribute for the increment icon button in the Stepper (StepperStateless) component. This attribute helps screen readers to announce the purpose of the increment button, making it clear that it increases the value. + +- The `ariaLive` prop allows you to specify an `aria-live` attribute for the Stepper component. This attribute is used to inform assistive technologies of updates to the content. + +- The `ariaDescribedBy` prop allows you to specify an `aria-describedby` attribute for the Stepper component. This attribute references the IDs of elements that describe the Stepper, providing additional context to screen readers. + +- The `ariaControls` prop allows you to specify an `aria-controls` attribute for the Stepper component. This attribute references the ID of the element that the Stepper controls, helping users understand the relationship between the Stepper and the controlled element. + +- 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. diff --git a/packages/orbit-components/src/Stepper/Stepper.stories.tsx b/packages/orbit-components/src/Stepper/Stepper.stories.tsx index 5ef658105d..ae2382c872 100644 --- a/packages/orbit-components/src/Stepper/Stepper.stories.tsx +++ b/packages/orbit-components/src/Stepper/Stepper.stories.tsx @@ -23,10 +23,17 @@ export const Default: Story = { disable: true, }, }, + + args: { + ariaLabel: "Passengers number", + titleIncrement: "Add a passenger", + titleDecrement: "Remove a passenger", + }, }; export const Playground: Story = { args: { + ...Default.args, id: "stepper-ID", name: "Passengers number", step: 1, @@ -36,8 +43,6 @@ export const Playground: Story = { 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 = { }; export const Rtl: Story = { - render: () => ( + render: args => ( - + ), @@ -95,4 +100,8 @@ export const Rtl: Story = { disable: true, }, }, + + args: { + ...Default.args, + }, }; diff --git a/packages/orbit-components/src/Stepper/StepperStateless/index.tsx b/packages/orbit-components/src/Stepper/StepperStateless/index.tsx index f2e37b7801..6340d6d186 100644 --- a/packages/orbit-components/src/Stepper/StepperStateless/index.tsx +++ b/packages/orbit-components/src/Stepper/StepperStateless/index.tsx @@ -48,6 +48,8 @@ const StepperStateless = ({ titleDecrement, disabledIncrement, disabledDecrement, + ariaLabel, + ariaLive, }: Props) => { const theme = useTheme(); @@ -77,8 +79,8 @@ const StepperStateless = ({ onDecrement(ev); } }} - title={titleDecrement} icons={iconStyles} + title={titleDecrement} /> ); diff --git a/packages/orbit-components/src/Stepper/index.tsx b/packages/orbit-components/src/Stepper/index.tsx index 99c92858f6..4eeec4f61b 100644 --- a/packages/orbit-components/src/Stepper/index.tsx +++ b/packages/orbit-components/src/Stepper/index.tsx @@ -46,6 +46,8 @@ const Stepper = ({ onChange, defaultValue = 0, maxWidth = 108, ...props }: Props titleIncrement, titleDecrement, active, + ariaLabel, + ariaLive, } = props; return ( diff --git a/packages/orbit-components/src/Stepper/types.d.ts b/packages/orbit-components/src/Stepper/types.d.ts index be5ee55efb..6f1adb2f77 100644 --- a/packages/orbit-components/src/Stepper/types.d.ts +++ b/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 ariaLive?: "off" | "assertive" | "polite"; // Deviation from other stepper properties readonly titleIncrement?: string; readonly titleDecrement?: string;