@delacour/react-native-ui 0.1.0-alpha.20260925064741 → 0.1.0-alpha.20260925065508

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925064741",
+	"version": "0.1.0-alpha.20260925065508",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -48,6 +48,7 @@
 		"./field": "./src/components/field/index.ts",
 		"./icon": "./src/components/icon/index.ts",
 		"./input": "./src/components/input/index.ts",
+		"./item": "./src/components/item/index.ts",
 		"./kpi": "./src/components/kpi/index.ts",
 		"./label": "./src/components/label/index.ts",
 		"./list-group": "./src/components/list-group/index.ts",
@@ -97,7 +98,7 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-charts": "0.1.0-alpha.20260925064741",
+		"@delacour/react-native-charts": "0.1.0-alpha.20260925065508",
 		"@gorhom/bottom-sheet": "^5.2.8",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",

package/src/components/item/AGENTS.md

@@ -0,0 +1,92 @@
+# Item
+
+A row of media, text and actions, for lists and settings. Compound root plus
+`Item.Media`, `Item.Content`, `Item.Title`, `Item.Description`, `Item.Actions`,
+`Item.Header` and `Item.Footer`, and two layout parts, `Item.Group` and
+`Item.Separator`.
+
+`import { Item } from "@delacour/react-native-ui/item";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/item` |
+| `item.tsx` | Root + the `Object.assign` compound surface, and the bare-text wrap it owns |
+| `item-media.tsx` | `Item.Media` |
+| `item-content.tsx` | `Item.Content` |
+| `item-title.tsx` | `Item.Title` |
+| `item-description.tsx` | `Item.Description` |
+| `item-actions.tsx` | `Item.Actions` |
+| `item-header.tsx` | `Item.Header` |
+| `item-footer.tsx` | `Item.Footer` |
+| `item-group.tsx` | `Item.Group` |
+| `item-separator.tsx` | `Item.Separator` |
+| `item.context.tsx` | `ItemProvider`, `useItem()`, `useItemContext()`, `useItemPart()` |
+| `item.types.ts` | Prop types shared by two or more parts |
+| `item.variants.ts` | Pure `tv()` slots and the four resolvers, no RN imports |
+| `item.variants.test.ts` | |
+
+## Design
+
+- **Axes**: `variant` — `default`, `outline`, `muted`; `size` — `sm`, `md`,
+  `lg`; `orientation` — `horizontal`, `vertical`. States: `isDisabled`,
+  `isSelected`, and `busy` inherited from `Pressable`. `Item.Media` has its own
+  `variant` — `default`, `icon`, `image`.
+- **It drops into a `ListGroup` as a row, and that is the point of it.** An item
+  reads the group's context through the `list-group.context` leaf (rule 3 —
+  never `../list-group`) and changes three things when it finds one:
+  - **The surface becomes `grouped`.** `resolveItemSurface` ignores the variant:
+    the group draws the border, fill and corner, and a row repeating any of them
+    would draw a card inside a card. `surface` rather than `variant` is the
+    `tv()` axis for that reason.
+  - **Size defaults to the group's.** `resolveItemSize` — own, else group, else
+    `md`. The two components share the `sm`/`md`/`lg` scale on purpose.
+  - **Press feedback defaults to `fade`**, not `scale` — a full-bleed row that
+    scales reads as the whole card flexing. `resolveItemFeedback`.
+- **Row metrics are `ListGroup`'s, number for number.** The group insets each
+  divider by its own row padding, so an item padded differently would sit with
+  its text and its divider out of line. The tests assert the item's `min-h`,
+  `gap`, `px` and `py` against `listGroupVariants().item()` at every size, and
+  the bare media icon against the group's `prefixIcon` — change one without the
+  other and `bun test` fails by name.
+- **Pressable only with a handler.** `resolveItemRender` returns one of two:
+  `pressable` (a handler — a `Pressable`, role `button`, children merged into
+  one accessible element; disabled, it keeps the role, reports `disabled` and
+  dims through `opacity-50`, which `Pressable` composes with its press
+  animation) or `static` (no handler — a plain `Animated.View` with no role, so
+  a static row never announces itself as a button). The plain branch is
+  `Animated.View` rather than `View` so the `ref` type is one type.
+- **A pressable item must not hold another control.** iOS merges an accessible
+  element's children into it, so a `Button` in the actions of a pressable item
+  is unreachable by VoiceOver. Either leave the item static and let the actions
+  be the controls, or make the row the control: a switch row takes
+  `accessibilityRole="switch"` and `accessibilityState={{ checked }}` on the
+  item, toggles from its `onPress`, and renders the `Switch` inside for show.
+- **`isSelected` lays `bg-accent` over any surface**, the muted fill included —
+  declared after `surface` in the `tv()` so tailwind-merge drops the losing
+  `bg-*`. It also sets `accessibilityState.selected`. What marks the choice (a
+  check, a radio) is composed into `Item.Actions` by the caller.
+- **Icons are composed, never passed as props.** `Item.Media` and
+  `Item.Actions` each wrap their subtree in an `IconDefaultsProvider`. Media
+  gets the foreground token at the size its variant calls for — a bare icon
+  matches a `ListGroup` prefix, an `icon` tile's glyph sits two steps smaller
+  inside it. Actions gets `muted-foreground` a step lower still, so a chevron
+  reads as a hint. A `Button` in the actions publishes its own defaults and is
+  unaffected.
+- **`Header` and `Footer` work on both orientations.** The horizontal root is
+  `flex-wrap` and the strips are `w-full`, so a strip takes a line of its own
+  above or below media, text and actions without the item having to become a
+  column.
+- **`Content` only flexes along a row.** Vertical, it is `self-stretch`: a
+  `flex-1` column in an auto-height parent collapses to zero in Yoga.
+- **`Item.Group` is spaced, not divided.** It is for standalone items — outlined
+  cards, a carousel — announced with `accessibilityRole="list"`. Rows sharing
+  one card with dividers belong in a `ListGroup`, which already does both.
+  `Item.Separator` is a `Separator` under the item's name, for the occasional
+  hand-placed rule in a group.
+- **String children** are wrapped in a `Content` around a `Title`, consecutive
+  strings collapsing into one — the same rule, and the same reason, as
+  [`ListGroup`](../list-group/AGENTS.md).
+- **Text colour goes on the text.** No slot but `title` and `description` holds
+  a `text-*` colour; the tests assert the root never does.

package/src/components/item/index.ts

@@ -0,0 +1,25 @@
+export { Item, type ItemProps } from "./item";
+export { type ItemContextValue, ItemProvider, useItem, useItemContext } from "./item.context";
+export type { ItemSlotProps, ItemTextProps } from "./item.types";
+export {
+	ITEM_ACTIONS_ICON_TOKEN,
+	ITEM_MEDIA_ICON_TOKEN,
+	ITEM_MEDIA_VARIANTS,
+	ITEM_ORIENTATIONS,
+	ITEM_SIZES,
+	ITEM_VARIANTS,
+	type ItemMediaVariant,
+	type ItemOrientation,
+	type ItemRender,
+	type ItemSize,
+	type ItemSurface,
+	type ItemVariant,
+	type ItemVariantProps,
+	itemVariants,
+	resolveItemFeedback,
+	resolveItemRender,
+	resolveItemSize,
+	resolveItemSurface,
+} from "./item.variants";
+export type { ItemGroupProps } from "./item-group";
+export type { ItemMediaProps } from "./item-media";

package/src/components/item/item-actions.tsx

@@ -0,0 +1,28 @@
+import { type ReactElement, useMemo } from "react";
+import { View } from "react-native";
+import { IconDefaultsProvider } from "../icon";
+import { useItemPart } from "./item.context";
+import type { ItemSlotProps } from "./item.types";
+import { ITEM_ACTIONS_ICON_TOKEN, itemVariants } from "./item.variants";
+
+/**
+ * The trailing slot — buttons, a chevron, a switch, a value.
+ *
+ * A bare icon here inherits a step below the media's size and the muted token,
+ * so a chevron reads as a hint that the row leads somewhere rather than
+ * competing with the row's own subject. A `Button` inside sets its own icon
+ * defaults and is unaffected.
+ */
+export function ItemActions({ className, children, ...props }: ItemSlotProps): ReactElement {
+	const { size } = useItemPart("Item.Actions");
+	const slots = itemVariants({ size });
+	const iconClassName = slots.actionsIcon();
+	const iconDefaults = useMemo(() => ({ className: iconClassName, color: ITEM_ACTIONS_ICON_TOKEN }), [iconClassName]);
+
+	return (
+		<View className={slots.actions({ className })} {...props}>
+			<IconDefaultsProvider value={iconDefaults}>{children}</IconDefaultsProvider>
+		</View>
+	);
+}
+ItemActions.displayName = "DelacourUI.Item.Actions";

package/src/components/item/item-content.tsx

@@ -0,0 +1,15 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useItemPart } from "./item.context";
+import type { ItemSlotProps } from "./item.types";
+import { itemVariants } from "./item.variants";
+
+/**
+ * The text column. Along a row it takes whatever width the media and actions
+ * leave, so the actions stay pinned to the trailing edge.
+ */
+export function ItemContent({ className, ...props }: ItemSlotProps): ReactElement {
+	const { orientation } = useItemPart("Item.Content");
+	return <View className={itemVariants({ orientation }).content({ className })} {...props} />;
+}
+ItemContent.displayName = "DelacourUI.Item.Content";

package/src/components/item/item-description.tsx

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useItemPart } from "./item.context";
+import type { ItemTextProps } from "./item.types";
+import { itemVariants } from "./item.variants";
+
+/** The item's secondary line, a step down in scale and on the muted token. */
+export function ItemDescription({ className, ...props }: ItemTextProps): ReactElement {
+	const { size } = useItemPart("Item.Description");
+	return <Text className={itemVariants({ size }).description({ className })} {...props} />;
+}
+ItemDescription.displayName = "DelacourUI.Item.Description";

package/src/components/item/item-footer.tsx

@@ -0,0 +1,13 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import type { ItemSlotProps } from "./item.types";
+import { itemVariants } from "./item.variants";
+
+/**
+ * A full-width strip below the row's content — metadata, a progress bar, a row
+ * of buttons. Takes a line of its own on either orientation.
+ */
+export function ItemFooter({ className, ...props }: ItemSlotProps): ReactElement {
+	return <View className={itemVariants().footer({ className })} {...props} />;
+}
+ItemFooter.displayName = "DelacourUI.Item.Footer";

package/src/components/item/item-group.tsx

@@ -0,0 +1,32 @@
+import type { ReactElement, ReactNode } from "react";
+import { View, type ViewProps } from "react-native";
+import { type ItemOrientation, itemVariants } from "./item.variants";
+
+export type ItemGroupProps = ViewProps & {
+	/**
+	 * `vertical` stacks the items down the screen. `horizontal` runs them across,
+	 * for a carousel — put it in a horizontal `ScrollView` and give each item
+	 * `orientation="vertical"` so every entry reads as a card.
+	 */
+	orientation?: ItemOrientation;
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * A stack of standalone items, spaced rather than divided, announced as a
+ * list.
+ *
+ * For rows sharing one card with dividers between them, put the items in a
+ * `ListGroup` instead — they take the group's surface and size from there.
+ */
+export function ItemGroup({ orientation = "vertical", className, ...props }: ItemGroupProps): ReactElement {
+	return (
+		<View
+			accessibilityRole="list"
+			className={itemVariants({ groupOrientation: orientation }).group({ className })}
+			{...props}
+		/>
+	);
+}
+ItemGroup.displayName = "DelacourUI.Item.Group";

package/src/components/item/item-header.tsx

@@ -0,0 +1,13 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import type { ItemSlotProps } from "./item.types";
+import { itemVariants } from "./item.variants";
+
+/**
+ * A full-width strip above the row's content — a cover image, a kicker, a
+ * timestamp. Takes a line of its own on either orientation.
+ */
+export function ItemHeader({ className, ...props }: ItemSlotProps): ReactElement {
+	return <View className={itemVariants().header({ className })} {...props} />;
+}
+ItemHeader.displayName = "DelacourUI.Item.Header";

package/src/components/item/item-media.tsx

@@ -0,0 +1,37 @@
+import { type ReactElement, useMemo } from "react";
+import { View } from "react-native";
+import { IconDefaultsProvider } from "../icon";
+import { useItemPart } from "./item.context";
+import type { ItemSlotProps } from "./item.types";
+import { ITEM_MEDIA_ICON_TOKEN, type ItemMediaVariant, itemVariants } from "./item.variants";
+
+export type ItemMediaProps = ItemSlotProps & {
+	/**
+	 * `default` draws nothing and sizes a bare icon to match a `ListGroup` row's.
+	 * `icon` sets the glyph on a filled tile. `image` is a fixed square that clips
+	 * its child to the corner — give the image `className="size-full"`.
+	 */
+	variant?: ItemMediaVariant;
+};
+
+/**
+ * The leading slot — a bare icon, an icon tile, a thumbnail, or an avatar
+ * passed straight through.
+ *
+ * Its subtree inherits an icon size read from the item's size and this slot's
+ * variant, and the foreground token, so a bare `<Icon icon={IconFile} />` comes
+ * out right with nothing said at the call site.
+ */
+export function ItemMedia({ variant = "default", className, children, ...props }: ItemMediaProps): ReactElement {
+	const { isSelected, size, surface } = useItemPart("Item.Media");
+	const slots = itemVariants({ isSelected, mediaVariant: variant, size, surface });
+	const iconClassName = slots.mediaIcon();
+	const iconDefaults = useMemo(() => ({ className: iconClassName, color: ITEM_MEDIA_ICON_TOKEN }), [iconClassName]);
+
+	return (
+		<View className={slots.media({ className })} {...props}>
+			<IconDefaultsProvider value={iconDefaults}>{children}</IconDefaultsProvider>
+		</View>
+	);
+}
+ItemMedia.displayName = "DelacourUI.Item.Media";

package/src/components/item/item-separator.tsx

@@ -0,0 +1,13 @@
+import type { ReactElement } from "react";
+import { Separator, type SeparatorProps } from "../separator";
+
+/**
+ * A hairline between items in an `Item.Group`. Match the group's axis — a
+ * horizontal group needs `orientation="vertical"`.
+ *
+ * A `ListGroup` inserts its own dividers, so this is for `Item.Group` only.
+ */
+export function ItemSeparator(props: SeparatorProps): ReactElement {
+	return <Separator {...props} />;
+}
+ItemSeparator.displayName = "DelacourUI.Item.Separator";

package/src/components/item/item-title.tsx

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useItemPart } from "./item.context";
+import type { ItemTextProps } from "./item.types";
+import { itemVariants } from "./item.variants";
+
+/**
+ * The item's primary line.
+ *
+ * Carries its own colour and type scale, read from the item's context: a React
+ * Native `View` does not cascade colour to a `Text` descendant.
+ */
+export function ItemTitle({ className, ...props }: ItemTextProps): ReactElement {
+	const { size } = useItemPart("Item.Title");
+	return <Text className={itemVariants({ size }).title({ className })} {...props} />;
+}
+ItemTitle.displayName = "DelacourUI.Item.Title";

package/src/components/item/item.context.tsx

@@ -0,0 +1,66 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { ItemOrientation, ItemSize, ItemSurface } from "./item.variants";
+
+export type ItemContextValue = {
+	/** Resolved size — the item's own, else its `ListGroup`'s, else `md`. */
+	size: ItemSize;
+	/** Whether the item's parts sit side by side or stack. */
+	orientation: ItemOrientation;
+	/** The surface actually drawn: `grouped` inside a `ListGroup`, else the variant. */
+	surface: ItemSurface;
+	/** Whether the item is disabled. */
+	isDisabled: boolean;
+	/** Whether the item is selected. */
+	isSelected: boolean;
+};
+
+const ItemContext = createContext<ItemContextValue | null>(null);
+
+/**
+ * Supplies the enclosing item's resolved size, orientation and surface to its
+ * parts.
+ *
+ * Lives in its own module, importing nothing but `item.variants`, so a part can
+ * read it without importing `./item` and closing a cycle through the root. See
+ * AGENTS.md rule 3.
+ */
+export function ItemProvider({ value, children }: { value: ItemContextValue; children: ReactNode }): ReactElement {
+	return <ItemContext value={value}>{children}</ItemContext>;
+}
+ItemProvider.displayName = "DelacourUI.Item.Provider";
+
+/** The enclosing item's context, or null outside an `<Item>`. */
+export function useItemContext(): ItemContextValue | null {
+	return use(ItemContext);
+}
+
+/**
+ * Reads the enclosing item's resolved size, orientation and surface.
+ *
+ * Lets a custom part style itself to match without props passed down through
+ * every slot. Throws outside an `<Item>` — use {@link useItemContext} where the
+ * enclosing item is optional.
+ */
+export function useItem(): ItemContextValue {
+	const context = useItemContext();
+	if (!context) {
+		throw new Error("useItem must be called inside an <Item>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing item's context, for a compound part that cannot work without
+ * one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`. A caller outside the
+ * library wants {@link useItem}, whose error message names the hook rather than
+ * a part.
+ */
+export function useItemPart(component: string): ItemContextValue {
+	const context = useItemContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside an <Item>.`);
+	}
+	return context;
+}

package/src/components/item/item.tsx

@@ -0,0 +1,218 @@
+import { Children, type ReactElement, type ReactNode, useMemo } from "react";
+import type { AccessibilityState } from "react-native";
+import Animated from "react-native-reanimated";
+import { useListGroupContext } from "../list-group/list-group.context";
+import { Pressable, type PressableProps } from "../pressable";
+import { type ItemContextValue, ItemProvider } from "./item.context";
+import {
+	type ItemOrientation,
+	type ItemSize,
+	type ItemVariant,
+	itemVariants,
+	resolveItemFeedback,
+	resolveItemRender,
+	resolveItemSize,
+	resolveItemSurface,
+} from "./item.variants";
+import { ItemActions } from "./item-actions";
+import { ItemContent } from "./item-content";
+import { ItemDescription } from "./item-description";
+import { ItemFooter } from "./item-footer";
+import { ItemGroup } from "./item-group";
+import { ItemHeader } from "./item-header";
+import { ItemMedia } from "./item-media";
+import { ItemSeparator } from "./item-separator";
+import { ItemTitle } from "./item-title";
+
+export type ItemProps = Omit<PressableProps, "children" | "disabled"> & {
+	/**
+	 * `default` draws no surface, `outline` a hairline border, `muted` a fill.
+	 * Ignored inside a `ListGroup`, which draws the surface itself.
+	 */
+	variant?: ItemVariant;
+	/**
+	 * Row density. `Item.Media`, `Item.Title` and `Item.Description` follow it.
+	 * Inside a `ListGroup` it defaults to the group's size.
+	 */
+	size?: ItemSize;
+	/** `horizontal` is the list row; `vertical` stacks the parts into a card. */
+	orientation?: ItemOrientation;
+	isDisabled?: boolean;
+	/** Lays the accent fill over the surface and announces the item as selected. */
+	isSelected?: boolean;
+	children?: ReactNode;
+};
+
+function ItemRoot({
+	variant = "default",
+	size,
+	orientation = "horizontal",
+	isDisabled = false,
+	isSelected = false,
+	feedback,
+	haptic,
+	pressedScale,
+	pressedOpacity,
+	busy,
+	asChild,
+	onPress,
+	onLongPress,
+	accessibilityState,
+	className,
+	children,
+	...props
+}: ItemProps): ReactElement {
+	const group = useListGroupContext();
+	const isInGroup = group !== null;
+	const resolvedSize = resolveItemSize(size, group?.size);
+	const surface = resolveItemSurface(variant, isInGroup);
+
+	const context = useMemo<ItemContextValue>(
+		() => ({ isDisabled, isSelected, orientation, size: resolvedSize, surface }),
+		[isDisabled, isSelected, orientation, resolvedSize, surface]
+	);
+	const content = useMemo(() => wrapTextChildren(children), [children]);
+	const rootClassName = itemVariants({ isDisabled, isSelected, orientation, size: resolvedSize, surface }).root({
+		className,
+	});
+
+	const render = resolveItemRender({ isDisabled, onLongPress, onPress });
+
+	if (render === "pressable") {
+		return (
+			<ItemProvider value={context}>
+				<Pressable
+					accessibilityState={{ ...accessibilityState, selected: isSelected }}
+					asChild={asChild}
+					busy={busy}
+					className={rootClassName}
+					disabled={isDisabled}
+					feedback={resolveItemFeedback(feedback, isInGroup)}
+					haptic={haptic}
+					onLongPress={onLongPress}
+					onPress={onPress}
+					pressedOpacity={pressedOpacity}
+					pressedScale={pressedScale}
+					{...props}
+				>
+					{content}
+				</Pressable>
+			</ItemProvider>
+		);
+	}
+
+	const state: AccessibilityState = { ...accessibilityState, busy, disabled: isDisabled, selected: isSelected };
+
+	return (
+		<ItemProvider value={context}>
+			<Animated.View accessibilityState={state} className={rootClassName} {...props}>
+				{content}
+			</Animated.View>
+		</ItemProvider>
+	);
+}
+
+/**
+ * Wraps bare text children in a title inside a content column.
+ *
+ * Consecutive strings and numbers are collected into a single title rather
+ * than one each — `Row {index}` is one piece of text. React Native cannot
+ * render a string outside a `<Text>`, so without this `<Item>Wi-Fi</Item>`
+ * would crash.
+ *
+ * Lives with the root because the root is what wraps its own text; a part
+ * importing it from here would close a cycle. See AGENTS.md rule 3.
+ */
+function wrapTextChildren(children: ReactNode): ReactNode {
+	const items = Children.toArray(children);
+	const output: ReactNode[] = [];
+	let run: (string | number)[] = [];
+
+	const flushRun = () => {
+		if (run.length === 0) return;
+		output.push(
+			<ItemContent key={`content-${output.length}`}>
+				<ItemTitle>{run.join("")}</ItemTitle>
+			</ItemContent>
+		);
+		run = [];
+	};
+
+	for (const child of items) {
+		if (typeof child === "string" || typeof child === "number") {
+			run.push(child);
+			continue;
+		}
+		flushRun();
+		output.push(child);
+	}
+	flushRun();
+
+	return output;
+}
+
+/**
+ * A row of media, text and actions, for lists and settings.
+ *
+ * Give it an `onPress` and it renders as a `Pressable` announced as a button;
+ * leave it off and it is a plain view, so a static row never claims to be a
+ * control. `resolveItemRender` makes that call, and a disabled one too. `size` is set once here — the media, the title and the description
+ * read it from context.
+ *
+ * It drops straight into a `ListGroup` as a row: inside one it takes the
+ * group's size unless given its own, draws no surface of its own whatever its
+ * `variant`, fades rather than scales on press, and pads itself to the inset
+ * the group draws its dividers at.
+ *
+ * @example
+ * <Item variant="outline">
+ *   <Item.Media variant="icon">
+ *     <Icon icon={IconFileText} />
+ *   </Item.Media>
+ *   <Item.Content>
+ *     <Item.Title>Invoice.pdf</Item.Title>
+ *     <Item.Description>2.4 MB · Updated yesterday</Item.Description>
+ *   </Item.Content>
+ *   <Item.Actions>
+ *     <Button size="sm" variant="outline">
+ *       <Button.Label>Open</Button.Label>
+ *     </Button>
+ *   </Item.Actions>
+ * </Item>
+ *
+ * @example
+ * <ListGroup>
+ *   <Item onPress={openWifi}>
+ *     <Item.Media>
+ *       <Icon icon={IconWifi} />
+ *     </Item.Media>
+ *     <Item.Content>
+ *       <Item.Title>Wi-Fi</Item.Title>
+ *     </Item.Content>
+ *     <Item.Actions>
+ *       <Icon icon={IconChevronRight} />
+ *     </Item.Actions>
+ *   </Item>
+ * </ListGroup>
+ */
+export const Item = Object.assign(ItemRoot, {
+	/** A spaced stack of standalone items, announced as a list. */
+	Group: ItemGroup,
+	/** A hairline between items in an `Item.Group`. */
+	Separator: ItemSeparator,
+	/** The leading slot — a bare icon, an icon tile, or an image. Sized by the item. */
+	Media: ItemMedia,
+	/** The text column, taking the width the media and actions leave. */
+	Content: ItemContent,
+	/** The primary line. Carries its own colour — a `View` cannot cascade one to a `Text`. */
+	Title: ItemTitle,
+	/** The secondary line, a step down in scale and on the muted token. */
+	Description: ItemDescription,
+	/** The trailing slot — buttons, a chevron, a switch, a value. */
+	Actions: ItemActions,
+	/** A full-width strip above the row's content. */
+	Header: ItemHeader,
+	/** A full-width strip below the row's content. */
+	Footer: ItemFooter,
+	displayName: "DelacourUI.Item",
+});

package/src/components/item/item.types.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+import type { TextProps, ViewProps } from "react-native";
+
+/**
+ * The shape of an item's layout slots — `Content`, `Actions`, `Header` and
+ * `Footer` — and the base `Item.Media` extends. Shared by several parts, so it
+ * lives in a leaf rather than in one of them arbitrarily.
+ */
+export type ItemSlotProps = ViewProps & { className?: string; children?: ReactNode };
+
+/** The shape of an item's two text lines, `Title` and `Description`. */
+export type ItemTextProps = TextProps & { className?: string };

package/src/components/item/item.variants.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, test } from "bun:test";
+import { ICON_SIZE_TOKENS } from "../../styles/tokens";
+import { LIST_GROUP_SIZES, listGroupVariants } from "../list-group/list-group.variants";
+import {
+	ITEM_MEDIA_VARIANTS,
+	ITEM_ORIENTATIONS,
+	ITEM_SIZES,
+	ITEM_VARIANTS,
+	itemVariants,
+	resolveItemFeedback,
+	resolveItemRender,
+	resolveItemSize,
+	resolveItemSurface,
+} from "./item.variants";
+
+/** Pulls the horizontal padding step out of a class string — `px-4` yields 4. */
+function paddingStep(cls: string): string | undefined {
+	return cls.match(/\bpx-(\d+(?:\.\d+)?)\b/)?.[1];
+}
+
+/** Position of a class string's `size-icon-*` token on the shared icon scale. */
+function iconStep(cls: string): number {
+	const token = cls.match(/\bsize-(icon-[\w-]+)\b/)?.[1];
+	return ICON_SIZE_TOKENS.indexOf(token as (typeof ICON_SIZE_TOKENS)[number]);
+}
+
+describe("resolveItemSurface", () => {
+	test("a standalone item keeps its own variant", () => {
+		for (const variant of ITEM_VARIANTS) {
+			expect(resolveItemSurface(variant, false)).toBe(variant);
+		}
+	});
+
+	// The group owns the surface: a border or a fill on each row would draw a
+	// card inside a card.
+	test("an item inside a ListGroup is always grouped, whatever its variant", () => {
+		for (const variant of ITEM_VARIANTS) {
+			expect(resolveItemSurface(variant, true)).toBe("grouped");
+		}
+	});
+});
+
+describe("resolveItemSize", () => {
+	test("an explicit size wins over the group's", () => {
+		expect(resolveItemSize("lg", "sm")).toBe("lg");
+	});
+
+	test("inherits the enclosing group's size when unset", () => {
+		for (const size of LIST_GROUP_SIZES) {
+			expect(resolveItemSize(undefined, size)).toBe(size);
+		}
+	});
+
+	test("falls back to md outside a group", () => {
+		expect(resolveItemSize(undefined, undefined)).toBe("md");
+	});
+});
+
+describe("resolveItemFeedback", () => {
+	test("a caller's feedback always wins", () => {
+		expect(resolveItemFeedback("none", true)).toBe("none");
+		expect(resolveItemFeedback("scale-fade", false)).toBe("scale-fade");
+	});
+
+	// A full-bleed row that scales reads as the whole card flexing.
+	test("fades inside a group and scales standalone", () => {
+		expect(resolveItemFeedback(undefined, true)).toBe("fade");
+		expect(resolveItemFeedback(undefined, false)).toBe("scale");
+	});
+});
+
+describe("resolveItemRender", () => {
+	const noop = () => {};
+
+	test("is static without a press handler, disabled or not", () => {
+		expect(resolveItemRender({ isDisabled: false })).toBe("static");
+		expect(resolveItemRender({ isDisabled: true })).toBe("static");
+	});
+
+	test("is a pressable with a handler", () => {
+		expect(resolveItemRender({ isDisabled: false, onPress: noop })).toBe("pressable");
+		expect(resolveItemRender({ isDisabled: false, onLongPress: noop })).toBe("pressable");
+	});
+
+	// Pressable composes its resting opacity with the press animation, so a
+	// disabled Pressable dims through `opacity-50` like any other row.
+	test("stays a pressable when disabled", () => {
+		expect(resolveItemRender({ isDisabled: true, onPress: noop })).toBe("pressable");
+		expect(resolveItemRender({ isDisabled: true, onLongPress: noop })).toBe("pressable");
+	});
+});
+
+describe("itemVariants root slot", () => {
+	test("gives every surface a distinct class string", () => {
+		const surfaces = [...ITEM_VARIANTS, "grouped"] as const;
+		const seen = new Set(surfaces.map((surface) => itemVariants({ surface }).root()));
+		expect(seen.size).toBe(surfaces.length);
+	});
+
+	test("maps each surface", () => {
+		expect(itemVariants({ surface: "default" }).root()).toContain("bg-transparent");
+		expect(itemVariants({ surface: "outline" }).root()).toContain("border-border");
+		expect(itemVariants({ surface: "muted" }).root()).toContain("bg-muted");
+	});
+
+	test("a standalone surface is rounded; a grouped one is not", () => {
+		for (const surface of ITEM_VARIANTS) {
+			expect(itemVariants({ surface }).root()).toMatch(/\brounded-/);
+		}
+		expect(itemVariants({ surface: "grouped" }).root()).not.toMatch(/\brounded-/);
+		expect(itemVariants({ surface: "grouped" }).root()).not.toContain("border-border");
+	});
+
+	// Without it a short row leaves the press feedback ending mid-card.
+	test("a grouped row spans the group", () => {
+		expect(itemVariants({ surface: "grouped" }).root()).toContain("w-full");
+	});
+
+	test("holds no text colour — a View cannot cascade one", () => {
+		for (const surface of [...ITEM_VARIANTS, "grouped"] as const) {
+			expect(itemVariants({ surface }).root()).not.toMatch(/\btext-/);
+		}
+	});
+
+	test("orientation picks the main axis", () => {
+		expect(itemVariants({ orientation: "horizontal" }).root()).toContain("flex-row");
+		expect(itemVariants({ orientation: "vertical" }).root()).toContain("flex-col");
+		expect(itemVariants({ orientation: "vertical" }).root()).not.toContain("flex-row");
+	});
+
+	test("disabled dims the row", () => {
+		expect(itemVariants({ isDisabled: true }).root()).toContain("opacity-50");
+		expect(itemVariants({ isDisabled: false }).root()).not.toContain("opacity-50");
+	});
+
+	test("selected lays the accent over every surface, the muted fill included", () => {
+		for (const surface of [...ITEM_VARIANTS, "grouped"] as const) {
+			const cls = itemVariants({ isSelected: true, surface }).root();
+			expect(cls).toContain("bg-accent");
+			expect(cls).not.toContain("bg-muted");
+			expect(cls).not.toContain("bg-transparent");
+		}
+	});
+});
+
+describe("itemVariants sizes", () => {
+	// This is what makes an Item drop into a ListGroup: the group insets its
+	// dividers by its own row padding, so the item's padding has to match it.
+	test("row padding matches ListGroup's divider inset at every size", () => {
+		for (const size of ITEM_SIZES) {
+			const itemPadding = paddingStep(itemVariants({ size }).root());
+			const dividerInset = listGroupVariants({ size })
+				.divider()
+				.match(/\bmx-(\d+(?:\.\d+)?)\b/)?.[1];
+			expect(itemPadding).toBeDefined();
+			expect(itemPadding).toBe(dividerInset);
+		}
+	});
+
+	test("row metrics match a ListGroup row at every size", () => {
+		for (const size of ITEM_SIZES) {
+			const item = itemVariants({ size }).root();
+			for (const cls of listGroupVariants({ size }).item().split(" ")) {
+				if (/^(min-h|gap|px|py)-/.test(cls)) expect(item).toContain(cls);
+			}
+		}
+	});
+
+	test("title and description step up with size", () => {
+		expect(itemVariants({ size: "sm" }).title()).toContain("text-sm");
+		expect(itemVariants({ size: "md" }).title()).toContain("text-base");
+		expect(itemVariants({ size: "lg" }).title()).toContain("text-lg");
+		expect(itemVariants({ size: "sm" }).description()).toContain("text-xs");
+		expect(itemVariants({ size: "md" }).description()).toContain("text-sm");
+		expect(itemVariants({ size: "lg" }).description()).toContain("text-base");
+	});
+
+	test("text carries its own colour tokens", () => {
+		expect(itemVariants().title()).toContain("text-foreground");
+		expect(itemVariants().description()).toContain("text-muted-foreground");
+	});
+
+	test("every media icon names an ascending step on the shared icon scale", () => {
+		for (const mediaVariant of ITEM_MEDIA_VARIANTS) {
+			if (mediaVariant === "image") continue;
+			const steps = ITEM_SIZES.map((size) => iconStep(itemVariants({ mediaVariant, size }).mediaIcon()));
+			for (const step of steps) expect(step).toBeGreaterThanOrEqual(0);
+			expect([...steps].sort((a, b) => a - b)).toEqual(steps);
+			expect(new Set(steps).size).toBe(steps.length);
+		}
+	});
+
+	test("a bare media icon matches ListGroup's prefix icon", () => {
+		for (const size of ITEM_SIZES) {
+			expect(itemVariants({ mediaVariant: "default", size }).mediaIcon()).toBe(
+				listGroupVariants({ size }).prefixIcon()
+			);
+		}
+	});
+});
+
+describe("itemVariants media slot", () => {
+	test("the icon tile has a fill and a corner", () => {
+		const cls = itemVariants({ mediaVariant: "icon" }).media();
+		expect(cls).toContain("bg-muted");
+		expect(cls).toMatch(/\brounded-/);
+	});
+
+	test("an image clips its child to the corner", () => {
+		expect(itemVariants({ mediaVariant: "image" }).media()).toContain("overflow-hidden");
+	});
+
+	test("the icon tile and image are fixed squares that grow with size", () => {
+		for (const mediaVariant of ["icon", "image"] as const) {
+			const edges = ITEM_SIZES.map((size) => {
+				const edge = itemVariants({ mediaVariant, size })
+					.media()
+					.match(/\bsize-(\d+)\b/)?.[1];
+				return Number(edge);
+			});
+			for (const edge of edges) expect(edge).toBeGreaterThan(0);
+			expect([...edges].sort((a, b) => a - b)).toEqual(edges);
+		}
+	});
+
+	test("a tile stays visible on the muted and the selected surface", () => {
+		for (const mediaVariant of ["icon", "image"] as const) {
+			for (const cls of [
+				itemVariants({ mediaVariant, surface: "muted" }).media(),
+				itemVariants({ isSelected: true, mediaVariant }).media(),
+			]) {
+				expect(cls).toContain("bg-background");
+				expect(cls).not.toContain("bg-muted");
+			}
+		}
+	});
+
+	test("a bare media slot draws nothing of its own", () => {
+		const cls = itemVariants({ mediaVariant: "default" }).media();
+		expect(cls).not.toMatch(/\bbg-/);
+		expect(cls).not.toMatch(/\bsize-\d/);
+	});
+});
+
+describe("itemVariants orientation", () => {
+	// A `flex-1` column in an auto-height parent collapses to nothing in Yoga.
+	test("content only flexes along a row", () => {
+		expect(itemVariants({ orientation: "horizontal" }).content()).toContain("flex-1");
+		expect(itemVariants({ orientation: "vertical" }).content()).not.toContain("flex-1");
+	});
+
+	test("header and footer are full-width strips on both axes", () => {
+		for (const orientation of ITEM_ORIENTATIONS) {
+			expect(itemVariants({ orientation }).header()).toContain("w-full");
+			expect(itemVariants({ orientation }).footer()).toContain("w-full");
+		}
+	});
+
+	test("a group runs down by default and across when horizontal", () => {
+		expect(itemVariants({ groupOrientation: "vertical" }).group()).toContain("flex-col");
+		expect(itemVariants({ groupOrientation: "horizontal" }).group()).toContain("flex-row");
+	});
+});

package/src/components/item/item.variants.ts

@@ -0,0 +1,200 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { PressableFeedback } from "../pressable/pressable.variants";
+
+export const ITEM_VARIANTS = ["default", "outline", "muted"] as const;
+
+export const ITEM_SIZES = ["sm", "md", "lg"] as const;
+
+export const ITEM_ORIENTATIONS = ["horizontal", "vertical"] as const;
+
+export const ITEM_MEDIA_VARIANTS = ["default", "icon", "image"] as const;
+
+export type ItemVariant = (typeof ITEM_VARIANTS)[number];
+export type ItemSize = (typeof ITEM_SIZES)[number];
+export type ItemOrientation = (typeof ITEM_ORIENTATIONS)[number];
+export type ItemMediaVariant = (typeof ITEM_MEDIA_VARIANTS)[number];
+
+/**
+ * The surface a row actually draws.
+ *
+ * One of the three variants a caller picks, or `grouped` — the surface an item
+ * takes inside a `ListGroup`, where the group already draws the card and the
+ * row must draw nothing but itself.
+ */
+export type ItemSurface = ItemVariant | "grouped";
+
+/** Theme token an icon in `Item.Media` inherits. */
+export const ITEM_MEDIA_ICON_TOKEN = "foreground";
+
+/** Theme token an icon in `Item.Actions` inherits — a trailing hint, not the row's subject. */
+export const ITEM_ACTIONS_ICON_TOKEN = "muted-foreground";
+
+/**
+ * The surface an item draws, given its variant and whether a `ListGroup`
+ * encloses it.
+ *
+ * Inside a group the variant is ignored: the group owns the border, the fill
+ * and the corner, and a row repeating any of them would draw a card inside a
+ * card.
+ */
+export function resolveItemSurface(variant: ItemVariant, isInGroup: boolean): ItemSurface {
+	return isInGroup ? "grouped" : variant;
+}
+
+/**
+ * An item's size: its own when set, else the enclosing `ListGroup`'s, else
+ * `md`.
+ *
+ * The two share one scale on purpose, so an item dropped into a `sm` group
+ * comes out `sm` with nothing said at the call site.
+ */
+export function resolveItemSize(size: ItemSize | undefined, groupSize: ItemSize | undefined): ItemSize {
+	return size ?? groupSize ?? "md";
+}
+
+/**
+ * The press feedback for an item, when the caller has not named one.
+ *
+ * A full-bleed row inside a group fades, because a row that scales reads as
+ * the whole card flexing. A standalone item is its own card, so it scales the
+ * way a card does.
+ */
+export function resolveItemFeedback(feedback: PressableFeedback | undefined, isInGroup: boolean): PressableFeedback {
+	return feedback ?? (isInGroup ? "fade" : "scale");
+}
+
+/**
+ * What an item renders as.
+ *
+ * - `pressable` — it has a handler: a `Pressable`, announced as a button. A
+ *   disabled one keeps the role, reports `disabled`, and dims through
+ *   `opacity-50`, which `Pressable` composes with its press animation.
+ * - `static` — no handler: a plain view with no role. A static row announcing
+ *   itself as a button is a lie VoiceOver tells on every swipe.
+ */
+export type ItemRender = "pressable" | "static";
+
+export function resolveItemRender(options: {
+	onPress?: () => void;
+	onLongPress?: () => void;
+	isDisabled: boolean;
+}): ItemRender {
+	const hasHandler = options.onPress !== undefined || options.onLongPress !== undefined;
+	return hasHandler ? "pressable" : "static";
+}
+
+/**
+ * Styling for every part of an item.
+ *
+ * Row metrics are the same numbers a `ListGroup` row uses, per size — asserted
+ * as a pair in the tests — because a group insets its dividers by its own row
+ * padding. An item whose padding drifted from that would sit in a group with
+ * its text and its divider out of line.
+ *
+ * `surface` rather than `variant` is the axis here, because inside a group the
+ * variant a caller passed does not decide what is drawn. `resolveItemSurface`
+ * is where that decision lives.
+ *
+ * The horizontal root wraps, and `header` and `footer` are `w-full`: a strip
+ * then takes a line of its own above or below the media, text and actions, on
+ * either orientation, with no extra prop. `content` only flexes along a row — a
+ * `flex-1` column in an auto-height parent collapses to nothing in Yoga.
+ *
+ * No slot but the two text slots holds a `text-*` colour — a React Native
+ * `View` does not cascade one to a `Text`.
+ *
+ * Free of React Native imports so it stays unit-testable — `bun test` cannot
+ * parse React Native's Flow-typed source. See AGENTS.md.
+ */
+export const itemVariants = tv({
+	slots: {
+		root: "",
+		media: "items-center justify-center",
+		/** Edge length an `Icon` in the media slot inherits. */
+		mediaIcon: "",
+		content: "justify-center gap-0.5",
+		title: "font-medium text-foreground",
+		description: "text-muted-foreground",
+		actions: "flex-row items-center gap-2",
+		/** Edge length an `Icon` in the actions slot inherits. */
+		actionsIcon: "",
+		header: "w-full flex-row items-center justify-between gap-2",
+		footer: "w-full flex-row items-center justify-between gap-2",
+		group: "",
+	},
+	variants: {
+		surface: {
+			default: { root: "rounded-lg border border-transparent bg-transparent" },
+			outline: { root: "rounded-lg border border-border bg-transparent" },
+			muted: { root: "rounded-lg border border-transparent bg-muted" },
+			grouped: { root: "w-full bg-transparent" },
+		},
+		size: {
+			sm: {
+				root: "min-h-12 gap-2.5 px-3 py-2",
+				title: "text-sm",
+				description: "text-xs",
+				actionsIcon: "size-icon-xs",
+			},
+			md: {
+				root: "min-h-14 gap-3 px-4 py-3",
+				title: "text-base",
+				description: "text-sm",
+				actionsIcon: "size-icon-sm",
+			},
+			lg: {
+				root: "min-h-16 gap-3.5 px-5 py-4",
+				title: "text-lg",
+				description: "text-base",
+				actionsIcon: "size-icon-md",
+			},
+		},
+		orientation: {
+			horizontal: { root: "flex-row flex-wrap items-center", content: "flex-1" },
+			vertical: { root: "flex-col items-start", content: "self-stretch" },
+		},
+		mediaVariant: {
+			default: {},
+			icon: { media: "rounded-md bg-muted" },
+			image: { media: "overflow-hidden rounded-md bg-muted" },
+		},
+		groupOrientation: {
+			vertical: { group: "flex-col gap-2" },
+			horizontal: { group: "flex-row gap-3" },
+		},
+		// The empty `false` branches type the props as `boolean` rather than
+		// `true`. See the note in button.variants.ts.
+		isDisabled: { true: { root: "opacity-50" }, false: {} },
+		isSelected: { true: { root: "bg-accent" }, false: {} },
+	},
+	compoundVariants: [
+		// A card-shaped surface is `rounded-lg`, stepping down to `rounded-md` at
+		// `sm` — the same one step `ListGroup` and `Accordion` take.
+		{ size: "sm", surface: ["default", "outline", "muted"], class: { root: "rounded-md" } },
+		{ mediaVariant: "default", size: "sm", class: { mediaIcon: "size-icon-md" } },
+		{ mediaVariant: "default", size: "md", class: { mediaIcon: "size-icon-lg" } },
+		{ mediaVariant: "default", size: "lg", class: { mediaIcon: "size-icon-xl" } },
+		{ mediaVariant: "icon", size: "sm", class: { media: "size-8", mediaIcon: "size-icon-sm" } },
+		{ mediaVariant: "icon", size: "md", class: { media: "size-10", mediaIcon: "size-icon-md" } },
+		{ mediaVariant: "icon", size: "lg", class: { media: "size-12", mediaIcon: "size-icon-lg" } },
+		{ mediaVariant: "image", size: "sm", class: { media: "size-10" } },
+		{ mediaVariant: "image", size: "md", class: { media: "size-12" } },
+		{ mediaVariant: "image", size: "lg", class: { media: "size-14" } },
+		// A tile is `bg-muted`, so on a muted or selected surface it would vanish
+		// into the row.
+		{ mediaVariant: ["icon", "image"], surface: "muted", class: { media: "bg-background" } },
+		{ mediaVariant: ["icon", "image"], isSelected: true, class: { media: "bg-background" } },
+	],
+	defaultVariants: {
+		surface: "default",
+		size: "md",
+		orientation: "horizontal",
+		mediaVariant: "default",
+		groupOrientation: "vertical",
+		isDisabled: false,
+		isSelected: false,
+	},
+});
+
+export type ItemVariantProps = VariantProps<typeof itemVariants>;