universal-modal-monorepo 1.0.0

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

@@ -0,0 +1,196 @@
+/** Modal size tokens. */
+export type ModalSize = 'sm' | 'md' | 'lg' | 'xl' | 'fullscreen';
+
+/** Modal placement relative to the viewport. */
+export type ModalPlacement = 'center' | 'top' | 'bottom' | 'left' | 'right';
+
+/** Why the modal closed. */
+export type CloseReason =
+  | 'esc'
+  | 'backdrop'
+  | 'close-icon'
+  | 'cancel'
+  | 'confirm'
+  | 'programmatic';
+
+/** Dialog ARIA role. Use `alertdialog` for confirmations that interrupt flow. */
+export type ModalRole = 'dialog' | 'alertdialog';
+
+/** Content that can be a string, node, or lazy factory. */
+export type ModalContent =
+  | string
+  | Node
+  | (() => string | Node | null | undefined);
+
+export type LifecycleResult = boolean | void | Promise<boolean | void>;
+
+export interface ModalLifecycleHooks {
+  beforeOpen?: () => LifecycleResult;
+  afterOpen?: () => void;
+  beforeClose?: (reason: CloseReason) => LifecycleResult;
+  afterClose?: (reason: CloseReason) => void;
+}
+
+export interface ModalActionHandlers {
+  onConfirm?: () => void | Promise<void>;
+  onCancel?: () => void | Promise<void>;
+}
+
+export interface ModalA11yOptions {
+  role?: ModalRole;
+  /** Accessible name when no visible title / labelledby is available. */
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
+  ariaDescribedBy?: string;
+  /** Selector, element, or factory for the element to focus on open. */
+  initialFocus?: string | HTMLElement | (() => HTMLElement | null);
+  /** Element that opened the modal; focus is restored here on close. */
+  returnFocus?: HTMLElement | (() => HTMLElement | null) | null;
+}
+
+export interface ModalBehaviorOptions {
+  /** Prevent ESC / backdrop / outside dismiss. Close icon & programmatic still work unless disabled. */
+  persistent?: boolean;
+  closeOnEsc?: boolean;
+  closeOnBackdrop?: boolean;
+  showCloseIcon?: boolean;
+  /** Base z-index; stacking adds per-layer offsets. */
+  zIndexBase?: number;
+  animationDuration?: number;
+}
+
+export interface ModalContentOptions {
+  size?: ModalSize;
+  placement?: ModalPlacement;
+  title?: string;
+  description?: string;
+  header?: ModalContent;
+  body?: ModalContent;
+  footer?: ModalContent;
+  confirmText?: string;
+  cancelText?: string;
+  /** Hide built-in confirm/cancel footer actions. */
+  hideActions?: boolean;
+}
+
+/**
+ * Runtime theme overrides mapped to CSS custom properties on the modal root.
+ * Prefer CSS variables globally; use `theme` for per-instance branding.
+ */
+export interface ModalTheme {
+  /** Primary brand color (buttons, focus ring). Maps to `--um-color-brand`. */
+  brand?: string;
+  /** Text/icon color on brand surfaces. Maps to `--um-color-brand-fg`. */
+  brandForeground?: string;
+  confirmBg?: string;
+  confirmFg?: string;
+  confirmBorder?: string;
+  cancelBg?: string;
+  cancelFg?: string;
+  cancelBorder?: string;
+  focusRing?: string;
+  /** Escape hatch: any `--um-*` custom property (with or without `--` prefix). */
+  cssVars?: Record<string, string>;
+}
+
+export interface ModalOptions
+  extends ModalLifecycleHooks,
+    ModalActionHandlers,
+    ModalA11yOptions,
+    ModalBehaviorOptions,
+    ModalContentOptions {
+  id?: string;
+  className?: string;
+  /** Per-instance brand / button color overrides. */
+  theme?: ModalTheme;
+  /** Mount node; defaults to `document.body`. */
+  container?: HTMLElement | null;
+}
+
+export type ModalEventMap = {
+  beforeOpen: undefined;
+  afterOpen: undefined;
+  beforeClose: CloseReason;
+  afterClose: CloseReason;
+  confirm: undefined;
+  cancel: undefined;
+  loadingChange: boolean;
+  openChange: boolean;
+};
+
+export type ModalEventName = keyof ModalEventMap;
+
+export type ModalListener<T> = T extends undefined
+  ? () => void
+  : (payload: T) => void;
+
+export interface ModalState {
+  id: string;
+  open: boolean;
+  loading: boolean;
+  size: ModalSize;
+  placement: ModalPlacement;
+  persistent: boolean;
+  closeOnEsc: boolean;
+  closeOnBackdrop: boolean;
+  showCloseIcon: boolean;
+  role: ModalRole;
+  zIndex: number;
+  title?: string;
+  description?: string;
+  confirmText: string;
+  cancelText: string;
+  hideActions: boolean;
+}
+
+export interface ModalHostElements {
+  root: HTMLElement;
+  backdrop: HTMLElement;
+  dialog: HTMLElement;
+  panel: HTMLElement;
+  header?: HTMLElement | null;
+  body?: HTMLElement | null;
+  footer?: HTMLElement | null;
+  closeButton?: HTMLElement | null;
+  confirmButton?: HTMLButtonElement | null;
+  cancelButton?: HTMLButtonElement | null;
+}
+
+export interface ResolvedModalOptions extends Required<
+  Pick<
+    ModalOptions,
+    | 'size'
+    | 'placement'
+    | 'persistent'
+    | 'closeOnEsc'
+    | 'closeOnBackdrop'
+    | 'showCloseIcon'
+    | 'role'
+    | 'zIndexBase'
+    | 'animationDuration'
+    | 'confirmText'
+    | 'cancelText'
+    | 'hideActions'
+  >
+> {
+  id: string;
+  title?: string;
+  description?: string;
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
+  ariaDescribedBy?: string;
+  className?: string;
+  theme?: ModalTheme;
+  header?: ModalContent;
+  body?: ModalContent;
+  footer?: ModalContent;
+  container: HTMLElement | null;
+  initialFocus?: ModalA11yOptions['initialFocus'];
+  returnFocus?: ModalA11yOptions['returnFocus'];
+  beforeOpen?: ModalLifecycleHooks['beforeOpen'];
+  afterOpen?: ModalLifecycleHooks['afterOpen'];
+  beforeClose?: ModalLifecycleHooks['beforeClose'];
+  afterClose?: ModalLifecycleHooks['afterClose'];
+  onConfirm?: ModalActionHandlers['onConfirm'];
+  onCancel?: ModalActionHandlers['onCancel'];
+}

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

@@ -0,0 +1,114 @@
+import { DEFAULT_OPTIONS } from './constants';
+import type { ModalContent, ModalOptions, ResolvedModalOptions } from './types';
+
+let idCounter = 0;
+
+export function createModalId(prefix = 'um-modal'): string {
+  idCounter += 1;
+  return `${prefix}-${idCounter}`;
+}
+
+export function omitUndefined<T extends Record<string, unknown>>(input: T): Partial<T> {
+  const result: Partial<T> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) {
+      (result as Record<string, unknown>)[key] = value;
+    }
+  }
+  return result;
+}
+
+export function resolveOptions(options: ModalOptions = {}): ResolvedModalOptions {
+  const id = options.id ?? createModalId();
+  const cleaned = omitUndefined(options as Record<string, unknown>) as ModalOptions;
+  const persistent = cleaned.persistent ?? DEFAULT_OPTIONS.persistent;
+
+  return {
+    ...DEFAULT_OPTIONS,
+    ...cleaned,
+    id,
+    persistent,
+    container: cleaned.container ?? (typeof document !== 'undefined' ? document.body : null),
+    closeOnEsc: persistent ? false : (cleaned.closeOnEsc ?? DEFAULT_OPTIONS.closeOnEsc),
+    closeOnBackdrop: persistent
+      ? false
+      : (cleaned.closeOnBackdrop ?? DEFAULT_OPTIONS.closeOnBackdrop),
+  };
+}
+
+export function resolveContent(content: ModalContent | undefined): string | Node | null {
+  if (content == null) return null;
+  if (typeof content === 'function') {
+    const result = content();
+    return result ?? null;
+  }
+  return content;
+}
+
+export function setContent(target: HTMLElement, content: ModalContent | undefined): void {
+  target.replaceChildren();
+  const resolved = resolveContent(content);
+  if (resolved == null) return;
+  if (typeof resolved === 'string') {
+    target.innerHTML = resolved;
+    return;
+  }
+  target.appendChild(resolved);
+}
+
+export function isPromiseLike<T>(value: unknown): value is PromiseLike<T> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'then' in value &&
+    typeof (value as PromiseLike<T>).then === 'function'
+  );
+}
+
+export async function runLifecycle(
+  hook: (() => unknown) | ((arg: never) => unknown) | undefined,
+  arg?: unknown,
+): Promise<boolean> {
+  if (!hook) return true;
+  const result = arg === undefined ? (hook as () => unknown)() : (hook as (a: unknown) => unknown)(arg);
+  const value = isPromiseLike(result) ? await result : result;
+  return value !== false;
+}
+
+export function getReturnFocusElement(
+  returnFocus: ModalOptions['returnFocus'],
+  fallback: Element | null = null,
+): HTMLElement | null {
+  if (returnFocus === null) return null;
+  if (typeof returnFocus === 'function') {
+    return returnFocus() ?? (fallback instanceof HTMLElement ? fallback : null);
+  }
+  if (returnFocus instanceof HTMLElement) return returnFocus;
+  if (fallback instanceof HTMLElement) return fallback;
+  return null;
+}
+
+export function resolveInitialFocus(
+  initialFocus: ModalOptions['initialFocus'],
+  dialog: HTMLElement,
+): HTMLElement | null {
+  if (!initialFocus) {
+    const autofocus = dialog.querySelector<HTMLElement>('[autofocus]');
+    if (autofocus) return autofocus;
+    return null;
+  }
+  if (typeof initialFocus === 'string') {
+    return dialog.querySelector<HTMLElement>(initialFocus);
+  }
+  if (typeof initialFocus === 'function') {
+    return initialFocus();
+  }
+  return initialFocus;
+}
+
+export function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+    return false;
+  }
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}

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

@@ -0,0 +1 @@
+export { ModalRenderer, type ModalRendererOptions } from './modal-renderer';

package/packages/universal-modal/src/dom/modal-renderer.ts

@@ -0,0 +1,191 @@
+import { CSS_CLASSES } from '../core/constants';
+import type { ModalEngine } from '../core/modal-engine';
+import type { ModalHostElements, ModalOptions } from '../core/types';
+import { setContent } from '../core/utils';
+
+export interface ModalRendererOptions {
+  /** Include confirm/cancel action buttons when options allow. */
+  includeActions?: boolean;
+}
+
+interface InternalElements extends ModalHostElements {
+  titleEl: HTMLHeadingElement;
+  descriptionEl: HTMLParagraphElement;
+}
+
+/**
+ * Imperative DOM builder used by Vanilla JS and Web Component adapters.
+ */
+export class ModalRenderer {
+  readonly elements: ModalHostElements;
+  private readonly engine: ModalEngine;
+  private readonly titleEl: HTMLHeadingElement;
+  private readonly descriptionEl: HTMLParagraphElement;
+
+  constructor(engine: ModalEngine, _options: ModalRendererOptions = {}) {
+    this.engine = engine;
+    const built = this.build();
+    this.elements = built;
+    this.titleEl = built.titleEl;
+    this.descriptionEl = built.descriptionEl;
+    this.syncContent();
+    this.engine.attach(this.elements);
+  }
+
+  mount(container?: HTMLElement | null): void {
+    const target = container ?? this.engine.getOptions().container ?? document.body;
+    if (!this.elements.root.isConnected) {
+      target.appendChild(this.elements.root);
+    }
+  }
+
+  unmount(): void {
+    this.elements.root.remove();
+  }
+
+  syncContent(options: Partial<ModalOptions> = {}): void {
+    if (Object.keys(options).length > 0) {
+      this.engine.updateOptions(options);
+    }
+
+    const opts = this.engine.getOptions();
+    const { header, body, footer } = this.elements;
+    const id = opts.id;
+
+    if (header) {
+      header.replaceChildren();
+
+      if (opts.header) {
+        setContent(header, opts.header);
+      } else {
+        if (opts.title) {
+          this.titleEl.id = `${id}-title`;
+          this.titleEl.textContent = opts.title;
+          header.appendChild(this.titleEl);
+        }
+        if (opts.description) {
+          this.descriptionEl.id = `${id}-description`;
+          this.descriptionEl.textContent = opts.description;
+          header.appendChild(this.descriptionEl);
+        }
+      }
+
+      header.hidden =
+        header.childElementCount === 0 && !opts.title && !opts.description && !opts.header;
+    }
+
+    if (body) {
+      if (opts.body !== undefined) {
+        setContent(body, opts.body);
+      }
+    }
+
+    if (footer) {
+      footer.replaceChildren();
+
+      if (opts.footer) {
+        setContent(footer, opts.footer);
+      } else if (!opts.hideActions) {
+        const actions = document.createElement('div');
+        actions.className = CSS_CLASSES.actions;
+
+        if (this.elements.cancelButton) {
+          this.elements.cancelButton.textContent = opts.cancelText;
+          actions.appendChild(this.elements.cancelButton);
+        }
+        if (this.elements.confirmButton) {
+          this.elements.confirmButton.textContent = opts.confirmText;
+          if (!this.elements.confirmButton.querySelector(`.${CSS_CLASSES.spinner}`)) {
+            const spin = document.createElement('span');
+            spin.className = CSS_CLASSES.spinner;
+            spin.setAttribute('aria-hidden', 'true');
+            this.elements.confirmButton.appendChild(spin);
+          }
+          actions.appendChild(this.elements.confirmButton);
+        }
+        footer.appendChild(actions);
+      }
+
+      footer.hidden = footer.childElementCount === 0;
+    }
+
+    if (this.elements.closeButton) {
+      this.elements.closeButton.hidden = !opts.showCloseIcon;
+    }
+  }
+
+  destroy(): void {
+    this.engine.detach();
+    this.unmount();
+  }
+
+  private build(): InternalElements {
+    const opts = this.engine.getOptions();
+
+    const root = document.createElement('div');
+    root.className = CSS_CLASSES.root;
+    root.hidden = true;
+    root.setAttribute('aria-hidden', 'true');
+
+    const backdrop = document.createElement('div');
+    backdrop.className = CSS_CLASSES.backdrop;
+    backdrop.setAttribute('data-um-backdrop', '');
+
+    const dialog = document.createElement('div');
+    dialog.className = CSS_CLASSES.dialog;
+
+    const panel = document.createElement('div');
+    panel.className = CSS_CLASSES.panel;
+    panel.dataset.size = opts.size;
+    panel.dataset.placement = opts.placement;
+
+    const closeButton = document.createElement('button');
+    closeButton.type = 'button';
+    closeButton.className = CSS_CLASSES.close;
+    closeButton.setAttribute('aria-label', 'Close dialog');
+    closeButton.innerHTML =
+      '<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" stroke-width="2" stroke-linecap="round"/></svg>';
+
+    const header = document.createElement('div');
+    header.className = CSS_CLASSES.header;
+
+    const titleEl = document.createElement('h2');
+    titleEl.className = CSS_CLASSES.title;
+
+    const descriptionEl = document.createElement('p');
+    descriptionEl.className = CSS_CLASSES.description;
+
+    const body = document.createElement('div');
+    body.className = CSS_CLASSES.body;
+
+    const footer = document.createElement('div');
+    footer.className = CSS_CLASSES.footer;
+
+    const cancelButton = document.createElement('button');
+    cancelButton.type = 'button';
+    cancelButton.className = CSS_CLASSES.cancel;
+
+    const confirmButton = document.createElement('button');
+    confirmButton.type = 'button';
+    confirmButton.className = CSS_CLASSES.confirm;
+
+    panel.append(closeButton, header, body, footer);
+    dialog.appendChild(panel);
+    root.append(backdrop, dialog);
+
+    return {
+      root,
+      backdrop,
+      dialog,
+      panel,
+      header,
+      body,
+      footer,
+      closeButton,
+      confirmButton,
+      cancelButton,
+      titleEl,
+      descriptionEl,
+    };
+  }
+}

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

@@ -0,0 +1,2 @@
+export * from './core/index';
+export { ModalRenderer, type ModalRendererOptions } from './dom/index';