accessible-kit 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.7] - 2026-01-26
+
+### Changed
+- **All Components - Focus Indicator Improvements**: Migrated from `:focus` to `:focus-visible` for better keyboard navigation UX
+  - **Breaking Change for Custom Themes**: If you have custom theme files, update `:focus` selectors to `:focus-visible`
+  - **Complete separation of concerns**: ALL visual styling (including `outline` properties) moved from `*.core.css` to `*.theme.css` files
+  - Core CSS files now contain ZERO visual styling - only structural layout and behavior
+  - Theme CSS files contain all focus styling including `outline`, `outline-offset`, and `outline-color`
+  - **Benefits**:
+    - Focus indicators only appear for keyboard navigation, not on mouse clicks
+    - Perfect separation between core functionality and visual design
+    - Complete customization freedom - modify or remove all focus styling in theme files
+    - No hardcoded visual defaults in core files
+  - **Affected components**: Dropdown, Modal, Offcanvas, Tabs, Accordion
+  - **Migration guide**: 
+    - Update your custom theme `:focus` selectors to `:focus-visible`
+    - All `outline` customization should now be done in `*.theme.css` files only
+  - Updated documentation in README with focus-visible information
+
+## [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 +171,8 @@ document.addEventListener('DOMContentLoaded', () => {
 - Zero dependencies
 - Full TypeScript-ready exports
 
+[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
 [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

@@ -19,6 +19,7 @@ A collection of fully accessible UI components for modern web applications. Buil
 - **♿ Inclusive** - High contrast mode and reduced motion support
 - **🔧 Framework Agnostic** - Works with any framework or vanilla JS
 - **📦 Tree-shakeable** - Import only what you need
+- **⌨️ Focus Visible** - Uses `:focus-visible` for better keyboard navigation UX
 
 ## 📚 Table of Contents
 
@@ -168,11 +169,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 +215,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 +278,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 +323,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 +340,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 +353,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:**
@@ -989,6 +1056,7 @@ Contains only logic, positioning, layout, and behavior:
 - Visibility states
 - Animations
 - Responsive breakpoints
+- **NO visual styling** - completely theme-agnostic
 
 **Do not modify** unless changing component functionality.
 
@@ -1000,6 +1068,7 @@ Contains all visual styling:
 - Typography
 - Borders and border-radius
 - Shadows
+- **All focus indicators** (`:focus-visible` with `outline`, `outline-offset`, etc.)
 - Dark mode
 - High contrast mode
 

package/package.json

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

package/src/css/a11y-accordion.theme.css

@@ -31,7 +31,7 @@
     background: #f9fafb;
 }
 
-[data-accordion-trigger]:focus {
+[data-accordion-trigger]:focus-visible {
     outline: 2px solid #3b82f6;
     outline-offset: -2px;
 }
@@ -78,7 +78,7 @@
     background: #2563eb;
 }
 
-[data-accordion-toggle]:focus {
+[data-accordion-toggle]:focus-visible {
     outline: 2px solid #3b82f6;
     outline-offset: 2px;
 }
@@ -112,7 +112,7 @@
     border-color: #d1d5db;
 }
 
-[data-accordion-toggle-all]:focus {
+[data-accordion-toggle-all]:focus-visible {
     outline: 2px solid #3b82f6;
     outline-offset: 2px;
 }
@@ -214,7 +214,7 @@
         border-width: 2px;
     }
 
-    [data-accordion-trigger]:focus {
+    [data-accordion-trigger]:focus-visible {
         outline-width: 3px;
     }
 }

package/src/css/a11y-dropdown.core.css

@@ -16,10 +16,6 @@
     cursor: pointer;
 }
 
-[data-dropdown-button]:focus {
-    outline-offset: 2px;
-}
-
 /* Button icon/arrow */
 [data-dropdown-arrow] {
     display: inline-block;
@@ -99,10 +95,6 @@
     text-decoration: none;
 }
 
-[data-dropdown-item]:focus {
-    outline: none;
-}
-
 /* Divider */
 [data-dropdown-divider] {
     height: 1px;
@@ -130,9 +122,6 @@
 }
 
 /* Navigation variant */
-[data-dropdown][data-variant="nav"] [data-dropdown-button]:focus {
-    outline-offset: 2px;
-}
 
 /* Language switcher variant */
 [data-dropdown][data-variant="language"] [data-dropdown-item] {
@@ -153,13 +142,6 @@
     }
 }
 
-/* High contrast mode support */
-@media (prefers-contrast: high) {
-    [data-dropdown-item]:focus {
-        outline-offset: -2px;
-    }
-}
-
 /* Reduced motion support - disable animations */
 @media (prefers-reduced-motion: reduce) {
     [data-dropdown-menu]:not([data-no-animation]),

package/src/css/a11y-dropdown.theme.css

@@ -20,7 +20,7 @@
     border-color: #9ca3af;
 }
 
-[data-dropdown-button]:focus {
+[data-dropdown-button]:focus-visible {
     outline: 2px solid #3b82f6;
     border-color: #3b82f6;
 }
@@ -61,9 +61,10 @@
 }
 
 [data-dropdown-item]:hover,
-[data-dropdown-item]:focus {
+[data-dropdown-item]:focus-visible {
     background: #f3f4f6;
     color: #111827;
+    outline: none;
 }
 
 [data-dropdown-item]:active {
@@ -98,7 +99,7 @@
     background: rgba(0, 0, 0, 0.05);
 }
 
-[data-dropdown][data-variant="nav"] [data-dropdown-button]:focus {
+[data-dropdown][data-variant="nav"] [data-dropdown-button]:focus-visible {
     outline: 2px solid currentColor;
 }
 
@@ -122,8 +123,9 @@
         border-width: 2px;
     }
 
-    [data-dropdown-item]:focus {
+    [data-dropdown-item]:focus-visible {
         outline: 2px solid currentColor;
+        outline-offset: -2px;
     }
 }
 
@@ -160,9 +162,10 @@
     }
 
     [data-dropdown-item]:hover,
-    [data-dropdown-item]:focus {
+    [data-dropdown-item]:focus-visible {
         background: #374151;
         color: #fff;
+        outline: none;
     }
 
     [data-dropdown-item]:active {

package/src/css/a11y-modal.core.css

@@ -110,11 +110,6 @@ body.modal-open {
     overflow: hidden;
 }
 
-/* Focus trap */
-[data-modal-dialog]:focus {
-    outline: none;
-}
-
 /* Responsive */
 @media (max-width: 640px) {
     [data-modal-dialog] {

package/src/css/a11y-modal.theme.css

@@ -16,6 +16,10 @@
         0 10px 10px -5px rgba(0, 0, 0, 0.04);
 }
 
+[data-modal-dialog]:focus-visible {
+    outline: none;
+}
+
 /* Modal header */
 [data-modal-header] {
     padding: 1.5rem;
@@ -66,7 +70,7 @@
     color: #111827;
 }
 
-[data-modal-close]:focus {
+[data-modal-close]:focus-visible {
     outline: 2px solid #3b82f6;
     outline-offset: 2px;
 }
@@ -200,7 +204,7 @@
         border: 2px solid currentColor;
     }
 
-    [data-modal-close]:focus {
+    [data-modal-close]:focus-visible {
         outline-width: 3px;
     }
 }

package/src/css/a11y-offcanvas.core.css

@@ -112,11 +112,6 @@ body.offcanvas-open {
     overflow: hidden;
 }
 
-/* Focus trap */
-[data-offcanvas-panel]:focus {
-    outline: none;
-}
-
 /* Reduced motion support */
 @media (prefers-reduced-motion: reduce) {
     [data-offcanvas-panel],

package/src/css/a11y-offcanvas.theme.css

@@ -2,6 +2,11 @@
 /* Obsahuje vizualne nastavenia: farby, velkosti, bordery, radiusy, spacing */
 /* Pre zmenu vzhladu upravte tento subor */
 
+/* Focus visible for the panel itself (focus trap) */
+[data-offcanvas-panel]:focus-visible {
+    outline: none;
+}
+
 /* Focus visible for all focusable elements inside offcanvas */
 [data-offcanvas-panel] :focus-visible {
     outline: 2px solid #3b82f6;

package/src/css/a11y-tabs.core.css

@@ -46,10 +46,6 @@
     pointer-events: none;
 }
 
-[data-tabs-tab]:focus {
-    outline-offset: -2px;
-}
-
 /* Tab panels container */
 [data-tabs-panels] {
     position: relative;
@@ -64,11 +60,6 @@
     display: block;
 }
 
-/* Focus within panel */
-[data-tabs-panel]:focus {
-    outline: none;
-}
-
 /* View Transitions API uses default cross-fade animation */
 /* Customization via pseudo-elements */
 ::view-transition-old(root),

package/src/css/a11y-tabs.theme.css

@@ -35,8 +35,9 @@
     background: #f9fafb;
 }
 
-[data-tabs-tab]:focus {
+[data-tabs-tab]:focus-visible {
     outline: 2px solid #3b82f6;
+    outline-offset: -2px;
     color: #374151;
 }
 
@@ -80,6 +81,10 @@
     line-height: 1.6;
 }
 
+[data-tabs-panel]:focus-visible {
+    outline: none;
+}
+
 /* Boxed variant */
 [data-tabs][data-tabs][data-variant="boxed"] [data-tabs-list] {
     border-bottom: 1px solid #e5e7eb;
@@ -136,7 +141,7 @@
     color: #fff;
 }
 
-[data-tabs][data-tabs][data-variant="pills"] [data-tabs-tab]:focus {
+[data-tabs][data-tabs][data-variant="pills"] [data-tabs-tab]:focus-visible {
     outline-color: #3b82f6;
 }
 
@@ -222,7 +227,7 @@
         border-width: 2px;
     }
 
-    [data-tabs-tab]:focus {
+    [data-tabs-tab]:focus-visible {
         outline-width: 3px;
     }
 }
@@ -246,7 +251,7 @@
         background: #1f2937;
     }
 
-    [data-tabs-tab]:focus {
+    [data-tabs-tab]:focus-visible {
         color: #f9fafb;
     }
 

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",