@atlaskit/node-data-provider 2.0.0

package/dist/es2019/index.js

@@ -0,0 +1,193 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+// re exported to avoid type issues
+// this type is only used in jsdoc comments in this file.
+
+/**
+ * This is the base class for creating a node data provider for an editor plugin.
+ *
+ * ## Usage
+ *
+ * ### Create a provider
+ *
+ * @example
+ * ```ts
+ * class EmojiNodeDataProvider extends NodeDataProvider<
+ *  { attrs: EmojiAttributes },
+ * { resolvedData: string }
+ * > {
+ *   constructor({ existingCache }?: { existingCache: Record<string, { resolvedData: string }> }) {
+ *     super({ existingCache, nodeName: 'emoji' });
+ *   }
+ *   nodeToKey(node: { attrs: EmojiAttributes }): string {
+ *     return `${node.attrs.shortName}-${node.attrs.text}-${node.attrs.id}`;
+ *   }
+ *   resolve(node: { attrs: EmojiAttributes }, _?: { signal: AbortSignal }) {
+ *     return Promise.resolve({ resolvedData: 'resolved' });
+ *   }
+ * }
+ * ```
+ *
+ * ### Use the provider
+ *
+ * @example
+ * ```ts
+ * const emojiNodeDataProvider = new EmojiNodeDataProvider();
+ * ```
+ *
+ * ### Caching
+ *
+ * @see {@link buildCaches} for more information on building caches.
+ *
+ * #### Load an existing provider with a cache
+ *
+ * @example
+ * ```
+ * await buildCaches({
+ *  adf: docFromSomewhere,
+ *  nodeDataProviders: [emojiNodeDataProvider],
+ *  signal: AbortSignal.timeout(5000),
+ * });
+ * emojiNodeDataProvider // { 'key': 'value' }
+ * ```
+ *
+ * ### Load an new provider with an existing cache
+ *
+ * @example
+ * ```
+ * const provider1 = new ExampleNodeDataProvider();
+ * await buildCaches({adf, nodeDataProviders: [provider1]})
+ * provider1.cache // { 'key': 'value' }
+ *
+ * const provider2 = new ExampleNodeDataProvider({existingCache: provider1.cache});
+ * ```
+ */
+export class NodeDataProvider {
+  /**
+   * This takes a node and returns a key that can be used to cache the result of the resolve function.
+   */
+
+  /**
+   * This returns the information required to render a node.
+   *
+   * If unresolvable, this method will throw an error.
+   *
+   * If signal is aborted, this method will return undefined.
+   */
+
+  /**
+   * The adf node name this provider is responsible for.
+   */
+
+  constructor({
+    existingCache = {},
+    nodeName,
+    nodeToKey,
+    resolve
+  }) {
+    /**
+     * This is added to ease building types
+     */
+    // @ts-ignore
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _defineProperty(this, "__node", {});
+    _defineProperty(this, "pending", {});
+    this.__cache = existingCache;
+    this.nodeName = nodeName;
+    this.nodeToKey = nodeToKey;
+    this.resolve = resolve;
+  }
+
+  /**
+   * Updates the providers cache.
+   *
+   * Useful in scenarios such as SSR where the cache is built on the server and then passed to the client.
+   *
+   * Avoids the need to provide the cache to the constructor (to allow decoupling creation of node data providers from cache building),
+   * and allow for caching to be managed at a group level across multiple providers.
+   *
+   * This is not expected to be used by consumers, for internal consumption examples;
+   * @see {@link buildCaches}
+   *
+   */
+  updateCache(cache, options) {
+    switch (options.strategy) {
+      case 'merge-override':
+        this.__cache = {
+          ...this.__cache,
+          ...cache
+        };
+        return;
+      case 'replace':
+        this.__cache = cache;
+        return;
+    }
+  }
+
+  /**
+   * This is the cache for the provider.
+   */
+  get cache() {
+    return this.__cache;
+  }
+  get(node, _) {
+    const key = this.nodeToKey(node);
+    const cached = this.cache[key];
+    if (cached) {
+      return cached;
+    }
+
+    // Get could be called from a variety of sources;
+    // - a Node Data Provider
+    // - a cache build
+    // - something else
+    //
+    // We want to avoid triggering multiple resolves for the same node -- so we keep track of pending requests
+    // and share them across any overlapping gets.
+    //
+    // When a get is cancelled -- we only want to cancel the shared resolve if all signals are aborted
+    // so we keep track of all signals that are not aborted.
+
+    let originalSignal = (_ === null || _ === void 0 ? void 0 : _.signal) || new AbortController().signal;
+    if (!this.pending[key]) {
+      const abortController = new AbortController();
+      this.pending[key] = {
+        resolving: new Promise(async (res, rej) => {
+          try {
+            const result = await this.resolve(node, {
+              signal: abortController.signal
+            }).catch(res => res(undefined));
+            res(result);
+          } catch {
+            res(undefined);
+          }
+        }),
+        abortController,
+        activeSignals: [originalSignal]
+      };
+    }
+    const handleAbort = () => {
+      this.pending[key].activeSignals = this.pending[key].activeSignals.filter(activeSignal => activeSignal !== originalSignal);
+      if (this.pending[key].activeSignals.length === 0) {
+        // abort the resolution if all signals are aborted
+        this.pending[key].abortController.abort();
+      }
+    };
+
+    // eslint-disable-next-line @repo/internal/dom-events/no-unsafe-event-listeners
+    originalSignal === null || originalSignal === void 0 ? void 0 : originalSignal.addEventListener('abort', handleAbort);
+    this.pending[key].resolving.then(resolvedValue => {
+      if (resolvedValue) {
+        this.cache[key] = resolvedValue;
+      }
+      // eslint-disable-next-line @repo/internal/dom-events/no-unsafe-event-listeners
+      originalSignal === null || originalSignal === void 0 ? void 0 : originalSignal.removeEventListener('abort', handleAbort);
+      return resolvedValue;
+    });
+    return this.pending[key].resolving;
+  }
+}
+
+// The purpose of this type is to ensure that either a DocNode or a PMNode is passed in
+// to the provider.
+// It is not opinionated about which nodes are used, so `any` is used here to allow
+// compatibility with both DocNodes and PMNodes.

package/dist/es2019/internal-types.js

@@ -0,0 +1 @@
+export {};

package/dist/es2019/plugin-hooks.js

@@ -0,0 +1,66 @@
+import { useEffect, useMemo, useState } from 'react';
+/**
+ *
+ *
+ * This hook is intended to simplify accessing data via the one tick providers.
+ *
+ * ```ts
+ * const value = useNodeDataProviderGet(emojiProvider, emojiNode);
+ *
+ * if (value.state === 'loading') {
+ *   return <Loading />;
+ * }
+ * if (value.state === 'failed') {
+ *  return <Fallback />;
+ * }
+ * return <Emoji properties=(value.result) />
+ * ```
+ */
+export function useNodeDataProviderGet(options) {
+  const getResult = useMemo(() => options.provider.get(options.node), [options.provider, options.node]);
+  let [resolved, setResolved] = useState(getResult !== undefined && !isPromise(getResult) ? getResult : undefined);
+  useEffect(() => {
+    if (!isPromise(getResult)) {
+      return;
+    }
+    let cancelled = false;
+    (async function () {
+      try {
+        let resolved = await getResult;
+        if (!cancelled) {
+          if (resolved === undefined) {
+            setResolved('error');
+          } else {
+            setResolved(resolved);
+          }
+        }
+      } catch {
+        setResolved('error');
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [getResult]);
+  if (resolved === undefined) {
+    return {
+      state: 'loading',
+      result: undefined
+    };
+  }
+  if (resolved === 'error') {
+    return {
+      state: 'failed',
+      result: undefined
+    };
+  }
+  return {
+    state: 'resolved',
+    result: resolved
+  };
+}
+function isPromise(obj) {
+  return !!obj && (typeof obj === 'object' || typeof obj === 'function') &&
+  // @ts-ignore
+  typeof obj.then === 'function';
+}

package/dist/es2019/providers/emoji.js

@@ -0,0 +1,26 @@
+import { NodeDataProvider } from '../index';
+export function createEmojiNodeDataProvider({
+  emojiProvider,
+  existingCache
+}) {
+  const emojiNodeDataProvider = new NodeDataProvider({
+    existingCache,
+    nodeName: 'emoji',
+    nodeToKey: node => {
+      const key = `${node.attrs.id}-${node.attrs.shortName}-${node.attrs.text}`;
+      return key;
+    },
+    async resolve(node, _resolveOptions) {
+      const emojiDescriptionWithVariations = await (await emojiProvider).fetchByEmojiId({
+        id: node.attrs.id,
+        shortName: node.attrs.shortName,
+        fallback: node.attrs.text
+      }, true);
+      if (!emojiDescriptionWithVariations) {
+        throw new Error('Could not resolve emoji');
+      }
+      return emojiDescriptionWithVariations;
+    }
+  });
+  return emojiNodeDataProvider;
+}

package/dist/esm/cache.js

@@ -0,0 +1,141 @@
+import _typeof from "@babel/runtime/helpers/typeof";
+import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
+import _regeneratorRuntime from "@babel/runtime/regenerator";
+import { traverse } from '@atlaskit/adf-utils/traverse';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+/**
+ * Builds {@link NodeDataProvider}s caches for a document.
+ *
+ * It will traverse the document and call the resolve method for each node.
+ * When all promises are resolved, NodeDataProviders will have their caches populated.
+ *
+ * The providers will then be ready for use with an Editor.
+ *
+ * To limit the time spent building the cache, a signal can be provided to abort the request.
+ *
+ * ## Usage
+ *
+ * @example
+ * ```ts
+ * buildCaches({
+ *  adf: doc,
+ *  nodeDataProviders: { emoji: emojiNodeDataProvider, ... },
+ *  signal: AbortSignal.timeout(5000),
+ * });
+ * ```
+ *
+ * ### Using caches
+ *
+ * To make use of a cache in another provider (ie. for a cache created on the server), you can retrieve the cache
+ * from the provider and pass it to the new provider.
+ *
+ * @example
+ * ```tsx
+ * // SSR env
+ * const ssrProvidersCaches = await buildCaches({adf, nodeDataProviders: { emoji }})
+ *
+ * // Client env (providersCaches is the cache from the server)
+ * <ContentNodeDataProviders ... existingProvidersCache={ssrProvidersCaches} />
+ * ```
+ *
+ * *Note:* On the client - buildCache is not expected to be used directly.
+ *
+ * @see {@link ContentNodeDataProviders} for expected client usage.
+ */
+export function buildCaches(_x) {
+  return _buildCaches.apply(this, arguments);
+}
+function _buildCaches() {
+  _buildCaches = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(_ref) {
+    var adf, nodeDataProviders, _ref$signal, signal, existingProvidersCache, visitors, promises, _loop, _i, _Object$values, caches, _i2, _Object$values2, nodeDataProvider;
+    return _regeneratorRuntime.wrap(function _callee$(_context2) {
+      while (1) switch (_context2.prev = _context2.next) {
+        case 0:
+          adf = _ref.adf, nodeDataProviders = _ref.nodeDataProviders, _ref$signal = _ref.signal, signal = _ref$signal === void 0 ? new AbortController().signal : _ref$signal, existingProvidersCache = _ref.existingProvidersCache;
+          visitors = {};
+          promises = [];
+          _loop = /*#__PURE__*/_regeneratorRuntime.mark(function _loop() {
+            var _nodeDataProvider, nodeDataProvider;
+            return _regeneratorRuntime.wrap(function _loop$(_context) {
+              while (1) switch (_context.prev = _context.next) {
+                case 0:
+                  _nodeDataProvider = _Object$values[_i];
+                  // widen type to avoid typescript errors with the specific node data provider types
+                  nodeDataProvider = _nodeDataProvider;
+                  if (existingProvidersCache && existingProvidersCache[nodeDataProvider.nodeName]) {
+                    nodeDataProvider.updateCache(existingProvidersCache[nodeDataProvider.nodeName], {
+                      strategy: 'merge-override'
+                    });
+                  }
+                  visitors[nodeDataProvider.nodeName] = function (node) {
+                    var result = nodeDataProvider.get(node, {
+                      signal: signal
+                    });
+                    if (!isPromise(result)) {
+                      nodeDataProvider.cache[nodeDataProvider.nodeToKey(node)] = result;
+                      return;
+                    }
+                    promises.push(result);
+                    result.then(function (resolvedValue) {
+                      var signalAborted = signal ? signal.aborted : false;
+                      if (!signalAborted && resolvedValue !== undefined) {
+                        nodeDataProvider.cache[nodeDataProvider.nodeToKey(node)] = resolvedValue;
+                      }
+                    });
+                    return undefined;
+                  };
+                case 4:
+                case "end":
+                  return _context.stop();
+              }
+            }, _loop);
+          });
+          _i = 0, _Object$values = Object.values(nodeDataProviders);
+        case 5:
+          if (!(_i < _Object$values.length)) {
+            _context2.next = 10;
+            break;
+          }
+          return _context2.delegateYield(_loop(), "t0", 7);
+        case 7:
+          _i++;
+          _context2.next = 5;
+          break;
+        case 10:
+          if (!adf) {
+            _context2.next = 16;
+            break;
+          }
+          traverse(adf, visitors);
+          _context2.next = 14;
+          return Promise.all(promises);
+        case 14:
+          _context2.next = 18;
+          break;
+        case 16:
+          _context2.next = 18;
+          return Promise.resolve();
+        case 18:
+          caches = {};
+          for (_i2 = 0, _Object$values2 = Object.values(nodeDataProviders); _i2 < _Object$values2.length; _i2++) {
+            nodeDataProvider = _Object$values2[_i2];
+            caches[nodeDataProvider.nodeName] = nodeDataProvider.cache;
+          }
+          return _context2.abrupt("return", caches);
+        case 21:
+        case "end":
+          return _context2.stop();
+      }
+    }, _callee);
+  }));
+  return _buildCaches.apply(this, arguments);
+}
+function isPromise(obj) {
+  return !!obj && (_typeof(obj) === 'object' || typeof obj === 'function') &&
+  // @ts-ignore
+  typeof obj.then === 'function';
+}

package/dist/esm/consumption/_global-ndp-caches.js

@@ -0,0 +1,13 @@
+import React from 'react';
+var GlobalNdpCachesContext = /*#__PURE__*/React.createContext({});
+export function useGlobalNdpCachesContext() {
+  var globalNdpCachesContextValue = React.useContext(GlobalNdpCachesContext);
+  return globalNdpCachesContextValue;
+}
+
+// The ndp caches currently use module scope to store the caches. This is not ideal, and a global provider
+// will avoid the need for this.
+// This function is used to reset the global ndp caches context in tests.
+export function _resetGlobalNdpCachesContext() {
+  GlobalNdpCachesContext = /*#__PURE__*/React.createContext({});
+}

package/dist/esm/consumption/_internal-context.js

@@ -0,0 +1,71 @@
+import React from 'react';
+import { buildCaches } from '../cache';
+import { useGlobalNdpCachesContext } from './_global-ndp-caches';
+import { LRUCache } from './_lru-cache';
+
+/**
+ * The settings for the data providers lru cache,
+ * increasing the value will increase the number of data providers that can be stored in the cache.
+ */
+var lruCacheSettings = {
+  page: 5,
+  default: 1
+};
+
+/**
+ * Sets up nodeview data providers for a content node.
+ *
+ * This will return the cached node data providers if they exist, otherwise it will call the provided getNodeDataProviders function.
+ *
+ * Note: Calling this has side effects where caches for the nodeview data providers will continue to be built
+ * in the background after this resolves to a set of nodeview data providers that can be used.
+ */
+export function useContentNodeDataProvidersSetup(content,
+/**
+ * Note: changes to this object will not be reflected in the cache.
+ */
+setupOptions) {
+  var _globalNdpCachesContextValue = useGlobalNdpCachesContext();
+  // Create a cache for the content type if it doesn't exist
+  // While this will not result in any existing context consumers getting the updated value.
+  // It will ensure that the cache is available for future consumers.
+  if (_globalNdpCachesContextValue[content.contentType] === undefined) {
+    var _lruCacheSettings$con;
+    _globalNdpCachesContextValue[content.contentType] = new LRUCache((_lruCacheSettings$con = lruCacheSettings[content.contentType]) !== null && _lruCacheSettings$con !== void 0 ? _lruCacheSettings$con : lruCacheSettings.default);
+  }
+  var contentTypeNdpCaches = _globalNdpCachesContextValue[content.contentType];
+
+  // The node data providers should only be rebuilt if the content changes
+  // to avoid unnecessary rebuilding of the cache.
+  // useRef is used over useMemo as use memo is not a guarantee that the value will be reused
+  // - in development it can be called twice
+  // - react have made clear that in future versions useMemo may add features that throw away the cache, and [recommend refs](https://react.dev/reference/react/useMemo#caveats) for this use case.
+  var currentContentKey = "".concat(content.contentType, "-").concat(content.contentId);
+  var contentKeyRef = React.useRef();
+  var nodeDataProvidersRef = React.useRef();
+  if (contentKeyRef.current !== currentContentKey) {
+    contentKeyRef.current = currentContentKey;
+    var cachedContentNdps = contentTypeNdpCaches === null || contentTypeNdpCaches === void 0 ? void 0 : contentTypeNdpCaches.get(content.contentId);
+    var nodeDataProviders = cachedContentNdps || setupOptions.getNodeDataProviders();
+
+    /**
+     * Note: while this will remove old NodeDataProviders from the cache -- these are passed directly to consumers,
+     * so removing from the cache will not result in actively used NodeDataProviders being deleted in some way.
+     *
+     */
+    contentTypeNdpCaches.set(content.contentId, nodeDataProviders);
+    buildCaches({
+      adf: setupOptions.adfToUpdateWith,
+      nodeDataProviders: nodeDataProviders,
+      existingProvidersCache: setupOptions.existingProvidersCache
+    }).then(function (warmedNodeDataProvidersCache) {
+      var _setupOptions$onCache;
+      (_setupOptions$onCache = setupOptions.onCacheWarmed) === null || _setupOptions$onCache === void 0 || _setupOptions$onCache.call(setupOptions, {
+        warmedNodeDataProvidersCache: warmedNodeDataProvidersCache,
+        nodeDataProviders: nodeDataProviders
+      });
+    });
+    nodeDataProvidersRef.current = nodeDataProviders;
+  }
+  return nodeDataProvidersRef.current;
+}

package/dist/esm/consumption/_lru-cache.js

@@ -0,0 +1,37 @@
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
+import _createClass from "@babel/runtime/helpers/createClass";
+export var LRUCache = /*#__PURE__*/function () {
+  function LRUCache(capacity) {
+    _classCallCheck(this, LRUCache);
+    this.capacity = capacity;
+    this.cache = new Map();
+  }
+  _createClass(LRUCache, [{
+    key: "get",
+    value: function get(key) {
+      if (!this.cache.has(key)) {
+        return undefined;
+      }
+
+      // Move the used key to the end to mark it as most recently used
+      var value = this.cache.get(key);
+      this.cache.delete(key);
+      this.cache.set(key, value);
+      return value;
+    }
+  }, {
+    key: "set",
+    value: function set(key, value) {
+      // Check if the key already exists and delete it to update its position
+      if (this.cache.has(key)) {
+        this.cache.delete(key);
+      } else if (this.cache.size >= this.capacity) {
+        // Remove the first (least recently used) cache item if we're at capacity
+        var firstKey = this.cache.keys().next().value;
+        this.cache.delete(firstKey);
+      }
+      this.cache.set(key, value);
+    }
+  }]);
+  return LRUCache;
+}();

package/dist/esm/consumption/content.js

@@ -0,0 +1,46 @@
+import React from 'react';
+import { _resetGlobalNdpCachesContext } from './_global-ndp-caches';
+import { useContentNodeDataProvidersSetup } from './_internal-context';
+var ContentNodeDataProvidersContext = /*#__PURE__*/React.createContext(undefined);
+
+/**
+ *
+ * @example
+ * ```tsx
+ * <ContentNodeDataProviders
+ * 	contentType="page" contentId="9001"
+ * 	adf={doc}
+ * 	placeholder={<Spinner />}
+ * 	existingProvidersCache={ssrProvidersCache}
+ * 	getNodeDataProviders={getPageNodeDataProviders}
+ * 	onCacheWarmed={trackCacheWarmed}
+ * >
+ * 	 <Editor />
+ * </ContentNodeDataProviders>
+ * ```
+ */
+export function ContentNodeDataProviders(props) {
+  var contentNodeDataProviders = useContentNodeDataProvidersSetup({
+    contentType: props.contentType,
+    contentId: props.contentId
+  }, {
+    adfToUpdateWith: props.adf,
+    existingProvidersCache: props.existingProvidersCache,
+    getNodeDataProviders: props.getNodeDataProviders,
+    onCacheWarmed: props.onCacheWarmed
+  });
+  return /*#__PURE__*/React.createElement(ContentNodeDataProvidersContext.Provider, {
+    value: contentNodeDataProviders
+  }, props.children);
+}
+export function useContentNodeDataProviders() {
+  var contentNodeDataProvidersContext = React.useContext(ContentNodeDataProvidersContext);
+  return contentNodeDataProvidersContext;
+}
+export {
+/**
+ * Exported for testing purposes only.
+ *
+ * This API will change.
+ */
+_resetGlobalNdpCachesContext as __testOnly_resetGlobalNdpCachesContext };

package/dist/esm/get-providers/confluence-page.js

@@ -0,0 +1,9 @@
+import { createEmojiNodeDataProvider } from '../providers/emoji';
+export function getConfluencePageProviders(_ref) {
+  var emojiProvider = _ref.emojiProvider;
+  return {
+    emoji: createEmojiNodeDataProvider({
+      emojiProvider: emojiProvider
+    })
+  };
+}