Merge pull request #7 from oleast/feat/convert-options

Author: oleast

src/converters.ts

@@ -1,18 +1,12 @@
-import {
-  appendMarksToChildren,
-  isBlockType,
-  isInlineType,
-  isMarkType,
-} from "./utils";
-import type { HTMLTagName, HTMLTextNode, TagConverter } from "./types";
+import { isBlockType, isInlineType, isMarkType } from "./utils";
+import type { HTMLTagName, TagConverter, TextConverter } from "./types";
 import {
   Block,
   BLOCKS,
   Inline,
   INLINES,
   Mark,
   MARKS,
-  Text,
 } from "@contentful/rich-text-types";
 
 const DEFAULT_NODE_TYPE_FOR_HTML_TAG: Partial<
@@ -53,41 +47,38 @@ const getDefaultNodeTypeForHtmlTag = (
   return DEFAULT_NODE_TYPE_FOR_HTML_TAG[tagName];
 };
 
-export const convertTagToBlock: TagConverter = (node, next) => {
+export const convertTagToBlock: TagConverter<Block> = (node, next) => {
   const nodeType = getDefaultNodeTypeForHtmlTag(node.tagName);
   if (!nodeType || !isBlockType(nodeType)) {
     return [];
   }
-  const block: Block = {
+  return {
     nodeType,
-    content: next(node) as Array<Block | Inline | Text>,
+    content: next(node),
     data: {},
   };
-  return block;
 };
 
-export const convertTagToInline: TagConverter = (node, next) => {
+export const convertTagToInline: TagConverter<Inline> = (node, next) => {
   const nodeType = getDefaultNodeTypeForHtmlTag(node.tagName);
   if (!nodeType || !isInlineType(nodeType)) {
     return [];
   }
-  const inline: Inline = {
+  return {
     nodeType,
-    content: next(node) as Array<Inline | Text>,
+    content: next(node),
     data: {},
   };
-  return inline;
 };
 
-export const convertTagToHyperlink: TagConverter = (node, next) => {
-  const inline: Inline = {
+export const convertTagToHyperlink: TagConverter<Inline> = (node, next) => {
+  return {
     nodeType: INLINES.HYPERLINK,
-    content: next(node) as Array<Inline | Text>,
+    content: next(node),
     data: {
       uri: node.attrs.href,
     },
   };
-  return inline;
 };
 
 export const convertTagToMark: TagConverter = (node, next) => {
@@ -98,15 +89,18 @@ export const convertTagToMark: TagConverter = (node, next) => {
   const mark: Mark = {
     type: nodeType,
   };
-  return appendMarksToChildren(mark, node, next);
+  return next(node, mark);
+};
+
+export const convertTagToChildren: TagConverter<Block> = (node, next) => {
+  return next(node);
 };
 
-export const convertTextNodeToText = (node: HTMLTextNode): Text => {
-  const textNode: Text = {
+export const convertTextNodeToText: TextConverter = (node, marks) => {
+  return {
     nodeType: "text",
-    marks: [],
+    marks,
     value: node.value,
     data: {},
   };
-  return textNode;
 };

src/htmlStringToDocument.ts

@@ -3,19 +3,30 @@ import {
   convertTagToBlock,
   convertTagToHyperlink,
   convertTextNodeToText,
+  convertTagToChildren,
 } from "./converters";
 import { parseHtml } from "./parseHtml";
-import { TopLevelBlock, Document } from "@contentful/rich-text-types";
+import {
+  TopLevelBlock,
+  Document,
+  Mark,
+  Text,
+  Inline,
+  Block,
+} from "@contentful/rich-text-types";
 import type {
   HTMLNode,
   HTMLTagName,
   Next,
   Options,
+  OptionsWithDefaults,
   TagConverter,
 } from "./types";
-import { createDocumentNode } from "./utils";
+import { createDocumentNode, getAsList } from "./utils";
 
-const DEFAULT_TAG_CONVERTERS: Partial<Record<HTMLTagName, TagConverter>> = {
+const DEFAULT_TAG_CONVERTERS: Partial<
+  Record<HTMLTagName, TagConverter<Block | Inline | Text>>
+> = {
   h1: convertTagToBlock,
   h2: convertTagToBlock,
   h3: convertTagToBlock,
@@ -42,25 +53,32 @@ const DEFAULT_TAG_CONVERTERS: Partial<Record<HTMLTagName, TagConverter>> = {
   a: convertTagToHyperlink,
 };
 
-const mapHtmlNodeToRichTextNode = (node: HTMLNode, options: Options) => {
+const mapHtmlNodeToRichTextNode = (
+  node: HTMLNode,
+  marks: Mark[],
+  options: OptionsWithDefaults
+) => {
+  const { convertText, convertTag } = options;
   if (node.type === "text") {
-    const textConverter = options.convertText ?? convertTextNodeToText;
-    return textConverter(node);
+    return convertText(node, marks);
   }
 
-  const next: Next = (node) => {
+  const mapChildren: Next = (node, mark) => {
+    const newMarks = mark ? getAsList(mark) : [];
+    const allMarks = newMarks.concat(marks);
     if (node.type === "element") {
       return node.children.flatMap((child) =>
-        mapHtmlNodeToRichTextNode(child, options)
+        mapHtmlNodeToRichTextNode(child, allMarks, options)
       );
     }
-    return mapHtmlNodeToRichTextNode(node, options);
+    return getAsList(mapHtmlNodeToRichTextNode(node, allMarks, options));
+  };
+
+  const next: Next = (node, marks) => {
+    return mapChildren(node, marks);
   };
 
-  const tagConverter =
-    options?.convertTag?.[node.tagName] ??
-    DEFAULT_TAG_CONVERTERS[node.tagName] ??
-    next;
+  const tagConverter = convertTag?.[node.tagName] ?? convertTagToChildren;
   const convertedNode = tagConverter(node, next);
   return convertedNode;
 };
@@ -69,9 +87,16 @@ export const htmlStringToDocument = (
   htmlString: string,
   options: Options = {}
 ): Document => {
+  const optionsWithDefaults: OptionsWithDefaults = {
+    convertTag: {
+      ...DEFAULT_TAG_CONVERTERS,
+      ...options.convertTag,
+    },
+    convertText: options.convertText ?? convertTextNodeToText,
+  };
   const parsedHtml = parseHtml(htmlString);
   const richTextNodes = parsedHtml.flatMap((node) =>
-    mapHtmlNodeToRichTextNode(node, options)
+    mapHtmlNodeToRichTextNode(node, [], optionsWithDefaults)
   );
   return createDocumentNode(richTextNodes as TopLevelBlock[]);
 };

src/index.ts

@@ -7,4 +7,6 @@ export type {
   Options,
   ConvertTagOptions,
   TagConverter,
+  TextConverter,
+  Next,
 } from "./types";

src/test/index.test.ts

@@ -4,15 +4,14 @@ import {
   Block,
   BLOCKS,
   Document,
-  Inline,
-  Text,
+  Mark,
   TopLevelBlock,
 } from "@contentful/rich-text-types";
 import { htmlStringToDocument } from "../htmlStringToDocument";
 
 import { describe, expect, it } from "vitest";
 import { EXAMPLE_RICH_TEXT } from "./example";
-import { createDocumentNode, getAsList } from "../utils";
+import { createDocumentNode } from "../utils";
 import * as helpers from "./helpers";
 
 // https://www.contentful.com/developers/docs/tutorials/general/getting-started-with-rich-text-field-type/
@@ -50,31 +49,19 @@ const richTextDocument: Document = {
 const htmlString = documentToHtmlString(EXAMPLE_RICH_TEXT);
 
 describe("Parse HTML string to Contentful Document", () => {
-  /*it("Parse string to generic HTML nodes", () => {
-    const htmlNodes = parseHtml(CISION_EXAMPLE);
-    expect(htmlNodes).toEqual([]);
-  });*/
-
-  /*it("Parse HTML string to Contentful Rich Text", () => {
-    const htmlNodes = htmlStringToDocument(CISION_EXAMPLE);
-    const newHtmlString = documentToHtmlString(htmlNodes);
-    expect(newHtmlString).toEqual(CISION_EXAMPLE);
-  });*/
-
   it("Parse HTML string to Contentful Rich Text", () => {
     const htmlNodes = htmlStringToDocument(htmlString);
     const newHtmlString = documentToHtmlString(htmlNodes);
     expect(newHtmlString).toEqual(htmlString);
   });
 
   it("Handles a simple convert option from 'div' to 'paragraph'", () => {
-    const divToParagraphConverter: TagConverter = (node, next) => {
-      const paragraph: Block = {
+    const divToParagraphConverter: TagConverter<Block> = (node, next) => {
+      return {
         nodeType: BLOCKS.PARAGRAPH,
-        content: getAsList(next(node)) as Array<Block | Inline | Text>,
+        content: next(node),
         data: {},
       };
-      return paragraph;
     };
     const matchText = "This is text in a div";
     const htmlNodes = htmlStringToDocument(`<div>${matchText}</div>`, {
@@ -92,4 +79,37 @@ describe("Parse HTML string to Contentful Document", () => {
       createDocumentNode([matchNode as TopLevelBlock])
     );
   });
+
+  it("Handles a complex convert option from 'span' with bold class to 'paragraph' and 'bold' mark", () => {
+    const styledSpanToMarkedParagraphConverter: TagConverter<Block> = (
+      node,
+      next
+    ) => {
+      const isBold = node.attrs.class === "bold";
+      const marks = isBold ? ({ type: "bold" } satisfies Mark) : undefined;
+      return {
+        nodeType: BLOCKS.PARAGRAPH,
+        content: next(node, marks),
+        data: {},
+      };
+    };
+    const matchText = "text";
+    const htmlNodes = htmlStringToDocument(
+      `<span class="bold">${matchText}</span>`,
+      {
+        convertTag: {
+          span: styledSpanToMarkedParagraphConverter,
+        },
+      }
+    );
+
+    const matchNode = createDocumentNode([
+      helpers.createBlock(
+        BLOCKS.PARAGRAPH,
+        helpers.createText(matchText, { type: "bold" })
+      ),
+    ] as TopLevelBlock[]);
+
+    expect(htmlNodes).toMatchObject(matchNode);
+  });
 });

src/types.ts

@@ -1,4 +1,10 @@
-import type { Mark, Node, Text } from "@contentful/rich-text-types";
+import type {
+  Block,
+  Inline,
+  Mark,
+  Node,
+  Text,
+} from "@contentful/rich-text-types";
 
 export type HTMLTagName = keyof HTMLElementTagNameMap;
 
@@ -16,19 +22,42 @@ export interface HTMLElementNode {
 
 export type HTMLNode = HTMLElementNode | HTMLTextNode;
 
+export type ContentfulNodeContent<TNodeType extends AnyContentfulNode> =
+  TNodeType extends Block
+    ? Block["content"][0]
+    : TNodeType extends Inline
+    ? Inline["content"][0]
+    : TNodeType extends Mark
+    ? Block["content"][0]
+    : TNodeType extends Text
+    ? Text
+    : never;
+
 export type AnyContentfulNode = Node | Mark | Text;
-export type ConverterResult = AnyContentfulNode | Array<AnyContentfulNode>;
+export type ConverterResult<TNodeType extends AnyContentfulNode> =
+  | ContentfulNodeContent<TNodeType>
+  | Array<ContentfulNodeContent<TNodeType>>;
+
+export type Next<TNodeType extends AnyContentfulNode = Block | Inline | Text> =
+  (
+    node: HTMLNode,
+    marks?: Mark | Mark[]
+  ) => Array<ContentfulNodeContent<TNodeType>>;
 
-export type Next = (node: HTMLNode) => ConverterResult;
+export type TextConverter = (node: HTMLTextNode, marks: Mark[]) => Text;
 
-export type TagConverter = (
+export type TagConverter<
+  TNodeType extends AnyContentfulNode = Block | Inline | Text
+> = (
   node: HTMLElementNode,
-  next: Next
-) => ConverterResult;
+  next: Next<TNodeType>
+) => ConverterResult<TNodeType>;
 
 export type ConvertTagOptions = Record<HTMLTagName | string, TagConverter>;
 
-export interface Options {
-  convertTag?: ConvertTagOptions;
-  convertText?: (node: HTMLTextNode) => Text;
+export interface OptionsWithDefaults {
+  convertTag: ConvertTagOptions;
+  convertText: TextConverter;
 }
+
+export type Options = Partial<OptionsWithDefaults>;

src/utils.ts

@@ -1,4 +1,3 @@
-import { Next, ConverterResult, HTMLNode } from "./types";
 import {
   BLOCKS,
   Document,
@@ -46,22 +45,6 @@ export const isNodeTypeText = (node: Node | Text | Mark): node is Text => {
   return false;
 };
 
-export const appendMarksToChildren = (
-  mark: Mark | Mark[],
-  node: HTMLNode,
-  next: Next
-): ConverterResult => {
-  const children = next(node);
-  const childrenAsList = getAsList(children);
-  const marksAsList = getAsList(mark);
-  return childrenAsList.map((child) => {
-    if (isNodeTypeText(child)) {
-      child.marks = [...child.marks, ...marksAsList];
-    }
-    return child;
-  });
-};
-
 export const createDocumentNode = (
   content: TopLevelBlock[],
   data: NodeData = {}