@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/app-bar/app-bar-overflow-indicator.tsx

@@ -0,0 +1,108 @@
+/**
+ * @file app-bar-overflow-indicator.tsx
+ * MD3 Expressive App Bar Overflow Indicator.
+ *
+ * Renders a "More" (more_vert) icon button that opens a Radix UI
+ * DropdownMenu containing overflow App Bar items.
+ *
+ * Used internally by <AppBarRow> and <AppBarColumn> when items exceed
+ * the visible count.
+ */
+
+import { cn } from "../../lib/utils";
+import { Menu, MenuContent, MenuItem, MenuTrigger } from "../menu";
+import { APP_BAR_COLORS, AppBarTokens } from "./app-bar.tokens";
+import type { AppBarItem, AppBarOverflowIndicatorProps } from "./app-bar.types";
+
+/** More vert icon for the overflow trigger button. */
+function MoreVertIcon() {
+	return (
+		<span
+			className="material-symbols-rounded text-[24px] leading-none select-none"
+			aria-hidden="true"
+		>
+			more_vert
+		</span>
+	);
+}
+
+/**
+ * Renders a single overflow item in the dropdown based on its type.
+ */
+function OverflowItem({ item }: { item: AppBarItem }) {
+	if (item.type === "toggleable") {
+		return (
+			<MenuItem
+				role="menuitemcheckbox"
+				selected={item.checked ?? false}
+				onClick={() => item.onCheckedChange?.(!item.checked)}
+				disabled={item.enabled === false}
+			>
+				{item.label}
+			</MenuItem>
+		);
+	}
+
+	if (item.type === "custom" && item.menuContent) {
+		return (
+			<>
+				{item.menuContent({
+					isOpen: true,
+					open: () => {},
+					close: () => {},
+				})}
+			</>
+		);
+	}
+
+	// Default: clickable
+	return (
+		<MenuItem onClick={item.onClick} disabled={item.enabled === false}>
+			{item.label}
+		</MenuItem>
+	);
+}
+
+/**
+ * MD3 App Bar Overflow Indicator.
+ *
+ * Renders a "more_vert" button that opens a dropdown menu
+ * with overflow action items.
+ */
+export function AppBarOverflowIndicator({
+	items,
+	className,
+}: AppBarOverflowIndicatorProps) {
+	if (items.length === 0) return null;
+
+	return (
+		<Menu>
+			<MenuTrigger asChild>
+				<button
+					type="button"
+					className={cn(
+						"flex items-center justify-center rounded-full",
+						"focus-visible:outline-none focus-visible:ring-2",
+						className,
+					)}
+					style={{
+						width: AppBarTokens.iconButtonTouchTarget,
+						height: AppBarTokens.iconButtonTouchTarget,
+						color: APP_BAR_COLORS.actionIcon,
+					}}
+					aria-label="More actions"
+					aria-haspopup="menu"
+				>
+					<MoreVertIcon />
+				</button>
+			</MenuTrigger>
+
+			<MenuContent align="end" sideOffset={4}>
+				{items.map((item, index) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: static list from props
+					<OverflowItem key={index} item={item} />
+				))}
+			</MenuContent>
+		</Menu>
+	);
+}

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

@@ -0,0 +1,104 @@
+/**
+ * @file app-bar-row.tsx
+ * MD3 Expressive App Bar Row DSL.
+ *
+ * Displays App Bar action items in a horizontal row.
+ * Items that exceed `maxItemCount` or available width collapse into a
+ * dropdown menu via <AppBarOverflowIndicator>.
+ *
+ * Translated from OverflowMeasurePolicy / AppBarRow.kt in Jetpack Compose M3.
+ *
+ * @see docs/m3/app-bars/AppBarRow.kt
+ */
+
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { AppBarTokens } from "./app-bar.tokens";
+import type { AppBarRowProps } from "./app-bar.types";
+import { AppBarItemButton } from "./app-bar-item-button";
+import { AppBarOverflowIndicator } from "./app-bar-overflow-indicator";
+
+/**
+ * MD3 Expressive App Bar Row.
+ *
+ * Renders action items in a row. Compatible with the `actions` prop of any App Bar.
+ *
+ * @example
+ * ```tsx
+ * <SmallAppBar
+ *   title="Messages"
+ *   actions={
+ *     <AppBarRow
+ *       maxItemCount={2}
+ *       items={[
+ *         { type: 'clickable', icon: <Icon>search</Icon>, label: 'Search', onClick: handleSearch },
+ *         { type: 'clickable', icon: <Icon>bookmark</Icon>, label: 'Bookmarks', onClick: handleBookmark },
+ *         { type: 'clickable', icon: <Icon>settings</Icon>, label: 'Settings', onClick: handleSettings },
+ *       ]}
+ *     />
+ *   }
+ * />
+ * ```
+ */
+export function AppBarRow({ items, maxItemCount, className }: AppBarRowProps) {
+	const containerRef = React.useRef<HTMLDivElement>(null);
+	const [visibleCount, setVisibleCount] = React.useState(
+		maxItemCount ?? items.length,
+	);
+
+	React.useEffect(() => {
+		if (maxItemCount !== undefined) {
+			setVisibleCount(Math.min(maxItemCount, items.length));
+			return;
+		}
+
+		const container = containerRef.current;
+		if (!container) return;
+
+		let debounceTimer: ReturnType<typeof setTimeout>;
+
+		const observer = new ResizeObserver((entries) => {
+			clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(() => {
+				const entry = entries[0];
+				if (!entry) return;
+
+				const available = entry.contentRect.width;
+				const itemWidth = AppBarTokens.iconButtonTouchTarget;
+				const hasOverflow = items.length > Math.floor(available / itemWidth);
+				const reservedWidth = hasOverflow ? itemWidth : 0;
+				const count = Math.max(
+					0,
+					Math.floor((available - reservedWidth) / itemWidth),
+				);
+				setVisibleCount(Math.min(count, items.length));
+			}, 100);
+		});
+
+		observer.observe(container);
+		return () => {
+			clearTimeout(debounceTimer);
+			observer.disconnect();
+		};
+	}, [items.length, maxItemCount]);
+
+	const visibleItems = items.slice(0, visibleCount);
+	const overflowItems = items.slice(visibleCount);
+
+	return (
+		<div
+			ref={containerRef}
+			className={cn("flex items-center", className)}
+			style={{ gap: AppBarTokens.iconButtonSpace }}
+		>
+			{visibleItems.map((item, index) => (
+				// biome-ignore lint/suspicious/noArrayIndexKey: items are static from props
+				<AppBarItemButton key={index} item={item} />
+			))}
+
+			{overflowItems.length > 0 && (
+				<AppBarOverflowIndicator items={overflowItems} />
+			)}
+		</div>
+	);
+}

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

@@ -0,0 +1,87 @@
+import { fireEvent, render, renderHook, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import {
+	BottomAppBar,
+	SearchAppBar,
+	SmallAppBar,
+	useAppBarScroll,
+} from "./index";
+
+describe("SmallAppBar", () => {
+	it("renders title correctly", () => {
+		render(<SmallAppBar title="My Title" />);
+		expect(screen.getByText("My Title")).toBeInTheDocument();
+	});
+
+	it("renders subtitle correctly", () => {
+		render(<SmallAppBar title="Main" subtitle="Sub" />);
+		expect(screen.getByText("Sub")).toBeInTheDocument();
+	});
+
+	it("applies role='banner' to the header", () => {
+		render(<SmallAppBar title="Role Test" />);
+		expect(screen.getByRole("banner")).toBeInTheDocument();
+	});
+
+	it("renders navigation icon", () => {
+		render(
+			<SmallAppBar
+				title="Nav Test"
+				navigationIcon={<button type="button" aria-label="Menu" />}
+			/>,
+		);
+		expect(screen.getByRole("button", { name: "Menu" })).toBeInTheDocument();
+	});
+
+	it("renders actions", () => {
+		render(
+			<SmallAppBar
+				title="Actions Test"
+				actions={<button type="button" aria-label="Search" />}
+			/>,
+		);
+		expect(screen.getByRole("button", { name: "Search" })).toBeInTheDocument();
+	});
+});
+
+describe("SearchAppBar", () => {
+	it("renders search bar with role='search'", () => {
+		render(<SearchAppBar searchPlaceholder="Search inside" />);
+		const searchContainer = screen.getByRole("search");
+		expect(searchContainer).toBeInTheDocument();
+		expect(searchContainer).toHaveAttribute("aria-label", "Search inside");
+	});
+
+	it("fires onSearchFocus when clicked", () => {
+		const onFocus = vi.fn();
+		render(<SearchAppBar onSearchFocus={onFocus} />);
+		const searchContainer = screen.getByRole("search");
+		fireEvent.click(searchContainer);
+		expect(onFocus).toHaveBeenCalled();
+	});
+});
+
+describe("BottomAppBar", () => {
+	it("applies role='navigation' to the container", () => {
+		render(<BottomAppBar />);
+		expect(screen.getByRole("navigation")).toBeInTheDocument();
+	});
+
+	it("renders FAB correctly", () => {
+		render(
+			<BottomAppBar
+				floatingActionButton={<button type="button" aria-label="Add" />}
+			/>,
+		);
+		expect(screen.getByRole("button", { name: "Add" })).toBeInTheDocument();
+	});
+});
+
+describe("useAppBarScroll", () => {
+	it("initializes with not scrolled", () => {
+		const { result } = renderHook(() =>
+			useAppBarScroll({ behavior: "pinned" }),
+		);
+		expect(result.current.isScrolled).toBe(false);
+	});
+});

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

@@ -0,0 +1,223 @@
+/**
+ * @file app-bar.tokens.ts
+ * MD3 Expressive App Bar — Design tokens ported from:
+ *   - AppBarTokens.kt (shared tokens)
+ *   - AppBarSmallTokens.kt
+ *   - AppBarMediumFlexibleTokens.kt
+ *   - AppBarLargeFlexibleTokens.kt
+ *   - BottomAppBarTokens.kt
+ *   - DockedToolbarTokens.kt
+ *   - FabSecondaryContainerTokens.kt
+ *
+ * All dimensional values are in px (dp equivalents for web at 1dp = 1px).
+ * Colors reference CSS custom properties — do NOT hardcode hex.
+ * @see docs/m3/app-bars/
+ */
+
+// ─── Dimensional Tokens ───────────────────────────────────────────────────────
+
+/**
+ * Height and spacing tokens for all App Bar variants.
+ * Maps directly from MD3 Kotlin token files.
+ */
+export const AppBarTokens = {
+	// ── Heights ─────────────────────────────────────────────────────────────
+	heights: {
+		/** SmallAppBar height. AppBarSmallTokens.ContainerHeight = 64dp */
+		small: 64,
+		/** Collapsed height for flexible variants. = SmallAppBar height. */
+		flexibleCollapsed: 64,
+		/** MediumFlexibleAppBar expanded height (without subtitle). AppBarMediumFlexibleTokens */
+		mediumFlexExpanded: 112,
+		/** MediumFlexibleAppBar expanded height (with subtitle). */
+		mediumFlexWithSubtitleExpanded: 136,
+		/** LargeFlexibleAppBar expanded height (without subtitle). AppBarLargeFlexibleTokens */
+		largeFlexExpanded: 120,
+		/** LargeFlexibleAppBar expanded height (with subtitle). */
+		largeFlexWithSubtitleExpanded: 152,
+		/** BottomAppBar height. BottomAppBarTokens.ContainerHeight = 80dp */
+		bottom: 80,
+		/** DockedToolbar height. DockedToolbarTokens.ContainerHeight = 64dp */
+		dockedToolbar: 64,
+	},
+
+	// ── Icon and Avatar sizes ──────────────────────────────────────────────
+	/** AppBarTokens.IconSize = 24dp */
+	iconSize: 24,
+	/** AppBarTokens.AvatarSize = 32dp */
+	avatarSize: 32,
+
+	// ── Spacing ──────────────────────────────────────────────────────────────
+	/** AppBarTokens.LeadingSpace = 4dp */
+	leadingSpace: 4,
+	/** AppBarTokens.TrailingSpace = 4dp */
+	trailingSpace: 4,
+	/** AppBarTokens.IconButtonSpace = 0dp (no gap between icon buttons) */
+	iconButtonSpace: 0,
+
+	// ── Docked Toolbar spacing ────────────────────────────────────────────
+	dockedToolbar: {
+		/** DockedToolbarTokens.ContainerLeadingSpace = 16dp */
+		leadingSpace: 16,
+		/** DockedToolbarTokens.ContainerTrailingSpace = 16dp */
+		trailingSpace: 16,
+		/** DockedToolbarTokens.ContainerMinSpacing = 4dp */
+		minSpacing: 4,
+		/** DockedToolbarTokens.ContainerMaxSpacing = 32dp */
+		maxSpacing: 32,
+	},
+
+	// ── Touch targets ─────────────────────────────────────────────────────
+	/** Minimum 48px touch target for icon buttons per MD3 accessibility spec. */
+	iconButtonTouchTarget: 48,
+} as const;
+
+// ─── Typography Tokens ────────────────────────────────────────────────────────
+
+/**
+ * MD3 type scale values mapped to Tailwind CSS class strings.
+ * Used across App Bar variants for consistent typography.
+ *
+ * Values derived from MD3 Material Type Scale specification.
+ */
+export const appBarTypography = {
+	/**
+	 * SmallAppBar title (collapsed state for flexible variants).
+	 * AppBarSmallTokens.TitleFont = TitleLarge
+	 * Spec: 22sp / 28sp line-height / medium weight
+	 */
+	titleLarge: "text-[22px] leading-[28px] font-medium tracking-[0px]",
+
+	/**
+	 * SmallAppBar subtitle.
+	 * AppBarSmallTokens.SubtitleFont = LabelMedium
+	 * Spec: 12sp / 16sp line-height / medium weight / 0.5px tracking
+	 */
+	labelMedium: "text-[12px] leading-[16px] font-medium tracking-[0.5px]",
+
+	/**
+	 * MediumFlexibleAppBar expanded title.
+	 * AppBarMediumFlexibleTokens.TitleFont = HeadlineMedium
+	 * Spec: 28sp / 36sp line-height / normal weight
+	 */
+	headlineMedium: "text-[28px] leading-[36px] font-normal tracking-[0px]",
+
+	/**
+	 * MediumFlexibleAppBar subtitle.
+	 * AppBarMediumFlexibleTokens.SubtitleFont = LabelLarge
+	 * Spec: 14sp / 20sp line-height / medium weight / 0.1px tracking
+	 */
+	labelLarge: "text-[14px] leading-[20px] font-medium tracking-[0.1px]",
+
+	/**
+	 * LargeFlexibleAppBar expanded title.
+	 * AppBarLargeFlexibleTokens.TitleFont = DisplaySmall
+	 * Spec: 36sp / 44sp line-height / normal weight / -0.25px tracking
+	 */
+	displaySmall: "text-[36px] leading-[44px] font-normal tracking-[-0.25px]",
+
+	/**
+	 * LargeFlexibleAppBar subtitle.
+	 * AppBarLargeFlexibleTokens.SubtitleFont = TitleMedium
+	 * Spec: 16sp / 24sp line-height / medium weight / 0.15px tracking
+	 */
+	titleMedium: "text-[16px] leading-6 font-medium tracking-[0.15px]",
+} as const;
+
+// ─── Color Tokens ─────────────────────────────────────────────────────────────
+
+/**
+ * CSS custom property references for App Bar colors.
+ * Maps to --md-sys-color-* tokens in the MD3 theme system.
+ *
+ * IMPORTANT: Never hardcode hex/rgba values here — these references
+ * automatically adapt to light/dark theme via the MD3ThemeProvider.
+ *
+ * AppBarTokens.kt spec:
+ * - ContainerColor → md-sys-color-surface
+ * - OnScrollContainerColor → md-sys-color-surface-container
+ */
+export const APP_BAR_COLORS = {
+	// ── Container ────────────────────────────────────────────────────────────
+	/** Default background. AppBarTokens.ContainerColor → surface */
+	container: "var(--md-sys-color-surface)",
+	/** Background when content is scrolled. AppBarTokens.OnScrollContainerColor → surface-container */
+	scrolledContainer: "var(--md-sys-color-surface-container)",
+
+	// ── Content ──────────────────────────────────────────────────────────────
+	/** Title color. AppBarTokens.TitleColor → on-surface */
+	title: "var(--md-sys-color-on-surface)",
+	/** Subtitle color. AppBarTokens.SubtitleColor → on-surface-variant */
+	subtitle: "var(--md-sys-color-on-surface-variant)",
+	/** Navigation icon color. AppBarTokens.LeadingIconColor → on-surface */
+	navigationIcon: "var(--md-sys-color-on-surface)",
+	/** Action icon color. AppBarTokens.TrailingIconColor → on-surface-variant */
+	actionIcon: "var(--md-sys-color-on-surface-variant)",
+
+	// ── Search Bar ───────────────────────────────────────────────────────────
+	/** Search bar pill background. → surface-container-high */
+	searchBarBg: "var(--md-sys-color-surface-container-high)",
+	/** Search bar text/icon color. */
+	searchBarContent: "var(--md-sys-color-on-surface-variant)",
+
+	// ── Bottom App Bar ───────────────────────────────────────────────────────
+	/** BottomAppBarTokens.ContainerColor → surface-container */
+	bottomContainer: "var(--md-sys-color-surface-container)",
+
+	// ── FAB on Bottom App Bar ────────────────────────────────────────────────
+	/** FabSecondaryContainerTokens.ContainerColor → secondary-container */
+	fabContainer: "var(--md-sys-color-secondary-container)",
+	/** FabSecondaryContainerTokens.IconColor → on-secondary-container */
+	fabIcon: "var(--md-sys-color-on-secondary-container)",
+} as const;
+
+// ─── Animation Constants ──────────────────────────────────────────────────────
+
+/**
+ * Color transition when App Bar background changes on scroll.
+ * MD3 Standard easing: cubic-bezier(0.2, 0, 0, 1), 200ms.
+ */
+export const APP_BAR_COLOR_TRANSITION = {
+	duration: 0.2,
+	ease: [0.2, 0, 0, 1] as [number, number, number, number],
+} as const;
+
+/**
+ * Spring animation for enterAlways behavior (hide/show on scroll direction).
+ * Equivalent to MD3 FastSpatial motion scheme.
+ */
+export const APP_BAR_ENTER_ALWAYS_SPRING = {
+	type: "spring",
+	stiffness: 380,
+	damping: 40,
+	mass: 1,
+} as const;
+
+/**
+ * Spring animation for Bottom App Bar hide/show.
+ * Slightly looser feel for bottom navigation.
+ */
+export const APP_BAR_BOTTOM_SPRING = {
+	type: "spring",
+	stiffness: 300,
+	damping: 30,
+} as const;
+
+/**
+ * SearchView appearance/disappearance transition.
+ * Uses spring for natural feel of expanding overlay.
+ */
+export const SEARCH_VIEW_SPRING = {
+	type: "spring",
+	stiffness: 400,
+	damping: 35,
+} as const;
+
+/**
+ * Title crossfade transition for flexible App Bars.
+ * Short duration keeps the collapse feeling snappy.
+ */
+export const APP_BAR_TITLE_FADE = {
+	duration: 0.15,
+	ease: "easeInOut",
+} as const;