vanilla-aria-modals 1.1.3 → 1.1.4

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file. Dates use I
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.1.4] - 2026-02-16
+### Fixed
+- Improve overlayless modal close logic. Removed the `isToggle` parameter from `removeA11yEvents` as it is no longer needed. The logic now works more smoothly, only unregisters modals in `removeA11yEvents` instead of the close handler wrapper, and preserves the overlayless modal bypass behavior
+
+### Changed
+- Update documentation, method order and chaining, and debug statements
+
 ## [1.1.3] - 2026-02-16
 ### Fixed
 - Add missing parameter titles to `README.md`. 
@@ -31,15 +38,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [1.0.3] - 2026-01-23
 ### Fixed
-- Improved `README.md` format for usage section
+- Improve `README.md` format for usage section
 
 ## [1.0.2] - 2026-01-23
 ### Fixed
-- Updated `package.json` keywords
+- Update `package.json` keywords
 
 ## [1.0.1] - 2026-01-23
 ### Fixed
-- Updated installation instructions for `README.md`
+- Update installation instructions for `README.md`
 
 ## [1.0.0] - 2026-01-23
 ### Added

package/README.md

@@ -1,17 +1,16 @@
-# ModalHandler
+# vanilla-aria-modals
 
 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.
+`vanilla-aria-modals` 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).
+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
 
@@ -92,14 +91,17 @@ 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, focus tracking and modal ID key counter
+  // Clear leftover document events, active modals, focus tracking, modal ID key counter 
+  // and overlayless modals registry
   modalHandler.reset();
 
   // Or individually:
-  // modalHandler.clearDocumentBodyEvents();
-  // modalHandler.clearActiveModals();
-  // modalHandler.clearFocusRegistry();
-  // modalHandler.resetKeys();
+  // modalHandler
+  //  .clearDocumentBodyEvents()
+  //  .clearActiveModals()
+  //  .clearFocusRegistry()
+  //  .resetKeys()
+  //  .clearPopups();
 }
 ```
 <br>
@@ -114,8 +116,59 @@ Enables or disables debug logs, aimed for reviewing stacked modals, clear and cl
 
 Returns `void`
 
+### generateKey()
+Generates a unique identifier for the modal.
+
+#### Parameters
+
+- **`prefix?: string;`** Optional prefix to modify the generated modal key.
+
+Returns `string`. The generated modal key to be used later in the code.
+
+### clearDocumentBodyEvents()
+Clears any leftover document body event listeners.
+
+Returns `this`
+
+### clearActiveModals()
+Resets the active modal stack.
+
+Returns `this`
+
+### clearFocusRegistry()
+Clears stored focus references.
+
+Returns `this`
+
+### resetKeys()
+
+Resets the internal modal key counter back to 0.
+
+Returns `this`
+
+### clearPopups()
+
+Clears the internal overlayless modals (popups) array
+
+Returns `this`
+
+### reset()
+Combines **clearDocumentBodyEvents()**, **clearActiveModals()**, **clearFocusRegistry()**, **resetKeys**, **clearPopups()** for a full cleanup.
+
+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.
+
+#### Parameters
+
+- **`modalKey: string;`** The unique key of the modal whose focus trap should be rebound.
+
+Returns `void`
+
 ### addA11yEvents()
-Registers ARIA events and modal stacking handling:
+Registers A11y events and modal stacking handling:
 - Close at overlay click
 - Close at ESC key
 - Trap focus
@@ -151,13 +204,12 @@ Returns `void`
 
 ### removeA11yEvents()
 
-Removes all accessibility and interaction event listeners for the specific registered modal.
+Removes all A11y 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()**.
-- **`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`
 
@@ -185,49 +237,4 @@ Restores focus to the element that was active before the modal opened.
 - **`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`
-
-### generateKey()
-Generates a unique identifier for the modal.
-
-#### Parameters
-
-- **`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.
-
-#### Parameters
-
-- **`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.1.3",
+  "version": "1.1.4",
   "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": {

package/src/ModalHandler.d.ts

@@ -3,17 +3,19 @@ export default class ModalHandler {
 
     setDebug(bool: boolean): void;
 
-    clearDocumentBodyEvents(): void;
+    generateKey(prefix?: string): string;
 
-    clearActiveModals(): void;
+    clearDocumentBodyEvents(): this;
 
-    clearFocusRegistry(): void;
+    clearActiveModals(): this;
 
-    reset(): void;
+    clearFocusRegistry(): this;
 
-    generateKey(prefix?: string): string;
+    resetKeys(): this;
 
-    resetKeys(): void;
+    clearPopups(): this;
+
+    reset(): void;
 
     rebindTrapFocus(modalKey: string): void;
 

package/src/ModalHandler.js

@@ -3,7 +3,8 @@ export default class ModalHandler {
   #eventsHandler;
   #focusHandler;
   #activeModals;
-  #modalIdCounter
+  #modalIdCounter;
+  #popups;
 
   constructor() {
     if (ModalHandler.instance) return ModalHandler.instance;
@@ -13,6 +14,7 @@ export default class ModalHandler {
     this.#focusHandler = {};
     this.#activeModals = [];
     this.#modalIdCounter = 0;
+    this.#popups = [];
   }
 
   setDebug(bool) {
@@ -50,10 +52,12 @@ export default class ModalHandler {
     if (this.#debug) {
       console.log('[ModalHandler][DEBUG]: Active modal stack before filtering => ', this.#activeModals);
     }
-
+    
+    // Check if the modal closed is overlayless (popup), 
+    // if so clear it from the stack without following normal LIFO order
     if (isOverlayLess) {
       if (this.#debug) {
-        console.log('[ModalHandler][DEBUG]: Overlayless modal closed ignoring stacking order.');
+        console.log('[ModalHandler][DEBUG]: Overlayless modal closed ignoring stacking order. (only click events)');
       }
 
       this.#activeModals = this.#activeModals.filter(key => key !== modalKey);
@@ -151,13 +155,11 @@ export default class ModalHandler {
       // Check if modal is overlayless and triggered by click so we can ignore stacking order later
       const isOverlayLess = !modalLmOuterLimits && e?.type === 'click';
 
+      // Only check stack for modals with overlay
       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}"`);
       }
@@ -166,12 +168,17 @@ export default class ModalHandler {
     }
   }
 
+  generateKey(prefix = 'modal') {
+    this.#modalIdCounter = (this.#modalIdCounter || 0) + 1;
+    return `${prefix}-${this.#modalIdCounter}`;
+  }
+
   clearDocumentBodyEvents() {
     const documentBodyEvents = this.#eventsHandler.documentBody;
 
     if (documentBodyEvents) {
       if (this.#debug) {
-        console.log('[ModalHandler][DEBUG]: Stored document body events before clearing => ', documentBodyEvents);
+        console.log('[ModalHandler][DEBUG]: Stored document body events before clear => ', documentBodyEvents);
       }
 
       for (const key in documentBodyEvents) {
@@ -190,7 +197,7 @@ export default class ModalHandler {
       }
 
       if (this.#debug) {
-        console.log('[ModalHandler][DEBUG]: Stored document body events after clearing => ', documentBodyEvents);
+        console.log('[ModalHandler][DEBUG]: Stored document body events after clear => ', documentBodyEvents);
       }
     } 
     else {
@@ -198,23 +205,27 @@ export default class ModalHandler {
         console.log('[ModalHandler][DEBUG]: No document body events were found to be cleared.');
       }
     }
+
+    return this;
   }
 
   clearActiveModals() {
     if (this.#debug) {
-      console.log('[ModalHandler][DEBUG]: Active modal stack before clearing => ', this.#activeModals);
+      console.log('[ModalHandler][DEBUG]: Active modal stack before clear => ', this.#activeModals);
     }
 
     this.#activeModals.length = 0;
 
     if (this.#debug) {
-      console.log('[ModalHandler][DEBUG]: Active modal stack after clearing => ', this.#activeModals);
+      console.log('[ModalHandler][DEBUG]: Active modal stack after clear => ', this.#activeModals);
     }
+
+    return this;
   }
 
   clearFocusRegistry() {
     if (this.#debug) {
-      console.log('[ModalHandler][DEBUG]: Focus registry before clearing => ', this.#focusHandler);
+      console.log('[ModalHandler][DEBUG]: Focus registry before clear => ', this.#focusHandler);
     }
 
     for (const key in this.#focusHandler) {
@@ -222,24 +233,47 @@ export default class ModalHandler {
     }
 
     if (this.#debug) {
-      console.log('[ModalHandler][DEBUG]: Focus registry after clearing => ', this.#focusHandler);
+      console.log('[ModalHandler][DEBUG]: Focus registry after clear => ', this.#focusHandler);
     }
+
+    return this;
   }
 
-  reset() {
-    this.clearDocumentBodyEvents();
-    this.clearActiveModals();
-    this.clearFocusRegistry();
-    this.resetKeys();
+  resetKeys() {
+    if (this.#debug) {
+      console.log('[ModalHandler][DEBUG]: Modal ID counter before reset => ', this.#modalIdCounter);
+    }
+
+    this.#modalIdCounter = 0;
+
+    if (this.#debug) {
+      console.log('[ModalHandler][DEBUG]: Modal ID counter after reset => ', this.#modalIdCounter);
+    }
+
+    return this;
   }
 
-  generateKey(prefix = 'modal') {
-    this.#modalIdCounter = (this.#modalIdCounter || 0) + 1;
-    return `${prefix}-${this.#modalIdCounter}`;
+  clearPopups() {
+    if (this.#debug) {
+      console.log('[ModalHandler][DEBUG]: Overlayless modals registry before clear => ', this.#popups);
+    }
+
+    this.#popups.length = 0;
+
+    if (this.#debug) {
+      console.log('[ModalHandler][DEBUG]: Overlayless modals registry after clear => ', this.#popups);
+    }
+
+    return this;
   }
 
-  resetKeys() {
-    this.#modalIdCounter = 0;
+  reset() {
+    this
+      .clearDocumentBodyEvents()
+      .clearActiveModals()
+      .clearFocusRegistry()
+      .resetKeys()
+      .clearPopups();
   }
 
   rebindTrapFocus(modalKey) {
@@ -282,6 +316,10 @@ export default class ModalHandler {
     // so lingering events can be removed if the modal stays open across re-renders
     documentEvents.push({ eventName: 'keydown', callback: escapeKeyHandler });
     
+    if (!modalLmOuterLimits) {
+      this.#popups.push(modalKey); // Register overlayless modal
+    }
+
     if (modalLmOuterLimits) {
       const outsideClickHandler = this.#handleOutsideClickClose(modalKey, handleActiveModalClose, modalLmOuterLimits, exemptLms);
 
@@ -307,15 +345,13 @@ export default class ModalHandler {
   }
 
   removeA11yEvents({
-    modalKey,
-    isToggle,
+    modalKey
   }) {
-    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 index = this.#popups.indexOf(modalKey); // Check if overlayless modal exists
+    const isOverlayLess = index !== -1 && this.#popups.splice(index, 1).length // Remove key from popups array
+
+    const isRegistered = this.#unregisterModal(modalKey, isOverlayLess);
+    if (!isRegistered) return;
 
     const eventsHandler = this.#eventsHandler[modalKey];