react-morpheus 0.1.4 → 0.1.5

package/README.md

@@ -2,23 +2,51 @@
 
 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>
   );
 
@@ -28,30 +56,97 @@ function Example() {
       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}
+      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 |
+| --- | --- | --- | --- |
+| `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. |
+| `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. |
+| `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`. |
+
+## Pitfalls
+
+### Responsiveness
+
+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
 
 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.
 
-## Scripts
+### Stacking
+
+`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`.
 
-- `bun run build` builds declarations and bundled ESM output.
+## 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,
+directions, 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

@@ -117,6 +117,7 @@ type MorphShellProps = {
 };
 type MorphContentLayersProps = {
     expanded: boolean;
+    settledState: "collapsed" | "expanded" | null;
     collapsedContent: ReactNode;
     expandedContent: ReactNode;
     collapsedLayerSize: PanelSize;

package/dist/index.js

@@ -391,6 +391,7 @@ function MorphShell({
 }
 function MorphContentLayers({
   expanded,
+  settledState,
   collapsedContent,
   expandedContent,
   collapsedLayerSize,
@@ -423,6 +424,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 +450,7 @@ function MorphContentLayers({
           opacity: targetOpacityTransition
         },
         style: {
+          display: !expanded && settledState === "collapsed" ? "none" : void 0,
           width: expandedLayerSize.width,
           height: expandedLayerSize.height,
           pointerEvents: expanded ? "auto" : "none",
@@ -477,6 +480,9 @@ function Morpheus({
   const measurements = useMorphMeasurements();
   const [animationEnabled, setAnimationEnabled] = useState2(false);
   const [shellOverflowVisible, setShellOverflowVisible] = useState2(false);
+  const [settledState, setSettledState] = useState2(
+    expanded ? "expanded" : "collapsed"
+  );
   const hasOpenedRef = useRef2(expanded);
   const beforeCloseCalledRef = useRef2(false);
   useEffect(() => {
@@ -545,9 +551,11 @@ function Morpheus({
               if (expanded) {
                 hasOpenedRef.current = true;
                 beforeCloseCalledRef.current = false;
+                setSettledState("expanded");
                 setShellOverflowVisible(true);
                 return;
               }
+              setSettledState("collapsed");
               if (hasOpenedRef.current) {
                 hasOpenedRef.current = false;
                 afterClose?.();
@@ -559,11 +567,13 @@ function Morpheus({
                 beforeClose?.();
               }
               setShellOverflowVisible(false);
+              setSettledState(expanded ? "collapsed" : "expanded");
             },
             children: /* @__PURE__ */ jsx2(
               MorphContentLayers,
               {
                 expanded,
+                settledState,
                 collapsedContent,
                 expandedContent,
                 collapsedLayerSize: motionState.collapsedLayerSize,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-morpheus",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "A React component for morphing one surface into other.",
   "type": "module",
   "license": "MIT",