aria-ease 3.0.3 → 4.0.1

package/README.md

@@ -156,136 +156,255 @@ menu.refresh();
 
 ### 🪗 Accordion
 
-Updates `aria-expanded` attributes for accordion panels.
+Creates accessible accordions with keyboard navigation and automatic state management.
+
+**Features:**
+
+- Arrow key navigation between triggers
+- Automatic ARIA attribute management
+- Single or multiple panel expansion
+- Enter/Space to toggle panels
+- Home/End key support
 
 ```javascript
-import { updateAccordionTriggerAriaAttributes } from "aria-ease/accordion";
+import { makeAccordionAccessible } from "aria-ease/accordion";
+
+// React Example
+useEffect(() => {
+  const accordion = makeAccordionAccessible({
+    accordionId: "accordion-container",
+    triggersClass: "accordion-trigger",
+    panelsClass: "accordion-panel",
+    allowMultiple: false, // Only one panel open at a time (default)
+  });
 
-const accordionStates = [
-  { expanded: true },
-  { expanded: false },
-  { expanded: false },
-];
+  return () => accordion.cleanup();
+}, []);
 
-// Call when accordion state changes
-updateAccordionTriggerAriaAttributes(
-  "accordion-container", // Container ID
-  "accordion-trigger", // Shared class for triggers
-  accordionStates, // State array
-  0, // Index of trigger that changed
-);
+// Programmatic control
+accordion.expandItem(0); // Expand first panel
+accordion.collapseItem(1); // Collapse second panel
+accordion.toggleItem(2); // Toggle third panel
 ```
 
 **HTML structure:**
 
 ```html
 <div id="accordion-container">
-  <button
-    class="accordion-trigger"
-    aria-expanded="false"
-    aria-controls="panel-1"
-  >
-    Section 1
-  </button>
-  <div id="panel-1">Content 1</div>
-
-  <button
-    class="accordion-trigger"
-    aria-expanded="false"
-    aria-controls="panel-2"
-  >
-    Section 2
-  </button>
-  <div id="panel-2">Content 2</div>
+  <button class="accordion-trigger">Section 1</button>
+  <div class="accordion-panel">Content 1</div>
+
+  <button class="accordion-trigger">Section 2</button>
+  <div class="accordion-panel">Content 2</div>
+
+  <button class="accordion-trigger">Section 3</button>
+  <div class="accordion-panel">Content 3</div>
 </div>
 ```
 
+<details>
+<summary>📌 Legacy API (Still Supported)</summary>
+
+```javascript
+import { updateAccordionTriggerAriaAttributes } from "aria-ease/accordion";
+
+const accordionStates = [{ display: true }, { display: false }];
+
+updateAccordionTriggerAriaAttributes(
+  "accordion-container",
+  "accordion-trigger",
+  accordionStates,
+  0,
+);
+```
+
+</details>
+
 ---
 
 ### ✅ Checkbox
 
-Updates `aria-checked` attributes for custom checkboxes.
+Creates accessible checkbox groups with keyboard navigation and state management.
+
+**Features:**
+
+- Arrow key navigation
+- Space to toggle
+- Independent state tracking
+- Home/End key support
+- Query checked states
 
 ```javascript
-import { updateCheckboxAriaAttributes } from "aria-ease/checkbox";
+import { makeCheckboxAccessible } from "aria-ease/checkbox";
 
-const checkboxStates = [
-  { checked: true },
-  { checked: false },
-  { checked: true },
-];
-
-// Call when checkbox is toggled
-function handleCheckboxClick(index) {
-  checkboxStates[index].checked = !checkboxStates[index].checked;
-
-  updateCheckboxAriaAttributes(
-    "checkbox-group",
-    "custom-checkbox",
-    checkboxStates,
-    index,
-  );
-}
+// React Example
+useEffect(() => {
+  const checkboxGroup = makeCheckboxAccessible({
+    checkboxGroupId: "checkbox-group",
+    checkboxesClass: "custom-checkbox",
+  });
+
+  return () => checkboxGroup.cleanup();
+}, []);
+
+// Programmatic control
+checkboxGroup.toggleCheckbox(0); // Toggle first checkbox
+checkboxGroup.setCheckboxState(1, true); // Check second checkbox
+const states = checkboxGroup.getCheckedStates(); // [true, false, true]
+const indices = checkboxGroup.getCheckedIndices(); // [0, 2]
 ```
 
 **HTML structure:**
 
 ```html
 <div id="checkbox-group">
-  <div
-    class="custom-checkbox"
-    role="checkbox"
-    aria-checked="false"
-    aria-label="Option 1"
-  ></div>
-  <div
-    class="custom-checkbox"
-    role="checkbox"
-    aria-checked="false"
-    aria-label="Option 2"
-  ></div>
+  <div class="custom-checkbox" aria-label="Option 1"></div>
+  <div class="custom-checkbox" aria-label="Option 2"></div>
+  <div class="custom-checkbox" aria-label="Option 3"></div>
 </div>
 ```
 
+<details>
+<summary>📌 Legacy API (Still Supported)</summary>
+
+```javascript
+import { updateCheckboxAriaAttributes } from "aria-ease/checkbox";
+
+const checkboxStates = [{ checked: true }, { checked: false }];
+
+updateCheckboxAriaAttributes(
+  "checkbox-group",
+  "custom-checkbox",
+  checkboxStates,
+  0,
+);
+```
+
+</details>
+
 ---
 
 ### 🔘 Radio Button
 
-Updates `aria-checked` attributes for custom radio buttons.
+Creates accessible radio groups with keyboard navigation and automatic selection management.
 
-```javascript
-import { updateRadioAriaAttributes } from "aria-ease/radio";
+**Features:**
+
+- Arrow key navigation (all directions)
+- Automatic unchecking of other radios
+- Space to select
+- Home/End key support
+- Single selection enforcement
 
-const radioStates = [{ checked: true }, { checked: false }, { checked: false }];
+```javascript
+import { makeRadioAccessible } from "aria-ease/radio";
 
-function handleRadioSelect(index) {
-  // Uncheck all, check selected
-  radioStates.forEach((state, i) => {
-    state.checked = i === index;
+// React Example
+useEffect(() => {
+  const radioGroup = makeRadioAccessible({
+    radioGroupId: "radio-group",
+    radiosClass: "custom-radio",
+    defaultSelectedIndex: 0, // Initially selected (optional)
   });
 
-  updateRadioAriaAttributes("radio-group", "custom-radio", radioStates);
-}
+  return () => radioGroup.cleanup();
+}, []);
+
+// Programmatic control
+radioGroup.selectRadio(2); // Select third radio
+const selected = radioGroup.getSelectedIndex(); // Get current selection
 ```
 
+**HTML structure:**
+
+```html
+<div id="radio-group">
+  <div class="custom-radio" aria-label="Option 1"></div>
+  <div class="custom-radio" aria-label="Option 2"></div>
+  <div class="custom-radio" aria-label="Option 3"></div>
+</div>
+```
+
+<details>
+<summary>📌 Legacy API (Still Supported)</summary>
+
+```javascript
+import { updateRadioAriaAttributes } from "aria-ease/radio";
+
+const radioStates = [{ checked: true }, { checked: false }];
+
+updateRadioAriaAttributes("radio-group", "custom-radio", radioStates, 0);
+```
+
+</details>
+
 ---
 
 ### 🔀 Toggle Button
 
-Updates `aria-pressed` attributes for toggle buttons.
+Creates accessible toggle buttons with keyboard interactions and state management.
+
+**Features:**
+
+- Enter/Space to toggle
+- Single toggle or toggle groups
+- Arrow key navigation (groups)
+- Home/End support (groups)
+- Query pressed states
 
 ```javascript
-import { updateToggleAriaAttribute } from "aria-ease/toggle";
+import { makeToggleAccessible } from "aria-ease/toggle";
 
-const toggleStates = [{ pressed: false }, { pressed: true }];
+// Single toggle button
+const toggle = makeToggleAccessible({
+  toggleId: "mute-button",
+  isSingleToggle: true,
+});
 
-function handleToggle(index) {
-  toggleStates[index].pressed = !toggleStates[index].pressed;
+// Toggle button group
+const toggleGroup = makeToggleAccessible({
+  toggleId: "toolbar",
+  togglesClass: "toggle-btn",
+  isSingleToggle: false,
+});
 
-  updateToggleAriaAttribute("toggle-container", "toggle-btn", toggleStates);
-}
+// Programmatic control
+toggle.toggleButton(0); // Toggle the button
+toggle.setPressed(0, true); // Set pressed state
+const states = toggleGroup.getPressedStates(); // [false, true, false]
+const indices = toggleGroup.getPressedIndices(); // [1]
+
+// Cleanup
+toggle.cleanup();
+```
+
+**HTML structure:**
+
+```html
+<!-- Single toggle -->
+<button id="mute-button">Mute</button>
+
+<!-- Toggle group -->
+<div id="toolbar">
+  <button class="toggle-btn">Bold</button>
+  <button class="toggle-btn">Italic</button>
+  <button class="toggle-btn">Underline</button>
+</div>
 ```
 
+<details>
+<summary>📌 Legacy API (Still Supported)</summary>
+
+```javascript
+import { updateToggleAriaAttribute } from "aria-ease/toggle";
+
+const toggleStates = [{ pressed: false }];
+
+updateToggleAriaAttribute("toggle-container", "toggle-btn", toggleStates, 0);
+```
+
+</details>
+
 ---
 
 ### 🧱 Block (Generic Focusable Groups)
@@ -336,23 +455,24 @@ Aria-Ease is designed to be lightweight and tree-shakable:
 
 | Import                       | Size (ESM)            |
 | ---------------------------- | --------------------- |
-| `aria-ease/accordion`        | ~1.5KB                |
-| `aria-ease/checkbox`         | ~1.6KB                |
-| `aria-ease/radio`            | ~1.6KB                |
-| `aria-ease/toggle`           | ~1.4KB                |
-| `aria-ease/menu`             | ~3.7KB                |
+| `aria-ease/accordion`        | ~6.5KB                |
+| `aria-ease/checkbox`         | ~6.0KB                |
+| `aria-ease/radio`            | ~5.5KB                |
+| `aria-ease/toggle`           | ~6.0KB                |
+| `aria-ease/menu`             | ~6.7KB                |
 | `aria-ease/block`            | ~1.7KB                |
-| Full bundle (all components) | ~416KB (uncompressed) |
+| `aria-ease/combobox`         | ~8.1KB                |
+| Full bundle (all components) | ~459KB (uncompressed) |
 
 **💡 Tip:** Always import individual components for optimal bundle size:
 
 ```javascript
-// ✅ Good - only imports menu code (~3.7KB)
+// ✅ Good - only imports menu code (~6.7KB)
 import { makeMenuAccessible } from "aria-ease/menu";
 //or
 import * as Block from "aria-ease/block";
 
-// ❌ Avoid - imports everything (~416KB)
+// ❌ Avoid - imports everything (~459KB)
 import { makeMenuAccessible } from "aria-ease";
 ```
 

package/bin/cli.cjs

@@ -13425,6 +13425,38 @@ async function runContractTestsPlaywright(componentName, url) {
           }
         }
       }
+      let shouldSkipTest = false;
+      for (const act of action) {
+        if (act.type === "keypress" && (act.target === "submenuTrigger" || act.target === "submenu")) {
+          const submenuSelector = componentContract.selectors[act.target];
+          if (submenuSelector) {
+            const submenuCount = await page.locator(submenuSelector).count();
+            if (submenuCount === 0) {
+              reporter.reportTest(dynamicTest, "skip", `Skipping test - ${act.target} element not found (optional submenu test)`);
+              shouldSkipTest = true;
+              break;
+            }
+          }
+        }
+      }
+      if (!shouldSkipTest) {
+        for (const assertion of assertions) {
+          if (assertion.target === "submenu" || assertion.target === "submenuTrigger") {
+            const submenuSelector = componentContract.selectors[assertion.target];
+            if (submenuSelector) {
+              const submenuCount = await page.locator(submenuSelector).count();
+              if (submenuCount === 0) {
+                reporter.reportTest(dynamicTest, "skip", `Skipping test - ${assertion.target} element not found (optional submenu test)`);
+                shouldSkipTest = true;
+                break;
+              }
+            }
+          }
+        }
+      }
+      if (shouldSkipTest) {
+        continue;
+      }
       for (const act of action) {
         if (act.type === "focus") {
           const focusSelector = componentContract.selectors[act.target];

package/bin/cli.js

@@ -204,7 +204,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-D374H2ZS.js");
+  const { runTest } = await import("./test-45KMD4F4.js");
   runTest();
 });
 program.command("help").description("Display help information").action(() => {

package/bin/{contractTestRunnerPlaywright-3VJUZSYK.js → contractTestRunnerPlaywright-EZLNNJV5.js}

@@ -152,6 +152,38 @@ async function runContractTestsPlaywright(componentName, url) {
           }
         }
       }
+      let shouldSkipTest = false;
+      for (const act of action) {
+        if (act.type === "keypress" && (act.target === "submenuTrigger" || act.target === "submenu")) {
+          const submenuSelector = componentContract.selectors[act.target];
+          if (submenuSelector) {
+            const submenuCount = await page.locator(submenuSelector).count();
+            if (submenuCount === 0) {
+              reporter.reportTest(dynamicTest, "skip", `Skipping test - ${act.target} element not found (optional submenu test)`);
+              shouldSkipTest = true;
+              break;
+            }
+          }
+        }
+      }
+      if (!shouldSkipTest) {
+        for (const assertion of assertions) {
+          if (assertion.target === "submenu" || assertion.target === "submenuTrigger") {
+            const submenuSelector = componentContract.selectors[assertion.target];
+            if (submenuSelector) {
+              const submenuCount = await page.locator(submenuSelector).count();
+              if (submenuCount === 0) {
+                reporter.reportTest(dynamicTest, "skip", `Skipping test - ${assertion.target} element not found (optional submenu test)`);
+                shouldSkipTest = true;
+                break;
+              }
+            }
+          }
+        }
+      }
+      if (shouldSkipTest) {
+        continue;
+      }
       for (const act of action) {
         if (act.type === "focus") {
           const focusSelector = componentContract.selectors[act.target];

package/bin/{test-D374H2ZS.js → test-45KMD4F4.js}

@@ -12776,7 +12776,7 @@ Error: ${error instanceof Error ? error.message : String(error)}`
 URL must include protocol (e.g., "http://localhost:5173/test")`
         );
       }
-      const { runContractTestsPlaywright } = await import("./contractTestRunnerPlaywright-3VJUZSYK.js");
+      const { runContractTestsPlaywright } = await import("./contractTestRunnerPlaywright-EZLNNJV5.js");
       contract = await runContractTestsPlaywright(componentName, url);
     } else {
       console.log(`\u{1F9EA} Running jsdom tests (limited event handling)`);

package/dist/{contractTestRunnerPlaywright-4UOHWGWD.js → contractTestRunnerPlaywright-UQQI5MYS.js}

@@ -150,6 +150,38 @@ async function runContractTestsPlaywright(componentName, url) {
           }
         }
       }
+      let shouldSkipTest = false;
+      for (const act of action) {
+        if (act.type === "keypress" && (act.target === "submenuTrigger" || act.target === "submenu")) {
+          const submenuSelector = componentContract.selectors[act.target];
+          if (submenuSelector) {
+            const submenuCount = await page.locator(submenuSelector).count();
+            if (submenuCount === 0) {
+              reporter.reportTest(dynamicTest, "skip", `Skipping test - ${act.target} element not found (optional submenu test)`);
+              shouldSkipTest = true;
+              break;
+            }
+          }
+        }
+      }
+      if (!shouldSkipTest) {
+        for (const assertion of assertions) {
+          if (assertion.target === "submenu" || assertion.target === "submenuTrigger") {
+            const submenuSelector = componentContract.selectors[assertion.target];
+            if (submenuSelector) {
+              const submenuCount = await page.locator(submenuSelector).count();
+              if (submenuCount === 0) {
+                reporter.reportTest(dynamicTest, "skip", `Skipping test - ${assertion.target} element not found (optional submenu test)`);
+                shouldSkipTest = true;
+                break;
+              }
+            }
+          }
+        }
+      }
+      if (shouldSkipTest) {
+        continue;
+      }
       for (const act of action) {
         if (act.type === "focus") {
           const focusSelector = componentContract.selectors[act.target];