@stackoverflow/stacks 0.75.0 → 1.0.0

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;
+}