@cdx-ui/components 0.2.2 → 0.2.4

package/docs/components/button/content.md

@@ -0,0 +1,398 @@
+# Button (https://design.candescent.com/docs/components/button)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=119-72), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/actions-button--default)
+
+A compound component with sub-components for label, icon, spinner, and grouping.
+
+```tsx
+import { Button } from '@cdx-ui/components';
+```
+
+## Variants
+
+```tsx
+import { Button, Box } from '@cdx-ui/components';
+
+export default function ButtonVariantsDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <Button variant="solid">
+        <Button.Label>Solid</Button.Label>
+      </Button>
+      <Button variant="outline">
+        <Button.Label>Outline</Button.Label>
+      </Button>
+      <Button variant="ghost">
+        <Button.Label>Ghost</Button.Label>
+      </Button>
+    </Box>
+  );
+}
+```
+
+### Solid
+
+```tsx
+import { Button, Box } from '@cdx-ui/components';
+
+export default function ButtonSolidDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <Button variant="solid" color="action">
+        <Button.Label>Action</Button.Label>
+      </Button>
+      <Button variant="solid" color="danger">
+        <Button.Label>Danger</Button.Label>
+      </Button>
+      <Button variant="solid" color="warning">
+        <Button.Label>Warning</Button.Label>
+      </Button>
+      <Button variant="solid" color="success">
+        <Button.Label>Success</Button.Label>
+      </Button>
+      <Button variant="solid" color="info">
+        <Button.Label>Info</Button.Label>
+      </Button>
+    </Box>
+  );
+}
+```
+
+### Outline
+
+```tsx
+import { Button, Box } from '@cdx-ui/components';
+
+export default function ButtonOutlineDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <Button variant="outline" color="action">
+        <Button.Label>Action</Button.Label>
+      </Button>
+      <Button variant="outline" color="danger">
+        <Button.Label>Danger</Button.Label>
+      </Button>
+      <Button variant="outline" color="warning">
+        <Button.Label>Warning</Button.Label>
+      </Button>
+      <Button variant="outline" color="success">
+        <Button.Label>Success</Button.Label>
+      </Button>
+      <Button variant="outline" color="info">
+        <Button.Label>Info</Button.Label>
+      </Button>
+    </Box>
+  );
+}
+```
+
+### Ghost
+
+```tsx
+import { Button, Box } from '@cdx-ui/components';
+
+export default function ButtonGhostDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <Button variant="ghost" color="action">
+        <Button.Label>Action</Button.Label>
+      </Button>
+      <Button variant="ghost" color="danger">
+        <Button.Label>Danger</Button.Label>
+      </Button>
+      <Button variant="ghost" color="warning">
+        <Button.Label>Warning</Button.Label>
+      </Button>
+      <Button variant="ghost" color="success">
+        <Button.Label>Success</Button.Label>
+      </Button>
+      <Button variant="ghost" color="info">
+        <Button.Label>Info</Button.Label>
+      </Button>
+    </Box>
+  );
+}
+```
+
+## Sizes
+
+```tsx
+import { Button, Box } from '@cdx-ui/components';
+
+export default function ButtonSizeDemo() {
+  return (
+    <Box className="flex-row gap-4">
+      <Box className="flex-col gap-4">
+        <Button variant="solid" size="default">
+          <Button.Label>Default</Button.Label>
+        </Button>
+        <Button variant="solid" size="small">
+          <Button.Label>Small</Button.Label>
+        </Button>
+      </Box>
+      <Box className="flex-col gap-4">
+        <Button variant="outline" size="default">
+          <Button.Label>Default</Button.Label>
+        </Button>
+        <Button variant="outline" size="small">
+          <Button.Label>Small</Button.Label>
+        </Button>
+      </Box>
+      <Box className="flex-col gap-4">
+        <Button variant="ghost" size="default">
+          <Button.Label>Default</Button.Label>
+        </Button>
+        <Button variant="ghost" size="small">
+          <Button.Label>Small</Button.Label>
+        </Button>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## With icons
+
+```tsx
+import { Button, View } from '@cdx-ui/components';
+import { AddIcon, DeleteIcon, SendIcon } from '@cdx-ui/icons';
+
+export default function ButtonIconsDemo() {
+  return (
+    <View className="flex-row flex-wrap gap-4">
+      <Button variant="outline">
+        <Button.Icon as={AddIcon} />
+        <Button.Label>Add</Button.Label>
+      </Button>
+      <Button color="danger">
+        <Button.Icon as={DeleteIcon} />
+        <Button.Label>Delete</Button.Label>
+      </Button>
+      <Button>
+        <Button.Label>Send</Button.Label>
+        <Button.Icon as={SendIcon} />
+      </Button>
+    </View>
+  );
+}
+```
+
+## Loading
+
+```tsx
+import { Button, Box } from '@cdx-ui/components';
+
+export default function ButtonLoadingDemo() {
+  return (
+    <Box className="flex-row flex-wrap gap-4">
+      <Button variant="solid" color="action">
+        <Button.Spinner />
+        <Button.Label>Loading</Button.Label>
+      </Button>
+      <Button variant="outline" color="action">
+        <Button.Spinner />
+        <Button.Label>Loading</Button.Label>
+      </Button>
+      <Button variant="ghost" color="action">
+        <Button.Spinner />
+        <Button.Label>Loading</Button.Label>
+      </Button>
+    </Box>
+  );
+}
+```
+
+## Full-width
+
+```tsx
+import { Button, Box } from '@cdx-ui/components';
+
+export default function ButtonFullWidthDemo() {
+  return (
+    <Box className="gap-4 w-64">
+      <Button fullWidth variant="solid">
+        <Button.Label>Submit</Button.Label>
+      </Button>
+      <Button fullWidth variant="outline">
+        <Button.Label>Delete</Button.Label>
+      </Button>
+      <Button fullWidth variant="ghost">
+        <Button.Label>Cancel</Button.Label>
+      </Button>
+    </Box>
+  );
+}
+```
+
+## Disabled
+
+```tsx
+import { Button, Box } from '@cdx-ui/components';
+
+export default function ButtonDisabledDemo() {
+  return (
+    <Box className="flex-row flex-wrap gap-4">
+      <Button variant="solid" color="action" isDisabled>
+        <Button.Label>Action</Button.Label>
+      </Button>
+      <Button variant="solid" color="danger" isDisabled>
+        <Button.Label>Danger</Button.Label>
+      </Button>
+      <Button variant="solid" color="warning" isDisabled>
+        <Button.Label>Warning</Button.Label>
+      </Button>
+      <Button variant="solid" color="success" isDisabled>
+        <Button.Label>Success</Button.Label>
+      </Button>
+      <Button variant="solid" color="info" isDisabled>
+        <Button.Label>Info</Button.Label>
+      </Button>
+    </Box>
+  );
+}
+```
+
+## Group
+
+```tsx
+import { Button, Box } from '@cdx-ui/components';
+
+export default function ButtonGroupDemo() {
+  return (
+    <Box className="gap-6">
+      <Button.Group>
+        <Button variant="outline">
+          <Button.Label>Left</Button.Label>
+        </Button>
+        <Button variant="outline">
+          <Button.Label>Center</Button.Label>
+        </Button>
+        <Button variant="outline">
+          <Button.Label>Right</Button.Label>
+        </Button>
+      </Button.Group>
+
+      <Button.Group isAttached>
+        <Button variant="outline">
+          <Button.Label>Left</Button.Label>
+        </Button>
+        <Button variant="outline">
+          <Button.Label>Center</Button.Label>
+        </Button>
+        <Button variant="outline">
+          <Button.Label>Right</Button.Label>
+        </Button>
+      </Button.Group>
+
+      <Button.Group isAttached flexDirection="column">
+        <Button variant="outline">
+          <Button.Label>Top</Button.Label>
+        </Button>
+        <Button variant="outline">
+          <Button.Label>Middle</Button.Label>
+        </Button>
+        <Button variant="outline">
+          <Button.Label>Bottom</Button.Label>
+        </Button>
+      </Button.Group>
+    </Box>
+  );
+}
+```
+
+## As link
+
+Use `Link` with `asChild` to merge navigation behavior onto the button.
+
+```tsx
+import { Button, Link } from '@cdx-ui/components';
+
+export default function ButtonAsLinkDemo() {
+  return (
+    <Link href="https://example.com" asChild webProps={{ target: '_blank', rel: 'noopener' }}>
+      <Button>
+        <Button.Label>Visit website</Button.Label>
+      </Button>
+    </Link>
+  );
+}
+```
+
+## API
+
+### Button
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the button's own styles. |
+| `children?` | `React.ReactNode` | — | Button content — typically `Button.Label`, `Button.Icon`, and/or `Button.Spinner`. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default `Pressable` host — merges Button's props onto the child instead of wrapping it (e.g. `<Button asChild><Link /></Button>`). |
+| `variant?` | `'solid' \| 'outline' \| 'ghost'` | `'solid'` | Visual style variant. |
+| `color?` | `'action' \| 'danger' \| 'warning' \| 'success' \| 'info'` | `'action'` | Color theme applied to the button surface and content. |
+| `size?` | `'default' \| 'small'` | `'default'` | Height and horizontal padding scale. |
+| `fullWidth?` | `boolean` | `false` | Stretch the button to fill the width of its container. |
+| `isDisabled?` | `boolean` | — | If true, the button will be disabled. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props) (including `onPress`).
+
+## Sub-components
+
+### Button.Label
+
+Text label inside the button. Inherits variant, color, and size from the parent Button context.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the label's own styles. |
+| `children?` | `React.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).
+
+### Button.Icon
+
+Renders a Forge icon. Inherits size, variant, and color from the parent Button context.
+
+| 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` | — | Forge icon component to render. Required unless `asChild` is set, in which case the consumer's substituted element is rendered instead. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default icon host. |
+| `position?` | `'leading' \| 'trailing'` | — | Position hint that emits `data-icon="inline-start"` or `data-icon="inline-end"`. CVA uses this attribute to apply leading/trailing padding logically (RTL-aware). Omit to apply the symmetric baseline gap. |
+
+Inherits all `ForgeIconProps` (react-native-svg `SvgProps` plus `filled` and `size`).
+
+### Button.Spinner
+
+Loading indicator displayed alongside the label.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes for the spinner container. |
+| `children?` | `React.ReactNode` | — | — |
+| `accessibilityLabel?` | `string` | `'Loading'` | Screen reader label for the spinner. |
+| `colorClassName?` | `string` | — | Uniwind `accent-*` color class override for the spinner. When omitted, the color is derived from the parent button's `variant` and `color`. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default `ActivityIndicator` host. |
+| `position?` | `'leading' \| 'trailing'` | — | Position hint that emits `data-icon="inline-start"` or `data-icon="inline-end"`. CVA uses this attribute to apply leading/trailing padding logically (RTL-aware). Omit to apply the symmetric baseline gap. |
+
+Inherits all [`ActivityIndicatorProps`](https://reactnative.dev/docs/activityindicator#props).
+
+### Button.Group
+
+Groups multiple buttons with consistent spacing and optional attached borders.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the group's own styles. |
+| `children` | `React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>[]` | — | The buttons to group together. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default `View` host. |
+| `flexDirection?` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | `'row'` | Layout direction of the grouped buttons. |
+| `isDisabled?` | `boolean` | — | Disable every button in the group. |
+| `isAttached?` | `boolean` | — | Remove the gap between buttons and merge their adjoining borders. |
+| `reversed?` | `boolean` | — | Reverse the visual order of the buttons. |
+| `isReversed?` | `boolean` | — | Alias of `reversed`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).

package/docs/components/button/design.md

@@ -0,0 +1,258 @@
+# Button — Design (https://design.candescent.com/docs/components/button)
+
+## Usage
+
+**Common alternative names**: Call to action, CTA
+
+---
+
+## Anatomy
+
+Buttons always have a label. They can also include an icon before or after the label.
+
+1. **Button**: The selectable area of the button.
+2. **Label**: Text that describes the button's action. Follow the label text guidelines below.
+3. **Leading Icon (optional)**: An icon can be included before the label to add additional affordance a button. Most buttons don't need an icon. Follow the icon guidelines.
+4. **Trailing Icon (optional)**: An icon can be included after the label to add additional affordance a button. Most buttons don't need an icon. Follow the icon guidelines.
+
+### Variant
+
+Buttons are available in 3 variants: **solid**, **outline**, and **ghost**.
+
+- **Solid**
+
+  High-emphasis buttons that should contain actions that are primary to your app.
+- **Outline**
+
+  Medium-emphasis buttons that should contain actions that are important but aren't the primary action in an app.
+- **Ghost**
+
+  Medium-emphasis buttons that should contain actions that are important but aren't the primary action in an app.
+
+### Color
+
+Buttons are versatile, and are available in a wide variety of colors. However, the most frequently used button colors should be: **Action,** and **Danger**.
+
+- **Action (Default)**
+
+  Utilizes the action color palette. Used for **most buttons** in designs.
+- **Danger**
+
+  Utilizes the danger color palette. Used for buttons with **destructive actions**.
+
+### Icon
+
+Icons may be added to buttons, either on the left or the right. For buttons with an icon but no label, use the Icon Button component instead.
+
+- **Show Leading Icon?: True**
+
+  Enables an icon that comes before the label (left side).
+- **Show End Icon?: True**
+
+  Enables an icon that comes after the label (right side).
+
+### Size
+
+Buttons are available in 2 sizes: **Default**, and **Small**. Size should be considered for visual balance and user focus; not to replace visual hierarchy.
+
+- **Size: Default**
+
+  Large buttons have a height of 44px. This matches the height of the Input Field component.
+- **Size: Small**
+
+  Small buttons have a height of 32px.
+
+---
+
+Usage
+
+### When to use
+
+> [!TIP]
+>
+> **For actions that users can take**
+>
+> - ex: Open a dialog
+> - ex: Submit a form
+
+> [!TIP]
+>
+> **When you need to provide a call-to-action for the user**
+>
+> - ex: _Add to cart_
+> - ex: _Sign up_
+> - ex: _Save_
+
+### When not to use
+
+> [!CAUTION]
+>
+> **As navigational elements**
+>
+> - ex: As links in navigation menus
+
+> [!CAUTION]
+>
+> **For simple, non-tabular information**
+>
+> - ex: Leading the user to a new website
+> - ex: Within blocks of running text
+
+### Hierarchy
+
+A button hierarchy emphasizes which button is most important in the context so the user can take action right away.
+
+Our buttons should use color and contrast to create three consistent levels of emphasis and hierarchy. The buttons with the strongest emphasis are **solid** buttons, followed by **outline**, then **ghost**.
+
+In general, your product work streams should follow these button guidelines for choosing the hierarchy of a button:
+
+| **Emphasis** | **Variant** | **Count** | **Use for**                                                                                              |
+| ------------ | ----------- | --------- | -------------------------------------------------------------------------------------------------------- |
+| High         | **solid**   | 1         | The **most important action**, to move forward in a flow, acknowledge & dismiss or finish a task.        |
+| Medium       | **outline** | Many      | Most actions, especially those inline with other content.                                                |
+| Low          | **ghost**   | A few     | **Dismissive actions** that give users a way out of something, letting them do nothing, dismiss or skip. |
+
+For detailed guidance on button placement, refer to the Button placement and hierarchy documentation.
+
+#### **Solid buttons**
+
+Solid buttons should be used for **high-emphasis actions**. Examples include moving forward in a flow, submitting a form, or highlighting the most common action a user would take on a page. Use them sparingly to avoid making the interface too busy.
+
+- **Do:** The single most important button should be solid. Other buttons should be lower emphasis.
+- **Do:** You can use multiple solid buttons if there is a clear separation between content.
+- **Don't:** Don’t use multiple solid buttons if there is no clear separation between content.
+
+When creating a Dialog, the single most important button (the affirmative action) should be a contained button. The dismissive action should be lower emphasis.
+
+- **Do:** Use solid buttons for affirmative actions, especially in a Dialog.
+- **Don't:** Don’t use solid buttons for dismissive actions, especially in a Dialog.
+
+#### Outline buttons
+
+Outline buttons should be used for **medium-emphasis actions** or actions that are supplementary to the main high-emphasis action. This variant will generally make up the majority of buttons on a page. They are also useful for when a page doesn’t have one true high-emphasis action.
+
+- **Do:** Use outline buttons inline with lists and other elements as needed. These medium-emphasis buttons are often most common.
+- **Caution:** Avoid using solid buttons in the middle of the page. Important actions should be placed at the top or bottom.
+
+#### Ghost buttons
+
+Ghost buttons are the least bold of the 3 variants, meaning that it is the least noticeable to users. Therefore, they should only be used for **low-emphasis actions**.
+
+The most common use for ghost buttons are **dismissive actions**: actions that give users a way out of a flow or allow them to ignore something. Some common examples include _Cancel_, _Close_, _Dismiss_, _Skip_, and _Ignore_.
+
+Always use ghost buttons when your users are aborting an action and thus navigating back to the previous state of the UI to create familiarity as they work through your product work streams.
+
+- **Do:** Use ghost buttons for dismissive actions. For example, a Cancel button could be used to back out of a process or action.
+- **Don't:** Don’t use outline buttons for buttons with dismissive behavior such as Cancel, Close, or Dismiss.
+
+#### Destructive buttons
+
+Destructive buttons should be used when the button’s action will cause permanent data loss. Any of the three button variants can be used as a destructive button by setting the property **color: danger**.
+
+_usage\_destructive\_01-ex_
+
+- **Do:** Use destructive buttons for actions that will delete data as soon as the button is pressed.
+- **Don't:** Don’t use destructive buttons for dismissive behaviors or other actions that don’t result in data loss.
+
+See the [destructive actions](https://design.candescent.com/docs/components/button/content.md) section below for more details about usage & behavior.
+
+### Layout and placement
+
+An **affirmative action** is something that takes the users further in their journey (for example, **Save**, **Review** or **Delete**), while a **dismissive action** takes a user back (for example, _Cancel_). Affirmative actions are the highest in the hierarchy.
+
+In most breakpoints, the visual hierarchy of buttons moves from right-to-left, starting with primary buttons on the right, followed by secondary buttons, and so on. So, an affirmative action should be the right-most button.
+
+In the Mobile breakpoint, where the buttons are full-width, the hierarchy moves from bottom-to-top, starting with primary buttons on the bottom.
+
+- **Mobile**
+
+  Hierarchy moves from bottom to top. Affirmative actions should always be the bottom-most button.
+- **Tablet and Above**
+
+  Hierarchy moves from right to left. Affirmative actions should always be the right-most button.
+
+### **Breakpoints**
+
+The width of buttons should change depending when they are viewed on a mobile device.
+
+- **Mobile**
+
+  Within the Mobile breakpoint (width \< 600px), most buttons should scale to 100% width of their container.
+- **Tablet and Above**
+
+  On all breakpoints larger than Mobile (width ≥ 600px), the width of buttons should hug their content.
+
+---
+
+## Behavior
+
+### Interaction states
+
+The default state of a button is clickable. The appearance of the button will respond as the user interacts with it.
+
+- **Resting (default)**
+
+  Default state. User is not interacting with the button.
+- **isHovered: True**
+
+  When the user’s cursor is hovering over the button.
+- **isFocused: True**
+
+  When a keyboard user is focused on the button using tab navigation controls.
+
+### Disabled
+
+Buttons can be disabled, which prevents the user from clicking on or interacting with the button.
+
+Using disabled buttons can cause accessibility issues so try and avoid them, as they often create more problems than they solve. Keep buttons active and use clear error messaging to guide users whenever possible. Use disabled buttons only in rare edge cases.
+
+- **isDisabled: true**
+
+  The user cannot interact with the button in this state.
+
+### Loading
+
+If a button’s action is not nearly-instant, it is recommended to give the user some visual feedback that the action is in progress. One way of accomplishing this is using a loading button.
+
+- **isLoading: true**
+
+  This state displays a loading spinner inside the button, and prevents the user from interacting with the button.
+
+### Destructive actions
+
+Destructive actions are **actions that cause permanent data loss**, such as discarding a draft email, deleting a user account, or closing a credit card. In most cases, these actions can’t be undone.
+
+In flows that contain destructive actions, **users should be prompted before the action is completed**, as it is possible they pressed the button by mistake. The first action that initiates the prompt should be a medium-emphasis or low-emphasis button, and the final action that triggers the destruction should be a high-emphasis button.
+
+- **Do:** Use destructive buttons for actions that will delete data as soon as the button is pressed.
+- **Don't:** Don’t use secondary style buttons for buttons with dismissive behavior such as “Cancel”, “Close”, or “Dismiss”.
+
+## Content
+
+## **Label text**
+
+Label text describes the action that will occur if a user taps a button. Since the width of the button 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.
+- Use verbs instead of adjectives whenever it makes sense to
+  - example: Use _Create account_ instead of _New account_
+
+* **Do:** Use short, direct labels that help the user understand the action the button represents.
+* **Don't:** Don’t wrap text within buttons. Find a way to write the label shorter if there isn’t enough room.
+* **Do:** Use a verb (“Create”) instead of an adjective (“New”) when it makes sense in context.
+* **Caution:** Adjectives can still be used in some cases. In this example, “Create transfer” would be misleading.
+* **Don't:** Don’t use a misleading verb. This example should instead say “Schedule transfer” or “New transfer”.
+
+## **Icons**
+
+Icons can be useful for reinforcing the button’s purpose, and can help the user scan the page more quickly. However, make sure that the icon has a clear **affordance** – the meaning of the symbol should be easily understood, and not conflict with the label’s text. When an action can be represented clearly by a symbol, we recommend using an [icon button](https://design.candescent.com/docs/components/icon-button/content.md).
+
+- **Do:** Use the icons most commonly associated with the action.
+- **Do:** Icons that are more specific (but still clear) can be used.
+- **Don't:** Don’t use icons that are not commonly associated with the action.
+- **Don't:** Don’t use icons that are commonly associated with other actions.
+- **Don't:** Don’t use two icons in a button. It may lead to confusion and/or clutter.
+- **Don't:** Don’t use a button with an icon and no label. Use an Icon Button instead.