aria-ease 6.9.0 → 6.9.1

package/dist/index.cjs

@@ -487,14 +487,14 @@ function validateConfig(config) {
     if (!Array.isArray(cfg.contracts)) {
       errors.push("contracts must be an array");
     } else {
-      cfg.contracts.forEach((contract2, idx) => {
-        if (typeof contract2 !== "object" || contract2 === null) {
+      cfg.contracts.forEach((contract, idx) => {
+        if (typeof contract !== "object" || contract === null) {
           errors.push(`contracts[${idx}] must be an object`);
         } else {
-          if (typeof contract2.src !== "string") {
+          if (typeof contract.src !== "string") {
             errors.push(`contracts[${idx}].src is required and must be a string`);
           }
-          if (contract2.out !== void 0 && typeof contract2.out !== "string") {
+          if (contract.out !== void 0 && typeof contract.out !== "string") {
             errors.push(`contracts[${idx}].out must be a string`);
           }
         }
@@ -2060,7 +2060,7 @@ var init_badgeHelper = __esm({
 var index_exports = {};
 __export(index_exports, {
   cleanupTests: () => cleanupTests,
-  contract: () => contract,
+  createContract: () => createContract,
   makeAccordionAccessible: () => makeAccordionAccessible,
   makeBlockAccessible: () => makeBlockAccessible,
   makeCheckboxAccessible: () => makeCheckboxAccessible,
@@ -3870,7 +3870,7 @@ var ContractBuilder = class {
     };
   }
 };
-function contract(componentName, define) {
+function createContract(componentName, define) {
   const builder = new ContractBuilder(componentName);
   define(builder);
   return new FluentContract(builder.build());
@@ -4112,14 +4112,14 @@ Error: ${error instanceof Error ? error.message : String(error)}`
       }
     }
   }
-  let contract2;
+  let contract;
   try {
     if (url) {
       const devServerUrl = await checkDevServer(url);
       if (devServerUrl) {
         console.log(`\u{1F3AD} Running Playwright tests on ${devServerUrl}`);
         const { runContractTestsPlaywright: runContractTestsPlaywright2 } = await Promise.resolve().then(() => (init_contractTestRunnerPlaywright(), contractTestRunnerPlaywright_exports));
-        contract2 = await runContractTestsPlaywright2(componentName, devServerUrl, strictness, config, configBaseDir);
+        contract = await runContractTestsPlaywright2(componentName, devServerUrl, strictness, config, configBaseDir);
       } else {
         throw new Error(
           `\u274C Dev server not running at ${url}
@@ -4128,7 +4128,7 @@ Please start your dev server and try again.`
       }
     } else if (component) {
       console.log(`\u{1F3AD} Running component contract tests in JSDOM mode`);
-      contract2 = await runContractTests(componentName, component, strictness);
+      contract = await runContractTests(componentName, component, strictness);
     } else {
       throw new Error("\u274C Either component or URL must be provided");
     }
@@ -4141,13 +4141,13 @@ Please start your dev server and try again.`
   const result = {
     violations: results.violations,
     raw: results,
-    contract: contract2
+    contract
   };
-  if (contract2.failures.length > 0 && url === "Playwright") {
+  if (contract.failures.length > 0 && url === "Playwright") {
     throw new Error(
       `
-\u274C ${contract2.failures.length} accessibility contract test${contract2.failures.length > 1 ? "s" : ""} failed (Playwright mode)
-\u2705 ${contract2.passes.length} test${contract2.passes.length > 1 ? "s" : ""} passed
+\u274C ${contract.failures.length} accessibility contract test${contract.failures.length > 1 ? "s" : ""} failed (Playwright mode)
+\u2705 ${contract.passes.length} test${contract.passes.length > 1 ? "s" : ""} passed
 
 \u{1F4CB} Review the detailed test report above for specific failures.
 \u{1F4A1} Contract tests validate ARIA attributes and keyboard interactions per W3C APG guidelines.`
@@ -4223,7 +4223,7 @@ async function cleanupTests() {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   cleanupTests,
-  contract,
+  createContract,
   makeAccordionAccessible,
   makeBlockAccessible,
   makeCheckboxAccessible,

package/dist/index.d.cts

@@ -327,7 +327,7 @@ declare class ContractBuilder {
     private validateDynamicTargets;
     build(): JsonContract;
 }
-declare function contract(componentName: string, define: (c: ContractBuilder) => void): FluentContract;
+declare function createContract(componentName: string, define: (c: ContractBuilder) => void): FluentContract;
 
 type StrictnessMode = 'minimal' | 'balanced' | 'strict' | 'paranoid';
 
@@ -348,4 +348,4 @@ declare function testUiComponent(componentName: string, component: HTMLElement |
  */
 declare function cleanupTests(): Promise<void>;
 
-export { ContractBuilder, type JsonContract, type RelationshipInvariant, cleanupTests, contract, makeAccordionAccessible, makeBlockAccessible, makeCheckboxAccessible, makeComboboxAccessible, makeMenuAccessible, makeRadioAccessible, makeTabsAccessible, makeToggleAccessible, testUiComponent };
+export { ContractBuilder, type JsonContract, type RelationshipInvariant, cleanupTests, createContract, makeAccordionAccessible, makeBlockAccessible, makeCheckboxAccessible, makeComboboxAccessible, makeMenuAccessible, makeRadioAccessible, makeTabsAccessible, makeToggleAccessible, testUiComponent };

package/dist/index.d.ts

@@ -327,7 +327,7 @@ declare class ContractBuilder {
     private validateDynamicTargets;
     build(): JsonContract;
 }
-declare function contract(componentName: string, define: (c: ContractBuilder) => void): FluentContract;
+declare function createContract(componentName: string, define: (c: ContractBuilder) => void): FluentContract;
 
 type StrictnessMode = 'minimal' | 'balanced' | 'strict' | 'paranoid';
 
@@ -348,4 +348,4 @@ declare function testUiComponent(componentName: string, component: HTMLElement |
  */
 declare function cleanupTests(): Promise<void>;
 
-export { ContractBuilder, type JsonContract, type RelationshipInvariant, cleanupTests, contract, makeAccordionAccessible, makeBlockAccessible, makeCheckboxAccessible, makeComboboxAccessible, makeMenuAccessible, makeRadioAccessible, makeTabsAccessible, makeToggleAccessible, testUiComponent };
+export { ContractBuilder, type JsonContract, type RelationshipInvariant, cleanupTests, createContract, makeAccordionAccessible, makeBlockAccessible, makeCheckboxAccessible, makeComboboxAccessible, makeMenuAccessible, makeRadioAccessible, makeTabsAccessible, makeToggleAccessible, testUiComponent };

package/dist/index.js

@@ -1805,7 +1805,7 @@ var ContractBuilder = class {
     };
   }
 };
-function contract(componentName, define) {
+function createContract(componentName, define) {
   const builder = new ContractBuilder(componentName);
   define(builder);
   return new FluentContract(builder.build());
@@ -2041,14 +2041,14 @@ Error: ${error instanceof Error ? error.message : String(error)}`
       }
     }
   }
-  let contract2;
+  let contract;
   try {
     if (url) {
       const devServerUrl = await checkDevServer(url);
       if (devServerUrl) {
         console.log(`\u{1F3AD} Running Playwright tests on ${devServerUrl}`);
         const { runContractTestsPlaywright } = await import("./contractTestRunnerPlaywright-XBWJZMR3.js");
-        contract2 = await runContractTestsPlaywright(componentName, devServerUrl, strictness, config, configBaseDir);
+        contract = await runContractTestsPlaywright(componentName, devServerUrl, strictness, config, configBaseDir);
       } else {
         throw new Error(
           `\u274C Dev server not running at ${url}
@@ -2057,7 +2057,7 @@ Please start your dev server and try again.`
       }
     } else if (component) {
       console.log(`\u{1F3AD} Running component contract tests in JSDOM mode`);
-      contract2 = await runContractTests(componentName, component, strictness);
+      contract = await runContractTests(componentName, component, strictness);
     } else {
       throw new Error("\u274C Either component or URL must be provided");
     }
@@ -2070,13 +2070,13 @@ Please start your dev server and try again.`
   const result = {
     violations: results.violations,
     raw: results,
-    contract: contract2
+    contract
   };
-  if (contract2.failures.length > 0 && url === "Playwright") {
+  if (contract.failures.length > 0 && url === "Playwright") {
     throw new Error(
       `
-\u274C ${contract2.failures.length} accessibility contract test${contract2.failures.length > 1 ? "s" : ""} failed (Playwright mode)
-\u2705 ${contract2.passes.length} test${contract2.passes.length > 1 ? "s" : ""} passed
+\u274C ${contract.failures.length} accessibility contract test${contract.failures.length > 1 ? "s" : ""} failed (Playwright mode)
+\u2705 ${contract.passes.length} test${contract.passes.length > 1 ? "s" : ""} passed
 
 \u{1F4CB} Review the detailed test report above for specific failures.
 \u{1F4A1} Contract tests validate ARIA attributes and keyboard interactions per W3C APG guidelines.`
@@ -2151,7 +2151,7 @@ async function cleanupTests() {
 }
 export {
   cleanupTests,
-  contract,
+  createContract,
   makeAccordionAccessible,
   makeBlockAccessible,
   makeCheckboxAccessible,

package/dist/src/utils/test/dsl/index.cjs

@@ -0,0 +1,320 @@
+'use strict';
+
+// src/utils/test/dsl/index.ts
+var FluentContract = class {
+  constructor(jsonContract) {
+    this.jsonContract = jsonContract;
+  }
+  toJSON() {
+    return this.jsonContract;
+  }
+};
+var StaticTargetBuilder = class {
+  constructor(targetName, sink) {
+    this.targetName = targetName;
+    this.sink = sink;
+  }
+  has(attribute, expectedValue) {
+    const create = (level) => {
+      this.sink.push({
+        target: this.targetName,
+        attribute,
+        expectedValue,
+        failureMessage: `Expected ${this.targetName} to have ${attribute}${expectedValue !== void 0 ? `=${expectedValue}` : ""}.`,
+        level
+      });
+    };
+    return {
+      required: () => create("required"),
+      recommended: () => create("recommended"),
+      optional: () => create("optional")
+    };
+  }
+};
+var StaticBuilder = class {
+  constructor(sink) {
+    this.sink = sink;
+  }
+  target(targetName) {
+    return new StaticTargetBuilder(targetName, this.sink);
+  }
+};
+var DynamicChain = class {
+  constructor(key, testsSink, selectors) {
+    this.key = key;
+    this.testsSink = testsSink;
+    this.selectors = selectors;
+  }
+  selectorTarget = "";
+  actions = [];
+  assertions = [];
+  explicitDescription = "";
+  on(target) {
+    this.selectorTarget = target;
+    this.actions.push({ type: "keypress", target, key: this.key });
+    return this;
+  }
+  describe(description) {
+    this.explicitDescription = description;
+    return this;
+  }
+  focus(targetExpression) {
+    const parsed = this.parseRelativeExpression(targetExpression);
+    if (parsed) {
+      if (!this.selectors[parsed.selectorKey]) {
+        const availableSelectors = Object.keys(this.selectors).sort().join(", ") || "(none)";
+        throw new Error(
+          `Invalid focus target expression "${targetExpression}": selector "${parsed.selectorKey}" is not defined. Available selectors: ${availableSelectors}`
+        );
+      }
+      if (!this.selectors.relative && this.selectors[parsed.selectorKey]) {
+        this.selectors.relative = this.selectors[parsed.selectorKey];
+      }
+      this.assertions.push({
+        target: "relative",
+        assertion: "toHaveFocus",
+        relativeTarget: parsed.relativeTarget
+      });
+    } else {
+      this.assertions.push({
+        target: targetExpression,
+        assertion: "toHaveFocus"
+      });
+    }
+    return this;
+  }
+  visible(target) {
+    this.assertions.push({ target, assertion: "toBeVisible" });
+    return this;
+  }
+  hidden(target) {
+    this.assertions.push({ target, assertion: "notToBeVisible" });
+    return this;
+  }
+  has(target, attribute, expectedValue) {
+    this.assertions.push({
+      target,
+      assertion: "toHaveAttribute",
+      attribute,
+      expectedValue
+    });
+    return this;
+  }
+  required() {
+    this.finalize("required");
+  }
+  recommended() {
+    this.finalize("recommended");
+  }
+  optional() {
+    this.finalize("optional");
+  }
+  finalize(level) {
+    if (!this.selectorTarget) {
+      throw new Error("Dynamic contract chain requires .on(<selectorKey>) before level terminator.");
+    }
+    const description = this.explicitDescription || `Pressing ${this.key} on ${this.selectorTarget} satisfies expected behavior.`;
+    this.testsSink.push({
+      description,
+      level,
+      action: this.actions,
+      assertions: this.assertions.map((a) => ({ ...a, level }))
+    });
+  }
+  parseRelativeExpression(input) {
+    const match = input.match(/^(next|previous|first|last)\(([^)]+)\)$/);
+    if (!match) return null;
+    const relativeTarget = match[1];
+    const selectorKey = match[2].trim();
+    return { relativeTarget, selectorKey };
+  }
+};
+var ContractBuilder = class {
+  constructor(componentName) {
+    this.componentName = componentName;
+  }
+  metaValue = {};
+  selectorsValue = {};
+  relationshipInvariants = [];
+  staticAssertions = [];
+  dynamicTests = [];
+  meta(meta) {
+    this.metaValue = { ...this.metaValue, ...meta };
+    return this;
+  }
+  selectors(selectors) {
+    this.selectorsValue = { ...this.selectorsValue, ...selectors };
+    return this;
+  }
+  relationship(invariant) {
+    this.relationshipInvariants.push(invariant);
+    return this;
+  }
+  relationships(builderFn) {
+    builderFn({
+      ariaReference: (from, attribute, to) => {
+        const create = (level) => {
+          this.relationshipInvariants.push({
+            type: "aria-reference",
+            from,
+            attribute,
+            to,
+            level
+          });
+        };
+        return {
+          required: () => create("required"),
+          recommended: () => create("recommended"),
+          optional: () => create("optional")
+        };
+      },
+      contains: (parent, child) => {
+        const create = (level) => {
+          this.relationshipInvariants.push({
+            type: "contains",
+            parent,
+            child,
+            level
+          });
+        };
+        return {
+          required: () => create("required"),
+          recommended: () => create("recommended"),
+          optional: () => create("optional")
+        };
+      }
+    });
+    return this;
+  }
+  static(builderFn) {
+    builderFn(new StaticBuilder(this.staticAssertions));
+    return this;
+  }
+  when(key) {
+    return new DynamicChain(key, this.dynamicTests, this.selectorsValue);
+  }
+  validateRelationshipInvariants() {
+    if (this.relationshipInvariants.length === 0) {
+      return;
+    }
+    const selectorKeys = new Set(Object.keys(this.selectorsValue));
+    const available = Object.keys(this.selectorsValue).sort().join(", ");
+    const errors = [];
+    this.relationshipInvariants.forEach((invariant, index) => {
+      const prefix = `relationships[${index}] (${invariant.type})`;
+      if (invariant.type === "aria-reference") {
+        if (!selectorKeys.has(invariant.from)) {
+          errors.push(`${prefix}: "from" references unknown selector "${invariant.from}"`);
+        }
+        if (!selectorKeys.has(invariant.to)) {
+          errors.push(`${prefix}: "to" references unknown selector "${invariant.to}"`);
+        }
+      }
+      if (invariant.type === "contains") {
+        if (!selectorKeys.has(invariant.parent)) {
+          errors.push(`${prefix}: "parent" references unknown selector "${invariant.parent}"`);
+        }
+        if (!selectorKeys.has(invariant.child)) {
+          errors.push(`${prefix}: "child" references unknown selector "${invariant.child}"`);
+        }
+      }
+    });
+    if (errors.length > 0) {
+      const availableSelectorsMessage = available.length > 0 ? available : "(none)";
+      throw new Error(
+        [
+          `Contract invariant validation failed for component "${this.componentName}".`,
+          ...errors.map((error) => `- ${error}`),
+          `Available selectors: ${availableSelectorsMessage}`
+        ].join("\n")
+      );
+    }
+  }
+  validateStaticTargets() {
+    const selectorKeys = new Set(Object.keys(this.selectorsValue));
+    const available = Object.keys(this.selectorsValue).sort().join(", ") || "(none)";
+    const errors = [];
+    this.staticAssertions.forEach((assertion, index) => {
+      if (!selectorKeys.has(assertion.target)) {
+        errors.push(`static.assertions[${index}]: target "${assertion.target}" is not defined in selectors`);
+      }
+    });
+    if (errors.length > 0) {
+      throw new Error(
+        [
+          `Contract static target validation failed for component "${this.componentName}".`,
+          ...errors.map((error) => `- ${error}`),
+          `Available selectors: ${available}`
+        ].join("\n")
+      );
+    }
+  }
+  validateDynamicTargets() {
+    const selectorKeys = new Set(Object.keys(this.selectorsValue));
+    const available = Object.keys(this.selectorsValue).sort().join(", ") || "(none)";
+    const errors = [];
+    const isValidActionTarget = (target) => {
+      return selectorKeys.has(target) || target === "document" || target === "relative";
+    };
+    const isValidAssertionTarget = (target) => {
+      return selectorKeys.has(target) || target === "relative";
+    };
+    this.dynamicTests.forEach((test, testIndex) => {
+      test.action.forEach((action, actionIndex) => {
+        if (!isValidActionTarget(action.target)) {
+          errors.push(
+            `dynamic[${testIndex}].action[${actionIndex}]: target "${action.target}" is not defined in selectors`
+          );
+        }
+      });
+      test.assertions.forEach((assertion, assertionIndex) => {
+        if (!isValidAssertionTarget(assertion.target)) {
+          errors.push(
+            `dynamic[${testIndex}].assertions[${assertionIndex}]: target "${assertion.target}" is not defined in selectors`
+          );
+        }
+        if (assertion.target === "relative" && !this.selectorsValue.relative) {
+          errors.push(
+            `dynamic[${testIndex}].assertions[${assertionIndex}]: target "relative" requires selectors.relative to be defined`
+          );
+        }
+      });
+    });
+    if (errors.length > 0) {
+      throw new Error(
+        [
+          `Contract dynamic target validation failed for component "${this.componentName}".`,
+          ...errors.map((error) => `- ${error}`),
+          `Available selectors: ${available}`,
+          `Allowed special targets: document, relative`
+        ].join("\n")
+      );
+    }
+  }
+  build() {
+    this.validateRelationshipInvariants();
+    this.validateStaticTargets();
+    this.validateDynamicTargets();
+    const fallbackId = this.metaValue.id || `aria-ease.contract.${this.componentName}`;
+    return {
+      meta: {
+        id: fallbackId,
+        version: this.metaValue.version || "1.0.0",
+        description: this.metaValue.description || `Fluent contract for ${this.componentName}`,
+        source: this.metaValue.source,
+        W3CName: this.metaValue.W3CName
+      },
+      selectors: this.selectorsValue,
+      relationships: this.relationshipInvariants,
+      static: [{ assertions: this.staticAssertions }],
+      dynamic: this.dynamicTests
+    };
+  }
+};
+function createContract(componentName, define) {
+  const builder = new ContractBuilder(componentName);
+  define(builder);
+  return new FluentContract(builder.build());
+}
+
+exports.createContract = createContract;

package/dist/src/utils/test/dsl/index.d.cts

@@ -0,0 +1,136 @@
+type Level = "required" | "recommended" | "optional";
+type ContractMeta = {
+    id?: string;
+    version?: string;
+    description?: string;
+    source?: {
+        apg?: string;
+        wcag?: string[];
+    };
+    W3CName?: string;
+};
+type SelectorsMap = Record<string, string>;
+type RelationshipInvariant = {
+    type: "aria-reference";
+    from: string;
+    attribute: string;
+    to: string;
+    level?: Level;
+} | {
+    type: "contains";
+    parent: string;
+    child: string;
+    level?: Level;
+};
+type StaticAssertion = {
+    target: string;
+    attribute: string;
+    expectedValue?: string;
+    failureMessage: string;
+    level: Level;
+};
+type DynamicAction = {
+    type: "focus" | "type" | "click" | "keypress" | "hover";
+    target: string;
+    key?: string;
+    value?: string;
+    relativeTarget?: string;
+};
+type DynamicAssertion = {
+    target: string;
+    assertion: "toBeVisible" | "notToBeVisible" | "toHaveAttribute" | "toHaveValue" | "toHaveFocus" | "toHaveRole";
+    attribute?: string;
+    expectedValue?: string;
+    failureMessage?: string;
+    relativeTarget?: string;
+    level?: Level;
+};
+type DynamicTest = {
+    description: string;
+    level?: Level;
+    action: DynamicAction[];
+    assertions: DynamicAssertion[];
+};
+type JsonContract = {
+    meta?: ContractMeta;
+    selectors: SelectorsMap;
+    relationships?: RelationshipInvariant[];
+    static: Array<{
+        assertions: StaticAssertion[];
+    }>;
+    dynamic: DynamicTest[];
+};
+declare class FluentContract {
+    private readonly jsonContract;
+    constructor(jsonContract: JsonContract);
+    toJSON(): JsonContract;
+}
+declare class StaticTargetBuilder {
+    private readonly targetName;
+    private readonly sink;
+    constructor(targetName: string, sink: StaticAssertion[]);
+    has(attribute: string, expectedValue?: string): {
+        required: () => void;
+        recommended: () => void;
+        optional: () => void;
+    };
+}
+declare class StaticBuilder {
+    private readonly sink;
+    constructor(sink: StaticAssertion[]);
+    target(targetName: string): StaticTargetBuilder;
+}
+declare class DynamicChain {
+    private readonly key;
+    private readonly testsSink;
+    private readonly selectors;
+    private selectorTarget;
+    private readonly actions;
+    private readonly assertions;
+    private explicitDescription;
+    constructor(key: string, testsSink: DynamicTest[], selectors: SelectorsMap);
+    on(target: string): this;
+    describe(description: string): this;
+    focus(targetExpression: string): this;
+    visible(target: string): this;
+    hidden(target: string): this;
+    has(target: string, attribute: string, expectedValue?: string): this;
+    required(): void;
+    recommended(): void;
+    optional(): void;
+    private finalize;
+    private parseRelativeExpression;
+}
+declare class ContractBuilder {
+    private readonly componentName;
+    private metaValue;
+    private selectorsValue;
+    private readonly relationshipInvariants;
+    private readonly staticAssertions;
+    private readonly dynamicTests;
+    constructor(componentName: string);
+    meta(meta: ContractMeta): this;
+    selectors(selectors: SelectorsMap): this;
+    relationship(invariant: RelationshipInvariant): this;
+    relationships(builderFn: (r: {
+        ariaReference: (from: string, attribute: string, to: string) => {
+            required: () => void;
+            recommended: () => void;
+            optional: () => void;
+        };
+        contains: (parent: string, child: string) => {
+            required: () => void;
+            recommended: () => void;
+            optional: () => void;
+        };
+    }) => void): this;
+    static(builderFn: (s: StaticBuilder) => void): this;
+    when(key: string): DynamicChain;
+    private validateRelationshipInvariants;
+    private validateStaticTargets;
+    private validateDynamicTargets;
+    build(): JsonContract;
+}
+declare function createContract(componentName: string, define: (c: ContractBuilder) => void): FluentContract;
+
+export { ContractBuilder, type JsonContract, type RelationshipInvariant, createContract };

package/dist/src/utils/test/dsl/index.d.ts

@@ -0,0 +1,136 @@
+type Level = "required" | "recommended" | "optional";
+type ContractMeta = {
+    id?: string;
+    version?: string;
+    description?: string;
+    source?: {
+        apg?: string;
+        wcag?: string[];
+    };
+    W3CName?: string;
+};
+type SelectorsMap = Record<string, string>;
+type RelationshipInvariant = {
+    type: "aria-reference";
+    from: string;
+    attribute: string;
+    to: string;
+    level?: Level;
+} | {
+    type: "contains";
+    parent: string;
+    child: string;
+    level?: Level;
+};
+type StaticAssertion = {
+    target: string;
+    attribute: string;
+    expectedValue?: string;
+    failureMessage: string;
+    level: Level;
+};
+type DynamicAction = {
+    type: "focus" | "type" | "click" | "keypress" | "hover";
+    target: string;
+    key?: string;
+    value?: string;
+    relativeTarget?: string;
+};
+type DynamicAssertion = {
+    target: string;
+    assertion: "toBeVisible" | "notToBeVisible" | "toHaveAttribute" | "toHaveValue" | "toHaveFocus" | "toHaveRole";
+    attribute?: string;
+    expectedValue?: string;
+    failureMessage?: string;
+    relativeTarget?: string;
+    level?: Level;
+};
+type DynamicTest = {
+    description: string;
+    level?: Level;
+    action: DynamicAction[];
+    assertions: DynamicAssertion[];
+};
+type JsonContract = {
+    meta?: ContractMeta;
+    selectors: SelectorsMap;
+    relationships?: RelationshipInvariant[];
+    static: Array<{
+        assertions: StaticAssertion[];
+    }>;
+    dynamic: DynamicTest[];
+};
+declare class FluentContract {
+    private readonly jsonContract;
+    constructor(jsonContract: JsonContract);
+    toJSON(): JsonContract;
+}
+declare class StaticTargetBuilder {
+    private readonly targetName;
+    private readonly sink;
+    constructor(targetName: string, sink: StaticAssertion[]);
+    has(attribute: string, expectedValue?: string): {
+        required: () => void;
+        recommended: () => void;
+        optional: () => void;
+    };
+}
+declare class StaticBuilder {
+    private readonly sink;
+    constructor(sink: StaticAssertion[]);
+    target(targetName: string): StaticTargetBuilder;
+}
+declare class DynamicChain {
+    private readonly key;
+    private readonly testsSink;
+    private readonly selectors;
+    private selectorTarget;
+    private readonly actions;
+    private readonly assertions;
+    private explicitDescription;
+    constructor(key: string, testsSink: DynamicTest[], selectors: SelectorsMap);
+    on(target: string): this;
+    describe(description: string): this;
+    focus(targetExpression: string): this;
+    visible(target: string): this;
+    hidden(target: string): this;
+    has(target: string, attribute: string, expectedValue?: string): this;
+    required(): void;
+    recommended(): void;
+    optional(): void;
+    private finalize;
+    private parseRelativeExpression;
+}
+declare class ContractBuilder {
+    private readonly componentName;
+    private metaValue;
+    private selectorsValue;
+    private readonly relationshipInvariants;
+    private readonly staticAssertions;
+    private readonly dynamicTests;
+    constructor(componentName: string);
+    meta(meta: ContractMeta): this;
+    selectors(selectors: SelectorsMap): this;
+    relationship(invariant: RelationshipInvariant): this;
+    relationships(builderFn: (r: {
+        ariaReference: (from: string, attribute: string, to: string) => {
+            required: () => void;
+            recommended: () => void;
+            optional: () => void;
+        };
+        contains: (parent: string, child: string) => {
+            required: () => void;
+            recommended: () => void;
+            optional: () => void;
+        };
+    }) => void): this;
+    static(builderFn: (s: StaticBuilder) => void): this;
+    when(key: string): DynamicChain;
+    private validateRelationshipInvariants;
+    private validateStaticTargets;
+    private validateDynamicTargets;
+    build(): JsonContract;
+}
+declare function createContract(componentName: string, define: (c: ContractBuilder) => void): FluentContract;
+
+export { ContractBuilder, type JsonContract, type RelationshipInvariant, createContract };

package/dist/src/utils/test/dsl/index.js

@@ -0,0 +1,318 @@
+// src/utils/test/dsl/index.ts
+var FluentContract = class {
+  constructor(jsonContract) {
+    this.jsonContract = jsonContract;
+  }
+  toJSON() {
+    return this.jsonContract;
+  }
+};
+var StaticTargetBuilder = class {
+  constructor(targetName, sink) {
+    this.targetName = targetName;
+    this.sink = sink;
+  }
+  has(attribute, expectedValue) {
+    const create = (level) => {
+      this.sink.push({
+        target: this.targetName,
+        attribute,
+        expectedValue,
+        failureMessage: `Expected ${this.targetName} to have ${attribute}${expectedValue !== void 0 ? `=${expectedValue}` : ""}.`,
+        level
+      });
+    };
+    return {
+      required: () => create("required"),
+      recommended: () => create("recommended"),
+      optional: () => create("optional")
+    };
+  }
+};
+var StaticBuilder = class {
+  constructor(sink) {
+    this.sink = sink;
+  }
+  target(targetName) {
+    return new StaticTargetBuilder(targetName, this.sink);
+  }
+};
+var DynamicChain = class {
+  constructor(key, testsSink, selectors) {
+    this.key = key;
+    this.testsSink = testsSink;
+    this.selectors = selectors;
+  }
+  selectorTarget = "";
+  actions = [];
+  assertions = [];
+  explicitDescription = "";
+  on(target) {
+    this.selectorTarget = target;
+    this.actions.push({ type: "keypress", target, key: this.key });
+    return this;
+  }
+  describe(description) {
+    this.explicitDescription = description;
+    return this;
+  }
+  focus(targetExpression) {
+    const parsed = this.parseRelativeExpression(targetExpression);
+    if (parsed) {
+      if (!this.selectors[parsed.selectorKey]) {
+        const availableSelectors = Object.keys(this.selectors).sort().join(", ") || "(none)";
+        throw new Error(
+          `Invalid focus target expression "${targetExpression}": selector "${parsed.selectorKey}" is not defined. Available selectors: ${availableSelectors}`
+        );
+      }
+      if (!this.selectors.relative && this.selectors[parsed.selectorKey]) {
+        this.selectors.relative = this.selectors[parsed.selectorKey];
+      }
+      this.assertions.push({
+        target: "relative",
+        assertion: "toHaveFocus",
+        relativeTarget: parsed.relativeTarget
+      });
+    } else {
+      this.assertions.push({
+        target: targetExpression,
+        assertion: "toHaveFocus"
+      });
+    }
+    return this;
+  }
+  visible(target) {
+    this.assertions.push({ target, assertion: "toBeVisible" });
+    return this;
+  }
+  hidden(target) {
+    this.assertions.push({ target, assertion: "notToBeVisible" });
+    return this;
+  }
+  has(target, attribute, expectedValue) {
+    this.assertions.push({
+      target,
+      assertion: "toHaveAttribute",
+      attribute,
+      expectedValue
+    });
+    return this;
+  }
+  required() {
+    this.finalize("required");
+  }
+  recommended() {
+    this.finalize("recommended");
+  }
+  optional() {
+    this.finalize("optional");
+  }
+  finalize(level) {
+    if (!this.selectorTarget) {
+      throw new Error("Dynamic contract chain requires .on(<selectorKey>) before level terminator.");
+    }
+    const description = this.explicitDescription || `Pressing ${this.key} on ${this.selectorTarget} satisfies expected behavior.`;
+    this.testsSink.push({
+      description,
+      level,
+      action: this.actions,
+      assertions: this.assertions.map((a) => ({ ...a, level }))
+    });
+  }
+  parseRelativeExpression(input) {
+    const match = input.match(/^(next|previous|first|last)\(([^)]+)\)$/);
+    if (!match) return null;
+    const relativeTarget = match[1];
+    const selectorKey = match[2].trim();
+    return { relativeTarget, selectorKey };
+  }
+};
+var ContractBuilder = class {
+  constructor(componentName) {
+    this.componentName = componentName;
+  }
+  metaValue = {};
+  selectorsValue = {};
+  relationshipInvariants = [];
+  staticAssertions = [];
+  dynamicTests = [];
+  meta(meta) {
+    this.metaValue = { ...this.metaValue, ...meta };
+    return this;
+  }
+  selectors(selectors) {
+    this.selectorsValue = { ...this.selectorsValue, ...selectors };
+    return this;
+  }
+  relationship(invariant) {
+    this.relationshipInvariants.push(invariant);
+    return this;
+  }
+  relationships(builderFn) {
+    builderFn({
+      ariaReference: (from, attribute, to) => {
+        const create = (level) => {
+          this.relationshipInvariants.push({
+            type: "aria-reference",
+            from,
+            attribute,
+            to,
+            level
+          });
+        };
+        return {
+          required: () => create("required"),
+          recommended: () => create("recommended"),
+          optional: () => create("optional")
+        };
+      },
+      contains: (parent, child) => {
+        const create = (level) => {
+          this.relationshipInvariants.push({
+            type: "contains",
+            parent,
+            child,
+            level
+          });
+        };
+        return {
+          required: () => create("required"),
+          recommended: () => create("recommended"),
+          optional: () => create("optional")
+        };
+      }
+    });
+    return this;
+  }
+  static(builderFn) {
+    builderFn(new StaticBuilder(this.staticAssertions));
+    return this;
+  }
+  when(key) {
+    return new DynamicChain(key, this.dynamicTests, this.selectorsValue);
+  }
+  validateRelationshipInvariants() {
+    if (this.relationshipInvariants.length === 0) {
+      return;
+    }
+    const selectorKeys = new Set(Object.keys(this.selectorsValue));
+    const available = Object.keys(this.selectorsValue).sort().join(", ");
+    const errors = [];
+    this.relationshipInvariants.forEach((invariant, index) => {
+      const prefix = `relationships[${index}] (${invariant.type})`;
+      if (invariant.type === "aria-reference") {
+        if (!selectorKeys.has(invariant.from)) {
+          errors.push(`${prefix}: "from" references unknown selector "${invariant.from}"`);
+        }
+        if (!selectorKeys.has(invariant.to)) {
+          errors.push(`${prefix}: "to" references unknown selector "${invariant.to}"`);
+        }
+      }
+      if (invariant.type === "contains") {
+        if (!selectorKeys.has(invariant.parent)) {
+          errors.push(`${prefix}: "parent" references unknown selector "${invariant.parent}"`);
+        }
+        if (!selectorKeys.has(invariant.child)) {
+          errors.push(`${prefix}: "child" references unknown selector "${invariant.child}"`);
+        }
+      }
+    });
+    if (errors.length > 0) {
+      const availableSelectorsMessage = available.length > 0 ? available : "(none)";
+      throw new Error(
+        [
+          `Contract invariant validation failed for component "${this.componentName}".`,
+          ...errors.map((error) => `- ${error}`),
+          `Available selectors: ${availableSelectorsMessage}`
+        ].join("\n")
+      );
+    }
+  }
+  validateStaticTargets() {
+    const selectorKeys = new Set(Object.keys(this.selectorsValue));
+    const available = Object.keys(this.selectorsValue).sort().join(", ") || "(none)";
+    const errors = [];
+    this.staticAssertions.forEach((assertion, index) => {
+      if (!selectorKeys.has(assertion.target)) {
+        errors.push(`static.assertions[${index}]: target "${assertion.target}" is not defined in selectors`);
+      }
+    });
+    if (errors.length > 0) {
+      throw new Error(
+        [
+          `Contract static target validation failed for component "${this.componentName}".`,
+          ...errors.map((error) => `- ${error}`),
+          `Available selectors: ${available}`
+        ].join("\n")
+      );
+    }
+  }
+  validateDynamicTargets() {
+    const selectorKeys = new Set(Object.keys(this.selectorsValue));
+    const available = Object.keys(this.selectorsValue).sort().join(", ") || "(none)";
+    const errors = [];
+    const isValidActionTarget = (target) => {
+      return selectorKeys.has(target) || target === "document" || target === "relative";
+    };
+    const isValidAssertionTarget = (target) => {
+      return selectorKeys.has(target) || target === "relative";
+    };
+    this.dynamicTests.forEach((test, testIndex) => {
+      test.action.forEach((action, actionIndex) => {
+        if (!isValidActionTarget(action.target)) {
+          errors.push(
+            `dynamic[${testIndex}].action[${actionIndex}]: target "${action.target}" is not defined in selectors`
+          );
+        }
+      });
+      test.assertions.forEach((assertion, assertionIndex) => {
+        if (!isValidAssertionTarget(assertion.target)) {
+          errors.push(
+            `dynamic[${testIndex}].assertions[${assertionIndex}]: target "${assertion.target}" is not defined in selectors`
+          );
+        }
+        if (assertion.target === "relative" && !this.selectorsValue.relative) {
+          errors.push(
+            `dynamic[${testIndex}].assertions[${assertionIndex}]: target "relative" requires selectors.relative to be defined`
+          );
+        }
+      });
+    });
+    if (errors.length > 0) {
+      throw new Error(
+        [
+          `Contract dynamic target validation failed for component "${this.componentName}".`,
+          ...errors.map((error) => `- ${error}`),
+          `Available selectors: ${available}`,
+          `Allowed special targets: document, relative`
+        ].join("\n")
+      );
+    }
+  }
+  build() {
+    this.validateRelationshipInvariants();
+    this.validateStaticTargets();
+    this.validateDynamicTargets();
+    const fallbackId = this.metaValue.id || `aria-ease.contract.${this.componentName}`;
+    return {
+      meta: {
+        id: fallbackId,
+        version: this.metaValue.version || "1.0.0",
+        description: this.metaValue.description || `Fluent contract for ${this.componentName}`,
+        source: this.metaValue.source,
+        W3CName: this.metaValue.W3CName
+      },
+      selectors: this.selectorsValue,
+      relationships: this.relationshipInvariants,
+      static: [{ assertions: this.staticAssertions }],
+      dynamic: this.dynamicTests
+    };
+  }
+};
+function createContract(componentName, define) {
+  const builder = new ContractBuilder(componentName);
+  define(builder);
+  return new FluentContract(builder.build());
+}
+
+export { createContract };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aria-ease",
-  "version": "6.9.0",
+  "version": "6.9.1",
   "description": "Accessibility infrastructure for the entire frontend engineering lifecycle. Build accessible patterns, run automated audits, verify component interactions, and gate deployments — all in one system.",
   "main": "dist/index.cjs",
   "type": "module",
@@ -20,9 +20,10 @@
     "build:core": "tsup ./index.ts --format esm,cjs --dts --outDir dist --external jest-axe --external @testing-library/react --external @axe-core/playwright --external playwright",
     "build:modules": "tsup ./src/combobox/index.ts ./src/accordion/index.ts ./src/block/index.ts ./src/checkbox/index.ts ./src/menu/index.ts ./src/tabs/index.ts ./src/radio/index.ts ./src/toggle/index.ts ./src/contracts/index.ts --format esm,cjs --dts --treeshake --outDir dist/src",
     "build:test": "tsup ./src/utils/test/index.ts --format esm,cjs --dts --treeshake --external jest-axe --external @testing-library/react --external playwright --external @playwright/test --outDir dist/src/utils/test",
+    "build:dsl": "tsup ./src/utils/test/dsl/index.ts --format esm,cjs --dts --treeshake --outDir dist/src/utils/test/dsl",
     "build:cli": "tsup ./src/utils/cli/cli.ts --format esm,cjs --dts --outDir bin --external commander --external chalk --external jest-axe --external @testing-library/react --external @axe-core/playwright --external playwright",
     "build:contracts": "mkdir -p ./dist/src/utils/test && cp -r ./src/utils/test/contract/aria-contracts ./dist/src/utils/test/",
-    "build": "npm run clean && npm run build:core && npm run build:modules && npm run build:test && npm run build:cli && npm run build:contracts"
+    "build": "npm run clean && npm run build:core && npm run build:modules && npm run build:test && npm run build:dsl && npm run build:cli && npm run build:contracts"
   },
   "repository": {
     "type": "git",
@@ -118,10 +119,10 @@
       "import": "./dist/src/tabs/index.js",
       "require": "./dist/src/tabs/index.cjs"
     },
-    "./contracts": {
-      "types": "./dist/src/contracts/index.d.ts",
-      "import": "./dist/src/contracts/index.js",
-      "require": "./dist/src/contracts/index.cjs"
+    "./contract": {
+      "types": "./dist/src/utils/test/dsl/index.d.ts",
+      "import": "./dist/src/utils/test/dsl/index.js",
+      "require": "./dist/src/utils/test/dsl/index.cjs"
     }
   },
   "files": [