feat(valid-document): add options that result in valid documents

- Add option to remove invalid white space text elements
- Add option to handle invalid inline nodes at top level
- Add option to handle invalid text nodes at top level

Author: oleast

src/htmlStringToDocument.ts

@@ -5,28 +5,24 @@ import {
   convertTextNodeToText,
   convertTagToChildren,
 } from "./converters";
-import { parseHtml } from "./parseHtml";
+import { parseHtml, ParserOptions } from "./parseHtml";
 import {
-  TopLevelBlock,
   Document,
   Mark,
   Text,
   Inline,
   Block,
-  BLOCKS,
 } from "@contentful/rich-text-types";
 import type {
-  HTMLElementNode,
   HTMLNode,
   HTMLTagName,
-  HTMLTextNode,
   Next,
   Options,
   OptionsWithDefaults,
   TagConverter,
-  TextConverter,
 } from "./types";
-import { createDocumentNode, getAsList, isWhiteSpace } from "./utils";
+import { createDocumentNode, getAsList, isNotNull } from "./utils";
+import { processConvertedNodesFromTopLevel } from "./processConvertedNodesFromTopLevel";
 
 const DEFAULT_TAG_CONVERTERS: Partial<
   Record<HTMLTagName, TagConverter<Block | Inline | Text>>
@@ -61,7 +57,6 @@ const mapHtmlNodeToRichTextNode = (
   node: HTMLNode,
   marks: Mark[],
   options: OptionsWithDefaults,
-  isTopLevel = false,
 ) => {
   const { convertText, convertTag } = options;
 
@@ -96,34 +91,22 @@ export const htmlStringToDocument = (
       ...options.convertTag,
     },
     convertText: options.convertText ?? convertTextNodeToText,
-    wrapTopLevelTextNodesInParagraphs: false,
-    ignoreWhiteSpace: false,
-    isWhiteSpace: options.isWhiteSpace ?? isWhiteSpace,
+    handleTopLevelInlines: options.handleTopLevelInlines ?? "preserve",
+    handleTopLevelText: options.handleTopLevelText ?? "preserve",
+    ignoreWhiteSpace: options.ignoreWhiteSpace ?? false,
   };
-  const parsedHtml = parseHtml(htmlString);
-  const richTextNodes = parsedHtml.flatMap((node) =>
-    mapHtmlNodeToRichTextNode(node, [], optionsWithDefaults, true),
-  );
 
-  const richTextNodesWithTopLevelTextNodesConverted: TopLevelBlock[] =
-    richTextNodes.map((node) => {
-      if (node.nodeType === "text") {
-        return {
-          data: {},
-          nodeType: BLOCKS.PARAGRAPH,
-          content: [
-            {
-              ...node,
-              nodeType: "text",
-            },
-          ],
-        };
-      }
+  const parserOptions: ParserOptions = {
+    ignoreWhiteSpace: optionsWithDefaults.ignoreWhiteSpace,
+  };
 
-      //TODO: Remove this type assertion.
-      // Other possible non-top level blocks are: LIST_ITEM, TABLE_ROW, TABLE_CELL and TABLE_HEADER_CELL
-      return node as TopLevelBlock;
-    });
+  const parsedHtml = parseHtml(htmlString, parserOptions);
+  const richTextNodes = parsedHtml.flatMap((node) =>
+    mapHtmlNodeToRichTextNode(node, [], optionsWithDefaults),
+  );
+  const processedRichTextNodes = richTextNodes
+    .map((node) => processConvertedNodesFromTopLevel(node, optionsWithDefaults))
+    .filter(isNotNull);
 
-  return createDocumentNode(richTextNodesWithTopLevelTextNodesConverted);
+  return createDocumentNode(processedRichTextNodes);
 };

src/parseHtml.ts

@@ -10,6 +10,10 @@ import { isNotNull, isWhiteSpace } from "./utils";
 
 import type { HTMLNode, HTMLTagName } from "./types";
 
+export interface ParserOptions {
+  ignoreWhiteSpace: boolean;
+}
+
 const isChildNodeComment = (childNode: ChildNode): childNode is CommentNode => {
   return childNode.nodeName === "#comment";
 };
@@ -30,9 +34,12 @@ const isChildNodeDocumentType = (
 
 const isTextNodePureWhiteSpace = (textNode: TextNode): boolean => {
   return isWhiteSpace(textNode.value);
-}
+};
 
-const mapChildNodeToHtmlNode = (childNode: ChildNode): HTMLNode | null => {
+const mapChildNodeToHtmlNode = (
+  childNode: ChildNode,
+  options: ParserOptions,
+): HTMLNode | null => {
   if (
     isChildNodeComment(childNode) ||
     isChildNodeDocumentType(childNode) ||
@@ -41,7 +48,7 @@ const mapChildNodeToHtmlNode = (childNode: ChildNode): HTMLNode | null => {
     return null;
   }
   if (isChildNodeTextNode(childNode)) {
-    if (isTextNodePureWhiteSpace(childNode)) {
+    if (options.ignoreWhiteSpace && isTextNodePureWhiteSpace(childNode)) {
       return null;
     }
     return {
@@ -54,17 +61,20 @@ const mapChildNodeToHtmlNode = (childNode: ChildNode): HTMLNode | null => {
     type: "element",
     tagName: childNode.tagName as HTMLTagName,
     children: childNode.childNodes
-      .map((c) => mapChildNodeToHtmlNode(c))
+      .map((c) => mapChildNodeToHtmlNode(c, options))
       .filter(isNotNull),
     attrs: Object.fromEntries(
       childNode.attrs.map((attr) => [attr.name, attr.value]),
     ),
   };
 };
 
-export const parseHtml = (htmlString: string): HTMLNode[] => {
+export const parseHtml = (
+  htmlString: string,
+  options: ParserOptions,
+): HTMLNode[] => {
   const parsedHtml = parseFragment(htmlString);
   return parsedHtml.childNodes
-    .map((node) => mapChildNodeToHtmlNode(node))
+    .map((node) => mapChildNodeToHtmlNode(node, options))
     .filter(isNotNull);
 };

src/processConvertedNodesFromTopLevel.ts

@@ -0,0 +1,58 @@
+import {
+  Block,
+  BLOCKS,
+  Inline,
+  Text,
+  TopLevelBlock,
+} from "@contentful/rich-text-types";
+import type { OptionsWithDefaults } from "./types";
+import {
+  isNodeTypeBlock,
+  isNodeTypeInline,
+  isNodeTypeText,
+  isNodeTypeTopLevelBlock,
+} from "./utils";
+
+export const processConvertedNodesFromTopLevel = (
+  node: Block | Inline | Text,
+  options: OptionsWithDefaults,
+): TopLevelBlock | null => {
+  if (isNodeTypeBlock(node)) {
+    if (isNodeTypeTopLevelBlock(node)) {
+      return node;
+    }
+    // Block types that can not be at the top level are: BLOCKS.DOCUMENT | BLOCKS.LIST_ITEM | BLOCKS.TABLE_ROW | BLOCKS.TABLE_CELL | BLOCKS.TABLE_HEADER_CELL
+    if (node.nodeType === BLOCKS.DOCUMENT) {
+      return null;
+    }
+    // TODO: Handle top level list items and table elements
+    return node as unknown as TopLevelBlock;
+  }
+  if (isNodeTypeInline(node)) {
+    if (options.handleTopLevelInlines === "remove") {
+      return null;
+    }
+    if (options.handleTopLevelInlines === "wrap-paragraph") {
+      return {
+        nodeType: BLOCKS.PARAGRAPH,
+        data: {},
+        content: [node],
+      };
+    }
+    return node as unknown as TopLevelBlock;
+  }
+  if (isNodeTypeText(node)) {
+    if (options.handleTopLevelText === "remove") {
+      return null;
+    }
+    if (options.handleTopLevelText === "wrap-paragraph") {
+      return {
+        nodeType: BLOCKS.PARAGRAPH,
+        data: {},
+        content: [node],
+      };
+    }
+    return node as unknown as TopLevelBlock;
+  }
+  return null;
+};

src/test/helpers.ts

@@ -2,10 +2,9 @@ import {
   Block,
   BLOCKS,
   Inline,
+  INLINES,
   Mark,
   Text,
-  TopLevelBlock,
-  TopLevelBlockEnum,
 } from "@contentful/rich-text-types";
 import { getAsList } from "../utils";
 
@@ -28,3 +27,15 @@ export const createBlock = (
     data: {},
   };
 };
+
+export const createInline = (
+  nodeType: INLINES,
+  content: Text | Inline | Array<Text | Inline>,
+  data: { [key: string]: string } = {},
+): Inline => {
+  return {
+    nodeType,
+    content: getAsList(content),
+    data,
+  };
+};