@bug-on/md3-react 2.0.2 → 3.0.0

package/src/ui/search/hooks/use-search-keyboard.test.ts

@@ -0,0 +1,202 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useSearchKeyboard } from "./use-search-keyboard";
+
+describe("useSearchKeyboard", () => {
+	const defaultProps = {
+		active: true,
+		onActiveChange: vi.fn(),
+		onSearch: vi.fn(),
+		query: "test",
+		itemCount: 3,
+	};
+
+	it("initializes with activeIndex -1", () => {
+		const { result } = renderHook(() => useSearchKeyboard({ ...defaultProps }));
+		expect(result.current.activeIndex).toBe(-1);
+	});
+
+	it("does not handle events if not active", () => {
+		const { result } = renderHook(() =>
+			useSearchKeyboard({ ...defaultProps, active: false }),
+		);
+		const e = {
+			key: "ArrowDown",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+		act(() => {
+			result.current.handleKeyDown(e);
+		});
+		expect(e.preventDefault).not.toHaveBeenCalled();
+		expect(result.current.activeIndex).toBe(-1);
+	});
+
+	it("moves focus down with ArrowDown and clamps at itemCount - 1", () => {
+		const { result } = renderHook(() => useSearchKeyboard({ ...defaultProps }));
+		const e = {
+			key: "ArrowDown",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+
+		// Move from -1 to 0
+		act(() => result.current.handleKeyDown(e));
+		expect(result.current.activeIndex).toBe(0);
+
+		// Move to 1
+		act(() => result.current.handleKeyDown(e));
+		expect(result.current.activeIndex).toBe(1);
+
+		// Move to 2
+		act(() => result.current.handleKeyDown(e));
+		expect(result.current.activeIndex).toBe(2);
+
+		// Clamp at 2
+		act(() => result.current.handleKeyDown(e));
+		expect(result.current.activeIndex).toBe(2);
+		expect(e.preventDefault).toHaveBeenCalledTimes(4);
+	});
+
+	it("moves focus up with ArrowUp and clamps at -1", () => {
+		const { result } = renderHook(() => useSearchKeyboard({ ...defaultProps }));
+		const eDown = {
+			key: "ArrowDown",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+		const eUp = {
+			key: "ArrowUp",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+
+		// Move down to index 1
+		act(() => {
+			result.current.handleKeyDown(eDown);
+			result.current.handleKeyDown(eDown);
+		});
+		expect(result.current.activeIndex).toBe(1);
+
+		// Move up to 0
+		act(() => result.current.handleKeyDown(eUp));
+		expect(result.current.activeIndex).toBe(0);
+
+		// Move up to -1
+		act(() => result.current.handleKeyDown(eUp));
+		expect(result.current.activeIndex).toBe(-1);
+
+		// Clamp at -1
+		act(() => result.current.handleKeyDown(eUp));
+		expect(result.current.activeIndex).toBe(-1);
+	});
+
+	it("calls onSearch with query when Enter is pressed without an active suggestion", () => {
+		const onSearch = vi.fn();
+		const { result } = renderHook(() =>
+			useSearchKeyboard({ ...defaultProps, onSearch }),
+		);
+		const e = {
+			key: "Enter",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+
+		act(() => result.current.handleKeyDown(e));
+		expect(e.preventDefault).toHaveBeenCalled();
+		expect(onSearch).toHaveBeenCalledWith("test");
+	});
+
+	it("calls onSelectSuggestion when Enter is pressed and an item is active", () => {
+		const onSearch = vi.fn();
+		const onSelectSuggestion = vi.fn();
+		const { result } = renderHook(() =>
+			useSearchKeyboard({ ...defaultProps, onSearch, onSelectSuggestion }),
+		);
+		const eDown = {
+			key: "ArrowDown",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+		const eEnter = {
+			key: "Enter",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+
+		// Move to index 0
+		act(() => result.current.handleKeyDown(eDown));
+		expect(result.current.activeIndex).toBe(0);
+
+		// Press Enter
+		act(() => result.current.handleKeyDown(eEnter));
+		expect(onSelectSuggestion).toHaveBeenCalledWith(0);
+		expect(onSearch).not.toHaveBeenCalled();
+	});
+
+	it("calls onSearch instead if onSelectSuggestion is missing and Enter is pressed on active item", () => {
+		const onSearch = vi.fn();
+		const { result } = renderHook(
+			() => useSearchKeyboard({ ...defaultProps, onSearch }), // NO onSelectSuggestion
+		);
+		const eDown = {
+			key: "ArrowDown",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+		const eEnter = {
+			key: "Enter",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+
+		act(() => result.current.handleKeyDown(eDown));
+		act(() => result.current.handleKeyDown(eEnter));
+
+		expect(onSearch).toHaveBeenCalledWith("test");
+	});
+
+	it("calls onActiveChange(false) when Escape is pressed", () => {
+		const onActiveChange = vi.fn();
+		const { result } = renderHook(() =>
+			useSearchKeyboard({ ...defaultProps, onActiveChange }),
+		);
+		const e = {
+			key: "Escape",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+
+		act(() => result.current.handleKeyDown(e));
+		expect(e.preventDefault).toHaveBeenCalled();
+		expect(onActiveChange).toHaveBeenCalledWith(false);
+	});
+
+	it("resets activeIndex when query changes", () => {
+		const { result, rerender } = renderHook(
+			(props) => useSearchKeyboard(props),
+			{ initialProps: { ...defaultProps, query: "a" } },
+		);
+		const e = {
+			key: "ArrowDown",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+
+		// Move index
+		act(() => result.current.handleKeyDown(e));
+		expect(result.current.activeIndex).toBe(0);
+
+		// Change query -> should reset to -1
+		rerender({ ...defaultProps, query: "ab" });
+		expect(result.current.activeIndex).toBe(-1);
+	});
+
+	it("resets activeIndex when active state changes to false", () => {
+		const { result, rerender } = renderHook(
+			(props) => useSearchKeyboard(props),
+			{ initialProps: { ...defaultProps, active: true } },
+		);
+		const e = {
+			key: "ArrowDown",
+			preventDefault: vi.fn(),
+		} as unknown as React.KeyboardEvent;
+
+		// Move index
+		act(() => result.current.handleKeyDown(e));
+		expect(result.current.activeIndex).toBe(0);
+
+		// Deactivate -> should reset to -1
+		rerender({ ...defaultProps, active: false });
+		expect(result.current.activeIndex).toBe(-1);
+	});
+});

package/src/ui/search/hooks/use-search-keyboard.ts

@@ -0,0 +1,104 @@
+/**
+ * @file use-search-keyboard.ts
+ * Keyboard navigation hook for the MD3 Search component.
+ *
+ * Handles:
+ * - ArrowDown / ArrowUp → navigate through suggestions (role="option")
+ * - Enter → submit search or select active suggestion
+ * - Escape → close the SearchView
+ */
+
+import * as React from "react";
+import type { UseSearchKeyboardReturn } from "../search.types";
+
+interface UseSearchKeyboardOptions {
+	/** Whether the SearchView is currently open. */
+	active: boolean;
+	/** Callback to close the SearchView. */
+	onActiveChange: (active: boolean) => void;
+	/** Callback for search submission. */
+	onSearch: (query: string) => void;
+	/** Current search query. */
+	query: string;
+	/** Total number of suggestion items in the listbox. */
+	itemCount: number;
+	/** Called when user selects a specific suggestion by index. */
+	onSelectSuggestion?: (index: number) => void;
+}
+
+/**
+ * Manages keyboard navigation for the Search component.
+ *
+ * Complies with WAI-ARIA Combobox pattern:
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ */
+export function useSearchKeyboard({
+	active,
+	onActiveChange,
+	onSearch,
+	query,
+	itemCount,
+	onSelectSuggestion,
+}: UseSearchKeyboardOptions): UseSearchKeyboardReturn {
+	const [activeIndex, setActiveIndex] = React.useState(-1);
+
+	// Reset active index when SearchView closes or query changes.
+	// Done during render phase to prevent double-renders on every keystroke,
+	// which would otherwise cause severe layout thrashing.
+	const resetKeyRef = React.useRef(`${active}:${query}`);
+	const currentKey = `${active}:${query}`;
+	if (resetKeyRef.current !== currentKey) {
+		resetKeyRef.current = currentKey;
+		setActiveIndex(-1);
+	}
+
+	const handleKeyDown = React.useCallback(
+		(e: React.KeyboardEvent) => {
+			if (!active) return;
+
+			switch (e.key) {
+				case "ArrowDown": {
+					e.preventDefault();
+					setActiveIndex((i) => (i < itemCount - 1 ? i + 1 : i));
+					break;
+				}
+				case "ArrowUp": {
+					e.preventDefault();
+					setActiveIndex((i) => (i > -1 ? i - 1 : -1));
+					break;
+				}
+				case "Enter": {
+					e.preventDefault();
+					if (activeIndex >= 0 && onSelectSuggestion) {
+						onSelectSuggestion(activeIndex);
+					} else {
+						onSearch(query);
+					}
+					break;
+				}
+				case "Escape": {
+					e.preventDefault();
+					onActiveChange(false);
+					break;
+				}
+				default:
+					break;
+			}
+		},
+		[
+			active,
+			activeIndex,
+			itemCount,
+			onActiveChange,
+			onSearch,
+			onSelectSuggestion,
+			query,
+		],
+	);
+
+	const resetActiveIndex = React.useCallback(() => {
+		setActiveIndex(-1);
+	}, []);
+
+	return { activeIndex, handleKeyDown, resetActiveIndex };
+}

package/src/ui/search/hooks/use-search-view-focus.test.ts

@@ -0,0 +1,96 @@
+import { renderHook } from "@testing-library/react";
+import type * as React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useSearchViewFocus } from "./use-search-view-focus";
+
+describe("useSearchViewFocus", () => {
+	const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
+	const originalCancelAnimationFrame = globalThis.cancelAnimationFrame;
+
+	afterEach(() => {
+		globalThis.requestAnimationFrame = originalRequestAnimationFrame;
+		globalThis.cancelAnimationFrame = originalCancelAnimationFrame;
+		vi.restoreAllMocks();
+	});
+
+	it("does not focus when active is false", () => {
+		const focusMock = vi.fn();
+		const ref = {
+			current: { focus: focusMock },
+		} as unknown as React.RefObject<HTMLInputElement>;
+		const rAFMock = vi.fn();
+		globalThis.requestAnimationFrame = rAFMock;
+
+		renderHook(() => useSearchViewFocus(ref, false));
+
+		expect(rAFMock).not.toHaveBeenCalled();
+		expect(focusMock).not.toHaveBeenCalled();
+	});
+
+	it("runs inner focus call on double requestAnimationFrame when active becomes true", () => {
+		const focusMock = vi.fn();
+		const ref = {
+			current: { focus: focusMock },
+		} as unknown as React.RefObject<HTMLInputElement>;
+
+		const rafCallbacks: FrameRequestCallback[] = [];
+		globalThis.requestAnimationFrame = vi.fn((cb: FrameRequestCallback) => {
+			rafCallbacks.push(cb);
+			return rafCallbacks.length;
+		});
+		globalThis.cancelAnimationFrame = vi.fn();
+
+		const { rerender } = renderHook(
+			({ active }) => useSearchViewFocus(ref, active),
+			{
+				initialProps: { active: false },
+			},
+		);
+
+		expect(globalThis.requestAnimationFrame).not.toHaveBeenCalled();
+
+		// Activate
+		rerender({ active: true });
+
+		// The hook should schedule the first rAF
+		expect(rafCallbacks.length).toBe(1);
+
+		// Fire first rAF
+		rafCallbacks[0](0);
+
+		// The hook should have scheduled the second rAF
+		expect(rafCallbacks.length).toBe(2);
+		expect(focusMock).not.toHaveBeenCalled();
+
+		// Fire second rAF
+		rafCallbacks[1](0);
+
+		// Now it should focus
+		expect(focusMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("cancels animation frames if unmounted during animation", () => {
+		const focusMock = vi.fn();
+		const ref = {
+			current: { focus: focusMock },
+		} as unknown as React.RefObject<HTMLInputElement>;
+
+		const rafCallbacks: FrameRequestCallback[] = [];
+		globalThis.requestAnimationFrame = vi.fn((cb: FrameRequestCallback) => {
+			rafCallbacks.push(cb);
+			return rafCallbacks.length;
+		});
+		globalThis.cancelAnimationFrame = vi.fn();
+
+		const { unmount } = renderHook(() => useSearchViewFocus(ref, true));
+
+		expect(rafCallbacks.length).toBe(1);
+
+		// Unmount before first rAF fires
+		unmount();
+
+		// Should have called cancelAnimationFrame with id 1
+		expect(globalThis.cancelAnimationFrame).toHaveBeenCalledWith(1);
+		expect(focusMock).not.toHaveBeenCalled();
+	});
+});

package/src/ui/search/hooks/use-search-view-focus.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+
+/**
+ * Focuses `inputRef` when `active` becomes true, using a double-rAF
+ * to wait for Framer Motion's layout animation to finish painting.
+ */
+export function useSearchViewFocus(
+	inputRef: React.RefObject<HTMLInputElement | null>,
+	active: boolean,
+): void {
+	React.useEffect(() => {
+		if (!active) return;
+		let raf2: number;
+		const raf1 = requestAnimationFrame(() => {
+			raf2 = requestAnimationFrame(() => {
+				inputRef.current?.focus();
+			});
+		});
+		return () => {
+			cancelAnimationFrame(raf1);
+			if (raf2) cancelAnimationFrame(raf2);
+		};
+	}, [active, inputRef]);
+}

package/src/ui/search/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @file index.ts
+ * MD3 Expressive Search — Public API exports.
+ *
+ * Components:
+ * - Search: Orchestrator (SearchBar + SearchView)
+ * - SearchBar: Collapsed pill state (standalone use)
+ * - SearchViewDocked: Expanded docked popup (standalone use)
+ * - SearchViewFullScreen: Expanded full-screen overlay (standalone use)
+ *
+ * Hook:
+ * - useSearchKeyboard: WAI-ARIA combobox keyboard navigation
+ *
+ * Tokens:
+ * - SearchTokens: Dimensional tokens (heights, sizes)
+ * - SEARCH_COLORS: CSS custom property color references
+ * - SEARCH_TYPOGRAPHY: Typography class strings
+ * - Animation constants
+ */
+
+export { useSearchKeyboard } from "./hooks/use-search-keyboard";
+// ─── Components ───────────────────────────────────────────────────────────────
+export { Search } from "./search";
+// ─── Tokens ───────────────────────────────────────────────────────────────────
+export {
+	SEARCH_BAR_EXIT_SPRING,
+	SEARCH_BAR_EXPAND_SPRING,
+	SEARCH_COLORS,
+	SEARCH_DOCKED_REVEAL_SPRING,
+	SEARCH_FULLSCREEN_SPRING,
+	SEARCH_TYPOGRAPHY,
+	SearchTokens,
+} from "./search.tokens";
+// ─── Types ────────────────────────────────────────────────────────────────────
+export type {
+	SearchProps,
+	SearchStyleType,
+	SearchVariant,
+} from "./search.types";
+export { SearchBar } from "./search-bar";
+// ─── Hook ─────────────────────────────────────────────────────────────────────
+export { useSearch } from "./search-context";
+export { SearchViewDocked } from "./search-view-docked";
+export { SearchViewFullScreen } from "./search-view-fullscreen";

package/src/ui/search/search-bar.tsx

@@ -0,0 +1,220 @@
+/**
+ * @file search-bar.tsx
+ * MD3 Expressive SearchBar — Collapsed state.
+ *
+ * Renders a pill-shaped search bar (CornerFull, h-56px).
+ * When focused/clicked → calls onActiveChange(true) to open SearchView.
+ *
+ * Option B (MD3 morphing): SearchBar is wrapped in its own AnimatePresence
+ * with mode="popLayout". When SearchView opens, SearchBar plays an exit
+ * animation (opacity → 0, scale → 0.95) before unmounting, releasing the
+ * shared layoutId so SearchView can claim it and morph from the same origin.
+ *
+ * Role: combobox (WAI-ARIA Search Combobox pattern).
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ */
+
+import { AnimatePresence, m, useReducedMotion } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { AnimatedPlaceholder } from "./animated-placeholder";
+import {
+	SEARCH_BAR_EXIT_SPRING,
+	SEARCH_BAR_EXPAND_SPRING,
+	SEARCH_COLORS,
+	SearchTokens,
+} from "./search.tokens";
+import type { SearchInternalProps, SearchProps } from "./search.types";
+
+/** Default search icon (Material Symbols). */
+function DefaultSearchIcon() {
+	return (
+		<span
+			className="material-symbols-rounded select-none leading-none"
+			style={{ fontSize: SearchTokens.iconSize }}
+			aria-hidden="true"
+		>
+			search
+		</span>
+	);
+}
+
+type SearchBarProps = Pick<
+	SearchProps,
+	| "query"
+	| "onQueryChange"
+	| "onSearch"
+	| "active"
+	| "onActiveChange"
+	| "leadingIcon"
+	| "trailingIcon"
+	| "placeholder"
+	| "textAlign"
+	| "className"
+	| "aria-label"
+> &
+	SearchInternalProps & {
+		/** KeyDown handler from useSearchKeyboard. */
+		onKeyDown: (e: React.KeyboardEvent) => void;
+		/** Currently highlighted suggestion index (-1 = none). */
+		activeIndex: number;
+	};
+
+/**
+ * SearchBar — collapsed state of the MD3 Search component.
+ *
+ * Uses Framer Motion `layout` + shared `layoutId` to morph into
+ * SearchView when active. Wrapped in AnimatePresence with mode="popLayout"
+ * so it exits (fades/scales out) before SearchView claims the layoutId.
+ */
+export function SearchBar({
+	query,
+	onQueryChange,
+	onSearch,
+	active,
+	onActiveChange,
+	leadingIcon,
+	trailingIcon,
+	placeholder = "Search",
+	textAlign = "left",
+	className,
+	"aria-label": ariaLabel = "Search",
+	searchId,
+	listboxId,
+	onKeyDown,
+	activeIndex,
+}: SearchBarProps) {
+	const shouldReduceMotion = useReducedMotion();
+	const inputRef = React.useRef<HTMLInputElement>(null);
+
+	const prevActiveRef = React.useRef(active);
+
+	const isRestoringFocusRef = React.useRef(false);
+
+	// When SearchView opens, focus moves to SearchView's input.
+	// When SearchView closes (true → false), restore focus here.
+	React.useEffect(() => {
+		let rafId: number;
+		if (prevActiveRef.current === true && active === false) {
+			isRestoringFocusRef.current = true;
+			inputRef.current?.focus();
+			// Reset after a tick to allow the focus event to fire
+			rafId = requestAnimationFrame(() => {
+				isRestoringFocusRef.current = false;
+			});
+		}
+		prevActiveRef.current = active;
+		return () => {
+			if (rafId) cancelAnimationFrame(rafId);
+		};
+	}, [active]);
+
+	const handleFocus = () => {
+		if (!active && !isRestoringFocusRef.current) {
+			onActiveChange(true);
+		}
+	};
+
+	const handleFormSubmit = (e: React.FormEvent) => {
+		e.preventDefault();
+		onSearch(query);
+	};
+
+	// aria-activedescendant points to the highlighted suggestion
+	const activeDescendant =
+		activeIndex >= 0 ? `${listboxId}-option-${activeIndex}` : undefined;
+
+	return (
+		/*
+		 * AnimatePresence mode="popLayout":
+		 * When SearchView opens (active=true), SearchBar plays its exit animation
+		 * first, then unmounts — releasing the shared layoutId for SearchView to
+		 * claim and morph from the pill shape.
+		 */
+		<AnimatePresence mode="popLayout">
+			{!active && (
+				<m.div
+					key={searchId}
+					layout={!shouldReduceMotion}
+					layoutId={shouldReduceMotion ? undefined : searchId}
+					transition={shouldReduceMotion ? undefined : SEARCH_BAR_EXPAND_SPRING}
+					className={cn("relative", className)}
+					style={{ height: SearchTokens.heights.bar }}
+					initial={shouldReduceMotion ? false : { opacity: 0, scale: 0.95 }}
+					animate={{ opacity: 1, scale: 1 }}
+					exit={
+						shouldReduceMotion
+							? {}
+							: { opacity: 0, scale: 0.95, transition: SEARCH_BAR_EXIT_SPRING }
+					}
+				>
+					{/* Background layer — rounded-full per SearchBarTokens.ContainerShape */}
+					<div
+						className="absolute inset-0 rounded-full"
+						style={{ backgroundColor: SEARCH_COLORS.container }}
+						aria-hidden="true"
+					/>
+
+					{/* <search> is the semantic element for role="search" */}
+					<search
+						aria-label={ariaLabel}
+						className="relative flex h-full items-center gap-2 rounded-full px-4"
+					>
+						<form className="contents" onSubmit={handleFormSubmit}>
+							<span
+								className="flex shrink-0 items-center justify-center"
+								style={{ color: SEARCH_COLORS.leadingIcon }}
+								aria-hidden="true"
+							>
+								{leadingIcon ?? <DefaultSearchIcon />}
+							</span>
+
+							{/* AnimatedPlaceholder wraps the input to provide a smooth
+							    translateX animation from textAlign → left on focus. */}
+							<AnimatedPlaceholder
+								text={placeholder}
+								textAlign={textAlign}
+								visible={!query}
+								focused={active}
+							>
+								{/* role="combobox" per WAI-ARIA combobox pattern */}
+								<input
+									ref={inputRef}
+									id={searchId}
+									type="search"
+									role="combobox"
+									aria-expanded={active}
+									aria-controls={listboxId}
+									aria-autocomplete="list"
+									aria-activedescendant={activeDescendant}
+									aria-label={placeholder}
+									value={query}
+									placeholder={placeholder}
+									className={cn(
+										"w-full bg-transparent border-none outline-none",
+										"text-[16px] leading-6 font-normal tracking-[0.5px]",
+										"placeholder:text-transparent",
+									)}
+									style={{ color: SEARCH_COLORS.inputText }}
+									onFocus={handleFocus}
+									onChange={(e) => onQueryChange(e.target.value)}
+									onKeyDown={onKeyDown}
+								/>
+							</AnimatedPlaceholder>
+
+							{trailingIcon && (
+								<span
+									className="flex shrink-0 items-center justify-center"
+									style={{ color: SEARCH_COLORS.trailingIcon }}
+									aria-hidden="true"
+								>
+									{trailingIcon}
+								</span>
+							)}
+						</form>
+					</search>
+				</m.div>
+			)}
+		</AnimatePresence>
+	);
+}