@bug-on/md3-react 2.0.3 → 3.0.1

package/src/ui/search/search.test.tsx

@@ -0,0 +1,233 @@
+/**
+ * @file search.test.tsx
+ * Unit tests for the MD3 Expressive Search component system.
+ *
+ * Tests cover:
+ * - SearchBar: render, focus → open, A11y attributes
+ * - SearchViewDocked: render when active, keyboard (Arrow, Enter, Escape)
+ * - SearchViewFullScreen: portal render, dialog role, close behavior
+ * - useSearchKeyboard: isolated hook behavior
+ */
+
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { Search } from "./search";
+import { SearchBar } from "./search-bar";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function makeBaseProps(overrides = {}) {
+	return {
+		query: "",
+		onQueryChange: vi.fn(),
+		onSearch: vi.fn(),
+		active: false,
+		onActiveChange: vi.fn(),
+		...overrides,
+	};
+}
+
+// ─── SearchBar ──────────────────────────────────────────────────────────────
+
+describe("SearchBar", () => {
+	it("renders the search input with placeholder", () => {
+		render(<Search {...makeBaseProps()} placeholder="Search messages" />);
+		expect(screen.getByPlaceholderText("Search messages")).toBeInTheDocument();
+	});
+
+	it("has role='combobox' on the input", () => {
+		render(<Search {...makeBaseProps()} />);
+		expect(screen.getByRole("combobox")).toBeInTheDocument();
+	});
+
+	it("input has aria-expanded=false when inactive", () => {
+		render(<Search {...makeBaseProps({ active: false })} />);
+		const input = screen.getByRole("combobox");
+		expect(input).toHaveAttribute("aria-expanded", "false");
+	});
+
+	it("calls onActiveChange(true) when input is focused", () => {
+		const onActiveChange = vi.fn();
+		render(<Search {...makeBaseProps({ onActiveChange })} />);
+		const input = screen.getByRole("combobox");
+		fireEvent.focus(input);
+		expect(onActiveChange).toHaveBeenCalledWith(true);
+	});
+
+	it("calls onQueryChange when user types", () => {
+		const onQueryChange = vi.fn();
+		render(<Search {...makeBaseProps({ onQueryChange })} />);
+		const input = screen.getByRole("combobox");
+		fireEvent.change(input, { target: { value: "hello" } });
+		expect(onQueryChange).toHaveBeenCalledWith("hello");
+	});
+});
+
+// ─── SearchViewDocked ────────────────────────────────────────────────────────
+
+describe("SearchViewDocked", () => {
+	it("does not render listbox when inactive", () => {
+		render(
+			<Search {...makeBaseProps({ active: false })} variant="docked">
+				<div role="option" tabIndex={-1}>
+					Result 1
+				</div>
+			</Search>,
+		);
+		expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
+	});
+
+	it("renders listbox when active", () => {
+		render(
+			<Search {...makeBaseProps({ active: true })} variant="docked">
+				<div role="option" tabIndex={-1}>
+					Result 1
+				</div>
+			</Search>,
+		);
+		expect(screen.getByRole("listbox")).toBeInTheDocument();
+	});
+
+	it("shows child results in the listbox", () => {
+		render(
+			<Search {...makeBaseProps({ active: true })} variant="docked">
+				<div role="option" tabIndex={-1} data-testid="result-item">
+					Result A
+				</div>
+			</Search>,
+		);
+		expect(screen.getByTestId("result-item")).toBeInTheDocument();
+	});
+
+	it("calls onActiveChange(false) on Escape key", () => {
+		const onActiveChange = vi.fn();
+		render(
+			<Search
+				{...makeBaseProps({ active: true, onActiveChange })}
+				variant="docked"
+			/>,
+		);
+		// Use the visible combobox input in the docked view
+		const inputs = screen.getAllByRole("combobox");
+		// The docked view renders a second input (id ending in "-view")
+		const viewInput = inputs.find((el) => el.id.endsWith("-view")) ?? inputs[0];
+		fireEvent.keyDown(viewInput, { key: "Escape" });
+		expect(onActiveChange).toHaveBeenCalledWith(false);
+	});
+
+	it("calls onSearch on Enter key", () => {
+		const onSearch = vi.fn();
+		render(
+			<Search
+				{...makeBaseProps({ active: true, query: "test", onSearch })}
+				variant="docked"
+			/>,
+		);
+		const inputs = screen.getAllByRole("combobox");
+		const viewInput = inputs.find((el) => el.id.endsWith("-view")) ?? inputs[0];
+		fireEvent.keyDown(viewInput, { key: "Enter" });
+		expect(onSearch).toHaveBeenCalledWith("test");
+	});
+
+	it("renders divider when styleType='divided'", () => {
+		render(
+			<Search
+				{...makeBaseProps({ active: true })}
+				variant="docked"
+				styleType="divided"
+			>
+				<div role="option" tabIndex={-1}>
+					Result
+				</div>
+			</Search>,
+		);
+		expect(document.querySelector("hr")).toBeInTheDocument();
+	});
+
+	it("does not render divider when styleType='contained'", () => {
+		render(
+			<Search
+				{...makeBaseProps({ active: true })}
+				variant="docked"
+				styleType="contained"
+			>
+				<div role="option" tabIndex={-1}>
+					Result
+				</div>
+			</Search>,
+		);
+		expect(document.querySelector("hr")).not.toBeInTheDocument();
+	});
+});
+
+// ─── SearchViewFullScreen ────────────────────────────────────────────────────
+
+describe("SearchViewFullScreen", () => {
+	it("renders a dialog when active", () => {
+		render(
+			<Search {...makeBaseProps({ active: true })} variant="fullscreen" />,
+		);
+		expect(screen.getByRole("dialog")).toBeInTheDocument();
+	});
+
+	it("has aria-modal=true on the dialog", () => {
+		render(
+			<Search {...makeBaseProps({ active: true })} variant="fullscreen" />,
+		);
+		expect(screen.getByRole("dialog")).toHaveAttribute("aria-modal", "true");
+	});
+
+	it("does not render dialog when inactive", () => {
+		render(
+			<Search {...makeBaseProps({ active: false })} variant="fullscreen" />,
+		);
+		expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+	});
+
+	it("calls onActiveChange(false) when close button is clicked", () => {
+		const onActiveChange = vi.fn();
+		render(
+			<Search
+				{...makeBaseProps({ active: true, onActiveChange })}
+				variant="fullscreen"
+			/>,
+		);
+		fireEvent.click(screen.getByLabelText("Close search"));
+		expect(onActiveChange).toHaveBeenCalledWith(false);
+	});
+
+	it("clears query when clear button is clicked", () => {
+		const onQueryChange = vi.fn();
+		render(
+			<Search
+				{...makeBaseProps({ active: true, query: "hello", onQueryChange })}
+				variant="fullscreen"
+			/>,
+		);
+		fireEvent.click(screen.getByLabelText("Clear search"));
+		expect(onQueryChange).toHaveBeenCalledWith("");
+	});
+});
+
+// ─── SearchBar standalone ────────────────────────────────────────────────────
+
+describe("SearchBar (standalone)", () => {
+	it("renders with all required ARIA on combobox", () => {
+		render(
+			<SearchBar
+				query=""
+				onQueryChange={vi.fn()}
+				onSearch={vi.fn()}
+				active={false}
+				onActiveChange={vi.fn()}
+				searchId="test-bar"
+				listboxId="test-listbox"
+				onKeyDown={vi.fn()}
+				activeIndex={-1}
+			/>,
+		);
+		const input = screen.getByRole("combobox");
+		expect(input).toHaveAttribute("aria-controls", "test-listbox");
+		expect(input).toHaveAttribute("aria-autocomplete", "list");
+	});
+});

package/src/ui/search/search.tokens.ts

@@ -0,0 +1,134 @@
+/**
+ * @file search.tokens.ts
+ * MD3 Expressive Search — Design tokens ported from:
+ *   - SearchBarTokens.kt (v0_210)
+ *   - SearchViewTokens.kt (v0_210)
+ *
+ * All dimensional values are in px (1dp = 1px on web).
+ * Colors reference CSS custom properties — do NOT hardcode hex.
+ * @see docs/m3/search/SearchBarTokens.kt
+ * @see docs/m3/search/SearchViewTokens.kt
+ */
+
+// ─── Dimensional Tokens ───────────────────────────────────────────────────────
+
+/**
+ * Height and shape tokens for Search variants.
+ * Maps directly from MD3 Kotlin token files.
+ */
+export const SearchTokens = {
+	// ── Heights ─────────────────────────────────────────────────────────────
+	heights: {
+		/** SearchBarTokens.ContainerHeight = 56dp */
+		bar: 56,
+		/** SearchViewTokens.DockedHeaderContainerHeight = 56dp */
+		dockedHeader: 56,
+		/** SearchViewTokens.FullScreenHeaderContainerHeight = 72dp */
+		fullScreenHeader: 72,
+	},
+
+	// ── Avatar ────────────────────────────────────────────────────────────
+	/** SearchBarTokens.AvatarSize = 30dp */
+	avatarSize: 30,
+
+	// ── Icon ───────────────────────────────────────────────────────────────
+	/** Standard icon size for leading/trailing icons. */
+	iconSize: 20,
+	/** Touch target for interactive icons per MD3 a11y spec. */
+	iconTouchTarget: 48,
+
+	// ── Gap ────────────────────────────────────────────────────────────────
+	/** Gap between SearchBar and results list when hasGap=true. */
+	dropdownGap: 2,
+} as const;
+
+// ─── Color Tokens ─────────────────────────────────────────────────────────────
+
+/**
+ * CSS custom property references for Search colors.
+ * Maps to --md-sys-color-* tokens in the MD3 theme system.
+ *
+ * SearchBarTokens.kt:
+ * - ContainerColor → SurfaceContainerHigh
+ * - LeadingIconColor → OnSurface
+ * - TrailingIconColor → OnSurfaceVariant
+ * - InputTextColor → OnSurface
+ * - SupportingTextColor → OnSurfaceVariant (placeholder)
+ *
+ * SearchViewTokens.kt:
+ * - ContainerColor → SurfaceContainerHigh
+ * - DividerColor → Outline
+ */
+export const SEARCH_COLORS = {
+	/** SearchBarTokens.ContainerColor → surface-container-high */
+	container: "var(--md-sys-color-surface-container-high)",
+	/** SearchBarTokens.LeadingIconColor → on-surface */
+	leadingIcon: "var(--md-sys-color-on-surface)",
+	/** SearchBarTokens.TrailingIconColor → on-surface-variant */
+	trailingIcon: "var(--md-sys-color-on-surface-variant)",
+	/** SearchBarTokens.InputTextColor → on-surface */
+	inputText: "var(--md-sys-color-on-surface)",
+	/** SearchBarTokens.SupportingTextColor → on-surface-variant (placeholder) */
+	supportingText: "var(--md-sys-color-on-surface-variant)",
+	/** SearchViewTokens.DividerColor → outline */
+	divider: "var(--md-sys-color-outline)",
+	/** Focus indicator → secondary */
+	focusIndicator: "var(--md-sys-color-secondary)",
+} as const;
+
+// ─── Typography Tokens ────────────────────────────────────────────────────────
+
+/**
+ * SearchBarTokens.InputTextFont = BodyLarge (16sp / 24sp line-height).
+ * SearchBarTokens.SupportingTextFont = BodyLarge.
+ */
+export const SEARCH_TYPOGRAPHY = {
+	/** BodyLarge — used for input text and placeholder. */
+	bodyLarge: "text-[16px] leading-6 font-normal tracking-[0.5px]",
+} as const;
+
+// ─── Animation Constants ──────────────────────────────────────────────────────
+
+/**
+ * Spring animation for SearchBar width expand (inactive → active).
+ * Matches MD3 FastSpatial motion scheme.
+ */
+export const SEARCH_BAR_EXPAND_SPRING = {
+	type: "spring" as const,
+	stiffness: 380,
+	damping: 38,
+	mass: 1,
+};
+
+/**
+ * Spring animation for Docked SearchView dropdown reveal (slide + fade).
+ * Offset Y: -8px on enter, opacity 0→1.
+ */
+export const SEARCH_DOCKED_REVEAL_SPRING = {
+	type: "spring" as const,
+	stiffness: 400,
+	damping: 35,
+	mass: 0.8,
+};
+
+/**
+ * Spring animation for FullScreen SearchView shape morphing.
+ * Lower stiffness + mass gives a smoother pill→fullscreen morph.
+ */
+export const SEARCH_FULLSCREEN_SPRING = {
+	type: "spring" as const,
+	stiffness: 300,
+	damping: 30,
+	mass: 0.9,
+};
+
+/**
+ * Exit transition for SearchBar when mode="popLayout" is used.
+ * Fast fade-out so SearchView can claim the layoutId quickly.
+ */
+export const SEARCH_BAR_EXIT_SPRING = {
+	type: "spring" as const,
+	stiffness: 500,
+	damping: 40,
+	mass: 0.6,
+};

package/src/ui/search/search.tsx

@@ -0,0 +1,131 @@
+/**
+ * @file search.tsx
+ * MD3 Expressive Search — Orchestrator component.
+ *
+ * Composes SearchBar (collapsed) + SearchView (expanded) into a single
+ * developer-facing API. Routes to the correct SearchView variant based on props.
+ *
+ * Developer usage:
+ * ```tsx
+ * const [query, setQuery] = useState("");
+ * const [active, setActive] = useState(false);
+ *
+ * <Search
+ *   query={query}
+ *   onQueryChange={setQuery}
+ *   onSearch={(q) => doSearch(q)}
+ *   active={active}
+ *   onActiveChange={setActive}
+ *   variant="docked"
+ *   styleType="contained"
+ * >
+ *   {results.map((r) => (
+ *     <div key={r.id} id={`${YOUR_LISTBOX_ID}-option-0`} role="option">
+ *       {r.label}
+ *     </div>
+ *   ))}
+ * </Search>
+ * ```
+ */
+
+import { m } from "motion/react";
+import * as React from "react";
+import { useSearchKeyboard } from "./hooks/use-search-keyboard";
+import type { SearchProps } from "./search.types";
+import { SearchBar } from "./search-bar";
+import { SearchProvider, useSearch } from "./search-context";
+import { SearchViewDocked } from "./search-view-docked";
+import { SearchViewFullScreen } from "./search-view-fullscreen";
+
+/**
+ * MD3 Expressive Search — Orchestrator component.
+ *
+ * Renders a SearchBar (collapsed pill) and the appropriate SearchView
+ * (docked popup or fullscreen overlay) based on `variant`.
+ *
+ * The component is fully controlled:
+ * - `active` / `onActiveChange` manage open/close state.
+ * - `query` / `onQueryChange` manage input value.
+ *
+ * Shared `searchId` (React.useId) links SearchBar and SearchView via
+ * Framer Motion `layoutId` for seamless animated transitions.
+ */
+function SearchComponent({
+	query,
+	onQueryChange,
+	onSearch,
+	active,
+	onActiveChange,
+	variant = "docked",
+	styleType = "contained",
+	hasGap = false,
+	leadingIcon,
+	trailingIcon,
+	placeholder = "Search",
+	textAlign = "left",
+	children,
+	id,
+	"aria-label": ariaLabel = "Search",
+	className,
+	viewClassName,
+}: SearchProps) {
+	const generatedId = React.useId();
+	const searchId = id ?? generatedId;
+	const listboxId = `${searchId}-listbox`;
+
+	const itemCount = React.Children.count(children);
+
+	const { activeIndex, handleKeyDown } = useSearchKeyboard({
+		active,
+		onActiveChange,
+		onSearch,
+		query,
+		itemCount,
+	});
+
+	const sharedProps = {
+		query,
+		onQueryChange,
+		onSearch,
+		active,
+		onActiveChange,
+		leadingIcon,
+		trailingIcon,
+		placeholder,
+		textAlign,
+		"aria-label": ariaLabel,
+		searchId,
+		listboxId,
+		onKeyDown: handleKeyDown,
+		activeIndex,
+	} as const;
+
+	return (
+		<SearchProvider value={{ activeIndex, listboxId }}>
+			<m.div className={className} style={{ minHeight: 56 }}>
+				<SearchBar {...sharedProps} />
+				{variant === "fullscreen" ? (
+					<SearchViewFullScreen
+						{...sharedProps}
+						styleType={styleType}
+						viewClassName={viewClassName}
+					>
+						{children}
+					</SearchViewFullScreen>
+				) : (
+					<SearchViewDocked
+						{...sharedProps}
+						styleType={styleType}
+						hasGap={hasGap}
+						viewClassName={viewClassName}
+					>
+						{children}
+					</SearchViewDocked>
+				)}
+			</m.div>
+		</SearchProvider>
+	);
+}
+
+/** MD3 Expressive Search component with `Search.useSearch` context accessor. */
+export const Search = Object.assign(SearchComponent, { useSearch });

package/src/ui/search/search.types.ts

@@ -0,0 +1,154 @@
+/**
+ * @file search.types.ts
+ * MD3 Expressive Search — TypeScript prop definitions.
+ * Spec: https://m3.material.io/components/search/overview
+ * Reference: docs/m3/search/SearchBar.kt (MD3 Expressive)
+ */
+
+import type * as React from "react";
+
+// ─── Variant & Style ──────────────────────────────────────────────────────────
+
+/**
+ * Display variant for the expanded SearchView.
+ *
+ * - `docked`: Popup dropdown below the SearchBar. For medium/large screens.
+ * - `fullscreen`: Full-screen dialog overlay. For compact/mobile screens.
+ */
+export type SearchVariant = "docked" | "fullscreen";
+
+/**
+ * Visual style type for the SearchView.
+ *
+ * - `contained`: No divider between the input area and results.
+ *   The container background is preserved continuously (recommended).
+ * - `divided`: A HorizontalDivider separates the input area from results.
+ */
+export type SearchStyleType = "contained" | "divided";
+
+// ─── Internal Shared Props ────────────────────────────────────────────────────
+
+/**
+ * Internal props shared between SearchBar and SearchView sub-components.
+ * Not part of the public API.
+ * @internal
+ */
+export interface SearchInternalProps {
+	/** Unique ID generated by useId(), used as Framer Motion layoutId. */
+	searchId: string;
+	/** Unique ID for the results listbox, used for aria-controls. */
+	listboxId: string;
+}
+
+// ─── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Props for the `<Search>` component (orchestrator).
+ *
+ * @example
+ * ```tsx
+ * const [query, setQuery] = useState("");
+ * const [active, setActive] = useState(false);
+ *
+ * <Search
+ *   query={query}
+ *   onQueryChange={setQuery}
+ *   onSearch={(q) => console.log("search:", q)}
+ *   active={active}
+ *   onActiveChange={setActive}
+ *   variant="docked"
+ *   styleType="contained"
+ * >
+ *   <SearchResultsList />
+ * </Search>
+ * ```
+ */
+export interface SearchProps {
+	// ── State ─────────────────────────────────────────────────────────────
+	/** Current search query value (controlled). */
+	query: string;
+	/** Called when user types in the search input. */
+	onQueryChange: (query: string) => void;
+	/** Called when user submits search (Enter key or suggestion click). */
+	onSearch: (query: string) => void;
+	/** Whether the SearchView is expanded/open (controlled). */
+	active: boolean;
+	/** Called when the Search open/close state should change. */
+	onActiveChange: (active: boolean) => void;
+
+	// ── Variants ──────────────────────────────────────────────────────────
+	/**
+	 * Display variant for the expanded state.
+	 * @default "docked"
+	 */
+	variant?: SearchVariant;
+	/**
+	 * Visual style for the SearchView container.
+	 * @default "contained"
+	 */
+	styleType?: SearchStyleType;
+	/**
+	 * Whether to add a 2dp gap between the input header and the results list.
+	 * Only applies when `variant="docked"`.
+	 * @default false
+	 */
+	hasGap?: boolean;
+
+	// ── Content ───────────────────────────────────────────────────────────
+	/**
+	 * Icon rendered at the leading edge of the search input.
+	 * Defaults to a built-in search icon.
+	 */
+	leadingIcon?: React.ReactNode;
+	/**
+	 * Icon or action rendered at the trailing edge of the search input.
+	 * Common examples: mic, camera, QR code.
+	 */
+	trailingIcon?: React.ReactNode;
+	/** Placeholder text shown when the input is empty. @default "Search" */
+	placeholder?: string;
+	/**
+	 * Align the placeholder text to left, center, or right.
+	 * Typed text will always remain left-aligned.
+	 * @default "left"
+	 */
+	textAlign?: "left" | "center" | "right";
+	/**
+	 * Search results or suggestions rendered inside the SearchView.
+	 * Use `role="option"` on each item for accessibility.
+	 */
+	children?: React.ReactNode;
+
+	// ── Accessibility ──────────────────────────────────────────────────────
+	/**
+	 * Override the auto-generated input element ID.
+	 * Auto-generated via React.useId() if not provided.
+	 */
+	id?: string;
+	/**
+	 * Accessible label for the search landmark.
+	 * @default "Search"
+	 */
+	"aria-label"?: string;
+
+	// ── Styling ────────────────────────────────────────────────────────────
+	/** Additional CSS classes for the SearchBar root element. */
+	className?: string;
+	/** Additional CSS classes for the SearchView container. */
+	viewClassName?: string;
+}
+
+// ─── Hook Return ───────────────────────────────────────────────────────────────
+
+/**
+ * Return type for `useSearchKeyboard`.
+ * @internal
+ */
+export interface UseSearchKeyboardReturn {
+	/** Currently highlighted suggestion index. -1 = none. */
+	activeIndex: number;
+	/** KeyDown handler — attach to the search input. */
+	handleKeyDown: (e: React.KeyboardEvent) => void;
+	/** Reset activeIndex (e.g., when query changes). */
+	resetActiveIndex: () => void;
+}

package/src/ui/search/trailing-action.tsx

@@ -0,0 +1,49 @@
+import type * as React from "react";
+import { IconButton } from "../icon-button";
+import { SEARCH_COLORS } from "./search.tokens";
+
+interface TrailingActionProps {
+	query: string;
+	trailingIcon?: React.ReactNode;
+	onClear: () => void;
+}
+
+/** Clear button when query is non-empty, otherwise the trailing icon slot. */
+export function TrailingAction({
+	query,
+	trailingIcon,
+	onClear,
+}: TrailingActionProps) {
+	if (query) {
+		return (
+			<IconButton
+				size="sm"
+				style={{ color: SEARCH_COLORS.trailingIcon }}
+				aria-label="Clear search"
+				onClick={onClear}
+			>
+				<span
+					className="material-symbols-rounded select-none leading-none"
+					style={{ fontSize: 20 }}
+					aria-hidden="true"
+				>
+					close
+				</span>
+			</IconButton>
+		);
+	}
+
+	if (trailingIcon) {
+		return (
+			<span
+				className="flex shrink-0 items-center justify-center"
+				style={{ color: SEARCH_COLORS.trailingIcon }}
+				aria-hidden="true"
+			>
+				{trailingIcon}
+			</span>
+		);
+	}
+
+	return null;
+}