@bug-on/md3-react 3.0.1 → 3.0.3

package/src/ui/toolbar/floating-toolbar.tsx

@@ -0,0 +1,344 @@
+import { AnimatePresence, m, type Variants } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+
+import { SPRING_TRANSITION } from "../shared/constants";
+import {
+	type FloatingToolbarColors,
+	standardFloatingToolbarColors,
+} from "./toolbar-colors";
+import { ToolbarContext } from "./toolbar-context";
+import type { FloatingToolbarScrollBehavior } from "./toolbar-scroll-behavior";
+import { FloatingToolbarTokens } from "./toolbar-tokens";
+
+export interface FloatingToolbarProps {
+	/** Whether the toolbar is expanded, showing startContent and endContent */
+	expanded: boolean;
+	/** Orientation of the toolbar */
+	orientation?: "horizontal" | "vertical";
+	/** Color configuration */
+	colors?: FloatingToolbarColors;
+	/** Shape variant: full = pill shape (default), large = large rounded */
+	shape?: "full" | "large";
+	/** Padding inside toolbar container */
+	contentPadding?: React.CSSProperties | string;
+	/** Scroll behavior hook result */
+	scrollBehavior?: FloatingToolbarScrollBehavior;
+	/** Start content (shown when expanded, usually on the left/top) */
+	startContent?: React.ReactNode;
+	/** End content (shown when expanded, usually on the right/bottom) */
+	endContent?: React.ReactNode;
+	/** Main toolbar content (always visible) */
+	children: React.ReactNode;
+	/** Whether to disable the internal scroll translation (useful when parent handles it) */
+	disableScrollTranslation?: boolean;
+	/** Whether to disable layout animation (useful when nested inside FloatingToolbarWithFab) */
+	disableLayoutAnimation?: boolean;
+	/**
+	 * Gap (px) between items in the center children slot.
+	 * Corresponds to MD3 `ContainerBetweenSpace` token (4dp default).
+	 * @default 4
+	 */
+	itemGap?: number;
+	/** Alignment (justify-content) of the center children slot */
+	childrenAlignment?: "start" | "center" | "end";
+	/** Custom CSS class applied to each child item in the toolbar slots */
+	itemClassName?: string;
+	className?: string;
+	style?: React.CSSProperties;
+	"aria-label"?: string;
+}
+
+// --- Module-level helpers ---
+
+const ALIGNMENT_CLASS: Record<"start" | "center" | "end", string> = {
+	start: "justify-start",
+	center: "justify-center",
+	end: "justify-end",
+};
+
+function resolveScrollTranslation(
+	scrollBehavior: FloatingToolbarScrollBehavior | undefined,
+	disabled: boolean | undefined,
+): { x: number | string; y: number | string } {
+	if (!scrollBehavior || disabled) return { x: 0, y: 0 };
+	const { offset, exitDirection } = scrollBehavior;
+	const percent = offset * -100;
+	switch (exitDirection) {
+		case "top":
+			return { y: `${-percent}%`, x: 0 };
+		case "bottom":
+			return { y: `${percent}%`, x: 0 };
+		case "start":
+			return { x: `${-percent}%`, y: 0 };
+		case "end":
+			return { x: `${percent}%`, y: 0 };
+		default:
+			return { x: 0, y: 0 };
+	}
+}
+
+function buildSlotVariants(
+	xHidden: string | number,
+	yHidden: string | number,
+	isHorizontal: boolean,
+): Variants {
+	return {
+		hidden: {
+			x: xHidden,
+			y: yHidden,
+			opacity: 0,
+			scale: 0.9,
+			width: isHorizontal ? 0 : "auto",
+			height: isHorizontal ? "auto" : 0,
+			transition: SPRING_TRANSITION,
+		},
+		visible: {
+			x: 0,
+			y: 0,
+			opacity: 1,
+			scale: 1,
+			width: "auto",
+			height: "auto",
+			transition: SPRING_TRANSITION,
+		},
+	};
+}
+
+function applyItemClassName(
+	nodes: React.ReactNode,
+	itemClassName: string,
+): React.ReactNode {
+	return React.Children.map(nodes, (child) => {
+		if (!React.isValidElement(child)) return child;
+		const element = child as React.ReactElement<{ className?: string }>;
+		return React.cloneElement(element, {
+			className: cn(element.props.className, itemClassName),
+		});
+	});
+}
+
+// --- Component ---
+
+/**
+ * Internal component for rendering the toolbar logic.
+ * Consumers should use HorizontalFloatingToolbar or VerticalFloatingToolbar.
+ */
+const FloatingToolbarBase = React.forwardRef<
+	HTMLDivElement,
+	FloatingToolbarProps
+>(
+	(
+		{
+			expanded,
+			orientation = "horizontal",
+			colors = standardFloatingToolbarColors,
+			shape = "full",
+			contentPadding,
+			scrollBehavior,
+			startContent,
+			endContent,
+			children,
+			disableScrollTranslation,
+			disableLayoutAnimation,
+			itemGap = FloatingToolbarTokens.ContainerBetweenSpace,
+			childrenAlignment = "center",
+			itemClassName,
+			className,
+			style,
+			"aria-label": ariaLabel,
+			...props
+		},
+		ref,
+	) => {
+		const isHorizontal = orientation === "horizontal";
+		const isStringPadding = typeof contentPadding === "string";
+
+		const cssVars = {
+			"--toolbar-bg": colors.toolbarContainerColor,
+			"--toolbar-color": colors.toolbarContentColor,
+			"--toolbar-size": `${FloatingToolbarTokens.ContainerHeight}px`,
+			...(isStringPadding ? {} : contentPadding),
+			...style,
+		} as React.CSSProperties;
+
+		const isScrolledOff = scrollBehavior && scrollBehavior.offset < 0;
+		const shadowClass = expanded ? "shadow-md" : "shadow-sm";
+		const containerShapeClass =
+			shape === "full" ? "rounded-full" : "rounded-2xl";
+
+		const leadingVariants = buildSlotVariants(
+			isHorizontal ? "-100%" : 0,
+			isHorizontal ? 0 : "100%",
+			isHorizontal,
+		);
+		const trailingVariants = buildSlotVariants(
+			isHorizontal ? "100%" : 0,
+			isHorizontal ? 0 : "-100%",
+			isHorizontal,
+		);
+
+		const processNodes = (nodes: React.ReactNode) =>
+			itemClassName ? applyItemClassName(nodes, itemClassName) : nodes;
+
+		const scrollTranslation = resolveScrollTranslation(
+			scrollBehavior,
+			disableScrollTranslation,
+		);
+
+		return (
+			<ToolbarContext.Provider value={{ orientation }}>
+				<m.div
+					ref={ref}
+					initial={false}
+					animate={scrollTranslation}
+					transition={SPRING_TRANSITION}
+				>
+					<m.div
+						role="toolbar"
+						aria-label={ariaLabel || "Floating Toolbar"}
+						aria-orientation={orientation}
+						aria-expanded={expanded}
+						inert={isScrolledOff ? true : undefined}
+						{...(disableLayoutAnimation ? {} : { layout: "position" as const })}
+						transition={SPRING_TRANSITION}
+						style={{
+							...cssVars,
+							backgroundColor: "var(--toolbar-bg)",
+							color: "var(--toolbar-color)",
+						}}
+						className={cn(
+							"flex pointer-events-auto relative",
+							isHorizontal
+								? "max-w-[90vw] h-(--toolbar-size)"
+								: "max-h-[90vh] w-(--toolbar-size) h-fit",
+							containerShapeClass,
+							shadowClass,
+							className,
+						)}
+						{...props}
+					>
+						<div
+							className={cn(
+								"flex-1 w-full h-full rounded-[inherit] scrollbar-hide",
+								isHorizontal
+									? "overflow-x-auto overflow-y-visible"
+									: "overflow-y-auto overflow-x-visible",
+							)}
+						>
+							<div
+								className={cn(
+									"flex items-center gap-1 min-w-0 min-h-0",
+									isHorizontal ? "flex-row h-full" : "flex-col w-full",
+									isStringPadding
+										? contentPadding
+										: isHorizontal
+											? "px-4"
+											: "py-6",
+								)}
+								style={isStringPadding ? undefined : contentPadding}
+							>
+								<AnimatePresence initial={false}>
+									{expanded && startContent && (
+										<m.div
+											key="start"
+											variants={leadingVariants}
+											initial="hidden"
+											animate="visible"
+											exit="hidden"
+											className={cn(
+												"flex shrink-0 overflow-hidden",
+												isHorizontal ? "flex-row" : "flex-col",
+											)}
+										>
+											{processNodes(startContent)}
+										</m.div>
+									)}
+								</AnimatePresence>
+
+								<div
+									className={cn(
+										"flex flex-1 items-center min-w-0 min-h-0 h-full",
+										isHorizontal ? "flex-row" : "flex-col",
+										ALIGNMENT_CLASS[childrenAlignment],
+									)}
+									style={{ gap: itemGap }}
+								>
+									{processNodes(children)}
+								</div>
+
+								<AnimatePresence initial={false}>
+									{expanded && endContent && (
+										<m.div
+											key="end"
+											variants={trailingVariants}
+											initial="hidden"
+											animate="visible"
+											exit="hidden"
+											className={cn(
+												"flex shrink-0 overflow-hidden",
+												isHorizontal ? "flex-row" : "flex-col",
+											)}
+										>
+											{processNodes(endContent)}
+										</m.div>
+									)}
+								</AnimatePresence>
+							</div>
+						</div>
+					</m.div>
+				</m.div>
+			</ToolbarContext.Provider>
+		);
+	},
+);
+FloatingToolbarBase.displayName = "FloatingToolbarBase";
+
+/**
+ * A horizontal floating toolbar that displays navigation and key actions.
+ * It can be positioned anywhere on the screen and floats over the rest of the content.
+ *
+ * @example
+ * ```tsx
+ * const [expanded, setExpanded] = useState(true);
+ * const scrollBehavior = useFloatingToolbarScrollBehavior({ exitDirection: 'bottom' });
+ *
+ * <HorizontalFloatingToolbar
+ *   expanded={expanded}
+ *   scrollBehavior={scrollBehavior}
+ *   startContent={<IconButton icon="undo" />}
+ *   endContent={<IconButton icon="redo" />}
+ * >
+ *   <IconButton icon="bold" />
+ *   <IconButton icon="italic" />
+ * </HorizontalFloatingToolbar>
+ * ```
+ *
+ * @see https://m3.material.io/components/toolbars/guidelines
+ */
+export const HorizontalFloatingToolbar = React.forwardRef<
+	HTMLDivElement,
+	Omit<FloatingToolbarProps, "orientation">
+>((props, ref) => (
+	<FloatingToolbarBase ref={ref} orientation="horizontal" {...props} />
+));
+HorizontalFloatingToolbar.displayName = "HorizontalFloatingToolbar";
+
+/**
+ * A vertical floating toolbar that displays navigation and key actions.
+ * It floats over the rest of the content.
+ *
+ * @example
+ * ```tsx
+ * <VerticalFloatingToolbar expanded={true}>
+ *   <IconButton icon="bold" />
+ * </VerticalFloatingToolbar>
+ * ```
+ */
+export const VerticalFloatingToolbar = React.forwardRef<
+	HTMLDivElement,
+	Omit<FloatingToolbarProps, "orientation">
+>((props, ref) => (
+	<FloatingToolbarBase ref={ref} orientation="vertical" {...props} />
+));
+VerticalFloatingToolbar.displayName = "VerticalFloatingToolbar";

package/src/ui/toolbar/index.ts

@@ -0,0 +1,35 @@
+export {
+	BottomDockedToolbar,
+	type BottomDockedToolbarProps,
+} from "./docked-toolbar";
+export {
+	type FloatingToolbarProps,
+	HorizontalFloatingToolbar,
+	VerticalFloatingToolbar,
+} from "./floating-toolbar";
+export {
+	type FloatingToolbarWithFabProps,
+	HorizontalFloatingToolbarWithFab,
+	VerticalFloatingToolbarWithFab,
+} from "./floating-toolbar-with-fab";
+export {
+	type FloatingToolbarColors,
+	standardFloatingToolbarColors,
+	vibrantFloatingToolbarColors,
+} from "./toolbar-colors";
+export { ToolbarDivider, type ToolbarDividerProps } from "./toolbar-divider";
+export {
+	ToolbarIconButton,
+	type ToolbarIconButtonProps,
+	type ToolbarIconButtonSize,
+	type ToolbarIconButtonVariant,
+} from "./toolbar-icon-button";
+export {
+	type FloatingToolbarScrollBehavior,
+	type UseFloatingToolbarScrollBehaviorOptions,
+	useFloatingToolbarScrollBehavior,
+} from "./toolbar-scroll-behavior";
+export {
+	ToolbarDividerTokens,
+	ToolbarIconButtonTokens,
+} from "./toolbar-tokens";

package/src/ui/toolbar/toolbar-colors.ts

@@ -0,0 +1,37 @@
+/**
+ * Color configuration types and standard values for the FloatingToolbar component.
+ * Maps MD3 design tokens to CSS custom properties used in Tailwind CSS.
+ */
+
+export interface FloatingToolbarColors {
+	/** The background color of the toolbar container */
+	toolbarContainerColor?: string;
+	/** The color of the content (icons, text) inside the toolbar */
+	toolbarContentColor?: string;
+	/** The background color of the FAB container */
+	fabContainerColor?: string;
+	/** The color of the content inside the FAB */
+	fabContentColor?: string;
+}
+
+/**
+ * Standard color configuration for the floating toolbar.
+ * Uses surface container for the toolbar and secondary container for the FAB.
+ */
+export const standardFloatingToolbarColors: FloatingToolbarColors = {
+	toolbarContainerColor: "var(--md-sys-color-surface-container)",
+	toolbarContentColor: "var(--md-sys-color-on-surface)",
+	fabContainerColor: "var(--md-sys-color-secondary-container)",
+	fabContentColor: "var(--md-sys-color-on-secondary-container)",
+};
+
+/**
+ * Vibrant color configuration for the floating toolbar.
+ * Uses primary container for the toolbar and tertiary container for the FAB.
+ */
+export const vibrantFloatingToolbarColors: FloatingToolbarColors = {
+	toolbarContainerColor: "var(--md-sys-color-primary-container)",
+	toolbarContentColor: "var(--md-sys-color-on-primary-container)",
+	fabContainerColor: "var(--md-sys-color-tertiary-container)",
+	fabContentColor: "var(--md-sys-color-on-tertiary-container)",
+};

package/src/ui/toolbar/toolbar-context.tsx

@@ -0,0 +1,13 @@
+import * as React from "react";
+
+export interface ToolbarContextValue {
+	orientation: "horizontal" | "vertical";
+}
+
+export const ToolbarContext = React.createContext<ToolbarContextValue | null>(
+	null,
+);
+
+export function useToolbarContext() {
+	return React.useContext(ToolbarContext);
+}

package/src/ui/toolbar/toolbar-divider.test.tsx

@@ -0,0 +1,54 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { ToolbarContext } from "./toolbar-context";
+import { ToolbarDivider } from "./toolbar-divider";
+
+describe("ToolbarDivider", () => {
+	it("renders as a semantic separator for horizontal toolbar (default)", () => {
+		render(<ToolbarDivider />);
+		const divider = screen.getByRole("separator");
+		expect(divider).toBeInTheDocument();
+	});
+
+	it("renders vertical aria-orientation for horizontal toolbar", () => {
+		render(<ToolbarDivider orientation="horizontal" />);
+		const divider = screen.getByRole("separator");
+		expect(divider).toHaveAttribute("aria-orientation", "vertical");
+	});
+
+	it("renders horizontal aria-orientation for vertical toolbar", () => {
+		render(<ToolbarDivider orientation="vertical" />);
+		const divider = screen.getByRole("separator");
+		expect(divider).toHaveAttribute("aria-orientation", "horizontal");
+	});
+
+	it("applies width class for horizontal toolbar (vertical line)", () => {
+		const { container } = render(<ToolbarDivider orientation="horizontal" />);
+		const divider = container.firstChild as HTMLElement;
+		expect(divider.className).toMatch(/w-px/);
+	});
+
+	it("applies height class for vertical toolbar (horizontal line)", () => {
+		const { container } = render(<ToolbarDivider orientation="vertical" />);
+		const divider = container.firstChild as HTMLElement;
+		expect(divider.className).toMatch(/h-px/);
+	});
+
+	it("applies custom className", () => {
+		const { container } = render(
+			<ToolbarDivider className="my-custom-class" />,
+		);
+		const divider = container.firstChild as HTMLElement;
+		expect(divider.className).toContain("my-custom-class");
+	});
+	it("consumes orientation from ToolbarContext", () => {
+		const { container } = render(
+			<ToolbarContext.Provider value={{ orientation: "vertical" }}>
+				<ToolbarDivider />
+			</ToolbarContext.Provider>,
+		);
+		const divider = container.firstChild as HTMLElement;
+		expect(divider).toHaveAttribute("aria-orientation", "horizontal");
+		expect(divider.className).toMatch(/h-px/);
+	});
+});

package/src/ui/toolbar/toolbar-divider.tsx

@@ -0,0 +1,73 @@
+/**
+ * @file toolbar-divider.tsx
+ *
+ * A decorative divider for use inside MD3 Toolbar components.
+ * Renders as a thin line that visually separates groups of toolbar actions.
+ *
+ * @see https://m3.material.io/components/toolbars/guidelines (Anatomy → Flexibility & slots)
+ */
+
+import type * as React from "react";
+import { cn } from "../../lib/utils";
+import { useToolbarContext } from "./toolbar-context";
+import { FloatingToolbarTokens, ToolbarDividerTokens } from "./toolbar-tokens";
+
+export interface ToolbarDividerProps {
+	/**
+	 * The toolbar's orientation context.
+	 * - `"horizontal"` toolbar → renders a **vertical** divider line.
+	 * - `"vertical"` toolbar → renders a **horizontal** divider line.
+	 * @default "horizontal"
+	 */
+	orientation?: "horizontal" | "vertical";
+	className?: string;
+}
+
+/**
+ * A thin decorative separator for grouping actions inside a Toolbar.
+ *
+ * Inherits its color from the toolbar's `--toolbar-color` CSS variable via
+ * `currentColor`, so it automatically adapts to both standard and vibrant
+ * color configurations.
+ *
+ * @example
+ * ```tsx
+ * <HorizontalFloatingToolbar expanded={true}>
+ *   <IconButton aria-label="Bold"><BoldIcon /></IconButton>
+ *   <IconButton aria-label="Italic"><ItalicIcon /></IconButton>
+ *   <ToolbarDivider />
+ *   <IconButton aria-label="Align left"><AlignLeftIcon /></IconButton>
+ * </HorizontalFloatingToolbar>
+ * ```
+ */
+export const ToolbarDivider: React.FC<ToolbarDividerProps> = ({
+	orientation: propsOrientation,
+	className,
+}) => {
+	const context = useToolbarContext();
+	const orientation = propsOrientation || context?.orientation || "horizontal";
+	const isHorizontalToolbar = orientation === "horizontal";
+
+	return (
+		<hr
+			aria-orientation={isHorizontalToolbar ? "vertical" : "horizontal"}
+			className={cn(
+				"shrink-0 bg-current opacity-30 border-none",
+				isHorizontalToolbar
+					? "w-px h-8 self-center mx-2"
+					: "h-px w-8 self-center my-2",
+				className,
+			)}
+			style={{
+				width: isHorizontalToolbar
+					? `${ToolbarDividerTokens.Thickness}px`
+					: `${ToolbarDividerTokens.HeightRatio * FloatingToolbarTokens.ContainerHeight}px`,
+				height: isHorizontalToolbar
+					? `${ToolbarDividerTokens.HeightRatio * FloatingToolbarTokens.ContainerHeight}px`
+					: `${ToolbarDividerTokens.Thickness}px`,
+			}}
+		/>
+	);
+};
+
+ToolbarDivider.displayName = "ToolbarDivider";

package/src/ui/toolbar/toolbar-icon-button.test.tsx

@@ -0,0 +1,68 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { ToolbarIconButton } from "./toolbar-icon-button";
+
+const FakeIcon = () => <svg data-testid="icon" />;
+
+describe("ToolbarIconButton", () => {
+	it("renders a button with the given aria-label", () => {
+		render(
+			<ToolbarIconButton aria-label="Add">
+				<FakeIcon />
+			</ToolbarIconButton>,
+		);
+		expect(screen.getByRole("button", { name: "Add" })).toBeDefined();
+	});
+
+	it("renders standard variant by default (no background)", () => {
+		const { container } = render(
+			<ToolbarIconButton aria-label="Share">
+				<FakeIcon />
+			</ToolbarIconButton>,
+		);
+		// Standard uses IconButton colorStyle="standard" — no filled bg class expected
+		const button = container.querySelector("button");
+		expect(button).toBeDefined();
+	});
+
+	it("applies narrow width class for toolbarSize=narrow", () => {
+		const { container } = render(
+			<ToolbarIconButton aria-label="Back" toolbarSize="narrow">
+				<FakeIcon />
+			</ToolbarIconButton>,
+		);
+		const button = container.querySelector("button");
+		// className should contain the 40px width override
+		expect(button?.className).toMatch(/w-\[40px\]/);
+	});
+
+	it("applies wide width class for toolbarSize=wide", () => {
+		const { container } = render(
+			<ToolbarIconButton aria-label="Add" toolbarSize="wide" emphasis="filled">
+				<FakeIcon />
+			</ToolbarIconButton>,
+		);
+		const button = container.querySelector("button");
+		expect(button?.className).toMatch(/w-\[64px\]/);
+	});
+
+	it("applies 48px height class for touch target compliance", () => {
+		const { container } = render(
+			<ToolbarIconButton aria-label="Edit">
+				<FakeIcon />
+			</ToolbarIconButton>,
+		);
+		const button = container.querySelector("button");
+		expect(button?.className).toMatch(/h-\[48px\]/);
+	});
+
+	it("is disabled when disabled prop is passed", () => {
+		render(
+			<ToolbarIconButton aria-label="Disabled" disabled>
+				<FakeIcon />
+			</ToolbarIconButton>,
+		);
+		const button = screen.getByRole("button", { name: "Disabled" });
+		expect(button).toHaveAttribute("disabled");
+	});
+});