vanilla-aria-modals 1.0.3 → 1.1.1

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to this project will be documented in this file. Dates use ISO 8601 formatting, and version numbers follow [Semantic Versioning](https://semver.org/).
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [1.1.1] - 2026-02-15
+### Fixed
+- Fix typos, update changelog, and add an example wrapper usage for the `closeHandler`.
+
+## [1.1.0] - 2026-02-15
+### Added
+- Support automatic modal key generation
+- Add a manual method to rebind the trap focus handler
+
+### Changed
+- Improve automation and simplify logic flow
+- Improve event-bubbling guard by binding the overlay method with `capture: true` and removing the dependency on asynchronous behavior and `e.stopPropagation`
+- Extend `closeHandler` method with a new `modalKey` parameter for caller usage
+
+### Fixed
+- Prevent overlayless modals from breaking the stacking order
 
 ## [1.0.3] - 2026-01-23
 ### Fixed

package/README.md

@@ -1,7 +1,10 @@
 # ModalHandler
 
+See the full release history and updates in the [Changelog](https://github.com/angelvalentino/vanilla-aria-modals/blob/main/CHANGELOG.md).
+
 ## 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.
@@ -27,9 +30,9 @@ TypeScript types are used in the **docs** and in the **.d.ts** file to indicate
 
 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:** The **closeHandler** receives both the original **DOM event** and the associated **modalKey** automatically. The caller can use these to inspect the event or determine which modal triggered the close.
 
-**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.
+**Note:** `lm` in the code stands for *HTMLElement*.
 
 ```js
 // Basic example of showing a modal
@@ -42,40 +45,31 @@ hideModal() {
   modalContainerLm.style.display = 'none';
 }
 
-closeModal() {
-  hideModal();
-  // ...Your hide UI logic
+openModal() {
+  // Generate a key or use your own
+  const modalKey = modalHandler.generateKey();
 
-  // Restore focus
-  modalHandler.restoreFocus({
-    modalKey: 'myModal'
-  });
+  const closeModal = () => {
+    hideModal();
+    // ...Your hide UI logic
 
-  // 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();
+    // Restore focus
+    modalHandler.restoreFocus({ modalKey: modalKey });
+    // Remove ARIA events added
+    modalHandler.removeA11yEvents({ modalKey: modalKey });
+  }
 
   showModal();
   // ...Your show UI logic
 
   // Add focus
   modalHandler.addFocus({
-    modalKey: 'myModal',
+    modalKey: modalKey,
     firstFocusableLm: modalFirstFocusableLm
   });
-
   // Add ARIA events 
   modalHandler.addA11yEvents({
-    modalKey: 'myModal',
+    modalKey: modalKey,
     modalLm: modalContentLm,
     modalLmOuterLimits: modalContentLm,
     closeLms: [...modalCloseBtns],
@@ -98,13 +92,14 @@ In Single Page Applications (SPA) or frameworks like React, Vue, or vanilla JS w
 ```js
 // Suppose your SPA route or component changes
 function onRouteChange() {
-  // Clear leftover document events, active modals, and focus tracking
+  // Clear leftover document events, active modals, focus tracking and modal ID key counter
   modalHandler.reset();
 
   // Or individually:
   // modalHandler.clearDocumentBodyEvents();
   // modalHandler.clearActiveModals();
   // modalHandler.clearFocusRegistry();
+  // modalHandler.resetKeys();
 }
 ```
 <br>
@@ -134,7 +129,22 @@ Registers ARIA events and modal stacking handling:
 - **`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()**.
+- **`closeHandler: (e: Event, modalKey: string) => void;`** Function to call when the modal should close. Usually should call **removeA11yEvents()**. Automatically receives the event **(e)** and **(modalKey)** from the wrapper; no need to pass as arguments. It’s up to the caller whether to use them.
+If you need to pass additional arguments to the close handler, you can wrap it in a function that returns a handler accepting only the two parameters (`e` and `modalKey`):
+  
+  ```js
+  const closeModalWrapper = (...args) => {
+    // Returns a handler that the utility calls internally with e and modalKey
+    return (e, modalKey) => {
+      // Your logic for the close handler here 
+      // Access to parameters thanks to closures
+    }
+  }
+
+  modalHandler.addA11yEvents({
+    closeHandler: closeModalWrapper(...args)
+  });
+  ```
 
 Returns `void`
 
@@ -146,8 +156,7 @@ Removes all accessibility and interaction event listeners for the specific regis
 **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.
+- **`isToggle?: boolean;`** Optional flag to indicate that the modal (no overlay, usually popups with toggle logic) is being closed via a toggle action (outside of the usual close handler). Setting this flag to **true** ensures the modal is properly removed from the active stack, even when called outside of any closing handler.
 
 Returns `void`
 
@@ -195,4 +204,25 @@ Returns `void`
 ### reset()
 Combines **clearDocumentBodyEvents()**, **clearActiveModals()**, **clearFocusRegistry()** for a full cleanup.
 
-Returns `void`
+Returns `void`
+
+### generateKey()
+Generates a unique identifier for the modal.
+
+- **`prefix?: string;`** Optional prefix to modify the generated modal key.
+
+Returns `string`. The generated modal key to be used later in the code.
+
+### resetKeys()
+
+Resets the internal modal key counter back to 0.
+
+Returns `void`
+
+### rebindTrapFocus()
+
+Re-attaches the focus-trapping event listener for a specific modal. The internal **trapFocus** method already queries the DOM on each keyboard event, so in most cases, manually rebinding is not necessary.
+
+- **`modalKey: string;`** The unique key of the modal whose focus trap should be rebound.
+
+returns `void`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-aria-modals",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "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": {
@@ -13,15 +13,18 @@
   "keywords": [
     "modal",
     "accessibility",
-    "aria",
+    "ARIA",
+    "WAI-ARIA",
+    "A11y",
     "trap-focus",
+    "focus-trap",
     "keyboard",
     "dialog",
-    "a11y",
     "vanilla-js",
-    "ui",
-    "frontend",
     "javascript",
+    "js",
+    "UI",
+    "frontend",
     "keyboard-navigation",
     "modal-manager",
     "focus-management",

package/src/ModalHandler.d.ts

@@ -11,6 +11,12 @@ export default class ModalHandler {
 
     reset(): void;
 
+    generateKey(prefix?: string): string;
+
+    resetKeys(): void;
+
+    rebindTrapFocus(modalKey: string): void;
+
     addA11yEvents(options: {
       modalKey: string;
       modalLm?: HTMLElement | null;
@@ -22,8 +28,7 @@ export default class ModalHandler {
 
     removeA11yEvents(options: {
       modalKey: string;
-      modalLm?: HTMLElement | null;
-      closeLms?: HTMLElement[] | null;
+      isToggle?: boolean
     }): void;
 
     addFocus(options: {

package/src/ModalHandler.js

@@ -1,16 +1,18 @@
 export default class ModalHandler {
+  #debug;
   #eventsHandler;
-  #activeModals;
   #focusHandler;
-  #debug;
+  #activeModals;
+  #modalIdCounter
 
   constructor() {
     if (ModalHandler.instance) return ModalHandler.instance;
     ModalHandler.instance = this;
+    this.#debug = false;
     this.#eventsHandler = {};
-    this.#activeModals = [];
     this.#focusHandler = {};
-    this.#debug = false;
+    this.#activeModals = [];
+    this.#modalIdCounter = 0;
   }
 
   setDebug(bool) {
@@ -39,7 +41,7 @@ export default class ModalHandler {
     return true;
   }
   
-  #unregisterModal(modalKey) {
+  #unregisterModal(modalKey, isOverlayLess) {
     if (!this.#activeModals.includes(modalKey)) {
       console.warn(`[ModalHandler]: Modal with key "${modalKey}" was not registered. Nothing to remove.`);
       return false;
@@ -49,13 +51,27 @@ export default class ModalHandler {
       console.log('[ModalHandler][DEBUG]: Active modal stack before filtering => ', this.#activeModals);
     }
 
-    this.#activeModals = this.#activeModals.filter(key => key !== modalKey);
+    if (isOverlayLess) {
+      if (this.#debug) {
+        console.log('[ModalHandler][DEBUG]: Overlayless modal closed ignoring stacking order.');
+      }
+
+      this.#activeModals = this.#activeModals.filter(key => key !== modalKey);
+    } 
+    else {
+      this.#activeModals.pop();
+    }
 
     if (this.#debug) {
       console.log(`[ModalHandler][DEBUG]: Unregister modal with key => "${modalKey}"`);
       console.log('[ModalHandler][DEBUG]: Active modal stack after filtering => ', this.#activeModals);
     }
 
+    if (this.#activeModals.length === 0) {
+      if (this.#debug) console.log('[ModalHandler][DEBUG]: Active modal stack is now empty.');
+      this.resetKeys();
+    }
+
     return true;
   }
 
@@ -103,15 +119,15 @@ export default class ModalHandler {
     }
   }
 
-  #handleEscapeKeyClose(closeHandler) {
+  #handleEscapeKeyClose(modalKey, closeHandler) {
     return e => {
       if (e.key === 'Escape') {
-        closeHandler(e);
+        closeHandler(e, modalKey);
       }
     }
   }
 
-  #handleOutsideClickClose(closeHandler, modalLmOuterLimits, exemptLms = []) {
+  #handleOutsideClickClose(modalKey, closeHandler, modalLmOuterLimits, exemptLms) {
     return e => {
       const clickedLm = e.target;
       
@@ -126,20 +142,27 @@ export default class ModalHandler {
         return;
       }
 
-      closeHandler(e);
+      closeHandler(e, modalKey);
     }
   }
 
-  #handleActiveModalClose(modalKey, closeHandler) {
+  #handleActiveModalClose(modalKey, closeHandler, modalLmOuterLimits) {
     return e => {
-      e.stopPropagation();
-      if (!this.#isActiveModal(modalKey)) return;
+      // Check if modal is overlayless and triggered by click so we can ignore stacking order later
+      const isOverlayLess = !modalLmOuterLimits && e?.type === 'click';
+
+      if (!isOverlayLess && !this.#isActiveModal(modalKey)) {
+        return;
+      }
+
+      const isRegistered = this.#unregisterModal(modalKey, isOverlayLess);
+      if (!isRegistered) return;
 
       if (this.#debug) {
         console.log(`[ModalHandler][DEBUG]: Close modal with key => "${modalKey}"`);
       }
 
-      closeHandler(); // Only close if this is the topmost modal
+      closeHandler(e, modalKey); // Only close if this is the topmost modal
     }
   }
 
@@ -154,8 +177,13 @@ export default class ModalHandler {
       for (const key in documentBodyEvents) {
         const events = documentBodyEvents[key];
 
-        events.forEach(eventHandler => {
-          document.body.removeEventListener(eventHandler.eventName, eventHandler.callback);
+        events.forEach(({ eventName, callback, isOutsideClickHandler }) => {
+          if (isOutsideClickHandler) {
+            document.body.removeEventListener(eventName, callback, true);
+          } 
+          else {
+            document.body.removeEventListener(eventName, callback);
+          }
         });
 
         events.length = 0;
@@ -202,6 +230,25 @@ export default class ModalHandler {
     this.clearDocumentBodyEvents();
     this.clearActiveModals();
     this.clearFocusRegistry();
+    this.resetKeys();
+  }
+
+  generateKey(prefix = 'modal') {
+    this.#modalIdCounter = (this.#modalIdCounter || 0) + 1;
+    return `${prefix}-${this.#modalIdCounter}`;
+  }
+
+  resetKeys() {
+    this.#modalIdCounter = 0;
+  }
+
+  rebindTrapFocus(modalKey) {
+    const eventsHandler = this.#eventsHandler[modalKey];
+    const trapFocusHandler = eventsHandler.find(hander => hander.isTrapFocusHandler === true);
+    const { lm, eventName, callback } = trapFocusHandler;
+
+    lm.removeEventListener(eventName, callback);
+    lm.addEventListener(eventName, callback);
   }
 
   addA11yEvents({
@@ -212,91 +259,92 @@ export default class ModalHandler {
     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;
-
+    // 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, modalLmOuterLimits);
+    const escapeKeyHandler = this.#handleEscapeKeyClose(modalKey, handleActiveModalClose);
+
+    // Ensure storage for this modal exists
+    if (!this.#eventsHandler[modalKey]) this.#eventsHandler[modalKey] = [];
+    if (!this.#eventsHandler.documentBody) this.#eventsHandler.documentBody = {};
+    if (!this.#eventsHandler.documentBody[modalKey]) this.#eventsHandler.documentBody[modalKey] = [];
+    
     const eventsHandler = this.#eventsHandler[modalKey];
+    const documentEvents = this.#eventsHandler.documentBody[modalKey];
 
-    // Remove event listeners from elements
-    document.body.removeEventListener('keydown', eventsHandler.escapeKeyHandler);
+    // Attach event listeners
+    document.body.addEventListener('keydown', escapeKeyHandler);
+    eventsHandler.push({ eventName: 'keydown', callback: escapeKeyHandler });
+    // 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 (eventsHandler.outsideClickHandler) {
-      document.body.removeEventListener('click', eventsHandler.outsideClickHandler);
+    if (modalLmOuterLimits) {
+      const outsideClickHandler = this.#handleOutsideClickClose(modalKey, handleActiveModalClose, modalLmOuterLimits, exemptLms);
+
+      // Use capture phase to detect outside clicks before event bubbling, 
+      // preventing auto-close on overlay click after modal opens
+      document.body.addEventListener('click', outsideClickHandler, true); 
+      eventsHandler.push({ eventName: 'click', callback: outsideClickHandler, isOutsideClickHandler: true });
+      // Keep references to body events for SPA view changes
+      documentEvents.push({ eventName: 'click', callback: outsideClickHandler, isOutsideClickHandler: true });
     }
     if (modalLm) {
-      modalLm.removeEventListener('keydown', eventsHandler.trapFocusHandler);
+      const trapFocusHandler = this.#handleTrapFocus(modalLm);
+      
+      modalLm.addEventListener('keydown', trapFocusHandler);
+      eventsHandler.push({ lm: modalLm, eventName: 'keydown', callback: trapFocusHandler, isTrapFocusHandler: true });
     }
     if (closeLms && Array.isArray(closeLms)) {
       closeLms.forEach(closeLm => {
-        closeLm.removeEventListener('click', eventsHandler.closeHandler);
+        closeLm.addEventListener('click', handleActiveModalClose);
       });
+      eventsHandler.push({ lm: closeLms, eventName: 'click', callback: handleActiveModalClose });
     }
+  }
+
+  removeA11yEvents({
+    modalKey,
+    isToggle,
+  }) {
+    if (isToggle) {
+      const removed = this.#unregisterModal(modalKey, isToggle);
+      if (this.#debug && removed) {
+        console.log('[ModalHandler][DEBUG]: Overlayless modal not triggered on close; removed via event cleanup.');
+      }
+    }
+
+    const eventsHandler = this.#eventsHandler[modalKey];
+
+    // Event cleanup
+    eventsHandler.forEach(({ lm, eventName, callback, isOutsideClickHandler }) => {
+      // if lm is undefined we just have to clear the body
+      if (lm === undefined) lm = document.body;
+
+      // Check for array of closing lms
+      if (Array.isArray(lm)) {
+        const lms = lm;
+
+        lms.forEach(lm => {
+          lm.removeEventListener(eventName, callback);
+        });
+      } 
+      else {
+        if (isOutsideClickHandler) {
+          lm.removeEventListener(eventName, callback, true);
+        } 
+        else {
+          lm.removeEventListener(eventName, callback);
+        }
+      }
+    });
     
     // Clean up stored handlers
-    delete this.#eventsHandler[modalKey]; 
+    this.#eventsHandler[modalKey].length = 0; // empties the array to remove any lingering references
+    delete this.#eventsHandler[modalKey]; // removes the property entirely from the eventsHandler object
     const documentEvents = this.#eventsHandler.documentBody[modalKey];
     documentEvents.length = 0;
   }