aria-ease 1.4.3 → 1.4.5

package/README.md

@@ -10,9 +10,11 @@ Out of the box accessibility utility package to develop production ready applica
 
 ## Features
 
+Don't spend hours wrestling with accessibility code. Aria-Ease provides pre-built, customizable functions that help you integrate accessibility seamlessly into your development workflow. It simplifies the process of adding essential accessibility features to common UI components like menus, accordions, and checkboxes, e.t.c. This allows you to focus on building great user experiences for everyone.
+
 The package currently has support for 5 components: accordions, blocks, checkboxes, menus, radio buttons
 
-Add accessibility to menu: menu can be a dropdown, side menu, slide navigation e.t.c. Basically any component that toggles display and has a list of interactive children items. The function creates a focus trap within the menu and focus can be navigated using the arrow keys. The escape key also closes the menu and returns the focus back to the trigger.
+Add accessibility to menu: menu can be a dropdown, slide navigation menu, e.t.c. Basically any component that toggles display and has a list of interactive children items. The function creates a focus trap within the menu and focus can be navigated using the arrow keys. The escape key also closes the menu and returns the focus back to the trigger.
 
 The makeMenuAccessible function takes two string arguments; the id of the menu, the class name of the children items of the menu. And should only be invoked after the menu has become visible or added to the DOM. When the menu is visible the first item of the menu is in focus and focus can be navigated using the Arrow keys. The Space and Enter keys clicks the menu item if they are buttons or links element. The Escape key closes the menu, and returns the focus back to the button that toggles the menu. The Tab key exits the trap.
 
@@ -20,22 +22,29 @@ The updateMenuTriggerAriaAttributes function take two string arguments; the id o
 
 #### Usage
 
-```
-import { makeMenuAccessible, updateMenuTriggerAriaAttributes, cleanUpMenuEventListeners } from 'aria-ease'
+```javascript
+import {
+  makeMenuAccessible,
+  updateMenuTriggerAriaAttributes,
+  cleanUpMenuEventListeners,
+} from "aria-ease";
 
 const MenuExample = () => {
   const toggleMenuDisplay = (event) => {
-    if (event.type === 'mousedown' || (event.type === 'keydown' && (event.key === 'Enter' || event.key === ' '))) {
+    if (
+      event.type === "mousedown" ||
+      (event.type === "keydown" && (event.key === "Enter" || event.key === " "))
+    ) {
       event.preventDefault();
-      const menu = document.querySelector('#menu-div');
-      if (getComputedStyle(menu).display === 'none') {
-        menu.style.display = 'block';
-        makeMenuAccessible('menu-div', 'menu-interactive-items');
-        updateMenuTriggerAriaAttributes('display-button', 'Close profile menu');
+      const menu = document.querySelector("#menu-div");
+      if (getComputedStyle(menu).display === "none") {
+        menu.style.display = "block";
+        makeMenuAccessible("menu-div", "menu-interactive-items");
+        updateMenuTriggerAriaAttributes("display-button", "Close profile menu");
       } else {
-        cleanUpMenuEventListeners('menu-div', 'menu-interactive-items');
-        menu.style.display = 'none';
-        updateMenuTriggerAriaAttributes('display-button', 'Open profile menu');
+        cleanUpMenuEventListeners("menu-div", "menu-interactive-items");
+        menu.style.display = "none";
+        updateMenuTriggerAriaAttributes("display-button", "Open profile menu");
       }
     }
   };
@@ -50,38 +59,64 @@ const MenuExample = () => {
         aria-expanded={false}
         aria-controls="menu-div"
         aria-label="Display profile menu"
-        className='menu-example-trigger-button'
+        className="menu-example-trigger-button"
         onKeyDown={toggleMenuDisplay}
       >
         Display Example Menu
       </button>
-      <div id="menu-div" role="menu" aria-labelledby="display-button" style={{display: 'none', marginTop: '5px'}}>
-        <button role="menuitem" className="menu-interactive-items" onClick={() => alert('Button clicked')}>One</button>
-        <button role="menuitem" className="menu-interactive-items" onClick={() => alert('Button clicked')}>Two</button>
-        <button role="menuitem" className="menu-interactive-items" onClick={() => alert('Button clicked')}>Three</button>
+      <div
+        id="menu-div"
+        role="menu"
+        aria-labelledby="display-button"
+        style={{ display: "none", marginTop: "5px" }}
+      >
+        <button
+          role="menuitem"
+          className="menu-interactive-items"
+          onClick={() => alert("Button clicked")}
+        >
+          One
+        </button>
+        <button
+          role="menuitem"
+          className="menu-interactive-items"
+          onClick={() => alert("Button clicked")}
+        >
+          Two
+        </button>
+        <button
+          role="menuitem"
+          className="menu-interactive-items"
+          onClick={() => alert("Button clicked")}
+        >
+          Three
+        </button>
       </div>
     </div>
-  )
-}
+  );
+};
 
-export default MenuExample
+export default MenuExample;
 ```
 
-Add accessibility to block: block can be entire web page body, tabs, interactive sliders and carousels e.t.c. Basically any component that is permanently displayed and has a list of related interractive children items. The function creates a focus trap within the block and the focus can be navigated using the arrow keys.
+Add accessibility to block: block can be tabs, entire web page body, interactive sliders and carousels e.t.c. Basically any 'block' component that is permanently displayed and has a list of related interractive children items. The function creates a focus trap within the block and the focus can be navigated using the arrow keys. Using the entire page as a block, the page serves as a focus trap, and the page can be navigated from one interactive item to another from the top of the page to the bottom and cycle back.
 
 The makeBlockAccessible function takes two string arguments; the id of the block main div, and the class name of the children items of the div. The function should be called on page render, so the event listeners get activated. On click of a button, the clicked button gets focused and the focus can be navigated using the arrow keys.
 
 #### Usage
 
-```
-import { useEffect } from 'react'
-import { makeBlockAccessible } from "aria-ease"
+```javascript
+import { useEffect } from "react";
+import { makeBlockAccessible } from "aria-ease";
 
 const BlockExample = () => {
   useEffect(() => {
-    const accessibleBlock = makeBlockAccessible('block-div', 'block-div-interactive-items');
+    const accessibleBlock = makeBlockAccessible(
+      "block-div",
+      "block-div-interactive-items"
+    );
     return accessibleBlock;
-  },[])
+  }, []);
 
   return (
     <div>
@@ -91,10 +126,10 @@ const BlockExample = () => {
         <button className="block-div-interactive-items">Three</button>
       </div>
     </div>
-  )
-}
+  );
+};
 
-export default BlockExample
+export default BlockExample;
 ```
 
 [Check out more features/functionality in the docs](https://aria-ease.vercel.app/docs)
@@ -105,6 +140,17 @@ Find a bug? Head on over to [issue page](https://github.com/aria-ease/aria-ease/
 
 Aria-ease is open-source software by [Isaac Victor](https://isaacvictordev.web.app/)
 
-### P.S.
+### P.S. Don't Forget About Focus Styling!
 
-Make sure to add elements focus styling in css otherwise visibility might be impacted.
+While Aria-Ease significantly aids in making your web applications more accessible, it's essential to remember that visual cues play a crucial role in accessibility. This is especially true for keyboard navigation, where focus styling indicates which element is currently selectable or active.
+
+Without clear focus styling, users who rely on keyboard navigation may find it challenging to determine which part of the page they are interacting with. Therefore, we strongly encourage you to implement distinct focus styles for interactive elements on your web pages.
+
+Here's a simple CSS example to enhance focus visibility:
+
+```css
+:focus {
+  outline: 2px solid rgba(0, 91, 211, 1); /* Blue outline for high contrast */
+  outline-offset: 1px;
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aria-ease",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "Out-of-the-box accessibility utility package to develop production ready applications.",
   "main": "index.js",
   "scripts": {
@@ -11,14 +11,20 @@
     "url": "git+https://github.com/aria-ease/aria-ease.git"
   },
   "keywords": [
+    "a11y",
     "ARIA",
-    "Accessibility"
+    "Accessibility",
+    "Assistive Technology",
+    "Keyboard Navigation",
+    "Focus Management",
+    "WCAG Guidelines",
+    "Inclusive Design"
   ],
   "author": "Isaac Akinduyile",
   "license": "ISC",
   "bugs": {
     "url": "https://github.com/aria-ease/aria-ease/issues"
   },
-  "homepage": "https://aria-ease.vercel.app/",
+  "homepage": "https://aria-ease.vercel.app/docs",
   "types": "./aria-ease.d.ts"
 }

package/src/block/makeBlockAccessible.js

@@ -7,7 +7,13 @@ import { handleKeyPress } from '../handleKeyPress';
 var eventListenersAdded = new Set();
 export function makeBlockAccessible(blockId, blockItemsClass) {
     var blockDiv = document.querySelector("#".concat(blockId));
+    if (!blockDiv) {
+        throw new Error('Invalid block main div id provided.');
+    }
     var blockItems = blockDiv.querySelectorAll(".".concat(blockItemsClass));
+    if (!blockItems) {
+        throw new Error('Invalid block items class provided.');
+    }
     blockItems.forEach(function (blockItem, blockItemIndex) {
         if (!eventListenersAdded.has(blockItem)) {
             eventListenersAdded.add(blockItem);

package/src/block/makeBlockAccessible.ts

@@ -11,7 +11,14 @@ let eventListenersAdded: Set<HTMLElement> = new Set();
 
 export function makeBlockAccessible(blockId: string, blockItemsClass: string) {
   const blockDiv: HTMLElement = document.querySelector(`#${blockId}`) as HTMLElement
-  const blockItems: NodeListOfHTMLElement = blockDiv.querySelectorAll(`.${blockItemsClass}`)
+  if(!blockDiv) {
+    throw new Error('Invalid block main div id provided.');
+  }
+
+  const blockItems: NodeListOfHTMLElement = blockDiv.querySelectorAll(`.${blockItemsClass}`);
+  if(!blockItems) {
+    throw new Error('Invalid block items class provided.');
+  }
 
   blockItems.forEach((blockItem: HTMLElement, blockItemIndex: number): void => {
     if (!eventListenersAdded.has(blockItem)) {

package/src/handleKeyPress.js

@@ -2,6 +2,9 @@ import { updateMenuTriggerAriaAttributes } from "./menu/updateMenuTriggerAriaAtt
 function handleMenuEscapeKeyPress(menuElement, menuTriggerButton, menuClosedStateAriaLabel) {
     menuElement.style.display = 'none';
     var menuTriggerButtonId = menuTriggerButton.getAttribute('id');
+    if (!menuTriggerButtonId) {
+        throw new Error("Menu trigger button does not have id attribute");
+    }
     updateMenuTriggerAriaAttributes("".concat(menuTriggerButtonId), "".concat(menuClosedStateAriaLabel));
 }
 export function handleKeyPress(event, elementItems, elementItemIndex, menuElementDiv, triggerButton, menuClosedStateAriaLabel) {

package/src/handleKeyPress.ts

@@ -4,6 +4,10 @@ import { updateMenuTriggerAriaAttributes } from "./menu/updateMenuTriggerAriaAtt
 function handleMenuEscapeKeyPress(menuElement: HTMLElement, menuTriggerButton: HTMLElement, menuClosedStateAriaLabel: string) {
     menuElement.style.display = 'none';
     const menuTriggerButtonId = menuTriggerButton.getAttribute('id');
+    if(!menuTriggerButtonId) {
+        throw new Error("Menu trigger button does not have id attribute")
+    }
+    
     updateMenuTriggerAriaAttributes(`${menuTriggerButtonId}`, `${menuClosedStateAriaLabel}`)
 }
 

package/src/menu/cleanUpMenuEventListeners.js

@@ -1,9 +1,21 @@
 import { handleKeyPress } from "../handleKeyPress";
 export function cleanUpMenuEventListeners(menuId, menuItemsClass) {
     var menuDiv = document.querySelector("#".concat(menuId));
+    if (!menuDiv) {
+        throw new Error("Invalid menu div id provided");
+    }
     var menuItems = menuDiv.querySelectorAll(".".concat(menuItemsClass));
+    if (!menuItems) {
+        throw new Error("Invalid menu items class provided");
+    }
     var triggerId = menuDiv.getAttribute('aria-labelledby');
+    if (!triggerId) {
+        throw new Error("Menu div doesn't contain aria-labelledby attribute");
+    }
     var triggerButton = document.querySelector("#".concat(triggerId));
+    if (!triggerButton) {
+        throw new Error("Menu trigger button id does not match menu div aria-labelledby attribute");
+    }
     menuItems.forEach(function (menuItem, menuItemIndex) {
         menuItem.removeEventListener('keydown', function (event) { return handleKeyPress(event, menuItems, menuItemIndex, menuDiv, triggerButton); });
     });

package/src/menu/cleanUpMenuEventListeners.ts

@@ -4,10 +4,24 @@ import { handleKeyPress } from "../handleKeyPress"
 
 export function cleanUpMenuEventListeners(menuId: string, menuItemsClass: string): void {
     const menuDiv: HTMLElement = document.querySelector(`#${menuId}`) as HTMLElement
+    if(!menuDiv) {
+        throw new Error("Invalid menu div id provided")
+    }
+
     const menuItems: NodeListOfHTMLElement = menuDiv.querySelectorAll(`.${menuItemsClass}`)
+    if(!menuItems) {
+        throw new Error("Invalid menu items class provided")
+    }
 
     const triggerId: string = menuDiv.getAttribute('aria-labelledby') as string
+    if(!triggerId) {
+        throw new Error("Menu div doesn't contain aria-labelledby attribute")
+    }
+
     const triggerButton: HTMLElement = document.querySelector(`#${triggerId}`) as HTMLElement
+    if(!triggerButton) {
+        throw new Error("Menu trigger button id does not match menu div aria-labelledby attribute")
+    }
 
     menuItems.forEach((menuItem: HTMLElement, menuItemIndex: number): void => {
         menuItem.removeEventListener('keydown', (event: KeyboardEvent): void => handleKeyPress(event, menuItems, menuItemIndex, menuDiv, triggerButton));

package/src/menu/makeMenuAccessible.js

@@ -7,15 +7,32 @@ import { handleKeyPress } from '../handleKeyPress';
 var eventListenersAdded = new Set();
 export function makeMenuAccessible(menuId, menuItemsClass) {
     var menuDiv = document.querySelector("#".concat(menuId));
+    if (!menuDiv) {
+        throw new Error("Invalid menu div id provided");
+    }
     var menuItems = menuDiv.querySelectorAll(".".concat(menuItemsClass));
     var triggerId = menuDiv.getAttribute('aria-labelledby');
+    if (!triggerId) {
+        throw new Error("Menu div doesn't contain aria-labelledby attribute");
+    }
     var triggerButton = document.querySelector("#".concat(triggerId));
+    if (!triggerButton) {
+        throw new Error("Menu trigger button id does not match menu div aria-labelledby attribute");
+    }
     var menuClosedStateAriaLabel = triggerButton.getAttribute('aria-label');
-    menuItems.item(0).focus();
-    menuItems.forEach(function (menuItem, menuItemIndex) {
-        if (!eventListenersAdded.has(menuItem)) {
-            eventListenersAdded.add(menuItem);
-            menuItem.addEventListener('keydown', function (event) { return handleKeyPress(event, menuItems, menuItemIndex, menuDiv, triggerButton, menuClosedStateAriaLabel); });
-        }
-    });
+    if (!menuClosedStateAriaLabel) {
+        throw new Error("Menu trigger button does not have initial aria-label");
+    }
+    if (menuItems && menuItems.length > 0) {
+        menuItems.item(0).focus();
+        menuItems.forEach(function (menuItem, menuItemIndex) {
+            if (!eventListenersAdded.has(menuItem)) {
+                eventListenersAdded.add(menuItem);
+                menuItem.addEventListener('keydown', function (event) { return handleKeyPress(event, menuItems, menuItemIndex, menuDiv, triggerButton, menuClosedStateAriaLabel); });
+            }
+        });
+    }
+    else {
+        throw new Error("Invalid menu items class provided");
+    }
 }

package/src/menu/makeMenuAccessible.ts

@@ -11,18 +11,36 @@ let eventListenersAdded: Set<HTMLElement> = new Set();
 
 export function makeMenuAccessible(menuId: string, menuItemsClass: string): void {
     const menuDiv: HTMLElement = document.querySelector(`#${menuId}`) as HTMLElement;
-    const menuItems: NodeListOfHTMLElement = menuDiv.querySelectorAll(`.${menuItemsClass}`);
+    if(!menuDiv) {
+        throw new Error("Invalid menu div id provided")
+    }
 
+    const menuItems: NodeListOfHTMLElement = menuDiv.querySelectorAll(`.${menuItemsClass}`);
+    
     const triggerId: string = menuDiv.getAttribute('aria-labelledby') as string;
+    if(!triggerId) {
+        throw new Error("Menu div doesn't contain aria-labelledby attribute")
+    }
+
     const triggerButton: HTMLElement = document.querySelector(`#${triggerId}`) as HTMLElement;
+    if(!triggerButton) {
+        throw new Error("Menu trigger button id does not match menu div aria-labelledby attribute")
+    }
 
     const menuClosedStateAriaLabel: string = triggerButton.getAttribute('aria-label')  as string;
+    if(!menuClosedStateAriaLabel) {
+        throw new Error("Menu trigger button does not have initial aria-label")
+    }
 
-    menuItems.item(0).focus();
-    menuItems.forEach((menuItem: HTMLElement, menuItemIndex: number): void => {
-        if (!eventListenersAdded.has(menuItem)) {
-            eventListenersAdded.add(menuItem);
-            menuItem.addEventListener('keydown', (event: KeyboardEvent): void => handleKeyPress(event, menuItems, menuItemIndex, menuDiv, triggerButton, menuClosedStateAriaLabel));
-        }
-    })
+    if(menuItems && menuItems.length > 0) {
+        menuItems.item(0).focus();
+        menuItems.forEach((menuItem: HTMLElement, menuItemIndex: number): void => {
+            if (!eventListenersAdded.has(menuItem)) {
+                eventListenersAdded.add(menuItem);
+                menuItem.addEventListener('keydown', (event: KeyboardEvent): void => handleKeyPress(event, menuItems, menuItemIndex, menuDiv, triggerButton, menuClosedStateAriaLabel));
+            }
+        })
+    } else {
+        throw new Error("Invalid menu items class provided")
+    }
 }

package/src/menu/updateMenuTriggerAriaAttributes.js

@@ -5,7 +5,13 @@
  */
 export function updateMenuTriggerAriaAttributes(triggerId, ariaLabel) {
     var triggerButton = document.querySelector("#".concat(triggerId));
+    if (!triggerButton) {
+        throw new Error("Invalid menu trigger button id provided");
+    }
     var currentAriaExpandedState = triggerButton.getAttribute('aria-expanded');
+    if (!currentAriaExpandedState) {
+        throw new Error("Menu trigger button does not have aria-expanded attribute");
+    }
     function triggerOpen(ariaLabel) {
         triggerButton.setAttribute('aria-expanded', 'true');
         triggerButton.setAttribute('aria-label', ariaLabel);

package/src/menu/updateMenuTriggerAriaAttributes.ts

@@ -8,8 +8,14 @@ import { HTMLElement } from "../../Types";
 
 export function updateMenuTriggerAriaAttributes(triggerId: string, ariaLabel: string): void {
     const triggerButton: HTMLElement = document.querySelector(`#${triggerId}`) as HTMLElement
+    if(!triggerButton) {
+        throw new Error("Invalid menu trigger button id provided")
+    }
 
     const currentAriaExpandedState: string = triggerButton.getAttribute('aria-expanded') as string
+    if(!currentAriaExpandedState) {
+        throw new Error("Menu trigger button does not have aria-expanded attribute")
+    }
 
     function triggerOpen(ariaLabel: string): void {
         triggerButton.setAttribute('aria-expanded', 'true')