@stackoverflow/stacks 0.73.1 → 0.76.0

package/LICENSE.MD

@@ -1,9 +1,9 @@
-The MIT License (MIT)
-
-Copyright 2017-2020 Stack Exchange Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+The MIT License (MIT)
+
+Copyright 2017-2020 Stack Exchange Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,47 +1,47 @@
-# Stacks
-
-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.
-
-The Stacks website documents:
-
-### Product
-- Semantic and accessible component markup
-- Cross-browser compatible Less / CSS
-- An [icon library](https://github.com/StackExchange/Stacks-Icons)
-
-### Email
-- Email templates & components
-
-Stacks documentation can be found at https://stackoverflow.design/
-
-## Table of contents
-
-- [Using Stacks](#using-stacks)
-- [Building Stacks](#building-stacks)
-- [Bugs and feature requests](#bugs-and-feature-requests)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Using Stacks
-Using Stacks is outlined in our [usage guidelines](https://stackoverflow.design/product/guidelines/using-stacks).
-
-## Building Stacks
-To contribute to Stacks documentation or its CSS library, you’ll need to build Stacks locally. View our [building guidelines](https://stackoverflow.design/product/guidelines/building).
-
-Having trouble getting these steps to work? Open [an issue](https://github.com/StackExchange/Stacks/issues/new) with a `setup` label.
-
-## 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)
-
-## 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).
-
-## Contributing
-If you’d like to contribute to Stacks, please read through our [contribution guidelines](/CONTRIBUTING.md). Included are directions for opening issues, coding standards, and notes on development.
-
-## License
-Code and documentation copyright 2017-2022 Stack Exchange, Inc and released under the [MIT License](/LICENSE.MD).
+# Stacks
+
+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.
+
+The Stacks website documents:
+
+### Product
+- Semantic and accessible component markup
+- Cross-browser compatible Less / CSS
+- An [icon library](https://github.com/StackExchange/Stacks-Icons)
+
+### Email
+- Email templates & components
+
+Stacks documentation can be found at https://stackoverflow.design/
+
+## Table of contents
+
+- [Using Stacks](#using-stacks)
+- [Building Stacks](#building-stacks)
+- [Bugs and feature requests](#bugs-and-feature-requests)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Using Stacks
+Using Stacks is outlined in our [usage guidelines](https://stackoverflow.design/product/guidelines/using-stacks).
+
+## Building Stacks
+To contribute to Stacks documentation or its CSS library, you’ll need to build Stacks locally. View our [building guidelines](https://stackoverflow.design/product/guidelines/building).
+
+Having trouble getting these steps to work? Open [an issue](https://github.com/StackExchange/Stacks/issues/new) with a `setup` label.
+
+## 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)
+
+## 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).
+
+## Contributing
+If you’d like to contribute to Stacks, please read through our [contribution guidelines](/CONTRIBUTING.md). Included are directions for opening issues, coding standards, and notes on development.
+
+## License
+Code and documentation copyright 2017-2022 Stack Exchange, Inc and released under the [MIT License](/LICENSE.MD).

package/dist/controllers/index.d.ts

@@ -0,0 +1,7 @@
+export { ExpandableController } from './s-expandable-control';
+export { hideModal, ModalController, showModal } from './s-modal';
+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';

package/dist/controllers/s-expandable-control.d.ts

@@ -0,0 +1,17 @@
+import * as Stacks from '../stacks';
+export declare class ExpandableController extends Stacks.StacksController {
+    private isCollapsed;
+    private events;
+    private isCheckable;
+    private isRadio;
+    private lastKeydownClickTimestamp;
+    initialize(): void;
+    _isCollapsedForClickable(): boolean;
+    _isCollapsedForCheckable(): boolean;
+    get controlledCollapsibles(): HTMLElement[];
+    _dispatchShowHideEvent(isShow: boolean): void;
+    _toggleClass(doAdd: boolean): void;
+    listener(e: Event): void;
+    connect(): void;
+    disconnect(): void;
+}

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

@@ -0,0 +1,97 @@
+import * as Stacks from "../stacks";
+export declare class ModalController extends Stacks.StacksController {
+    static targets: string[];
+    private modalTarget;
+    private initialFocusTargets;
+    private _boundClickFn;
+    private _boundKeypressFn;
+    private returnElement;
+    private _boundTabTrap;
+    connect(): void;
+    /**
+     * Disconnects all added event listeners on controller disconnect
+     */
+    disconnect(): void;
+    /**
+     * Toggles the visibility of the modal
+     */
+    toggle(dispatcher?: Event | Element | null): void;
+    /**
+     * Shows the modal
+     */
+    show(dispatcher?: Event | Element | null): void;
+    /**
+     * Hides the modal
+     */
+    hide(dispatcher?: Event | Element | null): void;
+    /**
+     * Validates the modal settings and attempts to set necessary internal variables
+     */
+    private validate;
+    /**
+     * Toggles the visibility of the modal element
+     * @param show Optional parameter that force shows/hides the element or toggles it if left undefined
+     */
+    private _toggle;
+    /**
+     * Listens for the s-modal: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 removeModalOnHide;
+    /**
+     * Gets all elements within the modal that could receive keyboard focus.
+     */
+    private getAllTabbables;
+    /**
+     * Returns the first visible element in an array or `undefined` if no elements are visible.
+     */
+    private firstVisible;
+    /**
+     * Returns the last visible element in an array or `undefined` if no elements are visible.
+     */
+    private lastVisible;
+    /**
+     * Attempts to shift keyboard focus into the modal.
+     * If elements with `data-s-modal-target="initialFocus"` are present and visible, one of those will be selected.
+     * Otherwise, the first visible focusable element will receive focus.
+     */
+    private focusInsideModal;
+    /**
+     * Returns keyboard focus to the modal if it has left or is about to leave.
+     */
+    private keepFocusWithinModal;
+    /**
+     * Binds global events to the document for hiding popovers on user interaction
+     */
+    private bindDocumentEvents;
+    /**
+     * Unbinds global events to the document for hiding popovers on user interaction
+     */
+    private unbindDocumentEvents;
+    /**
+     * Forces the popover to hide if a user clicks outside of it or its reference element
+     */
+    private hideOnOutsideClick;
+    /**
+     * Forces the popover 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-modal element via external JS
+ * @param element the element the `data-controller="s-modal"` attribute is on
+ */
+export declare function showModal(element: HTMLElement): void;
+/**
+ * Helper to manually hide an s-modal element via external JS
+ * @param element the element the `data-controller="s-modal"` attribute is on
+ */
+export declare function hideModal(element: HTMLElement): void;

package/dist/controllers/s-navigation-tablist.d.ts

@@ -0,0 +1,36 @@
+import * as Stacks from "../stacks";
+export declare class TabListController extends Stacks.StacksController {
+    private boundSelectTab;
+    private boundHandleKeydown;
+    connect(): void;
+    disconnect(): void;
+    /**
+     * Gets all tabs within the controller.
+     */
+    get tabTargets(): HTMLElement[];
+    /**
+     * Handles click events on individual tabs, causing them to be selected.
+     */
+    selectTab(event: MouseEvent): void;
+    /**
+     * Handles left and right arrow keydown events on individual tabs,
+     * selecting the adjacent tab corresponding to the event.
+     */
+    handleKeydown(event: KeyboardEvent): void;
+    /**
+     * Attempts to switch to a new tab, doing nothing if the tab is already selected or
+     * the s-navigation-tablist:select event is prevented.
+     */
+    private switchToTab;
+    /**
+     * Returns the currently selected tab or null if no tabs are selected.
+     */
+    get selectedTab(): HTMLElement | null;
+    /**
+     * Switches the tablist to the provided tab, updating the tabs and panels
+     * to reflect the change.
+     * @param selectedTab The tab to select. If `null` is provided or the element
+     * is not a valid tab, all tabs will be unselected.
+     */
+    set selectedTab(selectedTab: HTMLElement | null);
+}

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

@@ -0,0 +1,155 @@
+import * as Stacks from "../stacks";
+export declare abstract class BasePopoverController extends Stacks.StacksController {
+    private popper;
+    protected popoverElement: HTMLElement;
+    protected referenceElement: HTMLElement;
+    /**
+     * An attribute containing the ID of the popover element to render, e.g. aria-controls or aria-describedby.
+     */
+    protected abstract popoverSelectorAttribute: string;
+    /**
+     * Binds events to the document on element show
+     */
+    protected abstract bindDocumentEvents(): void;
+    /**
+     * Unbinds events on the document on element hide
+     */
+    protected abstract unbindDocumentEvents(): void;
+    /**
+     * Returns true if the if the popover is currently visible.
+     */
+    get isVisible(): boolean;
+    /**
+     * Gets whether the element is visible in the browser's viewport.
+     */
+    get isInViewport(): boolean;
+    protected get shouldHideOnOutsideClick(): boolean;
+    /**
+     * Initializes and validates controller variables
+     */
+    connect(): void;
+    /**
+     * Cleans up popper.js elements and disconnects all added event listeners
+     */
+    disconnect(): void;
+    /**
+     * Toggles the visibility of the popover
+     */
+    toggle(dispatcher?: Event | Element | null): void;
+    /**
+     * Shows the popover if not already visible
+     */
+    show(dispatcher?: Event | Element | null): void;
+    /**
+     * Hides the popover if not already hidden
+     */
+    hide(dispatcher?: Event | Element | null): void;
+    /**
+     * Binds document events for this popover and fires the shown event
+     */
+    protected shown(dispatcher?: Element | null): void;
+    /**
+     * Unbinds document events for this popover and fires the hidden event
+     */
+    protected hidden(dispatcher?: Element | null): void;
+    /**
+     * Generates the popover if not found during initialization
+     */
+    protected generatePopover(): HTMLElement | null;
+    /**
+     * Initializes the Popper for this instance
+     */
+    private initializePopper;
+    /**
+     * Validates the popover settings and attempts to set necessary internal variables
+     */
+    private validate;
+    /**
+     * Determines the correct dispatching element from a potential input
+     * @param dispatcher The event or element to get the dispatcher from
+     */
+    protected getDispatcher(dispatcher?: Event | Element | null): Element;
+    /**
+     * Schedules the popover to update on the next animation frame if visible
+     */
+    protected scheduleUpdate(): void;
+}
+export declare class PopoverController extends BasePopoverController {
+    static targets: never[];
+    protected popoverSelectorAttribute: string;
+    private boundHideOnOutsideClick;
+    private boundHideOnEscapePress;
+    /**
+     * Toggles optional classes in addition to BasePopoverController.shown
+     */
+    protected shown(dispatcher?: Element | null): void;
+    /**
+     * Toggles optional classes in addition to BasePopoverController.hidden
+     */
+    protected hidden(dispatcher?: Element | null): void;
+    /**
+     * Binds global events to the document for hiding popovers on user interaction
+     */
+    protected bindDocumentEvents(): void;
+    /**
+     * Unbinds global events to the document for hiding popovers on user interaction
+     */
+    protected unbindDocumentEvents(): void;
+    /**
+     * Forces the popover to hide if a user clicks outside of it or its reference element
+     * @param {Event} e - The document click event
+     */
+    private hideOnOutsideClick;
+    /**
+     * Forces the popover to hide if the user presses escape while it, one of its childen, or the reference element are focused
+     * @param {Event} e - The document keyup event
+     */
+    private hideOnEscapePress;
+    /**
+     * Toggles all classes on the originating element based on the `class-toggle` data
+     * @param {boolean=} show - A boolean indicating whether this is being triggered by a show or hide.
+     */
+    private toggleOptionalClasses;
+}
+/**
+ * Helper to manually show an s-popover element via external JS
+ * @param element the element the `data-controller="s-popover"` attribute is on
+ */
+export declare function showPopover(element: HTMLElement): void;
+/**
+ * Helper to manually hide an s-popover element via external JS
+ * @param element the element the `data-controller="s-popover"` attribute is on
+ */
+export declare function hidePopover(element: Element): void;
+/**
+ * Options to use when attaching a popover via `Stacks.attachPopover`.
+ * @see Stacks.attachPopover
+ */
+export interface PopoverOptions {
+    /**
+     * When true, the `click->s-popover#toggle` action will be attached to the controller element or reference element.
+     */
+    toggleOnClick?: boolean;
+    /**
+     * When set, `data-s-popover-placement` will be set to this value on the controller element.
+     */
+    placement?: string;
+    /**
+     * When true, the popover will appear immediately when the controller connects.
+     */
+    autoShow?: boolean;
+}
+/**
+ * Attaches a popover to an element and performs additional configuration.
+ * @param element the element that will receive the `data-controller="s-popover"` attribute.
+ * @param popover an element with the `.s-popover` class or HTML string containing a single element with the `.s-popover` class.
+ *                If the popover does not have a parent element, it will be inserted as a immediately after the reference element.
+ * @param options an optional collection of options to use when configuring the popover.
+ */
+export declare function attachPopover(element: Element, popover: Element | string, options?: PopoverOptions): void;
+/**
+ * Removes the popover controller from an element and removes the popover from the DOM.
+ * @param element the element that has the `data-controller="s-popover"` attribute.
+ * @returns The popover that was attached to the element.
+ */
+export declare function detachPopover(element: Element): HTMLElement | null;

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

@@ -0,0 +1,8 @@
+import * as Stacks from "../stacks";
+export declare class TableController extends Stacks.StacksController {
+    static targets: string[];
+    readonly columnTarget: Element;
+    readonly columnTargets: Element[];
+    setCurrentSort(headElem: Element, direction: "asc" | "desc" | "none"): void;
+    sort(evt: Event): void;
+}

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

@@ -0,0 +1,82 @@
+import { BasePopoverController } from "./s-popover";
+export interface TooltipOptions {
+    placement: string;
+}
+export declare class TooltipController extends BasePopoverController {
+    static targets: never[];
+    protected popoverSelectorAttribute: string;
+    private boundScheduleShow;
+    private boundHide;
+    private boundHideIfWithin;
+    private activeTimeout;
+    /**
+     * Binds mouseover and mouseout events in addition to BasePopoverController.connect
+     */
+    connect(): void;
+    /**
+     * Unbinds mouse events in addition to BasePopoverController.disconnect
+     */
+    disconnect(): void;
+    /**
+     * Attempts to show the tooltip popover so long as no other Stacks-managed popover is
+     * present on the page.
+     */
+    show(dispatcher?: Event | Element | null): void;
+    /**
+     * Sets up a tooltip popover show after a delay.
+     */
+    scheduleShow(dispatcher?: Event | Element | null): void;
+    /**
+     * Cancels the scheduled tooltip popover display and hides it if already displayed
+     */
+    hide(dispatcher?: Event | Element | null): void;
+    /**
+     * Applies data-s-tooltip-html-title and title attributes.
+     */
+    applyTitleAttributes(): HTMLElement | null;
+    /**
+     * Automatically hides the tooltip popover when a Stacks popover is shown anywhere on
+     * the page.
+     */
+    protected bindDocumentEvents(): void;
+    /**
+     * Unbinds all mouse events
+     */
+    protected unbindDocumentEvents(): void;
+    /**
+     * Attempts to generate a new tooltip popover from the title attribute if no popover
+     * was present when requested, otherwise throws an error.
+     */
+    protected generatePopover(): HTMLElement | null;
+    /**
+     * Hides the tooltip if is or is within the event's target.
+     * @param event An event object from s-popover:shown
+     */
+    private hideIfWithin;
+    /**
+     * Binds mouse events to show/hide on reference element hover
+     */
+    private bindMouseEvents;
+    /**
+     * Unbinds all mouse events
+     */
+    private unbindMouseEvents;
+    /**
+     * Generates an ID for tooltips created with setTooltip.
+     */
+    private static generateId;
+}
+/**
+ * Adds or updates a Stacks tooltip on a given element, initializing the controller if necessary
+ * @param element The element to add a tooltip to.
+ * @param html An HTML string to populate the tooltip with.
+ * @param options Options for rendering the tooltip.
+ */
+export declare function setTooltipHtml(element: Element, html: string, options?: TooltipOptions): void;
+/**
+ * Adds or updates a Stacks tooltip on a given element, initializing the controller if necessary
+ * @param element The element to add a tooltip to.
+ * @param text A plain text string to populate the tooltip with.
+ * @param options Options for rendering the tooltip.
+ */
+export declare function setTooltipText(element: Element, text: string, options?: TooltipOptions): void;

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

@@ -0,0 +1,48 @@
+import * as Stacks from "../stacks";
+export declare class UploaderController extends Stacks.StacksController {
+    static targets: string[];
+    private inputTarget;
+    private previewsTarget;
+    private uploaderTarget;
+    private boundDragEnter;
+    private boundDragLeave;
+    private static readonly FILE_DISPLAY_LIMIT;
+    private static readonly MAX_FILE_SIZE;
+    connect(): void;
+    disconnect(): void;
+    /**
+     * Handles rendering the file preview state on input change
+     */
+    handleInput(): void;
+    /**
+     * Resets the Uploader to initial state
+     */
+    reset(): void;
+    /**
+     * Set hide/show and disabled state on elements depending on preview state
+     * @param  {boolean} shouldPreview - Uploader is entering a preview state
+     */
+    private handleVisible;
+    /**
+     * Adds a DOM element to preview a selected file
+     * @param  {FilePreview} file
+     */
+    private addFilePreview;
+    /**
+     * Toggles display and disabled state for select elements on valid input
+     * @param  {boolean} active - Uploader is in active state (typically on 'dragenter')
+     */
+    private handleUploaderActive;
+    /**
+     * Converts the file data into a data URL
+     * @param  {File} file
+     * @returns an object containing a FilePreview object
+     */
+    private fileToDataURL;
+    /**
+     * Gets an array of FilePreviews from a FileList
+     * @param  {FileList|[]} files
+     * @returns an array of FilePreview objects from a FileList
+     */
+    private getDataURLs;
+}