Merge pull request #34 from Derugon/jquery

Add more jQuery plugins

jquery/confirmable.d.ts

@@ -0,0 +1,101 @@
+declare global {
+    interface JQuery {
+        confirmable: Confirmable;
+    }
+}
+
+interface Confirmable {
+    /**
+     * Enable inline confirmation for given clickable element (like `<a />` or `<button />`).
+     *
+     * An additional inline confirmation step being shown before the default action is carried out on
+     * click.
+     *
+     * Calling `.confirmable( { handler: function () { … } } )` will fire the handler only after the
+     * confirmation step.
+     *
+     * The element will have the `jquery-confirmable-element` class added to it when it's clicked for
+     * the first time, which has `white-space: nowrap;` and `display: inline-block;` defined in CSS.
+     * If the computed values for the element are different when you make it confirmable, you might
+     * encounter unexpected behavior.
+     *
+     * @param {Options} [options]
+     */
+    (options?: Partial<Options>): this;
+
+    /**
+     * Default options. Overridable primarily for internationalisation handling.
+     */
+    defaultOptions: Options;
+
+    handler(event: JQuery.Event, options: Options): void;
+}
+
+interface Options {
+    /**
+     * Optional selector used for jQuery event delegation.
+     */
+    delegate: string | null;
+
+    /**
+     * Events to hook to.
+     */
+    events: string;
+
+    /**
+     * Text to use for interface elements.
+     */
+    i18n: I18N;
+
+    /**
+     * Callback to fire when preparing confirmable buttons. It is fired separately for the 'Yes' and 'No' button.
+     * Receives the button jQuery object as the first parameter and 'yes' or 'no' as the second.
+     */
+    buttonCallback($button: JQuery): JQuery;
+
+    /**
+     * Callback to fire when the action is confirmed (user clicks the 'Yes' button).
+     */
+    handler: ((event: JQuery.Event) => void) | null;
+
+    /**
+     * Callback to fire when preparing confirmable interface.
+     * Receives the interface jQuery object as the only parameter.
+     */
+    wrapperCallback($interface: JQuery): JQuery;
+}
+
+// tslint:disable-next-line:interface-name
+interface I18N {
+    /**
+     * Text to use for the confirmation question.
+     */
+    confirm: string;
+
+    /**
+     * Text to use for the 'No' button.
+     */
+    no: string;
+
+    /**
+     * Title text to use for the 'No' button.
+     */
+    noTitle: string | undefined;
+
+    /**
+     * Word separator to place between the three text messages.
+     */
+    space: string;
+
+    /**
+     * Text to use for the 'Yes' button.
+     */
+    yes: string;
+
+    /**
+     * Title text to use for the 'Yes' button.
+     */
+    yesTitle: string | undefined;
+}
+
+export {};

jquery/footHovzer.d.ts

@@ -0,0 +1,33 @@
+declare global {
+    interface JQueryStatic {
+        /**
+         * Utility to stack stuff in an overlay fixed on the bottom of the page.
+         *
+         * Usage:
+         *
+         * ```js
+         * var hovzer = $.getFootHovzer();
+         * hovzer.$.append( $myCollection );
+         * hovzer.update();
+         * ```
+         *
+         * @private
+         * @returns {FootHovzer}
+         */
+        getFootHovzer(): FootHovzer;
+    }
+}
+
+interface FootHovzer {
+    /**
+     * The stack container.
+     */
+    $: JQuery;
+
+    /**
+     * Update dimensions of stack to account for changes in the subtree.
+     */
+    update(): void;
+}
+
+export {};

jquery/highlightText.d.ts

@@ -0,0 +1,42 @@
+declare global {
+    interface JQueryStatic {
+        highlightText: HighlightText;
+    }
+
+    interface JQuery {
+        /**
+         * Highlight certain text in current nodes (by wrapping it in `<span class="highlight">...</span>`).
+         *
+         * @param {string} matchString String to match
+         * @param {Options} [options]
+         * @returns {JQuery}
+         */
+        highlightText(matchString: string, options?: Options): this;
+    }
+}
+
+type Method = "prefixHighlight" | "prefixPlusComboHighlight" | "splitAndHighlight";
+
+interface HighlightText {
+    innerHighlight(node: Node, pat: string | RegExp): void;
+
+    prefixHighlight(node: Node, prefix: string): void;
+
+    prefixPlusComboHighlight(node: Node, prefix: string): void;
+
+    splitAndHighlight<T extends Node>(node: T, text: string): T;
+}
+
+interface Options {
+    /**
+     * Method of matching to use, one of:
+     *
+     * - 'splitAndHighlight': Split `matchString` on spaces, then match each word separately.
+     * - 'prefixHighlight': Match `matchString` at the beginning of text only.
+     * - 'prefixPlusComboHighlight': Match `matchString` plus any combining characters at
+     *   the beginning of text only.
+     */
+    method?: Method;
+}
+
+export {};

jquery/htmlform.d.ts

@@ -0,0 +1,21 @@
+declare global {
+    interface JQuery {
+        /**
+         * jQuery plugin to fade or snap to visible state.
+         *
+         * @param {boolean} [instantToggle=false]
+         * @returns {JQuery}
+         */
+        goIn(instantToggle?: boolean): this;
+
+        /**
+         * jQuery plugin to fade or snap to hiding state.
+         *
+         * @param {boolean} [instantToggle=false]
+         * @returns {JQuery}
+         */
+        goOut(instantToggle?: boolean): this;
+    }
+}
+
+export {};

jquery/index.d.ts

@@ -3,4 +3,13 @@ import "jquery";
 import "./client";
 import "./collapsibleTabs";
 import "./colorUtil";
+import "./confirmable";
+import "./footHovzer";
+import "./highlightText";
+import "./htmlform";
+import "./lengthLimit";
+import "./makeCollapsible";
+import "./spinner";
+import "./tablesorter";
 import "./textSelection";
+import "./updateTooltipAccessKeys";

jquery/lengthLimit.d.ts

@@ -0,0 +1,78 @@
+declare global {
+    interface JQueryStatic {
+        /**
+         * Utility function to trim down a string, based on byteLimit
+         * and given a safe start position. It supports insertion anywhere
+         * in the string, so "foo" to "fobaro" if limit is 4 will result in
+         * "fobo", not "foba". Basically emulating the native maxlength by
+         * reconstructing where the insertion occurred.
+         *
+         * @deprecated Use `require( 'mediawiki.String' ).trimByteLength` instead.
+         * @param {string} safeVal Known value that was previously returned by this
+         * function, if none, pass empty string.
+         * @param {string} newVal New value that may have to be trimmed down.
+         * @param {number} byteLimit Number of bytes the value may be in size.
+         * @param {FilterFunction} [filterFunction] Function to call on the string before assessing the length.
+         * @returns {TrimResult}
+         */
+        trimByteLength(
+            safeVal: string,
+            newVal: string,
+            byteLimit: number,
+            filterFunction?: FilterFunction
+        ): TrimResult;
+    }
+
+    interface JQuery {
+        /**
+         * Enforces a byte limit on an input field, assuming UTF-8 encoding, for situations
+         * when, for example, a database field has a byte limit rather than a character limit.
+         * Plugin rationale: Browser has native maxlength for number of characters (technically,
+         * UTF-16 code units), this plugin exists to limit number of bytes instead.
+         *
+         * Can be called with a custom limit (to use that limit instead of the maxlength attribute
+         * value), a filter function (in case the limit should apply to something other than the
+         * exact input value), or both. Order of parameters is important!
+         *
+         * @param {number} [limit] Limit to enforce, fallsback to maxLength-attribute,
+         *  called with fetched value as argument.
+         * @param {FilterFunction} [filterFunction] Function to call on the string before assessing the length.
+         * @returns {JQuery}
+         */
+        byteLimit(limit: number, filterFunction?: FilterFunction): this;
+        byteLimit(filterFunction?: FilterFunction): this;
+
+        /**
+         * Enforces a codepoint (character) limit on an input field.
+         *
+         * For unfortunate historical reasons, browsers' native maxlength counts [the number of UTF-16
+         * code units rather than Unicode codepoints] [1], which means that codepoints outside the Basic
+         * Multilingual Plane (e.g. many emojis) count as 2 characters each. This plugin exists to
+         * correct this.
+         *
+         * [1]: https://www.w3.org/TR/html5/sec-forms.html#limiting-user-input-length-the-maxlength-attribute
+         *
+         * Can be called with a custom limit (to use that limit instead of the maxlength attribute
+         * value), a filter function (in case the limit should apply to something other than the
+         * exact input value), or both. Order of parameters is important!
+         *
+         * @param {number} [limit] Limit to enforce, fallsback to maxLength-attribute,
+         *  called with fetched value as argument.
+         * @param {FilterFunction} [filterFunction] Function to call on the string before assessing the length.
+         * @returns {JQuery}
+         */
+        codePointLimit(limit: number, filterFunction?: FilterFunction): this;
+        codePointLimit(filterFunction?: FilterFunction): this;
+    }
+}
+
+interface FilterFunction {
+    (str: string): string;
+}
+
+interface TrimResult {
+    newVal: string;
+    trimmed: boolean;
+}
+
+export {};

jquery/makeCollapsible.d.ts

@@ -0,0 +1,53 @@
+declare global {
+    interface JQuery {
+        /**
+         * Enable collapsible-functionality on all elements in the collection.
+         *
+         * - Will prevent binding twice to the same element.
+         * - Initial state is expanded by default, this can be overridden by adding class
+         *   "mw-collapsed" to the "mw-collapsible" element.
+         * - Elements made collapsible have jQuery data "mw-made-collapsible" set to true.
+         * - The inner content is wrapped in a "div.mw-collapsible-content" (except for tables and lists).
+         *
+         * @param {Options} [options]
+         * @returns {JQuery}
+         */
+        makeCollapsible(options?: Options): this;
+    }
+}
+
+interface Options {
+    /**
+     * Elements to be used as togglers for this collapsible element. By default, if the collapsible
+     * element has an id attribute like 'mw-customcollapsible-XXX', elements with a **class**
+     * of 'mw-customtoggle-XXX' are made togglers for it.
+     */
+    $customTogglers?: JQuery;
+
+    /**
+     * Whether to collapse immediately. By default collapse only if the element has the 'mw-collapsed' class.
+     */
+    collapsed?: boolean;
+
+    /**
+     * Text used for the toggler, when clicking it would collapse the element.
+     * Default: the 'data-collapsetext' attribute of the collapsible element or the content of 'collapsible-collapse' message.
+     */
+    collapseText?: string;
+
+    /**
+     * Text used for the toggler, when clicking it would expand the element.
+     * Default: the 'data-expandtext' attribute of the collapsible element or the content of 'collapsible-expand' message.
+     */
+    expandText?: string;
+
+    /**
+     * Whether to use a "plain mode" when making the element collapsible - that is, hide entire tables
+     * and lists (instead of hiding only all rows but first of tables, and hiding each list item
+     * separately for lists) and don't wrap other elements in div.mw-collapsible-content.
+     * May only be used with custom togglers.
+     */
+    plainMode?: boolean;
+}
+
+export {};