react-modal-port 0.2.6 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## 1.0.0
+
+A full rework for correctness, type safety and packaging. See [MIGRATION.md](./MIGRATION.md) for upgrade steps.
+
+### Breaking changes
+
+- `launchModal` checks resolvers and props against the modal component's props. Explicit type arguments are no longer supported.
+- `onBackdropClick` moved from `resolvers` to `options.onDismiss`. The resolver form still works at runtime, with a deprecation warning.
+- `updateStack` was removed from the context. `stack` is now read-only.
+- `useModalState()` used inside a modal is scoped to that modal.
+- The UMD build and the `types/` folder were removed. Types now ship in `dist/` as `.d.ts` and `.d.cts`.
+
+### Fixes
+
+- A resolver closes its own modal instead of the top of the stack, so async resolvers no longer close modals that were stacked on top of them.
+- A modal resolves only once, even when resolvers are called repeatedly.
+- A resolver that throws or rejects leaves its modal open and can be retried. Previously the rejection went unhandled.
+- Stacked instances of the same component no longer share component state.
+- `useModal()` consumers no longer re-render on every stack or modal-state change.
+- TypeScript users who `require()` the package under `node16`/`nodenext` resolution get correct CommonJS types.
+
+### Features
+
+- `launchModal` returns a handle `{ id, close() }`.
+- `useModalStack()` gives a read-only view of the stack.
+- `useModalState` accepts updater functions.
+- `ModalPort` gained `container` (render through a portal) and `onStackChange`. The backdrop receives `modalId` and `stackSize`, and gets `onBackdropClick` only when the modal is dismissible.
+- `ModalProvider` and `ModalPort backdrop` are the new names; `ModalContextProvider` and `render` remain as aliases.
+- The bundles are marked `"use client"` for React Server Components.
+
+### Compatibility
+
+- Tested against React 19.0.0, the latest patch of 19.0, 19.1, 19.2 and 19.3, and the React canary. CI runs this matrix.
+
+### Tooling
+
+- Build with tsup (ESM + CJS). Tests run on Vitest with type tests, StrictMode and render-count checks, 100% coverage, and a packed-tarball smoke test. Lint, publint, arethetypeswrong and CI were added.
+
+## 0.3.0
+
+- Require React 19.
+
+## 0.2.x and earlier
+
+- Generic modal props, context improvements and initial releases.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Oliver Greuter-Wehn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,74 @@
+# Migrating from 0.x to 1.0
+
+1.0 fixes several stacking bugs, makes `launchModal` type-safe and modernises the package. Most apps need only a few mechanical changes. Deprecated names keep working throughout 1.x (with a development-only console warning where noted) and will be removed in 2.0.
+
+## Required changes
+
+### `launchModal` types are now checked
+
+Resolvers and props are checked against the modal component's props. Code that compiled before may now report real mistakes: misspelled resolver names, missing required props, or wrongly typed props. Fix the call site, or type the modal's props.
+
+Explicit type arguments are no longer needed or supported:
+
+```diff
+- launchModal<DecisionModalProps>(DecisionModal, resolvers, props);
++ launchModal(DecisionModal, resolvers, props);
+```
+
+Modals typed loosely (for example `React.FC<ModalProps>` or `FC<Record<string, any>>`) still accept anything, as before.
+
+### `onBackdropClick` moved from resolvers to options
+
+```diff
+- launchModal(Modal, { onClose, onBackdropClick: () => {} }, props);
++ launchModal(Modal, { onClose }, props, { onDismiss: () => {} });
+```
+
+The old form still works at runtime and logs a deprecation warning, but no longer type-checks. The modal component no longer receives `onBackdropClick` as a prop.
+
+The backdrop now receives `onBackdropClick` only when the modal is dismissible; otherwise it is `undefined`.
+
+### `updateStack` was removed
+
+`useModalContext()` no longer exposes `updateStack`, and `stack` is read-only. To close a modal programmatically, use the handle returned by `launchModal`:
+
+```ts
+const { close } = launchModal(Modal, resolvers, props);
+close();
+```
+
+To inspect the stack, use `useModalStack()`.
+
+### `useModalState` is scoped to its modal
+
+Inside a modal, `useModalState()` now reads and writes **that modal's** state, even while another modal is stacked on top. Previously it always targeted the top modal. Outside any modal it still targets the top one.
+
+The setter also accepts an updater function. Prefer it over spreading a captured state object:
+
+```diff
+- updateModalState({ ...modalState, name: value });
++ updateModalState((prev) => ({ ...prev, name: value }));
+```
+
+### Package layout
+
+- The UMD build (`dist/index.umd.js`) was removed; React 19 ships no UMD builds either. Use an ES module CDN such as esm.sh.
+- Type declarations moved from `types/` to `dist/`. Deep imports of `react-modal-port/types/...` will break; import types from `react-modal-port`.
+- Node ≥ 18 is required for tooling that resolves the package.
+
+## Behaviour changes you get for free
+
+- A resolver closes **its own** modal, even if other modals were stacked on top while it was running. Previously it closed whatever modal was on top.
+- Calling resolvers more than once (double-clicks, two buttons) closes the modal once.
+- A resolver that throws or rejects keeps its modal open and can be called again.
+- Stacking the same component on itself mounts a fresh instance instead of reusing the previous one's component state.
+- Components that only call `useModal()` no longer re-render when modals open, close or update their state.
+
+## Renamed (old names still work)
+
+| 0.x | 1.0 |
+| --- | --- |
+| `ModalContextProvider` | `ModalProvider` |
+| `<ModalPort render={...}>` | `<ModalPort backdrop={...}>` |
+| `useModalContext()` | `useModal()`, `useModalStack()`, `useModalState()` |
+| `ModalProps`, `ModalResolver`, `LaunchModalResolvers`, `LaunchModalProps` | Your modal's own prop types |

package/dist/index.cjs

@@ -1,2 +1,220 @@
-var e=require("react/jsx-runtime"),r=require("react");function n(){return n=Object.assign?Object.assign.bind():function(e){for(var r=1;r<arguments.length;r++){var n=arguments[r];for(var t in n)({}).hasOwnProperty.call(n,t)&&(e[t]=n[t])}return e},n.apply(null,arguments)}var t=r.createContext(null);function o(){var e=r.useContext(t);if(!e)throw new Error("useModalContext must be used within a ModalContextProvider");return e}exports.ModalContextProvider=function(o){var u=o.children,a=r.useState([]),l=a[0],c=a[1],s=r.useCallback(function(e,r,n){void 0===n&&(n={});var t=Object.keys(r).reduce(function(e,n){var t=r[n];return e[n]=function(){try{return Promise.resolve(t.apply(void 0,[].slice.call(arguments))).then(function(e){return c(function(e){return e.slice(0,-1)}),e})}catch(e){return Promise.reject(e)}},e},{});c(function(r){return[].concat(r,[{render:e,resolvers:t,props:n,state:{}}])})},[]),i=r.useCallback(function(e){c(function(r){var t=[].concat(r);return t.length>0&&(t[t.length-1]=n({},t[t.length-1],{state:n({},e)})),t})},[]);return e.jsx(t.Provider,{value:{stack:l,launchModal:s,updateStack:c,updateState:i},children:u})},exports.ModalPort=function(t){var u=t.onModalLaunch,a=t.onModalClose,l=t.render,c=o().stack,s=r.useMemo(function(){return c.length>0?c[c.length-1]:null},[c]),i=r.useRef(null),d=r.useCallback(function(e){e.currentTarget===e.target&&null!=s&&s.resolvers.onBackdropClick&&s.resolvers.onBackdropClick(e)},[s]);r.useEffect(function(){var e=i.current;!e&&s?null==u||u():e&&!s&&(null==a||a()),i.current=s},[s,u,a]);var v=null==s?void 0:s.render;return e.jsx(e.Fragment,{children:v&&e.jsx(l,{onBackdropClick:d,children:e.jsx(v,n({},s.resolvers,s.props))})||null})},exports.useModal=function(){return o().launchModal},exports.useModalContext=o,exports.useModalState=function(){var e=o(),r=e.stack,n=e.updateState;return 0===r.length?[null,n]:[r[r.length-1].state,n]};
-//# sourceMappingURL=index.cjs.map
+"use client";
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ModalContextProvider: () => ModalContextProvider,
+  ModalPort: () => ModalPort,
+  ModalProvider: () => ModalProvider,
+  useModal: () => useModal,
+  useModalContext: () => useModalContext,
+  useModalStack: () => useModalStack,
+  useModalState: () => useModalState
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/context.tsx
+var import_react = require("react");
+
+// src/store.ts
+function reducer(stack, action) {
+  switch (action.type) {
+    case "push":
+      return [...stack, action.item];
+    case "remove":
+      return stack.some((item) => item.id === action.id) ? stack.filter((item) => item.id !== action.id) : stack;
+    case "setState": {
+      const { id, update } = action;
+      if (!stack.some((item) => item.id === id)) return stack;
+      return stack.map(
+        (item) => item.id === id ? { ...item, state: typeof update === "function" ? update(item.state) : { ...update } } : item
+      );
+    }
+  }
+}
+
+// src/context.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var ActionsContext = (0, import_react.createContext)(null);
+var StackContext = (0, import_react.createContext)(null);
+var ItemContext = (0, import_react.createContext)(null);
+var nextId = 0;
+var warned = /* @__PURE__ */ new Set();
+var isProduction = () => {
+  try {
+    return process.env.NODE_ENV === "production";
+  } catch {
+    return false;
+  }
+};
+function warnOnce(key, message) {
+  if (isProduction() || warned.has(key)) return;
+  warned.add(key);
+  console.warn(`[react-modal-port] ${message}`);
+}
+function ModalProvider({ children }) {
+  const [stack, dispatch] = (0, import_react.useReducer)(reducer, []);
+  const actions = (0, import_react.useMemo)(() => {
+    const launchModal = ((render, resolvers, props = {}, options = {}) => {
+      const id = ++nextId;
+      let settled = false;
+      const wrap = (fn) => async (...args) => {
+        if (settled) return void 0;
+        settled = true;
+        try {
+          const result = await fn(...args);
+          dispatch({ type: "remove", id });
+          return result;
+        } catch (error) {
+          settled = false;
+          throw error;
+        }
+      };
+      const { onBackdropClick: legacyDismiss, ...ownResolvers } = resolvers;
+      if (legacyDismiss) {
+        warnOnce(
+          "onBackdropClick",
+          "Passing `onBackdropClick` as a resolver is deprecated. Use `launchModal(Modal, resolvers, props, { onDismiss })`."
+        );
+      }
+      const onDismiss = options.onDismiss ?? legacyDismiss;
+      for (const key of Object.keys(props)) {
+        if (key in ownResolvers) {
+          warnOnce(
+            `collision:${key}`,
+            `Prop "${key}" has the same name as a resolver and is ignored. Resolvers take precedence.`
+          );
+        }
+      }
+      dispatch({
+        type: "push",
+        item: {
+          id,
+          render,
+          props,
+          resolvers: Object.fromEntries(Object.entries(ownResolvers).map(([key, fn]) => [key, wrap(fn)])),
+          onDismiss: onDismiss ? wrap(onDismiss) : void 0,
+          state: {}
+        }
+      });
+      return {
+        id,
+        close: () => {
+          settled = true;
+          dispatch({ type: "remove", id });
+        }
+      };
+    });
+    return {
+      launchModal,
+      setState: (id, update) => dispatch({ type: "setState", id, update })
+    };
+  }, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ActionsContext, { value: actions, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(StackContext, { value: stack, children }) });
+}
+var ModalContextProvider = ModalProvider;
+function useRequired(context, hook) {
+  const value = (0, import_react.use)(context);
+  if (value === null) {
+    throw new Error(`${hook} must be used within a <ModalProvider>`);
+  }
+  return value;
+}
+function useModalItems(hook = "ModalPort") {
+  return useRequired(StackContext, hook);
+}
+function toEntry({ id, render, props, state }) {
+  return { id, render, props, state };
+}
+function useModal() {
+  return useRequired(ActionsContext, "useModal").launchModal;
+}
+function useModalStack() {
+  const items = useModalItems("useModalStack");
+  return (0, import_react.useMemo)(() => items.map(toEntry), [items]);
+}
+function useModalState() {
+  const { setState } = useRequired(ActionsContext, "useModalState");
+  const items = useModalItems("useModalState");
+  const ownId = (0, import_react.use)(ItemContext);
+  const item = ownId === null ? items.at(-1) : items.find((entry) => entry.id === ownId);
+  const id = item?.id;
+  const update = (0, import_react.useCallback)(
+    (next) => {
+      if (id !== void 0) setState(id, next);
+    },
+    [id, setState]
+  );
+  return [item ? item.state : null, update];
+}
+function useModalContext() {
+  const launchModal = useRequired(ActionsContext, "useModalContext").launchModal;
+  const stack = useModalStack();
+  const [, updateState] = useModalState();
+  return { stack, launchModal, updateState };
+}
+
+// src/modal-port.tsx
+var import_react2 = require("react");
+var import_react_dom = require("react-dom");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var NoBackdrop = ({ children }) => /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_react2.Fragment, { children });
+function ModalPort({
+  backdrop,
+  render,
+  container,
+  onModalLaunch,
+  onModalClose,
+  onStackChange
+}) {
+  const stack = useModalItems();
+  const size = stack.length;
+  const previousSize = (0, import_react2.useRef)(0);
+  (0, import_react2.useEffect)(() => {
+    const previous = previousSize.current;
+    if (previous === size) return;
+    previousSize.current = size;
+    onStackChange?.(size);
+    if (previous === 0) onModalLaunch?.();
+    else if (size === 0) onModalClose?.();
+  }, [size, onModalLaunch, onModalClose, onStackChange]);
+  const top = stack.at(-1);
+  if (!top) return null;
+  const Backdrop = backdrop ?? render ?? NoBackdrop;
+  const Modal = top.render;
+  const { onDismiss } = top;
+  const onBackdropClick = onDismiss ? (event) => {
+    if (event.currentTarget === event.target) void onDismiss(event);
+  } : void 0;
+  const content = /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(Backdrop, { onBackdropClick, modalId: top.id, stackSize: size, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(ItemContext, { value: top.id, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(Modal, { ...top.props, ...top.resolvers }) }, top.id) });
+  return container ? (0, import_react_dom.createPortal)(content, container) : content;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ModalContextProvider,
+  ModalPort,
+  ModalProvider,
+  useModal,
+  useModalContext,
+  useModalStack,
+  useModalState
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../src/context.tsx","../src/modal-port.tsx"],"sourcesContent":["import { \n  createContext, \n  useContext, \n  useState, \n  useCallback,\n  type SyntheticEvent \n} from 'react';\nimport { \n  type ModalStackItem,\n  type ModalContextProperties,\n  type LaunchModal,\n  type LaunchModalResolvers,\n  type ModalState,\n  type UpdateModalState,\n  ModalProps,\n} from './types';\n\nexport const ModalContext = createContext<ModalContextProperties | null>(null);\n\nexport const ModalContextProvider = ({ children }: Readonly<{ children: React.ReactNode }>) => {\n\n  const [ stack, updateStack ] = useState<ModalStackItem<any>[]>([]);\n\n  const launchModal = useCallback(<P extends Record<string, any> = Record<string, any>>(\n    render: React.FunctionComponent<ModalProps<P>>, \n    resolvers: LaunchModalResolvers,\n    props: any = {}\n  ) => {\n    // Wrap resolvers to update the stack\n    const wrappedResovers = Object.keys(resolvers).reduce((acc, key) => {\n      const resolver = resolvers[key];\n      acc[key] = async (...args: any[]) => {\n        const result = await resolver(...args);\n        // update stack with an array containing all the items in the stack except the last one\n        updateStack(currStack => currStack.slice(0, -1));\n        return result;\n      };\n      return acc;\n    }, {} as LaunchModalResolvers);\n\n    updateStack(prevStack => [\n      ...prevStack,\n      {\n        render,\n        resolvers: wrappedResovers,\n        props,\n        state: {},\n      },\n    ]);\n  }, []);\n\n  const updateState = useCallback((newState: ModalState) => {\n    updateStack(prevStack => {\n      const updatedStack = [...prevStack];\n      if (updatedStack.length > 0) {\n        updatedStack[updatedStack.length - 1] = {\n          ...updatedStack[updatedStack.length - 1],\n          state: { ...newState }\n        };\n      }\n      return updatedStack;\n    });\n  }, []);\n\n  const contextProperties: ModalContextProperties = {\n    stack,\n    launchModal,\n    updateStack,\n    updateState,\n  };\n\n  return <ModalContext.Provider value={contextProperties}>{children}</ModalContext.Provider>;\n\n};\n\n/**\n * Get properties from the modal context\n * @returns {ModalContextProperties} Object with the modal context properties\n */\nexport function useModalContext(): ModalContextProperties {\n  const context = useContext(ModalContext);\n  if (!context) {\n    throw new Error('useModalContext must be used within a ModalContextProvider');\n  }\n  return context;\n}\n\n/**\n * Short-hand for `useModalContext().launchModal`\n * @returns {LaunchModal} The launchModal function\n */\nexport function useModal() {\n  const { launchModal } = useModalContext();\n  return launchModal;\n}\n\n/**\n * Get access to the current modal state and a function to update it\n * @returns {[ ModalState | null, UpdateModalState ]} A tuple with the current modal state and a function to update it\n */\nexport function useModalState(): [ ModalState | null, UpdateModalState ] {\n  const { stack, updateState } = useModalContext();\n  if (stack.length === 0) {\n    return [null, updateState];\n  }\n  const state = stack[stack.length - 1].state;\n  return [ state, updateState ];\n}\n","import { \n  ModalProps,\n  type ModalPortProps, \n  type ModalStackItem \n} from \"./types\";\nimport { useModalContext } from \"./context\";\nimport { \n  type SyntheticEvent, \n  useCallback, \n  useEffect, \n  useMemo,\n  useRef,\n  type ReactElement\n} from \"react\";\n\nconst ModalPort: React.FC<ModalPortProps> = ({\n  onModalLaunch,\n  onModalClose,\n  render: Backdrop\n}) => {\n\n  const { stack } = useModalContext();\n  const currentModal: ModalStackItem<ModalProps> | null = useMemo(\n    () => stack.length > 0 ? stack[stack.length - 1] : null,\n    [ stack ]\n  );\n  \n  const previousModalRef = useRef<ModalStackItem<ModalProps> | null>(null);\n  \n  const onBackdropClick = useCallback((ev: SyntheticEvent) => {\n    if (ev.currentTarget !== ev.target) return;\n    if (currentModal?.resolvers.onBackdropClick) {\n      currentModal.resolvers.onBackdropClick(ev);\n    }\n  }, [ currentModal ]);\n\n  useEffect(() => {\n    const previousModal = previousModalRef.current;\n    \n    // Modal was launched (went from no modal to having a modal)\n    if (!previousModal && currentModal) {\n      onModalLaunch?.();\n    }\n    // Modal was closed (went from having a modal to no modal)\n    else if (previousModal && !currentModal) {\n      onModalClose?.();\n    }\n    \n    // Update the ref for next time\n    previousModalRef.current = currentModal;\n  }, [ currentModal, onModalLaunch, onModalClose ]);\n\n  const ModalContent = currentModal?.render;\n\n  return (\n    <>\n      {ModalContent && (\n        <Backdrop onBackdropClick={onBackdropClick}>\n          <ModalContent\n            {...currentModal.resolvers}\n            {...currentModal.props}\n          />\n        </Backdrop>\n      ) || null}\n    </>\n  );\n};\n\nexport default ModalPort;\nexport { ModalPort };\n"],"names":["ModalContext","createContext","useModalContext","context","useContext","Error","_ref","children","_useState","useState","stack","updateStack","launchModal","useCallback","render","resolvers","props","wrappedResovers","Object","keys","reduce","acc","key","resolver","Promise","resolve","apply","slice","call","arguments","then","result","currStack","e","reject","prevStack","concat","state","updateState","newState","updatedStack","length","_extends","_jsx","Provider","value","onModalLaunch","onModalClose","Backdrop","currentModal","useMemo","previousModalRef","useRef","onBackdropClick","ev","currentTarget","target","useEffect","previousModal","current","ModalContent","_Fragment","jsx","_useModalContext2"],"mappings":"kRAiBaA,EAAeC,EAAaA,cAAgC,MA8DzD,SAAAC,IACd,IAAMC,EAAUC,EAAUA,WAACJ,GAC3B,IAAKG,EACH,MAAU,IAAAE,MAAM,8DAElB,OAAOF,CACT,8BAlEoC,SAAHG,GAA6D,IAAvDC,EAAQD,EAARC,SAErCC,EAA+BC,EAAQA,SAAwB,IAAvDC,EAAKF,EAAA,GAAEG,EAAWH,EAE1B,GAAMI,EAAcC,EAAAA,YAAY,SAC9BC,EACAC,EACAC,QAAAA,IAAAA,IAAAA,EAAa,IAGb,IAAMC,EAAkBC,OAAOC,KAAKJ,GAAWK,OAAO,SAACC,EAAKC,GAC1D,IAAMC,EAAWR,EAAUO,GAO3B,OANAD,EAAIC,GAAI,WAAA,IAA4B,OAAAE,QAAAC,QACbF,EAAQG,WAAAC,EAAAA,GAAAA,MAAAC,KADKC,aACIC,KAAhCC,SAAAA,GAGN,OADApB,EAAY,SAAAqB,GAAa,OAAAA,EAAUL,MAAM,GAAI,EAAE,GACxCI,CAAO,EAChB,CAAC,MAAAE,UAAAT,QAAAU,OAAAD,EAAA,CAAA,EACMZ,CACT,EAAG,CAAA,GAEHV,EAAY,SAAAwB,GAAS,MAAA,GAAAC,OAChBD,EACH,CAAA,CACErB,OAAAA,EACAC,UAAWE,EACXD,MAAAA,EACAqB,MAAO,CAAA,IAEV,EACH,EAAG,IAEGC,EAAczB,cAAY,SAAC0B,GAC/B5B,EAAY,SAAAwB,GACV,IAAMK,EAAYJ,GAAAA,OAAOD,GAOzB,OANIK,EAAaC,OAAS,IACxBD,EAAaA,EAAaC,OAAS,GAAEC,EAChCF,CAAAA,EAAAA,EAAaA,EAAaC,OAAS,GACtCJ,CAAAA,MAAKK,KAAOH,MAGTC,CACT,EACF,EAAG,IASH,OAAOG,EAAAA,IAAC3C,EAAa4C,SAAQ,CAACC,MAPoB,CAChDnC,MAAAA,EACAE,YAAAA,EACAD,YAAAA,EACA2B,YAAAA,GAGoD/B,SAAGA,GAE3D,oBC1D4C,SAA7BD,GACb,IAAAwC,EAAaxC,EAAbwC,cACAC,EAAYzC,EAAZyC,aACQC,EAAQ1C,EAAhBQ,OAGQJ,EAAUR,IAAVQ,MACFuC,EAAkDC,EAAAA,QACtD,WAAA,OAAMxC,EAAM+B,OAAS,EAAI/B,EAAMA,EAAM+B,OAAS,GAAK,IAAI,EACvD,CAAE/B,IAGEyC,EAAmBC,SAA0C,MAE7DC,EAAkBxC,EAAAA,YAAY,SAACyC,GAC/BA,EAAGC,gBAAkBD,EAAGE,cACxBP,GAAAA,EAAclC,UAAUsC,iBAC1BJ,EAAalC,UAAUsC,gBAAgBC,EAE3C,EAAG,CAAEL,IAELQ,EAAAA,UAAU,WACR,IAAMC,EAAgBP,EAAiBQ,SAGlCD,GAAiBT,EACP,MAAbH,GAAAA,IAGOY,IAAkBT,IACzBF,MAAAA,GAAAA,KAIFI,EAAiBQ,QAAUV,CAC7B,EAAG,CAAEA,EAAcH,EAAeC,IAElC,IAAMa,EAAeX,MAAAA,OAAAA,EAAAA,EAAcnC,OAEnC,OACE6B,EAAAA,IAAAkB,EAAAA,SAAA,CAAAtD,SACGqD,GACCjB,EAAAmB,IAACd,EAAQ,CAACK,gBAAiBA,EAAe9C,SACxCoC,EAACmB,IAAAF,EAAYlB,EACPO,CAAAA,EAAAA,EAAalC,UACbkC,EAAajC,WAGlB,MAGX,8BD2BE,OADwBd,IAAhBU,WAEV,6DAOE,IAAAmD,EAA+B7D,IAAvBQ,EAAKqD,EAALrD,MAAO4B,EAAWyB,EAAXzB,YACf,OAAqB,IAAjB5B,EAAM+B,OACD,CAAC,KAAMH,GAGT,CADO5B,EAAMA,EAAM+B,OAAS,GAAGJ,MACtBC,EAClB"}
+{"version":3,"sources":["../src/index.ts","../src/context.tsx","../src/store.ts","../src/modal-port.tsx"],"sourcesContent":["export {\n  ModalProvider,\n  ModalContextProvider,\n  useModal,\n  useModalStack,\n  useModalState,\n  useModalContext,\n} from './context';\nexport { ModalPort } from './modal-port';\n\nexport type {\n  FunctionKeys,\n  Resolvers,\n  RestProps,\n  LaunchRest,\n  LaunchOptions,\n  LaunchModal,\n  ModalHandle,\n  ModalState,\n  UpdateModalState,\n  ModalStackEntry,\n  ModalPortRenderProps,\n  ModalPortProps,\n  ModalContextProperties,\n  ModalProps,\n  ModalResolver,\n  LaunchModalResolvers,\n  LaunchModalProps,\n} from './types';\n","import {\n  createContext,\n  use,\n  useCallback,\n  useMemo,\n  useReducer,\n  type ComponentType,\n  type Context,\n  type ReactNode,\n} from 'react';\nimport { reducer, type ModalItem, type StateUpdate } from './store';\nimport type {\n  LaunchModal,\n  LaunchOptions,\n  ModalContextProperties,\n  ModalStackEntry,\n  ModalState,\n  UpdateModalState,\n} from './types';\n\ntype Actions = {\n  launchModal: LaunchModal;\n  setState: (id: number, update: StateUpdate) => void;\n};\n\nconst ActionsContext = createContext<Actions | null>(null);\nconst StackContext = createContext<readonly ModalItem[] | null>(null);\n/** Id of the modal a component is rendered inside, if any. */\nexport const ItemContext = createContext<number | null>(null);\n\nlet nextId = 0;\nconst warned = new Set<string>();\ndeclare const process: { env: { NODE_ENV?: string } };\n// Bundlers replace the literal `process.env.NODE_ENV` but usually do not define `process`,\n// so read it directly; unbundled ESM (no `process` at all) falls back to development.\nconst isProduction = () => {\n  try {\n    return process.env.NODE_ENV === 'production';\n  } catch {\n    return false;\n  }\n};\nfunction warnOnce(key: string, message: string) {\n  if (isProduction() || warned.has(key)) return;\n  warned.add(key);\n  console.warn(`[react-modal-port] ${message}`);\n}\n\ntype AnyResolver = (...args: unknown[]) => unknown;\n\nexport function ModalProvider({ children }: { children?: ReactNode }) {\n  const [stack, dispatch] = useReducer(reducer, []);\n\n  const actions = useMemo<Actions>(() => {\n    const launchModal = ((\n      render: ComponentType<never>,\n      resolvers: Record<string, AnyResolver>,\n      props: Record<string, unknown> = {},\n      options: LaunchOptions = {},\n    ) => {\n      // Created outside the reducer so StrictMode's double-invoked reducers stay pure.\n      const id = ++nextId;\n      let settled = false;\n\n      const wrap =\n        (fn: AnyResolver) =>\n        async (...args: unknown[]) => {\n          if (settled) return undefined;\n          settled = true;\n          try {\n            const result = await fn(...args);\n            dispatch({ type: 'remove', id });\n            return result;\n          } catch (error) {\n            // Keep the modal open so the user can retry; let the caller handle the error.\n            settled = false;\n            throw error;\n          }\n        };\n\n      const { onBackdropClick: legacyDismiss, ...ownResolvers } = resolvers;\n      if (legacyDismiss) {\n        warnOnce(\n          'onBackdropClick',\n          'Passing `onBackdropClick` as a resolver is deprecated. Use `launchModal(Modal, resolvers, props, { onDismiss })`.',\n        );\n      }\n      const onDismiss = options.onDismiss ?? legacyDismiss;\n\n      for (const key of Object.keys(props)) {\n        if (key in ownResolvers) {\n          warnOnce(\n            `collision:${key}`,\n            `Prop \"${key}\" has the same name as a resolver and is ignored. Resolvers take precedence.`,\n          );\n        }\n      }\n\n      dispatch({\n        type: 'push',\n        item: {\n          id,\n          render,\n          props,\n          resolvers: Object.fromEntries(Object.entries(ownResolvers).map(([key, fn]) => [key, wrap(fn)])),\n          onDismiss: onDismiss ? wrap(onDismiss as AnyResolver) : undefined,\n          state: {},\n        },\n      });\n\n      return {\n        id,\n        close: () => {\n          settled = true;\n          dispatch({ type: 'remove', id });\n        },\n      };\n    }) as LaunchModal;\n\n    return {\n      launchModal,\n      setState: (id, update) => dispatch({ type: 'setState', id, update }),\n    };\n  }, []);\n\n  return (\n    <ActionsContext value={actions}>\n      <StackContext value={stack}>{children}</StackContext>\n    </ActionsContext>\n  );\n}\n\n/** @deprecated Use `ModalProvider`. */\nexport const ModalContextProvider = ModalProvider;\n\nfunction useRequired<T>(context: Context<T | null>, hook: string): T {\n  const value = use(context);\n  if (value === null) {\n    throw new Error(`${hook} must be used within a <ModalProvider>`);\n  }\n  return value;\n}\n\n/** @internal Full stack items, including wrapped resolvers. Used by `ModalPort`. */\nexport function useModalItems(hook = 'ModalPort'): readonly ModalItem[] {\n  return useRequired(StackContext, hook);\n}\n\nfunction toEntry({ id, render, props, state }: ModalItem): ModalStackEntry {\n  return { id, render, props, state };\n}\n\n/** Returns the `launchModal` function. Does not re-render when the stack changes. */\nexport function useModal(): LaunchModal {\n  return useRequired(ActionsContext, 'useModal').launchModal;\n}\n\n/** A read-only view of the modal stack, bottom first. */\nexport function useModalStack(): readonly ModalStackEntry[] {\n  const items = useModalItems('useModalStack');\n  return useMemo(() => items.map(toEntry), [items]);\n}\n\n/**\n * State shared by the modal this hook is called in (or the top modal, when called\n * outside any modal). Survives while other modals are stacked on top and is\n * discarded when the modal closes. `null` when there is no such modal.\n */\nexport function useModalState<S extends ModalState = ModalState>(): [S | null, UpdateModalState<S>] {\n  const { setState } = useRequired(ActionsContext, 'useModalState');\n  const items = useModalItems('useModalState');\n  const ownId = use(ItemContext);\n  const item = ownId === null ? items.at(-1) : items.find((entry) => entry.id === ownId);\n  const id = item?.id;\n\n  const update = useCallback<UpdateModalState<S>>(\n    (next) => {\n      if (id !== undefined) setState(id, next as StateUpdate);\n    },\n    [id, setState],\n  );\n\n  return [item ? (item.state as S) : null, update];\n}\n\n/**\n * @deprecated Use `useModal`, `useModalStack` and `useModalState`. This hook re-renders\n * on every stack change.\n */\nexport function useModalContext(): ModalContextProperties {\n  const launchModal = useRequired(ActionsContext, 'useModalContext').launchModal;\n  const stack = useModalStack();\n  const [, updateState] = useModalState();\n  return { stack, launchModal, updateState };\n}\n","import type { ComponentType } from 'react';\nimport type { ModalState } from './types';\n\nexport type ModalItem = {\n  readonly id: number;\n  readonly render: ComponentType<never>;\n  /** Resolvers, already wrapped so that they close this item. */\n  readonly resolvers: Readonly<Record<string, (...args: unknown[]) => Promise<unknown>>>;\n  readonly props: Readonly<Record<string, unknown>>;\n  readonly onDismiss: ((...args: unknown[]) => Promise<unknown>) | undefined;\n  readonly state: ModalState;\n};\n\nexport type StateUpdate = ModalState | ((prev: ModalState) => ModalState);\n\nexport type Action =\n  | { type: 'push'; item: ModalItem }\n  | { type: 'remove'; id: number }\n  | { type: 'setState'; id: number; update: StateUpdate };\n\n/** Pure stack reducer. Ids are created by the caller, so this stays StrictMode-safe. */\nexport function reducer(stack: readonly ModalItem[], action: Action): readonly ModalItem[] {\n  switch (action.type) {\n    case 'push':\n      return [...stack, action.item];\n    case 'remove':\n      return stack.some((item) => item.id === action.id)\n        ? stack.filter((item) => item.id !== action.id)\n        : stack;\n    case 'setState': {\n      const { id, update } = action;\n      if (!stack.some((item) => item.id === id)) return stack;\n      return stack.map((item) =>\n        item.id === id\n          ? { ...item, state: typeof update === 'function' ? update(item.state) : { ...update } }\n          : item,\n      );\n    }\n  }\n}\n","import { Fragment, useEffect, useRef, type ComponentType, type SyntheticEvent } from 'react';\nimport { createPortal } from 'react-dom';\nimport { ItemContext, useModalItems } from './context';\nimport type { ModalPortProps, ModalPortRenderProps } from './types';\n\nconst NoBackdrop = ({ children }: ModalPortRenderProps) => <Fragment>{children}</Fragment>;\n\n/** Renders the top modal of the stack inside `backdrop`. */\nexport function ModalPort({\n  backdrop,\n  render,\n  container,\n  onModalLaunch,\n  onModalClose,\n  onStackChange,\n}: ModalPortProps) {\n  const stack = useModalItems();\n  const size = stack.length;\n  const previousSize = useRef(0);\n\n  useEffect(() => {\n    const previous = previousSize.current;\n    if (previous === size) return;\n    previousSize.current = size;\n    onStackChange?.(size);\n    if (previous === 0) onModalLaunch?.();\n    else if (size === 0) onModalClose?.();\n  }, [size, onModalLaunch, onModalClose, onStackChange]);\n\n  const top = stack.at(-1);\n  if (!top) return null;\n\n  const Backdrop = backdrop ?? render ?? NoBackdrop;\n  // Props are typed per launch; the stack stores them loosely.\n  const Modal = top.render as ComponentType<Record<string, unknown>>;\n  const { onDismiss } = top;\n  const onBackdropClick = onDismiss\n    ? (event: SyntheticEvent) => {\n        // Ignore clicks that bubble up from the modal content.\n        if (event.currentTarget === event.target) void onDismiss(event);\n      }\n    : undefined;\n\n  const content = (\n    <Backdrop onBackdropClick={onBackdropClick} modalId={top.id} stackSize={size}>\n      <ItemContext key={top.id} value={top.id}>\n        <Modal {...top.props} {...top.resolvers} />\n      </ItemContext>\n    </Backdrop>\n  );\n\n  return container ? createPortal(content, container) : content;\n}\n"],"mappings":"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","names":["import_react","import_jsx_runtime"]}

package/dist/index.d.cts

@@ -0,0 +1,113 @@
+import * as react from 'react';
+import { ComponentType, ComponentProps, SyntheticEvent, KeyboardEvent, ReactNode } from 'react';
+
+type AnyFn = (...args: any[]) => any;
+/** Keys of `P` whose (non-nullable) value is a function, optional props included. */
+type FunctionKeys<P> = {
+    [K in keyof P]-?: NonNullable<P[K]> extends AnyFn ? K : never;
+}[keyof P];
+/** The subset of a modal's function props that resolve (and close) it. */
+type Resolvers<P, R extends FunctionKeys<P>> = {
+    [K in R]: P[K];
+};
+/** Everything the modal needs that is not passed as a resolver. */
+type RestProps<P, R extends PropertyKey> = Omit<P, R>;
+/** Options that concern the port rather than the modal component itself. */
+type LaunchOptions = {
+    /**
+     * Called when the modal is dismissed from outside its content (backdrop click,
+     * or Escape if your backdrop wires it). Wrapped like a resolver: it closes this
+     * modal once it has run, and keeps it open if it throws.
+     */
+    onDismiss?: (event?: SyntheticEvent | KeyboardEvent | Event) => unknown;
+};
+/**
+ * Arguments after `resolvers`: `props` is required when the modal still has required
+ * props left, optional when only optional props are left, and must be empty otherwise.
+ */
+type LaunchRest<P, R extends PropertyKey> = [keyof RestProps<P, R>] extends [never] ? [props?: Record<string, never>, options?: LaunchOptions] : object extends RestProps<P, R> ? [props?: RestProps<P, R>, options?: LaunchOptions] : [props: RestProps<P, R>, options?: LaunchOptions];
+/** Returned by `launchModal`; lets the launcher close the modal programmatically. */
+type ModalHandle = {
+    readonly id: number;
+    /** Removes this modal without calling any resolver. No-op if it is already gone. */
+    close: () => void;
+};
+/**
+ * Launch `render` on top of the modal stack.
+ *
+ * The modal's props are read from the component `C`. `R` is inferred from the keys of
+ * `resolvers`, which must be function props of the modal. The remaining props are type-checked against the modal's props.
+ */
+type LaunchModal = <C extends ComponentType<any>, R extends FunctionKeys<ComponentProps<C>> = never>(render: C, resolvers: Resolvers<ComponentProps<C>, R>, ...rest: LaunchRest<ComponentProps<C>, R>) => ModalHandle;
+type ModalState = Record<string, unknown>;
+type UpdateModalState<S extends ModalState = ModalState> = (update: S | ((prev: S) => S)) => void;
+/** A read-only view of one modal on the stack. */
+type ModalStackEntry = {
+    readonly id: number;
+    readonly render: ComponentType<never>;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly state: Readonly<ModalState>;
+};
+type ModalPortRenderProps = {
+    children?: ReactNode;
+    /** Present only when the current modal can be dismissed (it was launched with `onDismiss`). */
+    onBackdropClick?: (event: SyntheticEvent) => void;
+    /** Id of the modal currently shown. */
+    modalId: number;
+    /** Number of modals on the stack, including the one shown. */
+    stackSize: number;
+};
+type ModalPortProps = {
+    /** Component rendered around the current modal, typically a backdrop. */
+    backdrop?: ComponentType<ModalPortRenderProps>;
+    /** @deprecated Use `backdrop`. */
+    render?: ComponentType<ModalPortRenderProps>;
+    /** Render into this element through a portal instead of in place. */
+    container?: Element | DocumentFragment | null;
+    /** Called when the stack goes from empty to non-empty. */
+    onModalLaunch?: () => void;
+    /** Called when the stack becomes empty. */
+    onModalClose?: () => void;
+    /** Called with the new stack size whenever a modal is launched or closed. */
+    onStackChange?: (stackSize: number) => void;
+};
+type ModalContextProperties = {
+    readonly stack: readonly ModalStackEntry[];
+    launchModal: LaunchModal;
+    /** Replaces the state of the top modal. */
+    updateState: UpdateModalState;
+};
+/** @deprecated Type your modal's props directly. */
+type ModalProps<P = Record<string, any>> = P;
+/** @deprecated Use `Resolvers` or your modal's own prop types. */
+type ModalResolver = (...args: any[]) => unknown;
+/** @deprecated Use `Resolvers` or your modal's own prop types. */
+type LaunchModalResolvers = Record<string, ModalResolver>;
+/** @deprecated Use your modal's own prop types. */
+type LaunchModalProps = Record<string, unknown>;
+
+declare function ModalProvider({ children }: {
+    children?: ReactNode;
+}): react.JSX.Element;
+/** @deprecated Use `ModalProvider`. */
+declare const ModalContextProvider: typeof ModalProvider;
+/** Returns the `launchModal` function. Does not re-render when the stack changes. */
+declare function useModal(): LaunchModal;
+/** A read-only view of the modal stack, bottom first. */
+declare function useModalStack(): readonly ModalStackEntry[];
+/**
+ * State shared by the modal this hook is called in (or the top modal, when called
+ * outside any modal). Survives while other modals are stacked on top and is
+ * discarded when the modal closes. `null` when there is no such modal.
+ */
+declare function useModalState<S extends ModalState = ModalState>(): [S | null, UpdateModalState<S>];
+/**
+ * @deprecated Use `useModal`, `useModalStack` and `useModalState`. This hook re-renders
+ * on every stack change.
+ */
+declare function useModalContext(): ModalContextProperties;
+
+/** Renders the top modal of the stack inside `backdrop`. */
+declare function ModalPort({ backdrop, render, container, onModalLaunch, onModalClose, onStackChange, }: ModalPortProps): react.JSX.Element | null;
+
+export { type FunctionKeys, type LaunchModal, type LaunchModalProps, type LaunchModalResolvers, type LaunchOptions, type LaunchRest, type ModalContextProperties, ModalContextProvider, type ModalHandle, ModalPort, type ModalPortProps, type ModalPortRenderProps, type ModalProps, ModalProvider, type ModalResolver, type ModalStackEntry, type ModalState, type Resolvers, type RestProps, type UpdateModalState, useModal, useModalContext, useModalStack, useModalState };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import * as react from 'react';
+import { ComponentType, ComponentProps, SyntheticEvent, KeyboardEvent, ReactNode } from 'react';
+
+type AnyFn = (...args: any[]) => any;
+/** Keys of `P` whose (non-nullable) value is a function, optional props included. */
+type FunctionKeys<P> = {
+    [K in keyof P]-?: NonNullable<P[K]> extends AnyFn ? K : never;
+}[keyof P];
+/** The subset of a modal's function props that resolve (and close) it. */
+type Resolvers<P, R extends FunctionKeys<P>> = {
+    [K in R]: P[K];
+};
+/** Everything the modal needs that is not passed as a resolver. */
+type RestProps<P, R extends PropertyKey> = Omit<P, R>;
+/** Options that concern the port rather than the modal component itself. */
+type LaunchOptions = {
+    /**
+     * Called when the modal is dismissed from outside its content (backdrop click,
+     * or Escape if your backdrop wires it). Wrapped like a resolver: it closes this
+     * modal once it has run, and keeps it open if it throws.
+     */
+    onDismiss?: (event?: SyntheticEvent | KeyboardEvent | Event) => unknown;
+};
+/**
+ * Arguments after `resolvers`: `props` is required when the modal still has required
+ * props left, optional when only optional props are left, and must be empty otherwise.
+ */
+type LaunchRest<P, R extends PropertyKey> = [keyof RestProps<P, R>] extends [never] ? [props?: Record<string, never>, options?: LaunchOptions] : object extends RestProps<P, R> ? [props?: RestProps<P, R>, options?: LaunchOptions] : [props: RestProps<P, R>, options?: LaunchOptions];
+/** Returned by `launchModal`; lets the launcher close the modal programmatically. */
+type ModalHandle = {
+    readonly id: number;
+    /** Removes this modal without calling any resolver. No-op if it is already gone. */
+    close: () => void;
+};
+/**
+ * Launch `render` on top of the modal stack.
+ *
+ * The modal's props are read from the component `C`. `R` is inferred from the keys of
+ * `resolvers`, which must be function props of the modal. The remaining props are type-checked against the modal's props.
+ */
+type LaunchModal = <C extends ComponentType<any>, R extends FunctionKeys<ComponentProps<C>> = never>(render: C, resolvers: Resolvers<ComponentProps<C>, R>, ...rest: LaunchRest<ComponentProps<C>, R>) => ModalHandle;
+type ModalState = Record<string, unknown>;
+type UpdateModalState<S extends ModalState = ModalState> = (update: S | ((prev: S) => S)) => void;
+/** A read-only view of one modal on the stack. */
+type ModalStackEntry = {
+    readonly id: number;
+    readonly render: ComponentType<never>;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly state: Readonly<ModalState>;
+};
+type ModalPortRenderProps = {
+    children?: ReactNode;
+    /** Present only when the current modal can be dismissed (it was launched with `onDismiss`). */
+    onBackdropClick?: (event: SyntheticEvent) => void;
+    /** Id of the modal currently shown. */
+    modalId: number;
+    /** Number of modals on the stack, including the one shown. */
+    stackSize: number;
+};
+type ModalPortProps = {
+    /** Component rendered around the current modal, typically a backdrop. */
+    backdrop?: ComponentType<ModalPortRenderProps>;
+    /** @deprecated Use `backdrop`. */
+    render?: ComponentType<ModalPortRenderProps>;
+    /** Render into this element through a portal instead of in place. */
+    container?: Element | DocumentFragment | null;
+    /** Called when the stack goes from empty to non-empty. */
+    onModalLaunch?: () => void;
+    /** Called when the stack becomes empty. */
+    onModalClose?: () => void;
+    /** Called with the new stack size whenever a modal is launched or closed. */
+    onStackChange?: (stackSize: number) => void;
+};
+type ModalContextProperties = {
+    readonly stack: readonly ModalStackEntry[];
+    launchModal: LaunchModal;
+    /** Replaces the state of the top modal. */
+    updateState: UpdateModalState;
+};
+/** @deprecated Type your modal's props directly. */
+type ModalProps<P = Record<string, any>> = P;
+/** @deprecated Use `Resolvers` or your modal's own prop types. */
+type ModalResolver = (...args: any[]) => unknown;
+/** @deprecated Use `Resolvers` or your modal's own prop types. */
+type LaunchModalResolvers = Record<string, ModalResolver>;
+/** @deprecated Use your modal's own prop types. */
+type LaunchModalProps = Record<string, unknown>;
+
+declare function ModalProvider({ children }: {
+    children?: ReactNode;
+}): react.JSX.Element;
+/** @deprecated Use `ModalProvider`. */
+declare const ModalContextProvider: typeof ModalProvider;
+/** Returns the `launchModal` function. Does not re-render when the stack changes. */
+declare function useModal(): LaunchModal;
+/** A read-only view of the modal stack, bottom first. */
+declare function useModalStack(): readonly ModalStackEntry[];
+/**
+ * State shared by the modal this hook is called in (or the top modal, when called
+ * outside any modal). Survives while other modals are stacked on top and is
+ * discarded when the modal closes. `null` when there is no such modal.
+ */
+declare function useModalState<S extends ModalState = ModalState>(): [S | null, UpdateModalState<S>];
+/**
+ * @deprecated Use `useModal`, `useModalStack` and `useModalState`. This hook re-renders
+ * on every stack change.
+ */
+declare function useModalContext(): ModalContextProperties;
+
+/** Renders the top modal of the stack inside `backdrop`. */
+declare function ModalPort({ backdrop, render, container, onModalLaunch, onModalClose, onStackChange, }: ModalPortProps): react.JSX.Element | null;
+
+export { type FunctionKeys, type LaunchModal, type LaunchModalProps, type LaunchModalResolvers, type LaunchOptions, type LaunchRest, type ModalContextProperties, ModalContextProvider, type ModalHandle, ModalPort, type ModalPortProps, type ModalPortRenderProps, type ModalProps, ModalProvider, type ModalResolver, type ModalStackEntry, type ModalState, type Resolvers, type RestProps, type UpdateModalState, useModal, useModalContext, useModalStack, useModalState };