react-flow-modal 0.2.0 → 0.4.0

package/README.md

@@ -0,0 +1,261 @@
+# react-flow-modal
+
+Promise-based modal flows for React.
+
+`react-flow-modal` lets you treat modals as async flows using
+`Promise` and `async/await`, without coupling your UI to state-driven logic.
+
+---
+
+## Installation
+
+```bash
+pnpm add react-flow-modal
+# or
+npm install react-flow-modal
+# or
+yarn add react-flow-modal
+```
+
+---
+
+## Basic Usage
+
+```tsx
+import { ModalProvider, useModal, renderModals } from "react-flow-modal";
+
+function ConfirmModal({
+  onConfirm,
+  onCancel,
+}: {
+  onConfirm: () => void;
+  onCancel: () => void;
+}) {
+  return (
+    <div
+      style={{
+        position: "fixed",
+        inset: 0,
+        background: "rgba(0,0,0,0.5)",
+        display: "grid",
+        placeItems: "center",
+        zIndex: 1000,
+      }}
+    >
+      <div
+        style={{
+          background: "white",
+          padding: 24,
+          borderRadius: 8,
+          minWidth: 300,
+        }}
+      >
+        <h3>Are you sure?</h3>
+        <p>This action cannot be undone.</p>
+
+        <div style={{ display: "flex", gap: 8, marginTop: 16 }}>
+          <button onClick={onCancel}>Cancel</button>
+          <button onClick={onConfirm}>Confirm</button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function App() {
+  const modal = useModal();
+
+  const onClick = async () => {
+    const result = await modal.open("confirm", (resolve) => (
+      <ConfirmModal
+        onConfirm={() => resolve(true)}
+        onCancel={() => resolve(false)}
+      />
+    ));
+
+    console.log("Result:", result);
+  };
+
+  return <button onClick={onClick}>Open Confirm Modal</button>;
+}
+
+function ModalRenderer() {
+  return renderModals();
+}
+
+export default function Root() {
+  return (
+    <ModalProvider>
+      <App />
+      <ModalRenderer />
+    </ModalProvider>
+  );
+}
+```
+
+---
+
+## With AnimatePresence (Framer Motion)
+
+To support exit animations, modals must be rendered inside the same
+React tree as `AnimatePresence`.
+
+```tsx
+import { ModalProvider, useModal, renderModals } from "react-flow-modal";
+import { motion, AnimatePresence } from "motion/react";
+
+function ConfirmModal({
+  onConfirm,
+  onCancel,
+}: {
+  onConfirm: () => void;
+  onCancel: () => void;
+}) {
+  return (
+    <motion.div
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      exit={{ opacity: 0 }}
+      style={{
+        position: "fixed",
+        inset: 0,
+        background: "rgba(0,0,0,0.5)",
+        display: "grid",
+        placeItems: "center",
+        zIndex: 1000,
+      }}
+    >
+      <motion.div
+        initial={{ scale: 0.9, opacity: 0 }}
+        animate={{ scale: 1, opacity: 1 }}
+        exit={{ scale: 0.95, opacity: 0 }}
+        transition={{ duration: 0.2 }}
+        style={{
+          background: "white",
+          padding: 24,
+          borderRadius: 8,
+          minWidth: 300,
+        }}
+      >
+        <h3>Are you sure?</h3>
+        <p>This action cannot be undone.</p>
+
+        <div style={{ display: "flex", gap: 8, marginTop: 16 }}>
+          <button onClick={onCancel}>Cancel</button>
+          <button onClick={onConfirm}>Confirm</button>
+        </div>
+      </motion.div>
+    </motion.div>
+  );
+}
+
+function App() {
+  const modal = useModal();
+
+  const onClick = async () => {
+    const result = await modal.open("confirm", (resolve) => (
+      <ConfirmModal
+        onConfirm={() => resolve(true)}
+        onCancel={() => resolve(false)}
+      />
+    ));
+
+    console.log("Result:", result);
+  };
+
+  return <button onClick={onClick}>Open Confirm Modal</button>;
+}
+
+function ModalRenderer() {
+  return (
+    <AnimatePresence>
+      {renderModals()}
+    </AnimatePresence>
+  );
+}
+
+export default function Root() {
+  return (
+    <ModalProvider>
+      <App />
+      <ModalRenderer />
+    </ModalProvider>
+  );
+}
+```
+
+---
+
+## API
+
+### useModal
+
+```ts
+const modal = useModal();
+```
+
+Returns an object that controls the modal flow.
+
+```ts
+{
+  open<T>(
+    key: string,
+    render: (
+      resolve: (value: T) => void,
+      reject: (reason?: unknown) => void
+    ) => React.ReactNode
+  ): Promise<T>;
+}
+```
+
+### renderModals
+```ts
+renderModals(): React.ReactNode
+```
+Renders the entire modal stack. This function should be rendered **once** in your React tree.
+
+---
+
+## Important
+
+> ⚠️ Always resolve or reject the promise.
+> Leaving it pending will block the async flow.
+
+> ⚠️ `renderModals()` should be rendered once.
+> Rendering it multiple times may result in duplicated modals.
+
+---
+
+## Why react-flow-modal?
+
+Most modal libraries are state-driven:
+
+```tsx
+setOpen(true);
+```
+
+This makes modal control implicit and tightly coupled to rendering.
+
+`react-flow-modal` treats modals as explicit async control points:
+
+```tsx
+const result = await open(...);
+```
+
+This keeps control flow readable, composable, and testable.
+
+---
+
+## Features
+
+* Headless API (no styles, no UI constraints)
+* Promise-based modal control
+* Internal stack management
+* Render location fully controlled by the user
+* Works naturally with async / await
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   ModalHost: () => ModalHost,
   ModalProvider: () => ModalProvider,
+  renderModals: () => renderModals,
   useModal: () => useModal
 });
 module.exports = __toCommonJS(index_exports);
@@ -43,9 +44,6 @@ var ModalProvider = ({ children }) => {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ModalContext.Provider, { value: { stack, setStack }, children });
 };
 
-// src/ModalHost.tsx
-var import_react4 = require("react");
-
 // src/useModalContext.ts
 var import_react3 = require("react");
 var useModalContext = () => {
@@ -55,17 +53,12 @@ var useModalContext = () => {
   }
   return context;
 };
-
-// src/ModalHost.tsx
-var import_jsx_runtime2 = require("react/jsx-runtime");
-var ModalHost = () => {
+var renderModals = () => {
   const { stack } = useModalContext();
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_react4.Fragment, { children: stack.map((item) => item) });
+  return stack.map((item) => item);
 };
 
 // src/useModal.tsx
-var import_react5 = require("react");
-var import_jsx_runtime3 = require("react/jsx-runtime");
 var useModal = () => {
   const { setStack } = useModalContext();
   const pop = () => {
@@ -83,14 +76,23 @@ var useModal = () => {
         reject(reason);
         pop();
       });
-      push(/* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react5.Fragment, { children: element }, key));
+      push(element);
     });
   };
   return { open };
 };
+
+// src/ModalHost.tsx
+var import_react4 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var ModalHost = () => {
+  const { stack } = useModalContext();
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_react4.Fragment, { children: stack.map((item) => item) });
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ModalHost,
   ModalProvider,
+  renderModals,
   useModal
 });

package/dist/index.d.cts

@@ -1,11 +1,15 @@
-import React, { FC, PropsWithChildren } from 'react';
+import * as react from 'react';
+import react__default, { FC, PropsWithChildren } from 'react';
 
 declare const ModalProvider: FC<PropsWithChildren>;
 
-declare const ModalHost: FC;
-
 declare const useModal: () => {
-    open: <T>(key: string, render: (resolve: (value: T) => void, reject: (reason?: unknown) => void) => React.ReactNode) => Promise<T>;
+    open: <T>(key: string, render: (resolve: (value: T) => void, reject: (reason?: unknown) => void) => react__default.ReactNode) => Promise<T>;
 };
 
-export { ModalHost, ModalProvider, useModal };
+/** @deprecated use renderModals instead */
+declare const ModalHost: FC;
+
+declare const renderModals: () => react.ReactNode[];
+
+export { ModalHost, ModalProvider, renderModals, useModal };

package/dist/index.d.ts

@@ -1,11 +1,15 @@
-import React, { FC, PropsWithChildren } from 'react';
+import * as react from 'react';
+import react__default, { FC, PropsWithChildren } from 'react';
 
 declare const ModalProvider: FC<PropsWithChildren>;
 
-declare const ModalHost: FC;
-
 declare const useModal: () => {
-    open: <T>(key: string, render: (resolve: (value: T) => void, reject: (reason?: unknown) => void) => React.ReactNode) => Promise<T>;
+    open: <T>(key: string, render: (resolve: (value: T) => void, reject: (reason?: unknown) => void) => react__default.ReactNode) => Promise<T>;
 };
 
-export { ModalHost, ModalProvider, useModal };
+/** @deprecated use renderModals instead */
+declare const ModalHost: FC;
+
+declare const renderModals: () => react.ReactNode[];
+
+export { ModalHost, ModalProvider, renderModals, useModal };

package/dist/index.js

@@ -15,9 +15,6 @@ var ModalProvider = ({ children }) => {
   return /* @__PURE__ */ jsx(ModalContext.Provider, { value: { stack, setStack }, children });
 };
 
-// src/ModalHost.tsx
-import { Fragment } from "react";
-
 // src/useModalContext.ts
 import { useContext } from "react";
 var useModalContext = () => {
@@ -27,17 +24,12 @@ var useModalContext = () => {
   }
   return context;
 };
-
-// src/ModalHost.tsx
-import { jsx as jsx2 } from "react/jsx-runtime";
-var ModalHost = () => {
+var renderModals = () => {
   const { stack } = useModalContext();
-  return /* @__PURE__ */ jsx2(Fragment, { children: stack.map((item) => item) });
+  return stack.map((item) => item);
 };
 
 // src/useModal.tsx
-import { Fragment as Fragment2 } from "react";
-import { jsx as jsx3 } from "react/jsx-runtime";
 var useModal = () => {
   const { setStack } = useModalContext();
   const pop = () => {
@@ -55,13 +47,22 @@ var useModal = () => {
         reject(reason);
         pop();
       });
-      push(/* @__PURE__ */ jsx3(Fragment2, { children: element }, key));
+      push(element);
     });
   };
   return { open };
 };
+
+// src/ModalHost.tsx
+import { Fragment } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var ModalHost = () => {
+  const { stack } = useModalContext();
+  return /* @__PURE__ */ jsx2(Fragment, { children: stack.map((item) => item) });
+};
 export {
   ModalHost,
   ModalProvider,
+  renderModals,
   useModal
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-flow-modal",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Promise-based modal flows for React",
   "repository": {
     "type": "git",

package/src/ModalHost.tsx

@@ -1,6 +1,7 @@
 import React, { FC, Fragment } from 'react';
 import { useModalContext } from './useModalContext';
 
+/** @deprecated use renderModals instead */
 export const ModalHost: FC = () => {
     const { stack } = useModalContext();
 

package/src/index.ts

@@ -1,3 +1,4 @@
 export { ModalProvider } from './ModalProvider';
+export { useModal } from './useModal';
 export { ModalHost } from './ModalHost';
-export { useModal } from './useModal';
+export { renderModals } from './useModalContext';

package/src/useModal.tsx

@@ -29,7 +29,7 @@ export const useModal = () => {
                 reject(reason);
                 pop();
             });
-            push(<Fragment key={key}>{element}</Fragment>);
+            push(element);
         });
     };
 

package/src/useModalContext.ts

@@ -9,4 +9,10 @@ export const useModalContext = () => {
     }
 
     return context;
+};
+
+export const renderModals = () => {
+    const { stack } = useModalContext();
+
+    return stack.map((item) => (item));
 };