@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/chip/design.md

@@ -0,0 +1,418 @@
+# Chip — Design (https://design.candescent.com/docs/components/chip)
+
+## Usage
+
+**Example**
+
+**Common alternative names**: Tag, lozenge, label, category
+
+---
+
+## Anatomy
+
+In its most basic form, a Chip is a short label inside a container. A leading icon and a delete button can also be added to the chip.
+
+**Anatomy\_chip**
+
+1. **Label**: Text that describes the chip’s meaning or action.
+2. **Start Adornment (optional)**: An icon or avatar can be included before the label to add additional affordance a chip.
+3. **Delete button (optional)**: A button that can be used to delete or remove the chip.
+
+### Variant
+
+Chips are available in 2 variants: **Solid** and **Outlined**.
+
+- **Solid**
+
+  Solid background color. Higher emphasis than outlined variant.
+- **Outline**
+
+  Solid outline color, no background color. Lower emphasis than filled variant.
+
+### Color
+
+Chips are versatile, and are available in a wide variety of colors that can be used to indicate different levels of importance or status.
+
+- **color: default**
+
+  Neutral grey, most common, less visual prominence.
+- **color: primary**
+
+  Utilizes the primary brand color palette.
+- **color: danger**
+
+  Used for attributes or actions associated with the terms: error, danger, failure, negative, destructive
+- **color: warning**
+
+  Used for attributes or actions associated with the terms: warning, caution, avoid
+- **color: info**
+
+  Used for attributes or actions associated with the terms: informational, new
+- **color: success**
+
+  Used for attributes or actions associated with the terms: success, successful, completion, positive
+
+### Deletable
+
+A delete button may be added to the end of a chip. Clicking this button should delete/remove/clear the chip.
+
+- **Show Delete?: true**
+
+  An icon button with a cancel icon is displayed after the label (right side).
+
+### Size
+
+Chips are available in 3 sizes: **default, small** and **xsmall**. Size should be considered for visual balance and user focus; larger chips will draw greater attention.
+
+- **size: default**
+
+  Default chips have a height of 32px.
+- **size: small**
+
+  Small chips have a height of 20px.
+- **size: xsmall**
+
+  Mini chips have a height of 16px. The label’s font size does not change.
+
+---
+
+Usage
+
+Chips help users enter information, make selections, filter content, or trigger actions. They’re best used to help users accomplish their current task faster and more easily.
+
+### When to use
+
+> [!TIP]
+>
+> **Visually categorize and label content**
+>
+> - ex: “Dairy”, “Tree nuts”, “Soy”, and other allergens attached to restaurant menu items
+> - ex: “Not started”, “In progress”, and “Complete” on to-do list items
+
+> [!TIP]
+>
+> **Dynamically filter and refine the contents of a page, table, dashboard, etc.**
+>
+> - ex: Quickly selecting one or more categories to filter a list by
+> - ex: Open (and display the current value of) more advanced filter menus
+
+> [!TIP]
+>
+> **Provide dynamically-generated suggestions to help narrow a user’s intent**
+>
+> - ex: Pre-populated responses in a chat window
+> - ex: Suggested search queries
+
+> [!TIP]
+>
+> **Show discrete pieces of user-entered or user-selected information**
+>
+> - ex: Selecting multiple options from a menu in a Select or Autocomplete field
+> - ex: Showing valid contacts entered into the “To” field of a new email
+> - ex: Showing active search terms in an Autocomplete search field
+
+### When not to use
+
+> [!CAUTION]
+>
+> **To take the place of a button or significant call to action**
+>
+> - ex: As the submit button button on a form
+> - ex: As the affirmative or dismissive action in a dialog
+
+### Chips are not buttons
+
+Chips and buttons both prompt users to take actions and make selections. However, they have different use cases, and are not interchangeable.
+
+Buttons should be used for significant calls to action, and represent linear steps that progress the user through the product. Chips should appear dynamically based on the user’s current context, and encourage action by offering optional, forking paths.
+
+- **Do:** Use chips to present contextual, supplemental options
+- **Don't:** Don’t replace major actions with chips. Actions that progress users the next or previous step should always be buttons.
+
+### Types
+
+Chips are an extremely versatile component. We’ve grouped them into categories based on their intended use, following the lead of the Material Guidelines. Each type has their own set of best practices and behaviors.
+
+| **Chip type**  | **Purpose** | **Created by**      | **Behavior**                                                                 |
+| -------------- | ----------- | ------------------- | ---------------------------------------------------------------------------- |
+| **Tag**        | Categorize  | Application         | Visually categorize and label content                                        |
+| **Suggestion** | Information | Application         | Provide dynamically-generated suggestions to help narrow a user’s intent     |
+| **Filter**     | Filter      | Application or User | Dynamically filter and refine the contents of a page, table, dashboard, etc. |
+
+### Tag chips
+
+Tag chips are used to assign relevant terms or categories to items in the application for easy retrieval and comprehension. They enhance organization and provide meaningful context to various elements within the application.
+
+_usage\_tag\_01-ex_
+
+When to use
+
+> [!TIP]
+>
+> **To show multiple item categories**
+>
+> - ex: “Dairy”, “Tree nuts”, “Soy”, and other allergens attached to restaurant menu items
+> - ex: “Utilities”, “Takeout”, “Subscription”, or other categories assigned to transactions
+
+> [!TIP]
+>
+> **To provide status on an item**
+>
+> - ex: “Not started”, “In progress”, and “Complete” on to-do list items
+> - ex: “Offline”, “Online”, and “On a call” on a teller status dashboard
+
+When not to use
+
+> [!CAUTION]
+>
+> **Numerical counts**
+>
+> - Use a Badge component instead
+
+#### **Layout and placement**
+
+Chips are most often used in multiples, so they can easily look cluttered. To avoid this, place multiple chips in a horizontal row. When needed, chips should either wrap to additional lines, or in fixed-height areas, use horizontal scrolling and a “peek” view of the next chip.
+
+We recommend 8px of space between each chip, vertically and horizontally.
+
+**Example**
+
+#### Variants
+
+Tag chips have the most flexibility when it comes to color. When choosing a color, keep in mind that each color carries inherent meaning to users, so align your choice to that meaning.
+
+- **Default**: neutral grey
+- **Primary**: varies based on customer brand
+- **Danger**: error, danger, failure, negative, destructive
+- **Warning**: warning, caution, avoid
+- **Info**: informational, new
+- **Success**: success, successful, completion, positive
+
+In addition to color, tag chips often use an icon to reinforce the chip’s meaning. This is especially helpful for the chips using **severity colors** (error, warning, info, and success), as icons enable the user to understand the chip’s meaning at a quick glance.
+
+- **Do:** Use icons in combination with color to help reinforce the chip’s meaning.
+- **Don't:** Don’t use mismatched icons and colors with mismatched meanings. For example, the Warning color with the Info icon.
+
+### **Filter chips**
+
+Filter chips utilize keywords and tags to dynamically search through and refine content. They can serve as a good alternative to checkboxes and toggle buttons for selecting options.
+
+_usage\_filter\_01-ex_
+
+When to use
+
+> [!TIP]
+>
+> **To filter content on the current page, table, dashboard, etc.**
+>
+> - ex: Quickly selecting one or more categories to filter a list by
+> - ex: Open (and display the current value of) more advanced filter menus
+
+When not to use
+
+> [!CAUTION]
+>
+> **When the intent is to show new content on a page after clicking**
+>
+> - ex: Swapping to a different table or different data visualizations
+> - Use Tabs instead
+
+> [!CAUTION]
+>
+> **In a form where the intent is to select one option**
+>
+> - ex: Using a row of chips to select a shirt size
+> - Use a Form Control or [Select](https://design.candescent.com/docs/components/select/content.md) instead
+
+Layout and placement
+
+Place filter chips in a horizontal row. Use horizontal scrolling and a “peek” view of the next chip if needed. We recommend 8px of space between each chip.
+
+Additionally, filter chips should typically be placed above the content they are filtering. This helps the user understand what area the filter applies to.
+
+_usage\_filter\_layout\_01-ex_
+
+Variants
+
+The Chip component does not have predefined variants for “unselected” and “selected”. For the unselected state, we recommend the **default** color and either the **solid** or **outlined** variant. For the selected state, we recommend the **action** color, the **solid** variant, and adding a Check icon.
+
+- **Do:** Change the color AND the icon to show the selected state.
+- **Don't:** Don’t rely on just color changes. At least 2 visual differences are required to meet accessibility guidelines.
+
+### **Suggestion chips**
+
+Suggestion chips are valuable aids in refining user intent, providing dynamically-generated options like response suggestions or search filters.
+
+_usage\_suggestion\_01-ex_
+
+When to use
+
+> [!TIP]
+>
+> **To help users expedite the task at hand**
+>
+> - ex: Pre-populated responses in a chat window
+> - ex: Suggested search queries
+
+When not to use
+
+> [!CAUTION]
+>
+> **Long sentences**
+>
+> - Use a word or short phrase only
+
+Layout and placement
+
+Suggestion chips should be placed in close proximity to where the user takes action – generally directly above or below.
+
+_usage\_suggestion\_layout\_01-ex_
+
+Variants
+
+We recommend using neutral colors such as **default** or **primary**, for suggestion chips. Additionally, avoid using the small size for suggestion chips.
+
+- **Don't:** Don’t use semantic colors or other non-neutral colors for suggestion chips.
+- **Don't:** Don’t use the small size for suggestion chips, especially on mobile breakpoints.
+
+---
+
+## Behavior
+
+### Static
+
+By default, chips are static, and cannot be interacted with by the user. This allows chips to act as tags – visual labels that are used to categorize content. See the [Tag chips](https://design.candescent.com/docs/components/chip/content.md) section for details.
+
+### Clickable
+
+Chips can also be clickable. Clickable chips are interactive in a similar way to other button components.
+
+- **Interaction State: resting (default)**
+
+  Default state. User is not interacting with the chip.
+- **Interaction State: hover**
+
+  When the user’s cursor is hovering over the chip.
+- **Interaction State: focus**
+
+  When a keyboard user is focused on the chip using tab navigation controls.
+
+When the chip is focused, pressing Space or Enter should trigger the same action as a click. Pressing Esc will blur (unfocus) the chip.
+
+Deletable
+
+Chips can also be deletable. Deletable chips should display a delete icon in the `Chip.TrailingIcon` slot of the component. Clicking this icon should delete, remove, or clear the chip.
+
+- **Interaction State: resting (default)**
+
+  Default state. User is not interacting with the chip.
+- **Interaction State: hover**
+
+  When the user’s cursor is hovering over the delete button within the chip.
+- **Interaction State: focus**
+
+  When a keyboard user is focused on the chip using tab navigation controls.
+
+Even if the chip is not clickable, it should still be focusable in the tab order. When the chip is focused, pressing Backspace or Delete should trigger the same action as clicking the delete icon.
+
+### Clickable and deletable
+
+A chip can be both clickable and deletable.
+
+- **Interaction State: resting (default)**
+
+  Default state. User is not interacting with the chip.
+- **Interaction State: hover**
+
+  When the user’s cursor is hovering over the chip.
+- **Interaction State: focus**
+
+  When a keyboard user is focused on the chip using tab navigation controls.
+
+### Disabled
+
+Chips can be disabled, which prevents the user from clicking on or interacting with the chip. Using disabled chips can cause accessibility issues so try and avoid them, as they often create more problems than they solve. Keep chips active and use clear error messaging to guide users whenever possible. Use disabled chips only in rare edge cases.
+
+- **isDisabled: true**
+
+  The user cannot interact with the chip (or the delete button) in this state.
+
+### Keyboard controls
+
+Like other clickable and interactive components, users should be able to interact with chips using keyboard controls.
+
+#### Moving focus
+
+Chips that are clickable and/or deletable should be placed in the tab order. Users should be able to move between them using Tab and Shift + Tab.
+
+_behavior\_menu\_01-ex_
+
+#### **Clicking**
+
+When the user is focused on a clickable chip, pressing Space or Enter should trigger the same action as a click.
+
+_behavior\_menu\_02-ex_
+
+#### **Deleting**
+
+When the user is focused on a deletable chip (even if it is not clickable), pressing Backspace or Delete should trigger the same action as clicking the delete icon.
+
+_behavior\_menu\_03-ex_
+
+#### **Unfocusing**
+
+When the user is focused on chip, pressing `Esc` will unfocus (or blur) the chip.
+
+_behavior\_menu\_04-ex_
+
+## Content
+
+## Writing label text
+
+The label text of a chip should help the user understanding the meaning of the chip at a quick glance. Since the width of the chip is determined by the length of the text, labels should be short and direct.
+
+Use the following guidelines when writing button labels:
+
+- Labels should be short, but their meaning should still be clear.
+- Write labels in sentence case.
+- Limit labels to short phrases, even in suggestion chips.
+
+* **Do:** Use short, direct labels that help the user understand the purpose of the chip.
+* **Don't:** Don’t wrap or truncate text within chips. Find a way to write a shorter label if there isn’t enough room.
+
+## Choosing an adornment
+
+Adornments can be useful for reinforcing the chip’s purpose, and can help the user scan the page more quickly. Make sure that the adornment has a clear **affordance** – the meaning of the icon or avatar should be easily understood, and reinforce the meaning conveyed by the chip’s label and color.
+
+Our specific guidelines for adornments vary for each type of chip.
+
+Tag chips
+
+Adornments are commonly used in tag chips. Icons are especially useful for adding a useful symbol to categories, or reinforcing the meaning of a chip using a semantic color (error, warning, info, or success).
+
+However, keep in mind that adornments should help the user scan the page more quickly, and not add unnecessary visual clutter.
+
+- **Do:** If the label text describes the meaning of the chip (in this case, the trend direction), then the icon is just a recommended addition.
+- **Do:** If the label text does not describe the meaning on its own, an icon is required to reinforce the color.
+- **Don't:** Don’t convey the meaning of the chip just using color. This does not meet accessibility requirements.
+
+### Suggestion chip
+
+We do not recommend using adornments for suggestion chips. Keep the focus on the suggested keywords or phrases.
+
+- **Do:** Keep suggestion chips clean and focused on text-only labels. Simple, clear wording helps users quickly scan options and understand what action to take without added visual noise.
+- **Don't:** Avoid adding unnecessary icons to suggestion chips. Extra visuals can create clutter and distract from the label, making it harder for users to quickly understand and choose an option.
+
+### Filter chip
+
+Adornments can be used in filter chips, but make sure that they do not conflict with the active state’s checkmark icon.
+
+- **Do:** If the filter chips use icons, change the icon to a checkmark when the chip is selected.
+- **Don't:** If the filter chips use icons, just changing the color is not enough to meet accessibility requirements. Also, don’t add a checkmark icon next to the other icon.
+
+### **Input chip**
+
+Adornments are occasionally used in input chips. Avatars are especially useful for showing profile photos when selecting users or contacts. When using avatars in input chips, make sure that there is a fallback for users who do not have a profile photo.
+
+- **Do:** Use avatars for profile photos. If a user does not have a photo, use their initials as a fallback.
+- **Don't:** Don’t force the avatar to be a photo. There must be a fallback for users without a profile photo.

package/docs/components/color-area/content.md

@@ -0,0 +1,84 @@
+# Color Area (https://design.candescent.com/docs/components/color-area)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorarea--default)
+
+`ColorArea` selects saturation horizontally and brightness vertically.
+
+```tsx
+import { ColorArea, parseColor } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { useState } from 'react';
+import { ColorArea, parseColor, type Color } from '@cdx-ui/components';
+
+function requiredColor(value: string): Color {
+  const color = parseColor(value);
+  if (!color) {
+    throw new Error(`Expected ${value} to parse`);
+  }
+  return color;
+}
+
+export default function ColorAreaBasicDemo() {
+  const [value, setValue] = useState(requiredColor('#2F6FED'));
+
+  return (
+    <ColorArea value={value} onValueChange={setValue} accessibilityLabel="Brand color">
+      <ColorArea.Thumb />
+    </ColorArea>
+  );
+}
+```
+
+## API
+
+### ColorArea
+
+Owns standalone color state or reads the shared value when nested in `ColorPicker`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `value?` | `Color` | — | Current controlled color. |
+| `defaultValue?` | `Color` | — | Initial color for uncontrolled usage. |
+| `onValueChange?` | `((value: Color) => void)` | — | Called while either color channel changes. |
+| `onValueChangeComplete?` | `((value: Color) => void)` | — | Called when a pointer, keyboard, or screen reader interaction completes. |
+| `colorSpace?` | `'hsb'` | ``'hsb'`` | Color space represented by the area. |
+| `xChannel?` | `'saturation'` | ``'saturation'`` | Horizontal channel. |
+| `yChannel?` | `'brightness'` | ``'brightness'`` | Vertical channel. |
+| `step?` | `number` | ``1`` | Arrow-key and screen-reader increment. |
+| `pageStep?` | `number` | ``10`` | Shift-arrow and page-key increment. |
+| `isRTL?` | `boolean` | — | Overrides the platform layout direction for horizontal interaction. |
+| `isDisabled?` | `boolean` | ``false`` | Disables pointer, keyboard, and screen reader interaction. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Sub-components
+
+### ColorArea.Thumb
+
+Displays the current color and exposes the two-dimensional slider interaction.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Anatomy
+
+| `data-slot`        | Element                   |
+| ------------------ | ------------------------- |
+| `color-area`       | Gradient interaction area |
+| `color-area-thumb` | Current color position    |
+
+## Accessibility
+
+Give the area an accessible label. Keyboard users adjust saturation with horizontal arrows and brightness with vertical arrows; native screen readers expose each channel as an adjustable control.

package/docs/components/color-field/content.md

@@ -0,0 +1,132 @@
+# Color Field (https://design.candescent.com/docs/components/color-field)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorfield--default)
+
+`ColorField` parses full hex values or edits a single RGB or HSL channel.
+
+```tsx
+import { ColorField, ColorSwatch, Field, parseColor } from '@cdx-ui/components';
+```
+
+## Basic
+
+Compose `Field` for the visible label and place an optional swatch in `ColorField.Slot`.
+
+```tsx
+import { useState } from 'react';
+import { ColorField, ColorSwatch, Field, parseColor, type Color } from '@cdx-ui/components';
+
+function requiredColor(value: string): Color {
+  const color = parseColor(value);
+  if (!color) {
+    throw new Error(`Expected ${value} to parse`);
+  }
+  return color;
+}
+
+export default function ColorFieldBasicDemo() {
+  const [value, setValue] = useState(requiredColor('#2F6FED'));
+
+  return (
+    <Field name="brandColor" className="w-full max-w-xs">
+      <Field.Label>Brand color</Field.Label>
+      <ColorField value={value} onValueChange={setValue}>
+        <ColorField.Group>
+          <ColorField.Slot position="leading">
+            <ColorSwatch color={value} size="xs" />
+          </ColorField.Slot>
+          <ColorField.Input />
+        </ColorField.Group>
+      </ColorField>
+    </Field>
+  );
+}
+```
+
+## API
+
+### ColorField
+
+Owns standalone text and color state or edits the shared value when nested in `ColorPicker`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `variant?` | `'outline' \| null` | — | — |
+| `size?` | `'default' \| 'small' \| null` | — | — |
+| `value?` | `Color` | — | — |
+| `defaultValue?` | `Color` | — | — |
+| `onValueChange?` | `((value: Color) => void)` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+| `isReadOnly?` | `boolean` | — | — |
+| `isInvalid?` | `boolean` | — | — |
+| `isRequired?` | `boolean` | — | — |
+| `colorSpace?` | `'rgb' \| 'hsl'` | — | — |
+| `channel?` | `'red' \| 'green' \| 'blue' \| 'hue' \| 'saturation' \| 'lightness'` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `fullWidth?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Sub-components
+
+### ColorField.Group
+
+Provides the styled input shell and optional slots.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `variant?` | `'outline' \| null` | — | — |
+| `size?` | `'default' \| 'small' \| null` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `fullWidth?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### ColorField.Input
+
+The editable text input. Units such as `°` and `%` are part of channel text.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `type?` | `'text' \| 'password' \| 'file'` | `'text'` | — |
+| `disabled?` | `boolean` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+| `isInvalid?` | `boolean` | — | — |
+| `isReadOnly?` | `boolean` | — | — |
+| `isRequired?` | `boolean` | — | — |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default host. The primitive merges its wired behavior (focus/blur, ARIA props, refs) onto the child. When set, the `type="file"` web branch is bypassed. |
+| `placeholderTextColorClassName?` | `string` | — | — |
+
+Inherits all [`TextInputProps`](https://reactnative.dev/docs/textinput#props).
+
+### ColorField.Slot
+
+A leading or trailing layout slot for a swatch or other adornment.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `position?` | `'leading' \| 'trailing'` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Anatomy
+
+| `data-slot`         | Element        |
+| ------------------- | -------------- |
+| `color-field`       | Root container |
+| `color-field-group` | Input shell    |
+| `color-field-input` | Editable input |
+| `color-field-slot`  | Adornment slot |
+
+## Accessibility
+
+Compose `ColorField` inside `Field` to associate a visible label and validation message with the input. Invalid mid-edit text remains local and does not replace the current color.