Merge branch 'main' into add-input-docs

site/docs/components/switch/accessibility.mdx

@@ -0,0 +1,39 @@
+---
+# Leave the frontmatter as is
+title:
+  $ref: ./#/title
+layout: DetailComponent
+sidebar:
+  exclude: true
+data:
+  $ref: ./#/data
+---
+
+### Best practices
+
+- On focus, the screen reader should:
+  - Identify the switch
+  - Read out the text
+  - Express the state
+
+### Keyboard interactions
+
+<KeyboardControls>
+<KeyboardControl keyOrCombos="Tab">
+
+- If focus is on the previous element in the tab order, move focus onto Switch.
+- If focus is on Switch, moves focus to the next focusable element in the tab order.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Space">
+
+- Activate Switch to change state.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Shift + Tab">
+
+- If focus is on Switch, moves focus out of the component. Focus is set to the previous component in the tab order.
+- If focus is below Switch, move focus to Switch.
+
+</KeyboardControl>
+</KeyboardControls>

site/docs/components/switch/examples.mdx

@@ -0,0 +1,60 @@
+---
+# Leave the frontmatter as is
+title:
+  $ref: ./#/title
+layout: DetailComponent
+sidebar:
+  exclude: true
+data:
+  $ref: ./#/data
+---
+
+<LivePreviewControls>
+<LivePreview componentName="switch" exampleName="Default">
+
+### Switch
+
+By default, the switch thumb sits to the left side of the track and is in an unchecked state.
+
+- The switch state can be set using the optional `defaultChecked` prop.
+- The `onChange` event can be used to read the value using the second parameter.
+
+Guidance:
+
+- Only use the `checked` prop for a controlled switch that requires some logic for validating value.
+- We recommend that you always use a text description for a switch.
+
+</LivePreview>
+
+<LivePreview componentName="switch" exampleName="DefaultChecked" displayName="Checked" >
+
+### Checked
+
+When `defaultChecked={true}`, switch is in a `checked` state and the switch thumb sits to the right side of the track.
+
+</LivePreview>
+
+<LivePreview componentName="switch" exampleName="Disabled" >
+
+### Disabled
+
+You can set Switch to a disabled state. When `disabled`, it is not interactive or focusable.
+
+Guidance:
+
+Use a disabled state for switches that have permissions, dependencies or pre-requisites. For example, a switch in a [Form](/salt/patterns/forms) may be disabled because the user has not yet completed an earlier section of the form.
+
+</LivePreview>
+
+<LivePreview componentName="switch" exampleName="DisabledChecked" >
+
+### Disabled checked
+
+You can set a `checked` switch to a disabled state. When `disabled`, it is not interactive or focusable. This shows an option has been toggled to be “checked” but cannot be changed.
+
+Guidance:
+
+Use a disabled checked state for switches that have permissions, dependencies or pre-requisites. For example, a switch in a [Form](/salt/patterns/forms) may be checked but disabled as the user does not have permissions to edit their selection during a later stage in a form.
+
+</LivePreview>
+</LivePreviewControls>

site/docs/components/switch/index.mdx

@@ -0,0 +1,30 @@
+---
+title: Switch
+data:
+  description: Switch is a binary control used to toggle between two different states. When interacted with, the thumb of the switch travels along the track to indicate state. Switch is used to control settings, preferences, or actions within an application or system.
+
+  # Fill in the info from the content template's "Metadata" table below.
+  # To omit optional items, comment them out with #
+  sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/lab/src/switch/Switch.tsx"
+  package:
+    name: "@salt-ds/lab"
+  alsoKnownAs: ["Lightswitch", "Toggle", "Toggle switch"]
+  relatedComponents: [
+      # Add a { name: "...", relationship: "..." } block for each
+      # related component here (separated by commas).
+      # Permitted values for relationship are: "similarTo" or
+      # "contains".
+      { name: "Icon", relationship: "contains" },
+      { name: "Toggle Button", relationship: "similarTo" },
+      { name: "Toggle Button Group", relationship: "similarTo" },
+      { name: "Checkbox", relationship: "similarTo" },
+      { name: "Radio Button", relationship: "similarTo" },
+      { name: "Pill", relationship: "similarTo" },
+    ]
+  # stickerSheet: "https://figma.com/..."
+
+# Leave this as is
+layout: DetailComponent
+---
+
+{/* This area stays blank */}

site/docs/components/switch/usage.mdx

@@ -0,0 +1,51 @@
+---
+# Leave the frontmatter as is
+title:
+  $ref: ./#/title
+layout: DetailComponent
+sidebar:
+  exclude: true
+data:
+  $ref: ./#/data
+---
+
+### Using the Switch component
+
+#### When to use Switch
+
+- To present an instantaneous, binary choice between two options that doesn’t require the action to be submitted or confirmed. The corresponding action takes effect immediately.
+- To control a critical action that may require confirmation from the user before applying the action. This delay is usually intentional, ensuring that users do not accidentally make unwanted changes.
+
+#### When not to use Switch
+
+- To present a list of independent options where the user can select any number of choices. Instead, use [Checkbox](../checkbox).
+- To make a single selection between mutually exclusive choices between two or more options. Instead, use [Radio Button](../radio-button).
+- To toggle between two (or more) opposing yet mutually exclusive states or options with visual priority. Instead, use [Toggle Button](../toggle-button).
+- To present multiple options in a group within a compact UI, or if they’re subject to change depending on context. Instead, use [Selectable Pill](../pill).
+
+### Import
+
+{/* Update the text and code snippet below as needed: */}
+
+To import Switch from the lab Salt package, use:
+
+```js
+import { Switch } from "@salt-ds/lab";
+```
+
+### Content
+
+- The option that that switch controls should be made clear in the text inline to the switch.
+- Text should always sit to the right of the switch.
+- Keep the text description as clear and concise as possible, and ensure it accurately describes the action the switch will perform upon interaction.
+
+### Props
+
+{/* Update packageName and componentName below as needed */}
+{/* packageName is optional and defaults to "core" if omitted */}
+
+<PropsTable packageName="lab" componentName="Switch" />
+
+### References
+
+- Switch Pattern (https://www.w3.org/WAI/ARIA/apg/patterns/switch/ ) W3C

site/src/examples/switch/Default.tsx

@@ -0,0 +1,4 @@
+import { ReactElement } from "react";
+import { Switch } from "@salt-ds/lab";
+
+export const Default = (): ReactElement => <Switch label="Default" />;

site/src/examples/switch/DefaultChecked.tsx

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { Switch } from "@salt-ds/lab";
+
+export const DefaultChecked = (): ReactElement => (
+  <Switch label="Checked" defaultChecked />
+);

site/src/examples/switch/Disabled.tsx

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { Switch } from "@salt-ds/lab";
+
+export const Disabled = (): ReactElement => (
+  <Switch label="Disabled" disabled />
+);

site/src/examples/switch/DisabledChecked.tsx

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { Switch } from "@salt-ds/lab";
+
+export const DisabledChecked = (): ReactElement => (
+  <Switch label="Disabled + Checked" disabled defaultChecked />
+);

site/src/examples/switch/index.ts

@@ -0,0 +1,4 @@
+export * from "./Default";
+export * from "./DefaultChecked";
+export * from "./DisabledChecked";
+export * from "./Disabled";