@a11y-oracle/axe-bridge 1.0.0

package/dist/lib/types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @module types
+ *
+ * Minimal axe-core compatible types for the bridge. Defined locally
+ * to avoid a runtime dependency on axe-core. Structurally compatible
+ * with axe-core's result shapes.
+ */
+/** A single check result within an axe node. */
+export interface AxeCheck {
+    /** Check identifier. */
+    id: string;
+    /** Check-specific data (e.g., fontSize, fontWeight for color-contrast). */
+    data: unknown;
+    /** Related DOM nodes. */
+    relatedNodes: unknown[];
+    /** Impact level. */
+    impact?: string;
+    /** Description of the check result. */
+    message: string;
+}
+/** A single DOM node result from an axe rule. */
+export interface AxeNode {
+    /** CSS selector path to the element. */
+    target: string[];
+    /** HTML snippet of the element. */
+    html: string;
+    /** Checks where any one passing fixes the issue. */
+    any: AxeCheck[];
+    /** Checks where all must pass. */
+    all: AxeCheck[];
+    /** Checks where none should be present. */
+    none: AxeCheck[];
+    /** Node-level impact. */
+    impact?: string | null;
+    /** Human-readable failure summary. */
+    failureSummary?: string;
+}
+/** A single axe rule result (violation, pass, or incomplete). */
+export interface AxeRule {
+    /** Rule identifier (e.g., 'color-contrast'). */
+    id: string;
+    /** Impact severity. */
+    impact?: string | null;
+    /** WCAG tags. */
+    tags: string[];
+    /** Rule description. */
+    description: string;
+    /** Short help text. */
+    help: string;
+    /** URL to help documentation. */
+    helpUrl: string;
+    /** Affected DOM nodes. */
+    nodes: AxeNode[];
+}
+/**
+ * Full axe-core results object. Structurally compatible with
+ * `axe.AxeResults` without requiring the axe-core dependency.
+ */
+export interface AxeResults {
+    /** Rules that found violations. */
+    violations: AxeRule[];
+    /** Rules that passed. */
+    passes: AxeRule[];
+    /** Rules that could not be fully evaluated. */
+    incomplete: AxeRule[];
+    /** Rules that were not applicable. */
+    inapplicable: AxeRule[];
+    /** Allow additional properties from axe-core. */
+    [key: string]: unknown;
+}
+/**
+ * WCAG conformance level.
+ *
+ * Structurally compatible with the `WcagLevel` type in
+ * `@a11y-oracle/audit-formatter`. Defined locally to avoid an
+ * unnecessary cross-library dependency.
+ *
+ * Each AA level includes the contrast requirement (SC 1.4.3).
+ * Level A has no contrast SC.
+ */
+export type WcagLevel = 'wcag2a' | 'wcag2aa' | 'wcag21a' | 'wcag21aa' | 'wcag22a' | 'wcag22aa';
+/**
+ * Contrast ratio thresholds for a WCAG conformance level.
+ */
+export interface ContrastThresholds {
+    /** Minimum contrast ratio for normal text (e.g. 4.5 for AA). */
+    normalText: number;
+    /** Minimum contrast ratio for large text (e.g. 3.0 for AA). */
+    largeText: number;
+}
+/**
+ * Options for the incomplete contrast resolution pipeline.
+ *
+ * When `wcagLevel` is provided, thresholds are derived automatically.
+ * Explicit `threshold` / `largeTextThreshold` values override the
+ * level-derived values.
+ */
+export interface ContrastResolutionOptions {
+    /**
+     * WCAG conformance level. When set, contrast thresholds are derived
+     * from the level (e.g. AA → 4.5 / 3.0). Explicit threshold values
+     * take precedence. Default: `'wcag22aa'`.
+     */
+    wcagLevel?: WcagLevel;
+    /** Minimum contrast ratio for normal text. Overrides wcagLevel. */
+    threshold?: number;
+    /** Minimum contrast ratio for large text. Overrides wcagLevel. */
+    largeTextThreshold?: number;
+}
+/** Options for the `link-in-text-block` resolver. */
+export interface LinkInTextBlockOptions {
+    /**
+     * Minimum contrast ratio between link color and surrounding text
+     * to count as sufficient visual differentiation.
+     * Default: `3.0`.
+     */
+    linkTextContrastThreshold?: number;
+}
+/** Options for the `target-size` resolver. */
+export interface TargetSizeOptions {
+    /**
+     * Minimum dimension (width and height) in CSS pixels.
+     * Default: `24`.
+     */
+    minSize?: number;
+}
+/** Options for the `scrollable-region-focusable` resolver. */
+export interface ScrollableRegionOptions {
+    /**
+     * Maximum number of focusable children to inspect inside a
+     * scrollable container before giving up.
+     * Default: `50`.
+     */
+    maxChildren?: number;
+}
+/** Options for the `skip-link` resolver. */
+export interface SkipLinkOptions {
+    /**
+     * Delay in milliseconds after focus for CSS transitions to settle.
+     * Default: `100`.
+     */
+    focusSettleDelay?: number;
+}
+/** Options for the `aria-hidden-focus` resolver. */
+export interface AriaHiddenFocusOptions {
+    /**
+     * Maximum number of Tab presses during keyboard traversal.
+     * Default: `100`.
+     */
+    maxTabs?: number;
+}
+/** Options for the `focus-indicator` resolver. */
+export interface FocusIndicatorOptions {
+    /**
+     * Delay in milliseconds after focus for CSS transitions to settle.
+     * Default: `100`.
+     */
+    focusSettleDelay?: number;
+    /**
+     * Minimum percentage of pixels that must differ between resting
+     * and focused screenshots to count as a visible indicator.
+     * Default: `0.1`.
+     */
+    diffThreshold?: number;
+}
+/** Options for the `content-on-hover` resolver. */
+export interface ContentOnHoverOptions {
+    /**
+     * Delay in milliseconds after hover for content to appear.
+     * Default: `300`.
+     */
+    hoverDelay?: number;
+    /**
+     * Delay in milliseconds after dismiss action to check if content
+     * has disappeared.
+     * Default: `200`.
+     */
+    dismissDelay?: number;
+}
+/** Options for the `frame-tested` resolver. */
+export interface FrameTestedOptions {
+    /**
+     * The complete axe-core source code as a string. Required for
+     * injection into cross-origin iframes.
+     */
+    axeSource?: string;
+    /**
+     * Timeout in milliseconds for axe-core execution inside an iframe.
+     * Default: `30000`.
+     */
+    iframeTimeout?: number;
+}
+/**
+ * Combined options for the `resolveAllIncomplete` orchestrator.
+ *
+ * Each property corresponds to a resolver's options interface.
+ * The `skipRules` array allows excluding specific resolvers.
+ */
+export interface IncompleteResolutionOptions {
+    /** WCAG conformance level (applied to contrast resolver). */
+    wcagLevel?: WcagLevel;
+    /** Options for the `color-contrast` resolver. */
+    contrast?: ContrastResolutionOptions;
+    /** Options for the `link-in-text-block` resolver. */
+    linkInTextBlock?: LinkInTextBlockOptions;
+    /** Options for the `target-size` resolver. */
+    targetSize?: TargetSizeOptions;
+    /** Options for the `scrollable-region-focusable` resolver. */
+    scrollableRegion?: ScrollableRegionOptions;
+    /** Options for the `skip-link` resolver. */
+    skipLink?: SkipLinkOptions;
+    /** Options for the `aria-hidden-focus` resolver. */
+    ariaHiddenFocus?: AriaHiddenFocusOptions;
+    /** Options for the `focus-indicator` resolver. */
+    focusIndicator?: FocusIndicatorOptions;
+    /** Options for the `content-on-hover` resolver. */
+    contentOnHover?: ContentOnHoverOptions;
+    /** Options for the `frame-tested` resolver. */
+    frameTested?: FrameTestedOptions;
+    /**
+     * Rule IDs to skip during resolution. Matching resolvers
+     * will not be invoked and their incomplete entries will be
+     * left untouched.
+     */
+    skipRules?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"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"}

package/dist/lib/types.js

@@ -0,0 +1,8 @@
+/**
+ * @module types
+ *
+ * Minimal axe-core compatible types for the bridge. Defined locally
+ * to avoid a runtime dependency on axe-core. Structurally compatible
+ * with axe-core's result shapes.
+ */
+export {};

package/dist/lib/wcag-thresholds.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module wcag-thresholds
+ *
+ * Maps WCAG conformance levels to contrast ratio thresholds.
+ *
+ * WCAG defines two contrast requirements:
+ * - **SC 1.4.3 (Level AA):** 4.5:1 for normal text, 3:1 for large text.
+ * - **SC 1.4.6 (Level AAA):** 7:1 for normal text, 4.5:1 for large text.
+ *
+ * Level A has no contrast requirement. This module centralizes the
+ * mapping so thresholds derive from the configured level rather than
+ * being hardcoded throughout the codebase.
+ */
+import type { WcagLevel, ContrastThresholds } from './types.js';
+/**
+ * Get WCAG contrast thresholds for a given conformance level.
+ *
+ * Returns the normal-text and large-text thresholds, or `null` if
+ * the level does not include a contrast requirement (Level A).
+ *
+ * @param level - Target WCAG conformance level. Defaults to `'wcag22aa'`.
+ * @returns Contrast thresholds, or null if contrast is not required.
+ *
+ * @example
+ * ```typescript
+ * const thresholds = getContrastThresholds('wcag22aa');
+ * // { normalText: 4.5, largeText: 3.0 }
+ *
+ * const noContrast = getContrastThresholds('wcag22a');
+ * // null (Level A has no contrast SC)
+ * ```
+ */
+export declare function getContrastThresholds(level?: WcagLevel): ContrastThresholds | null;
+//# sourceMappingURL=wcag-thresholds.d.ts.map

package/dist/lib/wcag-thresholds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wcag-thresholds.d.ts","sourceRoot":"","sources":["../../src/lib/wcag-thresholds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAuBhE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,GAAE,SAAyB,GAC/B,kBAAkB,GAAG,IAAI,CAK3B"}

package/dist/lib/wcag-thresholds.js

@@ -0,0 +1,55 @@
+/**
+ * @module wcag-thresholds
+ *
+ * Maps WCAG conformance levels to contrast ratio thresholds.
+ *
+ * WCAG defines two contrast requirements:
+ * - **SC 1.4.3 (Level AA):** 4.5:1 for normal text, 3:1 for large text.
+ * - **SC 1.4.6 (Level AAA):** 7:1 for normal text, 4.5:1 for large text.
+ *
+ * Level A has no contrast requirement. This module centralizes the
+ * mapping so thresholds derive from the configured level rather than
+ * being hardcoded throughout the codebase.
+ */
+/**
+ * WCAG contrast thresholds by conformance tier.
+ *
+ * Each entry maps a WcagLevel to its contrast requirements.
+ * Level A standards have no contrast SC, so they return null.
+ */
+const THRESHOLD_MAP = {
+    // Level A — no contrast SC
+    wcag2a: null,
+    wcag21a: null,
+    wcag22a: null,
+    // Level AA — SC 1.4.3
+    wcag2aa: { normalText: 4.5, largeText: 3.0 },
+    wcag21aa: { normalText: 4.5, largeText: 3.0 },
+    wcag22aa: { normalText: 4.5, largeText: 3.0 },
+};
+/** Default level when none is specified. */
+const DEFAULT_LEVEL = 'wcag22aa';
+/**
+ * Get WCAG contrast thresholds for a given conformance level.
+ *
+ * Returns the normal-text and large-text thresholds, or `null` if
+ * the level does not include a contrast requirement (Level A).
+ *
+ * @param level - Target WCAG conformance level. Defaults to `'wcag22aa'`.
+ * @returns Contrast thresholds, or null if contrast is not required.
+ *
+ * @example
+ * ```typescript
+ * const thresholds = getContrastThresholds('wcag22aa');
+ * // { normalText: 4.5, largeText: 3.0 }
+ *
+ * const noContrast = getContrastThresholds('wcag22a');
+ * // null (Level A has no contrast SC)
+ * ```
+ */
+export function getContrastThresholds(level = DEFAULT_LEVEL) {
+    if (level in THRESHOLD_MAP) {
+        return THRESHOLD_MAP[level];
+    }
+    return THRESHOLD_MAP[DEFAULT_LEVEL];
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@a11y-oracle/axe-bridge",
+  "version": "1.0.0",
+  "description": "Axe-core result post-processor that resolves 10 incomplete rules using visual analysis, keyboard interaction, and CDP inspection",
+  "license": "MIT",
+  "author": "a11y-oracle",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a11y-oracle/a11y-oracle.git",
+    "directory": "libs/axe-bridge"
+  },
+  "bugs": {
+    "url": "https://github.com/a11y-oracle/a11y-oracle/issues"
+  },
+  "homepage": "https://github.com/a11y-oracle/a11y-oracle/tree/main/libs/axe-bridge",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "axe-core",
+    "wcag",
+    "color-contrast",
+    "focus-indicator",
+    "target-size",
+    "cdp",
+    "testing"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@a11y-oracle/cdp-types": "1.0.0",
+    "@a11y-oracle/focus-analyzer": "1.0.0",
+    "@a11y-oracle/keyboard-engine": "1.0.0",
+    "@a11y-oracle/visual-engine": "1.0.0",
+    "tslib": "^2.3.0"
+  }
+}