accessible-kit 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -5,15 +5,58 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.6] - 2026-01-15
+
+### Added
+- **Dropdown - Multiple ARIA Pattern Support**: Added `data-dropdown-role` attribute to support dialog and listbox patterns in addition to the default menu pattern
+  - **New attribute**: `data-dropdown-role` accepts `"menu"` (default), `"dialog"`, or `"listbox"`
+  - Automatically sets appropriate `aria-haspopup` value based on role type:
+    - `role="menu"` → `aria-haspopup="true"`
+    - `role="dialog"` → `aria-haspopup="dialog"`
+    - `role="listbox"` → `aria-haspopup="listbox"`
+  - Conditionally applies correct item roles (`menuitem`, none for dialog, `option` for listbox)
+  - Pattern-specific keyboard navigation:
+    - Menu/listbox: Arrow keys, Home/End, Tab closes dropdown
+    - Dialog: Arrow keys, Tab navigates within (doesn't close)
+  - **Use case example**: Radio playlists, media controls, or complex interactive widgets that aren't semantic "menus"
+  - Added comprehensive documentation and live example (radio playlist) to demo page
+  - Updated README with ARIA pattern guidance and when to use each pattern
+  - **Backwards compatible**: Defaults to `"menu"` pattern, existing implementations unchanged
+
+## [1.0.5] - 2025-12-21
+
+### Fixed
+- **Focus Trap - Manual Tab Navigation**: Complete rewrite of Tab key handling in Offcanvas and Modal components
+  - **BREAKING CHANGE in behavior**: Focus trap now completely overrides native browser Tab behavior
+  - Always prevents default Tab action and manually controls focus movement
+  - Eliminates `aria-hidden` violations caused by browser trying to focus hidden elements
+  - `updateFocusableElements()` is called on every Tab keypress to catch dynamic DOM changes
+  - Focus only moves through elements in the filtered `focusableElements` list
+  - Properly handles nested collapse components - focus skips closed submenus and includes opened ones
+
+### Details
+**Problem solved:**
+When using Tab key in offcanvas/modal with dynamic content (e.g., collapse menus), the browser's native Tab behavior would attempt to focus elements with `aria-hidden="true"`, causing console warnings and accessibility violations.
+
+**Solution:**
+The focus trap now takes complete control of Tab navigation:
+1. Every Tab keypress prevents default browser behavior
+2. Updates the list of focusable elements to reflect current DOM state
+3. Manually calculates and focuses the next/previous element from the filtered list
+4. Elements inside `aria-hidden="true"` containers are never focused
+
+This ensures perfect compatibility with dynamic components like animated collapse panels in navigation menus.
+
 ## [1.0.4] - 2025-12-21
 
 ### Fixed
-- **Focus Trap**: Fixed focus trap in Offcanvas and Modal components
+- **Focus Trap - Initial Implementation**: Improved focus trap in Offcanvas and Modal components
   - Focus trap now correctly excludes elements with `aria-hidden="true"` and their children
   - Fixed timing issue where `updateFocusableElements()` was called before CSS visibility changes applied
-  - Focus trap now properly skips hidden elements in collapsed/nested components (e.g., collapse submenus in navigation)
+  - Focus trap now properly skips hidden elements in collapsed/nested components
   - Added comprehensive filtering for hidden, invisible, and aria-hidden elements
   - Removed `visibility: hidden` check from filter to prevent false positives during panel opening
+  - Works correctly with both animated (CSS Grid) and non-animated collapse panels
 
 ### Added
 - Added `:focus-visible` styles to Offcanvas theme for better keyboard navigation visibility
@@ -109,6 +152,8 @@ document.addEventListener('DOMContentLoaded', () => {
 - Zero dependencies
 - Full TypeScript-ready exports
 
+[1.0.6]: https://github.com/5ulo/accessible-kit/compare/v1.0.5...v1.0.6
+[1.0.5]: https://github.com/5ulo/accessible-kit/compare/v1.0.4...v1.0.5
 [1.0.4]: https://github.com/5ulo/accessible-kit/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/5ulo/accessible-kit/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/5ulo/accessible-kit/compare/v1.0.1...v1.0.2

package/README.md

@@ -168,11 +168,12 @@ const dropdown = new AccessibleDropdown(element, {
 
 ## Dropdown
 
-Fully accessible dropdown component with keyboard navigation and ARIA support.
+Fully accessible dropdown component with keyboard navigation and ARIA support. Supports multiple ARIA patterns (menu, dialog, listbox) for different use cases.
 
 ### Features
 
-- ✅ Full ARIA attributes support
+- ✅ Full ARIA attributes support (menu, dialog, and listbox patterns)
+- ✅ Flexible role patterns via `data-dropdown-role` attribute
 - ✅ Keyboard navigation (arrows, Enter, Space, Esc, Home, End)
 - ✅ Focus management
 - ✅ Auto-close on outside click
@@ -213,6 +214,57 @@ Fully accessible dropdown component with keyboard navigation and ARIA support.
 </div>
 ```
 
+### ARIA Patterns
+
+The dropdown component supports multiple ARIA patterns to match different use cases. By default, it uses the **menu pattern**, but you can change this using the `data-dropdown-role` attribute.
+
+#### When to Use Each Pattern
+
+**Menu Pattern (default)** - Use `role="menu"` for:
+- Navigation menus
+- Action menus (Edit, Delete, etc.)
+- Language/region selectors
+- User profile menus
+- Context menus
+
+**Dialog Pattern** - Use `data-dropdown-role="dialog"` for:
+- Media player playlists/controls
+- Complex interactive widgets
+- Custom form controls
+- Rich content with multiple focusable elements
+- Non-menu disclosure patterns
+
+**Example: Dialog Pattern (Radio Playlist)**
+
+```html
+<!-- Use data-dropdown-role="dialog" for playlists, controls, or interactive widgets -->
+<div data-dropdown data-dropdown-role="dialog">
+  <button data-dropdown-button>
+    🎵 Playlist
+    <span data-dropdown-arrow></span>
+  </button>
+  <div data-dropdown-menu>
+    <div>
+      <div>
+        <button data-dropdown-item>Station 1</button>
+        <button data-dropdown-item>Station 2</button>
+        <button data-dropdown-item>Station 3</button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- This automatically sets:
+  - Button: aria-haspopup="dialog" (instead of "true")
+  - Menu: role="dialog" (instead of "menu")
+  - Items: No role attribute (instead of "menuitem")
+  - Keyboard: Tab allowed within dropdown (menu pattern closes on Tab)
+-->
+```
+
+**Why use dialog pattern?**
+When your dropdown contains complex interactive content (like a media player playlist), it's not semantically a "menu" of commands. The dialog pattern better represents this content structure and provides more appropriate keyboard behavior. Tab/Shift+Tab cycles through items within the dropdown (instead of closing it like menu pattern does).
+
 ### JavaScript Initialization
 
 ```javascript
@@ -225,6 +277,7 @@ document.addEventListener('DOMContentLoaded', () => {
 
 // Or manual initialization with options
 const dropdown = new Dropdown(element, {
+  dropdownRole: 'menu',          // 'menu' (default), 'dialog', or 'listbox'
   closeOnSelect: true,
   closeOnOutsideClick: true,
   closeOnEscape: true,
@@ -269,6 +322,9 @@ Dropdowns have **CSS Grid animations enabled by default**. The animation automat
 **Data attributes:**
 
 ```html
+<!-- Use dialog pattern for non-menu content -->
+<div data-dropdown data-dropdown-role="dialog">
+
 <!-- Keep dropdown open after selection -->
 <div data-dropdown data-close-on-select="false">
 
@@ -283,6 +339,7 @@ Dropdowns have **CSS Grid animations enabled by default**. The animation automat
 
 ```javascript
 {
+  dropdownRole: 'menu',          // ARIA pattern: 'menu', 'dialog', or 'listbox'
   closeOnSelect: true,           // Close after selecting item
   closeOnOutsideClick: true,     // Close on outside click
   closeOnEscape: true,           // Close on Escape key
@@ -295,12 +352,21 @@ Dropdowns have **CSS Grid animations enabled by default**. The animation automat
 
 ### Keyboard Navigation
 
+**Menu Pattern (default):**
+
 - **Enter** / **Space** - Open/close menu or select item
 - **↓** / **↑** - Navigate between items
 - **Home** / **End** - Jump to first/last item
 - **Esc** - Close menu and return focus to button
 - **Tab** - Close menu and move focus
 
+**Dialog Pattern:**
+
+- **Enter** / **Space** - Open/close or select item
+- **↓** / **↑** - Navigate between items
+- **Esc** - Close and return focus to button
+- **Tab** / **Shift+Tab** - Cycle through items within dialog (does not close)
+
 ### Variants
 
 **Navigation menu:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "accessible-kit",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Lightweight, accessible UI component library with full ARIA support. Zero dependencies, vanilla JavaScript.",
   "main": "src/js/index.js",
   "type": "module",

package/src/js/a11y-dropdown.js

@@ -18,6 +18,7 @@ class AccessibleDropdown {
 
         // Options
         this.options = {
+            dropdownRole: options.dropdownRole || "menu",
             closeOnSelect: options.closeOnSelect !== false,
             closeOnOutsideClick: options.closeOnOutsideClick !== false,
             closeOnEscape: options.closeOnEscape !== false,
@@ -91,18 +92,24 @@ class AccessibleDropdown {
                 .substr(2, 9)}`;
         }
 
-        // Button ARIA attributes
-        this.button.setAttribute("aria-haspopup", "true");
+        // Button ARIA attributes - set aria-haspopup based on dropdown role
+        const ariaHaspopupValue = this.options.dropdownRole === "menu" ? "true" : this.options.dropdownRole;
+        this.button.setAttribute("aria-haspopup", ariaHaspopupValue);
         this.button.setAttribute("aria-expanded", "false");
         this.button.setAttribute("aria-controls", this.menu.id);
 
-        // Menu ARIA attributes
-        this.menu.setAttribute("role", "menu");
+        // Menu ARIA attributes - set role based on dropdown role
+        this.menu.setAttribute("role", this.options.dropdownRole);
         this.menu.setAttribute("aria-labelledby", this.button.id);
 
-        // Menu items ARIA attributes
+        // Menu items ARIA attributes - set item role based on dropdown role
+        const itemRole = this.options.dropdownRole === "menu" ? "menuitem" :
+                         this.options.dropdownRole === "listbox" ? "option" : null;
+
         this.items.forEach((item) => {
-            item.setAttribute("role", "menuitem");
+            if (itemRole) {
+                item.setAttribute("role", itemRole);
+            }
             if (!item.hasAttribute("tabindex")) {
                 item.setAttribute("tabindex", "-1");
             }
@@ -184,32 +191,64 @@ class AccessibleDropdown {
     }
 
     handleItemKeydown(e, index) {
+        // Common navigation for all patterns
         switch (e.key) {
             case "Enter":
             case " ":
                 e.preventDefault();
                 this.selectItem(index);
                 break;
-            case "ArrowDown":
-                e.preventDefault();
-                this.focusNextItem();
-                break;
-            case "ArrowUp":
-                e.preventDefault();
-                this.focusPreviousItem();
-                break;
-            case "Home":
-                e.preventDefault();
-                this.setFocusedItem(0);
-                break;
-            case "End":
-                e.preventDefault();
-                this.setFocusedItem(this.items.length - 1);
-                break;
             case "Tab":
-                this.close();
+                // For dialog pattern, Tab should cycle within items
+                // For menu and listbox, close on Tab
+                if (this.options.dropdownRole === "dialog") {
+                    e.preventDefault();
+                    // Tab forward or backward through items
+                    if (e.shiftKey) {
+                        this.focusPreviousItem();
+                    } else {
+                        this.focusNextItem();
+                    }
+                } else {
+                    // Menu and listbox patterns close on Tab
+                    this.close();
+                }
                 break;
         }
+
+        // Pattern-specific navigation
+        if (this.options.dropdownRole === "menu" || this.options.dropdownRole === "listbox") {
+            switch (e.key) {
+                case "ArrowDown":
+                    e.preventDefault();
+                    this.focusNextItem();
+                    break;
+                case "ArrowUp":
+                    e.preventDefault();
+                    this.focusPreviousItem();
+                    break;
+                case "Home":
+                    e.preventDefault();
+                    this.setFocusedItem(0);
+                    break;
+                case "End":
+                    e.preventDefault();
+                    this.setFocusedItem(this.items.length - 1);
+                    break;
+            }
+        } else if (this.options.dropdownRole === "dialog") {
+            // Dialog pattern: Arrow keys for navigation (less strict)
+            switch (e.key) {
+                case "ArrowDown":
+                    e.preventDefault();
+                    this.focusNextItem();
+                    break;
+                case "ArrowUp":
+                    e.preventDefault();
+                    this.focusPreviousItem();
+                    break;
+            }
+        }
     }
 
     handleItemClick(e, index) {
@@ -320,6 +359,7 @@ function initDropdowns() {
 
     dropdowns.forEach((dropdown) => {
         const options = {
+            dropdownRole: dropdown.dataset.dropdownRole || "menu",
             closeOnSelect: dropdown.dataset.closeOnSelect !== "false",
             closeOnOutsideClick:
                 dropdown.dataset.closeOnOutsideClick !== "false",

package/src/js/a11y-modal.js

@@ -194,6 +194,10 @@ class AccessibleModal {
                 el.getClientRects().length > 0
             );
 
+            if (!isVisible) {
+                return false;
+            }
+
             // Check if element or any parent has aria-hidden="true"
             let currentElement = el;
             while (currentElement && currentElement !== this.dialog) {
@@ -214,7 +218,7 @@ class AccessibleModal {
                 return false;
             }
 
-            return isVisible;
+            return true;
         });
 
         this.firstFocusable = this.focusableElements[0] || null;
@@ -225,24 +229,39 @@ class AccessibleModal {
     handleFocusTrap(e) {
         if (!this.isOpen || e.key !== "Tab") return;
 
+        // Update focusable elements before each Tab to catch dynamic changes (e.g., collapse panels)
+        this.updateFocusableElements();
+
         // If no focusable elements, prevent default
         if (this.focusableElements.length === 0) {
             e.preventDefault();
             return;
         }
 
+        // Always prevent default Tab behavior - we'll handle focus manually
+        e.preventDefault();
+
+        // Find current element index in focusable list
+        const currentIndex = this.focusableElements.indexOf(document.activeElement);
+
         // Shift + Tab (backward)
         if (e.shiftKey) {
-            if (document.activeElement === this.firstFocusable) {
-                e.preventDefault();
+            if (currentIndex <= 0) {
+                // At first element or not in list - go to last
                 this.lastFocusable.focus();
+            } else {
+                // Go to previous element
+                this.focusableElements[currentIndex - 1].focus();
             }
         }
         // Tab (forward)
         else {
-            if (document.activeElement === this.lastFocusable) {
-                e.preventDefault();
+            if (currentIndex === -1 || currentIndex >= this.focusableElements.length - 1) {
+                // Not in list or at last element - go to first
                 this.firstFocusable.focus();
+            } else {
+                // Go to next element
+                this.focusableElements[currentIndex + 1].focus();
             }
         }
     }

package/src/js/a11y-offcanvas.js

@@ -237,24 +237,39 @@ class AccessibleOffcanvas {
     handleFocusTrap(e) {
         if (!this.isOpen || e.key !== "Tab") return;
 
+        // Update focusable elements before each Tab to catch dynamic changes (e.g., collapse panels)
+        this.updateFocusableElements();
+
         // If no focusable elements, prevent default
         if (this.focusableElements.length === 0) {
             e.preventDefault();
             return;
         }
 
+        // Always prevent default Tab behavior - we'll handle focus manually
+        e.preventDefault();
+
+        // Find current element index in focusable list
+        const currentIndex = this.focusableElements.indexOf(document.activeElement);
+
         // Shift + Tab (backward)
         if (e.shiftKey) {
-            if (document.activeElement === this.firstFocusable) {
-                e.preventDefault();
+            if (currentIndex <= 0) {
+                // At first element or not in list - go to last
                 this.lastFocusable.focus();
+            } else {
+                // Go to previous element
+                this.focusableElements[currentIndex - 1].focus();
             }
         }
         // Tab (forward)
         else {
-            if (document.activeElement === this.lastFocusable) {
-                e.preventDefault();
+            if (currentIndex === -1 || currentIndex >= this.focusableElements.length - 1) {
+                // Not in list or at last element - go to first
                 this.firstFocusable.focus();
+            } else {
+                // Go to next element
+                this.focusableElements[currentIndex + 1].focus();
             }
         }
     }

package/src/js/index.js

@@ -2,7 +2,7 @@
  * a11y-kit
  * Lightweight, accessible UI component library with full ARIA support
  *
- * @version 1.0.4
+ * @version 1.0.5
  * @license MIT
  */