@atlassian/aui 9.12.6 → 10.0.0-M02

package/entry/internal/deprecation.js

@@ -1 +1 @@
-import '@atlassian/aui/src/js/aui/internal/deprecation.js';
+import '@atlassian/aui/src/js/aui/internal/deprecation';

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@atlassian/aui",
     "description": "Atlassian User Interface library",
-    "version": "9.12.6",
+    "version": "10.0.0-M02",
     "author": "Atlassian Pty Ltd.",
     "homepage": "https://aui.atlassian.com",
     "license": "Apache-2.0",
@@ -51,9 +51,11 @@
         "underscore": "1.13.7"
     },
     "devDependencies": {
-        "@atlassian/aui-webpack-config": "3.0.1",
-        "@babel/core": "7.24.9",
-        "@babel/preset-env": "7.24.8",
+        "@atlassian/aui-webpack-config": "3.0.2",
+        "@babel/core": "7.25.8",
+        "@babel/preset-env": "7.25.8",
+        "@types/jqueryui": "1.12.23",
+        "@types/backbone": "1.4.22",
         "fs-extra": "9.1.0",
         "ignore-emit-webpack-plugin": "2.0.6",
         "jquery": "3.5.1",

package/src/js/aui/dialog.js

@@ -23,6 +23,7 @@ const ZINDEX_DIALOG_1 = 2600; // see also dialog.less
  * </pre>
  * @param options {object} [optional] Permitted options and defaults are as follows:
  * width (800), height (600), keypressListener (closes dialog on ESC).
+ * @returns {Popup}
 */
 function createPopup (options) {
     var defaults = {
@@ -80,7 +81,11 @@ function createPopup (options) {
      * Popup object
      * @class Popup
      * @static
-    */
+     * @property {function(): void} enable
+     * @property {function(): void} disable
+     * @property {function(): void} remove
+     * @property {function(): void} show
+     */
 
     //blanket for reference further down
     var blanket = $('.aui-blanket');
@@ -212,7 +217,10 @@ function createPopup (options) {
     return res;
 }
 
-// Scoping function
+/**
+ * Scoping function
+ * @type {(function(number, number, number): Dialog)|*}
+ */
 var Dialog = (function () {
     /**
      * @class Button

package/src/js/aui/internal/deprecation.ts

@@ -0,0 +1,368 @@
+import globalize from './globalize';
+
+type ArbitraryFunction = () => unknown;
+
+type SelectorMap = {
+    selector: string,
+    options?: DeprecationOptions,
+}
+
+/**
+ * Purely to reflect the existing state of the code, not ideal.
+ */
+export type DeprecationOptions = {
+    /**
+     * the version this has been deprecated since
+     */
+    sinceVersion?: string;
+    /**
+     * the version this will be removed in
+     */
+    removeInVersion?: string;
+    /**
+     * the name of an alternative to use
+     */
+    alternativeName?: string;
+    /**
+     * extra information to be printed at the end of the deprecation log
+     */
+    extraInfo?: string;
+    /**
+     * an extra object that will be printed at the end
+     */
+    extraObject?: object | string;
+    /**
+     * a human-readable name to show in the deprecation message. If not provided, it is inferred from the function or object being deprecated.
+     */
+    displayName?: string;
+    /**
+     * type of the deprecation to append to the start of the deprecation message. e.g. JS or CSS
+     */
+    deprecationType?: string;
+};
+
+// eslint-disable-next-line @typescript-eslint/unbound-method -- Leaving behaviour identical for now
+const has = Object.prototype.hasOwnProperty;
+const deprecationCalls: (string | string[])[] = [];
+
+function toSentenceCase (name: string): string {
+    if (!name) {
+        return '';
+    }
+    name = '' + name;
+
+    return name.charAt(0).toUpperCase() + name.substring(1);
+}
+
+function getDeprecatedLocation (printFrameOffset: number) {
+    const error = new Error();
+
+    let stacktraceString: string | undefined = error.stack ??
+        // @ts-expect-error -- preserving the legacy, not sure what .stacktrace would exist on, guessing the type
+        (error.stacktrace as string | undefined);
+    stacktraceString = (stacktraceString?.replace(/^Error\n/, '')) ?? '';
+
+    const stacktrace = stacktraceString.split('\n');
+    return stacktrace[printFrameOffset + 2];
+}
+
+function logger(...args: unknown[]): void {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- JS test DOM environments
+    if (typeof console !== 'undefined' && console.warn) {
+        Function.prototype.apply.call(console.warn, console, args);
+    }
+}
+
+/**
+ * Return a function that logs a deprecation warning to the console the first time it is called from a certain location.
+ * It will also print the stack frame of the calling function.
+ *
+ * @param {string} displayName the name of the thing being deprecated
+ * @param {DeprecationOptions} options
+ * @return {Function} that logs the warning and stack frame of the calling function. Takes in an optional parameter for the offset of
+ * the stack frame to print, the default is 0. For example, 0 will log it for the line of the calling function,
+ * -1 will print the location the logger was called from
+ */
+const getShowDeprecationMessagePublic = (displayName: string, options: DeprecationOptions): ArbitraryFunction => {
+    return getShowDeprecationMessageInternal(displayName, options);
+}
+
+/**
+ * Return a function that logs a deprecation warning to the console the first time it is called from a certain location.
+ * It will also print the stack frame of the calling function.
+ *
+ * @param {string | symbol | number | Function} displayName the name of the thing being deprecated
+ * @param {DeprecationOptions} [options]
+ * @return {Function} that logs the warning and stack frame of the calling function. Takes in an optional parameter for the offset of
+ * the stack frame to print, the default is 0. For example, 0 will log it for the line of the calling function,
+ * -1 will print the location the logger was called from
+ */
+function getShowDeprecationMessageInternal(displayName: string | ArbitraryFunction, options?: DeprecationOptions):  ArbitraryFunction {
+    // This can be used internally to pas in a showmessage fn
+    if (typeof displayName === 'function') {
+        return displayName;
+    }
+
+    let called = false;
+    options = options ?? {};
+
+    return function (printFrameOffset?: number): void {
+        let deprecatedLocation = getDeprecatedLocation(printFrameOffset ? printFrameOffset : 1) ?? '';
+        // Only log once if the stack frame doesn't exist to avoid spamming the console/test output
+        if (!called || !deprecationCalls.includes(deprecatedLocation)) {
+            deprecationCalls.push(deprecatedLocation);
+
+            called = true;
+
+            const deprecationType = options.deprecationType ?? '';
+
+            let message = 'DEPRECATED ' + deprecationType + '- ' + toSentenceCase(displayName) +
+                ' has been deprecated' + (options.sinceVersion ? ' since ' + options.sinceVersion : '') +
+                ' and will be removed in ' + (options.removeInVersion ?? 'a future release') + '.';
+
+            if (options.alternativeName) {
+                message += ' Use ' + options.alternativeName + ' instead. ';
+            }
+
+            if (options.extraInfo) {
+                message += ' ' + options.extraInfo;
+            }
+
+            if (deprecatedLocation === '') {
+                deprecatedLocation = ' \n ' + 'No stack trace of the deprecated usage is available in your current browser.';
+            } else {
+                deprecatedLocation = ' \n ' + String(deprecatedLocation);
+            }
+
+            if (options.extraObject) {
+                message += '\n';
+                logger(message, options.extraObject, deprecatedLocation);
+            } else {
+                logger(message, deprecatedLocation);
+            }
+        }
+    };
+}
+
+function logCssDeprecation (selectorMap: SelectorMap, newNode: Node) {
+    let displayName = selectorMap.options?.displayName;
+    displayName = displayName ? ' (' + displayName + ')' : '';
+
+    const options: DeprecationOptions = Object.assign({
+        deprecationType: 'CSS',
+        extraObject: newNode,
+    }, selectorMap.options);
+
+    getShowDeprecationMessageInternal('\'' + selectorMap.selector + '\' pattern' + displayName, options)();
+}
+
+/**
+ * Returns a wrapped version of the function that logs a deprecation warning when the function is used.
+ * @param {Function} fn the fn to wrap
+ * @param {string} displayName the name of the fn to be displayed in the message
+ * @param {DeprecationOptions} options
+ * @return {Function} wrapping the original function
+ */
+function deprecateFunctionExpression(fn: ArbitraryFunction, displayName: string, options: DeprecationOptions): ArbitraryFunction {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Just in case someone outside AUI is using it
+    options = options ?? {};
+    options.deprecationType = options.deprecationType ?? 'JS';
+
+    const showDeprecationMessage = getShowDeprecationMessageInternal(displayName || fn.name || 'this function', options);
+    return function (...args: unknown[]) {
+        showDeprecationMessage();
+        // @ts-expect-error Sorry TS, don't want to change this behaviour just yet in case of side effects
+        return fn.apply(this, args);
+    };
+}
+
+/**
+ * Returns a wrapped version of the constructor that logs a deprecation warning when the constructor is instantiated.
+ * @param {Function} constructorFn the constructor function to wrap
+ * @param {string} displayName the name of the fn to be displayed in the message
+ * @param {DeprecationOptions} options
+ * @return {Function} wrapping the original function
+ */
+function deprecateConstructor(constructorFn: ArbitraryFunction, displayName: string, options: DeprecationOptions): ArbitraryFunction {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Just in case someone outside AUI is using it
+    options = options ?? {};
+    options.deprecationType = options.deprecationType ?? 'JS';
+
+    const deprecatedConstructor = deprecateFunctionExpression(constructorFn, displayName, options);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    deprecatedConstructor.prototype = constructorFn.prototype;
+    Object.assign(deprecatedConstructor, constructorFn) //copy static methods across;
+
+    return deprecatedConstructor;
+}
+
+/**
+* Wraps a "value" object property in a deprecation warning in browsers supporting Object.defineProperty
+* @param {Object} obj the object containing the property
+* @param {string} prop the name of the property to deprecate
+* @param {DeprecationOptions} [options]
+*/
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- This is easier to read
+function deprecateValueProperty<T extends object, K extends keyof T & string>(obj: T, prop: K, options?: DeprecationOptions) {
+    let oldVal = obj[prop];
+    options = options ?? {};
+    options.deprecationType = options.deprecationType ?? 'JS';
+
+    const displayNameOrShowMessageFn = options.displayName ?? prop;
+    const showDeprecationMessage = getShowDeprecationMessageInternal(displayNameOrShowMessageFn, options);
+    Object.defineProperty(obj, prop, {
+        get: function (): T[K] {
+            showDeprecationMessage();
+            return oldVal;
+        },
+        set: function (val: T[K]): T[K] {
+            oldVal = val;
+            showDeprecationMessage();
+            return val;
+        }
+    });
+}
+
+/**
+ * Wraps an object property in a deprecation warning, if possible. functions will always log warnings, but other
+ * types of properties will only log in browsers supporting Object.defineProperty
+ * @param {Object} object the object containing the property
+ * @param {string} propertyKey the name of the property to deprecate
+ * @param {DeprecationOptions} options
+ */
+function deprecateObjectProperty<T extends object>(object: T, propertyKey: string & keyof T, options: DeprecationOptions) {
+    if (typeof object[propertyKey] === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Just in case someone outside AUI is using it
+        options = options ?? {};
+        options.deprecationType = options.deprecationType ?? 'JS';
+
+        const displayNameOrShowMessageFn = options.displayName ?? propertyKey;
+        // @ts-expect-error -- Maybe a TypeScript wizard can figure out something
+        // better than me so TS is happy. We only care it's a function.
+        object[propertyKey] = deprecateFunctionExpression(object[propertyKey], displayNameOrShowMessageFn, options);
+    } else {
+        deprecateValueProperty(object, propertyKey, options);
+    }
+}
+
+type DeprecationOptionsWithAltNamePrefix = DeprecationOptions & {
+    /**
+     * a prefix for the alternative property name. Used to generate alternativeName per property.
+     */
+    alternativeNamePrefix?: string
+}
+
+/**
+ * Wraps all an objects properties in a deprecation warning, if possible. functions will always log warnings, but other
+ * types of properties will only log in browsers supporting Object.defineProperty
+ * @param {Object} obj the object to be wrapped
+ * @param {string} objDisplayPrefix the object's prefix to be used in logs
+ * @param {DeprecationOptionsWithAltNamePrefix} options
+ */
+function deprecateAllProperties(obj: object, objDisplayPrefix: string, options: DeprecationOptionsWithAltNamePrefix) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Just in case someone outside AUI is using it
+    options = options ?? {};
+    for (const attr in obj) {
+        if (has.call(obj, attr)) {
+            options.deprecationType = options.deprecationType ?? 'JS';
+            options.displayName = objDisplayPrefix + attr;
+            options.alternativeName = options.alternativeNamePrefix && (options.alternativeNamePrefix + attr);
+            deprecateObjectProperty(obj,
+                // @ts-expect-error -- We're very safely checking this is actually an attribute on the object
+                attr,
+                Object.assign({}, options));
+        }
+    }
+}
+
+function matchesSelector(node: Node, selector: string) {
+    if (node instanceof Element) {
+        return node.matches(selector);
+    }
+    return false;
+}
+
+function handleAddingSelector(options?: DeprecationOptions) {
+    return function (selector: string) {
+        const selectorMap: SelectorMap = {
+            selector: selector,
+            options: options,
+        };
+
+        // Search if matches have already been added
+        const matches = document.querySelectorAll(selector);
+        for (const match of matches) {
+            logCssDeprecation(selectorMap, match);
+        }
+
+        observeFutureChange(selectorMap);
+    };
+}
+
+/**
+ * Return a function that logs a deprecation warning to the console the first time it is called from a certain location.
+ * It will also print the stack frame of the calling function.
+ */
+function deprecateCSS(selectors: string | string[], options?: DeprecationOptions): void {
+    if (typeof selectors === 'string') {
+        selectors = [selectors];
+    }
+
+    selectors.forEach(handleAddingSelector(options));
+}
+
+function testAndHandleDeprecation(newNode: Node) {
+    return function (selectorMap: SelectorMap) {
+        if (matchesSelector(newNode, selectorMap.selector)) {
+            logCssDeprecation(selectorMap, newNode);
+        }
+    };
+}
+
+const deprecatedSelectorMap: SelectorMap[] = [];
+let observer: MutationObserver | undefined = undefined;
+
+function observeFutureChange(selectorMap: SelectorMap) {
+    deprecatedSelectorMap.push(selectorMap);
+
+    // Lazily instantiate a mutation observer because they're expensive.
+    if (observer === undefined) {
+        observer = new MutationObserver(function (mutations) {
+            mutations.forEach(function (mutation) {
+                // TODO - should this also look at class changes, if possible?
+                const addedNodes = mutation.addedNodes;
+
+                for (const newNode of addedNodes) {
+                    if (newNode.nodeType === 1) {
+                        deprecatedSelectorMap.forEach(testAndHandleDeprecation(newNode));
+                    }
+                }
+            });
+        });
+
+        const config = {
+            childList: true,
+            subtree: true
+        };
+
+        observer.observe(document, config);
+    }
+}
+
+globalize('deprecate', {
+    fn: deprecateFunctionExpression,
+    construct: deprecateConstructor,
+    css: deprecateCSS,
+    prop: deprecateObjectProperty,
+    obj: deprecateAllProperties,
+    getMessageLogger: getShowDeprecationMessagePublic
+});
+
+export {
+    deprecateFunctionExpression as fn,
+    deprecateConstructor as construct,
+    deprecateCSS as css,
+    deprecateObjectProperty as prop,
+    deprecateAllProperties as obj,
+    getShowDeprecationMessagePublic as getMessageLogger
+};

package/src/js/aui/internal/select/suggestions-model.js

@@ -1,68 +1,90 @@
+/**
+ * @typedef {Object} Suggestion
+ * @property {string|number} id
+ */
 
+/**
+ * @typedef {Object} SuggestionsModelType
+ * @property {(oldSuggestions: Suggestion[]) => void} onChange
+ * @property {() => void} onHighlightChange
+ * @property {(index: number) => Suggestion|undefined} get
+ * @property {(suggestions?: Suggestion[]) => SuggestionsModelType} set
+ * @property {() => number} getNumberOfResults
+ * @property {(toHighlight?: Suggestion) => SuggestionsModelType} setHighlighted
+ * @property {(index: number) => SuggestionsModelType} highlight
+ * @property {() => SuggestionsModelType} highlightPrevious
+ * @property {() => SuggestionsModelType} highlightNext
+ * @property {() => Suggestion|undefined} highlighted
+ * @property {() => number} highlightedIndex
+ */
+
+/**
+ * @returns {SuggestionsModelType}
+ */
 function SuggestionsModel () {
-    this._suggestions = [];
-    this._activeIndex = -1;
-}
+    return {
+        _suggestions: [],
+        _activeIndex: -1,
 
-SuggestionsModel.prototype = {
-    onChange: function () {},
+        onChange: function () {},
 
-    onHighlightChange: function () {},
+        onHighlightChange: function () {},
 
-    get: function (index) {
-        return this._suggestions[index];
-    },
+        get: function (index) {
+            return this._suggestions[index];
+        },
 
-    set: function (suggestions) {
-        var oldSuggestions = this._suggestions;
-        this._suggestions = suggestions || [];
-        this.onChange(oldSuggestions);
-        return this;
-    },
+        set: function (suggestions) {
+            var oldSuggestions = this._suggestions;
+            this._suggestions = suggestions || [];
+            this.onChange(oldSuggestions);
+            return this;
+        },
 
-    getNumberOfResults: function () {
-        return this._suggestions.length;
-    },
+        getNumberOfResults: function () {
+            return this._suggestions.length;
+        },
 
-    setHighlighted: function (toHighlight) {
-        if (toHighlight) {
-            for (var i = 0; i < this._suggestions.length; i++) {
-                if (this._suggestions[i].id === toHighlight.id) {
-                    this.highlight(i);
+        setHighlighted: function (toHighlight) {
+            if (toHighlight) {
+                for (var i = 0; i < this._suggestions.length; i++) {
+                    if (this._suggestions[i].id === toHighlight.id) {
+                        this.highlight(i);
+                    }
                 }
             }
-        }
 
-        return this;
-    },
+            return this;
+        },
 
-    highlight: function (index) {
-        this._activeIndex = index;
-        this.onHighlightChange();
-        return this;
-    },
+        highlight: function (index) {
+            this._activeIndex = index;
+            this.onHighlightChange();
+            return this;
+        },
 
-    highlightPrevious: function () {
-        const current = this._activeIndex;
-        const previousActiveIndex = (current === 0) ? this._suggestions.length - 1 : (current - 1);
-        this.highlight(previousActiveIndex);
-        return this;
-    },
+        highlightPrevious: function () {
+            const current = this._activeIndex;
+            const previousActiveIndex = (current === 0) ? this._suggestions.length - 1 : (current - 1);
+            this.highlight(previousActiveIndex);
+            return this;
+        },
 
-    highlightNext: function () {
-        const current = this._activeIndex;
-        const nextActiveIndex = (current === this._suggestions.length - 1) ? 0 : (current + 1);
-        this.highlight(nextActiveIndex);
-        return this;
-    },
+        highlightNext: function () {
+            const current = this._activeIndex;
+            const nextActiveIndex = (current === this._suggestions.length - 1) ? 0 : (current + 1);
+            this.highlight(nextActiveIndex);
+            return this;
+        },
 
-    highlighted: function () {
-        return this.get(this._activeIndex);
-    },
+        highlighted: function () {
+            return this.get(this._activeIndex);
+        },
 
-    highlightedIndex: function () {
-        return this._activeIndex;
-    }
-};
+        highlightedIndex: function () {
+            return this._activeIndex;
+        }
+    };
+}
 
 export default SuggestionsModel;