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

package/src/components/fab/fab-action.tsx

@@ -0,0 +1,118 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { Icon, type IconComponent } from "../icon";
+import { Pressable } from "../pressable";
+import { Text } from "../text";
+import { useFabActionItem, useFabGroupPart } from "./fab.context";
+import { FAB_DIAL_STAGGER, FAB_FOREGROUND_TOKEN, fabVariants, resolveDialProgress } from "./fab.variants";
+
+/** How far below its resting place a closed action sits, in points. */
+const ACTION_RISE = 16;
+
+/** An action's scale at the start of its window. */
+const ACTION_START_SCALE = 0.6;
+
+export type FabActionProps = {
+	icon: IconComponent;
+	/** The chip beside the button, and the button's accessibility label. */
+	label: string;
+	onPress: () => void;
+	isDisabled?: boolean;
+	/** Draws the glyph in the destructive colour. The surface stays the dial's. */
+	isDestructive?: boolean;
+	className?: string;
+	labelClassName?: string;
+	/** Lands on the round button. */
+	testID?: string;
+};
+
+/**
+ * One action in a `Fab.Group`'s dial: a small round button on the trigger's
+ * centre line, and a label chip on the side facing into the screen.
+ *
+ * Takes its glyph as a prop rather than composing it, unlike `Fab`: the action
+ * draws two things — a button and a chip — from one label and one icon, and
+ * the dial owns how both look.
+ *
+ * Pressing runs the action, then closes the dial. The chip presses too, since a
+ * finger aims at the words, but it is hidden from assistive technology so a
+ * screen reader meets each action once.
+ *
+ * Its stagger window comes from its place in the dial, read on the UI thread
+ * from the dial's one spring. Under reduced motion it fades in place.
+ */
+export function FabAction({
+	icon,
+	label,
+	onPress,
+	isDisabled = false,
+	isDestructive = false,
+	className,
+	labelClassName,
+	testID,
+}: FabActionProps): ReactElement {
+	const { progress, count, labelSide, size, haptic, isReducedMotion, close } = useFabGroupPart("Fab.Action");
+	const { index } = useFabActionItem("Fab.Action");
+	const slots = fabVariants({ size, labelSide, isDisabled });
+
+	const style = useAnimatedStyle(() => {
+		if (isReducedMotion) {
+			const value = progress.value;
+			return {
+				opacity: value < 0 ? 0 : value > 1 ? 1 : value,
+				transform: [{ translateY: 0 }, { scale: 1 }],
+			};
+		}
+		const local = resolveDialProgress({ open: progress.value, index, count, stagger: FAB_DIAL_STAGGER });
+		return {
+			opacity: local,
+			transform: [
+				{ translateY: (1 - local) * ACTION_RISE },
+				{ scale: ACTION_START_SCALE + (1 - ACTION_START_SCALE) * local },
+			],
+		};
+	});
+
+	const handlePress = () => {
+		onPress();
+		close();
+	};
+
+	return (
+		<Animated.View className={slots.action({ className })} style={style}>
+			<Pressable
+				accessibilityElementsHidden
+				accessible={false}
+				className={slots.actionLabel()}
+				disabled={isDisabled}
+				feedback="fade"
+				importantForAccessibility="no-hide-descendants"
+				onPress={handlePress}
+			>
+				<Text className={slots.actionLabelText({ className: labelClassName })} numberOfLines={1}>
+					{label}
+				</Text>
+			</Pressable>
+			<View className={slots.actionAnchor()}>
+				<Pressable
+					accessibilityLabel={label}
+					accessibilityRole="button"
+					className={slots.actionButton()}
+					disabled={isDisabled}
+					feedback="scale"
+					haptic={haptic}
+					onPress={handlePress}
+					testID={testID}
+				>
+					<Icon
+						className={slots.actionIcon()}
+						color={isDestructive ? "destructive" : FAB_FOREGROUND_TOKEN.surface}
+						icon={icon}
+					/>
+				</Pressable>
+			</View>
+		</Animated.View>
+	);
+}
+FabAction.displayName = "DelacourUI.Fab.Action";

package/src/components/fab/fab-group.tsx

@@ -0,0 +1,214 @@
+import {
+	Children,
+	isValidElement,
+	type ReactElement,
+	type ReactNode,
+	use,
+	useCallback,
+	useEffect,
+	useMemo,
+	useState,
+} from "react";
+import { BackHandler, View, type ViewProps } from "react-native";
+import Animated, {
+	useAnimatedStyle,
+	useReducedMotion,
+	useSharedValue,
+	withSpring,
+	withTiming,
+} from "react-native-reanimated";
+import { SafeAreaInsetsContext } from "react-native-safe-area-context";
+import { scheduleOnRN } from "react-native-worklets";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { Icon, type IconComponent } from "../icon";
+import { Pressable } from "../pressable";
+import { Text } from "../text";
+import { FabActionItemProvider, type FabGroupContextValue, FabGroupProvider } from "./fab.context";
+import type { FabSharedProps } from "./fab.types";
+import {
+	FAB_DEFAULT_OFFSET,
+	FAB_FOREGROUND_TOKEN,
+	FAB_OPEN_ROTATION_DEG,
+	FAB_REDUCED_MOTION_MS,
+	type FabPlacement,
+	fabVariants,
+	resolveFabPlacementStyle,
+	resolveLabelSide,
+} from "./fab.variants";
+
+/** One spring for the whole dial, with a little overshoot so it lands rather than stops. */
+const DIAL_SPRING = { damping: 16, stiffness: 220, mass: 0.8 } as const;
+
+export type FabGroupProps = Omit<ViewProps, "children"> &
+	FabSharedProps & {
+		/** `Fab.Action`s, written top to bottom as they appear above the trigger. */
+		children: ReactNode;
+		/** The trigger's glyph. Turns 45° as the dial opens — a plus becomes a cross. */
+		icon: IconComponent;
+		/** Extends the trigger with this text while the dial is closed. */
+		label?: string;
+		isOpen?: boolean;
+		defaultOpen?: boolean;
+		onOpenChange?: (isOpen: boolean) => void;
+		/** Default `bottom-end`. A group is always pinned. */
+		placement?: FabPlacement;
+		/** Turn the glyph 45° as the dial opens. Default `true`. */
+		isRotatedOnOpen?: boolean;
+		/** Lands on the trigger, the one element a test or a flow presses. */
+		testID?: string;
+		/** Required: the trigger is a glyph, and the dial it opens needs a name. */
+		accessibilityLabel: string;
+		className?: string;
+	};
+
+/**
+ * A trigger that unfolds a dial of related actions, over a scrim.
+ *
+ * Renders a layer covering its parent — the scrim and the pinned dial — so it
+ * must be written in the screen's root container, as a sibling of the content
+ * it floats over. Nested inside a scroll view's content, the scrim would cover
+ * the content box rather than the screen.
+ *
+ * One spring drives the dial. Each action reads its own window of it, so
+ * closing halfway through opening runs the same cascade backwards. Actions are
+ * unmounted once the close settles, so a screen reader can never walk into a
+ * button nobody can see.
+ */
+export function FabGroup({
+	children,
+	icon,
+	label,
+	isOpen: isOpenProp,
+	defaultOpen = false,
+	onOpenChange,
+	placement = "bottom-end",
+	offset = FAB_DEFAULT_OFFSET,
+	isSafeAreaAware = true,
+	size = "md",
+	variant = "primary",
+	isDisabled = false,
+	haptic = false,
+	isRotatedOnOpen = true,
+	accessibilityLabel,
+	className,
+	testID,
+	...props
+}: FabGroupProps): ReactElement {
+	const [isOpen, setIsOpen] = useControllableState({
+		value: isOpenProp,
+		defaultValue: defaultOpen,
+		onChange: onOpenChange,
+	});
+	const isReducedMotion = useReducedMotion();
+	const insets = use(SafeAreaInsetsContext);
+	const progress = useSharedValue(isOpen ? 1 : 0);
+	const [isMounted, setIsMounted] = useState(isOpen);
+
+	// Mount before the open spring starts, in the same render that opened it,
+	// so the first frame of the dial already has its actions.
+	if (isOpen && !isMounted) setIsMounted(true);
+
+	useEffect(() => {
+		const target = isOpen ? 1 : 0;
+		const onSettled = (isFinished?: boolean) => {
+			"worklet";
+			if (isFinished && target === 0) scheduleOnRN(setIsMounted, false);
+		};
+		progress.value = isReducedMotion
+			? withTiming(target, { duration: FAB_REDUCED_MOTION_MS }, onSettled)
+			: withSpring(target, DIAL_SPRING, onSettled);
+	}, [isOpen, isReducedMotion, progress]);
+
+	useEffect(() => {
+		if (!isOpen) return;
+		const subscription = BackHandler.addEventListener("hardwareBackPress", () => {
+			setIsOpen(false);
+			return true;
+		});
+		return () => subscription.remove();
+	}, [isOpen, setIsOpen]);
+
+	const actions = Children.toArray(children).filter(isValidElement);
+	const count = actions.length;
+	const labelSide = resolveLabelSide(placement);
+
+	const close = useCallback(() => setIsOpen(false), [setIsOpen]);
+	const toggle = () => setIsOpen(!isOpen);
+
+	const context = useMemo<FabGroupContextValue>(
+		() => ({ progress, isOpen, count, labelSide, size, haptic, isReducedMotion, close }),
+		[progress, isOpen, count, labelSide, size, haptic, isReducedMotion, close]
+	);
+
+	const isExtended = label !== undefined && !isOpen;
+	const slots = fabVariants({ size, variant, isExtended, isDisabled, labelSide });
+
+	const scrimStyle = useAnimatedStyle(() => {
+		const value = progress.value;
+		return { opacity: value < 0 ? 0 : value > 1 ? 1 : value };
+	});
+
+	const glyphStyle = useAnimatedStyle(() => {
+		const value = progress.value;
+		const clamped = value < 0 ? 0 : value > 1 ? 1 : value;
+		return { transform: [{ rotate: `${isRotatedOnOpen ? clamped * FAB_OPEN_ROTATION_DEG : 0}deg` }] };
+	});
+
+	const anchorStyle = resolveFabPlacementStyle({
+		placement,
+		offset,
+		insetBottom: isSafeAreaAware ? (insets?.bottom ?? 0) : 0,
+	});
+
+	// Written top to bottom, but the action nearest the trigger leads the
+	// cascade — so the last child is index 0.
+	const dial = isMounted
+		? actions.map((action, position) => (
+				<FabActionItemProvider key={action.key ?? position} value={{ index: count - 1 - position }}>
+					{action}
+				</FabActionItemProvider>
+			))
+		: null;
+
+	return (
+		<FabGroupProvider value={context}>
+			<View accessibilityViewIsModal={isOpen} className="absolute inset-0" pointerEvents="box-none">
+				{isMounted ? (
+					<Animated.View className={slots.scrim()} style={scrimStyle}>
+						<Pressable
+							accessibilityLabel="Close"
+							accessibilityRole="button"
+							className="flex-1"
+							feedback="none"
+							onPress={close}
+						/>
+					</Animated.View>
+				) : null}
+				<View className={slots.dial({ className })} pointerEvents="box-none" style={anchorStyle} {...props}>
+					{dial}
+					<Pressable
+						accessibilityLabel={accessibilityLabel}
+						accessibilityRole="button"
+						accessibilityState={{ expanded: isOpen }}
+						className={slots.root()}
+						disabled={isDisabled}
+						feedback="scale"
+						haptic={haptic}
+						onPress={toggle}
+						testID={testID}
+					>
+						<Animated.View style={glyphStyle}>
+							<Icon className={slots.icon()} color={FAB_FOREGROUND_TOKEN[variant]} icon={icon} />
+						</Animated.View>
+						{isExtended ? (
+							<Text className={slots.label()} numberOfLines={1}>
+								{label}
+							</Text>
+						) : null}
+					</Pressable>
+				</View>
+			</View>
+		</FabGroupProvider>
+	);
+}
+FabGroup.displayName = "DelacourUI.Fab.Group";

package/src/components/fab/fab-label.tsx

@@ -0,0 +1,18 @@
+import type { ReactElement, ReactNode } from "react";
+import { Text, type TextProps } from "../text";
+import { useFabPart } from "./fab.context";
+import { fabVariants } from "./fab.variants";
+
+export type FabLabelProps = Omit<TextProps, "children"> & { children: ReactNode; className?: string };
+
+/**
+ * An extended fab's text.
+ *
+ * Carries its own colour, read from the fab's variant: a `View` does not cascade
+ * colour to a `Text`, so a colour on the root would be lost.
+ */
+export function FabLabel({ className, ...props }: FabLabelProps): ReactElement {
+	const { variant } = useFabPart("Fab.Label");
+	return <Text className={fabVariants({ variant }).label({ className })} numberOfLines={1} {...props} />;
+}
+FabLabel.displayName = "DelacourUI.Fab.Label";

package/src/components/fab/fab.context.tsx

@@ -0,0 +1,125 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { HapticFeedback } from "../pressable/pressable";
+import type { FabLabelSide, FabSize, FabVariant } from "./fab.variants";
+
+export type FabContextValue = {
+	size: FabSize;
+	variant: FabVariant;
+	/** A stadium with a label, rather than a circle. */
+	isExtended: boolean;
+	isDisabled: boolean;
+};
+
+const FabContext = createContext<FabContextValue | null>(null);
+
+/**
+ * Supplies the enclosing fab's axes to its subtree, so `Fab.Label` and a custom
+ * child can match it without the root passing props down.
+ *
+ * A leaf of its own, importing nothing but types, so a part reads it without
+ * importing `./fab` and closing a cycle.
+ */
+export function FabProvider({ value, children }: { value: FabContextValue; children: ReactNode }): ReactElement {
+	return <FabContext value={value}>{children}</FabContext>;
+}
+FabProvider.displayName = "DelacourUI.Fab.Provider";
+
+/** The enclosing fab's axes, or null outside a `<Fab>`. */
+export function useFabContext(): FabContextValue | null {
+	return use(FabContext);
+}
+
+/** Reads the enclosing fab's axes. Throws outside a `<Fab>`. */
+export function useFab(): FabContextValue {
+	const context = useFabContext();
+	if (!context) throw new Error("useFab must be called inside a <Fab>.");
+	return context;
+}
+
+/** The enclosing fab's axes, for a part that cannot work without one. Internal. */
+export function useFabPart(component: string): FabContextValue {
+	const context = useFabContext();
+	if (!context) throw new Error(`${component} must be rendered inside a <Fab>.`);
+	return context;
+}
+
+export type FabGroupContextValue = {
+	/** The dial's one spring, 0 closed → 1 open. It overshoots; readers clamp. */
+	progress: SharedValue<number>;
+	isOpen: boolean;
+	/** How many actions the dial holds — each action's stagger window depends on it. */
+	count: number;
+	labelSide: FabLabelSide;
+	/** The trigger's size. Actions are always `sm`, centred on the trigger's centre line. */
+	size: FabSize;
+	haptic: false | HapticFeedback;
+	/** Fade in place instead of rising with a stagger. */
+	isReducedMotion: boolean;
+	close: () => void;
+};
+
+const FabGroupContext = createContext<FabGroupContextValue | null>(null);
+
+/** Supplies the dial's spring and state to every action in it. */
+export function FabGroupProvider({
+	value,
+	children,
+}: {
+	value: FabGroupContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <FabGroupContext value={value}>{children}</FabGroupContext>;
+}
+FabGroupProvider.displayName = "DelacourUI.Fab.Group.Provider";
+
+/** The enclosing dial, or null outside a `<Fab.Group>`. */
+export function useFabGroupContext(): FabGroupContextValue | null {
+	return use(FabGroupContext);
+}
+
+/** Reads the enclosing dial. Throws outside a `<Fab.Group>`. */
+export function useFabGroup(): FabGroupContextValue {
+	const context = useFabGroupContext();
+	if (!context) throw new Error("useFabGroup must be called inside a <Fab.Group>.");
+	return context;
+}
+
+/** The enclosing dial, for a part that cannot work without one. Internal. */
+export function useFabGroupPart(component: string): FabGroupContextValue {
+	const context = useFabGroupContext();
+	if (!context) throw new Error(`${component} must be rendered inside a <Fab.Group>.`);
+	return context;
+}
+
+export type FabActionItemContextValue = {
+	/** 0 is the action nearest the trigger; the dial unfolds outward from it. */
+	index: number;
+};
+
+const FabActionItemContext = createContext<FabActionItemContextValue | null>(null);
+
+/**
+ * Supplies one action its place in the dial.
+ *
+ * The group wraps each child in one of these rather than cloning an `index`
+ * prop onto it: a provider reaches an action a caller wrapped in a fragment or
+ * produced from a helper, and adds no view to the layout.
+ */
+export function FabActionItemProvider({
+	value,
+	children,
+}: {
+	value: FabActionItemContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <FabActionItemContext value={value}>{children}</FabActionItemContext>;
+}
+FabActionItemProvider.displayName = "DelacourUI.Fab.Group.ItemProvider";
+
+/** This action's place in the dial. Throws outside a `<Fab.Group>`. Internal. */
+export function useFabActionItem(component: string): FabActionItemContextValue {
+	const context = use(FabActionItemContext);
+	if (!context) throw new Error(`${component} must be rendered inside a <Fab.Group>.`);
+	return context;
+}

package/src/components/fab/fab.tsx

@@ -0,0 +1,156 @@
+import { Children, type ReactElement, type ReactNode, use, useEffect, useMemo } from "react";
+import { View } from "react-native";
+import { SafeAreaInsetsContext } from "react-native-safe-area-context";
+import { IconDefaultsProvider } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { TextClassProvider } from "../text/text.context";
+import { type FabContextValue, FabProvider } from "./fab.context";
+import type { FabSharedProps } from "./fab.types";
+import {
+	FAB_DEFAULT_OFFSET,
+	FAB_FOREGROUND_TOKEN,
+	type FabPlacement,
+	fabVariants,
+	resolveFabPlacementStyle,
+} from "./fab.variants";
+import { FabAction } from "./fab-action";
+import { FabGroup } from "./fab-group";
+import { FabLabel } from "./fab-label";
+
+export type FabProps = Omit<PressableProps, "busy" | "children" | "disabled" | "haptic"> &
+	FabSharedProps & {
+		/** A stadium holding a `Fab.Label` beside the icon, rather than a circle. */
+		isExtended?: boolean;
+		/**
+		 * Pins the fab to the bottom of its nearest positioned ancestor. Omitted,
+		 * the fab sits in flow like any other view.
+		 */
+		placement?: FabPlacement;
+		/** Required in practice for a round fab — there is no text to read. */
+		accessibilityLabel?: string;
+		children?: ReactNode;
+	};
+
+function FabRoot({
+	size = "md",
+	variant = "primary",
+	isExtended = false,
+	placement,
+	offset = FAB_DEFAULT_OFFSET,
+	isSafeAreaAware = true,
+	isDisabled = false,
+	haptic = false,
+	feedback = "scale",
+	accessibilityLabel,
+	className,
+	children,
+	...props
+}: FabProps): ReactElement {
+	const insets = use(SafeAreaInsetsContext);
+
+	useEffect(() => {
+		if (process.env.NODE_ENV === "production") return;
+		if (!isExtended && !accessibilityLabel) {
+			console.warn(
+				"Fab: a round fab has no text for a screen reader to read. Pass `accessibilityLabel`, or `isExtended` with a `Fab.Label`."
+			);
+		}
+	}, [isExtended, accessibilityLabel]);
+
+	const context = useMemo<FabContextValue>(
+		() => ({ size, variant, isExtended, isDisabled }),
+		[size, variant, isExtended, isDisabled]
+	);
+
+	const slots = fabVariants({ size, variant, isExtended, isDisabled });
+	const iconClassName = slots.icon();
+	const iconDefaults = useMemo(
+		() => ({ className: iconClassName, color: FAB_FOREGROUND_TOKEN[variant] }),
+		[iconClassName, variant]
+	);
+
+	const button = (
+		<FabProvider value={context}>
+			<Pressable
+				accessibilityLabel={accessibilityLabel}
+				accessibilityRole="button"
+				className={slots.root({ className })}
+				disabled={isDisabled}
+				feedback={feedback}
+				haptic={haptic}
+				{...props}
+			>
+				<IconDefaultsProvider value={iconDefaults}>
+					<TextClassProvider value={slots.label()}>{wrapTextChildren(children)}</TextClassProvider>
+				</IconDefaultsProvider>
+			</Pressable>
+		</FabProvider>
+	);
+
+	if (!placement) return button;
+
+	const style = resolveFabPlacementStyle({
+		placement,
+		offset,
+		insetBottom: isSafeAreaAware ? (insets?.bottom ?? 0) : 0,
+	});
+
+	return (
+		<View pointerEvents="box-none" style={style}>
+			{button}
+		</View>
+	);
+}
+
+/**
+ * Wraps bare text children in a `Fab.Label` — React Native cannot render a
+ * string outside a `<Text>`.
+ */
+function wrapTextChildren(children: ReactNode): ReactNode {
+	return Children.map(children, (child) =>
+		typeof child === "string" || typeof child === "number" ? <FabLabel>{child}</FabLabel> : child
+	);
+}
+
+/**
+ * One primary action floating over the screen it belongs to — "New note" over
+ * a list.
+ *
+ * The icon is composed, the way a `Button`'s is: the fab publishes its icon
+ * size and its variant's foreground through `IconDefaultsProvider`, so a bare
+ * `<Icon icon={IconPlusLarge} />` comes out right with nothing said.
+ *
+ * `placement` pins it to the bottom of its nearest positioned ancestor, lifted
+ * by `offset` and, unless told otherwise, the bottom safe-area inset. Omitted,
+ * the fab sits in flow. Pad the bottom of a list it floats over by the fab's
+ * height plus its offset, or the last row hides behind it.
+ *
+ * `Fab.Group` turns the trigger into a dial of related actions that unfold
+ * above it.
+ *
+ * @example
+ * <Fab accessibilityLabel="New note" onPress={compose} placement="bottom-end">
+ *   <Icon icon={IconPlusLarge} />
+ * </Fab>
+ *
+ * @example
+ * <Fab isExtended onPress={write} placement="bottom-end">
+ *   <Icon icon={IconPencil} />
+ *   <Fab.Label>Write</Fab.Label>
+ * </Fab>
+ *
+ * @example
+ * <Fab.Group accessibilityLabel="Add something" icon={IconPlusLarge}>
+ *   <Fab.Action icon={IconImages} label="Photo" onPress={addPhoto} />
+ *   <Fab.Action icon={IconTrashCan} isDestructive label="Empty drafts" onPress={empty} />
+ * </Fab.Group>
+ */
+export const Fab = Object.assign(FabRoot, {
+	/** An extended fab's text, coloured for the fab's variant. */
+	Label: FabLabel,
+	/** A trigger that unfolds a dial of related actions, over a scrim. */
+	Group: FabGroup,
+	/** One action in a `Fab.Group`'s dial: a small round button and a label chip. */
+	Action: FabAction,
+	displayName: "DelacourUI.Fab",
+});

package/src/components/fab/fab.types.ts

@@ -0,0 +1,17 @@
+import type { HapticFeedback } from "../pressable/pressable";
+import type { FabSize, FabVariant } from "./fab.variants";
+
+/** The axes a `Fab` and a `Fab.Group`'s trigger share. */
+export type FabSharedProps = {
+	/** 44, 56 or 64pt. Default `md`. */
+	size?: FabSize;
+	/** Default `primary`. */
+	variant?: FabVariant;
+	isDisabled?: boolean;
+	/** Haptic played on press. Off by default. */
+	haptic?: false | HapticFeedback;
+	/** Distance from the bottom and side edges, before the safe-area inset. Default 16. */
+	offset?: number;
+	/** Add the bottom safe-area inset to `offset`. Default `true`. Ignored in flow. */
+	isSafeAreaAware?: boolean;
+};