react-morpheus 0.1.5 → 0.1.8

package/README.md

@@ -52,7 +52,6 @@ function Example() {
 
   return (
     <Morpheus
-      direction="bottom"
       anchor={MorphAnchor.TopMiddle}
       expanded={expanded}
       onClose={() => setExpanded(false)}
@@ -60,6 +59,7 @@ function Example() {
       overlayOpacity={0.18}
       overlayBlur={3}
       overlayZIndex={1200}
+      viewportPadding={16}
       spring={morphSpringPresets.smooth}
       collapsedContent={source}
       expandedContent={
@@ -85,8 +85,7 @@ should run around the closing animation.
 
 | Prop | Type | Required | Notes |
 | --- | --- | --- | --- |
-| `direction` | `"top" \| "right" \| "bottom" \| "left"` | Required | Where the panel opens from. Also chooses the default anchor when `anchor` is omitted. |
-| `anchor` | `MorphAnchor` | Optional | The edge or point that stays visually anchored. |
+| `anchor` | `MorphAnchor` | Required | The edge or point that stays visually anchored. |
 | `expanded` | `boolean` | Required | Controlled open state owned by your app. |
 | `onClose` | `() => void` | Optional | Called when the overlay requests closing. Use it to update your controlled open state. |
 | `beforeClose` | `() => void` | Optional | Called when the closing animation starts, after `expanded` has changed to `false`. Useful for close-intent side effects. |
@@ -94,6 +93,9 @@ should run around the closing animation.
 | `collapsedContent` | `ReactNode` | Required | The source surface Morpheus measures, renders, and uses as the opener. |
 | `expandedContent` | `ReactNode` | Required | The destination surface Morpheus measures and animates into. |
 | `className` | `string` | Optional | Classes applied to the root wrapper. Useful for block layout and responsive width constraints. |
+| `shellClassName` | `string` | Optional | Classes applied directly to the animated shell, including when it is portalled. |
+| `portalContainer` | `HTMLElement \| null` | Optional | Portal root for the expanded surface. Defaults to `document.body` after mount; pass `null` for legacy inline rendering. |
+| `viewportPadding` | `number` | Optional | Minimum viewport gutter for the expanded shell. Defaults to `16`. |
 | `overlayColor` | `string` | Optional | Backdrop color shown while expanded. |
 | `overlayOpacity` | `number` | Optional | Backdrop opacity from `0` to `1`. |
 | `overlayBlur` | `number` | Optional | Backdrop blur in pixels. |
@@ -116,14 +118,19 @@ upward; middle anchors feel better for centered inspectors or command surfaces.
 
 ### Parent Container Overflow
 
-Do not place Morpheus inside a container that clips overflow, such as
-`overflow: hidden`, `overflow: clip`, or scroll containers. The expanded surface
-is positioned from the local source element and can extend outside its original
-container while animating.
+Expanded surfaces and their overlays portal to `document.body` by default, so
+they can escape clipped, transformed, and independently stacked ancestors. The
+collapsed source remains in its original layout position. Pass another
+document-level `portalContainer` when needed, or `null` to opt into the legacy
+inline behavior.
+
+Targets are clamped to the viewport using `viewportPadding`. When their natural
+size is larger than the available viewport, the shell stays bounded and becomes
+scrollable after the opening animation settles.
 
 ### Stacking
 
-`overlayZIndex` controls the expanded morph surface. The overlay renders one
+`overlayZIndex` controls the portalled expanded surface. The overlay renders one
 layer below it so apps can move the whole morphing stack above their own chrome.
 Without this prop, Morpheus uses surface `1000` and overlay `999`.
 
@@ -131,7 +138,7 @@ Without this prop, Morpheus uses surface `1000` and overlay `999`.
 
 `example.html` is a small local playground for trying Morpheus in a browser
 without setting up an app shell. Use it to check the default interaction,
-directions, anchors, and overlay behavior while changing the component.
+anchors and overlay behavior while changing the component.
 
 ### Scripts
 

package/dist/index.d.ts

@@ -2,7 +2,6 @@ import * as react from 'react';
 import { ReactNode, RefObject } from 'react';
 import { Transition } from 'framer-motion';
 
-type MorphDirection = "top" | "right" | "bottom" | "left";
 declare enum MorphAnchor {
     LeftTop = "left-top",
     LeftMiddle = "left-middle",
@@ -18,6 +17,10 @@ type PanelSize = {
     width: number;
     height: number;
 };
+type PanelRect = PanelSize & {
+    left: number;
+    top: number;
+};
 type ContentOffset = {
     x: number;
     y: number;
@@ -49,8 +52,7 @@ type MorphMeasurements = {
 };
 type MorphMotionInput = {
     expanded: boolean;
-    direction: MorphDirection;
-    anchor?: MorphAnchor | undefined;
+    anchor: MorphAnchor;
     spring: Transition;
     animationEnabled: boolean;
     collapsed: MorphMeasuredSurface;
@@ -74,8 +76,7 @@ type MorphMotionState = {
     visualStyle: PanelVisualStyle;
 };
 type MorphProps = {
-    direction: MorphDirection;
-    anchor?: MorphAnchor | undefined;
+    anchor: MorphAnchor;
     expanded: boolean;
     onClose?: (() => void) | undefined;
     beforeClose?: (() => void) | undefined;
@@ -83,6 +84,9 @@ type MorphProps = {
     collapsedContent: ReactNode;
     expandedContent: ReactNode;
     className?: string;
+    shellClassName?: string;
+    portalContainer?: HTMLElement | null;
+    viewportPadding?: number;
     overlayColor?: string;
     overlayOpacity?: number;
     overlayBlur?: number;
@@ -114,6 +118,7 @@ type MorphShellProps = {
     onMorphComplete: () => void;
     onMorphStart: () => void;
     children: ReactNode;
+    className?: string | undefined;
 };
 type MorphContentLayersProps = {
     expanded: boolean;
@@ -136,9 +141,8 @@ type MorphLayerInteractivityProps = {
     inert?: boolean;
 };
 
-declare function Morpheus({ direction, anchor, expanded, onClose, beforeClose, afterClose, collapsedContent, expandedContent, className, overlayColor, overlayOpacity, overlayBlur, overlayZIndex: zIndex, spring, }: MorphProps): react.JSX.Element;
+declare function Morpheus(props: MorphProps): react.JSX.Element;
 
-declare const defaultAnchorByDirection: Record<MorphDirection, MorphAnchor>;
 declare const morphSpringPresets: {
     balanced: {
         type: "spring";
@@ -172,4 +176,4 @@ declare const morphSpringPresets: {
     };
 };
 
-export { type ContentOffset, MorphAnchor, type MorphContentLayersProps, type MorphDirection, type MorphLayerInteractivityProps, type MorphMeasuredSurface, type MorphMeasurementNodesProps, type MorphMeasurements, type MorphMotionInput, type MorphMotionState, type MorphOverlayProps, type MorphProps, type MorphShellProps, type MorphSpringPreset, type MorphSurfaceSnapshot, Morpheus, type PanelPosition, type PanelSize, type PanelVisualStyle, Morpheus as default, defaultAnchorByDirection, morphSpringPresets };
+export { type ContentOffset, MorphAnchor, type MorphContentLayersProps, type MorphLayerInteractivityProps, type MorphMeasuredSurface, type MorphMeasurementNodesProps, type MorphMeasurements, type MorphMotionInput, type MorphMotionState, type MorphOverlayProps, type MorphProps, type MorphShellProps, type MorphSpringPreset, type MorphSurfaceSnapshot, Morpheus, type PanelPosition, type PanelRect, type PanelSize, type PanelVisualStyle, Morpheus as default, morphSpringPresets };

package/dist/index.js

@@ -1,6 +1,15 @@
 // src/component.tsx
 import { motion as motion2 } from "framer-motion";
-import { useEffect, useRef as useRef2, useState as useState2 } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect as useLayoutEffect2,
+  useRef as useRef2,
+  useState as useState2
+} from "react";
+import { createPortal } from "react-dom";
 
 // src/measurement.ts
 import { useLayoutEffect, useRef, useState } from "react";
@@ -40,8 +49,14 @@ function getSurfaceVisualStyle(element) {
 }
 function measureSurface(element) {
   const measuredElement = getMeasuredElement(element);
-  const width = measuredElement.offsetWidth;
-  const height = measuredElement.offsetHeight;
+  const width = Math.max(
+    measuredElement.offsetWidth,
+    measuredElement.scrollWidth
+  );
+  const height = Math.max(
+    measuredElement.offsetHeight,
+    measuredElement.scrollHeight
+  );
   if (width === 0 || height === 0) {
     return null;
   }
@@ -115,12 +130,6 @@ var MorphAnchor = /* @__PURE__ */ ((MorphAnchor2) => {
 })(MorphAnchor || {});
 
 // src/motion.ts
-var defaultAnchorByDirection = {
-  top: "bottom-middle" /* BottomMiddle */,
-  right: "left-middle" /* LeftMiddle */,
-  bottom: "top-middle" /* TopMiddle */,
-  left: "right-middle" /* RightMiddle */
-};
 var anchorTransformOrigins = {
   ["left-top" /* LeftTop */]: "left top",
   ["left-middle" /* LeftMiddle */]: "left center",
@@ -173,8 +182,7 @@ var sourceContentFade = {
   duration: 0.12,
   ease: "easeOut"
 };
-var sourceReturnDelay = 0.06;
-var sourceGrowthRatio = 2;
+var sourceReturnDelay = 0.1;
 var instantTransition = { duration: 0 };
 var createSourceContentMotion = (spring) => ({
   opacity: sourceContentFade,
@@ -191,6 +199,12 @@ var createTargetContentMotion = (spring) => ({
   top: spring
 });
 var safeScale = (from, to) => to === 0 ? 1 : from / to;
+function getAxisScale(fromSize, toSize) {
+  return {
+    x: safeScale(toSize.width, fromSize.width),
+    y: safeScale(toSize.height, fromSize.height)
+  };
+}
 function getAnchoredPanelPosition(anchor, collapsedSize, targetSize) {
   const alignLeft = 0;
   const alignCenterX = (collapsedSize.width - targetSize.width) / 2;
@@ -230,7 +244,6 @@ function getLayerInteractivityProps(interactive) {
 }
 function getMorphMotionState({
   expanded,
-  direction,
   anchor,
   spring,
   animationEnabled,
@@ -241,10 +254,9 @@ function getMorphMotionState({
   const expandedLayerSize = expandedSurface.size;
   const animatedSize = expanded ? expandedLayerSize : collapsedLayerSize;
   const visualStyle = expanded ? expandedSurface.visualStyle : collapsed.visualStyle;
-  const panelAnchor = anchor ?? defaultAnchorByDirection[direction];
   const sourcePanelPosition = { left: 0, top: 0 };
   const targetPanelPosition = getAnchoredPanelPosition(
-    panelAnchor,
+    anchor,
     collapsedLayerSize,
     expandedLayerSize
   );
@@ -254,17 +266,17 @@ function getMorphMotionState({
     anchorPosition: expanded ? targetPanelPosition : sourcePanelPosition,
     animatedSize,
     collapsedLayerSize,
-    collapsedToExpandedScale: {
-      x: safeScale(collapsedLayerSize.width, expandedLayerSize.width),
-      y: safeScale(collapsedLayerSize.height, expandedLayerSize.height)
-    },
+    collapsedToExpandedScale: getAxisScale(
+      expandedLayerSize,
+      collapsedLayerSize
+    ),
     expandedLayerSize,
-    sourceGrowthScale: {
-      x: sourceGrowthRatio,
-      y: sourceGrowthRatio
-    },
+    sourceGrowthScale: getAxisScale(collapsedLayerSize, expandedLayerSize),
     sourceOpacityTransition: {
       ...sourceContentFade,
+      // On close, the source layer is still being non-uniformly scaled from
+      // the target geometry. Keep it transparent until the spring has brought
+      // it close enough to its natural proportions to avoid a stretched flash.
       delay: expanded ? 0 : sourceReturnDelay
     },
     sourcePosition: expanded ? invertPosition(targetPanelPosition) : sourcePanelPosition,
@@ -272,7 +284,7 @@ function getMorphMotionState({
     targetOpacityTransition: { ...contentFade, delay: expanded ? 0.03 : 0 },
     targetPosition: expanded ? sourcePanelPosition : targetPanelPosition,
     targetTransition: createTargetContentMotion(activeSpring),
-    transformOrigin: anchorTransformOrigins[panelAnchor],
+    transformOrigin: anchorTransformOrigins[anchor],
     visualStyle
   };
 }
@@ -324,22 +336,129 @@ function MorphOverlay({
   ) : null });
 }
 
+// src/placement.ts
+var clamp = (value, minimum, maximum) => Math.min(Math.max(value, minimum), Math.max(minimum, maximum));
+function getBoundedPanelSize(naturalSize, viewport, padding) {
+  const safePadding = Math.max(0, padding);
+  return {
+    width: Math.min(
+      naturalSize.width,
+      Math.max(1, viewport.width - safePadding * 2)
+    ),
+    height: Math.min(
+      naturalSize.height,
+      Math.max(1, viewport.height - safePadding * 2)
+    )
+  };
+}
+function getAnchoredTargetRect(anchor, source, targetSize, viewport, padding) {
+  const sourceCenterX = source.left + source.width / 2;
+  const sourceCenterY = source.top + source.height / 2;
+  let left = source.left;
+  let top = source.top;
+  switch (anchor) {
+    case "left-top" /* LeftTop */:
+      break;
+    case "left-middle" /* LeftMiddle */:
+      top = sourceCenterY - targetSize.height / 2;
+      break;
+    case "left-bottom" /* LeftBottom */:
+      top = source.top + source.height - targetSize.height;
+      break;
+    case "top-middle" /* TopMiddle */:
+      left = sourceCenterX - targetSize.width / 2;
+      break;
+    case "middle-middle" /* MiddleMiddle */:
+      left = sourceCenterX - targetSize.width / 2;
+      top = sourceCenterY - targetSize.height / 2;
+      break;
+    case "right-top" /* RightTop */:
+      left = source.left + source.width - targetSize.width;
+      break;
+    case "right-middle" /* RightMiddle */:
+      left = source.left + source.width - targetSize.width;
+      top = sourceCenterY - targetSize.height / 2;
+      break;
+    case "right-bottom" /* RightBottom */:
+      left = source.left + source.width - targetSize.width;
+      top = source.top + source.height - targetSize.height;
+      break;
+    case "bottom-middle" /* BottomMiddle */:
+      left = sourceCenterX - targetSize.width / 2;
+      top = source.top + source.height - targetSize.height;
+      break;
+  }
+  const safePadding = Math.max(0, padding);
+  const minimumLeft = viewport.left + safePadding;
+  const minimumTop = viewport.top + safePadding;
+  const maximumLeft = viewport.left + viewport.width - safePadding - targetSize.width;
+  const maximumTop = viewport.top + viewport.height - safePadding - targetSize.height;
+  return {
+    left: clamp(left, minimumLeft, maximumLeft),
+    top: clamp(top, minimumTop, maximumTop),
+    ...targetSize
+  };
+}
+function getPortalLayerPositions(expanded, source, target) {
+  const sourceFromTarget = {
+    left: source.left - target.left,
+    top: source.top - target.top
+  };
+  const targetFromSource = {
+    left: target.left - source.left,
+    top: target.top - source.top
+  };
+  const origin = { left: 0, top: 0 };
+  return expanded ? {
+    sourcePosition: sourceFromTarget,
+    targetPosition: origin
+  } : {
+    sourcePosition: origin,
+    targetPosition: targetFromSource
+  };
+}
+
 // src/component.tsx
 import { Fragment, jsx as jsx2, jsxs } from "react/jsx-runtime";
 var liveSurfaceContentClassName = "rmorph:absolute";
+var MorphMeasurementContext = createContext(false);
+function mergeClassNames(...classNames) {
+  return classNames.filter(Boolean).join(" ");
+}
+function getViewportBounds() {
+  const viewport = window.visualViewport;
+  if (viewport) {
+    return {
+      left: viewport.offsetLeft,
+      top: viewport.offsetTop,
+      width: viewport.width,
+      height: viewport.height
+    };
+  }
+  return {
+    left: 0,
+    top: 0,
+    width: document.documentElement.clientWidth,
+    height: document.documentElement.clientHeight
+  };
+}
 function MorphMeasurementNodes({
   collapsedRef,
   expandedRef,
   collapsedContent,
   expandedContent
 }) {
-  return /* @__PURE__ */ jsxs(Fragment, { children: [
+  const measurementStyle = {
+    overflow: "clip"
+  };
+  return /* @__PURE__ */ jsxs(MorphMeasurementContext.Provider, { value: true, children: [
     /* @__PURE__ */ jsx2(
       "div",
       {
         ref: collapsedRef,
-        "aria-hidden": "true",
+        inert: true,
         className: "rmorph:invisible rmorph:absolute rmorph:inset-x-0 rmorph:top-0 rmorph:pointer-events-none",
+        style: measurementStyle,
         children: collapsedContent
       }
     ),
@@ -347,8 +466,9 @@ function MorphMeasurementNodes({
       "div",
       {
         ref: expandedRef,
-        "aria-hidden": "true",
+        inert: true,
         className: "rmorph:invisible rmorph:absolute rmorph:inset-x-0 rmorph:top-0 rmorph:pointer-events-none",
+        style: measurementStyle,
         children: expandedContent
       }
     )
@@ -364,12 +484,13 @@ function MorphShell({
   spring,
   onMorphComplete,
   onMorphStart,
-  children
+  children,
+  className
 }) {
   return /* @__PURE__ */ jsx2(
     motion2.div,
     {
-      className: "rmorph:absolute rmorph:shadow-xs",
+      className: mergeClassNames("rmorph:absolute rmorph:shadow-xs", className),
       initial: false,
       animate: {
         width: animatedSize.width,
@@ -389,6 +510,51 @@ function MorphShell({
     }
   );
 }
+function PortalMorphShell({
+  expanded,
+  lifecyclePhase,
+  geometry,
+  collapsedVisualStyle,
+  expandedVisualStyle,
+  overflow,
+  zIndex,
+  spring,
+  onMorphComplete,
+  onMorphStart,
+  children,
+  className
+}) {
+  const rect = expanded ? geometry.target : geometry.source;
+  const visualStyle = expanded ? expandedVisualStyle : collapsedVisualStyle;
+  return /* @__PURE__ */ jsx2(
+    motion2.div,
+    {
+      "data-morpheus-portal-shell": "",
+      "data-morpheus-phase": lifecyclePhase,
+      inert: lifecyclePhase === "handoff" || void 0,
+      className: mergeClassNames("rmorph:fixed rmorph:shadow-xs", className),
+      initial: false,
+      animate: {
+        left: rect.left,
+        top: rect.top,
+        width: rect.width,
+        height: rect.height,
+        backgroundColor: visualStyle.backgroundColor,
+        borderRadius: visualStyle.borderRadius
+      },
+      onAnimationComplete: onMorphComplete,
+      ...onMorphStart ? { onAnimationStart: onMorphStart } : {},
+      style: {
+        overflow,
+        overscrollBehavior: "contain",
+        pointerEvents: lifecyclePhase === "handoff" ? "none" : void 0,
+        zIndex
+      },
+      transition: spring,
+      children
+    }
+  );
+}
 function MorphContentLayers({
   expanded,
   settledState,
@@ -461,8 +627,26 @@ function MorphContentLayers({
     )
   ] });
 }
-function Morpheus({
-  direction,
+function MeasurementTreePlaceholder({
+  className,
+  collapsedContent
+}) {
+  return /* @__PURE__ */ jsx2("div", { className, children: /* @__PURE__ */ jsx2("div", { className: "rmorph:relative rmorph:mx-auto rmorph:block rmorph:w-fit rmorph:align-top", children: /* @__PURE__ */ jsx2("div", { className: "rmorph:inline-block rmorph:align-top", children: collapsedContent }) }) });
+}
+function Morpheus(props) {
+  const insideMeasurementTree = useContext(MorphMeasurementContext);
+  if (insideMeasurementTree) {
+    return /* @__PURE__ */ jsx2(
+      MeasurementTreePlaceholder,
+      {
+        className: props.className ?? "rmorph:relative rmorph:inline-block rmorph:align-top",
+        collapsedContent: props.collapsedContent
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx2(MorpheusRoot, { ...props });
+}
+function MorpheusRoot({
   anchor,
   expanded,
   onClose,
@@ -471,6 +655,9 @@ function Morpheus({
   collapsedContent,
   expandedContent,
   className = "rmorph:relative rmorph:inline-block rmorph:align-top",
+  shellClassName,
+  portalContainer,
+  viewportPadding = 16,
   overlayColor = "#05070a",
   overlayOpacity = 0.54,
   overlayBlur = 0,
@@ -478,13 +665,51 @@ function Morpheus({
   spring = defaultPanelSpring
 }) {
   const measurements = useMorphMeasurements();
+  const anchorRef = useRef2(null);
+  const [defaultPortalContainer, setDefaultPortalContainer] = useState2(null);
   const [animationEnabled, setAnimationEnabled] = useState2(false);
   const [shellOverflowVisible, setShellOverflowVisible] = useState2(false);
-  const [settledState, setSettledState] = useState2(
+  const [inlineSettledState, setInlineSettledState] = useState2(expanded ? "expanded" : "collapsed");
+  const [portalPhase, setPortalPhase] = useState2(
     expanded ? "expanded" : "collapsed"
   );
+  const [portalVisualExpanded, setPortalVisualExpanded] = useState2(expanded);
+  const [portalGeometry, setPortalGeometry] = useState2(
+    null
+  );
   const hasOpenedRef = useRef2(expanded);
   const beforeCloseCalledRef = useRef2(false);
+  const beforeCloseRef = useRef2(beforeClose);
+  const afterCloseRef = useRef2(afterClose);
+  const previousExpandedRef = useRef2(expanded);
+  const portalStartFrameRef = useRef2(null);
+  const handoffFirstFrameRef = useRef2(null);
+  const handoffSecondFrameRef = useRef2(null);
+  const portalPhaseRef = useRef2(portalPhase);
+  const expandedRef = useRef2(expanded);
+  portalPhaseRef.current = portalPhase;
+  expandedRef.current = expanded;
+  beforeCloseRef.current = beforeClose;
+  afterCloseRef.current = afterClose;
+  const cancelPortalFrames = useCallback(() => {
+    if (portalStartFrameRef.current !== null) {
+      cancelAnimationFrame(portalStartFrameRef.current);
+      portalStartFrameRef.current = null;
+    }
+    if (handoffFirstFrameRef.current !== null) {
+      cancelAnimationFrame(handoffFirstFrameRef.current);
+      handoffFirstFrameRef.current = null;
+    }
+    if (handoffSecondFrameRef.current !== null) {
+      cancelAnimationFrame(handoffSecondFrameRef.current);
+      handoffSecondFrameRef.current = null;
+    }
+  }, []);
+  useEffect(() => {
+    if (portalContainer === void 0) {
+      setDefaultPortalContainer(document.body);
+    }
+  }, [portalContainer]);
   useEffect(() => {
     if (!measurements.ready) {
       return;
@@ -492,113 +717,339 @@ function Morpheus({
     const frame = requestAnimationFrame(() => setAnimationEnabled(true));
     return () => cancelAnimationFrame(frame);
   }, [measurements.ready]);
-  const motionState = getMorphMotionState({
+  const resolvedPortalContainer = portalContainer === void 0 ? defaultPortalContainer : portalContainer;
+  const portalEnabled = resolvedPortalContainer !== null;
+  const panelAnchor = anchor;
+  const updatePortalGeometry = useCallback(() => {
+    const sourceElement = anchorRef.current;
+    if (!sourceElement || !measurements.ready) {
+      return;
+    }
+    const sourceBounds = sourceElement.getBoundingClientRect();
+    const source = {
+      left: sourceBounds.left,
+      top: sourceBounds.top,
+      width: sourceBounds.width,
+      height: sourceBounds.height
+    };
+    const viewport = getViewportBounds();
+    const targetSize = getBoundedPanelSize(
+      measurements.expanded.size,
+      viewport,
+      viewportPadding
+    );
+    const target = getAnchoredTargetRect(
+      panelAnchor,
+      source,
+      targetSize,
+      viewport,
+      viewportPadding
+    );
+    setPortalGeometry((current) => {
+      if (current?.source.left === source.left && current.source.top === source.top && current.source.width === source.width && current.source.height === source.height && current.target.left === target.left && current.target.top === target.top && current.target.width === target.width && current.target.height === target.height) {
+        return current;
+      }
+      return { source, target };
+    });
+  }, [
+    measurements.expanded.size,
+    measurements.ready,
+    panelAnchor,
+    viewportPadding
+  ]);
+  useLayoutEffect2(() => {
+    if (!portalEnabled || !measurements.ready) {
+      return;
+    }
+    const expandedChanged = previousExpandedRef.current !== expanded;
+    previousExpandedRef.current = expanded;
+    updatePortalGeometry();
+    if (!expandedChanged) {
+      return;
+    }
+    cancelPortalFrames();
+    if (expanded) {
+      setPortalPhase("opening");
+      setPortalVisualExpanded(false);
+      portalStartFrameRef.current = requestAnimationFrame(() => {
+        portalStartFrameRef.current = null;
+        if (!expandedRef.current || portalPhaseRef.current !== "opening") {
+          return;
+        }
+        setPortalVisualExpanded(true);
+      });
+      return;
+    }
+    if (portalPhaseRef.current !== "collapsed" && portalPhaseRef.current !== "closing") {
+      setPortalPhase("closing");
+      setPortalVisualExpanded(false);
+      if (hasOpenedRef.current && !beforeCloseCalledRef.current) {
+        beforeCloseCalledRef.current = true;
+        beforeCloseRef.current?.();
+      }
+    }
+  }, [
+    cancelPortalFrames,
     expanded,
-    direction,
+    measurements.ready,
+    portalEnabled,
+    updatePortalGeometry
+  ]);
+  useLayoutEffect2(() => {
+    if (portalPhase !== "handoff" || expanded) {
+      return;
+    }
+    handoffFirstFrameRef.current = requestAnimationFrame(() => {
+      handoffFirstFrameRef.current = null;
+      if (expandedRef.current || portalPhaseRef.current !== "handoff") {
+        return;
+      }
+      handoffSecondFrameRef.current = requestAnimationFrame(() => {
+        handoffSecondFrameRef.current = null;
+        if (expandedRef.current || portalPhaseRef.current !== "handoff") {
+          return;
+        }
+        setPortalPhase("collapsed");
+        setPortalGeometry(null);
+        if (hasOpenedRef.current) {
+          hasOpenedRef.current = false;
+          afterCloseRef.current?.();
+        }
+      });
+    });
+    return cancelPortalFrames;
+  }, [cancelPortalFrames, expanded, portalPhase]);
+  useEffect(() => {
+    if (!portalEnabled || portalPhase === "collapsed" || !measurements.ready) {
+      return;
+    }
+    let frame = null;
+    const scheduleUpdate = () => {
+      if (frame !== null) {
+        return;
+      }
+      frame = requestAnimationFrame(() => {
+        frame = null;
+        updatePortalGeometry();
+      });
+    };
+    const observer = new ResizeObserver(scheduleUpdate);
+    if (anchorRef.current) {
+      observer.observe(anchorRef.current);
+    }
+    window.addEventListener("scroll", scheduleUpdate, true);
+    window.addEventListener("resize", scheduleUpdate);
+    window.visualViewport?.addEventListener("resize", scheduleUpdate);
+    window.visualViewport?.addEventListener("scroll", scheduleUpdate);
+    return () => {
+      if (frame !== null) {
+        cancelAnimationFrame(frame);
+      }
+      observer.disconnect();
+      window.removeEventListener("scroll", scheduleUpdate, true);
+      window.removeEventListener("resize", scheduleUpdate);
+      window.visualViewport?.removeEventListener("resize", scheduleUpdate);
+      window.visualViewport?.removeEventListener("scroll", scheduleUpdate);
+    };
+  }, [measurements.ready, portalEnabled, portalPhase, updatePortalGeometry]);
+  useEffect(() => cancelPortalFrames, [cancelPortalFrames]);
+  const motionState = getMorphMotionState({
+    expanded: portalEnabled ? portalVisualExpanded : expanded,
     anchor,
     spring,
     animationEnabled,
     collapsed: measurements.collapsed,
     expandedSurface: measurements.expanded
   });
-  const overflowVisible = expanded && shellOverflowVisible;
   const shouldRenderStaticSource = !measurements.ready && !expanded;
-  return /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsx2(
-      MorphOverlay,
+  const portalPresent = portalPhase !== "collapsed";
+  const portalIsRendered = portalEnabled && portalPresent && portalGeometry !== null && resolvedPortalContainer !== null;
+  const inlineSourceHidden = portalIsRendered && portalPhase !== "handoff";
+  const portalSettledState = portalPhase === "expanded" || portalPhase === "closing" ? "expanded" : "collapsed";
+  const portalTargetIsBounded = portalGeometry !== null && (portalGeometry.target.width < measurements.expanded.size.width || portalGeometry.target.height < measurements.expanded.size.height);
+  const contentLayers = (surfaceExpanded, settledState, portalMode = false) => {
+    const layerPositions = portalMode && portalGeometry ? getPortalLayerPositions(
+      surfaceExpanded,
+      portalGeometry.source,
+      portalGeometry.target
+    ) : {
+      sourcePosition: motionState.sourcePosition,
+      targetPosition: motionState.targetPosition
+    };
+    const sourceGrowthScale = portalMode && portalGeometry ? getAxisScale(
+      motionState.collapsedLayerSize,
+      portalGeometry.target
+    ) : motionState.sourceGrowthScale;
+    const collapsedToExpandedScale = portalMode && portalGeometry ? getAxisScale(
+      motionState.expandedLayerSize,
+      portalGeometry.source
+    ) : motionState.collapsedToExpandedScale;
+    return /* @__PURE__ */ jsx2(
+      MorphContentLayers,
       {
-        expanded,
-        onClose,
-        color: overlayColor,
-        opacity: overlayOpacity,
-        blur: overlayBlur,
-        zIndex
+        expanded: surfaceExpanded,
+        settledState,
+        collapsedContent,
+        expandedContent,
+        collapsedLayerSize: motionState.collapsedLayerSize,
+        expandedLayerSize: motionState.expandedLayerSize,
+        sourcePosition: layerPositions.sourcePosition,
+        targetPosition: layerPositions.targetPosition,
+        sourceGrowthScale,
+        collapsedToExpandedScale,
+        transformOrigin: motionState.transformOrigin,
+        sourceTransition: motionState.sourceTransition,
+        sourceOpacityTransition: motionState.sourceOpacityTransition,
+        targetTransition: motionState.targetTransition,
+        targetOpacityTransition: motionState.targetOpacityTransition
       }
-    ),
-    /* @__PURE__ */ jsxs("div", { className, "aria-live": "polite", children: [
+    );
+  };
+  const measurementNodes = /* @__PURE__ */ jsx2(
+    MorphMeasurementNodes,
+    {
+      collapsedRef: measurements.collapsedRef,
+      expandedRef: measurements.expandedRef,
+      collapsedContent,
+      expandedContent
+    }
+  );
+  if (!portalEnabled && portalContainer === null) {
+    const overflowVisible = expanded && shellOverflowVisible;
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsx2(
-        MorphMeasurementNodes,
+        MorphOverlay,
         {
-          collapsedRef: measurements.collapsedRef,
-          expandedRef: measurements.expandedRef,
-          collapsedContent,
-          expandedContent
+          expanded,
+          onClose,
+          color: overlayColor,
+          opacity: overlayOpacity,
+          blur: overlayBlur,
+          zIndex
         }
       ),
-      /* @__PURE__ */ jsx2("div", { className: "rmorph:relative rmorph:mx-auto rmorph:block rmorph:w-fit rmorph:align-top", children: shouldRenderStaticSource ? /* @__PURE__ */ jsx2("div", { className: "rmorph:inline-block rmorph:align-top", children: collapsedContent }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsxs("div", { className, "aria-live": "polite", children: [
+        measurementNodes,
+        /* @__PURE__ */ jsx2("div", { className: "rmorph:relative rmorph:mx-auto rmorph:block rmorph:w-fit rmorph:align-top", children: shouldRenderStaticSource ? /* @__PURE__ */ jsx2("div", { className: "rmorph:inline-block rmorph:align-top", children: collapsedContent }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx2(
+            "div",
+            {
+              "aria-hidden": "true",
+              style: {
+                visibility: "hidden",
+                width: motionState.collapsedLayerSize.width,
+                height: motionState.collapsedLayerSize.height
+              }
+            }
+          ),
+          /* @__PURE__ */ jsx2(
+            MorphShell,
+            {
+              expanded,
+              position: motionState.anchorPosition,
+              animatedSize: motionState.animatedSize,
+              visualStyle: motionState.visualStyle,
+              overflowVisible,
+              zIndex,
+              spring: motionState.activeSpring,
+              className: shellClassName,
+              onMorphComplete: () => {
+                if (expanded) {
+                  hasOpenedRef.current = true;
+                  beforeCloseCalledRef.current = false;
+                  setInlineSettledState("expanded");
+                  setShellOverflowVisible(true);
+                  return;
+                }
+                setInlineSettledState("collapsed");
+                if (hasOpenedRef.current) {
+                  hasOpenedRef.current = false;
+                  afterClose?.();
+                }
+              },
+              onMorphStart: () => {
+                if (!expanded && hasOpenedRef.current && !beforeCloseCalledRef.current) {
+                  beforeCloseCalledRef.current = true;
+                  beforeClose?.();
+                }
+                setShellOverflowVisible(false);
+                setInlineSettledState(expanded ? "collapsed" : "expanded");
+              },
+              children: contentLayers(expanded, inlineSettledState)
+            }
+          )
+        ] }) })
+      ] })
+    ] });
+  }
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs("div", { className, "aria-live": "polite", children: [
+      measurementNodes,
+      /* @__PURE__ */ jsx2("div", { className: "rmorph:relative rmorph:mx-auto rmorph:block rmorph:w-fit rmorph:align-top", children: /* @__PURE__ */ jsx2(
+        "div",
+        {
+          ref: anchorRef,
+          "data-morpheus-inline-source": "",
+          ...getLayerInteractivityProps(!inlineSourceHidden),
+          className: mergeClassNames(
+            "rmorph:inline-block rmorph:align-top rmorph:shadow-xs",
+            shellClassName
+          ),
+          style: {
+            visibility: inlineSourceHidden ? "hidden" : void 0,
+            pointerEvents: inlineSourceHidden ? "none" : void 0
+          },
+          children: collapsedContent
+        }
+      ) })
+    ] }),
+    portalIsRendered && portalGeometry && resolvedPortalContainer ? createPortal(
+      /* @__PURE__ */ jsxs(Fragment, { children: [
         /* @__PURE__ */ jsx2(
-          "div",
+          MorphOverlay,
           {
-            "aria-hidden": "true",
-            style: {
-              visibility: "hidden",
-              width: motionState.collapsedLayerSize.width,
-              height: motionState.collapsedLayerSize.height
-            }
+            expanded,
+            onClose,
+            color: overlayColor,
+            opacity: overlayOpacity,
+            blur: overlayBlur,
+            zIndex
           }
         ),
         /* @__PURE__ */ jsx2(
-          MorphShell,
+          PortalMorphShell,
           {
-            expanded,
-            position: motionState.anchorPosition,
-            animatedSize: motionState.animatedSize,
-            visualStyle: motionState.visualStyle,
-            overflowVisible,
+            expanded: portalVisualExpanded,
+            lifecyclePhase: portalPhase,
+            geometry: portalGeometry,
+            collapsedVisualStyle: measurements.collapsed.visualStyle,
+            expandedVisualStyle: measurements.expanded.visualStyle,
+            overflow: portalPhase === "expanded" ? portalTargetIsBounded ? "auto" : "visible" : "hidden",
             zIndex,
             spring: motionState.activeSpring,
+            className: shellClassName,
             onMorphComplete: () => {
-              if (expanded) {
+              if (expandedRef.current && portalPhaseRef.current === "opening" && portalVisualExpanded) {
                 hasOpenedRef.current = true;
                 beforeCloseCalledRef.current = false;
-                setSettledState("expanded");
-                setShellOverflowVisible(true);
+                setPortalPhase("expanded");
                 return;
               }
-              setSettledState("collapsed");
-              if (hasOpenedRef.current) {
-                hasOpenedRef.current = false;
-                afterClose?.();
-              }
-            },
-            onMorphStart: () => {
-              if (!expanded && hasOpenedRef.current && !beforeCloseCalledRef.current) {
-                beforeCloseCalledRef.current = true;
-                beforeClose?.();
+              if (!expandedRef.current && portalPhaseRef.current === "closing" && !portalVisualExpanded) {
+                setPortalPhase("handoff");
               }
-              setShellOverflowVisible(false);
-              setSettledState(expanded ? "collapsed" : "expanded");
             },
-            children: /* @__PURE__ */ jsx2(
-              MorphContentLayers,
-              {
-                expanded,
-                settledState,
-                collapsedContent,
-                expandedContent,
-                collapsedLayerSize: motionState.collapsedLayerSize,
-                expandedLayerSize: motionState.expandedLayerSize,
-                sourcePosition: motionState.sourcePosition,
-                targetPosition: motionState.targetPosition,
-                sourceGrowthScale: motionState.sourceGrowthScale,
-                collapsedToExpandedScale: motionState.collapsedToExpandedScale,
-                transformOrigin: motionState.transformOrigin,
-                sourceTransition: motionState.sourceTransition,
-                sourceOpacityTransition: motionState.sourceOpacityTransition,
-                targetTransition: motionState.targetTransition,
-                targetOpacityTransition: motionState.targetOpacityTransition
-              }
-            )
+            children: contentLayers(portalVisualExpanded, portalSettledState, true)
           }
         )
-      ] }) })
-    ] })
+      ] }),
+      resolvedPortalContainer
+    ) : null
   ] });
 }
 export {
   MorphAnchor,
   Morpheus,
   Morpheus as default,
-  defaultAnchorByDirection,
   morphSpringPresets
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-morpheus",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "A React component for morphing one surface into other.",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,7 @@
     "build:js": "tsup src/index.ts --format esm --dts --external react --external react-dom --external framer-motion --clean",
     "build:css": "tailwindcss -i src/style.css -o dist/style.css --minify",
     "check": "tsc --noEmit",
+    "test": "bun test",
     "publish:npm": "bun run scripts/publish.ts",
     "release:minor": "bun run scripts/release.ts minor",
     "release:major": "bun run scripts/release.ts major",
@@ -40,7 +41,9 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^20.11.1",
     "@tailwindcss/cli": "^4.3.3",
+    "@testing-library/react": "^16.3.2",
     "@types/bun": "^1.3.14",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",