@cdx-ui/components 0.2.3 → 0.2.4

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

@@ -0,0 +1,309 @@
+# ReorderableList (https://design.candescent.com/docs/components/reorderable-list)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-reorderablelist--default)
+
+Use `ReorderableList` for small ordered collections (accounts, favorites, dashboard tiles). Every row stays mounted so drop targets can be measured. For long read-only lists, use [`VirtualizedList`](https://design.candescent.com/docs/components/virtualized-list/content.md) instead.
+
+Drag-to-reorder uses `react-native-sortables` on native and `@dnd-kit/sortable` on web. Compose rows the same way on both platforms.
+
+## Installation
+
+`ReorderableList` ships from its own entry point, `@cdx-ui/components/reorderable-list`, not the main `@cdx-ui/components` entry. Its drag engines are optional peer dependencies, so apps that never import that entry point do not install them. Install the ones for the platforms you target.
+
+Native (iOS/Android) — also requires `react-native-gesture-handler` and `react-native-reanimated`:
+
+```bash
+pnpm add react-native-sortables
+# or: npm install react-native-sortables
+```
+
+Web:
+
+```bash
+pnpm add @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+# or: npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+```
+
+```tsx
+import { ListItem } from '@cdx-ui/components';
+import { ReorderableList } from '@cdx-ui/components/reorderable-list';
+```
+
+## Basic
+
+Compose with [`ListItem`](https://design.candescent.com/docs/components/list-item/content.md) and `ListItem.DragHandle`. Parent state owns `data`; `onReorder` receives the new array after a drop. Give the list a bounded height (same as `VirtualizedList`) so the `ScrollView` can layout; set flex sizing through `style` (for example `style={{ flex: 1 }}`) so native and web size the list the same way.
+
+`keyExtractor` must return a stable, unique key per item — never the index. Keys identify rows while they move; duplicates log a warning in development.
+
+```tsx
+import { useState } from 'react';
+import { Avatar, Box, Card, ListItem } from '@cdx-ui/components';
+import { ReorderableList } from '@cdx-ui/components/reorderable-list';
+import { ChevronRight } from '@cdx-ui/icons';
+
+const INITIAL = [
+  { id: '1', name: 'Alex Anderson', role: 'Software Engineer' },
+  { id: '2', name: 'Jordan Brooks', role: 'Product Designer' },
+  { id: '3', name: 'Taylor Chen', role: 'Engineering Manager' },
+  { id: '4', name: 'Morgan Davis', role: 'Data Scientist' },
+  { id: '5', name: 'Casey Evans', role: 'QA Lead' },
+  { id: '6', name: 'Riley Foster', role: 'Product Manager' },
+];
+
+export default function ReorderableListBasicDemo() {
+  const [contacts, setContacts] = useState(INITIAL);
+
+  return (
+    <Box className="h-96 w-full max-w-md">
+      <Card fullBleed className="flex-1">
+        <Card.Content className="flex-1">
+          <ReorderableList
+            data={contacts}
+            keyExtractor={(item) => item.id}
+            onReorder={setContacts}
+            style={{ flex: 1 }}
+            renderItem={({ item, index }) => (
+              <ListItem showSeparator={index < contacts.length - 1}>
+                <ListItem.DragHandle accessibilityLabel={`Reorder ${item.name}`} />
+                <ListItem.LeadingSlot>
+                  <Avatar size="md">
+                    <Avatar.Text>{item.name}</Avatar.Text>
+                  </Avatar>
+                </ListItem.LeadingSlot>
+                <ListItem.Content>
+                  <ListItem.Title>{item.name}</ListItem.Title>
+                  <ListItem.Description>{item.role}</ListItem.Description>
+                </ListItem.Content>
+                <ListItem.TrailingSlot>
+                  <ChevronRight size={20} />
+                </ListItem.TrailingSlot>
+              </ListItem>
+            )}
+          />
+        </Card.Content>
+      </Card>
+    </Box>
+  );
+}
+```
+
+## Pressable rows
+
+Rows can navigate with `onPress` (or `asChild` with a `Link`) and still reorder. Put `ListItem.DragHandle` first or last among the row's direct children: the row renders it beside the pressable element, so pressing the handle never opens the row.
+
+```tsx
+import { useState } from 'react';
+import { Box, Card, ListItem, Text } from '@cdx-ui/components';
+import { ReorderableList } from '@cdx-ui/components/reorderable-list';
+import { ChevronRight } from '@cdx-ui/icons';
+
+const INITIAL = [
+  { id: 'checking', name: 'Everyday Checking', balance: '$2,450.18' },
+  { id: 'savings', name: 'High-Yield Savings', balance: '$12,903.55' },
+  { id: 'credit', name: 'Rewards Credit Card', balance: '$384.20' },
+  { id: 'loan', name: 'Auto Loan', balance: '$9,112.00' },
+];
+
+export default function ReorderableListPressableDemo() {
+  const [accounts, setAccounts] = useState(INITIAL);
+  const [opened, setOpened] = useState<string | null>(null);
+
+  return (
+    <Box className="w-full max-w-md gap-3">
+      <Card fullBleed>
+        <Card.Content>
+          <ReorderableList
+            data={accounts}
+            keyExtractor={(item) => item.id}
+            onReorder={setAccounts}
+            getItemLabel={(item) => item.name}
+            renderItem={({ item, index }) => (
+              <ListItem
+                onPress={() => setOpened(item.name)}
+                accessibilityLabel={`Open ${item.name}`}
+                showSeparator={index < accounts.length - 1}
+              >
+                <ListItem.DragHandle accessibilityLabel={`Reorder ${item.name}`} />
+                <ListItem.Content>
+                  <ListItem.Title>{item.name}</ListItem.Title>
+                  <ListItem.Description>{item.balance}</ListItem.Description>
+                </ListItem.Content>
+                <ListItem.TrailingSlot>
+                  <ChevronRight size={20} />
+                </ListItem.TrailingSlot>
+              </ListItem>
+            )}
+          />
+        </Card.Content>
+      </Card>
+      <Text aria-live="polite">{opened ? `Opened ${opened}` : 'Select an account'}</Text>
+    </Box>
+  );
+}
+```
+
+## Scrollable content
+
+When the rows overflow the list's height, the list scrolls on its own. Dragging a row near the top or bottom edge auto-scrolls so the row can reach any position.
+
+```tsx
+import { useState } from 'react';
+import { Box, Card, ListItem } from '@cdx-ui/components';
+import { ReorderableList } from '@cdx-ui/components/reorderable-list';
+
+const INITIAL = [
+  { id: 'rent', name: 'Rent', detail: 'Due on the 1st' },
+  { id: 'electric', name: 'City Electric', detail: 'Autopay' },
+  { id: 'water', name: 'Water & Sewer', detail: 'Due on the 12th' },
+  { id: 'internet', name: 'Fiber Internet', detail: 'Autopay' },
+  { id: 'phone', name: 'Mobile Phone', detail: 'Due on the 18th' },
+  { id: 'auto-loan', name: 'Auto Loan', detail: 'Due on the 20th' },
+  { id: 'insurance', name: 'Auto Insurance', detail: 'Autopay' },
+  { id: 'daycare', name: 'Little Oaks Daycare', detail: 'Due on the 1st' },
+  { id: 'gym', name: 'Gym Membership', detail: 'Autopay' },
+  { id: 'streaming', name: 'Streaming', detail: 'Autopay' },
+  { id: 'student-loan', name: 'Student Loan', detail: 'Due on the 25th' },
+  { id: 'credit-card', name: 'Rewards Credit Card', detail: 'Due on the 28th' },
+];
+
+export default function ReorderableListScrollableDemo() {
+  const [payees, setPayees] = useState(INITIAL);
+
+  return (
+    <Box className="h-80 w-full max-w-md">
+      <Card fullBleed className="flex-1">
+        <Card.Content className="flex-1">
+          <ReorderableList
+            data={payees}
+            keyExtractor={(item) => item.id}
+            onReorder={setPayees}
+            getItemLabel={(item) => item.name}
+            style={{ flex: 1 }}
+            renderItem={({ item, index }) => (
+              <ListItem size="compact" showSeparator={index < payees.length - 1}>
+                <ListItem.DragHandle accessibilityLabel={`Reorder ${item.name}`} />
+                <ListItem.Content>
+                  <ListItem.Title>{item.name}</ListItem.Title>
+                  <ListItem.Description>{item.detail}</ListItem.Description>
+                </ListItem.Content>
+              </ListItem>
+            )}
+          />
+        </Card.Content>
+      </Card>
+    </Box>
+  );
+}
+```
+
+## Removing rows
+
+To remove a row, filter it out of `data`; the remaining rows close the gap. Put the remove control in `ListItem.TrailingSlot` and name the row in its label.
+
+```tsx
+import { useState } from 'react';
+import { Box, Button, Card, IconButton, ListItem, Text } from '@cdx-ui/components';
+import { ReorderableList } from '@cdx-ui/components/reorderable-list';
+import { Delete } from '@cdx-ui/icons';
+
+const INITIAL = [
+  { id: 'rent', name: 'Rent', detail: 'Due on the 1st' },
+  { id: 'electric', name: 'City Electric', detail: 'Autopay' },
+  { id: 'water', name: 'Water & Sewer', detail: 'Due on the 12th' },
+  { id: 'internet', name: 'Fiber Internet', detail: 'Autopay' },
+  { id: 'phone', name: 'Mobile Phone', detail: 'Due on the 18th' },
+];
+
+export default function ReorderableListRemovableDemo() {
+  const [payees, setPayees] = useState(INITIAL);
+
+  return (
+    <Box className="w-full max-w-md gap-3">
+      <Card fullBleed>
+        <Card.Content>
+          {payees.length > 0 ? (
+            <ReorderableList
+              data={payees}
+              keyExtractor={(item) => item.id}
+              onReorder={setPayees}
+              getItemLabel={(item) => item.name}
+              renderItem={({ item, index }) => (
+                <ListItem size="compact" showSeparator={index < payees.length - 1}>
+                  <ListItem.DragHandle accessibilityLabel={`Reorder ${item.name}`} />
+                  <ListItem.Content>
+                    <ListItem.Title>{item.name}</ListItem.Title>
+                    <ListItem.Description>{item.detail}</ListItem.Description>
+                  </ListItem.Content>
+                  <ListItem.TrailingSlot>
+                    <IconButton
+                      as={Delete}
+                      variant="ghost"
+                      size="small"
+                      accessibilityLabel={`Remove ${item.name}`}
+                      onPress={() =>
+                        setPayees((current) => current.filter((payee) => payee.id !== item.id))
+                      }
+                    />
+                  </ListItem.TrailingSlot>
+                </ListItem>
+              )}
+            />
+          ) : (
+            <Text className="body-sm text-content-secondary p-4">No payees left.</Text>
+          )}
+        </Card.Content>
+      </Card>
+      <Button variant="outline" onPress={() => setPayees(INITIAL)}>
+        <Button.Label>Reset</Button.Label>
+      </Button>
+    </Box>
+  );
+}
+```
+
+## API
+
+### ReorderableList
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `data` | `unknown[]` | — | Items in their current order. The parent owns this array and updates it from `onReorder`. |
+| `keyExtractor` | `(item: unknown, index: number) => string` | — | Returns a stable, unique key for an item. Keys identify rows while they move, so they must not be derived from `index`. Duplicate keys log a warning in development. |
+| `renderItem` | `(info: ReorderableListRenderItemInfo<unknown>) => ReactNode` | — | Renders one row. Compose with `ListItem` and `ListItem.DragHandle`. |
+| `onReorder` | `(data: unknown[]) => void` | — | Called with the reordered array after a drop or an accessibility move. |
+| `onReorderIndices?` | `((from: number, to: number) => void)` | — | Called after `onReorder` with the moved row's previous and new zero-based positions. |
+| `getItemLabel?` | `((item: unknown, index: number) => string)` | — | Returns the name screen readers use for a row in reorder announcements. Without it, announcements use the `item` label (`item 2`). Keys are never announced. |
+| `labels?` | `Partial<ReorderableListLabels>` | `{}` | Overrides for announcement and accessibility-action copy. Unset keys keep their defaults. |
+
+Inherits [`ScrollViewProps`](https://reactnative.dev/docs/scrollview#props) except `children`, `horizontal`, and `role`, which the list owns. `onScroll` and `onContentSizeChange` pass through to the `ScrollView`.
+
+### Labels
+
+Pass `labels` to translate or reword announcements and accessibility actions. `{item}` is the row name (from `getItemLabel`, or `item {position}`), `{position}` is 1-based, and `{count}` is the number of rows.
+
+```tsx
+<ReorderableList
+  getItemLabel={(account) => account.nickname}
+  labels={{ movedTo: '{item} déplacé en position {position} sur {count}.' }}
+  {...props}
+/>
+```
+
+## Anatomy
+
+| `data-slot`             | Element                         |
+| ----------------------- | ------------------------------- |
+| `reorderable-list`      | Scrollable list root            |
+| `list-item-drag-handle` | Handle on a composed `ListItem` |
+
+## Accessibility
+
+| Attribute                      | Behavior                                                                                                                                                                                                                             |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Role**                       | Root sets `role="list"`.                                                                                                                                                                                                             |
+| **Handle**                     | `ListItem.DragHandle` is a button with default label `Reorder`. Pass a row-specific `accessibilityLabel`. On native its default hint names the move actions; on web the keyboard instructions are linked through `aria-describedby`. |
+| **Activation**                 | Drag starts from the handle, which sits beside a pressable row's interactive element rather than inside it, so row `onPress` can still navigate. The click that ends a pointer drag does not press the row.                          |
+| **Single-pointer alternative** | On native, each handle exposes `Move up`, `Move down`, `Move to top`, and `Move to bottom` accessibility actions; actions that do not apply at the ends are omitted.                                                                 |
+| **Keyboard (web)**             | Focus the handle, press Space or Enter to pick up, the arrow keys to move, Space or Enter to drop, or Escape to cancel.                                                                                                              |
+| **Announcements**              | Pick-up, move, drop, and cancel are announced by position (`Moved item 2 to position 3 of 5.`). Pass `getItemLabel` to name rows; keys are never announced.                                                                          |

package/docs/components/scoped-theme/content.md

@@ -0,0 +1,47 @@
+# ScopedTheme (https://design.candescent.com/docs/components/scoped-theme)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/theming-scopedtheme--default)
+
+`ScopedTheme` locks a subtree to one theme, for a section, widget, or preview that must stay in a fixed mode.
+
+```tsx
+import { ScopedTheme } from '@cdx-ui/components';
+```
+
+## Basic
+
+Force dark tokens on the wrapped content. On web the wrapper is a `display: contents` element with the theme class, so CSS variables cascade into the children. On iOS and Android the theme is applied through React context.
+
+On web, `theme="light"` applies when no `.dark` ancestor is present. There is no light custom variant to override one. Native honors either value through context.
+
+Web apps enable the class cascade with the dark custom variant in `global.css`. See [Getting Started](https://design.candescent.com/docs/getting-started/developers/content.md).
+
+```tsx
+import { Card, Heading, ScopedTheme, Text } from '@cdx-ui/components';
+
+export default function ScopedThemeBasicDemo() {
+  return (
+    <ScopedTheme theme="dark">
+      <Card className="w-full max-w-md">
+        <Card.Header>
+          <Heading size="sm">Dark section</Heading>
+        </Card.Header>
+        <Card.Content>
+          <Text size="sm">This content always renders in dark mode.</Text>
+        </Card.Content>
+      </Card>
+    </ScopedTheme>
+  );
+}
+```
+
+## API
+
+### ScopedTheme
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `theme` | `string` | — | The theme forced on the subtree, such as `'dark'` or `'light'`. |
+| `children?` | `React.ReactNode` | — | The subtree that renders in `theme`. |
+
+Does not extend a React Native base component — every prop is listed above. Forge UI themes are `light` and `dark`.