@lcashe/react-modal-controller 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zakharov Vladyslav
+
+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/README.md

@@ -0,0 +1,340 @@
+# react-modal-controller
+
+Tiny and type-safe modal controller for React and Next.js.
+
+- No global modal registry
+- No reducers
+- No boilerplate
+- Full TypeScript inference
+
+---
+
+# Navigation
+
+- [Installation](#installation)
+- [React Setup](#react-setup)
+- [Next.js Setup](#nextjs-setup)
+- [Important](#important)
+- [Simple Example](#simple-example)
+- [Modal With Props](#modal-with-props)
+- [Dynamic Initial Props](#dynamic-initial-props)
+- [Auto Close Example](#auto-close-example)
+- [Multiple Modals](#multiple-modals)
+- [API](#api)
+
+---
+
+# Installation
+
+```bash
+npm install @lcashe/react-modal-controller
+```
+
+---
+
+# React Setup
+
+Wrap your application with `ModalScope`.
+
+```tsx
+import ReactDOM from 'react-dom/client';
+
+import { ModalScope } from '@lcashe/react-modal-controller';
+
+import { App } from './app';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+   <ModalScope>
+      <App />
+   </ModalScope>,
+);
+```
+
+---
+
+# Next.js Setup
+
+`app/layout.tsx`
+
+```tsx
+import { ModalScope } from '@lcashe/react-modal-controller';
+
+export default function Page() {
+   return <ModalScope>// PAGE CONTENT</ModalScope>;
+}
+```
+
+---
+
+# Important
+
+Your modal component must accept:
+
+```ts
+opened: boolean;
+onClose: VoidFunction;
+```
+
+Optional:
+
+```ts
+onExited?: VoidFunction;
+```
+
+Example:
+
+```tsx
+type ModalProps = {
+   opened: boolean;
+   title: string;
+   onClose: VoidFunction;
+};
+```
+
+---
+
+# Simple Example
+
+## Modal
+
+```tsx
+'use client';
+
+
+type ModalProps = {
+   opened: boolean;
+   onClose: VoidFunction;
+};
+
+export const Modal = ({ opened, onClose }: ModalProps) => {
+   if (!opened) {
+      return null;
+   }
+
+   return (
+      <div>
+         <h1>Modal</h1>
+
+         <button onClick={onClose}>Close</button>
+      </div>
+   );
+};
+```
+
+## Usage
+
+```tsx
+'use client';
+
+import { useModalController } from '@lcashe/react-modal-controller';
+
+import { Modal } from './modal';
+
+export const Component = () => {
+   const modal = useModalController(Modal);
+
+   return <button onClick={() => modal.open()}>Open modal</button>;
+};
+```
+
+---
+
+# Modal With Props
+
+## Modal
+
+```tsx
+'use client';
+
+type ModalProps = {
+   opened: boolean;
+   title: string;
+   onClose: VoidFunction;
+};
+
+export const Modal = ({ title, opened, onClose }: ModalProps) => {
+   if (!opened) {
+      return null;
+   }
+
+   return (
+      <div>
+         <h1>{title}</h1>
+
+         <button onClick={onClose}>Close</button>
+      </div>
+   );
+};
+```
+
+## Usage
+
+```tsx
+'use client';
+
+import { useModalController } from '@lcashe/react-modal-controller';
+
+import { Modal } from './modal';
+
+export const Component = () => {
+   const modal = useModalController(Modal, {
+      title: 'Initial title',
+   });
+
+   return (
+      <button
+         onClick={() =>
+            modal.open({
+               title: 'Another title', // optional
+            })
+         }
+      >
+         Open modal
+      </button>
+   );
+};
+```
+
+---
+
+# TypeScript Inference
+
+Props are inferred automatically.
+
+```tsx
+modal.open({
+   title: 'Example title',
+});
+```
+
+Autocomplete works out of the box.
+
+---
+
+# Dynamic Initial Props
+
+`initialProps` stay synchronized automatically.
+
+```tsx
+const modal = useModalController(Modal, {
+   title,
+});
+```
+
+When `title` changes, the next `open()` call will use the latest value.
+
+---
+
+# Auto Close Example
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+
+import { useModalController } from '@lcashe/react-modal-controller';
+
+import { Modal } from './modal';
+
+export const Component = () => {
+   const modal = useModalController(Modal);
+
+   useEffect(() => {
+      modal.open();
+
+      const timeoutId = setTimeout(() => {
+         modal.close();
+      }, 2000);
+
+      return () => {
+         clearTimeout(timeoutId);
+      };
+   }, [modal]);
+
+   return null;
+};
+```
+
+---
+
+# Multiple Modals
+
+```tsx
+const firstModal = useModalController(FirstModal);
+
+const secondModal = useModalController(SecondModal);
+
+const thirdModal = useModalController(ThirdModal);
+```
+
+---
+
+# Multiple Same Modals
+
+Each `useModalController` call creates its own local modal instance.
+
+Even if you pass the same modal component, every controller receives a unique internal id, so the modals are controlled separately.
+
+```tsx
+const firstModal = useModalController(Modal);
+
+const secondModal = useModalController(Modal);
+
+...
+
+secondModal.open() // <-- will open only the second modal
+```
+
+---
+
+# API
+
+## `useModalController(Component, initialProps?)`
+
+Returns:
+
+```ts
+{
+   open,
+   close,
+   remove,
+}
+```
+
+## `open(props?)`
+
+Open modal with optional props.
+
+```tsx
+modal.open();
+
+modal.open({
+   title: 'New title',
+});
+```
+
+---
+
+## `close()`
+
+Close modal.
+
+```tsx
+modal.close();
+```
+
+---
+
+## `remove()`
+
+Remove modal from the store completely.
+
+```tsx
+modal.remove();
+```
+
+---
+
+# License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var M=Object.defineProperty,b=Object.defineProperties,j=Object.getOwnPropertyDescriptor,S=Object.getOwnPropertyDescriptors,h=Object.getOwnPropertyNames,I=Object.getOwnPropertySymbols;var v=Object.prototype.hasOwnProperty,k=Object.prototype.propertyIsEnumerable;var T=(t,e,o)=>e in t?M(t,e,{enumerable:!0,configurable:!0,writable:!0,value:o}):t[e]=o,m=(t,e)=>{for(var o in e||(e={}))v.call(e,o)&&T(t,o,e[o]);if(I)for(var o of I(e))k.call(e,o)&&T(t,o,e[o]);return t},C=(t,e)=>b(t,S(e));var g=(t,e)=>{for(var o in e)M(t,o,{get:e[o],enumerable:!0})},V=(t,e,o,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let p of h(e))!v.call(t,p)&&p!==o&&M(t,p,{get:()=>e[p],enumerable:!(r=j(e,p))||r.enumerable});return t};var w=t=>V(M({},"__esModule",{value:!0}),t);var W={};g(W,{ModalContext:()=>i,ModalScope:()=>N,useModalController:()=>R});module.exports=w(W);var a=require("react");var E=require("react"),i=(0,E.createContext)(null);var u=require("react/jsx-runtime"),N=({children:t})=>{let[e,o]=(0,a.useState)([]),r=(0,a.useCallback)(l=>{let d={id:l.id,opened:!0,Component:l.Component,props:l.props};o(n=>{let x=n.findIndex(y=>y.id===l.id);if(x===-1)return[...n,d];let f=[...n];return f[x]=d,f})},[]),p=(0,a.useCallback)(l=>{o(d=>d.map(n=>n.id===l?C(m({},n),{opened:!1}):n))},[]),c=(0,a.useCallback)(l=>{o(d=>d.filter(n=>n.id!==l))},[]),P=(0,a.useMemo)(()=>({open:r,close:p,remove:c}),[r,p,c]);return(0,u.jsxs)(i.Provider,{value:P,children:[t,e.map(({Component:l,id:d,opened:n,props:x})=>(0,u.jsx)(l,C(m({},x),{opened:n,onClose:()=>p(d),onExited:()=>c(d)}),d))]})};var s=require("react");var R=(t,e)=>{let o=(0,s.useContext)(i);if(!o)throw new Error("useModalController must be used inside <ModalScope>");let r=(0,s.useId)(),p=(0,s.useRef)(e);(0,s.useEffect)(()=>{p.current=e},[e]),(0,s.useEffect)(()=>()=>{o.remove(r)},[o,r]);let c=(0,s.useCallback)(d=>{let n=m(m({},p.current||{}),d||{});o.open({id:r,Component:t,props:n})},[o,r,t]),P=(0,s.useCallback)(()=>{o.close(r)},[o,r]),l=(0,s.useCallback)(()=>{o.remove(r)},[o,r]);return{open:c,close:P,remove:l}};0&&(module.exports={ModalContext,ModalScope,useModalController});

package/dist/index.d.cts

@@ -0,0 +1,42 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { PropsWithChildren, ComponentType } from 'react';
+
+declare const ModalScope: ({ children }: PropsWithChildren) => react_jsx_runtime.JSX.Element;
+
+type Nullable<T> = T | null;
+type Maybe<T> = T | undefined;
+type ModalInjectedProps = {
+    opened: boolean;
+    onClose: VoidFunction;
+    onExited?: VoidFunction;
+};
+type ModalComponent<TProps extends object = object> = ComponentType<TProps & ModalInjectedProps>;
+type ExternalModalProps$1<TComponent> = TComponent extends ComponentType<infer TProps> ? Omit<TProps, keyof ModalInjectedProps> : never;
+type ModalItem<TProps extends object = object> = {
+    id: string;
+    Component: ModalComponent<TProps>;
+    props: TProps;
+};
+type StoredModalItem = {
+    id: string;
+    opened: boolean;
+    props: object;
+    Component: ComponentType<object & ModalInjectedProps>;
+};
+
+type ExternalModalProps<TProps extends ModalInjectedProps> = Omit<TProps, keyof ModalInjectedProps>;
+declare const useModalController: <TProps extends ModalInjectedProps>(Component: ComponentType<TProps>, initialProps?: ExternalModalProps<TProps>) => {
+    open: (props?: Partial<ExternalModalProps<TProps>>) => void;
+    close: () => void;
+    remove: () => void;
+};
+
+type ModalContextValue = {
+    open: <TProps extends object>(item: ModalItem<TProps>) => void;
+    close: (id: string) => void;
+    remove: (id: string) => void;
+};
+declare const ModalContext: react.Context<Nullable<ModalContextValue>>;
+
+export { type ExternalModalProps$1 as ExternalModalProps, type Maybe, type ModalComponent, ModalContext, type ModalContextValue, type ModalInjectedProps, type ModalItem, ModalScope, type Nullable, type StoredModalItem, useModalController };

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { PropsWithChildren, ComponentType } from 'react';
+
+declare const ModalScope: ({ children }: PropsWithChildren) => react_jsx_runtime.JSX.Element;
+
+type Nullable<T> = T | null;
+type Maybe<T> = T | undefined;
+type ModalInjectedProps = {
+    opened: boolean;
+    onClose: VoidFunction;
+    onExited?: VoidFunction;
+};
+type ModalComponent<TProps extends object = object> = ComponentType<TProps & ModalInjectedProps>;
+type ExternalModalProps$1<TComponent> = TComponent extends ComponentType<infer TProps> ? Omit<TProps, keyof ModalInjectedProps> : never;
+type ModalItem<TProps extends object = object> = {
+    id: string;
+    Component: ModalComponent<TProps>;
+    props: TProps;
+};
+type StoredModalItem = {
+    id: string;
+    opened: boolean;
+    props: object;
+    Component: ComponentType<object & ModalInjectedProps>;
+};
+
+type ExternalModalProps<TProps extends ModalInjectedProps> = Omit<TProps, keyof ModalInjectedProps>;
+declare const useModalController: <TProps extends ModalInjectedProps>(Component: ComponentType<TProps>, initialProps?: ExternalModalProps<TProps>) => {
+    open: (props?: Partial<ExternalModalProps<TProps>>) => void;
+    close: () => void;
+    remove: () => void;
+};
+
+type ModalContextValue = {
+    open: <TProps extends object>(item: ModalItem<TProps>) => void;
+    close: (id: string) => void;
+    remove: (id: string) => void;
+};
+declare const ModalContext: react.Context<Nullable<ModalContextValue>>;
+
+export { type ExternalModalProps$1 as ExternalModalProps, type Maybe, type ModalComponent, ModalContext, type ModalContextValue, type ModalInjectedProps, type ModalItem, ModalScope, type Nullable, type StoredModalItem, useModalController };

package/dist/index.js

@@ -0,0 +1 @@
+var v=Object.defineProperty,E=Object.defineProperties;var y=Object.getOwnPropertyDescriptors;var C=Object.getOwnPropertySymbols;var b=Object.prototype.hasOwnProperty,j=Object.prototype.propertyIsEnumerable;var f=(t,e,o)=>e in t?v(t,e,{enumerable:!0,configurable:!0,writable:!0,value:o}):t[e]=o,d=(t,e)=>{for(var o in e||(e={}))b.call(e,o)&&f(t,o,e[o]);if(C)for(var o of C(e))j.call(e,o)&&f(t,o,e[o]);return t},x=(t,e)=>E(t,y(e));import{useCallback as M,useMemo as h,useState as k}from"react";import{createContext as S}from"react";var c=S(null);import{jsx as g,jsxs as V}from"react/jsx-runtime";var G=({children:t})=>{let[e,o]=k([]),p=M(n=>{let s={id:n.id,opened:!0,Component:n.Component,props:n.props};o(r=>{let m=r.findIndex(T=>T.id===n.id);if(m===-1)return[...r,s];let P=[...r];return P[m]=s,P})},[]),l=M(n=>{o(s=>s.map(r=>r.id===n?x(d({},r),{opened:!1}):r))},[]),a=M(n=>{o(s=>s.filter(r=>r.id!==n))},[]),i=h(()=>({open:p,close:l,remove:a}),[p,l,a]);return V(c.Provider,{value:i,children:[t,e.map(({Component:n,id:s,opened:r,props:m})=>g(n,x(d({},m),{opened:r,onClose:()=>l(s),onExited:()=>a(s)}),s))]})};import{useCallback as u,useContext as w,useEffect as I,useId as N,useRef as R}from"react";var X=(t,e)=>{let o=w(c);if(!o)throw new Error("useModalController must be used inside <ModalScope>");let p=N(),l=R(e);I(()=>{l.current=e},[e]),I(()=>()=>{o.remove(p)},[o,p]);let a=u(s=>{let r=d(d({},l.current||{}),s||{});o.open({id:p,Component:t,props:r})},[o,p,t]),i=u(()=>{o.close(p)},[o,p]),n=u(()=>{o.remove(p)},[o,p]);return{open:a,close:i,remove:n}};export{c as ModalContext,G as ModalScope,X as useModalController};

package/package.json

@@ -0,0 +1,34 @@
+{
+   "name": "@lcashe/react-modal-controller",
+   "version": "1.0.0",
+   "description": "Tiny type-safe modal controller for React with inferred props and no registry.",
+   "license": "MIT",
+   "type": "module",
+   "main": "./dist/index.cjs",
+   "module": "./dist/index.js",
+   "types": "./dist/index.d.ts",
+   "files": [
+      "dist",
+      "README.md"
+   ],
+   "scripts": {
+      "build": "tsup components/modal-controller/index.ts --format esm,cjs --dts --minify --external react --tsconfig tsconfig.build.json",
+      "dev": "tsup components/modal-controller/index.ts --format esm,cjs --dts --watch --external react --tsconfig tsconfig.build.json",
+      "prepublishOnly": "npm run build"
+   },
+   "keywords": [
+      "react",
+      "modal",
+      "modal-controller",
+      "typescript",
+      "nextjs"
+   ],
+   "peerDependencies": {
+      "react": ">=18"
+   },
+   "devDependencies": {
+      "@types/react": "^19",
+      "tsup": "latest",
+      "typescript": "^5"
+   }
+}