@stackoverflow/stacks 1.6.6 → 1.7.0

package/lib/test/s-tooltip.visual.test.ts

@@ -0,0 +1,31 @@
+import { html, fixture } from "@open-wc/testing";
+import { screen } from "@testing-library/dom";
+import userEvent from "@testing-library/user-event";
+import { visualDiff } from "@web/test-runner-visual-regression";
+import "../ts/index";
+
+const user = userEvent.setup();
+
+describe("s-tooltip", () => {
+    it("should not introduce visual regressions", async () => {
+        const wrapper = await fixture(html`
+            <div style="height: 100px; width: 160px; display: inline-block;">
+                <button
+                    class="s-btn s-btn__filled"
+                    role="button"
+                    data-controller="s-tooltip"
+                    title="tooltip content"
+                    data-s-tooltip-placement="bottom-start"
+                >
+                    Hover tooltip popover
+                </button>
+            </div>
+        `);
+
+        const trigger = screen.getByRole("button");
+        await user.hover(trigger);
+        await screen.findByRole("tooltip");
+
+        await visualDiff(wrapper, "s-tooltip");
+    });
+});

package/lib/ts/controllers/index.ts

@@ -1,6 +1,8 @@
 // export all controllers *with helpers* so they can be bulk re-exported by the package entry point
 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,

package/lib/ts/controllers/s-banner.ts

@@ -0,0 +1,149 @@
+import * as Stacks from "../stacks";
+
+export class BannerController extends Stacks.StacksController {
+    static targets = ["banner"];
+
+    declare readonly bannerTarget: HTMLElement;
+
+    /**
+     * Toggles the visibility of the banner
+     */
+    toggle(dispatcher: Event | Element | null = null) {
+        this._toggle(undefined, dispatcher);
+    }
+
+    /**
+     * Shows the banner
+     */
+    show(dispatcher: Event | Element | null = null) {
+        this._toggle(true, dispatcher);
+    }
+
+    /**
+     * Hides the banner
+     */
+    hide(dispatcher: Event | Element | null = null) {
+        this._toggle(false, dispatcher);
+    }
+
+    /**
+     * Toggles the visibility of the banner element
+     * @param show Optional parameter that force shows/hides the element or toggles it if left undefined
+     */
+    private _toggle(
+        show?: boolean | undefined,
+        dispatcher: Event | Element | null = null
+    ) {
+        let toShow = show;
+        const isVisible =
+            this.bannerTarget.getAttribute("aria-hidden") === "false";
+
+        // if we're letting the class toggle, we need to figure out if the banner is visible manually
+        if (typeof toShow === "undefined") {
+            toShow = !isVisible;
+        }
+
+        // if the state matches the disired state, return without changing anything
+        if ((toShow && isVisible) || (!toShow && !isVisible)) {
+            return;
+        }
+
+        const dispatchingElement = this.getDispatcher(dispatcher);
+
+        // show/hide events trigger before toggling the class
+        const triggeredEvent = this.triggerEvent(
+            toShow ? "show" : "hide",
+            {
+                dispatcher: this.getDispatcher(dispatchingElement),
+            },
+            this.bannerTarget
+        );
+
+        // if this pre-show/hide event was prevented, don't attempt to continue changing the banner state
+        if (triggeredEvent.defaultPrevented) {
+            return;
+        }
+
+        this.bannerTarget.setAttribute(
+            "aria-hidden",
+            toShow ? "false" : "true"
+        );
+
+        if (!toShow) {
+            this.removeBannerOnHide();
+        }
+
+        this.triggerEvent(
+            toShow ? "shown" : "hidden",
+            {
+                dispatcher: dispatchingElement,
+            },
+            this.bannerTarget
+        );
+    }
+
+    /**
+     * Remove the element on hide if the `remove-when-hidden` flag is set
+     */
+    private removeBannerOnHide() {
+        if (this.data.get("remove-when-hidden") !== "true") {
+            return;
+        }
+
+        this.bannerTarget.addEventListener(
+            "s-banner:hidden",
+            () => {
+                this.element.remove();
+            },
+            { once: true }
+        );
+    }
+
+    /**
+     * Determines the correct dispatching element from a potential input
+     * @param dispatcher The event or element to get the dispatcher from
+     */
+    private getDispatcher(dispatcher: Event | Element | null = null): Element {
+        if (dispatcher instanceof Event) {
+            return <Element>dispatcher.target;
+        } else if (dispatcher instanceof Element) {
+            return dispatcher;
+        } else {
+            return this.element;
+        }
+    }
+}
+
+/**
+ * Helper to manually show an s-banner element via external JS
+ * @param element the element the `data-controller="s-banner"` attribute is on
+ */
+export function showBanner(element: HTMLElement) {
+    toggleBanner(element, true);
+}
+
+/**
+ * Helper to manually hide an s-banner element via external JS
+ * @param element the element the `data-controller="s-banner"` attribute is on
+ */
+export function hideBanner(element: HTMLElement) {
+    toggleBanner(element, false);
+}
+
+/**
+ * Helper to manually show an s-banner element via external JS
+ * @param element the element the `data-controller="s-banner"` attribute is on
+ * @param show whether to force show/hide the banner; toggles the banner if left undefined
+ */
+function toggleBanner(element: HTMLElement, show?: boolean | undefined) {
+    const controller = Stacks.application.getControllerForElementAndIdentifier(
+        element,
+        "s-banner"
+    ) as BannerController;
+
+    if (!controller) {
+        throw "Unable to get s-banner controller from element";
+    }
+
+    show ? controller.show() : controller.hide();
+}

package/lib/ts/controllers/s-toast.ts

@@ -0,0 +1,357 @@
+import * as Stacks from "../stacks";
+
+export class ToastController extends Stacks.StacksController {
+    static targets = ["toast", "initialFocus"];
+
+    declare readonly toastTarget: HTMLElement;
+    declare readonly initialFocusTargets: HTMLElement[];
+
+    private _boundClickFn!: (event: MouseEvent) => void;
+    private _boundKeypressFn!: (event: KeyboardEvent) => void;
+
+    private activeTimeout!: number;
+    private returnElement!: HTMLElement;
+
+    connect() {
+        this.validate();
+    }
+
+    /**
+     * Disconnects all added event listeners on controller disconnect
+     */
+    disconnect() {
+        this.unbindDocumentEvents();
+    }
+
+    /**
+     * Toggles the visibility of the toast
+     */
+    toggle(dispatcher: Event | Element | null = null) {
+        this._toggle(undefined, dispatcher);
+    }
+
+    /**
+     * Shows the toast
+     */
+    show(dispatcher: Event | Element | null = null) {
+        this._toggle(true, dispatcher);
+    }
+
+    /**
+     * Hides the toast
+     */
+    hide(dispatcher: Event | Element | null = null) {
+        this._toggle(false, dispatcher);
+    }
+
+    /**
+     * Validates the toast settings and attempts to set necessary internal variables
+     */
+    private validate() {
+        // check for returnElement support
+        const returnElementSelector = this.data.get("return-element");
+        if (returnElementSelector) {
+            this.returnElement = <HTMLElement>(
+                document.querySelector(returnElementSelector)
+            );
+
+            if (!this.returnElement) {
+                throw (
+                    "Unable to find element by return-element selector: " +
+                    returnElementSelector
+                );
+            }
+        }
+    }
+
+    /**
+     * Toggles the visibility of the toast element
+     * @param show Optional parameter that force shows/hides the element or toggles it if left undefined
+     */
+    private _toggle(
+        show?: boolean | undefined,
+        dispatcher: Event | Element | null = null
+    ) {
+        let toShow = show;
+        const isVisible =
+            this.toastTarget.getAttribute("aria-hidden") === "false";
+
+        // if we're letting the class toggle, we need to figure out if the toast is visible manually
+        if (typeof toShow === "undefined") {
+            toShow = !isVisible;
+        }
+
+        // if the state matches the disired state, return without changing anything
+        if ((toShow && isVisible) || (!toShow && !isVisible)) {
+            return;
+        }
+
+        const dispatchingElement = this.getDispatcher(dispatcher);
+
+        // show/hide events trigger before toggling the class
+        const triggeredEvent = this.triggerEvent(
+            toShow ? "show" : "hide",
+            {
+                returnElement: this.returnElement,
+                dispatcher: this.getDispatcher(dispatchingElement),
+            },
+            this.toastTarget
+        );
+
+        // if this pre-show/hide event was prevented, don't attempt to continue changing the toast state
+        if (triggeredEvent.defaultPrevented) {
+            return;
+        }
+
+        this.returnElement = triggeredEvent.detail.returnElement;
+        this.toastTarget.setAttribute("aria-hidden", toShow ? "false" : "true");
+
+        if (toShow) {
+            this.bindDocumentEvents();
+            this.hideAfterTimeout();
+
+            if (this.data.get("prevent-focus-capture") !== "true") {
+                this.focusInsideToast();
+            }
+        } else {
+            this.unbindDocumentEvents();
+            this.focusReturnElement();
+            this.removeToastOnHide();
+            this.clearActiveTimeout();
+        }
+
+        // check for transitionend support
+        const supportsTransitionEnd =
+            this.toastTarget.ontransitionend !== undefined;
+
+        // shown/hidden events trigger after toggling the class
+        if (supportsTransitionEnd) {
+            // wait until after the toast finishes transitioning to fire the event
+            this.toastTarget.addEventListener(
+                "transitionend",
+                () => {
+                    //TODO this is firing waaay to soon?
+                    this.triggerEvent(
+                        toShow ? "shown" : "hidden",
+                        {
+                            dispatcher: dispatchingElement,
+                        },
+                        this.toastTarget
+                    );
+                },
+                { once: true }
+            );
+        } else {
+            this.triggerEvent(
+                toShow ? "shown" : "hidden",
+                {
+                    dispatcher: dispatchingElement,
+                },
+                this.toastTarget
+            );
+        }
+    }
+
+    /**
+     * Listens for the s-toast:hidden event and focuses the returnElement when it is fired
+     */
+    private focusReturnElement() {
+        if (!this.returnElement) {
+            return;
+        }
+
+        this.toastTarget.addEventListener(
+            "s-toast:hidden",
+            () => {
+                // double check the element still exists when the event is called
+                if (
+                    this.returnElement &&
+                    document.body.contains(this.returnElement)
+                ) {
+                    this.returnElement.focus();
+                }
+            },
+            { once: true }
+        );
+    }
+
+    /**
+     * Remove the element on hide if the `remove-when-hidden` flag is set
+     */
+    private removeToastOnHide() {
+        if (this.data.get("remove-when-hidden") !== "true") {
+            return;
+        }
+
+        this.toastTarget.addEventListener(
+            "s-toast:hidden",
+            () => {
+                this.element.remove();
+            },
+            { once: true }
+        );
+    }
+
+    /**
+     * Hide the element after a delay
+     */
+    private hideAfterTimeout() {
+        if (
+            this.data.get("prevent-auto-hide") === "true" ||
+            this.data.get("hide-after-timeout") === "0"
+        ) {
+            return;
+        }
+
+        const timeout =
+            parseInt(this.data.get("hide-after-timeout") as string, 10) || 3000;
+
+        this.activeTimeout = window.setTimeout(() => this.hide(), timeout);
+    }
+
+    /**
+     * Cancels the activeTimeout
+     */
+    clearActiveTimeout() {
+        clearTimeout(this.activeTimeout);
+    }
+
+    /**
+     * Gets all elements within the toast that could receive keyboard focus.
+     */
+    private getAllTabbables() {
+        return Array.from(
+            this.toastTarget.querySelectorAll<HTMLElement>(
+                "[href], input, select, textarea, button, [tabindex]"
+            )
+        ).filter((el: Element) =>
+            el.matches(":not([disabled]):not([tabindex='-1'])")
+        );
+    }
+
+    /**
+     * Returns the first visible element in an array or `undefined` if no elements are visible.
+     */
+    private firstVisible(elements?: HTMLElement[]) {
+        // https://stackoverflow.com/a/21696585
+        return elements?.find((el) => el.offsetParent !== null);
+    }
+
+    /**
+     * Attempts to shift keyboard focus into the toast.
+     * If elements with `data-s-toast-target="initialFocus"` are present and visible, one of those will be selected.
+     * Otherwise, the first visible focusable element will receive focus.
+     */
+    private focusInsideToast() {
+        this.toastTarget.addEventListener(
+            "s-toast:shown",
+            () => {
+                const initialFocus =
+                    this.firstVisible(this.initialFocusTargets) ??
+                    this.firstVisible(this.getAllTabbables());
+                initialFocus?.focus();
+            },
+            { once: true }
+        );
+    }
+    /**
+     * Binds global events to the document for hiding toasts on user interaction
+     */
+    private bindDocumentEvents() {
+        // in order for removeEventListener to remove the right event, this bound function needs a constant reference
+        this._boundClickFn =
+            this._boundClickFn || this.hideOnOutsideClick.bind(this);
+        this._boundKeypressFn =
+            this._boundKeypressFn || this.hideOnEscapePress.bind(this);
+
+        document.addEventListener("mousedown", this._boundClickFn);
+        document.addEventListener("keyup", this._boundKeypressFn);
+    }
+
+    /**
+     * Unbinds global events to the document for hiding toasts on user interaction
+     */
+    private unbindDocumentEvents() {
+        document.removeEventListener("mousedown", this._boundClickFn);
+        document.removeEventListener("keyup", this._boundKeypressFn);
+    }
+
+    /**
+     * Forces the toast to hide if a user clicks outside of it or its reference element
+     */
+    private hideOnOutsideClick(e: Event) {
+        const target = <Node>e.target;
+        // check if the document was clicked inside either the toggle element or the toast itself
+        // note: .contains also returns true if the node itself matches the target element
+        if (
+            !this.toastTarget?.contains(target) &&
+            document.body.contains(target) &&
+            this.data.get("hide-on-outside-click") !== "false"
+        ) {
+            this._toggle(false, e);
+        }
+    }
+
+    /**
+     * Forces the toast to hide if the user presses escape while it, one of its childen, or the reference element are focused
+     */
+    private hideOnEscapePress(e: KeyboardEvent) {
+        // if the ESC key (27) wasn't pressed or if no toasts are showing, return
+        if (
+            e.which !== 27 ||
+            this.toastTarget.getAttribute("aria-hidden") === "true"
+        ) {
+            return;
+        }
+
+        this._toggle(false, e);
+    }
+
+    /**
+     * Determines the correct dispatching element from a potential input
+     * @param dispatcher The event or element to get the dispatcher from
+     */
+    private getDispatcher(dispatcher: Event | Element | null = null): Element {
+        if (dispatcher instanceof Event) {
+            return <Element>dispatcher.target;
+        } else if (dispatcher instanceof Element) {
+            return dispatcher;
+        } else {
+            return this.element;
+        }
+    }
+}
+
+/**
+ * Helper to manually show an s-toast element via external JS
+ * @param element the element the `data-controller="s-toast"` attribute is on
+ */
+export function showToast(element: HTMLElement) {
+    toggleToast(element, true);
+}
+
+/**
+ * Helper to manually hide an s-toast element via external JS
+ * @param element the element the `data-controller="s-toast"` attribute is on
+ */
+export function hideToast(element: HTMLElement) {
+    toggleToast(element, false);
+}
+
+/**
+ * Helper to manually show an s-toast element via external JS
+ * @param element the element the `data-controller="s-toast"` attribute is on
+ * @param show whether to force show/hide the toast; toggles the toast if left undefined
+ */
+function toggleToast(element: HTMLElement, show?: boolean | undefined) {
+    const controller = Stacks.application.getControllerForElementAndIdentifier(
+        element,
+        "s-toast"
+    ) as ToastController;
+
+    if (!controller) {
+        throw "Unable to get s-toast controller from element";
+    }
+
+    show ? controller.show() : controller.hide();
+}

package/lib/ts/index.ts

@@ -1,18 +1,22 @@
 import "../css/stacks.less";
 import {
+    BannerController,
     ExpandableController,
     ModalController,
     PopoverController,
     TableController,
     TabListController,
+    ToastController,
     TooltipController,
     UploaderController,
 } from "./controllers";
 import { application, StacksApplication } from "./stacks";
 
 // register all built-in controllers
+application.register("s-banner", BannerController);
 application.register("s-expandable-control", ExpandableController);
 application.register("s-modal", ModalController);
+application.register("s-toast", ToastController);
 application.register("s-navigation-tablist", TabListController);
 application.register("s-popover", PopoverController);
 application.register("s-table", TableController);

package/lib/ts/stacks.ts

@@ -1,4 +1,4 @@
-import * as Stimulus from "stimulus";
+import * as Stimulus from "@hotwired/stimulus";
 
 export class StacksApplication extends Stimulus.Application {
     static _initializing = true;

package/lib/tsconfig.json

@@ -1,8 +1,8 @@
 {
     "compilerOptions": {
         "strict": true,
-        "target": "es5",
-        "lib": ["dom", "es6", "dom.iterable", "scripthost"], // es6 stuff is polyfilled by stimulus
+        "target": "es6",
+        "lib": ["dom", "es6", "dom.iterable", "scripthost"],
         "outDir": "../dist",
         "sourceMap": true,
         "moduleResolution": "node",

package/package.json

@@ -5,7 +5,7 @@
     "type": "git",
     "url": "https://github.com/StackExchange/Stacks.git"
   },
-  "version": "1.6.6",
+  "version": "1.7.0",
   "files": [
     "dist",
     "lib"
@@ -22,8 +22,11 @@
     "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": "backstop test",
-    "approve": "backstop approve",
+    "test": "web-test-runner",
+    "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",
@@ -32,40 +35,50 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@popperjs/core": "^2.11.6",
-    "stimulus": "^2.0.0"
+    "@hotwired/stimulus": "^3.2.1",
+    "@popperjs/core": "^2.11.6"
   },
   "devDependencies": {
     "@11ty/eleventy": "^1.0.2",
-    "@highlightjs/cdn-assets": "^11.6.0",
-    "@stackoverflow/stacks-editor": "^0.8.2",
-    "@stackoverflow/stacks-icons": "^3.1.0",
-    "@typescript-eslint/eslint-plugin": "^5.42.0",
-    "@typescript-eslint/parser": "^5.46.0",
-    "backstopjs": "^6.1.4",
-    "concurrently": "^7.5.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",
+    "@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",
+    "@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",
     "docsearch.js": "^2.6.3",
     "eleventy-plugin-highlightjs": "^1.1.0",
     "eleventy-plugin-nesting-toc": "^1.3.0",
-    "eslint": "^8.29.0",
-    "eslint-config-prettier": "^8.5.0",
+    "eslint": "^8.31.0",
+    "eslint-config-prettier": "^8.6.0",
     "eslint-plugin-no-unsanitized": "^4.0.2",
     "jquery": "^3.6.1",
     "less-loader": "^11.1.0",
     "list.js": "^2.3.1",
     "markdown-it": "^13.0.1",
-    "mini-css-extract-plugin": "^2.6.1",
+    "mini-css-extract-plugin": "^2.7.2",
     "postcss-less": "^6.0.0",
-    "postcss-loader": "^7.0.1",
-    "prettier": "^2.7.1",
+    "postcss-loader": "^7.0.2",
+    "prettier": "^2.8.2",
+    "rollup-plugin-postcss": "^4.0.2",
     "stylelint": "^14.16.0",
     "stylelint-config-recommended": "^9.0.0",
     "stylelint-config-standard": "^29.0.0",
     "terser-webpack-plugin": "^5.3.6",
     "ts-loader": "^9.4.2",
-    "typescript": "^4.9.3",
+    "typescript": "^4.9.4",
     "webpack": "^5.75.0",
     "webpack-cli": "^5.0.0",
     "webpack-merge": "^5.8.0"
@@ -84,5 +97,8 @@
     "not and_uc > 0",
     "not Samsung > 0",
     "not Android > 0"
-  ]
+  ],
+  "overrides": {
+    "aria-query": "~5.0.0"
+  }
 }