fine-modal-react 0.0.0

package/README.md

@@ -0,0 +1,123 @@
+# Fine Modal React
+
+Typed, promise-based modals for React 19+ with two mounting strategies: a global host or colocated modal components.
+
+## Installation
+
+```bash
+npm install fine-modal-react
+# or
+pnpm add fine-modal-react
+```
+
+Peer deps: `react` and `react-dom` (19.x).
+
+## Define a modal (shared for both strategies)
+
+```tsx
+import { FineModal } from 'fine-modal-react'
+
+export const ConfirmInviteModal = FineModal.define({
+  id: 'ConfirmInviteModal',
+  component: ({ initialProps, onConfirm, onCancel }: {
+    initialProps: { email: string }
+    onConfirm: (value: 'sent') => void
+    onCancel: () => void
+  }) => (
+    <section>
+      <p>Send an invite to {initialProps.email}?</p>
+      <div>
+        <button type="button" onClick={() => onConfirm('sent')}>Send</button>
+        <button type="button" onClick={onCancel}>Cancel</button>
+      </div>
+    </section>
+  ),
+})
+
+export const modals = [ConfirmInviteModal] as const
+```
+
+### (Optional) TypeScript registration for typed `open`
+
+```ts
+import type { modals } from './modals'
+
+declare module 'fine-modal-react' {
+  interface Register {
+    readonly modals?: typeof modals
+  }
+}
+```
+
+## Option A: Global host (central place for all modals)
+
+Use a single `ModalHost` near the app root. Open modals anywhere via their string id.
+
+```tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { FineModal } from 'fine-modal-react'
+import App from './app'
+import { modals } from './modals'
+
+const ModalHost = FineModal.createHost({ modals })
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+    <ModalHost />
+  </StrictMode>
+)
+```
+
+```tsx
+// anywhere in the tree
+import { FineModal } from 'fine-modal-react'
+
+export function App() {
+  const handleInvite = async () => {
+    const result = await FineModal.open('ConfirmInviteModal', {
+      email: 'teammate@company.com',
+    })
+
+    if (result === 'sent') {
+      console.log('Invite sent')
+    } else {
+      console.log('Invite cancelled')
+    }
+  }
+
+  return <button onClick={handleInvite}>Invite teammate</button>
+}
+```
+
+## Option B: Local modal component (colocated scope)
+
+Render the modal component where you need it; open it via its static API. This avoids a global host if you only need the modal in one subtree.
+
+```tsx
+import { ConfirmInviteModal } from './modals'
+
+export function App() {
+  const handleInvite = async () => {
+    const result = await ConfirmInviteModal.open({ email: 'new.user@org.com' })
+    if (result === 'sent') {
+      console.log('Invite sent')
+    }
+  }
+
+  return (
+    <>
+      <button onClick={handleInvite}>Invite teammate</button>
+      <ConfirmInviteModal />
+    </>
+  )
+}
+```
+
+## Modal authoring notes
+
+- `onConfirm(value)` resolves the promise returned by `open` with `value`.
+- `onCancel()` resolves the promise with `null` and closes the modal.
+- If your modal needs initial props, add an `initialProps` field to the component props; `open` will require/accept that shape.
+- `FineModal.open` automatically closes an existing modal with the same id before opening a new one.

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import React from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/index.d.ts
+interface ModalStatics<Id extends string, InitialProps, Result> {
+  id: Id;
+  open: (...args: [InitialProps] extends [void] ? [] : [InitialProps] extends [undefined] ? [] : [props: InitialProps]) => Promise<Result | null>;
+  close: () => void;
+}
+type ExtractInitialProps<C> = C extends React.ComponentType<infer P> ? P extends {
+  initialProps: infer IP;
+} ? IP : never : never;
+type ExtractResult<C> = C extends React.ComponentType<infer P> ? P extends {
+  onConfirm: (value: infer R) => any;
+} ? R : never : never;
+interface Register {}
+type GetProp<T, K extends PropertyKey> = K extends keyof T ? T[K] : never;
+type RegisteredModals = NonNullable<GetProp<Register, 'modals'>> extends readonly unknown[] ? NonNullable<GetProp<Register, 'modals'>>[number] : never;
+type ModalMap = { [M in RegisteredModals as M extends {
+  id: infer N;
+} ? N extends string ? N : never : never]: M };
+type RegisteredIds = keyof ModalMap;
+type PropsById<N extends RegisteredIds> = ModalMap[N] extends {
+  open: (p: infer P) => any;
+} ? P : never;
+type ResultById<N extends RegisteredIds> = ModalMap[N] extends {
+  open: (...a: any[]) => Promise<infer R>;
+} ? R : never;
+type PropsArg<N extends RegisteredIds> = [PropsById<N>] extends [never] ? [] : [undefined] extends [PropsById<N>] ? [] : [void] extends [PropsById<N>] ? [] : [props: PropsById<N>];
+type AnyModal = React.FC<any> & {
+  id: string;
+};
+interface CreateHostOptions {
+  modals: readonly AnyModal[];
+}
+declare const obj: {
+  open<N extends RegisteredIds>(id: N, ...args: PropsArg<N>): Promise<ResultById<N>>;
+  close<N extends RegisteredIds>(id: string, value: ResultById<N> | null): void;
+} & {
+  define: <const Id extends string, C extends React.ComponentType<any>>(options: {
+    id: Id;
+    component: C;
+  }) => ((props: Omit<React.ComponentProps<C>, "initialProps" | "onConfirm" | "onCancel">) => false | react_jsx_runtime0.JSX.Element) & ModalStatics<Id, ExtractInitialProps<C>, ExtractResult<C>>;
+  createHost: (options: CreateHostOptions) => () => react_jsx_runtime0.JSX.Element[];
+};
+//#endregion
+export { obj as FineModal, Register };

package/dist/index.js

@@ -0,0 +1,88 @@
+import React, { useCallback, useMemo, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/index.tsx
+const createStore = () => {
+	let listeners = [];
+	const store$1 = {
+		modals: {},
+		subscribe: (cb) => {
+			listeners.push(cb);
+			return () => {
+				listeners = listeners.filter((listener) => listener !== cb);
+			};
+		},
+		getSnapshot: () => store$1.modals,
+		open: (id, props) => {
+			store$1.modals = {
+				...store$1.modals,
+				[id]: props
+			};
+			listeners.forEach((cb) => cb());
+		},
+		close: (id) => {
+			const { [id]: _removed, ...rest } = store$1.modals;
+			store$1.modals = rest;
+			listeners.forEach((cb) => cb());
+		}
+	};
+	return store$1;
+};
+const store = createStore();
+const resolves = {};
+const FineModal = {
+	open: (id, props) => new Promise((r) => {
+		if (resolves[id]) FineModal.close(id, null);
+		resolves[id] = r;
+		store.open(id, props);
+	}),
+	close: (id, value = null) => {
+		resolves[id]?.(value);
+		store.close(id);
+		delete resolves[id];
+	}
+};
+const define = (options) => {
+	const Modal = (props) => {
+		const snap = useSyncExternalStore(store.subscribe, store.getSnapshot);
+		const id = options.id;
+		const initialProps = snap[id];
+		const handleConfirm = useCallback((value) => {
+			FineModal.close(id, value);
+		}, [id]);
+		const handleCancel = useCallback(() => {
+			FineModal.close(id, null);
+		}, [id]);
+		return initialProps !== null && /* @__PURE__ */ jsx(options.component, {
+			...props,
+			initialProps,
+			onConfirm: handleConfirm,
+			onCancel: handleCancel
+		});
+	};
+	return Object.assign(Modal, {
+		id: options.id,
+		open: (...args) => FineModal.open(options.id, args[0] ?? {}),
+		close: () => FineModal.close(options.id, null)
+	});
+};
+const createHost = (options) => {
+	const modalsMap = options.modals.reduce((acc, modal) => ({
+		...acc,
+		[modal.id]: modal
+	}), {});
+	return function ModalHost() {
+		const snap = useSyncExternalStore(store.subscribe, store.getSnapshot);
+		return useMemo(() => Object.entries(snap).filter(([id]) => id in modalsMap), [snap]).map(([id, props]) => {
+			const Modal = modalsMap[id];
+			return /* @__PURE__ */ jsx(Modal, { initialProps: props }, id);
+		});
+	};
+};
+const obj = Object.assign(FineModal, {
+	define,
+	createHost
+});
+
+//#endregion
+export { obj as FineModal };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "fine-modal-react",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "Typed, promise-based modal utilities for React 19+.",
+  "author": "lorof",
+  "license": "MIT",
+  "homepage": "https://github.com/lorof/fine-modal-react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lorof/fine-modal-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lorof/fine-modal-react/issues"
+  },
+  "keywords": [
+    "react",
+    "modal",
+    "dialog",
+    "typescript",
+    "promise"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown ./src/index.tsx",
+    "dev": "tsdown --watch",
+    "play": "vite",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp && npm publish",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@tsconfig/strictest": "^2.0.8",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "@vitest/browser-playwright": "^4.0.16",
+    "bumpp": "^10.3.2",
+    "tsdown": "^0.18.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16",
+    "vitest-browser-react": "^2.0.2"
+  }
+}