@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/bottom-sheet/design.md

@@ -0,0 +1,249 @@
+# Bottom Sheet — Design (https://design.candescent.com/docs/components/bottom-sheet)
+
+## Usage
+
+**Common alternative names:** Sheet, Action sheet, Slide-up panel, Bottom drawer
+
+## Anatomy
+
+A bottom sheet is built from a **header** area (top of the sheet), a **body**, and a **footer**.
+
+**Anatomy\_avatar**
+
+1. **Sheet surface:** The panel anchored to the bottom of the screen; rounded top corners, square at the bottom edge.
+2. **Drag handle:** Horizontal bar at the top of the sheet that indicates the sheet can be dragged vertically.
+3. **Leading button** (optional)**:** Optional action in the leading corner (top-left), for example back or a contextual icon.
+4. **Title** (optional)**:** Optional label for the sheet task, shown when the sheet needs a clear name.
+5. **Close control** (optional)**:** Optional dismiss control in the trailing corner (top-right).
+6. **Slot:** Space for lists, forms, controls, or any other components used as the sheet content. Scrolls when the sheet uses the scroll view.
+7. **Footer:** Includes a primary button by default at the bottom of the sheet. Secondary actions can be added when needed.
+
+### Full bleed
+
+Full bleed controls how slot content is laid out horizontally within the bottom sheet, defining whether it stays within the standard gutters or can extend edge to edge within safe area boundaries.
+
+- **fullBleed: False (default)**
+
+  Slot uses horizontal inset; lists and fields do not touch the sheet side edges.
+- **fullBleed: True**
+
+  Slot content runs edge-to-edge within the sheet; use when full-width lists, imagery, or dividers should meet the sheet boundary.
+
+### Scroll view
+
+The scroll view defines how the bottom sheet handles content height and scrolling, determining whether it expands to full screen with internal scrolling or remains fixed at a shorter height.
+
+- **Use ScrollView?: True (default)**
+
+  Built-in scrolling in the slot; pairs with fixed height and long content.
+- **Use ScrollView?: False**
+
+  No component-level scroll wrapper; best when content is short, hugs content height is used, or the slot owns its own scroll behavior.
+
+### Footer
+
+- **Show Footer?: True (default)**
+
+  Footer strip visible; includes the default primary button and optional secondary actions per button hierarchy.
+- **Show Footer: False**
+
+  Footer hidden; use when the flow completes from slot selection alone or from header actions only (document when this is appropriate).
+
+---
+
+Usage
+
+### When to use
+
+> [!TIP]
+>
+> **For short tasks or choices tied to the current screen**
+>
+> - ex: Sort or filter a list
+> - ex: Share or export
+> - ex: Overflow (“More”) actions
+
+> [!TIP]
+>
+> **For extra detail or options without changing screens**
+>
+> - ex: Item details or metadata
+> - ex: Pickers and lightweight previews
+
+> [!TIP]
+>
+> **For a small amount of secondary input**
+>
+> - ex: Rename or add a label
+> - ex: A few fields that support the main task
+
+> [!TIP]
+>
+> **When people should stay oriented to what is underneath**
+>
+> - ex: A map or list still visible (dimmed) behind the sheet
+
+### When not to use
+
+> [!CAUTION]
+>
+> **For primary, multi-step flows**
+>
+> - ex: Full onboarding or checkout as a single sheet flow
+> - ex: Complex wizards that need a dedicated layout
+
+> [!CAUTION]
+>
+> **For critical system-level alerts**
+>
+> - ex: Errors or warnings that must interrupt everywhere—use a dialog or platform alert
+
+> [!CAUTION]
+>
+> **For deep hierarchical navigation**
+>
+> - ex: Many nested levels inside the sheet
+
+> [!CAUTION]
+>
+> **For side- or top-anchored panels on large layouts**
+>
+> - ex: A right-side detail rail or expanding left nav—use Drawer.
+
+### Placement
+
+Bottom sheets float above all content, separated by a translucent overlay that indicates a modal state. They are pinned to the bottom of the viewport, span the available width within safe areas, and expand upward with a rounded top edge.
+
+_usage\_placement\_mobile_
+
+### Bottom sheet vs Drawer
+
+Bottom sheet supports tasks at the bottom edge of the mobile viewport. Drawer supports panels from the left, right, or top. Keep usage consistent to maintain predictable behavior.
+
+- **Do:** Put sort, share, overflow, and short forms that rise from the bottom on Bottom sheet on mobile and narrow web.
+- **Don't:** Don't use a bottom sheet as a right-hand detail rail or left navigation surface on desktop—that belongs on Drawer.
+
+### Responsive behavior
+
+Responsive behavior defines how the bottom sheet adapts across screen sizes, ensuring the same task remains in a bottom‑anchored pattern without shifting to a different surface.
+
+- **Do:** Make scroll in the slot obvious when the sheet uses fixed height (fade, clipped row, or scroll bar).
+- **Don't:** Don’t use scrollable content without a clear affordance or place the primary action below the viewport.
+
+### Action hierarchy in the footer
+
+The footer ships with a **default action button** when shown. Secondary actions should follow Button hierarchy.
+
+- **Do:** Keep one clear primary in the footer for the sheet’s main outcome.
+- **Don't:** Don't show two competing primaries of the same weight.
+
+### Destructive actions
+
+Bottom sheet footers follow the same **order and placement** rules as other mobile action areas: on a stacked footer, put the **primary** (for example **Save changes**) **at the bottom** as the full-width control; place **secondary** and **destructive** actions **above** it or in a row above it, using **lower emphasis** (text or ghost/outlined)—never as a competing filled primary.
+
+- **Do:** Place destructive actions as a secondary pattern with clear labeling and confirmation when needed.
+- **Don't:** Don't use destructive fill as the default primary except on a dedicated destructive confirm sheet.
+
+### Breakpoints
+
+On wider viewports, bottom sheets follow defined patterns for max width, horizontal alignment, and overlay behavior. When behavior shifts at specific breakpoints, maintain a consistent pattern for how the component adapts.
+
+A common responsive pattern is to transition the bottom sheet into a drawer on larger viewports. This allows content to scale more naturally with available space while preserving a familiar interaction model across breakpoints.
+
+_usage\_breakpoints\_01-ex_
+
+---
+
+## Behavior
+
+### Opening and closing
+
+Bottom sheets open with a short upward motion and a overlay fade-in, and close with the reverse. Motion should follow established motion guidelines. For modal use, focus moves into the sheet on open and returns to the triggering control on close.
+
+_behavior\_opening\_closing\_01-ex_
+
+### Dismissal
+
+Bottom sheets support common dismissal patterns such as overlay tap (for modal use), a close control, swipe down when enabled, and platform back where applicable. Available dismissal methods remain consistent across supported platforms.
+
+_behavior\_dismissal\_01-ex_
+
+### Interaction states
+
+Footer actions follow standard button states, including hover on web. Content within the sheet, such as rows or options, follows established list or control patterns. Loading states appear within the content area and do not shift footer actions in a way that could cause mis-taps.
+
+_behavior\_keyboard\_and\_textinput\_01-ex_
+
+### Keyboard and text input
+
+When a bottom sheet includes form fields, the layout adjusts while the keyboard is open to keep the focused input and primary actions visible. The primary CTA remains pinned to the top of the keyboard so it is always accessible. Content within the sheet may scroll to maintain access to fields and actions on smaller viewports.
+
+Behavior remains consistent across breakpoints so the same task is supported in both bottom sheet and drawer patterns without shifting the interaction model.
+
+_behavior\_keyboard\_and\_textinput\_02-ex_
+
+### Keyboard and assistive technology
+
+For modal use, focus remains within the sheet until it is closed. On web, Escape closes the sheet when it does not conflict with nested interactions. The component uses an appropriate accessible role and is labeled from its visible title.
+
+_behavior\_keyboard\_unfocusing\_01-ex_
+
+### Stacking
+
+Bottom sheets do not stack. For multi-step flows, content updates within the same sheet or follows a clear back navigation pattern.
+
+## Content
+
+## Titles
+
+Titles should clearly describe the task or decision presented in the bottom sheet.
+
+Use these guidelines when writing titles:
+
+- Use short, task-based phrasing (aim for 1 to 3 words when possible)
+- Write in sentence case (aside from proper nouns)
+- Focus on the user action (for example, “Sort by,” “Share,” “Edit label”)
+
+* **Do:** Use clear, action-focused titles.
+* **Caution:** Avoid marketing or promotional language.
+* **Don't:** Don’t use vague or decorative language.
+
+## Primary action
+
+The primary action represents the main outcome of the bottom sheet.
+
+Use these guidelines when writing primary actions:
+
+- Use a clear verb + object structure (for example, “Save changes,” “Apply filters”)
+- Keep labels concise and specific to the outcome
+- Ensure the action reflects what happens next
+
+* **Do:** Make the outcome clear and actionable.
+* **Don't:** Don’t use generic labels like “Continue” when a more specific action is possible.
+
+## List and option labels
+
+Lists and options help users scan and select quickly within the bottom sheet.
+
+Use these guidelines when writing list content:
+
+- Use sentence case (aside from proper nouns)
+- Maintain parallel structure across options
+- Keep labels short and easy to scan
+- Aim for single-line items when possible
+
+* **Do:** Prioritize clarity and scannability.
+* **Don't:** Don’t use inconsistent phrasing or overly long labels.
+
+## Triggers
+
+Triggers are the controls that open the bottom sheet.
+
+Use these guidelines when labeling triggers:
+
+- Use clear, outcome-based labels (for example, “Sort,” “Filters,” “More”)
+- Ensure the trigger label aligns with the title shown in the sheet
+- Keep labels short and predictable
+
+* **Do:** Match the trigger to the task presented in the sheet.
+* **Don't:** Don’t create mismatches between the trigger and the sheet content.

package/docs/components/box/content.md

@@ -0,0 +1,141 @@
+# Box (https://design.candescent.com/docs/components/box)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-box--default)
+
+`Box` groups and lays out content on every platform. Use it wherever you would reach for a `View` or `div`.
+
+```tsx
+import { Box } from '@cdx-ui/components';
+```
+
+## Basic
+
+Use `Box` with layout classes, spacing-scale padding and a semantic surface background to build a section of a screen. For rows and columns with a token gap, use [`HStack` and `VStack`](https://design.candescent.com/docs/components/stack/content.md).
+
+```tsx
+import { Box, Heading, Text } from '@cdx-ui/components';
+
+export default function BoxBasicDemo() {
+  return (
+    <Box className="w-full max-w-sm gap-1 bg-surface-secondary p-4">
+      <Heading size="sm">Everyday Checking</Heading>
+      <Text color="secondary">Available balance $2,481.06</Text>
+    </Box>
+  );
+}
+```
+
+## Semantic elements
+
+Set `role` to render a semantic element on web. Native platforms expose the same role to assistive technology and render a view.
+
+```tsx
+import { Box, Link } from '@cdx-ui/components';
+
+const LINKS = [
+  { label: 'Accounts', href: 'https://example.com/accounts' },
+  { label: 'Transfers', href: 'https://example.com/transfers' },
+  { label: 'Statements', href: 'https://example.com/statements' },
+] as const;
+
+export default function BoxSemanticElementsDemo() {
+  return (
+    <Box role="navigation" aria-label="Banking">
+      <Box role="list" className="flex-row gap-6">
+        {LINKS.map((link) => (
+          <Box key={link.label} role="listitem">
+            <Link href={link.href}>
+              <Link.Label>{link.label}</Link.Label>
+            </Link>
+          </Box>
+        ))}
+      </Box>
+    </Box>
+  );
+}
+```
+
+| `role`          | Web element |
+| --------------- | ----------- |
+| `article`       | `<article>` |
+| `banner`        | `<header>`  |
+| `complementary` | `<aside>`   |
+| `contentinfo`   | `<footer>`  |
+| `figure`        | `<figure>`  |
+| `form`          | `<form>`    |
+| `list`          | `<ul>`      |
+| `listitem`      | `<li>`      |
+| `main`          | `<main>`    |
+| `navigation`    | `<nav>`     |
+| `region`        | `<section>` |
+
+Any other role, or no role, renders a `<div>`. For headings and text use [`Heading`](https://design.candescent.com/docs/components/heading/content.md) and [`Text`](https://design.candescent.com/docs/components/text/content.md), not a `Box` with a text role.
+
+## As child
+
+Set `asChild` to apply Box's props to its only child instead of rendering another view. Here a `ScrollView` takes the Box's role, label and layout classes.
+
+```tsx
+import { Box, HStack, ScrollView, Text } from '@cdx-ui/components';
+
+const TRANSACTIONS = [
+  { label: 'Springfield Electric', amount: '−$84.12' },
+  { label: 'Payroll deposit', amount: '+$2,150.00' },
+  { label: 'Corner Market', amount: '−$23.47' },
+  { label: 'Transfer to Savings', amount: '−$200.00' },
+  { label: 'City Water', amount: '−$41.90' },
+  { label: 'Coffee House', amount: '−$5.25' },
+] as const;
+
+export default function BoxAsChildDemo() {
+  return (
+    <Box
+      asChild
+      role="region"
+      aria-label="Recent transactions"
+      className="h-40 w-full max-w-sm bg-surface-secondary"
+    >
+      <ScrollView contentContainerClassName="gap-3 p-4">
+        {TRANSACTIONS.map((transaction) => (
+          <HStack key={transaction.label} className="justify-between">
+            <Text>{transaction.label}</Text>
+            <Text color="secondary">{transaction.amount}</Text>
+          </HStack>
+        ))}
+      </ScrollView>
+    </Box>
+  );
+}
+```
+
+## API
+
+### Box
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Renders the child element in place of the default `View`, merging Box's props onto it. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). Every `ViewProps` prop and the `ref` pass through to the rendered view unchanged. Type a ref with `BoxRef`:
+
+```tsx
+import { Box, type BoxRef } from '@cdx-ui/components';
+
+const ref = useRef<BoxRef>(null);
+
+<Box ref={ref} />;
+```
+
+## Anatomy
+
+| `data-slot` | Element |
+| ----------- | ------- |
+| `box`       | Root    |
+
+## Accessibility
+
+`Box` sets no role and adds no keyboard, focus or labeling behavior. Accessibility props such as `role`, `aria-label`, `accessibilityLabel` and `importantForAccessibility` pass through to the rendered view.
+
+Give a landmark role (`navigation`, `region`, `complementary`) an `aria-label` when the page has more than one landmark of that type, so screen-reader users can tell them apart.

package/docs/components/breadcrumbs/content.md

@@ -0,0 +1,169 @@
+# Breadcrumbs (https://design.candescent.com/docs/components/breadcrumbs)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/navigation-breadcrumbs--default)
+
+A compound component for hierarchical navigation. Compose each segment with `Breadcrumbs.Item`; the final item is always the current page and is not interactive.
+
+```tsx
+import { Breadcrumbs } from '@cdx-ui/components';
+```
+
+## Basic
+
+Add `href` to ancestor items so they can navigate. Wrap your app with `LinkProvider` to connect breadcrumb navigation to your router.
+
+```tsx
+import { Breadcrumbs } from '@cdx-ui/components';
+
+export default function BreadcrumbsBasicDemo() {
+  return (
+    <Breadcrumbs accessibilityLabel="Account navigation">
+      <Breadcrumbs.Item href="#home">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#accounts">Accounts</Breadcrumbs.Item>
+      <Breadcrumbs.Item>Checking account</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
+```
+
+## Underlined
+
+Set `isUnderlined` to underline interactive ancestor items.
+
+```tsx
+import { Breadcrumbs } from '@cdx-ui/components';
+
+export default function BreadcrumbsUnderlinedDemo() {
+  return (
+    <Breadcrumbs isUnderlined accessibilityLabel="Catalog navigation">
+      <Breadcrumbs.Item href="#home">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#catalog">Catalog</Breadcrumbs.Item>
+      <Breadcrumbs.Item>Product details</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
+```
+
+## Custom separator
+
+Pass text or any React element to `separator`.
+
+```tsx
+import { Breadcrumbs } from '@cdx-ui/components';
+
+export default function BreadcrumbsCustomSeparatorDemo() {
+  return (
+    <Breadcrumbs separator="›" accessibilityLabel="Settings navigation">
+      <Breadcrumbs.Item href="#home">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#settings">Settings</Breadcrumbs.Item>
+      <Breadcrumbs.Item>Security</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
+```
+
+## With icons
+
+Items accept custom content, including icons and text. A custom icon can also be used as the separator.
+An `Icon` or `Text` placed directly in an item follows the item's color in every state (ancestor, hover,
+current page, disabled), and one passed as `separator` follows the separator color, so neither needs color
+classes. Set `color` on it to override.
+
+```tsx
+import { Breadcrumbs, Icon, Text } from '@cdx-ui/components';
+import { ChevronRight, Home, Storefront } from '@cdx-ui/icons';
+
+export default function BreadcrumbsWithIconsDemo() {
+  return (
+    <Breadcrumbs
+      accessibilityLabel="Marketplace navigation"
+      separator={
+        <Icon
+          as={ChevronRight}
+          className="size-4"
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+        />
+      }
+    >
+      <Breadcrumbs.Item href="#home">
+        <Icon
+          as={Home}
+          className="size-4"
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+        />
+        <Text>Home</Text>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#marketplace">
+        <Icon
+          as={Storefront}
+          className="size-4"
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+        />
+        <Text>Marketplace</Text>
+      </Breadcrumbs.Item>
+      <Breadcrumbs.Item>Product details</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
+```
+
+## Disabled
+
+Set `isDisabled` to make every ancestor item non-interactive. The final item remains styled as the current page.
+
+```tsx
+import { Breadcrumbs } from '@cdx-ui/components';
+
+export default function BreadcrumbsDisabledDemo() {
+  return (
+    <Breadcrumbs isDisabled accessibilityLabel="Disabled account navigation">
+      <Breadcrumbs.Item href="#home">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#accounts">Accounts</Breadcrumbs.Item>
+      <Breadcrumbs.Item>Checking account</Breadcrumbs.Item>
+    </Breadcrumbs>
+  );
+}
+```
+
+## API
+
+### Breadcrumbs
+
+The navigation landmark and state provider for the breadcrumb trail.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `separator?` | `ReactNode` | ``/`` | Separator rendered between breadcrumb items. A direct `Icon` or `Text` child takes the separator color unless it sets `color`. |
+| `isDisabled?` | `boolean` | `false` | When `true`, ancestor items are not interactive and use muted text. The current page keeps its color. |
+| `isUnderlined?` | `boolean` | `false` | When `true`, interactive ancestor items are underlined. |
+| `color?` | `'neutral' \| 'action' \| 'danger' \| 'warning' \| 'success' \| 'info'` | `'neutral'` | Semantic color for ancestor items. `neutral` uses the standard text hierarchy. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Sub-components
+
+### Breadcrumbs.Item
+
+A segment in the trail. Ancestor items with an `href` are interactive. The final item is always rendered as the non-interactive current page, even when it receives an `href`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Item content. A direct `Icon` or `Text` child takes the item's state color unless it sets `color`. |
+| `href?` | `string` | — | URL or route path opened on press. Omit when the link only runs `onPress`. |
+| `action?` | `'navigate' \| 'push' \| 'replace'` | — | Navigation action forwarded to the `LinkProvider`. Defaults to `'navigate'`. |
+| `isVisited?` | `boolean` | — | If true, the link will render in its visited style (native). On web, visited styling is driven by the CSS `:visited` pseudo-class. |
+| `webProps?` | `React.AnchorHTMLAttributes<HTMLAnchorElement>` | — | HTML anchor attributes applied only on web. Ignored on native platforms. `target`, `rel`, and `download` are forwarded via react-native-web's `hrefAttrs`. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props) used by interactive ancestor items.
+
+## Accessibility
+
+On web, `Breadcrumbs` renders a named `navigation` landmark. Its `accessibilityLabel` defaults to "Breadcrumb".
+
+Separators are hidden from assistive technologies. The final item receives `aria-current="page"` on web and `accessibilityState.selected` on native platforms.