fix(docs): add documentation for parserOptions and postProcessing

Author: oleast

README.md

@@ -270,3 +270,67 @@ htmlStringToDocument(htmlString, options);
 //   ],
 // };
 ```
+
+## invalid Rich Text Documents
+
+The Contentful Rich Text format requires the `Document` adhere to a specific format.
+The full ruleset can be found in the [Contentful Documentation](https://www.contentful.com/developers/docs/concepts/rich-text/#rules-of-rich-text).
+
+By default this library will convert any HTML node by node to create a rich text document. This means that the result can be an invalid document.
+
+Uploading an invalid document to Contentful will result in an error. The `@contentful/rich-text-types` package from Contentful includes a `validateRichTextDocument` as of version `17.0.0`.
+
+**To mitigate invalid documents you have a few options:**
+
+- Use the built in `parserOptions` and/or `postProcessing` options. (Currently useful for removing whitespace, and fixing top level nodes).
+- Add a custom `TagConverter` og `TextConverter` that handles your case. (To handle cases like wrong child elements of `Inline` nodes, list elements, or tables).
+- Change your HTML to a valid format before converting it.
+
+### Handling invalid top level nodes
+
+Some elements can not be at the top level of a `Document`. This includes `Text`-nodes, `Inline`-nodes, `li`-elements, and any child element of `table` (like a `tr` or `td`).
+
+To handle cases where this appears this library includes a few utilities that process document after it has been created.
+
+These options are:
+
+- `options.postProcessing.handleTopLevelText: "preserve" | "remove" | "wrap-paragraph"`. Default: `"preserve"`.
+- `options.postProcessing.handleTopLevelInlines: "preserve" | "remove" | "wrap-paragraph"`. Default: `"preserve"`.
+
+Examples of usage:
+
+```typescript
+const htmlNodes = htmlStringToDocument(html, {
+  postProcessing: {
+    handleTopLevelText: "wrap-paragraph",
+    handleTopLevelInlines: "remove",
+  },
+});
+```
+
+How it works:
+
+- `"preserve"`: Keep top level nodes as they are, even if it results in an invalid `Document`.
+- `"remove"`: Remove the node with all its child nodes from the document.
+- `"wrap-paragraph"`: Wrap the node in a simple `paragraph`-node to make it valid.
+
+### Handling extra whitespace nodes
+
+A formatted HTML string might include whitespace that will be parsed and added to the document output. This can result in unwanted text nodes or an invalid document.
+
+Whitespace can be removed by using the `handleWhitespaceNodes` option.
+
+- `optons.parserOptions.handleWhitespaceNodes: "preserve" | "remove"`. Default: `"preserve"`.
+
+```typescript
+const htmlNodes = htmlStringToDocument(html, {
+  parserOptions: {
+    handleWhitespaceNodes: "preserve",
+  },
+});
+```
+
+How it works:
+
+- `"preserve"`: Keep all whitespace text nodes as they are in the original html string.
+- `"remove"`: Remove any text node that consist purely of whitespace from the HTML node tree. Uses the following Regex `/^\s*$/`.

src/htmlStringToDocument.ts

@@ -91,13 +91,21 @@ export const htmlStringToDocument = (
       ...options.convertTag,
     },
     convertText: options.convertText ?? convertTextNodeToText,
-    handleTopLevelInlines: options.handleTopLevelInlines ?? "preserve",
-    handleTopLevelText: options.handleTopLevelText ?? "preserve",
-    ignoreWhiteSpace: options.ignoreWhiteSpace ?? false,
+    parserOptions: {
+      handleWhitespaceNodes:
+        options?.parserOptions?.handleWhitespaceNodes ?? "preserve",
+    },
+    postProcessing: {
+      handleTopLevelInlines:
+        options?.postProcessing?.handleTopLevelInlines ?? "preserve",
+      handleTopLevelText:
+        options?.postProcessing?.handleTopLevelText ?? "preserve",
+    },
   };
 
   const parserOptions: ParserOptions = {
-    ignoreWhiteSpace: optionsWithDefaults.ignoreWhiteSpace,
+    ignoreWhiteSpace:
+      optionsWithDefaults.parserOptions.handleWhitespaceNodes == "remove",
   };
 
   const parsedHtml = parseHtml(htmlString, parserOptions);

src/processConvertedNodesFromTopLevel.ts

@@ -29,10 +29,10 @@ export const processConvertedNodesFromTopLevel = (
     return node as unknown as TopLevelBlock;
   }
   if (isNodeTypeInline(node)) {
-    if (options.handleTopLevelInlines === "remove") {
+    if (options.postProcessing.handleTopLevelInlines === "remove") {
       return null;
     }
-    if (options.handleTopLevelInlines === "wrap-paragraph") {
+    if (options.postProcessing.handleTopLevelInlines === "wrap-paragraph") {
       return {
         nodeType: BLOCKS.PARAGRAPH,
         data: {},
@@ -42,10 +42,10 @@ export const processConvertedNodesFromTopLevel = (
     return node as unknown as TopLevelBlock;
   }
   if (isNodeTypeText(node)) {
-    if (options.handleTopLevelText === "remove") {
+    if (options.postProcessing.handleTopLevelText === "remove") {
       return null;
     }
-    if (options.handleTopLevelText === "wrap-paragraph") {
+    if (options.postProcessing.handleTopLevelText === "wrap-paragraph") {
       return {
         nodeType: BLOCKS.PARAGRAPH,
         data: {},

src/test/index.test.ts

@@ -108,7 +108,9 @@ describe("Processing top level inline nodes to valid formats", () => {
   it("Removes an invalid top level inline node", () => {
     const htmlNodes = htmlStringToDocument(
       `<a href="http://example.com">Top level hyperlink</a>`,
-      { handleTopLevelInlines: "remove" },
+      {
+        postProcessing: { handleTopLevelInlines: "remove" },
+      },
     );
     const matchNode = createDocumentNode([] as TopLevelBlock[]);
 
@@ -119,7 +121,9 @@ describe("Processing top level inline nodes to valid formats", () => {
   it("Wraps an invalid top level inline node in a paragraph", () => {
     const htmlNodes = htmlStringToDocument(
       `<a href="http://example.com">Top level hyperlink</a>`,
-      { handleTopLevelInlines: "wrap-paragraph" },
+      {
+        postProcessing: { handleTopLevelInlines: "wrap-paragraph" },
+      },
     );
     const matchNode = createDocumentNode([
       helpers.createBlock(
@@ -156,7 +160,7 @@ describe("Processing top level text nodes to valid formats", () => {
     const htmlNodes = htmlStringToDocument(
       "<div>Text under top level div</div>",
       {
-        handleTopLevelText: "wrap-paragraph",
+        postProcessing: { handleTopLevelText: "wrap-paragraph" },
       },
     );
     const matchNode = createDocumentNode([
@@ -173,7 +177,9 @@ describe("Processing top level text nodes to valid formats", () => {
   it("Removes an invalid top level text node", () => {
     const htmlNodes = htmlStringToDocument(
       "<div>Text under top level div</div>",
-      { handleTopLevelText: "remove" },
+      {
+        postProcessing: { handleTopLevelText: "remove" },
+      },
     );
     const matchNode = createDocumentNode([] as TopLevelBlock[]);
 
@@ -186,7 +192,9 @@ describe("Processing top level text nodes to valid formats", () => {
       "Some unwrapped text prefixing a p tag." +
         "<p>Paragraph content <span>I am a text node</span></p>" +
         "Some unwrapped text suffixing a p tag",
-      { handleTopLevelText: "wrap-paragraph" },
+      {
+        postProcessing: { handleTopLevelText: "wrap-paragraph" },
+      },
     );
 
     const matchNode = createDocumentNode([
@@ -210,11 +218,13 @@ describe("Processing top level text nodes to valid formats", () => {
 });
 
 describe("Parsing options for whitespace", () => {
-  it("Handles text nodes with only whitespace by ignoring them", () => {
+  it("Handles text nodes with only whitespace by removing them", () => {
     const html = `<h2>Heading on the first line</h2>\n\n<p>Text on the third line.</p>`;
 
     const htmlNodes = htmlStringToDocument(html, {
-      ignoreWhiteSpace: true,
+      parserOptions: {
+        handleWhitespaceNodes: "remove",
+      },
     });
 
     const matchNode = createDocumentNode([
@@ -232,11 +242,13 @@ describe("Parsing options for whitespace", () => {
     expect(validateRichTextDocument(htmlNodes).length).toEqual(0);
   });
 
-  it("Handles text nodes with only whitespace by including them", () => {
+  it("Handles text nodes with only whitespace by preserving them", () => {
     const html = `<h2>Heading on the first line</h2>\n\n<p>Text on the third line.</p>`;
 
     const htmlNodes = htmlStringToDocument(html, {
-      ignoreWhiteSpace: false,
+      parserOptions: {
+        handleWhitespaceNodes: "preserve",
+      },
     });
 
     const matchNode = createDocumentNode([

src/types.ts

@@ -55,15 +55,29 @@ export type TagConverter<
 
 export type ConvertTagOptions = Record<HTMLTagName | string, TagConverter>;
 
+export type HandleWhitespaceNodes = "preserve" | "remove";
 export type HandleTopLevelText = "preserve" | "remove" | "wrap-paragraph";
 export type HandleTopLevelInlines = "preserve" | "remove" | "wrap-paragraph";
 
+export interface ParserOptions {
+  handleWhitespaceNodes: HandleWhitespaceNodes;
+}
+
+export interface PostProcessingOptions {
+  handleTopLevelInlines: HandleTopLevelInlines;
+  handleTopLevelText: HandleTopLevelText;
+}
+
 export interface OptionsWithDefaults {
   convertTag: ConvertTagOptions;
   convertText: TextConverter;
-  handleTopLevelInlines: HandleTopLevelInlines;
-  handleTopLevelText: HandleTopLevelText;
-  ignoreWhiteSpace: boolean;
+  parserOptions: ParserOptions;
+  postProcessing: PostProcessingOptions;
 }
 
-export type Options = Partial<OptionsWithDefaults>;
+export type Options = Partial<
+  Omit<OptionsWithDefaults, "parserOptions" | "postProcessing"> & {
+    parserOptions: Partial<ParserOptions>;
+    postProcessing: Partial<PostProcessingOptions>;
+  }
+>;