@aphrody/m3-motion 3.3.2 → 3.3.4

package/src/components/M3Transition.tsx

@@ -0,0 +1,207 @@
+"use client";
+import * as React from "react";
+import { AnimatePresence, motion } from "motion/react";
+import type { HTMLMotionProps, MotionStyle, Transition, Variants } from "motion/react";
+import { m3Easings, m3Durations } from "../easings.js";
+import { motionVariants, useM3ReducedMotion } from "../hooks/useM3ReducedMotion.js";
+
+export type M3TransitionPattern =
+  | "fade"
+  | "fade-through"
+  | "shared-axis-x"
+  | "shared-axis-y"
+  | "shared-axis-z"
+  | "collapse";
+
+export interface M3TransitionProps extends Omit<HTMLMotionProps<"div">, "variants" | "style"> {
+  style?: MotionStyle;
+  /**
+   * Unique key representing the active view/content. Changing this key triggers the transition.
+   */
+  stateKey: React.Key;
+  /**
+   * Which M3 transition pattern to apply.
+   * @default "fade"
+   */
+  pattern?: M3TransitionPattern;
+  /**
+   * Direction of navigation for shared-axis-* patterns.
+   * @default true
+   */
+  forward?: boolean;
+  /**
+   * Custom variants — overrides the pattern defaults entirely.
+   */
+  variants?: Variants;
+  /**
+   * AnimatePresence mode.
+   * @default "wait"
+   */
+  mode?: "wait" | "sync" | "popLayout";
+}
+
+const OFFSET = 30;
+const SCALE_OFFSET = 0.08;
+
+function buildVariants(pattern: M3TransitionPattern, forward: boolean): Variants {
+  const enterTransition: Transition = {
+    ease: m3Easings.emphasizedDecelerate,
+    duration: m3Durations.medium2,
+  };
+  const exitTransition: Transition = {
+    ease: m3Easings.emphasizedAccelerate,
+    duration: m3Durations.short4,
+  };
+
+  switch (pattern) {
+    case "fade-through":
+      return {
+        initial: { opacity: 0, scale: 0.92 },
+        animate: {
+          opacity: 1,
+          scale: 1,
+          transition: {
+            opacity: { ease: m3Easings.emphasizedDecelerate, duration: 0.21 },
+            scale: { ease: m3Easings.emphasizedDecelerate, duration: 0.21 },
+          },
+        },
+        exit: {
+          opacity: 0,
+          transition: { opacity: { ease: m3Easings.emphasizedAccelerate, duration: 0.09 } },
+        },
+      };
+    case "shared-axis-x":
+      return {
+        initial: { opacity: 0, x: forward ? OFFSET : -OFFSET },
+        animate: {
+          opacity: 1,
+          x: 0,
+          transition: {
+            x: enterTransition,
+            opacity: { ease: m3Easings.standard, duration: m3Durations.medium2 },
+          },
+        },
+        exit: {
+          opacity: 0,
+          x: forward ? -OFFSET : OFFSET,
+          transition: {
+            x: exitTransition,
+            opacity: { ease: m3Easings.standard, duration: m3Durations.short4 },
+          },
+        },
+      };
+    case "shared-axis-y":
+      return {
+        initial: { opacity: 0, y: forward ? OFFSET : -OFFSET },
+        animate: {
+          opacity: 1,
+          y: 0,
+          transition: {
+            y: enterTransition,
+            opacity: { ease: m3Easings.standard, duration: m3Durations.medium2 },
+          },
+        },
+        exit: {
+          opacity: 0,
+          y: forward ? -OFFSET : OFFSET,
+          transition: {
+            y: exitTransition,
+            opacity: { ease: m3Easings.standard, duration: m3Durations.short4 },
+          },
+        },
+      };
+    case "shared-axis-z":
+      return {
+        initial: { opacity: 0, scale: forward ? 1 - SCALE_OFFSET : 1 + SCALE_OFFSET },
+        animate: {
+          opacity: 1,
+          scale: 1,
+          transition: {
+            scale: enterTransition,
+            opacity: { ease: m3Easings.standard, duration: m3Durations.medium2 },
+          },
+        },
+        exit: {
+          opacity: 0,
+          scale: forward ? 1 + SCALE_OFFSET : 1 - SCALE_OFFSET,
+          transition: {
+            scale: exitTransition,
+            opacity: { ease: m3Easings.standard, duration: m3Durations.short4 },
+          },
+        },
+      };
+    case "collapse":
+      return {
+        initial: { height: 0, opacity: 0 },
+        animate: {
+          height: "auto",
+          opacity: 1,
+          transition: {
+            height: { ease: m3Easings.emphasized, duration: m3Durations.medium4 },
+            opacity: { ease: m3Easings.standard, duration: m3Durations.medium2 },
+          },
+        },
+        exit: {
+          height: 0,
+          opacity: 0,
+          transition: {
+            height: { ease: m3Easings.emphasized, duration: m3Durations.medium4 },
+            opacity: { ease: m3Easings.standard, duration: m3Durations.medium2 },
+          },
+        },
+      };
+    case "fade":
+    default:
+      return {
+        initial: { opacity: 0 },
+        animate: { opacity: 1, transition: enterTransition },
+        exit: { opacity: 0, transition: exitTransition },
+      };
+  }
+}
+
+/**
+ * M3Transition — generic Material 3 transition wrapper.
+ * Supports all standard M3 patterns via the `pattern` prop.
+ * The `stateKey` prop drives AnimatePresence re-mounts.
+ */
+export const M3Transition = React.forwardRef<HTMLDivElement, M3TransitionProps>(
+  (
+    {
+      stateKey,
+      pattern = "fade",
+      forward = true,
+      mode = "wait",
+      variants,
+      children,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    const reduced = useM3ReducedMotion();
+    const resolvedVariants = motionVariants(variants ?? buildVariants(pattern, forward), reduced);
+    const baseStyle: MotionStyle =
+      pattern === "collapse" ? { overflow: "hidden" } : { willChange: "opacity, transform" };
+    const resolvedStyle: MotionStyle = { ...baseStyle, ...style };
+
+    return (
+      <AnimatePresence mode={mode}>
+        <motion.div
+          key={stateKey}
+          ref={ref}
+          variants={resolvedVariants}
+          initial={reduced ? false : "initial"}
+          animate="animate"
+          exit="exit"
+          style={resolvedStyle}
+          {...props}
+        >
+          {children}
+        </motion.div>
+      </AnimatePresence>
+    );
+  },
+);
+
+M3Transition.displayName = "M3Transition";

package/src/easings.ts

@@ -0,0 +1,62 @@
+/**
+ * Material Design 3 Easing Presets.
+ * Represented as cubic-bezier array coordinates [x1, y1, x2, y2].
+ *
+ * Source of truth: @aphrody/material-web/tokens/versions/v0_192/_md-sys-motion.scss
+ * and docs/01-md3-spec-foundations.md §7.1
+ *
+ * Note on `emphasized`: the full M3 emphasized path is a 2-segment spline
+ * (not expressible as a single cubic-bezier). The token file maps
+ * easing-emphasized to cubic-bezier(0.2, 0, 0, 1) — identical to standard —
+ * because that is the closest single-bezier approximation used in web
+ * implementations. Use emphasizedDecelerate / emphasizedAccelerate for
+ * enter/exit transitions respectively (recommended practice per spec §7.1).
+ */
+export const m3Easings = {
+  /** Closest single-bezier approximation. Use emphasizedDecelerate/Accelerate for transitions. */
+  emphasized: [0.2, 0.0, 0.0, 1.0],
+  emphasizedDecelerate: [0.05, 0.7, 0.1, 1.0],
+  emphasizedAccelerate: [0.3, 0.0, 0.8, 0.15],
+  standard: [0.2, 0.0, 0.0, 1.0],
+  standardDecelerate: [0.0, 0.0, 0.0, 1.0],
+  standardAccelerate: [0.3, 0.0, 1.0, 1.0],
+  linear: [0.0, 0.0, 1.0, 1.0],
+  /** Legacy (M2 default) — kept for migration compatibility. */
+  legacy: [0.4, 0.0, 0.2, 1.0],
+  legacyDecelerate: [0.0, 0.0, 0.2, 1.0],
+  legacyAccelerate: [0.4, 0.0, 1.0, 1.0],
+} as const;
+
+export type M3EasingKey = keyof typeof m3Easings;
+export type M3EasingValue = (typeof m3Easings)[M3EasingKey];
+
+/**
+ * Material Design 3 Duration Presets (in seconds, compatible with Motion duration option).
+ *
+ * Canonical values from _md-sys-motion.scss:
+ * short1=50ms, short2=100ms, short3=150ms, short4=200ms
+ * medium1=250ms, medium2=300ms, medium3=350ms, medium4=400ms
+ * long1=450ms, long2=500ms, long3=550ms, long4=600ms
+ * extraLong1=700ms, extraLong2=800ms, extraLong3=900ms, extraLong4=1000ms
+ */
+export const m3Durations = {
+  short1: 0.05,
+  short2: 0.1,
+  short3: 0.15,
+  short4: 0.2,
+  medium1: 0.25,
+  medium2: 0.3,
+  medium3: 0.35,
+  medium4: 0.4,
+  long1: 0.45,
+  long2: 0.5,
+  long3: 0.55,
+  long4: 0.6,
+  extraLong1: 0.7,
+  extraLong2: 0.8,
+  extraLong3: 0.9,
+  extraLong4: 1.0,
+} as const;
+
+export type M3DurationKey = keyof typeof m3Durations;
+export type M3DurationValue = (typeof m3Durations)[M3DurationKey];

package/src/hooks/useM3Animate.ts

@@ -0,0 +1,93 @@
+import { useAnimate } from "motion/react";
+import type {
+  AnimationScope,
+  AnimationPlaybackControlsWithThen,
+  AnimationSequence,
+  SequenceOptions,
+  ElementOrSelector,
+  DOMKeyframesDefinition,
+  AnimationOptions,
+  MotionValue,
+  UnresolvedValueKeyframe,
+  ValueAnimationTransition,
+  ObjectTarget,
+} from "motion/react";
+import { m3Easings, m3Durations } from "../easings.js";
+import { useM3ReducedMotion } from "./useM3ReducedMotion.js";
+
+/**
+ * Overloaded type for the scoped animate function returned by useM3Animate.
+ * Mirrors the overload set of the underlying motion animate, adding M3 defaults.
+ */
+export interface M3AnimateFn {
+  (sequence: AnimationSequence, options?: SequenceOptions): AnimationPlaybackControlsWithThen;
+  (
+    value: string | MotionValue<string>,
+    keyframes: string | UnresolvedValueKeyframe<string>[],
+    options?: ValueAnimationTransition<string>,
+  ): AnimationPlaybackControlsWithThen;
+  (
+    value: number | MotionValue<number>,
+    keyframes: number | UnresolvedValueKeyframe<number>[],
+    options?: ValueAnimationTransition<number>,
+  ): AnimationPlaybackControlsWithThen;
+  <V extends string | number>(
+    value: V | MotionValue<V>,
+    keyframes: V | UnresolvedValueKeyframe<V>[],
+    options?: ValueAnimationTransition<V>,
+  ): AnimationPlaybackControlsWithThen;
+  (
+    element: ElementOrSelector,
+    keyframes: DOMKeyframesDefinition,
+    options?: AnimationOptions,
+  ): AnimationPlaybackControlsWithThen;
+  <O extends object>(
+    object: O | O[],
+    keyframes: ObjectTarget<O>,
+    options?: AnimationOptions,
+  ): AnimationPlaybackControlsWithThen;
+}
+
+/**
+ * A custom hook wrapping motion's `useAnimate` that injects Material 3 motion defaults
+ * (emphasized easing and medium2 duration) for all imperative DOM animations.
+ *
+ * SSR-safe: useAnimate creates refs; no DOM access occurs at module or render time.
+ */
+export function useM3Animate<T extends Element = HTMLElement>(): [AnimationScope<T>, M3AnimateFn] {
+  const [scope, animate] = useAnimate<T>();
+  const reduced = useM3ReducedMotion();
+
+  const m3Animate: M3AnimateFn = (
+    elementOrSelector: unknown,
+    keyframes?: unknown,
+    options?: unknown,
+  ) => {
+    const defaults = { ease: m3Easings.emphasized, duration: m3Durations.medium2 };
+    const immediate = reduced ? { type: "tween", duration: 0, delay: 0, repeat: 0 } : {};
+    if (Array.isArray(elementOrSelector) && elementOrSelector.some(Array.isArray)) {
+      // Sequence overload
+      const sequenceOptions =
+        typeof keyframes === "object" && keyframes !== null ? (keyframes as SequenceOptions) : {};
+      const sequence = reduced
+        ? elementOrSelector.map((segment) =>
+            Array.isArray(segment)
+              ? [segment[0], segment[1], { ...segment[2], ...immediate, at: 0 }]
+              : segment,
+          )
+        : elementOrSelector;
+      return (animate as CallableFunction)(sequence, {
+        ...sequenceOptions,
+        defaultTransition: { ...defaults, ...sequenceOptions.defaultTransition, ...immediate },
+      }) as AnimationPlaybackControlsWithThen;
+    }
+
+    return (animate as CallableFunction)(elementOrSelector, keyframes, {
+      ...defaults,
+      ...(typeof options === "object" && options !== null ? options : {}),
+      ...immediate,
+    }) as AnimationPlaybackControlsWithThen;
+  };
+
+  return [scope, m3Animate];
+}

package/src/hooks/useM3ReducedMotion.ts

@@ -0,0 +1,43 @@
+"use client";
+
+// SPDX-License-Identifier: Apache-2.0
+import { useSyncExternalStore } from "react";
+import type { TargetAndTransition, Variants } from "motion/react";
+
+const QUERY = "(prefers-reduced-motion: reduce)";
+
+function subscribe(onChange: () => void): () => void {
+  if (typeof window === "undefined" || !window.matchMedia) return () => {};
+  const media = window.matchMedia(QUERY);
+  media.addEventListener("change", onChange);
+  return () => media.removeEventListener("change", onChange);
+}
+
+/** Tracks the OS preference, including changes made while an application is open. */
+export function useM3ReducedMotion(): boolean {
+  return useSyncExternalStore(
+    subscribe,
+    () => typeof window !== "undefined" && !!window.matchMedia?.(QUERY).matches,
+    () => false,
+  );
+}
+
+function immediate(target: TargetAndTransition): TargetAndTransition;
+function immediate(target: TargetAndTransition | string): TargetAndTransition | string;
+function immediate(target: TargetAndTransition | string): TargetAndTransition | string {
+  if (typeof target === "string") return target;
+  return { ...target, transition: { type: "tween", duration: 0, delay: 0 } };
+}
+
+/** Preserve each state and custom variant while removing animation and stagger delays. */
+export function motionVariants(variants: Variants, reduced: boolean): Variants {
+  if (!reduced) return variants;
+  return Object.fromEntries(
+    Object.entries(variants).map(([key, variant]) => [
+      key,
+      typeof variant === "function"
+        ? (...args: Parameters<typeof variant>) => immediate(variant(...args))
+        : immediate(variant),
+    ]),
+  );
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from "./springs.js";
+export * from "./easings.js";
+export * from "./spring-interpolation.js";
+export * from "./components/M3Fade.js";
+export * from "./components/M3SharedAxis.js";
+export * from "./components/M3FadeThrough.js";
+export * from "./components/M3Collapse.js";
+export * from "./components/M3ContainerTransform.js";
+export * from "./components/M3Transition.js";
+export * from "./components/M3ListStagger.js";
+export * from "./hooks/useM3Animate.js";
+export { useM3ReducedMotion } from "./hooks/useM3ReducedMotion.js";