accessible-kit 1.0.8 → 1.0.9

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.9] - 2026-03-02
+
+### Added
+- **Dropdown - Navigation ARIA Pattern**: New `data-dropdown-role="navigation"` value for disclosure dropdowns containing links (language switchers, nav menus)
+  - **Button**: sets only `aria-expanded` + `aria-controls` — no `aria-haspopup` (correct for disclosure pattern per WAI-ARIA APG)
+  - **Menu element**: no `role` override — preserves native `<nav>` landmark semantics
+  - **Items**: no `role` override — preserves native `<a>` link semantics and `hreflang`/`aria-current` attributes
+  - **Keyboard**: Arrow keys navigate, `Home`/`End` jump to first/last, `Tab` closes (same as menu pattern)
+  - **Mouse click**: links navigate naturally and support Ctrl+click / middle-click (open in new tab)
+  - Updated demo language switchers (header nav + standalone) to use the new pattern with `<nav>`, `<ul>/<li>/<a>`, `hreflang`, and `aria-current`
+  - Updated Usage info box in demo to 3-column grid: Menu / Navigation / Dialog patterns
+  - Backwards compatible — all existing `menu`, `dialog`, `listbox` dropdowns unchanged
+
+### Changed
+- **README**: Updated ARIA Patterns section — removed "Language/region selectors" and "Navigation menus" from Menu Pattern (they were semantically incorrect there), added dedicated Navigation Pattern description and code example
+- **README**: Updated Language Switcher variant example to use `data-dropdown-role="navigation"` with `<nav>` and `<a>` elements
+- **README**: Added Navigation Pattern to Keyboard Navigation section
+
 ## [1.0.7] - 2026-01-26
 
 ### Changed
@@ -171,6 +189,8 @@ document.addEventListener('DOMContentLoaded', () => {
 - Zero dependencies
 - Full TypeScript-ready exports
 
+[1.0.9]: https://github.com/5ulo/accessible-kit/compare/v1.0.8...v1.0.9
+[1.0.8]: https://github.com/5ulo/accessible-kit/compare/v1.0.7...v1.0.8
 [1.0.7]: https://github.com/5ulo/accessible-kit/compare/v1.0.6...v1.0.7
 [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

package/README.md

@@ -173,7 +173,7 @@ Fully accessible dropdown component with keyboard navigation and ARIA support. S
 
 ### Features
 
-- ✅ Full ARIA attributes support (menu, dialog, and listbox patterns)
+- ✅ Full ARIA attributes support (menu, navigation, dialog, and listbox patterns)
 - ✅ Flexible role patterns via `data-dropdown-role` attribute
 - ✅ Keyboard navigation (arrows, Enter, Space, Esc, Home, End)
 - ✅ Focus management
@@ -222,11 +222,14 @@ The dropdown component supports multiple ARIA patterns to match different use ca
 #### 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
+- User profile menus (button items)
+- Context menus (button items)
+
+**Navigation Pattern** - Use `data-dropdown-role="navigation"` for:
+- Language/region switchers
+- Navigation dropdowns containing `<a>` links
+- Any disclosure widget where native `<nav>` landmark and link semantics must be preserved
 
 **Dialog Pattern** - Use `data-dropdown-role="dialog"` for:
 - Media player playlists/controls
@@ -266,6 +269,38 @@ The dropdown component supports multiple ARIA patterns to match different use ca
 **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).
 
+**Example: Navigation Pattern (Language Switcher)**
+
+```html
+<!-- Use data-dropdown-role="navigation" for language switchers and nav menus with links -->
+<div data-dropdown data-dropdown-role="navigation">
+  <button data-dropdown-button aria-label="Výber jazyka">
+    🇬🇧 English
+    <span data-dropdown-arrow></span>
+  </button>
+  <nav data-dropdown-menu aria-label="Výber jazyka">
+    <div>
+      <div>
+        <ul style="list-style: none; margin: 0; padding: 0;">
+          <li><a href="/en" hreflang="en" lang="en" data-dropdown-item aria-current="page">English</a></li>
+          <li><a href="/sk" hreflang="sk" lang="sk" data-dropdown-item>Slovensky</a></li>
+        </ul>
+      </div>
+    </div>
+  </nav>
+</div>
+
+<!-- This automatically sets:
+  - Button: aria-expanded + aria-controls only (no aria-haspopup)
+  - Menu: no role override (preserves native <nav> landmark)
+  - Items: no role override (preserves native <a> link semantics)
+  - Keyboard: Arrow keys navigate, Tab closes (same as menu pattern)
+-->
+```
+
+**Why use navigation pattern?**
+Language switchers and nav dropdowns contain `<a>` links, not menu commands. The `role="menu"` + `role="menuitem"` pattern is semantically incorrect for links — it hides the native link semantics from screen readers. The navigation pattern keeps the `<nav>` landmark and `<a>` link roles intact, allowing users to understand they're navigating, not executing commands.
+
 ### JavaScript Initialization
 
 ```javascript
@@ -278,7 +313,7 @@ document.addEventListener('DOMContentLoaded', () => {
 
 // Or manual initialization with options
 const dropdown = new Dropdown(element, {
-  dropdownRole: 'menu',          // 'menu' (default), 'dialog', or 'listbox'
+  dropdownRole: 'menu',          // 'menu' (default), 'dialog', 'listbox', or 'navigation'
   closeOnSelect: true,
   closeOnOutsideClick: true,
   closeOnEscape: true,
@@ -340,7 +375,7 @@ Dropdowns have **CSS Grid animations enabled by default**. The animation automat
 
 ```javascript
 {
-  dropdownRole: 'menu',          // ARIA pattern: 'menu', 'dialog', or 'listbox'
+  dropdownRole: 'menu',          // ARIA pattern: 'menu', 'dialog', 'listbox', or 'navigation'
   closeOnSelect: true,           // Close after selecting item
   closeOnOutsideClick: true,     // Close on outside click
   closeOnEscape: true,           // Close on Escape key
@@ -368,6 +403,14 @@ Dropdowns have **CSS Grid animations enabled by default**. The animation automat
 - **Esc** - Close and return focus to button
 - **Tab** / **Shift+Tab** - Cycle through items within dialog (does not close)
 
+**Navigation Pattern:**
+
+- **↓** / **↑** - Navigate between links
+- **Home** / **End** - Jump to first/last link
+- **Esc** - Close and return focus to button
+- **Tab** - Close and move focus
+- **Enter** - Follow link (native browser behavior)
+
 ### Variants
 
 **Navigation menu:**
@@ -389,25 +432,31 @@ Dropdowns have **CSS Grid animations enabled by default**. The animation automat
 **Language switcher:**
 
 ```html
-<div data-dropdown data-variant="language">
-  <button data-dropdown-button>
+<div data-dropdown data-variant="language" data-dropdown-role="navigation">
+  <button data-dropdown-button aria-label="Výber jazyka">
     🇬🇧 EN
     <span data-dropdown-arrow></span>
   </button>
-  <div data-dropdown-menu>
+  <nav data-dropdown-menu aria-label="Výber jazyka">
     <div>
       <div>
-        <button data-dropdown-item>
-          <span data-dropdown-item-flag>🇬🇧</span>
-          English
-        </button>
-        <button data-dropdown-item>
-          <span data-dropdown-item-flag>🇸🇰</span>
-          Slovenčina
-        </button>
+        <ul style="list-style: none; margin: 0; padding: 0;">
+          <li>
+            <a href="/en" hreflang="en" lang="en" data-dropdown-item aria-current="page">
+              <span data-dropdown-item-flag>🇬🇧</span>
+              English
+            </a>
+          </li>
+          <li>
+            <a href="/sk" hreflang="sk" lang="sk" data-dropdown-item>
+              <span data-dropdown-item-flag>🇸🇰</span>
+              Slovenčina
+            </a>
+          </li>
+        </ul>
       </div>
     </div>
-  </div>
+  </nav>
 </div>
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "accessible-kit",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "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

@@ -92,17 +92,26 @@ class AccessibleDropdown {
                 .substr(2, 9)}`;
         }
 
-        // 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);
+        const isNavigation = this.options.dropdownRole === "navigation";
+
+        // Button ARIA attributes
+        // Navigation (disclosure) pattern: aria-expanded + aria-controls only, no aria-haspopup
+        if (!isNavigation) {
+            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 - set role based on dropdown role
-        this.menu.setAttribute("role", this.options.dropdownRole);
+        // Menu ARIA attributes
+        // Navigation pattern: skip role override to preserve native element role (e.g. <nav> landmark)
+        if (!isNavigation) {
+            this.menu.setAttribute("role", this.options.dropdownRole);
+        }
         this.menu.setAttribute("aria-labelledby", this.button.id);
 
-        // Menu items ARIA attributes - set item role based on dropdown role
+        // Menu items ARIA attributes
+        // Navigation pattern: skip role override to preserve native element semantics (e.g. <a> links)
         const itemRole = this.options.dropdownRole === "menu" ? "menuitem" :
                          this.options.dropdownRole === "listbox" ? "option" : null;
 
@@ -217,7 +226,7 @@ class AccessibleDropdown {
         }
 
         // Pattern-specific navigation
-        if (this.options.dropdownRole === "menu" || this.options.dropdownRole === "listbox") {
+        if (this.options.dropdownRole === "menu" || this.options.dropdownRole === "listbox" || this.options.dropdownRole === "navigation") {
             switch (e.key) {
                 case "ArrowDown":
                     e.preventDefault();
@@ -252,8 +261,11 @@ class AccessibleDropdown {
     }
 
     handleItemClick(e, index) {
-        e.preventDefault();
-        e.stopPropagation();
+        // Navigation pattern: let links handle click naturally (supports Ctrl+click, middle-click, etc.)
+        if (this.options.dropdownRole !== "navigation") {
+            e.preventDefault();
+            e.stopPropagation();
+        }
         this.selectItem(index);
     }