@bug-on/md3-react 3.0.1 → 3.0.3

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

@@ -0,0 +1,136 @@
+/**
+ * @file toolbar-icon-button.tsx
+ *
+ * A thin wrapper around the MD3 `IconButton` component, pre-configured
+ * for use inside Toolbar slots.
+ *
+ * Supports the three emphasis variants described in the MD3 Flexibility & slots
+ * spec, plus narrow/wide sizing for asymmetric visual hierarchy.
+ *
+ * @see https://m3.material.io/components/toolbars/guidelines (Anatomy → Flexibility & slots)
+ * @see https://m3.material.io/components/icon-buttons/overview
+ */
+
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+import { type BaseIconButtonProps, IconButton } from "../buttons/icon-button";
+import { ToolbarIconButtonTokens } from "./toolbar-tokens";
+
+export interface ToolbarIconButtonProps
+	extends Omit<BaseIconButtonProps, "colorStyle" | "size" | "shape"> {
+	/**
+	 * Visual emphasis variant.
+	 *
+	 * ⚠️ Avoid emphasising more than one action at a time.
+	 * @default "standard"
+	 */
+	emphasis?: ToolbarIconButtonVariant;
+	/**
+	 * Button width sizing.
+	 *
+	 * Height is always `48px` to meet MD3 touch-target requirements.
+	 * @default "default"
+	 */
+	toolbarSize?: ToolbarIconButtonSize;
+	/** Icon content — typically a single SVG icon component. */
+	children: React.ReactNode;
+	/**
+	 * Accessible label — **REQUIRED** because icon buttons have no visible text.
+	 */
+	"aria-label": string;
+}
+
+/**
+ * Width sizing for a toolbar icon button.
+ *
+ * MD3 guideline: *"Use wide and narrow icon buttons"* to create visual hierarchy.
+ * Touch-target height is always 48dp regardless of width.
+ *
+ * - `narrow` → 40px wide (secondary, de-emphasised)
+ * - `default` → 48px wide (standard square touch target)
+ * - `wide` → 64px wide (primary emphasis, draws eye)
+ */
+export type ToolbarIconButtonSize = "narrow" | "default" | "wide";
+
+/**
+ * Visual emphasis variant for a toolbar icon button.
+ *
+ * MD3 guideline: *"Use different icon button color styles, such as filled,
+ * tonal, and standard."*
+ *
+ * ⚠️ **Avoid emphasising more than one action at a time.**
+ * Use `"filled"` or `"tonal"` for the single highest-priority action and
+ * keep all other buttons as `"standard"`.
+ */
+export type ToolbarIconButtonVariant = "standard" | "tonal" | "filled";
+
+const TOOLBAR_ICON_BUTTON_WIDTH: Record<ToolbarIconButtonSize, string> = {
+	narrow: `w-[${ToolbarIconButtonTokens.NarrowWidth}px]`,
+	default: `w-[${ToolbarIconButtonTokens.DefaultWidth}px]`,
+	wide: `w-[${ToolbarIconButtonTokens.WideWidth}px]`,
+};
+
+const VARIANT_TO_COLOR_STYLE: Record<
+	ToolbarIconButtonVariant,
+	"standard" | "filled" | "tonal"
+> = {
+	standard: "standard",
+	tonal: "tonal",
+	filled: "filled",
+};
+
+/**
+ * An MD3 icon button optimised for use inside Toolbar slots.
+ *
+ * Wraps the project's `IconButton` and adds:
+ * - Three emphasis styles (`standard`, `tonal`, `filled`) via `emphasis` prop.
+ * - Three width sizes (`narrow`, `default`, `wide`) for visual hierarchy.
+ * - Always `rounded-full` shape (required for floating toolbars per MD3 spec).
+ * - Always 48dp height to meet MD3 accessibility touch-target requirements.
+ *
+ * @example
+ * ```tsx
+ * // Standard (default) — use for most actions
+ * <ToolbarIconButton aria-label="Share">
+ *   <ShareIcon />
+ * </ToolbarIconButton>
+ *
+ * // Filled + wide — use for the single highest-priority action
+ * <ToolbarIconButton emphasis="filled" toolbarSize="wide" aria-label="Add">
+ *   <PlusIcon />
+ * </ToolbarIconButton>
+ * ```
+ *
+ * @see https://m3.material.io/components/toolbars/guidelines
+ */
+export const ToolbarIconButton = React.forwardRef<
+	HTMLButtonElement,
+	ToolbarIconButtonProps
+>(
+	(
+		{ emphasis = "standard", toolbarSize = "default", className, ...props },
+		ref,
+	) => {
+		const widthClass = TOOLBAR_ICON_BUTTON_WIDTH[toolbarSize];
+		const colorStyle = VARIANT_TO_COLOR_STYLE[emphasis];
+
+		return (
+			<IconButton
+				ref={ref}
+				variant="default"
+				colorStyle={colorStyle}
+				size="md"
+				shape="round"
+				className={cn(
+					`h-[${ToolbarIconButtonTokens.Height}px]`,
+					widthClass,
+					className,
+				)}
+				{...props}
+			/>
+		);
+	},
+);
+
+ToolbarIconButton.displayName = "ToolbarIconButton";

package/src/ui/toolbar/toolbar-scroll-behavior.ts

@@ -0,0 +1,140 @@
+import { useMotionValueEvent, useScroll } from "motion/react";
+import { type RefObject, useEffect, useRef, useState } from "react";
+
+/**
+ * Configuration options for the `useFloatingToolbarScrollBehavior` hook.
+ */
+export interface UseFloatingToolbarScrollBehaviorOptions {
+	/** Direction toolbar exits: 'top' | 'bottom' | 'start' | 'end'. Defaults to 'bottom'. */
+	exitDirection?: "top" | "bottom" | "start" | "end";
+	/** Scroll distance threshold to trigger collapse (in px). Defaults to 10. */
+	collapseThreshold?: number;
+	/** Scroll distance threshold to trigger expand (in px). Defaults to 10. */
+	expandThreshold?: number;
+	/** Optional ref to a scrollable container. If not provided, it listens to window scroll. */
+	scrollContainerRef?: RefObject<HTMLElement | null>;
+}
+
+/**
+ * The resulting behavior object returned by `useFloatingToolbarScrollBehavior`.
+ */
+export interface FloatingToolbarScrollBehavior {
+	/** Current offset. 0 is fully visible, -1 is fully hidden. */
+	offset: number;
+	/** Whether the toolbar is currently expanded. */
+	isExpanded: boolean;
+	/** Optional scroll handler to bind to a React scrollable container (legacy fallback). */
+	onScroll?: (event: React.UIEvent<HTMLElement>) => void;
+	/** Manually update the expanded state of the toolbar. */
+	setExpanded: (expanded: boolean) => void;
+	/** The configured exit direction. */
+	exitDirection: "top" | "bottom" | "start" | "end";
+}
+
+/**
+ * A hook that provides scroll behavior for floating toolbars, allowing them to
+ * collapse (exit) when scrolling down and expand (enter) when scrolling up.
+ * Leverages Framer Motion's useScroll internally for optimized performance.
+ *
+ * @param options Configuration options for scroll behavior.
+ * @returns An object containing the current scroll state and handlers.
+ *
+ * @example
+ * ```tsx
+ * const scrollBehavior = useFloatingToolbarScrollBehavior({
+ *   exitDirection: 'bottom',
+ *   collapseThreshold: 20
+ * });
+ *
+ * <HorizontalFloatingToolbar scrollBehavior={scrollBehavior}>
+ *   <IconButton icon="bold" />
+ * </HorizontalFloatingToolbar>
+ * ```
+ */
+export function useFloatingToolbarScrollBehavior(
+	options: UseFloatingToolbarScrollBehaviorOptions = {},
+): FloatingToolbarScrollBehavior {
+	const {
+		exitDirection = "bottom",
+		collapseThreshold = 10,
+		expandThreshold = 10,
+		scrollContainerRef,
+	} = options;
+
+	const [isExpanded, setIsExpanded] = useState(true);
+	const [offset, setOffset] = useState(0); // 0 to -1
+
+	const { scrollY } = useScroll({
+		container: scrollContainerRef,
+	});
+
+	const lastScrollY = useRef(0);
+	const accumulatedScroll = useRef(0);
+
+	useMotionValueEvent(scrollY, "change", (currentScrollY) => {
+		const deltaY = currentScrollY - lastScrollY.current;
+
+		// Ignore bouncing (negative scroll or past max scroll on macOS)
+		if (currentScrollY < 0) return;
+
+		lastScrollY.current = currentScrollY;
+
+		// Only accumulate if we are scrolling in the same direction
+		if (Math.sign(deltaY) !== Math.sign(accumulatedScroll.current)) {
+			accumulatedScroll.current = deltaY;
+		} else {
+			accumulatedScroll.current += deltaY;
+		}
+
+		if (deltaY > 0 && isExpanded) {
+			// Scrolling down -> collapse
+			if (accumulatedScroll.current > collapseThreshold) {
+				setIsExpanded(false);
+				setOffset(-1);
+			}
+		} else if (deltaY < 0 && !isExpanded) {
+			// Scrolling up -> expand
+			if (Math.abs(accumulatedScroll.current) > expandThreshold) {
+				setIsExpanded(true);
+				setOffset(0);
+			}
+		}
+	});
+
+	// Accessibility: Always force expanded if forced-colors mode or accessibility preferences
+	useEffect(() => {
+		if (typeof window !== "undefined") {
+			const matchMedia = window.matchMedia("(forced-colors: active)");
+			if (matchMedia.matches) {
+				setIsExpanded(true);
+				setOffset(0);
+			}
+
+			const listener = (e: MediaQueryListEvent) => {
+				if (e.matches) {
+					setIsExpanded(true);
+					setOffset(0);
+				}
+			};
+
+			matchMedia.addEventListener("change", listener);
+			return () => matchMedia.removeEventListener("change", listener);
+		}
+	}, []);
+
+	const setExpanded = (expanded: boolean) => {
+		setIsExpanded(expanded);
+		setOffset(expanded ? 0 : -1);
+	};
+
+	// Dummy onScroll for legacy compatibility if users still attach it
+	const onScroll = () => {};
+
+	return {
+		offset,
+		isExpanded,
+		onScroll,
+		setExpanded,
+		exitDirection,
+	};
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Design tokens for the MD3 Expressive Toolbars components.
+ * Extracted from `FloatingToolbarTokens.kt` and `FabBaselineTokens.kt`.
+ */
+
+export const FloatingToolbarTokens = {
+	ContainerBetweenSpace: 4,
+	ContainerExternalPadding: 16,
+	ContainerHeight: 64,
+	ContainerLeadingSpace: 8,
+	ContainerShape: "full",
+	ContainerTrailingSpace: 8,
+	VerticalContainerExternalPadding: 24,
+} as const;
+
+export const FabBaselineTokens = {
+	ContainerHeight: 56,
+	ContainerWidth: 56,
+	MediumContainerHeight: 80,
+	MediumContainerWidth: 80,
+	IconSize: 24,
+	MediumIconSize: 28,
+} as const;
+
+export const ToolbarToFabGap = 8;
+
+/**
+ * Design tokens for the ToolbarDivider component.
+ * The divider is a decorative separator used to group toolbar actions.
+ */
+export const ToolbarDividerTokens = {
+	/** Divider line thickness in px */
+	Thickness: 1,
+	/** Divider size as a fraction of the toolbar container dimension */
+	HeightRatio: 0.5,
+} as const;
+
+/**
+ * Design tokens for the ToolbarIconButton component.
+ * Sizes follow MD3 Expressive touch-target minimums (48dp height always).
+ * - narrow: de-emphasised secondary actions
+ * - default: standard icon button
+ * - wide: primary action emphasis inside the toolbar
+ */
+export const ToolbarIconButtonTokens = {
+	NarrowWidth: 40,
+	DefaultWidth: 48,
+	WideWidth: 64,
+	/** Minimum touch-target height per MD3 accessibility guidelines */
+	Height: 48,
+} as const;

package/test-clip.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <title>Test Clip - MD3 Expressive</title>
+  <meta name="description" content="Test file for clipping behavior in MD3 Expressive components.">
+  <meta property="og:title" content="Test Clip - MD3 Expressive">
+  <meta property="og:description" content="Test file for clipping behavior in MD3 Expressive components.">
+  <style>
+    .wrapper {
+      display: flex;
+      align-items: center;
+      overflow: hidden;
+      width: fit-content;
+      height: 64px;
+      background: rgba(255,0,0,0.2);
+    }
+    .inner {
+      width: 200px;
+      height: 64px;
+      border-radius: 32px;
+      background: blue;
+      box-shadow: 0 4px 6px rgba(0,0,0,0.5);
+    }
+  </style>
+</head>
+<body>
+  <div class="wrapper">
+    <div class="inner"></div>
+  </div>
+</body>
+</html>

package/test-shadow.html

@@ -1,7 +1,11 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-<style>
+  <title>Test Shadow - MD3 Expressive</title>
+  <meta name="description" content="Test file for shadow behavior in MD3 Expressive components.">
+  <meta property="og:title" content="Test Shadow - MD3 Expressive">
+  <meta property="og:description" content="Test file for shadow behavior in MD3 Expressive components.">
+  <style>
   .outer {
     width: 200px;
     display: flex;

package/test-width.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <title>Test Width - MD3 Expressive</title>
+  <meta name="description" content="Test file for width transitions in MD3 Expressive components.">
+  <meta property="og:title" content="Test Width - MD3 Expressive">
+  <meta property="og:description" content="Test file for width transitions in MD3 Expressive components.">
+  <style>
+    .wrapper {
+      box-sizing: border-box;
+      overflow: hidden;
+      padding: 20px;
+      margin: -20px;
+      width: 0px; /* Animate to 0 */
+      background: rgba(0,255,0,0.5);
+      border: 1px solid red;
+    }
+    .inner {
+      width: 100px;
+      height: 50px;
+      background: blue;
+    }
+  </style>
+</head>
+<body>
+  <div style="display: flex;">
+    <div style="width: 50px; height: 50px; background: yellow;"></div>
+    <div class="wrapper">
+      <div class="inner"></div>
+    </div>
+    <div style="width: 50px; height: 50px; background: yellow;"></div>
+  </div>
+</body>
+</html>