@cdx-ui/components 0.2.3 → 0.2.5

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

@@ -0,0 +1,695 @@
+# List Item (https://design.candescent.com/docs/components/list-item)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=3710-4649), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/surfaces-listitem--default)
+
+A compound component with sub-components for leading content, title, description, meta, trailing content, and section headers. Provide `onPress` to make the row pressable, or use `asChild` with `Link` for navigation.
+
+```tsx
+import { ListItem } from '@cdx-ui/components';
+```
+
+## Basic
+
+Compose `ListItem.LeadingSlot`, `ListItem.Content`, and `ListItem.TrailingSlot` for a typical account or transaction row. Set `onPress` to make the row interactive.
+
+```tsx
+import { Avatar, Card, ListItem, Text } from '@cdx-ui/components';
+import { Person } from '@cdx-ui/icons';
+
+export default function ListItemBasicDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem onPress={() => {}} showSeparator={false}>
+          <ListItem.LeadingSlot>
+            <Avatar>
+              <Avatar.Icon as={Person} />
+            </Avatar>
+          </ListItem.LeadingSlot>
+          <ListItem.Content>
+            <ListItem.Title>Joint Checking · 6643</ListItem.Title>
+            <ListItem.Description>Available balance</ListItem.Description>
+          </ListItem.Content>
+          <ListItem.TrailingSlot>
+            <Text>$2,450.00</Text>
+          </ListItem.TrailingSlot>
+        </ListItem>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## Static items
+
+Omit `onPress` when rows present read-only information, such as account balances. The rows retain the same structure without suggesting that they navigate or trigger an action.
+
+```tsx
+import { Card, Heading, ListItem, Text } from '@cdx-ui/components';
+
+const accounts = [
+  {
+    name: 'Joint Checking · 6643',
+    description: 'Available balance',
+    balance: '$2,450.00',
+  },
+  {
+    name: 'High Yield Savings · 7891',
+    description: 'Available balance',
+    balance: '$25,430.00',
+  },
+];
+
+export default function ListItemAvailableBalancesDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Header>
+        <Heading size="sm">Available balances</Heading>
+      </Card.Header>
+      <Card.Content>
+        {accounts.map((account, index) => (
+          <ListItem key={account.name} showSeparator={index < accounts.length - 1}>
+            <ListItem.Content>
+              <ListItem.Title>{account.name}</ListItem.Title>
+              <ListItem.Description>{account.description}</ListItem.Description>
+            </ListItem.Content>
+            <ListItem.TrailingSlot>
+              <Text>{account.balance}</Text>
+            </ListItem.TrailingSlot>
+          </ListItem>
+        ))}
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## Sizes
+
+Use `size="compact"` for denser rows. Typography stays the same; padding and min-height shrink.
+
+```tsx
+import { Avatar, Card, ListItem, Text, VStack } from '@cdx-ui/components';
+import { Person } from '@cdx-ui/icons';
+
+export default function ListItemSizesDemo() {
+  return (
+    <VStack space="2xl" className="w-full max-w-md">
+      {(['default', 'compact'] as const).map((size) => (
+        <VStack key={size} space="sm">
+          <Text size="sm">{size}</Text>
+          <Card fullBleed>
+            <Card.Content>
+              <ListItem size={size} onPress={() => {}} showSeparator={false}>
+                <ListItem.LeadingSlot>
+                  <Avatar>
+                    <Avatar.Icon as={Person} />
+                  </Avatar>
+                </ListItem.LeadingSlot>
+                <ListItem.Content>
+                  <ListItem.Title>Joint Checking · 6643</ListItem.Title>
+                  <ListItem.Description>Available balance</ListItem.Description>
+                </ListItem.Content>
+                <ListItem.TrailingSlot>
+                  <Text>$2,450.00</Text>
+                </ListItem.TrailingSlot>
+              </ListItem>
+            </Card.Content>
+          </Card>
+        </VStack>
+      ))}
+    </VStack>
+  );
+}
+```
+
+## With meta
+
+`ListItem.Meta` adds a tertiary line under the description — useful for timestamps and sources in alert feeds.
+
+```tsx
+import { Card, ListItem } from '@cdx-ui/components';
+
+export default function ListItemWithMetaDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem onPress={() => {}} showSeparator={false}>
+          <ListItem.Content>
+            <ListItem.Title>Security alert</ListItem.Title>
+            <ListItem.Description>
+              Unusual login detected from a new device in Portland, OR
+            </ListItem.Description>
+            <ListItem.Meta>2 hours ago · by System</ListItem.Meta>
+          </ListItem.Content>
+        </ListItem>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## With switch
+
+Omit `onPress` when the row hosts an interactive control in `ListItem.TrailingSlot`, such as a `Switch`.
+
+```tsx
+import { useState } from 'react';
+import { Card, ListItem, Switch } from '@cdx-ui/components';
+import { Notifications } from '@cdx-ui/icons';
+
+export default function ListItemWithSwitchDemo() {
+  const [enabled, setEnabled] = useState(true);
+
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem showSeparator={false}>
+          <ListItem.LeadingSlot>
+            <Notifications size={24} />
+          </ListItem.LeadingSlot>
+          <ListItem.Content>
+            <ListItem.Title>Push Notifications</ListItem.Title>
+            <ListItem.Description>Receive alerts for account activity</ListItem.Description>
+          </ListItem.Content>
+          <ListItem.TrailingSlot>
+            <Switch value={enabled} onValueChange={setEnabled} />
+          </ListItem.TrailingSlot>
+        </ListItem>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## Sectioned
+
+Use `ListItem.SectionHeader` to group rows (e.g. by date). Each row renders its own bottom separator — set `showSeparator={false}` on the last item.
+
+```tsx
+import { Card, Chip, ListItem } from '@cdx-ui/components';
+
+export default function ListItemSectionedDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem.SectionHeader>Today, Friday February 13</ListItem.SectionHeader>
+
+        <ListItem onPress={() => {}}>
+          <ListItem.Content>
+            <ListItem.Title>Wire transfer received</ListItem.Title>
+            <ListItem.Description>
+              Save money with our bank account and credit card. Enjoy no annual fee cross-border
+              banking for 1 year
+            </ListItem.Description>
+            <ListItem.Meta>5 hours · by System</ListItem.Meta>
+          </ListItem.Content>
+          <ListItem.TrailingSlot>
+            <Chip color="info" size="small">
+              <Chip.Label>NEW</Chip.Label>
+            </Chip>
+          </ListItem.TrailingSlot>
+        </ListItem>
+
+        <ListItem onPress={() => {}}>
+          <ListItem.Content>
+            <ListItem.Title>Payment reminder</ListItem.Title>
+            <ListItem.Description>
+              Your credit card payment of $1,250.00 is due in 3 days
+            </ListItem.Description>
+            <ListItem.Meta>8 hours · by System</ListItem.Meta>
+          </ListItem.Content>
+        </ListItem>
+
+        <ListItem.SectionHeader>Thursday February 12</ListItem.SectionHeader>
+
+        <ListItem onPress={() => {}}>
+          <ListItem.Content>
+            <ListItem.Title>Account statement ready</ListItem.Title>
+            <ListItem.Description>
+              Your January statement is now available for download
+            </ListItem.Description>
+            <ListItem.Meta>1 day · by System</ListItem.Meta>
+          </ListItem.Content>
+        </ListItem>
+
+        <ListItem onPress={() => {}} showSeparator={false}>
+          <ListItem.Content>
+            <ListItem.Title>Security alert</ListItem.Title>
+            <ListItem.Description>
+              New device logged into your account from Portland, OR
+            </ListItem.Description>
+            <ListItem.Meta>1 day · by System</ListItem.Meta>
+          </ListItem.Content>
+          <ListItem.TrailingSlot>
+            <Chip color="info" size="small">
+              <Chip.Label>NEW</Chip.Label>
+            </Chip>
+          </ListItem.TrailingSlot>
+        </ListItem>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+Set `variant="subtle"` when grouping a contact list alphabetically. The neutral background stands the letter headers apart from their rows. The fill replaces the header's bottom border; the label styling and top divider stay the same.
+
+```tsx
+import { Avatar, Card, ListItem } from '@cdx-ui/components';
+
+export default function ListItemSectionedSubtleDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem.SectionHeader variant="subtle" showDivider={false}>
+          A
+        </ListItem.SectionHeader>
+
+        <ListItem onPress={() => {}}>
+          <ListItem.LeadingSlot>
+            <Avatar>
+              <Avatar.Text>Adam White</Avatar.Text>
+            </Avatar>
+          </ListItem.LeadingSlot>
+          <ListItem.Content>
+            <ListItem.Title>Adam White</ListItem.Title>
+            <ListItem.Description>Classmate</ListItem.Description>
+          </ListItem.Content>
+        </ListItem>
+
+        <ListItem onPress={() => {}} showSeparator={false}>
+          <ListItem.LeadingSlot>
+            <Avatar>
+              <Avatar.Text>Aron Smith</Avatar.Text>
+            </Avatar>
+          </ListItem.LeadingSlot>
+          <ListItem.Content>
+            <ListItem.Title>Aron Smith</ListItem.Title>
+            <ListItem.Description>Gym</ListItem.Description>
+          </ListItem.Content>
+        </ListItem>
+
+        <ListItem.SectionHeader variant="subtle" showDivider={false}>
+          B
+        </ListItem.SectionHeader>
+
+        <ListItem onPress={() => {}}>
+          <ListItem.LeadingSlot>
+            <Avatar>
+              <Avatar.Text>Bennett Charles</Avatar.Text>
+            </Avatar>
+          </ListItem.LeadingSlot>
+          <ListItem.Content>
+            <ListItem.Title>Bennett Charles</ListItem.Title>
+            <ListItem.Description>Savings •••1189</ListItem.Description>
+          </ListItem.Content>
+        </ListItem>
+
+        <ListItem onPress={() => {}} showSeparator={false}>
+          <ListItem.LeadingSlot>
+            <Avatar>
+              <Avatar.Text>Brightside Dental</Avatar.Text>
+            </Avatar>
+          </ListItem.LeadingSlot>
+          <ListItem.Content>
+            <ListItem.Title>Brightside Dental</ListItem.Title>
+            <ListItem.Description>Business Checking •••6021</ListItem.Description>
+          </ListItem.Content>
+        </ListItem>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+Set `variant="gradient"` for account group headers on a dashboard. The fill fades from the primary surface into a brand tint and keeps the bottom border.
+
+```tsx
+import { Card, ListItem, Text } from '@cdx-ui/components';
+
+export default function ListItemSectionedGradientDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem.SectionHeader variant="gradient" showDivider={false}>
+          Checking &amp; savings
+        </ListItem.SectionHeader>
+
+        <ListItem onPress={() => {}}>
+          <ListItem.Content>
+            <ListItem.Title>Joint Household Checking</ListItem.Title>
+            <ListItem.Description>Available balance</ListItem.Description>
+          </ListItem.Content>
+          <ListItem.TrailingSlot>
+            <Text weight="semibold">$9,311.45</Text>
+          </ListItem.TrailingSlot>
+        </ListItem>
+
+        <ListItem onPress={() => {}} showSeparator={false}>
+          <ListItem.Content>
+            <ListItem.Title>Deposit Savings</ListItem.Title>
+            <ListItem.Description>Available balance</ListItem.Description>
+          </ListItem.Content>
+          <ListItem.TrailingSlot>
+            <Text weight="semibold">$6,345.67</Text>
+          </ListItem.TrailingSlot>
+        </ListItem>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## Virtualized list
+
+For long scrollable lists, render `ListItem` rows from `VirtualizedList` inside a `fullBleed` `Card`. 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 ListItemVirtualizedDemo() {
+  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>
+                    <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>
+  );
+}
+```
+
+## Multiple trailing
+
+`ListItem.TrailingSlot` lays out multiple children in a horizontal row. Interactive trailing elements manage their own touch targets.
+
+```tsx
+import { Avatar, Card, IconButton, ListItem } from '@cdx-ui/components';
+import { ChevronRight, Person, Star } from '@cdx-ui/icons';
+
+export default function ListItemMultipleTrailingDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem onPress={() => {}} showSeparator={false}>
+          <ListItem.LeadingSlot>
+            <Avatar>
+              <Avatar.Icon as={Person} />
+            </Avatar>
+          </ListItem.LeadingSlot>
+          <ListItem.Content>
+            <ListItem.Title>Savings Account</ListItem.Title>
+            <ListItem.Description>·4321</ListItem.Description>
+          </ListItem.Content>
+          <ListItem.TrailingSlot>
+            <IconButton as={Star} size="small" variant="ghost" onPress={() => {}} />
+            <ChevronRight size={20} />
+          </ListItem.TrailingSlot>
+        </ListItem>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## Disabled
+
+Set `isDisabled` to block press handling and reduce opacity.
+
+```tsx
+import { Avatar, Card, ListItem } from '@cdx-ui/components';
+import { ChevronRight, Person } from '@cdx-ui/icons';
+
+export default function ListItemDisabledDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem onPress={() => {}} isDisabled showSeparator={false}>
+          <ListItem.LeadingSlot>
+            <Avatar>
+              <Avatar.Icon as={Person} />
+            </Avatar>
+          </ListItem.LeadingSlot>
+          <ListItem.Content>
+            <ListItem.Title>Locked Account · 9912</ListItem.Title>
+            <ListItem.Description>Contact support to unlock</ListItem.Description>
+          </ListItem.Content>
+          <ListItem.TrailingSlot>
+            <ChevronRight size={20} />
+          </ListItem.TrailingSlot>
+        </ListItem>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## As link
+
+Use `asChild` with `Link` so the link owns navigation while `ListItem` owns layout and visual treatment — no nested pressables.
+
+```tsx
+import { Card, Link, ListItem } from '@cdx-ui/components';
+import { ChevronRight, Notifications, Settings } from '@cdx-ui/icons';
+
+export default function ListItemAsLinkDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem asChild>
+          <Link href="https://example.com/settings" accessibilityLabel="Account settings">
+            <ListItem.LeadingSlot>
+              <Settings size={24} />
+            </ListItem.LeadingSlot>
+            <ListItem.Content>
+              <ListItem.Title>Account Settings</ListItem.Title>
+              <ListItem.Description>Manage your preferences</ListItem.Description>
+            </ListItem.Content>
+            <ListItem.TrailingSlot>
+              <ChevronRight size={20} />
+            </ListItem.TrailingSlot>
+          </Link>
+        </ListItem>
+        <ListItem asChild showSeparator={false}>
+          <Link href="https://example.com/notifications" accessibilityLabel="Notifications">
+            <ListItem.LeadingSlot>
+              <Notifications size={24} />
+            </ListItem.LeadingSlot>
+            <ListItem.Content>
+              <ListItem.Title>Notifications</ListItem.Title>
+              <ListItem.Description>Push, email, and SMS alerts</ListItem.Description>
+            </ListItem.Content>
+            <ListItem.TrailingSlot>
+              <ChevronRight size={20} />
+            </ListItem.TrailingSlot>
+          </Link>
+        </ListItem>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## API
+
+### ListItem
+
+Root row container. Renders as `View` by default; becomes pressable when `onPress` is provided. Use `asChild` to merge props onto a single child (e.g. `Link`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `crossAlign?` | `'center' \| 'start'` | `'center'` | Vertical alignment of the leading, content, and trailing slots. `start` top-aligns them so trailing text lines up with the title. |
+| `onPressIn?` | `((event: GestureResponderEvent) => void) \| null` | — | Called when a touch is engaged before `onPress`. |
+| `onPressOut?` | `((event: GestureResponderEvent) => void) \| null` | — | Called when a touch is released before `onPress`. |
+| `onHoverIn?` | `((event: MouseEvent) => void) \| null` | — | Called when the hover is activated to provide visual feedback. |
+| `onHoverOut?` | `((event: MouseEvent) => void) \| null` | — | Called when the hover is deactivated to undo visual feedback. |
+| `isDisabled?` | `boolean` | — | Disables press handling when the root is pressable (maps to Pressable `disabled`). |
+| `onPress?` | `((event: GestureResponderEvent) => void) \| null` | — | When set (and `asChild` is not used), root renders as pressable with interaction props. |
+| `asChild?` | `boolean` | — | Merge props onto a single child (for example `Link`) instead of rendering `View` or `Pressable`. The child's `onPress` is kept unless this component also passes `onPress`. `isDisabled` suppresses press on the child. |
+| `accessory?` | `ReactNode` | — | Interactive control that must sit beside the row's pressable element, never inside it (for example a drag handle). On a pressable row (`onPress`, or `asChild` with an element child) the root renders a non-interactive container holding the accessory and the pressable region as siblings. The container receives `ref`, `className`, `style`, and data attributes, and mirrors the region's interaction state as `data-*`; the region receives every other prop. A non-pressable row renders the accessory inline beside `children`. |
+| `accessoryPosition?` | `'start' \| 'end'` | `'start'` | Side of the pressable region the accessory renders on. |
+| `pressableClassName?` | `string` | — | Class names for the pressable region when `accessory` splits the row. |
+| `pressableStyle?` | `StyleProp<ViewStyle>` | — | Style for the pressable region when `accessory` splits the row. |
+| `size?` | `'default' \| 'compact'` | `'default'` | Vertical density. `compact` reduces padding and min-height; typography stays the same. |
+| `showSeparator?` | `boolean` | `true` | Bottom border between rows. Set `false` on the last row to avoid a trailing border. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). When `onPress` is set, pressable event handlers (`onPressIn`, `onPressOut`, `onHoverIn`, `onHoverOut`) are also accepted.
+
+| Attribute            | Values            | Description                                                                                                                                                                 |
+| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-slot`          | `list-item`       | Root row                                                                                                                                                                    |
+| `data-disabled`      | `true` \| `false` | Disabled state                                                                                                                                                              |
+| `data-hover`         | `true` \| `false` | Hover (web, when pressable)                                                                                                                                                 |
+| `data-active`        | `true` \| `false` | Pressed (when pressable)                                                                                                                                                    |
+| `data-focus-visible` | `true` \| `false` | Keyboard focus ring (web)                                                                                                                                                   |
+| `data-dragging`      | `true` \| `false` | True while this row is dragged in a [`ReorderableList`](https://design.candescent.com/docs/components/reorderable-list/content.md). Read from the list's row context; there is no prop |
+
+## Sub-components
+
+### ListItem.LeadingSlot
+
+Optional leading adornment (Avatar, Icon). Decorative and `aria-hidden` by default — set `aria-hidden={false}` when the slot contains meaningful controls.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Renders the consumer's child element in place of the default `View` host. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### ListItem.DragHandle
+
+Explicit grip used with [`ReorderableList`](https://design.candescent.com/docs/components/reorderable-list/content.md). Outside a list row it renders nothing and logs a development warning. Make it the first or last direct child of `ListItem`, not a child of `ListItem.LeadingSlot` (that slot is `aria-hidden` by default) or `ListItem.TrailingSlot`.
+
+On a pressable row (`onPress`, or `asChild`), the row renders the handle beside its pressable element instead of inside it, so tapping or clicking the handle never presses the row and screen readers reach both controls. Under `asChild`, pass the handle and the interactive element as siblings: `<ListItem asChild><ListItem.DragHandle /><Link>…</Link></ListItem>`. A handle nested deeper in a pressable row logs a development warning.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### ListItem.Content
+
+Flex column for the text stack (`ListItem.Title`, `ListItem.Description`, and `ListItem.Meta`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Renders the consumer's child element in place of the default `View` host. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### ListItem.Title
+
+Primary label. Truncates to one line by default (`numberOfLines={1}`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Renders the consumer's child element in place of the default `Text` host. |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### ListItem.Description
+
+Secondary text below the title. Wraps freely by default.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Renders the consumer's child element in place of the default `Text` host. |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### ListItem.Meta
+
+Tertiary metadata line (timestamp, source). Truncates to one line by default (`numberOfLines={1}`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Renders the consumer's child element in place of the default `Text` host. |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### ListItem.TrailingSlot
+
+Optional trailing content (amount, chip, chevron, switch, or action buttons). Renders children in a horizontal row with gap.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Renders the consumer's child element in place of the default `View` host. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### ListItem.SectionHeader
+
+Group heading row with an optional accent top-border divider and an optional `subtle` neutral background. String or number children are auto-styled. Supports a `trailing` adornment (e.g. a count Chip).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children` | `ReactNode` | — | Primary section label. String or number children are styled as an uppercase label. |
+| `asChild?` | `boolean` | — | Renders the consumer's child element in place of the default `View` host. |
+| `trailing?` | `ReactNode` | — | Optional right-aligned adornment (e.g. section Chip). |
+| `variant?` | `'ghost' \| 'subtle' \| 'gradient'` | `'ghost'` | Background treatment. `ghost` has no fill and a bottom border; `subtle` adds a neutral fill (matching `subtle` on Avatar, Chip, and IconButton) and drops the bottom border. `gradient` fades from the primary surface into a brand tint, left to right, and keeps the bottom border. Label typography is the same for all three. |
+| `showDivider?` | `boolean` | `true` | Accent top border above the header. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute      | Values                | Description                      |
+| -------------- | --------------------- | -------------------------------- |
+| `data-slot`    | `list-section-header` | Section header root              |
+| `data-divider` | `true` \| `false`     | Whether the top divider is shown |
+
+## Anatomy
+
+| `data-slot`             | Element               |
+| ----------------------- | --------------------- |
+| `list-item`             | Root row              |
+| `list-item-drag-handle` | Drag handle           |
+| `list-item-leading`     | Leading adornment     |
+| `list-item-content`     | Text stack            |
+| `list-item-title`       | Primary label         |
+| `list-item-description` | Secondary text        |
+| `list-item-meta`        | Tertiary metadata     |
+| `list-item-trailing`    | Trailing content      |
+| `list-section-header`   | Section group heading |
+
+## Accessibility
+
+| Attribute                    | Behavior                                                                                                                                                                          |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Role**                     | No implicit ARIA role. Add `role="listitem"` when inside a `role="list"` container.                                                                                               |
+| **Keyboard**                 | Pressable rows are Tab-focusable. Activate with Enter or Space. Focus ring via `focus-visible` on web.                                                                            |
+| **Screen reader**            | Provide an explicit `accessibilityLabel` on pressable rows when needed. Nested title and description text are read individually.                                                  |
+| **`ListItem.LeadingSlot`**   | `aria-hidden` by default — override for meaningful leading content.                                                                                                               |
+| **`ListItem.DragHandle`**    | Button role with default label `Reorder`. Provide a per-row `accessibilityLabel`. On iOS and Android it carries the list's move accessibility actions and a hint that names them. |
+| **`ListItem.SectionHeader`** | Uses `accessibilityRole="header"` for VoiceOver section navigation.                                                                                                               |
+| **Disabled**                 | Sets `accessibilityState={{ disabled: true }}` on pressable roots. Non-pressable disabled rows receive `data-disabled` styling only.                                              |