@atlaskit/node-data-provider 2.0.0

package/dist/types/internal-types.d.ts

@@ -0,0 +1,2 @@
+import { type NodeDataProvider } from './index';
+export type AnyNodeDataProvider = NodeDataProvider<any, Record<string, any>>;

package/dist/types/plugin-hooks.d.ts

@@ -0,0 +1,32 @@
+import type { Node as PMNode } from '@atlaskit/editor-prosemirror/model';
+import type { NodeDataProvider } from './index';
+/**
+ *
+ *
+ * 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 declare function useNodeDataProviderGet<_NodeDataProvider extends NodeDataProvider<any, any>>(options: {
+    provider: _NodeDataProvider;
+    node: PMNode;
+}): {
+    state: 'loading';
+    result: undefined;
+} | {
+    state: 'failed';
+    result: undefined;
+} | {
+    state: 'resolved';
+    result: _NodeDataProvider['cache'][string];
+};

package/dist/types/providers/emoji.d.ts

@@ -0,0 +1,10 @@
+import { type EmojiAttributes } from '@atlaskit/adf-schema';
+import type { EmojiDescriptionWithVariations, EmojiProvider } from '@atlaskit/emoji';
+import { NodeDataProvider } from '../index';
+export declare function createEmojiNodeDataProvider({ emojiProvider, existingCache, }: {
+    emojiProvider: Promise<EmojiProvider>;
+    existingCache?: Record<string, EmojiDescriptionWithVariations>;
+}): EmojiNodeDataProvider;
+export type EmojiNodeDataProvider = NodeDataProvider<{
+    attrs: EmojiAttributes;
+}, EmojiDescriptionWithVariations>;

package/dist/types-ts4.5/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-ts4.5/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-ts4.5/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-ts4.5/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-ts4.5/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-ts4.5/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-ts4.5/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;
+};

package/dist/types-ts4.5/internal-types.d.ts

@@ -0,0 +1,2 @@
+import { type NodeDataProvider } from './index';
+export type AnyNodeDataProvider = NodeDataProvider<any, Record<string, any>>;

package/dist/types-ts4.5/plugin-hooks.d.ts

@@ -0,0 +1,32 @@
+import type { Node as PMNode } from '@atlaskit/editor-prosemirror/model';
+import type { NodeDataProvider } from './index';
+/**
+ *
+ *
+ * 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 declare function useNodeDataProviderGet<_NodeDataProvider extends NodeDataProvider<any, any>>(options: {
+    provider: _NodeDataProvider;
+    node: PMNode;
+}): {
+    state: 'loading';
+    result: undefined;
+} | {
+    state: 'failed';
+    result: undefined;
+} | {
+    state: 'resolved';
+    result: _NodeDataProvider['cache'][string];
+};

package/dist/types-ts4.5/providers/emoji.d.ts

@@ -0,0 +1,10 @@
+import { type EmojiAttributes } from '@atlaskit/adf-schema';
+import type { EmojiDescriptionWithVariations, EmojiProvider } from '@atlaskit/emoji';
+import { NodeDataProvider } from '../index';
+export declare function createEmojiNodeDataProvider({ emojiProvider, existingCache, }: {
+    emojiProvider: Promise<EmojiProvider>;
+    existingCache?: Record<string, EmojiDescriptionWithVariations>;
+}): EmojiNodeDataProvider;
+export type EmojiNodeDataProvider = NodeDataProvider<{
+    attrs: EmojiAttributes;
+}, EmojiDescriptionWithVariations>;

package/emoji-provider/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@atlaskit/node-data-provider/emoji-provider",
+  "main": "../dist/cjs/providers/emoji.js",
+  "module": "../dist/esm/providers/emoji.js",
+  "module:es2019": "../dist/es2019/providers/emoji.js",
+  "sideEffects": false,
+  "types": "../dist/types/providers/emoji.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.4": {
+      "*": [
+        "../dist/types-ts4.5/providers/emoji.d.ts"
+      ]
+    }
+  }
+}

package/get-confluence-page-providers/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@atlaskit/node-data-provider/get-confluence-page-providers",
+  "main": "../dist/cjs/get-providers/confluence-page.js",
+  "module": "../dist/esm/get-providers/confluence-page.js",
+  "module:es2019": "../dist/es2019/get-providers/confluence-page.js",
+  "sideEffects": false,
+  "types": "../dist/types/get-providers/confluence-page.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.4": {
+      "*": [
+        "../dist/types-ts4.5/get-providers/confluence-page.d.ts"
+      ]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+	"name": "@atlaskit/node-data-provider",
+	"version": "2.0.0",
+	"description": "Node data provider for @atlaskit/editor-core plugins and @atlaskit/renderer",
+	"author": "Atlassian Pty Ltd",
+	"license": "Apache-2.0",
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org/"
+	},
+	"atlassian": {
+		"team": "Editor: Core Experiences",
+		"singleton": true,
+		"releaseModel": "continuous",
+		"runReact18": true
+	},
+	"repository": "https://stash.atlassian.com/projects/ATLASSIAN/repos/atlassian-frontend-monorepo",
+	"main": "dist/cjs/index.js",
+	"module": "dist/esm/index.js",
+	"module:es2019": "dist/es2019/index.js",
+	"types": "dist/types/index.d.ts",
+	"sideEffects": false,
+	"atlaskit:src": "src/index.ts",
+	"af:exports": {
+		".": "./src/index.ts",
+		"./plugin-hooks": "./src/plugin-hooks.ts",
+		"./content": "./src/consumption/content.tsx",
+		"./cache": "./src/cache.ts",
+		"./emoji-provider": "./src/providers/emoji.ts",
+		"./get-confluence-page-providers": "./src/get-providers/confluence-page.ts"
+	},
+	"dependencies": {
+		"@atlaskit/adf-schema": "^40.8.1",
+		"@atlaskit/adf-utils": "^19.8.0",
+		"@atlaskit/emoji": "^67.7.0",
+		"@babel/runtime": "^7.0.0"
+	},
+	"peerDependencies": {
+		"react": "^16.8.0"
+	},
+	"devDependencies": {
+		"@atlaskit/editor-test-helpers": "*",
+		"@testing-library/react": "^12.1.5",
+		"@testing-library/react-hooks": "^8.0.1",
+		"typescript": "~5.4.2"
+	},
+	"techstack": {
+		"@atlassian/frontend": {
+			"import-structure": [
+				"atlassian-conventions"
+			],
+			"circular-dependencies": [
+				"file-and-folder-level"
+			]
+		},
+		"@repo/internal": {
+			"dom-events": "use-bind-event-listener",
+			"analytics": [
+				"analytics-next"
+			],
+			"deprecation": [
+				"no-deprecated-imports"
+			],
+			"imports": [
+				"import-no-extraneous-disable-for-examples-and-docs"
+			]
+		}
+	},
+	"stricter": {
+		"no-unused-dependencies": {
+			"checkDevDependencies": true
+		}
+	}
+}

package/plugin-hooks/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@atlaskit/node-data-provider/plugin-hooks",
+  "main": "../dist/cjs/plugin-hooks.js",
+  "module": "../dist/esm/plugin-hooks.js",
+  "module:es2019": "../dist/es2019/plugin-hooks.js",
+  "sideEffects": false,
+  "types": "../dist/types/plugin-hooks.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.4": {
+      "*": [
+        "../dist/types-ts4.5/plugin-hooks.d.ts"
+      ]
+    }
+  }
+}