@aphrody/m3-motion 3.2.1

package/README.md

@@ -0,0 +1,243 @@
+# @aphrody/m3-motion
+
+High-fidelity React animation components for Material Design 3 (M3) motion specifications, powered by [Motion](https://motion.dev/) (formerly Framer Motion).
+
+This package implements the core Material Design 3 motion patterns—including **Container Transform**, **Shared Axis**, **Fade Through**, **Collapse**, and **Fade**—using Google's official spring, easing, and duration tokens.
+
+---
+
+## Installation
+
+```bash
+bun add @aphrody/m3-motion motion
+```
+
+Ensure you have `react` (>= 18.0.0) and `motion` (>= 12.0.0) installed in your project.
+
+---
+
+## 1. Container Transform (`M3ContainerTransform`)
+
+The container transform pattern transitions one UI element to another (e.g., morphing a small Card component into a full-page Detail view). 
+
+### Key Features
+* **Aspect Ratio Preservation**: Automatically prevents layout distortion (skewing/stretching) of children during container morphs using layout-position correction.
+* **Spec-Compliant Cross-Fade**: Fades out the starting content early (0% to 30% of transition) and delays the fade-in of target content (20% to 100% of transition) to avoid messy intermediate states.
+* **Pointer Event Management**: Prevents inactive, hidden content from intercepting pointer interactions.
+* **Flexibility**: Supports both the **Single-Container Toggle** approach (re-rendering within the same container) and the **Two-Container Shared Layout** approach (different source/target elements linked via `layoutId`).
+
+### Sub-Components
+* `M3ContainerTransform`: Parent morphing container.
+* `M3ContainerTransformStart`: Wrapper for starting content (e.g., collapsed card details).
+* `M3ContainerTransformEnd`: Wrapper for ending content (e.g., expanded page details).
+
+---
+
+### Code Examples
+
+#### Single-Container Toggle Approach
+Best when morphing a single component instance in place using state.
+
+```tsx
+import React, { useState } from "react";
+import { 
+  M3ContainerTransform, 
+  M3ContainerTransformStart, 
+  M3ContainerTransformEnd 
+} from "@aphrody/m3-motion";
+
+export const MorphingCard = () => {
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  return (
+    <M3ContainerTransform
+      isExpanded={isExpanded}
+      speed="default"
+      style={{
+        width: isExpanded ? 500 : 250,
+        height: isExpanded ? 400 : 150,
+        borderRadius: isExpanded ? 28 : 16,
+        backgroundColor: "var(--md-sys-color-surface-container)",
+        cursor: "pointer"
+      }}
+      onClick={() => setIsExpanded(!isExpanded)}
+    >
+      {/* Start state (collapsed content) */}
+      <M3ContainerTransformStart>
+        <div style={{ padding: 16 }}>
+          <h3>Collapsed Card</h3>
+          <p>Click me to expand...</p>
+        </div>
+      </M3ContainerTransformStart>
+
+      {/* End state (expanded detail content) */}
+      <M3ContainerTransformEnd>
+        <div style={{ padding: 24 }}>
+          <h2>Detailed View</h2>
+          <p>This is the expanded content showing the full detail surface.</p>
+          <button onClick={(e) => { e.stopPropagation(); setIsExpanded(false); }}>
+            Close
+          </button>
+        </div>
+      </M3ContainerTransformEnd>
+    </M3ContainerTransform>
+  );
+};
+```
+
+#### Two-Container Shared Layout Approach (linked via `layoutId`)
+Best for page/route transitions or separate DOM elements. Wrap the conditional render in `<AnimatePresence>` to enable the exit fade-out transition.
+
+```tsx
+import React, { useState } from "react";
+import { AnimatePresence } from "motion/react";
+import { 
+  M3ContainerTransform, 
+  M3ContainerTransformStart, 
+  M3ContainerTransformEnd 
+} from "@aphrody/m3-motion";
+
+export const ListView = () => {
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  return (
+    <div>
+      {/* List of items */}
+      {!selectedId && (
+        <div className="grid">
+          <M3ContainerTransform 
+            layoutId="card-item-1" 
+            onClick={() => setSelectedId("1")}
+            style={{ borderRadius: 16, background: "#eee", width: 200, height: 120 }}
+          >
+            <M3ContainerTransformStart>
+              <div style={{ padding: 12 }}>Card Content 1</div>
+            </M3ContainerTransformStart>
+          </M3ContainerTransform>
+        </div>
+      )}
+
+      {/* Expanded detail page */}
+      <AnimatePresence>
+        {selectedId === "1" && (
+          <div className="backdrop">
+            <M3ContainerTransform 
+              layoutId="card-item-1" 
+              style={{ borderRadius: 24, background: "#fff", width: 600, height: 450 }}
+            >
+              <M3ContainerTransformEnd>
+                <div style={{ padding: 24 }}>
+                  <h2>Expanded Title 1</h2>
+                  <p>Long detail text...</p>
+                  <button onClick={() => setSelectedId(null)}>Back to List</button>
+                </div>
+              </M3ContainerTransformEnd>
+            </M3ContainerTransform>
+          </div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+};
+```
+
+---
+
+## 2. Shared Axis (`M3SharedAxis`)
+
+Used for transitions between UI elements that have a spatial or navigational relationship (e.g., page stepper, tab switching, or dialog overlays). Supports `x`, `y`, and `z` axes.
+
+* Default enter duration: **300ms** (`medium2`) with `emphasizedDecelerate` ease.
+* Default exit duration: **200ms** (`short4`) with `emphasizedAccelerate` ease.
+
+### Code Example
+
+```tsx
+import React, { useState } from "react";
+import { M3SharedAxis } from "@aphrody/m3-motion";
+
+export const StepWizard = () => {
+  const [step, setStep] = useState(0);
+
+  return (
+    <div>
+      <M3SharedAxis 
+        stateKey={step} 
+        axis="x" 
+        forward={step > 0} 
+        style={{ padding: 20 }}
+      >
+        {step === 0 && <div>Step 1: Enter details</div>}
+        {step === 1 && <div>Step 2: Review options</div>}
+        {step === 2 && <div>Step 3: Confirm purchase</div>}
+      </M3SharedAxis>
+      
+      <button onClick={() => setStep(prev => Math.max(0, prev - 1))}>Back</button>
+      <button onClick={() => setStep(prev => Math.min(2, prev + 1))}>Next</button>
+    </div>
+  );
+};
+```
+
+---
+
+## 3. Fade Through (`M3FadeThrough`)
+
+Used for transitions between primary views that do not have a strong spatial relationship (e.g., bottom navigation switching, settings screens).
+
+* Default exit duration (fade-out): **90ms** with `emphasizedAccelerate` ease.
+* Default enter duration (fade-in & scale-up from 92%): **210ms** with `emphasizedDecelerate` ease.
+
+### Code Example
+
+```tsx
+import React, { useState } from "react";
+import { M3FadeThrough } from "@aphrody/m3-motion";
+
+export const AppNavigation = () => {
+  const [currentTab, setCurrentTab] = useState("home");
+
+  return (
+    <div>
+      <M3FadeThrough stateKey={currentTab} style={{ height: 400 }}>
+        {currentTab === "home" && <div>Home View Content</div>}
+        {currentTab === "search" && <div>Search Page Content</div>}
+        {currentTab === "profile" && <div>User Profile Settings</div>}
+      </M3FadeThrough>
+
+      <nav>
+        <button onClick={() => setCurrentTab("home")}>Home</button>
+        <button onClick={() => setCurrentTab("search")}>Search</button>
+        <button onClick={() => setCurrentTab("profile")}>Profile</button>
+      </nav>
+    </div>
+  );
+};
+```
+
+---
+
+## 4. Duration and Easing Presets
+
+Developers have direct access to official Material Design 3 timings and curves:
+
+```tsx
+import { m3Easings, m3Durations, m3Springs } from "@aphrody/m3-motion";
+
+// Custom animation example using M3 tokens
+const myCustomTransition = {
+  ease: m3Easings.emphasizedDecelerate,
+  duration: m3Durations.medium4, // 400ms
+};
+```
+
+### Motion Presets Summary
+* **`m3Easings`**: Bezier curves for `emphasized` (approx), `emphasizedDecelerate` (enter), `emphasizedAccelerate` (exit), `standard`, `standardDecelerate`, and `standardAccelerate`.
+* **`m3Durations`**: Timing scales from `short1` (50ms) to `extraLong4` (1000ms).
+* **`m3Springs`**: Hand-tuned spring constants (`fast`, `default`, `slow`) split into `spatial` (bouncy) and `effects` (critically damped).
+
+---
+
+## License
+
+Apache-2.0

package/dist/components/M3Collapse.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+import type { HTMLMotionProps } from "motion/react";
+export interface M3CollapseProps extends HTMLMotionProps<"div"> {
+    /**
+     * If true, the component expands. If false, it collapses.
+     * 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 false
+     */
+    appear?: boolean;
+}
+/**
+ * M3Collapse transition component.
+ * Animates the height and opacity of its children, perfect for accordions, menus, or disclosures.
+ */
+export declare const M3Collapse: React.ForwardRefExoticComponent<Omit<M3CollapseProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=M3Collapse.d.ts.map

package/dist/components/M3Collapse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"M3Collapse.d.ts","sourceRoot":"","sources":["../../src/components/M3Collapse.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,MAAM,WAAW,eAAgB,SAAQ,eAAe,CAAC,KAAK,CAAC;IAC7D;;;;OAIG;IACH,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,qGAsDtB,CAAC"}

package/dist/components/M3ContainerTransform.d.ts

@@ -0,0 +1,54 @@
+import * as React from "react";
+import type { HTMLMotionProps } from "motion/react";
+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 declare const M3ContainerTransformContext: React.Context<M3ContainerTransformContextValue | null>;
+/**
+ * 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 declare const M3ContainerTransform: React.ForwardRefExoticComponent<Omit<M3ContainerTransformProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export interface M3ContainerTransformStartProps extends HTMLMotionProps<"div"> {
+    /**
+     * Overrides the active state. By default, active when isExpanded is false.
+     */
+    active?: boolean;
+}
+/**
+ * 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 declare const M3ContainerTransformStart: React.ForwardRefExoticComponent<Omit<M3ContainerTransformStartProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export interface M3ContainerTransformEndProps extends HTMLMotionProps<"div"> {
+    /**
+     * Overrides the active state. By default, active when isExpanded is true.
+     */
+    active?: boolean;
+}
+/**
+ * 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 declare const M3ContainerTransformEnd: React.ForwardRefExoticComponent<Omit<M3ContainerTransformEndProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=M3ContainerTransform.d.ts.map

package/dist/components/M3ContainerTransform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"M3ContainerTransform.d.ts","sourceRoot":"","sources":["../../src/components/M3ContainerTransform.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAA2B,MAAM,cAAc,CAAC;AAI7E,MAAM,WAAW,yBAA0B,SAAQ,eAAe,CAAC,KAAK,CAAC;IACvE;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gCAAgC;IAC/C,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;CACpC;AAED,eAAO,MAAM,2BAA2B,wDAAqE,CAAC;AAsB9G;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,+GA6BhC,CAAC;AAIF,MAAM,WAAW,8BAA+B,SAAQ,eAAe,CAAC,KAAK,CAAC;IAC5E;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,oHAkCrC,CAAC;AAIF,MAAM,WAAW,4BAA6B,SAAQ,eAAe,CAAC,KAAK,CAAC;IAC1E;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,kHAmCnC,CAAC"}

package/dist/components/M3Fade.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+import type { HTMLMotionProps } from "motion/react";
+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 declare const M3Fade: React.ForwardRefExoticComponent<Omit<M3FadeProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=M3Fade.d.ts.map

package/dist/components/M3Fade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"M3Fade.d.ts","sourceRoot":"","sources":["../../src/components/M3Fade.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,MAAM,WAAW,WAAY,SAAQ,eAAe,CAAC,KAAK,CAAC;IACzD;;;;OAIG;IACH,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,MAAM,iGAwClB,CAAC"}

package/dist/components/M3FadeThrough.d.ts

@@ -0,0 +1,19 @@
+import * as React from "react";
+import type { HTMLMotionProps, Transition } from "motion/react";
+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 declare const M3FadeThrough: React.FC<M3FadeThroughProps>;
+//# sourceMappingURL=M3FadeThrough.d.ts.map

package/dist/components/M3FadeThrough.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"M3FadeThrough.d.ts","sourceRoot":"","sources":["../../src/components/M3FadeThrough.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAY,MAAM,cAAc,CAAC;AAG1E,MAAM,WAAW,kBAAmB,SAAQ,eAAe,CAAC,KAAK,CAAC;IAChE;;OAEG;IACH,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC;IACpB;;OAEG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAgDtD,CAAC"}

package/dist/components/M3ListStagger.d.ts

@@ -0,0 +1,40 @@
+import * as React from "react";
+import type { HTMLMotionProps } from "motion/react";
+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;
+}
+/**
+ * M3ListStagger — stagger container for list-item enter/exit animations.
+ *
+ * Usage:
+ *   <M3ListStagger>
+ *     {items.map(item => <M3ListStaggerItem key={item.id}>{item.label}</M3ListStaggerItem>)}
+ *   </M3ListStagger>
+ */
+export declare const M3ListStagger: React.ForwardRefExoticComponent<M3ListStaggerProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * M3ListStaggerItem — a single animated item inside M3ListStagger.
+ * Must be a direct or indirect descendant of M3ListStagger to inherit variants.
+ */
+export declare const M3ListStaggerItem: React.ForwardRefExoticComponent<Omit<M3ListStaggerItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=M3ListStagger.d.ts.map

package/dist/components/M3ListStagger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"M3ListStagger.d.ts","sourceRoot":"","sources":["../../src/components/M3ListStagger.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAAY,MAAM,cAAc,CAAC;AAG9D,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAuB,SAAQ,eAAe,CAAC,KAAK,CAAC;IACpE,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAiCD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,2FAmBzB,CAAC;AAIF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,4GAa7B,CAAC"}

package/dist/components/M3SharedAxis.d.ts

@@ -0,0 +1,35 @@
+import * as React from "react";
+import type { HTMLMotionProps, Transition } from "motion/react";
+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 declare const M3SharedAxis: React.ForwardRefExoticComponent<Omit<M3SharedAxisProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=M3SharedAxis.d.ts.map

package/dist/components/M3SharedAxis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"M3SharedAxis.d.ts","sourceRoot":"","sources":["../../src/components/M3SharedAxis.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAY,MAAM,cAAc,CAAC;AAG1E,MAAM,WAAW,iBAAkB,SAAQ,eAAe,CAAC,KAAK,CAAC;IAC/D;;;;OAIG;IACH,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,uGA6DxB,CAAC"}

package/dist/components/M3Transition.d.ts

@@ -0,0 +1,36 @@
+import * as React from "react";
+import type { HTMLMotionProps, MotionStyle, Variants } from "motion/react";
+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";
+}
+/**
+ * M3Transition — generic Material 3 transition wrapper.
+ * Supports all standard M3 patterns via the `pattern` prop.
+ * The `stateKey` prop drives AnimatePresence re-mounts.
+ */
+export declare const M3Transition: React.ForwardRefExoticComponent<Omit<M3TransitionProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=M3Transition.d.ts.map

package/dist/components/M3Transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"M3Transition.d.ts","sourceRoot":"","sources":["../../src/components/M3Transition.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAc,QAAQ,EAAE,MAAM,cAAc,CAAC;AAGvF,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,cAAc,GACd,eAAe,GACf,eAAe,GACf,eAAe,GACf,UAAU,CAAC;AAEf,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC3F,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;OAEG;IACH,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;CACtC;AA0HD;;;;GAIG;AACH,eAAO,MAAM,YAAY,uGAoCxB,CAAC"}

package/dist/easings.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Material Design 3 Easing Presets.
+ * Represented as cubic-bezier array coordinates [x1, y1, x2, y2].
+ *
+ * Source of truth: packages/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 declare const m3Easings: {
+    /** Closest single-bezier approximation. Use emphasizedDecelerate/Accelerate for transitions. */
+    readonly emphasized: readonly [0.2, 0, 0, 1];
+    readonly emphasizedDecelerate: readonly [0.05, 0.7, 0.1, 1];
+    readonly emphasizedAccelerate: readonly [0.3, 0, 0.8, 0.15];
+    readonly standard: readonly [0.2, 0, 0, 1];
+    readonly standardDecelerate: readonly [0, 0, 0, 1];
+    readonly standardAccelerate: readonly [0.3, 0, 1, 1];
+    readonly linear: readonly [0, 0, 1, 1];
+    /** Legacy (M2 default) — kept for migration compatibility. */
+    readonly legacy: readonly [0.4, 0, 0.2, 1];
+    readonly legacyDecelerate: readonly [0, 0, 0.2, 1];
+    readonly legacyAccelerate: readonly [0.4, 0, 1, 1];
+};
+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 declare const m3Durations: {
+    readonly short1: 0.05;
+    readonly short2: 0.1;
+    readonly short3: 0.15;
+    readonly short4: 0.2;
+    readonly medium1: 0.25;
+    readonly medium2: 0.3;
+    readonly medium3: 0.35;
+    readonly medium4: 0.4;
+    readonly long1: 0.45;
+    readonly long2: 0.5;
+    readonly long3: 0.55;
+    readonly long4: 0.6;
+    readonly extraLong1: 0.7;
+    readonly extraLong2: 0.8;
+    readonly extraLong3: 0.9;
+    readonly extraLong4: 1;
+};
+export type M3DurationKey = keyof typeof m3Durations;
+export type M3DurationValue = (typeof m3Durations)[M3DurationKey];
+//# sourceMappingURL=easings.d.ts.map

package/dist/easings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"easings.d.ts","sourceRoot":"","sources":["../src/easings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS;IACpB,gGAAgG;;;;;;;;IAQhG,8DAA8D;;;;CAItD,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,SAAS,CAAC;AACjD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,WAAW,CAAC,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;CAiBd,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,WAAW,CAAC;AACrD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,aAAa,CAAC,CAAC"}

package/dist/hooks/useM3Animate.d.ts

@@ -0,0 +1,21 @@
+import type { AnimationScope, AnimationPlaybackControlsWithThen, AnimationSequence, SequenceOptions, ElementOrSelector, DOMKeyframesDefinition, AnimationOptions, MotionValue, UnresolvedValueKeyframe, ValueAnimationTransition, ObjectTarget } from "motion/react";
+/**
+ * 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 declare function useM3Animate<T extends Element = HTMLElement>(): [AnimationScope<T>, M3AnimateFn];
+//# sourceMappingURL=useM3Animate.d.ts.map

package/dist/hooks/useM3Animate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useM3Animate.d.ts","sourceRoot":"","sources":["../../src/hooks/useM3Animate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,iCAAiC,EACjC,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,uBAAuB,EACvB,wBAAwB,EACxB,YAAY,EACb,MAAM,cAAc,CAAC;AAGtB;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,iCAAiC,CAAC;IAC5F,CACE,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,EACnC,SAAS,EAAE,MAAM,GAAG,uBAAuB,CAAC,MAAM,CAAC,EAAE,EACrD,OAAO,CAAC,EAAE,wBAAwB,CAAC,MAAM,CAAC,GACzC,iCAAiC,CAAC;IACrC,CACE,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,EACnC,SAAS,EAAE,MAAM,GAAG,uBAAuB,CAAC,MAAM,CAAC,EAAE,EACrD,OAAO,CAAC,EAAE,wBAAwB,CAAC,MAAM,CAAC,GACzC,iCAAiC,CAAC;IACrC,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EACxB,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,EACzB,SAAS,EAAE,CAAC,GAAG,uBAAuB,CAAC,CAAC,CAAC,EAAE,EAC3C,OAAO,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACpC,iCAAiC,CAAC;IACrC,CACE,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,sBAAsB,EACjC,OAAO,CAAC,EAAE,gBAAgB,GACzB,iCAAiC,CAAC;IACrC,CAAC,CAAC,SAAS,MAAM,EACf,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,EACf,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,iCAAiC,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CA0ChG"}

package/dist/index.d.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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sCAAsC,CAAC;AACrD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC"}