universal-modal-monorepo 1.0.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "universal-modal-monorepo",
+  "version": "1.0.0",
+  "description": "Monorepo for @poluru-labs/universal-modal packages",
+  "author": {
+    "name": "Subrahmanyam Poluru",
+    "email": "mail.polurus@gmail.com",
+    "url": "https://polurus.com"
+  },
+  "license": "MIT",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "npm run build -w @poluru-labs/universal-modal && npm run build -w @poluru-labs/universal-modal-vanilla -w @poluru-labs/universal-modal-web-component -w @poluru-labs/universal-modal-react -w @poluru-labs/universal-modal-vue -w @poluru-labs/universal-modal-angular",
+    "build:core": "npm run build -w @poluru-labs/universal-modal",
+    "typecheck": "npm run typecheck --workspaces --if-present",
+    "clean": "npm run clean --workspaces --if-present",
+    "examples": "node scripts/serve-examples.mjs",
+    "publish:packages": "npm publish -w @poluru-labs/universal-modal && npm publish -w @poluru-labs/universal-modal-vanilla && npm publish -w @poluru-labs/universal-modal-web-component && npm publish -w @poluru-labs/universal-modal-react && npm publish -w @poluru-labs/universal-modal-vue && npm publish -w @poluru-labs/universal-modal-angular"
+  },
+  "devDependencies": {
+    "@angular/common": "^19.0.0",
+    "@angular/core": "^19.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vue": "^3.5.13"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/packages/universal-modal/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/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.0 — 2026-08-01
+
+### Added
+- Framework-agnostic modal engine (focus trap, scroll lock, stacking, lifecycle)
+- DOM renderer and CSS variable themes (light/dark)
+- Brand and button color tokens (`--um-color-brand`, `--um-btn-*`)
+- Per-instance `theme` option / `applyModalTheme()`
+- MIT license, AUTHORS, NOTICE

package/packages/universal-modal/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/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/README.md

@@ -0,0 +1,29 @@
+# @poluru-labs/universal-modal
+
+Framework-agnostic modal **core** (engine, focus trap, scroll lock, stacking, DOM renderer) and CSS themes.
+
+## Install
+
+```bash
+npm install @poluru-labs/universal-modal
+```
+
+Framework adapters (install the one you need):
+
+```bash
+npm install @poluru-labs/universal-modal-react
+npm install @poluru-labs/universal-modal-vue
+npm install @poluru-labs/universal-modal-angular
+npm install @poluru-labs/universal-modal-vanilla
+npm install @poluru-labs/universal-modal-web-component
+```
+
+## Styles
+
+```ts
+import '@poluru-labs/universal-modal/styles.css';
+```
+
+## Author
+
+Subrahmanyam Poluru · [polurus.com](https://polurus.com) · mail.polurus@gmail.com

package/packages/universal-modal/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@poluru-labs/universal-modal",
+  "version": "1.0.0",
+  "description": "Framework-agnostic universal modal engine, DOM renderer, and CSS themes.",
+  "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"
+  },
+  "bugs": {
+    "url": "https://github.com/poluru-labs/universal-modal/issues",
+    "email": "mail.polurus@gmail.com"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://polurus.com"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "modal",
+    "dialog",
+    "popup",
+    "accessibility",
+    "a11y",
+    "focus-trap",
+    "typescript",
+    "poluru-labs"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "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"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "AUTHORS",
+    "NOTICE",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup && node scripts/copy-styles.mjs",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tgz",
+    "prepublishOnly": "npm run clean && npm run typecheck && npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/packages/universal-modal/scripts/copy-styles.mjs

@@ -0,0 +1,11 @@
+import { copyFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const source = resolve(root, 'src/styles/modal.css');
+const target = resolve(root, 'dist/styles.css');
+
+mkdirSync(dirname(target), { recursive: true });
+copyFileSync(source, target);
+console.log('Copied styles → dist/styles.css');

package/packages/universal-modal/src/core/constants.ts

@@ -0,0 +1,50 @@
+import type { ResolvedModalOptions } from './types';
+
+export const DEFAULT_Z_INDEX_BASE = 1000;
+export const Z_INDEX_LAYER_STEP = 10;
+
+export const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'area[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+  '[contenteditable="true"]',
+].join(',');
+
+export const DEFAULT_OPTIONS: Omit<ResolvedModalOptions, 'id' | 'container'> = {
+  size: 'md',
+  placement: 'center',
+  persistent: false,
+  closeOnEsc: true,
+  closeOnBackdrop: true,
+  showCloseIcon: true,
+  role: 'dialog',
+  zIndexBase: DEFAULT_Z_INDEX_BASE,
+  animationDuration: 200,
+  confirmText: 'Confirm',
+  cancelText: 'Cancel',
+  hideActions: false,
+};
+
+export const CSS_CLASSES = {
+  root: 'um-modal',
+  open: 'um-modal--open',
+  closing: 'um-modal--closing',
+  loading: 'um-modal--loading',
+  backdrop: 'um-modal__backdrop',
+  dialog: 'um-modal__dialog',
+  panel: 'um-modal__panel',
+  header: 'um-modal__header',
+  title: 'um-modal__title',
+  description: 'um-modal__description',
+  body: 'um-modal__body',
+  footer: 'um-modal__footer',
+  close: 'um-modal__close',
+  actions: 'um-modal__actions',
+  confirm: 'um-modal__btn um-modal__btn--confirm',
+  cancel: 'um-modal__btn um-modal__btn--cancel',
+  spinner: 'um-modal__spinner',
+} as const;

package/packages/universal-modal/src/core/event-emitter.ts

@@ -0,0 +1,46 @@
+import type { ModalEventMap } from './types';
+
+type Listener<K extends keyof ModalEventMap> = (
+  payload: ModalEventMap[K],
+) => void;
+
+/**
+ * Tiny typed pub/sub used by the modal engine.
+ * Framework wrappers can subscribe without depending on DOM CustomEvents.
+ */
+export class EventEmitter {
+  private readonly listeners = new Map<
+    keyof ModalEventMap,
+    Set<Listener<keyof ModalEventMap>>
+  >();
+
+  on<K extends keyof ModalEventMap>(event: K, listener: Listener<K>): () => void {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(listener as Listener<keyof ModalEventMap>);
+    return () => this.off(event, listener);
+  }
+
+  off<K extends keyof ModalEventMap>(event: K, listener: Listener<K>): void {
+    this.listeners.get(event)?.delete(listener as Listener<keyof ModalEventMap>);
+  }
+
+  emit<K extends keyof ModalEventMap>(
+    event: K,
+    ...args: ModalEventMap[K] extends undefined ? [] | [undefined] : [ModalEventMap[K]]
+  ): void {
+    const set = this.listeners.get(event);
+    if (!set?.size) return;
+    const payload = (args[0] ?? undefined) as ModalEventMap[K];
+    for (const listener of [...set]) {
+      (listener as Listener<K>)(payload);
+    }
+  }
+
+  clear(): void {
+    this.listeners.clear();
+  }
+}

package/packages/universal-modal/src/core/focus-trap.ts

@@ -0,0 +1,101 @@
+import { FOCUSABLE_SELECTOR } from './constants';
+
+function isVisible(el: HTMLElement): boolean {
+  if (el.hasAttribute('disabled') || el.getAttribute('aria-hidden') === 'true') {
+    return false;
+  }
+  const style = window.getComputedStyle(el);
+  if (style.display === 'none' || style.visibility === 'hidden') {
+    return false;
+  }
+  return el.getClientRects().length > 0;
+}
+
+export function getFocusableElements(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+    isVisible,
+  );
+}
+
+export interface FocusTrap {
+  activate: (initialFocus?: HTMLElement | null) => void;
+  deactivate: () => void;
+  update: () => void;
+}
+
+/**
+ * Keeps keyboard focus inside `container` while active.
+ * Only the topmost trap should be active when modals are stacked.
+ */
+export function createFocusTrap(container: HTMLElement): FocusTrap {
+  let active = false;
+
+  const onKeyDown = (event: KeyboardEvent): void => {
+    if (!active || event.key !== 'Tab') return;
+
+    const focusable = getFocusableElements(container);
+    if (focusable.length === 0) {
+      event.preventDefault();
+      container.focus();
+      return;
+    }
+
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const current = document.activeElement as HTMLElement | null;
+
+    if (event.shiftKey) {
+      if (!current || current === first || !container.contains(current)) {
+        event.preventDefault();
+        last.focus();
+      }
+      return;
+    }
+
+    if (!current || current === last || !container.contains(current)) {
+      event.preventDefault();
+      first.focus();
+    }
+  };
+
+  return {
+    activate(initialFocus) {
+      if (active) return;
+      active = true;
+
+      container.addEventListener('keydown', onKeyDown);
+
+      const focusable = getFocusableElements(container);
+      const target =
+        initialFocus && container.contains(initialFocus)
+          ? initialFocus
+          : focusable[0] ?? container;
+
+      // Defer so the dialog is in the accessibility tree first.
+      requestAnimationFrame(() => {
+        target.focus({ preventScroll: true });
+      });
+    },
+
+    deactivate() {
+      if (!active) return;
+      active = false;
+      container.removeEventListener('keydown', onKeyDown);
+    },
+
+    update() {
+      // No-op placeholder for consumers that re-query focusables after DOM updates.
+    },
+  };
+}
+
+export function restoreFocus(element: HTMLElement | null): void {
+  if (!element) return;
+  try {
+    if (document.contains(element) && typeof element.focus === 'function') {
+      element.focus({ preventScroll: true });
+    }
+  } catch {
+    // Element may have been detached or become non-focusable.
+  }
+}

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

@@ -0,0 +1,39 @@
+export { ModalEngine, type ModalEngineConfig } from './modal-engine';
+export { modalStack, type StackEntry } from './modal-stack';
+export { EventEmitter } from './event-emitter';
+export { createFocusTrap, getFocusableElements, restoreFocus, type FocusTrap } from './focus-trap';
+export { lockBodyScroll, unlockBodyScroll, resetScrollLock } from './scroll-lock';
+export { CSS_CLASSES, DEFAULT_OPTIONS, DEFAULT_Z_INDEX_BASE, FOCUSABLE_SELECTOR, Z_INDEX_LAYER_STEP } from './constants';
+export {
+  createModalId,
+  getReturnFocusElement,
+  isPromiseLike,
+  prefersReducedMotion,
+  resolveContent,
+  resolveInitialFocus,
+  resolveOptions,
+  runLifecycle,
+  setContent,
+} from './utils';
+export type {
+  CloseReason,
+  LifecycleResult,
+  ModalA11yOptions,
+  ModalActionHandlers,
+  ModalBehaviorOptions,
+  ModalContent,
+  ModalContentOptions,
+  ModalEventMap,
+  ModalEventName,
+  ModalHostElements,
+  ModalLifecycleHooks,
+  ModalListener,
+  ModalOptions,
+  ModalPlacement,
+  ModalRole,
+  ModalSize,
+  ModalState,
+  ModalTheme,
+  ResolvedModalOptions,
+} from './types';
+export { applyModalTheme } from './theme';