@stackoverflow/stacks 1.6.6 → 1.7.0

package/README.md

@@ -1,5 +1,7 @@
 # Stacks
 
+[![ci status][gh-action-badge]][gh-action-url] [![npm version][npm-badge]][npm-url]
+
 Stacks is Stack Overflow’s design system. It includes the resources needed to create consistent, predictable interfaces and workflows that conform to Stack Overflow’s principles, design language, and best practices.
 
 Our documentation is built with Stacks itself, using its [immutable, atomic classes](http://johnpolacek.com/rethinking/) and components.
@@ -22,6 +24,7 @@ Stacks documentation can be found at https://stackoverflow.design/
 - [Building Stacks](#building-stacks)
 - [Linting Stacks](#linting-stacks)
 - [Testing Stacks](#testing-stacks)
+- [Releasing Stacks](#release-a-new-version-of-stacks)
 - [Bugs and feature requests](#bugs-and-feature-requests)
 - [Contributing](#contributing)
 - [License](#license)
@@ -55,9 +58,85 @@ npm run lint:format
 ```
 
 ## Testing Stacks
-Stacks has implemented visual regression testing with [Backstop](https://github.com/garris/BackstopJS). To test if your new feature introduces visual regressions, run `npm run test` in a new Terminal window while Stacks is running. After the tests have run, a new browser window with any regressions will show. If the regressions are desired, you can run `npm run approve` to establish the new baseline.
 
-Individual routes to test are found in [backstop.json](/backstop.json)
+Run all test suites by running:
+```sh
+npm test
+```
+### Unit/Component Tests
+
+Unit/Component tests are written with [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro).
+Please follow the library's principles and documentation to write tests.
+
+Stacks uses [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) and [Playwright](https://modern-web.dev/docs/test-runner/browser-launchers/playwright/) to run tests in a real browser context.
+
+Execute the unit/component tests suite by running:
+```sh
+npm run test:unit
+```
+or if you prefer watch mode run:
+```sh
+npm run test:unit:watch
+```
+
+### Visual Regression Tests
+
+**Prerequisite:** 
+In order to pull and upload baseline images you need to have `git lfs` installed in your local machine. Please follow [this guide](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage) to install that.
+
+
+This [Web Test Runner plugin](https://www.npmjs.com/package/@web/test-runner-visual-regression) is used to run visual regression tests. [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro).
+Visual regression tests end with this suffix `*.visual.test.ts`.
+
+Execute the visual regression tests suite by running:
+```sh
+npm run test:visual
+```
+
+Update the visual baseline via:
+```sh
+npm run test:visual:update
+```
+
+Failing tests (including diffs) can be found under `screenshots/[browser]/failed/` folders.
+
+## Releasing a new version of Stacks
+Stacks uses [Semantic Versioning](https://semver.org/), is distributed via [npm](https://www.npmjs.com/package/@stackoverflow/stacks), and publishes [release notes on Github](https://github.com/StackExchange/Stacks/releases). Follow the steps below to release a new version of Stacks.
+
+### Bump the version number
+```sh
+npm version [major | minor | patch]
+```
+
+### Push the new tag
+```sh
+git push && git push --tags
+```
+
+### Create release notes [on Github](https://github.com/StackExchange/Stacks/releases/new)
+
+1. Visit https://github.com/StackExchange/Stacks/releases/new
+1. Choose your new version from the "Choose a tag" dropdown
+1. Click "Generate release notes"
+1. Cleanup and complete the release notes
+    - Prominently mention any breaking changes, if applicable
+    - Include a "What's Changed" section in the release notes
+    - Mention significant bug fixes
+    - Mention new features
+    - Mention significant under-the-hood changes that could impact consumers
+
+### Ship your newly created version to [npm](https://www.npmjs.com/package/@stackoverflow/stacks)
+```sh
+npm publish
+```
+
+### Merge `develop` into `production` and push
+```sh
+git checkout production && git merge develop && git push
+```
+
+### Push the updated docs site
+Head to [Netlify](https://app.netlify.com), navigate to the Stacks overview, click on "Production deploys", and select "Deploy site" from the "Trigger deploy" dropdown.
 
 ## Bugs and feature requests
 Have a bug or feature request? First search existing or closed issues to make sure the issue hasn’t been noted yet. If not, review our [issue guidelines](/CONTRIBUTING.md#open-an-issue) for submitting [a bug report](/CONTRIBUTING.md#reporting-bugs) or [feature request](/CONTRIBUTING.md#feature-requests).
@@ -67,3 +146,8 @@ If you’d like to contribute to Stacks, please read through our [contribution g
 
 ## License
 Code and documentation copyright 2017-2022 Stack Exchange, Inc and released under the [MIT License](/LICENSE.MD).
+
+[gh-action-url]: https://github.com/StackExchange/Stacks/actions/workflows/main.yml
+[gh-action-badge]: https://github.com/StackExchange/Stacks/actions/workflows/main.yml/badge.svg?branch=develop
+[npm-url]: https://npmjs.org/package/@stackoverflow/stacks
+[npm-badge]: https://img.shields.io/npm/v/@stackoverflow/stacks.svg

package/dist/controllers/index.d.ts

@@ -1,5 +1,7 @@
 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";

package/dist/controllers/s-banner.d.ts

@@ -0,0 +1,41 @@
+import * as Stacks from "../stacks";
+export declare class BannerController extends Stacks.StacksController {
+    static targets: string[];
+    readonly bannerTarget: HTMLElement;
+    /**
+     * Toggles the visibility of the banner
+     */
+    toggle(dispatcher?: Event | Element | null): void;
+    /**
+     * Shows the banner
+     */
+    show(dispatcher?: Event | Element | null): void;
+    /**
+     * Hides the banner
+     */
+    hide(dispatcher?: Event | Element | null): void;
+    /**
+     * 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;
+    /**
+     * Remove the element on hide if the `remove-when-hidden` flag is set
+     */
+    private removeBannerOnHide;
+    /**
+     * Determines the correct dispatching element from a potential input
+     * @param dispatcher The event or element to get the dispatcher from
+     */
+    private getDispatcher;
+}
+/**
+ * Helper to manually show an s-banner element via external JS
+ * @param element the element the `data-controller="s-banner"` attribute is on
+ */
+export declare function showBanner(element: HTMLElement): void;
+/**
+ * Helper to manually hide an s-banner element via external JS
+ * @param element the element the `data-controller="s-banner"` attribute is on
+ */
+export declare function hideBanner(element: HTMLElement): void;

package/dist/controllers/s-toast.d.ts

@@ -0,0 +1,97 @@
+import * as Stacks from "../stacks";
+export declare class ToastController extends Stacks.StacksController {
+    static targets: string[];
+    readonly toastTarget: HTMLElement;
+    readonly initialFocusTargets: HTMLElement[];
+    private _boundClickFn;
+    private _boundKeypressFn;
+    private activeTimeout;
+    private returnElement;
+    connect(): void;
+    /**
+     * Disconnects all added event listeners on controller disconnect
+     */
+    disconnect(): void;
+    /**
+     * Toggles the visibility of the toast
+     */
+    toggle(dispatcher?: Event | Element | null): void;
+    /**
+     * Shows the toast
+     */
+    show(dispatcher?: Event | Element | null): void;
+    /**
+     * Hides the toast
+     */
+    hide(dispatcher?: Event | Element | null): void;
+    /**
+     * Validates the toast settings and attempts to set necessary internal variables
+     */
+    private validate;
+    /**
+     * 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;
+    /**
+     * Listens for the s-toast:hidden event and focuses the returnElement when it is fired
+     */
+    private focusReturnElement;
+    /**
+     * Remove the element on hide if the `remove-when-hidden` flag is set
+     */
+    private removeToastOnHide;
+    /**
+     * Hide the element after a delay
+     */
+    private hideAfterTimeout;
+    /**
+     * Cancels the activeTimeout
+     */
+    clearActiveTimeout(): void;
+    /**
+     * Gets all elements within the toast that could receive keyboard focus.
+     */
+    private getAllTabbables;
+    /**
+     * Returns the first visible element in an array or `undefined` if no elements are visible.
+     */
+    private firstVisible;
+    /**
+     * 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;
+    /**
+     * Binds global events to the document for hiding toasts on user interaction
+     */
+    private bindDocumentEvents;
+    /**
+     * Unbinds global events to the document for hiding toasts on user interaction
+     */
+    private unbindDocumentEvents;
+    /**
+     * Forces the toast to hide if a user clicks outside of it or its reference element
+     */
+    private hideOnOutsideClick;
+    /**
+     * Forces the toast to hide if the user presses escape while it, one of its childen, or the reference element are focused
+     */
+    private hideOnEscapePress;
+    /**
+     * Determines the correct dispatching element from a potential input
+     * @param dispatcher The event or element to get the dispatcher from
+     */
+    private getDispatcher;
+}
+/**
+ * Helper to manually show an s-toast element via external JS
+ * @param element the element the `data-controller="s-toast"` attribute is on
+ */
+export declare function showToast(element: HTMLElement): void;
+/**
+ * Helper to manually hide an s-toast element via external JS
+ * @param element the element the `data-controller="s-toast"` attribute is on
+ */
+export declare function hideToast(element: HTMLElement): void;