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

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

@@ -0,0 +1,182 @@
+import { type ReactElement, type ReactNode, useCallback, useEffect, useMemo } from "react";
+import { type AccessibilityActionEvent, View, type ViewProps, type ViewStyle } from "react-native";
+import Animated, {
+	ReduceMotion,
+	useAnimatedStyle,
+	useReducedMotion,
+	useSharedValue,
+	withSpring,
+	withTiming,
+} from "react-native-reanimated";
+import { Pressable } from "../pressable";
+import {
+	type SelectionModeItemContextValue,
+	SelectionModeItemProvider,
+	useSelectionModePart,
+} from "./selection-mode.context";
+import {
+	resolveIndicatorShown,
+	resolveItemAccessibility,
+	resolveItemPress,
+	SELECTION_MODE_INDICATOR_OFFSET,
+	SELECTION_MODE_MOTION,
+	type SelectionIndicator,
+	selectionModeVariants,
+} from "./selection-mode.variants";
+import { SelectionModeIndicator, SelectionModeRing } from "./selection-mode-indicator";
+
+export type SelectionModeItemProps = Omit<ViewProps, "children"> & {
+	/** The item's id. Selection is a set of ids, never indices. */
+	value: string;
+	/** What it wraps — a row, an avatar, a swatch. */
+	children: ReactNode;
+	/** The item's own press, run while the mode is off — and always, for a disabled item. */
+	onPress?: () => void;
+	/** Cannot start the mode or be picked. Its own `onPress` still runs. */
+	isDisabled?: boolean;
+	/** How it shows it is picked. Default `leading`. */
+	indicator?: SelectionIndicator;
+	/** Show the indicator even while the mode is off — an always-on picker. */
+	isIndicatorAlwaysShown?: boolean;
+	className?: string;
+	/** Reshapes the `ring` to the item's own corner — `rounded-full` around a round swatch. */
+	ringClassName?: string;
+};
+
+/**
+ * Slides a `leading` indicator in: a spacer opens from 0 to 34pt and pushes the
+ * content over while the mark fades in. Under reduced motion the spacer snaps
+ * and only the fade plays, 150ms.
+ */
+function useLeadingStyles(isShown: boolean): {
+	spacerStyle: ReturnType<typeof useAnimatedStyle<ViewStyle>>;
+	markStyle: ReturnType<typeof useAnimatedStyle<ViewStyle>>;
+} {
+	const isReducedMotion = useReducedMotion();
+	const slide = useSharedValue(isShown ? 1 : 0);
+	const fade = useSharedValue(isShown ? 1 : 0);
+
+	useEffect(() => {
+		const target = isShown ? 1 : 0;
+		if (isReducedMotion) {
+			slide.value = target;
+			fade.value = withTiming(target, {
+				duration: SELECTION_MODE_MOTION.reducedFadeMs,
+				reduceMotion: ReduceMotion.Never,
+			});
+			return;
+		}
+		slide.value = withSpring(target, SELECTION_MODE_MOTION.spring);
+		fade.value = withTiming(target, { duration: SELECTION_MODE_MOTION.fadeMs });
+	}, [fade, isReducedMotion, isShown, slide]);
+
+	const offset = SELECTION_MODE_INDICATOR_OFFSET;
+	const spacerStyle = useAnimatedStyle(() => ({ width: slide.value * offset }));
+	const markStyle = useAnimatedStyle(() => ({ opacity: fade.value }));
+	return { markStyle, spacerStyle };
+}
+
+/**
+ * One pickable thing. Wraps whatever it holds rather than replacing it.
+ *
+ * Off, a press runs the item's own `onPress` and a long press turns the mode on
+ * with this item picked. On, a press toggles it and `onPress` does not run. A
+ * disabled item never toggles and never starts the mode, but keeps its own
+ * press — a section header, a "load more" row.
+ *
+ * While the mode is on it is announced as a checkbox; while off it keeps the
+ * semantics of what it wraps and offers "Start selecting" as an action.
+ */
+export function SelectionModeItem({
+	value,
+	children,
+	onPress,
+	isDisabled = false,
+	indicator = "leading",
+	isIndicatorAlwaysShown = false,
+	className,
+	ringClassName,
+	onAccessibilityAction,
+	...props
+}: SelectionModeItemProps): ReactElement {
+	const selection = useSelectionModePart("SelectionMode.Item");
+	const { isActive, toggle, enter } = selection;
+	const isSelected = selection.isSelected(value);
+	const isShown = resolveIndicatorShown({ indicator, isActive, isIndicatorAlwaysShown });
+
+	const press = resolveItemPress({ hasOnPress: onPress !== undefined, isActive, isDisabled });
+	const pressKind = press.kind;
+	const handlePress = useCallback(() => {
+		if (pressKind === "toggle") toggle(value);
+		else if (pressKind === "press") onPress?.();
+	}, [onPress, pressKind, toggle, value]);
+
+	const canEnter = !isActive && !isDisabled;
+	const handleLongPress = useCallback(() => enter(value), [enter, value]);
+
+	const accessibility = resolveItemAccessibility({ isActive, isDisabled, isSelected });
+	const handleAccessibilityAction = useCallback(
+		(event: AccessibilityActionEvent) => {
+			if (canEnter && event.nativeEvent.actionName === "longpress") enter(value);
+			onAccessibilityAction?.(event);
+		},
+		[canEnter, enter, onAccessibilityAction, value]
+	);
+	const accessibilityProps =
+		accessibility.kind === "checkbox"
+			? {
+					accessibilityHint: accessibility.accessibilityHint,
+					accessibilityRole: accessibility.accessibilityRole,
+					accessibilityState: accessibility.accessibilityState,
+				}
+			: {
+					accessibilityActions: accessibility.accessibilityActions,
+					accessibilityRole: onPress ? ("button" as const) : undefined,
+				};
+
+	const context = useMemo<SelectionModeItemContextValue>(
+		() => ({ indicator, isDisabled, isSelected, value }),
+		[indicator, isDisabled, isSelected, value]
+	);
+
+	const slots = selectionModeVariants({ indicator, isSelected: isSelected && isShown });
+	const { markStyle, spacerStyle } = useLeadingStyles(isShown);
+
+	// A leading item is a row: a spacer that opens to push the content over, the
+	// content, then the mark drawn on top of the gap the spacer made. The mark
+	// comes last so a child with a fill of its own never paints over it.
+	const content =
+		indicator === "leading" ? (
+			<>
+				<Animated.View style={spacerStyle} />
+				<View className="flex-1">{children}</View>
+				<Animated.View className={slots.indicatorSlot()} pointerEvents="none" style={markStyle}>
+					<SelectionModeIndicator />
+				</Animated.View>
+			</>
+		) : (
+			<>
+				{children}
+				{indicator === "ring" && isShown && isSelected ? (
+					<SelectionModeRing className={ringClassName} isSelected={isSelected} />
+				) : null}
+			</>
+		);
+
+	return (
+		<SelectionModeItemProvider value={context}>
+			<Pressable
+				className={slots.item({ className })}
+				feedback={indicator === "leading" ? "fade" : "scale"}
+				onAccessibilityAction={handleAccessibilityAction}
+				onLongPress={canEnter ? handleLongPress : undefined}
+				onPress={pressKind === "none" ? undefined : handlePress}
+				{...accessibilityProps}
+				{...props}
+			>
+				{content}
+			</Pressable>
+		</SelectionModeItemProvider>
+	);
+}
+SelectionModeItem.displayName = "DelacourUI.SelectionMode.Item";

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

@@ -0,0 +1,89 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SelectionModeState } from "./selection-mode.types";
+import type { SelectionIndicator } from "./selection-mode.variants";
+
+export type SelectionModeContextValue = SelectionModeState;
+
+const SelectionModeContext = createContext<SelectionModeContextValue | null>(null);
+
+/**
+ * Supplies a selection to every part beneath it.
+ *
+ * In a leaf of its own, importing nothing but types, so a part can read it
+ * without importing `./selection-mode` and closing a cycle (package AGENTS.md
+ * rule 3).
+ */
+export function SelectionModeProvider({
+	value,
+	children,
+}: {
+	value: SelectionModeContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <SelectionModeContext value={value}>{children}</SelectionModeContext>;
+}
+SelectionModeProvider.displayName = "DelacourUI.SelectionMode.Provider";
+
+/** The enclosing selection, or null outside a `<SelectionMode>`. */
+export function useSelectionModeContext(): SelectionModeContextValue | null {
+	return use(SelectionModeContext);
+}
+
+/**
+ * Reads the enclosing selection: whether the mode is on, what is picked, and
+ * the actions that move it.
+ *
+ * For a custom child — an item drawn with `indicator="none"` that paints its own
+ * picked state, a toolbar of its own. Throws outside a `<SelectionMode>` — use
+ * {@link useSelectionModeContext} where the selection is optional.
+ */
+export function useSelectionMode(): SelectionModeContextValue {
+	const context = useSelectionModeContext();
+	if (!context) {
+		throw new Error("useSelectionMode must be called inside a <SelectionMode>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing selection, for a compound part that cannot work without it.
+ *
+ * Internal: deliberately not re-exported from `index.ts`.
+ */
+export function useSelectionModePart(component: string): SelectionModeContextValue {
+	const context = useSelectionModeContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <SelectionMode>.`);
+	}
+	return context;
+}
+
+export type SelectionModeItemContextValue = {
+	/** The item's id. */
+	value: string;
+	/** Whether it is picked. */
+	isSelected: boolean;
+	/** Whether it can be picked at all. */
+	isDisabled: boolean;
+	/** How it shows it is picked. */
+	indicator: SelectionIndicator;
+};
+
+const SelectionModeItemContext = createContext<SelectionModeItemContextValue | null>(null);
+
+/** Supplies one item's id and state, so a `SelectionMode.Indicator` inside it needs no `value`. */
+export function SelectionModeItemProvider({
+	value,
+	children,
+}: {
+	value: SelectionModeItemContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <SelectionModeItemContext value={value}>{children}</SelectionModeItemContext>;
+}
+SelectionModeItemProvider.displayName = "DelacourUI.SelectionMode.Item.Provider";
+
+/** The enclosing item, or null outside a `<SelectionMode.Item>`. */
+export function useSelectionModeItemContext(): SelectionModeItemContextValue | null {
+	return use(SelectionModeItemContext);
+}

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

@@ -0,0 +1,207 @@
+import { type ReactElement, type ReactNode, useCallback, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { type HapticFeedback, playHaptic } from "../pressable/pressable";
+import { type SelectionModeContextValue, SelectionModeProvider } from "./selection-mode.context";
+import {
+	resolveIsAllSelected,
+	resolveIsSameSelection,
+	resolveSelectAll,
+	resolveToggle,
+	selectionModeVariants,
+} from "./selection-mode.variants";
+import { SelectionModeAction } from "./selection-mode-action";
+import { SelectionModeBar } from "./selection-mode-bar";
+import { SelectionModeGroup } from "./selection-mode-group";
+import { SelectionModeHeader } from "./selection-mode-header";
+import { SelectionModeIndicator } from "./selection-mode-indicator";
+import { SelectionModeItem } from "./selection-mode-item";
+
+export type SelectionModeProps = ViewProps & {
+	children: ReactNode;
+	className?: string;
+	/** Every pickable id, in list order — what select-all picks and "n of m" counts. */
+	values?: readonly string[];
+	/** Whether the mode is on. Controlled. */
+	isActive?: boolean;
+	/** Whether the mode starts on, while uncontrolled. */
+	defaultActive?: boolean;
+	onActiveChange?: (isActive: boolean) => void;
+	/** The picked ids, in the order they were picked. Controlled. */
+	selected?: readonly string[];
+	/** The ids picked to begin with, while uncontrolled. */
+	defaultSelected?: readonly string[];
+	/** Called with the whole new list. Never called for a change that changes nothing. */
+	onSelectedChange?: (selected: string[]) => void;
+	/** The most ids that can be picked. Select-all stops here too. */
+	max?: number;
+	/** Played on entering the mode and on every toggle. Off by default. */
+	haptic?: false | HapticFeedback;
+};
+
+function SelectionModeRoot({
+	children,
+	className,
+	values,
+	isActive,
+	defaultActive = false,
+	onActiveChange,
+	selected,
+	defaultSelected = EMPTY,
+	onSelectedChange,
+	max,
+	haptic = false,
+	...props
+}: SelectionModeProps): ReactElement {
+	const [active, setActive] = useControllableState<boolean>({
+		defaultValue: defaultActive,
+		onChange: onActiveChange,
+		value: isActive,
+	});
+	const [picked, setPicked] = useControllableState<readonly string[]>({
+		defaultValue: defaultSelected,
+		onChange: onSelectedChange as ((next: readonly string[]) => void) | undefined,
+		value: selected,
+	});
+	const isSelectedControlled = selected !== undefined;
+
+	const commit = useCallback(
+		(next: string[]): boolean => {
+			if (resolveIsSameSelection(next, picked)) return false;
+			setPicked(next);
+			return true;
+		},
+		[picked, setPicked]
+	);
+
+	const toggle = useCallback(
+		(value: string) => {
+			if (commit(resolveToggle({ max, selected: picked, value })) && haptic) playHaptic(haptic);
+		},
+		[commit, haptic, max, picked]
+	);
+
+	const enter = useCallback(
+		(value?: string) => {
+			if (!active) setActive(true);
+			const didPick =
+				value !== undefined && !picked.includes(value) && commit(resolveToggle({ max, selected: picked, value }));
+			if (haptic && (!active || didPick)) playHaptic(haptic);
+		},
+		[active, commit, haptic, max, picked, setActive]
+	);
+
+	const exit = useCallback(() => {
+		if (active) setActive(false);
+		if (!isSelectedControlled) commit([]);
+	}, [active, commit, isSelectedControlled, setActive]);
+
+	const selectAll = useCallback(() => {
+		commit(resolveSelectAll({ max, selected: picked, values: values ?? EMPTY }));
+	}, [commit, max, picked, values]);
+
+	const clear = useCallback(() => {
+		commit([]);
+	}, [commit]);
+
+	const isSelected = useCallback((value: string) => picked.includes(value), [picked]);
+
+	const context = useMemo<SelectionModeContextValue>(
+		() => ({
+			clear,
+			count: picked.length,
+			enter,
+			exit,
+			haptic,
+			isActive: active,
+			isAllSelected: resolveIsAllSelected({ max, selected: picked, values: values ?? EMPTY }),
+			isSelected,
+			max,
+			selectAll,
+			selected: [...picked],
+			toggle,
+			total: values?.length,
+		}),
+		[active, clear, enter, exit, haptic, isSelected, max, picked, selectAll, toggle, values]
+	);
+
+	return (
+		<SelectionModeProvider value={context}>
+			<View className={selectionModeVariants().root({ className })} {...props}>
+				{children}
+			</View>
+		</SelectionModeProvider>
+	);
+}
+
+/**
+ * A stable empty list, so an uncontrolled selection does not seed its state
+ * from a fresh array on every render.
+ */
+const EMPTY: readonly string[] = [];
+
+/**
+ * Pick several things at once, then act on them from a bar.
+ *
+ * A mode: off, the list is for reading and each item keeps its own press; a
+ * long press on an item turns the mode on with that item picked. On, a press
+ * toggles, `SelectionMode.Header` says so and offers the way out, and
+ * `SelectionMode.Bar` rises over the bottom edge with the actions.
+ *
+ * Selection is a set of ids — a `string[]` in the order things were picked,
+ * never indices — controlled with `selected` + `onSelectedChange` or held from
+ * `defaultSelected`. The mode is `isActive` + `onActiveChange`, or
+ * `defaultActive`. Exiting clears an uncontrolled selection; a controlled one is
+ * left to the caller. `values` lists every pickable id, which is what
+ * select-all and the "n of m" count need. `max` caps both toggling and
+ * select-all.
+ *
+ * The root fills the height it is offered (`flex-1`), so give it one. The bar is
+ * absolute, over the list, so pad the bottom of the list (`pb-24`) for the last
+ * row to scroll clear of it.
+ *
+ * @example
+ * <SelectionMode onSelectedChange={setSelected} selected={selected} values={ids}>
+ *   <SelectionMode.Header title="Choose" />
+ *   <FlatList
+ *     contentContainerClassName="pb-24"
+ *     data={messages}
+ *     renderItem={({ item }) => (
+ *       <SelectionMode.Item onPress={() => open(item)} value={item.id}>
+ *         <Item>…</Item>
+ *       </SelectionMode.Item>
+ *     )}
+ *   />
+ *   <SelectionMode.Bar>
+ *     <SelectionMode.Action icon={IconTrashCan} isDestructive isExitOnPress onPress={remove}>
+ *       Delete
+ *     </SelectionMode.Action>
+ *   </SelectionMode.Bar>
+ * </SelectionMode>
+ *
+ * @example
+ * <SelectionMode defaultActive values={swatches}>
+ *   <SelectionMode.Group columns={5}>
+ *     {swatches.map((swatch) => (
+ *       <SelectionMode.Item indicator="ring" key={swatch} ringClassName="rounded-full" value={swatch}>
+ *         <Swatch color={swatch} />
+ *       </SelectionMode.Item>
+ *     ))}
+ *   </SelectionMode.Group>
+ * </SelectionMode>
+ */
+export const SelectionMode = Object.assign(SelectionModeRoot, {
+	/** One pickable thing. Wraps whatever it holds. */
+	Item: SelectionModeItem,
+	/** The round picked mark, for an item that places its own. */
+	Indicator: SelectionModeIndicator,
+	/** Shown while the mode is on: close, the count and select-all. */
+	Header: SelectionModeHeader,
+	/** The actions, over the bottom edge, while something is picked. */
+	Bar: SelectionModeBar,
+	/** One action in the bar: an icon over a label. */
+	Action: SelectionModeAction,
+	/** Lays items out as a stacked card, a grid or a horizontal strip. */
+	Group: SelectionModeGroup,
+	displayName: "DelacourUI.SelectionMode",
+});

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

@@ -0,0 +1,36 @@
+import type { HapticFeedback } from "../pressable/pressable";
+
+/**
+ * Everything a selection exposes — what the root publishes and what
+ * `useSelectionMode()` returns.
+ *
+ * Shared by the root, which builds it, and the context leaf, which carries it.
+ */
+export type SelectionModeState = {
+	/** Whether the mode is on: a press toggles, the header and bar show. */
+	isActive: boolean;
+	/** The picked ids, in the order they were picked. */
+	selected: string[];
+	/** Whether `value` is picked. */
+	isSelected: (value: string) => boolean;
+	/** Picks or unpicks `value`, respecting `max`. */
+	toggle: (value: string) => void;
+	/** Picks every value up to `max`, keeping existing picks first. */
+	selectAll: () => void;
+	/** Unpicks everything, and stays in the mode. */
+	clear: () => void;
+	/** Turns the mode on, picking `value` when one is given. */
+	enter: (value?: string) => void;
+	/** Turns the mode off. Clears an uncontrolled selection; a controlled one is left to the caller. */
+	exit: () => void;
+	/** How many ids are picked. */
+	count: number;
+	/** How many ids are pickable, or `undefined` when the root was given no `values`. */
+	total: number | undefined;
+	/** The cap on picks, if any. */
+	max: number | undefined;
+	/** Whether select-all has nothing left to add — the control reads "Deselect all". */
+	isAllSelected: boolean;
+	/** Played on enter and on every toggle. */
+	haptic: false | HapticFeedback;
+};