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

package/src/components/swipe/swipe-panel.tsx

@@ -0,0 +1,55 @@
+import type { ReactElement } from "react";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { SwipeTileProvider, useSwipePart } from "./swipe.context";
+import { resolveOutermostIndex, type SwipeSide, type SwipeTileProps, swipeVariants } from "./swipe.variants";
+
+type SwipePanelLayerProps = {
+	side: SwipeSide;
+	/** The `Swipe.Action` elements lifted out of the side's marker. */
+	tiles: ReactElement<SwipeTileProps>[];
+	/** Hidden from assistive technology while the row is shut. */
+	isHidden: boolean;
+};
+
+const START_EDGE = { start: 0 } as const;
+const END_EDGE = { end: 0 } as const;
+
+/**
+ * The layer behind one edge of the row. Internal: the root renders one per side
+ * that has tiles.
+ *
+ * **Exactly as wide as the gap the row has left**, animated off the same offset
+ * the row moves on — never wider, so it cannot paint over a row that has no
+ * background of its own, and never narrower, so there is no hole. Its own
+ * colour is the outermost tile's, so the overshoot that tile grows into reads
+ * as the same action.
+ *
+ * Pinned by logical `start` / `end` rather than `left` / `right`, so the layout
+ * mirrors under right to left with no sign of its own; only the row's
+ * translation has to flip.
+ */
+export function SwipePanelLayer({ side, tiles, isHidden }: SwipePanelLayerProps): ReactElement {
+	const { offset } = useSwipePart("Swipe.Panel");
+	const outermost = tiles[resolveOutermostIndex(side, tiles.length)];
+	const slots = swipeVariants({ color: outermost?.props.color ?? "default", side });
+
+	const panelStyle = useAnimatedStyle(() => ({
+		width: Math.max(0, side === "start" ? offset.value : -offset.value),
+	}));
+
+	return (
+		<Animated.View
+			accessibilityElementsHidden={isHidden}
+			className={slots.panel()}
+			importantForAccessibility={isHidden ? "no-hide-descendants" : "auto"}
+			style={[side === "start" ? START_EDGE : END_EDGE, panelStyle]}
+		>
+			{tiles.map((tile, index) => (
+				<SwipeTileProvider key={tile.key ?? index} value={{ count: tiles.length, index, side }}>
+					{tile}
+				</SwipeTileProvider>
+			))}
+		</Animated.View>
+	);
+}
+SwipePanelLayer.displayName = "DelacourUI.Swipe.Panel";

package/src/components/swipe/swipe-start.tsx

@@ -0,0 +1,15 @@
+import type { ReactElement } from "react";
+import type { SwipePanelProps } from "./swipe.types";
+
+/**
+ * Marks the tiles behind the row's start edge — revealed by sliding the row
+ * toward `end`.
+ *
+ * A marker, never rendered: the root lifts its children out by element type and
+ * lays them out itself, because only the root knows how wide the gap is. On its
+ * own it renders nothing.
+ */
+export function SwipeStart(_props: SwipePanelProps): ReactElement | null {
+	return null;
+}
+SwipeStart.displayName = "DelacourUI.Swipe.Start";

package/src/components/swipe/swipe.context.tsx

@@ -0,0 +1,135 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { SwipeOpenSide, SwipeSide } from "./swipe.variants";
+
+export type SwipeContextValue = {
+	/** The side that is settled open, or null. Changes on a settle, never during a drag. */
+	openSide: SwipeOpenSide;
+	/** Slides the row aside to reveal `side`. A side with no panel stays shut. */
+	open: (side: SwipeSide) => void;
+	/** Slides the row back over its panels. */
+	close: () => void;
+	/** The row's logical offset — positive reveals `start`. Internal to the parts. */
+	offset: SharedValue<number>;
+	/** Whether the layout runs right to left, read once from `I18nManager`. */
+	isRTL: boolean;
+	/** Runs a tile's action, then closes the row unless it asks to stay open. */
+	runAction: (onPress: () => void, isKeptOpen: boolean) => void;
+};
+
+const SwipeContext = createContext<SwipeContextValue | null>(null);
+
+/**
+ * Supplies a row's state to its tiles.
+ *
+ * In a leaf of its own, importing nothing but types, so a part can read it
+ * without importing `./swipe` and closing a cycle (package AGENTS.md rule 3).
+ */
+export function SwipeProvider({ value, children }: { value: SwipeContextValue; children: ReactNode }): ReactElement {
+	return <SwipeContext value={value}>{children}</SwipeContext>;
+}
+SwipeProvider.displayName = "DelacourUI.Swipe.Provider";
+
+/** The enclosing row, or null outside a `<Swipe>`. */
+export function useSwipeContext(): SwipeContextValue | null {
+	return use(SwipeContext);
+}
+
+/**
+ * Reads the enclosing row: which side is open, and `open` / `close`.
+ *
+ * For a custom child of the row that has to close it — a button inside the row
+ * that acts and then tucks the actions away. Throws outside a `<Swipe>`.
+ */
+export function useSwipe(): SwipeContextValue {
+	const context = useSwipeContext();
+	if (!context) throw new Error("useSwipe must be called inside a <Swipe>.");
+	return context;
+}
+
+/**
+ * The enclosing row, for a part that cannot work without it.
+ *
+ * Internal: deliberately not re-exported from `index.ts`.
+ */
+export function useSwipePart(component: string): SwipeContextValue {
+	const context = useSwipeContext();
+	if (!context) throw new Error(`${component} must be rendered inside a <Swipe>.`);
+	return context;
+}
+
+export type SwipeTileContextValue = {
+	side: SwipeSide;
+	/** Source order within its panel. */
+	index: number;
+	/** How many tiles share the panel. */
+	count: number;
+};
+
+const SwipeTileContext = createContext<SwipeTileContextValue | null>(null);
+
+/** Where a tile sits in its panel. The root wraps every tile it lifts out in one. */
+export function SwipeTileProvider({
+	value,
+	children,
+}: {
+	value: SwipeTileContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <SwipeTileContext value={value}>{children}</SwipeTileContext>;
+}
+SwipeTileProvider.displayName = "DelacourUI.Swipe.TileProvider";
+
+/**
+ * A tile's place in its panel. Internal.
+ *
+ * Throws when a `Swipe.Action` was rendered anywhere but inside `Swipe.Start`
+ * or `Swipe.End` — the root lifts tiles out of those two markers only.
+ */
+export function useSwipeTilePart(component: string): SwipeTileContextValue {
+	const context = use(SwipeTileContext);
+	if (!context) throw new Error(`${component} must be written inside <Swipe.Start> or <Swipe.End>.`);
+	return context;
+}
+
+export type SwipeGroupContextValue = {
+	/** Adds a row's close to the group. Returns the matching unregister. */
+	register: (id: string, close: () => void) => () => void;
+	/** Tells the group `id` has opened, so an exclusive group closes the rest. */
+	notifyOpen: (id: string) => void;
+	/** Closes every row in the group. */
+	closeAll: () => void;
+};
+
+const SwipeGroupContext = createContext<SwipeGroupContextValue | null>(null);
+
+/** Supplies a group's registry to the rows beneath it, however deeply they are nested. */
+export function SwipeGroupProvider({
+	value,
+	children,
+}: {
+	value: SwipeGroupContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <SwipeGroupContext value={value}>{children}</SwipeGroupContext>;
+}
+SwipeGroupProvider.displayName = "DelacourUI.Swipe.Group.Provider";
+
+/** The enclosing group, or null for a row standing on its own. */
+export function useSwipeGroupContext(): SwipeGroupContextValue | null {
+	return use(SwipeGroupContext);
+}
+
+const NO_GROUP = { closeAll: () => {} } as const;
+
+/**
+ * Closes every row in the enclosing `Swipe.Group` — before a list scrolls away,
+ * or when a screen loses focus.
+ *
+ * Outside a group it returns a no-op rather than throwing, so a screen can call
+ * it whether or not its rows are grouped.
+ */
+export function useSwipeGroup(): { closeAll: () => void } {
+	const group = useSwipeGroupContext();
+	return group ? { closeAll: group.closeAll } : NO_GROUP;
+}

package/src/components/swipe/swipe.tsx

@@ -0,0 +1,393 @@
+import {
+	Children,
+	type ReactElement,
+	type ReactNode,
+	type Ref,
+	useCallback,
+	useEffect,
+	useId,
+	useImperativeHandle,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+import { type AccessibilityActionEvent, I18nManager, type LayoutChangeEvent, View, type ViewProps } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, {
+	useAnimatedStyle,
+	useReducedMotion,
+	useSharedValue,
+	withDelay,
+	withSpring,
+	withTiming,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { type HapticFeedback, playHaptic } from "../pressable/pressable";
+import { type SwipeContextValue, SwipeProvider, useSwipeGroupContext } from "./swipe.context";
+import {
+	partitionSwipeChildren,
+	resolveOutermostIndex,
+	SWIPE_FLY_OFF_DURATION,
+	SWIPE_FULL_FRACTION,
+	SWIPE_PROJECTION,
+	SWIPE_REDUCED_DURATION,
+	SWIPE_RUBBER_BAND,
+	SWIPE_SPRING,
+	SWIPE_TILE_WIDTH,
+	type SwipeOpenSide,
+	type SwipeSide,
+	swipeVariants,
+} from "./swipe.variants";
+import { SwipeAction } from "./swipe-action";
+import { SwipeEnd } from "./swipe-end";
+import { SwipeGroup } from "./swipe-group";
+import { SwipePanelLayer } from "./swipe-panel";
+import { SwipeStart } from "./swipe-start";
+
+export type SwipeHandle = {
+	/** Slides the row aside to reveal `side`. A side with no tiles stays shut. */
+	open: (side: SwipeSide) => void;
+	close: () => void;
+};
+
+export type SwipeProps = Omit<ViewProps, "children"> & {
+	/** `Swipe.Start`, `Swipe.End` and the row — anything that is not a panel. Order does not matter. */
+	children: ReactNode;
+	className?: string;
+	/** The moving row. */
+	contentClassName?: string;
+	/** A drag far past the panel fires the outermost action. Default `true`. */
+	isFullSwipe?: boolean;
+	/** Turns the gesture off. Tiles already open stay tappable. */
+	isDisabled?: boolean;
+	/** Ticks once as a drag crosses the full-swipe point. Off by default. */
+	haptic?: false | HapticFeedback;
+	/** The side that settled open, or `null` once the row is shut. */
+	onOpenChange?: (side: SwipeOpenSide) => void;
+	ref?: Ref<SwipeHandle>;
+};
+
+/**
+ * Read once: a direction change needs an app reload in React Native, so there
+ * is no live value to follow.
+ */
+const IS_RTL = I18nManager.isRTL;
+
+function SwipeRoot({
+	children,
+	className,
+	contentClassName,
+	isFullSwipe = true,
+	isDisabled = false,
+	haptic = false,
+	onOpenChange,
+	onLayout,
+	accessibilityLabel,
+	accessibilityHint,
+	ref,
+	...props
+}: SwipeProps): ReactElement {
+	const { start, end, row } = useMemo(() => partitionSwipeChildren(Children.toArray(children)), [children]);
+	const startWidth = start.length * SWIPE_TILE_WIDTH;
+	const endWidth = end.length * SWIPE_TILE_WIDTH;
+	const isReducedMotion = useReducedMotion();
+
+	// Logical points: positive reveals `start`. The row's translation flips it
+	// under right to left; nothing else has to.
+	const offset = useSharedValue(0);
+	const grabbed = useSharedValue(0);
+	const rowWidth = useSharedValue(0);
+	const rowOpacity = useSharedValue(1);
+	const isActive = useSharedValue(false);
+	const isPastFull = useSharedValue(false);
+
+	const [openSide, setOpenSide] = useState<SwipeOpenSide>(null);
+	const openSideRef = useRef<SwipeOpenSide>(null);
+	const group = useSwipeGroupContext();
+	const id = useId();
+
+	const onOpenChangeRef = useRef(onOpenChange);
+	onOpenChangeRef.current = onOpenChange;
+
+	const settle = useCallback(
+		(side: SwipeOpenSide) => {
+			if (openSideRef.current === side) return;
+			openSideRef.current = side;
+			setOpenSide(side);
+			onOpenChangeRef.current?.(side);
+			if (side !== null) group?.notifyOpen(id);
+		},
+		[group, id]
+	);
+
+	const animateTo = useCallback(
+		(target: number) => {
+			offset.value = isReducedMotion
+				? withTiming(target, { duration: SWIPE_REDUCED_DURATION })
+				: withSpring(target, SWIPE_SPRING);
+		},
+		[isReducedMotion, offset]
+	);
+
+	const close = useCallback(() => {
+		animateTo(0);
+		settle(null);
+	}, [animateTo, settle]);
+
+	const open = useCallback(
+		(side: SwipeSide) => {
+			const width = side === "start" ? startWidth : endWidth;
+			if (width <= 0) return;
+			animateTo(side === "start" ? width : -width);
+			settle(side);
+		},
+		[animateTo, endWidth, settle, startWidth]
+	);
+
+	useImperativeHandle(ref, () => ({ close, open }), [close, open]);
+
+	// A group closes the others through this, so a row already shut is left
+	// alone — a drag under way on it is not the group's to cancel.
+	const closeFromGroup = useCallback(() => {
+		if (openSideRef.current !== null) close();
+	}, [close]);
+
+	useEffect(() => group?.register(id, closeFromGroup), [closeFromGroup, group, id]);
+
+	const runAction = useCallback(
+		(onPress: () => void, isKeptOpen: boolean) => {
+			onPress();
+			if (!isKeptOpen) close();
+		},
+		[close]
+	);
+
+	const tilesRef = useRef({ end, start });
+	tilesRef.current = { end, start };
+
+	// Runs once the fly-off has carried the row away. The way back is delayed a
+	// beat so an action that removes the row unmounts it before it slides in.
+	const completeFullSwipe = useCallback(
+		(side: SwipeSide) => {
+			const tiles = tilesRef.current[side];
+			const outermost = tiles[resolveOutermostIndex(side, tiles.length)];
+			outermost?.props.onPress?.();
+
+			openSideRef.current = null;
+			setOpenSide(null);
+			onOpenChangeRef.current?.(null);
+
+			if (isReducedMotion) {
+				offset.value = 0;
+				rowOpacity.value = withDelay(SWIPE_REDUCED_DURATION, withTiming(1, { duration: SWIPE_REDUCED_DURATION }));
+			} else {
+				offset.value = withDelay(SWIPE_FLY_OFF_DURATION, withSpring(0, SWIPE_SPRING));
+			}
+		},
+		[isReducedMotion, offset, rowOpacity]
+	);
+
+	const pan = useMemo(
+		() =>
+			Gesture.Pan()
+				.enabled(!isDisabled)
+				.activeOffsetX([-10, 10])
+				.failOffsetY([-8, 8])
+				.onStart(() => {
+					"worklet";
+					isActive.value = true;
+					grabbed.value = offset.value;
+					isPastFull.value = false;
+				})
+				.onUpdate((event) => {
+					"worklet";
+					const raw = grabbed.value + (IS_RTL ? -event.translationX : event.translationX);
+					const isUnbacked = (raw > 0 && startWidth <= 0) || (raw < 0 && endWidth <= 0);
+					const next = isUnbacked ? raw * SWIPE_RUBBER_BAND : raw;
+					offset.value = next;
+
+					if (!isFullSwipe || haptic === false || rowWidth.value <= 0) return;
+					const width = next > 0 ? startWidth : endWidth;
+					const isPast = width > 0 && Math.abs(next) > width + SWIPE_FULL_FRACTION * rowWidth.value;
+					if (isPast === isPastFull.value) return;
+					isPastFull.value = isPast;
+					if (isPast) playHaptic(haptic);
+				})
+				.onFinalize((event) => {
+					"worklet";
+					if (!isActive.value) return;
+					isActive.value = false;
+
+					// `resolveSwipeRelease`, restated: a worklet body stays self-contained.
+					const current = offset.value;
+					const velocity = IS_RTL ? -event.velocityX : event.velocityX;
+					const projected = current + velocity * SWIPE_PROJECTION;
+					const isCrossing = current !== 0 && Math.sign(projected) !== Math.sign(current);
+					const side: SwipeSide = projected > 0 ? "start" : "end";
+					const width = side === "start" ? startWidth : endWidth;
+					const fullAt = width + SWIPE_FULL_FRACTION * rowWidth.value;
+					const isClosing = projected === 0 || isCrossing || width <= 0;
+					const isFull =
+						!isClosing &&
+						isFullSwipe &&
+						rowWidth.value > 0 &&
+						Math.abs(current) > fullAt &&
+						Math.abs(projected) > fullAt;
+					const isOpening = !isClosing && !isFull && Math.abs(projected) > width / 2;
+					const direction = side === "start" ? 1 : -1;
+
+					if (isFull) {
+						if (isReducedMotion) {
+							rowOpacity.value = withTiming(0, { duration: SWIPE_REDUCED_DURATION }, (finished) => {
+								if (finished) scheduleOnRN(completeFullSwipe, side);
+							});
+						} else {
+							offset.value = withTiming(
+								direction * rowWidth.value,
+								{ duration: SWIPE_FLY_OFF_DURATION },
+								(finished) => {
+									if (finished) scheduleOnRN(completeFullSwipe, side);
+								}
+							);
+						}
+						return;
+					}
+
+					const target = isOpening ? direction * width : 0;
+					offset.value = isReducedMotion
+						? withTiming(target, { duration: SWIPE_REDUCED_DURATION })
+						: withSpring(target, { ...SWIPE_SPRING, velocity });
+					scheduleOnRN(settle, isOpening ? side : null);
+				}),
+		[
+			completeFullSwipe,
+			endWidth,
+			grabbed,
+			haptic,
+			isActive,
+			isDisabled,
+			isFullSwipe,
+			isPastFull,
+			isReducedMotion,
+			offset,
+			rowOpacity,
+			rowWidth,
+			settle,
+			startWidth,
+		]
+	);
+
+	const shieldTap = useMemo(
+		() =>
+			Gesture.Tap().onEnd(() => {
+				"worklet";
+				scheduleOnRN(close);
+			}),
+		[close]
+	);
+
+	const rowStyle = useAnimatedStyle(() => ({
+		opacity: rowOpacity.value,
+		transform: [{ translateX: IS_RTL ? -offset.value : offset.value }],
+	}));
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			rowWidth.value = event.nativeEvent.layout.width;
+			onLayout?.(event);
+		},
+		[onLayout, rowWidth]
+	);
+
+	const actions = useMemo(() => [...start, ...end].map((tile) => tile.props), [end, start]);
+	const accessibilityActions = useMemo(
+		() =>
+			actions.flatMap((action) => (action.label === undefined ? [] : [{ label: action.label, name: action.label }])),
+		[actions]
+	);
+	const handleAccessibilityAction = useCallback(
+		(event: AccessibilityActionEvent) => {
+			const action = actions.find((entry) => entry.label === event.nativeEvent.actionName);
+			action?.onPress?.();
+		},
+		[actions]
+	);
+
+	const context = useMemo<SwipeContextValue>(
+		() => ({ close, isRTL: IS_RTL, offset, open, openSide, runAction }),
+		[close, offset, open, openSide, runAction]
+	);
+
+	const slots = swipeVariants();
+	const isShut = openSide === null;
+
+	return (
+		<SwipeProvider value={context}>
+			<View className={slots.root({ className })} onLayout={handleLayout} {...props}>
+				{start.length > 0 ? <SwipePanelLayer isHidden={isShut} side="start" tiles={start} /> : null}
+				{end.length > 0 ? <SwipePanelLayer isHidden={isShut} side="end" tiles={end} /> : null}
+				<GestureDetector gesture={pan}>
+					<Animated.View
+						accessibilityActions={accessibilityActions}
+						accessibilityHint={accessibilityHint}
+						accessibilityLabel={accessibilityLabel}
+						accessible
+						className={slots.row({ className: contentClassName })}
+						onAccessibilityAction={handleAccessibilityAction}
+						style={rowStyle}
+					>
+						{row}
+						{isShut ? null : (
+							<GestureDetector gesture={shieldTap}>
+								<View accessible={false} className="absolute inset-0" />
+							</GestureDetector>
+						)}
+					</Animated.View>
+				</GestureDetector>
+			</View>
+		</SwipeProvider>
+	);
+}
+
+/**
+ * A row that slides aside to reveal actions behind it — delete, archive,
+ * snooze, mark done.
+ *
+ * The tiles sit **behind** the row rather than beside it, so nothing reflows
+ * when one opens, and only the row moves, on the UI thread. A drag that is
+ * clearly sideways claims the touch and one that commits vertically gives it
+ * up, so a list of rows scrolls normally. A release opens a side or closes the
+ * row by where it would come to rest; a drag far past the panel fires the
+ * outermost action (`isFullSwipe`, on by default).
+ *
+ * `Swipe.Start` and `Swipe.End` are markers: their `Swipe.Action`s are lifted
+ * out and laid out by the root. Everything else is the row. Every action is
+ * also published as an accessibility action on the row, since a swipe is
+ * invisible to a screen reader.
+ *
+ * Wrap rows in `Swipe.Group` to keep one open at a time; `useSwipeGroup()`
+ * closes them all. A ref exposes `open(side)` and `close()`.
+ *
+ * @example
+ * <Swipe haptic="selection">
+ *   <Swipe.Start>
+ *     <Swipe.Action color="success" icon={IconCheckmark2} label="Done" onPress={complete} />
+ *   </Swipe.Start>
+ *   <Swipe.End>
+ *     <Swipe.Action color="warning" icon={IconBell} label="Snooze" onPress={snooze} />
+ *     <Swipe.Action color="destructive" icon={IconTrashCan} label="Delete" onPress={remove} />
+ *   </Swipe.End>
+ *   <Item>…</Item>
+ * </Swipe>
+ */
+export const Swipe = Object.assign(SwipeRoot, {
+	/** Tiles behind the start edge. A marker: its children are lifted out. */
+	Start: SwipeStart,
+	/** Tiles behind the end edge — the edge text runs toward. A marker. */
+	End: SwipeEnd,
+	/** One tile: a glyph above a caption, on its colour. */
+	Action: SwipeAction,
+	/** Keeps one row open at a time, however deeply its rows are nested. */
+	Group: SwipeGroup,
+	displayName: "DelacourUI.Swipe",
+});

package/src/components/swipe/swipe.types.ts

@@ -0,0 +1,7 @@
+import type { ReactNode } from "react";
+
+/** `Swipe.Start` and `Swipe.End` — markers whose children are the panel's tiles. */
+export type SwipePanelProps = {
+	/** One or more `Swipe.Action`s, in visual order. */
+	children: ReactNode;
+};