@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/menu/menu.tsx

@@ -0,0 +1,289 @@
+// ─── MD3 Expressive Menu — Root (Menu, MenuTrigger, MenuContent) ─────────────
+import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+import { AnimatePresence, m } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { MENU_CONTAINER_VARIANTS } from "./menu-animations";
+import { MenuProvider, useMenuContext } from "./menu-context";
+import {
+	BASELINE_COLORS,
+	MENU_CONTAINER_SHAPE,
+	MENU_GROUP_GAP,
+	MENU_MAX_WIDTH,
+	MENU_MIN_WIDTH,
+	MENU_POPUP_PADDING_Y,
+	STANDARD_COLORS,
+	VIBRANT_COLORS,
+} from "./menu-tokens";
+import type {
+	MenuContentProps,
+	MenuGroupProps,
+	MenuProps,
+	MenuTriggerProps,
+} from "./menu-types";
+
+// ─── Menu (Root) ──────────────────────────────────────────────────────────────
+
+/**
+ * MD3 Expressive Menu root component.
+ *
+ * Wraps Radix `DropdownMenu.Root` and provides `MenuContext` with `colorVariant`
+ * and `open` state to all descendant MenuItem and MenuGroup components.
+ *
+ * @example
+ * <Menu colorVariant="standard">
+ *   <MenuTrigger asChild>
+ *     <IconButton name="more_vert" />
+ *   </MenuTrigger>
+ *   <MenuContent>
+ *     <MenuGroup index={0} count={2}>
+ *       <MenuItem>Cut</MenuItem>
+ *       <MenuItem>Copy</MenuItem>
+ *     </MenuGroup>
+ *     <MenuGroup index={1} count={2}>
+ *       <MenuItem>Paste</MenuItem>
+ *     </MenuGroup>
+ *   </MenuContent>
+ * </Menu>
+ */
+export function Menu({
+	children,
+	variant,
+	menuVariant,
+	colorVariant = "standard",
+	open: controlledOpen,
+	onOpenChange: controlledOnOpenChange,
+	defaultOpen,
+	...props
+}: MenuProps &
+	Omit<React.ComponentPropsWithoutRef<typeof DropdownMenu.Root>, "children">) {
+	// Support deprecated menuVariant prop
+	const resolvedVariant = variant ?? menuVariant ?? "baseline";
+
+	// Support both controlled and uncontrolled open state.
+	// Initialize internalOpen from defaultOpen so that `defaultOpen={true}` works.
+	const [internalOpen, setInternalOpen] = React.useState(
+		() => defaultOpen ?? false,
+	);
+	const isControlled = controlledOpen !== undefined;
+	const open = isControlled ? controlledOpen : internalOpen;
+
+	const handleOpenChange = React.useCallback(
+		(next: boolean) => {
+			if (!isControlled) setInternalOpen(next);
+			controlledOnOpenChange?.(next);
+		},
+		[isControlled, controlledOnOpenChange],
+	);
+
+	return (
+		<MenuProvider
+			variant={resolvedVariant}
+			colorVariant={colorVariant}
+			open={open}
+			onOpenChange={handleOpenChange}
+		>
+			<DropdownMenu.Root
+				{...props}
+				defaultOpen={defaultOpen}
+				open={isControlled ? open : undefined}
+				onOpenChange={handleOpenChange}
+			>
+				{children}
+			</DropdownMenu.Root>
+		</MenuProvider>
+	);
+}
+Menu.displayName = "Menu";
+
+// ─── MenuTrigger ──────────────────────────────────────────────────────────────
+
+/**
+ * The trigger element that opens/closes the Menu.
+ *
+ * Use `asChild` to merge trigger behavior with your own element (e.g. a Button or IconButton).
+ */
+export const MenuTrigger = React.forwardRef<
+	React.ComponentRef<typeof DropdownMenu.Trigger>,
+	MenuTriggerProps & React.ComponentPropsWithoutRef<typeof DropdownMenu.Trigger>
+>(({ children, asChild = true, ...props }, ref) => (
+	<DropdownMenu.Trigger ref={ref} asChild={asChild} {...props}>
+		{children}
+	</DropdownMenu.Trigger>
+));
+MenuTrigger.displayName = "MenuTrigger";
+
+// ─── MenuContent (popup panel) ────────────────────────────────────────────────
+
+/**
+ * The popup container for the menu's contents.
+ *
+ * Renders into a portal. Uses Radix `forceMount` + Framer Motion `AnimatePresence`
+ * so the exit animation (scale + opacity via FastEffects) plays before the portal
+ * unmounts. The `open` state is read from `MenuContext`.
+ *
+ * Transform-origin is automatically set via the Radix CSS variable
+ * `--radix-dropdown-menu-content-transform-origin`.
+ *
+ * @param hasOverflow - Set true when using SubMenu to prevent clipping
+ */
+export const MenuContent = React.forwardRef<
+	React.ComponentRef<typeof DropdownMenu.Content>,
+	MenuContentProps &
+		Omit<React.ComponentPropsWithoutRef<typeof DropdownMenu.Content>, "asChild">
+>(
+	(
+		{
+			children,
+			sideOffset = 6,
+			side = "bottom",
+			align = "start",
+			hasOverflow = false,
+			colorVariant: propColorVariant,
+			separatorStyle = "gap",
+			className,
+			...props
+		},
+		ref,
+	) => {
+		const {
+			open,
+			variant,
+			colorVariant: contextColorVariant,
+		} = useMenuContext();
+		const colorVariant = propColorVariant ?? contextColorVariant;
+
+		// Baseline always uses baseline colors; expressive uses colorVariant
+		const colors =
+			variant === "baseline"
+				? BASELINE_COLORS
+				: colorVariant === "vibrant"
+					? VIBRANT_COLORS
+					: STANDARD_COLORS;
+
+		const isExpressiveGap =
+			variant === "expressive" && separatorStyle === "gap";
+
+		// Expressive variant: large rounded container with elevation (unless gap variant)
+		// Baseline variant: CornerExtraSmall (4px) container
+		const containerClassName =
+			variant === "expressive"
+				? cn(
+						"z-50 flex flex-col",
+						MENU_MIN_WIDTH,
+						MENU_MAX_WIDTH,
+						isExpressiveGap ? MENU_GROUP_GAP : "",
+						isExpressiveGap ? "bg-transparent" : colors.containerBg,
+						isExpressiveGap ? "" : "rounded-2xl",
+						isExpressiveGap ? "" : "elevation-2",
+						hasOverflow || isExpressiveGap
+							? "overflow-visible"
+							: "overflow-hidden",
+						"outline-none",
+						className,
+					)
+				: cn(
+						"z-50 flex flex-col",
+						MENU_MIN_WIDTH,
+						MENU_MAX_WIDTH,
+						MENU_POPUP_PADDING_Y,
+						MENU_GROUP_GAP,
+						colors.containerBg,
+						MENU_CONTAINER_SHAPE,
+						"elevation-2",
+						hasOverflow ? "overflow-visible" : "overflow-hidden",
+						"outline-none",
+						className,
+					);
+
+		// Helper to recursively flatten fragments
+		const flattenChildren = (nodes: React.ReactNode): React.ReactElement[] => {
+			return React.Children.toArray(nodes).reduce(
+				(acc: React.ReactElement[], child) => {
+					if (React.isValidElement(child)) {
+						if (child.type === React.Fragment) {
+							return acc.concat(
+								flattenChildren(
+									(child as React.ReactElement<{ children?: React.ReactNode }>)
+										.props.children,
+								),
+							);
+						}
+						acc.push(child as React.ReactElement);
+					}
+					return acc;
+				},
+				[],
+			);
+		};
+
+		let renderedChildren: React.ReactNode = children;
+
+		if (variant === "expressive") {
+			const validChildren = flattenChildren(children);
+			const groupCount = validChildren.length;
+
+			const enhancedChildren = validChildren.map((child, i) =>
+				React.cloneElement(child as React.ReactElement<MenuGroupProps>, {
+					index: i,
+					count: groupCount,
+					isGapVariant: isExpressiveGap,
+				}),
+			);
+
+			renderedChildren =
+				separatorStyle === "divider"
+					? enhancedChildren.reduce<React.ReactNode[]>((acc, child, i) => {
+							if (i > 0) {
+								acc.push(
+									<hr
+										key={`divider-${(child as React.ReactElement).key || i}`}
+										className={cn(
+											"mx-3 my-0.5 h-px border-0 bg-m3-outline-variant",
+										)}
+									/>,
+								);
+							}
+							acc.push(child);
+							return acc;
+						}, [])
+					: enhancedChildren;
+		}
+
+		return (
+			<AnimatePresence>
+				{open && (
+					<DropdownMenu.Portal forceMount>
+						<DropdownMenu.Content
+							ref={ref}
+							sideOffset={sideOffset}
+							side={side}
+							align={align}
+							asChild
+							forceMount
+							{...props}
+						>
+							<m.div
+								role="menu"
+								aria-orientation="vertical"
+								className={containerClassName}
+								variants={MENU_CONTAINER_VARIANTS}
+								initial="hidden"
+								animate="visible"
+								exit="exit"
+								style={{
+									...(props.style as React.CSSProperties),
+									transformOrigin:
+										"var(--radix-dropdown-menu-content-transform-origin)",
+								}}
+							>
+								{renderedChildren}
+							</m.div>
+						</DropdownMenu.Content>
+					</DropdownMenu.Portal>
+				)}
+			</AnimatePresence>
+		);
+	},
+);
+MenuContent.displayName = "MenuContent";

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

@@ -0,0 +1,223 @@
+// ─── MD3 Expressive Menu — SubMenu ───────────────────────────────────────────
+// Nested sub-menu triggered by hover/keyboard on a MenuItem
+import * as ContextMenu from "@radix-ui/react-context-menu";
+import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+import { AnimatePresence, m } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { Icon } from "../icon";
+import { SUBMENU_CONTAINER_VARIANTS } from "./menu-animations";
+import { useMenuContext } from "./menu-context";
+import {
+	BASELINE_COLORS,
+	MENU_CONTAINER_SHAPE,
+	MENU_GROUP_GAP,
+	MENU_MAX_WIDTH,
+	MENU_MIN_WIDTH,
+	MENU_POPUP_PADDING_Y,
+	STANDARD_COLORS,
+	VIBRANT_COLORS,
+} from "./menu-tokens";
+import type {
+	MenuColorVariant,
+	MenuItemProps,
+	SubMenuProps,
+} from "./menu-types";
+
+/**
+ * A nested SubMenu that opens from a trigger MenuItem.
+ *
+ * Keyboard: ArrowRight opens, ArrowLeft/Escape closes (handled by Radix).
+ * The parent MenuContent should set `hasOverflow={true}` when SubMenus are used.
+ *
+ * ### Hover delays
+ * `hoverOpenDelay` (default: 200ms) — time before the submenu opens on hover.
+ * `hoverCloseDelay` (default: 300ms) — time before the submenu closes after pointer-leave.
+ * These delays allow the user to safely move diagonally from trigger to submenu content
+ * without accidental close (safe polygon behavior from Radix still applies).
+ *
+ * @example
+ * <MenuContent hasOverflow>
+ *   <SubMenu
+ *     trigger={
+ *       <MenuItem trailingIcon={<Icon name="chevron_right" size={20} />}>
+ *         Share
+ *       </MenuItem>
+ *     }
+ *   >
+ *     <MenuItem>Via Email</MenuItem>
+ *     <MenuItem>Via Link</MenuItem>
+ *   </SubMenu>
+ * </MenuContent>
+ */
+export function SubMenu({
+	children,
+	trigger,
+	side = "right",
+	colorVariant: propColorVariant,
+	hoverOpenDelay = 200,
+	hoverCloseDelay = 300,
+}: SubMenuProps) {
+	const { colorVariant: contextColorVariant, menuPrimitive } = useMenuContext();
+	const colorVariant = propColorVariant ?? contextColorVariant;
+
+	// Controlled open state for hover delay support.
+	// Note: We use Radix's controlled mode carefully — Radix still handles keyboard
+	// and the safe polygon logic internally when we pass open/onOpenChange.
+	const [open, setOpen] = React.useState(false);
+	const openTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+	const closeTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(
+		null,
+	);
+
+	const clearTimers = React.useCallback(() => {
+		if (openTimerRef.current) clearTimeout(openTimerRef.current);
+		if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
+	}, []);
+
+	const handleTriggerPointerEnter = React.useCallback(() => {
+		clearTimers();
+		openTimerRef.current = setTimeout(() => setOpen(true), hoverOpenDelay);
+	}, [hoverOpenDelay, clearTimers]);
+
+	const handleTriggerPointerLeave = React.useCallback(() => {
+		clearTimers();
+		closeTimerRef.current = setTimeout(() => setOpen(false), hoverCloseDelay);
+	}, [hoverCloseDelay, clearTimers]);
+
+	const handleContentPointerEnter = React.useCallback(() => {
+		// Keep open when pointer moves into the submenu content
+		clearTimers();
+	}, [clearTimers]);
+
+	const handleContentPointerLeave = React.useCallback(() => {
+		clearTimers();
+		closeTimerRef.current = setTimeout(() => setOpen(false), hoverCloseDelay);
+	}, [hoverCloseDelay, clearTimers]);
+
+	// Cleanup timers on unmount
+	React.useEffect(() => () => clearTimers(), [clearTimers]);
+
+	// Select the correct Radix Sub primitives based on which menu family is active.
+	const Sub = menuPrimitive === "context" ? ContextMenu.Sub : DropdownMenu.Sub;
+	const SubTrigger =
+		menuPrimitive === "context"
+			? ContextMenu.SubTrigger
+			: DropdownMenu.SubTrigger;
+	const SubContent =
+		menuPrimitive === "context"
+			? ContextMenu.SubContent
+			: DropdownMenu.SubContent;
+	const Portal =
+		menuPrimitive === "context" ? ContextMenu.Portal : DropdownMenu.Portal;
+
+	return (
+		<Sub open={open} onOpenChange={setOpen}>
+			{/* SubTrigger renders its own element (no asChild) so it can correctly
+			 * compute the bounding box for SubContent positioning. */}
+			<SubTrigger
+				className="w-full outline-none"
+				onPointerEnter={handleTriggerPointerEnter}
+				onPointerLeave={handleTriggerPointerLeave}
+			>
+				{React.isValidElement(trigger)
+					? React.cloneElement(trigger as React.ReactElement<MenuItemProps>, {
+							isSubTrigger: true,
+							// Auto-add chevron if missing
+							trailingIcon: (trigger.props as MenuItemProps).trailingIcon || (
+								<Icon name="chevron_right" size={20} />
+							),
+						})
+					: trigger}
+			</SubTrigger>
+
+			{/* SubMenu popup */}
+			<AnimatePresence>
+				{open && (
+					<Portal forceMount>
+						<SubContent
+							sideOffset={4}
+							alignOffset={-4}
+							forceMount
+							className="outline-none"
+						>
+							<SubMenuContent
+								side={side}
+								colorVariant={colorVariant}
+								onPointerEnter={handleContentPointerEnter}
+								onPointerLeave={handleContentPointerLeave}
+							>
+								{children}
+							</SubMenuContent>
+						</SubContent>
+					</Portal>
+				)}
+			</AnimatePresence>
+		</Sub>
+	);
+}
+SubMenu.displayName = "SubMenu";
+
+/**
+ * Inner wrapper to handle animations.
+ */
+function SubMenuContent({
+	children,
+	side,
+	colorVariant: propColorVariant,
+	onPointerEnter,
+	onPointerLeave,
+}: {
+	children: React.ReactNode;
+	side: "left" | "right";
+	colorVariant?: MenuColorVariant;
+	onPointerEnter?: React.PointerEventHandler<HTMLDivElement>;
+	onPointerLeave?: React.PointerEventHandler<HTMLDivElement>;
+}) {
+	const { menuVariant, colorVariant: contextColorVariant } = useMenuContext();
+	const colorVariant = propColorVariant ?? contextColorVariant;
+	const colors =
+		menuVariant === "baseline"
+			? BASELINE_COLORS
+			: colorVariant === "vibrant"
+				? VIBRANT_COLORS
+				: STANDARD_COLORS;
+
+	return (
+		<m.div
+			role="menu"
+			aria-orientation="vertical"
+			onPointerEnter={onPointerEnter}
+			onPointerLeave={onPointerLeave}
+			className={cn(
+				"z-50 flex flex-col",
+				// Width constraints
+				MENU_MIN_WIDTH,
+				MENU_MAX_WIDTH,
+				// Vertical padding: 8dp
+				MENU_POPUP_PADDING_Y,
+				// Gap between groups: 2dp
+				MENU_GROUP_GAP,
+				// Container background
+				colors.containerBg,
+				// Container shape: CornerExtraSmall (4px)
+				MENU_CONTAINER_SHAPE,
+				// Elevation-2 shadow
+				"elevation-2",
+				// Overflow clip
+				"overflow-hidden",
+				"outline-none",
+			)}
+			variants={SUBMENU_CONTAINER_VARIANTS}
+			initial="hidden"
+			animate="visible"
+			exit="exit"
+			style={{
+				transformOrigin: side === "right" ? "top left" : "top right",
+			}}
+		>
+			{children}
+		</m.div>
+	);
+}
+SubMenuContent.displayName = "SubMenuContent";