@bug-on/md3-react 3.0.2 → 3.0.3

package/src/ui/shared/motion-tokens.ts

@@ -0,0 +1,238 @@
+/**
+ * @file ui/shared/motion-tokens.ts
+ *
+ * Framer Motion spring presets derived from the official MD3 Expressive
+ * motion physics system (May 2025).
+ *
+ * Usage hierarchy:
+ *   1. Import a named preset (e.g. `FAST_SPATIAL_SPRING`) for convenience.
+ *   2. Call `getMotionSpring(speed, type)` when you need to pick dynamically.
+ *   3. Call `getMotionTransitionCSS(speed, type, scheme?)` for pure-CSS contexts.
+ *
+ * @see https://m3.material.io/styles/motion/overview/how-it-works
+ * @see https://m3.material.io/styles/motion/overview/specs
+ */
+
+import type { Transition } from "motion/react";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MD3 Spring Token Structure
+//
+// MD3 defines springs as dampingRatio (0–1) + stiffness.
+// Framer Motion uses absolute `damping` coefficient.
+//
+// Conversion (with Framer's default mass = 1):
+//   damping = 2 × dampingRatio × √stiffness
+//
+// Computed values (rounded to 2 decimal places):
+//
+//   fast  spatial:  2 × 0.6 × √800   = 2 × 0.6 × 28.28  ≈ 33.94
+//   fast  effects:  2 × 1.0 × √3800  = 2 × 61.64         ≈ 123.29
+//   default spatial: 2 × 0.8 × √380  = 2 × 0.8 × 19.49  ≈ 31.19
+//   default effects: 2 × 1.0 × √1600 = 2 × 40            = 80
+//   slow  spatial:  2 × 0.8 × √200   = 2 × 0.8 × 14.14  ≈ 22.63
+//   slow  effects:  2 × 1.0 × √800   = 2 × 28.28         ≈ 56.57
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ── Spatial springs — use for position, size, border-radius, rotation, scale ─
+
+/**
+ * MD3 Expressive — Fast Spatial Spring
+ * `md.sys.motion.spring.fast.spatial` (dampingRatio: 0.6, stiffness: 800)
+ *
+ * Use for: small components (buttons, switches, chips).
+ * Has notable bounce/overshoot — feels snappy and expressive.
+ */
+export const FAST_SPATIAL_SPRING: Transition = {
+	type: "spring",
+	stiffness: 800,
+	damping: 33.94,
+} as const;
+
+/**
+ * MD3 Expressive — Default Spatial Spring
+ * `md.sys.motion.spring.default.spatial` (dampingRatio: 0.8, stiffness: 380)
+ *
+ * Use for: medium elements (bottom sheets, menus, navigation rail).
+ * Gentle overshoot — the go-to spring for most UI animations.
+ */
+export const DEFAULT_SPATIAL_SPRING: Transition = {
+	type: "spring",
+	stiffness: 380,
+	damping: 31.19,
+} as const;
+
+/**
+ * MD3 Expressive — Slow Spatial Spring
+ * `md.sys.motion.spring.slow.spatial` (dampingRatio: 0.8, stiffness: 200)
+ *
+ * Use for: full-screen transitions and large layout shifts.
+ * Subtle, slow overshoot.
+ */
+export const SLOW_SPATIAL_SPRING: Transition = {
+	type: "spring",
+	stiffness: 200,
+	damping: 22.63,
+} as const;
+
+// ── Effects springs — use for color, opacity (critically damped, no bounce) ──
+
+/**
+ * MD3 Expressive — Fast Effects Spring
+ * `md.sys.motion.spring.fast.effects` (dampingRatio: 1.0, stiffness: 3800)
+ *
+ * Use for: color changes on switches, icon swaps, badge counts.
+ * Critically damped — very fast, no overshoot.
+ */
+export const FAST_EFFECTS_SPRING: Transition = {
+	type: "spring",
+	stiffness: 3800,
+	damping: 123.29,
+} as const;
+
+/**
+ * MD3 Expressive — Default Effects Spring
+ * `md.sys.motion.spring.default.effects` (dampingRatio: 1.0, stiffness: 1600)
+ *
+ * Use for: opacity fades, color transitions for medium-sized elements.
+ * Critically damped — smooth with no overshoot.
+ */
+export const DEFAULT_EFFECTS_SPRING: Transition = {
+	type: "spring",
+	stiffness: 1600,
+	damping: 80,
+} as const;
+
+/**
+ * MD3 Expressive — Slow Effects Spring
+ * `md.sys.motion.spring.slow.effects` (dampingRatio: 1.0, stiffness: 800)
+ *
+ * Use for: full-screen opacity/color transitions.
+ * Critically damped — slow and smooth.
+ */
+export const SLOW_EFFECTS_SPRING: Transition = {
+	type: "spring",
+	stiffness: 800,
+	damping: 56.57,
+} as const;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dynamic helper
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type SpringSpeed = "fast" | "default" | "slow";
+export type SpringAnimationType = "spatial" | "effects";
+
+const springMap = {
+	fast: { spatial: FAST_SPATIAL_SPRING, effects: FAST_EFFECTS_SPRING },
+	default: { spatial: DEFAULT_SPATIAL_SPRING, effects: DEFAULT_EFFECTS_SPRING },
+	slow: { spatial: SLOW_SPATIAL_SPRING, effects: SLOW_EFFECTS_SPRING },
+} as const;
+
+/**
+ * Pick a Framer Motion spring by speed and type.
+ *
+ * @example
+ * ```tsx
+ * transition={getMotionSpring("fast", "spatial")}
+ * ```
+ */
+export function getMotionSpring(
+	speed: SpringSpeed,
+	type: SpringAnimationType,
+): Transition {
+	return springMap[speed][type];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CSS transition strings
+// For contexts where Framer Motion is not used (plain CSS / Tailwind).
+// Uses official Web spring → CSS cubic-bezier conversion table.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CSS_CURVES = {
+	expressive: {
+		fast: {
+			spatial: {
+				curve: "cubic-bezier(0.42, 1.67, 0.21, 0.90)",
+				durationMs: 350,
+			},
+			effects: {
+				curve: "cubic-bezier(0.31, 0.94, 0.34, 1.00)",
+				durationMs: 150,
+			},
+		},
+		default: {
+			spatial: {
+				curve: "cubic-bezier(0.38, 1.21, 0.22, 1.00)",
+				durationMs: 500,
+			},
+			effects: {
+				curve: "cubic-bezier(0.34, 0.80, 0.34, 1.00)",
+				durationMs: 200,
+			},
+		},
+		slow: {
+			spatial: {
+				curve: "cubic-bezier(0.39, 1.29, 0.35, 0.98)",
+				durationMs: 650,
+			},
+			effects: {
+				curve: "cubic-bezier(0.34, 0.88, 0.34, 1.00)",
+				durationMs: 300,
+			},
+		},
+	},
+	standard: {
+		fast: {
+			spatial: {
+				curve: "cubic-bezier(0.27, 1.06, 0.18, 1.00)",
+				durationMs: 350,
+			},
+			effects: {
+				curve: "cubic-bezier(0.31, 0.94, 0.34, 1.00)",
+				durationMs: 150,
+			},
+		},
+		default: {
+			spatial: {
+				curve: "cubic-bezier(0.27, 1.06, 0.18, 1.00)",
+				durationMs: 500,
+			},
+			effects: {
+				curve: "cubic-bezier(0.34, 0.80, 0.34, 1.00)",
+				durationMs: 200,
+			},
+		},
+		slow: {
+			spatial: {
+				curve: "cubic-bezier(0.27, 1.06, 0.18, 1.00)",
+				durationMs: 750,
+			},
+			effects: {
+				curve: "cubic-bezier(0.34, 0.88, 0.34, 1.00)",
+				durationMs: 300,
+			},
+		},
+	},
+} as const;
+
+export type MotionScheme = "expressive" | "standard";
+
+/**
+ * Returns a CSS `transition` value string using the official MD3 web curve
+ * conversion, e.g. `"500ms cubic-bezier(0.38, 1.21, 0.22, 1.00)"`.
+ *
+ * @example
+ * ```ts
+ * element.style.transition = `border-radius ${getMotionTransitionCSS("default", "spatial")}`;
+ * ```
+ */
+export function getMotionTransitionCSS(
+	speed: SpringSpeed,
+	type: SpringAnimationType,
+	scheme: MotionScheme = "expressive",
+): string {
+	const { curve, durationMs } = CSS_CURVES[scheme][speed][type];
+	return `${durationMs}ms ${curve}`;
+}

package/src/ui/snackbar/snackbar.tsx

@@ -27,8 +27,9 @@ import {
 } from "motion/react";
 import * as React from "react";
 import { cn } from "../../lib/utils";
+import { IconButton } from "../buttons/icon-button";
 import { Icon } from "../icon";
-import { IconButton } from "../icon-button";
+import { DEFAULT_SPATIAL_SPRING } from "../shared/motion-tokens";
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -44,11 +45,8 @@ const RESULT = {
 
 // ─── Animation Config (Framer Motion — NOT CSS transitions) ──────────────────
 
-const SNACKBAR_SPRING = {
-	type: "spring" as const,
-	bounce: 0.15,
-	duration: 0.4,
-};
+// MD3 default.spatial: stiffness=380, dampingRatio=0.8 → Framer damping ≈ 31.19
+const SNACKBAR_SPRING = DEFAULT_SPATIAL_SPRING;
 
 const SNACKBAR_ANIM = {
 	initial: { opacity: 0, y: 56, scale: 0.9 },

package/src/ui/switch/switch.tsx

@@ -20,32 +20,26 @@ import {
 import * as React from "react";
 import { cn } from "../../lib/utils";
 import { Ripple, type RippleOrigin } from "../ripple";
+import {
+	FAST_EFFECTS_SPRING,
+	FAST_SPATIAL_SPRING,
+} from "../shared/motion-tokens";
 import { SwitchColors, SwitchTokens } from "./switch.tokens";
 import type { SwitchProps } from "./switch.types";
 
 // ─── Animation constants ───────────────────────────────────────────────────────
 
-/**
- * FastSpatial spring — equivalent to MotionSchemeKeyTokens.FastSpatial.
- * Used for thumb translation and size morph on checked state change.
- */
-const FAST_SPATIAL_SPRING = {
-	type: "spring",
-	stiffness: 500,
-	damping: 40,
-} as const;
+// FAST_SPATIAL_SPRING and FAST_EFFECTS_SPRING imported from motion-tokens:
+//   fast.spatial: stiffness=800, dampingRatio=0.6 → Framer damping≈33.94 (thumb movement/size)
+//   fast.effects: stiffness=3800, dampingRatio=1.0 → Framer damping≈123.29 (state layer)
 
 /** Instant transition (SnapSpec equivalent) — used when thumb is pressed. */
 const SNAP_TRANSITION = { duration: 0 } as const;
 
-/** Color transition for track/thumb color changes. */
-const COLOR_TRANSITION = { duration: 0.2, ease: "easeInOut" } as const;
-
-/** State layer spring — for hover/focus overlay. */
-const STATE_LAYER_SPRING = {
-	type: "spring",
-	stiffness: 400,
-	damping: 30,
+/** Color transition for track/thumb color changes. Uses fast.effects CSS curve. */
+const COLOR_TRANSITION = {
+	duration: 0.15,
+	ease: [0.31, 0.94, 0.34, 1.0] as [number, number, number, number],
 } as const;
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -223,7 +217,7 @@ const SwitchVisual = React.memo(function SwitchVisual({
 
 	const stateLayerTransition = prefersReduced
 		? { duration: 0 }
-		: STATE_LAYER_SPRING;
+		: FAST_EFFECTS_SPRING;
 
 	return (
 		<div

package/src/ui/text-field/text-field.tokens.ts

@@ -12,17 +12,17 @@
 
 export const TF_COLORS = {
 	/** Filled container background */
-	filledBg: "var(--color-m3-surface-container-highest)",
+	filledBg: "var(--md-sys-color-surface-container-highest)",
 	/** Input text color */
-	inputText: "var(--color-m3-on-surface)",
+	inputText: "var(--md-sys-color-on-surface)",
 	/** Label (unfloated) + icons + prefix/suffix + supporting text */
-	onSurfaceVariant: "var(--color-m3-on-surface-variant)",
+	onSurfaceVariant: "var(--md-sys-color-on-surface-variant)",
 	/** Focused active indicator / outline, floated label */
-	primary: "var(--color-m3-primary)",
+	primary: "var(--md-sys-color-primary)",
 	/** Error indicator / outline / label / icon / supporting text */
-	error: "var(--color-m3-error)",
+	error: "var(--md-sys-color-error)",
 	/** Outlined border (enabled) */
-	outline: "var(--color-m3-outline)",
+	outline: "var(--md-sys-color-outline)",
 	/** Transparent */
 	transparent: "transparent",
 } as const;
@@ -78,12 +78,12 @@ export const TF_TYPOGRAPHY = {
 export const TF_CLASSES = {
 	// Container
 	filledContainer:
-		"bg-[var(--color-m3-surface-container-highest)] rounded-tl-[4px] rounded-tr-[4px] rounded-bl-none rounded-br-none",
+		"bg-[var(--md-sys-color-surface-container-highest)] rounded-tl-[4px] rounded-tr-[4px] rounded-bl-none rounded-br-none",
 	outlinedContainer: "bg-transparent rounded-[4px]",
 
 	// Input
 	input:
-		"bg-transparent outline-none w-full text-base text-[var(--color-m3-on-surface)] caret-[var(--color-m3-primary)] placeholder:text-[var(--color-m3-on-surface-variant)]",
+		"bg-transparent outline-none w-full text-base text-[var(--md-sys-color-on-surface)] caret-[var(--md-sys-color-primary)] placeholder:text-[var(--md-sys-color-on-surface-variant)]",
 	inputNoSpinner:
 		"[appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none",
 
@@ -91,14 +91,14 @@ export const TF_CLASSES = {
 	disabled: "opacity-[0.38] pointer-events-none cursor-not-allowed",
 
 	// Supporting text
-	supportingText: "text-xs text-[var(--color-m3-on-surface-variant)] px-4",
-	errorText: "text-xs text-[var(--color-m3-error)] px-4",
+	supportingText: "text-xs text-[var(--md-sys-color-on-surface-variant)] px-4",
+	errorText: "text-xs text-[var(--md-sys-color-error)] px-4",
 
 	// Prefix / Suffix
 	prefixSuffix:
-		"text-base text-[var(--color-m3-on-surface-variant)] select-none shrink-0",
+		"text-base text-[var(--md-sys-color-on-surface-variant)] select-none shrink-0",
 
 	// State layer (hover)
 	stateLayer:
-		"absolute inset-0 bg-[var(--color-m3-on-surface)] opacity-0 transition-opacity duration-150 pointer-events-none rounded-[inherit]",
+		"absolute inset-0 bg-[var(--md-sys-color-on-surface)] opacity-0 transition-opacity duration-150 pointer-events-none rounded-[inherit]",
 } as const;

package/src/ui/text-field/text-field.tsx

@@ -18,12 +18,11 @@
  * @see https://m3.material.io/components/text-fields/overview
  */
 
-"use client";
-
 import { domMax, LazyMotion, useReducedMotion } from "motion/react";
 import * as React from "react";
 import { cn } from "../../lib/utils";
 import { ScrollArea } from "../scroll-area";
+import { useToolbarContext } from "../toolbar/toolbar-context";
 import { ActiveIndicator } from "./subcomponents/active-indicator";
 import { FloatingLabel } from "./subcomponents/floating-label";
 import { LeadingIcon } from "./subcomponents/leading-icon";
@@ -107,6 +106,12 @@ const TextFieldComponent = React.forwardRef<TextFieldHandle, TextFieldProps>(
 		ref,
 	) => {
 		const prefersReduced = useReducedMotion() ?? false;
+		const toolbarContext = useToolbarContext();
+		const isInToolbar = !!toolbarContext;
+
+		// ── Props Override (Toolbar) ──────────────────────────────────────────
+		const resolvedDense = isInToolbar ? true : dense;
+		const resolvedLabel = isInToolbar ? undefined : label;
 
 		// ── IDs ───────────────────────────────────────────────────────────────
 		const generatedId = React.useId();
@@ -141,7 +146,9 @@ const TextFieldComponent = React.forwardRef<TextFieldHandle, TextFieldProps>(
 			errorProp ||
 			!!nativeError ||
 			(maxLength !== undefined && currentValue.length > maxLength);
-		const containerHeight = dense ? TF_SIZE.denseHeight : TF_SIZE.height;
+		const containerHeight = resolvedDense
+			? TF_SIZE.denseHeight
+			: TF_SIZE.height;
 		const showAsterisk = required && !noAsterisk;
 
 		// ── Refs ──────────────────────────────────────────────────────────────
@@ -270,7 +277,8 @@ const TextFieldComponent = React.forwardRef<TextFieldHandle, TextFieldProps>(
 
 		// ── Input classes ─────────────────────────────────────────────────────
 		const inputClass = cn(
-			"bg-transparent outline-none w-full self-end",
+			"bg-transparent outline-none w-full",
+			isInToolbar ? "self-center" : "self-end",
 			"text-base leading-6 text-m3-on-surface",
 			"caret-[var(--color-m3-primary)]",
 			"placeholder:text-m3-on-surface-variant/60",
@@ -315,22 +323,26 @@ const TextFieldComponent = React.forwardRef<TextFieldHandle, TextFieldProps>(
 		const containerClass = cn(
 			"relative flex items-center",
 			variant === "filled"
-				? "bg-[var(--color-m3-surface-container-highest)] rounded-tl-sm rounded-tr-sm"
+				? isInToolbar
+					? "bg-transparent"
+					: "bg-[var(--color-m3-surface-container-highest)] rounded-tl-sm rounded-tr-sm"
 				: "bg-transparent rounded-sm",
 			fullWidth ? "w-full" : "w-fit",
 		);
 
 		const innerClass = cn(
-			"relative flex flex-col flex-1 min-w-0",
+			"relative flex flex-col flex-1 min-w-0 h-full",
 			paddingStart,
 			paddingEnd,
-			variant === "filled"
-				? dense
-					? "pt-5 pb-2"
-					: "pt-6 pb-2"
-				: dense
-					? "py-3"
-					: "py-4",
+			isInToolbar
+				? "justify-center"
+				: variant === "filled"
+					? resolvedDense
+						? "pt-5 pb-2"
+						: "pt-6 pb-2"
+					: resolvedDense
+						? "py-3"
+						: "py-4",
 		);
 
 		const wrapperClass = cn(
@@ -340,7 +352,7 @@ const TextFieldComponent = React.forwardRef<TextFieldHandle, TextFieldProps>(
 			className,
 		);
 
-		const containerHeightClass = dense ? "h-12" : "h-14";
+		const containerHeightClass = resolvedDense ? "h-12" : "h-14";
 
 		// ── Render ────────────────────────────────────────────────────────────
 		return (
@@ -354,7 +366,7 @@ const TextFieldComponent = React.forwardRef<TextFieldHandle, TextFieldProps>(
 						)}
 					>
 						{/* Outlined border with animated notch */}
-						{variant === "outlined" && (
+						{variant === "outlined" && !isInToolbar && (
 							<OutlineContainer
 								isFloated={isFloated}
 								isFocused={isFocused}
@@ -367,7 +379,7 @@ const TextFieldComponent = React.forwardRef<TextFieldHandle, TextFieldProps>(
 						)}
 
 						{/* Hover state layer (filled only) */}
-						{variant === "filled" && (
+						{variant === "filled" && !isInToolbar && (
 							<div
 								aria-hidden="true"
 								className={cn(
@@ -388,9 +400,9 @@ const TextFieldComponent = React.forwardRef<TextFieldHandle, TextFieldProps>(
 						{/* Inner column: floating label + input row */}
 						<div className={innerClass}>
 							{/* Floating label — absolutely positioned over the inner region */}
-							{label && (
+							{resolvedLabel && (
 								<FloatingLabel
-									text={label}
+									text={resolvedLabel}
 									isFloated={isFloated}
 									isFocused={isFocused}
 									isError={isError}
@@ -485,7 +497,7 @@ const TextFieldComponent = React.forwardRef<TextFieldHandle, TextFieldProps>(
 						)}
 
 						{/* Active indicator: bottom border line (filled variant only) */}
-						{variant === "filled" && (
+						{variant === "filled" && !isInToolbar && (
 							<ActiveIndicator
 								isFocused={isFocused}
 								isError={isError}

package/src/ui/theme-provider/index.tsx

@@ -106,11 +106,7 @@ export function MD3ThemeProvider({
 		) as ThemeMode | null;
 
 		if (savedColor) setSourceColor(savedColor);
-		if (
-			savedMode === "light" ||
-			savedMode === "dark" ||
-			savedMode === "system"
-		)
+		if (savedMode === "light" || savedMode === "dark" || savedMode === "system")
 			setMode(savedMode);
 
 		setIsHydrated(true);

package/src/ui/toc.tsx

@@ -139,7 +139,7 @@ export function TableOfContents({
 			aria-label="On this page"
 			className={cn("pl-6 flex flex-col h-full", className)}
 		>
-			<h4 className="text-xs font-bold text-m3-on-surface-variant uppercase tracking-widest mb-4 sm:hidden lg:block">
+			<h4 className="text-xs font-bold text-m3-on-surface-variant uppercase tracking-widest mb-4 hidden lg:block">
 				On this page
 			</h4>
 			<ScrollArea

package/src/ui/toolbar/__snapshots__/bottom-docked-toolbar.test.tsx.snap

@@ -0,0 +1,51 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`BottomDockedToolbar > snapshots: with leading and trailing content 1`] = `
+<div
+  aria-label="Bottom Docked Toolbar"
+  class="fixed bottom-0 left-0 right-0 w-full z-40 flex items-center h-16 justify-between shadow-[0_-1px_3px_rgba(0,0,0,0.1)] pointer-events-auto"
+  role="toolbar"
+  style="--toolbar-bg: var(--md-sys-color-surface-container); --toolbar-color: var(--md-sys-color-on-surface); background-color: var(--toolbar-bg); color: var(--toolbar-color); padding-left: 16px; padding-right: 16px; transform: none;"
+>
+  <div
+    class="flex items-center justify-start flex-1 shrink-0"
+  >
+    <span>
+      Lead
+    </span>
+  </div>
+  <div
+    class="flex items-center justify-center flex-1 shrink-0"
+  >
+    Center
+  </div>
+  <div
+    class="flex items-center justify-end flex-1 shrink-0"
+  >
+    <span>
+      Trail
+    </span>
+  </div>
+</div>
+`;
+
+exports[`BottomDockedToolbar > snapshots: without optional content 1`] = `
+<div
+  aria-label="Bottom Docked Toolbar"
+  class="fixed bottom-0 left-0 right-0 w-full z-40 flex items-center h-16 justify-between shadow-[0_-1px_3px_rgba(0,0,0,0.1)] pointer-events-auto"
+  role="toolbar"
+  style="--toolbar-bg: var(--md-sys-color-surface-container); --toolbar-color: var(--md-sys-color-on-surface); background-color: var(--toolbar-bg); color: var(--toolbar-color); padding-left: 16px; padding-right: 16px; transform: none;"
+>
+  <div
+    class="flex items-center justify-start flex-1 shrink-0"
+  />
+  <div
+    class="flex items-center justify-center flex-1 shrink-0"
+  >
+    Center
+  </div>
+  <div
+    class="flex items-center justify-end flex-1 shrink-0"
+  />
+</div>
+`;