vanilla-aria-modals 1.0.0

package/LICENSE.txt

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 Angel Valentino
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# ModalHandler
+
+## Introduction
+
+`ModalHandler` is a framework-agnostic utility for managing accessibility (A11y) events in modals or modal-like UIs within your web application. It supports modal stacking and key accessibility features, including focus trapping, focus management, and closing modals with the Escape key or an outside click.
+
+Although designed primarily for modal interactions, it can be used in any UI logic that requires basic ARIA support and focus management.
+
+It supports a dynamic number of modals and events. In SPAs or dynamic interfaces, navigating away or re-rendering a component without closing a modal can leave lingering event listeners on `document.body`, which may interfere with future interactions. A reset method is provided to call on route changes or component unmounts. See more at: [SPA / Advanced Usage](#spa--advanced-usage)
+
+`ModalHandler` is written in vanilla JS for full flexibility. You can modify it directly in `node_modules` if needed. Just update the `.d.ts` file when changing public methods to keep IntelliSense accurate. Internals documentation, such as architecture and logic flow can be found [here](https://github.com/angelvalentino/vanilla-aria-modals/blob/main/docs/architecture.md).
+
+## Set up
+
+```js
+import ModalHandler from './ModalHandler';
+const modalHandler = new ModalHandler();
+```
+
+`ModalHandler` is a singleton, so creating multiple instances returns the same object.
+
+TypeScript types are used in the **docs** and in the **.d.ts** file to indicate the intended type and optionality of parameters, even though the class is fully vanilla JavaScript. This makes it easier to use, manage, and understand, without requiring any compiler.
+
+<br>
+
+## Usage
+
+A fully detailed example including the necessary JavaScript, HTML, and CSS files, can be found [here](https://github.com/angelvalentino/vanilla-aria-modals/tree/main/example).
+
+**Note:** `lm` in the code stands for *HTMLElement*.
+**Note:** `e.stopPropagation()` prevents other click events (like overlay clicks) from triggering while opening a modal. This can happen because when adding the open modal event, the ARIA events are also added during propagation and can trigger the overlay click event. It is already managed via the class with a timeout, but it is better for robustness to stop propagation here as well if bubbling is not needed in that instance.
+
+```js
+// Basic example of showing a modal
+showModal() {
+  modalContainerLm.style.display = 'block';
+}
+
+// Basic example of hiding a modal
+hideModal() {
+  modalContainerLm.style.display = 'none';
+}
+
+closeModal() {
+  hideModal();
+  // ...Your hide UI logic
+
+  // Restore focus
+  modalHandler.restoreFocus({
+    modalKey: 'myModal'
+  });
+
+  // Remove ARIA events added
+  modalHandler.removeA11yEvents({
+    modalKey: 'myModal',
+    modalLm: modalContentLm,
+    closeLms: [...modalCloseBtns]
+  });
+}
+
+
+openModal(e) {
+  // Stop event propagation to make sure no events are called on bubbling
+  e.stopPropagation();
+
+  showModal();
+  // ...Your show UI logic
+
+  // Add focus
+  modalHandler.addFocus({
+    modalKey: 'myModal',
+    firstFocusableLm: modalFirstFocusableLm
+  });
+
+  // Add ARIA events 
+  modalHandler.addA11yEvents({
+    modalKey: 'myModal',
+    modalLm: modalContentLm,
+    modalLmOuterLimits: modalContentLm,
+    closeLms: [...modalCloseBtns],
+    closeHandler: closeModal
+  });
+}
+
+const openModalBtn = document.getElementById('open-modal-btn');
+openModalBtn.addEventListener('click', openModal);
+```
+
+<br>
+
+## SPA / Advanced Usage
+
+In Single Page Applications (SPA) or frameworks like React, Vue, or vanilla JS with dynamic content, modals may persist across view changes. To prevent lingering events or broken focus, `ModalHandler` provides cleanup methods.
+
+### Example: Cleanup on route change or component unmount
+
+```js
+// Suppose your SPA route or component changes
+function onRouteChange() {
+  // Clear leftover document events, active modals, and focus tracking
+  modalHandler.reset();
+
+  // Or individually:
+  // modalHandler.clearDocumentBodyEvents();
+  // modalHandler.clearActiveModals();
+  // modalHandler.clearFocusRegistry();
+}
+```
+<br>
+
+## Public API Methods
+
+### setDebug()
+Enables or disables debug logs, aimed for reviewing stacked modals, clear and close logic.
+
+#### Parameters
+- **`bool: boolean;`** **true** enables debug mode, **false** disables it.
+
+Returns `void`
+
+### addA11yEvents()
+Registers ARIA events and modal stacking handling:
+- Close at overlay click
+- Close at ESC key
+- Trap focus
+- Modal stacking
+
+#### Parameters
+**Takes parameters as a single object, which are destructured inside the method.**
+
+- **`modalKey: string;`** Unique modal identifier. Used for stacking and event management.
+- **`modalLm?: HTMLElement | null;`** *(optional)* The main modal element. Used to trap focus inside the modal. 
+- **`modalLmOuterLimits?: HTMLElement | null;`** *(optional)* The container that defines the modal boundary. Used to detect clicks outside the modal. **modalLm** is usually used here, but depending on the UI we may not want to trap focus into the same container we want to close, maybe just in a part of it.
+- **`closeLms?: HTMLElement[] | null;`** *(optional)* Array of elements that should trigger closing the modal (e.g., close buttons).
+- **`exemptLms?: HTMLElement[];`** *(optional)* Array of elements that should not trigger closing even if clicked outside.
+- **`closeHandler: () => void;`** Function to call when the modal should close. Usually should call **removeA11yEvents()**.
+
+Returns `void`
+
+### removeA11yEvents()
+
+Removes all accessibility and interaction event listeners for the specific registered modal.
+
+#### Parameters
+**Takes parameters as a single object, which are destructured inside the method.**
+
+- **`modalKey: string;`** Unique modal identifier. Must match the modalKey used in **addA11yEvents()**.
+- **`modalLm?: HTMLElement | null;`** *(optional)* The main modal element. Used to be able to properly remove the trap focus event.
+- **`closeLms?: HTMLElement[] | null;`** *(optional)* Array of close elements used in **addA11yEvents()**. Used to be able to properly remove the close event from the given elements.
+
+Returns `void`
+
+### addFocus()
+
+Focuses a specific element inside a modal. If `auto` is **true**, the class automatically stores the last active element and manages its restoration later. If `auto` is **false**, the method returns the last active element so the user can handle it manually.
+
+#### Parameters
+**Takes parameters as a single object, which are destructured inside the method.**
+
+- **`modalKey: string;`** Unique modal identifier.
+- **`firstFocusableLm: HTMLElement;`** Element to receive focus.
+- **`lastFocusedLm?: HTMLElement | null;`** *(optional)* Stores a custom element as the last focused. Defaults to **document.activeElement**.
+- **`auto?: boolean;`** *(optional)* Defaults to **true**. If **false**, focus is returned but not stored for restoration. Can be used with truthy or falsy values as well.
+
+Returns `HTMLElement | void`
+
+### restoreFocus()
+Restores focus to the element that was active before the modal opened.
+
+#### Parameters
+**Takes parameters as a single object, which are destructured inside the method.**
+
+- **`modalKey: string;`** Unique modal identifier.
+- **`lastFocusedLm?: HTMLElement | null;`** *(optional)* Custom element to restore focus to if auto is **false**.
+- **`auto?: boolean;`** *(optional)* Defaults to **true**. If **false**, uses lastFocusedLm to restore focus instead of the stored one.
+
+Returns `void`
+
+### clearDocumentBodyEvents()
+Clears any leftover document body event listeners.
+
+Returns `void`
+
+### clearActiveModals()
+Resets the active modal stack.
+
+Returns `void`
+
+### clearFocusRegistry()
+Clears stored focus references.
+
+Returns `void`
+
+### reset()
+Combines **clearDocumentBodyEvents()**, **clearActiveModals()**, **clearFocusRegistry()** for a full cleanup.
+
+Returns `void`

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "vanilla-aria-modals",
+  "version": "1.0.0",
+  "description": "Framework-agnostic utility for managing accessibility in modals or modal-like UIs, including modal stacking, focus management, and closing via Escape key or outside click.",
+  "main": "src/ModalHandler.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/angelvalentino/vanilla-aria-modals.git"
+  },
+  "keywords": [
+    "modal",
+    "accessibility",
+    "aria",
+    "focus-trapping",
+    "keyboard",
+    "dialog",
+    "a11y",
+    "vanilla-js",
+    "ui",
+    "frontend",
+    "javascript"
+  ],
+  "author": "Angel Valentino <angelvalentino294@gmail.com> (https://angelvalentino.dev)",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/angelvalentino/vanilla-aria-modals/issues"
+  },
+  "homepage": "https://github.com/angelvalentino/vanilla-aria-modals#readme",
+  "type": "module"
+}

package/src/ModalHandler.d.ts

@@ -0,0 +1,41 @@
+export default class ModalHandler {
+    constructor();
+
+    setDebug(bool: boolean): void;
+
+    clearDocumentBodyEvents(): void;
+
+    clearActiveModals(): void;
+
+    clearFocusRegistry(): void;
+
+    reset(): void;
+
+    addA11yEvents(options: {
+      modalKey: string;
+      modalLm?: HTMLElement | null;
+      modalLmOuterLimits?: HTMLElement | null;
+      closeLms?: HTMLElement[] | null;
+      exemptLms?: HTMLElement[];
+      closeHandler: () => void;
+    }): void;
+
+    removeA11yEvents(options: {
+      modalKey: string;
+      modalLm?: HTMLElement | null;
+      closeLms?: HTMLElement[] | null;
+    }): void;
+
+    addFocus(options: {
+      modalKey: string;
+      firstFocusableLm: HTMLElement;
+      lastFocusedLm?: HTMLElement | null;
+      auto?: boolean;
+    }): HTMLElement | void;
+
+    restoreFocus(options: {
+      modalKey: string;
+      lastFocusedLm?: HTMLElement | null;
+      auto?: boolean;
+    }): void;
+  }

package/src/ModalHandler.js

@@ -0,0 +1,344 @@
+export default class ModalHandler {
+  #eventsHandler;
+  #activeModals;
+  #focusHandler;
+  #debug;
+
+  constructor() {
+    if (ModalHandler.instance) return ModalHandler.instance;
+    ModalHandler.instance = this;
+    this.#eventsHandler = {};
+    this.#activeModals = [];
+    this.#focusHandler = {};
+    this.#debug = false;
+  }
+
+  setDebug(bool) {
+    this.#debug = Boolean(bool);
+    console.info(`[ModalHandler]: Debug mode ${this.#debug ? 'ON' : 'OFF'}`);
+  }
+
+  #isActiveModal(modalKey) {
+    const modals = this.#activeModals;
+    return modals.length && modals[modals.length - 1] === modalKey;
+  }
+
+  #registerModal(modalKey) {
+    if (this.#activeModals.includes(modalKey)) {
+      console.warn(`[ModalHandler]: Modal with key "${modalKey}" is already registered. Skipping.`);
+      return false;
+    }
+
+    this.#activeModals.push(modalKey);
+
+    if (this.#debug) {
+      console.log(`[ModalHandler][DEBUG]: Register modal with key => "${modalKey}"`);
+      console.log('[ModalHandler][DEBUG]: Active modal stack => ', this.#activeModals);
+    }
+
+    return true;
+  }
+  
+  #unregisterModal(modalKey) {
+    if (!this.#activeModals.includes(modalKey)) {
+      console.warn(`[ModalHandler]: Modal with key "${modalKey}" was not registered. Nothing to remove.`);
+      return false;
+    }
+
+    if (this.#debug) {
+      console.log('[ModalHandler][DEBUG]: Active modal stack before filtering => ', this.#activeModals);
+    }
+
+    this.#activeModals = this.#activeModals.filter(key => key !== modalKey);
+
+    if (this.#debug) {
+      console.log(`[ModalHandler][DEBUG]: Unregister modal with key => "${modalKey}"`);
+      console.log('[ModalHandler][DEBUG]: Active modal stack after filtering => ', this.#activeModals);
+    }
+
+    return true;
+  }
+
+  #trapFocus(e, element) {
+    // Select all focusable elements within the given element
+    const focusableLms = element.querySelectorAll(`
+      a[href]:not([disabled]), 
+      button:not([disabled]), 
+      textarea:not([disabled]), 
+      input:not([disabled]), 
+      select:not([disabled]),
+      [tabindex]:not([tabindex="-1"])
+    `);
+    // Get the first and last focusable elements
+    const firstFocusableLm = focusableLms[0]; 
+    const lastFocusableLm = focusableLms[focusableLms.length - 1];
+
+    // Check if the Tab key was pressed
+    const isTabPressed = (e.key === 'Tab');
+    
+    // Exit if the Tab key was not pressed
+    if (!isTabPressed) { 
+      return; 
+    }
+
+    if (e.shiftKey) /* shift + tab */ {
+      if (document.activeElement === firstFocusableLm ) {
+        // If 'Shift + Tab' is pressed and focus is on the first element, move focus to the last element
+        lastFocusableLm.focus();
+        e.preventDefault();
+      }
+    } 
+    else /* tab */ {
+      if (document.activeElement === lastFocusableLm) {
+        // If Tab is pressed and focus is on the last element, move focus to the first element
+        firstFocusableLm.focus();
+        e.preventDefault();
+      }
+    }
+  }
+
+  #handleTrapFocus(modalLm) {
+    return e => {
+      this.#trapFocus(e, modalLm);
+    }
+  }
+
+  #handleEscapeKeyClose(closeHandler) {
+    return e => {
+      if (e.key === 'Escape') {
+        closeHandler(e);
+      }
+    }
+  }
+
+  #handleOutsideClickClose(closeHandler, modalLmOuterLimits, exemptLms = []) {
+    return e => {
+      const clickedLm = e.target;
+      
+      // Click was inside the modal
+      if (modalLmOuterLimits.contains(clickedLm)) {
+        return;
+      } 
+
+      // Click was outside the modal
+      const isClickOnExempt = exemptLms.some(exemptEl => exemptEl?.contains(clickedLm));
+      if (isClickOnExempt) {
+        return;
+      }
+
+      closeHandler(e);
+    }
+  }
+
+  #handleActiveModalClose(modalKey, closeHandler) {
+    return e => {
+      e.stopPropagation();
+      if (!this.#isActiveModal(modalKey)) return;
+
+      if (this.#debug) {
+        console.log(`[ModalHandler][DEBUG]: Close modal with key => "${modalKey}"`);
+      }
+
+      closeHandler(); // Only close if this is the topmost modal
+    }
+  }
+
+  clearDocumentBodyEvents() {
+    const documentBodyEvents = this.#eventsHandler.documentBody;
+
+    if (documentBodyEvents) {
+      if (this.#debug) {
+        console.log('[ModalHandler][DEBUG]: Stored document body events before clearing => ', documentBodyEvents);
+      }
+
+      for (const key in documentBodyEvents) {
+        const events = documentBodyEvents[key];
+
+        events.forEach(eventHandler => {
+          document.body.removeEventListener(eventHandler.eventName, eventHandler.callback);
+        });
+
+        events.length = 0;
+      }
+
+      if (this.#debug) {
+        console.log('[ModalHandler][DEBUG]: Stored document body events after clearing => ', documentBodyEvents);
+      }
+    } 
+    else {
+      if (this.#debug) {
+        console.log('[ModalHandler][DEBUG]: No document body events were found to be cleared.');
+      }
+    }
+  }
+
+  clearActiveModals() {
+    if (this.#debug) {
+      console.log('[ModalHandler][DEBUG]: Active modal stack before clearing => ', this.#activeModals);
+    }
+
+    this.#activeModals.length = 0;
+
+    if (this.#debug) {
+      console.log('[ModalHandler][DEBUG]: Active modal stack after clearing => ', this.#activeModals);
+    }
+  }
+
+  clearFocusRegistry() {
+    if (this.#debug) {
+      console.log('[ModalHandler][DEBUG]: Focus registry before clearing => ', this.#focusHandler);
+    }
+
+    for (const key in this.#focusHandler) {
+      delete this.#focusHandler[key];
+    }
+
+    if (this.#debug) {
+      console.log('[ModalHandler][DEBUG]: Focus registry after clearing => ', this.#focusHandler);
+    }
+  }
+
+  reset() {
+    this.clearDocumentBodyEvents();
+    this.clearActiveModals();
+    this.clearFocusRegistry();
+  }
+
+  addA11yEvents({
+    modalKey,
+    modalLm = null, 
+    modalLmOuterLimits = null,
+    closeLms = null, 
+    exemptLms = [],
+    closeHandler
+  }) {
+    // Extra guard to protect against event bubbling after modal open
+    setTimeout(() => {
+      // Register modal key and skip if already registered
+      const isNew = this.#registerModal(modalKey);
+      if (!isNew) return;
+
+      // Register event handlers reference
+      const handleActiveModalClose = this.#handleActiveModalClose(modalKey, closeHandler);
+      const escapeKeyHandler = this.#handleEscapeKeyClose(handleActiveModalClose);
+      const outsideClickHandler = this.#handleOutsideClickClose(handleActiveModalClose, modalLmOuterLimits, exemptLms);
+      const trapFocusHandler = this.#handleTrapFocus(modalLm);
+
+      // Attach event listeners
+      document.body.addEventListener('keydown', escapeKeyHandler);
+      
+      if (modalLmOuterLimits) {
+        document.body.addEventListener('click', outsideClickHandler);
+      }
+      if (modalLm) {
+        modalLm.addEventListener('keydown', trapFocusHandler);
+      }
+      if (closeLms && Array.isArray(closeLms)) {
+        closeLms.forEach(closeLm => {
+          closeLm.addEventListener('click', handleActiveModalClose);
+        });
+      }
+      
+      // Ensure eventsHandler object exists for this modal
+      if (!this.#eventsHandler[modalKey]) {
+        this.#eventsHandler[modalKey] = {};
+      }
+      const eventsHandler = this.#eventsHandler[modalKey];
+
+      // Ensure the documentBody object and array exist for this modal key
+      if (!this.#eventsHandler.documentBody) {
+        this.#eventsHandler.documentBody = {};
+      }
+      if (!this.#eventsHandler.documentBody[modalKey]) {
+        this.#eventsHandler.documentBody[modalKey] = [];
+      }
+      const documentEvents = this.#eventsHandler.documentBody[modalKey];
+
+      // Store event handlers references so they can be removed later
+      eventsHandler.escapeKeyHandler = escapeKeyHandler;
+      modalLmOuterLimits && (eventsHandler.outsideClickHandler = outsideClickHandler);
+      modalLm && (eventsHandler.trapFocusHandler = trapFocusHandler);
+      closeLms && (eventsHandler.closeHandler = handleActiveModalClose);
+
+      // Keep references to body events for SPA view changes,
+      // so lingering events can be removed if the modal stays open across re-renders
+      documentEvents.push({ eventName: 'keydown', callback: escapeKeyHandler });
+      if (modalLmOuterLimits) {
+        documentEvents.push({ eventName: 'click', callback: outsideClickHandler });
+      }
+    });
+  }
+
+  removeA11yEvents({
+    modalKey,
+    modalLm = null, 
+    closeLms = null
+  }) {
+    // Unregister modal key and skip if it wasn't registered
+    const isRegistered = this.#unregisterModal(modalKey);
+    if (!isRegistered) return;
+
+    const eventsHandler = this.#eventsHandler[modalKey];
+
+    // Remove event listeners from elements
+    document.body.removeEventListener('keydown', eventsHandler.escapeKeyHandler);
+    
+    if (eventsHandler.outsideClickHandler) {
+      document.body.removeEventListener('click', eventsHandler.outsideClickHandler);
+    }
+    if (modalLm) {
+      modalLm.removeEventListener('keydown', eventsHandler.trapFocusHandler);
+    }
+    if (closeLms && Array.isArray(closeLms)) {
+      closeLms.forEach(closeLm => {
+        closeLm.removeEventListener('click', eventsHandler.closeHandler);
+      });
+    }
+    
+    // Clean up stored handlers
+    delete this.#eventsHandler[modalKey]; 
+    const documentEvents = this.#eventsHandler.documentBody[modalKey];
+    documentEvents.length = 0;
+  }
+
+  addFocus({
+    modalKey, 
+    firstFocusableLm, 
+    lastFocusedLm = null, 
+    auto = true
+  }) {
+    if (auto && Object.hasOwn(this.#focusHandler, modalKey)) {
+      console.warn(`[ModalHandler]: Duplicate focus registration for modal "${modalKey}"`);
+      return;
+    }
+
+    const lastFocusableLm = lastFocusedLm ? lastFocusedLm : document.activeElement;
+    if (auto) this.#focusHandler[modalKey] = lastFocusableLm;
+
+    // Needs a timeout for keyboard navigation, if not focus is unreliable
+    setTimeout(() => {
+      firstFocusableLm.focus();
+    });
+
+    if (!auto) return lastFocusableLm;
+  }
+
+  restoreFocus({
+    modalKey, 
+    lastFocusedLm = null, 
+    auto = true
+  }) {
+    if (auto && !Object.hasOwn(this.#focusHandler, modalKey)) {
+      console.warn(`[ModalHandler]: No stored focus for modal "${modalKey}" to restore.`);
+      return;
+    }
+
+    const lastFocusableLm = auto ? this.#focusHandler[modalKey] : lastFocusedLm;
+    lastFocusableLm.focus();
+
+    // Clean up the stored focus
+    if (auto) {
+      delete this.#focusHandler[modalKey];
+    }
+  }
+}