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

package/src/components/selection-mode/AGENTS.md

@@ -0,0 +1,155 @@
+# SelectionMode
+
+Pick several things at once — messages to archive, people to share with,
+swatches to apply — then act on them from a bar. A compound root plus
+`SelectionMode.Item`, `.Indicator`, `.Header`, `.Bar`, `.Action` and `.Group`,
+and `useSelectionMode()`.
+
+`import { SelectionMode } from "@delacour/react-native-ui/selection-mode";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/selection-mode` |
+| `selection-mode.tsx` | Root — owns the mode and the selection — plus the `Object.assign` compound surface |
+| `selection-mode-item.tsx` | `SelectionMode.Item`: wraps a child, decides what a press does, slides the leading mark in |
+| `selection-mode-indicator.tsx` | `SelectionMode.Indicator`, the round mark, and the internal `ring` (`DelacourUI.SelectionMode.Item.Ring`) |
+| `selection-mode-header.tsx` | `SelectionMode.Header`: close, the count and select-all, while the mode is on |
+| `selection-mode-bar.tsx` | `SelectionMode.Bar`: the absolute action bar over the bottom edge |
+| `selection-mode-action.tsx` | `SelectionMode.Action`: an icon over a label, handed the selection |
+| `selection-mode-group.tsx` | `SelectionMode.Group`: a stacked card, a grid or a horizontal strip |
+| `selection-mode.context.tsx` | The selection context and the per-item context, with their hooks |
+| `selection-mode.types.ts` | `SelectionModeState` — what the root builds and the context carries |
+| `selection-mode.variants.ts` | The slotted `tv()`, the motion constants, the tokens and every pure resolver |
+| `selection-mode.variants.test.ts` | |
+
+## Design
+
+- **Axes**: `indicator` (`leading` default, `ring`, `none`) on an item;
+  `placement` (`edge` default, `floating`) on the bar; `isSelected` and
+  `isDestructive` drive the indicator's fill and an action's colour.
+- **Selection is a set of ids, never indices.** A `string[]` in the order things
+  were picked. An index changes meaning the moment a list is sorted, filtered or
+  paged; an id does not, so a selection survives a refetch.
+- **It is a mode, not a property of each row.** Off, the list is for reading and
+  each item runs its own `onPress`. A long press turns the mode on with that item
+  picked; then a press toggles and the row's own handler does not run.
+  `resolveItemPress` is the whole decision and is pure.
+- **A disabled item keeps its own press, even while the mode is on.** It never
+  toggles and never starts the mode, but a section header or a "load more" row
+  still has to work while someone is picking.
+- **Exit clears an uncontrolled selection and leaves a controlled one alone.**
+  The close button and `exit()` call `setActive(false)`; only when `selected` is
+  uncontrolled do they also clear. A caller that owns `selected` may want to keep
+  it — a draft that survives leaving the mode — and clearing behind its back
+  would fight it.
+- **Both pairs are controllable.** `isActive`/`defaultActive`/`onActiveChange`
+  and `selected`/`defaultSelected`/`onSelectedChange`, through
+  `useControllableState`. A change that changes nothing — a toggle refused at
+  the cap, a select-all with nothing left to add — notifies nobody
+  (`resolveIsSameSelection`), the rule `ToggleButton.Group` keeps.
+- **`max` caps toggling and select-all, and never takes a pick away.** An
+  unpicked item at the cap does not go on, but a picked one still comes off, so
+  the way out of a full selection is always open. Select-all fills up to the cap
+  keeping existing picks first, and never drops a controlled pick that is already
+  past it.
+- **Select-all flips to "Deselect all" at the cap, not only at the total.**
+  `resolveIsAllSelected` is true once every value is picked or once the cap is
+  reached below the total — past that point select-all would do nothing, and a
+  control that does nothing reads as broken.
+- **`values` is optional, and the header degrades without it.** With it the
+  label is `"{title} · n of m"` and select-all shows; without it the label is
+  `"n selected"` and select-all is dropped, because there is nothing to pick all
+  of.
+- **The indicator is round on purpose.** A square box is a form control being
+  filled in; a round one is a thing picked out of a set. `Checkbox` stays square.
+  22pt (`size-5.5` — the icon scale skips 22), `border-2 border-border`, picked
+  `bg-primary` with a `primary-foreground` check. It pops from 0.8 on a spring.
+- **The leading mark pushes the content rather than covering it.** A spacer
+  opens from 0 to 34pt (`SELECTION_MODE_INDICATOR_OFFSET`, the mark plus a 12pt
+  gap) and the mark is drawn *after* the content, absolutely positioned over the
+  gap, so a child with a fill of its own never paints over it. A picked leading
+  row also takes `bg-primary/5`.
+- **`ring` draws a 2pt primary ring a 2pt gap outside the item** (`-inset-1`)
+  with a small check badge at the top-end. Its corner is `rounded-xl` by default;
+  `ringClassName` reshapes it — `rounded-full` around a round swatch. That prop
+  is an addition: a ring that cannot match the item's own corner looks wrong on
+  anything round.
+- **`none` draws nothing.** The caller reads `useSelectionMode().isSelected` and
+  paints its own state, or places a `SelectionMode.Indicator` itself.
+- **The bar is absolute, over the list.** It never shrinks the list, so the list
+  must pad its own bottom (`pb-24`). It is hidden while nothing is picked unless
+  `isShownWhenEmpty`, and never shown with the mode off. `edge` pads its own
+  bottom with the safe-area inset (at least 8pt); `floating` lifts the whole
+  card by the inset instead, so the card keeps its own padding.
+- **An action is handed the selection as it stands at the press.** A handler
+  that closed over `selected` would see a stale list; `onPress(selected)` cannot.
+  `isExitOnPress` exits afterwards — a delete, whose picks no longer exist.
+- **The root fills the height it is offered** (`flex-1`). Give it one: inside a
+  `ScrollView` with no height the bar has no bottom to sit on. An `h-*` class on
+  the root itself is not enough — `flex-1` sets a zero basis, and in a parent
+  with no height of its own the root collapses to nothing. Size the parent, or
+  add `flex-none` to a root that should take its content's height (an always-on
+  picker with no bar).
+- **Haptics are off by default.** `haptic` plays on entering the mode and on each
+  toggle that changed something — called from JS through `playHaptic`, since
+  neither moment is a gesture callback.
+- **Every part but the root throws outside a `SelectionMode`**, by name.
+- **The header's two controls take their own `testID`s** — `closeTestID` and
+  `selectAllTestID` — the way `Alert` and `Chip` forward one to their close
+  control. A `testID` on the header lands on its row, and a test that has to
+  leave the mode cannot reach a button the component draws for itself.
+
+## Motion
+
+- Indicator: the check fades in 200ms and the mark pops on a spring. The leading
+  spacer opens on the same spring while the mark fades.
+- Header: fades in from 8pt above (`FadeInDown` with an 8pt initial value).
+- Bar: slides up and fades in (`FadeInUp`), fades out downward.
+- **Reduced motion is opacity-only, 150ms, and never disappears.** Every
+  transition sets `ReduceMotion.Never` on its 150ms fade, because under the
+  default policy a fade completes instantly — and the fade *is* the information
+  that the mode changed. The spacer snaps rather than sliding.
+
+## Accessibility
+
+- **While the mode is on, an item is a checkbox.** `accessibilityRole="checkbox"`,
+  `accessibilityState={{ checked, disabled }}`, hint "Double-tap to select".
+  `resolveItemAccessibility` is the decision and is pure.
+- **While off, an item keeps the semantics of what it wraps** — a `button` when
+  it has an `onPress`, no role otherwise — and offers a `longpress` action
+  labelled "Start selecting", so the mode can be entered without the gesture. A
+  disabled item offers nothing it cannot do.
+- **The count is announced.** The header label is a polite live region on
+  Android; iOS has none, so the header calls
+  `AccessibilityInfo.announceForAccessibility` when the label changes.
+- **A group's `label` is its `accessibilityLabel`**, and a grid or strip is a
+  `list`.
+
+## Group
+
+- **`resolveGroupLayout` decides the shape.** `isHorizontal` is a strip and wins
+  over `columns`; two or more columns is a grid (floored); otherwise a stack.
+- **A stack is a card** (`rounded-lg border border-border bg-card`) with a
+  `Separator` between rows unless `hasSeparators={false}`.
+- **A grid measures itself.** Each cell is `resolveGridItemWidth` — the measured
+  width less the gaps, split evenly — and nothing renders until the first layout,
+  so no cell flashes at the wrong width. `hasSeparators` does not apply.
+- **A strip pads its scroll content by 8pt** so a ring and its badge are not
+  clipped by the scroll view.
+
+## Out of scope
+
+- **`SelectionMode.Sheet`.** Importing `../bottom-sheet` would force the optional
+  sheet engine and `react-native-teleport` on every consumer of this component.
+  The `in-a-sheet` demo shows the composition instead: `SelectionMode` wraps the
+  `BottomSheet` (context reaches through the portal), the items go in the sheet's
+  scroll view, and the bar goes in `BottomSheet.Footer sticky` as
+  `className="relative border-t-0 bg-transparent"` with `isSafeAreaAware={false}`. A
+  first-class part is a follow-up, possibly on its own subpath.
+- **Drag to select a range.** A pan across rows would fight the list's own
+  scroll; not in v1.
+- **Replacing the screen's navbar.** The header renders where it is placed; a
+  screen that wants it in place of its navbar hides the navbar itself while
+  `isActive`.

package/src/components/selection-mode/index.ts

@@ -0,0 +1,43 @@
+export { SelectionMode, type SelectionModeProps } from "./selection-mode";
+export {
+	type SelectionModeContextValue,
+	type SelectionModeItemContextValue,
+	SelectionModeProvider,
+	useSelectionMode,
+	useSelectionModeContext,
+	useSelectionModeItemContext,
+} from "./selection-mode.context";
+export type { SelectionModeState } from "./selection-mode.types";
+export {
+	resolveBarVisible,
+	resolveGridItemWidth,
+	resolveGroupLayout,
+	resolveHeaderCount,
+	resolveIndicatorShown,
+	resolveIsAllSelected,
+	resolveIsSameSelection,
+	resolveItemAccessibility,
+	resolveItemPress,
+	resolveSelectAll,
+	resolveToggle,
+	SELECTION_BAR_PLACEMENTS,
+	SELECTION_INDICATORS,
+	SELECTION_MODE_ACTION_FOREGROUND_TOKEN,
+	SELECTION_MODE_CHECK_TOKEN,
+	SELECTION_MODE_INDICATOR_OFFSET,
+	SELECTION_MODE_MOTION,
+	SELECTION_MODE_START_ACTION,
+	type SelectionBarPlacement,
+	type SelectionGroupLayout,
+	type SelectionIndicator,
+	type SelectionItemAccessibility,
+	type SelectionItemPress,
+	type SelectionModeVariantProps,
+	selectionModeVariants,
+} from "./selection-mode.variants";
+export type { SelectionModeActionProps } from "./selection-mode-action";
+export type { SelectionModeBarProps } from "./selection-mode-bar";
+export type { SelectionModeGroupProps } from "./selection-mode-group";
+export type { SelectionModeHeaderProps } from "./selection-mode-header";
+export type { SelectionModeIndicatorProps } from "./selection-mode-indicator";
+export type { SelectionModeItemProps } from "./selection-mode-item";

package/src/components/selection-mode/selection-mode-action.tsx

@@ -0,0 +1,65 @@
+import { type ReactElement, type ReactNode, useCallback } from "react";
+import { Icon, type IconComponent } from "../icon";
+import { Pressable } from "../pressable";
+import { Text } from "../text";
+import { useSelectionModePart } from "./selection-mode.context";
+import { SELECTION_MODE_ACTION_FOREGROUND_TOKEN, selectionModeVariants } from "./selection-mode.variants";
+
+export type SelectionModeActionProps = {
+	/** The label, under the icon. */
+	children: ReactNode;
+	icon?: IconComponent;
+	/** Called with the selection as it stands at the press. */
+	onPress: (selected: string[]) => void;
+	/** Leave the mode once `onPress` has run. */
+	isExitOnPress?: boolean;
+	/** Draw the label and icon in the destructive colour. */
+	isDestructive?: boolean;
+	isDisabled?: boolean;
+	className?: string;
+	labelClassName?: string;
+};
+
+/**
+ * One action in the bar: an icon over a label, sharing the bar's width evenly
+ * with its siblings.
+ *
+ * `onPress` receives the current selection, so the handler never closes over a
+ * stale one. `isExitOnPress` leaves the mode afterwards — a delete or an archive,
+ * whose picks no longer exist to stay picked.
+ */
+export function SelectionModeAction({
+	children,
+	icon,
+	onPress,
+	isExitOnPress = false,
+	isDestructive = false,
+	isDisabled = false,
+	className,
+	labelClassName,
+}: SelectionModeActionProps): ReactElement {
+	const { selected, exit } = useSelectionModePart("SelectionMode.Action");
+	const slots = selectionModeVariants({ isDestructive, isDisabled });
+	const token = SELECTION_MODE_ACTION_FOREGROUND_TOKEN[isDestructive ? "destructive" : "default"];
+
+	const handlePress = useCallback(() => {
+		onPress([...selected]);
+		if (isExitOnPress) exit();
+	}, [exit, isExitOnPress, onPress, selected]);
+
+	return (
+		<Pressable
+			accessibilityLabel={typeof children === "string" ? children : undefined}
+			className={slots.action({ className })}
+			disabled={isDisabled}
+			feedback="fade"
+			onPress={handlePress}
+		>
+			{icon ? <Icon color={token} icon={icon} size="xl" /> : null}
+			<Text className={slots.actionLabel({ className: labelClassName })} numberOfLines={1}>
+				{children}
+			</Text>
+		</Pressable>
+	);
+}
+SelectionModeAction.displayName = "DelacourUI.SelectionMode.Action";

package/src/components/selection-mode/selection-mode-bar.tsx

@@ -0,0 +1,79 @@
+import type { ReactElement } from "react";
+import type { ViewProps } from "react-native";
+import Animated, {
+	FadeIn,
+	FadeInUp,
+	FadeOut,
+	FadeOutDown,
+	ReduceMotion,
+	useReducedMotion,
+} from "react-native-reanimated";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useSelectionModePart } from "./selection-mode.context";
+import {
+	resolveBarVisible,
+	SELECTION_MODE_MOTION,
+	type SelectionBarPlacement,
+	selectionModeVariants,
+} from "./selection-mode.variants";
+
+export type SelectionModeBarProps = ViewProps & {
+	/** `edge` spans the bottom of the page; `floating` is an inset card above it. Default `edge`. */
+	placement?: SelectionBarPlacement;
+	/** Keep the bar up while nothing is picked. Default `false`. */
+	isShownWhenEmpty?: boolean;
+	/** Clear the home indicator with the bottom safe-area inset. Default `true`. */
+	isSafeAreaAware?: boolean;
+	className?: string;
+};
+
+const ENTERING = FadeInUp.duration(SELECTION_MODE_MOTION.fadeMs);
+const EXITING = FadeOutDown.duration(SELECTION_MODE_MOTION.reducedFadeMs);
+const REDUCED_ENTERING = FadeIn.duration(SELECTION_MODE_MOTION.reducedFadeMs).reduceMotion(ReduceMotion.Never);
+const REDUCED_EXITING = FadeOut.duration(SELECTION_MODE_MOTION.reducedFadeMs).reduceMotion(ReduceMotion.Never);
+
+/** The breathing room under the actions when there is no inset to clear. */
+const BAR_MIN_BOTTOM = 8;
+
+/**
+ * The actions for what is picked, over the bottom edge of the root.
+ *
+ * Absolute, so it sits over the list rather than shrinking it — pad the bottom
+ * of the list so its last row can scroll clear. Hidden while nothing is picked
+ * unless `isShownWhenEmpty`, and never shown with the mode off. It slides up
+ * and fades in; under reduced motion it only fades.
+ *
+ * `edge` pads its own bottom with the safe-area inset. `floating` lifts the
+ * whole card by it instead, so the card keeps its own padding.
+ */
+export function SelectionModeBar({
+	placement = "edge",
+	isShownWhenEmpty = false,
+	isSafeAreaAware = true,
+	className,
+	style,
+	children,
+	...props
+}: SelectionModeBarProps): ReactElement | null {
+	const { isActive, count } = useSelectionModePart("SelectionMode.Bar");
+	const isReducedMotion = useReducedMotion();
+	const insets = useSafeAreaInsets();
+	const inset = isSafeAreaAware ? insets.bottom : 0;
+
+	if (!resolveBarVisible({ count, isActive, isShownWhenEmpty })) return null;
+
+	const placementStyle = placement === "edge" ? { paddingBottom: Math.max(inset, BAR_MIN_BOTTOM) } : { bottom: inset };
+
+	return (
+		<Animated.View
+			className={selectionModeVariants({ placement }).bar({ className })}
+			entering={isReducedMotion ? REDUCED_ENTERING : ENTERING}
+			exiting={isReducedMotion ? REDUCED_EXITING : EXITING}
+			style={[placementStyle, style]}
+			{...props}
+		>
+			{children}
+		</Animated.View>
+	);
+}
+SelectionModeBar.displayName = "DelacourUI.SelectionMode.Bar";

package/src/components/selection-mode/selection-mode-group.tsx

@@ -0,0 +1,123 @@
+import { Children, Fragment, type ReactElement, type ReactNode, useCallback, useState } from "react";
+import { type LayoutChangeEvent, ScrollView, View, type ViewProps } from "react-native";
+import { Separator } from "../separator";
+import { Text } from "../text";
+import { useSelectionModePart } from "./selection-mode.context";
+import { resolveGridItemWidth, resolveGroupLayout, selectionModeVariants } from "./selection-mode.variants";
+
+export type SelectionModeGroupProps = ViewProps & {
+	/** Lay the items out in a grid of this many columns. */
+	columns?: number;
+	/** A single scrolling row. Wins over `columns`. */
+	isHorizontal?: boolean;
+	/** Each item's width in a horizontal strip. Default 44. */
+	itemWidth?: number;
+	/** Space between items in a grid or a strip. Default 12. */
+	gap?: number;
+	/** A caption above the items, and the group's accessibility label. */
+	label?: string;
+	/** Hairlines between stacked items. Default `true` for a stack, `false` for a grid or a strip. */
+	hasSeparators?: boolean;
+	className?: string;
+	labelClassName?: string;
+	children?: ReactNode;
+};
+
+/**
+ * The room a ring and its badge need outside an item, so a strip's scroll view
+ * does not clip them.
+ */
+const STRIP_INSET = 8;
+
+/**
+ * Lays items out as a stacked card list, a grid or a horizontal strip.
+ *
+ * A stack is a card with hairlines between its rows. A grid splits the measured
+ * width evenly between `columns`, less the gaps. A strip scrolls sideways, each
+ * item `itemWidth` wide, with room around it for a `ring` to draw.
+ *
+ * A grid or a strip is announced as a list; `label` names it either way.
+ */
+export function SelectionModeGroup({
+	columns,
+	isHorizontal = false,
+	itemWidth = 44,
+	gap = 12,
+	label,
+	hasSeparators,
+	className,
+	labelClassName,
+	children,
+	...props
+}: SelectionModeGroupProps): ReactElement {
+	useSelectionModePart("SelectionMode.Group");
+	const layout = resolveGroupLayout({ columns, isHorizontal });
+	const slots = selectionModeVariants({ layout: layout.kind });
+	const items = Children.toArray(children);
+	const [width, setWidth] = useState(0);
+
+	const handleLayout = useCallback((event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width), []);
+
+	const renderBody = (): ReactElement => {
+		if (layout.kind === "strip") {
+			return (
+				<ScrollView
+					contentContainerStyle={{ gap, padding: STRIP_INSET }}
+					horizontal
+					showsHorizontalScrollIndicator={false}
+				>
+					{items.map((child, index) => (
+						<View key={keyOf(child, index)} style={{ width: itemWidth }}>
+							{child}
+						</View>
+					))}
+				</ScrollView>
+			);
+		}
+
+		if (layout.kind === "grid") {
+			const cellWidth = resolveGridItemWidth({ columns: layout.columns, containerWidth: width, gap });
+			return (
+				<View className={slots.group()} onLayout={handleLayout} style={{ gap }}>
+					{width > 0
+						? items.map((child, index) => (
+								<View key={keyOf(child, index)} style={{ width: cellWidth }}>
+									{child}
+								</View>
+							))
+						: null}
+				</View>
+			);
+		}
+
+		const isSeparated = hasSeparators ?? true;
+		return (
+			<View className={slots.group()}>
+				{items.map((child, index) => (
+					<Fragment key={keyOf(child, index)}>
+						{isSeparated && index > 0 ? <Separator /> : null}
+						{child}
+					</Fragment>
+				))}
+			</View>
+		);
+	};
+
+	return (
+		<View
+			accessibilityLabel={label}
+			accessibilityRole={layout.kind === "stack" ? undefined : "list"}
+			className={className}
+			{...props}
+		>
+			{label ? <Text className={slots.groupLabel({ className: labelClassName })}>{label}</Text> : null}
+			{renderBody()}
+		</View>
+	);
+}
+SelectionModeGroup.displayName = "DelacourUI.SelectionMode.Group";
+
+/** The key `Children.toArray` already gave a child, or its index for a bare value. */
+function keyOf(child: ReturnType<typeof Children.toArray>[number], index: number): string | number {
+	return typeof child === "object" && child !== null && "key" in child && child.key !== null ? child.key : index;
+}

package/src/components/selection-mode/selection-mode-header.tsx

@@ -0,0 +1,85 @@
+import { type ReactElement, useEffect } from "react";
+import { AccessibilityInfo, Platform, type ViewProps } from "react-native";
+import Animated, { FadeIn, FadeInDown, FadeOut, ReduceMotion, useReducedMotion } from "react-native-reanimated";
+import { IconCrossMedium } from "../../icons/central";
+import { Button } from "../button";
+import { Icon } from "../icon";
+import { Text } from "../text";
+import { useSelectionModePart } from "./selection-mode.context";
+import { resolveHeaderCount, SELECTION_MODE_MOTION, selectionModeVariants } from "./selection-mode.variants";
+
+export type SelectionModeHeaderProps = ViewProps & {
+	/** Leads the count when the root knows its `values`. Default `"Select"`. */
+	title?: string;
+	/** Drop the select-all control. It is also dropped when the root has no `values` to pick from. */
+	isSelectAllHidden?: boolean;
+	/** `testID` for the close control, so a test or automation can leave the mode. */
+	closeTestID?: string;
+	/** `testID` for the select-all control. */
+	selectAllTestID?: string;
+	className?: string;
+};
+
+const ENTERING = FadeInDown.duration(SELECTION_MODE_MOTION.fadeMs).withInitialValues({
+	opacity: 0,
+	transform: [{ translateY: -SELECTION_MODE_MOTION.headerTravel }],
+});
+const EXITING = FadeOut.duration(SELECTION_MODE_MOTION.reducedFadeMs);
+const REDUCED_ENTERING = FadeIn.duration(SELECTION_MODE_MOTION.reducedFadeMs).reduceMotion(ReduceMotion.Never);
+const REDUCED_EXITING = FadeOut.duration(SELECTION_MODE_MOTION.reducedFadeMs).reduceMotion(ReduceMotion.Never);
+
+/**
+ * Says the mode is on and offers the way out.
+ *
+ * Renders only while the mode is on: a close button that exits, the count —
+ * `"{title} · n of m"`, or `"n selected"` when the root has no `values` — and
+ * select-all, which turns into "Deselect all" once there is nothing left to add.
+ * It fades in from 8pt above; under reduced motion it only fades.
+ *
+ * The count is announced as it changes: a polite live region on Android, an
+ * announcement on iOS, which has no live regions.
+ */
+export function SelectionModeHeader({
+	title = "Select",
+	isSelectAllHidden = false,
+	closeTestID,
+	selectAllTestID,
+	className,
+	...props
+}: SelectionModeHeaderProps): ReactElement | null {
+	const { isActive, count, total, isAllSelected, exit, selectAll, clear } =
+		useSelectionModePart("SelectionMode.Header");
+	const isReducedMotion = useReducedMotion();
+	const label = resolveHeaderCount({ count, title, total });
+	const slots = selectionModeVariants();
+
+	useEffect(() => {
+		if (isActive && Platform.OS === "ios") AccessibilityInfo.announceForAccessibility(label);
+	}, [isActive, label]);
+
+	if (!isActive) return null;
+
+	const hasSelectAll = !isSelectAllHidden && total !== undefined && total > 0;
+
+	return (
+		<Animated.View
+			className={slots.header({ className })}
+			entering={isReducedMotion ? REDUCED_ENTERING : ENTERING}
+			exiting={isReducedMotion ? REDUCED_EXITING : EXITING}
+			{...props}
+		>
+			<Button accessibilityLabel="Stop selecting" onPress={exit} size="icon-md" testID={closeTestID} variant="ghost">
+				<Icon icon={IconCrossMedium} />
+			</Button>
+			<Text accessibilityLiveRegion="polite" className={slots.headerTitle()} numberOfLines={1}>
+				{label}
+			</Text>
+			{hasSelectAll ? (
+				<Button onPress={isAllSelected ? clear : selectAll} size="sm" testID={selectAllTestID} variant="ghost">
+					<Button.Label>{isAllSelected ? "Deselect all" : "Select all"}</Button.Label>
+				</Button>
+			) : null}
+		</Animated.View>
+	);
+}
+SelectionModeHeader.displayName = "DelacourUI.SelectionMode.Header";

package/src/components/selection-mode/selection-mode-indicator.tsx

@@ -0,0 +1,118 @@
+import { type ReactElement, useEffect } from "react";
+import type { ViewProps, ViewStyle } from "react-native";
+import Animated, {
+	ReduceMotion,
+	useAnimatedStyle,
+	useReducedMotion,
+	useSharedValue,
+	withSequence,
+	withSpring,
+	withTiming,
+} from "react-native-reanimated";
+import { IconCheckmark1Small } from "../../icons/central";
+import { Icon } from "../icon";
+import { useSelectionModeItemContext, useSelectionModePart } from "./selection-mode.context";
+import { SELECTION_MODE_CHECK_TOKEN, SELECTION_MODE_MOTION, selectionModeVariants } from "./selection-mode.variants";
+
+export type SelectionModeIndicatorProps = ViewProps & {
+	/** The id it reports on. Defaults to the enclosing `SelectionMode.Item`'s. */
+	value?: string;
+	className?: string;
+};
+
+/**
+ * Animates a picked state in: the check fades, and the whole mark pops from 0.8
+ * on a spring. Under reduced motion the pop is dropped and the fade is 150ms.
+ */
+function usePickedStyle(isSelected: boolean): ReturnType<typeof useAnimatedStyle<ViewStyle>> {
+	const isReducedMotion = useReducedMotion();
+	const picked = useSharedValue(isSelected ? 1 : 0);
+	const scale = useSharedValue(1);
+
+	useEffect(() => {
+		const target = isSelected ? 1 : 0;
+		if (isReducedMotion) {
+			picked.value = withTiming(target, {
+				duration: SELECTION_MODE_MOTION.reducedFadeMs,
+				reduceMotion: ReduceMotion.Never,
+			});
+			return;
+		}
+		picked.value = withTiming(target, { duration: SELECTION_MODE_MOTION.fadeMs });
+		if (isSelected)
+			scale.value = withSequence(withTiming(0.8, { duration: 0 }), withSpring(1, SELECTION_MODE_MOTION.spring));
+	}, [isReducedMotion, isSelected, picked, scale]);
+
+	return useAnimatedStyle(() => ({ opacity: picked.value, transform: [{ scale: scale.value }] }));
+}
+
+/**
+ * The round mark a `leading` item shows: an empty ring, or a filled circle with
+ * a check.
+ *
+ * Round on purpose. A square box is a form control being filled in; a round
+ * one is a thing picked out of a set. `Checkbox` stays square.
+ *
+ * Rendered by `SelectionMode.Item` itself. Render one by hand only for an item
+ * drawn with `indicator="none"` that wants the mark somewhere else in its
+ * layout — inside an item it reads that item's id, elsewhere it takes `value`.
+ */
+export function SelectionModeIndicator({ value, className, ...props }: SelectionModeIndicatorProps): ReactElement {
+	const selection = useSelectionModePart("SelectionMode.Indicator");
+	const item = useSelectionModeItemContext();
+	const id = value ?? item?.value;
+	if (id === undefined) {
+		throw new Error("SelectionMode.Indicator needs a `value`, or an enclosing <SelectionMode.Item>.");
+	}
+
+	const isSelected = selection.isSelected(id);
+	const slots = selectionModeVariants({ isSelected });
+	const checkStyle = usePickedStyle(isSelected);
+
+	return (
+		<Animated.View
+			accessibilityElementsHidden
+			className={slots.indicator({ className })}
+			importantForAccessibility="no-hide-descendants"
+			{...props}
+		>
+			<Animated.View style={checkStyle}>
+				<Icon className={slots.indicatorCheck()} color={SELECTION_MODE_CHECK_TOKEN} icon={IconCheckmark1Small} />
+			</Animated.View>
+		</Animated.View>
+	);
+}
+SelectionModeIndicator.displayName = "DelacourUI.SelectionMode.Indicator";
+
+/**
+ * The `ring` indicator: a primary ring a 2pt gap outside the item, and a small
+ * check badge at its top-end corner. Drawn only while the item is picked.
+ *
+ * Internal — `SelectionMode.Item` renders it. `className` reshapes the ring to
+ * the item's own corner: `rounded-full` around a round swatch.
+ */
+export function SelectionModeRing({
+	isSelected,
+	className,
+}: {
+	isSelected: boolean;
+	className?: string;
+}): ReactElement {
+	const slots = selectionModeVariants({ indicator: "ring", isSelected });
+	const pickedStyle = usePickedStyle(isSelected);
+
+	return (
+		<Animated.View
+			accessibilityElementsHidden
+			className={slots.ring({ className })}
+			importantForAccessibility="no-hide-descendants"
+			pointerEvents="none"
+			style={pickedStyle}
+		>
+			<Animated.View className={slots.ringBadge()}>
+				<Icon className={slots.indicatorCheck()} color={SELECTION_MODE_CHECK_TOKEN} icon={IconCheckmark1Small} />
+			</Animated.View>
+		</Animated.View>
+	);
+}
+SelectionModeRing.displayName = "DelacourUI.SelectionMode.Item.Ring";