@atlassian/atlassian-connect-js 5.3.190

package/src/host/modules/messages.js

@@ -0,0 +1,309 @@
+/**
+* Messages are the primary method for providing system feedback in the product user interface.
+* Messages include notifications of various kinds: alerts, confirmations, notices, warnings, info and errors.
+* For visual examples of each kind please see the [Design guide](https://docs.atlassian.com/aui/latest/docs/messages.html).
+* ### Example ###
+* ```
+* //create a message
+* var message = AP.messages.info('plain text title', 'plain text body');
+* ```
+* @deprecated after August 2017 | Please use the Flag module instead.
+* @name Messages
+* @module
+* @ignore
+*/
+
+import $ from '../dollar';
+import HostApi from '../host-api';
+import util from '../util';
+import AnalyticsAction from '../actions/analytics_action';
+
+const MESSAGE_BAR_ID = 'ac-message-container';
+const MESSAGE_TYPES = ['generic', 'error', 'warning', 'success', 'info', 'hint'];
+const MSGID_PREFIX = 'ap-message-';
+const MSGID_REGEXP = new RegExp(`^${MSGID_PREFIX}[0-9A-fa-f]+$`);
+const _messages = {};
+
+function validateMessageId(msgId) {
+  return MSGID_REGEXP.test(msgId);
+}
+
+function getMessageBar() {
+  let $msgBar = $('#' + MESSAGE_BAR_ID);
+
+  if ($msgBar.length < 1) {
+    $msgBar = $('<div id="' + MESSAGE_BAR_ID + '" />').appendTo('body');
+  }
+  return $msgBar;
+}
+
+function filterMessageOptions(options) {
+  const copy = {};
+  const allowed = ['closeable', 'fadeout', 'delay', 'duration', 'id'];
+  if (typeof options === 'object') {
+    allowed.forEach(key => {
+      if (key in options) {
+        copy[key] = options[key];
+      }
+    });
+  }
+  return copy;
+}
+
+var messageCloseListenerCreated = false;
+
+function showMessage(name, title, body, options) {
+  if(!messageCloseListenerCreated) {
+    createMessageCloseListener();
+    messageCloseListenerCreated = true;
+  }
+
+  const $msgBar = getMessageBar();
+  options = filterMessageOptions(options);
+  $.extend(options, {
+    title: title,
+    body: AJS.escapeHtml(body)
+  });
+
+  if (MESSAGE_TYPES.indexOf(name) < 0) {
+    throw 'Invalid message type. Must be: ' + MESSAGE_TYPES.join(', ');
+  }
+  if (validateMessageId(options.id)) {
+    AJS.messages[name]($msgBar, options);
+    // Calculate the left offset based on the content width.
+    // This ensures the message always stays in the centre of the window.
+    $msgBar.css('margin-left', '-' + $msgBar.innerWidth() / 2 + 'px');
+  }
+}
+
+function deprecatedShowMessage(name, title, body, options, callback) {
+  const methodUsed = `AP.messages.${name}`;
+  console.warn(`DEPRECATED API - AP.messages.${name} has been deprecated since ACJS 5.0 and will be removed in a future release. Use AP.flag.create instead.`);
+  AnalyticsAction.trackDeprecatedMethodUsed(methodUsed, callback._context.extension);
+  const frameworkAdaptor = HostApi.getFrameworkAdaptor();
+  const messageProvider = frameworkAdaptor.getProviderByModuleName('messages');
+  if (messageProvider) {
+    const messageType = name;
+    let createMessage = messageProvider[messageType];
+    if (!createMessage) {
+      messageProvider[messageType] = messageProvider.generic;
+    }
+    createMessage(title, body, options);
+  } else {
+    showMessage(name, title, body, options);
+  }
+}
+
+function createMessageCloseListener(){
+  $(document).on('aui-message-close', function(e, $msg) {
+    const _id = $msg.attr('id').replace(MSGID_PREFIX, '');
+    if (_messages[_id]) {
+      if ($.isFunction(_messages[_id].onCloseTrigger)) {
+        _messages[_id].onCloseTrigger();
+      }
+      _messages[_id]._destroy();
+    }
+  });
+}
+
+
+
+function messageModule(messageType) {
+  return {
+    constructor: function(title, body, options, callback) {
+      callback = util.last(arguments);
+      const _id = callback._id;
+      if (typeof title !== 'string') {
+        title = '';
+      }
+      if (typeof body !== 'string') {
+        body = '';
+      }
+      if (typeof options !== 'object') {
+        options = {};
+      }
+      options.id = MSGID_PREFIX + _id;
+      deprecatedShowMessage(messageType, title, body, options, callback);
+      _messages[_id] = this;
+    }
+  };
+}
+
+export default {
+  /**
+  * Close a message
+  * @deprecated after August 2017 | Please use the Flag module instead.
+  * @name clear
+  * @method
+  * @memberof module:Messages#
+  * @param    {String}    id  The id that was returned when the message was created.
+  * @example
+  * //create a message
+  * var message = AP.messages.info('title', 'body');
+  * setTimeout(function(){
+  *   AP.messages.clear(message);
+  * }, 2000);
+  */
+  clear: function(msg) {
+    const id = MSGID_PREFIX + msg._id;
+    if (validateMessageId(id)) {
+      const frameworkAdaptor = HostApi.getFrameworkAdaptor();
+      const messageProvider = frameworkAdaptor.getProviderByModuleName('messages');
+      if (messageProvider) {
+        messageProvider.clear(id);
+      } else {
+        $('#' + id).closeMessage();
+      }
+    }
+  },
+
+  /**
+  * Trigger an event when a message is closed
+  * @deprecated after August 2017 | Please use the Flag module instead.
+  * @name onClose
+  * @method
+  * @memberof module:Messages#
+  * @param    {String}    id  The id that was returned when the message was created.
+  * @param    {Function}  callback  The function that is run when the event is triggered
+  * @example
+  * //create a message
+  * var message = AP.messages.info('title', 'body');
+  * AP.messages.onClose(message, function() {
+  *   console.log(message, ' has been closed!');
+  * });
+  */
+  onClose: function(msg, callback) {
+    callback = util.last(arguments);
+    const id = msg._id;
+    const frameworkAdaptor = HostApi.getFrameworkAdaptor();
+    const messageProvider = frameworkAdaptor.getProviderByModuleName('messages');
+    if (messageProvider) {
+      const fullId = MSGID_PREFIX + msg._id;
+      messageProvider.onClose(fullId, callback);
+    } else {
+      if (_messages[id]) {
+        _messages[id].onCloseTrigger = callback;
+      }
+    }
+  },
+
+  /**
+  * Show a generic message
+  * @deprecated after August 2017 | Please use the Flag module instead.
+  * @name generic
+  * @method
+  * @memberof module:Messages#
+  * @param    {String}            title       Sets the title text of the message.
+  * @param    {String}            body        The main content of the message.
+  * @param    {Object}            options             Message Options
+  * @param    {Boolean}           options.closeable   Adds a control allowing the user to close the message, removing it from the page.
+  * @param    {Boolean}           options.fadeout     Toggles the fade away on the message
+  * @param    {Number}            options.delay       Time to wait (in ms) before starting fadeout animation (ignored if fadeout==false)
+  * @param    {Number}            options.duration    Fadeout animation duration in milliseconds (ignored if fadeout==false)
+  * @returns  {String}    The id to be used when clearing the message
+  * @example
+  * //create a message
+  * var message = AP.messages.generic('title', 'generic message example');
+  */
+  generic: messageModule('generic'),
+
+  /**
+  * Show an error message
+  * @deprecated after August 2017 | Please use the Flag module instead.
+  * @name error
+  * @method
+  * @memberof module:Messages#
+  * @param    {String}            title       Sets the title text of the message.
+  * @param    {String}            body        The main content of the message.
+  * @param    {Object}            options             Message Options
+  * @param    {Boolean}           options.closeable   Adds a control allowing the user to close the message, removing it from the page.
+  * @param    {Boolean}           options.fadeout     Toggles the fade away on the message
+  * @param    {Number}            options.delay       Time to wait (in ms) before starting fadeout animation (ignored if fadeout==false)
+  * @param    {Number}            options.duration    Fadeout animation duration in milliseconds (ignored if fadeout==false)
+  * @returns  {String}    The id to be used when clearing the message
+  * @example
+  * //create a message
+  * var message = AP.messages.error('title', 'error message example');
+  */
+  error: messageModule('error'),
+
+  /**
+  * Show a warning message
+  * @deprecated after August 2017 | Please use the Flag module instead.
+  * @name warning
+  * @method
+  * @memberof module:Messages#
+  * @param    {String}            title       Sets the title text of the message.
+  * @param    {String}            body        The main content of the message.
+  * @param    {Object}            options             Message Options
+  * @param    {Boolean}           options.closeable   Adds a control allowing the user to close the message, removing it from the page.
+  * @param    {Boolean}           options.fadeout     Toggles the fade away on the message
+  * @param    {Number}            options.delay       Time to wait (in ms) before starting fadeout animation (ignored if fadeout==false)
+  * @param    {Number}            options.duration    Fadeout animation duration in milliseconds (ignored if fadeout==false)
+  * @returns  {String}    The id to be used when clearing the message
+  * @example
+  * //create a message
+  * var message = AP.messages.warning('title', 'warning message example');
+  */
+  warning: messageModule('warning'),
+
+  /**
+  * Show a success message
+  * @deprecated after August 2017 | Please use the Flag module instead.
+  * @name success
+  * @method
+  * @memberof module:Messages#
+  * @param    {String}            title       Sets the title text of the message.
+  * @param    {String}            body        The main content of the message.
+  * @param    {Object}            options             Message Options
+  * @param    {Boolean}           options.closeable   Adds a control allowing the user to close the message, removing it from the page.
+  * @param    {Boolean}           options.fadeout     Toggles the fade away on the message
+  * @param    {Number}            options.delay       Time to wait (in ms) before starting fadeout animation (ignored if fadeout==false)
+  * @param    {Number}            options.duration    Fadeout animation duration in milliseconds (ignored if fadeout==false)
+  * @returns  {String}    The id to be used when clearing the message
+  * @example
+  * //create a message
+  * var message = AP.messages.success('title', 'success message example');
+  */
+  success: messageModule('success'),
+
+  /**
+  * Show an info message
+  * @deprecated after August 2017 | Please use the Flag module instead.
+  * @name info
+  * @method
+  * @memberof module:Messages#
+  * @param    {String}            title       Sets the title text of the message.
+  * @param    {String}            body        The main content of the message.
+  * @param    {Object}            options             Message Options
+  * @param    {Boolean}           options.closeable   Adds a control allowing the user to close the message, removing it from the page.
+  * @param    {Boolean}           options.fadeout     Toggles the fade away on the message
+  * @param    {Number}            options.delay       Time to wait (in ms) before starting fadeout animation (ignored if fadeout==false)
+  * @param    {Number}            options.duration    Fadeout animation duration in milliseconds (ignored if fadeout==false)
+  * @returns  {String}    The id to be used when clearing the message
+  * @example
+  * //create a message
+  * var message = AP.messages.info('title', 'info message example');
+  */
+  info: messageModule('info'),
+
+  /**
+  * Show a hint message
+  * @deprecated after August 2017 | Please use the Flag module instead.
+  * @name hint
+  * @method
+  * @memberof module:Messages#
+  * @param    {String}            title               Sets the title text of the message.
+  * @param    {String}            body                The main content of the message.
+  * @param    {Object}            options             Message Options
+  * @param    {Boolean}           options.closeable   Adds a control allowing the user to close the message, removing it from the page.
+  * @param    {Boolean}           options.fadeout     Toggles the fade away on the message
+  * @param    {Number}            options.delay       Time to wait (in ms) before starting fadeout animation (ignored if fadeout==false)
+  * @param    {Number}            options.duration    Fadeout animation duration in milliseconds (ignored if fadeout==false)
+  * @returns  {String}    The id to be used when clearing the message
+  * @example
+  * //create a message
+  * var message = AP.messages.hint('title', 'hint message example');
+  */
+  hint: messageModule('hint')
+};

package/src/host/modules/page.js

@@ -0,0 +1,29 @@
+/**
+ * A JavaScript module which provides functions for general page modules.
+ * @module Page
+ */
+import util from '../util';
+
+export default {
+  /**
+   * Sets the title of the document when a full page iframe is loaded.
+   * @memberOf module:Page
+   * @method setTitle
+   * @param {String} title the title of the document to be set.
+   * @example
+   * AP.page.setTitle(title)
+   */
+  setTitle: function (title, callback) {
+    callback = util.last(arguments);
+
+    if (
+      callback._context.extension.options &&
+      callback._context.extension.options.isFullPage
+    ) {
+      const productSuffix =
+        ' - ' + util.guessProductFromModuleDefined(window.connectHost);
+
+      document.title = title + productSuffix;
+    }
+  },
+};

package/src/host/modules/scroll-position.js

@@ -0,0 +1,102 @@
+import util from '../util';
+import $ from '../dollar';
+import EventDispatcher from '../dispatchers/event_dispatcher';
+import EventActions from '../actions/event_actions';
+
+
+const TRIGGER_PERCENTAGE = 10; //% before scroll events are fired
+let activeGeneralPageAddon;
+let lastScrollEventTriggered; //top or bottom
+
+EventDispatcher.register('iframe-bridge-established', function(data) {
+  if(data.extension.options.isFullPage) {
+    window.addEventListener('scroll', scrollEventHandler);
+    activeGeneralPageAddon = data.extension.id;
+  }
+});
+
+EventDispatcher.register('iframe-destroyed', function(extension) {
+  removeScrollEvent();
+});
+
+EventDispatcher.register('iframe-unload', function(extension) {
+  removeScrollEvent();
+});
+
+function removeScrollEvent(){
+  window.removeEventListener('scroll', scrollEventHandler);
+  activeGeneralPageAddon = undefined;
+  lastScrollEventTriggered = undefined;
+}
+
+function scrollEventHandler(){
+  var documentHeight = document.documentElement.scrollHeight;
+  var windowHeight = window.innerHeight;
+
+  var boundary = documentHeight * (TRIGGER_PERCENTAGE/100);
+  if(window.pageYOffset <= boundary) {
+    triggerEvent('nearTop');
+  } else if((windowHeight + window.pageYOffset + boundary) >= documentHeight) {
+    triggerEvent('nearBottom');
+  } else {
+    lastScrollEventTriggered = undefined;
+  }
+}
+
+function triggerEvent(type) {
+  if(lastScrollEventTriggered === type) {
+    return; // only once per scroll.
+  }
+  EventActions.broadcast('scroll.' + type, {id: activeGeneralPageAddon}, {});
+  lastScrollEventTriggered = type;
+}
+
+/**
+ * Enables apps to get and set the scroll position.
+ * @exports Scroll-position
+ */
+export default {
+  /**
+   * Gets the scroll position relative to the browser viewport
+   *
+   * @param callback {Function} callback to pass the scroll position
+   * @noDemo
+   * @example
+   * AP.scrollPosition.getPosition(function(obj) { console.log(obj); });
+   */
+  getPosition: function (callback) {
+    callback = util.last(arguments);
+    // scrollPosition.getPosition is only available for general-pages
+    if (callback._context.extension.options.isFullPage) {
+      var $el = util.getIframeByExtensionId(callback._context.extension_id);
+      var offset = $el.offset();
+      var $window = $(window);
+
+      callback({
+        scrollY: $window.scrollTop() - offset.top,
+        scrollX: $window.scrollLeft() - offset.left,
+        width: window.innerWidth,
+        height: window.innerHeight
+      });
+    }
+  },
+  /**
+   * Sets the vertical scroll position relative to the iframe
+   *
+   * @param y {Number} vertical offset position
+   * @param callback {Function} callback to pass the scroll position
+   * @noDemo
+   * @example
+   * AP.scrollPosition.setVerticalPosition(30, function(obj) { console.log(obj); });
+   */
+  setVerticalPosition: function(y, callback) {
+    callback = util.last(arguments);
+    if (callback._context.extension.options && callback._context.extension.options.isFullPage) {
+      var $el = util.getIframeByExtensionId(callback._context.extension_id);
+      var offset = $el.offset();
+      if(typeof y === 'number') {
+        document.documentElement.scrollTop = offset.top + y;
+      }
+    }
+  }
+};

package/src/host/modules/theming.js

@@ -0,0 +1,114 @@
+import simpleXDM from 'simple-xdm/host';
+import { getGlobalTheme, ThemeMutationObserver, CURRENT_SURFACE_CSS_VAR } from '@atlaskit/tokens';
+
+import util from '../util';
+
+
+const getPluginFeatureFlags = () => ({
+  // Add feature flags sent to the plugin on theming bootstrap here
+})
+
+const getSurfaceValue = (extension_id) => {
+  const iframe = document.getElementById(extension_id);
+  if (!iframe) {
+    return;
+  }
+
+  const styles = getComputedStyle(iframe);
+  const currentSurface = styles.getPropertyValue(CURRENT_SURFACE_CSS_VAR);
+  const raised = styles.getPropertyValue('--ds-surface-raised');
+  const overlay = styles.getPropertyValue('--ds-surface-overlay');
+
+  if (currentSurface === raised) {
+    return 'raised';
+  }
+
+  if (currentSurface === overlay) {
+    return 'overlay';
+  }
+};
+
+/**
+ * Broadcasts the new theme to all plugins.
+ * @typedef {import("@atlaskit/tokens").ThemeState} ThemeState
+ * @param newTheme {ThemeState}
+ */
+function broadcastThemeChange(newTheme) {
+  const featureFlags = getPluginFeatureFlags();
+  if (ThemingModuleState.extensionIds.length) {
+    ThemingModuleState.extensionIds.forEach((id) => {
+      const surface = getSurfaceValue(id);
+      simpleXDM.broadcast(
+        'theme_changed',
+        { id },
+        { newTheme, featureFlags, surface }
+      );
+    });
+  }
+}
+
+// Exported only for testing
+export const ThemingModuleState = {
+  /**
+   * An array containing extension ID's for each app that has enabled theming.
+   * Theme change events are only sent to apps listed in this array.
+   */
+  extensionIds: [],
+  /**
+   * Observer that will only trigger on changes to data-theme on the root html element.
+   * Dispatches the new theme to all plugins when the theme changes.
+   */
+  themeObserver: new ThemeMutationObserver((newTheme) => {
+    broadcastThemeChange(newTheme);
+  })
+}
+
+// Only functions that make up the public ACJS theming API should be exported on this object.
+const ThemingModule = {
+  /**
+   * Starts observing theme changes and dispatches the `theme_initialized` event to the plugin.
+   * This event causes the plugin to react when the host's theme changes.
+   */
+  initializeTheming() {
+    const callback = util.last(arguments);
+    const forceNoCleanup = arguments.length === 1 ? false : arguments[0];
+
+    if (!callback || !callback._context || !callback._context.extension_id) {
+      return;
+    }
+
+    const { _context: { extension_id } } = callback;
+
+    if (!extension_id) {
+      return;
+    }
+
+    const initialTheme = getGlobalTheme();
+    const surface = getSurfaceValue(extension_id);
+    const featureFlags = getPluginFeatureFlags();
+
+    // The theme_initialized event should be broadcast even if it has previously been initialized by the plugin.
+    // This is to ensure that theming works in multi-page apps after navigating to a different page.
+    // The reason is that isThemingInitialized on the plugin side starts as `false` when all.js is loaded.
+    // The theme_initialized event is needed to change it to `true` for any new page.
+    simpleXDM.broadcast(
+      'theme_initialized',
+      { id: extension_id },
+      { initialTheme, featureFlags, surface, forceNoCleanup }
+    );
+
+    if (!ThemingModuleState.extensionIds.includes(extension_id)) {
+      ThemingModuleState.extensionIds.push(extension_id);
+      ThemingModuleState.themeObserver.observe(document.documentElement);
+    }
+  },
+  /**
+   * This has to be part of the API so the plugin can notify us when theme loading is finished.
+   * The underscore indicates it should not be called by apps directly.
+   * @private
+   */
+  _finishedInitTheming() {
+  }
+};
+
+export default ThemingModule;

package/src/host/stores/extension_configuration_options_store.js

@@ -0,0 +1,24 @@
+import util from '../util';
+
+class ExtensionConfigurationOptionsStore {
+  constructor() {
+    this.store = {};
+  }
+  set(obj, val) {
+    if(val) {
+      var toSet = {};
+      toSet[obj] = val;
+    } else {
+      toSet = obj;
+    }
+    util.extend(this.store, toSet);
+  }
+  get(key) {
+    if(key) {
+      return this.store[key];
+    }
+    return util.extend({}, this.store); //clone
+  }
+}
+
+export default new ExtensionConfigurationOptionsStore();

package/src/host/util.js

@@ -0,0 +1,98 @@
+import $ from './dollar';
+
+function escapeSelector(s) {
+  if (!s) {
+    throw new Error('No selector to escape');
+  }
+  return s.replace(/[!"#$%&'()*+,.\/:;<=>?@[\\\]^`{|}~]/g, '\\$&');
+}
+
+function stringToDimension(value) {
+  var percent = false;
+  var unit = 'px';
+
+  if(typeof value === 'string') {
+    percent = value.indexOf('%') === value.length - 1;
+    value = parseInt(value, 10);
+    if (percent) {
+      unit = '%';
+    }
+  }
+
+  if(!isNaN(value)) {
+    return value + unit;
+  }
+}
+
+function getIframeByExtensionId(id) {
+  return $('iframe#' + escapeSelector(id));
+}
+
+function first(arr, numb){
+  if(numb) {
+    return arr.slice(0, numb);
+  }
+  return arr[0];
+}
+
+function last(arr){
+  return arr[arr.length - 1];
+}
+
+function pick(obj, keys) {
+  if(typeof obj !== 'object') {
+    return {};
+  }
+  return Object.keys(obj)
+    .filter((key) => keys.indexOf(key) >= 0)
+    .reduce((newObj, key) => Object.assign(newObj, { [key]: obj[key] }), {});
+}
+
+function debounce (fn, wait) {
+  var timeout;
+  return function () {
+    var ctx = this;
+    var args = [].slice.call(arguments);
+    function later() {
+      timeout = null;
+      fn.apply(ctx, args);
+    }
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    timeout = setTimeout(later, wait || 50);
+  };
+}
+
+function isSupported(domElem, attr, value, defaultValue) {
+  if (domElem && domElem[attr] && domElem[attr].supports) {
+    return domElem[attr].supports(value);
+  } else {
+    return defaultValue;
+  }
+}
+
+function guessProductFromModuleDefined(connectHost) {
+  if (connectHost.isModuleDefined('jira')) {
+    return 'Jira';
+  }
+
+  if (connectHost.isModuleDefined('confluence')) {
+    return 'Confluence';
+  }
+
+  return '';
+}
+
+export default {
+  escapeSelector,
+  stringToDimension,
+  getIframeByExtensionId,
+  first,
+  last,
+  pick,
+  debounce,
+  isSupported,
+  extend: Object.assign,
+  guessProductFromModuleDefined,
+};

package/src/host/utils/access-narrowing-context.js

@@ -0,0 +1,18 @@
+export function getAccessNarrowingSpaceContext(extension) {
+  if (extension?.options && AJS?.Meta?.get) {
+    const productContext = {
+      ...(extension.options.productContext || {})
+    };
+    if (AJS.Meta.get('space-key')) {
+      productContext['an.spaceKey'] = AJS.Meta.get('space-key');
+    }
+    return {
+      ...extension,
+      options: {
+        ...extension.options,
+        productContext,
+      }
+    };
+  }
+  return extension;
+}