@aphrody/m3-motion 3.3.2 → 3.3.4

package/src/components/M3ContainerTransform.tsx

@@ -0,0 +1,187 @@
+import * as React from "react";
+import { motion } from "motion/react";
+import type { HTMLMotionProps, Transition, MotionStyle } from "motion/react";
+import { m3Springs } from "../springs.js";
+import { m3Easings } from "../easings.js";
+import { useM3ReducedMotion } from "../hooks/useM3ReducedMotion.js";
+
+export interface M3ContainerTransformProps extends HTMLMotionProps<"div"> {
+  /**
+   * Shared identifier linking the starting container (e.g., card) and ending container (e.g., detail page).
+   */
+  layoutId?: string;
+  /**
+   * Speed preset to use for the morphing animation.
+   * @default "default"
+   */
+  speed?: "fast" | "default" | "slow";
+  /**
+   * If true, renders the expanded container state.
+   * @default false
+   */
+  isExpanded?: boolean;
+}
+
+export interface M3ContainerTransformContextValue {
+  isExpanded: boolean;
+  speed: "fast" | "default" | "slow";
+}
+
+export const M3ContainerTransformContext =
+  React.createContext<M3ContainerTransformContextValue | null>(null);
+
+/**
+ * Helper function to generate spec-compliant cross-fade timings.
+ */
+function getDefaultTransition(isActive: boolean, speed: "fast" | "default" | "slow"): Transition {
+  if (speed === "fast") {
+    return isActive
+      ? { delay: 0.05, duration: 0.15, ease: m3Easings.emphasizedDecelerate }
+      : { duration: 0.08, ease: m3Easings.emphasizedAccelerate };
+  }
+  if (speed === "slow") {
+    return isActive
+      ? { delay: 0.2, duration: 0.6, ease: m3Easings.emphasizedDecelerate }
+      : { duration: 0.25, ease: m3Easings.emphasizedAccelerate };
+  }
+  // Default speed
+  return isActive
+    ? { delay: 0.1, duration: 0.35, ease: m3Easings.emphasizedDecelerate }
+    : { duration: 0.15, ease: m3Easings.emphasizedAccelerate };
+}
+
+/**
+ * M3ContainerTransform component.
+ * Implements the Material 3 Container Transform motion pattern using shared element transitions.
+ * Use the same layoutId on both source and target containers to morph them smoothly.
+ */
+export const M3ContainerTransform = React.forwardRef<HTMLDivElement, M3ContainerTransformProps>(
+  (
+    {
+      layoutId,
+      speed = "default",
+      isExpanded = false,
+      children,
+      transition,
+      style,
+      ...props
+    }: M3ContainerTransformProps,
+    ref,
+  ) => {
+    const reduced = useM3ReducedMotion();
+    // Select the M3 spatial spring configuration based on speed
+    const springConfig = m3Springs[speed].spatial;
+
+    const contextValue = React.useMemo(() => ({ isExpanded, speed }), [isExpanded, speed]);
+
+    return (
+      <M3ContainerTransformContext.Provider value={contextValue}>
+        <motion.div
+          ref={ref}
+          layoutId={reduced ? undefined : layoutId}
+          layout={!reduced}
+          transition={
+            reduced ? { type: "tween", duration: 0, delay: 0 } : transition || springConfig
+          }
+          style={{
+            position: "relative",
+            willChange: "transform, border-radius",
+            overflow: "hidden",
+            ...style,
+          }}
+          {...props}
+        >
+          {children}
+        </motion.div>
+      </M3ContainerTransformContext.Provider>
+    );
+  },
+);
+
+M3ContainerTransform.displayName = "M3ContainerTransform";
+
+export interface M3ContainerTransformStartProps extends HTMLMotionProps<"div"> {
+  /**
+   * Overrides the active state. By default, active when isExpanded is false.
+   */
+  active?: boolean;
+}
+
+export interface M3ContainerTransformEndProps extends HTMLMotionProps<"div"> {
+  /**
+   * Overrides the active state. By default, active when isExpanded is true.
+   */
+  active?: boolean;
+}
+
+/**
+ * One cross-fading layer of the container transform. `start` is shown while collapsed, `end` while
+ * expanded; the inactive layer is taken out of the flow and stops receiving pointer events, so the
+ * content never distorts during the morph.
+ */
+const ContainerTransformLayer = React.forwardRef<
+  HTMLDivElement,
+  M3ContainerTransformStartProps & { layer: "start" | "end" }
+>(({ layer, active, children, style, transition, layout = "position", ...props }, ref) => {
+  const reduced = useM3ReducedMotion();
+  const context = React.useContext(M3ContainerTransformContext);
+  const isActive = active ?? (context ? context.isExpanded === (layer === "end") : true);
+  const speed = context?.speed ?? "default";
+
+  const baseStyle: MotionStyle = {
+    width: "100%",
+    height: "100%",
+    boxSizing: "border-box",
+    pointerEvents: isActive ? "auto" : "none",
+    ...(!isActive && {
+      position: "absolute",
+      top: 0,
+      left: 0,
+    }),
+    ...style,
+  };
+
+  return (
+    <motion.div
+      ref={ref}
+      layout={reduced ? false : layout}
+      {...(layer === "end" ? { initial: reduced ? false : { opacity: 0 } } : {})}
+      animate={{ opacity: isActive ? 1 : 0 }}
+      transition={
+        reduced
+          ? { type: "tween", duration: 0, delay: 0 }
+          : transition || getDefaultTransition(isActive, speed)
+      }
+      style={baseStyle}
+      {...props}
+      inert={!isActive || props.inert}
+      aria-hidden={!isActive || props["aria-hidden"]}
+    >
+      {children}
+    </motion.div>
+  );
+});
+
+/**
+ * M3ContainerTransformStart component.
+ * Represents the starting content (e.g., Card content) inside M3ContainerTransform.
+ * Prevents aspect ratio distortion and fades out during the container transform morph.
+ */
+export const M3ContainerTransformStart = React.forwardRef<
+  HTMLDivElement,
+  M3ContainerTransformStartProps
+>((props, ref) => <ContainerTransformLayer layer="start" ref={ref} {...props} />);
+
+M3ContainerTransformStart.displayName = "M3ContainerTransformStart";
+
+/**
+ * M3ContainerTransformEnd component.
+ * Represents the target content (e.g., Detail page content) inside M3ContainerTransform.
+ * Prevents aspect ratio distortion and fades in during the container transform morph.
+ */
+export const M3ContainerTransformEnd = React.forwardRef<
+  HTMLDivElement,
+  M3ContainerTransformEndProps
+>((props, ref) => <ContainerTransformLayer layer="end" ref={ref} {...props} />);
+
+M3ContainerTransformEnd.displayName = "M3ContainerTransformEnd";

package/src/components/M3Fade.tsx

@@ -0,0 +1,68 @@
+import * as React from "react";
+import { motion, AnimatePresence } from "motion/react";
+import type { HTMLMotionProps } from "motion/react";
+import { m3Easings, m3Durations } from "../easings.js";
+import { motionVariants, useM3ReducedMotion } from "../hooks/useM3ReducedMotion.js";
+
+export interface M3FadeProps extends HTMLMotionProps<"div"> {
+  /**
+   * If true, the component will transition in. If false, it will transition out.
+   * If omitted, the component behaves as a standard motion element meant to be unmounted/mounted
+   * by an external <AnimatePresence>.
+   */
+  in?: boolean;
+  /**
+   * If true, animate the transition on initial mount.
+   * @default true
+   */
+  appear?: boolean;
+}
+
+/**
+ * M3Fade transition component.
+ * Fades elements in/out using Material 3 standard decelerate/accelerate curves.
+ */
+export const M3Fade = React.forwardRef<HTMLDivElement, M3FadeProps>(
+  ({ in: inProp, appear = true, children, variants: customVariants, ...props }, ref) => {
+    const reduced = useM3ReducedMotion();
+    const variants = {
+      initial: { opacity: 0 },
+      animate: {
+        opacity: 1,
+        transition: {
+          ease: m3Easings.emphasizedDecelerate,
+          duration: m3Durations.medium2,
+        },
+      },
+      exit: {
+        opacity: 0,
+        transition: {
+          ease: m3Easings.emphasizedAccelerate,
+          duration: m3Durations.short4,
+        },
+      },
+    };
+
+    const content = (
+      <motion.div
+        ref={ref}
+        variants={motionVariants(customVariants ?? variants, reduced)}
+        initial={appear && !reduced ? "initial" : false}
+        animate="animate"
+        exit="exit"
+        style={{ willChange: "opacity" }}
+        {...props}
+      >
+        {children}
+      </motion.div>
+    );
+
+    if (inProp !== undefined) {
+      return <AnimatePresence>{inProp ? content : null}</AnimatePresence>;
+    }
+
+    return content;
+  },
+);
+
+M3Fade.displayName = "M3Fade";

package/src/components/M3FadeThrough.tsx

@@ -0,0 +1,80 @@
+import * as React from "react";
+import { motion, AnimatePresence } from "motion/react";
+import type { HTMLMotionProps, Transition, Variants } from "motion/react";
+import { m3Easings } from "../easings.js";
+import { motionVariants, useM3ReducedMotion } from "../hooks/useM3ReducedMotion.js";
+
+export interface M3FadeThroughProps extends HTMLMotionProps<"div"> {
+  /**
+   * Unique key representing the active view/content. Changing this key triggers the transition.
+   */
+  stateKey: React.Key;
+  /**
+   * Custom transition for the fade through animation.
+   */
+  transition?: Transition;
+}
+
+/**
+ * M3FadeThrough transition component.
+ * Implements the Material 3 Fade Through navigation pattern.
+ * The outgoing element fades out over 90ms, followed by the incoming element fading in and scaling up over 210ms.
+ */
+export const M3FadeThrough: React.FC<M3FadeThroughProps> = ({
+  stateKey,
+  transition: customTransition,
+  variants: customVariants,
+  children,
+  ...props
+}) => {
+  const reduced = useM3ReducedMotion();
+  const defaultVariants: Variants = {
+    initial: {
+      opacity: 0,
+      scale: 0.92,
+    },
+    animate: {
+      opacity: 1,
+      scale: 1,
+      transition: customTransition || {
+        opacity: {
+          ease: m3Easings.emphasizedDecelerate,
+          duration: 0.21,
+        },
+        scale: {
+          ease: m3Easings.emphasizedDecelerate,
+          duration: 0.21,
+        },
+      },
+    },
+    exit: {
+      opacity: 0,
+      transition: customTransition || {
+        opacity: {
+          ease: m3Easings.emphasizedAccelerate,
+          duration: 0.09,
+        },
+      },
+    },
+  };
+
+  const resolvedVariants = motionVariants(customVariants ?? defaultVariants, reduced);
+
+  return (
+    <AnimatePresence mode="wait">
+      <motion.div
+        key={stateKey}
+        variants={resolvedVariants}
+        initial={reduced ? false : "initial"}
+        animate="animate"
+        exit="exit"
+        style={{ willChange: "opacity, transform" }}
+        {...props}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  );
+};
+
+M3FadeThrough.displayName = "M3FadeThrough";

package/src/components/M3ListStagger.tsx

@@ -0,0 +1,117 @@
+"use client";
+import * as React from "react";
+import { AnimatePresence, motion, useIsPresent } from "motion/react";
+import type { HTMLMotionProps, Variants } from "motion/react";
+import { m3Easings, m3Durations } from "../easings.js";
+import { motionVariants, useM3ReducedMotion } from "../hooks/useM3ReducedMotion.js";
+
+export interface M3ListStaggerProps {
+  /**
+   * Delay between each child item entering the scene (seconds).
+   * @default 0.05
+   */
+  staggerDelay?: number;
+  /**
+   * Delay before the stagger sequence starts (seconds).
+   * @default 0
+   */
+  delayChildren?: number;
+  /**
+   * If true, items animate on initial render.
+   * @default true
+   */
+  appear?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+  children?: React.ReactNode;
+}
+
+export interface M3ListStaggerItemProps extends HTMLMotionProps<"div"> {
+  children?: React.ReactNode;
+}
+
+const containerVariants: Variants = {
+  hidden: {},
+  visible: (_custom: { staggerDelay: number; delayChildren: number }) => ({
+    transition: {
+      staggerChildren: _custom.staggerDelay,
+      delayChildren: _custom.delayChildren,
+    },
+  }),
+  exit: {},
+};
+
+const itemVariants: Variants = {
+  hidden: { opacity: 0, y: 8 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    transition: {
+      ease: m3Easings.emphasizedDecelerate,
+      duration: m3Durations.medium2,
+    },
+  },
+  exit: {
+    opacity: 0,
+    y: 4,
+    transition: {
+      ease: m3Easings.emphasizedAccelerate,
+      duration: m3Durations.short3,
+    },
+  },
+};
+
+/**
+ * M3ListStagger — stagger container for list-item enter/exit animations.
+ *
+ * Usage:
+ *   <M3ListStagger>
+ *     {items.map(item => <M3ListStaggerItem key={item.id}>{item.label}</M3ListStaggerItem>)}
+ *   </M3ListStagger>
+ */
+export const M3ListStagger = React.forwardRef<HTMLDivElement, M3ListStaggerProps>(
+  ({ staggerDelay = 0.05, delayChildren = 0, appear = true, children, className, style }, ref) => {
+    const reduced = useM3ReducedMotion();
+    return (
+      <motion.div
+        ref={ref}
+        className={className}
+        style={style}
+        variants={motionVariants(containerVariants, reduced)}
+        initial={appear && !reduced ? "hidden" : false}
+        animate="visible"
+        exit="exit"
+        custom={{ staggerDelay, delayChildren }}
+      >
+        <AnimatePresence initial={appear && !reduced}>{children}</AnimatePresence>
+      </motion.div>
+    );
+  },
+);
+
+M3ListStagger.displayName = "M3ListStagger";
+
+/**
+ * M3ListStaggerItem — a single animated item inside M3ListStagger.
+ * Must be a direct or indirect descendant of M3ListStagger to inherit variants.
+ */
+export const M3ListStaggerItem = React.forwardRef<HTMLDivElement, M3ListStaggerItemProps>(
+  ({ children, style, ...props }, ref) => {
+    const present = useIsPresent();
+    const reduced = useM3ReducedMotion();
+    return (
+      <motion.div
+        ref={ref}
+        variants={motionVariants(itemVariants, reduced)}
+        style={{ willChange: "opacity, transform", ...style }}
+        {...props}
+        inert={!present || props.inert}
+        aria-hidden={!present || props["aria-hidden"]}
+      >
+        {children}
+      </motion.div>
+    );
+  },
+);
+
+M3ListStaggerItem.displayName = "M3ListStaggerItem";

package/src/components/M3SharedAxis.tsx

@@ -0,0 +1,115 @@
+import * as React from "react";
+import { motion, AnimatePresence } from "motion/react";
+import type { HTMLMotionProps, Transition, Variants } from "motion/react";
+import { m3Easings, m3Durations } from "../easings.js";
+import { motionVariants, useM3ReducedMotion } from "../hooks/useM3ReducedMotion.js";
+
+export interface M3SharedAxisProps extends HTMLMotionProps<"div"> {
+  /**
+   * If true, the component will transition in. If false, it will transition out.
+   * If omitted, the component behaves as a standard motion element meant to be unmounted/mounted
+   * by an external <AnimatePresence>.
+   */
+  in?: boolean;
+  /**
+   * Axis of translation.
+   * @default "x"
+   */
+  axis?: "x" | "y" | "z";
+  /**
+   * Direction of navigation. If true, slides forward/up/zoom-in. If false, slides backward/down/zoom-out.
+   * @default true
+   */
+  forward?: boolean;
+  /**
+   * If true, animate the transition on initial mount.
+   * @default true
+   */
+  appear?: boolean;
+  /**
+   * Custom transition for the shared axis animation.
+   */
+  transition?: Transition;
+}
+
+/**
+ * M3SharedAxis transition component.
+ * Implements the Material 3 Shared Axis motion pattern (X, Y, Z axes).
+ */
+export const M3SharedAxis = React.forwardRef<HTMLDivElement, M3SharedAxisProps>(
+  (
+    {
+      in: inProp,
+      axis = "x",
+      forward = true,
+      appear = true,
+      transition: customTransition,
+      variants: customVariants,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const reduced = useM3ReducedMotion();
+    // Offset values according to M3 specifications (usually 30px translation or ~8% scale change)
+    const translateOffset = 30;
+    const scaleOffset = 0.08;
+
+    const defaultVariants: Variants = {
+      initial: {
+        opacity: 0,
+        x: axis === "x" ? (forward ? translateOffset : -translateOffset) : 0,
+        y: axis === "y" ? (forward ? translateOffset : -translateOffset) : 0,
+        scale: axis === "z" ? (forward ? 1 - scaleOffset : 1 + scaleOffset) : 1,
+      },
+      animate: {
+        opacity: 1,
+        x: 0,
+        y: 0,
+        scale: 1,
+        transition: customTransition || {
+          x: { ease: m3Easings.emphasizedDecelerate, duration: m3Durations.medium2 },
+          y: { ease: m3Easings.emphasizedDecelerate, duration: m3Durations.medium2 },
+          scale: { ease: m3Easings.emphasizedDecelerate, duration: m3Durations.medium2 },
+          opacity: { ease: m3Easings.standard, duration: m3Durations.medium2 },
+        },
+      },
+      exit: {
+        opacity: 0,
+        x: axis === "x" ? (forward ? -translateOffset : translateOffset) : 0,
+        y: axis === "y" ? (forward ? -translateOffset : translateOffset) : 0,
+        scale: axis === "z" ? (forward ? 1 + scaleOffset : 1 - scaleOffset) : 1,
+        transition: customTransition || {
+          x: { ease: m3Easings.emphasizedAccelerate, duration: m3Durations.short4 },
+          y: { ease: m3Easings.emphasizedAccelerate, duration: m3Durations.short4 },
+          scale: { ease: m3Easings.emphasizedAccelerate, duration: m3Durations.short4 },
+          opacity: { ease: m3Easings.standard, duration: m3Durations.short4 },
+        },
+      },
+    };
+
+    const resolvedVariants = motionVariants(customVariants ?? defaultVariants, reduced);
+
+    const content = (
+      <motion.div
+        ref={ref}
+        variants={resolvedVariants}
+        initial={appear && !reduced ? "initial" : false}
+        animate="animate"
+        exit="exit"
+        style={{ willChange: "opacity, transform" }}
+        {...props}
+      >
+        {children}
+      </motion.div>
+    );
+
+    if (inProp !== undefined) {
+      return <AnimatePresence mode="wait">{inProp ? content : null}</AnimatePresence>;
+    }
+
+    return content;
+  },
+);
+
+M3SharedAxis.displayName = "M3SharedAxis";