@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/divider/content.md

@@ -0,0 +1,112 @@
+# Divider (https://design.candescent.com/docs/components/divider)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=6771-8895), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-divider--default)
+
+`Divider` visually separates related groups of content.
+
+```tsx
+import { Divider } from '@cdx-ui/components';
+```
+
+## Basic
+
+Use a horizontal divider to separate stacked sections.
+
+```tsx
+import { Divider, VStack } from '@cdx-ui/components';
+
+export default function DividerBasicDemo() {
+  return (
+    <VStack space="xl" className="w-full">
+      <Divider />
+      <Divider />
+      <Divider />
+    </VStack>
+  );
+}
+```
+
+## With label
+
+Add `Divider.Label` to place text between two line segments. Labeled dividers must use this sub-component so the label receives the correct typography and accessibility treatment.
+
+```tsx
+import { Divider, VStack } from '@cdx-ui/components';
+
+export default function DividerWithLabelDemo() {
+  return (
+    <VStack space="xl" className="w-full">
+      <Divider>
+        <Divider.Label>or</Divider.Label>
+      </Divider>
+      <Divider>
+        <Divider.Label>More options</Divider.Label>
+      </Divider>
+    </VStack>
+  );
+}
+```
+
+## Vertical
+
+Set `vertical` to separate content arranged side by side. The parent must provide an explicit height so the divider can stretch.
+
+```tsx
+import { Box, Divider, HStack, Text } from '@cdx-ui/components';
+
+export default function DividerVerticalDemo() {
+  return (
+    <HStack className="h-40 w-full items-stretch">
+      <Box className="flex-1 items-center justify-center">
+        <Text>Checking</Text>
+      </Box>
+      <Divider vertical>
+        <Divider.Label>or</Divider.Label>
+      </Divider>
+      <Box className="flex-1 items-center justify-center">
+        <Text>Savings</Text>
+      </Box>
+    </HStack>
+  );
+}
+```
+
+## API
+
+### Divider
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | When present, splits the divider into line, content, line. Use `Divider.Label` so the label receives the correct typography and accessibility treatment. |
+| `vertical?` | `boolean` | — | Renders a vertical divider instead of the default horizontal orientation. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). The default orientation is horizontal.
+
+## Sub-components
+
+### Divider.Label
+
+Text displayed between the divider's two line segments.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the text's own styles. |
+| `children?` | `ReactNode` | — | Text content, which may include nested `Text` elements. |
+| `asChild?` | `boolean` | — | Renders the consumer's child element in place of the default `Text` host. |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+## Accessibility
+
+An unlabeled divider is decorative and hidden from the accessibility tree. For a labeled divider, the line segments are hidden while the label remains available to screen readers.
+
+`Divider` does not define a semantic section boundary. Use a heading or landmark role when content needs programmatic grouping.
+
+## When to use
+
+| Component                  | Use for                                                      |
+| -------------------------- | ------------------------------------------------------------ |
+| `Divider`                  | Section breaks, login "or" separators, toolbar groups        |
+| `ListItem` `showSeparator` | Bottom border between list rows                              |
+| `ListItem.SectionHeader`   | Dated or grouped list section headings with an accent border |

package/docs/components/drawer/content.md

@@ -0,0 +1,428 @@
+# Drawer (https://design.candescent.com/docs/components/drawer)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=9956-15204), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-drawer--default)
+
+A compound panel with permanent and modal presentations. Both share the same header, content, and
+footer anatomy. `variant` only changes how the panel appears on the page. Both variants attach to
+an edge through `placement` (`left`, `right`, `top`, `bottom`); the default is `right`.
+
+```tsx
+import { Drawer } from '@cdx-ui/components';
+```
+
+> [!NOTE]
+>
+> **Portal host**
+>
+> Modal drawers portal `Drawer.Header`, `Drawer.Content`, and `Drawer.Footer` automatically.
+> `ForgeDesignProvider` mounts the shared portal host; otherwise mount one `PortalHost` from
+> `@cdx-ui/primitives` near your app root.
+
+## Basic
+
+Modal drawers overlay the page from the chosen edge with a backdrop. Clicking the backdrop, the
+header close control, or pressing Escape closes the drawer. Open them with `isOpen` /
+`onOpenChange` — there is no trigger slot in Figma.
+
+```tsx
+import { useState } from 'react';
+import { Button, Drawer, Text } from '@cdx-ui/components';
+
+export default function DrawerBasicDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button onPress={() => setOpen(true)}>
+        <Button.Label>Open drawer</Button.Label>
+      </Button>
+      <Drawer variant="modal" isOpen={open} onOpenChange={setOpen}>
+        <Drawer.Header>
+          <Drawer.Title>Filter accounts</Drawer.Title>
+          <Drawer.Description>Choose which accounts appear in this view.</Drawer.Description>
+        </Drawer.Header>
+        <Drawer.Content>
+          <Text>Drawer body content stays scrollable when it exceeds the panel height.</Text>
+        </Drawer.Content>
+        <Drawer.Footer>
+          <Button variant="ghost" onPress={() => setOpen(false)}>
+            <Button.Label>Cancel</Button.Label>
+          </Button>
+          <Button onPress={() => setOpen(false)}>
+            <Button.Label>Apply</Button.Label>
+          </Button>
+        </Drawer.Footer>
+      </Drawer>
+    </>
+  );
+}
+```
+
+## Permanent rail
+
+Use `variant="permanent"` for an in-layout rail that pushes sibling content aside. Place a
+left or right drawer next to a `flex-1` main region in a horizontal row (drawer after the main
+region for `right`, before it for `left`). Place a top or bottom drawer in a vertical column.
+There is no overlay; the header close control still dismisses the rail.
+
+```tsx
+import { Box, Button, Drawer, Text } from '@cdx-ui/components';
+
+export default function DrawerPermanentDemo() {
+  return (
+    <Box className="h-90 flex-row border border-stroke-secondary">
+      <Box className="flex-1 items-center justify-center gap-4 p-4">
+        <Text>Main content area</Text>
+        <Button variant="outline">
+          <Button.Label>Primary action</Button.Label>
+        </Button>
+      </Box>
+      <Drawer variant="permanent" size="small">
+        <Drawer.Header showSeparator={false}>
+          <Drawer.Title>Accounts</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content>
+          <Text size="sm" color="secondary">
+            Checking
+          </Text>
+          <Text size="sm" color="secondary">
+            Savings
+          </Text>
+          <Text size="sm" color="secondary">
+            Credit card
+          </Text>
+        </Drawer.Content>
+      </Drawer>
+    </Box>
+  );
+}
+```
+
+## Sizes
+
+Panel width follows the `size` variant on left and right: `small` (240px), `default` (360px), and
+`large` (480px), capped at the viewport. On top and bottom the same tokens map to height.
+
+```tsx
+import { Box, Drawer, Text } from '@cdx-ui/components';
+
+const sizeLabels = {
+  small: '240px',
+  default: '360px',
+  large: '480px',
+} as const;
+
+export default function DrawerSizesDemo() {
+  return (
+    <Box className="gap-4">
+      {(Object.keys(sizeLabels) as (keyof typeof sizeLabels)[]).map((size) => (
+        <Drawer key={size} size={size} className="h-30">
+          <Drawer.Header showSeparator={false}>
+            <Drawer.Title>{size}</Drawer.Title>
+          </Drawer.Header>
+          <Drawer.Content>
+            <Text size="sm" color="secondary">
+              {sizeLabels[size]}
+            </Text>
+          </Drawer.Content>
+        </Drawer>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Placement
+
+Set `placement` to open the panel from `left`, `right`, `top`, or `bottom`. The most common case is
+`right`, which is the default.
+
+```tsx
+import { useState } from 'react';
+import { Box, Button, Drawer, Text, type DrawerPlacement } from '@cdx-ui/components';
+
+const placements: DrawerPlacement[] = ['left', 'right', 'top', 'bottom'];
+
+export default function DrawerSidesDemo() {
+  const [open, setOpen] = useState(false);
+  const [placement, setPlacement] = useState<DrawerPlacement>('right');
+
+  return (
+    <>
+      <Box className="flex-row flex-wrap gap-2">
+        {placements.map((value) => (
+          <Button
+            key={value}
+            variant="outline"
+            onPress={() => {
+              setPlacement(value);
+              setOpen(true);
+            }}
+          >
+            <Button.Label>{value}</Button.Label>
+          </Button>
+        ))}
+      </Box>
+      <Drawer variant="modal" isOpen={open} onOpenChange={setOpen} placement={placement}>
+        <Drawer.Header>
+          <Drawer.Title>{placement} drawer</Drawer.Title>
+          <Drawer.Description>The panel attaches to this edge of the viewport.</Drawer.Description>
+        </Drawer.Header>
+        <Drawer.Content>
+          <Text>Default is right. Size maps to width on left/right and height on top/bottom.</Text>
+        </Drawer.Content>
+        <Drawer.Footer>
+          <Button variant="ghost" onPress={() => setOpen(false)}>
+            <Button.Label>Close</Button.Label>
+          </Button>
+        </Drawer.Footer>
+      </Drawer>
+    </>
+  );
+}
+```
+
+## Full bleed content
+
+Set `fullBleed` on `Drawer.Content` to remove horizontal padding for edge-to-edge lists, dividers, or imagery.
+
+```tsx
+import { Box, Drawer, ListItem } from '@cdx-ui/components';
+
+export default function DrawerFullBleedDemo() {
+  return (
+    <Box className="h-70 flex-row border border-stroke-secondary">
+      <Drawer>
+        <Drawer.Header>
+          <Drawer.Title>Recent activity</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content fullBleed>
+          {['Coffee shop', 'Direct deposit', 'Transfer to savings'].map((label, index, labels) => (
+            <ListItem key={label} size="compact" showSeparator={index < labels.length - 1}>
+              <ListItem.Content>
+                <ListItem.Title>{label}</ListItem.Title>
+              </ListItem.Content>
+            </ListItem>
+          ))}
+        </Drawer.Content>
+      </Drawer>
+    </Box>
+  );
+}
+```
+
+## Header variants
+
+Compose `Drawer.LeadingSlot`, `Drawer.Title`, and `Drawer.Description` directly inside
+`Drawer.Header`. The header places the leading slot first, stacks the title and description, and
+adds a close control at the end. Set `close={null}` to remove it.
+
+```tsx
+import { FilterList } from '@cdx-ui/icons';
+import { Box, Drawer, Icon, Text } from '@cdx-ui/components';
+
+export default function DrawerHeaderVariantsDemo() {
+  return (
+    <Box className="gap-4">
+      <Drawer className="h-40">
+        <Drawer.Header>
+          <Drawer.LeadingSlot>
+            <Icon as={FilterList} className="size-6" />
+          </Drawer.LeadingSlot>
+          <Drawer.Title>Filter accounts</Drawer.Title>
+          <Drawer.Description>Choose which accounts appear in this view.</Drawer.Description>
+        </Drawer.Header>
+        <Drawer.Content>
+          <Text size="sm" color="secondary">
+            Leading slot, text column, and the default close control.
+          </Text>
+        </Drawer.Content>
+      </Drawer>
+      <Drawer className="h-30">
+        <Drawer.Header close={null}>
+          <Drawer.Title>Accounts</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content>
+          <Text size="sm" color="secondary">
+            No close control.
+          </Text>
+        </Drawer.Content>
+      </Drawer>
+    </Box>
+  );
+}
+```
+
+## API
+
+### Drawer
+
+Controls open state, dismissal behavior, size, and variant for the compound component.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children` | `ReactNode` | — | — |
+| `size?` | `'small' \| 'default' \| 'large' \| null` | — | — |
+| `variant?` | `'permanent' \| 'modal' \| null` | — | — |
+| `placement?` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'right'` | Edge the panel attaches to. Applies to both `modal` and `permanent`. |
+| `fullBleed?` | `boolean` | — | — |
+| `animation?` | `'disable-all'` | — | — |
+| `zIndex?` | `number` | — | Stacking order for the modal overlay layer (backdrop + panel). Defaults to {@link MODAL_OVERLAY_Z_INDEX} (10000). |
+| `isOpen?` | `boolean` | — | Controlled open state. Use `defaultOpen` for the uncontrolled variant. |
+| `onOpenChange?` | `((open: boolean) => void)` | — | — |
+| `defaultOpen?` | `boolean` | — | — |
+| `closeOnBackdropPress?` | `boolean` | — | — |
+| `closeOnEscKey?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props), except `children` and `role`.
+
+| Attribute   | Value    | Description  |
+| ----------- | -------- | ------------ |
+| `data-slot` | `drawer` | Root element |
+
+## Sub-components
+
+### Drawer.Header
+
+Fixed top region. Place `Drawer.LeadingSlot`, `Drawer.Title`, and `Drawer.Description` as direct
+children. Whatever the JSX order, the header renders the first leading slot, then a column holding
+every other child, then the close control. It renders a default `Drawer.Close` unless you compose
+one yourself. Pass a node to `close` to replace it, or `close={null}` to remove it. `asChild`
+renders the child unchanged, with no close control.
+
+`Drawer.LeadingSlot` and `Drawer.Close` are matched by component identity. Wrapping either in
+`memo()`, an HOC, or a custom component moves it into the text column. Extra leading slots or close
+controls are not rendered.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `showSeparator?` | `boolean \| null` | — | — |
+| `asChild?` | `boolean` | — | Substitute the header element with the single child. The child is rendered unchanged: no row partition and no close control are applied, and `close` is ignored. |
+| `close?` | `ReactNode` | — | Close control rendered at the end of the row. - omitted: renders a composed `Drawer.Close` child if present, otherwise a default `<Drawer.Close />` - `null`: renders no close control - a node: rendered in place of the default and any `Drawer.Close` child |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Drawer.LeadingSlot
+
+Optional leading region in the header (icon or custom content). Place it as a direct child of
+`Drawer.Header`. 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).
+
+### Drawer.Close
+
+Dismiss control. `Drawer.Header` renders one by default. Compose it yourself to change its props,
+such as a more specific `accessibilityLabel` (default `"Close"`) or custom children in place of the
+close icon. Closes modal and permanent drawers through `onOpenChange(false)`. Modal drawers also
+close when the backdrop is pressed (`closeOnBackdropPress`, default `true`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Replaces the default close glyph. |
+| `accessibilityLabel?` | `string` | — | Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+### Drawer.Title
+
+Heading announced when the modal drawer opens.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Drawer.Description
+
+Secondary text linked to the panel through `aria-describedby` on modal drawers.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Drawer.Content
+
+Scrollable content region between the header and footer. Matches the Figma `Drawer.Content` slot. Set `fullBleed` to remove horizontal padding.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `contentClassName?` | `string` | — | — |
+| `fullBleed?` | `boolean` | — | — |
+
+Inherits all [`ScrollViewProps`](https://reactnative.dev/docs/scrollview#props).
+
+### Drawer.Footer
+
+Action row below the content. Layout stacks vertically below 600px viewport width and aligns horizontally on wider viewports unless `layout` is set.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `showSeparator?` | `boolean \| null` | — | — |
+| `direction?` | `'row' \| 'column'` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Hook
+
+### useDrawer
+
+Returns the nearest modal drawer's state and dismissal configuration:
+
+```tsx
+const { open, onOpenChange } = useDrawer();
+```
+
+## Anatomy
+
+| `data-slot`          | Element                               |
+| -------------------- | ------------------------------------- |
+| `drawer`             | Root panel (permanent) or modal shell |
+| `drawer-overlay`     | Modal backdrop scrim                  |
+| `drawer-header`      | Header region                         |
+| `drawer-leading`     | Optional header leading slot          |
+| `drawer-title`       | Title text                            |
+| `drawer-description` | Description text                      |
+| `drawer-close`       | Header dismiss control                |
+| `drawer-content`     | Scrollable body region                |
+| `drawer-footer`      | Footer actions                        |
+
+## Accessibility
+
+- Modal drawers receive `aria-modal`, `aria-labelledby`, and `aria-describedby` relationships automatically.
+- Focus moves into the panel, remains trapped while open, and returns to the previously focused element after close.
+- Escape closes the modal drawer on web when `closeOnEscKey` is enabled.
+- Android's hardware back button closes the modal drawer.
+- Permanent drawers stay in layout, do not trap focus, and do not render an overlay.
+
+## Constraints
+
+- A shared `PortalHost` must be mounted once near the app root. `ForgeDesignProvider` includes one.
+- Modal drawers portal Figma slots automatically. Do not wrap them in `Dialog.Popup` or a custom portal.
+- Modal drawers slide in from `placement` using transform only.
+- Permanent left/right drawers sit in a horizontal flex row next to a `flex-1` sibling. Permanent
+  top/bottom drawers sit in a vertical flex column next to a `flex-1` sibling.
+- Permanent drawers are for wide layouts (desktop, tablet, landscape). On a phone they consume
+  most of the viewport (`small` is 240px). Use `variant="modal"` on small screens.