@atlaskit/node-data-provider 2.0.0

package/dist/esm/index.js

@@ -0,0 +1,230 @@
+import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
+import _createClass from "@babel/runtime/helpers/createClass";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import _regeneratorRuntime from "@babel/runtime/regenerator";
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+// 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 var NodeDataProvider = /*#__PURE__*/function () {
+  /**
+   * 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.
+   */
+
+  function NodeDataProvider(_ref) {
+    var _ref$existingCache = _ref.existingCache,
+      existingCache = _ref$existingCache === void 0 ? {} : _ref$existingCache,
+      nodeName = _ref.nodeName,
+      nodeToKey = _ref.nodeToKey,
+      resolve = _ref.resolve;
+    _classCallCheck(this, NodeDataProvider);
+    /**
+     * 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}
+   *
+   */
+  _createClass(NodeDataProvider, [{
+    key: "updateCache",
+    value: function updateCache(cache, options) {
+      switch (options.strategy) {
+        case 'merge-override':
+          this.__cache = _objectSpread(_objectSpread({}, this.__cache), cache);
+          return;
+        case 'replace':
+          this.__cache = cache;
+          return;
+      }
+    }
+
+    /**
+     * This is the cache for the provider.
+     */
+  }, {
+    key: "cache",
+    get: function get() {
+      return this.__cache;
+    }
+  }, {
+    key: "get",
+    value: function get(node, _) {
+      var _this = this;
+      var key = this.nodeToKey(node);
+      var 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.
+
+      var originalSignal = (_ === null || _ === void 0 ? void 0 : _.signal) || new AbortController().signal;
+      if (!this.pending[key]) {
+        var abortController = new AbortController();
+        this.pending[key] = {
+          resolving: new Promise( /*#__PURE__*/function () {
+            var _ref2 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(res, rej) {
+              var result;
+              return _regeneratorRuntime.wrap(function _callee$(_context) {
+                while (1) switch (_context.prev = _context.next) {
+                  case 0:
+                    _context.prev = 0;
+                    _context.next = 3;
+                    return _this.resolve(node, {
+                      signal: abortController.signal
+                    }).catch(function (res) {
+                      return res(undefined);
+                    });
+                  case 3:
+                    result = _context.sent;
+                    res(result);
+                    _context.next = 10;
+                    break;
+                  case 7:
+                    _context.prev = 7;
+                    _context.t0 = _context["catch"](0);
+                    res(undefined);
+                  case 10:
+                  case "end":
+                    return _context.stop();
+                }
+              }, _callee, null, [[0, 7]]);
+            }));
+            return function (_x, _x2) {
+              return _ref2.apply(this, arguments);
+            };
+          }()),
+          abortController: abortController,
+          activeSignals: [originalSignal]
+        };
+      }
+      var handleAbort = function handleAbort() {
+        _this.pending[key].activeSignals = _this.pending[key].activeSignals.filter(function (activeSignal) {
+          return 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 || originalSignal.addEventListener('abort', handleAbort);
+      this.pending[key].resolving.then(function (resolvedValue) {
+        if (resolvedValue) {
+          _this.cache[key] = resolvedValue;
+        }
+        // eslint-disable-next-line @repo/internal/dom-events/no-unsafe-event-listeners
+        originalSignal === null || originalSignal === void 0 || originalSignal.removeEventListener('abort', handleAbort);
+        return resolvedValue;
+      });
+      return this.pending[key].resolving;
+    }
+  }]);
+  return NodeDataProvider;
+}();
+
+// 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/esm/internal-types.js

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

package/dist/esm/plugin-hooks.js

@@ -0,0 +1,90 @@
+import _typeof from "@babel/runtime/helpers/typeof";
+import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
+import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
+import _regeneratorRuntime from "@babel/runtime/regenerator";
+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) {
+  var getResult = useMemo(function () {
+    return options.provider.get(options.node);
+  }, [options.provider, options.node]);
+  var _useState = useState(getResult !== undefined && !isPromise(getResult) ? getResult : undefined),
+    _useState2 = _slicedToArray(_useState, 2),
+    resolved = _useState2[0],
+    setResolved = _useState2[1];
+  useEffect(function () {
+    if (!isPromise(getResult)) {
+      return;
+    }
+    var cancelled = false;
+    _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee() {
+      var _resolved;
+      return _regeneratorRuntime.wrap(function _callee$(_context) {
+        while (1) switch (_context.prev = _context.next) {
+          case 0:
+            _context.prev = 0;
+            _context.next = 3;
+            return getResult;
+          case 3:
+            _resolved = _context.sent;
+            if (!cancelled) {
+              if (_resolved === undefined) {
+                setResolved('error');
+              } else {
+                setResolved(_resolved);
+              }
+            }
+            _context.next = 10;
+            break;
+          case 7:
+            _context.prev = 7;
+            _context.t0 = _context["catch"](0);
+            setResolved('error');
+          case 10:
+          case "end":
+            return _context.stop();
+        }
+      }, _callee, null, [[0, 7]]);
+    }))();
+    return function () {
+      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/esm/providers/emoji.js

@@ -0,0 +1,47 @@
+import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
+import _regeneratorRuntime from "@babel/runtime/regenerator";
+import { NodeDataProvider } from '../index';
+export function createEmojiNodeDataProvider(_ref) {
+  var emojiProvider = _ref.emojiProvider,
+    existingCache = _ref.existingCache;
+  var emojiNodeDataProvider = new NodeDataProvider({
+    existingCache: existingCache,
+    nodeName: 'emoji',
+    nodeToKey: function nodeToKey(node) {
+      var key = "".concat(node.attrs.id, "-").concat(node.attrs.shortName, "-").concat(node.attrs.text);
+      return key;
+    },
+    resolve: function resolve(node, _resolveOptions) {
+      return _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee() {
+        var emojiDescriptionWithVariations;
+        return _regeneratorRuntime.wrap(function _callee$(_context) {
+          while (1) switch (_context.prev = _context.next) {
+            case 0:
+              _context.next = 2;
+              return emojiProvider;
+            case 2:
+              _context.next = 4;
+              return _context.sent.fetchByEmojiId({
+                id: node.attrs.id,
+                shortName: node.attrs.shortName,
+                fallback: node.attrs.text
+              }, true);
+            case 4:
+              emojiDescriptionWithVariations = _context.sent;
+              if (emojiDescriptionWithVariations) {
+                _context.next = 7;
+                break;
+              }
+              throw new Error('Could not resolve emoji');
+            case 7:
+              return _context.abrupt("return", emojiDescriptionWithVariations);
+            case 8:
+            case "end":
+              return _context.stop();
+          }
+        }, _callee);
+      }))();
+    }
+  });
+  return emojiNodeDataProvider;
+}

package/dist/types/cache.d.ts

@@ -0,0 +1,61 @@
+import type { DocNode } from '@atlaskit/adf-schema';
+import { type AnyNodeDataProvider } from './internal-types';
+import { type EmojiNodeDataProvider } from './providers/emoji';
+export type NodeDataProvidersCache = {
+    [nodeName: string]: Record<string, any>;
+};
+export type NodeDataProviders = {
+    emoji: EmojiNodeDataProvider;
+    [nodeName: string]: AnyNodeDataProvider;
+};
+/**
+ * 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 declare function buildCaches({ adf, nodeDataProviders, signal, existingProvidersCache, }: {
+    adf?: DocNode;
+    /**
+     * Providers to build caches for
+     */
+    nodeDataProviders: NodeDataProviders;
+    /**
+     * Signal to abort cache building -- the caches will be built up to the point of abort.
+     */
+    signal?: AbortSignal;
+    existingProvidersCache?: NodeDataProvidersCache;
+}): Promise<NodeDataProvidersCache>;

package/dist/types/consumption/_global-ndp-caches.d.ts

@@ -0,0 +1,8 @@
+import { type NodeDataProviders } from '../cache';
+import { type LRUCache } from './_lru-cache';
+type GlobalNdpCachesContextValue = {
+    [contentType: string]: LRUCache<NodeDataProviders>;
+};
+export declare function useGlobalNdpCachesContext(): GlobalNdpCachesContextValue;
+export declare function _resetGlobalNdpCachesContext(): void;
+export {};

package/dist/types/consumption/_internal-context.d.ts

@@ -0,0 +1,32 @@
+import { type DocNode } from '@atlaskit/adf-schema';
+import { type NodeDataProviders, type NodeDataProvidersCache } from '../cache';
+/**
+ * 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 declare function useContentNodeDataProvidersSetup(content: {
+    /**
+     * The type of content.
+     */
+    contentType: 'page';
+    contentId: string;
+}, 
+/**
+ * Note: changes to this object will not be reflected in the cache.
+ */
+setupOptions: {
+    /**
+     * Note: this will only be used if no existing NodeDataProviders are found for the content.
+     */
+    adfToUpdateWith?: DocNode;
+    existingProvidersCache?: NodeDataProvidersCache;
+    getNodeDataProviders: () => NodeDataProviders;
+    onCacheWarmed?: (_: {
+        warmedNodeDataProvidersCache: NodeDataProvidersCache;
+        nodeDataProviders: NodeDataProviders;
+    }) => void;
+}): NodeDataProviders | undefined;

package/dist/types/consumption/_lru-cache.d.ts

@@ -0,0 +1,7 @@
+export declare class LRUCache<T> {
+    private capacity;
+    private cache;
+    constructor(capacity: number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+}

package/dist/types/consumption/content.d.ts

@@ -0,0 +1,65 @@
+import React from 'react';
+import { type DocNode } from '@atlaskit/adf-schema';
+import { type NodeDataProviders, type NodeDataProvidersCache } from '../cache';
+import { _resetGlobalNdpCachesContext } from './_global-ndp-caches';
+/**
+ *
+ * @example
+ * ```tsx
+ * <ContentNodeDataProviders
+ * 	contentType="page" contentId="9001"
+ * 	adf={doc}
+ * 	placeholder={<Spinner />}
+ * 	existingProvidersCache={ssrProvidersCache}
+ * 	getNodeDataProviders={getPageNodeDataProviders}
+ * 	onCacheWarmed={trackCacheWarmed}
+ * >
+ * 	 <Editor />
+ * </ContentNodeDataProviders>
+ * ```
+ */
+export declare function ContentNodeDataProviders(props: {
+    /**
+     * The type of content, this is used to group the resulting providers cache
+     *
+     * Note: Providers Caches are stored in an internal LRU cache, are grouped by content type.
+     */
+    contentType: 'page';
+    /**
+     * The type of content, this is used to group the resulting providers cache
+     *
+     */
+    contentId: string;
+    /**
+     * This is optional - when passed the caches in the data providers will be warmed
+     * based on this document.
+     */
+    adf?: DocNode;
+    /**
+     * This is optional, and supports passing in an existing providers cache.
+     *
+     * An example of this is when you have a server-side rendered providers cache that you want to use on the client.
+     */
+    existingProvidersCache?: NodeDataProvidersCache;
+    /**
+     * Returns a set of `NodeDataProviders` which are put in context for use when creating an editor or renderer.
+     * These will be pre-warmed if adf is passed in.
+     */
+    getNodeDataProviders: () => NodeDataProviders;
+    /**
+     * Called when the cache is warmed.
+     */
+    onCacheWarmed?: (_: {
+        warmedNodeDataProvidersCache: NodeDataProvidersCache;
+        nodeDataProviders: NodeDataProviders;
+    }) => void;
+    children: React.ReactNode;
+}): JSX.Element;
+export declare function useContentNodeDataProviders(): NodeDataProviders | undefined;
+export { 
+/**
+ * Exported for testing purposes only.
+ *
+ * This API will change.
+ */
+_resetGlobalNdpCachesContext as __testOnly_resetGlobalNdpCachesContext, };

package/dist/types/get-providers/confluence-page.d.ts

@@ -0,0 +1,6 @@
+import type { EmojiProvider } from '@atlaskit/emoji';
+export declare function getConfluencePageProviders({ emojiProvider, }: {
+    emojiProvider: Promise<EmojiProvider>;
+}): {
+    emoji: import("../providers/emoji").EmojiNodeDataProvider;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,136 @@
+import type { buildCaches } from './cache';
+export type { buildCaches as __doNotUseThisType };
+/**
+ * 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 declare class NodeDataProvider<INode extends ReceivableNode, Result extends unknown> {
+    /**
+     * This is added to ease building types
+     */
+    __node: INode;
+    private __cache;
+    /**
+     * This takes a node and returns a key that can be used to cache the result of the resolve function.
+     */
+    nodeToKey: (node: INode) => string;
+    /**
+     * 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.
+     */
+    resolve: (node: INode, _?: {
+        signal?: AbortSignal;
+    }) => Promise<Result | undefined>;
+    /**
+     * The adf node name this provider is responsible for.
+     */
+    nodeName: string;
+    constructor({ existingCache, nodeName, nodeToKey, resolve, }: {
+        /**
+         * A cache to load the provider with.
+         *
+         * @see {@link buildCaches} for more information on building caches.
+         */
+        existingCache?: Record<string, Result>;
+        /**
+         * The adf node name this provider is responsible for.
+         *
+         * It is used for;
+         * - determining if the traverser should use this provider to resolve a node when building caches
+         * - identifying the node when submitting analytics events via the helper react hooks
+         */
+        nodeName: string;
+        nodeToKey: typeof NodeDataProvider.prototype.nodeToKey;
+        resolve: typeof NodeDataProvider.prototype.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: Record<string, Result>, options: {
+        strategy: 'merge-override' | 'replace';
+    }): void;
+    /**
+     * This is the cache for the provider.
+     */
+    get cache(): Record<string, Result>;
+    private pending;
+    get(node: INode, _?: {
+        signal: AbortSignal;
+    }): Promise<Result | undefined> | Result;
+}
+export type ReceivableNode = {
+    [key: string]: any;
+    attrs: {
+        [key: string]: any;
+    };
+};
+export type ResolveOptions = {
+    signal: AbortSignal;
+};