remove unnecessary functions, refactor

Author: pokornyd

README.md

@@ -21,6 +21,10 @@ Install the package via npm
 
 ## Features
 
+### API Overview
+
+![Module API](media/resolver-api-overview.png)
+
 ### Parsing rich text HTML to a JSON tree
 
 The tool provides environment-aware (browser or Node.js) `parseHtml` function to transform HTML into an array of simplified JSON trees. Any valid HTML is parsed, including all attributes. Together with built-in transformation methods, this tool is a suitable option for processing HTML and rich text from external sources, to make it compatible with Kontent.ai rich text format. See dedicated [JSON transformer docs](docs/index.md) for further information.
@@ -35,6 +39,11 @@ The tool provides environment-aware (browser or Node.js) `parseHtml` function to
 - Vue: [vue-portabletext](https://github.com/portabletext/vue-portabletext)
 - Astro: [astro-portabletext](https://github.com/theisel/astro-portabletext)
 
+> [!TIP]
+> This module re-exports modified `toHTML` function and `<PortableText>` component from `to-html` and `react-portabletext` packages respectively. These modified helpers provide default resolution for tags which are either unsupported or only partially supported in the original packages (`sub` and `sup` tags, images, tables and links).
+>
+> Make sure to use these re-exports if you want to take advantage of the default resolution.
+
 The tool provides `transformToPortableText` function to convert rich text content into an array of Portable Text blocks, with custom blocks defined for Kontent.ai-specific objects.
 
 Combined with a suitable package for the framework of your choice, this makes for an optimal solution for resolving rich text.
@@ -56,12 +65,6 @@ https://github.com/kontent-ai/rich-text-resolver-js/blob/6fe68490a32bb304d141cff
 
 https://github.com/kontent-ai/rich-text-resolver-js/blob/6fe68490a32bb304d141cff741fb7e57001550eb/showcase/showcase.ts#L14-L24
 
-> [!TIP] 
-> Package provides helpers for image resolution:
-> * React: `ImageComponent` component, accepting `PortableTextImage` as a prop.
-> * HTML: `resolveImage` function, accepting `PortableTextImage` and an optional custom resolver.
-> * Vue: `resolveImageVue` function, accepting `PortableTextImage`, Vue render function and an optional custom resolver.
-
 ##### Item link – **PortableTextItemLink**
 
 https://github.com/kontent-ai/rich-text-resolver-js/blob/6fe68490a32bb304d141cff741fb7e57001550eb/showcase/showcase.ts#L26-L34
@@ -70,49 +73,8 @@ https://github.com/kontent-ai/rich-text-resolver-js/blob/6fe68490a32bb304d141cff
 
 https://github.com/kontent-ai/rich-text-resolver-js/blob/6fe68490a32bb304d141cff741fb7e57001550eb/showcase/showcase.ts#L36-L62
 
-> [!TIP] 
-> Package provides helpers for table resolution:
-> * React: `TableComponent` component, accepting `PortableTextTable` as a prop.
-> * HTML: `resolveTable` function, accepting `PortableTextTable` and an optional custom resolver.
-> * Vue: `resolveTableVue` function, accepting `PortableTextTable`, Vue render function and an optional custom resolver.
-
 ## Examples
 
-### Modifying portable text nodes
-
-Package exports a `traversePortableText` method, which accepts an array of `PortableTextObject` and a callback function. The method recursively traverses all nodes and their subnodes, optionally modifying them with the provided callback:
-
-```ts
-    import {
-      PortableTextObject,
-      transformToPortableText,
-      traversePortableText,
-    } from "@kontent-ai/rich-text-resolver";
-
-    const input = `<figure data-asset-id="guid" data-image-id="guid"><img src="https://asseturl.xyz" data-asset-id="guid" data-image-id="guid" alt=""></figure>`;
-
-    // Adds height parameter to asset reference and changes _type.  
-    const processBlocks = (block: PortableTextObject) => {
-      if (block._type === "image") {
-        const modifiedReference = {
-          ...block.asset,
-          height: 300
-        }
-  
-        return {
-          ...block,
-          asset: modifiedReference,
-          _type: "modifiedImage"
-        }
-      }
-
-      // logic for modifying other object types...
-    }
-
-    const portableText = transformToPortableText(input);
-    const modifiedPortableText = traversePortableText(portableText, processBlocks);
-```
-
 ### Plain HTML resolution
 
 HTML resolution using a slightly modified version of `toHTML` function from `@portabletext/to-html` package.
@@ -184,7 +146,6 @@ import {
 } from "@kontent-ai/rich-text-resolver/utils/react";
 import {
   transformToPortableText,
-  resolveTable,
 } from "@kontent-ai/rich-text-resolver";
 
 // assumes richTextElement from SDK
@@ -195,7 +156,7 @@ const resolvers: PortableTextReactResolvers = {
       const item = richTextElement.linkedItems.find(item => item.system.codename === value.component._ref);
       return <div>{item?.elements.text_element.value}</div>;
     },
-    // default components for table and image for convenience
+    // Image and Table components are used as a default fallback if a resolver isn't explicitly specified
     table: ({ value }) => <TableComponent {...value} />,
     image: ({ value }) => <ImageComponent {...value} />,
   },
@@ -286,6 +247,42 @@ const components: PortableTextComponents = {
 </template>
 ```
 
+### Modifying portable text nodes
+
+Package exports a `traversePortableText` method, which accepts an array of `PortableTextObject` and a callback function. The method recursively traverses all nodes and their subnodes, optionally modifying them with the provided callback:
+
+```ts
+    import {
+      PortableTextObject,
+      transformToPortableText,
+      traversePortableText,
+    } from "@kontent-ai/rich-text-resolver";
+
+    const input = `<figure data-asset-id="guid" data-image-id="guid"><img src="https://asseturl.xyz" data-asset-id="guid" data-image-id="guid" alt=""></figure>`;
+
+    // Adds height parameter to asset reference and changes _type.  
+    const processBlocks = (block: PortableTextObject) => {
+      if (block._type === "image") {
+        const modifiedReference = {
+          ...block.asset,
+          height: 300
+        }
+  
+        return {
+          ...block,
+          asset: modifiedReference,
+          _type: "modifiedImage"
+        }
+      }
+
+      // logic for modifying other object types...
+    }
+
+    const portableText = transformToPortableText(input);
+    const modifiedPortableText = traversePortableText(portableText, processBlocks);
+```
+
+
 ### MAPI transformation
 
 `toManagementApiFormat` is a custom transformation method built upon `toHTML` package, allowing you to restore portable text previously created from management API rich text back into MAPI supported format.
@@ -303,9 +300,9 @@ const components: PortableTextComponents = {
 ```
 
 > [!IMPORTANT]  
-> MAPI transformation logic expects Portable Text that had been previously created from management API rich text and performs only minimal validation.
+> MAPI transformation logic expects Portable Text that had been previously created from management API rich text and performs only minimal validation. It doesn't provide implicit transformation capabilities from other formats (such as delivery API).
 >
-> Transformation from other formats (such as delivery API) is not supported unless the blocks are manually adjusted to be MAPI compatible prior to running the method.
+> If you're interested in transforming external HTML or rich text to a MAPI compatible format, see [JSON transformer docs](docs/index.md) instead.
 
 [last-commit]: https://img.shields.io/github/last-commit/kontent-ai/rich-text-resolver-js?style=for-the-badge
 [contributors-shield]: https://img.shields.io/github/contributors/kontent-ai/rich-text-resolver-js?style=for-the-badge

docs/index.md

@@ -1,6 +1,6 @@
 # JSON Transformers
 
-This module provides an environment-aware (browser or Node.js) `parseHtml` function to convert an HTML string into an array of nodes. The JSON structure can subsequently be transformed using one of the provided transformation methods, either to a modified HTML string or a completely different structure, both in synchronous and asynchronous manner.
+This module provides an environment-aware (browser or Node.js) `parseHtml` function to convert an HTML string into an array of nodes. The resulting array can subsequently be modified by one of the provided functions and transformed back to HTML.
 
 This toolset can be particularly useful for transforming rich text or HTML content from external sources into a valid Kontent.ai rich text format in migration scenarios. 
 
@@ -34,38 +34,38 @@ export interface DomHtmlNode<TAttributes = Record<string, string | undefined>> {
 }
 ```
 
-The resulting array can be transformed using one of the functions included in the module.
-
 ### HTML Transformation
 
 To transform the `DomNode` array back to HTML, you can use `nodesToHtml` function or its async variant `nodesToHtmlAsync`. The function accepts the parsed array and a `transformers` object, which defines custom transformation for each HTML node. Text nodes are transformed automatically. A wildcard `*` can be used to define fallback transformation for remaining tags. If no explicit or wildcard transformation is provided, default resolution is used.
 
 #### Basic
 Basic example of HTML transformation, removing HTML attribute `style` and transforming `b` tag to `strong`:
 ```ts
-import { nodesToHtml, NodeToStringMap, parseHtml } from '@kontent-ai/rich-text-resolver';
+import { nodesToHtml, NodeToHtmlMap, parseHtml } from '@kontent-ai/rich-text-resolver';
 
 const rawHtml = `<p style="color:red">Hello <b>World!</b></p>`;
 const parsedNodes = parseHtml(rawHtml);
 
-const transformers: NodeToStringMap = {
+const transformers: NodeToHtmlMap = {
   // children contains already transformed child nodes
   b: (node, children) => `<strong>${children}</strong>`;
+
+  // wildcard transformation removes attributes from remaining nodes
   "*": (node, children) => `<${node.tagName}>${children}</${node.tagName}>`;
 };
 
 // restores original HTML with attributes
 const defaultOutput = nodesToHtml(parsedNodes, {});
 console.log(defaultOutput); // <p style="color:red">Hello <b>World!</b></p>
 
-// b is converted to strong, wildcard transformation omits attributes from remaining nodes
+// b is converted to strong, wildcard transformation is used for remaining nodes
 const customOutput = nodesToHtml(parsedNodes, transformers);
 console.log(customOutput); // <p>Hello <strong>World!</strong></p>
 ```
 
 #### Advanced
 
-For more complex scenarios, optional context and its handler can be passed to the top level transformation function (`nodesToHtml` or its async variant) as third and fourth parameters respectively.
+For more complex scenarios, optional context and its handler can be passed to `nodesToHtml` as third and fourth parameters respectively.
 
 The context can then be accessed in individual transformations, defined in the `transformers` object. If you need to dynamically update the context, you may optionally provide a context handler, which accepts current node and context as parameters and passes a cloned, modified context for child node processing, ensuring each node gets valid contextual data.
 
@@ -82,15 +82,15 @@ For that matter, we will use `nodesToHtmlAsync` method and pass an instance of J
 import { ManagementClient } from "@kontent-ai/management-sdk";
 import {
   parseHtml,
-  AsyncNodeToStringMap,
+  AsyncNodeToHtmlMap,
   nodesToHtmlAsync,
 } from "@kontent-ai/rich-text-resolver";
 
 const input = `<img src="https://website.com/image.jpg" alt="some image">`;
 const nodes = parseHtml(input);
 
 // type parameter specifies context type, in this case ManagementClient
-const transformers: AsyncNodeToStringMap<ManagementClient> = {
+const transformers: AsyncNodeToHtmlMap<ManagementClient> = {
   // context (client) can be accessed as a third parameter in each transformation
   img: async (node, _, client) =>
     await new Promise<string>(async (resolve, reject) => {
@@ -155,7 +155,7 @@ In this case, we can store depth as a context and increment it via handler anyti
 import {
   nodesToHtml,
   DomNode,
-  NodeToStringMap,
+  NodeToHtmlMap,
   parseHtml,
 } from "@kontent-ai/rich-text-resolver";
 
@@ -178,7 +178,7 @@ const depthHandler = (node: DomNode, context: DepthContext): DepthContext =>
     ? { ...context, divSpanDepth: context.divSpanDepth + 1 } // return new context with incremented depth
     : context; // return the same context if not div/span
 
-const transformers: NodeToStringMap<DepthContext> = {
+const transformers: NodeToHtmlMap<DepthContext> = {
   // we'll only define transformations for 'div' and 'span'. Default resolution will transform remaining tags.
   div: (_, children, context) =>
     // topmost div is at depth=1, as context is updated before processing.
@@ -201,56 +201,4 @@ console.log(output);
 
 ```
 
-### Generic transformation
-
-Should you need to transform the nodes to a different structure, rather than HTML (string), you can use `transformNodes` (`transformNodesAsync`) function. Its usage is similar but revolves around generics and provides further control over the output, such as specifying custom transformation for text nodes.
-
-Snippet showcasing use of `transformNodes` to convert the `DomNode` array into Portable Text, as used internally in this module. Full source code in [the corresponding TS file](../src/transformers/portable-text-transformer/portable-text-transformer.ts).
-
-```ts
-// context stores current list type and list item depth
-type ListContext = {
-  depth: number;
-  type: "number" | "bullet" | "unknown";
-};
-
-const transformers: NodeTransformers<PortableTextItem, ListContext> = {
-  text: processText,
-  tag: {
-    ...(Object.fromEntries(
-      blockElements.map((tagName) => [tagName, processBlock]),
-    ) as Record<BlockElement, NodeToPortableText<DomHtmlNode>>),
-    ...(Object.fromEntries(
-      textStyleElements.map((tagName) => [tagName, processMark]),
-    ) as Record<TextStyleElement, NodeToPortableText<DomHtmlNode>>),
-    ...(Object.fromEntries(
-      ignoredElements.map((tagName) => [tagName, ignoreProcessing]),
-    ) as Record<IgnoredElement, NodeToPortableText<DomHtmlNode>>),
-    a: processMark,
-    li: processListItem,
-    table: processTable,
-    tr: processTableRow,
-    td: processTableCell,
-    br: processLineBreak,
-    img: processImage,
-    object: processLinkedItemOrComponent,
-  },
-};
-
-const updateListContext = (node: DomNode, context: ListContext): ListContext =>
-  (isElement(node) && isListBlock(node))
-    ? { depth: context.depth + 1, type: node.tagName === "ol" ? "number" : "bullet" }
-    : context;
-
-export const nodesToPortableText = (
-  parsedNodes: DomNode[],
-): PortableTextObject[] =>
-  transformNodes(
-    parsedNodes,
-    transformers,
-    { depth: 0, type: "unknown" }, // initialization of list transformation context
-    updateListContext,
-  ) as PortableTextObject[];
-```
-
 

index.ts

@@ -1,6 +1,6 @@
-export { transformNodes, transformNodesAsync, nodesToHtml, nodesToHtmlAsync, NodeTransformer, NodeTransformers, AsyncNodeTransformer, AsyncNodeTransformers, NodeToString, NodeToStringAsync, NodeToStringMap, AsyncNodeToStringMap } from './src/index.js';
+export { nodesToHtml, nodesToHtmlAsync, NodeToHtml, NodeToHtmlAsync, NodeToHtmlMap, AsyncNodeToHtmlMap } from './src/index.js';
 export { traversePortableText } from './src/utils/transformer-utils.js';
-export { nodesToPortableText, transformToPortableText } from "./src/transformers/portable-text-transformer/portable-text-transformer.js";
+export { transformToPortableText } from "./src/transformers/portable-text-transformer/portable-text-transformer.js";
 export { parseHtml } from "./src/parser/index.js";
 export { resolveImage, resolveTable, toHTMLImageDefault, PortableTextHtmlResolvers, toHTML } from "./src/utils/resolution/html.js";
 export { resolveImage as resolveImageVue, resolveTable as resolveTableVue, toVueImageDefault } from "./src/utils/resolution/vue.js";