@uuv/a11y 0.0.1

package/bundle/uuv-a11y.bundle.js.LICENSE.txt

@@ -0,0 +1,28 @@
+/*!
+ * jQuery JavaScript Library v3.7.1
+ * https://jquery.com/
+ *
+ * Copyright OpenJS Foundation and other contributors
+ * Released under the MIT license
+ * https://jquery.org/license
+ *
+ * Date: 2023-08-28T13:37Z
+ */
+
+/**
+ * @license
+ * Lodash <https://lodash.com/>
+ * Copyright OpenJS Foundation and other contributors <https://openjsf.org/>
+ * Released under MIT license <https://lodash.com/license>
+ * Based on Underscore.js 1.8.3 <http://underscorejs.org/LICENSE>
+ * Copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors
+ */
+
+/** @license React v17.0.2
+ * react-is.production.min.js
+ *
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */

package/dist/README.md

@@ -0,0 +1,199 @@
+
+# @uuv/a11y
+<div align="center">  
+<a href="https://orange-opensource.github.io/uuv/">  
+<picture>  
+<img alt="UUV Logo" src="https://orange-opensource.github.io/uuv/img/uuv.png">  
+</picture>  
+</a>  
+</div>  
+
+<h3 align="center">  
+Automated a11y validation
+</h3>  
+
+<p align="center">  
+@uuv/a11y is a solution for automated accessibility validations
+</p>  
+
+<p align="center">  
+<a href="https://www.npmjs.com/package/@uuv/commons" target="_blank">  
+<img src="https://img.shields.io/badge/available%20on%20npm-grey?logo=npm" alt="npm"/>  
+</a>  
+<a href="https://www.npmjs.com/package/@uuv/commons" target="_blank">  
+<img src="https://img.shields.io/badge/accessibility-yes-green" alt="accessibility"/>  
+</a>  
+<a href="https://jestjs.io/fr/" target="_blank">  
+<img src="https://img.shields.io/badge/tested%20with-jest-yellow?logo=jest" alt="jest"/>  
+</a>  
+<br />  
+</p>  
+
+<div align="center">
+<a href="https://www.npmjs.com/package/@uuv/cypress" target="_blank">
+    <img alt="@uuv/cypress npm library download count"
+        src="https://img.shields.io/npm/dt/%40uuv/cypress?logo=npm&label=%40uuv%2Fcypress"></img>
+</a>
+<a href="https://www.npmjs.com/package/@uuv/playwright" target="_blank">
+    <img alt="@uuv/playwright npm library download count"
+         src="https://img.shields.io/npm/dt/%40uuv/playwright?logo=npm&label=%40uuv%2Fplaywright"></img>
+</a>
+<a href="https://www.npmjs.com/package/@uuv/assistant" target="_blank">
+    <img alt="@uuv/assistant npm library download count"
+         src="https://img.shields.io/npm/dt/%40uuv/assistant?logo=npm&label=%40uuv%2Fassistant"></img>
+</a>
+<a href="https://www.npmjs.com/package/@uuv/a11y" target="_blank">
+    <img alt="@uuv/a11y npm library download count"
+         src="https://img.shields.io/npm/dt/%40uuv/a11y?logo=npm&label=%40uuv%2Fa11y"></img>
+</a>
+<a href="https://plugins.jetbrains.com/plugin/22437-uuv" target="_blank">
+    <img alt="JetBrains Plugin Downloads" src="https://img.shields.io/jetbrains/plugin/d/22437-uuv?logo=jetbrains&label=UUV%20plugin"></img>
+</a>
+<br />
+</div>
+
+## What is @uuv/a11y?
+
+<p align="center">  
+
+The `@uuv` library (User centric Usecases Validator) is an accessibility driven solution to facilitate the writing and execution of end-to-end tests that are understandable to any human being.
+
+`@uuv/a11y` is the part of this solution used to perform automated accessibility checks to guarantee non-regression.
+
+
+## How it works ?
+The following references are available :
+
+### RGAA
+
+For each criterion of the RGAA, the following algorithm is executed :
+
+ ![Diagram a11Y RGAA](./docs/diagram-a11y-rgaa.png)
+
+**Consult [this page](https://orange-opensource.github.io/uuv/docs/tools/uuv-a11y#rgaa) to find out which RGAA verifications are implemented in the library**
+</p>  
+
+## Usage
+### With UNPKG
+1.  Add script tag to import @uuv/a11y in your html page :
+    ```html
+    <script src="https://unpkg.com/@uuv/a11y/dist/bundle/uuv-a11y.bundle.js">
+    </script>
+    ```
+2. Add script tag to execute
+    ```html
+    <script>
+      const rgaaChecker = new uuvA11y.RgaaChecker(url, enabledRules);
+      const result = await rgaaChecker.validate().toPromise();
+      // Print complete result
+      console.log(result);
+      // Print result summary group by criteria
+      console.log(result.summary());
+    </script>
+    ```
+  [Stackblitz example](https://stackblitz.com/edit/web-platform-fihgra?file=index.html)
+
+### As a dependency
+1. Import @uuv/a11y npm dependency
+    ```shell
+    npm install -D @uuv/a11y
+    ```
+2. Use it in your file
+    ```typescript
+    import {
+      RgaaChecker,
+      A11yResult,
+    } from "@uuv/a11y";
+    
+    const currentUrl = "<set your current url>";
+    const rgaaChecker = new RgaaChecker(currentUrl, enabledRules);
+    const result: A11yResult = await rgaaChecker.validate().toPromise();
+    // Print complete result
+    console.log(result);
+    // Print result summary group by criteria
+    console.log(result.summary());
+    ```
+### During E2E Testing (recommended usage car visualisation des noeuds)
+1. add `@uuv/cypress` npm dependency :
+    ```shell
+    npm install --save-dev @uuv/cypress
+    ```
+2. create the file `uuv/e2e/a11y.feature` in the project root with the following content and replace url `https://e2e-test-quest.github.io/simple-webapp/a11y-test.html` by yours :
+    ```gherkin
+    Feature: A11y
+  
+    Scenario: Default RGAA
+      When I visit path "https://e2e-test-quest.github.io/simple-webapp/a11y-test.html"
+      Then I should not have any rgaa accessibility issue
+    
+    Scenario: RGAA with result
+      When I visit path "https://e2e-test-quest.github.io/simple-webapp/a11y-test.html"
+      Then I should have the following result based on the rgaa reference
+      """json
+        {
+          "status": "error",
+          "criteria": {
+            "1.1": {
+              "status": "error"
+            },
+            "1.2": {
+              "status": "error"
+            },
+            "1.3": {
+              "status": "manual"
+            },
+            "1.4": {
+              "status": "manual"
+            },
+            "1.5": {
+              "status": "manual"
+            },
+            "1.6": {
+              "status": "success"
+            },
+            "2.1": {
+              "status": "error"
+            },
+            "8.1": {
+              "status": "error"
+            },
+            "8.3": {
+              "status": "success"
+            },
+            "8.4": {
+              "status": "manual"
+            },
+            "8.5": {
+              "status": "error"
+            },
+            "8.6": {
+              "status": "manual"
+            },
+            "8.10": {
+              "status": "error"
+            },
+            "11.1": {
+              "status": "success"
+            }
+          }
+        }
+      """
+    ```
+3. Then execute your tests :
+    ```shell
+    npx uuv e2e
+    ```
+
+
+## License
+
+[<a href="https://github.com/Orange-OpenSource/uuv/blob/main/LICENSE">  
+<img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"/>  
+</a>](https://spdx.org/licenses/MIT.html)
+
+This project is licensed under the terms of the [MIT license](https://github.com/Orange-OpenSource/uuv/blob/main/LICENSE).
+
+## Authors
+
+- [@luifr10](https://github.com/luifr10)
+- [@stanlee974](https://github.com/stanlee974)

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./lib";

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib"), exports);

package/dist/lib/engine/engine.d.ts

@@ -0,0 +1,12 @@
+import { Observable } from "rxjs";
+import { A11yRule, A11yRuleResult, A11yReference } from "../model/";
+export declare class Engine {
+    readonly targetUrl: string;
+    readonly reference: A11yReference;
+    constructor(targetUrl: string, reference: A11yReference);
+    buildCheckListItemFromRule(rule: A11yRule): Observable<A11yRuleResult>;
+    private getRuleResult;
+    private buildResultForAutoCheck;
+    private buildResultForManualCheck;
+    private getSelector;
+}

package/dist/lib/engine/engine.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Engine = void 0;
+const rxjs_1 = require("rxjs");
+const model_1 = require("../model/");
+class Engine {
+    targetUrl;
+    reference;
+    constructor(targetUrl, reference) {
+        this.targetUrl = targetUrl;
+        this.reference = reference;
+    }
+    buildCheckListItemFromRule(rule) {
+        return new rxjs_1.Observable(observer => {
+            const foundElements = rule.query.execute();
+            const result = this.getRuleResult(rule, foundElements);
+            observer.next(result);
+            observer.complete();
+        });
+    }
+    getRuleResult(rule, foundElements) {
+        if (rule.check === model_1.RuleCheckEnum.MANUAL) {
+            return this.buildResultForManualCheck(rule, foundElements);
+        }
+        else {
+            // Then we are considering rule as RuleCheckEnum.AUTO
+            return this.buildResultForAutoCheck(rule, foundElements);
+        }
+    }
+    buildResultForAutoCheck(rule, $el) {
+        const a11YRuleresult = new model_1.A11yRuleResult(this.targetUrl, rule);
+        if (rule.shouldNotExist) {
+            if ($el?.length > 0) {
+                for (const element of $el) {
+                    const selector = this.getSelector(element);
+                    const validation = a11YRuleresult.getOrAddValidation(rule.criterion);
+                    validation.errorNodes.push({
+                        node: element,
+                        selector: selector,
+                        html: element.outerHTML
+                    });
+                    validation.status = model_1.A11yResultStatus.ERROR;
+                }
+            }
+            else {
+                const validation = a11YRuleresult.getOrAddValidation(rule.criterion);
+                validation.status = model_1.A11yResultStatus.SUCCESS;
+            }
+        }
+        else {
+            if ($el.length === 0 && !rule.elementType.includes("warning") && !rule.elementType.includes("obsolete")) {
+                const validation = a11YRuleresult.getOrAddValidation(rule.criterion);
+                validation.status = model_1.A11yResultStatus.ERROR;
+                validation.errorNodes.push({
+                    selector: rule.query.getSelector(),
+                });
+            }
+            else {
+                const validation = a11YRuleresult.getOrAddValidation(rule.criterion);
+                validation.status = model_1.A11yResultStatus.SUCCESS;
+            }
+        }
+        return a11YRuleresult;
+    }
+    buildResultForManualCheck(rule, $el) {
+        const a11YRuleresult = new model_1.A11yRuleResult(this.targetUrl, rule);
+        const validation = a11YRuleresult.getOrAddValidation(rule.criterion);
+        validation.status = model_1.A11yResultStatus.SUCCESS;
+        for (let i = 0; i < $el.length; i++) {
+            const selector = this.getSelector($el[i]);
+            const attributesToCheck = [];
+            rule.attributes.forEach((attribute) => {
+                const attributeFilledWithInformation = $el[i].getAttribute(attribute);
+                if (attributeFilledWithInformation) {
+                    attributesToCheck.push(` ${attribute}=${attributeFilledWithInformation}`);
+                }
+            });
+            const manualValidation = a11YRuleresult.getOrAddValidation(rule.criterion);
+            manualValidation.status = model_1.A11yResultStatus.MANUAL;
+            manualValidation.nodesToCheckManually.push({
+                node: $el[i],
+                selector: selector,
+                attributes: attributesToCheck.toString(),
+                html: $el[i].outerHTML,
+                help: rule.id ? `${this.reference.getRuleUrl(rule.id)}` : ""
+            });
+        }
+        return a11YRuleresult;
+    }
+    getSelector(element) {
+        const path = [];
+        while (element.nodeType === Node.ELEMENT_NODE) {
+            let selector = element.nodeName.toLowerCase();
+            if (element.id) {
+                selector += "#" + element.id;
+                path.unshift(selector);
+                break;
+            }
+            else if (element.getAttribute("data-testid")) {
+                selector += `[data-testid=${element.getAttribute("data-testid")}]`;
+                path.unshift(selector);
+                break;
+            }
+            else {
+                let sibling = element.previousSibling;
+                let index = 1;
+                while (sibling) {
+                    if (sibling.nodeType === Node.ELEMENT_NODE && sibling.nodeName.toLowerCase() === selector) {
+                        index++;
+                    }
+                    sibling = sibling.previousSibling;
+                }
+                if (index > 1 || element.nextSibling) {
+                    selector += ":nth-of-type(" + index + ")";
+                }
+            }
+            path.unshift(selector);
+            element = element.parentNode;
+        }
+        return path.join(" > ");
+    }
+}
+exports.Engine = Engine;

package/dist/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./reference";
+export * from "./model";
+export * from "./query";

package/dist/lib/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./reference"), exports);
+__exportStar(require("./model"), exports);
+__exportStar(require("./query"), exports);

package/dist/lib/model/checker.d.ts

@@ -0,0 +1,14 @@
+import { A11yReference } from "./reference";
+import { Observable } from "rxjs";
+import { A11yResult } from "./result";
+import { A11yRule } from "./rule";
+import { Engine } from "../engine/engine";
+export declare abstract class A11yChecker {
+    readonly url: string;
+    readonly engine: Engine;
+    readonly reference: A11yReference;
+    protected constructor(url: string, engine: Engine, reference: A11yReference);
+    abstract rules(): A11yRule[];
+    validate(): Observable<A11yResult>;
+    private buildCheckList;
+}

package/dist/lib/model/checker.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A11yChecker = void 0;
+const rxjs_1 = require("rxjs");
+const result_1 = require("./result");
+class A11yChecker {
+    url;
+    engine;
+    reference;
+    constructor(url, engine, reference) {
+        this.url = url;
+        this.engine = engine;
+        this.reference = reference;
+    }
+    validate() {
+        const result = new result_1.A11yResult(this.url, this.reference);
+        const rules = this.rules();
+        const checkList = this.buildCheckList(rules);
+        return (0, rxjs_1.forkJoin)(checkList)
+            .pipe((0, rxjs_1.map)((ruleResults) => {
+            result.ruleResults = ruleResults;
+            result.computeStatus();
+            return result;
+        }), (0, rxjs_1.tap)(result => {
+            console.debug("result");
+            console.debug(result);
+        }));
+    }
+    buildCheckList(rules) {
+        const checkList = [];
+        rules.forEach(rule => checkList.push(this.engine.buildCheckListItemFromRule(rule)));
+        return checkList;
+    }
+}
+exports.A11yChecker = A11yChecker;

package/dist/lib/model/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./checker";
+export * from "./reference";
+export * from "./result";
+export * from "./rule";

package/dist/lib/model/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./checker"), exports);
+__exportStar(require("./reference"), exports);
+__exportStar(require("./result"), exports);
+__exportStar(require("./rule"), exports);

package/dist/lib/model/reference.d.ts

@@ -0,0 +1,55 @@
+import { A11yRule } from "./rule";
+export interface A11yReference {
+    name: string;
+    version: string;
+    rules: A11yRule[];
+    url: string;
+    /**
+     * Build complete coverage
+     */
+    coverage(): A11yReferenceCoverage;
+    /**
+     * Returns online rule url related to a ruleId
+     * @param ruleId
+     */
+    getRuleUrl(ruleId: string): string;
+}
+export declare enum A11yReferenceEnum {
+    RGAA = "RGAA",
+    WCAG_WEB = "WCAG-WEB",
+    WCAG_ANDROID = "WCAG-ANDROID",
+    WCAG_IOS = "WCAG-IOS"
+}
+export declare class Comments {
+    info?: string;
+    warning?: string;
+    danger?: string;
+}
+export declare abstract class Coverage {
+    id: string;
+    name?: string;
+    auto: number;
+    partial: number;
+    wontBeImplemented: number;
+    manual: number;
+    inProgress: number;
+    testsCount: number;
+    comments?: Comments;
+    autoPercentage(): number;
+}
+export declare class A11yReferenceCoverage {
+    name: string;
+    topics: A11yReferenceTopicCoverage[];
+    constructor(name: string);
+}
+export declare class A11yReferenceTopicCoverage extends Coverage {
+    criterias: A11yReferenceCriteriaCoverage[];
+    constructor(id: any, name: any);
+}
+export declare class A11yReferenceCriteriaCoverage extends Coverage {
+    tests: A11yReferenceTestCoverage[];
+    constructor(id: any, name: any);
+}
+export declare class A11yReferenceTestCoverage extends Coverage {
+    constructor(id: any, name: any);
+}

package/dist/lib/model/reference.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A11yReferenceTestCoverage = exports.A11yReferenceCriteriaCoverage = exports.A11yReferenceTopicCoverage = exports.A11yReferenceCoverage = exports.Coverage = exports.Comments = exports.A11yReferenceEnum = void 0;
+var A11yReferenceEnum;
+(function (A11yReferenceEnum) {
+    A11yReferenceEnum["RGAA"] = "RGAA";
+    A11yReferenceEnum["WCAG_WEB"] = "WCAG-WEB";
+    A11yReferenceEnum["WCAG_ANDROID"] = "WCAG-ANDROID";
+    A11yReferenceEnum["WCAG_IOS"] = "WCAG-IOS";
+})(A11yReferenceEnum = exports.A11yReferenceEnum || (exports.A11yReferenceEnum = {}));
+class Comments {
+    info;
+    warning;
+    danger;
+}
+exports.Comments = Comments;
+class Coverage {
+    id;
+    name;
+    auto = 0;
+    partial = 0;
+    wontBeImplemented = 0;
+    manual = 0;
+    inProgress = 0;
+    testsCount = 0;
+    comments;
+    autoPercentage() {
+        return Math.round(this.auto /
+            (this.testsCount) * 100) || 0;
+    }
+}
+exports.Coverage = Coverage;
+class A11yReferenceCoverage {
+    name;
+    topics = [];
+    constructor(name) {
+        this.name = name;
+    }
+}
+exports.A11yReferenceCoverage = A11yReferenceCoverage;
+class A11yReferenceTopicCoverage extends Coverage {
+    criterias = [];
+    constructor(id, name) {
+        super();
+        this.id = id;
+        this.name = name;
+    }
+}
+exports.A11yReferenceTopicCoverage = A11yReferenceTopicCoverage;
+class A11yReferenceCriteriaCoverage extends Coverage {
+    tests = [];
+    constructor(id, name) {
+        super();
+        this.id = id;
+        this.name = name;
+    }
+}
+exports.A11yReferenceCriteriaCoverage = A11yReferenceCriteriaCoverage;
+class A11yReferenceTestCoverage extends Coverage {
+    constructor(id, name) {
+        super();
+        this.id = id;
+        this.name = name;
+    }
+}
+exports.A11yReferenceTestCoverage = A11yReferenceTestCoverage;

package/dist/lib/model/result.d.ts

@@ -0,0 +1,57 @@
+import { A11yRule } from "./rule";
+import { A11yReference } from "./reference";
+export declare enum A11yResultStatus {
+    UNKNOWN = "unknown",
+    SUCCESS = "success",
+    MANUAL = "manual",
+    ERROR = "error"
+}
+export interface NonCompliantNode {
+    node?: HTMLElement;
+    selector: string;
+    html?: string;
+}
+export interface NodeToCheckManually {
+    node: HTMLElement;
+    selector: string;
+    attributes: string;
+    html: string;
+    help: string;
+}
+export declare class A11yRuleValidationResult {
+    readonly criteria: string;
+    status: A11yResultStatus;
+    errorNodes: NonCompliantNode[];
+    nodesToCheckManually: NodeToCheckManually[];
+    constructor(criteria: string);
+}
+export declare class A11yRuleResult {
+    readonly url: string;
+    readonly rule: A11yRule;
+    status: A11yResultStatus;
+    validations: A11yRuleValidationResult[];
+    constructor(url: string, rule: A11yRule);
+    getOrAddValidation(criteria: string): A11yRuleValidationResult;
+    getErrorNodes(): NonCompliantNode[];
+    getNodesToCheckManually(): NodeToCheckManually[];
+    computeStatus(): void;
+    private getStatus;
+}
+export declare class A11yResult {
+    readonly url: string;
+    readonly reference: A11yReference;
+    status: A11yResultStatus;
+    ruleResults: A11yRuleResult[];
+    constructor(url: string, reference: A11yReference);
+    computeStatus(): void;
+    summary(): {
+        status: A11yResultStatus;
+        criteria: {};
+    };
+    private buildSummaryForCriterion;
+    private getPosition;
+    private groupRuleResultByLevel;
+    private getKeyOfLevel;
+    private groupRuleResultByCriterion;
+    private groupRuleResultByTestOfACriterion;
+}