Compatibility with 1.39 (LTS)

- add various `@since`/`@deprecated` annotations for declarations added/modified/deprecated/removed with 1.40/1.41/1.42 - add `isoDate`/`url` tablesorter parsers, removed since 1.40 - add `jquery.tipsy` RL module, removed since 1.41 - add `mw.language.commafy`, removed since 1.40 - add missing `script` property of a RL module (not added recently, just an oversight)
wikimedia-gadgets · May 28, 2024 · 6712c9c · 6712c9c
1 parent 49ad52d
commit 6712c9c
Show file tree

Hide file tree

Showing 12 changed files with 141 additions and 3 deletions.
diff --git a/jquery/colorUtil.d.ts b/jquery/colorUtil.d.ts
@@ -1,6 +1,7 @@
 declare global {
     interface JQueryStatic {
         /**
+         * @deprecated Removed since 1.41.
          * @see https://doc.wikimedia.org/mediawiki-core/REL1_40/js/#!/api/jQuery.colorUtil
          */
         colorUtil: ColorUtil;

diff --git a/jquery/tablesorter.d.ts b/jquery/tablesorter.d.ts
@@ -33,9 +33,17 @@ export interface ParserMap {
     currency: "numeric";
     date: "numeric";
     IPAddress: "numeric";
+    /**
+     * @deprecated Removed since 1.40.
+     */
+    isoDate: "numeric";
     number: "numeric";
     text: "text";
     time: "numeric";
+    /**
+     * @deprecated Removed since 1.40.
+     */
+    url: "text";
     usLongDate: "numeric";
 }
 

diff --git a/jquery/tipsy.d.ts b/jquery/tipsy.d.ts
@@ -0,0 +1,78 @@
+declare global {
+    interface JQuery<TElement> {
+        /**
+         * @deprecated
+         * @deprecated Removed since 1.41.
+         */
+        tipsy: JQueryTipsy<TElement>;
+    }
+}
+
+type StringProvider<T = HTMLElement> = string | ((ctx: T) => string);
+type MethodsOf<T> = {
+    [P in keyof T]: T[P] extends (...args: unknown[]) => void ? P : never;
+}[keyof T];
+
+type NSDirection = "n" | "s" | "";
+type EWDirection = "e" | "w" | "";
+type Direction = `${NSDirection}${EWDirection}`;
+
+interface JQueryTipsy<T = HTMLElement> {
+    (options: true): Tipsy;
+    (options?: MethodsOf<Tipsy> | Options<T>): JQuery<T>;
+
+    defaults: Required<Options>;
+
+    /**
+     * Yields a closure of the supplied parameters, producing a function that takes
+     * no arguments and is suitable for use as an autogravity function like so:
+     *
+     * @param {number} margin (int) - distance from the viewable region edge that an
+     *  element should be before setting its tooltip's gravity to be away
+     *  from that edge.
+     * @param {Direction} prefer (string, e.g. `n`, `sw`, `w`) - the direction to prefer
+     *  if there are no viewable region edges effecting the tooltip's
+     *  gravity. It will try to vary from this minimally, for example,
+     *  if `sw` is preferred and an element is near the right viewable
+     *  region edge, but not the top edge, it will set the gravity for
+     *  that element's tooltip to be `se`, preserving the southern
+     *  component.
+     */
+    autoBounds(margin: number, prefer: Direction): Direction;
+    autoNS(): boolean;
+    autoWE(): boolean;
+    elementOptions<T extends Options>(ele: HTMLElement, options: T): T;
+}
+
+interface Options<T = HTMLElement> {
+    center?: boolean;
+    className?: StringProvider<T> | null;
+    delayIn?: number;
+    delayOut?: number;
+    fade?: boolean;
+    fallback?: string;
+    gravity?: StringProvider<T>;
+    html?: boolean;
+    live?: boolean;
+    offset?: number;
+    opacity?: number;
+    title?: StringProvider<T>;
+    trigger?: "hover" | "manual";
+}
+
+interface Tipsy<T = HTMLElement> {
+    $element: JQuery<T>;
+    enabled: boolean;
+    options: Required<Options>;
+
+    closeOnEsc(e: KeyboardEvent): void;
+    getTitle(): string;
+    fixTitle(): void;
+    hide(): void;
+    keyHandler(e: KeyboardEvent): void;
+    show(): void;
+    tip(): JQuery;
+    validate(): void;
+}
+
+export {};
diff --git a/mw/Api.d.ts b/mw/Api.d.ts
@@ -490,6 +490,7 @@ declare global {
              * are loaded. If all messages are known, the returned promise is resolved immediately.
              *
              * @since 1.27
+             * @since 1.42 - accepts a single string message as parameter.
              * @param {string|string[]} messages Messages to retrieve
              * @param {ApiQueryAllMessagesParams} [options] Additional parameters for the API call
              * @returns {JQuery.Promise<boolean>}
@@ -719,7 +720,7 @@ declare global {
             /**
              * Convenience method for `action=watch`.
              *
-             * @since 1.35 - expiry parameter can be passed when Watchlist Expiry is enabled
+             * @since 1.35 - expiry parameter can be passed when Watchlist Expiry is enabled.
              * @param {TypeOrArray<TitleLike>} pages Full page name or instance of {@link mw.Title}, or an
              *  array thereof. If an array is passed, the return value passed to the promise will also be an
              *  array of appropriate objects.

diff --git a/mw/Rest.d.ts b/mw/Rest.d.ts
@@ -92,6 +92,7 @@ declare global {
              *
              * Note: only sending `application/json` is currently supported.
              *
+             * @since 1.42 - body parameter is optional.
              * @param {string} path
              * @param {Object.<string, any>} [body]
              * @param {Object.<string, any>} [headers]

diff --git a/mw/Title.d.ts b/mw/Title.d.ts
@@ -131,6 +131,7 @@ declare global {
              * Note that this method will work for non-file titles but probably give nonsensical results.
              * A title like `User:Dr._J._Fail` will be returned as `Dr. J`! Use {@link getMainText} instead.
              *
+             * @since 1.40
              * @returns {string}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Title.html#getFileNameTextWithoutExtension
              */
@@ -144,6 +145,7 @@ declare global {
              * Note that this method will work for non-file titles but probably give nonsensical results.
              * A title like `User:Dr._J._Fail` will be returned as `Dr._J`! Use {@link getMain} instead.
              *
+             * @since 1.40
              * @returns {string}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Title.html#getFileNameWithoutExtension
              */

diff --git a/mw/language.d.ts b/mw/language.d.ts
@@ -58,6 +58,28 @@ declare global {
              */
             function bcp47(languageTag: string): string;
 
+            /**
+             * Apply pattern to format value as a string.
+             *
+             * Using patterns from {@link https://www.unicode.org/reports/tr35/#Number_Format_Patterns Unicode TR35}.
+             *
+             * @private
+             * @deprecated This function will be made private in a future release;
+             *  it is poorly named, corresponds to a deprecated function in core, and
+             *  its functionality should be rolled into convertNumber().
+             * @deprecated Removed since 1.40.
+             * @param {number} value
+             * @param {string} pattern Pattern string as described by Unicode TR35
+             * @param {number|null} [minimumGroupingDigits=null]
+             * @throws {Error} If unable to find a number expression in `pattern`.
+             * @return {string}
+             */
+            function commafy(
+                value: number,
+                pattern: string,
+                minimumGroupingDigits?: number | null
+            ): string;
+
             /**
              * Grammatical transformations, needed for inflected languages.
              * Invoked by putting `{{grammar:case|word}}` in a message.

diff --git a/mw/loader.d.ts b/mw/loader.d.ts
@@ -46,13 +46,20 @@ type ModuleScript =
     | string;
 
 interface ModuleRegistryEntry {
+    /**
+     * @since 1.41
+     */
     declarator?: ModuleDeclarator | null;
     dependencies: string[];
+    /**
+     * @since 1.41
+     */
     deprecationWarning?: string | null;
     group: number | null;
     messages?: ModuleMessages | null;
     module: Module;
     packageExports: any;
+    script?: ModuleScript | null;
     skip: string | null;
     source: string;
     state: "error" | "loaded" | "missing" | "registered" | "ready";
@@ -322,6 +329,7 @@ declare global {
              * Implement a module given a function which returns the components of the module
              *
              * @private
+             * @since 1.41
              * @param {ModuleDeclarator} declarator The declarator should return an array with the following keys:
              *
              * - 0. {string} module Name of module and current module version. Formatted
@@ -368,6 +376,8 @@ declare global {
              * Does not support mw.loader.store caching.
              *
              * @private
+             * @since 1.41 - deprecationWarning parameter can be passed.
+             * @deprecated since 1.41
              * @param {string} module
              * @param {ModuleScript} [script] Module code. This can be a function,
              *  a list of URLs to load via `<script src>`, a string for `domEval()`, or an
@@ -408,10 +418,10 @@ declare global {
              * the modules are registered.
              *
              * @private
+             * @since 1.41 - version can no longer be a number (timestamp).
              * @param {string|Array} modules Module name or array of arrays, each containing
              *  a list of arguments compatible with this method
              * @param {string|number} [version] Module version hash (falls backs to empty string)
-             *  Can also be a number (timestamp) for compatibility with MediaWiki 1.25 and earlier.
              * @param {Array<string|number>} [dependencies] Array of module names on which this module depends.
              * @param {string|null} [group=null] Group which the module is in
              * @param {string} [source="local"] Name of the source
@@ -538,6 +548,7 @@ declare global {
                 /**
                  * Construct a JSON-serializable object representing the content of the store.
                  *
+                 * @deprecated Removed since 1.41.
                  * @returns {JsonModuleStore} Module store contents.
                  */
                 function toJSON(): JsonModuleStore;

diff --git a/mw/storage.d.ts b/mw/storage.d.ts
@@ -63,6 +63,7 @@ interface SafeStorage {
     /**
      * Set an object value in device storage by JSON encoding.
      *
+     * @since 1.41 - returns a boolean indicating whether the value was set.
      * @param {string} key Key name to store under
      * @param {Object} value Object value to be stored
      * @param {number} [expiry] Number of seconds after which this item can be deleted

diff --git a/mw/tempUserCreated.d.ts b/mw/tempUserCreated.d.ts
@@ -3,6 +3,7 @@ declare global {
         /**
          * Respond to the creation of a temporary user.
          *
+         * @since 1.42
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.tempUserCreated.html
          */
         namespace tempUserCreated {

diff --git a/mw/user.d.ts b/mw/user.d.ts
@@ -25,6 +25,7 @@ export interface User {
      * where `value` contains only alphanumerical characters (a-z, A-Z, and 0-9), and `feature`
      * can also include hyphens.
      *
+     * @since 1.41
      * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.user.clientPrefs.html
      */
     clientPrefs: {
@@ -75,6 +76,7 @@ export interface User {
      * will be used for their account. It may also be used in previews. However, the account is not
      * created yet, and the name is not visible to other users.
      *
+     * @since 1.41
      * @returns {JQuery.Promise<string>} Promise resolved with the username if we succeeded,
      *  or resolved with `null` if we failed
      * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.user.html#.acquireTempUserName
@@ -110,6 +112,7 @@ export interface User {
     /**
      * Get date user first registered, if available.
      *
+     * @since 1.42
      * @returns {false|null|Date} False for anonymous users, null if data is
      *  unavailable, or Date for when the user registered. For temporary users
      *  that is when their temporary account was created.
@@ -194,6 +197,7 @@ export interface User {
     /**
      * Check whether the user is a normal non-temporary registered user.
      *
+     * @since 1.40
      * @returns {boolean}
      * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.user.html#.isNamed
      */
@@ -202,6 +206,7 @@ export interface User {
     /**
      * Check whether the user is an autocreated temporary user.
      *
+     * @since 1.40
      * @returns {boolean}
      * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.user.html#.isTemp
      */

diff --git a/mw/util.d.ts b/mw/util.d.ts
@@ -99,6 +99,7 @@ declare global {
             /**
              * Creates a detached portlet Element in the skin with no elements.
              *
+             * @since 1.41
              * @param {string} id of the new portlet.
              * @param {string} [label] of the new portlet.
              * @param {string} [before] selector of the element preceding the new portlet. If not passed
@@ -191,6 +192,7 @@ declare global {
             /**
              * Add content to the subtitle of the skin.
              *
+             * @since 1.40
              * @param {HTMLElement|string} nodeOrHTMLString
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.addSubtitle
              */
@@ -200,6 +202,7 @@ declare global {
              * Clears the entire subtitle if present in the page. Used for refreshing subtitle
              * after edit with response from parse API.
              *
+             * @since 1.40
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.clearSubtitle
              */
             function clearSubtitle(): void;
@@ -264,7 +267,8 @@ declare global {
              * \ { } ( ) | . ? * + - ^ $ [ ]
              * ```
              *
-             * @since 1.26; moved to {@link mw.util} in 1.34
+             * @since 1.26
+             * @since 1.34 - moved to {@link mw.util}.
              * @param {string} str String to escape
              * @returns {string} Escaped string
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.escapeRegExp
@@ -282,6 +286,7 @@ declare global {
              * mw.util.getArrayParam( 'foo', new URLSearchParams( '?foo[]=a&foo[]=b' ) ); // [ 'a', 'b' ]
              * mw.util.getArrayParam( 'foo', new URLSearchParams( '?foo=a' ) ); // null
              * ```
+             * @since 1.41
              * @param {string} param The parameter name.
              * @param {URLSearchParams} [params] Parsed URL parameters to search through, defaulting to the current browsing location.
              * @returns {string[]|null} Parameter value, or null if parameter was not found.
@@ -353,6 +358,7 @@ declare global {
              * This is used when testing for infinity in the context of expiries,
              * such as watchlisting, page protection, and block expiries.
              *
+             * @since 1.42
              * @param {string|null} str
              * @returns {boolean}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.isInfinity
@@ -435,6 +441,7 @@ declare global {
              *
              * This functionality has been adapted from `MediaWiki\User\TempUser\Pattern::isMatch()`
              *
+             * @since 1.40
              * @param {string} username
              * @returns {boolean}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.isTemporaryUser