aria-ease 6.2.3 → 6.3.0

package/README.md

@@ -11,7 +11,7 @@ Out of the box accessibility utility package to develop production ready applica
 
 - 🎯 **Tree-shakable** - Import only what you need (1.4KB - 3.7KB per component)
 - ♿ **WCAG Compliant** - Follows WAI-ARIA best practices
-- ⌨️ **Keyboard Navigation** - Full keyboard support out of the box
+- ⌨️ **Keyboard Interaction** - Full keyboard support out of the box
 - 🧪 **Contract Testing** - Built-in accessibility testing framework
 - 🎭 **Framework Agnostic** - Works with React, Vue, vanilla JS, etc.
 - 🔍 **CLI Audit Tool** - Automated accessibility testing for your sites
@@ -82,7 +82,7 @@ The CLI will automatically find and load your config file, with validation to ca
 
 ### 🍔 Menu (Dropdowns)
 
-Creates accessible menus with focus trapping and keyboard navigation. Works for dropdowns that toggles display with interactive items.
+Creates accessible menus with aria attribute management, focus trapping, and keyboard interaction. Works for dropdowns that toggles display with interactive items.
 
 **Features:**
 
@@ -138,13 +138,97 @@ menu.refresh();
 
 ## 🎮 Live Demo
 
-- [Menu Component](https://codesandbox.io/p/sandbox/szsclq) - Dropdown with keyboard navigation
+- [Menu Component](https://codepen.io/aria-ease/pen/PwGqdzp) - Menu dropdown with keyboard interaction
+
+---
+
+### 🍔 Combobox (Listbox)
+
+Creates accessible listbox combobox with aria attribute management, focus trapping, and keyboard interaction.
+
+**Features:**
+
+- Arrow key navigation
+- Escape key closes listbox
+- ARIA attribute management (aria-expanded, aria-activedescendant, aria-controls, roles)
+- Focus management with aria-activedescendant pattern
+
+```javascript
+import * as Combobox from "aria-ease/combobox";
+
+// React Example
+useEffect(() => {
+  comboboxRef.current = Combobox.makeComboboxAccessible({
+    comboboxInputId: "search-input",
+    listBoxId: "suggestions-list",
+    listBoxItemsClass: "suggestion-item",
+  });
+
+  return () => {
+    if (comboboxRef.current) {
+      comboboxRef.current.cleanup();
+    }
+  };
+}, []);
+
+// Programmatically control
+comboboxRef.current.openListbox(); // Open the listbox
+comboboxRef.current.refresh(); // Refresh the cache after dynamically adding/removing a listbox option item
+
+// Vanilla JS Example
+const combobox = Combobox.makeComboboxAccessible({
+  comboboxInputId: "fruit",
+  comboboxButtonId: "show-list-button",
+  listBoxId: "fruits-listbox",
+  listBoxItemsClass: "list-option",
+  callback: {
+    onSelect: (option) => {
+      input.value = option.textContent;
+      // Show all options after selection
+      options.forEach((opt) => (opt.hidden = false));
+    },
+    onOpenChange: (isOpen) => {
+      console.log("Listbox is", isOpen ? "open" : "closed");
+    },
+  },
+});
+
+// Programmatically control
+combobox.openListbox();
+combobox.closeListbox();
+
+// If you dynamically add/remove listbox option items, refresh the cache
+combobox.refresh();
+```
+
+**Required HTML structure:**
+
+```html
+<div id="combo-wrapper">
+  <label for="fruit">Select a fruit</label>
+  <div class="input-wrapper">
+    <input type="text" id="fruit" placeholder="Search fruits..." />
+    <button id="show-list-button" tabindex="-1">▼</button>
+  </div>
+
+  <ul id="fruits-listbox">
+    <li id="apple" class="list-option">Apple</li>
+    <li id="mango" class="list-option">Mango</li>
+    <li id="orange" class="list-option">Orange</li>
+    <li id="banana" class="list-option">Banana</li>
+  </ul>
+</div>
+```
+
+## 🎮 Live Demo
+
+- [Combobox Component](https://codepen.io/aria-ease/pen/ByLNqOE) - Listbox combobox with keyboard interaction
 
 ---
 
 ### 🪗 Accordion
 
-Creates accessible accordions with keyboard navigation and automatic state management.
+Creates accessible accordions with keyboard interaction and automatic state management.
 
 **Features:**
 
@@ -212,14 +296,12 @@ makeAccordionAccessible({
 
 ### ✅ Checkbox
 
-Creates accessible checkbox groups with keyboard navigation and state management.
+Creates accessible checkbox groups with keyboard interaction and state management.
 
 **Features:**
 
-- Arrow key navigation
 - Space to toggle
 - Independent state tracking
-- Home/End key support
 - Query checked states
 
 ```javascript
@@ -270,14 +352,13 @@ makeCheckboxAccessible({
 
 ### 🔘 Radio Button
 
-Creates accessible radio groups with keyboard navigation and automatic selection management.
+Creates accessible radio groups with keyboard interaction and automatic selection management.
 
 **Features:**
 
 - Arrow key navigation (all directions)
 - Automatic unchecking of other radios
 - Space to select
-- Home/End key support
 - Single selection enforcement
 
 ```javascript
@@ -334,8 +415,6 @@ Creates accessible toggle buttons with keyboard interactions and state managemen
 
 - Enter/Space to toggle
 - Single toggle or toggle groups
-- Arrow key navigation (groups)
-- Home/End support (groups)
 - Query pressed states
 
 ```javascript
@@ -492,7 +571,7 @@ useEffect(() => {
 
 ## 🎨 Focus Styling
 
-Aria-Ease handles ARIA attributes and keyboard navigation, but **you must provide visible focus styles**:
+Aria-Ease handles ARIA attributes and keyboard interaction, but **you must provide visible focus styles**:
 
 ```css
 :focus {

package/bin/{chunk-7RMRFSJL.js → chunk-XLG3MIPQ.js}

@@ -11,6 +11,10 @@ var contract_default = {
   accordion: {
     path: "./contracts/AccordionContract.json",
     component: "accordion"
+  },
+  tabs: {
+    path: "./contracts/TabsContract.json",
+    component: "tabs"
   }
 };
 
@@ -125,7 +129,7 @@ ${"\u2500".repeat(60)}`);
     this.log(`\u{1F4A1} Optional Enhancements (${suggestions.length}):
 `);
     this.log(`These features are optional per APG guidelines but recommended`);
-    this.log(`for improved user experience and keyboard navigation:
+    this.log(`for improved user experience and keyboard interaction:
 `);
     suggestions.forEach((test, index) => {
       this.log(`${index + 1}. ${test.description}`);

package/bin/cli.cjs

@@ -299,6 +299,10 @@ var init_contract = __esm({
       accordion: {
         path: "./contracts/AccordionContract.json",
         component: "accordion"
+      },
+      tabs: {
+        path: "./contracts/TabsContract.json",
+        component: "tabs"
       }
     };
   }
@@ -419,7 +423,7 @@ ${"\u2500".repeat(60)}`);
         this.log(`\u{1F4A1} Optional Enhancements (${suggestions.length}):
 `);
         this.log(`These features are optional per APG guidelines but recommended`);
-        this.log(`for improved user experience and keyboard navigation:
+        this.log(`for improved user experience and keyboard interaction:
 `);
         suggestions.forEach((test, index) => {
           this.log(`${index + 1}. ${test.description}`);
@@ -708,9 +712,9 @@ async function runContractTestsPlaywright(componentName, url) {
       }
       await page.addStyleTag({ content: `* { transition: none !important; animation: none !important; }` });
     }
-    const mainSelector = componentContract.selectors.trigger || componentContract.selectors.input || componentContract.selectors.container;
+    const mainSelector = componentContract.selectors.trigger || componentContract.selectors.input || componentContract.selectors.container || componentContract.selectors.tablist || componentContract.selectors.tab;
     if (!mainSelector) {
-      throw new Error(`CRITICAL: No main selector (trigger, input, or container) found in contract for ${componentName}`);
+      throw new Error(`CRITICAL: No main selector (trigger, input, container, tablist, or tab) found in contract for ${componentName}`);
     }
     try {
       await page.locator(mainSelector).first().waitFor({ state: "attached", timeout: 3e4 });
@@ -772,28 +776,52 @@ async function runContractTestsPlaywright(componentName, url) {
         failures.push(`Target ${test.target} not found.`);
         continue;
       }
+      const isRedundantCheck = (selector, attrName, expectedVal) => {
+        const attrPattern = new RegExp(`\\[${attrName}(?:=["']?([^\\]"']+)["']?)?\\]`);
+        const match = selector.match(attrPattern);
+        if (!match) return false;
+        if (!expectedVal) return true;
+        const selectorValue = match[1];
+        if (selectorValue) {
+          const expectedValues = expectedVal.split(" | ");
+          return expectedValues.includes(selectorValue);
+        }
+        return false;
+      };
       if (!test.expectedValue) {
         const attributes = test.attribute.split(" | ");
         let hasAny = false;
+        let allRedundant = true;
         for (const attr of attributes) {
-          const value = await target.getAttribute(attr.trim());
+          const attrTrimmed = attr.trim();
+          if (isRedundantCheck(targetSelector, attrTrimmed)) {
+            passes.push(`${attrTrimmed} on ${test.target} verified by selector (already present in: ${targetSelector}).`);
+            hasAny = true;
+            continue;
+          }
+          allRedundant = false;
+          const value = await target.getAttribute(attrTrimmed);
           if (value !== null) {
             hasAny = true;
             break;
           }
         }
-        if (!hasAny) {
+        if (!hasAny && !allRedundant) {
           failures.push(test.failureMessage + ` None of the attributes "${test.attribute}" are present.`);
-        } else {
+        } else if (!allRedundant && hasAny) {
           passes.push(`At least one of the attributes "${test.attribute}" exists on the element.`);
         }
       } else {
-        const attributeValue = await target.getAttribute(test.attribute);
-        const expectedValues = test.expectedValue.split(" | ");
-        if (!attributeValue || !expectedValues.includes(attributeValue)) {
-          failures.push(test.failureMessage + ` Attribute value does not match expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+        if (isRedundantCheck(targetSelector, test.attribute, test.expectedValue)) {
+          passes.push(`${test.attribute}="${test.expectedValue}" on ${test.target} verified by selector (already present in: ${targetSelector}).`);
         } else {
-          passes.push(`Attribute value matches expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+          const attributeValue = await target.getAttribute(test.attribute);
+          const expectedValues = test.expectedValue.split(" | ");
+          if (!attributeValue || !expectedValues.includes(attributeValue)) {
+            failures.push(test.failureMessage + ` Attribute value does not match expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+          } else {
+            passes.push(`Attribute value matches expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+          }
         }
       }
     }
@@ -902,6 +930,19 @@ This indicates a problem with the menu component's close functionality.`
       if (shouldSkipTest) {
         continue;
       }
+      if (componentContract.selectors.panel && componentContract.selectors.tab && componentContract.selectors.tablist) {
+        if (dynamicTest.isVertical !== void 0 && componentContract.selectors.tablist) {
+          const tablistSelector = componentContract.selectors.tablist;
+          const tablist = page.locator(tablistSelector).first();
+          const orientation = await tablist.getAttribute("aria-orientation");
+          const isVertical = orientation === "vertical";
+          if (dynamicTest.isVertical !== isVertical) {
+            const skipReason = dynamicTest.isVertical ? `Skipping vertical tabs test - component has horizontal orientation` : `Skipping horizontal tabs test - component has vertical orientation`;
+            reporter.reportTest(dynamicTest, "skip", skipReason);
+            continue;
+          }
+        }
+      }
       for (const act of action) {
         if (!page || page.isClosed()) {
           failures.push(`CRITICAL: Browser/page closed during test execution. Remaining actions skipped.`);

package/bin/cli.js

@@ -207,7 +207,7 @@ program.command("audit").description("Run axe-core powered accessibility audit o
   console.log(chalk.green("\n\u{1F389} All audits completed."));
 });
 program.command("test").description("Run core a11y accessibility standard tests on UI components").action(async () => {
-  const { runTest } = await import("./test-A3ESFXOR.js");
+  const { runTest } = await import("./test-XSDP2NX3.js");
   runTest();
 });
 program.command("help").description("Display help information").action(() => {

package/bin/{contractTestRunnerPlaywright-ACAWN34W.js → contractTestRunnerPlaywright-JXQUUKFO.js}

@@ -2,7 +2,7 @@ import {
   ContractReporter,
   contract_default,
   createTestPage
-} from "./chunk-7RMRFSJL.js";
+} from "./chunk-XLG3MIPQ.js";
 import {
   __export,
   __reExport
@@ -56,9 +56,9 @@ async function runContractTestsPlaywright(componentName, url) {
       }
       await page.addStyleTag({ content: `* { transition: none !important; animation: none !important; }` });
     }
-    const mainSelector = componentContract.selectors.trigger || componentContract.selectors.input || componentContract.selectors.container;
+    const mainSelector = componentContract.selectors.trigger || componentContract.selectors.input || componentContract.selectors.container || componentContract.selectors.tablist || componentContract.selectors.tab;
     if (!mainSelector) {
-      throw new Error(`CRITICAL: No main selector (trigger, input, or container) found in contract for ${componentName}`);
+      throw new Error(`CRITICAL: No main selector (trigger, input, container, tablist, or tab) found in contract for ${componentName}`);
     }
     try {
       await page.locator(mainSelector).first().waitFor({ state: "attached", timeout: 3e4 });
@@ -120,28 +120,52 @@ async function runContractTestsPlaywright(componentName, url) {
         failures.push(`Target ${test.target} not found.`);
         continue;
       }
+      const isRedundantCheck = (selector, attrName, expectedVal) => {
+        const attrPattern = new RegExp(`\\[${attrName}(?:=["']?([^\\]"']+)["']?)?\\]`);
+        const match = selector.match(attrPattern);
+        if (!match) return false;
+        if (!expectedVal) return true;
+        const selectorValue = match[1];
+        if (selectorValue) {
+          const expectedValues = expectedVal.split(" | ");
+          return expectedValues.includes(selectorValue);
+        }
+        return false;
+      };
       if (!test.expectedValue) {
         const attributes = test.attribute.split(" | ");
         let hasAny = false;
+        let allRedundant = true;
         for (const attr of attributes) {
-          const value = await target.getAttribute(attr.trim());
+          const attrTrimmed = attr.trim();
+          if (isRedundantCheck(targetSelector, attrTrimmed)) {
+            passes.push(`${attrTrimmed} on ${test.target} verified by selector (already present in: ${targetSelector}).`);
+            hasAny = true;
+            continue;
+          }
+          allRedundant = false;
+          const value = await target.getAttribute(attrTrimmed);
           if (value !== null) {
             hasAny = true;
             break;
           }
         }
-        if (!hasAny) {
+        if (!hasAny && !allRedundant) {
           failures.push(test.failureMessage + ` None of the attributes "${test.attribute}" are present.`);
-        } else {
+        } else if (!allRedundant && hasAny) {
           passes.push(`At least one of the attributes "${test.attribute}" exists on the element.`);
         }
       } else {
-        const attributeValue = await target.getAttribute(test.attribute);
-        const expectedValues = test.expectedValue.split(" | ");
-        if (!attributeValue || !expectedValues.includes(attributeValue)) {
-          failures.push(test.failureMessage + ` Attribute value does not match expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+        if (isRedundantCheck(targetSelector, test.attribute, test.expectedValue)) {
+          passes.push(`${test.attribute}="${test.expectedValue}" on ${test.target} verified by selector (already present in: ${targetSelector}).`);
         } else {
-          passes.push(`Attribute value matches expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+          const attributeValue = await target.getAttribute(test.attribute);
+          const expectedValues = test.expectedValue.split(" | ");
+          if (!attributeValue || !expectedValues.includes(attributeValue)) {
+            failures.push(test.failureMessage + ` Attribute value does not match expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+          } else {
+            passes.push(`Attribute value matches expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+          }
         }
       }
     }
@@ -250,6 +274,19 @@ This indicates a problem with the menu component's close functionality.`
       if (shouldSkipTest) {
         continue;
       }
+      if (componentContract.selectors.panel && componentContract.selectors.tab && componentContract.selectors.tablist) {
+        if (dynamicTest.isVertical !== void 0 && componentContract.selectors.tablist) {
+          const tablistSelector = componentContract.selectors.tablist;
+          const tablist = page.locator(tablistSelector).first();
+          const orientation = await tablist.getAttribute("aria-orientation");
+          const isVertical = orientation === "vertical";
+          if (dynamicTest.isVertical !== isVertical) {
+            const skipReason = dynamicTest.isVertical ? `Skipping vertical tabs test - component has horizontal orientation` : `Skipping horizontal tabs test - component has vertical orientation`;
+            reporter.reportTest(dynamicTest, "skip", skipReason);
+            continue;
+          }
+        }
+      }
       for (const act of action) {
         if (!page || page.isClosed()) {
           failures.push(`CRITICAL: Browser/page closed during test execution. Remaining actions skipped.`);

package/bin/{test-A3ESFXOR.js → test-XSDP2NX3.js}

@@ -2,7 +2,7 @@ import {
   ContractReporter,
   closeSharedBrowser,
   contract_default
-} from "./chunk-7RMRFSJL.js";
+} from "./chunk-XLG3MIPQ.js";
 import "./chunk-I2KLQ2HA.js";
 
 // src/utils/test/src/test.ts
@@ -114,7 +114,7 @@ Error: ${error instanceof Error ? error.message : String(error)}`
       const devServerUrl = await checkDevServer(url);
       if (devServerUrl) {
         console.log(`\u{1F3AD} Running Playwright tests on ${devServerUrl}`);
-        const { runContractTestsPlaywright } = await import("./contractTestRunnerPlaywright-ACAWN34W.js");
+        const { runContractTestsPlaywright } = await import("./contractTestRunnerPlaywright-JXQUUKFO.js");
         contract = await runContractTestsPlaywright(componentName, devServerUrl);
       } else {
         throw new Error(

package/dist/{chunk-PDZQOXUN.js → chunk-RDEAG4KE.js}

@@ -29,6 +29,10 @@ var contract_default = {
   accordion: {
     path: "./contracts/AccordionContract.json",
     component: "accordion"
+  },
+  tabs: {
+    path: "./contracts/TabsContract.json",
+    component: "tabs"
   }
 };
 
@@ -143,7 +147,7 @@ ${"\u2500".repeat(60)}`);
     this.log(`\u{1F4A1} Optional Enhancements (${suggestions.length}):
 `);
     this.log(`These features are optional per APG guidelines but recommended`);
-    this.log(`for improved user experience and keyboard navigation:
+    this.log(`for improved user experience and keyboard interaction:
 `);
     suggestions.forEach((test, index) => {
       this.log(`${index + 1}. ${test.description}`);

package/dist/{contractTestRunnerPlaywright-O7FF7GV4.js → contractTestRunnerPlaywright-EUXD6ZZK.js}

@@ -4,7 +4,7 @@ import {
   __reExport,
   contract_default,
   createTestPage
-} from "./chunk-PDZQOXUN.js";
+} from "./chunk-RDEAG4KE.js";
 
 // node_modules/@playwright/test/index.mjs
 var test_exports = {};
@@ -54,9 +54,9 @@ async function runContractTestsPlaywright(componentName, url) {
       }
       await page.addStyleTag({ content: `* { transition: none !important; animation: none !important; }` });
     }
-    const mainSelector = componentContract.selectors.trigger || componentContract.selectors.input || componentContract.selectors.container;
+    const mainSelector = componentContract.selectors.trigger || componentContract.selectors.input || componentContract.selectors.container || componentContract.selectors.tablist || componentContract.selectors.tab;
     if (!mainSelector) {
-      throw new Error(`CRITICAL: No main selector (trigger, input, or container) found in contract for ${componentName}`);
+      throw new Error(`CRITICAL: No main selector (trigger, input, container, tablist, or tab) found in contract for ${componentName}`);
     }
     try {
       await page.locator(mainSelector).first().waitFor({ state: "attached", timeout: 3e4 });
@@ -118,28 +118,52 @@ async function runContractTestsPlaywright(componentName, url) {
         failures.push(`Target ${test.target} not found.`);
         continue;
       }
+      const isRedundantCheck = (selector, attrName, expectedVal) => {
+        const attrPattern = new RegExp(`\\[${attrName}(?:=["']?([^\\]"']+)["']?)?\\]`);
+        const match = selector.match(attrPattern);
+        if (!match) return false;
+        if (!expectedVal) return true;
+        const selectorValue = match[1];
+        if (selectorValue) {
+          const expectedValues = expectedVal.split(" | ");
+          return expectedValues.includes(selectorValue);
+        }
+        return false;
+      };
       if (!test.expectedValue) {
         const attributes = test.attribute.split(" | ");
         let hasAny = false;
+        let allRedundant = true;
         for (const attr of attributes) {
-          const value = await target.getAttribute(attr.trim());
+          const attrTrimmed = attr.trim();
+          if (isRedundantCheck(targetSelector, attrTrimmed)) {
+            passes.push(`${attrTrimmed} on ${test.target} verified by selector (already present in: ${targetSelector}).`);
+            hasAny = true;
+            continue;
+          }
+          allRedundant = false;
+          const value = await target.getAttribute(attrTrimmed);
           if (value !== null) {
             hasAny = true;
             break;
           }
         }
-        if (!hasAny) {
+        if (!hasAny && !allRedundant) {
           failures.push(test.failureMessage + ` None of the attributes "${test.attribute}" are present.`);
-        } else {
+        } else if (!allRedundant && hasAny) {
           passes.push(`At least one of the attributes "${test.attribute}" exists on the element.`);
         }
       } else {
-        const attributeValue = await target.getAttribute(test.attribute);
-        const expectedValues = test.expectedValue.split(" | ");
-        if (!attributeValue || !expectedValues.includes(attributeValue)) {
-          failures.push(test.failureMessage + ` Attribute value does not match expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+        if (isRedundantCheck(targetSelector, test.attribute, test.expectedValue)) {
+          passes.push(`${test.attribute}="${test.expectedValue}" on ${test.target} verified by selector (already present in: ${targetSelector}).`);
         } else {
-          passes.push(`Attribute value matches expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+          const attributeValue = await target.getAttribute(test.attribute);
+          const expectedValues = test.expectedValue.split(" | ");
+          if (!attributeValue || !expectedValues.includes(attributeValue)) {
+            failures.push(test.failureMessage + ` Attribute value does not match expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+          } else {
+            passes.push(`Attribute value matches expected value. Expected: ${test.expectedValue}, Found: ${attributeValue}`);
+          }
         }
       }
     }
@@ -248,6 +272,19 @@ This indicates a problem with the menu component's close functionality.`
       if (shouldSkipTest) {
         continue;
       }
+      if (componentContract.selectors.panel && componentContract.selectors.tab && componentContract.selectors.tablist) {
+        if (dynamicTest.isVertical !== void 0 && componentContract.selectors.tablist) {
+          const tablistSelector = componentContract.selectors.tablist;
+          const tablist = page.locator(tablistSelector).first();
+          const orientation = await tablist.getAttribute("aria-orientation");
+          const isVertical = orientation === "vertical";
+          if (dynamicTest.isVertical !== isVertical) {
+            const skipReason = dynamicTest.isVertical ? `Skipping vertical tabs test - component has horizontal orientation` : `Skipping horizontal tabs test - component has vertical orientation`;
+            reporter.reportTest(dynamicTest, "skip", skipReason);
+            continue;
+          }
+        }
+      }
       for (const act of action) {
         if (!page || page.isClosed()) {
           failures.push(`CRITICAL: Browser/page closed during test execution. Remaining actions skipped.`);