framer-motion 12.41.0 → 12.42.0

package/dist/framer-motion.dev.js

@@ -5715,6 +5715,29 @@
         element.style?.setProperty("view-transition-class", className);
         classed.push(element);
     }
+    /**
+     * Set the element's `view-transition-group` so its layer reconstructs the DOM
+     * hierarchy in the pseudo-tree (`contain`) - or stays flat (`none`). Tracked in
+     * `grouped` for cleanup. When the element clips (any non-`visible` overflow) its
+     * name is recorded in `clipChildren` so the caller can clip the nested children
+     * (`::view-transition-group-children(name)`), mirroring the live clip through
+     * the whole transition rather than only at the live-DOM handoff.
+     *
+     * Ignored by browsers without nested view-transition groups, where it harmlessly
+     * degrades to the flat default.
+     */
+    function applyGroup(element, name, group, grouped, clipChildren) {
+        if (!group)
+            return;
+        element.style?.setProperty("view-transition-group", group);
+        grouped.push(element);
+        if (group !== "none" && clipChildren) {
+            const style = getComputedStyle(element);
+            if (style.overflowX !== "visible" || style.overflowY !== "visible") {
+                clipChildren.add(name);
+            }
+        }
+    }
     /**
      * Resolve a selector/Element to elements and ensure each one carries a
      * `view-transition-name` we can target from script.
@@ -5728,7 +5751,7 @@
      * across both captures (before and after the update), which is what allows a
      * persistent element to animate as a single `group` layer.
      */
-    function assignViewTransitionNames(definition, registry, assigned, forcedNames, className, classed = []) {
+    function assignViewTransitionNames(definition, registry, assigned, forcedNames, className, classed = [], group, grouped = [], clipChildren) {
         const elements = resolveElements(definition);
         /**
          * The new end of a paired morph: give each element the matching name from
@@ -5749,6 +5772,7 @@
                 assigned.push(element);
                 registry.set(element, name);
                 tagClass(element, className, classed);
+                applyGroup(element, name, group, grouped, clipChildren);
                 return name;
             });
         }
@@ -5789,6 +5813,7 @@
             }
             registry.set(element, name);
             tagClass(element, className, classed);
+            applyGroup(element, name, group, grouped, clipChildren);
             return name;
         });
     }
@@ -5798,13 +5823,16 @@
      * (they're not in `assigned`). Safe to call more than once (e.g. on both a
      * finished and an interrupted transition).
      */
-    function releaseViewTransitionNames(assigned, classed = []) {
+    function releaseViewTransitionNames(assigned, classed = [], grouped = []) {
         for (const element of assigned) {
             element.style?.removeProperty("view-transition-name");
         }
         for (const element of classed) {
             element.style?.removeProperty("view-transition-class");
         }
+        for (const element of grouped) {
+            element.style?.removeProperty("view-transition-group");
+        }
     }
 
     function chooseLayerType(valueName) {
@@ -5889,14 +5917,14 @@
         new: { opacity: 0, scale: 0.85 },
         old: { opacity: 1, scale: 1 },
     };
-    const cornerProps = [
-        "borderTopLeftRadius",
-        "borderTopRightRadius",
-        "borderBottomRightRadius",
-        "borderBottomLeftRadius",
-    ];
+    /**
+     * How much two box aspect ratios must differ before a morph is treated as
+     * aspect-changing (and so worth cropping). Matches the projection engine's
+     * `preserve-aspect` threshold, so small layout jitter doesn't trigger a crop.
+     */
+    const ASPECT_TOLERANCE = 0.2;
     function startViewAnimation(builder) {
-        const { update, targets, resolveDefs, noCrop, pairs, classNames, options: defaultOptions, } = builder;
+        const { update, targets, resolveDefs, cropOverride, pairs, classNames, flatGroups, options: defaultOptions, } = builder;
         if (!document.startViewTransition) {
             // An async IIFE (not `new Promise(async …)`) so a throwing/rejecting
             // update rejects this promise rather than leaving it unsettled.
@@ -5920,8 +5948,21 @@
          * ever stripping an author's own inline `view-transition-name`.
          */
         const classed = [];
+        /**
+         * Elements we set a `view-transition-group` on (for nesting), tracked for
+         * cleanup. `clipChildren` collects the names of nested parents that clip in
+         * the live layout, so their `::view-transition-group-children` is clipped
+         * through the transition - not just once the live DOM takes back over.
+         */
+        const grouped = [];
+        const clipChildren = new Set();
         const layerTargets = new Map();
         const croppedNames = new Set();
+        /**
+         * Each layer's explicit `.crop(true | false)` override (by resolved name),
+         * so `finalizeCrop` can let an author's choice win over the morph default.
+         */
+        const cropForName = new Map();
         /**
          * Each layer's stagger position (index + total) within its subject, per
          * snapshot. Resolving against the snapshot the layer belongs to keeps
@@ -5943,6 +5984,18 @@
         const resolveLayers = (phase) => {
             targets.forEach((target, definition) => {
                 const className = classNames.get(definition);
+                /**
+                 * Nest each resolved layer under its DOM-ancestor layer by default
+                 * (`contain`), so an ancestor's clip/transform/opacity reach it
+                 * through the transition; `.group(false)` opts a subject out (`none`)
+                 * to stay flat and escape. Skipped for root / pre-named layers, which
+                 * aren't elements we resolve and style.
+                 */
+                const group = definition === "root" || !resolveDefs.has(definition)
+                    ? undefined
+                    : flatGroups.has(definition)
+                        ? "none"
+                        : "contain";
                 let names;
                 if (definition === "root" || !resolveDefs.has(definition)) {
                     names = [definition];
@@ -5955,7 +6008,7 @@
                      */
                     if (phase === "old") {
                         pairFrom.set(definition, resolveElements(definition));
-                        names = assignViewTransitionNames(definition, nameRegistry, assigned, undefined, className, classed);
+                        names = assignViewTransitionNames(definition, nameRegistry, assigned, undefined, className, classed, group, grouped, clipChildren);
                         pairNames.set(definition, names);
                     }
                     else {
@@ -5975,13 +6028,16 @@
                              */
                             nameRegistry.delete(el);
                         }
-                        names = assignViewTransitionNames(pairs.get(definition), nameRegistry, assigned, pairNames.get(definition), className, classed);
+                        names = assignViewTransitionNames(pairs.get(definition), nameRegistry, assigned, pairNames.get(definition), className, classed, group, grouped, clipChildren);
                     }
                 }
                 else {
-                    names = assignViewTransitionNames(definition, nameRegistry, assigned, undefined, className, classed);
+                    names = assignViewTransitionNames(definition, nameRegistry, assigned, undefined, className, classed, group, grouped, clipChildren);
                 }
-                const cropped = definition !== "root" && !noCrop.has(definition);
+                // Record any explicit `.crop(true | false)` per resolved name; the
+                // crop set itself is computed later by `finalizeCrop` (it needs both
+                // snapshots to know which morphs change aspect ratio).
+                const override = cropOverride.get(definition);
                 names.forEach((name, index) => {
                     /**
                      * If two subjects resolve to the same element, merge their
@@ -5991,8 +6047,8 @@
                     layerTargets.set(name, existing && existing !== target
                         ? { ...existing, ...target }
                         : target);
-                    if (cropped)
-                        croppedNames.add(name);
+                    if (override !== undefined)
+                        cropForName.set(name, override);
                     const stagger = layerStagger.get(name) ?? {};
                     stagger[phase] = [index, names.length];
                     layerStagger.set(name, stagger);
@@ -6027,44 +6083,62 @@
             return transition;
         };
         /**
-         * Measured corner radii per cropped layer, so the clip can animate each
-         * corner between the old and new elements. Per-corner (rather than the
-         * shorthand) so mismatched/individual radii interpolate cleanly.
+         * Each layer's box size per snapshot, so `finalizeCrop` can tell whether a
+         * morph's aspect ratio changed (the only case worth cropping).
          */
-        const cropRadii = new Map();
-        const recordRadii = (style, name, phase) => {
-            const corners = {};
-            for (const corner of cornerProps)
-                corners[corner] = style[corner];
-            const entry = cropRadii.get(name) ?? {};
-            entry[phase] = corners;
-            cropRadii.set(name, entry);
-        };
+        const cropBox = new Map();
+        const measureLayers = (phase) => nameRegistry.forEach((name, element) => {
+            const rect = element.getBoundingClientRect?.();
+            if (rect && rect.height) {
+                const entry = cropBox.get(name) ?? {};
+                entry[phase] = { width: rect.width, height: rect.height };
+                cropBox.set(name, entry);
+            }
+        });
         /**
-         * Cropped layers all come from `.add()`, so their elements are in the
-         * registry - read each one's corner radii directly. For a paired morph both
-         * ends share a name; the new-snapshot element is registered last, so it
-         * wins the `new` reading (and the old end the `old` reading).
+         * With both snapshots measured, settle which layers crop. The default crops
+         * only a morph whose aspect ratio *changes* between snapshots - the one case
+         * where `object-fit: cover` does real work. A same-aspect morph or a
+         * fade-only layer is left uncropped: its corners scale naturally (no flash
+         * from squaring, no `overflow: clip` eating its shadow) and a backdrop can't
+         * be clipped to nothing. An explicit `.crop(true | false)` overrides either
+         * way. Runs after both snapshots are measured, since aspect needs both.
          */
-        const measureCrop = (phase) => {
-            if (!croppedNames.size)
-                return;
-            nameRegistry.forEach((name, element) => {
-                if (croppedNames.has(name)) {
-                    recordRadii(getComputedStyle(element), name, phase);
+        const finalizeCrop = () => {
+            croppedNames.clear();
+            for (const name of layerStagger.keys()) {
+                if (name === "root")
+                    continue;
+                // An explicit `.crop(true | false)` wins; otherwise crop a morph
+                // whose aspect ratio changed.
+                if (cropForName.get(name) ?? aspectChanged(name)) {
+                    croppedNames.add(name);
                 }
-            });
+            }
+        };
+        /**
+         * Whether a layer is a morph whose box aspect ratio changed between
+         * snapshots (beyond a small tolerance). Fade-only layers (one snapshot) are
+         * never "changed".
+         */
+        const aspectChanged = (name) => {
+            const box = cropBox.get(name);
+            if (!box?.old || !box?.new || !box.old.height || !box.new.height) {
+                return false;
+            }
+            return (Math.abs(box.old.width / box.old.height -
+                box.new.width / box.new.height) > ASPECT_TOLERANCE);
         };
         /**
          * Write the persistent view-transition CSS: suppress root capture when the
          * root has no animations of its own; force linear timing (baked into the
          * keyframes, so we can retime later via updateTiming); and clip +
          * object-fit: cover every cropped morph (the UA default overflows on
-         * aspect-ratio change), with an animated border-radius added below.
+         * aspect-ratio change).
          *
          * `css.commit` replaces rather than appends, so we re-set the full rule set
-         * each call - the second call (in the update callback) then picks up cropped
-         * layers that only exist in the new snapshot.
+         * each call - the crop rules are only known after `finalizeCrop` runs in the
+         * update callback, so the second call writes them.
          */
         const commitViewCSS = () => {
             if (!hasTarget("root", targets)) {
@@ -6075,33 +6149,49 @@
                 css.set(`::view-transition-group(${name})`, { overflow: "clip" });
                 css.set(`::view-transition-old(${name}), ::view-transition-new(${name})`, { width: "100%", height: "100%", "object-fit": "cover" });
             });
+            /**
+             * Clip the nested children of any layer that clips in the live layout,
+             * so a wrapper crops its child for the whole morph (mirroring the DOM)
+             * rather than only at the live-DOM handoff. No-op on browsers without
+             * nested view-transition groups.
+             */
+            clipChildren.forEach((name) => {
+                css.set(`::view-transition-group-children(${name})`, {
+                    overflow: "clip",
+                });
+            });
             css.commit(); // Write
         };
         const cleanup = () => {
-            releaseViewTransitionNames(assigned, classed);
+            releaseViewTransitionNames(assigned, classed, grouped);
             css.remove(); // Write
         };
         const callback = async () => {
             await update();
             /**
              * Re-resolve so elements created by the update are named for the new
-             * snapshot, then measure the cropped layers' new border-radius.
+             * snapshot, then measure them. With both snapshots measured we can
+             * settle the crop set (aspect-changing morphs + forced).
              */
-            const croppedBefore = croppedNames.size;
             resolveLayers("new");
-            measureCrop("new");
+            measureLayers("new");
+            finalizeCrop();
             /**
-             * Re-commit the crop CSS only if the new snapshot introduced cropped
-             * layers, so a layer that exists only in the new snapshot is clipped
-             * too - without forcing a redundant style write on the common path.
+             * Re-commit the crop CSS unconditionally: `finalizeCrop` is computed
+             * here (after both snapshots are measured), so the clip rules must be
+             * (re)written to match the settled set.
              */
-            if (croppedNames.size > croppedBefore)
-                commitViewCSS();
+            commitViewCSS();
         };
         let transition;
         try {
             resolveLayers("old");
-            measureCrop("old");
+            /**
+             * Measure the old snapshot against the optimistic crop set (the new
+             * snapshot doesn't exist yet, so aspect change can't be known here;
+             * `finalizeCrop` settles it post-update).
+             */
+            measureLayers("old");
             commitViewCSS();
             transition = document.startViewTransition(callback);
         }
@@ -6330,38 +6420,6 @@
                     });
                     animations.push(new NativeAnimationWrapper(animation));
                 }
-                /**
-                 * Animate each cropped layer's clip corners between the old and
-                 * new elements, so a cropped morph keeps rounded corners
-                 * (handling individual per-corner radii).
-                 */
-                cropRadii.forEach((radii, name) => {
-                    if (!radii.old && !radii.new)
-                        return;
-                    const target = layerTargets.get(name);
-                    const [index, total] = staggerPosition(name, "group");
-                    const radiusOptions = resolveLayerTransition(target, "group", "layout", index === -1 ? 0 : index, total);
-                    radiusOptions.duration && (radiusOptions.duration = secondsToMilliseconds(radiusOptions.duration));
-                    radiusOptions.delay && (radiusOptions.delay = secondsToMilliseconds(radiusOptions.delay));
-                    for (const corner of cornerProps) {
-                        // `||` (not `??`) so an empty measurement (e.g. an
-                        // un-rendered element) falls back rather than producing
-                        // an invalid keyframe.
-                        const from = radii.old?.[corner] || radii.new?.[corner] || "0px";
-                        const to = radii.new?.[corner] || radii.old?.[corner] || "0px";
-                        // Skip square corners - nothing to round.
-                        if (parseFloat(from) === 0 && parseFloat(to) === 0) {
-                            continue;
-                        }
-                        animations.push(new NativeAnimation({
-                            ...radiusOptions,
-                            element: document.documentElement,
-                            name: corner,
-                            pseudoElement: `::view-transition-group(${name})`,
-                            keyframes: [from, to],
-                        }));
-                    }
-                });
                 resolve(new GroupAnimation(animations));
             })
                 .catch(() => 
@@ -6471,10 +6529,12 @@
              */
             this.resolveDefs = new Set();
             /**
-             * Subjects opted out of the default crop (clip + object-fit: cover +
-             * animated corner radii) via `.crop(false)`.
+             * Per-subject crop override: `true` forces the crop (clip + object-fit:
+             * cover + animated corner radii) on, `false` forces it off. A subject with
+             * no entry uses the default - crop only a genuine morph (a layer present in
+             * both snapshots), so a fade-only enter/exit isn't clipped to nothing.
              */
-            this.noCrop = new Set();
+            this.cropOverride = new Map();
             /**
              * Subjects paired with a different new-snapshot target (the second `.add()`
              * argument), so two distinct elements share one name and morph into each
@@ -6487,6 +6547,14 @@
              * the opaque generated name.
              */
             this.classNames = new Map();
+            /**
+             * Subjects opted out of automatic group nesting via `.group(false)`. Their
+             * layer stays a flat top-level group (`view-transition-group: none`) instead
+             * of nesting under its DOM-ancestor layer - so it animates independently and
+             * escapes an ancestor's clip/transform (e.g. an element that lifts out of a
+             * card and flies across, which nesting would clip to the card).
+             */
+            this.flatGroups = new Set();
             this.notifyReady = noop;
             this.notifyReject = noop;
             this.readyPromise = new Promise((resolve, reject) => {
@@ -6524,14 +6592,37 @@
             return this;
         }
         /**
-         * Morphs are clipped + `object-fit: cover` (and their corners animate)
-         * by default. Call `.crop(false)` to opt this subject out and fall back
-         * to the browser default (which overflows on aspect-ratio change).
+         * Control this subject's crop (clip + `object-fit: cover` + animated
+         * corners). By default a subject auto-crops only when it actually morphs -
+         * present in both snapshots (a survivor, or an `.add(a, b)` pair). A
+         * fade-only enter/exit has no second box to crop against, so it's left to
+         * the browser default; in particular the `overflow: clip` a crop adds would
+         * otherwise clip a mis-sized enter/exit layer to nothing.
+         *
+         * `.crop(false)` forces the crop off (e.g. a text morph, where
+         * `object-fit: cover` clips glyphs as the box grows); `.crop(true)` forces
+         * it on for a non-morph the default wouldn't otherwise crop.
          */
         crop(enabled = true) {
+            this.cropOverride.set(this.currentSubject, enabled);
+            return this;
+        }
+        /**
+         * By default a subject's layer nests under its nearest DOM-ancestor layer
+         * (`view-transition-group: contain`), so the ancestor's clip/transform/opacity
+         * apply to it through the transition - mirroring how the DOM actually paints,
+         * and letting a wrapper crop its child for the whole morph rather than only
+         * once the live DOM takes back over. (Needs a browser that supports nested
+         * view-transition groups; elsewhere it degrades to the flat default.)
+         *
+         * Call `.group(false)` to opt out: the layer stays flat and top-level, so it
+         * animates independently and escapes an ancestor's clip - e.g. an element
+         * that should lift out of a card and fly across, which nesting would clip.
+         */
+        group(enabled = true) {
             enabled
-                ? this.noCrop.delete(this.currentSubject)
-                : this.noCrop.add(this.currentSubject);
+                ? this.flatGroups.delete(this.currentSubject)
+                : this.flatGroups.add(this.currentSubject);
             return this;
         }
         /**