aria-ease 6.7.0 → 6.9.0

package/README.md

@@ -31,13 +31,13 @@ Aria-Ease isn't a utility library. **It's an accessibility infrastructure** that
 
 **Traditional approach:** Build features → Manual testing → Find accessibility issues → Fix them → Manual testing again → Ship (maybe)
 
-**Aria-Ease approach:** Build with accessible utilities → Automated audits catch issues → Contract tests verify deterministic component behaviors → CI/CD gates deployment → Ship with confidence
+**Aria-Ease approach:** Build with accessible baseline utilities → Automated audits catch issues → Contract tests verify consistent baseline component behaviors → CI/CD gates deployment → Ship with confidence
 
 ### What Makes This Different?
 
 #### 1. **Component Utilities** (Available Now)
 
-Reusable accessible interaction patterns that implement WAI-ARIA APG specifications. Tree-shakable, framework-agnostic, production-ready.
+Reusable accessible interaction patterns based on Aria-Ease's baseline interpretation of WAI-ARIA APG guidance. Not the only valid implementation, but a proven, consistent place to start. Tree-shakable, framework-agnostic, production-ready.
 
 ```javascript
 // Instead of 50+ lines managing ARIA attributes and keyboard events...
@@ -60,7 +60,9 @@ npx aria-ease audit --url https://yoursite.com
 
 #### 3. **Contract Testing** (Available Now)
 
-This is the game-changer. We encoded the WAI-ARIA APG into deterministic JSON "contracts" and built a custom Playwright runner with isolated test-harness architecture. Run it locally or in CI/CD.
+This is the game-changer. We encoded a deterministic, testable baseline interpretation of WAI-ARIA APG guidance into JSON "contracts" and built a custom Playwright runner with isolated test-harness architecture. Run it locally or in CI/CD.
+
+Today, Aria-Ease maintains this baseline contract set. Down the line, contracts are being designed to be extendable and overridable so teams and experts can enforce their own standards without losing consistency.
 
 **The result?** Component interaction testing that feels closer to unit testing than manual QA.
 
@@ -70,7 +72,7 @@ npx aria-ease test
 # ✓ 26 assertions in ~1 second in CI
 ```
 
-**Why this matters:** Before, verifying a combobox meant manual keyboard testing across browsers. Now, it's automated, fast, and repeatable. You can boast about executing 26 combobox interaction assertions in ~2 seconds.
+**Why this matters:** Before, verifying a combobox meant testing every interaction manually. Now, Aria-Ease automates the repeatable baseline aspects of testing a combobox: keyboard interaction, ARIA state updates, visibility, and semantic roles.
 
 #### 4. **CI/CD Integration** (Available Now)
 
@@ -111,7 +113,7 @@ Visualize accessibility health across your entire application. Track progress, i
 - 🎯 **Tree-shakable** - Import only what you need (1.4KB - 3.7KB per component)
 - ♿ **WCAG Compliant** - Follows WAI-ARIA best practices
 - ⌨️ **Keyboard Interaction** - Full keyboard support out of the box
-- 🧪 **Contract Testing** - Built-in accessibility testing framework
+- 🧪 **Contract Testing** - Built-in baseline accessibility testing framework
 - 🎭 **Framework Agnostic** - Works with React, Vue, vanilla JS, etc.
 - 🔍 **CLI Audit Tool** - Automated accessibility testing for your sites
 - 📦 **TypeScript Support** - Full type definitions included
@@ -176,6 +178,61 @@ npx aria-ease audit
 
 The CLI will automatically find and load your config file, with validation to catch errors early.
 
+### Contract DSL Build Workflow
+
+You can author custom component contracts as readable DSL files and compile them with a built-in CLI command.
+
+1. Create one or more `*.contract.mjs` files that export a contract built with `contract("component.name", ...)`.
+2. Configure contract sources in `ariaease.config.js`.
+3. Run `npx aria-ease build contracts`.
+4. Run `npx aria-ease test`.
+
+Example config with multiple contract sources:
+
+```javascript
+export default {
+  test: {
+    strictness: "balanced",
+    components: [
+      {
+        name: "combobox.listbox",
+        path: "./tests/external-contracts/combobox.listbox.contract.json",
+        strategyPath: "./tests/external-strategies/CustomComboboxStrategy.js",
+      },
+    ],
+  },
+  contracts: [
+    {
+      src: "./tests/external-contracts/**/*.contract.mjs",
+      // optional: out: "./tests/external-contracts/generated"
+    },
+    {
+      src: "./tests/client-a/**/*.contract.mjs",
+      out: "./tests/client-a/generated",
+    },
+  ],
+};
+```
+
+Example `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "build:contracts": "npx aria-ease build contracts",
+    "test:a11y": "npx aria-ease build contracts && npx aria-ease test"
+  }
+}
+```
+
+During build, Aria-Ease validates:
+
+- contract schema shape
+- selector references in static/dynamic targets
+- relationship references (`aria-reference`, `contains`)
+
+At runtime, relationship invariants are executed and reported alongside static assertions and dynamic tests.
+
 **Perfect for CI/CD pipelines** to catch accessibility issues before production!
 
 #### 🏅 Show Your Accessibility Commitment
@@ -663,7 +720,7 @@ describe("Shopify User Menu Accessibility Test", () => {
 
 ### Strictness Modes
 
-Aria-Ease supports strictness policies to define how contract levels are enforced.
+Aria-Ease supports strictness policies to define how APG specs are enforced.
 
 - `minimal`
   - `required` -> error
@@ -717,9 +774,14 @@ export default {
 Or override per test call:
 
 ```javascript
-await testUiComponent("menu", null, "http://localhost:5173/test-harness?component=menu", {
-  strictness: "strict",
-});
+await testUiComponent(
+  "menu",
+  null,
+  "http://localhost:5173/test-harness?component=menu",
+  {
+    strictness: "strict",
+  },
+);
 ```
 
 ---
@@ -946,6 +1008,11 @@ export default {
       out: "./accessibility-reports",
     },
   },
+  contracts: [
+    {
+      src: "./tests/external-contracts/**/*.contract.mjs",
+    },
+  ],
 };
 ```
 
@@ -955,7 +1022,7 @@ Add to `package.json`:
 {
   "scripts": {
     "audit": "npx aria-ease audit -f html",
-    "test:a11y": "npx aria-ease test",
+    "test:a11y": "npx aria-ease build contracts && npx aria-ease test",
     "ci": "npm run audit && npm run test:a11y"
   }
 }

package/bin/AccordionComponentStrategy-4ZEIQ2V6.js

@@ -0,0 +1,42 @@
+import {
+  test_exports
+} from "./chunk-PK5L2SAF.js";
+import "./chunk-I2KLQ2HA.js";
+
+// src/utils/test/src/component-strategies/AccordionComponentStrategy.ts
+var AccordionComponentStrategy = class {
+  constructor(mainSelector, selectors, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
+    this.mainSelector = mainSelector;
+    this.selectors = selectors;
+    this.actionTimeoutMs = actionTimeoutMs;
+    this.assertionTimeoutMs = assertionTimeoutMs;
+  }
+  async resetState(page) {
+    if (!this.selectors.panel || !this.selectors.trigger || this.selectors.popup) {
+      return;
+    }
+    const triggerSelector = this.selectors.trigger;
+    const panelSelector = this.selectors.panel;
+    if (!triggerSelector || !panelSelector) return;
+    const allTriggers = await page.locator(triggerSelector).all();
+    for (const trigger of allTriggers) {
+      const isExpanded = await trigger.getAttribute("aria-expanded") === "true";
+      const triggerPanel = await trigger.getAttribute("aria-controls");
+      if (isExpanded && triggerPanel) {
+        await trigger.click({ timeout: this.actionTimeoutMs });
+        const panel = page.locator(`#${triggerPanel}`);
+        await (0, test_exports.expect)(panel).toBeHidden({ timeout: this.assertionTimeoutMs }).catch(() => {
+        });
+      }
+    }
+  }
+  async shouldSkipTest() {
+    return false;
+  }
+  getMainSelector() {
+    return this.mainSelector;
+  }
+};
+export {
+  AccordionComponentStrategy
+};

package/bin/ComboboxComponentStrategy-OGRVZXAF.js

@@ -0,0 +1,64 @@
+import {
+  test_exports
+} from "./chunk-PK5L2SAF.js";
+import "./chunk-I2KLQ2HA.js";
+
+// src/utils/test/src/component-strategies/ComboboxComponentStrategy.ts
+var ComboboxComponentStrategy = class {
+  constructor(mainSelector, selectors, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
+    this.mainSelector = mainSelector;
+    this.selectors = selectors;
+    this.actionTimeoutMs = actionTimeoutMs;
+    this.assertionTimeoutMs = assertionTimeoutMs;
+  }
+  async resetState(page) {
+    if (!this.selectors.popup) return;
+    const popupSelector = this.selectors.popup;
+    const popupElement = page.locator(popupSelector).first();
+    const isPopupVisible = await popupElement.isVisible().catch(() => false);
+    if (!isPopupVisible) return;
+    let listBoxClosed = false;
+    let closeSelector = this.selectors.input;
+    if (!closeSelector && this.selectors.focusable) {
+      closeSelector = this.selectors.focusable;
+    } else if (!closeSelector) {
+      closeSelector = this.selectors.button;
+    }
+    if (closeSelector) {
+      const closeElement = page.locator(closeSelector).first();
+      await closeElement.focus();
+      await page.keyboard.press("Escape");
+      listBoxClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+    }
+    if (!listBoxClosed && this.selectors.button) {
+      const buttonElement = page.locator(this.selectors.button).first();
+      await buttonElement.click({ timeout: this.actionTimeoutMs });
+      listBoxClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+    }
+    if (!listBoxClosed) {
+      await page.mouse.click(10, 10);
+      listBoxClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+    }
+    if (!listBoxClosed) {
+      throw new Error(
+        `\u274C FATAL: Cannot close combobox popup between tests. Popup remains visible after trying:
+  1. Escape key
+  2. Clicking button
+  3. Clicking outside
+This indicates a problem with the combobox component's close functionality.`
+      );
+    }
+    if (this.selectors.input) {
+      await page.locator(this.selectors.input).first().clear();
+    }
+  }
+  async shouldSkipTest() {
+    return false;
+  }
+  getMainSelector() {
+    return this.mainSelector;
+  }
+};
+export {
+  ComboboxComponentStrategy
+};

package/bin/MenuComponentStrategy-JAMTCSNF.js

@@ -0,0 +1,81 @@
+import {
+  test_exports
+} from "./chunk-PK5L2SAF.js";
+import "./chunk-I2KLQ2HA.js";
+
+// src/utils/test/src/component-strategies/MenuComponentStrategy.ts
+var MenuComponentStrategy = class {
+  constructor(mainSelector, selectors, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
+    this.mainSelector = mainSelector;
+    this.selectors = selectors;
+    this.actionTimeoutMs = actionTimeoutMs;
+    this.assertionTimeoutMs = assertionTimeoutMs;
+  }
+  async resetState(page) {
+    if (!this.selectors.popup) return;
+    const popupSelector = this.selectors.popup;
+    const popupElement = page.locator(popupSelector).first();
+    const isPopupVisible = await popupElement.isVisible().catch(() => false);
+    if (!isPopupVisible) return;
+    let menuClosed = false;
+    let closeSelector = this.selectors.input;
+    if (!closeSelector && this.selectors.focusable) {
+      closeSelector = this.selectors.focusable;
+    } else if (!closeSelector) {
+      closeSelector = this.selectors.trigger;
+    }
+    if (closeSelector) {
+      const closeElement = page.locator(closeSelector).first();
+      await closeElement.focus();
+      await page.keyboard.press("Escape");
+      menuClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+    }
+    if (!menuClosed && this.selectors.trigger) {
+      const triggerElement = page.locator(this.selectors.trigger).first();
+      await triggerElement.click({ timeout: this.actionTimeoutMs });
+      menuClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+    }
+    if (!menuClosed) {
+      await page.mouse.click(10, 10);
+      menuClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+    }
+    if (!menuClosed) {
+      throw new Error(
+        `\u274C FATAL: Cannot close menu between tests. Menu remains visible after trying:
+  1. Escape key
+  2. Clicking trigger
+  3. Clicking outside
+This indicates a problem with the menu component's close functionality.`
+      );
+    }
+    if (this.selectors.input) {
+      await page.locator(this.selectors.input).first().clear();
+    }
+    if (this.selectors.trigger) {
+      const triggerElement = page.locator(this.selectors.trigger).first();
+      await triggerElement.focus();
+    }
+  }
+  async shouldSkipTest(test, page) {
+    const requiresSubmenu = test.action.some(
+      (act) => act.target === "submenu" || act.target === "submenuTrigger" || act.target === "submenuItems"
+    ) || test.assertions.some(
+      (assertion) => assertion.target === "submenu" || assertion.target === "submenuTrigger" || assertion.target === "submenuItems"
+    );
+    if (!requiresSubmenu) {
+      return false;
+    }
+    const submenuTriggerSelector = this.selectors.submenuTrigger;
+    if (!submenuTriggerSelector) {
+      return true;
+    }
+    const submenuTriggerCount = await page.locator(submenuTriggerSelector).count();
+    return submenuTriggerCount === 0;
+  }
+  getMainSelector() {
+    return this.mainSelector;
+  }
+};
+export {
+  MenuComponentStrategy
+};

package/bin/TabsComponentStrategy-3SQURPMX.js

@@ -0,0 +1,29 @@
+import "./chunk-I2KLQ2HA.js";
+
+// src/utils/test/src/component-strategies/TabsComponentStrategy.ts
+var TabsComponentStrategy = class {
+  constructor(mainSelector, selectors) {
+    this.mainSelector = mainSelector;
+    this.selectors = selectors;
+  }
+  async resetState() {
+  }
+  async shouldSkipTest(test, page) {
+    if (test.isVertical !== void 0 && this.selectors.tablist) {
+      const tablistSelector = this.selectors.tablist;
+      const tablist = page.locator(tablistSelector).first();
+      const orientation = await tablist.getAttribute("aria-orientation");
+      const isVertical = orientation === "vertical";
+      if (test.isVertical !== isVertical) {
+        return true;
+      }
+    }
+    return false;
+  }
+  getMainSelector() {
+    return this.mainSelector;
+  }
+};
+export {
+  TabsComponentStrategy
+};