fomantic-ui 2.9.3-beta.9 → 2.9.3

package/types/fomantic-ui-popup.d.ts

@@ -0,0 +1,523 @@
+declare namespace FomanticUI {
+    interface Popup {
+        settings: PopupSettings;
+
+        /**
+         * Shows popup.
+         */
+        (behavior: 'show'): JQuery;
+
+        /**
+         * Hides popup.
+         */
+        (behavior: 'hide'): JQuery;
+
+        /**
+         * Hides all visible pop ups on the page.
+         */
+        (behavior: 'hide all'): JQuery;
+
+        /**
+         * Returns current popup dom element.
+         */
+        (behavior: 'get popup'): JQuery;
+
+        /**
+         * Changes current popup content.
+         */
+        (behavior: 'change content', html: string): JQuery;
+
+        /**
+         * Toggles visibility of popup.
+         */
+        (behavior: 'toggle'): JQuery;
+
+        /**
+         * Returns whether popup is visible.
+         */
+        (behavior: 'is visible'): boolean;
+
+        /**
+         * Returns whether popup is hidden.
+         */
+        (behavior: 'is hidden'): boolean;
+
+        /**
+         * Returns whether popup is created and inserted into the page.
+         */
+        (behavior: 'exists'): boolean;
+
+        /**
+         * Adjusts popup when content size changes (only necessary for centered popups).
+         */
+        (behavior: 'reposition'): JQuery;
+
+        /**
+         * Repositions a popup.
+         */
+        (behavior: 'set position', position: number): JQuery;
+
+        /**
+         * Removes popup from the page.
+         */
+        (behavior: 'remove popup'): JQuery;
+
+        /**
+         * Removes popup from the page and removes all events.
+         */
+        (behavior: 'destroy'): JQuery;
+
+        <K extends keyof PopupSettings>(behavior: 'setting', name: K, value?: undefined, ): Partial<Pick<PopupSettings, keyof PopupSettings>>;
+        <K extends keyof PopupSettings>(behavior: 'setting', name: K, value: PopupSettings[K]): JQuery;
+        (behavior: 'setting', value: Partial<Pick<PopupSettings, keyof PopupSettings>>): JQuery;
+        (settings?: Partial<Pick<PopupSettings, keyof PopupSettings>>): JQuery;
+    }
+
+    /**
+     * @see {@link https://fomantic-ui.com/modules/popup.html#/settings}
+     */
+    interface PopupSettings {
+        // region Popup Settings
+
+        /**
+         * Can specify a DOM element that should be used as the popup.
+         * This is useful for including a pre-formatted popup.
+         * @default false
+         */
+        popup: false | string;
+
+        /**
+         * Whether all other popups should be hidden when this popup is opened.
+         * @default false
+         */
+        exclusive: boolean;
+
+        /**
+         * Whether to move popup to same offset container as target element when popup already exists on the page.
+         * Using a popup inside of an element without 'overflow:visible', like a sidebar, may require you to set this to 'false'.
+         * @default true
+         */
+        movePopup: boolean;
+
+        /**
+         * Whether popup should attach 'mutationObservers' to automatically run destroy when the element is removed from the page's DOM.
+         * @default true
+         */
+        observeChanges: boolean;
+
+        /**
+         * When the popup surpasses the boundary of this element, it will attempt to find another display position.
+         * @default window
+         */
+        boundary: Window | string;
+
+        /**
+         * Selector or jquery object specifying where the popup should be created.
+         * @default 'body'
+         */
+        context: string | JQuery;
+
+        /**
+         * Will automatically hide a popup on scroll event in this context.
+         * @default window
+         */
+        scrollContext: Window | string;
+
+        /**
+         * Number of pixels that a popup is allowed to appear outside the boundaries of its context.
+         * This allows for permissible rounding errors when an element is against the edge of its 'context'.
+         * @default 2
+         */
+        jitter: number;
+
+        /**
+         * Position that the popup should appear.
+         * @default 'top left'
+         */
+        position: string;
+
+        /**
+         * If given position should be used, regardless if popup fits.
+         * @default false
+         */
+        forcePosition: boolean;
+
+        /**
+         * If a popup is inline it will be created next to current element, allowing for local css rules to apply.
+         * It will not be removed from the DOM after being hidden.
+         * Otherwise popups will appended to body and removed after being hidden.
+         * @default false
+         */
+        inline: boolean;
+
+        /**
+         * Whether popup contents should be preserved in the page after being hidden, allowing it to re-appear slightly faster on subsequent loads.
+         * @default false
+         */
+        preserve: boolean;
+
+        /**
+         * Can be set to 'adjacent' or 'opposite' to prefer adjacent or opposite position if popup cannot fit on screen.
+         * @default 'opposite'
+         */
+        prefer: 'opposite' | 'adjacent';
+
+        /**
+         * When set to 'false', a popup will not appear and produce an error message if it cannot entirely fit on page.
+         * Setting this to a position like, 'right center' forces the popup to use this position as a last resort even if it is partially offstage.
+         * Setting this to 'true' will use the last attempted position.
+         * @default false
+         */
+        lastResort: boolean | string;
+
+        /**
+         * Event used to trigger popup.
+         * Can be either 'focus', 'click', 'hover', or 'manual'.
+         * Manual popups must be triggered with '$('.element').popup('show');'.
+         * @default 'hover'
+         */
+        on: 'hover' | 'focus' | 'click' | 'manual';
+
+        /**
+         * Delay in milliseconds before showing or hiding a popup on hover or focus.
+         * @default {}
+         */
+        delay: object; // TODO
+
+        /**
+         * Named transition to use when animating menu in and out.
+         * Alternatively you can provide an object to set individual values for hide/show transitions as well as hide/show duration.
+         * @default 'scale'
+         */
+        transition: string | object;
+
+        /**
+         * Duration of animation events.
+         * The value will be ignored when individual hide/show duration values are provided via the 'transition' setting.
+         * @default 200
+         */
+        duration: number;
+
+        /**
+         * When a target element is less than 2x this amount, the popup will appear with the arrow centered on the target element, instead of with the popup edge matching the target's edge.
+         * @default 20
+         */
+        arrowPixelsFromEdge: number;
+
+        /**
+         * Whether popup should set fluid popup variation width on load to avoid 'width: 100%' including padding.
+         * @default true
+         */
+        setFluidWidth: boolean;
+
+        /**
+         * Whether popup should not close on hover (useful for popup navigation menus).
+         * @default false
+         */
+        hoverable: boolean;
+
+        /**
+         * Whether popup should hide when clicking on the page, 'auto' only hides for popups without on: 'hover'.
+         * @default true
+         */
+        closable: boolean | 'auto';
+
+        /**
+         * When using on: 'hover' whether 'touchstart' events should be added to allow the popup to be triggered.
+         * @default true
+         */
+        addTouchEvents: boolean;
+
+        /**
+         * Whether popup should hide on scroll or touchmove, 'auto' only hides for popups without on: 'click'.
+         * Set this to 'false' to prevent mobile browsers from closing popups when you tap inside input fields.
+         * @default 'auto'
+         */
+        hideOnScroll: 'auto' | boolean;
+
+        /**
+         * If a selector or jQuery object is specified this allows the popup to be positioned relative to that element.
+         * @default false
+         */
+        target: false | string | JQuery;
+
+        /**
+         * Offset for distance of popup from element.
+         * @default 0
+         */
+        distanceAway: number;
+
+        /**
+         * Offset in pixels from calculated position.
+         * @default 0
+         */
+        offset: number;
+
+        /**
+         * Number of iterations before giving up search for popup position when a popup cannot fit on screen.
+         * @default 15
+         */
+        maxSearchDepth: number;
+
+        // endregion
+
+        // region Callbacks
+
+        /**
+         * Callback on popup element creation, with created popup.
+         */
+        onCreate(this: JQuery): void;
+
+        /**
+         * Callback immediately before Popup is removed from DOM.
+         */
+        onRemove(this: JQuery): void;
+
+        /**
+         * Callback before popup is shown.
+         * Returning 'false' from this callback will cancel the popup from showing.
+         */
+        onShow(this: JQuery): boolean;
+
+        /**
+         * Callback after popup is shown.
+         */
+        onVisible(this: JQuery): void;
+
+        /**
+         * Callback before popup is hidden.
+         * Returning 'false' from this callback will cancel the popup from hiding.
+         */
+        onHide(this: JQuery): boolean;
+
+        /**
+         * Callback after popup is hidden.
+         */
+        onHidden(this: JQuery): void;
+
+        /**
+         * Callback after popup cannot be placed on screen.
+         */
+        onUnplaceable(this: JQuery): void;
+
+        // endregion
+
+        // region Content Settings
+
+        /**
+         * Popup variation to use, can use multiple variations with a space delimiter.
+         */
+        variation: string;
+
+        /**
+         * Content to display.
+         */
+        content: string;
+
+        /**
+         * Title to display alongside content.
+         */
+        title: string;
+
+        /**
+         * HTML content to display instead of preformatted title and content.
+         */
+        html: string;
+
+        // endregion
+
+        // region DOM Settings
+
+        /**
+         * DOM Selectors used internally.
+         * Selectors used to find parts of a module.
+         */
+        selector: Popup.SelectorSettings;
+
+        /**
+         * Class names used to determine element state.
+         */
+        metadata: Popup.MetadataSettings;
+
+        /**
+         * Class names used to determine element state.
+         */
+        className: Popup.ClassNameSettings;
+
+        // endregion
+
+        // region Debug Settings
+
+        /**
+         * Name used in log statements
+         * @default 'Popup'
+         */
+        name: string;
+
+        /**
+         * Event namespace. Makes sure module teardown does not effect other events attached to an element.
+         * @default 'popup'
+         */
+        namespace: string;
+
+        /**
+         * Silences all console output including error messages, regardless of other debug settings.
+         * @default false
+         */
+        silent: boolean;
+
+        /**
+         * Debug output to console
+         * @default false
+         */
+        debug: boolean;
+
+        /**
+         * Show console.table output with performance metrics
+         * @default true
+         */
+        performance: boolean;
+
+        /**
+         * Debug output includes all internal behaviors
+         * @default false
+         */
+        verbose: boolean;
+
+        error: Popup.ErrorSettings;
+
+        // endregion
+    }
+
+    namespace Popup {
+        type SelectorSettings = Partial<Pick<Settings.Selectors, keyof Settings.Selectors>>;
+        type MetadataSettings = Partial<Pick<Settings.Metadatas, keyof Settings.Metadatas>>;
+        type ClassNameSettings = Partial<Pick<Settings.ClassNames, keyof Settings.ClassNames>>;
+        type ErrorSettings = Partial<Pick<Settings.Errors, keyof Settings.Errors>>;
+
+        namespace Settings {
+            interface Selectors {
+                /**
+                 * @default '.ui.popup'
+                 */
+                popup: string;
+            }
+        
+            interface Metadatas {
+                /**
+                 * @default 'activator'
+                 */
+                activator: string;
+
+                /**
+                 * @default 'content'
+                 */
+                content: string;
+
+                /**
+                 * @default 'html'
+                 */
+                html: string;
+
+                /**
+                 * @default 'offset'
+                 */
+                offset: string;
+
+                /**
+                 * @default 'position'
+                 */
+                position: string;
+
+                /**
+                 * @default 'title'
+                 */
+                title: string;
+
+                /**
+                 * @default 'variation'
+                 */
+                variation: string;
+            }
+        
+            interface ClassNames {
+                /**
+                 * @default 'active'
+                 */
+                active: string;
+
+                /**
+                 * @default 'basic'
+                 */
+                basic: string;
+
+                /**
+                 * @default 'animating'
+                 */
+                animating: string;
+
+                /**
+                 * @default 'dropdown'
+                 */
+                dropdown: string;
+
+                /**
+                 * @default 'fluid'
+                 */
+                fluid: string;
+
+                /**
+                 * @default 'loading'
+                 */
+                loading: string;
+
+                /**
+                 * @default 'ui popup'
+                 */
+                popup: string;
+
+                /**
+                 * @default 'top left center bottom right'
+                 */
+                position: string;
+
+                /**
+                 * @default 'visible'
+                 */
+                visible: string;
+
+                /**
+                 * @default 'visible'
+                 */
+                popupVisible: string;
+            }
+
+            interface Errors {
+                /**
+                 * @default 'The position you specified is not a valid position'
+                 */
+                invalidPosition: string;
+
+                /**
+                 * @default 'Popup does not fit within the boundaries of the viewport'
+                 */
+                cannotPlace: string;
+
+                /**
+                 * @default 'The method you called is not defined.'
+                 */
+                method: string;
+
+                /**
+                 * @default 'This module requires ui transitions'
+                 */
+                noTransition: string;
+
+                /**
+                 * @default 'The target or popup you specified does not exist on the page'
+                 */
+                notFound: string;
+            }
+        }
+    }
+}