accessible-kit 1.0.5 → 1.0.6

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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
@@ -134,6 +152,7 @@ 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

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.5",
+  "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",