@bug-on/md3-react 2.0.3 → 3.0.1

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

@@ -0,0 +1,75 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { LargeFlexibleAppBar } from "./large-flexible-app-bar";
+import { MediumFlexibleAppBar } from "./medium-flexible-app-bar";
+
+describe("FlexibleAppBars", () => {
+	describe("MediumFlexibleAppBar", () => {
+		it("renders correctly with essential props", () => {
+			render(
+				<MediumFlexibleAppBar
+					title="Medium Title"
+					navigationIcon={
+						<button type="button" data-testid="medium-nav">
+							Menu
+						</button>
+					}
+					actions={
+						<button type="button" data-testid="medium-actions">
+							Edit
+						</button>
+					}
+				/>,
+			);
+
+			// Should render title inside the expanded area and pinned area (sometimes twice, or just once if transitioning)
+			expect(screen.getAllByText("Medium Title").length).toBeGreaterThan(0);
+			expect(screen.getByTestId("medium-nav")).toBeInTheDocument();
+			expect(screen.getByTestId("medium-actions")).toBeInTheDocument();
+		});
+
+		it("renders subtitle if provided", () => {
+			render(
+				<MediumFlexibleAppBar
+					title="Has Subtitle"
+					subtitle="Medium Subtitle"
+				/>,
+			);
+			expect(screen.getAllByText("Medium Subtitle").length).toBeGreaterThan(0);
+		});
+	});
+
+	describe("LargeFlexibleAppBar", () => {
+		it("renders correctly with essential props", () => {
+			render(
+				<LargeFlexibleAppBar
+					title="Large Title"
+					navigationIcon={
+						<button type="button" data-testid="large-nav">
+							Close
+						</button>
+					}
+					actions={
+						<button type="button" data-testid="large-actions">
+							Save
+						</button>
+					}
+				/>,
+			);
+
+			expect(screen.getAllByText("Large Title").length).toBeGreaterThan(0);
+			expect(screen.getByTestId("large-nav")).toBeInTheDocument();
+			expect(screen.getByTestId("large-actions")).toBeInTheDocument();
+		});
+
+		it("renders headerContent", () => {
+			render(
+				<LargeFlexibleAppBar
+					title="With Header Content"
+					headerContent={<div data-testid="header-content">Custom Content</div>}
+				/>,
+			);
+			expect(screen.getByTestId("header-content")).toBeInTheDocument();
+		});
+	});
+});

package/src/ui/app-bar/hooks/use-app-bar-scroll.ts

@@ -0,0 +1,110 @@
+/**
+ * @file use-app-bar-scroll.ts
+ * MD3 Expressive App Bar — Scroll behavior hook.
+ *
+ * Tracks scroll state for App Bar behaviors:
+ * - `pinned`: background color change only
+ * - `enterAlways`: hide/show based on scroll direction
+ * - `exitUntilCollapsed`: drives collapse fraction (0 = expanded, 1 = collapsed)
+ */
+
+import * as React from "react";
+import type {
+	AppBarScrollBehavior,
+	UseAppBarScrollReturn,
+} from "../app-bar.types";
+
+interface UseAppBarScrollOptions {
+	/** Ref to the scrollable container. Defaults to `window`. */
+	scrollElement?: React.RefObject<HTMLElement | null>;
+	/** Scroll behavior mode. @default "pinned" */
+	behavior?: AppBarScrollBehavior;
+	/** Collapsed height in px — used for `exitUntilCollapsed`. @default 64 */
+	collapsedHeight?: number;
+	/** Expanded height in px — used for `exitUntilCollapsed`. @default 112 */
+	expandedHeight?: number;
+}
+
+/**
+ * Tracks scroll position and derives App Bar state for all three behaviors.
+ *
+ * @example
+ * ```tsx
+ * // pinned (color change only)
+ * const { isScrolled } = useAppBarScroll({ behavior: 'pinned' });
+ *
+ * // enterAlways (hide/show)
+ * const { isHidden } = useAppBarScroll({ behavior: 'enterAlways' });
+ *
+ * // exitUntilCollapsed (collapse animation)
+ * const { collapsedFraction } = useAppBarScroll({
+ *   behavior: 'exitUntilCollapsed',
+ *   collapsedHeight: 64,
+ *   expandedHeight: 112,
+ * });
+ * ```
+ */
+export function useAppBarScroll({
+	scrollElement,
+	behavior = "pinned",
+	collapsedHeight = 64,
+	expandedHeight = 112,
+}: UseAppBarScrollOptions = {}): UseAppBarScrollReturn {
+	const [isScrolled, setIsScrolled] = React.useState(false);
+	const [collapsedFraction, setCollapsedFraction] = React.useState(0);
+	const [isHidden, setIsHidden] = React.useState(false);
+
+	// Track previous scroll position for direction detection
+	const prevScrollYRef = React.useRef(0);
+	// Hysteresis to prevent rapid toggling on enterAlways
+	const hideThreshold = 64;
+
+	React.useEffect(() => {
+		const scrollDistance = expandedHeight - collapsedHeight;
+
+		const getScrollY = (): number => {
+			const el = scrollElement?.current;
+			return el ? el.scrollTop : window.scrollY;
+		};
+
+		const handleScroll = () => {
+			const currentY = getScrollY();
+			const prevY = prevScrollYRef.current;
+			const delta = currentY - prevY;
+			prevScrollYRef.current = currentY;
+
+			// Pinned: only toggle background color
+			setIsScrolled(currentY > 0);
+
+			if (behavior === "exitUntilCollapsed") {
+				const fraction =
+					scrollDistance > 0
+						? Math.min(1, Math.max(0, currentY / scrollDistance))
+						: 0;
+				setCollapsedFraction(fraction);
+			}
+
+			if (behavior === "enterAlways") {
+				if (delta > 0 && currentY > hideThreshold) {
+					// Scrolling down — hide
+					setIsHidden(true);
+				} else if (delta < 0) {
+					// Scrolling up — show
+					setIsHidden(false);
+				}
+			}
+		};
+
+		const target = scrollElement?.current ?? window;
+		target.addEventListener("scroll", handleScroll, { passive: true });
+
+		// Sync initial state
+		handleScroll();
+
+		return () => {
+			target.removeEventListener("scroll", handleScroll);
+		};
+	}, [scrollElement, behavior, collapsedHeight, expandedHeight]);
+
+	return { isScrolled, collapsedFraction, isHidden };
+}

package/src/ui/app-bar/hooks/use-flexible-app-bar.ts

@@ -0,0 +1,123 @@
+/**
+ * @file use-flexible-app-bar.ts
+ * Shared animation hook for MediumFlexibleAppBar and LargeFlexibleAppBar.
+ *
+ * Extracts common scroll-driven animation state to avoid duplication.
+ */
+
+import type { MotionValue } from "motion/react";
+import { useMotionValue, useReducedMotion, useTransform } from "motion/react";
+import type { RefObject } from "react";
+import * as React from "react";
+import { APP_BAR_COLOR_TRANSITION, APP_BAR_COLORS } from "../app-bar.tokens";
+import type { AppBarColors } from "../app-bar.types";
+import { useAppBarScroll } from "./use-app-bar-scroll";
+
+interface UseFlexibleAppBarOptions {
+	collapsedHeight: number;
+	expandedHeight: number;
+	scrollElement?: RefObject<HTMLElement | null>;
+	colors?: AppBarColors;
+	/** [start, end] progress range where large title fades from 1 → 0 */
+	largeTitleFadeRange: [number, number];
+	/** [start, end] progress range where small title fades from 0 → 1 */
+	smallTitleFadeRange: [number, number];
+	/** [start, end] progress range where subtitle fades from 1 → 0 */
+	subtitleFadeRange: [number, number];
+	/** [start, end] progress range where headerContent fades from 1 → 0 */
+	headerContentFadeRange: [number, number];
+	/** [expanded, collapsed] Y offset for large title */
+	largeTitleYRange: [number, number];
+}
+
+export interface FlexibleAppBarAnimationState {
+	height: MotionValue<number>;
+	currentBg: string;
+	cssTransition: string | undefined;
+	largeTitleOpacity: MotionValue<number>;
+	largeTitleY: MotionValue<number>;
+	smallTitleOpacity: MotionValue<number>;
+	subtitleOpacity: MotionValue<number>;
+	headerContentOpacity: MotionValue<number>;
+}
+
+export function useFlexibleAppBar({
+	collapsedHeight,
+	expandedHeight,
+	scrollElement,
+	colors,
+	largeTitleFadeRange,
+	smallTitleFadeRange,
+	subtitleFadeRange,
+	headerContentFadeRange,
+	largeTitleYRange,
+}: UseFlexibleAppBarOptions): FlexibleAppBarAnimationState {
+	const shouldReduceMotion = useReducedMotion();
+
+	const { collapsedFraction } = useAppBarScroll({
+		scrollElement,
+		behavior: "exitUntilCollapsed",
+		collapsedHeight,
+		expandedHeight,
+	});
+
+	const scrollProgress = useMotionValue(0);
+
+	React.useEffect(() => {
+		scrollProgress.set(
+			shouldReduceMotion
+				? collapsedFraction > 0.5
+					? 1
+					: 0
+				: collapsedFraction,
+		);
+	}, [collapsedFraction, scrollProgress, shouldReduceMotion]);
+
+	const height = useTransform(
+		scrollProgress,
+		[0, 1],
+		[expandedHeight, collapsedHeight],
+	);
+
+	const containerBg = colors?.containerColor ?? APP_BAR_COLORS.container;
+	const scrolledBg =
+		colors?.scrolledContainerColor ?? APP_BAR_COLORS.scrolledContainer;
+	const currentBg = collapsedFraction > 0 ? scrolledBg : containerBg;
+
+	const cssTransition = shouldReduceMotion
+		? undefined
+		: `background-color ${APP_BAR_COLOR_TRANSITION.duration}s cubic-bezier(${APP_BAR_COLOR_TRANSITION.ease.join(",")})`;
+
+	const largeTitleOpacity = useTransform(
+		scrollProgress,
+		[largeTitleFadeRange[0], largeTitleFadeRange[1]],
+		[1, 0],
+	);
+	const largeTitleY = useTransform(scrollProgress, [0, 1], largeTitleYRange);
+	const smallTitleOpacity = useTransform(
+		scrollProgress,
+		[smallTitleFadeRange[0], smallTitleFadeRange[1]],
+		[0, 1],
+	);
+	const subtitleOpacity = useTransform(
+		scrollProgress,
+		[subtitleFadeRange[0], subtitleFadeRange[1]],
+		[1, 0],
+	);
+	const headerContentOpacity = useTransform(
+		scrollProgress,
+		[headerContentFadeRange[0], headerContentFadeRange[1]],
+		[1, 0],
+	);
+
+	return {
+		height,
+		currentBg,
+		cssTransition,
+		largeTitleOpacity,
+		largeTitleY,
+		smallTitleOpacity,
+		subtitleOpacity,
+		headerContentOpacity,
+	};
+}

package/{dist/ui/app-bar/index.d.ts → src/ui/app-bar/index.ts}

@@ -24,16 +24,49 @@
  * - APP_BAR_COLORS: CSS custom property color references
  * - Animation constants (APP_BAR_COLOR_TRANSITION, etc.)
  */
-export { APP_BAR_BOTTOM_SPRING, APP_BAR_COLOR_TRANSITION, APP_BAR_COLORS, APP_BAR_ENTER_ALWAYS_SPRING, APP_BAR_TITLE_FADE, AppBarTokens, appBarTypography, SEARCH_VIEW_SPRING, } from "./app-bar.tokens";
-export type { AppBarColors, AppBarColumnProps, AppBarItem, AppBarItemType, AppBarMenuState, AppBarOverflowIndicatorProps, AppBarRowProps, AppBarScrollBehavior, BaseAppBarProps, BottomAppBarProps, DockedToolbarProps, FlexibleAppBarProps, SearchAppBarProps, SearchBarVariant, SearchViewProps, SmallAppBarProps, TitleAlignment, UseAppBarScrollReturn, } from "./app-bar.types";
+
+// ─── Tokens ───────────────────────────────────────────────────────────────────
+export {
+	APP_BAR_BOTTOM_SPRING,
+	APP_BAR_COLOR_TRANSITION,
+	APP_BAR_COLORS,
+	APP_BAR_ENTER_ALWAYS_SPRING,
+	APP_BAR_TITLE_FADE,
+	AppBarTokens,
+	appBarTypography,
+	SEARCH_VIEW_SPRING,
+} from "./app-bar.tokens";
+// ─── Types ────────────────────────────────────────────────────────────────────
+export type {
+	AppBarColors,
+	AppBarColumnProps,
+	AppBarItem,
+	AppBarItemType,
+	AppBarMenuState,
+	AppBarOverflowIndicatorProps,
+	AppBarRowProps,
+	AppBarScrollBehavior,
+	BaseAppBarProps,
+	BottomAppBarProps,
+	DockedToolbarProps,
+	FlexibleAppBarProps,
+	SearchAppBarProps,
+	SearchBarVariant,
+	SearchViewProps,
+	SmallAppBarProps,
+	TitleAlignment,
+	UseAppBarScrollReturn,
+} from "./app-bar.types";
 export { AppBarColumn } from "./app-bar-column";
 export { AppBarOverflowIndicator } from "./app-bar-overflow-indicator";
 export { AppBarRow } from "./app-bar-row";
 export { BottomAppBar } from "./bottom-app-bar";
 export { DockedToolbar } from "./docked-toolbar";
+// ─── Hook ─────────────────────────────────────────────────────────────────────
 export { useAppBarScroll } from "./hooks/use-app-bar-scroll";
 export { LargeFlexibleAppBar } from "./large-flexible-app-bar";
 export { MediumFlexibleAppBar } from "./medium-flexible-app-bar";
 export { SearchAppBar } from "./search-app-bar";
 export { SearchView, SearchViewContainer } from "./search-view";
+// ─── Components ───────────────────────────────────────────────────────────────
 export { SmallAppBar } from "./small-app-bar";

package/src/ui/app-bar/large-flexible-app-bar.tsx

@@ -0,0 +1,165 @@
+/**
+ * @file large-flexible-app-bar.tsx
+ * MD3 Expressive Large Flexible App Bar.
+ *
+ * Like MediumFlexibleAppBar but with larger typography.
+ * Expanded height: 120px (no subtitle) / 152px (with subtitle)
+ * Collapsed height: 64px
+ * Title crossfade: DisplaySmall (expanded) ↔ TitleLarge (collapsed)
+ *
+ * @see docs/m3/app-bars/AppBarLargeFlexibleTokens.kt
+ */
+
+import { m } from "motion/react";
+import { cn } from "../../lib/utils";
+import {
+	APP_BAR_COLORS,
+	AppBarTokens,
+	appBarTypography,
+} from "./app-bar.tokens";
+import type { FlexibleAppBarProps } from "./app-bar.types";
+import { useFlexibleAppBar } from "./hooks/use-flexible-app-bar";
+
+/**
+ * MD3 Expressive Large Flexible App Bar.
+ *
+ * @example
+ * ```tsx
+ * <LargeFlexibleAppBar
+ *   title="Discover"
+ *   subtitle="Trending today"
+ *   navigationIcon={<IconButton aria-label="Open menu"><Icon>menu</Icon></IconButton>}
+ *   headerContent={<img src="/banner.jpg" alt="" className="rounded-xl h-20 w-full object-cover" />}
+ * />
+ * ```
+ */
+export function LargeFlexibleAppBar({
+	title,
+	subtitle,
+	titleAlignment = "start",
+	navigationIcon,
+	actions,
+	colors,
+	scrollElement,
+	headerContent,
+	collapsedHeight = AppBarTokens.heights.flexibleCollapsed,
+	expandedHeight,
+	className,
+}: FlexibleAppBarProps) {
+	const resolvedExpandedHeight =
+		expandedHeight ??
+		(subtitle
+			? AppBarTokens.heights.largeFlexWithSubtitleExpanded
+			: AppBarTokens.heights.largeFlexExpanded);
+
+	const {
+		height,
+		currentBg,
+		cssTransition,
+		largeTitleOpacity,
+		largeTitleY,
+		smallTitleOpacity,
+		subtitleOpacity,
+		headerContentOpacity,
+	} = useFlexibleAppBar({
+		collapsedHeight,
+		expandedHeight: resolvedExpandedHeight,
+		scrollElement,
+		colors,
+		largeTitleFadeRange: [0, 0.35],
+		smallTitleFadeRange: [0.55, 0.95],
+		subtitleFadeRange: [0, 0.25],
+		headerContentFadeRange: [0, 0.2],
+		largeTitleYRange: [0, 12],
+	});
+
+	const isCentered = titleAlignment === "center";
+
+	return (
+		<m.header
+			role="banner"
+			className={cn(
+				"fixed top-0 inset-x-0 z-50 flex flex-col overflow-hidden",
+				className,
+			)}
+			style={{ height, backgroundColor: currentBg, transition: cssTransition }}
+		>
+			<div
+				className="flex items-center px-1 shrink-0"
+				style={{ height: collapsedHeight }}
+			>
+				{navigationIcon && (
+					<div
+						className="shrink-0 flex items-center justify-center"
+						style={{
+							width: AppBarTokens.iconButtonTouchTarget,
+							height: AppBarTokens.iconButtonTouchTarget,
+						}}
+					>
+						{navigationIcon}
+					</div>
+				)}
+
+				<m.div
+					className={cn("flex-1 min-w-0", !navigationIcon && "pl-4")}
+					style={{ opacity: smallTitleOpacity }}
+					aria-hidden="true"
+				>
+					<span
+						className={cn(
+							appBarTypography.titleLarge,
+							"truncate block",
+							isCentered && "text-center",
+						)}
+						style={{ color: colors?.titleColor ?? APP_BAR_COLORS.title }}
+					>
+						{title}
+					</span>
+				</m.div>
+
+				{actions && <div className="flex items-center shrink-0">{actions}</div>}
+			</div>
+
+			<div
+				className={cn(
+					"flex flex-col flex-1 px-4 pb-4 justify-end",
+					isCentered ? "items-center" : "items-start",
+				)}
+			>
+				<m.span
+					className={cn(appBarTypography.displaySmall, "truncate w-full")}
+					style={{
+						opacity: largeTitleOpacity,
+						y: largeTitleY,
+						color: colors?.titleColor ?? APP_BAR_COLORS.title,
+						...(isCentered && { textAlign: "center" }),
+					}}
+				>
+					{title}
+				</m.span>
+
+				{subtitle && (
+					<m.span
+						className={cn(appBarTypography.titleMedium, "truncate w-full")}
+						style={{
+							opacity: subtitleOpacity,
+							color: colors?.subtitleColor ?? APP_BAR_COLORS.subtitle,
+							...(isCentered && { textAlign: "center" }),
+						}}
+					>
+						{subtitle}
+					</m.span>
+				)}
+
+				{headerContent && (
+					<m.div
+						className="mt-3 w-full"
+						style={{ opacity: headerContentOpacity }}
+					>
+						{headerContent}
+					</m.div>
+				)}
+			</div>
+		</m.header>
+	);
+}

package/src/ui/app-bar/medium-flexible-app-bar.tsx

@@ -0,0 +1,167 @@
+/**
+ * @file medium-flexible-app-bar.tsx
+ * MD3 Expressive Medium Flexible App Bar.
+ *
+ * Two-row layout in expanded state, collapses to single row on scroll.
+ * Expanded height: 112px (no subtitle) / 136px (with subtitle)
+ * Collapsed height: 64px
+ * Title crossfade: HeadlineMedium (expanded) ↔ TitleLarge (collapsed)
+ *
+ * Supports `exitUntilCollapsed` scroll behavior only.
+ *
+ * @see docs/m3/app-bars/AppBarMediumFlexibleTokens.kt
+ */
+
+import { m } from "motion/react";
+import { cn } from "../../lib/utils";
+import {
+	APP_BAR_COLORS,
+	AppBarTokens,
+	appBarTypography,
+} from "./app-bar.tokens";
+import type { FlexibleAppBarProps } from "./app-bar.types";
+import { useFlexibleAppBar } from "./hooks/use-flexible-app-bar";
+
+/**
+ * MD3 Expressive Medium Flexible App Bar.
+ *
+ * @example
+ * ```tsx
+ * <MediumFlexibleAppBar
+ *   title="Settings"
+ *   subtitle="Manage your preferences"
+ *   navigationIcon={<IconButton aria-label="Go back"><Icon>arrow_back</Icon></IconButton>}
+ *   actions={<IconButton aria-label="More options"><Icon>more_vert</Icon></IconButton>}
+ * />
+ * ```
+ */
+export function MediumFlexibleAppBar({
+	title,
+	subtitle,
+	titleAlignment = "start",
+	navigationIcon,
+	actions,
+	colors,
+	scrollElement,
+	headerContent,
+	collapsedHeight = AppBarTokens.heights.flexibleCollapsed,
+	expandedHeight,
+	className,
+}: FlexibleAppBarProps) {
+	const resolvedExpandedHeight =
+		expandedHeight ??
+		(subtitle
+			? AppBarTokens.heights.mediumFlexWithSubtitleExpanded
+			: AppBarTokens.heights.mediumFlexExpanded);
+
+	const {
+		height,
+		currentBg,
+		cssTransition,
+		largeTitleOpacity,
+		largeTitleY,
+		smallTitleOpacity,
+		subtitleOpacity,
+		headerContentOpacity,
+	} = useFlexibleAppBar({
+		collapsedHeight,
+		expandedHeight: resolvedExpandedHeight,
+		scrollElement,
+		colors,
+		largeTitleFadeRange: [0, 0.4],
+		smallTitleFadeRange: [0.5, 0.9],
+		subtitleFadeRange: [0, 0.3],
+		headerContentFadeRange: [0, 0.25],
+		largeTitleYRange: [0, 8],
+	});
+
+	const isCentered = titleAlignment === "center";
+
+	return (
+		<m.header
+			role="banner"
+			className={cn(
+				"fixed top-0 inset-x-0 z-50 flex flex-col overflow-hidden",
+				className,
+			)}
+			style={{ height, backgroundColor: currentBg, transition: cssTransition }}
+		>
+			<div
+				className="flex items-center px-1 shrink-0"
+				style={{ height: collapsedHeight }}
+			>
+				{navigationIcon && (
+					<div
+						className="shrink-0 flex items-center justify-center"
+						style={{
+							width: AppBarTokens.iconButtonTouchTarget,
+							height: AppBarTokens.iconButtonTouchTarget,
+						}}
+					>
+						{navigationIcon}
+					</div>
+				)}
+
+				<m.div
+					className={cn(
+						"flex-1 min-w-0",
+						isCentered ? "text-center" : "text-start",
+						!navigationIcon && "pl-4",
+					)}
+					style={{ opacity: smallTitleOpacity }}
+					aria-hidden="true"
+				>
+					<span
+						className={cn(appBarTypography.titleLarge, "truncate block")}
+						style={{ color: colors?.titleColor ?? APP_BAR_COLORS.title }}
+					>
+						{title}
+					</span>
+				</m.div>
+
+				{actions && <div className="flex items-center shrink-0">{actions}</div>}
+			</div>
+
+			<div
+				className={cn(
+					"flex flex-col flex-1 px-4 pb-3 justify-end",
+					isCentered ? "items-center" : "items-start",
+				)}
+			>
+				<m.span
+					className={cn(appBarTypography.headlineMedium, "truncate w-full")}
+					style={{
+						opacity: largeTitleOpacity,
+						y: largeTitleY,
+						color: colors?.titleColor ?? APP_BAR_COLORS.title,
+						...(isCentered && { textAlign: "center" }),
+					}}
+				>
+					{title}
+				</m.span>
+
+				{subtitle && (
+					<m.span
+						className={cn(appBarTypography.labelLarge, "truncate w-full")}
+						style={{
+							opacity: subtitleOpacity,
+							color: colors?.subtitleColor ?? APP_BAR_COLORS.subtitle,
+							...(isCentered && { textAlign: "center" }),
+						}}
+					>
+						{subtitle}
+					</m.span>
+				)}
+
+				{headerContent && (
+					<m.div
+						className="mt-2 w-full"
+						style={{ opacity: headerContentOpacity }}
+					>
+						{headerContent}
+					</m.div>
+				)}
+			</div>
+		</m.header>
+	);
+}