Update to 1.41, fix types & cleanup docs

README.md

@@ -28,7 +28,7 @@ Edit your project's `tsconfig.json` file so that it includes
 ]
 ```
 
-You should be all set! `mw` will be available in the global scope. There is no need to put any import statements in the TypeScript source files. 
+You should be all set! `mw` will be available in the global scope. There is no need to put any import statements in the TypeScript source files.
 
 **If you find any errors or have suggestions for more specific typings, please open a PR or file an issue.**
 
@@ -58,4 +58,3 @@ import type { ApiEditPageParams, ApiParseParams } from "types-mediawiki/api_para
 ```
 
 Since it is just a type import, it doesn't generate any JavaScript. Hence, such imports can also be used in non-modular applications.
-

jquery/client.d.ts

@@ -1,5 +1,10 @@
 declare global {
     interface JQueryStatic {
+        /**
+         * User-agent detection
+         *
+         * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.client
+         */
         client: Client;
     }
 }
@@ -10,26 +15,30 @@ interface Client {
      *
      * The resulting client object will be in the following format:
      *
-     *     {
-     *         'name': 'firefox',
-     *         'layout': 'gecko',
-     *         'layoutVersion': 20101026,
-     *         'platform': 'linux'
-     *         'version': '3.5.1',
-     *         'versionBase': '3',
-     *         'versionNumber': 3.5,
-     *     }
+     * ```js
+     * {
+     *     'name': 'firefox',
+     *     'layout': 'gecko',
+     *     'layoutVersion': 20101026,
+     *     'platform': 'linux'
+     *     'version': '3.5.1',
+     *     'versionBase': '3',
+     *     'versionNumber': 3.5,
+     * }
+     * ```
      *
      * Example:
      *
-     *     if ( $.client.profile().layout == 'gecko' ) {
-     *         // This will only run in Gecko browsers, such as Mozilla Firefox.
-     *     }
+     * ```js
+     * if ( $.client.profile().layout == 'gecko' ) {
+     *     // This will only run in Gecko browsers, such as Mozilla Firefox.
+     * }
      *
-     *     var profile = $.client.profile();
-     *     if ( profile.layout == 'gecko' && profile.platform == 'linux' ) {
-     *         // This will only run in Gecko browsers on Linux.
-     *     }
+     * var profile = $.client.profile();
+     * if ( profile.layout == 'gecko' && profile.platform == 'linux' ) {
+     *     // This will only run in Gecko browsers on Linux.
+     * }
+     * ```
      *
      * Recognised browser names:
      *
@@ -67,11 +76,12 @@ interface Client {
      * - `solaris` (untested)
      * - `win`
      *
-     * @param {Object} [nav] An object with a 'userAgent' and 'platform' property.
+     * @param {ClientNavigator} [nav] An object with a 'userAgent' and 'platform' property.
      *  Defaults to the global `navigator` object.
-     * @return {Object} The client object
+     * @returns {ClientProfile} The client object
+     * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.client-method-profile
      */
-    profile(nav?: { userAgent: string; platform: string }): ClientProfile;
+    profile(nav?: ClientNavigator): ClientProfile;
 
     /**
      * Checks the current browser against a support map object.
@@ -82,53 +92,74 @@ interface Client {
      *
      * A browser map is in the following format:
      *
-     *     {
-     *         // Multiple rules with configurable operators
-     *         'msie': [['>=', 7], ['!=', 9]],
-     *         // Match no versions
-     *         'iphone': false,
-     *         // Match any version
-     *         'android': null
-     *     }
+     * ```js
+     * {
+     *     // Multiple rules with configurable operators
+     *     'msie': [['>=', 7], ['!=', 9]],
+     *     // Match no versions
+     *     'iphone': false,
+     *     // Match any version
+     *     'android': null
+     * }
+     * ```
      *
      * It can optionally be split into ltr/rtl sections:
      *
-     *     {
-     *         'ltr': {
-     *             'android': null,
-     *             'iphone': false
-     *         },
-     *         'rtl': {
-     *             'android': false,
-     *             // rules are not inherited from ltr
-     *             'iphone': false
-     *         }
+     * ```js
+     * {
+     *     'ltr': {
+     *         'android': null,
+     *         'iphone': false
+     *     },
+     *     'rtl': {
+     *         'android': false,
+     *         // rules are not inherited from ltr
+     *         'iphone': false
      *     }
+     * }
+     * ```
      *
-     * @param {Object} map Browser support map
-     * @param {Object} [profile] A client-profile object
+     * @param {ClientSupportMap} map Browser support map
+     * @param {ClientProfile} [profile] A client-profile object
      * @param {boolean} [exactMatchOnly=false] Only return true if the browser is matched,
      *  otherwise returns true if the browser is not found.
-     *
-     * @return {boolean} The current browser is in the support map
+     * @returns {boolean} The current browser is in the support map
+     * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.client-method-test
      */
-    test(map: any, profile?: ClientProfile, exactMatchOnly?: boolean): boolean;
+    test(map: ClientSupportMap, profile?: ClientProfile, exactMatchOnly?: boolean): boolean;
 }
 
+export interface ClientNavigator {
+    userAgent: string;
+    platform: string;
+}
+
+type ClientProfileName =
+    | "android"
+    | "chrome"
+    | "crios"
+    | "edge"
+    | "firefox"
+    | "fxios"
+    | "konqueror"
+    | "msie"
+    | "opera"
+    | "rekong"
+    | "safari"
+    | "silk";
+
+type ComparisonOperator = "==" | "===" | "!=" | "!==" | "<" | "<=" | ">" | ">=";
+type ClientSupportCondition = [ComparisonOperator, string | number];
+
+type UndirectedClientSupportMap = Partial<
+    Record<ClientProfileName, false | null | ClientSupportCondition[]>
+>;
+type ClientSupportMap =
+    | UndirectedClientSupportMap
+    | Record<"ltr" | "rtl", UndirectedClientSupportMap>;
+
 interface ClientProfile {
-    name:
-        | "android"
-        | "chrome"
-        | "crios"
-        | "edge"
-        | "firefox"
-        | "fxios"
-        | "konqueror"
-        | "msie"
-        | "opera"
-        | "rekong"
-        | "safari"
-        | "silk";
+    name: ClientProfileName;
     layout: "edge" | "gecko" | "khtml" | "presto" | "trident" | "webkit";
     layoutVersion: number;
     platform: "ipad" | "iphone" | "linux" | "mac" | "solaris" | "win";

jquery/collapsibleTabs.d.ts

@@ -13,13 +13,21 @@ declare global {
     }
 }
 
-/** A jQuery plugin that makes collapsible tabs for the Vector skin. */
+/**
+ * A jQuery plugin that makes collapsible tabs for the Vector skin.
+ */
 interface CollapsibleTabsOptions {
-    /** Optional tab selector. Defaults to `#p-views ul`. */
+    /**
+     * Optional tab selector. Defaults to `#p-views ul`.
+     */
     expandedContainer: string;
-    /** Optional menu item selector. Defaults to `#p-cactions ul`. */
+    /**
+     * Optional menu item selector. Defaults to `#p-cactions ul`.
+     */
     collapsedContainer: string;
-    /** Optional selector for tabs that are collapsible. Defaults to `li.collapsible`. */
+    /**
+     * Optional selector for tabs that are collapsible. Defaults to `li.collapsible`.
+     */
     collapsible: string;
     shifting: boolean;
     expandedWidth: number;

jquery/colorUtil.d.ts

@@ -4,27 +4,27 @@ declare global {
     }
 }
 
+type Color = [number, number, number];
+
 interface ColorUtil {
     /**
      * Parse CSS color strings looking for color tuples
      *
      * Based on highlightFade by Blair Mitchelmore
      * <http://jquery.offput.ca/highlightFade/>
      *
-     * @param {Array|string} color
-     * @return {Array}
+     * @param {Color|string} color
+     * @returns {Color}
      */
-    getRGB(color: string | number[]): number[];
+    getRGB<T extends Color>(color: string | T): T;
 
     /**
      * Named color map
      *
      * Based on Interface by Stefan Petre
      * <http://interface.eyecon.ro/>
-     *
-     * @property {Object}
      */
-    colors: Record<string, [number, number, number]>;
+    colors: Record<string, Color>;
 
     /**
      * Convert an RGB color value to HSL.
@@ -40,9 +40,9 @@ interface ColorUtil {
      * @param {number} r The red color value
      * @param {number} g The green color value
      * @param {number} b The blue color value
-     * @return {number[]} The HSL representation
+     * @returns {Color} The HSL representation
      */
-    rgbToHsl(r: number, g: number, b: number): number[];
+    rgbToHsl(r: number, g: number, b: number): Color;
 
     /**
      * Convert an HSL color value to RGB.
@@ -58,25 +58,30 @@ interface ColorUtil {
      * @param {number} h The hue
      * @param {number} s The saturation
      * @param {number} l The lightness
-     * @return {number[]} The RGB representation
+     * @returns {Color} The RGB representation
      */
-    hslToRgb(h: number, s: number, l: number): number[];
+    hslToRgb(h: number, s: number, l: number): Color;
 
     /**
      * Get a brighter or darker rgb() value string.
      *
      * Usage:
      *
-     *     $.colorUtil.getColorBrightness( 'red', +0.1 );
-     *     // > "rgb(255,50,50)"
-     *     $.colorUtil.getColorBrightness( 'rgb(200,50,50)', -0.2 );
-     *     // > "rgb(118,29,29)"
+     * ```js
+     * $.colorUtil.getColorBrightness( 'red', +0.1 );
+     * // > "rgb(255,50,50)"
+     * $.colorUtil.getColorBrightness( 'rgb(200,50,50)', -0.2 );
+     * // > "rgb(118,29,29)"
+     * ```
      *
-     * @param {Mixed} currentColor Current value in css
+     * @param {Color|string} currentColor Current value in css
      * @param {number} mod Wanted brightness modification between -1 and 1
-     * @return {string} Like `'rgb(r,g,b)'`
+     * @returns {string} Like `'rgb(r,g,b)'`
      */
-    getColorBrightness(currentColor: any, mod: number): `rgb(${number},${number},${number})`;
+    getColorBrightness(
+        currentColor: string | Color,
+        mod: number
+    ): `rgb(${number},${number},${number})`;
 }
 
 export {};

jquery/index.d.ts

@@ -1,6 +1,6 @@
 import "jquery";
 
-import "./textSelection";
-import "./collapsibleTabs";
 import "./client";
+import "./collapsibleTabs";
 import "./colorUtil";
+import "./textSelection";