@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/tooltip/content.md

@@ -0,0 +1,350 @@
+# Tooltip (https://design.candescent.com/docs/components/tooltip)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=12996-1099), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-tooltip--default)
+
+`Tooltip` is a compound component for short contextual hints. Compose `Tooltip.Trigger` with the interactive element and `Tooltip.Content` for the overlay body.
+
+```tsx
+import { Tooltip } from '@cdx-ui/components';
+```
+
+## Basic
+
+The default `hover` trigger opens on hover and focus on web, and on long press on native. Include `Tooltip.Arrow` inside `Tooltip.Content` when you want a directional pointer; omit it for a plain surface.
+
+```tsx
+import { Button, Tooltip } from '@cdx-ui/components';
+
+export default function TooltipBasicDemo() {
+  return (
+    <Tooltip>
+      <Tooltip.Trigger asChild>
+        <Button variant="solid" color="action">
+          <Button.Label>Hover for tooltip</Button.Label>
+        </Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <Tooltip.Arrow />
+        Helpful information about this element
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+## Without arrow
+
+Omit `Tooltip.Arrow` for a plain tooltip surface.
+
+```tsx
+import { Button, Tooltip } from '@cdx-ui/components';
+
+export default function TooltipWithoutArrowDemo() {
+  return (
+    <Tooltip>
+      <Tooltip.Trigger asChild>
+        <Button variant="solid" color="action">
+          <Button.Label>Hover me</Button.Label>
+        </Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>Plain tooltip without an arrow</Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+## Focus trigger
+
+Set `trigger="focus"` to open when the trigger receives keyboard focus. On native, focus and hover both map to long press.
+
+```tsx
+import { Button, Tooltip } from '@cdx-ui/components';
+
+export default function TooltipFocusTriggerDemo() {
+  return (
+    <Tooltip trigger="focus">
+      <Tooltip.Trigger asChild>
+        <Button variant="solid" color="action">
+          <Button.Label>Focus me</Button.Label>
+        </Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <Tooltip.Arrow />
+        Keyboard-accessible tooltip
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+## Click trigger
+
+Set `trigger="click"` to toggle the tooltip on press. On web, it closes on outside click or Escape.
+
+```tsx
+import { Button, Tooltip } from '@cdx-ui/components';
+
+export default function TooltipClickTriggerDemo() {
+  return (
+    <Tooltip trigger="click">
+      <Tooltip.Trigger asChild>
+        <Button variant="solid" color="action">
+          <Button.Label>Click for tooltip</Button.Label>
+        </Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <Tooltip.Arrow />
+        Opens on click or press. On web, closes on outside click or Escape.
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+## Placement
+
+Set `placement` to position the tooltip relative to the trigger. The component flips when there is not enough space.
+
+```tsx
+import { Box, Button, Tooltip, type TooltipPlacement } from '@cdx-ui/components';
+
+function PlacementExample({
+  placement,
+  label,
+}: Readonly<{
+  placement: TooltipPlacement;
+  label: string;
+}>) {
+  return (
+    <Tooltip placement={placement}>
+      <Tooltip.Trigger asChild>
+        <Button variant="solid" color="action">
+          <Button.Label>{label}</Button.Label>
+        </Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <Tooltip.Arrow />
+        {label} placement
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+
+export default function TooltipPlacementDemo() {
+  return (
+    <Box className="items-center gap-8">
+      <PlacementExample placement="top" label="Top" />
+      <Box className="flex-row items-center gap-16">
+        <PlacementExample placement="left" label="Left" />
+        <PlacementExample placement="right" label="Right" />
+      </Box>
+      <PlacementExample placement="bottom" label="Bottom" />
+    </Box>
+  );
+}
+```
+
+## Custom triggers
+
+Use `Tooltip.Trigger` with `asChild` to attach tooltips to avatars, chips, switches, icons, and other interactive elements.
+
+```tsx
+import { useState, type ReactElement } from 'react';
+import { Avatar, Box, Button, Chip, IconButton, Switch, Text, Tooltip } from '@cdx-ui/components';
+import { Info } from '@cdx-ui/icons';
+
+function CustomTriggerRow({
+  label,
+  content,
+  children,
+}: Readonly<{
+  label: string;
+  content: string;
+  children: ReactElement;
+}>) {
+  return (
+    <Box className="flex-row items-center gap-6">
+      <Text color="secondary" size="sm" className="w-20">
+        {label}
+      </Text>
+      <Tooltip>
+        <Tooltip.Trigger asChild>{children}</Tooltip.Trigger>
+        <Tooltip.Content>
+          <Tooltip.Arrow />
+          {content}
+        </Tooltip.Content>
+      </Tooltip>
+    </Box>
+  );
+}
+
+export default function TooltipCustomTriggersDemo() {
+  const [notifications, setNotifications] = useState(false);
+
+  return (
+    <Box className="items-start gap-8">
+      <CustomTriggerRow label="Avatar" content="Account owner profile">
+        <Avatar size="md">
+          <Avatar.Image src="https://www.loremfaces.net/128/id/1.jpg" />
+          <Avatar.Text>Jane Doe</Avatar.Text>
+        </Avatar>
+      </CustomTriggerRow>
+
+      <CustomTriggerRow label="Chip" content="Filter by premium members">
+        <Chip color="action" variant="outline">
+          <Chip.Label>Premium</Chip.Label>
+        </Chip>
+      </CustomTriggerRow>
+
+      <CustomTriggerRow label="Switch" content="Enable email notifications">
+        <Switch
+          value={notifications}
+          onValueChange={setNotifications}
+          accessibilityLabel="Email notifications"
+        />
+      </CustomTriggerRow>
+
+      <CustomTriggerRow label="Icon" content="Additional account information">
+        <IconButton as={Info} variant="ghost" accessibilityLabel="More information" />
+      </CustomTriggerRow>
+
+      <CustomTriggerRow label="Button" content="Initiate a funds transfer">
+        <Button color="action" variant="outline">
+          <Button.Label>Transfer</Button.Label>
+        </Button>
+      </CustomTriggerRow>
+    </Box>
+  );
+}
+```
+
+## Delay
+
+Use `enterDelay` and `leaveDelay` to debounce show and hide timing.
+
+```tsx
+import { Button, Tooltip } from '@cdx-ui/components';
+
+export default function TooltipDelayDemo() {
+  return (
+    <Tooltip enterDelay={500} leaveDelay={300}>
+      <Tooltip.Trigger asChild>
+        <Button variant="solid" color="action">
+          <Button.Label>Delayed tooltip</Button.Label>
+        </Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <Tooltip.Arrow />
+        Waits 500ms to open and 300ms to close
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+## Disabled
+
+Set `isDisabled` to block tooltip interactions.
+
+```tsx
+import { Button, Tooltip } from '@cdx-ui/components';
+
+export default function TooltipDisabledDemo() {
+  return (
+    <Tooltip isDisabled>
+      <Tooltip.Trigger asChild>
+        <Button variant="solid" color="action">
+          <Button.Label>Disabled tooltip</Button.Label>
+        </Button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        <Tooltip.Arrow />
+        This tooltip does not open
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+```
+
+## API
+
+### Tooltip
+
+Root container for trigger and content. Controls open state, placement, offset, and trigger mode.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+| `enterDelay?` | `number` | ``0`` | Milliseconds to wait before showing the tooltip. |
+| `leaveDelay?` | `number` | ``0`` | Milliseconds to wait before hiding the tooltip. |
+| `isOpen?` | `boolean` | — | Controlled open state. |
+| `defaultOpen?` | `boolean` | ``false`` | Uncontrolled initial open state. |
+| `onOpen?` | `(() => void)` | — | Called when the tooltip opens. |
+| `onClose?` | `(() => void)` | — | Called when the tooltip closes. |
+| `placement?` | `'auto' \| 'auto-start' \| 'auto-end' \| 'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'` | ``'top'`` | Preferred placement relative to the trigger. |
+| `offset?` | `number` | ``8`` | Distance in pixels between the tooltip and the trigger. |
+| `trigger?` | `'hover' \| 'focus' \| 'click'` | ``'hover'`` | Interaction that opens the tooltip. On web, `hover` opens on hover and focus; on native, long press. `focus` opens on focus (web) or long press (native). `click` toggles on press — on web, dismisses on outside click or Escape. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute       | Values             | Description                    |
+| --------------- | ------------------ | ------------------------------ |
+| `data-state`    | `open` \| `closed` | Whether the tooltip is visible |
+| `data-disabled` | `true` \| `false`  | Disabled state                 |
+
+## Sub-components
+
+### Tooltip.Trigger
+
+Wraps the element that opens the tooltip. Use `asChild` when composing with `Button` or other interactive children so hover and focus attach to the correct element.
+
+| 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` | — | When true, merges trigger props onto the single child element. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+### Tooltip.Content
+
+Tooltip body rendered in a portal. Plain string and number children are wrapped in styled text.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Tooltip.Arrow
+
+Optional directional arrow that points toward the trigger. Compose inside `Tooltip.Content`; positioning follows the resolved placement.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Optional directional arrow that points toward the trigger. Compose inside `Tooltip.Content`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute   | Values                                 | Description             |
+| ----------- | -------------------------------------- | ----------------------- |
+| `data-slot` | `tooltip-arrow`                        | Arrow element           |
+| `data-side` | `top` \| `bottom` \| `left` \| `right` | Resolved placement side |
+
+## Anatomy
+
+| `data-slot`       | Element                |
+| ----------------- | ---------------------- |
+| `tooltip-trigger` | Trigger wrapper        |
+| `tooltip-content` | Portal content surface |
+| `tooltip-arrow`   | Directional arrow      |
+
+## Accessibility
+
+On web, tooltip content uses `role="tooltip"` and the trigger is linked via `aria-describedby`. On native, content uses `accessibilityLiveRegion="polite"`. Tooltip content is decorative on native and does not trap focus.

package/docs/components/virtualized-list/content.md

@@ -0,0 +1,250 @@
+# Virtualized List (https://design.candescent.com/docs/components/virtualized-list)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=4040-4933), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-virtualizedlist--large-data-set)
+
+A thin wrapper around [`@shopify/flash-list`](https://shopify.github.io/flash-list/) that sets `role="list"` for accessibility. Use it when a list is long enough that mounting every row would hurt scroll performance.
+
+```tsx
+import { VirtualizedList } from '@cdx-ui/components';
+```
+
+## Basic
+
+Pass `data` and `renderItem`. Give the list a bounded height (or nest it in a flex parent that has one) so it can scroll. Use `ItemSeparatorComponent` for dividers between rows.
+
+```tsx
+import { Avatar, Box, Card, Divider, Text, VirtualizedList } from '@cdx-ui/components';
+import { CONTACTS } from './_data';
+
+export default function VirtualizedListBasicDemo() {
+  return (
+    <Box className="h-96 w-full max-w-md">
+      <Card fullBleed className="flex-1">
+        <Card.Content className="flex-1">
+          <VirtualizedList
+            data={CONTACTS}
+            keyExtractor={(item) => item.id}
+            ItemSeparatorComponent={() => <Divider />}
+            renderItem={({ item }) => (
+              <Box className="flex-row items-center gap-3 px-4 py-3">
+                <Avatar size="md">
+                  <Avatar.Text>{item.name.slice(0, 2)}</Avatar.Text>
+                </Avatar>
+                <Box className="flex-1 gap-0.5">
+                  <Text weight="semibold">{item.name}</Text>
+                  <Text color="secondary" size="sm">
+                    {item.role}
+                  </Text>
+                </Box>
+              </Box>
+            )}
+          />
+        </Card.Content>
+      </Card>
+    </Box>
+  );
+}
+```
+
+## Empty state
+
+Set `ListEmptyComponent` to show placeholder content when `data` is empty.
+
+```tsx
+import { Box, Card, Heading, Text, VirtualizedList } from '@cdx-ui/components';
+import type { Contact } from './_data';
+
+export default function VirtualizedListEmptyDemo() {
+  return (
+    <Box className="h-72 w-full max-w-md">
+      <Card fullBleed className="flex-1">
+        <Card.Content className="flex-1">
+          <VirtualizedList
+            data={[] as Contact[]}
+            keyExtractor={(item) => item.id}
+            renderItem={({ item }) => <Text>{item.name}</Text>}
+            ListEmptyComponent={
+              <Box className="items-center justify-center gap-2 px-4 py-12">
+                <Heading size="md">No contacts found</Heading>
+                <Text color="secondary" size="sm" className="text-center">
+                  Try adjusting your search or filters to find what you{"'"}re looking for.
+                </Text>
+              </Box>
+            }
+          />
+        </Card.Content>
+      </Card>
+    </Box>
+  );
+}
+```
+
+## Header and footer
+
+`ListHeaderComponent` and `ListFooterComponent` render above and below the scrollable items.
+
+```tsx
+import { Avatar, Box, Card, Divider, Text, VirtualizedList } from '@cdx-ui/components';
+import { CONTACTS } from './_data';
+
+export default function VirtualizedListHeaderFooterDemo() {
+  return (
+    <Box className="h-96 w-full max-w-md">
+      <Card fullBleed className="flex-1">
+        <Card.Content className="flex-1">
+          <VirtualizedList
+            data={CONTACTS}
+            keyExtractor={(item) => item.id}
+            ItemSeparatorComponent={() => <Divider />}
+            ListHeaderComponent={
+              <Box className="gap-0.5 border-b border-stroke-secondary bg-surface-secondary px-4 py-3">
+                <Text weight="semibold">My Team</Text>
+                <Text color="secondary" size="sm">
+                  {CONTACTS.length} members
+                </Text>
+              </Box>
+            }
+            ListFooterComponent={
+              <Box className="items-center border-t border-stroke-secondary bg-surface-secondary px-4 py-3">
+                <Text color="secondary" size="sm">
+                  Showing all {CONTACTS.length} members
+                </Text>
+              </Box>
+            }
+            renderItem={({ item }) => (
+              <Box className="flex-row items-center gap-3 px-4 py-3">
+                <Avatar size="md">
+                  <Avatar.Text>{item.name.slice(0, 2)}</Avatar.Text>
+                </Avatar>
+                <Box className="flex-1 gap-0.5">
+                  <Text weight="semibold">{item.name}</Text>
+                  <Text color="secondary" size="sm">
+                    {item.role}
+                  </Text>
+                </Box>
+              </Box>
+            )}
+          />
+        </Card.Content>
+      </Card>
+    </Box>
+  );
+}
+```
+
+## With ListItem
+
+Compose with [`ListItem`](https://design.candescent.com/docs/components/list-item/content.md) inside a `fullBleed` [`Card`](https://design.candescent.com/docs/components/card/content.md) for account, transaction, and settings rows. Only visible rows mount at a time.
+
+```tsx
+import { Avatar, Box, Card, ListItem, Text, VirtualizedList } from '@cdx-ui/components';
+
+const TITLES = ['Coffee Shop', 'Grocery Store', 'Gas Station', 'Online Transfer', 'Restaurant'];
+const DESCRIPTIONS = ['Visa · *4321', 'Debit · *6643', 'Visa · *8821', 'Internal', 'Visa · *4321'];
+const AMOUNTS = ['$12.45', '$84.20', '$41.75', '$250.00', '$36.18'];
+
+const transactions = Array.from({ length: 50 }, (_, i) => ({
+  id: String(i),
+  title: TITLES[i % TITLES.length],
+  description: DESCRIPTIONS[i % DESCRIPTIONS.length],
+  amount: AMOUNTS[i % AMOUNTS.length],
+  date: `May ${String((i % 28) + 1)}`,
+}));
+
+export default function VirtualizedListWithListItemDemo() {
+  return (
+    <Box className="h-96 w-full max-w-md">
+      <Card fullBleed className="flex-1">
+        <Card.Content className="flex-1">
+          <ListItem.SectionHeader>Recent Transactions</ListItem.SectionHeader>
+          <VirtualizedList
+            data={transactions}
+            keyExtractor={(item) => item.id}
+            renderItem={({ item, index }) => (
+              <ListItem onPress={() => undefined} showSeparator={index < transactions.length - 1}>
+                <ListItem.LeadingSlot>
+                  <Avatar size="md">
+                    <Avatar.Text>{item.title.slice(0, 2).toUpperCase()}</Avatar.Text>
+                  </Avatar>
+                </ListItem.LeadingSlot>
+                <ListItem.Content>
+                  <ListItem.Title>{item.title}</ListItem.Title>
+                  <ListItem.Description>{item.description}</ListItem.Description>
+                  <ListItem.Meta>{item.date}</ListItem.Meta>
+                </ListItem.Content>
+                <ListItem.TrailingSlot>
+                  <Text>{item.amount}</Text>
+                </ListItem.TrailingSlot>
+              </ListItem>
+            )}
+          />
+        </Card.Content>
+      </Card>
+    </Box>
+  );
+}
+```
+
+## API
+
+### VirtualizedList
+
+Accepts all [`FlashListProps<T>`](https://shopify.github.io/flash-list/docs/usage) from `@shopify/flash-list`. Key props:
+
+| Prop                     | Type                            | Description                                                  |
+| ------------------------ | ------------------------------- | ------------------------------------------------------------ |
+| `data`                   | `T[]`                           | Array of items to render                                     |
+| `renderItem`             | `ListRenderItem<T>`             | Render function for each item                                |
+| `keyExtractor`           | `(item, index) => string`       | Unique key for each item                                     |
+| `horizontal`             | `boolean`                       | Horizontal scroll direction                                  |
+| `numColumns`             | `number`                        | Multi-column grid layout                                     |
+| `ItemSeparatorComponent` | `ReactElement \| ComponentType` | Separator between items                                      |
+| `ListHeaderComponent`    | `ReactElement \| ComponentType` | Header above the list                                        |
+| `ListFooterComponent`    | `ReactElement \| ComponentType` | Footer below the list                                        |
+| `ListEmptyComponent`     | `ReactElement \| ComponentType` | Shown when `data` is empty                                   |
+| `onEndReached`           | `() => void`                    | Called when the end of the list is approached                |
+| `onEndReachedThreshold`  | `number`                        | How far from the end to trigger `onEndReached`               |
+| `extraData`              | `unknown`                       | Extra value that triggers re-render of items when it changes |
+
+For the full FlashList API (e.g. `getItemType`, `overrideItemLayout`, `drawDistance`), see the [FlashList documentation](https://shopify.github.io/flash-list/docs/usage).
+
+## Ref
+
+Access the underlying list for imperative methods via `VirtualizedListRef`:
+
+```tsx
+import { useRef } from 'react';
+import { VirtualizedList, type VirtualizedListRef } from '@cdx-ui/components';
+
+const listRef = useRef<VirtualizedListRef>(null);
+
+<VirtualizedList ref={listRef} data={items} renderItem={renderItem} />;
+
+listRef.current?.scrollToIndex({ index: 10, animated: true });
+```
+
+## Types
+
+Common FlashList types are re-exported from `@cdx-ui/components` so consumers do not need to depend on `@shopify/flash-list` directly:
+
+```tsx
+import type {
+  VirtualizedListProps,
+  VirtualizedListRef,
+  ListRenderItem,
+  ListRenderItemInfo,
+  ViewToken,
+} from '@cdx-ui/components';
+```
+
+| Type                      | Description                                                            |
+| ------------------------- | ---------------------------------------------------------------------- |
+| `VirtualizedListProps<T>` | Props accepted by `VirtualizedList` (alias for `FlashListProps<T>`)    |
+| `VirtualizedListRef`      | Ref type for imperative methods                                        |
+| `ListRenderItem<T>`       | Type for the `renderItem` callback                                     |
+| `ListRenderItemInfo<T>`   | Object passed to `renderItem` — `item`, `index`, `target`, `extraData` |
+| `ViewToken`               | Item visibility info for `onViewableItemsChanged`                      |
+
+## Accessibility
+
+`VirtualizedList` sets `role="list"` on the root. Add `role="listitem"` on row roots (or use components that provide it) when the list should be announced as a list to assistive technology.

package/docs/foundations/content.md

@@ -0,0 +1,9 @@
+# Foundations (https://design.candescent.com/docs/foundations)
+
+## Styles
+
+- [Tokens](https://design.candescent.com/docs/foundations/styles/tokens/what-are-tokens/content.md) — Named design decisions for color, type, spacing, and more that keep every brand consistent.
+
+## Expressions
+
+- [Icons](https://design.candescent.com/docs/foundations/expressions/icons/content.md) — Browse all available icons in the Forge UI icon library. Search, filter, and copy import statements.

package/docs/foundations/expressions/icons/content.md

@@ -0,0 +1,19 @@
+# Icons (https://design.candescent.com/docs/foundations/expressions/icons)
+
+Cross-platform icon library for Forge UI, built on [Material Symbols](https://fonts.google.com/icons) (outlined style, weight 400, optical size 24). Renders via `react-native-svg` and targets iOS, Android, and Web.
+
+3,983 icons are available, each with outlined and filled variants, plus support for custom
+SVGs.
+
+```bash
+pnpm add @cdx-ui/icons
+# or: npm install @cdx-ui/icons
+```
+
+## Search icons
+
+The browser on the site searches icons by name. To find an icon without it:
+
+- An export name is the Material Symbols name in PascalCase: `arrow_forward` is `ArrowForward`. A name that starts with a digit gets a leading underscore: `10k` is `_10k`. Look names up at [Material Symbols](https://fonts.google.com/icons).
+- Every icon is also exported with an `Icon` suffix (`ArrowForwardIcon`) and a `Cdx` prefix (`CdxArrowForward`). Pass `filled` for the filled variant where one exists.
+- To confirm a name exists, search `lib/typescript/icons/index.d.ts` in the installed `@cdx-ui/icons` package, or the "Icon names" section of [llms-full.txt](https://design.candescent.com/llms-full.txt), which lists every export, custom icons included.