@bug-on/md3-react 2.0.3 → 3.0.0

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

@@ -0,0 +1,49 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { SearchAppBar } from "./search-app-bar";
+import { SearchView } from "./search-view";
+
+describe("SearchAppBar and SearchView", () => {
+	describe("SearchAppBar", () => {
+		it("renders correctly with search bar", () => {
+			render(<SearchAppBar searchPlaceholder="Search here..." />);
+
+			expect(screen.getByText("Search here...")).toBeInTheDocument();
+		});
+
+		it("triggers onSearchFocus when clicked and via Enter key", () => {
+			const onSearchFocus = vi.fn();
+			render(<SearchAppBar onSearchFocus={onSearchFocus} />);
+
+			const searchBar = screen.getByRole("search");
+			fireEvent.click(searchBar);
+			expect(onSearchFocus).toHaveBeenCalledTimes(1);
+
+			fireEvent.keyDown(searchBar, { key: "Enter" });
+			expect(onSearchFocus).toHaveBeenCalledTimes(2);
+		});
+	});
+
+	describe("SearchView", () => {
+		it("renders overlay correctly", () => {
+			const onClose = vi.fn();
+			render(
+				<SearchView onClose={onClose} placeholder="Type to search">
+					<div data-testid="search-results">Results</div>
+				</SearchView>,
+			);
+
+			expect(screen.getByPlaceholderText("Type to search")).toBeInTheDocument();
+			expect(screen.getByTestId("search-results")).toBeInTheDocument();
+		});
+
+		it("calls onClose when back button is pressed", () => {
+			const onClose = vi.fn();
+			render(<SearchView onClose={onClose} />);
+
+			const btn = screen.getByRole("button", { name: "Close search" });
+			fireEvent.click(btn);
+			expect(onClose).toHaveBeenCalledTimes(1);
+		});
+	});
+});

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

@@ -0,0 +1,176 @@
+/**
+ * @file search-app-bar.tsx
+ * MD3 Expressive Search App Bar.
+ *
+ * New variant in MD3 Expressive (May 2025).
+ * Replaces the title area with a pill-shaped search bar.
+ * Uses Framer Motion layoutId to enable shared element transition with <SearchView>.
+ *
+ * @see docs/m3/app-bars/AppBar.kt — SearchAppBar
+ */
+
+import { m, useReducedMotion } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import {
+	APP_BAR_COLOR_TRANSITION,
+	APP_BAR_COLORS,
+	AppBarTokens,
+} from "./app-bar.tokens";
+import type { SearchAppBarProps } from "./app-bar.types";
+import { useAppBarScroll } from "./hooks/use-app-bar-scroll";
+
+/** Built-in search icon (Material Symbols) used as default. */
+function SearchIcon({ className }: { className?: string }) {
+	return (
+		<span
+			className={cn(
+				"material-symbols-rounded text-[20px] leading-none select-none",
+				className,
+			)}
+			aria-hidden="true"
+		>
+			search
+		</span>
+	);
+}
+
+/**
+ * MD3 Expressive Search App Bar.
+ *
+ * When the search bar is clicked, callers should open a `<SearchView>` overlay.
+ * Uses Framer Motion `layoutId` (via `searchBarId`) for a smooth shared-element
+ * transition between this bar and the search view.
+ *
+ * @example
+ * ```tsx
+ * const [searchOpen, setSearchOpen] = useState(false);
+ *
+ * <SearchAppBar
+ *   searchBarId="main-search"
+ *   searchPlaceholder="Search messages..."
+ *   onSearchFocus={() => setSearchOpen(true)}
+ *   trailingSearchActions={
+ *     <IconButton aria-label="Voice search"><Icon>mic</Icon></IconButton>
+ *   }
+ *   externalActions={<Avatar src={user.avatar} />}
+ * />
+ *
+ * <AnimatePresence>
+ *   {searchOpen && (
+ *     <SearchView
+ *       searchBarId="main-search"
+ *       onClose={() => setSearchOpen(false)}
+ *     />
+ *   )}
+ * </AnimatePresence>
+ * ```
+ */
+export function SearchAppBar({
+	searchPlaceholder = "Search",
+	searchValue,
+	onSearchFocus,
+	leadingSearchIcon,
+	trailingSearchActions,
+	externalActions,
+	navigationIcon,
+	colors,
+	scrollBehavior = "pinned",
+	scrollElement,
+	searchBarId = "search-bar",
+	className,
+}: SearchAppBarProps) {
+	const shouldReduceMotion = useReducedMotion();
+	const [isSearchOpen, setIsSearchOpen] = React.useState(false);
+
+	const { isScrolled } = useAppBarScroll({
+		scrollElement,
+		behavior:
+			scrollBehavior === "exitUntilCollapsed" ? "pinned" : scrollBehavior,
+	});
+
+	const containerBg = colors?.containerColor ?? APP_BAR_COLORS.container;
+	const scrolledBg =
+		colors?.scrolledContainerColor ?? APP_BAR_COLORS.scrolledContainer;
+	const currentBg = isScrolled ? scrolledBg : containerBg;
+
+	const cssTransition = shouldReduceMotion
+		? undefined
+		: `background-color ${APP_BAR_COLOR_TRANSITION.duration}s cubic-bezier(${APP_BAR_COLOR_TRANSITION.ease.join(",")})`;
+
+	const handleSearchClick = () => {
+		setIsSearchOpen(true);
+		onSearchFocus?.();
+	};
+
+	const handleKeyDown = (e: React.KeyboardEvent) => {
+		if (e.key === "Enter" || e.key === " ") {
+			e.preventDefault();
+			handleSearchClick();
+		}
+	};
+
+	return (
+		<m.header
+			role="banner"
+			className={cn(
+				"fixed top-0 inset-x-0 z-50 flex items-center gap-2 px-4",
+				className,
+			)}
+			style={{
+				height: AppBarTokens.heights.small,
+				backgroundColor: currentBg,
+				transition: cssTransition,
+			}}
+		>
+			{/* Optional navigation icon — leading edge */}
+			{navigationIcon && (
+				<div
+					className="shrink-0 flex items-center justify-center"
+					style={{
+						width: AppBarTokens.iconButtonTouchTarget,
+						height: AppBarTokens.iconButtonTouchTarget,
+					}}
+				>
+					{navigationIcon}
+				</div>
+			)}
+
+			<m.div
+				layoutId={shouldReduceMotion ? undefined : searchBarId}
+				role="search"
+				aria-label={searchPlaceholder}
+				aria-expanded={isSearchOpen}
+				tabIndex={0}
+				className="relative flex flex-1 items-center gap-2 rounded-full cursor-text h-10 px-4 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2"
+				onClick={handleSearchClick}
+				onKeyDown={handleKeyDown}
+			>
+				<div className="absolute inset-0 rounded-full bg-m3-surface-container-high -z-10" />
+				<span
+					className="shrink-0"
+					style={{ color: APP_BAR_COLORS.searchBarContent }}
+				>
+					{leadingSearchIcon ?? <SearchIcon />}
+				</span>
+
+				<span
+					className="flex-1 text-[16px] leading-6 truncate select-none"
+					style={{ color: APP_BAR_COLORS.searchBarContent }}
+				>
+					{searchValue ?? searchPlaceholder}
+				</span>
+
+				{trailingSearchActions && (
+					<div className="flex items-center shrink-0">
+						{trailingSearchActions}
+					</div>
+				)}
+			</m.div>
+
+			{externalActions && (
+				<div className="flex items-center shrink-0">{externalActions}</div>
+			)}
+		</m.header>
+	);
+}

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

@@ -0,0 +1,227 @@
+/**
+ * @file search-view.tsx
+ * MD3 Expressive Search View.
+ *
+ * Full-screen overlay activated when a SearchAppBar's search bar is clicked.
+ * Shares a Framer Motion `layoutId` with the SearchAppBar search bar for a
+ * smooth shared element transition.
+ *
+ * Usage pattern:
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * // In render:
+ * <SearchAppBar searchBarId="main" onSearchFocus={() => setOpen(true)} />
+ * <AnimatePresence>
+ *   {open && <SearchView searchBarId="main" onClose={() => setOpen(false)} />}
+ * </AnimatePresence>
+ * ```
+ *
+ * Design notes:
+ * - The SearchView is intentionally separate from SearchAppBar to allow consumers
+ *   to customize the results/suggestions content without coupling.
+ * - The `searchBarId` prop must match between SearchAppBar and SearchView to
+ *   enable the shared element transition.
+ * - Focus is moved to the search input when the view opens.
+ * - Escape key closes the view and returns focus to the search bar.
+ */
+
+import { AnimatePresence, m, useReducedMotion } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import {
+	APP_BAR_COLORS,
+	AppBarTokens,
+	SEARCH_VIEW_SPRING,
+} from "./app-bar.tokens";
+import type { SearchViewProps } from "./app-bar.types";
+
+/** Built-in back arrow icon. */
+function ArrowBackIcon() {
+	return (
+		<span
+			className="material-symbols-rounded text-[24px] leading-none select-none"
+			aria-hidden="true"
+		>
+			arrow_back
+		</span>
+	);
+}
+
+/** Built-in clear icon. */
+function CloseIcon() {
+	return (
+		<span
+			className="material-symbols-rounded text-[24px] leading-none select-none"
+			aria-hidden="true"
+		>
+			close
+		</span>
+	);
+}
+
+/**
+ * MD3 Expressive Search View.
+ *
+ * Renders a full-screen search overlay with a shared element transition
+ * from the triggering `<SearchAppBar>` search bar.
+ *
+ * Mount/unmount this component via `<AnimatePresence>` in the consumer.
+ */
+export function SearchView({
+	searchBarId = "search-bar",
+	value = "",
+	onChange,
+	onClose,
+	placeholder = "Search",
+	children,
+	leadingIcon,
+	trailingAction,
+	className,
+}: SearchViewProps) {
+	const shouldReduceMotion = useReducedMotion();
+	const inputRef = React.useRef<HTMLInputElement>(null);
+
+	// Move focus to the search input when the view opens
+	React.useEffect(() => {
+		const timer = window.setTimeout(() => {
+			inputRef.current?.focus();
+		}, 50);
+		return () => window.clearTimeout(timer);
+	}, []);
+
+	// Close on Escape key
+	const handleKeyDown = (e: React.KeyboardEvent) => {
+		if (e.key === "Escape") {
+			onClose();
+		}
+	};
+
+	const viewTransition = shouldReduceMotion
+		? { duration: 0 }
+		: SEARCH_VIEW_SPRING;
+
+	return (
+		<m.div
+			role="dialog"
+			aria-modal="true"
+			aria-label="Search"
+			className={cn(
+				"fixed inset-0 z-60 flex flex-col bg-m3-surface",
+				className,
+			)}
+			initial={shouldReduceMotion ? {} : { opacity: 0 }}
+			animate={{ opacity: 1 }}
+			exit={shouldReduceMotion ? {} : { opacity: 0 }}
+			transition={viewTransition}
+			onKeyDown={handleKeyDown}
+		>
+			{/* Search Bar — matches layoutId of SearchAppBar search bar */}
+			<m.div
+				layoutId={shouldReduceMotion ? undefined : searchBarId}
+				className="flex items-center gap-2 px-4 shrink-0 bg-m3-surface"
+				style={{
+					height: AppBarTokens.heights.small,
+				}}
+			>
+				{/* Leading: back button or custom icon */}
+				<button
+					type="button"
+					className={cn(
+						"shrink-0 flex items-center justify-center rounded-full",
+						"focus-visible:outline-none focus-visible:ring-2",
+					)}
+					style={{
+						width: AppBarTokens.iconButtonTouchTarget,
+						height: AppBarTokens.iconButtonTouchTarget,
+						color: APP_BAR_COLORS.navigationIcon,
+					}}
+					aria-label="Close search"
+					onClick={onClose}
+				>
+					{leadingIcon ?? <ArrowBackIcon />}
+				</button>
+
+				{/* Search input */}
+				<div
+					className="relative flex flex-1 items-center rounded-full px-4 gap-2"
+					style={{
+						height: 40,
+					}}
+				>
+					{/* Background Layer */}
+					<div className="absolute inset-0 rounded-full bg-m3-surface-container-high -z-10" />
+					<input
+						ref={inputRef}
+						aria-label={placeholder}
+						type="search"
+						value={value}
+						onChange={(e) => onChange?.(e.target.value)}
+						placeholder={placeholder}
+						className={cn(
+							"flex-1 bg-transparent border-none outline-none",
+							"text-[16px] leading-6",
+							"placeholder:text-m3-on-surface-variant",
+						)}
+						style={{ color: APP_BAR_COLORS.title }}
+					/>
+
+					{/* Clear button — show when there's a value */}
+					{value && (
+						<button
+							type="button"
+							className={cn(
+								"shrink-0 flex items-center justify-center rounded-full",
+								"focus-visible:outline-none focus-visible:ring-2",
+							)}
+							style={{
+								width: 40,
+								height: 40,
+								color: APP_BAR_COLORS.searchBarContent,
+							}}
+							aria-label="Clear search"
+							onClick={() => onChange?.("")}
+						>
+							{trailingAction ?? <CloseIcon />}
+						</button>
+					)}
+				</div>
+			</m.div>
+
+			{/* Results / suggestions area */}
+			{children && (
+				<m.div
+					className="flex-1 overflow-y-auto"
+					initial={shouldReduceMotion ? {} : { opacity: 0, y: -8 }}
+					animate={{ opacity: 1, y: 0 }}
+					transition={{ delay: 0.1, duration: 0.15 }}
+				>
+					{children}
+				</m.div>
+			)}
+		</m.div>
+	);
+}
+
+/**
+ * Convenience wrapper that handles the AnimatePresence + open state.
+ *
+ * @example
+ * ```tsx
+ * <SearchBar
+ *   isOpen={searchOpen}
+ *   onClose={() => setSearchOpen(false)}
+ *   searchBarId="main-search"
+ * >
+ *   <SearchResultsList results={results} />
+ * </SearchBar>
+ * ```
+ */
+export function SearchViewContainer({
+	isOpen,
+	...props
+}: SearchViewProps & { isOpen: boolean }) {
+	return (
+		<AnimatePresence>{isOpen && <SearchView {...props} />}</AnimatePresence>
+	);
+}

package/src/ui/app-bar/small-app-bar.test.tsx

@@ -0,0 +1,48 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { SmallAppBar } from "./small-app-bar";
+
+describe("SmallAppBar", () => {
+	it("renders correctly with basic props", () => {
+		render(<SmallAppBar title="Inbox" />);
+
+		const header = screen.getByRole("banner");
+		expect(header).toBeInTheDocument();
+
+		const titleElement = screen.getByText("Inbox");
+		expect(titleElement).toBeInTheDocument();
+	});
+
+	it("renders subtitle, actions, and navigationIcon", () => {
+		render(
+			<SmallAppBar
+				title="Profile"
+				subtitle="@username"
+				navigationIcon={
+					<button type="button" data-testid="nav-icon">
+						Back
+					</button>
+				}
+				actions={
+					<button type="button" data-testid="actions-btn">
+						Search
+					</button>
+				}
+			/>,
+		);
+
+		expect(screen.getByText("Profile")).toBeInTheDocument();
+		expect(screen.getByText("@username")).toBeInTheDocument();
+		expect(screen.getByTestId("nav-icon")).toBeInTheDocument();
+		expect(screen.getByTestId("actions-btn")).toBeInTheDocument();
+	});
+
+	it("applies custom classNames", () => {
+		render(<SmallAppBar title="Custom" className="test-small-bar" />);
+
+		// Container has the class
+		const _container = screen.getByText("Custom").closest("div");
+		// Actually banner is inside or might be the returned container
+		expect(document.querySelector(".test-small-bar")).toBeInTheDocument();
+	});
+});

package/src/ui/app-bar/small-app-bar.tsx

@@ -0,0 +1,203 @@
+/**
+ * @file small-app-bar.tsx
+ * MD3 Expressive Small App Bar.
+ *
+ * Single-row layout: [navigationIcon][title + subtitle][actions]
+ * Height: 64px | Title: TitleLarge (22sp) | Subtitle: LabelMedium (12sp)
+ *
+ * Scroll behaviors:
+ * - pinned: changes background color surface → surface-container
+ * - enterAlways: slides up when scrolling down, slides down when scrolling up
+ *
+ * @see docs/m3/app-bars/AppBarSmallTokens.kt
+ */
+
+import { AnimatePresence, m, useReducedMotion } from "motion/react";
+import { cn } from "../../lib/utils";
+import {
+	APP_BAR_COLOR_TRANSITION,
+	APP_BAR_COLORS,
+	APP_BAR_ENTER_ALWAYS_SPRING,
+	AppBarTokens,
+	appBarTypography,
+} from "./app-bar.tokens";
+import type { SmallAppBarProps } from "./app-bar.types";
+import { useAppBarScroll } from "./hooks/use-app-bar-scroll";
+
+interface SmallAppBarInnerProps
+	extends Pick<
+		SmallAppBarProps,
+		| "title"
+		| "subtitle"
+		| "titleAlignment"
+		| "navigationIcon"
+		| "actions"
+		| "colors"
+		| "className"
+	> {
+	currentBg: string;
+	cssTransition: string | undefined;
+}
+
+/** Inner content shared between pinned and enterAlways variants. */
+function SmallAppBarInner({
+	title,
+	subtitle,
+	titleAlignment = "start",
+	navigationIcon,
+	actions,
+	colors,
+	className,
+	currentBg,
+	cssTransition,
+}: SmallAppBarInnerProps) {
+	const isCentered = titleAlignment === "center";
+
+	return (
+		<m.header
+			role="banner"
+			className={cn("flex items-center px-1 h-full w-full", className)}
+			style={{ backgroundColor: currentBg, transition: cssTransition }}
+		>
+			{navigationIcon && (
+				<div
+					className="shrink-0 flex items-center justify-center"
+					style={{
+						width: AppBarTokens.iconButtonTouchTarget,
+						height: AppBarTokens.iconButtonTouchTarget,
+					}}
+				>
+					{navigationIcon}
+				</div>
+			)}
+
+			<div
+				className={cn(
+					"flex-1 flex flex-col justify-center min-w-0",
+					isCentered ? "items-center" : "items-start",
+					!navigationIcon && "pl-4",
+				)}
+			>
+				<span
+					className={cn(
+						appBarTypography.titleLarge,
+						"truncate w-full",
+						isCentered && "text-center",
+					)}
+					style={{ color: colors?.titleColor ?? APP_BAR_COLORS.title }}
+				>
+					{title}
+				</span>
+				{subtitle && (
+					<span
+						className={cn(
+							appBarTypography.labelMedium,
+							"truncate w-full",
+							isCentered && "text-center",
+						)}
+						style={{ color: colors?.subtitleColor ?? APP_BAR_COLORS.subtitle }}
+					>
+						{subtitle}
+					</span>
+				)}
+			</div>
+
+			{actions && <div className="flex items-center shrink-0">{actions}</div>}
+		</m.header>
+	);
+}
+
+/**
+ * MD3 Expressive Small App Bar.
+ *
+ * @example
+ * ```tsx
+ * // Left-aligned (default)
+ * <SmallAppBar
+ *   title="Inbox"
+ *   navigationIcon={<IconButton aria-label="Go back"><Icon>arrow_back</Icon></IconButton>}
+ *   actions={<IconButton aria-label="Search"><Icon>search</Icon></IconButton>}
+ *   scrollBehavior="pinned"
+ * />
+ *
+ * // Center-aligned with subtitle
+ * <SmallAppBar
+ *   title="Profile"
+ *   subtitle="@username"
+ *   titleAlignment="center"
+ *   scrollBehavior="enterAlways"
+ * />
+ * ```
+ */
+export function SmallAppBar({
+	title,
+	subtitle,
+	titleAlignment = "start",
+	navigationIcon,
+	actions,
+	colors,
+	scrollBehavior = "pinned",
+	scrollElement,
+	className,
+}: SmallAppBarProps) {
+	const shouldReduceMotion = useReducedMotion();
+
+	const { isScrolled, isHidden } = useAppBarScroll({
+		scrollElement,
+		behavior:
+			scrollBehavior === "exitUntilCollapsed" ? "pinned" : scrollBehavior,
+	});
+
+	const containerBg = colors?.containerColor ?? APP_BAR_COLORS.container;
+	const scrolledBg =
+		colors?.scrolledContainerColor ?? APP_BAR_COLORS.scrolledContainer;
+	const currentBg = isScrolled ? scrolledBg : containerBg;
+
+	const cssTransition = shouldReduceMotion
+		? undefined
+		: `background-color ${APP_BAR_COLOR_TRANSITION.duration}s cubic-bezier(${APP_BAR_COLOR_TRANSITION.ease.join(",")})`;
+
+	const innerProps: SmallAppBarInnerProps = {
+		title,
+		subtitle,
+		titleAlignment,
+		navigationIcon,
+		actions,
+		colors,
+		currentBg,
+		cssTransition,
+	};
+
+	const barHeight = AppBarTokens.heights.small;
+
+	if (scrollBehavior !== "enterAlways") {
+		return (
+			<div
+				className={cn("fixed top-0 inset-x-0 z-50", className)}
+				style={{ height: barHeight }}
+			>
+				<SmallAppBarInner {...innerProps} />
+			</div>
+		);
+	}
+
+	return (
+		<AnimatePresence initial={false}>
+			{!isHidden && (
+				<m.div
+					key="small-app-bar"
+					initial={{ y: "-100%" }}
+					animate={{ y: 0 }}
+					exit={{ y: "-100%" }}
+					transition={
+						shouldReduceMotion ? { duration: 0 } : APP_BAR_ENTER_ALWAYS_SPRING
+					}
+					className={cn("fixed top-0 inset-x-0 z-50", className)}
+					style={{ height: barHeight }}
+				>
+					<SmallAppBarInner {...innerProps} />
+				</m.div>
+			)}
+		</AnimatePresence>
+	);
+}