@tiptap/static-renderer 3.0.0-next.1 → 3.0.0-next.5

package/dist/index.d.ts

@@ -1,52 +1,327 @@
-import { ExtensionAttribute } from '@tiptap/core';
+import { NodeType, MarkType, ExtensionAttribute, Node, Mark as Mark$1, JSONContent, Extensions } from '@tiptap/core';
+import React from 'react';
+import { DOMOutputSpec, Mark, Node as Node$1 } from '@tiptap/pm/model';
 
 /**
- * A mark type is either a JSON representation of a mark or a Prosemirror mark instance
+ * This function returns the attributes of a node or mark that are defined by the given extension attributes.
+ * @param nodeOrMark The node or mark to get the attributes from
+ * @param extensionAttributes The extension attributes to use
+ * @param onlyRenderedAttributes If true, only attributes that are rendered in the HTML are returned
+ */
+declare function getAttributes(nodeOrMark: NodeType | MarkType, extensionAttributes: ExtensionAttribute[], onlyRenderedAttributes?: boolean): Record<string, any>;
+/**
+ * This function returns the HTML attributes of a node or mark that are defined by the given extension attributes.
+ * @param nodeOrMark The node or mark to get the attributes from
+ * @param extensionAttributes The extension attributes to use
+ */
+declare function getHTMLAttributes(nodeOrMark: NodeType | MarkType, extensionAttributes: ExtensionAttribute[]): Record<string, any>;
+
+/**
+ * Props for a node renderer
  */
-type MarkType<Type extends string = any, Attributes extends undefined | Record<string, any> = any> = {
-    type: Type;
-    attrs: Attributes;
+type NodeProps<TNodeType = any, TChildren = any> = {
+    /**
+     * The current node to render
+     */
+    node: TNodeType;
+    /**
+     * Unless the node is the root node, this will always be defined
+     */
+    parent?: TNodeType;
+    /**
+     * The children of the current node
+     */
+    children?: TChildren;
+    /**
+     * Render a child element
+     */
+    renderElement: (props: {
+        /**
+         * Tiptap JSON content to render
+         */
+        content: TNodeType;
+        /**
+         * The parent node of the current node
+         */
+        parent?: TNodeType;
+    }) => TChildren;
 };
 /**
- * A node type is either a JSON representation of a node or a Prosemirror node instance
+ * Props for a mark renderer
  */
-type NodeType<Type extends string = any, Attributes extends undefined | Record<string, any> = any, NodeMarkType extends MarkType = any, Content extends NodeType[] = any> = {
-    type: Type;
-    attrs: Attributes;
-    content?: Content;
-    marks?: NodeMarkType[];
-    text?: string;
+type MarkProps<TMarkType = any, TChildren = any, TNodeType = any> = {
+    /**
+     * The current mark to render
+     */
+    mark: TMarkType;
+    /**
+     * The children of the current mark
+     */
+    children?: TChildren;
+    /**
+     * The node the current mark is applied to
+     */
+    node: TNodeType;
+    /**
+     * The node the current mark is applied to
+     */
+    parent?: TNodeType;
 };
+type TiptapStaticRendererOptions<
+/**
+ * The return type of the render function (e.g. React.ReactNode, string)
+ */
+TReturnType, 
+/**
+ * A mark type is either a JSON representation of a mark or a Prosemirror mark instance
+ */
+TMarkType extends {
+    type: any;
+} = MarkType, 
 /**
- * A node type is either a JSON representation of a doc node or a Prosemirror doc node instance
+ * A node type is either a JSON representation of a node or a Prosemirror node instance
  */
-type DocumentType<TNodeAttributes extends Record<string, any> = Record<string, any>, TContentType extends NodeType[] = NodeType[]> = NodeType<'doc', TNodeAttributes, never, TContentType>;
+TNodeType extends {
+    content?: {
+        forEach: (cb: (node: TNodeType) => void) => void;
+    };
+    marks?: readonly TMarkType[];
+    type: string | {
+        name: string;
+    };
+} = NodeType, 
 /**
- * A node type is either a JSON representation of a text node or a Prosemirror text node instance
+ * A node renderer is a function that takes a node and its children and returns the rendered output
  */
-type TextType<TMarkType extends MarkType = MarkType> = {
-    type: 'text';
-    text: string;
-    marks: TMarkType[];
+TNodeRender extends (ctx: NodeProps<TNodeType, TReturnType | TReturnType[]>) => TReturnType = (ctx: NodeProps<TNodeType, TReturnType | TReturnType[]>) => TReturnType, 
+/**
+ * A mark renderer is a function that takes a mark and its children and returns the rendered output
+ */
+TMarkRender extends (ctx: MarkProps<TMarkType, TReturnType | TReturnType[], TNodeType>) => TReturnType = (ctx: MarkProps<TMarkType, TReturnType | TReturnType[], TNodeType>) => TReturnType> = {
+    /**
+     * Mapping of node types to react components
+     */
+    nodeMapping: Record<string, NoInfer<TNodeRender>>;
+    /**
+     * Mapping of mark types to react components
+     */
+    markMapping: Record<string, NoInfer<TMarkRender>>;
+    /**
+     * Component to render if a node type is not handled
+     */
+    unhandledNode?: NoInfer<TNodeRender>;
+    /**
+     * Component to render if a mark type is not handled
+     */
+    unhandledMark?: NoInfer<TMarkRender>;
 };
 /**
- * Describes the output of a `renderHTML` function in prosemirror
- * @see https://prosemirror.net/docs/ref/#model.DOMOutputSpec
+ * Tiptap Static Renderer
+ * ----------------------
+ *
+ * This function is a basis to allow for different renderers to be created.
+ * Generic enough to be able to statically render Prosemirror JSON or Prosemirror Nodes.
+ *
+ * Using this function, you can create a renderer that takes a JSON representation of a Prosemirror document
+ * and renders it using a mapping of node types to React components or even to a string.
+ * This function is used as the basis to create the `reactRenderer` and `stringRenderer` functions.
+ */
+declare function TiptapStaticRenderer<
+/**
+ * The return type of the render function (e.g. React.ReactNode, string)
+ */
+TReturnType, 
+/**
+ * A mark type is either a JSON representation of a mark or a Prosemirror mark instance
+ */
+TMarkType extends {
+    type: string | {
+        name: string;
+    };
+} = MarkType, 
+/**
+ * A node type is either a JSON representation of a node or a Prosemirror node instance
+ */
+TNodeType extends {
+    content?: {
+        forEach: (cb: (node: TNodeType) => void) => void;
+    };
+    marks?: readonly TMarkType[];
+    type: string | {
+        name: string;
+    };
+} = NodeType, 
+/**
+ * A node renderer is a function that takes a node and its children and returns the rendered output
+ */
+TNodeRender extends (ctx: NodeProps<TNodeType, TReturnType | TReturnType[]>) => TReturnType = (ctx: NodeProps<TNodeType, TReturnType | TReturnType[]>) => TReturnType, 
+/**
+ * A mark renderer is a function that takes a mark and its children and returns the rendered output
+ */
+TMarkRender extends (ctx: MarkProps<TMarkType, TReturnType | TReturnType[], TNodeType>) => TReturnType = (ctx: MarkProps<TMarkType, TReturnType | TReturnType[], TNodeType>) => TReturnType>(
+/**
+ * The function that actually renders the component
  */
-type DOMOutputSpecArray = [string] | [string, Record<string, any>] | [string, 0] | [string, Record<string, any>, 0] | [string, Record<string, any>, DOMOutputSpecArray | 0] | [string, DOMOutputSpecArray];
+renderComponent: (ctx: {
+    component: TNodeRender;
+    props: NodeProps<TNodeType, TReturnType | TReturnType[]>;
+} | {
+    component: TMarkRender;
+    props: MarkProps<TMarkType, TReturnType | TReturnType[], TNodeType>;
+}) => TReturnType, { nodeMapping, markMapping, unhandledNode, unhandledMark, }: TiptapStaticRendererOptions<TReturnType, TMarkType, TNodeType, TNodeRender, TMarkRender>): ({ content, parent, }: {
+    /**
+     * Tiptap JSON content to render
+     */
+    content: TNodeType;
+    /**
+     * The parent node of the current node
+     */
+    parent?: TNodeType;
+}) => TReturnType;
 
+declare function renderJSONContentToString<
 /**
- * This function returns the attributes of a node or mark that are defined by the given extension attributes.
- * @param nodeOrMark The node or mark to get the attributes from
- * @param extensionAttributes The extension attributes to use
- * @param onlyRenderedAttributes If true, only attributes that are rendered in the HTML are returned
+ * A mark type is either a JSON representation of a mark or a Prosemirror mark instance
  */
-declare function getAttributes(nodeOrMark: NodeType | MarkType, extensionAttributes: ExtensionAttribute[], onlyRenderedAttributes?: boolean): Record<string, any>;
+TMarkType extends {
+    type: any;
+} = MarkType, 
 /**
- * This function returns the HTML attributes of a node or mark that are defined by the given extension attributes.
- * @param nodeOrMark The node or mark to get the attributes from
- * @param extensionAttributes The extension attributes to use
+ * A node type is either a JSON representation of a node or a Prosemirror node instance
  */
-declare function getHTMLAttributes(nodeOrMark: NodeType | MarkType, extensionAttributes: ExtensionAttribute[]): Record<string, any>;
+TNodeType extends {
+    content?: {
+        forEach: (cb: (node: TNodeType) => void) => void;
+    };
+    marks?: readonly TMarkType[];
+    type: string | {
+        name: string;
+    };
+} = NodeType>(options: TiptapStaticRendererOptions<string, TMarkType, TNodeType>): ({ content, parent, }: {
+    content: TNodeType;
+    parent?: TNodeType | undefined;
+}) => string;
+/**
+ * Serialize the attributes of a node or mark to a string
+ * @param attrs The attributes to serialize
+ * @returns The serialized attributes as a string
+ */
+declare function serializeAttrsToHTMLString(attrs: Record<string, any> | undefined | null): string;
+/**
+ * Serialize the children of a node or mark to a string
+ * @param children The children to serialize
+ * @returns The serialized children as a string
+ */
+declare function serializeChildrenToHTMLString(children?: string | string[]): string;
+
+declare function renderJSONContentToReactElement<
+/**
+ * A mark type is either a JSON representation of a mark or a Prosemirror mark instance
+ */
+TMarkType extends {
+    type: any;
+} = MarkType, 
+/**
+ * A node type is either a JSON representation of a node or a Prosemirror node instance
+ */
+TNodeType extends {
+    content?: {
+        forEach: (cb: (node: TNodeType) => void) => void;
+    };
+    marks?: readonly TMarkType[];
+    type: string | {
+        name: string;
+    };
+} = NodeType>(options: TiptapStaticRendererOptions<React.ReactNode, TMarkType, TNodeType>): ({ content, parent, }: {
+    content: TNodeType;
+    parent?: TNodeType | undefined;
+}) => React.ReactNode;
+
+type DomOutputSpecToElement<T> = (content: DOMOutputSpec) => (children?: T | T[]) => T;
+/**
+ * This takes a NodeExtension and maps it to a React component
+ * @param extension The node extension to map to a React component
+ * @param extensionAttributes All available extension attributes
+ * @returns A tuple with the name of the extension and a React component that renders the extension
+ */
+declare function mapNodeExtensionToReactNode<T>(domOutputSpecToElement: DomOutputSpecToElement<T>, extension: Node, extensionAttributes: ExtensionAttribute[], options?: Partial<Pick<TiptapStaticRendererOptions<T, Mark, Node$1>, 'unhandledNode'>>): [string, (props: NodeProps<Node$1, T | T[]>) => T];
+/**
+ * This takes a MarkExtension and maps it to a React component
+ * @param extension The mark extension to map to a React component
+ * @param extensionAttributes All available extension attributes
+ * @returns A tuple with the name of the extension and a React component that renders the extension
+ */
+declare function mapMarkExtensionToReactNode<T>(domOutputSpecToElement: DomOutputSpecToElement<T>, extension: Mark$1, extensionAttributes: ExtensionAttribute[], options?: Partial<Pick<TiptapStaticRendererOptions<T, Mark, Node$1>, 'unhandledMark'>>): [string, (props: MarkProps<Mark, T | T[]>) => T];
+/**
+ * This function will statically render a Prosemirror Node to a target element type using the given extensions
+ * @param renderer The renderer to use to render the Prosemirror Node to the target element type
+ * @param domOutputSpecToElement A function that takes a Prosemirror DOMOutputSpec and returns a function that takes children and returns the target element type
+ * @param mapDefinedTypes An object with functions to map the doc and text types to the target element type
+ * @param content The Prosemirror Node to render
+ * @param extensions The extensions to use to render the Prosemirror Node
+ * @param options Additional options to pass to the renderer that can override the default behavior
+ * @returns The rendered target element type
+ */
+declare function renderToElement<T>({ renderer, domOutputSpecToElement, mapDefinedTypes, content, extensions, options, }: {
+    renderer: (options: TiptapStaticRendererOptions<T, Mark, Node$1>) => (ctx: {
+        content: Node$1;
+    }) => T;
+    domOutputSpecToElement: DomOutputSpecToElement<T>;
+    mapDefinedTypes: {
+        doc: (props: NodeProps<Node$1, T | T[]>) => T;
+        text: (props: NodeProps<Node$1, T | T[]>) => T;
+    };
+    content: Node$1 | JSONContent;
+    extensions: Extensions;
+    options?: Partial<TiptapStaticRendererOptions<T, Mark, Node$1>>;
+}): T;
+
+/**
+ * Take a DOMOutputSpec and return a function that can render it to a string
+ * @param content The DOMOutputSpec to convert to a string
+ * @returns A function that can render the DOMOutputSpec to a string
+ */
+declare function domOutputSpecToHTMLString(content: DOMOutputSpec): (children?: string | string[]) => string;
+/**
+ * This function will statically render a Prosemirror Node to HTML using the provided extensions and options
+ * @param content The content to render to HTML
+ * @param extensions The extensions to use for rendering
+ * @param options The options to use for rendering
+ * @returns The rendered HTML string
+ */
+declare function renderToHTMLString({ content, extensions, options, }: {
+    content: Node$1 | JSONContent;
+    extensions: Extensions;
+    options?: Partial<TiptapStaticRendererOptions<string, Mark, Node$1>>;
+}): string;
+
+/**
+ * This code is just to show the flexibility of this renderer. We can potentially render content to any format we want.
+ * This is a simple example of how we can render content to markdown. This is not a full implementation of a markdown renderer.
+ */
+declare function renderToMarkdown({ content, extensions, options, }: {
+    content: Node$1 | JSONContent;
+    extensions: Extensions;
+    options?: Partial<TiptapStaticRendererOptions<string, Mark, Node$1>>;
+}): string;
+
+/**
+ * Take a DOMOutputSpec and return a function that can render it to a React element
+ * @param content The DOMOutputSpec to convert to a React element
+ * @returns A function that can render the DOMOutputSpec to a React element
+ */
+declare function domOutputSpecToReactElement(content: DOMOutputSpec, key?: number): (children?: React.ReactNode) => React.ReactNode;
+/**
+ * This function will statically render a Prosemirror Node to a React component using the given extensions
+ * @param content The content to render to a React component
+ * @param extensions The extensions to use for rendering
+ * @param options The options to use for rendering
+ * @returns The React element that represents the rendered content
+ */
+declare function renderToReactElement({ content, extensions, options, }: {
+    content: Node$1 | JSONContent;
+    extensions: Extensions;
+    options?: Partial<TiptapStaticRendererOptions<React.ReactNode, Mark, Node$1>>;
+}): React.ReactNode;
 
-export { type DOMOutputSpecArray, type DocumentType, type MarkType, type NodeType, type TextType, getAttributes, getHTMLAttributes };
+export { type DomOutputSpecToElement, type MarkProps, type NodeProps, TiptapStaticRenderer, type TiptapStaticRendererOptions, domOutputSpecToHTMLString, domOutputSpecToReactElement, getAttributes, getHTMLAttributes, mapMarkExtensionToReactNode, mapNodeExtensionToReactNode, renderJSONContentToReactElement, renderJSONContentToString, renderToElement, renderToHTMLString, renderToMarkdown, renderToReactElement, serializeAttrsToHTMLString, serializeChildrenToHTMLString };