@cdx-ui/components 0.2.3 → 0.2.4

package/AGENTS.md

@@ -0,0 +1,24 @@
+# @cdx-ui/components — agent guide
+
+This package ships its own Forge UI documentation in `docs/`, generated from the docs site
+at the commit this version was released from. It matches the installed version exactly.
+
+## Use the bundled docs first
+
+- Prefer `docs/` over https://design.candescent.com. The live site tracks the latest
+  unreleased source, so its APIs and examples can be ahead of this install.
+- Start at `docs/llms.txt`: an index of every page, linking each to its local file.
+- For a page at site path `<path>` (for example `components/button` or
+  `getting-started/developers`):
+  - `docs/<path>/content.md` has the page prose, demo source and generated prop tables.
+  - `docs/<path>/design.md` has design guidance. Only some pages have one.
+- Search the folder directly (for example `grep -rl "BottomSheet" docs/`) instead of
+  fetching a concatenated file.
+
+## When sources disagree
+
+The installed type declarations in `lib/typescript/` are the final word on props and
+exports. If they disagree with `docs/`, trust the types.
+
+Links inside `content.md` and `design.md` use absolute site URLs, so they open the live
+site rather than this version. Prefer the local file for the same `<path>`.

package/README.md

@@ -46,6 +46,8 @@ export function Example() {
 
 The [component reference](https://design.candescent.com/docs/components) is the source of truth for the catalog — every component has a page there with live examples, props, and accessibility notes.
 
+The package also ships that reference as markdown in `docs/`, matched to the installed version; coding agents should start at `AGENTS.md` in the package root.
+
 > `Box` is exported but deprecated — use React Native's `View` directly.
 
 ### Providers

package/coverage.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="108" height="20" role="img" aria-label="coverage: 92.3%"><title>coverage: 92.3%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="108" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="47" height="20" fill="#4b0"/><rect width="108" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="835" y="150" fill-opacity=".8" filter="url(#blur)" textLength="370">92.3%</text><text x="835" y="150" fill-opacity=".3" textLength="370">92.3%</text></g><text x="835" y="140" textLength="370">92.3%</text></g></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="108" height="20" role="img" aria-label="coverage: 92.6%"><title>coverage: 92.6%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="108" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="47" height="20" fill="#4b0"/><rect width="108" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="835" y="150" fill-opacity=".8" filter="url(#blur)" textLength="370">92.6%</text><text x="835" y="150" fill-opacity=".3" textLength="370">92.6%</text></g><text x="835" y="140" textLength="370">92.6%</text></g></g></svg>

package/docs/components/accordion/content.md

@@ -0,0 +1,538 @@
+# Accordion (https://design.candescent.com/docs/components/accordion)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=11210-5320), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/surfaces-accordion--default)
+
+Use `Accordion` for FAQs, settings, and other sections where people reveal content as needed. Compose each item from a trigger and content region.
+
+```tsx
+import { Accordion } from '@cdx-ui/components';
+```
+
+## Basic
+
+Use `type="single"` when only one item should be open. Control the open item with `value` and `onValueChange`, or provide `defaultValue` for uncontrolled usage.
+
+```tsx
+import { useState } from 'react';
+import { Accordion, Text } from '@cdx-ui/components';
+
+export default function AccordionBasicDemo() {
+  const [value, setValue] = useState<string | undefined>('shipping');
+
+  return (
+    <Accordion
+      type="single"
+      value={value}
+      onValueChange={setValue}
+      aria-label="Store policies"
+      className="w-full max-w-md"
+    >
+      <Accordion.Item value="shipping">
+        <Accordion.Trigger>
+          <Accordion.Label>
+            <Accordion.Title>Shipping policy</Accordion.Title>
+          </Accordion.Label>
+        </Accordion.Trigger>
+        <Accordion.Content>
+          <Text size="sm" color="secondary">
+            Standard shipping is free on orders over $50.
+          </Text>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="returns" showSeparator={false}>
+        <Accordion.Trigger>
+          <Accordion.Label>
+            <Accordion.Title>Returns</Accordion.Title>
+          </Accordion.Label>
+        </Accordion.Trigger>
+        <Accordion.Content>
+          <Text size="sm" color="secondary">
+            Return unused items within 30 days for a full refund.
+          </Text>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+## Multiple
+
+Use `type="multiple"` to let people open and close items independently.
+
+```tsx
+import { Accordion, Text } from '@cdx-ui/components';
+
+export default function AccordionMultipleDemo() {
+  return (
+    <Accordion
+      type="multiple"
+      defaultValue={['alerts', 'security']}
+      aria-label="Account settings"
+      className="w-full max-w-md"
+    >
+      <Accordion.Item value="alerts">
+        <Accordion.Trigger>
+          <Accordion.Label>
+            <Accordion.Title>Alerts</Accordion.Title>
+          </Accordion.Label>
+        </Accordion.Trigger>
+        <Accordion.Content>
+          <Text size="sm" color="secondary">
+            Receive balance, deposit, and payment notifications.
+          </Text>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="security" showSeparator={false}>
+        <Accordion.Trigger>
+          <Accordion.Label>
+            <Accordion.Title>Security</Accordion.Title>
+          </Accordion.Label>
+        </Accordion.Trigger>
+        <Accordion.Content>
+          <Text size="sm" color="secondary">
+            Review sign-in and device security preferences.
+          </Text>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+## Rich labels
+
+Compose `Accordion.LeadingSlot`, `Accordion.Description`, and `Accordion.Meta` when a trigger needs more context than a title alone.
+
+```tsx
+import { Accordion, Icon, Text } from '@cdx-ui/components';
+import { Notifications } from '@cdx-ui/icons';
+
+export default function AccordionRichLabelDemo() {
+  return (
+    <Accordion
+      type="single"
+      defaultValue="notifications"
+      aria-label="Notification preferences"
+      className="w-full max-w-md"
+    >
+      <Accordion.Item value="notifications" showSeparator={false}>
+        <Accordion.Trigger>
+          <Accordion.LeadingSlot>
+            <Icon as={Notifications} />
+          </Accordion.LeadingSlot>
+          <Accordion.Label>
+            <Accordion.Title>Notifications</Accordion.Title>
+            <Accordion.Description>Manage account alerts</Accordion.Description>
+            <Accordion.Meta>3 channels enabled</Accordion.Meta>
+          </Accordion.Label>
+        </Accordion.Trigger>
+        <Accordion.Content>
+          <Text size="sm" color="secondary">
+            Choose when Forge sends push, email, and SMS notifications.
+          </Text>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+## Full bleed
+
+Set `fullBleed` on items nested in an already-padded surface to avoid a second horizontal inset. Here the payment summary, Accordion details, and card action all align to the Card's shared gutter.
+
+```tsx
+import {
+  Accordion,
+  Button,
+  Card,
+  Chip,
+  Divider,
+  Heading,
+  HStack,
+  Icon,
+  Text,
+  VStack,
+} from '@cdx-ui/components';
+import { AccountBalance, ReceiptLong } from '@cdx-ui/icons';
+
+export default function AccordionFullBleedDemo() {
+  return (
+    <Card className="w-full max-w-md">
+      <Card.Header>
+        <VStack className="gap-0.5">
+          <Text size="sm" color="secondary">
+            Upcoming payment
+          </Text>
+          <Heading size="sm">Visa Platinum · 0275</Heading>
+        </VStack>
+        <Chip color="success" size="small">
+          <Chip.Label>AutoPay on</Chip.Label>
+        </Chip>
+      </Card.Header>
+      <Card.Content>
+        <VStack space="lg">
+          <VStack space="xs">
+            <Text size="sm" color="secondary">
+              Statement balance
+            </Text>
+            <Text size="xl" weight="semibold">
+              $842.17
+            </Text>
+            <Text size="sm" color="secondary">
+              Due September 18
+            </Text>
+          </VStack>
+          <Divider />
+          <Accordion type="single" defaultValue="breakdown" aria-label="Payment details">
+            <Accordion.Item value="breakdown" fullBleed>
+              <Accordion.Trigger>
+                <Accordion.LeadingSlot>
+                  <Icon as={ReceiptLong} />
+                </Accordion.LeadingSlot>
+                <Accordion.Label>
+                  <Accordion.Title>Payment breakdown</Accordion.Title>
+                  <Accordion.Description>How the amount was calculated</Accordion.Description>
+                </Accordion.Label>
+              </Accordion.Trigger>
+              <Accordion.Content>
+                <VStack space="sm">
+                  <HStack space="lg" className="justify-between">
+                    <Text size="sm" color="secondary">
+                      Purchases
+                    </Text>
+                    <Text size="sm">$796.42</Text>
+                  </HStack>
+                  <HStack space="lg" className="justify-between">
+                    <Text size="sm" color="secondary">
+                      Interest
+                    </Text>
+                    <Text size="sm">$34.75</Text>
+                  </HStack>
+                  <HStack space="lg" className="justify-between">
+                    <Text size="sm" color="secondary">
+                      Fees
+                    </Text>
+                    <Text size="sm">$11.00</Text>
+                  </HStack>
+                </VStack>
+              </Accordion.Content>
+            </Accordion.Item>
+            <Accordion.Item value="account" fullBleed showSeparator={false}>
+              <Accordion.Trigger>
+                <Accordion.LeadingSlot>
+                  <Icon as={AccountBalance} />
+                </Accordion.LeadingSlot>
+                <Accordion.Label>
+                  <Accordion.Title>Payment account</Accordion.Title>
+                  <Accordion.Description>Joint Checking · 4821</Accordion.Description>
+                </Accordion.Label>
+              </Accordion.Trigger>
+              <Accordion.Content>
+                <HStack space="lg" className="justify-between">
+                  <Text size="sm" color="secondary">
+                    Available balance
+                  </Text>
+                  <Text size="sm">$4,250.18</Text>
+                </HStack>
+              </Accordion.Content>
+            </Accordion.Item>
+          </Accordion>
+        </VStack>
+      </Card.Content>
+      <Card.Footer>
+        <Button color="action" fullWidth>
+          <Button.Label>Review payment</Button.Label>
+        </Button>
+      </Card.Footer>
+    </Card>
+  );
+}
+```
+
+## Indicator overrides
+
+Pass an `indicator` to `Accordion.Trigger` to replace the default chevron, or pass `null` to suppress it.
+
+```tsx
+import { Accordion, Icon, Text } from '@cdx-ui/components';
+import { Hexagon } from '@cdx-ui/icons';
+
+export default function AccordionIndicatorOverridesDemo() {
+  return (
+    <Accordion
+      type="multiple"
+      defaultValue={['custom', 'hidden']}
+      aria-label="Indicator options"
+      className="w-full max-w-md"
+    >
+      <Accordion.Item value="custom">
+        <Accordion.Trigger
+          indicator={
+            <Accordion.Indicator>
+              <Icon as={Hexagon} />
+            </Accordion.Indicator>
+          }
+        >
+          <Accordion.Label>
+            <Accordion.Title>Custom indicator</Accordion.Title>
+          </Accordion.Label>
+        </Accordion.Trigger>
+        <Accordion.Content>
+          <Text size="sm" color="secondary">
+            Replace the default chevron with another visual.
+          </Text>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="hidden" showSeparator={false}>
+        <Accordion.Trigger indicator={null}>
+          <Accordion.Label>
+            <Accordion.Title>No indicator</Accordion.Title>
+          </Accordion.Label>
+        </Accordion.Trigger>
+        <Accordion.Content>
+          <Text size="sm" color="secondary">
+            Pass null when the surrounding design provides the open-state affordance.
+          </Text>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+## Disabled
+
+Set `disabled` on an item, or `isDisabled` on `Accordion` to disable the entire group.
+
+```tsx
+import { Accordion, Text } from '@cdx-ui/components';
+
+export default function AccordionDisabledDemo() {
+  return (
+    <Accordion
+      type="single"
+      defaultValue="enabled"
+      aria-label="Account options"
+      className="w-full max-w-md"
+    >
+      <Accordion.Item value="enabled">
+        <Accordion.Trigger>
+          <Accordion.Label>
+            <Accordion.Title>Enabled option</Accordion.Title>
+          </Accordion.Label>
+        </Accordion.Trigger>
+        <Accordion.Content>
+          <Text size="sm" color="secondary">
+            This item can be opened and closed.
+          </Text>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="disabled" disabled showSeparator={false}>
+        <Accordion.Trigger>
+          <Accordion.Label>
+            <Accordion.Title>Unavailable option</Accordion.Title>
+          </Accordion.Label>
+        </Accordion.Trigger>
+        <Accordion.Content>
+          <Text size="sm" color="secondary">
+            Disabled content cannot be opened.
+          </Text>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+## API
+
+### Accordion
+
+Root container that manages the open item value or values. The `type` discriminant determines the controlled and uncontrolled value shape.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `type?` | `'single' \| 'multiple'` | — | — |
+| `value?` | `string \| string[]` | — | — |
+| `defaultValue?` | `string \| string[]` | — | — |
+| `onValueChange?` | `((value: string) => void) \| ((value: string[]) => void)` | — | — |
+| `collapsible?` | `boolean` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). Single mode uses `string | undefined`; multiple mode uses `string[]`. `collapsible` applies only to single mode.
+
+| Attribute   | Values      | Description    |
+| ----------- | ----------- | -------------- |
+| `data-slot` | `accordion` | Root container |
+
+## Sub-components
+
+### Accordion.Item
+
+One disclosure item. Requires a unique `value`; `fullBleed` and `showSeparator` control its layout.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `fullBleed?` | `boolean` | `false` | Removes horizontal padding so trigger and content can render edge to edge. |
+| `showSeparator?` | `boolean` | `true` | Renders a separator below the item when true. |
+| `value` | `string` | — | Required stable id within the Accordion. |
+| `disabled?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute       | Values             | Description                            |
+| --------------- | ------------------ | -------------------------------------- |
+| `data-slot`     | `accordion-item`   | Item container                         |
+| `data-state`    | `open` \| `closed` | Disclosure state                       |
+| `data-disabled` | `true` \| `false`  | Effective item or group disabled state |
+
+### Accordion.Trigger
+
+Pressable header control that toggles its item. It renders the default chevron unless `indicator` replaces or suppresses it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Either children or a render prop that receives a boolean reflecting whether the component is currently pressed. |
+| `asChild?` | `boolean` | — | Substitute the rendered trigger element with the single child. The child must be another Forge primitive (IconButton, Chip, Button) — anything whose underlying Pressable accepts Pressable-shaped handlers. When set, the auto-injected expand indicator is skipped and `accordionTriggerVariants` is not applied so the substituted component's own appearance wins. |
+| `indicator?` | `ReactNode` | — | Replaces the default open/closed chevron. Pass `null` to suppress the indicator. When `asChild` is set, only an explicitly provided indicator is appended to the substituted child. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props) (including `onPress`).
+
+| Attribute            | Values              | Description               |
+| -------------------- | ------------------- | ------------------------- |
+| `data-slot`          | `accordion-trigger` | Trigger pressable         |
+| `data-state`         | `open` \| `closed`  | Disclosure state          |
+| `data-disabled`      | `true` \| `false`   | Effective disabled state  |
+| `data-hover`         | `true` \| `false`   | Pointer hover state       |
+| `data-active`        | `true` \| `false`   | Pressed state             |
+| `data-focus-visible` | `true` \| `false`   | Keyboard focus-ring state |
+
+### Accordion.LeadingSlot
+
+Optional leading adornment such as an icon, avatar, or badge. Decorative content is hidden from the accessibility tree by default.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Accordion.Label
+
+Flexible column for `Accordion.Title`, `Accordion.Description`, and `Accordion.Meta`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Accordion.Title
+
+Primary trigger label.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Accordion.Description
+
+Supporting text displayed below the title.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Accordion.Meta
+
+Tertiary trigger metadata displayed below the description.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Accordion.Indicator
+
+Visual open-state affordance. It renders `KeyboardArrowDown` by default and rotates while open; compose custom children to replace the glyph.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute    | Values                | Description         |
+| ------------ | --------------------- | ------------------- |
+| `data-slot`  | `accordion-indicator` | Indicator container |
+| `data-state` | `open` \| `closed`    | Disclosure state    |
+
+### Accordion.Content
+
+Revealed content associated with its trigger. It is not mounted while the item is closed.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute    | Values              | Description             |
+| ------------ | ------------------- | ----------------------- |
+| `data-slot`  | `accordion-content` | Revealed content region |
+| `data-state` | `open`              | Present while mounted   |
+
+## Anatomy
+
+| `data-slot`             | Element                 |
+| ----------------------- | ----------------------- |
+| `accordion`             | Root container          |
+| `accordion-item`        | Disclosure item         |
+| `accordion-trigger`     | Trigger pressable       |
+| `accordion-leading`     | Leading adornment       |
+| `accordion-label`       | Trigger text stack      |
+| `accordion-title`       | Primary label           |
+| `accordion-description` | Supporting label        |
+| `accordion-meta`        | Tertiary metadata       |
+| `accordion-indicator`   | Open-state affordance   |
+| `accordion-content`     | Revealed content region |
+
+## Accessibility
+
+| Attribute             | Behavior                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| **Role**              | Each `Accordion.Trigger` is a button. Open content is exposed as a region on web.  |
+| **Expanded state**    | `aria-expanded` / `accessibilityState.expanded` reflects whether the item is open. |
+| **Relationship**      | `aria-controls` links the trigger to Content; Content is labelled by its trigger.  |
+| **Keyboard**          | Focus triggers with Tab and toggle them with Enter or Space.                       |
+| **Disabled**          | `disabled` prevents one item from toggling; root `isDisabled` disables every item. |
+| **Leading content**   | `Accordion.LeadingSlot` is hidden from the accessibility tree by default.          |
+| **Content lifecycle** | Closed content is unmounted and therefore absent from the accessibility tree.      |