@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/switch/content.md

@@ -0,0 +1,150 @@
+# Switch (https://design.candescent.com/docs/components/switch)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=308-19827), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-switch--default)
+
+A switch controls a single setting that takes effect immediately. Always provide an accessible label.
+
+```tsx
+import { Switch } from '@cdx-ui/components';
+```
+
+## Basic
+
+Use `value` and `onValueChange` for a controlled switch, or `defaultValue` for an uncontrolled switch.
+
+```tsx
+import { useState } from 'react';
+import { Box, Switch, Text } from '@cdx-ui/components';
+
+export default function SwitchBasicDemo() {
+  const [enabled, setEnabled] = useState(false);
+
+  return (
+    <Box className="flex-row items-center gap-3">
+      <Switch value={enabled} onValueChange={setEnabled} accessibilityLabel="Account alerts" />
+      <Text>Account alerts {enabled ? 'on' : 'off'}</Text>
+    </Box>
+  );
+}
+```
+
+## Sizes
+
+`size` changes the track and thumb on web. iOS and Android render the system switch, so `size` has no effect.
+
+```tsx
+import { Box, Switch, Text } from '@cdx-ui/components';
+
+export default function SwitchSizesDemo() {
+  return (
+    <Box className="gap-4">
+      <Box className="flex-row items-center gap-3">
+        <Switch size="sm" defaultValue accessibilityLabel="Small switch" />
+        <Text>Small</Text>
+      </Box>
+      <Box className="flex-row items-center gap-3">
+        <Switch size="md" defaultValue accessibilityLabel="Medium switch" />
+        <Text>Medium</Text>
+      </Box>
+      <Box className="flex-row items-center gap-3">
+        <Switch size="lg" defaultValue accessibilityLabel="Large switch" />
+        <Text>Large</Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Disabled
+
+Disabled switches can display either the on or off state.
+
+```tsx
+import { Box, Switch, Text } from '@cdx-ui/components';
+
+export default function SwitchDisabledDemo() {
+  return (
+    <Box className="gap-4">
+      <Box className="flex-row items-center gap-3">
+        <Switch isDisabled accessibilityLabel="Disabled off switch" />
+        <Text>Disabled off</Text>
+      </Box>
+      <Box className="flex-row items-center gap-3">
+        <Switch isDisabled defaultValue accessibilityLabel="Disabled on switch" />
+        <Text>Disabled on</Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Invalid
+
+Use `isInvalid` when the current setting fails validation.
+
+```tsx
+import { Box, Switch, Text } from '@cdx-ui/components';
+
+export default function SwitchInvalidDemo() {
+  return (
+    <Box className="flex-row items-center gap-3">
+      <Switch isInvalid accessibilityLabel="Required security alerts" />
+      <Text>Security alerts are required</Text>
+    </Box>
+  );
+}
+```
+
+## In a list item
+
+Place switches after their labels in settings lists. The setting should update as soon as the switch is toggled.
+
+```tsx
+import { useState } from 'react';
+import { Card, ListItem, Switch } from '@cdx-ui/components';
+import { Notifications } from '@cdx-ui/icons';
+
+export default function ListItemWithSwitchDemo() {
+  const [enabled, setEnabled] = useState(true);
+
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem showSeparator={false}>
+          <ListItem.LeadingSlot>
+            <Notifications size={24} />
+          </ListItem.LeadingSlot>
+          <ListItem.Content>
+            <ListItem.Title>Push Notifications</ListItem.Title>
+            <ListItem.Description>Receive alerts for account activity</ListItem.Description>
+          </ListItem.Content>
+          <ListItem.TrailingSlot>
+            <Switch value={enabled} onValueChange={setEnabled} />
+          </ListItem.TrailingSlot>
+        </ListItem>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## API
+
+### Switch
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size?` | `'sm' \| 'md' \| 'lg'` | `'md'` | Track and thumb size on web. iOS and Android render the system switch, so `size` has no effect. |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the switch's own styles. |
+| `accessibilityLabel?` | `string` | — | Accessible label announced by screen readers. |
+| `onFocus?` | `(() => void)` | — | Called when the switch receives focus. |
+| `onBlur?` | `(() => void)` | — | Called when the switch loses focus. |
+| `onValueChange?` | `((value: boolean) => void)` | — | Callback invoked when the switch value changes. |
+| `isChecked?` | `boolean` | — | Alias for `value`. `value` takes precedence when both are set. |
+| `value?` | `boolean` | — | Controlled on/off state. Takes precedence over `isChecked`. |
+| `isDisabled?` | `boolean` | — | If true, the switch will be disabled. |
+| `disabled?` | `boolean` | — | Alias for `isDisabled`. Either prop disables the switch. |
+| `defaultValue?` | `boolean` | — | Initial state when uncontrolled. No effect when `value` or `isChecked` is set. |
+| `isInvalid?` | `boolean` | — | If true, set the switch to the invalid state. |
+
+Does not extend a React Native base component — every prop is listed above.

package/docs/components/switch/design.md

@@ -0,0 +1,208 @@
+# Switch — Design (https://design.candescent.com/docs/components/switch)
+
+## Usage
+
+**Example**
+
+**Common alternative names**: Toggle, Toggle switch
+
+---
+
+## **Anatomy**
+
+A switch is made up of a track, and a knob that slides along that track when the switch is toggled.
+
+**Anatomy\_switch**
+
+1. **Knob (unchecked)**: In the unchecked (off) state, the knob is smaller, grey, and on the left side of the track.
+2. **Track (unchecked)**: In the unchecked (off) state, the track is transparent with a grey border.
+3. **Track (checked)**: In the checked (on) state, the track has a solid fill color.
+
+### **Color**
+
+The radio button component is available the colors: **Action**, and **Danger**.
+
+- **color: action**
+
+  Utilizes the defualt color palette. Used for **most switches** in designs.
+- **color: danger**
+
+  Utilizes the danger color palette when checked. Indicates that there is an error with the user’s selection.
+
+### **Platform**
+
+The Switch utilizes the operating system's native switch component on iOS and Android. This causes some visual differences between platforms.
+
+- **Platform: iOS**
+
+  The size for iPhone and iPad. Wider track for touch on native iOS; 64×28 px.
+- **Platform: Web**
+
+  The default for web and desktop. Pointer-friendly control; 48×28 px.
+
+---
+
+Usage
+
+### When to use
+
+> [!TIP]
+>
+> **To allow the user to toggle between two binary states**
+>
+> - ex: _on_ and _off_
+> - ex: _yes_ and _no_
+> - ex: _enabled_ and _disabled_
+
+> [!TIP]
+>
+> **When the change should take immediate effect**
+>
+> - ex: in a settings menu, turning off the WiFi toggle should immediately turn off the WiFi
+> - See the behavior section for details
+
+### When not to use
+
+> [!CAUTION]
+>
+> **Groups of options in a form**
+>
+> - ex: selecting toppings for a pizza
+> - A form can use switch components in certain cases, but they should not generally be grouped.
+> - Use a Form Control with checkboxes or radio buttons instead.
+
+> [!CAUTION]
+>
+> **To allow the user to choose between two options that are not binary**
+>
+> - ex: choosing between a business or personal account for a payment
+> - Use a Form Control with radio buttons instead.
+
+- **Do:** Use switches for settings that have a clear on and off state.
+- **Don't:** Don’t use switches to select options from a list in a form.
+- **Don't:** Don’t use a switch for options that are not a clear on/off or yes/no binary.
+
+### Switch vs checkbox
+
+At first glance, switches and checkboxes appear like they can be used interchangeably. However, the key difference is that toggling a switch should save or take effect immediately, while a checkbox should not take effect until a button is clicked (ex: the **Submit** button on a form).
+
+| \*\* \*\*     | **Switch**                                             | **Checkbox**                         |
+| ------------- | ------------------------------------------------------ | ------------------------------------ |
+| **Behavior**  | Takes effect immediately                               | Takes effect after clicking a button |
+| **Use cases** | Settings, preferences                                  | Forms, surveys, terms and conditions |
+| **Platform**  | Common on mobile and tablet, especially in native apps | Common on both web and mobile        |
+
+### **Labels**
+
+A switch should always have a label. The most common method is to use the switch in a List Item component. The list item label also serves as the switch label. This is a common pattern in settings menus found on mobile devices.
+
+_usage\_labels\_01-ex_
+
+- **Do:** Keep the label positioned at the end.
+- **Caution:** Avoid other label placements unless absolutely necessary.
+
+### **Layout and placement**
+
+The layout and placement of switches depends on the context and the device type.
+
+#### **Forms**
+
+In forms, checkboxes and radio buttons are usually preferred over switches.
+
+- **Do:** Use checkboxes when people can choose none, some, or many options in a list. Selections are submitted with the form, not applied immediately.
+- **Don't:** Don’t use toggles for multi-select lists. Toggles read as instant on/off settings, not optional add-ons.
+
+#### **Settings**
+
+In settings screens and menus, the switch is more commonly placed after the label. Users expect this layout on mobile devices, so using this layout is encouraged when designing for responsive web as well.
+
+- **Do:** People scan labels first, then flip the control where they expect it in a list.
+- **Don't:** Don’t put the switch on the left with the label trailing on the right. It breaks the usual settings pattern and makes the control harder to find and tap.
+
+---
+
+## Behavior
+
+### Toggle states
+
+Due to their binary nature, switches have two toggle states:
+
+- **isChecked: false (default)**
+
+  This state indicates that the current value of the switch represents off, no, false, disabled, etc.
+- **isChecked: true**
+
+  This state indicates that the current value of the switch represents on, yes, true, enabled, etc.
+
+### Interaction states
+
+The default state of an switch is clickable. The appearance of the switch will respond as the user interacts with it.
+
+- **Interaction State: resting**
+
+  The user can interact with the switch in this state.
+- **Interaction State: hover**
+
+  The user is currently hovering over the switch.
+- **Interaction State: focus**
+
+  The user is currently focusing on the switch using keyboard navigation.
+
+### Disabled
+
+Switches can be disabled, which prevents the user from clicking on or interacting with it. Note that disabled switches can appear as checked or unchecked, so this state is often used to show read only switches.
+
+- **isDisabled: true**
+
+  The user cannot interact with the switch in this state.
+
+### Dynamic label text
+
+The label text should describe what the control will do when the switch is on (checked). The label should not change based on the current state of the switch. For more details about writing label text, see the Content tab.
+
+## Content
+
+As mentioned previously, a switch should always be clearly labeled. Consider the following guidelines when writing labels for switches.
+
+## Phrasing
+
+The label text should describe what the control will do when the switch is on (checked); it should not be neutral or ambiguous. When in doubt, say the label aloud and append “on” or “off” to the end. If it doesn’t make sense, rewrite the label.
+
+- **Do:** In this example, the label describes that airplane mode will be on when the switch is on.
+- **Don't:** Don’t start the label with a verb. In this example, “enable airplane mode is off” will confuse users.
+- **Don't:** Don’t change the text of the label based on the state of the switch. Dynamic label text will not meet accessibility guidelines.
+
+## Punctuation
+
+Never end a label with punctuation, even if the label is technically a complete sentence.
+
+- **Do:** Use short, informative labels without punctuation.
+- **Don't:** Don’t use end punctuation, including question marks.
+
+For additional guidance on creating groups of radio buttons, please see the Form Control page. This page includes information about writing the group label, writing and organizing the options, and writing helper text.
+
+## **Opt-in vs. opt-out**
+
+Opt-in and opt-out are two different approaches to gaining consent or permission from a user. Checkboxes and switches are commonly used for these actions. It’s important to know the differences between the two approaches in order to design a user-centered experience.
+
+### **Opt-in**
+
+By default, the user **has not** given permission. The user must actively choose to **give** permission. This approach is generally considered more privacy-friendly.
+
+Common examples:
+
+- A user is asked if they agree to the terms and conditions before they complete their registration.
+- A user is asked if they would like to subscribe to a newsletter before they complete their registration.
+
+### **Opt-out**
+
+By the default, the user **has** given consent or permission. The user must actively choose to **revoke or withdraw** permission. This approach is generally considered less privacy-friendly.
+
+Common examples:
+
+- A user visits a website, and the website considers their use of the website an implicit agreement to the terms and conditions.
+- A user completes their registration, and is then automatically subscribed to that website’s newsletter. They must manually take action to unsubscribe.
+
+### **Further reading**
+
+For further reading about opt-in vs. opt-out, check out [this blog post](https://www.cookieyes.com/blog/opt-in-opt-out/).