@delacour/react-native-ui 0.1.0-alpha.3 → 0.1.0

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 };