@splunk/react-ui 5.7.1 → 5.8.0

package/docs-llm/Switch.md

@@ -0,0 +1,268 @@
+# Switch
+
+## Overview
+
+
+> Image: Illustration of a switch component.
+
+
+<Message appearance="fill" type="info">
+    <div>All data entry components should be wrapped in a <Link to="ControlGroup">Control Group</Link> to provide a label, error states, and help or error text, ensuring an accessible experience for all users.</div>
+</Message>
+
+## When to use this component
+### Toggle
+- There's a binary choice for enabling a setting, like on/off, true/false, enable/disable, or activate/deactivate.
+- Toggles can be grouped when the items can be independently controlled.
+
+### Checkbox
+<Message appearance="fill" type="warning">
+    <div>Prefer the <Link to="Checkbox">Checkbox</Link> component over the checkbox appearance of Switch.</div>
+</Message>
+
+## When to use another component
+- If multiple related options can be selected from a list, use Checkbox
+- If there are more than two choices or two choices that don't map to a boolean relationship (such as on/off) use Radio List or Radio Bar
+- If there are multiple options, space conservation is important, and only one option can be selected at a time use a Select or Combobox
+- If making a selection from a long list of items, consider using Multiselect instead.
+- If only one option in a set can be selected, use Radio List or Radio Bar instead.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Switch component or something else
+    A(Can the user select more than 1 option?) -- Yes --- B(Are there fewer than 5 options and you don't need to conserve space?)
+    B -- Yes --- C(Switch - Checkbox group)
+    B -- No --- D(Multiselect)
+    A -- No --- E("Do the options have a boolean (Ex. on/off) relationship?")
+    E -- Yes --- F(Switch - Toggle)
+    E -- No --- G(Are there fewer than 5 options and you don't need to conserve space?)
+    G -- Yes --- H(Radio List or Radio Bar)
+    G -- No --- I(Select or ComboBox)
+```
+
+### Check out
+- [Radio List][1]
+- [Radio Bar][2]
+- [Combo Box][3]
+- [Select][4]
+- [Multiselect][5]
+
+## Usage
+
+### Grouping settings
+Checkboxes visually group similar items effectively and take up less space than switches.
+
+> Image: Examples of a group of two Switches, 
+
+
+### In forms
+Toggles work best if changing the state is immediately effective and there's no need for an additional action to apply or save a change. Consider Checkboxes or Radio Lists within a form containing other elements that need to be saved or submitted.
+
+> Image: Example of Notification settings with a group of two Switches, 
+
+
+### Toggle groups
+When grouped, toggles control binary options, not opposing states. A binary option represents a single selection that is either on or off.
+
+> Image: Examples of a group of two Toggles grouped with a title. In the first example with heart eyes emoji, the Toggles are labeled, 
+
+
+## Content
+
+### Be concise
+Use sentence-style capitalization and keep labels concise.
+
+> Image: Examples of switch label length: The first example with the heart eyes emoji has a concise label, 
+
+
+[1]: ./Radiolist
+[2]: ./Radiobar
+[3]: ./ComboBox
+[4]: ./Select
+[5]: ./Multiselect
+[6]: ./Dropdown
+[7]: ./Checkbox
+
+## Examples
+
+
+### Basic
+
+```typescript
+import React, { useState } from 'react';
+
+import Switch from '@splunk/react-ui/Switch';
+
+
+const Basic = () => {
+    const [enableBluetooth, setEnableBluetooth] = useState(true);
+    const [enableWifi, setEnableWifi] = useState(false);
+
+    return (
+        <>
+            <Switch
+                appearance="toggle"
+                selected={enableBluetooth}
+                onClick={() => setEnableBluetooth(!enableBluetooth)}
+            >
+                Enable bluetooth
+            </Switch>
+            <Switch
+                appearance="toggle"
+                selected={enableWifi}
+                onClick={() => setEnableWifi(!enableWifi)}
+            >
+                Enable wifi
+            </Switch>
+        </>
+    );
+};
+
+export default Basic;
+```
+
+
+
+### Disabled
+
+```typescript
+import React from 'react';
+
+import Switch from '@splunk/react-ui/Switch';
+
+
+const Disabled = () => {
+    return (
+        <>
+            <Switch appearance="toggle" disabled selected>
+                Enable bluetooth
+            </Switch>
+            <Switch appearance="toggle" disabled>
+                Enable wifi
+            </Switch>
+        </>
+    );
+};
+
+export default Disabled;
+```
+
+
+
+
+## API
+
+
+### Switch API
+
+`Switch` is a basic form control with an on/off state.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| appearance | 'checkbox' \| 'toggle' | no | 'checkbox' | **DEPRECATED**: Value 'checkbox'. Consider using the `Checkbox` component instead. Determines if the component renders as a checkbox or toggle.  The 'checkbox' value is deprecated and will be removed in a future major version. |
+| children | React.ReactNode | no |  |  |
+| describedBy | string | no |  | The id of the description. When placed in a ControlGroup, this is automatically set to the ControlGroup's help component. |
+| disabled | boolean | no |  |  |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts, and null when it unmounts. |
+| error | boolean | no |  | Highlight the field as having an error only when appearance is 'checkbox'. |
+| id | string | no |  | If `Switch` is not provided children as the label, an id can be provided for the control. Set a label's for attribute to this id to link the two elements. |
+| inline | boolean | no |  | Make the control an inline block with variable width. |
+| labelledBy | string | no |  | If `Switch` is not provided children as the label, an id can be provided to another element. |
+| onClick | SwitchClickHandler \| SwitchCheckboxWithSomeClickHandler | no |  |  |
+| selected | boolean \| 'some' | no |  | 'some' is only valid when appearance is 'checkbox'. The current value of `selected` is passed to the onClick handler. |
+| selectedLabel | string | no |  | **DEPRECATED**: This prop is deprecated and will be removed in the next major version. The customized content presented to screen readers when selected. |
+| someSelectedLabel | string | no |  | **DEPRECATED**: This prop is deprecated and will be removed in the next major version. The customized content presented to screen readers when selected="some". |
+| toggleRef | React.Ref<HTMLAnchorElement \| HTMLButtonElement \| HTMLSpanElement> | no |  | A React ref which is set to the toggle when the component mounts and null when it unmounts. |
+| unselectedLabel | string | no |  | **DEPRECATED**: This prop is deprecated and will be removed in the next major version. The customized content presented to screen readers when unselected. |
+| value | any | no |  | The `value` is used as an identifier and is passed to the `onClick` handler. This is useful when managing a group of switches with a single `onClick` handler. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| SwitchCheckboxWithSomeClickHandler | (     event: React.MouseEvent<HTMLButtonElement>,     data: {         selected: boolean \| 'some';         value?: any; // eslint-disable-line @typescript-eslint/no-explicit-any     } ) => void |  |
+| SwitchClickHandler | (     event: React.MouseEvent<HTMLButtonElement>,     data: {         selected: boolean;         value?: any; // eslint-disable-line @typescript-eslint/no-explicit-any     } ) => void |  |
+
+
+
+
+
+## Accessibility
+
+## Switch / Checkbox
+## Visual Design
+
+- Color contrast ratio **MUST** be:
+    - &gt=4.5:1 for Label text to page-background (all states) [SC 1.4.3][1]
+    - &gt=3:1 for [SC 1.4.11][2]:
+        - For toggle, circle to toggle-background-color
+        - For checkbox, checkmark to checkbox-background (selected)
+        - Border to page-background (active)
+    - Focus State: if the focus ring has a radius of [SC 1.4.11][2]:
+        - &lt 3px: &gt=4.5.1 between button &lt&gt focus &lt&gt background
+        - &gt 3px: &gt=3.1 between button &lt&gt focus &lt&gt background
+
+## States
+
+- Color contrast rules do not apply to disabled checkbox
+
+## Interaction Model
+
+- Toggle:
+    - Focus management
+    - **MUST** have keyboard navigation [SC 2.1][3]:
+        - <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> to focus on checkbox from element before or after in meaningful sequence
+        - <kbd>Space</kbd> and <kbd>Enter</kbd> to change state to on or off 
+
+- Checkbox:
+    - Checkbox **SHOULD** have `tabindex="0"` to make checkboxes focusable by keyboard
+    - **MUST** have keyboard navigation [SC 2.1][3]:
+        - <kbd>Tab</kbd> and <kbd>Shift+Tab</kbd> to focus on checkbox from element before or after in
+            a meaningful sequence
+        - <kbd>Space</kbd> to change status to...
+
+            - Simple State: `selected`, `unselected`
+            - Tri-state: `selected`, `unselected`, `mixed-state`
+
+## Implementation
+
+- Toggle:
+    - Screen reader **MUST** announce when toggle is focused [SC 4.1.2][4]:
+        - Name of toggle(label)
+        - `"Switch"` or `"Toggle"` (role's name is dependent on browser)
+        - `"On"` or `"Off"` (value)
+
+- Checkbox:
+    - Screen reader **MUST** announce when checkbox is focused [SC 4.1.2][4]:
+        - Label (name)
+        - `"checkbox"` (role)
+        - `"unchecked"` or `"checked"`, `"mixed"` (value)
+    - **MUST** include ARIA labels: [SC 4.1.2][4]:
+        - When checked, `aria-checked=true`
+        - When not checked, `aria-checked=false`
+        - when partially checked, `aria-checked=mixed`
+    - If checkboxes are in a **group** the following **MUST** apply for screen reader:
+        - Upon first focus into the group, announce how many checkboxes are in that list
+        - Name of group
+    - When developing a parent-child checkbox component, the following **MUST** apply:
+        - Focused checkbox:
+            - <kbd>Space</kbd>: cycle the checked state of the checkbox between checked, unchecked and mixed
+            - <kbd>Tab</kbd>: move focus to the next interactive element after checkbox
+            - <kbd>Shift+Tab</kbd>: move focus to the previous interactive element
+        - Parent checkbox:
+            - Unchecked makes all controlled checkboxes unchecked
+            - Checked makes all controlled checkboxes checked
+            - Mixed makes all the controlled checkboxes return to the last state the user selected for the particular checkbox or default state
+        - Child checkbox:
+            - Checked: all children checkboxes will check parent checkbox
+            - Unchecked: all children checkboxes will uncheck parent checkbox
+            - Checking some will partially check (mixed) the parent checkbox
+
+[1]: https://www.w3.org/TR/WCAG21/#contrast-minimum
+[2]: https://www.w3.org/TR/WCAG21/#non-text-contrast
+[3]: https://www.w3.org/TR/WCAG21/#keyboard-accessible
+[4]: https://www.w3.org/TR/WCAG21/#name-role-value
+
+