@stackoverflow/stacks 1.10.2 → 2.0.0-rc.0

package/lib/exports/v1/constants-colors.less.test.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from "vitest";
+import { renderLess } from "../../test/less-test-utils";
+
+describe("constants-colors", () => {
+    it("should output all the css generated by the v1 colors/theming generation mixins", async () => {
+        const css = await renderLess(`
+            @import "./lib/exports/v1/constants-colors.less";
+        `);
+
+        expect(css).toMatchSnapshot();
+    });
+});

package/lib/stacks-static.less

@@ -56,6 +56,11 @@
 // LESS CONSTANTS AND MIXINS
 @import "exports/exports.less";
 
+//  --  ATOMIC CLASSES (v1 colors)
+@import "atomic/v1/border.less"; // Deprecated
+@import "atomic/v1/color.less"; // Deprecated
+@import "atomic/v1/typography.less"; // Deprecated
+
 //  --  ATOMIC CLASSES
 @import "atomic/border.less";
 @import "atomic/color.less";

package/lib/test/axe-apca/README.md

@@ -0,0 +1,34 @@
+# axe-apca
+
+⚠️ *Once this package become more mature and stable it should be extracted in its own repo (e.g. StackExchange/axe-apca) and published as an npm package. This will allow to use the rule/checks in many contexts including our Core codebase.*
+
+This package contains custom axe rules and checks for [APCA](https://readtech.org/) Bronze and Silver+ [conformance levels](https://readtech.org/ARC/tests/visual-readability-contrast/?tn=criterion).
+
+## Usage
+
+### Installation
+
+⚠️ *The following command doesn't work because this package is not published on npm yet.*
+
+```bash
+npm install --save-dev axe-core axe-apca
+```
+
+### Setup
+
+```js
+import axe from "axe-core";
+import { registerAxeAPCA } from 'axe-apca';
+
+registerAxeAPCA('bronze'); // or registerAxeAPCA('silver');
+
+ // consider turning off default WCAG 2.1 AA color contrast rules when using APCA
+axe.configure({
+    rules: [{ id: "color-contrast", enabled: false }]
+})
+
+ axe.run(document, (err, results) => {
+    if (err) throw err;
+    console.log(results);
+});
+```

package/lib/test/axe-apca/index.ts

@@ -0,0 +1,3 @@
+import registerAxeAPCA from "./src/axe-apca";
+
+export default registerAxeAPCA;

package/lib/test/axe-apca/package.wip.json

@@ -0,0 +1,30 @@
+{
+    "name": "axe-apca",
+    "description": "Axe rules to check against APCA bronze and silver+ conformance levels.",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/StackExchange/axe-apca.git"
+    },
+    "version": "0.0.0",
+    "main": "TODO",
+    "types": "TODO",
+    "scripts": {
+        "build": "TODO: transpile ts to js",
+        "test": "web-test-runner"
+    },
+    "license": "MIT",
+    "dependencies": {
+        "apca-w3": "^0.1.9"
+    },
+    "peerDependencies": {
+        "axe-core": "^4.0.0"
+    },
+    "devDependencies": {
+        "@open-wc/testing": "^3.2.0",
+        "@web/dev-server-esbuild": "^0.4.1",
+        "@web/dev-server-rollup": "^0.5.2",
+        "@web/test-runner": "^0.16.1",
+        "@web/test-runner-playwright": "^0.10.1",
+        "typescript": "^5.1.6"
+    }
+}

package/lib/test/axe-apca/src/apca-w3.d.ts

@@ -0,0 +1,3 @@
+declare module "apca-w3" {
+    export function calcAPCA(textColor: string, bgColor: string): number;
+}

package/lib/test/axe-apca/src/axe-apca.test.ts

@@ -0,0 +1,155 @@
+import { html, fixture, expect } from "@open-wc/testing";
+import axe from "axe-core";
+import type { AxeResults } from "axe-core";
+import registerAxeAPCA from "./axe-apca";
+
+const runAxe = async (el: HTMLElement): Promise<AxeResults> => {
+    return new Promise((resolve, reject) => {
+        axe.run(el, (err, results) => {
+            if (err) reject(err);
+            resolve(results);
+        });
+    });
+};
+
+describe("axe-apca", () => {
+    describe("bronze conformance level", () => {
+        beforeEach(() => {
+            registerAxeAPCA("bronze");
+        });
+
+        it("should check for APCA accessibility contrast violations", async () => {
+            const el: HTMLElement = await fixture(
+                html`<p
+                    style="background: white; color: black; font-size: 12px; font-weight: 400;"
+                >
+                    Some copy
+                </p>`
+            );
+
+            const results = await runAxe(el);
+
+            const apcaPasses = results.passes.filter((violation) =>
+                violation.id.includes("color-contrast-apca-bronze")
+            );
+
+            await expect(apcaPasses.length).to.equal(1);
+
+            const passNode = apcaPasses[0].nodes[0];
+            expect(passNode.all[0].message).to.include(
+                "Element has sufficient APCA bronze level lightness contrast"
+            );
+        });
+
+        it("should detect APCA accessibility contrast violations", async () => {
+            const el: HTMLElement = await fixture(
+                html`<p
+                    style="background: white; color: lightgray; font-size: 12px; font-weight: 400;"
+                >
+                    Some copy
+                </p>`
+            );
+
+            const results = await runAxe(el);
+
+            const apcaViolations = results.violations.filter((violation) =>
+                violation.id.includes("color-contrast-apca-bronze")
+            );
+
+            await expect(apcaViolations.length).to.equal(1);
+
+            const violationNode = apcaViolations[0].nodes[0];
+            expect(violationNode.failureSummary).to.include(
+                "Element has insufficient APCA bronze level contrast"
+            );
+        });
+
+        it("should check nested nodes", async () => {
+            const el: HTMLElement = await fixture(
+                html`<div style="background: black;">
+                    <h2>Some title</h2>
+                    <p>Some copy</p>
+                    <button style="background: black;">Some button</button>
+                </div>`
+            );
+
+            const results = await runAxe(el);
+
+            const apcaViolations = results.violations.filter((violation) =>
+                violation.id.includes("color-contrast-apca-bronze")
+            );
+
+            await expect(apcaViolations[0].nodes.length).to.equal(3);
+        });
+    });
+
+    describe("silver conformance level", () => {
+        beforeEach(() => {
+            registerAxeAPCA("silver");
+        });
+
+        it("should check for APCA accessibility contrast violations", async () => {
+            const el: HTMLElement = await fixture(
+                html`<p
+                    style="background: white; color: black; font-size: 14px; font-weight: 400;"
+                >
+                    Some copy
+                </p>`
+            );
+
+            const results = await runAxe(el);
+
+            const apcaPasses = results.passes.filter((violation) =>
+                violation.id.includes("color-contrast-apca-silver")
+            );
+
+            await expect(apcaPasses.length).to.equal(1);
+
+            const passNode = apcaPasses[0].nodes[0];
+            expect(passNode.all[0].message).to.include(
+                "Element has sufficient APCA silver level lightness contrast"
+            );
+        });
+
+        it("should detect APCA accessibility contrast violations", async () => {
+            const el: HTMLElement = await fixture(
+                html`<p
+                    style="background: white; color: black; font-size: 12px; font-weight: 400;"
+                >
+                    Some copy
+                </p>`
+            );
+
+            const results = await runAxe(el);
+
+            const apcaViolations = results.violations.filter((violation) =>
+                violation.id.includes("color-contrast-apca-silver")
+            );
+
+            await expect(apcaViolations.length).to.equal(1);
+
+            const violationNode = apcaViolations[0].nodes[0];
+            expect(violationNode.failureSummary).to.include(
+                "Element has insufficient APCA silver level contrast"
+            );
+        });
+
+        it("should check nested nodes", async () => {
+            const el: HTMLElement = await fixture(
+                html`<div style="background: black;">
+                    <h2>Some title</h2>
+                    <p>Some copy</p>
+                    <button style="background: black;">Some button</button>
+                </div>`
+            );
+
+            const results = await runAxe(el);
+
+            const apcaViolations = results.violations.filter((violation) =>
+                violation.id.includes("color-contrast-apca-silver")
+            );
+
+            await expect(apcaViolations[0].nodes.length).to.equal(3);
+        });
+    });
+});

package/lib/test/axe-apca/src/axe-apca.ts

@@ -0,0 +1,212 @@
+import { calcAPCA } from "apca-w3";
+import axe from "axe-core";
+import type { Check, Rule } from "axe-core";
+
+// Augment Axe types to include the color utilities we use in this file
+// https://github.com/dequelabs/axe-core/blob/develop/lib/commons/color/color.js
+type Color = {
+    red: number;
+    green: number;
+    blue: number;
+    alpha: number;
+    toHexString: () => string;
+};
+
+declare module "axe-core" {
+    const commons: {
+        color: {
+            getForegroundColor: (
+                node: HTMLElement,
+                _: unknown,
+                bgColor: Color | null
+            ) => Color | null;
+            getBackgroundColor: (node: HTMLElement) => Color | null;
+        };
+    };
+}
+
+const getAPCASilverPlusThreshold = (
+    fontSize: string,
+    fontWeight: string
+): number | null => {
+    const silverPlusAPCALookupTable = [
+        // See https://readtech.org/ARC/tests/visual-readability-contrast/?tn=criterion (May 22, 2022)
+        // font size in px | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 weights
+        [10, -1, -1, -1, -1, -1, -1, -1, -1, -1],
+        [12, -1, -1, -1, -1, -1, -1, -1, -1, -1],
+        [14, -1, -1, -1, 100, 100, 90, 75, -1, -1],
+        [15, -1, -1, -1, 100, 100, 90, 70, -1, -1],
+        [16, -1, -1, -1, 90, 75, 70, 60, 60, -1],
+        [18, -1, -1, 100, 75, 70, 60, 55, 55, 55],
+        [21, -1, -1, 90, 70, 60, 55, 50, 50, 50],
+        [24, -1, -1, 75, 60, 55, 50, 45, 45, 45],
+        [28, -1, 100, 70, 55, 50, 45, 43, 43, 43],
+        [32, -1, 90, 65, 50, 45, 43, 40, 40, 40],
+        [36, -1, 75, 60, 45, 43, 40, 38, 38, 38],
+        [48, 90, 60, 55, 43, 40, 38, 35, 35, 35],
+        [60, 75, 55, 50, 40, 38, 35, 33, 33, 33],
+        [72, 60, 50, 45, 38, 35, 33, 30, 30, 30],
+        [96, 50, 45, 40, 35, 33, 30, 25, 25, 25],
+    ];
+
+    const size = parseFloat(fontSize);
+    const weight = parseFloat(fontWeight);
+
+    // Go over the table backwards to find the first matching font size and then the weight.
+    // The value null is returned when the combination of font size and weight does not have
+    // any elegible APCA luminosity silver compliant thresholds (represented by -1 in the table).
+    silverPlusAPCALookupTable.reverse();
+    for (const [rowSize, ...rowWeights] of silverPlusAPCALookupTable) {
+        if (size >= rowSize) {
+            for (const [idx, keywordWeight] of [
+                900, 800, 700, 600, 500, 400, 300, 200, 100,
+            ].entries()) {
+                if (weight >= keywordWeight) {
+                    const threshold = rowWeights[rowWeights.length - 1 - idx];
+                    return threshold === -1 ? null : threshold;
+                }
+            }
+        }
+    }
+
+    return null;
+};
+
+const getAPCABronzeThreshold = (fontSize: string): number | null => {
+    const size = parseFloat(fontSize);
+
+    // APCA Bronze Level Conformance
+    // https://readtech.org/ARC/tests/visual-readability-contrast/?tn=criterion
+    switch (true) {
+        case size >= 32:
+            return 45;
+        case size >= 16:
+            return 60;
+        default:
+            return 75;
+    }
+};
+
+const generateColorContrastAPCAConformanceCheck = (
+    conformanceLevel: string,
+    conformanceThresholdFn: (
+        fontSize: string,
+        fontWeight: string
+    ) => number | null
+): Check => ({
+    id: `color-contrast-apca-${conformanceLevel}-conformance`,
+    metadata: {
+        impact: "serious",
+        messages: {
+            pass:
+                "Element has sufficient APCA " +
+                conformanceLevel +
+                " level lightness contrast (Lc) of ${data.apcaContrast}Lc (foreground color: ${data.fgColor}, background color: ${data.bgColor}, font size: ${data.fontSize}, font weight: ${data.fontWeight}). Expected minimum APCA contrast of ${data.apcaThreshold}}",
+            fail: {
+                default:
+                    "Element has insufficient APCA " +
+                    conformanceLevel +
+                    " level contrast of ${data.apcaContrast}Lc (foreground color: ${data.fgColor}, background color: ${data.bgColor}, font size: ${data.fontSize}, font weight: ${data.fontWeight}). Expected minimum APCA lightness contrast of ${data.apcaThreshold}Lc",
+                increaseFont:
+                    "Element has insufficient APCA " +
+                    conformanceLevel +
+                    " level contrast of ${data.apcaContrast}Lc (foreground color: ${data.fgColor}, background color: ${data.bgColor}, font size: ${data.fontSize}, font weight: ${data.fontWeight}). Increase font size and/or font weight to meet APCA conformance minimums",
+            },
+            incomplete: "Unable to determine APCA lightness contrast (Lc)",
+        },
+    },
+    evaluate: function (node: HTMLElement) {
+        const nodeStyle = window.getComputedStyle(node);
+        const fontSize = nodeStyle.getPropertyValue("font-size");
+        const fontWeight = nodeStyle.getPropertyValue("font-weight");
+
+        const bgColor: Color | null =
+            axe.commons.color.getBackgroundColor(node);
+        const fgColor: Color | null = axe.commons.color.getForegroundColor(
+            node,
+            false,
+            bgColor
+        );
+
+        // missing data to determine APCA contrast for this node
+        if (!bgColor || !fgColor || !fontSize || !fontWeight) {
+            return undefined;
+        }
+
+        const toRGBA = (color: Color) => {
+            return `rgba(${color.red}, ${color.green}, ${color.blue}, ${color.alpha})`;
+        };
+
+        const apcaContrast = Math.abs(
+            calcAPCA(toRGBA(fgColor), toRGBA(bgColor))
+        );
+        const apcaThreshold = conformanceThresholdFn(fontSize, fontWeight);
+
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        this.data({
+            fgColor: fgColor.toHexString(),
+            bgColor: bgColor.toHexString(),
+            fontSize: `${((parseFloat(fontSize) * 72) / 96).toFixed(
+                1
+            )}pt (${fontSize}px)`,
+            fontWeight: fontWeight,
+            apcaContrast: Math.round(apcaContrast * 100) / 100,
+            apcaThreshold: apcaThreshold,
+            messageKey: apcaThreshold === null ? "increaseFont" : "default",
+        });
+
+        return apcaThreshold ? apcaContrast >= apcaThreshold : false;
+    },
+});
+
+const generateColorContrastAPCARule = (conformanceLevel: string): Rule => ({
+    id: `color-contrast-apca-${conformanceLevel}`,
+    impact: "serious",
+    matches: "color-contrast-matches",
+    metadata: {
+        description: `Ensures the contrast between foreground and background colors meets APCA ${conformanceLevel} level conformance minimums thresholds`,
+        tags: ["apca", "wcag3", `apca-${conformanceLevel}`],
+        help: "Elements must meet APCA conformance minimums thresholds",
+        helpUrl:
+            "https://readtech.org/ARC/tests/visual-readability-contrast/?tn=criterion",
+    },
+    all: [`color-contrast-apca-${conformanceLevel}-conformance`],
+    tags: ["apca", "wcag3", `apca-${conformanceLevel}`],
+});
+
+const colorContrastAPCASilverConformanceCheck =
+    generateColorContrastAPCAConformanceCheck(
+        "silver",
+        getAPCASilverPlusThreshold
+    );
+
+const colorContrastAPCABronzeConformanceCheck =
+    generateColorContrastAPCAConformanceCheck("bronze", getAPCABronzeThreshold);
+
+const colorContrastAPCASilverRule = generateColorContrastAPCARule("silver");
+const colorContrastAPCABronzeRule = generateColorContrastAPCARule("bronze");
+
+const registerAxeAPCA = (conformanceLevel: "bronze" | "silver") => {
+    axe.configure({
+        rules: [generateColorContrastAPCARule(conformanceLevel)],
+        checks: [
+            generateColorContrastAPCAConformanceCheck(
+                conformanceLevel,
+                conformanceLevel === "bronze"
+                    ? getAPCABronzeThreshold
+                    : getAPCASilverPlusThreshold
+            ),
+        ],
+    });
+};
+
+export {
+    colorContrastAPCASilverRule,
+    colorContrastAPCASilverConformanceCheck,
+    colorContrastAPCABronzeRule,
+    colorContrastAPCABronzeConformanceCheck,
+};
+
+export default registerAxeAPCA;

package/lib/test/less-test-utils.ts

@@ -0,0 +1,28 @@
+import beautify from "cssbeautify";
+import * as less from "less";
+import * as path from "path";
+import * as fs from "fs";
+
+// cssbeautify is an old package that doesn't support ES modules
+const cssbeautify = beautify as (css: string) => string;
+
+const getSubdirectories = (dirPath: string): string[] => {
+    const subdirs = fs
+        .readdirSync(dirPath)
+        .map((file) => path.join(dirPath, file))
+        .filter((path) => fs.statSync(path).isDirectory());
+    return subdirs.reduce(
+        (acc, subdir) => [...acc, subdir, ...getSubdirectories(subdir)],
+        subdirs
+    );
+};
+
+const renderLess = async (lessCode: string) => {
+    const { css } = await less.render(lessCode, {
+        paths: getSubdirectories(path.join(__dirname, "../")),
+    });
+
+    return cssbeautify(css);
+};
+
+export { renderLess };

package/lib/test/test-utils.ts

@@ -2,6 +2,10 @@ import { html, fixture, expect, unsafeStatic } from "@open-wc/testing";
 import { screen } from "@testing-library/dom";
 import { visualDiff } from "@web/test-runner-visual-regression";
 import type { TemplateResult } from "lit-html";
+import axe from "axe-core";
+import registerAxeAPCA from "./axe-apca";
+
+registerAxeAPCA("bronze");
 
 const colorThemes = ["dark", "light"];
 const baseThemes = ["", "highcontrast"];
@@ -317,7 +321,20 @@ const runComponentTest = ({
         }
 
         if (type === "a11y") {
-            // TODO add conditional option for high contrast mode to test against AAA
+            const highcontrast = theme?.includes("highcontrast");
+            axe.configure({
+                rules: [
+                    // for non-high contrast, we disable WCAG 2.1 AA (4.5:1)
+                    // and use APCA bronze level instead
+                    { id: "color-contrast", enabled: false },
+                    {
+                        id: "color-contrast-apca-bronze",
+                        enabled: !highcontrast,
+                    },
+                    // for high contrast, we check against WCAG 2.1 AAA (7:1)
+                    { id: "color-contrast-enhanced", enabled: highcontrast },
+                ],
+            });
             await expect(el).to.be.accessible();
         }
 

package/lib/tsconfig.json

@@ -8,6 +8,7 @@
         "moduleResolution": "node",
         "skipLibCheck": true,
         "declaration": true,
+        "allowSyntheticDefaultImports": true,
         "paths": {
             "@open-wc/testing": ["./test/open-wc-testing-patch.d.ts"]
         }

package/package.json

@@ -5,7 +5,7 @@
         "type": "git",
         "url": "https://github.com/StackExchange/Stacks.git"
     },
-    "version": "1.10.2",
+    "version": "2.0.0-rc.0",
     "files": [
         "dist",
         "lib"
@@ -22,12 +22,14 @@
         "build:docs": "webpack --mode=production --config ./docs/webpack.config.js && cd ./docs && eleventy",
         "start:webpack": "webpack --watch --config ./docs/webpack.config.js",
         "start:eleventy": "cd ./docs && eleventy --serve",
-        "test": "npm run test:unit && npm run test:a11y && npm run test:visual",
+        "test": "npm run test:less && npm run test:unit && npm run test:a11y && npm run test:visual",
         "test:a11y": "web-test-runner --group=a11y",
         "test:unit": "web-test-runner --group=unit",
         "test:unit:watch": "web-test-runner --group=unit --watch",
         "test:visual": "pwsh run-test-visual.ps1 npx web-test-runner --group=visual",
         "test:visual:update": "pwsh run-test-visual.ps1 npx web-test-runner --group=visual --update-visual-baseline",
+        "test:less": "vitest run .less.test.ts",
+        "test:less:update": "npm run test:less -- -u",
         "prepublishOnly": "npm run build",
         "format": "prettier --write ./lib",
         "lint": "concurrently -n w: npm:lint:*",
@@ -44,21 +46,25 @@
         "@11ty/eleventy": "^2.0.1",
         "@highlightjs/cdn-assets": "^11.8.0",
         "@open-wc/testing": "^3.2.0",
-        "@rollup/plugin-commonjs": "^25.0.3",
+        "@rollup/plugin-commonjs": "^25.0.4",
         "@rollup/plugin-replace": "^5.0.2",
         "@stackoverflow/stacks-editor": "^0.8.8",
-        "@stackoverflow/stacks-icons": "^5.4.0",
+        "@stackoverflow/stacks-icons": "^5.5.0",
         "@testing-library/dom": "^9.3.1",
         "@testing-library/user-event": "^14.4.3",
-        "@typescript-eslint/eslint-plugin": "^6.2.1",
-        "@typescript-eslint/parser": "^6.2.1",
+        "@types/cssbeautify": "^0.3.2",
+        "@types/less": "^3.0.3",
+        "@typescript-eslint/eslint-plugin": "^6.4.0",
+        "@typescript-eslint/parser": "^6.4.0",
         "@web/dev-server-esbuild": "^0.4.1",
         "@web/dev-server-rollup": "^0.5.2",
         "@web/test-runner": "^0.17.0",
         "@web/test-runner-playwright": "^0.10.1",
         "@web/test-runner-visual-regression": "^0.8.2",
+        "apca-w3": "^0.1.9",
         "concurrently": "^8.2.0",
         "css-loader": "^6.8.1",
+        "cssbeautify": "^0.3.1",
         "cssnano": "^6.0.1",
         "docsearch.js": "^2.6.3",
         "eleventy-plugin-highlightjs": "^1.1.0",
@@ -73,7 +79,7 @@
         "mini-css-extract-plugin": "^2.7.6",
         "postcss-less": "^6.0.0",
         "postcss-loader": "^7.3.3",
-        "prettier": "^3.0.0",
+        "prettier": "^3.0.1",
         "rollup-plugin-postcss": "^4.0.2",
         "stylelint": "^15.10.2",
         "stylelint-config-recommended": "^13.0.0",
@@ -81,6 +87,7 @@
         "terser-webpack-plugin": "^5.3.9",
         "ts-loader": "^9.4.4",
         "typescript": "^5.1.6",
+        "vitest": "^0.33.0",
         "webpack": "^5.88.2",
         "webpack-cli": "^5.1.4",
         "webpack-merge": "^5.9.0"