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

package/src/components/drawer/drawer-body.tsx

@@ -0,0 +1,46 @@
+import type { ReactElement } from "react";
+import { ScrollView, type ScrollViewProps, View, type ViewProps } from "react-native";
+import { cn } from "../../lib/cn";
+import { drawerVariants } from "./drawer.variants";
+
+export type DrawerBodyProps =
+	/** Scrolls when its content is taller than the panel. The default. */
+	| ({ isScrollable?: true; className?: string; contentContainerClassName?: string } & ScrollViewProps)
+	/** A plain column, for content that fits — a few chips and a slider. */
+	| ({ isScrollable: false; className?: string } & ViewProps);
+
+/**
+ * The panel's content, between the header and the footer, taking the height
+ * left over.
+ *
+ * Scrolls by default. The panel's pan waits for travel along its own axis and
+ * fails on travel across it, so a vertical scroll in a start or end drawer
+ * never moves the drawer. A top or bottom drawer's pan runs along the same axis
+ * as a vertical scroll — keep their content short, or reach for a `BottomSheet`.
+ *
+ * @example
+ * <Drawer.Body>
+ *   <ListGroup>…</ListGroup>
+ * </Drawer.Body>
+ *
+ * @example
+ * <Drawer.Body isScrollable={false}>…</Drawer.Body>
+ */
+export function DrawerBody(props: DrawerBodyProps): ReactElement {
+	const slots = drawerVariants();
+
+	if (props.isScrollable === false) {
+		const { isScrollable: _isScrollable, className, ...rest } = props;
+		return <View className={cn(slots.body(), slots.bodyContent(), className)} {...rest} />;
+	}
+
+	const { isScrollable: _isScrollable, className, contentContainerClassName, ...rest } = props;
+	return (
+		<ScrollView
+			className={slots.body({ className })}
+			contentContainerClassName={slots.bodyContent({ className: contentContainerClassName })}
+			{...rest}
+		/>
+	);
+}
+DrawerBody.displayName = "DelacourUI.Drawer.Body";

package/src/components/drawer/drawer-close.tsx

@@ -0,0 +1,76 @@
+import { type ReactElement, useCallback } from "react";
+import { IconCrossSmall } from "../../icons/central";
+import { Slot } from "../../lib/slot";
+import { Icon } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { useDrawerPart } from "./drawer.context";
+import { DRAWER_CLOSE_HIT_SLOP, drawerVariants } from "./drawer.variants";
+
+export type DrawerCloseProps =
+	/** Donates the close to the single child — a `Button` in the footer, a navigation row. */
+	| ({ asChild: true; children: ReactElement } & Omit<PressableProps, "asChild" | "children">)
+	/** The ✕ glyph. */
+	| ({ asChild?: false; accessibilityLabel?: string } & Omit<PressableProps, "asChild" | "children">);
+
+/**
+ * Closes the drawer.
+ *
+ * Without children it is a ✕: this library's `Pressable` with `fade` feedback
+ * — a scale on a glyph this small reads as a jitter — 8pt of slop because a
+ * bare glyph has no capsule to bring it toward 44pt, and `"Close"` as its
+ * label. `Drawer.Header` writes one at its trailing edge unless told not to.
+ *
+ * With `asChild` it donates the close to its child, chained ahead of the
+ * child's own `onPress` — a navigation row that should also shut the menu.
+ * Either way it is the same `setOpen(false)` the scrim, the swipe and the back
+ * button take, and it closes even a non-dismissible drawer: it is one of the
+ * drawer's own actions.
+ *
+ * @example
+ * <Drawer.Close asChild>
+ *   <Button variant="secondary">Done</Button>
+ * </Drawer.Close>
+ */
+export function DrawerClose(props: DrawerCloseProps): ReactElement {
+	const { close } = useDrawerPart("Drawer.Close");
+	const { onPress } = props;
+
+	const handlePress = useCallback(() => {
+		close();
+		onPress?.();
+	}, [close, onPress]);
+
+	if (props.asChild) {
+		const { asChild: _asChild, children, onPress: _onPress, ...rest } = props;
+		return (
+			<Slot onPress={handlePress} {...rest}>
+				{children}
+			</Slot>
+		);
+	}
+
+	const {
+		asChild: _asChild,
+		accessibilityLabel = "Close",
+		className,
+		feedback = "fade",
+		hitSlop = DRAWER_CLOSE_HIT_SLOP,
+		onPress: _onPress,
+		...rest
+	} = props;
+
+	return (
+		<Pressable
+			accessibilityLabel={accessibilityLabel}
+			accessibilityRole="button"
+			className={drawerVariants().close({ className })}
+			feedback={feedback}
+			hitSlop={hitSlop}
+			onPress={handlePress}
+			{...rest}
+		>
+			<Icon color="muted-foreground" icon={IconCrossSmall} />
+		</Pressable>
+	);
+}
+DrawerClose.displayName = "DelacourUI.Drawer.Close";

package/src/components/drawer/drawer-content.tsx

@@ -0,0 +1,186 @@
+import { type ReactElement, useCallback, useEffect, useId, useMemo } from "react";
+import {
+	AccessibilityInfo,
+	findNodeHandle,
+	I18nManager,
+	useWindowDimensions,
+	View,
+	type ViewProps,
+} from "react-native";
+import { GestureDetector } from "react-native-gesture-handler";
+import Animated, { useAnimatedReaction, useAnimatedStyle, useSharedValue } from "react-native-reanimated";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { Overlay, useOverlayBackHandler, useOverlayPresence } from "../overlay";
+import { type DrawerFocusTarget, DrawerPanelProvider, type DrawerPanelValue, useDrawerPart } from "./drawer.context";
+import {
+	type DrawerSide,
+	type DrawerSize,
+	drawerVariants,
+	resolveDrawerDragFraction,
+	resolveDrawerEdge,
+	resolveDrawerExtent,
+	resolveDrawerFrameExtent,
+	resolveDrawerInsets,
+	resolveDrawerOffset,
+} from "./drawer.variants";
+import { useDrawerPan } from "./use-drawer-pan";
+
+export type DrawerContentProps = ViewProps & {
+	className?: string;
+	/** Classes for the scrim behind the panel. */
+	scrimClassName?: string;
+	/** The edge it opens from. `start` and `end` follow the layout direction. Default `"start"`. */
+	side?: DrawerSide;
+	/** The panel's width (start, end) or height (top, bottom): `sm` 62% to 280, `md` 78% to 320, `lg` 88% to 400, `full` 94%. Default `"md"`. */
+	size?: DrawerSize;
+	/** Whether a swipe toward the edge dismisses it. Default true. */
+	isSwipeDismissible?: boolean;
+};
+
+/** Moves VoiceOver / TalkBack focus to a mounted element. A no-op when it has gone. */
+function focus(target: DrawerFocusTarget | null): void {
+	if (target === null) return;
+	const handle = findNodeHandle(target as Parameters<typeof findNodeHandle>[0]);
+	if (handle !== null) AccessibilityInfo.setAccessibilityFocus(handle);
+}
+
+/**
+ * The panel, its scrim and the portal they draw through.
+ *
+ * Renders nothing until the drawer opens, and stays mounted through the exit
+ * (`useOverlayPresence`), so the portal, the z-order and the back button all
+ * follow presence. It draws in the `modal` band — over the navigator's header
+ * and over an open bottom sheet.
+ *
+ * - **Geometry.** `side` resolves to a physical edge under `I18nManager.isRTL`;
+ *   `size` to an extent along that edge's axis. The panel pads the safe-area
+ *   insets on every side that meets a screen edge.
+ * - **Motion.** Opening and closing slide the panel along `progress`; under
+ *   reduce motion it fades in place instead. A swipe toward the edge drags it
+ *   and thins the scrim with it; see `useDrawerPan` for the release.
+ * - **Dismissal.** A scrim tap, Android back, the iOS escape gesture and the
+ *   swipe close a dismissible drawer. With `isDismissible={false}` the scrim
+ *   still takes the touch and only the drawer's own actions close it.
+ * - **Accessibility.** The panel is modal to assistive technology, a `dialog`
+ *   labelled by the title; focus moves to the title once it has entered and
+ *   back to the trigger, if still mounted, once it has gone.
+ *
+ * @example
+ * <Drawer.Content side="end" size="lg">
+ *   <Drawer.Header>…</Drawer.Header>
+ *   <Drawer.Body>…</Drawer.Body>
+ * </Drawer.Content>
+ */
+export function DrawerContent({
+	className,
+	scrimClassName,
+	side = "start",
+	size = "md",
+	isSwipeDismissible = true,
+	children,
+	style,
+	...props
+}: DrawerContentProps): ReactElement | null {
+	const { isOpen, close, isDismissible, titleId, titleRef, triggerRef } = useDrawerPart("Drawer.Content");
+	const id = useId();
+
+	const isRTL = I18nManager.isRTL;
+	const edge = resolveDrawerEdge(side, isRTL);
+	const isHorizontal = edge === "left" || edge === "right";
+	const window = useWindowDimensions();
+	const safeArea = useSafeAreaInsets();
+	const insets = resolveDrawerInsets(edge, safeArea);
+	const extent = resolveDrawerFrameExtent(
+		edge,
+		resolveDrawerExtent(size, isHorizontal ? window.width : window.height),
+		insets
+	);
+
+	const handleEntered = useCallback(() => focus(titleRef.current), [titleRef]);
+	const handleExited = useCallback(() => focus(triggerRef.current), [triggerRef]);
+	const { isPresent, isReduced, progress } = useOverlayPresence({
+		isOpen,
+		onEntered: handleEntered,
+		onExited: handleExited,
+	});
+
+	useOverlayBackHandler({ id, isEnabled: isPresent && isDismissible, onBack: close });
+
+	const drag = useSharedValue(0);
+	useEffect(() => {
+		if (isOpen) drag.value = 0;
+	}, [isOpen, drag]);
+
+	const pan = useDrawerPan({
+		drag,
+		edge,
+		extent,
+		isEnabled: isSwipeDismissible && isDismissible,
+		onDismiss: close,
+	});
+
+	// The scrim fades with presence and thins as a drag carries the panel out.
+	// A shared value of its own, because `Overlay.Scrim` takes a writable one.
+	const scrimProgress = useSharedValue(0);
+	useAnimatedReaction(
+		() => progress.value * (1 - resolveDrawerDragFraction(edge, drag.value, extent)),
+		(visibility) => {
+			scrimProgress.value = visibility;
+		},
+		[edge, extent]
+	);
+
+	const panelStyle = useAnimatedStyle(() => {
+		const slide = isReduced ? { translateX: 0, translateY: 0 } : resolveDrawerOffset(edge, extent, progress.value);
+		return {
+			opacity: isReduced ? progress.value : 1,
+			transform: [
+				{ translateX: slide.translateX + (isHorizontal ? drag.value : 0) },
+				{ translateY: slide.translateY + (isHorizontal ? 0 : drag.value) },
+			],
+		};
+	}, [edge, extent, isHorizontal, isReduced]);
+
+	const panel = useMemo<DrawerPanelValue>(() => ({ edge, side }), [edge, side]);
+
+	if (!isPresent) return null;
+
+	const slots = drawerVariants({ edge });
+	const onEscape = isDismissible ? close : undefined;
+	const frame = {
+		height: isHorizontal ? undefined : extent,
+		paddingBottom: insets.bottom,
+		paddingLeft: insets.left,
+		paddingRight: insets.right,
+		paddingTop: insets.top,
+		width: isHorizontal ? extent : undefined,
+	};
+
+	return (
+		<Overlay.Portal id={id} layer="modal">
+			<Overlay.Scrim
+				className={slots.scrim({ className: scrimClassName })}
+				onDismiss={onEscape}
+				progress={scrimProgress}
+			/>
+			<View className={slots.positioner()} pointerEvents="box-none" style={{ direction: "ltr" }}>
+				<GestureDetector gesture={pan}>
+					<Animated.View
+						accessibilityLabelledBy={titleId}
+						accessibilityViewIsModal
+						className={slots.content({ className })}
+						onAccessibilityEscape={onEscape}
+						role="dialog"
+						style={[frame, panelStyle, style]}
+						{...props}
+					>
+						<View className={slots.inner()} style={{ direction: isRTL ? "rtl" : "ltr" }}>
+							<DrawerPanelProvider value={panel}>{children}</DrawerPanelProvider>
+						</View>
+					</Animated.View>
+				</GestureDetector>
+			</View>
+		</Overlay.Portal>
+	);
+}
+DrawerContent.displayName = "DelacourUI.Drawer.Content";

package/src/components/drawer/drawer-description.tsx

@@ -0,0 +1,23 @@
+import type { ReactElement } from "react";
+import { cn } from "../../lib/cn";
+import { Text, type TextPresetProps } from "../text";
+import { useDrawerPart } from "./drawer.context";
+
+export type DrawerDescriptionProps = TextPresetProps;
+
+/**
+ * Supporting copy under the title.
+ *
+ * *Is* a `Text.Paragraph`, muted by default so the title and this read as a
+ * hierarchy. `color` is an ordinary prop. It has no slot in `drawerVariants` —
+ * see the note there.
+ *
+ * @example
+ * <Drawer.Description>Signed in as aria@harbour.studio</Drawer.Description>
+ */
+export function DrawerDescription({ className, color = "muted", ...props }: DrawerDescriptionProps): ReactElement {
+	const { descriptionId } = useDrawerPart("Drawer.Description");
+
+	return <Text.Paragraph className={cn(className)} color={color} nativeID={descriptionId} {...props} />;
+}
+DrawerDescription.displayName = "DelacourUI.Drawer.Description";

package/src/components/drawer/drawer-footer.tsx

@@ -0,0 +1,21 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { drawerVariants } from "./drawer.variants";
+
+export type DrawerFooterProps = ViewProps & { className?: string };
+
+/**
+ * Actions at the panel's far end, under a hairline: a row, right-aligned in a
+ * left-to-right layout. It pushes itself to the panel's end with `mt-auto`, so
+ * it sits at the bottom however short the content is — with or without a body.
+ *
+ * @example
+ * <Drawer.Footer>
+ *   <Button variant="secondary" onPress={reset}>Reset</Button>
+ *   <Drawer.Close asChild><Button>Show results</Button></Drawer.Close>
+ * </Drawer.Footer>
+ */
+export function DrawerFooter({ className, ...props }: DrawerFooterProps): ReactElement {
+	return <View className={drawerVariants().footer({ className })} {...props} />;
+}
+DrawerFooter.displayName = "DelacourUI.Drawer.Footer";

package/src/components/drawer/drawer-header.tsx

@@ -0,0 +1,42 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { drawerVariants } from "./drawer.variants";
+import { DrawerClose } from "./drawer-close";
+
+export type DrawerHeaderProps = ViewProps & {
+	className?: string;
+	/** Hide the ✕ the header writes at its trailing edge. Default false. */
+	isCloseHidden?: boolean;
+};
+
+/**
+ * The top of the panel: `Drawer.Title` and `Drawer.Description` in a column
+ * that takes the row's slack, and a ✕ at the trailing edge.
+ *
+ * The ✕ is in the flow, not pinned to a corner, so a long title wraps before
+ * it rather than under it, and it lands on the correct side under RTL with no
+ * rule of its own. `isCloseHidden` drops it — a navigation drawer whose rows
+ * all close it, or a drawer with a `Close` in its footer.
+ *
+ * @example
+ * <Drawer.Header>
+ *   <Drawer.Title>Filters</Drawer.Title>
+ *   <Drawer.Description>12 results</Drawer.Description>
+ * </Drawer.Header>
+ */
+export function DrawerHeader({
+	className,
+	isCloseHidden = false,
+	children,
+	...props
+}: DrawerHeaderProps): ReactElement {
+	const slots = drawerVariants();
+
+	return (
+		<View className={slots.header({ className })} {...props}>
+			<View className={slots.heading()}>{children}</View>
+			{isCloseHidden ? null : <DrawerClose />}
+		</View>
+	);
+}
+DrawerHeader.displayName = "DelacourUI.Drawer.Header";

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

@@ -0,0 +1,35 @@
+import { type ReactElement, useCallback } from "react";
+import { cn } from "../../lib/cn";
+import { Text, type TextPresetProps } from "../text";
+import { type DrawerFocusTarget, useDrawerPart } from "./drawer.context";
+
+/**
+ * A `Text.Header`'s props less `ref`: the drawer holds the title's ref itself,
+ * to move accessibility focus onto it.
+ */
+export type DrawerTitleProps = Omit<TextPresetProps, "ref">;
+
+/**
+ * The drawer's heading.
+ *
+ * *Is* a `Text.Header`. It carries the `nativeID` the panel is labelled by on
+ * Android, and it is where accessibility focus lands once the panel has
+ * finished entering, so a screen reader announces what the drawer is first.
+ *
+ * @example
+ * <Drawer.Title>Menu</Drawer.Title>
+ */
+export function DrawerTitle({ className, ...props }: DrawerTitleProps): ReactElement {
+	const { titleId, titleRef } = useDrawerPart("Drawer.Title");
+	const setTitleRef = useCallback(
+		(node: DrawerFocusTarget | null) => {
+			titleRef.current = node;
+		},
+		[titleRef]
+	);
+
+	return (
+		<Text.Header accessibilityRole="header" className={cn(className)} nativeID={titleId} ref={setTitleRef} {...props} />
+	);
+}
+DrawerTitle.displayName = "DelacourUI.Drawer.Title";

package/src/components/drawer/drawer-trigger.tsx

@@ -0,0 +1,54 @@
+import { type ReactElement, useCallback } from "react";
+import { composeRefs } from "../../lib/compose-refs";
+import { Slot } from "../../lib/slot";
+import { Pressable, type PressableProps } from "../pressable";
+import { useDrawerPart } from "./drawer.context";
+
+export type DrawerTriggerProps = PressableProps;
+
+/**
+ * The control that opens the drawer.
+ *
+ * On its own it is this library's `Pressable`. **`asChild` donates the press
+ * rather than wrapping the child**, the way `BottomSheet.Trigger` does: two tap
+ * gestures in an ancestor/descendant pair are not simultaneous, so a `Button`
+ * wrapped in a pressable trigger would win the touch and the drawer would never
+ * open. With `asChild` the open is chained ahead of the child's own `onPress`.
+ *
+ * The trigger's ref is kept so accessibility focus can return to it when the
+ * drawer closes.
+ *
+ * @example
+ * <Drawer.Trigger asChild>
+ *   <Button accessibilityLabel="Menu" size="icon-md" variant="ghost">
+ *     <Icon icon={IconMenu} />
+ *   </Button>
+ * </Drawer.Trigger>
+ */
+export function DrawerTrigger({ asChild = false, children, onPress, ref, ...props }: DrawerTriggerProps): ReactElement {
+	const { setOpen, triggerRef } = useDrawerPart("Drawer.Trigger");
+
+	const handlePress = useCallback(() => {
+		setOpen(true);
+		onPress?.();
+	}, [setOpen, onPress]);
+
+	const composedRef = composeRefs(ref, (node) => {
+		triggerRef.current = node;
+	});
+
+	if (asChild) {
+		return (
+			<Slot onPress={handlePress} ref={composedRef} {...props}>
+				{children}
+			</Slot>
+		);
+	}
+
+	return (
+		<Pressable accessibilityRole="button" onPress={handlePress} ref={composedRef} {...props}>
+			{children}
+		</Pressable>
+	);
+}
+DrawerTrigger.displayName = "DelacourUI.Drawer.Trigger";

package/src/components/drawer/drawer.context.tsx

@@ -0,0 +1,114 @@
+import { createContext, type ReactElement, type ReactNode, type RefObject, use } from "react";
+import { I18nManager } from "react-native";
+import { type DrawerEdge, type DrawerSide, resolveDrawerEdge } from "./drawer.variants";
+
+/** Anything `AccessibilityInfo.setAccessibilityFocus` can be pointed at through `findNodeHandle`. */
+export type DrawerFocusTarget = object;
+
+export type DrawerContextValue = {
+	/** Whether the drawer is open — the owner's state, not the exit animation's. */
+	isOpen: boolean;
+	/** Opens or closes it. Reports through `onOpenChange` only when the value changes. */
+	setOpen: (isOpen: boolean) => void;
+	/** `setOpen(false)`, for an action inside the panel. */
+	close: () => void;
+	/** Whether the scrim, Android back and the iOS escape gesture close it. */
+	isDismissible: boolean;
+	/** The logical side `Drawer.Content` opens from. `"start"` outside the content. */
+	side: DrawerSide;
+	/** The physical edge that side resolves to under the layout direction. */
+	edge: DrawerEdge;
+};
+
+/** The root's state, before `Drawer.Content` adds its side. */
+export type DrawerRootValue = Omit<DrawerContextValue, "side" | "edge"> & {
+	/** The `nativeID` `Drawer.Title` carries and the panel is labelled by. */
+	titleId: string;
+	/** The `nativeID` `Drawer.Description` carries. */
+	descriptionId: string;
+	/** The trigger, so focus can return to it on close. */
+	triggerRef: RefObject<DrawerFocusTarget | null>;
+	/** The title, so focus can land on it on open. */
+	titleRef: RefObject<DrawerFocusTarget | null>;
+};
+
+/** The side and edge `Drawer.Content` resolved, for the parts inside it. */
+export type DrawerPanelValue = { side: DrawerSide; edge: DrawerEdge };
+
+const DrawerContext = createContext<DrawerRootValue | null>(null);
+
+const DrawerPanelContext = createContext<DrawerPanelValue>({
+	edge: resolveDrawerEdge("start", I18nManager.isRTL),
+	side: "start",
+});
+
+/**
+ * Supplies the drawer's state to its parts.
+ *
+ * Lives in its own module, importing nothing but `drawer.variants`, so a part
+ * can read it without importing `./drawer` — that import would close a cycle,
+ * and Metro serves a partially initialised module for one.
+ */
+export function DrawerProvider({ value, children }: { value: DrawerRootValue; children: ReactNode }): ReactElement {
+	return <DrawerContext value={value}>{children}</DrawerContext>;
+}
+DrawerProvider.displayName = "DelacourUI.Drawer.Provider";
+
+/** Supplies the resolved side and edge to the parts inside `Drawer.Content`. */
+export function DrawerPanelProvider({
+	value,
+	children,
+}: {
+	value: DrawerPanelValue;
+	children: ReactNode;
+}): ReactElement {
+	return <DrawerPanelContext value={value}>{children}</DrawerPanelContext>;
+}
+DrawerPanelProvider.displayName = "DelacourUI.Drawer.PanelProvider";
+
+/** The enclosing drawer's context, or null outside a `<Drawer>`. */
+export function useDrawerContext(): DrawerContextValue | null {
+	const root = use(DrawerContext);
+	const panel = use(DrawerPanelContext);
+	if (!root) return null;
+	return {
+		close: root.close,
+		edge: panel.edge,
+		isDismissible: root.isDismissible,
+		isOpen: root.isOpen,
+		setOpen: root.setOpen,
+		side: panel.side,
+	};
+}
+
+/**
+ * Reads the enclosing drawer's open state, its setter and — inside
+ * `Drawer.Content` — the side it opened from and the edge that resolved to.
+ *
+ * Lets a custom row close the drawer after it navigates, without the caller
+ * threading a setter down. Throws outside a `<Drawer>`.
+ */
+export function useDrawer(): DrawerContextValue {
+	const context = useDrawerContext();
+	if (!context) {
+		throw new Error("useDrawer must be called inside a <Drawer>.");
+	}
+	return context;
+}
+
+/**
+ * The root's full context, for a part that cannot work without one. Internal:
+ * not re-exported from `index.ts`.
+ */
+export function useDrawerPart(component: string): DrawerRootValue {
+	const context = use(DrawerContext);
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Drawer>.`);
+	}
+	return context;
+}
+
+/** The side and edge `Drawer.Content` resolved. */
+export function useDrawerPanel(): DrawerPanelValue {
+	return use(DrawerPanelContext);
+}