react-morpheus 0.1.4 → 0.1.7

package/README.md

@@ -2,56 +2,158 @@
 
 A controlled React component for morphing one UI state into another.
 
-`Morpheus` does not manage its own open state. Keep the `expanded` boolean in
-your app state and pass your trigger to `collapsedContent` so Morpheus can
-render, measure, and morph from it. Opening is the responsibility of the source
-component's own click handler.
-Overlay clicks call `onClose`; update your controlled state there. Use
-`beforeClose` and `afterClose` for work that should run around the closing
-animation.
+React Morpheus exists for interfaces where a control should become the next
+piece of UI instead of opening a detached popover. The component keeps the
+source surface, destination surface, and overlay explicit. Your app still owns
+state and content; Morpheus owns the measured transition between those two
+surfaces.
+
+## Demo
+
+<!-- react-morpheus-demo:start -->
+https://github.com/user-attachments/assets/f90e7096-f587-4793-8e80-476cf844569d
+<!-- react-morpheus-demo:end -->
+
+## Installation
+
+```sh
+bun add react-morpheus
+```
+
+```sh
+npm i react-morpheus
+```
+
+```sh
+yarn add react-morpheus
+```
+
+## Usage
+
+Import the component and stylesheet, keep the open state in your app, and pass
+both surfaces to Morpheus.
 
 ```tsx
-import { Morpheus, MorphAnchor } from "react-morpheus";
+import { useState } from "react";
+import {
+  Morpheus,
+  MorphAnchor,
+  morphSpringPresets,
+} from "react-morpheus";
 import "react-morpheus/style.css";
 
 function Example() {
   const [expanded, setExpanded] = useState(false);
   const source = (
     <button type="button" onClick={() => setExpanded(true)}>
-      Open
+      Open menu
     </button>
   );
 
   return (
     <Morpheus
-      direction="bottom"
       anchor={MorphAnchor.TopMiddle}
       expanded={expanded}
       onClose={() => setExpanded(false)}
-      beforeClose={() => console.log("closing")}
-      afterClose={() => console.log("closed")}
-      collapsedContent={source}
-      expandedContent={<div>Expanded content</div>}
+      overlayColor="#0f172a"
+      overlayOpacity={0.18}
+      overlayBlur={3}
       overlayZIndex={1200}
+      viewportPadding={16}
+      spring={morphSpringPresets.smooth}
+      collapsedContent={source}
+      expandedContent={
+        <section>
+          <h2>San Francisco</h2>
+          <p>Context, actions, and details live here.</p>
+          <button type="button" onClick={() => setExpanded(false)}>
+            Close
+          </button>
+        </section>
+      }
     />
   );
 }
 ```
 
-`overlayZIndex` controls the expanded morph 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`.
+`Morpheus` does not manage its own open state. Opening is the responsibility of
+the source component's own click handler. Overlay clicks call `onClose`; update
+your controlled state there. Use `beforeClose` and `afterClose` for work that
+should run around the closing animation.
+
+## Props
+
+| Prop | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `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. |
+| `afterClose` | `() => void` | Optional | Called after the closing animation completes. |
+| `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. |
+| `overlayZIndex` | `number` | Optional | Stacking level for the expanded surface. Defaults to `1000`; the overlay renders one layer below it. |
+| `spring` | `Transition` | Optional | Framer Motion transition. Pass your own transition or use `morphSpringPresets`. |
 
-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.
+## Pitfalls
 
-## Scripts
+### Responsiveness
 
-- `bun run build` builds declarations and bundled ESM output.
+Let the collapsed trigger keep its natural size. Morpheus reads that box before
+animating to the expanded surface.
+
+Put responsive width rules on `className`, such as viewport-bound max widths, so
+the animated shell has stable constraints on narrow screens.
+
+Pick an anchor that matches the source location. Top anchors feel right for
+menus opening below a trigger; bottom anchors feel right for surfaces opening
+upward; middle anchors feel better for centered inspectors or command surfaces.
+
+### Parent Container Overflow
+
+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 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`.
+
+## Development
+
+`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,
+anchors and overlay behavior while changing the component.
+
+### Scripts
+
+- `bun run build` builds declarations, bundled ESM output, and CSS.
 - `bun run check` runs TypeScript without emitting files.
 - `bun run publish:npm` builds and publishes to npm.
 - `bun run release:patch` bumps the patch version, builds, tags, and publishes.
 - `bun run release:minor` bumps the minor version, builds, tags, and publishes.
 - `bun run release:major` bumps the major version, builds, tags, and publishes.
+
+## Credits
+
+Inspired by Family Wallet and Benji Taylor's
+[Family Values](https://benji.org/family-values) post.
+
+## License
+
+Released under the [MIT License](https://github.com/shivekkhurana/react-morpheus/blob/master/LICENSE).

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,9 +118,11 @@ type MorphShellProps = {
     onMorphComplete: () => void;
     onMorphStart: () => void;
     children: ReactNode;
+    className?: string | undefined;
 };
 type MorphContentLayersProps = {
     expanded: boolean;
+    settledState: "collapsed" | "expanded" | null;
     collapsedContent: ReactNode;
     expandedContent: ReactNode;
     collapsedLayerSize: PanelSize;
@@ -135,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";
@@ -171,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,6 @@ var sourceContentFade = {
   duration: 0.12,
   ease: "easeOut"
 };
-var sourceReturnDelay = 0.06;
-var sourceGrowthRatio = 2;
 var instantTransition = { duration: 0 };
 var createSourceContentMotion = (spring) => ({
   opacity: sourceContentFade,
@@ -191,6 +198,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 +243,6 @@ function getLayerInteractivityProps(interactive) {
 }
 function getMorphMotionState({
   expanded,
-  direction,
   anchor,
   spring,
   animationEnabled,
@@ -241,10 +253,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,25 +265,19 @@ 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
-    },
-    sourceOpacityTransition: {
-      ...sourceContentFade,
-      delay: expanded ? 0 : sourceReturnDelay
-    },
+    sourceGrowthScale: getAxisScale(collapsedLayerSize, expandedLayerSize),
+    sourceOpacityTransition: { ...sourceContentFade },
     sourcePosition: expanded ? invertPosition(targetPanelPosition) : sourcePanelPosition,
     sourceTransition: createSourceContentMotion(activeSpring),
     targetOpacityTransition: { ...contentFade, delay: expanded ? 0.03 : 0 },
     targetPosition: expanded ? sourcePanelPosition : targetPanelPosition,
     targetTransition: createTargetContentMotion(activeSpring),
-    transformOrigin: anchorTransformOrigins[panelAnchor],
+    transformOrigin: anchorTransformOrigins[anchor],
     visualStyle
   };
 }
@@ -324,22 +329,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 +459,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 +477,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,8 +503,54 @@ 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,
   collapsedContent,
   expandedContent,
   collapsedLayerSize,
@@ -423,6 +583,7 @@ function MorphContentLayers({
           opacity: sourceOpacityTransition
         },
         style: {
+          display: expanded && settledState === "expanded" ? "none" : void 0,
           width: collapsedLayerSize.width,
           height: collapsedLayerSize.height,
           pointerEvents: expanded ? "none" : "auto",
@@ -448,6 +609,7 @@ function MorphContentLayers({
           opacity: targetOpacityTransition
         },
         style: {
+          display: !expanded && settledState === "collapsed" ? "none" : void 0,
           width: expandedLayerSize.width,
           height: expandedLayerSize.height,
           pointerEvents: expanded ? "auto" : "none",
@@ -458,8 +620,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,
@@ -468,6 +648,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,
@@ -475,10 +658,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 [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;
@@ -486,109 +710,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;
-                setShellOverflowVisible(true);
+                setPortalPhase("expanded");
                 return;
               }
-              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);
             },
-            children: /* @__PURE__ */ jsx2(
-              MorphContentLayers,
-              {
-                expanded,
-                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.4",
+  "version": "0.1.7",
   "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",