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

package/src/components/toast/toast-item.tsx

@@ -0,0 +1,308 @@
+import { type ReactElement, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { AccessibilityInfo, type LayoutChangeEvent, Platform, View } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, {
+	Easing,
+	type SharedValue,
+	useAnimatedStyle,
+	useReducedMotion,
+	useSharedValue,
+	withDelay,
+	withSpring,
+	withTiming,
+} from "react-native-reanimated";
+import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";
+import { OVERLAY_MOTION } from "../overlay/overlay.variants";
+import { playHaptic } from "../pressable";
+import { Spinner } from "../spinner";
+import { Toast } from "./toast";
+import { ToastItemProvider } from "./toast.context";
+import type { ToastHandle, ToastItem, ToastPlacement, ToastStore } from "./toast.store";
+import {
+	createToastTimer,
+	pauseToastTimer,
+	startToastTimer,
+	type ToastTimer,
+	toastTimerRemaining,
+} from "./toast.timer";
+import {
+	resolveToastAnnouncement,
+	resolveToastDepthStyle,
+	resolveToastDrag,
+	resolveToastDuration,
+	resolveToastEnterDelay,
+	resolveToastHaptic,
+	resolveToastInterrupts,
+	resolveToastRelease,
+	resolveToastStackedHeight,
+	TOAST_ENTER_DISTANCE,
+	toastVariants,
+} from "./toast.variants";
+
+const ENTER_EASING = Easing.out(Easing.cubic);
+const EXIT_EASING = Easing.in(Easing.cubic);
+const SETTLE_SPRING = { damping: 20, stiffness: 260, mass: 0.6 } as const;
+const DEPTH_MS = 220;
+const SWIPE_OUT_MS = 180;
+
+export type ToastViewportItemProps = {
+	item: ToastItem;
+	store: ToastStore;
+	placement: ToastPlacement;
+	depth: number;
+	isExiting: boolean;
+	/** Points from the screen edge to the toast's edge — safe area plus offset. */
+	edgeOffset: number;
+	/** False while the app is backgrounded; the clock stops. */
+	isAppActive: boolean;
+	isScreenReaderEnabled: boolean;
+	/** The front toast's height in this stack — the front one writes it, the ones behind take it. */
+	frontHeight: SharedValue<number>;
+};
+
+/** The default card for a message toast. */
+function renderMessage(item: ToastItem & { kind: "message" }, handle: ToastHandle): ReactNode {
+	const { action } = item;
+	return (
+		<Toast onHide={handle.hide} status={item.status} testID={`toast-${item.id}`}>
+			<Toast.Indicator>{item.isLoading ? <Spinner /> : undefined}</Toast.Indicator>
+			<Toast.Content>
+				<Toast.Title>{item.title}</Toast.Title>
+				{item.description ? <Toast.Description>{item.description}</Toast.Description> : null}
+			</Toast.Content>
+			{action ? (
+				<Toast.Action onPress={() => action.onPress(handle)} testID={`toast-${item.id}-action`}>
+					{action.label}
+				</Toast.Action>
+			) : null}
+			{item.isLoading ? null : <Toast.Close testID={`toast-${item.id}-close`} />}
+		</Toast>
+	);
+}
+
+/**
+ * One toast in the viewport: its motion, its clock and its swipe.
+ *
+ * - **Motion.** It enters from its edge — 16pt and a fade, after its stagger
+ *   delay — and recedes with `depth`: further toward the edge, smaller and
+ *   fainter, animated as depth changes. Hidden, it fades back toward its edge
+ *   and only then leaves the store. Under reduce motion the entrance is a fade.
+ * - **Clock.** The auto-hide clock restarts on every update (a promise toast's
+ *   success gets a full duration) and pauses while the app is in the
+ *   background and while a finger is on the toast.
+ * - **Swipe.** A pan follows the finger sideways and toward the edge and
+ *   rubber-bands toward the centre; `resolveToastRelease` decides on release.
+ *   It activates only past 10pt, so a tap still reaches the action and the ✕.
+ * - **Announcement.** Each revision is announced and plays its haptic once.
+ */
+export function ToastViewportItem({
+	item,
+	store,
+	placement,
+	depth,
+	isExiting,
+	edgeOffset,
+	isAppActive,
+	isScreenReaderEnabled,
+	frontHeight,
+}: ToastViewportItemProps): ReactElement {
+	const { id, createdAt, batchIndex, revision, onHide } = item;
+	const isReduced = useReducedMotion();
+	const presence = useSharedValue(0);
+	const depthValue = useSharedValue(depth);
+	const dragX = useSharedValue(0);
+	const dragY = useSharedValue(0);
+	const width = useSharedValue(0);
+	const height = useSharedValue(0);
+	const isFront = depth === 0 && !isExiting;
+	const [isTouched, setTouched] = useState(false);
+
+	const hide = useCallback(() => store.dispatch({ type: "hide", id }), [store, id]);
+	const handle = useMemo<ToastHandle>(() => ({ id, hide }), [id, hide]);
+	const itemContext = useMemo(() => ({ id, hide }), [id, hide]);
+
+	const remove = useCallback(() => {
+		store.dispatch({ type: "remove", id });
+		onHide?.();
+	}, [store, id, onHide]);
+
+	useEffect(() => {
+		if (isExiting) {
+			presence.value = withTiming(0, { duration: OVERLAY_MOTION.exitMs, easing: EXIT_EASING }, (finished) => {
+				if (finished) scheduleOnRN(remove);
+			});
+			return;
+		}
+		const delay = resolveToastEnterDelay({ createdAt, batchIndex, now: Date.now() });
+		presence.value = withDelay(delay, withTiming(1, { duration: OVERLAY_MOTION.enterMs, easing: ENTER_EASING }));
+	}, [isExiting, createdAt, batchIndex, presence, remove]);
+
+	useEffect(() => {
+		depthValue.value = withTiming(depth, { duration: DEPTH_MS, easing: ENTER_EASING });
+	}, [depth, depthValue]);
+
+	useEffect(() => {
+		if (isFront && height.value > 0) frontHeight.value = height.value;
+	}, [isFront, height, frontHeight]);
+
+	const duration =
+		item.kind === "message"
+			? resolveToastDuration(
+					{ duration: item.duration, hasAction: item.action !== undefined, isLoading: item.isLoading },
+					{ isScreenReaderEnabled }
+				)
+			: resolveToastDuration({ duration: item.duration }, { isScreenReaderEnabled });
+	const isPaused = !isAppActive || isTouched;
+	const clock = useRef<{ key: string; timer: ToastTimer } | null>(null);
+
+	useEffect(() => {
+		if (isExiting) return;
+		const key = `${revision}:${duration}`;
+		if (clock.current?.key !== key) clock.current = { key, timer: createToastTimer(duration) };
+		if (isPaused) return;
+		const running = clock.current;
+		running.timer = startToastTimer(running.timer, Date.now());
+		const remaining = toastTimerRemaining(running.timer, Date.now());
+		const timeout = Number.isFinite(remaining) ? setTimeout(hide, remaining) : null;
+		return () => {
+			if (timeout !== null) clearTimeout(timeout);
+			running.timer = pauseToastTimer(running.timer, Date.now());
+		};
+	}, [revision, duration, isPaused, isExiting, hide]);
+
+	const status = item.kind === "message" ? item.status : "default";
+	const announcement =
+		item.kind === "message" ? resolveToastAnnouncement({ title: item.title, description: item.description }) : null;
+	const haptic = resolveToastHaptic(status, item.haptic);
+
+	// Once per revision: a promise toast is announced loading and again when it settles.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: revision is the trigger; the rest only changes with it
+	useEffect(() => {
+		if (haptic !== false) scheduleOnUI(playHaptic, haptic);
+		if (announcement === null) return;
+		if (Platform.OS === "ios" && resolveToastInterrupts(status)) {
+			AccessibilityInfo.announceForAccessibilityWithOptions(announcement, { queue: false });
+		} else {
+			AccessibilityInfo.announceForAccessibility(announcement);
+		}
+	}, [revision]);
+
+	const pan = useMemo(
+		() =>
+			Gesture.Pan()
+				.activeOffsetX([-10, 10])
+				.activeOffsetY([-10, 10])
+				.onBegin(() => {
+					"worklet";
+					scheduleOnRN(setTouched, true);
+				})
+				.onUpdate((event) => {
+					"worklet";
+					const drag = resolveToastDrag({
+						placement,
+						translationX: event.translationX,
+						translationY: event.translationY,
+					});
+					dragX.value = drag.x;
+					dragY.value = drag.y;
+				})
+				.onEnd((event) => {
+					"worklet";
+					const release = resolveToastRelease({
+						placement,
+						translationX: event.translationX,
+						translationY: event.translationY,
+						velocityX: event.velocityX,
+						velocityY: event.velocityY,
+						width: width.value,
+						height: height.value,
+					});
+					if (release.kind === "settle") {
+						dragX.value = withSpring(0, SETTLE_SPRING);
+						dragY.value = withSpring(0, SETTLE_SPRING);
+						return;
+					}
+					if (release.axis === "x") {
+						dragX.value = withTiming(release.direction * (width.value + 48), { duration: SWIPE_OUT_MS });
+					} else {
+						dragY.value = withTiming(release.direction * (height.value + edgeOffset + 24), {
+							duration: SWIPE_OUT_MS,
+						});
+					}
+					scheduleOnRN(hide);
+				})
+				.onFinalize(() => {
+					"worklet";
+					scheduleOnRN(setTouched, false);
+				}),
+		[placement, dragX, dragY, width, height, edgeOffset, hide]
+	);
+
+	const animatedStyle = useAnimatedStyle(() => {
+		const stack = resolveToastDepthStyle(depthValue.value, placement);
+		const towardEdge = placement === "bottom" ? 1 : -1;
+		const enter = isReduced ? 0 : towardEdge * TOAST_ENTER_DISTANCE * (1 - presence.value);
+		const stackedHeight = resolveToastStackedHeight({
+			depth: depthValue.value,
+			natural: height.value,
+			front: frontHeight.value,
+		});
+		return {
+			height: stackedHeight ?? undefined,
+			opacity: Math.max(0, presence.value * stack.opacity),
+			transform: [
+				{ translateX: dragX.value },
+				{ translateY: stack.translateY + enter + dragY.value },
+				{ scale: stack.scale },
+			],
+		};
+	});
+
+	const onLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			width.value = event.nativeEvent.layout.width;
+		},
+		[width]
+	);
+
+	// The card's own height, measured inside the clip, so a toast behind still
+	// knows how tall it is when it moves up — and the front one publishes it.
+	const onCardLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			height.value = event.nativeEvent.layout.height;
+			if (isFront) frontHeight.value = event.nativeEvent.layout.height;
+		},
+		[height, isFront, frontHeight]
+	);
+
+	const zIndex = 2 * (50 - depth) - (isExiting ? 1 : 0);
+	const edge = placement === "bottom" ? { bottom: edgeOffset } : { top: edgeOffset };
+
+	return (
+		<View className={toastVariants().item()} pointerEvents="box-none" style={[edge, { zIndex }]}>
+			<GestureDetector gesture={pan}>
+				<Animated.View
+					onLayout={onLayout}
+					pointerEvents={isExiting ? "none" : "auto"}
+					style={[
+						{
+							width: "100%",
+							maxWidth: 560,
+							overflow: "hidden",
+							justifyContent: placement === "bottom" ? "flex-end" : "flex-start",
+							transformOrigin: placement === "bottom" ? "bottom" : "top",
+						},
+						animatedStyle,
+					]}
+				>
+					<View onLayout={onCardLayout} style={{ flexShrink: 0 }}>
+						<ToastItemProvider value={itemContext}>
+							{item.kind === "message" ? renderMessage(item, handle) : item.render(handle)}
+						</ToastItemProvider>
+					</View>
+				</Animated.View>
+			</GestureDetector>
+		</View>
+	);
+}
+ToastViewportItem.displayName = "DelacourUI.ToastViewport.Item";

package/src/components/toast/toast-title.tsx

@@ -0,0 +1,13 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useToastPart } from "./toast.context";
+import { toastVariants } from "./toast.variants";
+
+export type ToastTitleProps = TextPresetProps;
+
+/** What happened, in the status's colour — Alert's token for it, the same shade as the glyph. */
+export function ToastTitle({ className, ...props }: ToastTitleProps): ReactElement {
+	const { status } = useToastPart("Toast.Title");
+	return <Text className={toastVariants({ status }).title({ className })} {...props} />;
+}
+ToastTitle.displayName = "DelacourUI.Toast.Title";

package/src/components/toast/toast-viewport.tsx

@@ -0,0 +1,135 @@
+import { type ReactElement, useEffect, useState, useSyncExternalStore } from "react";
+import { AccessibilityInfo, AppState, View } from "react-native";
+import { useReanimatedKeyboardAnimation } from "react-native-keyboard-controller";
+import Animated, { useAnimatedStyle, useSharedValue } from "react-native-reanimated";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { Overlay } from "../overlay";
+import type { ToastItem, ToastPlacement, ToastStore } from "./toast.store";
+import { resolveToastStack, TOAST_PLACEMENTS, toastVariants } from "./toast.variants";
+import { toastStore } from "./toast-api";
+import { ToastViewportItem } from "./toast-item";
+
+/** The gap between a toast and the safe area, in points, when no `offset` is given. */
+const DEFAULT_EDGE_GAP = 8;
+
+export type ToastViewportProps = {
+	/** Extra points between each stack and its safe-area edge — clear a tab bar with `{ bottom: 56 }`. Default 8 each. */
+	offset?: { top?: number; bottom?: number };
+	/** The store to draw. Default: the one `toast` writes to. */
+	store?: ToastStore;
+};
+
+/** Whether VoiceOver or TalkBack is running, kept current. */
+function useScreenReaderEnabled(): boolean {
+	const [isEnabled, setEnabled] = useState(false);
+	useEffect(() => {
+		let isMounted = true;
+		AccessibilityInfo.isScreenReaderEnabled().then((value) => {
+			if (isMounted) setEnabled(value);
+		});
+		const subscription = AccessibilityInfo.addEventListener("screenReaderChanged", setEnabled);
+		return () => {
+			isMounted = false;
+			subscription.remove();
+		};
+	}, []);
+	return isEnabled;
+}
+
+/** False while the app is in the background or inactive — every toast's clock stops. */
+function useAppActive(): boolean {
+	const [isActive, setActive] = useState(AppState.currentState === "active");
+	useEffect(() => {
+		const subscription = AppState.addEventListener("change", (state) => setActive(state === "active"));
+		return () => subscription.remove();
+	}, []);
+	return isActive;
+}
+
+/**
+ * Draws every toast — mount it once, inside `OverlayProvider`, beside the
+ * navigator.
+ *
+ * Two stacks, top and bottom, in the overlay z-order's `toast` band, above
+ * every sheet and every dialog. Both are `box-none`: only a toast's own card
+ * takes a touch, so the app under the viewport stays tappable. The top stack
+ * sits under the status bar; the bottom one above the home indicator, and it
+ * rides up with the keyboard. Each stack draws its newest three and queues the
+ * rest (`resolveToastStack`).
+ *
+ * Renders nothing — and holds no overlay registration — while there is no
+ * toast. Without an `OverlayProvider` it draws inline and warns once in
+ * development, like every overlay.
+ *
+ * @example
+ * <OverlayProvider>
+ *   <BottomSheetProvider>
+ *     <Stack />
+ *     <ToastViewport />
+ *   </BottomSheetProvider>
+ * </OverlayProvider>
+ */
+export function ToastViewport({ offset, store = toastStore }: ToastViewportProps): ReactElement | null {
+	const items = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+	const insets = useSafeAreaInsets();
+	const isAppActive = useAppActive();
+	const isScreenReaderEnabled = useScreenReaderEnabled();
+	const keyboard = useReanimatedKeyboardAnimation();
+	const insetBottom = insets.bottom;
+	const topFrontHeight = useSharedValue(0);
+	const bottomFrontHeight = useSharedValue(0);
+
+	// The keyboard covers the home indicator, so the bottom stack lifts by the
+	// part of the keyboard above that inset — no more.
+	const keyboardLift = useAnimatedStyle(() => ({
+		transform: [{ translateY: -Math.max(0, -keyboard.height.value - insetBottom) }],
+	}));
+
+	if (items.length === 0) return null;
+
+	const byId = new Map<string, ToastItem>(items.map((item) => [item.id, item]));
+	const edgeOffsets: Record<ToastPlacement, number> = {
+		top: insets.top + (offset?.top ?? DEFAULT_EDGE_GAP),
+		bottom: insets.bottom + (offset?.bottom ?? DEFAULT_EDGE_GAP),
+	};
+	const slots = toastVariants();
+
+	const stacks = TOAST_PLACEMENTS.map((placement) => ({
+		placement,
+		entries: resolveToastStack(items, placement).filter((entry) => entry.isVisible),
+	}));
+
+	return (
+		<Overlay.Portal layer="toast">
+			<View className={slots.viewport()} pointerEvents="box-none">
+				{stacks.map(({ placement, entries }) => (
+					<Animated.View
+						className={slots.stack()}
+						key={placement}
+						pointerEvents="box-none"
+						style={placement === "bottom" ? keyboardLift : undefined}
+					>
+						{entries.map((entry) => {
+							const item = byId.get(entry.id);
+							return item ? (
+								<ToastViewportItem
+									depth={entry.depth}
+									edgeOffset={edgeOffsets[placement]}
+									frontHeight={placement === "bottom" ? bottomFrontHeight : topFrontHeight}
+									isAppActive={isAppActive}
+									isExiting={entry.isExiting}
+									isScreenReaderEnabled={isScreenReaderEnabled}
+									item={item}
+									key={item.id}
+									placement={placement}
+									store={store}
+								/>
+							) : null;
+						})}
+					</Animated.View>
+				))}
+			</View>
+		</Overlay.Portal>
+	);
+}
+ToastViewport.displayName = "DelacourUI.ToastViewport";

package/src/components/toast/toast.context.tsx

@@ -0,0 +1,69 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { ToastStatus } from "./toast.store";
+
+/** The action `Toast.Action` lends its root, so a screen reader's `activate` runs it. */
+export type ToastRegisteredAction = {
+	label: string;
+	run: () => void;
+};
+
+export type ToastContextValue = {
+	status: ToastStatus;
+	/** Hides the toast — the root's `onHide`, or the viewport's for the toast it is drawing. */
+	hide: () => void;
+	/** `Toast.Action` registers itself here while mounted, and passes `null` on unmount. */
+	registerAction: (action: ToastRegisteredAction | null) => void;
+};
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+/**
+ * Supplies the enclosing toast's status and `hide` to its parts.
+ *
+ * Its own module, importing nothing but types, so a part can read it without
+ * importing `./toast` — that import would close a cycle (package rule 3).
+ */
+export function ToastProvider({ value, children }: { value: ToastContextValue; children: ReactNode }): ReactElement {
+	return <ToastContext value={value}>{children}</ToastContext>;
+}
+ToastProvider.displayName = "DelacourUI.Toast.Provider";
+
+/** The enclosing toast's context, or null outside a `<Toast>`. */
+export function useToastContext(): ToastContextValue | null {
+	return use(ToastContext);
+}
+
+/** Internal: the enclosing toast's context for a part that cannot work without one. */
+export function useToastPart(component: string): ToastContextValue {
+	const context = useToastContext();
+	if (!context) throw new Error(`${component} must be rendered inside a <Toast>.`);
+	return context;
+}
+
+/** What the viewport tells a toast it is drawing: which one, and how to hide it. */
+export type ToastItemContextValue = {
+	id: string;
+	hide: () => void;
+};
+
+const ToastItemContext = createContext<ToastItemContextValue | null>(null);
+
+/**
+ * Wraps each toast the viewport draws, so a `<Toast>` inside a custom
+ * `render` hides the right toast with no `onHide` of its own.
+ */
+export function ToastItemProvider({
+	value,
+	children,
+}: {
+	value: ToastItemContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <ToastItemContext value={value}>{children}</ToastItemContext>;
+}
+ToastItemProvider.displayName = "DelacourUI.ToastViewport.ItemProvider";
+
+/** The toast the viewport is drawing here, or null outside one. */
+export function useToastItemContext(): ToastItemContextValue | null {
+	return use(ToastItemContext);
+}