universal-modal-monorepo 1.0.0

package/packages/universal-modal-react/src/UniversalModal.tsx

@@ -0,0 +1,340 @@
+import {
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+import {
+  CSS_CLASSES,
+  ModalEngine,
+  type CloseReason,
+  type ModalOptions,
+  type ModalPlacement,
+  type ModalRole,
+  type ModalSize,
+  type ModalTheme,
+} from '@poluru-labs/universal-modal';
+
+export interface UniversalModalProps {
+  open: boolean;
+  onOpenChange?: (open: boolean) => void;
+  size?: ModalSize;
+  placement?: ModalPlacement;
+  title?: string;
+  description?: string;
+  persistent?: boolean;
+  closeOnEsc?: boolean;
+  closeOnBackdrop?: boolean;
+  showCloseIcon?: boolean;
+  role?: ModalRole;
+  confirmText?: string;
+  cancelText?: string;
+  hideActions?: boolean;
+  loading?: boolean;
+  zIndexBase?: number;
+  className?: string;
+  style?: CSSProperties;
+  theme?: ModalTheme;
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
+  ariaDescribedBy?: string;
+  children?: ReactNode;
+  header?: ReactNode;
+  footer?: ReactNode;
+  onConfirm?: () => void | Promise<void>;
+  onCancel?: () => void | Promise<void>;
+  beforeOpen?: ModalOptions['beforeOpen'];
+  afterOpen?: ModalOptions['afterOpen'];
+  beforeClose?: ModalOptions['beforeClose'];
+  afterClose?: ModalOptions['afterClose'];
+}
+
+export function UniversalModal({
+  open,
+  onOpenChange,
+  size = 'md',
+  placement = 'center',
+  title,
+  description,
+  persistent = false,
+  closeOnEsc = true,
+  closeOnBackdrop = true,
+  showCloseIcon = true,
+  role = 'dialog',
+  confirmText = 'Confirm',
+  cancelText = 'Cancel',
+  hideActions = false,
+  loading: loadingProp,
+  zIndexBase,
+  className,
+  style,
+  theme,
+  ariaLabel,
+  ariaLabelledBy,
+  ariaDescribedBy,
+  children,
+  header,
+  footer,
+  onConfirm,
+  onCancel,
+  beforeOpen,
+  afterOpen,
+  beforeClose,
+  afterClose,
+}: UniversalModalProps) {
+  const reactId = useId();
+  const id = `um-${reactId.replace(/:/g, '')}`;
+  const titleId = `${id}-title`;
+  const descId = `${id}-description`;
+
+  const rootRef = useRef<HTMLDivElement>(null);
+  const backdropRef = useRef<HTMLDivElement>(null);
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const confirmRef = useRef<HTMLButtonElement>(null);
+  const cancelRef = useRef<HTMLButtonElement>(null);
+
+  const engineRef = useRef<ModalEngine | null>(null);
+  const onOpenChangeRef = useRef(onOpenChange);
+  onOpenChangeRef.current = onOpenChange;
+  const [mounted, setMounted] = useState(false);
+  const [visible, setVisible] = useState(open);
+  const [loading, setLoading] = useState(Boolean(loadingProp));
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  useEffect(() => {
+    if (loadingProp !== undefined) {
+      setLoading(loadingProp);
+      engineRef.current?.setLoading(loadingProp);
+    }
+  }, [loadingProp]);
+
+  useEffect(() => {
+    if (!mounted || !rootRef.current || !backdropRef.current || !dialogRef.current || !panelRef.current) {
+      return;
+    }
+
+    const engine = new ModalEngine({
+      id,
+      size,
+      placement,
+      title,
+      description,
+      persistent,
+      closeOnEsc,
+      closeOnBackdrop,
+      showCloseIcon,
+      role,
+      confirmText,
+      cancelText,
+      hideActions,
+      zIndexBase,
+      className,
+      theme,
+      ariaLabel,
+      ariaLabelledBy: ariaLabelledBy ?? (title ? titleId : undefined),
+      ariaDescribedBy: ariaDescribedBy ?? (description ? descId : undefined),
+      beforeOpen,
+      afterOpen,
+      beforeClose,
+      afterClose,
+      onConfirm,
+      onCancel,
+      manageDom: true,
+    });
+
+    engine.attach({
+      root: rootRef.current,
+      backdrop: backdropRef.current,
+      dialog: dialogRef.current,
+      panel: panelRef.current,
+      closeButton: closeRef.current,
+      confirmButton: confirmRef.current,
+      cancelButton: cancelRef.current,
+    });
+
+    const unsubs = [
+      engine.on('openChange', (isOpen) => {
+        setVisible(isOpen);
+        onOpenChangeRef.current?.(isOpen);
+      }),
+      engine.on('loadingChange', setLoading),
+      engine.on('afterClose', () => setVisible(false)),
+    ];
+
+    engineRef.current = engine;
+
+    return () => {
+      for (const off of unsubs) off();
+      engine.destroy();
+      engineRef.current = null;
+    };
+    // Engine is created once per mount; options synced below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [mounted, id]);
+
+  useEffect(() => {
+    engineRef.current?.updateOptions({
+      size,
+      placement,
+      title,
+      description,
+      persistent,
+      closeOnEsc,
+      closeOnBackdrop,
+      showCloseIcon,
+      role,
+      confirmText,
+      cancelText,
+      hideActions,
+      zIndexBase,
+      className,
+      theme,
+      ariaLabel,
+      ariaLabelledBy: ariaLabelledBy ?? (title ? titleId : undefined),
+      ariaDescribedBy: ariaDescribedBy ?? (description ? descId : undefined),
+      beforeOpen,
+      afterOpen,
+      beforeClose,
+      afterClose,
+      onConfirm,
+      onCancel,
+    });
+  }, [
+    size,
+    placement,
+    title,
+    description,
+    persistent,
+    closeOnEsc,
+    closeOnBackdrop,
+    showCloseIcon,
+    role,
+    confirmText,
+    cancelText,
+    hideActions,
+    zIndexBase,
+    className,
+    theme,
+    ariaLabel,
+    ariaLabelledBy,
+    ariaDescribedBy,
+    beforeOpen,
+    afterOpen,
+    beforeClose,
+    afterClose,
+    onConfirm,
+    onCancel,
+    titleId,
+    descId,
+  ]);
+
+  useEffect(() => {
+    const engine = engineRef.current;
+    if (!engine) return;
+    if (open && !engine.isOpen) void engine.open();
+    if (!open && engine.isOpen) void engine.close('programmatic');
+  }, [open]);
+
+  if (!mounted || typeof document === 'undefined') return null;
+
+  const rootClass = [
+    CSS_CLASSES.root,
+    visible || open ? CSS_CLASSES.open : '',
+    loading ? CSS_CLASSES.loading : '',
+    className ?? '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return createPortal(
+    <div
+      ref={rootRef}
+      className={rootClass}
+      style={style}
+      hidden={!visible && !open}
+      aria-hidden={!(visible || open)}
+    >
+      <div ref={backdropRef} className={CSS_CLASSES.backdrop} data-um-backdrop="" />
+      <div ref={dialogRef} className={CSS_CLASSES.dialog}>
+        <div ref={panelRef} className={CSS_CLASSES.panel} data-size={size} data-placement={placement}>
+          {showCloseIcon ? (
+            <button
+              ref={closeRef}
+              type="button"
+              className={CSS_CLASSES.close}
+              aria-label="Close dialog"
+            >
+              <svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false">
+                <path
+                  d="M6.4 6.4l11.2 11.2M17.6 6.4L6.4 17.6"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                />
+              </svg>
+            </button>
+          ) : null}
+
+          {(header || title || description) && (
+            <div className={CSS_CLASSES.header}>
+              {header ?? (
+                <>
+                  {title ? (
+                    <h2 id={titleId} className={CSS_CLASSES.title}>
+                      {title}
+                    </h2>
+                  ) : null}
+                  {description ? (
+                    <p id={descId} className={CSS_CLASSES.description}>
+                      {description}
+                    </p>
+                  ) : null}
+                </>
+              )}
+            </div>
+          )}
+
+          <div className={CSS_CLASSES.body}>{children}</div>
+
+          {(footer || !hideActions) && (
+            <div className={CSS_CLASSES.footer}>
+              {footer ?? (
+                <div className={CSS_CLASSES.actions}>
+                  <button
+                    ref={cancelRef}
+                    type="button"
+                    className={CSS_CLASSES.cancel}
+                    disabled={loading}
+                  >
+                    {cancelText}
+                  </button>
+                  <button
+                    ref={confirmRef}
+                    type="button"
+                    className={CSS_CLASSES.confirm}
+                    disabled={loading}
+                    aria-busy={loading}
+                  >
+                    {confirmText}
+                    <span className={CSS_CLASSES.spinner} aria-hidden="true" />
+                  </button>
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
+export type { CloseReason, ModalPlacement, ModalRole, ModalSize };

package/packages/universal-modal-react/src/index.ts

@@ -0,0 +1,10 @@
+export { UniversalModal, type UniversalModalProps } from './UniversalModal';
+export type {
+  CloseReason,
+  ModalOptions,
+  ModalPlacement,
+  ModalRole,
+  ModalSize,
+  ModalState,
+  ModalTheme,
+} from '@poluru-labs/universal-modal';

package/packages/universal-modal-react/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/universal-modal-react/tsup.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: { index: 'src/index.ts' },
+  format: ['esm', 'cjs'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  external: ['react', 'react-dom', 'react/jsx-runtime', '@poluru-labs/universal-modal'],
+  esbuildOptions(options) {
+    options.jsx = 'automatic';
+  },
+});

package/packages/universal-modal-vanilla/AUTHORS

@@ -0,0 +1,5 @@
+# Authors
+
+Subrahmanyam Poluru <mail.polurus@gmail.com>
+https://polurus.com
+https://www.linkedin.com/in/polurus/

package/packages/universal-modal-vanilla/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 — 2026-08-01
+
+### Added
+- Initial public release
+- Depends on `@poluru-labs/universal-modal@1.0.0`
+- MIT licensed (see LICENSE)
+

package/packages/universal-modal-vanilla/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Subrahmanyam Poluru 
+
+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/packages/universal-modal-vanilla/NOTICE

@@ -0,0 +1,6 @@
+@poluru-labs/universal-modal
+Copyright (c) 2026 Subrahmanyam Poluru 
+
+This product is developed and maintained by .
+Homepage: https://polurus.com
+Contact: mail.polurus@gmail.com

package/packages/universal-modal-vanilla/README.md

@@ -0,0 +1,12 @@
+# @poluru-labs/universal-modal-vanilla
+
+```bash
+npm install @poluru-labs/universal-modal-vanilla
+```
+
+```ts
+import { createModal } from '@poluru-labs/universal-modal-vanilla';
+import '@poluru-labs/universal-modal/styles.css';
+```
+
+Author: Subrahmanyam Poluru · mail.polurus@gmail.com

package/packages/universal-modal-vanilla/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@poluru-labs/universal-modal-vanilla",
+  "version": "1.0.0",
+  "description": "Vanilla JS/TS adapter for @poluru-labs/universal-modal",
+  "author": {
+    "name": "Subrahmanyam Poluru",
+    "email": "mail.polurus@gmail.com",
+    "url": "https://polurus.com"
+  },
+  "contributors": [
+    {
+      "name": "Subrahmanyam Poluru",
+      "email": "mail.polurus@gmail.com",
+      "url": "https://www.linkedin.com/in/polurus/"
+    }
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/poluru-labs/universal-modal#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/poluru-labs/universal-modal.git",
+    "directory": "packages/universal-modal-vanilla"
+  },
+  "bugs": {
+    "url": "https://github.com/poluru-labs/universal-modal/issues",
+    "email": "mail.polurus@gmail.com"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "modal",
+    "dialog",
+    "vanilla-js",
+    "typescript",
+    "poluru-labs"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "AUTHORS",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tgz",
+    "prepublishOnly": "npm run clean && npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "@poluru-labs/universal-modal": "1.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://polurus.com"
+  }
+}

package/packages/universal-modal-vanilla/src/create-modal.ts

@@ -0,0 +1,125 @@
+import {
+  ModalEngine,
+  ModalRenderer,
+  type CloseReason,
+  type ModalEngineConfig,
+  type ModalEventMap,
+  type ModalOptions,
+  type ModalState,
+  type ResolvedModalOptions,
+} from '@poluru-labs/universal-modal';
+
+export interface CreateModalOptions extends ModalEngineConfig {
+  /** Auto-mount into container (default: true). */
+  autoMount?: boolean;
+}
+
+export interface VanillaModal {
+  readonly id: string;
+  readonly el: HTMLElement;
+  readonly isOpen: boolean;
+  readonly isLoading: boolean;
+  getState: () => ModalState;
+  getOptions: () => Readonly<ResolvedModalOptions>;
+  updateOptions: (partial: Partial<ModalOptions>) => void;
+  setContent: (options: Partial<ModalOptions>) => void;
+  open: () => Promise<boolean>;
+  close: (reason?: CloseReason) => Promise<boolean>;
+  confirm: () => Promise<void>;
+  cancel: () => Promise<void>;
+  setLoading: (loading: boolean) => void;
+  on: <K extends keyof ModalEventMap>(
+    event: K,
+    listener: (payload: ModalEventMap[K]) => void,
+  ) => () => void;
+  off: <K extends keyof ModalEventMap>(
+    event: K,
+    listener: (payload: ModalEventMap[K]) => void,
+  ) => void;
+  destroy: () => void;
+}
+
+/**
+ * Vanilla JS / TypeScript factory.
+ */
+export function createModal(options: CreateModalOptions = {}): VanillaModal {
+  const { autoMount = true, ...engineOptions } = options;
+  const engine = new ModalEngine(engineOptions);
+  const renderer = new ModalRenderer(engine);
+
+  if (autoMount) {
+    renderer.mount();
+  }
+
+  return {
+    get id() {
+      return engine.id;
+    },
+    get el() {
+      return renderer.elements.root;
+    },
+    get isOpen() {
+      return engine.isOpen;
+    },
+    get isLoading() {
+      return engine.isLoading;
+    },
+    getState: () => engine.getState(),
+    getOptions: () => engine.getOptions(),
+    updateOptions: (partial) => {
+      renderer.syncContent(partial);
+    },
+    setContent: (partial) => {
+      renderer.syncContent(partial);
+    },
+    open: () => engine.open(),
+    close: (reason) => engine.close(reason),
+    confirm: () => engine.confirm(),
+    cancel: () => engine.cancel(),
+    setLoading: (loading) => engine.setLoading(loading),
+    on: (event, listener) => engine.on(event, listener),
+    off: (event, listener) => engine.off(event, listener),
+    destroy: () => {
+      renderer.destroy();
+      engine.destroy();
+    },
+  };
+}
+
+/** Imperative helper: open a one-shot confirmation dialog. */
+export function confirmModal(
+  options: CreateModalOptions & { message?: string },
+): Promise<boolean> {
+  const { message, body, afterClose, onConfirm, onCancel, ...rest } = options;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (value: boolean) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    const modal = createModal({
+      role: 'alertdialog',
+      hideActions: false,
+      ...rest,
+      body: body ?? (message ? `<p>${message}</p>` : undefined),
+      onConfirm: async () => {
+        await onConfirm?.();
+        settle(true);
+      },
+      onCancel: async () => {
+        await onCancel?.();
+        settle(false);
+      },
+      afterClose: (reason: CloseReason) => {
+        afterClose?.(reason);
+        if (reason !== 'confirm') settle(false);
+        queueMicrotask(() => modal.destroy());
+      },
+    });
+
+    void modal.open();
+  });
+}

package/packages/universal-modal-vanilla/src/index.ts

@@ -0,0 +1,14 @@
+export {
+  confirmModal,
+  createModal,
+  type CreateModalOptions,
+  type VanillaModal,
+} from './create-modal';
+export type {
+  CloseReason,
+  ModalOptions,
+  ModalPlacement,
+  ModalRole,
+  ModalSize,
+  ModalState,
+} from '@poluru-labs/universal-modal';

package/packages/universal-modal-vanilla/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/universal-modal-vanilla/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: { index: 'src/index.ts' },
+  format: ['esm', 'cjs'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  external: ['@poluru-labs/universal-modal'],
+});