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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925064429",
+	"version": "0.1.0-alpha.20260925065508",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -48,6 +48,8 @@
 		"./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",
 		"./meter": "./src/components/meter/index.ts",
@@ -96,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.20260925064429",
+		"@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/chart/AGENTS.md

@@ -87,6 +87,14 @@ knows nothing about tokens.
   tailwind-merge is what lets a caller's `className="aspect-video h-auto"`
   cleanly win when they want that instead.
 
+- **`frameClassName` resizes the frame, not the root.** The canvas fills the
+  frame, and the frame carries the size's height, so a `className` on the root
+  cannot shorten the plot — the frame would overflow it. `frameClassName` is
+  merged after the size's `h-chart-*`, and the tokens are registered with
+  tailwind-merge, so `h-16` cleanly replaces it. `Kpi.Sparkline` is the reason
+  it exists: a sparkline is a chart with no axes a third the height of the
+  smallest one.
+
 - **The tooltip is a React Native view even though it floats over the canvas.**
   It wants `popover`, `border`, the radius scale and the type scale, none of
   which exist in Skia, and it is the part a caller most wants to restyle —

package/src/components/chart/chart.tsx

@@ -72,6 +72,12 @@ export type ChartProps = {
 	/** How the scrub coexists with a scrolling parent. Defaults to holding. */
 	scrubConfig?: ScrubConfig;
 	className?: string;
+	/**
+	 * Merged onto the frame — the view the canvas fills — after the size's
+	 * height. `frameClassName="h-16"` is a sparkline; the three `size` heights
+	 * are for a chart someone reads with axes.
+	 */
+	frameClassName?: string;
 	/** Named on the frame, so a capture flow or a test can find the plot. */
 	testID?: string;
 	children?: ReactNode;
@@ -106,6 +112,7 @@ function ChartRoot({
 	orientation = "vertical",
 	scrubConfig,
 	className,
+	frameClassName,
 	testID,
 	children,
 }: ChartProps): ReactElement {
@@ -231,7 +238,7 @@ function ChartRoot({
 	return (
 		<ChartProvider value={value}>
 			<View className={slots.root({ className })}>
-				<View className={slots.frame()} onLayout={onLayout} testID={testID}>
+				<View className={slots.frame({ className: frameClassName })} onLayout={onLayout} testID={testID}>
 					<CartesianChart
 						curve={curve}
 						data={data}

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",
+});