Add accessibility props to Switch

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

@@ -0,0 +1,53 @@
+---
+title: Accessibility
+redirect_from:
+  - /components/switch/accessibility/
+---
+
+## Accessibility
+
+The Switch component has been designed with accessibility in mind.
+
+It supports keyboard navigation and includes the following properties that provide additional information to screen readers:
+
+| Name           | Type     | Description                                                                                                                                                                                                                                                                 |
+| :------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ariaControls   | `string` | Allows you to specify an `aria-controls` attribute to establish the relationship between the Switch and element which is controlled by it. `ariaControls` works only with a unique `id` of an element.                                                                      |
+| ariaLabel      | `string` | Allows you to specify an `aria-label` attribute of the component.                                                                                                                                                                                                           |
+| ariaLabelledby | `string` | Allows you to specify an `aria-labelledby` attribute of the component. This attribute references the id(s) of element(s) that label(s) the Switch, separated by a space. The elements with those ids can be hidden, so that their text is only announced by screen readers. |
+
+While these props are optional, we recommend including them to ensure proper functionality with assistive technologies.
+This helps users better understand the component's context and improves the overall experience.
+
+### Example
+
+The following code snippet shows how to use these properties:
+
+```jsx
+<Card
+  title="Billing details"
+  actions={
+    <Switch
+      checked={isExpanded}
+      onChange={handleShowBillingDetails}
+      ariaLabel="Toggle billing details section"
+      ariaControls="BillingDetailsForm"
+    />
+  }
+>
+  {isExpanded && (
+    <CardSection>
+      <BillingDetailsForm id="BillingDetailsForm" />
+    </CardSection>
+  )}
+</Card>
+```
+
+Using the `ariaLabel` prop enables screen readers to properly announce the Switch component.
+Alternatively, you can use the `ariaLabelledby` prop to reference another element that serves as a label for the Switch component.
+
+For enhanced accessibility, it is recommended to have these label strings translated and dynamically updated based on the user's current journey state
+(e.g. if a billing details section is expanded and the user is about to collapse it, the screen reader should properly announce it).
+
+The `ariaControls` prop establishes a connection between the Switch and the element it controls.
+This relationship enables users to navigate directly from the Switch to this element, improving the overall navigation experience.

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

@@ -16,14 +16,16 @@ After adding import to your project you can use it simply like:
 
 The table below contains all types of the props available in the Switch component.
 
-| Name           | Type                    | Default      | Description                             |
-| :------------- | :---------------------- | :----------- | :-------------------------------------- |
-| dataTest       | `string`                |              | Optional prop for testing purposes.     |
-| id             | `string`                |              | Set `id` for `Switch` input             |
-| **onChange**   | `() => void \| Promise` |              | Function for handling onChange event.   |
-| onFocus        | `() => void \| Promise` |              | Function for handling onFocus event.    |
-| onBlur         | `() => void \| Promise` |              | Function for handling onBlur event.     |
-| **checked**    | `boolean`               |              | If `true`, the Switch will be checked.  |
-| ariaLabelledby | `string`                |              | Optional prop for a11y element          |
-| icon           | `React.Node`            | `<Circle />` | Optional property for custom icon.      |
-| disabled       | `boolean`               | `false`      | If `true`, the Switch will be disabled. |
+| Name           | Type                    | Default      | Description                                |
+| :------------- | :---------------------- | :----------- | :----------------------------------------- |
+| dataTest       | `string`                |              | Optional prop for testing purposes.        |
+| id             | `string`                |              | Set `id` for `Switch` input.               |
+| **onChange**   | `() => void \| Promise` |              | Function for handling onChange event.      |
+| onFocus        | `() => void \| Promise` |              | Function for handling onFocus event.       |
+| onBlur         | `() => void \| Promise` |              | Function for handling onBlur event.        |
+| **checked**    | `boolean`               |              | If `true`, the Switch will be checked.     |
+| icon           | `React.Node`            | `<Circle />` | Optional property for custom icon.         |
+| disabled       | `boolean`               | `false`      | If `true`, the Switch will be disabled.    |
+| ariaControls   | `string`                |              | Optional prop for `aria-controls` value.   |
+| ariaLabel      | `string`                |              | Optional prop for `aria-label` value.      |
+| ariaLabelledby | `string`                |              | Optional prop for `aria-labelledby` value. |

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

@@ -16,6 +16,7 @@ const meta: Meta<typeof Switch> = {
   args: {
     checked: false,
     onChange: action("onChange"),
+    ariaLabel: "Set up price alerts",
   },
 
   parameters: {
@@ -42,6 +43,7 @@ export const CustomIcon: Story = {
   args: {
     checked: true,
     icon: "Lock",
+    ariaLabel: "Lock the price",
   },
 
   argTypes: {
@@ -64,7 +66,6 @@ export const Playground: Story = {
   args: {
     ...CustomIcon.args,
     id: "switch-id",
-    ariaLabelledby: "aria-labelledby",
     disabled: false,
     onFocus: action("onFocus"),
     onBlur: action("onBlur"),

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

@@ -8,7 +8,22 @@ import handleKeyDown from "../utils/handleKeyDown";
 import type { Props } from "./types";
 
 const Switch = React.forwardRef<HTMLInputElement, Props>(
-  ({ onChange, checked, dataTest, id, icon, onBlur, onFocus, disabled, ariaLabelledby }, ref) => {
+  (
+    {
+      onChange,
+      checked,
+      dataTest,
+      id,
+      icon,
+      onBlur,
+      onFocus,
+      disabled,
+      ariaControls,
+      ariaLabel,
+      ariaLabelledby,
+    },
+    ref,
+  ) => {
     return (
       <label className="inline-block">
         <div
@@ -28,14 +43,16 @@ const Switch = React.forwardRef<HTMLInputElement, Props>(
             disabled={disabled}
             aria-checked={checked}
             role="switch"
-            aria-labelledby={ariaLabelledby}
             onKeyDown={!disabled ? handleKeyDown<HTMLInputElement>(undefined, onChange) : undefined}
             onBlur={!disabled ? onBlur : undefined}
             onChange={!disabled ? onChange : undefined}
             onFocus={!disabled ? onFocus : undefined}
             type="checkbox"
             data-test={dataTest}
             id={id}
+            aria-controls={ariaControls}
+            aria-label={ariaLabel}
+            aria-labelledby={ariaLabelledby}
           />
           <div
             className={cx(

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

@@ -8,9 +8,11 @@ import type * as Common from "../common/types";
 export interface Props extends Common.Globals {
   readonly icon?: React.ReactNode;
   readonly checked: boolean;
-  readonly ariaLabelledby?: string;
   readonly disabled?: boolean;
   readonly onChange: React.ChangeEventHandler<HTMLInputElement>;
   readonly onFocus?: React.FocusEventHandler<HTMLInputElement>;
   readonly onBlur?: React.FocusEventHandler<HTMLInputElement>;
+  readonly ariaControls?: string;
+  readonly ariaLabel?: string;
+  readonly ariaLabelledby?: string;
 }