react-modal-port 0.1.0

package/dist/cjs/context.js

@@ -0,0 +1,140 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useModalState = exports.useModal = exports.useModalContext = exports.ModalContextProvider = exports.ModalContext = void 0;
+var jsx_runtime_1 = require("react/jsx-runtime");
+var react_1 = require("react");
+exports.ModalContext = (0, react_1.createContext)({
+    stack: [],
+    launchModal: function () { },
+    updateStack: function () { },
+    updateState: function () { },
+});
+var ModalContextProvider = function (_a) {
+    var children = _a.children;
+    var _b = (0, react_1.useState)([]), stack = _b[0], updateStack = _b[1];
+    var launchModal = function (render, resolvers, onBackdropClickUse) {
+        // Wrap resolvers to update the stack
+        var wrappedResovers = Object.keys(resolvers).reduce(function (acc, key) {
+            var resolver = resolvers[key];
+            acc[key] = function (ev) { return __awaiter(void 0, void 0, void 0, function () {
+                var result;
+                return __generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0: return [4 /*yield*/, resolver(ev)];
+                        case 1:
+                            result = _a.sent();
+                            updateStack(stack.slice(0, -1));
+                            return [2 /*return*/, result];
+                    }
+                });
+            }); };
+            return acc;
+        }, {});
+        updateStack(__spreadArray(__spreadArray([], stack, true), [
+            {
+                render: render,
+                resolvers: wrappedResovers,
+                onBackdropClickUse: onBackdropClickUse,
+                state: {},
+            },
+        ], false));
+    };
+    var updateState = function (newState) {
+        var updatedStack = __spreadArray([], stack, true);
+        updatedStack[stack.length - 1].state = __assign({}, newState);
+        updateStack(updatedStack);
+    };
+    var contextProperties = {
+        stack: stack,
+        launchModal: launchModal,
+        updateStack: updateStack,
+        updateState: updateState,
+    };
+    return (0, jsx_runtime_1.jsx)(exports.ModalContext.Provider, { value: contextProperties, children: children });
+};
+exports.ModalContextProvider = ModalContextProvider;
+/**
+ * Get properties from the modal context
+ * @returns {ModalContextProperties} Object with the modal context properties
+ */
+function useModalContext() {
+    return (0, react_1.useContext)(exports.ModalContext);
+}
+exports.useModalContext = useModalContext;
+/**
+ * Short-hand for `useModalContext().launchModal`
+ * @returns {LaunchModal} The launchModal function
+ */
+function useModal() {
+    var launchModal = useModalContext().launchModal;
+    return launchModal;
+}
+exports.useModal = useModal;
+/**
+ * Get access to the current modal state and a function to update it
+ * @returns {[ ModalState, UpdateModalState ]} A tuple with the current modal state and a function to update it
+ */
+function useModalState() {
+    var _a = useModalContext(), stack = _a.stack, updateState = _a.updateState;
+    if (stack.length === 0)
+        throw new Error('Trying to access modal state while no modal is open');
+    var state = stack[stack.length - 1].state;
+    return [state, updateState];
+}
+exports.useModalState = useModalState;

package/dist/cjs/index.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModalPort = exports.useModal = exports.useModalContext = exports.ModalContextProvider = void 0;
+var context_1 = require("./context");
+Object.defineProperty(exports, "ModalContextProvider", { enumerable: true, get: function () { return context_1.ModalContextProvider; } });
+Object.defineProperty(exports, "useModalContext", { enumerable: true, get: function () { return context_1.useModalContext; } });
+Object.defineProperty(exports, "useModal", { enumerable: true, get: function () { return context_1.useModal; } });
+var modal_port_1 = require("./modal-port");
+Object.defineProperty(exports, "ModalPort", { enumerable: true, get: function () { return __importDefault(modal_port_1).default; } });

package/dist/cjs/modal-port.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var jsx_runtime_1 = require("react/jsx-runtime");
+var context_1 = require("./context");
+var react_1 = require("react");
+var ModalPort = function (_a) {
+    var onModalLaunch = _a.onModalLaunch, onModalClose = _a.onModalClose, Backdrop = _a.render;
+    var stack = (0, context_1.useModalContext)().stack;
+    var currentModal = (0, react_1.useMemo)(function () { return stack.length > 0 ? stack[stack.length - 1] : null; }, [stack]);
+    var onBackdropClick = (0, react_1.useCallback)(function (ev) {
+        if (ev.currentTarget !== ev.target)
+            return;
+        (currentModal === null || currentModal === void 0 ? void 0 : currentModal.onBackdropClickUse) &&
+            currentModal.resolvers[currentModal.onBackdropClickUse](ev);
+    }, [currentModal]);
+    (0, react_1.useEffect)(function () {
+        if (currentModal) {
+            onModalLaunch && onModalLaunch();
+        }
+        else {
+            onModalClose && onModalClose();
+        }
+    }, [currentModal, onModalLaunch, onModalClose]);
+    return currentModal && ((0, jsx_runtime_1.jsx)(Backdrop, { onBackdropClick: onBackdropClick, children: currentModal.render(currentModal.resolvers) })) || null;
+};
+exports.default = ModalPort;

package/dist/esm/context.js

@@ -0,0 +1,133 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useState } from 'react';
+export var ModalContext = createContext({
+    stack: [],
+    launchModal: function () { },
+    updateStack: function () { },
+    updateState: function () { },
+});
+export var ModalContextProvider = function (_a) {
+    var children = _a.children;
+    var _b = useState([]), stack = _b[0], updateStack = _b[1];
+    var launchModal = function (render, resolvers, onBackdropClickUse) {
+        // Wrap resolvers to update the stack
+        var wrappedResovers = Object.keys(resolvers).reduce(function (acc, key) {
+            var resolver = resolvers[key];
+            acc[key] = function (ev) { return __awaiter(void 0, void 0, void 0, function () {
+                var result;
+                return __generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0: return [4 /*yield*/, resolver(ev)];
+                        case 1:
+                            result = _a.sent();
+                            updateStack(stack.slice(0, -1));
+                            return [2 /*return*/, result];
+                    }
+                });
+            }); };
+            return acc;
+        }, {});
+        updateStack(__spreadArray(__spreadArray([], stack, true), [
+            {
+                render: render,
+                resolvers: wrappedResovers,
+                onBackdropClickUse: onBackdropClickUse,
+                state: {},
+            },
+        ], false));
+    };
+    var updateState = function (newState) {
+        var updatedStack = __spreadArray([], stack, true);
+        updatedStack[stack.length - 1].state = __assign({}, newState);
+        updateStack(updatedStack);
+    };
+    var contextProperties = {
+        stack: stack,
+        launchModal: launchModal,
+        updateStack: updateStack,
+        updateState: updateState,
+    };
+    return _jsx(ModalContext.Provider, { value: contextProperties, children: children });
+};
+/**
+ * Get properties from the modal context
+ * @returns {ModalContextProperties} Object with the modal context properties
+ */
+export function useModalContext() {
+    return useContext(ModalContext);
+}
+/**
+ * Short-hand for `useModalContext().launchModal`
+ * @returns {LaunchModal} The launchModal function
+ */
+export function useModal() {
+    var launchModal = useModalContext().launchModal;
+    return launchModal;
+}
+/**
+ * Get access to the current modal state and a function to update it
+ * @returns {[ ModalState, UpdateModalState ]} A tuple with the current modal state and a function to update it
+ */
+export function useModalState() {
+    var _a = useModalContext(), stack = _a.stack, updateState = _a.updateState;
+    if (stack.length === 0)
+        throw new Error('Trying to access modal state while no modal is open');
+    var state = stack[stack.length - 1].state;
+    return [state, updateState];
+}

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { ModalContextProvider, useModalContext, useModal, } from './context';
+export { default as ModalPort } from './modal-port';

package/dist/esm/modal-port.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useModalContext } from "./context";
+import { useCallback, useEffect, useMemo } from "react";
+var ModalPort = function (_a) {
+    var onModalLaunch = _a.onModalLaunch, onModalClose = _a.onModalClose, Backdrop = _a.render;
+    var stack = useModalContext().stack;
+    var currentModal = useMemo(function () { return stack.length > 0 ? stack[stack.length - 1] : null; }, [stack]);
+    var onBackdropClick = useCallback(function (ev) {
+        if (ev.currentTarget !== ev.target)
+            return;
+        (currentModal === null || currentModal === void 0 ? void 0 : currentModal.onBackdropClickUse) &&
+            currentModal.resolvers[currentModal.onBackdropClickUse](ev);
+    }, [currentModal]);
+    useEffect(function () {
+        if (currentModal) {
+            onModalLaunch && onModalLaunch();
+        }
+        else {
+            onModalClose && onModalClose();
+        }
+    }, [currentModal, onModalLaunch, onModalClose]);
+    return currentModal && (_jsx(Backdrop, { onBackdropClick: onBackdropClick, children: currentModal.render(currentModal.resolvers) })) || null;
+};
+export default ModalPort;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "react-modal-port",
+  "version": "0.1.0",
+  "description": "Launch modals from any React component.",
+  "type": "module",
+  "types": "./types/index.d.ts",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "exports": {
+    "import": "./dist/esm/index.js",
+    "require": "./dist/cjs/index.js",
+    "types": "./types/index.d.ts"
+  },
+  "files": [
+    "dist",
+    "types"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc --outDir dist/esm --module esnext",
+    "build:cjs": "tsc --outDir dist/cjs --module commonjs",
+    "prepare": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oliverwehn/react-modal-port.git"
+  },
+  "tags": [
+    "react",
+    "modal",
+    "dialog"
+  ],
+  "keywords": [
+    "react",
+    "react-component",
+    "modal",
+    "dialog"
+  ],
+  "author": "Oliver Greuter-Wehn",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/oliverwehn/react-modal-port/issues"
+  },
+  "homepage": "https://github.com/oliverwehn/react-modal-port#readme",
+  "devDependencies": {
+    "@types/react": "^18",
+    "@types/react-dom": "^18.2.19",
+    "react": "^18.2.0",
+    "react-dom": "^18",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "@types/react": "^18",
+    "react": "^18",
+    "react-dom": "^18"
+  }
+}

package/readme.md

@@ -0,0 +1,289 @@
+# react-modal-port
+
+This small but neat package allows you to:
+* Define and style modals the way *you* want or need.
+* Launch modals flexibly from anywhere in your React app.
+* Have them render at one specific place in your DOM.
+
+## Installation
+
+```bash
+$ npm install react-modal-port
+```
+
+## 🧩 Components
+
+### ModalContextProvider
+
+The `ModalContextProvider` wraps your app to allow your app’s components to launch or render modals.
+
+### ModalPort
+
+The `ModalPort` handles the rendering of your modals. It leaves the *how* you want to render your modals fully up to you. It simply requires a `React.FunctionComponent` to be passed to it via its `render` prop. This component allows you to wrap any rendered modal in, for example, a backdrop component.
+
+Besides `children` a prop `onBackdropClick` is passed to `render`. It holds, if provided to the modal on launch, the click handler function that should be called if the backdrop is clicked, e.g. to dismiss the modal.
+
+
+```tsx
+import React from 'react';
+import { ModalContextProvider } from 'react-modal-port';
+
+// Backdrop component to be passed to the `ModalPort`’s `render` prop
+const Backdrop: React.FC<ModalPortRenderProps> = ({ children, onBackdropClick }) => (
+  <div
+    style="
+      position: fixed;
+      z-index: 1000,
+      display: flex;
+      justify-content: center;
+      align-items-center;
+      background-color: rgba(0,0,0,.65);
+      top: 0;
+      right: 0;
+      bottom: 0;
+      left: 0;
+    "
+    onClick={onBackdropClick}
+  >
+    {children}
+  </div>
+);
+
+// Your app’s root layout component
+const RootLayout:React.FC<PropsWithChildren> = ({ children }) => (
+  <ModalContextProvider>
+    <div style="width: 100%; min-height: 100vh;">
+      {children}
+      <ModalPort render={Backdrop} />
+    </div>
+  </ModalContextProvider>
+);
+
+export default RootLayout;
+```
+
+## 🚀 Launching Modals
+
+Launching modals makes use of the `useModal` hook that provides you with the `launchModal` function.
+
+```tsx
+import React from 'react';
+import { useModal } from 'react-modal-port';
+import DecisionModal from './modals/decision';
+
+const Page: React.FC = () => {
+
+  const launchModal = useModal();
+  const [ decision, setDecision ] = useState<boolean|null>(null);
+
+  const onClick = () => {
+    launchModal(
+      // Modal component
+      DecisionModal, 
+      // Modal resolvers
+      {
+        decideYay: () => setDecision(true),
+        decideNay: () => setDecision(false),
+        leaveMeAlone: () => {},
+      },
+      // Optional name of the `onBackdropClick` resolver
+      "leaveMeAlone"
+    );
+  }
+
+  return (
+    <div style="padding: 4rem;">
+      <h1>Welcome</h1>
+      {decision === null && (
+      <p>Make your decision!</p>
+      ) || (
+      <p>Your decision is: {decision && "Yay" || "Nay"}</p>
+      )}
+      
+      <div style="display: flex; flex-direction: row; gap: 0.5rem;">
+        <button type="button" onClick={onClick}>Let me decide now</button>
+      </div>
+    </div>
+  );
+}
+
+```
+The `launchModal` function expects the following arguments:
+| Argument | Type | Description |
+|----------|------|-------------|
+| render | `React.FC` | A function that renders the modal and returns a `ReactNode`. |
+| resolvers | `{ [key: string]: (ev?: SyntheticEvent) => Promise<any>\|void }` | An object of resolver functions that will be passed as props to `render`. |
+| onBackdropClickUse | `string` | Optional: The key of the resolver function in the `resolvers` object that should be passed to the backdrop component’s `onBackdropClick` prop. |
+
+Modals can be created and designed to fully fit your needs. The only requirement is to define the functions to resolve them, for example, when clicking a button. The modal component for the example above could look like this:
+
+```tsx
+import React from 'react';
+
+type DecisionModalProps = {
+  decideYay: () => void;
+  decideNay: () => void;
+  leaveMeAlone?: () => void;
+};
+
+const DecisionModal: React.FC<DecisionModalProps> = ({
+  decideYay,
+  decideNay,
+}) => (
+  <div
+    style="background-color: white; border-radius: 0.5rem; padding: 1rem; display: flex; flex-direction: column; align-items: center; gap: 0.5rem;"
+    role="dialog"
+    aria-modal="true"
+    aria-labeledby="modal-title"
+    aria-describedby="modal-description"
+  >
+    <h4 id="modal-title">How do you decide?</h4>
+    <div id ="modal-description">
+      <p>Make your decision and click one of the buttons below.</p>
+    </div>
+    <div style="display: flex; flex-direction: row; gap: 0.25rem; justify-content: center;">
+      <button type="button" onClick={decideYay}>Yay</button>
+      <button type="button" onClick={decideNay}>Nay</button>
+    </div>
+  </div>
+)
+
+export default DecisionModal;
+```
+
+## 🔂 Asynchronous Resolution
+
+Modals can be simple like the one above or highly complex like a full wizard experience or questionnaire. It is also possible to trigger asynchronous operations within a resolver function. As long as the resolver function returns a promise, the modal won’t close until the promise is resolved.
+
+So you could adapt the `onClick` handler in our earlier example as follows:
+```tsx
+  // ...
+
+  const onClick = () => {
+    launchModal(
+      // Modal component
+      DecisionModal, 
+      // Modal resolvers
+      {
+        decideYay: () => setDecision(true),
+        decideNay: () => setDecision(false),
+        letMeThinkAboutIt: (p: Promise) => p,
+        leaveMeAlone: () => {},
+      },
+      // Optional name of the `onBackdropClick` resolver
+      "leaveMeAlone"
+    );
+  }
+
+  // ...
+```
+
+It then could cater the following modal functionality:
+
+
+```tsx
+import React from 'react';
+
+type DecisionModalProps = {
+  decideYay: () => void;
+  decideNay: () => void;
+  letMeThinkAboutIt: (p: Promise) => Promise;
+  leaveMeAlone?: () => void;
+};
+
+const DecisionModal: React.FC<DecisionModalProps> = ({
+  decideYay,
+  decideNay,
+  letMeThinkAboutIt,
+}) => {
+
+  const imUndecided = () => {
+    const p = new Promise((resolve) => {
+      const options = [ decideYay, decideNay ];
+      setTimeout(
+        () => resolve(options[Math.round(Math.random())]),
+        Math.random() * 60000
+      );
+    });
+    letMeThinkAboutIt(p);
+  };
+
+  return (
+    <div
+      style="background-color: white; border-radius: 0.5rem; padding: 1rem; display: flex; flex-direction: column; align-items: center; gap: 0.5rem;"
+      role="dialog"
+      aria-modal="true"
+      aria-labeledby="modal-title"
+      aria-describedby="modal-description"
+    >
+      <h4 id="modal-title">How do you decide?</h4>
+      <div id ="modal-description">
+        <p>Make your decision and click one of the buttons below.</p>
+      </div>
+      <div style="display: flex; flex-direction: row; gap: 0.25rem; justify-content: center;">
+        <button type="button" onClick={decideYay}>Yay</button>
+        <button type="button" onClick={decideNay}>Nay</button>
+        <button type="button" onClick={imUndecided}>Let me think</button>
+      </div>
+    </div>
+  );
+}
+
+export default DecisionModal;
+```
+
+## 🥞 Stacking Modals And Handling Modal State
+
+If you need to launch a modal from a modal, the modals become (logically) stacked. That means that the `ModalPort` will always render the modal at the top of the modal stack and will return to the previous one as soon as the current one is resolved. Via the resolver functions, data can be passed from the resolving modal to the modal it was launched from.
+
+In case you need to handle state within multiple stacked modal, you can create, access, and update the modal state using the `useModalState` hook. It returns a tuple with the current modal state and a function to update the state. The modal state is always an object holding key-value pairs. Each modal’s modal state will persist until the modal itself is resolved.
+
+In the example below, we’ll ask the user to enter their name and prompt them in a second modal to confirm. We’ll fall back to the first modal with the name previously entered if the user wishes to edit it once more.
+
+```tsx
+import React from "react"; 
+import ConfirmModal from "./ConfirmModal";
+
+type AskForNameModalProps = {
+  provideName: ModalResolver,
+};
+
+export const AskForNameModal: React.FC<AskForNameModalProps> = ({
+  provideName,
+}) => {
+
+  const launchModal = useModal();
+  const [ modalState, updateModalState ] = useModalState();
+  const onNameChange = (ev) => {
+    updateModalState({
+      ...modalState,
+      name: ev.target.value,
+    });
+  };
+
+  const onButtonClick = () => {
+    launchModal(ConfirmModal, {
+      confirm: () => provideName(modalState.name),
+     });
+  };
+
+  return (
+    <div 
+      style="background-color: white; border-radius: 0.5rem; padding: 1rem; display: flex; flex-direction: column; align-items: center; gap: 0.5rem;"
+      role="dialog"
+      aria-modal="true"
+      aria-labeledby="modal-title"
+      aria-describedby="modal-description"
+    >
+      <h4 id="modal-title">How should we call you?</h4>
+      <div id="modal-description">
+        <p>Please enter your firstname or nickname of choice.</p>
+      </div>
+      <input type="text" value={modalState.name} onChange={onNameChange} style="width: 100%">
+      <button type="button" onClick={onButtonClick}>Set name</button>
+    </div>
+  );
+
+}
+
+```

package/types/index.d.ts

@@ -0,0 +1,51 @@
+/// <reference types="react" />
+
+export type ModalResolver = (...args: any[]) => Promise<void>|void;
+
+
+export type LaunchModalResolvers = {
+  [key: string]: ModalResolver;
+};
+
+export type ModalStackItem = {
+  render: React.FunctionComponent<LaunchModalResolvers>;
+  resolvers: LaunchModalResolvers;
+  onBackdropClickUse?: string;
+  state: ModalState;
+};
+
+export type LaunchModal = (
+  render: React.FunctionComponent<LaunchModalResolvers>, 
+  resolvers: LaunchModalResolvers,
+  onBackdropClickUse?: string,
+) => void;
+
+export type ModalState = { [key: string]: any };
+export type UpdateModalState = (newState: ModalState) => void;
+
+export type ModalContextProperties = {
+  stack: ModalStackItem[];
+  launchModal: LaunchModal;
+  updateStack: (newStack: ModalStackItem[]) => void;
+  updateState: (newState: ModalState) => void;
+};
+
+export type ModalPortRenderProps = React.PropsWithChildren & {
+  onBackdropClick?: (ev: React.SyntheticEvent) => void;
+};
+
+export type ModalPortProps = {
+  onModalLaunch?: () => void | null;
+  onModalClose?: () => void | null;
+  render: React.FC<ModalPortRenderProps>;
+};
+
+declare module 'react-modal-port' {
+
+  const ModalContextProvider: React.FC<PropsWithChildren>;
+  const useModalContext: () => ModalContextProperties;
+  const useModal: () => ModalContextProperties['launchModal'];
+  const ModalPort: React.FC<ModalPortProps>;
+
+}
+