universal-modal-monorepo 1.0.0

package/AUTHORS

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

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project are documented in each package `CHANGELOG.md`.
+
+## 1.0.0 — 2026-08-01
+
+### Added
+- Monorepo packages: core + react / vue / angular / vanilla / web-component
+- Brand and button theming via CSS variables and `theme` option
+- MIT license, AUTHORS, NOTICE, SECURITY policy

package/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/NOTICE

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

package/README.md

@@ -0,0 +1,239 @@
+# @poluru-labs/universal-modal
+
+Production-grade **universal modal** monorepo — framework-agnostic core plus separately installable adapters.
+
+**Author:** Subrahmanyam Poluru ([polurus.com](https://polurus.com)) · [mail.polurus@gmail.com](mailto:mail.polurus@gmail.com) · [LinkedIn](https://www.linkedin.com/in/polurus/)  
+**Org:** [Poluru](https://github.com/poluru-labs) · License: MIT
+
+> npm cannot publish or install a package named `@scope/pkg/react` (the `/` is a subpath, not a package).  
+> Install the matching package name instead — same idea as `@headlessui/react`.
+
+---
+
+## Install
+
+Pick the adapter for your stack (each pulls in the core automatically):
+
+```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
+```
+
+Core only (engine + styles):
+
+```bash
+npm install @poluru-labs/universal-modal
+```
+
+Import styles once:
+
+```ts
+import '@poluru-labs/universal-modal/styles.css';
+```
+
+### Brand & button colors
+
+Override globally with CSS variables:
+
+```css
+:root {
+  --um-color-brand: #0d47a1;
+  --um-color-brand-fg: #ffffff;
+  --um-btn-confirm-bg: var(--um-color-brand);
+  --um-btn-confirm-fg: var(--um-color-brand-fg);
+  --um-btn-confirm-border: var(--um-color-brand);
+  --um-btn-cancel-bg: #fff;
+  --um-btn-cancel-fg: #111827;
+  --um-btn-cancel-border: #e5e7eb;
+}
+```
+
+Or per modal via `theme`:
+
+```ts
+createModal({
+  title: 'Delete?',
+  theme: {
+    brand: '#0d47a1',
+    confirmBg: '#b91c1c',
+    confirmFg: '#ffffff',
+  },
+});
+```
+
+See [docs/THEMING.md](docs/THEMING.md).
+
+---
+
+## Packages
+
+| Package | Import |
+|---|---|
+| `@poluru-labs/universal-modal` | Core engine, types, `ModalRenderer`, CSS |
+| `@poluru-labs/universal-modal-react` | `UniversalModal` React component |
+| `@poluru-labs/universal-modal-vue` | `UniversalModal` Vue 3 component |
+| `@poluru-labs/universal-modal-angular` | `UniversalModalComponent` Angular standalone |
+| `@poluru-labs/universal-modal-vanilla` | `createModal`, `confirmModal` |
+| `@poluru-labs/universal-modal-web-component` | `<universal-modal>` custom element |
+
+---
+
+## Usage
+
+### React
+
+```bash
+npm install @poluru-labs/universal-modal-react
+```
+
+```tsx
+import { useState } from 'react';
+import { UniversalModal } from '@poluru-labs/universal-modal-react';
+import '@poluru-labs/universal-modal/styles.css';
+
+export function Example() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <button onClick={() => setOpen(true)}>Open</button>
+      <UniversalModal open={open} onOpenChange={setOpen} title="Hello">
+        <p>Content</p>
+      </UniversalModal>
+    </>
+  );
+}
+```
+
+### Vue 3
+
+```bash
+npm install @poluru-labs/universal-modal-vue
+```
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { UniversalModal } from '@poluru-labs/universal-modal-vue';
+import '@poluru-labs/universal-modal/styles.css';
+const open = ref(false);
+</script>
+
+<template>
+  <UniversalModal v-model:open="open" title="Hello">
+    <p>Content</p>
+  </UniversalModal>
+</template>
+```
+
+### Angular
+
+```bash
+npm install @poluru-labs/universal-modal-angular
+```
+
+```ts
+import { UniversalModalComponent } from '@poluru-labs/universal-modal-angular';
+import '@poluru-labs/universal-modal/styles.css';
+```
+
+### Vanilla JS / TypeScript
+
+```bash
+npm install @poluru-labs/universal-modal-vanilla
+```
+
+```ts
+import { createModal } from '@poluru-labs/universal-modal-vanilla';
+import '@poluru-labs/universal-modal/styles.css';
+
+const modal = createModal({
+  title: 'Delete?',
+  role: 'alertdialog',
+  onConfirm: async () => api.remove(),
+});
+await modal.open();
+```
+
+### Web Components
+
+```bash
+npm install @poluru-labs/universal-modal-web-component
+```
+
+```ts
+import '@poluru-labs/universal-modal-web-component';
+import '@poluru-labs/universal-modal/styles.css';
+```
+
+```html
+<universal-modal id="demo" title="Settings" size="lg">
+  <p>Content</p>
+</universal-modal>
+<script>
+  document.getElementById('demo').open();
+</script>
+```
+
+---
+
+## Monorepo layout
+
+```text
+packages/
+  universal-modal/                 # @poluru-labs/universal-modal
+  universal-modal-react/           # @poluru-labs/universal-modal-react
+  universal-modal-vue/
+  universal-modal-angular/
+  universal-modal-vanilla/
+  universal-modal-web-component/
+examples/
+docs/
+```
+
+---
+
+## Develop
+
+```bash
+npm install
+npm run build
+npm run examples
+```
+
+- http://localhost:4173/examples/index.html — gallery hub  
+- Vanilla / Web Component / React / Vue / Angular each include multiple samples (confirm, drawer, sheet, fullscreen, persistent, themed, nested)
+
+See `docs/API.md`, `docs/THEMING.md`, and `docs/ACCESSIBILITY.md`.
+
+---
+
+## Publish checklist
+
+Before `npm run publish:packages`:
+
+1. You are logged in (`npm whoami`) and can publish under `@poluru-labs`
+2. GitHub repo URLs in each `package.json` match the real remote (or update them)
+3. `npm run build` succeeds
+4. Each package includes `LICENSE`, `AUTHORS`, `NOTICE`, `CHANGELOG.md`, `README.md`
+5. No secrets in the tarball (`npm pack -w @poluru-labs/universal-modal --dry-run`)
+
+```bash
+npm run build
+npm run publish:packages
+```
+
+Publishes core first, then each adapter.
+
+---
+
+## License & legal
+
+- **License:** [MIT](LICENSE) © Subrahmanyam Poluru 
+- **Authors:** [AUTHORS](AUTHORS)
+- **Notice:** [NOTICE](NOTICE)
+- **Security:** [SECURITY.md](SECURITY.md)
+
+Third-party runtime code: none in the published core (framework peers are optional and not bundled). DevDependencies (TypeScript, tsup, React/Vue/Angular for builds) are not shipped in the npm tarball.

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 1.x | Yes |
+
+## Reporting a vulnerability
+
+Please report security issues privately to **mail.polurus@gmail.com**.
+
+Include:
+- Package name and version
+- Description of the issue
+- Steps to reproduce (if possible)
+- Impact assessment
+
+Do not open a public GitHub issue for security reports until a fix is available or we confirm disclosure is safe.
+
+We aim to acknowledge reports within 7 days.

package/docs/ACCESSIBILITY.md

@@ -0,0 +1,43 @@
+# Accessibility notes
+
+Author: **Subrahmanyam Poluru** · 
+
+## Semantics
+
+- Root dialog uses `role="dialog"` by default
+- Use `role="alertdialog"` for destructive or blocking confirms
+- Always sets `aria-modal="true"`
+- Prefers `aria-labelledby` (title) and `aria-describedby` (description)
+- Falls back to `aria-label` when no visible title is provided
+
+## Keyboard
+
+- `Tab` / `Shift+Tab` are trapped inside the **topmost** open modal
+- `Escape` closes the topmost modal (unless `persistent` or `closeOnEsc: false`)
+- Close, Cancel, and Confirm are real `<button>` elements
+
+## Focus management
+
+1. On open: focus moves to `initialFocus`, then `[autofocus]`, then the first focusable control, then the dialog itself
+2. On close: focus restores to `returnFocus` (or the previously focused element)
+3. Nested modals: only the top layer’s focus trap is active
+
+## Screen readers
+
+- Title and description IDs are stable per modal instance
+- Loading confirm buttons expose `aria-busy="true"`
+- Close control has `aria-label="Close dialog"`
+- Hidden closed roots use `hidden` + `aria-hidden="true"`
+
+## Motion
+
+- Honors `prefers-reduced-motion: reduce` (skips enter/exit delays and CSS transitions)
+
+## Authoring checklist
+
+- [ ] Provide a title **or** `ariaLabel`
+- [ ] Use `alertdialog` for confirms that interrupt the user’s flow
+- [ ] Ensure at least one focusable control inside the dialog
+- [ ] Pass `returnFocus` to the trigger in Vanilla / imperative usage
+- [ ] Verify stacked modals: ESC closes only the top layer
+- [ ] Confirm focus returns after close with VoiceOver / NVDA

package/docs/API.md

@@ -0,0 +1,56 @@
+# API Reference
+
+Author: **Subrahmanyam Poluru** · mail.polurus@gmail.com · https://polurus.com
+
+## Install
+
+```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
+```
+
+## Imports
+
+```ts
+import { ModalEngine, ModalRenderer } from '@poluru-labs/universal-modal';
+import { createModal, confirmModal } from '@poluru-labs/universal-modal-vanilla';
+import { UniversalModal } from '@poluru-labs/universal-modal-react';
+import { UniversalModal } from '@poluru-labs/universal-modal-vue';
+import { UniversalModalComponent } from '@poluru-labs/universal-modal-angular';
+import '@poluru-labs/universal-modal-web-component';
+import '@poluru-labs/universal-modal/styles.css';
+```
+
+## Options (shared)
+
+```ts
+type ModalOptions = {
+  id?: string;
+  size?: 'sm' | 'md' | 'lg' | 'xl' | 'fullscreen';
+  placement?: 'center' | 'top' | 'bottom' | 'left' | 'right';
+  title?: string;
+  description?: string;
+  persistent?: boolean;
+  closeOnEsc?: boolean;
+  closeOnBackdrop?: boolean;
+  showCloseIcon?: boolean;
+  role?: 'dialog' | 'alertdialog';
+  confirmText?: string;
+  cancelText?: string;
+  hideActions?: boolean;
+  zIndexBase?: number;
+  onConfirm?: () => void | Promise<void>;
+  onCancel?: () => void | Promise<void>;
+  beforeOpen?: () => boolean | void | Promise<boolean | void>;
+  afterOpen?: () => void;
+  beforeClose?: (reason: CloseReason) => boolean | void | Promise<boolean | void>;
+  afterClose?: (reason: CloseReason) => void;
+};
+```
+
+## Events
+
+`beforeOpen` · `afterOpen` · `beforeClose` · `afterClose` · `confirm` · `cancel` · `openChange` · `loadingChange`

package/docs/THEMING.md

@@ -0,0 +1,65 @@
+# Theming & brand colors
+
+Default brand color: `#0d47a1`.
+
+## 1. CSS variables (recommended)
+
+Import styles, then override on `:root`, `[data-um-theme]`, or a parent:
+
+```css
+:root {
+  --um-color-brand: #0d47a1;
+  --um-color-brand-fg: #ffffff;
+
+  --um-btn-confirm-bg: var(--um-color-brand);
+  --um-btn-confirm-fg: var(--um-color-brand-fg);
+  --um-btn-confirm-border: var(--um-color-brand);
+
+  --um-btn-cancel-bg: #ffffff;
+  --um-btn-cancel-fg: #111827;
+  --um-btn-cancel-border: #e5e7eb;
+}
+```
+
+### Brand tokens
+
+| Variable | Purpose |
+|---|---|
+| `--um-color-brand` | Primary brand color |
+| `--um-color-brand-fg` | Text/icon on brand surfaces |
+| `--um-color-accent` | Alias of brand (legacy) |
+| `--um-color-accent-fg` | Alias of brand foreground |
+
+### Button tokens
+
+| Variable | Purpose |
+|---|---|
+| `--um-btn-confirm-bg` | Confirm button background |
+| `--um-btn-confirm-fg` | Confirm button text |
+| `--um-btn-confirm-border` | Confirm button border |
+| `--um-btn-cancel-bg` | Cancel button background |
+| `--um-btn-cancel-fg` | Cancel button text |
+| `--um-btn-cancel-border` | Cancel button border |
+
+## 2. Per-modal `theme` option
+
+```ts
+createModal({
+  title: 'Delete?',
+  theme: {
+    brand: '#0d47a1',
+    brandForeground: '#ffffff',
+    confirmBg: '#b91c1c',
+    confirmFg: '#ffffff',
+    confirmBorder: '#b91c1c',
+    cancelBg: '#ffffff',
+    cancelFg: '#111827',
+    cancelBorder: '#e5e7eb',
+    cssVars: {
+      'um-radius': '16px',
+    },
+  },
+});
+```
+
+React / Vue / Angular accept the same `theme` prop/input.

package/examples/angular/app.component.html

@@ -0,0 +1,137 @@
+<main class="demo-page">
+  <header class="demo-header">
+    <p class="demo-kicker">Angular</p>
+    <h1>Modal samples</h1>
+    <p>
+      Standalone <code>UniversalModalComponent</code> patterns — drop this into an Angular
+      16+ app with the package import.
+    </p>
+  </header>
+
+  <section class="demo-grid">
+    <article class="demo-card">
+      <h2>1. Archive confirm</h2>
+      <p>Alertdialog with async confirm handler.</p>
+      <button type="button" (click)="open('archive')">Archive workspace</button>
+    </article>
+    <article class="demo-card">
+      <h2>2. Danger delete</h2>
+      <p>Custom red confirm theme.</p>
+      <button type="button" (click)="open('danger')">Delete webhook</button>
+    </article>
+    <article class="demo-card">
+      <h2>3. Right drawer</h2>
+      <p>Large form panel.</p>
+      <button type="button" (click)="open('drawer')">Edit workspace</button>
+    </article>
+    <article class="demo-card">
+      <h2>4. Top notice</h2>
+      <p>No footer actions.</p>
+      <button type="button" (click)="open('top')">Show notice</button>
+    </article>
+    <article class="demo-card">
+      <h2>5. Fullscreen</h2>
+      <p>Checklist / walkthrough layout.</p>
+      <button type="button" (click)="open('fullscreen')">Open checklist</button>
+    </article>
+    <article class="demo-card">
+      <h2>6. Persistent</h2>
+      <p>Blocks ESC and backdrop.</p>
+      <button type="button" (click)="open('persistent')">Accept DPA</button>
+    </article>
+    <article class="demo-card">
+      <h2>7. Brand theme</h2>
+      <p>Per-dialog brand override.</p>
+      <button type="button" (click)="open('brand')">Open branded</button>
+    </article>
+  </section>
+
+  <universal-modal
+    [open]="sample === 'archive'"
+    title="Archive workspace?"
+    description="Members keep read-only access."
+    role="alertdialog"
+    confirmText="Archive"
+    cancelText="Cancel"
+    (openChange)="onOpenChange($event)"
+    (confirm)="onArchive()"
+  >
+    <label class="demo-field">
+      Workspace
+      <input [value]="workspace" (input)="workspace = $any($event.target).value" />
+    </label>
+  </universal-modal>
+
+  <universal-modal
+    [open]="sample === 'danger'"
+    title="Delete webhook?"
+    role="alertdialog"
+    confirmText="Delete"
+    [theme]="dangerTheme"
+    (openChange)="onOpenChange($event)"
+  >
+    <p>Deliveries will stop immediately.</p>
+  </universal-modal>
+
+  <universal-modal
+    [open]="sample === 'drawer'"
+    title="Workspace settings"
+    size="lg"
+    placement="right"
+    confirmText="Save"
+    (openChange)="onOpenChange($event)"
+  >
+    <div class="demo-stack">
+      <label class="demo-field">Name <input [value]="workspace" /></label>
+      <label class="demo-field">Slug <input value="poluru-labs" /></label>
+    </div>
+  </universal-modal>
+
+  <universal-modal
+    [open]="sample === 'top'"
+    title="Deploy in progress"
+    placement="top"
+    [hideActions]="true"
+    (openChange)="onOpenChange($event)"
+  >
+    <p>You can keep browsing while the pipeline finishes.</p>
+  </universal-modal>
+
+  <universal-modal
+    [open]="sample === 'fullscreen'"
+    title="Launch checklist"
+    size="fullscreen"
+    confirmText="Mark complete"
+    (openChange)="onOpenChange($event)"
+  >
+    <div class="demo-stack">
+      <p>✓ Domain verified</p>
+      <p>✓ Billing method added</p>
+      <p>✓ First project created</p>
+    </div>
+  </universal-modal>
+
+  <universal-modal
+    [open]="sample === 'persistent'"
+    title="Data processing agreement"
+    role="alertdialog"
+    [persistent]="true"
+    [showCloseIcon]="false"
+    confirmText="Accept"
+    cancelText="Decline"
+    (openChange)="onOpenChange($event)"
+  >
+    <p>Outside dismiss is disabled until you choose an action.</p>
+  </universal-modal>
+
+  <universal-modal
+    [open]="sample === 'brand'"
+    title="Branded dialog"
+    description="theme input maps to CSS variables."
+    [theme]="brandTheme"
+    confirmText="Apply"
+    (openChange)="onOpenChange($event)"
+  >
+    <p>Use this for one-off brand treatments.</p>
+  </universal-modal>
+</main>

package/examples/angular/app.component.ts

@@ -0,0 +1,53 @@
+import { Component } from '@angular/core';
+import {
+  UniversalModalComponent,
+  type ModalTheme,
+} from '@poluru-labs/universal-modal-angular';
+
+type Sample =
+  | 'archive'
+  | 'danger'
+  | 'drawer'
+  | 'top'
+  | 'fullscreen'
+  | 'persistent'
+  | 'brand'
+  | null;
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [UniversalModalComponent],
+  templateUrl: './app.component.html',
+  styleUrl: './styles.css',
+})
+export class AppComponent {
+  sample: Sample = null;
+  workspace = 'Poluru Labs';
+
+  readonly dangerTheme: ModalTheme = {
+    confirmBg: '#b91c1c',
+    confirmFg: '#ffffff',
+    confirmBorder: '#b91c1c',
+  };
+
+  readonly brandTheme: ModalTheme = {
+    brand: '#0d47a1',
+    brandForeground: '#ffffff',
+    confirmBg: '#0d47a1',
+    confirmFg: '#ffffff',
+  };
+
+  open(sample: Exclude<Sample, null>): void {
+    this.sample = sample;
+  }
+
+  onOpenChange(open: boolean): void {
+    if (!open) this.sample = null;
+  }
+
+  async onArchive(): Promise<void> {
+    await new Promise((r) => setTimeout(r, 700));
+    console.log('archived', this.workspace);
+  }
+}