modalio 0.9.0

package/src/core.ts

@@ -0,0 +1,226 @@
+import type { ComponentType, Dispatch } from "react";
+import type {
+	DeferredPromise,
+	ModalAction,
+	ModalHocProps,
+	ModalRegistryEntry,
+	ModalStore,
+} from "./types";
+
+/** Symbol for storing modal IDs on component functions */
+const symModalId: unique symbol = Symbol("ModalManagerId");
+
+/** Type for components with attached modal ID */
+type ComponentWithModalId = ComponentType<Record<string, unknown>> & {
+	[symModalId]?: string;
+};
+
+// Initial empty state
+export const initialState: ModalStore = {};
+
+// Modal registry - maps IDs to component definitions
+export const MODAL_REGISTRY: Record<string, ModalRegistryEntry> = {};
+
+// Track already mounted modals for delayed visibility
+export const ALREADY_MOUNTED: Record<string, boolean> = {};
+
+/** Promise callbacks for modal open/close resolution */
+export const modalCallbacks: Record<string, DeferredPromise<unknown>> = {};
+export const hideModalCallbacks: Record<string, DeferredPromise<unknown>> = {};
+
+/**
+ * Cleanup all callbacks for a modal (prevents memory leaks)
+ */
+export const cleanupCallbacks = (modalId: string): void => {
+	delete modalCallbacks[modalId];
+	delete hideModalCallbacks[modalId];
+};
+
+/**
+ * Cleanup all callbacks (useful for testing or full reset)
+ */
+export const cleanupAllCallbacks = (): void => {
+	for (const key of Object.keys(modalCallbacks)) {
+		delete modalCallbacks[key];
+	}
+	for (const key of Object.keys(hideModalCallbacks)) {
+		delete hideModalCallbacks[key];
+	}
+};
+
+// UID counter for generating unique IDs
+let uidSeed = 0;
+
+/**
+ * Reset the UID seed (useful for SSR to prevent hydration mismatches)
+ * Call this on the server before rendering to ensure consistent IDs
+ * @internal
+ */
+export const resetUidSeed = (): void => {
+	uidSeed = 0;
+};
+
+// Note: If you need external store subscriptions, implement useSyncExternalStore support here
+
+// Global dispatch function - set by Provider
+let dispatchFn: Dispatch<ModalAction> = () => {
+	throw new Error(
+		"No dispatch method detected. Did you wrap your app with ModalManager.Provider?",
+	);
+};
+
+/**
+ * Generate a unique modal ID
+ */
+export const getUid = (): string => `_modal_${uidSeed++}`;
+
+/**
+ * Get the modal ID from a string or component
+ */
+export const getModalId = (
+	modal: string | ComponentType<Record<string, unknown>>,
+): string => {
+	if (typeof modal === "string") {
+		return modal;
+	}
+	const modalWithId = modal as ComponentWithModalId;
+	if (!modalWithId[symModalId]) {
+		modalWithId[symModalId] = getUid();
+	}
+	return modalWithId[symModalId];
+};
+
+/**
+ * Get a registered modal component by ID
+ */
+export const getModal = (
+	modalId: string,
+): ComponentType<ModalHocProps & Record<string, unknown>> | undefined => {
+	return MODAL_REGISTRY[modalId]?.comp;
+};
+
+/**
+ * Set the global dispatch function
+ */
+export const setDispatch = (fn: Dispatch<ModalAction>): void => {
+	dispatchFn = fn;
+};
+
+/**
+ * Get the current dispatch function
+ */
+export const getDispatch = (): Dispatch<ModalAction> => dispatchFn;
+
+/**
+ * Action creators
+ */
+export const actions = {
+	open: (modalId: string, data?: Record<string, unknown>): ModalAction => ({
+		type: "modalio/show",
+		payload: { modalId, data },
+	}),
+
+	close: (modalId: string): ModalAction => ({
+		type: "modalio/hide",
+		payload: { modalId },
+	}),
+
+	remove: (modalId: string): ModalAction => ({
+		type: "modalio/remove",
+		payload: { modalId },
+	}),
+
+	setFlags: (modalId: string, flags: Record<string, unknown>): ModalAction => ({
+		type: "modalio/set-flags",
+		payload: { modalId, flags },
+	}),
+};
+
+/**
+ * Reducer for modal state management
+ */
+export const reducer = (state: ModalStore, action: ModalAction): ModalStore => {
+	switch (action.type) {
+		case "modalio/show": {
+			const { modalId, data } = action.payload;
+			return {
+				...state,
+				[modalId]: {
+					...state[modalId],
+					modalId,
+					data,
+					// If already mounted, show immediately; otherwise delay
+					isOpen: !!ALREADY_MOUNTED[modalId],
+					delayOpen: !ALREADY_MOUNTED[modalId],
+				},
+			};
+		}
+
+		case "modalio/hide": {
+			const { modalId } = action.payload;
+			const modalState = state[modalId];
+			if (!modalState) {
+				return state;
+			}
+			return {
+				...state,
+				[modalId]: {
+					...modalState,
+					isOpen: false,
+				},
+			};
+		}
+
+		case "modalio/remove": {
+			const { modalId } = action.payload;
+			const newState = { ...state };
+			delete newState[modalId];
+			return newState;
+		}
+
+		case "modalio/set-flags": {
+			const { modalId, flags } = action.payload;
+			const existingState = state[modalId];
+			// Only set flags if the modal exists
+			if (!existingState) {
+				return state;
+			}
+			return {
+				...state,
+				[modalId]: {
+					...existingState,
+					...flags,
+				},
+			};
+		}
+
+		default:
+			return state;
+	}
+};
+
+/**
+ * Register a modal component
+ */
+export const register = (
+	id: string,
+	// biome-ignore lint/suspicious/noExplicitAny: component props vary
+	comp: ComponentType<any>,
+	props?: Record<string, unknown>,
+): void => {
+	if (MODAL_REGISTRY[id]) {
+		MODAL_REGISTRY[id].props = props;
+	} else {
+		MODAL_REGISTRY[id] = {
+			comp: comp as ComponentType<ModalHocProps & Record<string, unknown>>,
+			props,
+		};
+	}
+};
+
+/**
+ * Unregister a modal component
+ */
+export const unregister = (id: string): void => {
+	delete MODAL_REGISTRY[id];
+};

package/src/hoc.tsx

@@ -0,0 +1,114 @@
+import { type ComponentType, type Ref, useContext, useEffect } from "react";
+import { setFlags } from "./api";
+import { ModalContext, ModalIdContext } from "./context";
+import { ALREADY_MOUNTED } from "./core";
+import { useModal } from "./hooks";
+import type { ModalHocProps } from "./types";
+
+/** Props passed directly to the HOC wrapper */
+type HocOwnProps = ModalHocProps;
+
+/** Props for components that accept a ref (React 19+ style) */
+export interface RefProp<T> {
+	ref?: Ref<T>;
+}
+
+/**
+ * HOC to create a modal component with automatic registration and lifecycle management.
+ * Uses React 19's ref-as-prop pattern (no forwardRef needed).
+ *
+ * @example
+ * ```tsx
+ * interface MyModalProps {
+ *   title: string;
+ *   onSave: () => void;
+ * }
+ *
+ * const MyModal = createModal<MyModalProps>(({ title, onSave }) => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Dialog open={modal.open} onOpenChange={(open) => !open && modal.dismiss()}>
+ *       <DialogContent onAnimationEnd={modal.onAnimationEnd}>
+ *         <h2>{title}</h2>
+ *         <Button onClick={() => { onSave(); modal.close(); }}>Save</Button>
+ *       </DialogContent>
+ *     </Dialog>
+ *   );
+ * });
+ *
+ * // Usage
+ * open(MyModal, { data: { title: 'Edit Item', onSave: handleSave } });
+ * ```
+ */
+export const createModal = <
+	TProps extends Record<string, unknown> = Record<string, unknown>,
+	TRef = unknown,
+>(
+	Comp: ComponentType<TProps & RefProp<TRef>>,
+): ComponentType<TProps & HocOwnProps & RefProp<TRef>> => {
+	function WrappedComponent(allProps: TProps & HocOwnProps & RefProp<TRef>) {
+		// Extract HOC props
+		const { defaultOpen, keepMounted, modalId, ref, ...restProps } =
+			allProps as HocOwnProps & RefProp<TRef> & Record<string, unknown>;
+		const componentProps = restProps as TProps;
+
+		const { data, open: openModal } = useModal(modalId);
+		const modals = useContext(ModalContext);
+
+		// Only mount if this modal exists in the store
+		const shouldMount = modalId in modals;
+
+		// Handle default visibility and track mounted state
+		useEffect(() => {
+			if (defaultOpen) {
+				openModal();
+			}
+
+			ALREADY_MOUNTED[modalId] = true;
+
+			return () => {
+				delete ALREADY_MOUNTED[modalId];
+			};
+		}, [modalId, openModal, defaultOpen]);
+
+		// Handle keepMounted flag
+		useEffect(() => {
+			if (keepMounted) {
+				setFlags(modalId, { keepMounted: true });
+			}
+		}, [modalId, keepMounted]);
+
+		// Handle delayed visibility (for modals shown before mount)
+		const delayOpen = modals[modalId]?.delayOpen;
+		useEffect(() => {
+			if (delayOpen) {
+				openModal(data);
+			}
+		}, [delayOpen, data, openModal]);
+
+		if (!shouldMount) {
+			return null;
+		}
+
+		// Merge static props with dynamic data from open()
+		const mergedProps: TProps & RefProp<TRef> = {
+			...componentProps,
+			...(data as Partial<TProps>),
+			ref,
+		};
+
+		return (
+			<ModalIdContext.Provider value={modalId}>
+				<Comp {...mergedProps} />
+			</ModalIdContext.Provider>
+		);
+	}
+
+	// Copy display name for debugging
+	WrappedComponent.displayName = `ModalManager(${
+		Comp.displayName || Comp.name || "Component"
+	})`;
+
+	return WrappedComponent;
+};

package/src/hooks.ts

@@ -0,0 +1,250 @@
+import { useCallback, useContext, useEffect, useMemo, useRef } from "react";
+import {
+	closeModal,
+	markClosed,
+	notifyOpened,
+	openModal,
+	removeModal,
+} from "./api";
+import { ModalContext, ModalIdContext } from "./context";
+import {
+	getModalId,
+	hideModalCallbacks,
+	MODAL_REGISTRY,
+	modalCallbacks,
+	register,
+} from "./core";
+import type { ModalHandler, ModalHocProps, ModalProps } from "./types";
+import { type InternalModalConfig, MODAL_CONFIG_KEY } from "./types";
+
+/**
+ * Hook to control a modal from within the modal component or from anywhere.
+ * Returns an enhanced handler with state and control methods.
+ *
+ * @example
+ * ```tsx
+ * // Inside a modal component (uses context)
+ * const modal = useModal();
+ *
+ * return (
+ *   <Dialog open={modal.open} onOpenChange={(open) => !open && modal.dismiss()}>
+ *     <DialogContent onAnimationEnd={modal.onAnimationEnd}>
+ *       <Button onClick={() => modal.close(result)}>Save</Button>
+ *       <Button onClick={modal.dismiss}>Cancel</Button>
+ *     </DialogContent>
+ *   </Dialog>
+ * );
+ *
+ * // With a specific modal component
+ * const modal = useModal(MyModal);
+ * modal.open({ userId: '123' });
+ *
+ * // With a string ID
+ * const modal = useModal('my-modal');
+ * ```
+ */
+
+export function useModal(
+	modal?: string,
+	data?: Record<string, unknown>,
+): ModalHandler;
+
+export function useModal<
+	TProps extends Record<string, unknown>,
+	P extends Partial<ModalProps<React.ComponentType<TProps & ModalHocProps>>>,
+>(
+	modal: React.ComponentType<TProps & ModalHocProps>,
+	data?: P,
+): ModalHandler<TProps>;
+
+export function useModal(
+	// biome-ignore lint/suspicious/noExplicitAny: component props vary
+	modal?: React.ComponentType<any> | string,
+	initialData?: Record<string, unknown>,
+): ModalHandler {
+	const modals = useContext(ModalContext);
+	const contextModalId = useContext(ModalIdContext);
+
+	// Determine modal ID - from argument or context
+	const modalId = modal ? getModalId(modal) : contextModalId;
+
+	if (!modalId) {
+		throw new Error(
+			"[ModalManager] No modal id found in useModal. " +
+				"Either pass a modal component/id or use inside a modal component.",
+		);
+	}
+
+	// Check if modal argument is a component reference (not a string ID)
+	// Note: ForwardRefExoticComponent is an object, not a function
+	const isComponentRef = modal !== undefined && typeof modal !== "string";
+
+	// Register component if passed and not already registered
+	useEffect(() => {
+		if (isComponentRef && !MODAL_REGISTRY[modalId]) {
+			register(
+				modalId,
+				modal as React.ComponentType<Record<string, unknown>>,
+				initialData,
+			);
+		}
+	}, [isComponentRef, modalId, modal, initialData]);
+
+	const modalInfo = modals[modalId];
+
+	// Use refs to avoid stale closures in animation handlers
+	const modalInfoRef = useRef(modalInfo);
+	useEffect(() => {
+		modalInfoRef.current = modalInfo;
+	}, [modalInfo]);
+
+	// Memoized control methods
+	const openCallback = useCallback(
+		(data?: Record<string, unknown>) => {
+			const ref = openModal(modalId, { data });
+			return ref.afterClosed();
+		},
+		[modalId],
+	);
+
+	const closeCallback = useCallback(
+		(result?: unknown) => {
+			modalCallbacks[modalId]?.resolve(result);
+			delete modalCallbacks[modalId];
+			closeModal(modalId);
+		},
+		[modalId],
+	);
+
+	const dismissCallback = useCallback(() => {
+		modalCallbacks[modalId]?.resolve(undefined);
+		delete modalCallbacks[modalId];
+		closeModal(modalId);
+	}, [modalId]);
+
+	const removeCallback = useCallback(() => removeModal(modalId), [modalId]);
+
+	// Animation completion handler
+	const onAnimationEnd = useCallback(() => {
+		const current = modalInfoRef.current;
+
+		if (current?.isOpen) {
+			// Modal is opening - notify afterOpened promise
+			notifyOpened(modalId);
+		} else {
+			// Modal is closing - mark as fully closed
+			markClosed(modalId);
+
+			// Resolve close promise when closing animation completes
+			hideModalCallbacks[modalId]?.resolve(undefined);
+			delete hideModalCallbacks[modalId];
+
+			// Remove if not keepMounted (use ref for latest value)
+			if (!current?.keepMounted) {
+				removeModal(modalId);
+			}
+		}
+	}, [modalId]);
+
+	return useMemo(
+		() => ({
+			// State
+			modalId,
+			data: modalInfo?.data,
+			isOpen: !!modalInfo?.isOpen,
+			keepMounted: !!modalInfo?.keepMounted,
+			// Controls
+			open: openCallback,
+			close: closeCallback,
+			dismiss: dismissCallback,
+			remove: removeCallback,
+			// Animation handler
+			onAnimationEnd,
+		}),
+		[
+			modalId,
+			modalInfo?.data,
+			modalInfo?.isOpen,
+			modalInfo?.keepMounted,
+			openCallback,
+			closeCallback,
+			dismissCallback,
+			removeCallback,
+			onAnimationEnd,
+		],
+	);
+}
+
+/**
+ * Hook to get typed data passed to a modal
+ * Must be used inside a modal component (within ModalIdContext)
+ *
+ * @example
+ * ```tsx
+ * interface MyModalData {
+ *   userId: string;
+ *   userName: string;
+ * }
+ *
+ * const MyModal = createModal(() => {
+ *   const data = useModalData<MyModalData>();
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Dialog open={modal.open}>
+ *       <DialogContent>
+ *         <p>User: {data?.userName}</p>
+ *       </DialogContent>
+ *     </Dialog>
+ *   );
+ * });
+ *
+ * // Usage:
+ * open(MyModal, { data: { userId: '123', userName: 'John' } });
+ * ```
+ */
+export function useModalData<TData = Record<string, unknown>>():
+	| TData
+	| undefined {
+	const modals = useContext(ModalContext);
+	const modalId = useContext(ModalIdContext);
+
+	if (!modalId) {
+		throw new Error(
+			"[ModalManager] useModalData must be used inside a modal component. " +
+				"Make sure you're using createModal() to wrap your modal.",
+		);
+	}
+
+	const modalInfo = modals[modalId];
+	const data = modalInfo?.data;
+
+	// Filter out internal modal config from user data
+	if (!data) {
+		return undefined;
+	}
+	const { [MODAL_CONFIG_KEY]: _, ...userData } = data;
+	return userData as TData;
+}
+
+/**
+ * Hook to get the modal config options (disableClose, keepMounted, etc.)
+ * Must be used inside a modal component
+ */
+export function useModalConfig(): InternalModalConfig {
+	const modals = useContext(ModalContext);
+	const modalId = useContext(ModalIdContext);
+
+	if (!modalId) {
+		throw new Error(
+			"[ModalManager] useModalConfig must be used inside a modal component.",
+		);
+	}
+
+	const modalInfo = modals[modalId];
+	const config = modalInfo?.data?.[MODAL_CONFIG_KEY] as
+		| InternalModalConfig
+		| undefined;
+
+	return config ?? {};
+}

package/src/index.ts

@@ -0,0 +1,81 @@
+// Primary API - ModalManager namespace
+
+// Re-export adapter types
+export type {
+	AdapterOptions,
+	BaseUiDialogPopupProps,
+	BaseUiDialogPortalProps,
+	BaseUiDialogRootProps,
+	BaseUiPopoverPopupProps,
+	BaseUiPopoverPortalProps,
+	BaseUiPopoverRootProps,
+	ShadcnUiDrawerContentProps,
+	ShadcnUiDrawerRootProps,
+} from "./adapters";
+// Re-export adapters
+export {
+	// Base UI adapters
+	baseUiAlertDialog,
+	baseUiAlertDialogPopup,
+	baseUiAlertDialogPortal,
+	baseUiDialog,
+	baseUiDialogPopup,
+	baseUiDialogPortal,
+	// Base UI Popover adapters
+	baseUiPopover,
+	baseUiPopoverPopup,
+	baseUiPopoverPortal,
+	// Base UI Sheet adapters
+	baseUiSheet,
+	baseUiSheetPopup,
+	baseUiSheetPortal,
+	// Radix UI adapters
+	radixUiAlertDialog,
+	radixUiAlertDialogContent,
+	radixUiDialog,
+	radixUiDialogContent,
+	radixUiPopover,
+	radixUiSheet,
+	radixUiSheetContent,
+	// Shadcn adapters
+	shadcnUiAlertDialog,
+	shadcnUiAlertDialogContent,
+	shadcnUiDialog,
+	shadcnUiDialogContent,
+	shadcnUiDrawer,
+	shadcnUiDrawerContent,
+	shadcnUiPopover,
+	shadcnUiSheet,
+	shadcnUiSheetContent,
+} from "./adapters";
+// Re-export context (for advanced usage)
+export { ModalContext, ModalIdContext } from "./context";
+// Re-export core utilities (for advanced usage)
+export { getModalId, reducer } from "./core";
+// Re-export hooks
+export { useModal, useModalConfig, useModalData } from "./hooks";
+export { ModalManager } from "./modal-manager";
+// Re-export types
+export type {
+	DeferredPromise,
+	InternalModalConfig,
+	ModalAction,
+	ModalActionType,
+	ModalAnimationHandlers,
+	ModalConfig,
+	ModalControls,
+	ModalHandler,
+	ModalHocProps,
+	ModalLifecycleState,
+	ModalProps,
+	ModalProviderProps,
+	ModalReadState,
+	ModalRef,
+	ModalState,
+	ModalStore,
+	RadixDialogContentProps,
+	RadixDialogProps,
+	ShadcnDialogProps,
+} from "./types";
+// Re-export constants
+export { MODAL_CONFIG_KEY } from "./types";