universal-modal-monorepo 1.0.0

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

@@ -0,0 +1,410 @@
+import { CSS_CLASSES } from './constants';
+import { EventEmitter } from './event-emitter';
+import { createFocusTrap, restoreFocus, type FocusTrap } from './focus-trap';
+import { modalStack } from './modal-stack';
+import { lockBodyScroll, unlockBodyScroll } from './scroll-lock';
+import type {
+  CloseReason,
+  ModalEventMap,
+  ModalHostElements,
+  ModalOptions,
+  ModalState,
+  ResolvedModalOptions,
+} from './types';
+import { applyModalTheme } from './theme';
+import {
+  getReturnFocusElement,
+  prefersReducedMotion,
+  resolveInitialFocus,
+  resolveOptions,
+  runLifecycle,
+} from './utils';
+
+export interface ModalEngineConfig extends ModalOptions {
+  /** When true, engine manages focus trap + ESC on the attached host. */
+  manageDom?: boolean;
+}
+
+/**
+ * Framework-agnostic modal controller.
+ * Owns state, lifecycle, stacking, scroll lock, and optional DOM host wiring.
+ */
+export class ModalEngine {
+  private options: ResolvedModalOptions;
+  private readonly emitter = new EventEmitter();
+  private opened = false;
+  private loading = false;
+  private transitioning = false;
+  private zIndex = 0;
+  private host: ModalHostElements | null = null;
+  private focusTrap: FocusTrap | null = null;
+  private returnFocusEl: HTMLElement | null = null;
+  private manageDom: boolean;
+  private boundKeyDown = (event: KeyboardEvent): void => {
+    this.handleKeyDown(event);
+  };
+  private stacked = false;
+
+  constructor(config: ModalEngineConfig = {}) {
+    const { manageDom = true, ...options } = config;
+    this.manageDom = manageDom;
+    this.options = resolveOptions(options);
+    this.zIndex = this.options.zIndexBase;
+  }
+
+  get id(): string {
+    return this.options.id;
+  }
+
+  get isOpen(): boolean {
+    return this.opened;
+  }
+
+  get isLoading(): boolean {
+    return this.loading;
+  }
+
+  getOptions(): Readonly<ResolvedModalOptions> {
+    return this.options;
+  }
+
+  getState(): ModalState {
+    return {
+      id: this.options.id,
+      open: this.opened,
+      loading: this.loading,
+      size: this.options.size,
+      placement: this.options.placement,
+      persistent: this.options.persistent,
+      closeOnEsc: this.options.closeOnEsc,
+      closeOnBackdrop: this.options.closeOnBackdrop,
+      showCloseIcon: this.options.showCloseIcon,
+      role: this.options.role,
+      zIndex: this.zIndex,
+      title: this.options.title,
+      description: this.options.description,
+      confirmText: this.options.confirmText,
+      cancelText: this.options.cancelText,
+      hideActions: this.options.hideActions,
+    };
+  }
+
+  updateOptions(partial: Partial<ModalOptions>): void {
+    this.options = resolveOptions({
+      ...this.options,
+      ...partial,
+      id: this.options.id,
+    });
+    if (this.host) {
+      this.applyHostAttributes();
+    }
+  }
+
+  on<K extends keyof ModalEventMap>(
+    event: K,
+    listener: (payload: ModalEventMap[K]) => void,
+  ): () => void {
+    return this.emitter.on(event, listener);
+  }
+
+  off<K extends keyof ModalEventMap>(
+    event: K,
+    listener: (payload: ModalEventMap[K]) => void,
+  ): void {
+    this.emitter.off(event, listener);
+  }
+
+  /**
+   * Bind rendered DOM nodes so the engine can trap focus, wire ESC, and sync ARIA.
+   */
+  attach(host: ModalHostElements): void {
+    this.detach();
+    this.host = host;
+    this.focusTrap = createFocusTrap(host.dialog);
+    this.applyHostAttributes();
+
+    if (this.manageDom) {
+      host.backdrop.addEventListener('click', this.handleBackdropClick);
+      host.closeButton?.addEventListener('click', this.handleCloseIconClick);
+      host.confirmButton?.addEventListener('click', this.handleConfirmClick);
+      host.cancelButton?.addEventListener('click', this.handleCancelClick);
+    }
+  }
+
+  detach(): void {
+    if (!this.host) return;
+
+    if (this.manageDom) {
+      this.host.backdrop.removeEventListener('click', this.handleBackdropClick);
+      this.host.closeButton?.removeEventListener('click', this.handleCloseIconClick);
+      this.host.confirmButton?.removeEventListener('click', this.handleConfirmClick);
+      this.host.cancelButton?.removeEventListener('click', this.handleCancelClick);
+    }
+
+    this.focusTrap?.deactivate();
+    this.focusTrap = null;
+    this.host = null;
+  }
+
+  async open(): Promise<boolean> {
+    if (this.opened || this.transitioning) return false;
+
+    this.emitter.emit('beforeOpen');
+    const allowed = await runLifecycle(this.options.beforeOpen);
+    if (!allowed) return false;
+
+    this.transitioning = true;
+    this.returnFocusEl = getReturnFocusElement(
+      this.options.returnFocus,
+      document.activeElement,
+    );
+
+    this.opened = true;
+    this.emitter.emit('openChange', true);
+
+    this.zIndex = modalStack.push({
+      id: this.id,
+      zIndexBase: this.options.zIndexBase,
+      activate: () => this.activateLayer(),
+      deactivate: () => this.deactivateLayer(),
+    });
+    this.stacked = true;
+
+    lockBodyScroll();
+    this.applyHostOpenState(true);
+
+    if (this.host && this.manageDom) {
+      const initial = resolveInitialFocus(this.options.initialFocus, this.host.dialog);
+      this.focusTrap?.activate(initial);
+    }
+
+    const duration = prefersReducedMotion() ? 0 : this.options.animationDuration;
+    await wait(duration);
+
+    this.transitioning = false;
+    this.options.afterOpen?.();
+    this.emitter.emit('afterOpen');
+    return true;
+  }
+
+  async close(reason: CloseReason = 'programmatic'): Promise<boolean> {
+    if (!this.opened || this.transitioning) return false;
+    if (this.loading && reason !== 'programmatic') return false;
+
+    this.emitter.emit('beforeClose', reason);
+    const allowed = await runLifecycle(this.options.beforeClose, reason);
+    if (!allowed) return false;
+
+    this.transitioning = true;
+    this.applyHostOpenState(false, true);
+
+    const duration = prefersReducedMotion() ? 0 : this.options.animationDuration;
+    await wait(duration);
+
+    this.opened = false;
+    this.emitter.emit('openChange', false);
+    this.teardownLayer();
+    this.applyHostOpenState(false, false);
+
+    restoreFocus(this.returnFocusEl);
+    this.returnFocusEl = null;
+    this.transitioning = false;
+
+    this.options.afterClose?.(reason);
+    this.emitter.emit('afterClose', reason);
+    return true;
+  }
+
+  async confirm(): Promise<void> {
+    if (!this.opened || this.loading) return;
+    this.emitter.emit('confirm');
+
+    const handler = this.options.onConfirm;
+    if (!handler) {
+      await this.close('confirm');
+      return;
+    }
+
+    this.setLoading(true);
+    try {
+      await handler();
+      await this.close('confirm');
+    } catch (error) {
+      this.setLoading(false);
+      throw error;
+    }
+  }
+
+  async cancel(): Promise<void> {
+    if (!this.opened || this.loading) return;
+    this.emitter.emit('cancel');
+
+    const handler = this.options.onCancel;
+    if (!handler) {
+      await this.close('cancel');
+      return;
+    }
+
+    this.setLoading(true);
+    try {
+      await handler();
+      await this.close('cancel');
+    } catch (error) {
+      this.setLoading(false);
+      throw error;
+    }
+  }
+
+  setLoading(loading: boolean): void {
+    if (this.loading === loading) return;
+    this.loading = loading;
+    this.emitter.emit('loadingChange', loading);
+
+    if (this.host) {
+      this.host.root.classList.toggle(CSS_CLASSES.loading, loading);
+      if (this.host.confirmButton) {
+        this.host.confirmButton.disabled = loading;
+        this.host.confirmButton.setAttribute('aria-busy', String(loading));
+      }
+      if (this.host.cancelButton) {
+        this.host.cancelButton.disabled = loading;
+      }
+      if (this.host.closeButton) {
+        (this.host.closeButton as HTMLButtonElement).disabled = loading;
+      }
+    }
+  }
+
+  handleBackdropClick = (): void => {
+    if (!this.opened || !this.options.closeOnBackdrop || this.options.persistent) return;
+    if (!modalStack.isTop(this.id)) return;
+    void this.close('backdrop');
+  };
+
+  handleCloseIconClick = (): void => {
+    if (!this.opened || this.loading) return;
+    void this.close('close-icon');
+  };
+
+  handleConfirmClick = (): void => {
+    void this.confirm();
+  };
+
+  handleCancelClick = (): void => {
+    void this.cancel();
+  };
+
+  handleKeyDown(event: KeyboardEvent): void {
+    if (!this.opened || event.key !== 'Escape') return;
+    if (!modalStack.isTop(this.id)) return;
+    if (!this.options.closeOnEsc || this.options.persistent || this.loading) return;
+
+    event.preventDefault();
+    event.stopPropagation();
+    void this.close('esc');
+  }
+
+  destroy(): void {
+    if (this.opened) {
+      this.opened = false;
+      this.teardownLayer();
+    }
+    this.detach();
+    this.emitter.clear();
+  }
+
+  private activateLayer(): void {
+    if (!this.manageDom) return;
+    document.addEventListener('keydown', this.boundKeyDown, true);
+    if (this.host && this.opened) {
+      const initial = resolveInitialFocus(this.options.initialFocus, this.host.dialog);
+      this.focusTrap?.activate(initial);
+    }
+  }
+
+  private deactivateLayer(): void {
+    if (!this.manageDom) return;
+    document.removeEventListener('keydown', this.boundKeyDown, true);
+    this.focusTrap?.deactivate();
+  }
+
+  private teardownLayer(): void {
+    if (this.stacked) {
+      modalStack.remove(this.id);
+      this.stacked = false;
+      unlockBodyScroll();
+    }
+    document.removeEventListener('keydown', this.boundKeyDown, true);
+    this.focusTrap?.deactivate();
+    this.setLoading(false);
+  }
+
+  private applyHostAttributes(): void {
+    if (!this.host) return;
+    const { root, dialog, panel } = this.host;
+    const opts = this.options;
+
+    root.dataset.modalId = opts.id;
+    root.style.setProperty('--um-z-index', String(this.zIndex || opts.zIndexBase));
+    root.style.setProperty('--um-animation-duration', `${opts.animationDuration}ms`);
+    root.classList.add(CSS_CLASSES.root);
+    root.classList.toggle(CSS_CLASSES.loading, this.loading);
+    if (opts.className) {
+      for (const token of opts.className.split(/\s+/).filter(Boolean)) {
+        root.classList.add(token);
+      }
+    }
+    applyModalTheme(root, opts.theme);
+
+    panel.dataset.size = opts.size;
+    panel.dataset.placement = opts.placement;
+
+    dialog.setAttribute('role', opts.role);
+    dialog.setAttribute('aria-modal', 'true');
+    dialog.tabIndex = -1;
+
+    const titleId = `${opts.id}-title`;
+    const descId = `${opts.id}-description`;
+
+    if (opts.ariaLabelledBy) {
+      dialog.setAttribute('aria-labelledby', opts.ariaLabelledBy);
+    } else if (opts.title) {
+      dialog.setAttribute('aria-labelledby', titleId);
+    } else if (opts.ariaLabel) {
+      dialog.setAttribute('aria-label', opts.ariaLabel);
+      dialog.removeAttribute('aria-labelledby');
+    }
+
+    if (opts.ariaDescribedBy) {
+      dialog.setAttribute('aria-describedby', opts.ariaDescribedBy);
+    } else if (opts.description) {
+      dialog.setAttribute('aria-describedby', descId);
+    }
+
+    if (this.host.closeButton) {
+      this.host.closeButton.hidden = !opts.showCloseIcon;
+      this.host.closeButton.setAttribute('aria-label', 'Close dialog');
+    }
+  }
+
+  private applyHostOpenState(open: boolean, closing = false): void {
+    if (!this.host) return;
+    const { root } = this.host;
+    root.classList.toggle(CSS_CLASSES.open, open && !closing);
+    root.classList.toggle(CSS_CLASSES.closing, closing);
+    root.style.setProperty('--um-z-index', String(this.zIndex || this.options.zIndexBase));
+    root.setAttribute('aria-hidden', open ? 'false' : 'true');
+    if (!open && !closing) {
+      root.hidden = true;
+    } else {
+      root.hidden = false;
+    }
+  }
+}
+
+function wait(ms: number): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    window.setTimeout(resolve, ms);
+  });
+}

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

@@ -0,0 +1,68 @@
+import { DEFAULT_Z_INDEX_BASE, Z_INDEX_LAYER_STEP } from './constants';
+
+export interface StackEntry {
+  id: string;
+  zIndexBase: number;
+  activate: () => void;
+  deactivate: () => void;
+}
+
+/**
+ * Global stack coordinating nested/stacked modals:
+ * - assigns increasing z-index layers
+ * - only the top modal receives ESC / focus-trap activation
+ */
+class ModalStackManager {
+  private readonly stack: StackEntry[] = [];
+
+  get size(): number {
+    return this.stack.length;
+  }
+
+  get top(): StackEntry | undefined {
+    return this.stack[this.stack.length - 1];
+  }
+
+  isTop(id: string): boolean {
+    return this.top?.id === id;
+  }
+
+  push(entry: StackEntry): number {
+    const previous = this.top;
+    previous?.deactivate();
+
+    this.stack.push(entry);
+    const zIndex = this.computeZIndex(entry);
+    entry.activate();
+    return zIndex;
+  }
+
+  remove(id: string): void {
+    const index = this.stack.findIndex((entry) => entry.id === id);
+    if (index === -1) return;
+
+    const [removed] = this.stack.splice(index, 1);
+    removed?.deactivate();
+
+    const top = this.top;
+    if (top) {
+      top.activate();
+    }
+  }
+
+  computeZIndex(entry: StackEntry): number {
+    const index = this.stack.findIndex((item) => item.id === entry.id);
+    const layer = index === -1 ? this.stack.length : index;
+    const base = entry.zIndexBase || DEFAULT_Z_INDEX_BASE;
+    return base + layer * Z_INDEX_LAYER_STEP;
+  }
+
+  clear(): void {
+    while (this.stack.length) {
+      const entry = this.stack.pop();
+      entry?.deactivate();
+    }
+  }
+}
+
+export const modalStack = new ModalStackManager();

package/packages/universal-modal/src/core/scroll-lock.ts

@@ -0,0 +1,78 @@
+interface ScrollLockState {
+  count: number;
+  previousOverflow: string;
+  previousPaddingRight: string;
+  previousPosition: string;
+  previousTop: string;
+  previousWidth: string;
+  scrollY: number;
+}
+
+let state: ScrollLockState | null = null;
+
+function getScrollbarWidth(): number {
+  if (typeof window === 'undefined') return 0;
+  return window.innerWidth - document.documentElement.clientWidth;
+}
+
+/**
+ * Reference-counted body scroll lock so nested modals unlock only when
+ * the last modal closes.
+ */
+export function lockBodyScroll(): void {
+  if (typeof document === 'undefined') return;
+
+  const body = document.body;
+  if (!state) {
+    const scrollbarWidth = getScrollbarWidth();
+    state = {
+      count: 0,
+      previousOverflow: body.style.overflow,
+      previousPaddingRight: body.style.paddingRight,
+      previousPosition: body.style.position,
+      previousTop: body.style.top,
+      previousWidth: body.style.width,
+      scrollY: window.scrollY,
+    };
+
+    body.style.overflow = 'hidden';
+    if (scrollbarWidth > 0) {
+      const currentPadding = Number.parseFloat(getComputedStyle(body).paddingRight) || 0;
+      body.style.paddingRight = `${currentPadding + scrollbarWidth}px`;
+    }
+
+    // iOS Safari fallback
+    body.style.position = 'fixed';
+    body.style.top = `-${state.scrollY}px`;
+    body.style.width = '100%';
+  }
+
+  state.count += 1;
+}
+
+export function unlockBodyScroll(): void {
+  if (typeof document === 'undefined' || !state) return;
+
+  state.count -= 1;
+  if (state.count > 0) return;
+
+  const body = document.body;
+  const { previousOverflow, previousPaddingRight, previousPosition, previousTop, previousWidth, scrollY } =
+    state;
+
+  body.style.overflow = previousOverflow;
+  body.style.paddingRight = previousPaddingRight;
+  body.style.position = previousPosition;
+  body.style.top = previousTop;
+  body.style.width = previousWidth;
+  window.scrollTo(0, scrollY);
+  state = null;
+}
+
+/** Test helper — reset lock state. */
+export function resetScrollLock(): void {
+  if (state) {
+    state.count = 1;
+    unlockBodyScroll();
+  }
+}

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

@@ -0,0 +1,50 @@
+import type { ModalTheme } from './types';
+
+const THEME_VAR_MAP: Record<keyof Omit<ModalTheme, 'cssVars'>, string> = {
+  brand: '--um-color-brand',
+  brandForeground: '--um-color-brand-fg',
+  confirmBg: '--um-btn-confirm-bg',
+  confirmFg: '--um-btn-confirm-fg',
+  confirmBorder: '--um-btn-confirm-border',
+  cancelBg: '--um-btn-cancel-bg',
+  cancelFg: '--um-btn-cancel-fg',
+  cancelBorder: '--um-btn-cancel-border',
+  focusRing: '--um-focus-ring',
+};
+
+function toCssVarName(name: string): string {
+  if (name.startsWith('--')) return name;
+  if (name.startsWith('um-')) return `--${name}`;
+  return `--um-${name}`;
+}
+
+/**
+ * Apply brand / button theme tokens onto a modal root element.
+ */
+export function applyModalTheme(target: HTMLElement, theme?: ModalTheme | null): void {
+  if (!theme) return;
+
+  for (const [key, cssVar] of Object.entries(THEME_VAR_MAP) as Array<
+    [keyof typeof THEME_VAR_MAP, string]
+  >) {
+    const value = theme[key];
+    if (typeof value === 'string' && value.length > 0) {
+      target.style.setProperty(cssVar, value);
+    }
+  }
+
+  // Keep accent aliases in sync when brand is customized.
+  if (theme.brand) {
+    target.style.setProperty('--um-color-accent', 'var(--um-color-brand)');
+  }
+  if (theme.brandForeground) {
+    target.style.setProperty('--um-color-accent-fg', 'var(--um-color-brand-fg)');
+  }
+
+  if (theme.cssVars) {
+    for (const [name, value] of Object.entries(theme.cssVars)) {
+      if (typeof value !== 'string') continue;
+      target.style.setProperty(toCssVarName(name), value);
+    }
+  }
+}