@stackoverflow/stacks 1.6.7 → 1.7.1

package/README.md

@@ -24,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)
@@ -99,6 +100,44 @@ 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).
 

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;