@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/ripple.tsx

@@ -0,0 +1,234 @@
+import { AnimatePresence, m, useReducedMotion } from "motion/react";
+import * as React from "react";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MD3 Expressive Ripple
+//
+// - Origin: pointer-down coordinates (x, y) relative to container
+// - Shape: perfectly round circle, expands from origin to diagonally fill btn
+// - Color: currentColor at 12% opacity (matches MD3 state layer spec)
+// - A11y: disabled when `prefers-reduced-motion` is active (configurable)
+// - Clipping: caller wraps in overflow-hidden; border-radius handled on parent
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Represents a single ripple wave instance with position and size metadata.
+ *
+ * @example
+ * ```tsx
+ * const ripple: RippleOrigin = { id: Date.now(), x: 50, y: 30, size: 200 };
+ * ```
+ */
+export interface RippleOrigin {
+	/** Unique identifier used as React key and for removal. */
+	id: number;
+	/** X coordinate of the pointer event relative to the container's left edge (px). */
+	x: number;
+	/** Y coordinate of the pointer event relative to the container's top edge (px). */
+	y: number;
+	/**
+	 * Diameter of the ripple circle (px).
+	 * Typically `Math.hypot(width, height) * 2` to ensure it fills the container.
+	 */
+	size: number;
+}
+
+/** @internal Props for a single animated ripple element. */
+interface RippleItemProps {
+	ripple: RippleOrigin;
+	onDone: (id: number) => void;
+}
+
+/** @internal Memoized single ripple wave — minimises re-renders. */
+const RippleItem = React.memo(function RippleItem({
+	ripple,
+	onDone,
+}: RippleItemProps) {
+	return (
+		<m.span
+			key={ripple.id}
+			aria-hidden="true"
+			style={{
+				position: "absolute",
+				left: ripple.x - ripple.size / 2,
+				top: ripple.y - ripple.size / 2,
+				width: ripple.size,
+				height: ripple.size,
+				borderRadius: "50%",
+				backgroundColor: "currentColor",
+				pointerEvents: "none",
+				transformOrigin: "center",
+			}}
+			initial={{ scale: 0, opacity: 0.12 }}
+			animate={{ scale: 1, opacity: 0 }}
+			exit={{ opacity: 0 }}
+			transition={{
+				scale: { duration: 0.5, ease: [0.2, 0, 0, 1] },
+				opacity: { duration: 0.4, ease: "easeOut", delay: 0.1 },
+			}}
+			onAnimationComplete={() => onDone(ripple.id)}
+		/>
+	);
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Ripple Component
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Props for the `Ripple` presentation component.
+ */
+export interface RippleProps {
+	/** Active ripple instances to render. Managed by the parent via `useRipple`. */
+	ripples: RippleOrigin[];
+	/** Called when a ripple's exit animation completes — remove it from state. */
+	onRippleDone: (id: number) => void;
+	/**
+	 * Completely disables the ripple effect.
+	 * Use this when the parent element is disabled or interaction is not desired.
+	 * @default false
+	 */
+	disabled?: boolean;
+	/**
+	 * When `true`, the ripple respects the user's OS-level
+	 * `prefers-reduced-motion` accessibility setting and renders nothing if active.
+	 *
+	 * Set to `false` to always show ripples regardless of system preference.
+	 * @default true
+	 */
+	respectSystemMotion?: boolean;
+}
+
+/**
+ * MD3 Expressive Ripple — animated touch-feedback wave layer.
+ *
+ * Renders absolutely-positioned ripple circles inside an `overflow-hidden`
+ * container. Must be placed as a direct child of the interactive element.
+ *
+ * @remarks
+ * - The parent element **must** have `overflow: hidden` and `position: relative`
+ *   (or equivalent) for clipping to work correctly.
+ * - Set `disabled` to `true` on parent's disabled state to avoid stale ripples.
+ * - The ripple color is `currentColor` at 12% opacity — matching MD3 state layer spec.
+ *
+ * @example
+ * ```tsx
+ * const { ripples, onPointerDown, removeRipple } = useRippleState();
+ *
+ * <button onPointerDown={onPointerDown} className="relative overflow-hidden">
+ *   <Ripple ripples={ripples} onRippleDone={removeRipple} />
+ *   Click me
+ * </button>
+ * ```
+ *
+ * @see {@link useRippleState} for the state management hook
+ * @see https://m3.material.io/foundations/interaction/states/overview
+ */
+export function Ripple({
+	ripples,
+	onRippleDone,
+	disabled = false,
+	respectSystemMotion = true,
+}: RippleProps) {
+	const prefersReduced = useReducedMotion();
+
+	// Disabled prop: explicitly turned off by consumer
+	if (disabled) return null;
+
+	// Respect system prefers-reduced-motion when opted-in
+	if (respectSystemMotion && prefersReduced) return null;
+
+	return (
+		<AnimatePresence>
+			{ripples.map((r) => (
+				<RippleItem key={r.id} ripple={r} onDone={onRippleDone} />
+			))}
+		</AnimatePresence>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useRippleState Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Options for configuring `useRippleState` behaviour.
+ */
+export interface UseRippleStateOptions {
+	/**
+	 * When `true`, the ripple is suppressed — `onPointerDown` becomes a no-op.
+	 * Use this to sync the ripple with the parent element's `disabled` state.
+	 * @default false
+	 */
+	disabled?: boolean;
+}
+
+/**
+ * `useRippleState` — state manager for MD3 Expressive ripple waves.
+ *
+ * Tracks active ripple instances and provides pointer event handlers.
+ * Pair with the `<Ripple>` component for rendering.
+ *
+ * @remarks
+ * This hook only manages ripple *state* (coordinates, size, lifecycle).
+ * The actual animation is handled by `<Ripple>` via Framer Motion.
+ * Respecting `prefers-reduced-motion` is handled by `<Ripple>` itself.
+ *
+ * @param options - Configuration options. See {@link UseRippleStateOptions}.
+ * @returns `{ ripples, onPointerDown, removeRipple }` — bind to the interactive element.
+ *
+ * @example
+ * ```tsx
+ * function MyButton({ disabled, children }) {
+ *   const { ripples, onPointerDown, removeRipple } = useRippleState({ disabled });
+ *
+ *   return (
+ *     <button
+ *       disabled={disabled}
+ *       onPointerDown={onPointerDown}
+ *       className="relative overflow-hidden"
+ *     >
+ *       <Ripple ripples={ripples} onRippleDone={removeRipple} disabled={disabled} />
+ *       {children}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link Ripple} for the rendering component
+ */
+export function useRippleState(options: UseRippleStateOptions = {}) {
+	const { disabled = false } = options;
+	const [ripples, setRipples] = React.useState<RippleOrigin[]>([]);
+
+	const onPointerDown = React.useCallback(
+		(e: React.PointerEvent<HTMLElement>) => {
+			if (disabled) return;
+			const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+			const x = e.clientX - rect.left;
+			const y = e.clientY - rect.top;
+			const rippleSize = Math.hypot(rect.width, rect.height) * 2;
+			setRipples((prev) => [
+				...prev,
+				{ id: Date.now(), x, y, size: rippleSize },
+			]);
+		},
+		[disabled],
+	);
+
+	const removeRipple = React.useCallback((id: number) => {
+		setRipples((prev) => prev.filter((r) => r.id !== id));
+	}, []);
+
+	return { ripples, onPointerDown, removeRipple };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Legacy alias — preserved for backward-compatibility
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @deprecated Use `useRippleState` instead. This alias will be removed in a future version.
+ * @see {@link useRippleState}
+ */
+export const useRipple = useRippleState;

package/src/ui/scroll-area.test.tsx

@@ -0,0 +1,58 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { ScrollArea } from "./scroll-area";
+
+describe("ScrollArea", () => {
+	it("renders correctly with children", () => {
+		render(
+			<ScrollArea className="h-40 w-40">
+				<div data-testid="content">Long content here</div>
+			</ScrollArea>,
+		);
+
+		expect(screen.getByTestId("content")).toBeInTheDocument();
+	});
+
+	it("renders scrollbars when type is 'always'", async () => {
+		const { container } = render(
+			<ScrollArea type="always" className="h-40 w-40">
+				<div style={{ height: "1000px" }}>Overflowing content</div>
+			</ScrollArea>,
+		);
+
+		await waitFor(() => {
+			const scrollbars = container.querySelectorAll("[data-orientation]");
+			expect(scrollbars.length).toBeGreaterThan(0);
+		});
+	});
+
+	it("respects orientation prop", async () => {
+		const { container } = render(
+			<ScrollArea type="always" orientation="horizontal" className="h-40 w-40">
+				<div style={{ width: "1000px" }}>Overflowing content</div>
+			</ScrollArea>,
+		);
+
+		await waitFor(() => {
+			const scrollbar = container.querySelector(
+				'[data-orientation="horizontal"]',
+			);
+			expect(scrollbar).toBeInTheDocument();
+		});
+	});
+
+	it("hides scrollbar when type is 'none'", async () => {
+		const { container } = render(
+			<ScrollArea type="none" className="h-40 w-40">
+				<div style={{ height: "1000px" }}>Overflowing content</div>
+			</ScrollArea>,
+		);
+
+		await waitFor(() => {
+			const scrollbar = container.querySelector(
+				'[data-orientation="vertical"]',
+			);
+			expect(scrollbar).toHaveClass("hidden");
+		});
+	});
+});

package/src/ui/scroll-area.tsx

@@ -0,0 +1,139 @@
+"use client";
+
+import * as RadixScrollArea from "@radix-ui/react-scroll-area";
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+/** Radix accepts hover/scroll/always/auto. We add 'none' as a UI-only hide. */
+export type ScrollAreaType = "hover" | "scroll" | "always" | "none";
+type RadixScrollAreaType = "hover" | "scroll" | "always" | "auto";
+export type ScrollAreaOrientation = "vertical" | "horizontal" | "both";
+
+export interface ScrollAreaProps
+	extends Omit<
+		React.ComponentPropsWithoutRef<typeof RadixScrollArea.Root>,
+		"type"
+	> {
+	/**
+	 * Controls when the scrollbars are visible.
+	 * - `hover`: Show on hover (default, recommended for desktop)
+	 * - `scroll`: Show only while scrolling (recommended for mobile)
+	 * - `always`: Always visible
+	 * - `none`: Never visible
+	 */
+	type?: ScrollAreaType;
+	/**
+	 * The scrollbar orientation to render.
+	 * @default "vertical"
+	 */
+	orientation?: ScrollAreaOrientation;
+	/** Delay in ms before scrollbars hide when `type` is `hover` or `scroll`. */
+	scrollHideDelay?: number;
+	/** Extra classes applied to the inner viewport element. */
+	viewportClassName?: string;
+}
+
+// ─── Root ─────────────────────────────────────────────────────────────────────
+const ScrollArea = React.forwardRef<
+	React.ElementRef<typeof RadixScrollArea.Root>,
+	ScrollAreaProps
+>(
+	(
+		{
+			className,
+			viewportClassName,
+			children,
+			type = "hover",
+			orientation = "vertical",
+			scrollHideDelay = 600,
+			...props
+		},
+		ref,
+	) => {
+		const radixType: RadixScrollAreaType = type === "none" ? "always" : type;
+
+		return (
+			<RadixScrollArea.Root
+				ref={ref}
+				type={radixType}
+				scrollHideDelay={scrollHideDelay}
+				className={cn("relative overflow-hidden flex flex-col", className)}
+				{...props}
+			>
+				<RadixScrollArea.Viewport
+					className={cn(
+						"h-full w-full flex-1 min-h-0 min-w-0 rounded-[inherit]",
+						"outline-none focus-visible:ring-2 focus-visible:ring-m3-primary focus-visible:ring-offset-1",
+						viewportClassName,
+					)}
+				>
+					{children}
+				</RadixScrollArea.Viewport>
+
+				{(orientation === "vertical" || orientation === "both") && (
+					<ScrollAreaScrollbar
+						orientation="vertical"
+						className={type === "none" ? "hidden" : undefined}
+					/>
+				)}
+
+				{(orientation === "horizontal" || orientation === "both") && (
+					<ScrollAreaScrollbar
+						orientation="horizontal"
+						className={type === "none" ? "hidden" : undefined}
+					/>
+				)}
+
+				<RadixScrollArea.Corner className="bg-m3-surface-container" />
+			</RadixScrollArea.Root>
+		);
+	},
+);
+ScrollArea.displayName = "ScrollArea";
+
+// ─── Scrollbar ────────────────────────────────────────────────────────────────
+const ScrollAreaScrollbar = React.forwardRef<
+	React.ElementRef<typeof RadixScrollArea.Scrollbar>,
+	React.ComponentPropsWithoutRef<typeof RadixScrollArea.Scrollbar>
+>(({ className, orientation = "vertical", ...props }, ref) => (
+	<RadixScrollArea.Scrollbar
+		ref={ref}
+		orientation={orientation}
+		className={cn(
+			"flex touch-none select-none transition-all duration-300 ease-in-out",
+			"absolute z-50",
+			orientation === "vertical" &&
+				"right-0 top-0 bottom-0 w-2.5 border-l border-l-transparent p-px",
+			orientation === "horizontal" &&
+				"bottom-0 left-0 right-0 h-2.5 flex-col border-t border-t-transparent p-px",
+			"data-[state=hidden]:opacity-0 data-[state=visible]:opacity-100",
+			className,
+		)}
+		{...props}
+	>
+		<RadixScrollArea.Thumb
+			className={cn(
+				"relative flex-1 rounded-full bg-m3-on-surface/25 transition-colors duration-200",
+				"hover:bg-m3-on-surface/40 active:bg-m3-on-surface/55",
+				"before:absolute before:left-1/2 before:top-1/2 before:min-h-11 before:min-w-11 before:-translate-x-1/2 before:-translate-y-1/2",
+			)}
+		/>
+	</RadixScrollArea.Scrollbar>
+));
+ScrollAreaScrollbar.displayName = RadixScrollArea.Scrollbar.displayName;
+
+// ─── Corner ───────────────────────────────────────────────────────────────────
+const ScrollAreaCorner = React.forwardRef<
+	React.ComponentRef<typeof RadixScrollArea.Corner>,
+	React.ComponentPropsWithoutRef<typeof RadixScrollArea.Corner>
+>(({ className, ...props }, ref) => (
+	<RadixScrollArea.Corner
+		ref={ref}
+		className={cn("bg-m3-surface-container", className)}
+		{...props}
+	/>
+));
+ScrollAreaCorner.displayName = "ScrollAreaCorner";
+
+export { ScrollArea, ScrollAreaScrollbar };

package/src/ui/search/animated-placeholder.tsx

@@ -0,0 +1,145 @@
+/**
+ * @file animated-placeholder.tsx
+ * MD3 Expressive Search — Animated placeholder overlay.
+ *
+ * Replaces the native `::placeholder` with a GPU-accelerated `translateX`
+ * animation so the placeholder text can smoothly slide from its alignment
+ * position (center / right) to left when the search input is focused.
+ *
+ * Implementation notes:
+ * - Only `transform: translateX` is animated → no layout triggers, no paint.
+ * - Container width is measured once via `useLayoutEffect` (before paint) to
+ *   avoid a first-render flash, then kept fresh via `ResizeObserver`.
+ * - xOffset is stored in `useState` so Framer Motion picks up changes and
+ *   re-animates smoothly on container resize.
+ * - The span is never unmounted — only opacity-toggled — to preserve the
+ *   measurement ref between renders.
+ */
+
+import { m, useReducedMotion } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { SEARCH_COLORS, SEARCH_TYPOGRAPHY } from "./search.tokens";
+
+/** Spring tuned to match MD3 Standard Decelerate curve. */
+const PLACEHOLDER_SPRING = {
+	type: "spring" as const,
+	stiffness: 350,
+	damping: 30,
+	mass: 0.8,
+};
+
+interface AnimatedPlaceholderProps {
+	/** Placeholder text to display. */
+	text: string;
+	/** Alignment of the placeholder when idle (not focused). @default "left" */
+	textAlign: "left" | "center" | "right";
+	/**
+	 * Whether the placeholder should be visible.
+	 * Pass `!query` — hide when the user has typed something.
+	 */
+	visible: boolean;
+	/**
+	 * Whether the search is in an active/focused state.
+	 * When `true`, the placeholder snaps to `left` regardless of `textAlign`.
+	 */
+	focused: boolean;
+	/**
+	 * The `<input>` element that this component wraps.
+	 * It should have `w-full` instead of `flex-1` since this wrapper
+	 * takes over the `flex-1` role in the parent flex layout.
+	 */
+	children: React.ReactNode;
+	/** Extra className forwarded to the wrapper div. */
+	className?: string;
+}
+
+/**
+ * Wraps a search `<input>` with an animated placeholder overlay.
+ *
+ * The wrapper div occupies `flex-1` so it fits seamlessly in the
+ * horizontal flex layout used by search bar headers. The children
+ * (the `<input>`) should use `w-full` to fill the wrapper.
+ *
+ * Accessibility: `aria-label` on the `<input>` carries the placeholder
+ * text for screen readers; this span is `aria-hidden="true"`.
+ */
+export function AnimatedPlaceholder({
+	text,
+	textAlign,
+	visible,
+	focused,
+	children,
+	className,
+}: AnimatedPlaceholderProps) {
+	const shouldReduceMotion = useReducedMotion();
+	const containerRef = React.useRef<HTMLDivElement>(null);
+	const spanRef = React.useRef<HTMLSpanElement | null>(null);
+
+	// Offset in pixels from left when idle. 0 means no animation (left-aligned).
+	const [xOffset, setXOffset] = React.useState(0);
+
+	const recalculate = React.useCallback(() => {
+		const container = containerRef.current;
+		const span = spanRef.current;
+		if (!container || !span || textAlign === "left") {
+			setXOffset(0);
+			return;
+		}
+		const containerWidth = container.offsetWidth;
+		const textWidth = span.offsetWidth;
+		if (textAlign === "center") {
+			setXOffset(Math.max(0, (containerWidth - textWidth) / 2));
+		} else {
+			// right
+			setXOffset(Math.max(0, containerWidth - textWidth));
+		}
+	}, [textAlign]);
+
+	// Measure synchronously before first paint to prevent a position flash.
+	React.useLayoutEffect(() => {
+		recalculate();
+	}, [recalculate]);
+
+	// Keep measurement fresh when the container is resized.
+	React.useEffect(() => {
+		const container = containerRef.current;
+		if (!container) return;
+		const observer = new ResizeObserver(recalculate);
+		observer.observe(container);
+		return () => observer.disconnect();
+	}, [recalculate]);
+
+	// When focused or no longer visible (user typed), snap to left (x=0).
+	const targetX = focused || !visible ? 0 : xOffset;
+
+	return (
+		<div
+			ref={containerRef}
+			className={cn("relative flex-1 min-w-0", className)}
+		>
+			{children}
+
+			{/* Animated placeholder — decorative only, aria-hidden */}
+			<m.span
+				ref={(el) => {
+					spanRef.current = el;
+				}}
+				aria-hidden="true"
+				className={cn(
+					"pointer-events-none absolute inset-y-0 left-0",
+					"flex items-center whitespace-nowrap select-none",
+					SEARCH_TYPOGRAPHY.bodyLarge,
+				)}
+				style={{ color: SEARCH_COLORS.supportingText }}
+				animate={{
+					x: targetX,
+					opacity: visible ? 1 : 0,
+				}}
+				transition={shouldReduceMotion ? { duration: 0 } : PLACEHOLDER_SPRING}
+			>
+				{text}
+			</m.span>
+		</div>
+	);
+}