react-morpheus 0.1.9 → 0.1.11

package/README.md

@@ -1,5 +1,7 @@
 # React Morpheus
 
+[![npm version](https://img.shields.io/npm/v/react-morpheus.svg)](https://www.npmjs.com/package/react-morpheus)
+
 A controlled React component for morphing one UI state into another.
 
 React Morpheus exists for interfaces where a control should become the next
@@ -17,17 +19,21 @@ https://github.com/user-attachments/assets/f90e7096-f587-4793-8e80-476cf844569d
 ## Installation
 
 ```sh
-bun add react-morpheus
+bun add react-morpheus cuelume
 ```
 
 ```sh
-npm i react-morpheus
+npm i react-morpheus cuelume
 ```
 
 ```sh
-yarn add react-morpheus
+yarn add react-morpheus cuelume
 ```
 
+[Cuelume](https://github.com/Danilaa1/cuelume) is a required peer dependency;
+sound playback remains opt-in. It synthesizes cues with the Web Audio API, so
+React Morpheus does not bundle audio files.
+
 ## Usage
 
 Import the component and stylesheet, keep the open state in your app, and pass
@@ -55,6 +61,8 @@ function Example() {
       anchor={MorphAnchor.TopMiddle}
       expanded={expanded}
       onClose={() => setExpanded(false)}
+      openSound="bloom"
+      closeSound="droplet"
       overlayColor="#0f172a"
       overlayOpacity={0.18}
       overlayBlur={3}
@@ -81,6 +89,31 @@ 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.
 
+## Sounds
+
+Use `openSound` and `closeSound` to add Cuelume cues to the controlled state
+transition. React Morpheus calls Cuelume directly; you do not need to call
+`bind()` or `play()` yourself.
+
+```tsx
+<Morpheus
+  expanded={expanded}
+  openSound="bloom"
+  closeSound="droplet"
+  // ...the remaining props
+/>
+```
+
+Each configured cue plays once when `expanded` changes. The initial render is
+silent, including when `expanded` is initially `true`. Omit either prop to keep
+that direction silent.
+
+Both props accept Cuelume's `SoundName` values:
+
+`arrival`, `bloom`, `chime`, `droplet`, `error`, `loading`, `page`, `press`,
+`pulse`, `ready`, `release`, `scan`, `sparkle`, `success`, `tick`, `toggle`, and
+`whisper`.
+
 ## Props
 
 | Prop | Type | Required | Notes |
@@ -90,6 +123,8 @@ should run around the closing animation.
 | `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. |
+| `openSound` | `SoundName` | Optional | Cuelume sound played once when `expanded` changes to `true`. |
+| `closeSound` | `SoundName` | Optional | Cuelume sound played once when `expanded` changes to `false`. |
 | `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. |

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
 import { ReactNode, RefObject } from 'react';
+import { SoundName } from 'cuelume';
 import { Transition } from 'framer-motion';
 
 declare enum MorphAnchor {
@@ -81,6 +82,8 @@ type MorphProps = {
     onClose?: (() => void) | undefined;
     beforeClose?: (() => void) | undefined;
     afterClose?: (() => void) | undefined;
+    openSound?: SoundName | undefined;
+    closeSound?: SoundName | undefined;
     collapsedContent: ReactNode;
     expandedContent: ReactNode;
     className?: string;

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/component.tsx
+import { play } from "cuelume";
 import { motion as motion2 } from "framer-motion";
 import {
   createContext,
@@ -652,6 +653,8 @@ function MorpheusRoot({
   onClose,
   beforeClose,
   afterClose,
+  openSound,
+  closeSound,
   collapsedContent,
   expandedContent,
   className = "rmorph:relative rmorph:inline-block rmorph:align-top",
@@ -682,6 +685,9 @@ function MorpheusRoot({
   const beforeCloseRef = useRef2(beforeClose);
   const afterCloseRef = useRef2(afterClose);
   const previousExpandedRef = useRef2(expanded);
+  const previousSoundExpandedRef = useRef2(expanded);
+  const openSoundRef = useRef2(openSound);
+  const closeSoundRef = useRef2(closeSound);
   const portalStartFrameRef = useRef2(null);
   const handoffFirstFrameRef = useRef2(null);
   const handoffSecondFrameRef = useRef2(null);
@@ -691,6 +697,18 @@ function MorpheusRoot({
   expandedRef.current = expanded;
   beforeCloseRef.current = beforeClose;
   afterCloseRef.current = afterClose;
+  openSoundRef.current = openSound;
+  closeSoundRef.current = closeSound;
+  useEffect(() => {
+    if (previousSoundExpandedRef.current === expanded) {
+      return;
+    }
+    previousSoundExpandedRef.current = expanded;
+    const sound = expanded ? openSoundRef.current : closeSoundRef.current;
+    if (sound) {
+      play(sound);
+    }
+  }, [expanded]);
   const cancelPortalFrames = useCallback(() => {
     if (portalStartFrameRef.current !== null) {
       cancelAnimationFrame(portalStartFrameRef.current);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-morpheus",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "A controlled React component for morphing one UI surface into another.",
   "keywords": [
     "react",
@@ -38,7 +38,7 @@
   "scripts": {
     "prepare": "bun run build",
     "build": "bun run build:js && bun run build:css",
-    "build:js": "tsup src/index.ts --format esm --dts --external react --external react-dom --external framer-motion --clean",
+    "build:js": "tsup src/index.ts --format esm --dts --external react --external react-dom --external framer-motion --external cuelume --clean",
     "build:css": "tailwindcss -i src/style.css -o dist/style.css --minify",
     "check": "tsc --noEmit",
     "test": "bun test",
@@ -48,6 +48,7 @@
     "release:patch": "bun run scripts/release.ts patch"
   },
   "peerDependencies": {
+    "cuelume": "^0.2.2",
     "framer-motion": "^12.42.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"