@cdx-ui/components 0.2.2 → 0.2.4

package/docs/components/badge/content.md

@@ -0,0 +1,235 @@
+# Badge (https://design.candescent.com/docs/components/badge)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=6894-409), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-badge--default)
+
+Wraps a host element (Avatar, Button, IconButton, etc.) and overlays a corner indicator for counts, status dots, or icons.
+
+```tsx
+import { Badge } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { Avatar, Badge, Box, Button } from '@cdx-ui/components';
+
+export default function BadgeBasicDemo() {
+  return (
+    <Box className="flex-row flex-wrap items-center gap-6">
+      <Badge
+        label={5}
+        color="danger"
+        overlap="circular"
+        accessibilityLabel="5 unread notifications"
+      >
+        <Avatar size="xl" accessibilityLabel="Sofia Rivera">
+          <Avatar.Image src="https://www.loremfaces.net/128/id/4.jpg" />
+          <Avatar.Text>Sofia Rivera</Avatar.Text>
+        </Avatar>
+      </Badge>
+      <Badge label="New" color="info" overlap="rectangular">
+        <Button variant="outline" color="action">
+          <Button.Label>Inbox</Button.Label>
+        </Button>
+      </Badge>
+    </Box>
+  );
+}
+```
+
+## Colors
+
+```tsx
+import { Avatar, Badge, Box } from '@cdx-ui/components';
+
+const COLORS = ['action', 'danger', 'warning', 'success', 'info'] as const;
+
+export default function BadgeColorsDemo() {
+  return (
+    <Box className="flex-row flex-wrap items-center gap-6">
+      {COLORS.map((color) => (
+        <Badge
+          key={color}
+          label={3}
+          color={color}
+          overlap="circular"
+          accessibilityLabel="3 notifications"
+        >
+          <Avatar size="lg" accessibilityLabel="User">
+            <Avatar.Text>User</Avatar.Text>
+          </Avatar>
+        </Badge>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Dot
+
+Use `variant="dot"` for a contentless status indicator.
+
+```tsx
+import { Avatar, Badge, Box } from '@cdx-ui/components';
+
+const COLORS = ['action', 'danger', 'warning', 'success', 'info'] as const;
+
+export default function BadgeDotDemo() {
+  return (
+    <Box className="flex-row flex-wrap items-center gap-6">
+      {COLORS.map((color) => (
+        <Badge key={color} variant="dot" color={color} overlap="circular">
+          <Avatar size="lg" accessibilityLabel="User">
+            <Avatar.Text>User</Avatar.Text>
+          </Avatar>
+        </Badge>
+      ))}
+    </Box>
+  );
+}
+```
+
+## With icon
+
+Pass a Forge icon via `icon`. When both `icon` and `label` are set, `icon` wins.
+
+```tsx
+import { Avatar, Badge, Box, IconButton } from '@cdx-ui/components';
+import { Check, Error, Notifications } from '@cdx-ui/icons';
+
+export default function BadgeWithIconDemo() {
+  return (
+    <Box className="flex-row flex-wrap items-center gap-6">
+      <Badge icon={Check} color="success" overlap="circular">
+        <Avatar size="lg" accessibilityLabel="Verified user">
+          <Avatar.Image src="https://www.loremfaces.net/128/id/1.jpg" />
+          <Avatar.Text>Verified</Avatar.Text>
+        </Avatar>
+      </Badge>
+      <Badge icon={Error} color="danger" overlap="circular">
+        <Avatar size="lg" accessibilityLabel="Error status">
+          <Avatar.Image src="https://www.loremfaces.net/128/id/2.jpg" />
+          <Avatar.Text>Error</Avatar.Text>
+        </Avatar>
+      </Badge>
+      <Badge icon={Check} color="action" overlap="circular">
+        <IconButton
+          as={Notifications}
+          variant="subtle"
+          color="neutral"
+          accessibilityLabel="Notifications"
+        />
+      </Badge>
+    </Box>
+  );
+}
+```
+
+## Placements
+
+Placement values are logical and RTL-aware (`end` is right in LTR).
+
+```tsx
+import { Avatar, Badge, Box } from '@cdx-ui/components';
+
+const PLACEMENTS = ['top-start', 'top-end', 'bottom-start', 'bottom-end'] as const;
+
+export default function BadgePlacementsDemo() {
+  return (
+    <Box className="flex-row flex-wrap items-center gap-6">
+      {PLACEMENTS.map((placement) => (
+        <Badge
+          key={placement}
+          label={1}
+          color="danger"
+          placement={placement}
+          overlap="circular"
+          accessibilityLabel="1 notification"
+        >
+          <Avatar size="lg" accessibilityLabel="User">
+            <Avatar.Image src="https://www.loremfaces.net/128/id/5.jpg" />
+            <Avatar.Text>User</Avatar.Text>
+          </Avatar>
+        </Badge>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Overlap
+
+Use `overlap="circular"` for round hosts (Avatar, IconButton) and `overlap="rectangular"` for box hosts (Button).
+
+```tsx
+import { Avatar, Badge, Box, Button, IconButton } from '@cdx-ui/components';
+import { Notifications } from '@cdx-ui/icons';
+
+export default function BadgeOverlapDemo() {
+  return (
+    <Box className="gap-6">
+      <Box className="flex-row flex-wrap items-center gap-6">
+        <Badge label={5} color="danger" overlap="circular" accessibilityLabel="5 notifications">
+          <Avatar size="lg" accessibilityLabel="User">
+            <Avatar.Image src="https://www.loremfaces.net/128/id/1.jpg" />
+            <Avatar.Text>User</Avatar.Text>
+          </Avatar>
+        </Badge>
+        <Badge label={5} color="danger" overlap="circular" accessibilityLabel="5 notifications">
+          <IconButton
+            as={Notifications}
+            variant="subtle"
+            color="neutral"
+            accessibilityLabel="Notifications"
+          />
+        </Badge>
+      </Box>
+      <Box className="flex-row flex-wrap items-center gap-6">
+        <Badge label={5} color="danger" overlap="rectangular" accessibilityLabel="5 notifications">
+          <Button variant="outline" color="action">
+            <Button.Label>Inbox</Button.Label>
+          </Button>
+        </Badge>
+        <Badge label="New" color="info" overlap="rectangular">
+          <Button variant="solid" color="action">
+            <Button.Label>Updates</Button.Label>
+          </Button>
+        </Badge>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## API
+
+### Badge
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `variant?` | `'default' \| 'dot'` | `'default'` | `default` shows icon or label content. `dot` is a contentless circle and ignores `icon` and `label`. |
+| `color?` | `'action' \| 'danger' \| 'warning' \| 'success' \| 'info'` | `'action'` | Semantic color of the indicator background and its content. |
+| `placement?` | `'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'` | `'top-end'` | Corner of the host. Logical and RTL-aware: `end` is the right edge in LTR. |
+| `overlap?` | `'circular' \| 'rectangular'` | `'rectangular'` | `circular` sits the indicator on a round host (Avatar, IconButton). `rectangular` centers it on a box corner (Button). |
+| `label?` | `ReactNode` | — | Indicator content for `variant="default"`. A string or number is styled as text; any other node renders as-is. Ignored when `variant` is `dot` or when `icon` is set. |
+| `icon?` | `ForgeIcon` | — | Forge icon for `variant="default"`. Takes precedence over `label`. Ignored when `variant` is `dot`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Anatomy
+
+| `data-slot`       | Element                                        |
+| ----------------- | ---------------------------------------------- |
+| `badge`           | Root wrapper                                   |
+| `badge-indicator` | Corner indicator                               |
+| `badge-label`     | Text label, when `label` is a string or number |
+
+## Accessibility
+
+`Badge` is non-interactive and has no implicit role. The indicator sets `pointerEvents` to `none`, so it does not intercept presses meant for the host.
+
+Set `accessibilityLabel` for a meaningful announcement (for example, `"5 unread notifications"`). The label is placed on the indicator, so it does not replace the host's accessible name. A `dot`, and any indicator without `accessibilityLabel`, is hidden from assistive technology — a string or number `label` is not announced on its own.
+
+`Badge` is not a live region. A count that changes is not announced automatically. Put the meaning on the host's `accessibilityLabel`, or announce the change elsewhere, when the update needs to be heard.

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

@@ -0,0 +1,351 @@
+# Bottom Sheet (https://design.candescent.com/docs/components/bottom-sheet)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=3187-706), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-bottomsheet--default)
+
+A compound component controlled imperatively via `useBottomSheet()`.
+
+```tsx
+import { BottomSheet, useBottomSheet } from '@cdx-ui/components';
+```
+
+> [!WARNING]
+>
+> **Provider required**
+>
+> Wrap your app root with `BottomSheet.Provider` to enable modal presentation.
+
+## Basic
+
+```tsx
+import { BottomSheet, useBottomSheet, Button, Text } from '@cdx-ui/components';
+import { BottomSheetDemoFrame } from './_frame';
+
+export default function BottomSheetBasicDemo() {
+  const { ref, present, dismiss } = useBottomSheet();
+
+  return (
+    <BottomSheetDemoFrame>
+      <Button variant="solid" color="action" onPress={present}>
+        <Button.Label>Open sheet</Button.Label>
+      </Button>
+      <BottomSheet.Modal ref={ref}>
+        <BottomSheet.View>
+          <BottomSheet.Header title="Sheet Title" onClose={dismiss} />
+          <BottomSheet.Content>
+            <Text>
+              A bottom sheet presents focused content without leaving the current context.
+            </Text>
+          </BottomSheet.Content>
+        </BottomSheet.View>
+      </BottomSheet.Modal>
+    </BottomSheetDemoFrame>
+  );
+}
+```
+
+## With footer
+
+Pass `BottomSheet.Footer` through the `footer` prop on `BottomSheet.Modal` so it stays pinned and animates with the sheet.
+
+```tsx
+import { BottomSheet, useBottomSheet, Button, Text } from '@cdx-ui/components';
+import { BottomSheetDemoFrame } from './_frame';
+
+export default function BottomSheetWithFooterDemo() {
+  const { ref, present, dismiss } = useBottomSheet();
+
+  return (
+    <BottomSheetDemoFrame>
+      <Button variant="solid" color="action" onPress={present}>
+        <Button.Label>Open sheet</Button.Label>
+      </Button>
+      <BottomSheet.Modal
+        ref={ref}
+        footer={
+          <BottomSheet.Footer>
+            <Button variant="solid" color="action" onPress={dismiss}>
+              <Button.Label>Confirm</Button.Label>
+            </Button>
+          </BottomSheet.Footer>
+        }
+      >
+        <BottomSheet.View>
+          <BottomSheet.Header title="Confirm Action" onClose={dismiss} />
+          <BottomSheet.Content>
+            <Text>
+              The footer stays pinned at the bottom and handles safe-area insets automatically.
+            </Text>
+          </BottomSheet.Content>
+        </BottomSheet.View>
+      </BottomSheet.Modal>
+    </BottomSheetDemoFrame>
+  );
+}
+```
+
+## Header variants
+
+```tsx
+import { BottomSheet, useBottomSheet, Box, Button, Text } from '@cdx-ui/components';
+import { BottomSheetDemoFrame } from './_frame';
+
+export default function BottomSheetHeaderVariantsDemo() {
+  const { ref: refBasic, present: presentBasic, dismiss: dismissBasic } = useBottomSheet();
+  const { ref: refFull, present: presentFull, dismiss: dismissFull } = useBottomSheet();
+
+  return (
+    <BottomSheetDemoFrame>
+      <Box className="flex-row gap-3">
+        <Button variant="outline" color="action" onPress={presentBasic}>
+          <Button.Label>Title + close</Button.Label>
+        </Button>
+        <Button variant="outline" color="action" onPress={presentFull}>
+          <Button.Label>Back + subtitle</Button.Label>
+        </Button>
+      </Box>
+
+      <BottomSheet.Modal ref={refBasic}>
+        <BottomSheet.View>
+          <BottomSheet.Header title="Account Options" onClose={dismissBasic} />
+          <BottomSheet.Content>
+            <Text>Header with title and close button.</Text>
+          </BottomSheet.Content>
+        </BottomSheet.View>
+      </BottomSheet.Modal>
+
+      <BottomSheet.Modal ref={refFull} handleVisible={false}>
+        <BottomSheet.View>
+          <BottomSheet.Header
+            title="Transfer"
+            subtitle="Step 2 of 3"
+            onBack={dismissFull}
+            onClose={dismissFull}
+          />
+          <BottomSheet.Content>
+            <Text>Full header with back button, title, subtitle, and close.</Text>
+          </BottomSheet.Content>
+        </BottomSheet.View>
+      </BottomSheet.Modal>
+    </BottomSheetDemoFrame>
+  );
+}
+```
+
+## Scrollable content
+
+```tsx
+import { BottomSheet, useBottomSheet, Box, Button, Text } from '@cdx-ui/components';
+import { BottomSheetDemoFrame } from './_frame';
+
+const ITEMS = Array.from({ length: 12 }, (_, i) => ({
+  id: String(i + 1),
+  label: `List item ${i + 1}`,
+}));
+
+export default function BottomSheetScrollableDemo() {
+  const { ref, present, dismiss } = useBottomSheet();
+
+  return (
+    <BottomSheetDemoFrame>
+      <Button variant="solid" color="action" onPress={present}>
+        <Button.Label>Scrollable content</Button.Label>
+      </Button>
+      <BottomSheet.Modal
+        ref={ref}
+        snapPoints={['70%']}
+        enableDynamicSizing={false}
+        footer={
+          <BottomSheet.Footer>
+            <Button variant="solid" color="action" onPress={dismiss}>
+              <Button.Label>Done</Button.Label>
+            </Button>
+          </BottomSheet.Footer>
+        }
+      >
+        <BottomSheet.Header title="Scrollable Sheet" onClose={dismiss} />
+        <BottomSheet.ScrollView style={{ flex: 1 }} contentContainerStyle={{ flexGrow: 1 }}>
+          <BottomSheet.Content>
+            {ITEMS.map((item) => (
+              <Box key={item.id} className="border-b border-stroke-secondary py-3">
+                <Text>{item.label}</Text>
+              </Box>
+            ))}
+          </BottomSheet.Content>
+        </BottomSheet.ScrollView>
+      </BottomSheet.Modal>
+    </BottomSheetDemoFrame>
+  );
+}
+```
+
+## Snap points
+
+By default, dynamic sizing caps the sheet at 90% of the screen height. Pass `snapPoints` with `enableDynamicSizing={false}` for fixed heights.
+
+```tsx
+import { BottomSheet, useBottomSheet, Button, Text } from '@cdx-ui/components';
+import { BottomSheetDemoFrame } from './_frame';
+
+export default function BottomSheetSnapPointsDemo() {
+  const { ref, present, dismiss } = useBottomSheet();
+
+  return (
+    <BottomSheetDemoFrame>
+      <Button variant="solid" color="action" onPress={present}>
+        <Button.Label>Fixed snap points</Button.Label>
+      </Button>
+      <BottomSheet.Modal
+        ref={ref}
+        snapPoints={['40%', '75%']}
+        enableDynamicSizing={false}
+        footer={
+          <BottomSheet.Footer>
+            <Button variant="solid" color="action" onPress={dismiss}>
+              <Button.Label>Close</Button.Label>
+            </Button>
+          </BottomSheet.Footer>
+        }
+      >
+        <BottomSheet.View>
+          <BottomSheet.Header title="Snap Points" onClose={dismiss} />
+          <BottomSheet.Content>
+            <Text>
+              This sheet snaps between 40% and 75% of the container. Drag up or down to snap between
+              positions.
+            </Text>
+          </BottomSheet.Content>
+        </BottomSheet.View>
+      </BottomSheet.Modal>
+    </BottomSheetDemoFrame>
+  );
+}
+```
+
+## Handle hidden
+
+```tsx
+import { BottomSheet, useBottomSheet, Button, Text } from '@cdx-ui/components';
+import { BottomSheetDemoFrame } from './_frame';
+
+export default function BottomSheetHandleHiddenDemo() {
+  const { ref, present, dismiss } = useBottomSheet();
+
+  return (
+    <BottomSheetDemoFrame>
+      <Button variant="solid" color="action" onPress={present}>
+        <Button.Label>No drag handle</Button.Label>
+      </Button>
+      <BottomSheet.Modal ref={ref} handleVisible={false}>
+        <BottomSheet.View>
+          <BottomSheet.Header title="No Handle" onClose={dismiss} />
+          <BottomSheet.Content>
+            <Text>
+              Set handleVisible to false when the header provides sufficient visual anchoring. The
+              sheet can still be dismissed by tapping the backdrop or using the close button.
+            </Text>
+          </BottomSheet.Content>
+        </BottomSheet.View>
+      </BottomSheet.Modal>
+    </BottomSheetDemoFrame>
+  );
+}
+```
+
+## API
+
+### BottomSheet.Modal
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `handleVisible?` | `boolean` | `true` | Show the drag handle indicator. When false, `handleComponent` is set to null. |
+| `footer?` | `React.ReactNode` | — | Footer content rendered via gorhom's BottomSheetFooter for animated positioning and safe-area handling. Pass it through this prop; a footer placed as a child does not animate with the sheet. |
+
+Also accepts all props from `@gorhom/bottom-sheet`'s `BottomSheetModal` including `snapPoints`, `enableDynamicSizing`, `onDismiss`, and `onChange`.
+
+### BottomSheet.Header
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title?` | `string` | — | Title text. Ignored when `children` is set. |
+| `subtitle?` | `string` | — | Secondary line under the title. Has no effect without `title`, or when `children` is set. |
+| `children?` | `React.ReactNode` | — | Custom header content. Replaces `title` and `subtitle`. |
+| `className?` | `string` | — | — |
+| `onClose?` | `(() => void)` | — | Shows the close button when set. |
+| `closeAccessibilityLabel?` | `string` | `Close` | Accessible name for the close button. |
+| `onBack?` | `(() => void)` | — | Shows the back button when set. |
+| `backAccessibilityLabel?` | `string` | `Go back` | Accessible name for the back button. |
+
+### BottomSheet.Content
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children?` | `React.ReactNode` | — | — |
+| `className?` | `string` | — | — |
+| `hasSafeAreaInset?` | `boolean` | — | Adds bottom padding equal to the safe-area inset. |
+| `style?` | `ViewStyle` | — | — |
+
+### BottomSheet.Footer
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children?` | `React.ReactNode` | — | — |
+| `className?` | `string` | — | — |
+| `style?` | `ViewStyle` | — | — |
+
+## Sub-components
+
+### BottomSheet.Provider
+
+Required once at the app root. Wraps the tree to enable modal presentation.
+
+```tsx
+<BottomSheet.Provider>
+  <App />
+</BottomSheet.Provider>
+```
+
+### BottomSheet.ScrollView
+
+Scrollable content wrapper for sheets with long content. Enables footer margin adjustment by default.
+
+### BottomSheet.View
+
+Non-scrollable content wrapper for fit-to-content sheets. Enables footer margin adjustment by default.
+
+## Hook
+
+### useBottomSheet
+
+Returns an imperative handle to present and dismiss a sheet.
+
+```tsx
+const { ref, present, dismiss } = useBottomSheet();
+```
+
+| Return    | Type                             | Description                        |
+| --------- | -------------------------------- | ---------------------------------- |
+| `ref`     | `RefObject<BottomSheetModalRef>` | Ref to pass to `BottomSheet.Modal` |
+| `present` | `() => void`                     | Opens the sheet                    |
+| `dismiss` | `() => void`                     | Closes the sheet                   |
+
+For advanced control (e.g. `snapToIndex`, `minimize`, `restore`), access `ref.current` directly.
+
+### useBottomSheetScrollable
+
+Pass the result to `VirtualizedList`'s `renderScrollComponent` when the list is inside a sheet. A plain list uses React Native's `ScrollView`, which Android cannot scroll against the sheet's pan gesture.
+
+```tsx
+const renderScrollComponent = useBottomSheetScrollable();
+
+<VirtualizedList
+  data={accounts}
+  renderItem={renderItem}
+  renderScrollComponent={renderScrollComponent}
+/>
+```
+
+## Accessibility
+
+- Pressing the backdrop closes the sheet.
+- Swiping down dismisses the sheet.
+- The close button's accessible name defaults to "Close", and the back button's defaults to "Go back".