@obinexusltd/obix-driver-accessibility-tree 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,380 @@
+# @obinexusltd/obix-driver-accessibility-tree
+
+[![npm version](https://img.shields.io/npm/v/@obinexusltd/obix-driver-accessibility-tree)](https://www.npmjs.com/package/@obinexusltd/obix-driver-accessibility-tree)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A full-featured accessibility driver for the [OBIX SDK](https://github.com/OBINexusComputing/obix-sdk). Solves 10 core browser accessibility problems: live region management, screen reader detection, accessibility tree mirroring, ARIA widget compliance, semantic HTML enhancement, keyboard navigation, ARIA state management, focus trapping, axe-core validation, and framework-level interaction mode detection.
+
+## Installation
+
+```bash
+npm install @obinexusltd/obix-driver-accessibility-tree
+
+# Optional: enable axe-core validation
+npm install axe-core
+```
+
+## Quick Start
+
+```typescript
+import { createAccessibilityTreeDriver } from '@obinexusltd/obix-driver-accessibility-tree';
+
+const driver = createAccessibilityTreeDriver({
+  rootElement: document.getElementById('app')!,
+  liveRegionDefaults: { level: 'polite', atomic: true },
+  screenReaderHints: true,
+});
+
+await driver.initialize();
+
+// Announce a message to screen readers
+driver.announce('Your changes have been saved.', 'polite');
+
+// Trap focus inside a dialog
+const trap = driver.focusManager.createFocusTrap(dialogElement);
+trap.activate();
+
+// Clean up
+await driver.destroy();
+```
+
+## API Reference
+
+### Driver Lifecycle
+
+```typescript
+const driver = createAccessibilityTreeDriver(config?: AccessibilityTreeDriverConfig);
+
+await driver.initialize();  // Lazy-initialize all sub-features
+await driver.destroy();     // Tear down all features and release resources
+```
+
+**Config options:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `rootElement` | `HTMLElement` | `document.body` | Root element to observe |
+| `liveRegionDefaults.level` | `'off' \| 'polite' \| 'assertive'` | `'polite'` | Default aria-live level |
+| `liveRegionDefaults.atomic` | `boolean` | `false` | Default aria-atomic value |
+| `liveRegionDefaults.relevant` | `string` | `'additions text'` | Default aria-relevant value |
+| `liveRegionDefaults.label` | `string` | `undefined` | Default aria-label for regions |
+| `screenReaderHints` | `boolean` | `false` | Enable screen reader detection heuristics |
+
+---
+
+### Live Region Manager
+
+Manages `aria-live` regions for dynamic content announcements. Creates visually hidden elements that are accessible to screen readers.
+
+```typescript
+// Access after initialize()
+const { liveRegions } = driver;
+
+// Create a named live region
+const region = liveRegions.createRegion('status', { level: 'polite', atomic: true });
+
+// Announce via a specific region
+region.announce('Item deleted.');
+
+// Announce globally (uses the default region)
+liveRegions.announceGlobal('Page loaded.', 'assertive');
+
+// Inspect active regions
+const active = liveRegions.getActiveRegions();
+```
+
+---
+
+### Screen Reader Bridge
+
+Browser-safe screen reader detection using media queries (no intrusive heuristics). Creates dedicated regions for polite, assertive, and route-change announcements.
+
+```typescript
+const { screenReaderBridge } = driver;
+
+// Detect screen reader signals
+const result = screenReaderBridge.detect();
+result.likely;         // boolean — screen reader probably active
+result.signals;        // string[] — detected signals (forced-colors, prefers-contrast, etc.)
+
+// Make announcements
+screenReaderBridge.announcePolite('Form submitted successfully.');
+screenReaderBridge.announceAssertive('Error: required field missing.');
+screenReaderBridge.announceRouteChange('/dashboard');
+```
+
+---
+
+### Accessibility Tree Mirror
+
+Real-time DOM-to-accessibility-tree synchronization via `MutationObserver`. Maps HTML semantics to ARIA roles and diffs the tree on every mutation.
+
+```typescript
+const { treeMirror } = driver;
+
+// Start observing
+treeMirror.observe(document.getElementById('app')!);
+
+// Snapshot the current tree
+const tree = treeMirror.snapshot();
+
+// Diff since last snapshot
+const changes = treeMirror.diff();
+
+// Serialize to JSON
+const json = treeMirror.serialize();
+
+// React to tree changes
+treeMirror.onTreeChange((changes) => {
+  console.log('tree updated', changes);
+});
+```
+
+---
+
+### ARIA Widget Compliance
+
+W3C ARIA Authoring Practices pattern validation and auto-configuration. Applies correct ARIA attributes for common widget patterns.
+
+**Supported patterns:**
+
+| Pattern | Widget Type |
+|---------|-------------|
+| `accordion` | Expandable sections |
+| `menu-bar` | Horizontal menu |
+| `slider` | Range input |
+| `tabs` | Tab panel group |
+| `dialog` | Modal dialog |
+| `listbox` | Selection list |
+| `tree` | Hierarchical list |
+| `combobox` | Autocomplete input |
+
+```typescript
+const { widgetCompliance } = driver;
+
+// Apply a pattern to an element
+widgetCompliance.applyPattern(element, 'tabs');
+
+// Validate an element against its declared pattern
+const result = widgetCompliance.validate(element);
+result.valid;     // boolean
+result.errors;    // string[]
+result.warnings;  // string[]
+```
+
+---
+
+### Semantic HTML Enhancer
+
+Auto-injects missing ARIA attributes based on built-in rules. Detects and fixes common accessibility issues such as clickable `div` elements without a role, missing `alt` text, and unlabeled inputs.
+
+```typescript
+const { semanticEnhancer } = driver;
+
+// One-shot scan of the root element
+const report = semanticEnhancer.scan();
+report.fixed;    // number — attributes auto-applied
+report.skipped;  // number — elements that needed manual review
+
+// Continuously observe and fix new content
+semanticEnhancer.observe(document.body);
+
+// Add a custom rule
+semanticEnhancer.addRule({
+  selector: '[data-tooltip]',
+  apply: (el) => { el.setAttribute('aria-describedby', el.dataset.tooltip!); },
+});
+
+// Inspect the built-in rule set
+const rules = semanticEnhancer.getBuiltinRules();
+```
+
+---
+
+### Keyboard Navigation Controller
+
+Implements ARIA keyboard navigation patterns with arrow-key movement, Home/End support, and optional type-ahead.
+
+**Supported patterns:** `roving-tabindex`, `activedescendant`, `grid`
+
+```typescript
+const { keyboardNav } = driver;
+
+// Create a named navigation context
+const nav = keyboardNav.createNavigation('my-listbox', {
+  pattern: 'roving-tabindex',
+  orientation: 'vertical',
+  wrap: true,
+  typeAhead: true,
+});
+
+nav.mount(containerElement);
+
+// Programmatic movement
+nav.moveTo(itemElement);
+nav.moveNext();
+nav.movePrev();
+nav.moveFirst();
+nav.moveLast();
+
+const current = nav.getCurrentItem();
+
+nav.unmount();
+```
+
+---
+
+### ARIA State Manager
+
+Reactive ARIA state management with batch update support. Tracks element-to-state mappings and emits change events.
+
+```typescript
+const { stateManager } = driver;
+
+// Set ARIA state on an element
+stateManager.setState(buttonEl, { expanded: true, disabled: false });
+
+// Read current state
+const state = stateManager.getState(buttonEl);
+
+// Read all tracked states
+const all = stateManager.getAllStates();
+
+// Subscribe to changes
+const unsubscribe = stateManager.onStateChange((element, newState) => {
+  console.log('state changed', element, newState);
+});
+
+unsubscribe(); // remove listener
+```
+
+---
+
+### Focus Management
+
+Programmatic focus control with a save/restore stack and focus trap support. Escape key automatically deactivates traps.
+
+```typescript
+const { focusManager } = driver;
+
+// Move focus to an element
+focusManager.moveFocus(targetElement);
+
+// Save the current focus position
+focusManager.saveFocus();
+
+// Restore last saved focus
+focusManager.restoreFocus();
+
+// Create and activate a focus trap (e.g. inside a modal)
+const trap = focusManager.createFocusTrap(dialogElement);
+trap.activate();   // Tab/Shift+Tab cycle inside dialogElement, Escape deactivates
+trap.deactivate(); // Release trap and return focus to trigger
+```
+
+---
+
+### axe-core Integration
+
+Optional runtime ARIA validation using axe-core (peer dependency). Lazy-loads axe-core on first use; runs 18 default ARIA-specific rules.
+
+```typescript
+// Requires: npm install axe-core
+const { axeIntegration } = driver;
+
+// Check if axe-core is available
+const available = await axeIntegration.isAvailable();
+
+// Run on the whole document
+const results = await axeIntegration.run();
+results.violations;  // AxeViolation[]
+results.passes;      // AxePass[]
+results.incomplete;  // AxeIncomplete[]
+
+// Run on a specific element
+const nodeResults = await axeIntegration.runOnNode(formElement);
+```
+
+---
+
+### Framework Integration
+
+Unified facade for framework-level accessibility. Detects interaction mode, manages navigation landmarks, and provides an accessibility summary.
+
+```typescript
+const { framework } = driver;
+
+// Detect how the user is currently interacting
+const mode = framework.detectInteractionMode();
+// 'keyboard' | 'pointer' | 'touch' | 'screen-reader'
+
+// Register a navigation pathway
+framework.registerPathway('main-nav', {
+  landmark: 'navigation',
+  element: navElement,
+  label: 'Main Navigation',
+});
+
+// Jump to a landmark
+framework.navigateToLandmark('main');
+
+// Get an accessibility health summary
+const summary = framework.getAccessibilitySummary();
+summary.interactionMode;  // current mode
+summary.landmarks;        // registered landmark count
+summary.liveRegions;      // active region count
+```
+
+---
+
+### Sub-Module Accessors
+
+Direct access to underlying sub-modules after `initialize()`:
+
+```typescript
+driver.liveRegions        // LiveRegionManagerAPI
+driver.screenReaderBridge // ScreenReaderBridgeAPI
+driver.treeMirror         // TreeMirrorAPI
+driver.widgetCompliance   // WidgetComplianceAPI
+driver.semanticEnhancer   // SemanticEnhancerAPI
+driver.keyboardNav        // KeyboardNavigationAPI
+driver.stateManager       // AriaStateManagerAPI
+driver.focusManager       // FocusManagerAPI
+driver.axeIntegration     // AxeIntegrationAPI
+driver.framework          // FrameworkIntegrationAPI
+```
+
+---
+
+## Architecture
+
+| Module | Responsibility |
+|--------|---------------|
+| `live-region-manager` | aria-live region creation and announcements |
+| `screen-reader-bridge` | Screen reader detection via media queries |
+| `accessibility-tree-mirror` | MutationObserver-based DOM-to-ARIA tree sync |
+| `aria-widget-compliance` | W3C ARIA pattern validation and auto-config |
+| `semantic-html-enhancer` | Auto-inject missing ARIA from built-in rules |
+| `keyboard-navigation` | Roving tabindex / activedescendant / grid patterns |
+| `state-properties-manager` | Reactive ARIA state with change events |
+| `focus-management` | Focus trap, save/restore, programmatic movement |
+| `axe-core-integration` | Optional runtime validation via axe-core |
+| `framework-integration` | Interaction mode, landmarks, accessibility summary |
+| `types` | All shared TypeScript interfaces |
+
+---
+
+## Environment Support
+
+| Environment | Support |
+|-------------|---------|
+| Browser | Full — MutationObserver, media queries, focus APIs |
+| Node.js / SSR | Safe import — no `window`/`document` access at load time |
+| Deno | Graceful no-op — `isBrowser: false` |
+| jsdom (test) | Full — all features work in JSDOM (Vitest) |
+
+---
+
+## License
+
+MIT — OBINexus <okpalan@protonmail.com>

package/dist/accessibility-tree-mirror.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Feature 4: Accessibility Tree Mirror
+ * Real-time DOM-to-Accessibility Tree synchronization with MutationObserver
+ */
+import type { AccessibilityNode, Disposable } from "./types.js";
+export interface TreeMirrorConfig {
+    rootElement: Element;
+    observe?: boolean;
+    subtreeFilter?: (element: Element) => boolean;
+}
+export interface TreeDiff {
+    type: "added" | "removed" | "changed";
+    path: string;
+    oldNode?: AccessibilityNode;
+    newNode?: AccessibilityNode;
+}
+export interface TreeMirrorAPI extends Disposable {
+    observe(): void;
+    disconnect(): void;
+    snapshot(): AccessibilityNode;
+    diff(previous: AccessibilityNode, current: AccessibilityNode): TreeDiff[];
+    serialize(): string;
+    onTreeChange(handler: (diffs: TreeDiff[]) => void): () => void;
+}
+export declare function createAccessibilityTreeMirror(config: TreeMirrorConfig): TreeMirrorAPI;
+//# sourceMappingURL=accessibility-tree-mirror.d.ts.map

package/dist/accessibility-tree-mirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility-tree-mirror.d.ts","sourceRoot":"","sources":["../src/accessibility-tree-mirror.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA2ChE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;CAC/C;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,OAAO,IAAI,IAAI,CAAC;IAChB,UAAU,IAAI,IAAI,CAAC;IACnB,QAAQ,IAAI,iBAAiB,CAAC;IAC9B,IAAI,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,iBAAiB,GAAG,QAAQ,EAAE,CAAC;IAC1E,SAAS,IAAI,MAAM,CAAC;IACpB,YAAY,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAChE;AA6ED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,gBAAgB,GACvB,aAAa,CA4Ef"}

package/dist/accessibility-tree-mirror.js

@@ -0,0 +1,173 @@
+/**
+ * Feature 4: Accessibility Tree Mirror
+ * Real-time DOM-to-Accessibility Tree synchronization with MutationObserver
+ */
+/** Implied ARIA role mapping from HTML tag names */
+const IMPLIED_ROLES = {
+    a: "link",
+    article: "article",
+    aside: "complementary",
+    button: "button",
+    details: "group",
+    dialog: "dialog",
+    footer: "contentinfo",
+    form: "form",
+    h1: "heading",
+    h2: "heading",
+    h3: "heading",
+    h4: "heading",
+    h5: "heading",
+    h6: "heading",
+    header: "banner",
+    hr: "separator",
+    img: "img",
+    input: "textbox",
+    li: "listitem",
+    main: "main",
+    menu: "menu",
+    nav: "navigation",
+    ol: "list",
+    option: "option",
+    progress: "progressbar",
+    section: "region",
+    select: "combobox",
+    summary: "button",
+    table: "table",
+    tbody: "rowgroup",
+    td: "cell",
+    textarea: "textbox",
+    tfoot: "rowgroup",
+    th: "columnheader",
+    thead: "rowgroup",
+    tr: "row",
+    ul: "list",
+};
+function buildNode(element, filter) {
+    const tag = element.tagName?.toLowerCase() ?? "";
+    const explicitRole = element.getAttribute("role");
+    const role = explicitRole || IMPLIED_ROLES[tag] || "generic";
+    const label = element.getAttribute("aria-label") ||
+        element.getAttribute("aria-labelledby") ||
+        element.title ||
+        undefined;
+    const description = element.getAttribute("aria-describedby") || undefined;
+    // Collect aria-* attributes
+    const attributes = {};
+    if (element.attributes) {
+        for (let i = 0; i < element.attributes.length; i++) {
+            const attr = element.attributes[i];
+            if (attr.name.startsWith("aria-") || attr.name === "role" || attr.name === "tabindex") {
+                attributes[attr.name] = attr.value;
+            }
+        }
+    }
+    const children = [];
+    for (let i = 0; i < element.children.length; i++) {
+        const child = element.children[i];
+        if (filter && !filter(child))
+            continue;
+        children.push(buildNode(child, filter));
+    }
+    return {
+        role,
+        label,
+        description,
+        attributes: Object.keys(attributes).length > 0 ? attributes : undefined,
+        children: children.length > 0 ? children : undefined,
+    };
+}
+function diffNodes(prev, curr, path, result) {
+    if (!prev && curr) {
+        result.push({ type: "added", path, newNode: curr });
+        return;
+    }
+    if (prev && !curr) {
+        result.push({ type: "removed", path, oldNode: prev });
+        return;
+    }
+    if (!prev || !curr)
+        return;
+    // Check if node itself changed
+    if (prev.role !== curr.role ||
+        prev.label !== curr.label ||
+        prev.description !== curr.description ||
+        JSON.stringify(prev.attributes) !== JSON.stringify(curr.attributes)) {
+        result.push({ type: "changed", path, oldNode: prev, newNode: curr });
+    }
+    // Diff children
+    const prevChildren = prev.children ?? [];
+    const currChildren = curr.children ?? [];
+    const maxLen = Math.max(prevChildren.length, currChildren.length);
+    for (let i = 0; i < maxLen; i++) {
+        diffNodes(prevChildren[i], currChildren[i], `${path}/${i}`, result);
+    }
+}
+export function createAccessibilityTreeMirror(config) {
+    let observer = null;
+    let cachedSnapshot = null;
+    const changeHandlers = new Set();
+    function takeSnapshot() {
+        return buildNode(config.rootElement, config.subtreeFilter);
+    }
+    function handleMutations() {
+        const prev = cachedSnapshot;
+        cachedSnapshot = takeSnapshot();
+        if (prev && changeHandlers.size > 0) {
+            const diffs = diffNodes_wrapper(prev, cachedSnapshot);
+            if (diffs.length > 0) {
+                for (const handler of changeHandlers) {
+                    handler(diffs);
+                }
+            }
+        }
+    }
+    function diffNodes_wrapper(prev, curr) {
+        const result = [];
+        diffNodes(prev, curr, "", result);
+        return result;
+    }
+    return {
+        observe() {
+            if (observer)
+                return;
+            cachedSnapshot = takeSnapshot();
+            observer = new MutationObserver(handleMutations);
+            observer.observe(config.rootElement, {
+                attributes: true,
+                attributeFilter: ["role", "tabindex", "aria-label", "aria-labelledby",
+                    "aria-describedby", "aria-expanded", "aria-selected", "aria-hidden",
+                    "aria-controls", "aria-live", "aria-atomic", "aria-relevant",
+                    "aria-activedescendant", "aria-checked", "aria-disabled",
+                    "aria-pressed", "aria-valuenow", "aria-valuemin", "aria-valuemax"],
+                childList: true,
+                subtree: true,
+            });
+        },
+        disconnect() {
+            if (observer) {
+                observer.disconnect();
+                observer = null;
+            }
+        },
+        snapshot() {
+            cachedSnapshot = takeSnapshot();
+            return cachedSnapshot;
+        },
+        diff(previous, current) {
+            return diffNodes_wrapper(previous, current);
+        },
+        serialize() {
+            return JSON.stringify(this.snapshot(), null, 2);
+        },
+        onTreeChange(handler) {
+            changeHandlers.add(handler);
+            return () => { changeHandlers.delete(handler); };
+        },
+        destroy() {
+            this.disconnect();
+            cachedSnapshot = null;
+            changeHandlers.clear();
+        },
+    };
+}
+//# sourceMappingURL=accessibility-tree-mirror.js.map

package/dist/accessibility-tree-mirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility-tree-mirror.js","sourceRoot":"","sources":["../src/accessibility-tree-mirror.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,oDAAoD;AACpD,MAAM,aAAa,GAA2B;IAC5C,CAAC,EAAE,MAAM;IACT,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,aAAa;IACrB,IAAI,EAAE,MAAM;IACZ,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;IACb,MAAM,EAAE,QAAQ;IAChB,EAAE,EAAE,WAAW;IACf,GAAG,EAAE,KAAK;IACV,KAAK,EAAE,SAAS;IAChB,EAAE,EAAE,UAAU;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,YAAY;IACjB,EAAE,EAAE,MAAM;IACV,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,QAAQ;IACjB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,UAAU;IACjB,EAAE,EAAE,MAAM;IACV,QAAQ,EAAE,SAAS;IACnB,KAAK,EAAE,UAAU;IACjB,EAAE,EAAE,cAAc;IAClB,KAAK,EAAE,UAAU;IACjB,EAAE,EAAE,KAAK;IACT,EAAE,EAAE,MAAM;CACX,CAAC;AAwBF,SAAS,SAAS,CAAC,OAAgB,EAAE,MAAiC;IACpE,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IACjD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,YAAY,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC;IAE7D,MAAM,KAAK,GACT,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC;QAClC,OAAO,CAAC,YAAY,CAAC,iBAAiB,CAAC;QACtC,OAAuB,CAAC,KAAK;QAC9B,SAAS,CAAC;IAEZ,MAAM,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,kBAAkB,CAAC,IAAI,SAAS,CAAC;IAE1E,4BAA4B;IAC5B,MAAM,UAAU,GAA2B,EAAE,CAAC;IAC9C,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACnD,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACnC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBACtF,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;YACrC,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAwB,EAAE,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAClC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,SAAS;QACvC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO;QACL,IAAI;QACJ,KAAK;QACL,WAAW;QACX,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QACvE,QAAQ,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;KACrD,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAChB,IAAmC,EACnC,IAAmC,EACnC,IAAY,EACZ,MAAkB;IAElB,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;QAClB,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,OAAO;IACT,CAAC;IACD,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,OAAO;IACT,CAAC;IACD,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO;IAE3B,+BAA+B;IAC/B,IACE,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI;QACvB,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK;QACzB,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,WAAW;QACrC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,EACnE,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,gBAAgB;IAChB,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IACzC,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAClE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACtE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,MAAwB;IAExB,IAAI,QAAQ,GAA4B,IAAI,CAAC;IAC7C,IAAI,cAAc,GAA6B,IAAI,CAAC;IACpD,MAAM,cAAc,GAAG,IAAI,GAAG,EAA+B,CAAC;IAE9D,SAAS,YAAY;QACnB,OAAO,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IAC7D,CAAC;IAED,SAAS,eAAe;QACtB,MAAM,IAAI,GAAG,cAAc,CAAC;QAC5B,cAAc,GAAG,YAAY,EAAE,CAAC;QAChC,IAAI,IAAI,IAAI,cAAc,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACpC,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;YACtD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;oBACrC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACjB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS,iBAAiB,CAAC,IAAuB,EAAE,IAAuB;QACzE,MAAM,MAAM,GAAe,EAAE,CAAC;QAC9B,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;QAClC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO;QACL,OAAO;YACL,IAAI,QAAQ;gBAAE,OAAO;YACrB,cAAc,GAAG,YAAY,EAAE,CAAC;YAChC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,eAAe,CAAC,CAAC;YACjD,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE;gBACnC,UAAU,EAAE,IAAI;gBAChB,eAAe,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB;oBACnE,kBAAkB,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa;oBACnE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe;oBAC5D,uBAAuB,EAAE,cAAc,EAAE,eAAe;oBACxD,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,CAAC;gBACpE,SAAS,EAAE,IAAI;gBACf,OAAO,EAAE,IAAI;aACd,CAAC,CAAC;QACL,CAAC;QAED,UAAU;YACR,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,UAAU,EAAE,CAAC;gBACtB,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC;QAED,QAAQ;YACN,cAAc,GAAG,YAAY,EAAE,CAAC;YAChC,OAAO,cAAc,CAAC;QACxB,CAAC;QAED,IAAI,CAAC,QAAQ,EAAE,OAAO;YACpB,OAAO,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9C,CAAC;QAED,SAAS;YACP,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAClD,CAAC;QAED,YAAY,CAAC,OAAO;YAClB,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC5B,OAAO,GAAG,EAAE,GAAG,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACnD,CAAC;QAED,OAAO;YACL,IAAI,CAAC,UAAU,EAAE,CAAC;YAClB,cAAc,GAAG,IAAI,CAAC;YACtB,cAAc,CAAC,KAAK,EAAE,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/aria-widget-compliance.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Feature 2: ARIA Widget Compliance Engine
+ * W3C ARIA Authoring Practices design patterns with validation
+ */
+import type { Disposable } from "./types.js";
+import type { AriaStateManagerAPI } from "./state-properties-manager.js";
+import type { FocusManagerAPI } from "./focus-management.js";
+import type { KeyboardNavigationAPI } from "./keyboard-navigation.js";
+export type WidgetPattern = "accordion" | "menu-bar" | "slider" | "tabs" | "dialog" | "listbox" | "tree" | "combobox";
+export interface WidgetConfig {
+    container: Element;
+    pattern: WidgetPattern;
+    options?: Record<string, unknown>;
+}
+export interface WidgetHandle extends Disposable {
+    activate(): void;
+    deactivate(): void;
+    getPattern(): WidgetPattern;
+    validate(): WidgetValidationResult;
+}
+export interface WidgetValidationResult {
+    valid: boolean;
+    errors: Array<{
+        element: Element;
+        message: string;
+        severity: "error" | "warning";
+    }>;
+}
+export interface WidgetComplianceDeps {
+    stateManager: AriaStateManagerAPI;
+    focusManager: FocusManagerAPI;
+    keyboardNav: KeyboardNavigationAPI;
+}
+export interface WidgetComplianceAPI extends Disposable {
+    createWidget(id: string, config: WidgetConfig): WidgetHandle;
+    getWidget(id: string): WidgetHandle | undefined;
+    destroyWidget(id: string): void;
+    validateAll(): Map<string, WidgetValidationResult>;
+    getSupportedPatterns(): WidgetPattern[];
+}
+export declare function createWidgetComplianceEngine(deps: WidgetComplianceDeps): WidgetComplianceAPI;
+//# sourceMappingURL=aria-widget-compliance.d.ts.map

package/dist/aria-widget-compliance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aria-widget-compliance.d.ts","sourceRoot":"","sources":["../src/aria-widget-compliance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEtE,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,UAAU,GACV,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,SAAS,GACT,MAAM,GACN,UAAU,CAAC;AAEf,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,IAAI,IAAI,CAAC;IACjB,UAAU,IAAI,IAAI,CAAC;IACnB,UAAU,IAAI,aAAa,CAAC;IAC5B,QAAQ,IAAI,sBAAsB,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;QACZ,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;KAC/B,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,mBAAmB,CAAC;IAClC,YAAY,EAAE,eAAe,CAAC;IAC9B,WAAW,EAAE,qBAAqB,CAAC;CACpC;AAED,MAAM,WAAW,mBAAoB,SAAQ,UAAU;IACrD,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,YAAY,CAAC;IAC7D,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAChD,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACnD,oBAAoB,IAAI,aAAa,EAAE,CAAC;CACzC;AAmQD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,oBAAoB,GACzB,mBAAmB,CAiErB"}