@stackoverflow/stacks 1.7.1 → 1.9.0

package/lib/test/test-utils.ts

@@ -0,0 +1,444 @@
+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";
+
+const colorThemes = ["dark", "light"];
+const baseThemes = ["", "highcontrast"];
+type Themes = ["light" | "dark" | "highcontrast" | ""];
+type TestTypes = "visual" | "a11y";
+
+type TestOptions = {
+    /**
+     * Enable tests for all color themes
+     * default: true
+     */
+    testColorThemes: boolean;
+    /**
+     * Enable tests for high contrast
+     * default: true
+     */
+    testHighContrast: boolean;
+    /**
+     * Include tests for the component without any variants applied
+     * default: true
+     */
+    includeNullVariant: boolean;
+    /**
+     * Include tests for the component without any modifiers applied
+     * default: true
+     */
+    includeNullModifier: boolean;
+};
+
+interface ComponentTestVariationArgs {
+    /**
+     * Base class of the component
+     * (e.g. "s-component")
+     */
+    baseClass: string;
+    /**
+     * Variants of the component
+     * (e.g. ["primary", "secondary"])
+     */
+    variants?: string[];
+    /**
+     * Modifiers of the component
+     * (e.g. { primary: ["filled", "outlined"], secondary: ["xs", "sm", "md"] })
+     */
+    modifiers?: ComponentTestModifiers;
+    /**
+     * Options for the test
+     */
+    options?: TestOptions;
+}
+
+type ComponentTestArgs = {
+    /**
+     * The element to test
+     * use the `html` template tag to render the element
+     */
+    element: TemplateResult;
+    /**
+     * testid of the test
+     * (e.g. "s-component-primary-important")
+     */
+    testid: string;
+    /**
+     * Theme to apply to the test element
+     */
+    theme?: Themes;
+    /**
+     * Type of test to run
+     */
+    type: TestTypes;
+};
+
+interface ComponentTestsArgs extends ComponentTestVariationArgs {
+    /**
+     * Additional html attributes applied to the test element
+     * (e.g. { role: "button",  id: "id" } -> <element role="button" id="id">  )
+     */
+    attributes?: Record<string, string>;
+    /**
+     * Child elements to render inside the test element
+     * (if key `default` is used, the testid will not include the child name)
+     */
+    children?: {
+        [key: string]: string;
+    };
+    /**
+     * testids of tests to exclude from testing
+     */
+    excludedTestids?: (string | RegExp)[];
+    /**
+     * testids of tests to skip
+     */
+    skippedTestids?: (string | RegExp)[];
+    /**
+     * HTML tag name of the test element
+     */
+    tag?: string;
+    /**
+     * Function that returns a template for the test element
+     * used to wrap the component test element in a container
+     */
+    template?: (args: {
+        component: unknown;
+        tag?: string;
+        testid: string;
+    }) => ReturnType<typeof html>;
+    /**
+     * Type of test to run
+     */
+    type: TestTypes;
+}
+
+type ComponentTestModifiers = {
+    /**
+     * Primary grouping of modifiers to test
+     * The base class will be used as a prefix for these modifiers
+     */
+    primary?: string[];
+    /**
+     * Secondary grouping of modifiers to test
+     * The base class will be used as a prefix for these modifiers
+     */
+    secondary?: string[];
+    /**
+     * Grouping of modifers to test that will not be prefixed with the base class
+     */
+    global?: string[];
+    /**
+     * Modifiers to test individually
+     * The base class will be used as a prefix for these modifiers
+     */
+    standalone?: string[];
+};
+
+type ComponentTestProps = {
+    classes: string;
+    testid: string;
+    theme?: Themes;
+};
+
+const attrObjToString = (attrs: Record<string, string>): string => {
+    const attrString = Object.keys(attrs).map((key) => {
+        return `${key}="${attrs[key]}"` || "";
+    });
+    return attrString.join(" ") || "";
+};
+
+const buildClasses = ({
+    baseClass,
+    prefixed = [],
+    unprefixed = [],
+}: {
+    baseClass: string;
+    prefixed?: string[];
+    unprefixed?: string[];
+}) =>
+    [
+        baseClass,
+        ...prefixed.filter((x) => x).map((suffix) => `${baseClass}__${suffix}`),
+        ...unprefixed.filter((x) => x),
+    ].join(" ");
+
+const buildTestElement = ({
+    attributes = {},
+    children = "",
+    tag = "div",
+    testid,
+}: {
+    attributes?: Record<string, string>;
+    children?: string;
+    tag?: string;
+    testid: string;
+}) => {
+    const unsafe = {
+        tag: unsafeStatic(tag),
+        attributes: unsafeStatic(attrObjToString(attributes).toString()),
+        children: unsafeStatic(children),
+    };
+
+    return html`
+        <${unsafe.tag}
+            ${unsafe.attributes}
+            data-testid="${testid}"
+        >
+            ${unsafe.children}
+        </${unsafe.tag}>
+    `;
+};
+
+const buildTestid = (arr: string[]) => arr.filter(Boolean).join("-");
+
+const getComponentTestVariations = ({
+    baseClass,
+    variants = [],
+    modifiers,
+    options = {
+        testColorThemes: true,
+        testHighContrast: true,
+        includeNullVariant: false,
+        includeNullModifier: true,
+    },
+}: ComponentTestVariationArgs): ComponentTestProps[] => {
+    const testVariations: ComponentTestProps[] = [];
+    // Test default, high contrast themes
+    [...(options.testHighContrast ? baseThemes : [""])].forEach((baseTheme) => {
+        // Test light, dark theme
+        [...(options.testColorThemes ? colorThemes : [""])].forEach(
+            (colorTheme) => {
+                const theme = [baseTheme, colorTheme].filter(Boolean) as Themes;
+                const testidBase = buildTestid([baseClass, ...theme]);
+                const primaryModifiers = modifiers?.primary
+                    ? ["", ...(<[]>modifiers.primary)]
+                    : [""];
+                const secondaryModifiers = modifiers?.secondary
+                    ? ["", ...(<[]>modifiers.secondary)]
+                    : [""];
+                const globalModifiers = modifiers?.global
+                    ? ["", ...(<[]>modifiers.global)]
+                    : [""];
+
+                primaryModifiers.forEach((primaryModifier) => {
+                    secondaryModifiers.forEach((secondaryModifier) => {
+                        globalModifiers.forEach((globalModifier) => {
+                            ["", ...variants].forEach((variant) => {
+                                testVariations.push({
+                                    classes: buildClasses({
+                                        baseClass,
+                                        prefixed: [
+                                            variant,
+                                            primaryModifier,
+                                            secondaryModifier,
+                                        ],
+                                        unprefixed: [globalModifier],
+                                    }),
+                                    testid: buildTestid([
+                                        testidBase,
+                                        variant,
+                                        [
+                                            primaryModifier,
+                                            secondaryModifier,
+                                            globalModifier,
+                                        ]
+                                            .filter(Boolean)
+                                            .join("-"),
+                                    ]),
+                                    theme,
+                                });
+                            });
+                        });
+                    });
+                });
+
+                // create standalone modifiers test props
+                modifiers?.standalone?.forEach((standaloneModifier) => {
+                    testVariations.push({
+                        testid: buildTestid([testidBase, standaloneModifier]),
+                        classes: buildClasses({
+                            baseClass,
+                            prefixed: [standaloneModifier],
+                        }),
+                        theme,
+                    });
+                });
+            }
+        );
+    });
+
+    // Sorting for readability
+    return testVariations.sort((a, b) => a.testid.localeCompare(b.testid));
+};
+
+/**
+ * Constructs and runs an individual test for a component
+ */
+const runComponentTest = ({
+    element,
+    testid,
+    theme,
+    type,
+}: ComponentTestArgs) => {
+    const getDescription = (type: TestTypes) => {
+        switch (type) {
+            case "a11y":
+                return "should be accessible";
+            case "visual":
+                return "should not introduce visual regressions";
+            default:
+                return "";
+        }
+    };
+
+    it(`${type}: ${testid} ${getDescription(type)}`, async () => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        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);
+        }
+
+        if (type === "a11y") {
+            // TODO add conditional option for high contrast mode to test against AAA
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+            await expect(el).to.be.accessible();
+        }
+
+        if (type === "visual") {
+            await visualDiff(el, testid);
+        }
+    });
+};
+
+/**
+ * Constructs and runs tests for a component with a each provided combination
+ */
+const runComponentTests = ({
+    baseClass,
+    variants = [],
+    modifiers,
+    options = {
+        testColorThemes: true,
+        testHighContrast: true,
+        includeNullVariant: false,
+        includeNullModifier: true,
+    },
+    attributes,
+    children,
+    excludedTestids = [],
+    skippedTestids = [],
+    tag,
+    template,
+    type,
+}: ComponentTestsArgs) => {
+    getComponentTestVariations({
+        baseClass,
+        variants,
+        modifiers,
+        options,
+    }).forEach(({ testid, classes, theme }) => {
+        const allChildren: {
+            [key: string]: string;
+        } = children ? { ...children } : { default: "" };
+
+        Object.keys(allChildren).forEach((key) => {
+            const testidModified =
+                key !== "default" ? `${testid}-${key}` : testid;
+            const children = allChildren[key];
+
+            const shouldSkipTest = excludeOrSkipTest({
+                patterns: skippedTestids,
+                skip: true,
+                testid: testidModified,
+                type,
+            });
+
+            const shouldExcludeTest = excludeOrSkipTest({
+                patterns: excludedTestids,
+                testid: testidModified,
+                type,
+            });
+
+            if (shouldSkipTest || shouldExcludeTest) {
+                return;
+            }
+
+            const element = template
+                ? html`${template({
+                      testid: testidModified,
+                      component: buildTestElement({
+                          attributes: {
+                              class: classes,
+                              ...attributes,
+                          },
+                          children,
+                          testid: `${testidModified}-nested`,
+                          tag,
+                      }),
+                  })}`
+                : buildTestElement({
+                      attributes: {
+                          class: classes,
+                          ...attributes,
+                      },
+                      children,
+                      testid: testidModified,
+                      tag,
+                  });
+
+            runComponentTest({
+                element,
+                testid: testidModified,
+                theme,
+                type,
+            });
+        });
+    });
+};
+
+const matchTestidByPattern = ({
+    testid,
+    pattern,
+}: {
+    testid: string;
+    pattern: string | RegExp;
+}): boolean => {
+    if (pattern instanceof RegExp) {
+        return pattern.test(testid);
+    } else {
+        return pattern === testid;
+    }
+};
+
+const excludeOrSkipTest = ({
+    patterns,
+    skip = false,
+    testid,
+    type,
+}: {
+    patterns: (string | RegExp)[];
+    skip?: boolean;
+    testid: string;
+    type: TestTypes;
+}): boolean => {
+    const matchesTest = patterns.some((pattern) => {
+        return matchTestidByPattern({ testid, pattern });
+    });
+
+    if (matchesTest && skip) {
+        it.skip(`${type}: ${testid} (skipped)`, () => {
+            return;
+        });
+    }
+
+    return matchesTest;
+};
+
+export { runComponentTest, runComponentTests };

package/lib/tsconfig.json

@@ -9,5 +9,5 @@
         "skipLibCheck": true,
         "declaration": true
     },
-    "include": ["ts/**/*"]
+    "include": ["**/*.ts"]
 }

package/package.json

@@ -5,7 +5,7 @@
     "type": "git",
     "url": "https://github.com/StackExchange/Stacks.git"
   },
-  "version": "1.7.1",
+  "version": "1.9.0",
   "files": [
     "dist",
     "lib"
@@ -13,7 +13,7 @@
   "main": "./dist/js/stacks.js",
   "types": "./dist/index.d.ts",
   "style": "./dist/css/stacks.css",
-  "less": "./lib/css/stacks.less",
+  "less": "./lib/stacks.less",
   "unpkg": "dist/css/stacks.min.css",
   "scripts": {
     "start": "concurrently -n w: npm:start:*",
@@ -23,14 +23,15 @@
     "start:webpack": "webpack --watch --config ./docs/webpack.config.js",
     "start:eleventy": "cd ./docs && eleventy --serve",
     "test": "web-test-runner",
+    "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": "web-test-runner --group=visual",
     "test:visual:update": "web-test-runner --group=visual --update-visual-baseline",
     "prepublishOnly": "npm run build",
     "lint": "concurrently -n w: npm:lint:*",
-    "lint:ts": "eslint ./lib/ts",
-    "lint:css": "stylelint ./lib/css",
+    "lint:ts": "eslint ./lib/**/*.ts",
+    "lint:css": "stylelint ./lib/*",
     "lint:format": "prettier --check ./lib"
   },
   "license": "MIT",
@@ -39,48 +40,48 @@
     "@popperjs/core": "^2.11.6"
   },
   "devDependencies": {
-    "@11ty/eleventy": "^1.0.2",
+    "@11ty/eleventy": "^2.0.0",
     "@highlightjs/cdn-assets": "^11.7.0",
     "@open-wc/testing": "^3.1.7",
     "@rollup/plugin-commonjs": "^24.0.1",
     "@rollup/plugin-replace": "^5.0.2",
-    "@stackoverflow/stacks-editor": "^0.8.4",
-    "@stackoverflow/stacks-icons": "^5.0.2",
-    "@testing-library/dom": "^8.19.1",
+    "@stackoverflow/stacks-editor": "^0.8.6",
+    "@stackoverflow/stacks-icons": "^5.3.1",
+    "@testing-library/dom": "^9.0.1",
     "@testing-library/user-event": "^14.4.3",
-    "@typescript-eslint/eslint-plugin": "^5.47.1",
-    "@typescript-eslint/parser": "^5.48.2",
-    "@web/dev-server-esbuild": "^0.3.3",
-    "@web/dev-server-rollup": "0.3.21",
-    "@web/test-runner": "^0.15.0",
+    "@typescript-eslint/eslint-plugin": "^5.56.0",
+    "@typescript-eslint/parser": "^5.54.0",
+    "@web/dev-server-esbuild": "^0.3.4",
+    "@web/dev-server-rollup": "^0.4.0",
+    "@web/test-runner": "^0.15.1",
     "@web/test-runner-playwright": "^0.9.0",
     "@web/test-runner-visual-regression": "^0.7.0",
     "concurrently": "^7.6.0",
-    "css-loader": "^6.7.2",
-    "cssnano": "^5.1.14",
+    "css-loader": "^6.7.3",
+    "cssnano": "^5.1.15",
     "docsearch.js": "^2.6.3",
     "eleventy-plugin-highlightjs": "^1.1.0",
     "eleventy-plugin-nesting-toc": "^1.3.0",
-    "eslint": "^8.31.0",
-    "eslint-config-prettier": "^8.6.0",
+    "eslint": "^8.36.0",
+    "eslint-config-prettier": "^8.7.0",
     "eslint-plugin-no-unsanitized": "^4.0.2",
-    "jquery": "^3.6.1",
+    "jquery": "^3.6.4",
     "less-loader": "^11.1.0",
     "list.js": "^2.3.1",
     "markdown-it": "^13.0.1",
     "mini-css-extract-plugin": "^2.7.2",
     "postcss-less": "^6.0.0",
     "postcss-loader": "^7.0.2",
-    "prettier": "^2.8.2",
+    "prettier": "^2.8.4",
     "rollup-plugin-postcss": "^4.0.2",
-    "stylelint": "^14.16.0",
-    "stylelint-config-recommended": "^9.0.0",
-    "stylelint-config-standard": "^29.0.0",
+    "stylelint": "^15.3.0",
+    "stylelint-config-recommended": "^10.0.1",
+    "stylelint-config-standard": "^30.0.1",
     "terser-webpack-plugin": "^5.3.6",
     "ts-loader": "^9.4.2",
-    "typescript": "^4.9.4",
-    "webpack": "^5.75.0",
-    "webpack-cli": "^5.0.0",
+    "typescript": "^4.9.5",
+    "webpack": "^5.76.1",
+    "webpack-cli": "^5.0.1",
     "webpack-merge": "^5.8.0"
   },
   "browserslist": [

package/dist/controllers/index.d.ts

@@ -1,9 +0,0 @@
-export { ExpandableController } from "./s-expandable-control";
-export { hideModal, ModalController, showModal } from "./s-modal";
-export { hideBanner, BannerController, showBanner } from "./s-banner";
-export { hideToast, ToastController, showToast } from "./s-toast";
-export { TabListController } from "./s-navigation-tablist";
-export { attachPopover, detachPopover, hidePopover, BasePopoverController, PopoverController, showPopover, } from "./s-popover";
-export { TableController } from "./s-table";
-export { setTooltipHtml, setTooltipText, TooltipController } from "./s-tooltip";
-export { UploaderController } from "./s-uploader";