@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/app-bar/app-bar.types.ts

@@ -0,0 +1,441 @@
+/**
+ * @file app-bar.types.ts
+ * MD3 Expressive App Bar — TypeScript prop definitions.
+ * Spec: https://m3.material.io/components/app-bars/overview
+ * Reference: docs/m3/app-bars/AppBar.kt (MD3 Expressive, May 2025)
+ *
+ * Note: Component name is "App Bar" (not "Top App Bar") per MD3 Expressive May 2025 rename.
+ */
+
+import type * as React from "react";
+
+// ─── Scroll Behavior ─────────────────────────────────────────────────────────
+
+/**
+ * Controls how the App Bar responds to scroll events.
+ *
+ * - `pinned`: Always visible. Changes background color when scrolled.
+ * - `enterAlways`: Hides when scrolling down, reveals when scrolling up.
+ * - `exitUntilCollapsed`: Collapses from expandedHeight → collapsedHeight as user scrolls.
+ */
+export type AppBarScrollBehavior =
+	| "pinned"
+	| "enterAlways"
+	| "exitUntilCollapsed";
+
+// ─── Title Alignment ─────────────────────────────────────────────────────────
+
+/** Horizontal alignment of the title (and subtitle) text. */
+export type TitleAlignment = "start" | "center";
+
+// ─── Color Overrides ─────────────────────────────────────────────────────────
+
+/**
+ * Optional color overrides for the App Bar.
+ * All values should be CSS color strings (var(--md-sys-color-*) or hex).
+ *
+ * By default, App Bars use MD3 system color tokens automatically.
+ */
+export interface AppBarColors {
+	/** Background when not scrolled. Default: `var(--md-sys-color-surface)` */
+	containerColor?: string;
+	/** Background when content has scrolled past top. Default: `var(--md-sys-color-surface-container)` */
+	scrolledContainerColor?: string;
+	/** Title text color. Default: `var(--md-sys-color-on-surface)` */
+	titleColor?: string;
+	/** Subtitle text color. Default: `var(--md-sys-color-on-surface-variant)` */
+	subtitleColor?: string;
+	/** Navigation icon color. Default: `var(--md-sys-color-on-surface)` */
+	navigationIconColor?: string;
+	/** Action icon color. Default: `var(--md-sys-color-on-surface-variant)` */
+	actionIconColor?: string;
+}
+
+// ─── Base Props ──────────────────────────────────────────────────────────────
+
+/**
+ * Shared props for all top App Bar variants.
+ */
+export interface BaseAppBarProps {
+	/**
+	 * Navigation icon slot (typically IconButton with back arrow or hamburger).
+	 * Should have `aria-label` for accessibility.
+	 */
+	navigationIcon?: React.ReactNode;
+	/**
+	 * Action icon slots rendered at the trailing end.
+	 * Typically `<IconButton>` components. Use `<AppBarRow>` for overflow support.
+	 */
+	actions?: React.ReactNode;
+	/** Optional color overrides. Defaults use MD3 system color tokens. */
+	colors?: AppBarColors;
+	/**
+	 * Scroll behavior that controls how the App Bar reacts to scroll events.
+	 * @default "pinned"
+	 */
+	scrollBehavior?: AppBarScrollBehavior;
+	/**
+	 * Ref to the scrollable element to observe.
+	 * If not provided, listens to `window` scroll events.
+	 */
+	scrollElement?: React.RefObject<HTMLElement | null>;
+	/** Additional CSS class applied to the root header element. */
+	className?: string;
+}
+
+// ─── Small App Bar ────────────────────────────────────────────────────────────
+
+/**
+ * Props for `<SmallAppBar>`.
+ *
+ * Single-row layout with navigation icon, title, and action buttons.
+ * Height: 64px. Title font: TitleLarge (22sp).
+ */
+export interface SmallAppBarProps extends BaseAppBarProps {
+	/** The main title content. */
+	title: React.ReactNode;
+	/**
+	 * Optional subtitle displayed below the title.
+	 * Font: LabelMedium (12sp).
+	 */
+	subtitle?: React.ReactNode;
+	/**
+	 * Horizontal alignment of the title and subtitle.
+	 * When `center`: title is centered, nav icon and actions balance both sides.
+	 * @default "start"
+	 */
+	titleAlignment?: TitleAlignment;
+}
+
+// ─── Flexible App Bars ────────────────────────────────────────────────────────
+
+/**
+ * Props for `<MediumFlexibleAppBar>` and `<LargeFlexibleAppBar>`.
+ *
+ * Two-row layout in expanded state (nav row + title row).
+ * Collapses to single row when scrolled.
+ * Only supports `exitUntilCollapsed` scroll behavior.
+ */
+export interface FlexibleAppBarProps extends BaseAppBarProps {
+	/** The main title content (rendered in both expanded and collapsed states). */
+	title: React.ReactNode;
+	/**
+	 * Optional subtitle displayed in the expanded title row.
+	 * Affects expanded height (adds extra rows).
+	 */
+	subtitle?: React.ReactNode;
+	/**
+	 * Horizontal alignment of the title and subtitle.
+	 * @default "start"
+	 */
+	titleAlignment?: TitleAlignment;
+	/**
+	 * Collapsed height in px. The App Bar settles to this height after full scroll.
+	 * @default 64
+	 */
+	collapsedHeight?: number;
+	/**
+	 * Expanded (initial) height in px.
+	 * Defaults depend on variant and subtitle presence.
+	 */
+	expandedHeight?: number;
+	/**
+	 * Additional content rendered in the expanded title area.
+	 * Supports images, circular avatars (32dp), Filled Buttons, or custom elements.
+	 * Hidden when collapsed.
+	 */
+	headerContent?: React.ReactNode;
+}
+
+// ─── Search App Bar ────────────────────────────────────────────────────────────
+
+/** Visual variant of the search bar. */
+export type SearchBarVariant = "filled" | "outlined";
+
+/**
+ * Props for `<SearchAppBar>`.
+ *
+ * Replaces the title with a pill-shaped search input bar.
+ * New variant in MD3 Expressive (May 2025).
+ *
+ * @example
+ * ```tsx
+ * <SearchAppBar
+ *   searchPlaceholder="Search..."
+ *   onSearchFocus={() => setSearchViewOpen(true)}
+ *   trailingSearchActions={<IconButton aria-label="Voice search">...</IconButton>}
+ *   externalActions={<Avatar />}
+ * />
+ * ```
+ */
+export interface SearchAppBarProps extends BaseAppBarProps {
+	/** Placeholder text in the search bar. @default "Search" */
+	searchPlaceholder?: string;
+	/** Controlled search value. */
+	searchValue?: string;
+	/** Called when search input changes (inside the SearchView). */
+	onSearchChange?: (value: string) => void;
+	/**
+	 * Called when the search bar is focused/clicked.
+	 * Consumers should open a `<SearchView>` in response.
+	 */
+	onSearchFocus?: () => void;
+	/** Called when the search view is closed/blurred. */
+	onSearchBlur?: () => void;
+	/**
+	 * Icon rendered at the leading edge of the search bar (inside the pill).
+	 * Defaults to a search icon.
+	 */
+	leadingSearchIcon?: React.ReactNode;
+	/**
+	 * Action icons rendered at the trailing edge of the search bar (inside the pill).
+	 * Common examples: mic, camera, QR code.
+	 */
+	trailingSearchActions?: React.ReactNode;
+	/**
+	 * Action icons rendered outside the search bar (at the trailing edge of the bar).
+	 * Common example: profile avatar button.
+	 */
+	externalActions?: React.ReactNode;
+	/**
+	 * Horizontal alignment of the search bar.
+	 * @default "start"
+	 */
+	titleAlignment?: TitleAlignment;
+	/**
+	 * Visual style of the search bar.
+	 * @default "filled"
+	 */
+	searchBarVariant?: SearchBarVariant;
+	/**
+	 * Unique identifier for the search bar — used as the Framer Motion `layoutId`
+	 * to enable shared element transitions with `<SearchView>`.
+	 * Must be unique if multiple SearchAppBars are on the page.
+	 * @default "search-bar"
+	 */
+	searchBarId?: string;
+}
+
+// ─── Bottom App Bar ───────────────────────────────────────────────────────────
+
+/**
+ * Props for `<BottomAppBar>`.
+ *
+ * Fixed to the bottom of the screen. Contains navigation actions and optional FAB.
+ * Height: 80px. Background: `surface-container`. Elevation: Level2.
+ */
+export interface BottomAppBarProps {
+	/**
+	 * Action icon buttons rendered at the leading end.
+	 * Typically 3-4 `<IconButton>` components.
+	 */
+	actions?: React.ReactNode;
+	/**
+	 * Floating Action Button rendered at the trailing end.
+	 * Consumer provides a `<FAB>` or `<FABPosition>` component.
+	 */
+	floatingActionButton?: React.ReactNode;
+	/**
+	 * Scroll behavior.
+	 * - `visible`: Always visible.
+	 * - `hidden`: Slides down when scrolling down, appears when scrolling up.
+	 * @default "visible"
+	 */
+	scrollBehavior?: "visible" | "hidden";
+	/**
+	 * Ref to the scrollable element to observe.
+	 * If not provided, listens to `window` scroll events.
+	 */
+	scrollElement?: React.RefObject<HTMLElement | null>;
+	/** Additional CSS class applied to the root nav element. */
+	className?: string;
+}
+
+// ─── Docked Toolbar ────────────────────────────────────────────────────────────
+
+/**
+ * Props for `<DockedToolbar>`.
+ *
+ * Secondary navigation bar. Not an App Bar — typically appears below the main App Bar.
+ * Height: 64px. Background: `surface-container`.
+ * Contains chips, segmented buttons, or filter actions.
+ */
+export interface DockedToolbarProps {
+	/** Toolbar content (chips, segmented buttons, filter actions, etc.) */
+	children: React.ReactNode;
+	/**
+	 * Accessible label for the toolbar (required for accessibility).
+	 * e.g., "Filter options" or "Content navigation"
+	 */
+	"aria-label": string;
+	/** Additional CSS class applied to the root element. */
+	className?: string;
+}
+
+// ─── App Bar DSL ──────────────────────────────────────────────────────────────
+
+/** Type of item in an App Bar Row/Column. */
+export type AppBarItemType = "clickable" | "toggleable" | "custom";
+
+/**
+ * State passed to custom overflow menu content renderers.
+ */
+export interface AppBarMenuState {
+	isOpen: boolean;
+	open: () => void;
+	close: () => void;
+}
+
+/**
+ * Defines a single action item for use in `<AppBarRow>` or `<AppBarColumn>`.
+ * Translated from `AppBarItem` sealed interface in Kotlin DSL.
+ */
+export interface AppBarItem {
+	/** Type determines which props are required. */
+	type: AppBarItemType;
+	/** Icon displayed in the App Bar (always shown). */
+	icon: React.ReactNode;
+	/** Accessible label for the icon button. Also shown in overflow menu. */
+	label: string;
+	/** Whether the item is interactive. @default true */
+	enabled?: boolean;
+	// Clickable item
+	/** Called when the item is pressed (required for `type: "clickable"`). */
+	onClick?: () => void;
+	// Toggleable item
+	/** Current checked state (for `type: "toggleable"`). */
+	checked?: boolean;
+	/** Called when checked state changes (for `type: "toggleable"`). */
+	onCheckedChange?: (checked: boolean) => void;
+	// Custom item
+	/** Custom content rendered in the App Bar (for `type: "custom"`). */
+	appBarContent?: React.ReactNode;
+	/** Custom content rendered in the overflow dropdown menu. */
+	menuContent?: (state: AppBarMenuState) => React.ReactNode;
+}
+
+/**
+ * Props for `<AppBarRow>`.
+ *
+ * Displays App Bar items in a horizontal row.
+ * Items that overflow the available width collapse into a dropdown menu.
+ */
+export interface AppBarRowProps {
+	/** App Bar action items to display. */
+	items: AppBarItem[];
+	/**
+	 * Maximum number of items to display before collapsing to overflow.
+	 * If not set, uses available container width to determine count.
+	 */
+	maxItemCount?: number;
+	/** Additional CSS class applied to the row container. */
+	className?: string;
+}
+
+/**
+ * Props for `<AppBarColumn>`.
+ *
+ * Displays App Bar items in a vertical column.
+ * Items that overflow collapse into a dropdown menu.
+ */
+export interface AppBarColumnProps {
+	/** App Bar action items to display. */
+	items: AppBarItem[];
+	/**
+	 * Maximum number of items to display before collapsing to overflow.
+	 */
+	maxItemCount?: number;
+	/** Additional CSS class applied to the column container. */
+	className?: string;
+}
+
+/**
+ * Props for `<AppBarOverflowIndicator>`.
+ *
+ * Renders a "More" (MoreVert) icon button that opens a dropdown menu
+ * containing overflow App Bar items.
+ */
+export interface AppBarOverflowIndicatorProps {
+	/** Items that did not fit in the row/column and should appear in the dropdown. */
+	items: AppBarItem[];
+	/** Additional CSS class applied to the trigger button. */
+	className?: string;
+}
+
+// ─── Search View ──────────────────────────────────────────────────────────────
+
+/**
+ * Props for `<SearchView>`.
+ *
+ * Full-screen overlay shown when the search bar is activated.
+ * Designed to share a Framer Motion `layoutId` with the `<SearchAppBar>`
+ * search bar for smooth shared element transitions.
+ *
+ * Integration with SearchAppBar:
+ * ```tsx
+ * const [isOpen, setIsOpen] = useState(false);
+ *
+ * <SearchAppBar
+ *   searchBarId="main-search"
+ *   onSearchFocus={() => setIsOpen(true)}
+ * />
+ * <AnimatePresence>
+ *   {isOpen && (
+ *     <SearchView
+ *       searchBarId="main-search"
+ *       onClose={() => setIsOpen(false)}
+ *     />
+ *   )}
+ * </AnimatePresence>
+ * ```
+ */
+export interface SearchViewProps {
+	/**
+	 * Must match the `searchBarId` of the triggering `<SearchAppBar>`.
+	 * Used as the Framer Motion `layoutId` for shared element transition.
+	 * @default "search-bar"
+	 */
+	searchBarId?: string;
+	/** Current search value. */
+	value?: string;
+	/** Called when search value changes. */
+	onChange?: (value: string) => void;
+	/** Called when the view is closed (Escape key or back navigation). */
+	onClose: () => void;
+	/** Placeholder text in the search input. @default "Search" */
+	placeholder?: string;
+	/**
+	 * Content rendered below the search input (suggestions, history, results).
+	 */
+	children?: React.ReactNode;
+	/** Navigation icon (back arrow) rendered at the leading edge. */
+	leadingIcon?: React.ReactNode;
+	/** Trailing action in the search input (e.g., clear button). */
+	trailingAction?: React.ReactNode;
+	/** Additional CSS class applied to the overlay container. */
+	className?: string;
+}
+
+// ─── Internal Hook Return ─────────────────────────────────────────────────────
+
+/**
+ * Return type for `useAppBarScroll`.
+ * @internal
+ */
+export interface UseAppBarScrollReturn {
+	/**
+	 * True when the scroll position is greater than 0.
+	 * Used by `pinned` behavior to change background color.
+	 */
+	isScrolled: boolean;
+	/**
+	 * Fraction from 0 (fully expanded) to 1 (fully collapsed).
+	 * Used by `exitUntilCollapsed` to drive collapse animations.
+	 */
+	collapsedFraction: number;
+	/**
+	 * True when the App Bar should be visually hidden.
+	 * Only relevant for `enterAlways` behavior.
+	 */
+	isHidden: boolean;
+}

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

@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { BottomAppBar } from "./bottom-app-bar";
+
+// Mock IntersectionObserver for useAppBarScroll
+const mockIntersectionObserver = vi.fn();
+mockIntersectionObserver.mockReturnValue({
+	observe: () => null,
+	unobserve: () => null,
+	disconnect: () => null,
+});
+window.IntersectionObserver =
+	mockIntersectionObserver as unknown as typeof IntersectionObserver;
+
+describe("BottomAppBar", () => {
+	it("renders correctly with actions and FAB", () => {
+		render(
+			<BottomAppBar
+				actions={<div data-testid="actions">Actions Content</div>}
+				floatingActionButton={<div data-testid="fab">FAB Content</div>}
+			/>,
+		);
+
+		const nav = screen.getByRole("navigation", { name: /bottom app bar/i });
+		expect(nav).toBeInTheDocument();
+		expect(nav).toHaveClass(
+			"fixed bottom-0 inset-x-0 z-50 flex items-center bg-m3-surface-container",
+		);
+
+		expect(screen.getByTestId("actions")).toBeInTheDocument();
+		expect(screen.getByTestId("actions")).toHaveTextContent("Actions Content");
+
+		expect(screen.getByTestId("fab")).toBeInTheDocument();
+		expect(screen.getByTestId("fab")).toHaveTextContent("FAB Content");
+	});
+
+	it("applies custom classNames", () => {
+		render(<BottomAppBar className="custom-bottom-action-bar" />);
+		const nav = screen.getByRole("navigation");
+		expect(nav).toHaveClass("custom-bottom-action-bar");
+	});
+});

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

@@ -0,0 +1,84 @@
+/**
+ * @file bottom-app-bar.tsx
+ * MD3 Expressive Bottom App Bar.
+ *
+ * Fixed to bottom of screen. Contains action icons and optional FAB.
+ * Height: 80px | Background: surface-container | Elevation: Level2 (always)
+ *
+ * @see docs/m3/app-bars/BottomAppBarTokens.kt
+ */
+
+import { m, useReducedMotion } from "motion/react";
+import { cn } from "../../lib/utils";
+import { APP_BAR_BOTTOM_SPRING, AppBarTokens } from "./app-bar.tokens";
+import type { BottomAppBarProps } from "./app-bar.types";
+import { useAppBarScroll } from "./hooks/use-app-bar-scroll";
+
+/**
+ * MD3 Expressive Bottom App Bar.
+ *
+ * @example
+ * ```tsx
+ * // With FAB
+ * <BottomAppBar
+ *   actions={
+ *     <>
+ *       <IconButton aria-label="Check"><Icon>check_box</Icon></IconButton>
+ *       <IconButton aria-label="Brush"><Icon>brush</Icon></IconButton>
+ *     </>
+ *   }
+ *   floatingActionButton={<FAB aria-label="Compose">...</FAB>}
+ * />
+ *
+ * // Auto-hide on scroll
+ * <BottomAppBar scrollBehavior="hidden" actions={...} />
+ * ```
+ */
+export function BottomAppBar({
+	actions,
+	floatingActionButton,
+	scrollBehavior = "visible",
+	scrollElement,
+	className,
+}: BottomAppBarProps) {
+	const shouldReduceMotion = useReducedMotion();
+
+	const { isHidden } = useAppBarScroll({
+		scrollElement,
+		behavior: scrollBehavior === "hidden" ? "enterAlways" : "pinned",
+	});
+
+	const hideTransition = shouldReduceMotion
+		? { duration: 0 }
+		: APP_BAR_BOTTOM_SPRING;
+
+	const translateY = scrollBehavior === "hidden" && isHidden ? "100%" : "0%";
+
+	return (
+		<m.nav
+			role="navigation"
+			aria-label="Bottom app bar"
+			className={cn(
+				"fixed bottom-0 inset-x-0 z-50",
+				"flex items-center",
+				"bg-m3-surface-container",
+				"px-2", // minimal horizontal padding, icon buttons provide spacing
+				"elevation-2", // BottomAppBarTokens.ContainerElevation = Level2 (always)
+				className,
+			)}
+			style={{
+				height: AppBarTokens.heights.bottom,
+			}}
+			animate={{ y: translateY }}
+			transition={hideTransition}
+		>
+			{/* Actions — leading end */}
+			{actions && <div className="flex items-center flex-1">{actions}</div>}
+
+			{/* FAB — trailing end */}
+			{floatingActionButton && (
+				<div className="shrink-0 ml-auto mr-2">{floatingActionButton}</div>
+			)}
+		</m.nav>
+	);
+}

package/src/ui/app-bar/docked-toolbar.test.tsx

@@ -0,0 +1,34 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { DockedToolbar } from "./docked-toolbar";
+
+describe("DockedToolbar", () => {
+	it("renders successfully with given children and aria-label", () => {
+		render(
+			<DockedToolbar aria-label="Test Toolbar">
+				<div data-testid="toolbar-content">Toolbar Item</div>
+			</DockedToolbar>,
+		);
+
+		const toolbar = screen.getByRole("toolbar", { name: "Test Toolbar" });
+		expect(toolbar).toBeInTheDocument();
+		expect(toolbar).toHaveClass(
+			"flex items-center w-full overflow-x-auto bg-m3-surface-container",
+		);
+
+		const content = screen.getByTestId("toolbar-content");
+		expect(content).toBeInTheDocument();
+		expect(content).toHaveTextContent("Toolbar Item");
+	});
+
+	it("applies additional classNames", () => {
+		render(
+			<DockedToolbar aria-label="Toolbar" className="custom-test-class">
+				<span />
+			</DockedToolbar>,
+		);
+
+		const toolbar = screen.getByRole("toolbar");
+		expect(toolbar).toHaveClass("custom-test-class");
+	});
+});

package/src/ui/app-bar/docked-toolbar.tsx

@@ -0,0 +1,54 @@
+/**
+ * @file docked-toolbar.tsx
+ * MD3 Expressive Docked Toolbar.
+ *
+ * Secondary navigation component. NOT an App Bar.
+ * Usually appears directly below the main App Bar.
+ * Height: 64px | Background: surface-container
+ * Typical content: chips, segmented buttons, filter actions.
+ *
+ * @see docs/m3/app-bars/DockedToolbarTokens.kt
+ */
+
+import { cn } from "../../lib/utils";
+import { AppBarTokens } from "./app-bar.tokens";
+import type { DockedToolbarProps } from "./app-bar.types";
+
+/**
+ * MD3 Expressive Docked Toolbar.
+ *
+ * @example
+ * ```tsx
+ * <DockedToolbar aria-label="Filter options">
+ *   <Chip label="All" selected onClick={() => setFilter('all')} />
+ *   <Chip label="Unread" onClick={() => setFilter('unread')} />
+ *   <Chip label="Starred" onClick={() => setFilter('starred')} />
+ * </DockedToolbar>
+ * ```
+ */
+export function DockedToolbar({
+	children,
+	"aria-label": ariaLabel,
+	className,
+}: DockedToolbarProps) {
+	return (
+		<div
+			role="toolbar"
+			aria-label={ariaLabel}
+			className={cn(
+				"flex items-center w-full overflow-x-auto bg-m3-surface-container",
+				className,
+			)}
+			style={{
+				height: AppBarTokens.heights.dockedToolbar,
+				// DockedToolbarTokens: LeadingSpace = 16dp, TrailingSpace = 16dp
+				paddingLeft: AppBarTokens.dockedToolbar.leadingSpace,
+				paddingRight: AppBarTokens.dockedToolbar.trailingSpace,
+				// MinSpacing = 4dp (gap between items)
+				gap: AppBarTokens.dockedToolbar.minSpacing,
+			}}
+		>
+			{children}
+		</div>
+	);
+}