@stackoverflow/stacks 2.0.8 → 2.1.0-rc.0

package/lib/exports/mixins.less

@@ -110,6 +110,39 @@
 }
 
 
+/**
+ * Focus styles for the given context.
+ *
+ * Usage example:
+ * .focus-styles(true, true);
+ *
+ * @inset: boolean - whether the focus style be placed inside the element.
+ * @border: boolean - whether the element's border color change to match the focus style.
+ */
+.focus-styles(@inset: false, @border: false) {
+    & when not (@inset) and not (@border) {
+        box-shadow: 0 0 0 var(--su-static2) var(--focus-neutral), 0 0 0 var(--su-static4) var(--focus-theme);
+    }
+
+    & when not (@inset) and (@border) {
+        border-color: var(--focus-neutral) !important;
+        box-shadow: 0 0 0 var(--su-static1) var(--focus-neutral), 0 0 0 calc(var(--su-static4) - var(--su-static1)) var(--focus-theme);
+    }
+
+    & when (@inset) and not (@border) {
+        box-shadow: inset 0 0 0 var(--su-static2) var(--focus-theme), inset 0 0 0 var(--su-static4) var(--focus-neutral);
+    }
+
+    & when (@inset) and (@border) {
+        border-color: var(--focus-theme) !important;
+        box-shadow: inset 0 0 0 var(--su-static1) var(--focus-theme), inset 0 0 0 calc(var(--su-static4) - var(--su-static1)) var(--focus-neutral);
+    }
+
+    // We include a 2px transparent outline to ensure Windows High Contrast Forced Color Mode
+    // includes outlines as expected See https://blogs.windows.com/msedgedev/2020/09/17/styling-for-windows-high-contrast-with-new-standards-for-forced-colors/
+    outline: var(--su-static2) solid transparent !important;
+}
+
 //  =============================================================================
 //  --  COLORS
 //      The following mixins let us do color math on the browser. They take a

package/lib/input-utils.less

@@ -17,19 +17,16 @@
 
     .has-error & {
         --_@{prefix}-bc: var(--red-400);
-        --_@{prefix}-bs-focus: 0 0 0 var(--su-static4) var(--focus-ring-error);
         @error();
     }
 
     .has-success & {
         --_@{prefix}-bc: var(--green-400);
-        --_@{prefix}-bs-focus: 0 0 0 var(--su-static4) var(--focus-ring-success);
         @success();
     }
 
     .has-warning & {
         --_@{prefix}-bc: var(--yellow-500);
-        --_@{prefix}-bs-focus: 0 0 0 var(--su-static4) var(--focus-ring-warning);
         @warning();
     }
 }

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

@@ -0,0 +1,94 @@
+import { html, fixture, expect } from "@open-wc/testing";
+import { screen } from "@testing-library/dom";
+import axe from "axe-core";
+import registerAPCACheck from "apca-check";
+import { generateTestVariations, type TestVariationArgs } from "./test-utils";
+import type { AdditionalAssertion } from "./assertions";
+
+type A11yTestArgs = TestVariationArgs & {
+    /**
+     * Additional assertions to run against the test element
+     */
+    additionalAssertions?: AdditionalAssertion[];
+};
+
+// register Stack APCA conformance threshold function
+// see also https://stackoverflow.design/product/base/color-fundamentals/#accessibility-standards
+const customConformanceThresholdFn = (fontSize: string): number | null => {
+    // if the font size is 32px or larger, we use a 45Lc threshold
+    // otherwise, we use a 60Lc threshold
+    return parseFloat(fontSize) >= 32 ? 45 : 60;
+};
+registerAPCACheck("custom", customConformanceThresholdFn);
+
+const scheduleA11yTest = ({
+    element,
+    testid,
+    theme,
+    additionalAssertions = [],
+}: {
+    element: ReturnType<typeof html>;
+    testid: string;
+    theme: string[];
+    additionalAssertions?: AdditionalAssertion[];
+}) => {
+    it(`a11y: ${testid} should be accessible`, async () => {
+        await fixture(element);
+        const el = screen.getByTestId(testid);
+
+        document.body.className = "";
+
+        if (theme?.length) {
+            const prefixedThemes = theme.map((t) => `theme-${t}`);
+            document.body.classList.add(...prefixedThemes);
+        }
+
+        const highcontrast = theme?.includes("highcontrast");
+
+        axe.configure({
+            rules: [
+                // for non-high contrast, we disable WCAG 2.1 AA (4.5:1)
+                // and use a Stacks-specific APCA custom level instead
+                { id: "color-contrast", enabled: false },
+                {
+                    id: "color-contrast-apca-custom",
+                    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();
+        el.remove();
+    });
+
+    additionalAssertions.forEach((assertion) => {
+        it(`a11y: ${testid} ${assertion.description}`, async () => {
+            await fixture(element);
+            const el = screen.getByTestId(testid);
+            await assertion.assertion(el);
+            el.remove();
+        });
+    });
+};
+
+const runA11yTests = (args: A11yTestArgs) => {
+    const testVariations = generateTestVariations(args);
+    testVariations.forEach((variation) => {
+        if (variation.skipped) {
+            it.skip(`a11y: ${variation.testid} (skipped)`, () => {
+                return;
+            });
+            return;
+        }
+
+        scheduleA11yTest({
+            ...variation,
+            additionalAssertions: args.additionalAssertions,
+        });
+    });
+};
+
+export type { AdditionalAssertion };
+export { runA11yTests };

package/lib/test/assertions.ts

@@ -1,10 +1,14 @@
 import { expect } from "@open-wc/testing";
 import Color from "colorjs.io";
-import type { AdditionalAssertion } from "./test-utils";
+
+type AdditionalAssertion = {
+    description: string;
+    assertion: (node: HTMLElement) => Promise<void> | void;
+};
 
 // TODO: evaluate if we can do this check against all the components
 // automatically instead of having to add the assertion manually
-export const WCAGNonTextContrast: AdditionalAssertion = {
+const WCAGNonTextContrast: AdditionalAssertion = {
     description:
         "should pass WCAG22 1.4.11 non-text-contrast success criterion (https://www.w3.org/TR/WCAG22/#non-text-contrast)",
     assertion: (node) => {
@@ -18,7 +22,7 @@ export const WCAGNonTextContrast: AdditionalAssertion = {
             selectedNodeStyles.getPropertyValue("background-color")
         );
 
-        // we are specificng WCAG21 because of colorjs.io API
+        // we are specifing WCAG21 because of colorjs.io API
         // WCAG21 and WCAG22 algoirthms are the same
         const WCAGcontrast = bgSelectedNodeColor.contrast(
             bgBodyColor,
@@ -27,3 +31,6 @@ export const WCAGNonTextContrast: AdditionalAssertion = {
         expect(WCAGcontrast).to.be.at.least(3);
     },
 };
+
+export type { AdditionalAssertion };
+export { WCAGNonTextContrast };