@bug-on/md3-react 2.0.2 → 3.0.0

package/src/ui/menu/menu-animations.ts

@@ -0,0 +1,102 @@
+// ─── MD3 Expressive Menu — Framer Motion Animation Variants ──────────────────
+// FastSpatial: mirrors MotionSchemeKeyTokens.FastSpatial
+//   Android: spring(stiffness=380, dampingRatio=0.7)
+//   Framer:  damping = 2 × 0.7 × √(380 × 1) ≈ 27.3 → use 28
+// FastEffects: mirrors MotionSchemeKeyTokens.FastEffects
+//   Android: duration=150ms, FastOutLinearIn
+//   Framer:  duration=0.15, ease=[0.4, 0, 1, 1]
+
+import type { Transition, Variants } from "motion/react";
+
+// ─── Shared spring/easing specs ───────────────────────────────────────────────
+
+/** FastSpatial spring — used for shape morphing and spatial enter animations */
+export const FAST_SPATIAL_SPRING: Transition = {
+	type: "spring",
+	stiffness: 380,
+	damping: 28,
+	mass: 1,
+};
+
+/** FastEffects transition — used for opacity and exit animations */
+export const FAST_EFFECTS_TRANSITION: Transition = {
+	duration: 0.15,
+	ease: [0.4, 0, 1, 1], // FastOutLinearIn
+};
+
+// ─── Menu popup container ─────────────────────────────────────────────────────
+
+/**
+ * Enter/exit animation for the menu popup container.
+ * Scale from 0.8→1.0 with FastSpatial spring.
+ * Transform-origin is driven by the Radix CSS variable
+ * `--radix-dropdown-menu-content-transform-origin`.
+ */
+export const MENU_CONTAINER_VARIANTS: Variants = {
+	hidden: {
+		opacity: 0,
+		scale: 0.8,
+	},
+	visible: {
+		opacity: 1,
+		scale: 1,
+		transition: FAST_SPATIAL_SPRING,
+	},
+	exit: {
+		opacity: 0,
+		scale: 0.8,
+		transition: FAST_EFFECTS_TRANSITION,
+	},
+};
+
+// ─── Selected check icon ──────────────────────────────────────────────────────
+
+/** Size of the check icon in px (20dp per SegmentedMenuTokens.ItemLeadingIconSize) */
+export const MENU_CHECK_ICON_SIZE = 20;
+
+/**
+ * Expand/collapse animation for the check icon that appears when a MenuItem is
+ * selected. Uses horizontal expansion (width + marginInlineEnd) with FastSpatial.
+ *
+ * ONLY used for the animated check ↔ selectedIcon swap in selectable items.
+ * Regular (static) leading icons should NOT use these variants.
+ */
+export const CHECK_ICON_VARIANTS: Variants = {
+	hidden: {
+		opacity: 0,
+		width: 0,
+	},
+	visible: {
+		opacity: 1,
+		width: MENU_CHECK_ICON_SIZE,
+		transition: FAST_SPATIAL_SPRING,
+	},
+	exit: {
+		opacity: 0,
+		width: 0,
+		transition: FAST_EFFECTS_TRANSITION,
+	},
+};
+
+// ─── SubMenu content ──────────────────────────────────────────────────────────
+
+/** SubMenu popup uses the same FastSpatial/FastEffects pattern as root menu */
+export const SUBMENU_CONTAINER_VARIANTS: Variants = {
+	hidden: {
+		opacity: 0,
+		scale: 0.9,
+		x: -4,
+	},
+	visible: {
+		opacity: 1,
+		scale: 1,
+		x: 0,
+		transition: FAST_SPATIAL_SPRING,
+	},
+	exit: {
+		opacity: 0,
+		scale: 0.9,
+		x: -4,
+		transition: FAST_EFFECTS_TRANSITION,
+	},
+};

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

@@ -0,0 +1,99 @@
+// ─── MD3 Expressive Menu — React Context ──────────────────────────────────────
+import * as React from "react";
+import type {
+	MenuColorVariant,
+	MenuPrimitive,
+	MenuVariant,
+} from "./menu-types";
+
+// ─── Context shape ────────────────────────────────────────────────────────────
+
+interface MenuContextValue {
+	/** Visual variant: baseline (M3 standard) or expressive (shape-morphing) */
+	variant: MenuVariant;
+	/** Color variant inherited by all children unless overridden */
+	colorVariant: MenuColorVariant;
+	/**
+	 * Which Radix primitive family drives this menu:
+	 * - "dropdown" → @radix-ui/react-dropdown-menu (button/field trigger)
+	 * - "context"  → @radix-ui/react-context-menu (right-click trigger)
+	 * - "static"   → plain HTML via Slot (VerticalMenu, always-visible)
+	 */
+	menuPrimitive: MenuPrimitive;
+	/**
+	 * Whether the menu popup is currently open.
+	 * Used by MenuContent to drive AnimatePresence for exit animations.
+	 */
+	open: boolean;
+	/** Setter forwarded from Menu root — kept in sync with Radix Root open state */
+	onOpenChange: (open: boolean) => void;
+}
+
+// ─── Backward-compat derived getter ───────────────────────────────────────────
+// Components that still reference `isStatic` (MenuGroup, etc.) use this helper
+// during the incremental migration period.
+export function isStaticPrimitive(primitive: MenuPrimitive): boolean {
+	return primitive === "static";
+}
+
+// ─── Context ──────────────────────────────────────────────────────────────────
+
+const MenuContext = React.createContext<MenuContextValue>({
+	variant: "baseline",
+	colorVariant: "standard",
+	menuPrimitive: "dropdown",
+	open: false,
+	onOpenChange: () => {},
+});
+
+// ─── Provider ─────────────────────────────────────────────────────────────────
+
+export interface MenuProviderProps {
+	variant?: MenuVariant;
+	colorVariant?: MenuColorVariant;
+	menuPrimitive?: MenuPrimitive;
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	children: React.ReactNode;
+}
+
+export function MenuProvider({
+	variant = "baseline",
+	colorVariant = "standard",
+	menuPrimitive = "dropdown",
+	open,
+	onOpenChange,
+	children,
+}: MenuProviderProps) {
+	const value = React.useMemo<MenuContextValue>(
+		() => ({ variant, colorVariant, menuPrimitive, open, onOpenChange }),
+		[variant, colorVariant, menuPrimitive, open, onOpenChange],
+	);
+
+	return <MenuContext.Provider value={value}>{children}</MenuContext.Provider>;
+}
+
+// ─── Hook ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns the nearest MenuContext value.
+ * Safe to use outside a MenuProvider (returns default: baseline, dropdown, closed).
+ *
+ * Includes backward-compat shims:
+ * - `menuVariant` → alias for `variant` (deprecated, will be removed)
+ * - `isStatic`    → `menuPrimitive === "static"`
+ */
+export function useMenuContext(): MenuContextValue & {
+	isStatic: boolean;
+	menuVariant: MenuVariant;
+} {
+	const ctx = React.useContext(MenuContext);
+	return React.useMemo(
+		() => ({
+			...ctx,
+			isStatic: ctx.menuPrimitive === "static",
+			menuVariant: ctx.variant,
+		}),
+		[ctx],
+	);
+}

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

@@ -0,0 +1,47 @@
+// ─── MD3 Expressive Menu — MenuDivider ───────────────────────────────────────
+// Spec: HorizontalDividerPadding = PaddingValues(horizontal = 12.dp, vertical = 2.dp)
+import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { useMenuContext } from "./menu-context";
+import type { MenuDividerProps } from "./menu-types";
+
+/**
+ * A horizontal divider for use between MenuItems or MenuGroups.
+ *
+ * Uses traditional line-based separation (as opposed to the gap-based
+ * separation in MenuGroup, which is the Expressive default).
+ *
+ * Spec: horizontal=12dp padding, vertical=2dp padding, `outline-variant` color.
+ *
+ * @example
+ * <MenuContent>
+ *   <MenuItem>Cut</MenuItem>
+ *   <MenuDivider />
+ *   <MenuItem>Paste</MenuItem>
+ * </MenuContent>
+ */
+export const MenuDivider = React.forwardRef<HTMLHRElement, MenuDividerProps>(
+	({ className, ...props }, ref) => {
+		const { menuVariant } = useMenuContext();
+
+		return (
+			<DropdownMenu.Separator asChild>
+				<hr
+					ref={ref}
+					className={cn(
+						// Baseline: 8dp vertical margin, 0 horizontal. Expressive: 12dp horizontal, 2dp vertical
+						menuVariant === "baseline" ? "my-2 mx-0" : "mx-3 my-0.5",
+						// 1px height line
+						"h-px border-0",
+						// outline-variant color
+						"bg-m3-outline-variant",
+						className,
+					)}
+					{...props}
+				/>
+			</DropdownMenu.Separator>
+		);
+	},
+);
+MenuDivider.displayName = "MenuDivider";

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

@@ -0,0 +1,200 @@
+// ─── MD3 Expressive Menu — MenuGroup ────────────────────────────────────────
+// Gap-based grouping with shape morphing on hover (core Expressive feature)
+import { m } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { FAST_SPATIAL_SPRING } from "./menu-animations";
+
+import { useMenuContext } from "./menu-context";
+import {
+	BASELINE_COLORS,
+	GROUP_SHAPES,
+	MENU_GROUP_PADDING_Y,
+	STANDARD_COLORS,
+	VIBRANT_COLORS,
+} from "./menu-tokens";
+import type {
+	MenuGroupPosition,
+	MenuGroupProps,
+	MenuItemPosition,
+	MenuItemProps,
+} from "./menu-types";
+
+// Extend MenuGroupProps with data-* attributes for testing and aria- attributes
+type MenuGroupDivProps = MenuGroupProps & {
+	[key: `data-${string}`]: string | undefined;
+	id?: string;
+	"aria-label"?: string;
+	"aria-labelledby"?: string;
+};
+
+// ─── Position helper ──────────────────────────────────────────────────────────
+
+function getGroupPosition(index: number, count: number): MenuGroupPosition {
+	if (count === 1) return "standalone";
+	if (index === 0) return "leading";
+	if (index === count - 1) return "trailing";
+	return "middle";
+}
+
+function getGroupActiveShape(position: MenuGroupPosition): string {
+	return GROUP_SHAPES[
+		`${position}Active` as keyof typeof GROUP_SHAPES
+	] as string;
+}
+
+// ─── MenuGroup ────────────────────────────────────────────────────────────────
+
+/**
+ * A container that groups MenuItem elements with gap-based visual separation —
+ * the defining feature of MD3 Expressive menus.
+ *
+ * Shape morphing: on hover, the container's border-radius transitions from the
+ * "inactive" small shape to the "active" large shape via a FastSpatial spring.
+ * The shape depends on the group's position (leading/middle/trailing/standalone).
+ *
+ * MenuItem children automatically receive `itemPosition` props based on their
+ * index within the group.
+ *
+ * @example
+ * <MenuContent>
+ *   <MenuGroup>
+ *     <MenuItem>Cut</MenuItem>
+ *     <MenuItem>Copy</MenuItem>
+ *     <MenuItem>Paste</MenuItem>
+ *   </MenuGroup>
+ *   <MenuGroup>
+ *     <MenuItem>Select All</MenuItem>
+ *   </MenuGroup>
+ * </MenuContent>
+ */
+export const MenuGroup = React.forwardRef<HTMLDivElement, MenuGroupDivProps>(
+	(
+		{
+			children,
+			label,
+			index = 0,
+			count = 1,
+			colorVariant: propColorVariant,
+			isGapVariant,
+			itemPosition,
+			className,
+			...rest
+		},
+		ref,
+	) => {
+		const {
+			menuVariant,
+			colorVariant: contextColorVariant,
+			isStatic,
+		} = useMenuContext();
+		const colorVariant = propColorVariant ?? contextColorVariant;
+		const colors =
+			menuVariant === "baseline"
+				? BASELINE_COLORS
+				: colorVariant === "vibrant"
+					? VIBRANT_COLORS
+					: STANDARD_COLORS;
+
+		const position = getGroupPosition(index, count);
+		const activeShape = getGroupActiveShape(position);
+
+		const [isHovered, setIsHovered] = React.useState(false);
+		const currentShape =
+			isStatic || isHovered ? activeShape : GROUP_SHAPES.inactive;
+
+		const handlePointerEnter = React.useCallback(() => setIsHovered(true), []);
+		const handlePointerLeave = React.useCallback(() => setIsHovered(false), []);
+
+		// Helper to recursively flatten fragments and collect valid elements.
+		// This is necessary because cloneElement cannot be used on React.Fragment.
+		const flattenChildren = (
+			children: React.ReactNode,
+		): React.ReactElement[] => {
+			return React.Children.toArray(children).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;
+				},
+				[],
+			);
+		};
+
+		const validChildren = flattenChildren(children);
+		const itemCount = validChildren.length;
+
+		const enhancedChildren = validChildren.map((child, i) => {
+			const itemPosition: MenuItemPosition =
+				itemCount === 1
+					? "standalone"
+					: i === 0
+						? "leading"
+						: i === itemCount - 1
+							? "trailing"
+							: "middle";
+
+			return React.cloneElement(child as React.ReactElement<MenuItemProps>, {
+				itemPosition,
+				colorVariant,
+			});
+		});
+
+		return (
+			<m.div
+				ref={ref}
+				role="group"
+				aria-label={label}
+				className={cn(
+					"relative",
+					// In baseline variant, MenuGroup is transparent so it shouldn't clip.
+					// In expressive variant, it needs overflow-hidden to clip hover states to its morphing shape.
+					menuVariant === "baseline" ? "" : "overflow-hidden",
+					// Vertical padding: 2dp for gap variant (to match Figma), 4dp for baseline
+					isGapVariant ? "py-0.5" : MENU_GROUP_PADDING_Y,
+					// Horizontal padding: 4dp for expressive menus (both static and popup), 0 for baseline
+					menuVariant === "expressive" ? "px-1" : "",
+					// Gap variant has floating segments, so each group manages its own shadow
+					isGapVariant ? "elevation-2" : "",
+					// Background based on color variant (transparent for baseline to avoid double-layering)
+					menuVariant === "baseline" ? "bg-transparent" : colors.containerBg,
+					className,
+				)}
+				animate={{ borderRadius: currentShape }}
+				transition={FAST_SPATIAL_SPRING}
+				onPointerEnter={handlePointerEnter}
+				onPointerLeave={handlePointerLeave}
+				{...rest}
+			>
+				{/* Optional group label: labelSmall typography, 12dp horizontal padding */}
+				{label && (
+					<span
+						className={cn(
+							// Padding: 12dp top, 12dp horizontal, 8dp bottom (MD3 spec)
+							"block pt-3 px-3 pb-2",
+							"text-label-small",
+							menuVariant === "baseline"
+								? "text-m3-on-surface-variant"
+								: colorVariant === "vibrant"
+									? "text-m3-on-tertiary-container"
+									: "text-m3-on-surface-variant",
+						)}
+					>
+						{label}
+					</span>
+				)}
+				{enhancedChildren}
+			</m.div>
+		);
+	},
+);
+MenuGroup.displayName = "MenuGroup";