-
Notifications
You must be signed in to change notification settings - Fork 89
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Co-authored-by: lilyvc <[email protected]> Co-authored-by: Joana Moreira <[email protected]> Co-authored-by: Zhihao Cui <[email protected]>
- Loading branch information
1 parent
25f3010
commit ef51568
Showing
9 changed files
with
206 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 */} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
import { ReactElement } from "react"; | ||
import { Switch } from "@salt-ds/lab"; | ||
|
||
export const Default = (): ReactElement => <Switch label="Default" />; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
import { ReactElement } from "react"; | ||
import { Switch } from "@salt-ds/lab"; | ||
|
||
export const DefaultChecked = (): ReactElement => ( | ||
<Switch label="Checked" defaultChecked /> | ||
); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
import { ReactElement } from "react"; | ||
import { Switch } from "@salt-ds/lab"; | ||
|
||
export const Disabled = (): ReactElement => ( | ||
<Switch label="Disabled" disabled /> | ||
); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
import { ReactElement } from "react"; | ||
import { Switch } from "@salt-ds/lab"; | ||
|
||
export const DisabledChecked = (): ReactElement => ( | ||
<Switch label="Disabled + Checked" disabled defaultChecked /> | ||
); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
export * from "./Default"; | ||
export * from "./DefaultChecked"; | ||
export * from "./DisabledChecked"; | ||
export * from "./Disabled"; |
ef51568
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Successfully deployed to the following URLs:
saltdesignsystem – ./
saltdesignsystem-git-main-fed-team.vercel.app
saltdesignsystem-fed-team.vercel.app
saltdesignsystem.vercel.app
www.saltdesignsystem.com
next.saltdesignsystem.com