@cdx-ui/components 0.2.2 → 0.2.4

package/docs/components/checkbox/content.md

@@ -0,0 +1,236 @@
+# Checkbox (https://design.candescent.com/docs/components/checkbox)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=366-383), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-checkbox--states)
+
+A compound component with sub-components for indicator, icon, label, and grouping.
+
+```tsx
+import { Checkbox } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { Checkbox } from '@cdx-ui/components';
+
+export default function CheckboxBasicDemo() {
+  return (
+    <Checkbox value="terms">
+      <Checkbox.Label>I agree to the terms and conditions</Checkbox.Label>
+    </Checkbox>
+  );
+}
+```
+
+## Group
+
+```tsx
+import { useState } from 'react';
+import { Checkbox } from '@cdx-ui/components';
+
+export default function CheckboxGroupDemo() {
+  const [selected, setSelected] = useState<string[]>(['notifications']);
+
+  return (
+    <Checkbox.Group value={selected} onChange={setSelected} aria-label="Email preferences">
+      <Checkbox value="notifications">
+        <Checkbox.Label>Email notifications</Checkbox.Label>
+      </Checkbox>
+      <Checkbox value="updates">
+        <Checkbox.Label>Product updates</Checkbox.Label>
+      </Checkbox>
+      <Checkbox value="marketing">
+        <Checkbox.Label>Marketing emails</Checkbox.Label>
+      </Checkbox>
+    </Checkbox.Group>
+  );
+}
+```
+
+## Indeterminate
+
+```tsx
+import { useState } from 'react';
+import { Checkbox, Box } from '@cdx-ui/components';
+
+export default function CheckboxIndeterminateDemo() {
+  const options = ['Read', 'Write', 'Execute'];
+  const [selected, setSelected] = useState<string[]>(['Read']);
+
+  const allChecked = selected.length === options.length;
+  const isIndeterminate = selected.length > 0 && !allChecked;
+
+  return (
+    <Box className="gap-2">
+      <Checkbox
+        value="all"
+        isChecked={allChecked}
+        isIndeterminate={isIndeterminate}
+        onChange={(checked) => setSelected(checked ? options : [])}
+      >
+        <Checkbox.Label>Select all permissions</Checkbox.Label>
+      </Checkbox>
+
+      <Box className="ml-6">
+        <Checkbox.Group value={selected} onChange={setSelected} aria-label="Individual permissions">
+          {options.map((option) => (
+            <Checkbox key={option} value={option}>
+              <Checkbox.Label>{option}</Checkbox.Label>
+            </Checkbox>
+          ))}
+        </Checkbox.Group>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Disabled
+
+```tsx
+import { Checkbox, Box } from '@cdx-ui/components';
+
+export default function CheckboxDisabledDemo() {
+  return (
+    <Box className="gap-2">
+      <Checkbox value="unchecked" isDisabled>
+        <Checkbox.Label>Disabled unchecked</Checkbox.Label>
+      </Checkbox>
+      <Checkbox value="checked" isChecked isDisabled>
+        <Checkbox.Label>Disabled checked</Checkbox.Label>
+      </Checkbox>
+    </Box>
+  );
+}
+```
+
+## Invalid
+
+```tsx
+import { Checkbox } from '@cdx-ui/components';
+
+export default function CheckboxInvalidDemo() {
+  return (
+    <Checkbox value="required-field" isInvalid>
+      <Checkbox.Label>You must accept the terms to continue</Checkbox.Label>
+    </Checkbox>
+  );
+}
+```
+
+## With field
+
+```tsx
+import { useState } from 'react';
+import { Checkbox, Field } from '@cdx-ui/components';
+
+export default function CheckboxWithFieldDemo() {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <Field isRequired isInvalid={selected.length === 0}>
+      <Field.Label>Notification channels</Field.Label>
+      <Checkbox.Group value={selected} onChange={setSelected}>
+        <Checkbox value="email">
+          <Checkbox.Label>Email</Checkbox.Label>
+        </Checkbox>
+        <Checkbox value="sms">
+          <Checkbox.Label>Text message</Checkbox.Label>
+        </Checkbox>
+        <Checkbox value="push">
+          <Checkbox.Label>Push notification</Checkbox.Label>
+        </Checkbox>
+      </Checkbox.Group>
+      <Field.Error>Select at least one notification channel.</Field.Error>
+    </Field>
+  );
+}
+```
+
+## API
+
+### Checkbox
+
+Auto-renders its indicator and check icon — compose `Checkbox.Label` inside it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the checkbox's own styles. |
+| `children?` | `ReactNode` | — | Content rendered after the indicator, typically a `Checkbox.Label`. |
+| `value` | `string` | — | Identifies this checkbox. Must be unique among siblings in a `Checkbox.Group`. |
+| `onChange?` | `((isSelected: boolean) => void)` | — | Called with the new checked state when the user toggles the checkbox. |
+| `defaultIsChecked?` | `boolean` | — | Initial checked state when uncontrolled. No effect when `isChecked` is set. |
+| `isChecked?` | `boolean` | — | Controlled checked state. When set, `defaultIsChecked` has no effect. |
+| `isDisabled?` | `boolean` | — | Prevents interaction and applies disabled styling. Inherited from a parent `Checkbox.Group` or form field when omitted. |
+| `isInvalid?` | `boolean` | — | Applies invalid styling. Inherited from a parent form field when omitted. |
+| `isReadOnly?` | `boolean` | — | Focusable, but the checked state cannot be changed. |
+| `isRequired?` | `boolean` | — | Marks the checkbox as required. |
+| `isIndeterminate?` | `boolean` | — | Shows the indeterminate (mixed) icon instead of the check, regardless of `isChecked`. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+## Sub-components
+
+### Checkbox.Label
+
+Text label rendered alongside the checkbox indicator. Automatically receives disabled state from context.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the label's own styles. |
+| `children?` | `ReactNode` | — | Label content (or a custom element when `asChild` is set). |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default `Text` host. |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Checkbox.Indicator
+
+The visual box that displays the checked, unchecked, or indeterminate state. Auto-rendered by the root and exposed for custom composition. Reads interaction and validation state from context.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the indicator's own styles. |
+| `children?` | `ReactNode` | — | Indicator content, typically a `Checkbox.Icon`. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default `View` host. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Checkbox.Icon
+
+The check or indeterminate icon rendered inside the indicator when checked or indeterminate. Auto-rendered; include it only to customize the glyph.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `filled?` | `boolean` | — | When `true`, renders the filled variant of the icon (if available). Defaults to `false` (outlined). |
+| `size?` | `string \| number` | — | Width and height of the icon, in pixels or any SVG length. The bare icon renders at 24 when omitted. |
+| `data-testid?` | `string` | — | Test identifier forwarded to the rendered SVG. |
+| `as` | `ForgeIcon` | — | The `@cdx-ui/icons` component to render. |
+
+Inherits all `ForgeIconProps` (react-native-svg `SvgProps` plus `filled` and `size`).
+
+### Checkbox.Group
+
+Groups multiple checkboxes with shared state management and consistent spacing.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the group's own styles. |
+| `children?` | `ReactNode` | — | The `Checkbox` items in the group. |
+| `value?` | `string[]` | `[]` | The `value` of every checked checkbox in the group. |
+| `onChange?` | `((value: string[]) => void)` | — | Called with the updated list of checked values when the user toggles a checkbox. |
+| `isDisabled?` | `boolean` | — | Disables every checkbox in the group. |
+| `isInvalid?` | `boolean` | — | Marks the group as invalid. Set `isInvalid` on each `Checkbox` to style it as invalid. |
+| `isReadOnly?` | `boolean` | — | Makes every checkbox in the group focusable but unchangeable. |
+| `direction?` | `'column' \| 'row'` | `'column'` | Stacks the checkboxes vertically (`column`) or lays them out in a row. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Prop         | Type                        | Default    | Description                          |
+| ------------ | --------------------------- | ---------- | ------------------------------------ |
+| `value`      | `string[]`                  | `[]`       | Currently selected checkbox values   |
+| `onChange`   | `(value: string[]) => void` | —          | Called when selection changes        |
+| `isDisabled` | `boolean`                   | `false`    | Disables all checkboxes in the group |
+| `isInvalid`  | `boolean`                   | `false`    | Marks all checkboxes as invalid      |
+| `isReadOnly` | `boolean`                   | `false`    | Makes all checkboxes read-only       |
+| `direction`  | `'column' \| 'row'`         | `'column'` | Layout direction of the group        |

package/docs/components/checkbox/design.md

@@ -0,0 +1,214 @@
+# Checkbox — Design (https://design.candescent.com/docs/components/checkbox)
+
+## Usage
+
+**Example**
+
+**Common alternative names**: Check, checkmark, tick, tick mark
+
+---
+
+## Anatomy
+
+A Checkbox is made up of a square container and a checkmark icon.
+
+**Anatomy\_checkbox**
+
+1. **Square container**: The empty square container that will contain the checkmark icon when checked.
+2. **Checkmark icon**: Shows that the checkbox is currently in the checked state.
+3. **Indeterminate icon**: Shows that the checkbox is currently in the indeterminate state.
+
+### Color
+
+The checkbox component is available the colors: **Action**, and **Danger**.
+
+- **color: action**
+
+  Utilizes the primary color palette. Used for most checkboxes in designs.
+- **color: danger**
+
+  Utilizes the error color palette when checked. Indicates that there is an error with the user’s selection.
+
+### Size
+
+Checkboxes are available in **Default** and **Small** sizes. Small checkboxes should only be used on desktop devices because they do not meet the minimum touch target requirements.
+
+- **size: default**
+
+  The default size: 20×20 px
+- **size: small**
+
+  A slightly smaller size: ??x?? px
+
+---
+
+Usage
+
+### When to use
+
+> [!TIP]
+>
+> **When a user needs to select any number of options from a list**
+>
+> - ex: While ordering a pizza, a customer may select **none**, **one**, or **multiple** pizza toppings.
+> - ex: A user viewing a report may select **none**, **one**, or **multiple** options to filter the data.
+
+> [!TIP]
+>
+> **When a user must select a minimum number of options from a list**
+>
+> - ex: While ordering a pizza, a customer must select **at least 1** type of pizza sauce.
+> - ex: An applicant must select **at least 3** skills they know on a job application.
+
+> [!TIP]
+>
+> **Selecting multiple items for batch actions**
+>
+> - ex: A user may select multiple rows of a table to delete them all at the same time.
+
+> [!TIP]
+>
+> **When a user can turn on/off a single option**
+>
+> - ex: User selects a checkbox to indicate that they agree to the terms & conditions
+
+- **Do:** Use a checkbox for agreeing to terms and conditions, and other similar inputs in forms.
+- **Don't:** Don’t use a switch for agreeing to terms and conditions.
+
+### When not to use
+
+> [!CAUTION]
+>
+> **When a user may only select one option**
+>
+> - ex: A Yes or No question
+> - ex: Choosing between making something public or private
+> - Instead, try using radio buttons.
+
+- **Do:** Use checkboxes when a user may select multiple items
+- **Don't:** Don’t use checkboxes when a user may only select one item. Instead, use radio buttons.
+
+### Labels
+
+A Checkbox should always have a label. The most common method is to use the label built-in to the Checkbox component.
+
+- **Show Label?: true**
+
+  Displays a label after the Checkbox.
+
+#### **Overflow**
+
+Labels should be kept short and concise. But when this isn’t possible, you may wrap the text down to a second line.
+
+- **Do:** When necessary, long labels can wrap to a second line.
+- **Don't:** Don't truncate the label text.
+
+#### **Other labeling methods**
+
+Checkboxes can also be given labels by being part of a list or table.
+
+- **List Item**
+
+  A checkbox can be added to the left content slot of List Item component. This is useful for allowing the user to select from a more complex list. Each item serves as the “label”.
+- **DataGrid**
+
+  In a DataGrid table, rows can be made selectable. This adds a checkbox to each row, including one in the header that allows the user to select the entire table. Each row serves as the “label”.
+
+### **Layout and placement**
+
+Checkboxes are most commonly used inside of a Form Control component. This component wraps the checkboxes with a label for the group and optional helper text, enables the correct behavior and WCAG considerations, and provides layout controls. See the Form Control page for details and best practices.
+
+---
+
+## **Behavior**
+
+### Selection states
+
+Checkboxes have three states of being selected (checked):
+
+- **isChecked: false (default)**
+
+  This state indicates that the item **is not** currently selected.
+- **isChecked: true**
+
+  This state indicates that the item **is** currently selected.
+- **isIndeterminate: true**
+
+  This is a special state used for items that have children. It indicates that some (but not all) of the children are selected.
+
+### Interaction states
+
+The default state of an checkbox is clickable. The appearance of the checkbox will respond as the user interacts with it.
+
+- **Interaction State: resting**
+
+  The user can interact with the checkbox in this state.
+- **Interaction State: hover**
+
+  The user is currently hovering over the checkbox.
+- **Interaction State: focus**
+
+  The user is currently focusing on the checkbox using keyboard navigation.
+
+### Disabled
+
+Checkboxes can be disabled, which prevents the user from clicking on or interacting with it. Note that disabled checkboxes can appear as unchecked, checked, or indeterminate, so this state is often used to show **read only** checkboxes.
+
+- **isDisabled: true**
+
+  The user cannot interact with the checkbox in this state.
+
+## Content
+
+As mentioned previously, a checkbox should always be clearly labeled. Consider the following guidelines when writing labels for checkboxes.
+
+## Punctuation
+
+Never end a label with punctuation, even if the label is technically a complete sentence.
+
+- **Do:** Even complete sentences don’t need end punctuation.
+- **Don't:** Don’t use end punctuation, even on complete sentences.
+
+## Multiple options in a set
+
+When multiple labeled checkboxes are used as a set of options, the options could be single nouns, phrases, or even short sentences. Try to keep the options matching in style.
+
+- **Do:** Use the same style for each option. In this example, each option is the name of a skill.
+- **Don't:** Don’t mix different styles. In this example, the first option has a verb, but the other options do not.
+
+For additional guidance on creating groups of checkboxes, please see the Form Control page. This page includes information about writing the group label, writing and organizing the options, and writing helper text.
+
+## Negations
+
+Avoid using negations, especially double negatives. These may confuse the user about what is actually being asked. Always be as clear as possible.
+
+- **Do:** In this example, it’s clear that checking an item represents the user adding that topping to their pizza.
+- **Don't:** Don’t use negation in options. In this example, the user must check every checkbox if they want no toppings.
+- **Do:** This example clearly implies that checking the Checkbox is the user consenting to receive marketing emails.
+- **Don't:** The negation “don’t” in this example may cause confusion, especially because it is an opt-out scenario.
+
+## 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/).