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

package/src/components/menu/menu-sub-trigger.tsx

@@ -0,0 +1,50 @@
+import type { ReactElement } from "react";
+import { I18nManager, View } from "react-native";
+import Animated, { interpolate, useAnimatedStyle } from "react-native-reanimated";
+import { IconChevronRight } from "../../icons/central";
+import { Icon } from "../icon";
+import { useMenuSubPart } from "./menu.context";
+import type { MenuItemProps } from "./menu.types";
+import { MENU_INDICATOR_TOKEN, MENU_SUB_ROTATION, menuVariants, resolveMenuItemAccessibility } from "./menu.variants";
+import { MenuRow } from "./menu-item";
+
+export type MenuSubTriggerProps = Omit<MenuItemProps, "onSelect" | "isClosedOnSelect" | "trailing">;
+
+/**
+ * The row that expands a `Menu.Sub`. Never closes the menu.
+ *
+ * Its chevron points to the trailing edge and turns 90° to point down as the
+ * rows open, off the submenu's own `progress`, so it and the height cannot drift.
+ * Under RTL the chevron is mirrored on a wrapper view, so it points left and
+ * still turns down. Announced as `expanded`.
+ */
+export function MenuSubTrigger({ isDisabled = false, ...props }: MenuSubTriggerProps): ReactElement {
+	const { isOpen, progress, toggle } = useMenuSubPart("Menu.SubTrigger");
+	const slots = menuVariants();
+	const collapsed = MENU_SUB_ROTATION.collapsed;
+	const expanded = MENU_SUB_ROTATION.expanded;
+
+	const rotationStyle = useAnimatedStyle(() => ({
+		transform: [{ rotate: `${interpolate(progress.value, [0, 1], [collapsed, expanded])}deg` }],
+	}));
+
+	return (
+		<MenuRow
+			accessibilityState={resolveMenuItemAccessibility({ isDisabled, isExpanded: isOpen, kind: "sub-trigger" })}
+			isDisabled={isDisabled}
+			kind="sub-trigger"
+			onSelect={toggle}
+			trailing={
+				<View className={slots.indicator()} style={I18nManager.isRTL ? mirrored : undefined}>
+					<Animated.View style={rotationStyle}>
+						<Icon className={slots.itemIcon()} color={MENU_INDICATOR_TOKEN} icon={IconChevronRight} />
+					</Animated.View>
+				</View>
+			}
+			{...props}
+		/>
+	);
+}
+MenuSubTrigger.displayName = "DelacourUI.Menu.SubTrigger";
+
+const mirrored = { transform: [{ scaleX: -1 }] };

package/src/components/menu/menu-sub.tsx

@@ -0,0 +1,75 @@
+import { type ReactElement, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { View } from "react-native";
+import { cancelAnimation, useSharedValue, withSpring } from "react-native-reanimated";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { type MenuSubContextValue, MenuSubProvider } from "./menu.context";
+import { MENU_SUB_SPRING } from "./menu.variants";
+
+export type MenuSubProps = {
+	children: ReactNode;
+	isOpen?: boolean;
+	defaultOpen?: boolean;
+	onOpenChange?: (isOpen: boolean) => void;
+};
+
+/**
+ * A nested group of rows that expands in place under its `Menu.SubTrigger`.
+ *
+ * It never flies out to a second panel: on a phone there is no room beside the
+ * first, and a second layer over the first hides where the user came from. The
+ * rows push the ones below down, with `Collapsible`'s measured height and spring.
+ *
+ * @example
+ * <Menu.Sub>
+ *   <Menu.SubTrigger icon={IconFolder1}>Move to</Menu.SubTrigger>
+ *   <Menu.SubContent>
+ *     <Menu.Item onSelect={moveToInbox}>Inbox</Menu.Item>
+ *   </Menu.SubContent>
+ * </Menu.Sub>
+ */
+export function MenuSub({
+	children,
+	isOpen: isOpenProp,
+	defaultOpen = false,
+	onOpenChange,
+}: MenuSubProps): ReactElement {
+	const changeRef = useRef(onOpenChange);
+	changeRef.current = onOpenChange;
+	const handleChange = useCallback((next: boolean) => changeRef.current?.(next), []);
+
+	const [isOpen, setOpen] = useControllableState<boolean>({
+		defaultValue: defaultOpen,
+		onChange: handleChange,
+		value: isOpenProp,
+	});
+
+	const openRef = useRef(isOpen);
+	openRef.current = isOpen;
+	const toggle = useCallback(() => setOpen(!openRef.current), [setOpen]);
+
+	const progress = useSharedValue(isOpen ? 1 : 0);
+	const contentHeight = useSharedValue(-1);
+
+	// React state, never a JS-thread read of `contentHeight` — the write is queued
+	// onto the UI runtime and a read straight after it can still see -1.
+	const [isMeasured, setMeasured] = useState(false);
+	const onMeasured = useCallback(() => setMeasured(true), []);
+
+	useEffect(() => {
+		if (isOpen && !isMeasured) return;
+		progress.value = withSpring(isOpen ? 1 : 0, MENU_SUB_SPRING);
+		return () => cancelAnimation(progress);
+	}, [isMeasured, isOpen, progress]);
+
+	const context = useMemo<MenuSubContextValue>(
+		() => ({ contentHeight, isOpen, onMeasured, progress, toggle }),
+		[contentHeight, isOpen, onMeasured, progress, toggle]
+	);
+
+	return (
+		<MenuSubProvider value={context}>
+			<View>{children}</View>
+		</MenuSubProvider>
+	);
+}
+MenuSub.displayName = "DelacourUI.Menu.Sub";

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

@@ -0,0 +1,57 @@
+import { type ComponentRef, type ReactElement, useCallback, useMemo } from "react";
+import type Animated from "react-native-reanimated";
+import { composeRefs } from "../../lib/compose-refs";
+import { Slot } from "../../lib/slot";
+import { Pressable, type PressableProps } from "../pressable";
+import { type MenuMeasurable, useMenuPart } from "./menu.context";
+import { MENU_TRIGGER_HINT } from "./menu.variants";
+
+export type MenuTriggerProps = PressableProps & { asChild?: boolean };
+
+/**
+ * The control that opens the menu, and closes it again.
+ *
+ * A press measures the trigger with `measureInWindow`, anchors the panel to
+ * that rect and opens. Announced `expanded` while open, with the hint
+ * "Opens a menu".
+ *
+ * **`asChild` donates the press rather than wrapping the child**, as
+ * `BottomSheet.Trigger` does: two nested taps are not simultaneous, and Gesture
+ * Handler gives the touch to the descendant — a `Button` wrapped in a pressable
+ * trigger would win the tap and the menu would never open. The child receives
+ * `onPress` (chained ahead of its own), the ref the trigger measures, and the
+ * accessibility props, through `Slot`. So the child has to be something that
+ * handles `onPress` — a `Button`, a `ListGroup.Item`, anything on `Pressable`.
+ *
+ * @example
+ * <Menu.Trigger asChild>
+ *   <Button variant="outline">Options</Button>
+ * </Menu.Trigger>
+ */
+export function MenuTrigger({ asChild = false, children, onPress, ref, ...props }: MenuTriggerProps): ReactElement {
+	const { isOpen, toggle, triggerRef } = useMenuPart("Menu.Trigger");
+
+	const handlePress = useCallback(() => {
+		toggle();
+		onPress?.();
+	}, [onPress, toggle]);
+
+	const setTrigger = useCallback(
+		(node: ComponentRef<typeof Animated.View> | null) => {
+			triggerRef.current = node as MenuMeasurable | null;
+		},
+		[triggerRef]
+	);
+	const composedRef = useMemo(() => composeRefs(ref, setTrigger), [ref, setTrigger]);
+
+	const shared = {
+		accessibilityHint: MENU_TRIGGER_HINT,
+		accessibilityState: { expanded: isOpen },
+		onPress: handlePress,
+		ref: composedRef,
+		...props,
+	};
+
+	return asChild ? <Slot {...shared}>{children}</Slot> : <Pressable {...shared}>{children}</Pressable>;
+}
+MenuTrigger.displayName = "DelacourUI.Menu.Trigger";

package/src/components/menu/menu.context.tsx

@@ -0,0 +1,214 @@
+import {
+	createContext,
+	type ReactElement,
+	type ReactNode,
+	type RefObject,
+	use,
+	useCallback,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+import type { View } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import type { HapticFeedback } from "../pressable/pressable";
+import type { MenuAnchorRect } from "./menu.variants";
+
+/** Anything `measureInWindow` can be called on — a host view, or an animated one. */
+export type MenuMeasurable = Pick<View, "measureInWindow">;
+
+export type MenuContextValue = {
+	isOpen: boolean;
+	/** Where the panel is anchored, set on open. `null` until the first open. */
+	anchor: MenuAnchorRect | null;
+	/**
+	 * Opens the menu. With an `anchor` it opens there — ContextMenu passes a
+	 * zero-size point. Without one it measures the trigger first.
+	 */
+	open: (anchor?: MenuAnchorRect) => void;
+	close: () => void;
+	/** Closes an open menu, opens a closed one from the trigger. */
+	toggle: () => void;
+	/** The trigger's node, measured on open. */
+	triggerRef: RefObject<MenuMeasurable | null>;
+	/** Played when a row is chosen. */
+	haptic: false | HapticFeedback;
+};
+
+const MenuContext = createContext<MenuContextValue | null>(null);
+
+/**
+ * The menu's state provider.
+ *
+ * Exported so ContextMenu can drive the open state with an anchor of its own:
+ * build a value with {@link useMenuRootValue} and wrap `Menu.Content` in this,
+ * without importing the `Menu` root at all.
+ */
+export function MenuRootProvider({ value, children }: { value: MenuContextValue; children: ReactNode }): ReactElement {
+	return <MenuContext value={value}>{children}</MenuContext>;
+}
+MenuRootProvider.displayName = "DelacourUI.Menu.RootProvider";
+
+/** The menu's open state and controls, for a custom part. Throws outside a menu. */
+export function useMenu(): Pick<MenuContextValue, "isOpen" | "open" | "close"> {
+	const { isOpen, open, close } = useMenuPart("useMenu");
+	return { close, isOpen, open };
+}
+
+/** The whole context, for the menu's own parts. Throws with the part's name outside a menu. */
+export function useMenuPart(part: string): MenuContextValue {
+	const context = use(MenuContext);
+	if (!context) throw new Error(`${part} must be used inside a <Menu>.`);
+	return context;
+}
+
+export type UseMenuRootValueOptions = {
+	isOpen?: boolean;
+	defaultOpen?: boolean;
+	onOpenChange?: (isOpen: boolean) => void;
+	haptic?: false | HapticFeedback;
+};
+
+/**
+ * Builds a menu's context value: the controllable open state, the anchor, and
+ * the trigger measurement.
+ *
+ * The root calls it; ContextMenu calls it too, and opens with `open(point)`.
+ * Callbacks are ref-backed, so the value keeps its identity across a caller
+ * passing a fresh `onOpenChange` every render.
+ */
+export function useMenuRootValue({
+	isOpen: isOpenProp,
+	defaultOpen = false,
+	onOpenChange,
+	haptic = false,
+}: UseMenuRootValueOptions): MenuContextValue {
+	const changeRef = useRef(onOpenChange);
+	changeRef.current = onOpenChange;
+	const handleChange = useCallback((next: boolean) => changeRef.current?.(next), []);
+
+	const [isOpen, setOpen] = useControllableState<boolean>({
+		defaultValue: defaultOpen,
+		onChange: handleChange,
+		value: isOpenProp,
+	});
+
+	const [anchor, setAnchor] = useState<MenuAnchorRect | null>(null);
+	const triggerRef = useRef<MenuMeasurable | null>(null);
+
+	const openRef = useRef(isOpen);
+	openRef.current = isOpen;
+
+	// Set by `open()` so the effect below can tell an open it asked for from one a
+	// controlling parent made by flipping `isOpen` — which still needs a measurement.
+	const isOpeningRef = useRef(false);
+
+	const measureTrigger = useCallback((then?: () => void) => {
+		const node = triggerRef.current;
+		if (!node || typeof node.measureInWindow !== "function") {
+			then?.();
+			return;
+		}
+
+		node.measureInWindow((x, y, width, height) => {
+			setAnchor({ height, width, x, y });
+			then?.();
+		});
+	}, []);
+
+	const open = useCallback(
+		(next?: MenuAnchorRect) => {
+			const show = () => {
+				if (openRef.current) return;
+				isOpeningRef.current = true;
+				setOpen(true);
+			};
+
+			if (next) {
+				setAnchor(next);
+				show();
+				return;
+			}
+
+			measureTrigger(show);
+		},
+		[measureTrigger, setOpen]
+	);
+
+	useEffect(() => {
+		if (!isOpen) return;
+		if (isOpeningRef.current) {
+			isOpeningRef.current = false;
+			return;
+		}
+		measureTrigger();
+	}, [isOpen, measureTrigger]);
+
+	const close = useCallback(() => {
+		if (openRef.current) setOpen(false);
+	}, [setOpen]);
+
+	const toggle = useCallback(() => {
+		if (openRef.current) close();
+		else open();
+	}, [close, open]);
+
+	return useMemo<MenuContextValue>(
+		() => ({ anchor, close, haptic, isOpen, open, toggle, triggerRef }),
+		[anchor, close, haptic, isOpen, open, toggle]
+	);
+}
+
+export type MenuSubContextValue = {
+	isOpen: boolean;
+	toggle: () => void;
+	/** The submenu's travel, 0 closed to 1 open. The chevron and the clip both read it. */
+	progress: SharedValue<number>;
+	contentHeight: SharedValue<number>;
+	onMeasured: () => void;
+};
+
+const MenuSubContext = createContext<MenuSubContextValue | null>(null);
+
+export function MenuSubProvider({
+	value,
+	children,
+}: {
+	value: MenuSubContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <MenuSubContext value={value}>{children}</MenuSubContext>;
+}
+MenuSubProvider.displayName = "DelacourUI.Menu.SubProvider";
+
+export function useMenuSubPart(part: string): MenuSubContextValue {
+	const context = use(MenuSubContext);
+	if (!context) throw new Error(`${part} must be used inside a <Menu.Sub>.`);
+	return context;
+}
+
+export type MenuRadioGroupContextValue = {
+	value: string | undefined;
+	select: (value: string) => void;
+};
+
+const MenuRadioGroupContext = createContext<MenuRadioGroupContextValue | null>(null);
+
+export function MenuRadioGroupProvider({
+	value,
+	children,
+}: {
+	value: MenuRadioGroupContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <MenuRadioGroupContext value={value}>{children}</MenuRadioGroupContext>;
+}
+MenuRadioGroupProvider.displayName = "DelacourUI.Menu.RadioGroupProvider";
+
+export function useMenuRadioGroupPart(part: string): MenuRadioGroupContextValue {
+	const context = use(MenuRadioGroupContext);
+	if (!context) throw new Error(`${part} must be used inside a <Menu.RadioGroup>.`);
+	return context;
+}

package/src/components/menu/menu.tsx

@@ -0,0 +1,88 @@
+import type { ReactElement, ReactNode } from "react";
+import type { HapticFeedback } from "../pressable/pressable";
+import { MenuRootProvider, useMenuRootValue } from "./menu.context";
+import { MenuBackground } from "./menu-background";
+import { MenuCheckboxItem } from "./menu-checkbox-item";
+import { MenuContent } from "./menu-content";
+import { MenuItem } from "./menu-item";
+import { MenuLabel } from "./menu-label";
+import { MenuRadioGroup } from "./menu-radio-group";
+import { MenuRadioItem } from "./menu-radio-item";
+import { MenuSeparator } from "./menu-separator";
+import { MenuSub } from "./menu-sub";
+import { MenuSubContent } from "./menu-sub-content";
+import { MenuSubTrigger } from "./menu-sub-trigger";
+import { MenuTrigger } from "./menu-trigger";
+
+export type MenuProps = {
+	children: ReactNode;
+	/** Controlled open state. Leave it off and the menu holds its own. */
+	isOpen?: boolean;
+	/** Initial open state while uncontrolled. */
+	defaultOpen?: boolean;
+	onOpenChange?: (isOpen: boolean) => void;
+	/** Played when a row is chosen. Off by default. */
+	haptic?: false | HapticFeedback;
+};
+
+function MenuRoot({ children, isOpen, defaultOpen, onOpenChange, haptic }: MenuProps): ReactElement {
+	const value = useMenuRootValue({ defaultOpen, haptic, isOpen, onOpenChange });
+	return <MenuRootProvider value={value}>{children}</MenuRootProvider>;
+}
+
+/**
+ * A list of verbs dropped from the control that opens it — rename, duplicate,
+ * share, delete.
+ *
+ * A menu is not a select: a row runs an action, it does not become the
+ * trigger's value. The panel is anchored to the trigger, flips above it near
+ * the bottom of the screen, stays inside the safe area, and scrolls when the
+ * rows outgrow the room.
+ *
+ * Rows close the menu when chosen; `Menu.CheckboxItem` rows stay open, since
+ * several are usually toggled at once. `Menu.Sub` expands in place. An outside
+ * tap, Android's back button and a second press of the trigger all close it.
+ *
+ * State works either way from one hook: pass `isOpen` to control it, or leave
+ * it off. `onOpenChange` hears both. `useMenu()` hands a custom part
+ * `{ isOpen, open, close }`.
+ *
+ * @example
+ * <Menu>
+ *   <Menu.Trigger asChild>
+ *     <Button variant="outline">Options</Button>
+ *   </Menu.Trigger>
+ *   <Menu.Content>
+ *     <Menu.Item icon={IconPencil} onSelect={rename}>Rename</Menu.Item>
+ *     <Menu.Separator />
+ *     <Menu.Item icon={IconTrashCan} variant="destructive" onSelect={remove}>Delete</Menu.Item>
+ *   </Menu.Content>
+ * </Menu>
+ */
+export const Menu = Object.assign(MenuRoot, {
+	/** The control that opens and closes the menu. `asChild` donates the press to a `Button`. */
+	Trigger: MenuTrigger,
+	/** The anchored panel, in a transparent `Modal`. */
+	Content: MenuContent,
+	/** The panel's surface. Pass one as a `Menu.Content` child to repaint it. */
+	Background: MenuBackground,
+	/** A section heading. */
+	Label: MenuLabel,
+	/** A verb: runs `onSelect` and closes. */
+	Item: MenuItem,
+	/** A row that toggles a setting. Stays open. */
+	CheckboxItem: MenuCheckboxItem,
+	/** Holds the value for a set of radio rows. */
+	RadioGroup: MenuRadioGroup,
+	/** One option in a radio group. Closes. */
+	RadioItem: MenuRadioItem,
+	/** A rule between groups of rows. */
+	Separator: MenuSeparator,
+	/** Nested rows that expand in place. */
+	Sub: MenuSub,
+	/** The row that expands a `Menu.Sub`. */
+	SubTrigger: MenuSubTrigger,
+	/** The rows a `Menu.Sub` discloses. */
+	SubContent: MenuSubContent,
+	displayName: "DelacourUI.Menu",
+});

package/src/components/menu/menu.types.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import type { ViewProps } from "react-native";
+import type { IconComponent } from "../icon/icon";
+import type { MenuItemVariant } from "./menu.variants";
+
+/**
+ * What every row shares — an item, a checkbox row, a radio row and a sub-trigger.
+ *
+ * Built on `ViewProps` rather than `PressableProps`: a row drives its own press
+ * fill on a tap of its own, so `feedback`, `asChild` and the pressable's other
+ * knobs would be props it accepts and ignores.
+ */
+export type MenuItemProps = Omit<ViewProps, "children" | "style"> & {
+	/** The label. A string is wrapped in a `Text` on the row's type. */
+	children: ReactNode;
+	className?: string;
+	icon?: IconComponent;
+	/** Which side the icon sits on. Default `leading`. */
+	iconPlacement?: "leading" | "trailing";
+	/** A second, quieter line under the label. */
+	description?: string;
+	/** A key hint drawn at the row's end, e.g. `⌘R`. */
+	shortcut?: string;
+	/** Anything else drawn at the row's end. */
+	trailing?: ReactNode;
+	variant?: MenuItemVariant;
+	/** Reserve the icon column with no icon, so the label lines up with rows that have one. */
+	isInset?: boolean;
+	isDisabled?: boolean;
+	/** Whether choosing the row closes the menu. Default `true`. */
+	isClosedOnSelect?: boolean;
+	onSelect?: () => void;
+};