fix(richtext)!: HTML and Markdown parsing for links and edge cases

nx.json

@@ -11,6 +11,9 @@
     "test": {
       "dependsOn": ["build"]
     },
+    "test:types": {
+      "dependsOn": ["build"]
+    },
     "lint": {
       "dependsOn": ["^build"],
       "cache": true

packages/astro/src/lib/richTextToHTML.ts

@@ -1,7 +1,8 @@
 import {
+  ComponentBlok,
   richTextResolver,
   type StoryblokRichTextNode,
-  type StoryblokRichTextResolvers,
+  type StoryblokRichTextOptions,
 } from '@storyblok/js';
 import { experimental_AstroContainer } from 'astro/container';
 import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro';
@@ -13,13 +14,13 @@ let container: null | experimental_AstroContainer = null;
  * @experimental Converts a Storyblok RichText field into an HTML string.
  *
  * This API is still under development and may change in future releases.
- * It also relies on Astro’s experimental
+ * It also relies on Astro's experimental
  * [experimental_AstroContainer](https://docs.astro.build/en/reference/container-reference/) feature.
  *
  * @async
  * @param {StoryblokRichTextNode} richTextField - The root RichText node to convert.
- * @param {StoryblokRichTextResolvers} [customResolvers] - Optional custom resolvers
- *   for customizing how specific nodes or marks are transformed into HTML.
+ * @param {StoryblokRichTextOptions['tiptapExtensions']} [tiptapExtensions] - Optional custom
+ *   tiptap extensions for customizing how specific nodes or marks are rendered.
  * @returns {Promise<string>} A promise that resolves to the HTML string representation
  *   of the provided RichText content.
  *
@@ -36,7 +37,7 @@ let container: null | experimental_AstroContainer = null;
  */
 export const richTextToHTML = async (
   richTextField: StoryblokRichTextNode,
-  customResolvers?: StoryblokRichTextResolvers,
+  tiptapExtensions?: StoryblokRichTextOptions['tiptapExtensions'],
 ): Promise<string> => {
   // Create Astro container only once
   if (!container) {
@@ -45,17 +46,11 @@ export const richTextToHTML = async (
 
   // Collect async render results keyed by placeholder ID
   const asyncReplacements: Promise<{ id: string; result: string }>[] = [];
-  // Build the resolvers object
-  const resolvers: StoryblokRichTextResolvers = {
-    // Handle async components
-    blok: (node) => {
-      const componentBody = node.attrs?.body;
-      if (!Array.isArray(componentBody)) {
-        return '';
-      }
 
-      return componentBody
-        .map((blok) => {
+  const resolver = richTextResolver<string>({
+    tiptapExtensions: {
+      blok: ComponentBlok.configure({
+        renderComponent: (blok: Record<string, unknown>, _id?: string) => {
           if (!blok || typeof blok !== 'object' || !container) {
             return '';
           }
@@ -77,15 +72,11 @@ export const richTextToHTML = async (
 
           asyncReplacements.push(promise);
           return placeholder;
-        })
-        .join('\n');
+        },
+      }),
+      ...tiptapExtensions,
     },
-
-    // Add custom resolvers if provided
-    ...customResolvers,
-  };
-
-  const resolver = richTextResolver({ resolvers });
+  });
 
   let html = resolver.render(richTextField);
   // Wait for all async renders

packages/astro/src/public.d.ts

@@ -20,19 +20,18 @@ declare module '@storyblok/astro/client' {
   import type {
     StoryblokClient,
     StoryblokRichTextNode,
-    StoryblokRichTextResolvers,
   } from '@storyblok/astro';
   /**
    * @experimental Converts a Storyblok RichText field into an HTML string.
    *
    * This API is still under development and may change in future releases.
-   * It also relies on Astro’s experimental
+   * It also relies on Astro's experimental
    * [experimental_AstroContainer](https://docs.astro.build/en/reference/container-reference/) feature.
    *
    * @async
    * @param {StoryblokRichTextNode} richTextField - The root RichText node to convert.
-   * @param {StoryblokRichTextResolvers} [customResolvers] - Optional custom resolvers
-   *   for customizing how specific nodes or marks are transformed into HTML.
+   * @param {Record<string, any>} [tiptapExtensions] - Optional custom tiptap extensions
+   *   for customizing how specific nodes or marks are rendered.
    * @returns {Promise<string>} A promise that resolves to the HTML string representation
    *   of the provided RichText content.
    *
@@ -49,7 +48,7 @@ declare module '@storyblok/astro/client' {
    */
   export function richTextToHTML(
     richTextField: StoryblokRichTextNode,
-    customResolvers?: StoryblokRichTextResolvers
+    tiptapExtensions?: Record<string, any>
   ): Promise<string>;
 
   /**

packages/astro/src/types.ts

@@ -30,9 +30,7 @@ export type {
   StoryblokRichTextDocumentNode,
   StoryblokRichTextImageOptimizationOptions,
   StoryblokRichTextNode,
-  StoryblokRichTextNodeResolver,
   StoryblokRichTextNodeTypes,
   StoryblokRichTextOptions,
-  StoryblokRichTextResolvers,
   TextTypes,
 } from '@storyblok/js';

packages/js/cypress/e2e/index.cy.ts

@@ -17,7 +17,7 @@ describe('@storyblok/js', () => {
       cy.get('@consoleError').should('not.be.called');
       cy.get('#rich-text-container').should(
         'have.html',
-        '<p></p><p>Hola<strong>in bold</strong></p><p><button href="hola@alvarosaburido.dev" target="null">hola@alvarosaburido.dev</button></p><span blok="[object Object]" id="undefined" style="display: none"></span><p></p><p>paragraph after empty line</p><p></p><ul><li><p>an item in a list</p></li><li><p>another item</p></li></ul><p></p><ol order="1"><li><p>item in another list</p></li><li><p>another item</p></li></ol><p></p><blockquote><p>this is a quote</p></blockquote><p></p><hr><p></p><p>some words after an &lt;hr&gt;</p><p></p><p><em>italic text</em></p><p></p><p><s>strikethrough</s></p><p></p><p><u>underlined</u></p><p></p><p><sup>superscript</sup></p><p></p><p><sub>subscript</sub></p><p></p><p><code>inline code</code> </p>',
+        '<p></p><p>Hola<strong>in bold</strong></p><p><button href="jane@example.com">jane@example.com</button></p><span data-blok="{&quot;component&quot;:&quot;custom_component&quot;,&quot;message&quot;:&quot;hey John&quot;}" style="display: none"></span><p></p><p>paragraph after empty line</p><p></p><ul><li><p>an item in a list</p></li><li><p>another item</p></li></ul><p></p><ol order="1"><li><p>item in another list</p></li><li><p>another item</p></li></ol><p></p><blockquote><p>this is a quote</p></blockquote><p></p><hr><p></p><p>some words after an &lt;hr&gt;</p><p></p><p><em>italic text</em></p><p></p><p><s>strikethrough</s></p><p></p><p><u>underlined</u></p><p></p><p><sup>superscript</sup></p><p></p><p><sub>subscript</sub></p><p></p><p><code>inline code</code> </p>',
       );
     });
   });

packages/js/playground/vanilla/main.ts

@@ -1,12 +1,11 @@
 /* eslint-disable no-console */
+import { Mark } from '@tiptap/core';
 import type {
-  StoryblokRichTextNode,
   StoryblokRichTextOptions,
 } from '@storyblok/js';
 import {
   apiPlugin,
   loadStoryblokBridge,
-  MarkTypes,
   renderRichText,
   storyblokInit,
   useStoryblokBridge,
@@ -52,12 +51,17 @@ window.loadStoryblokBridgeScript = () => {
   loadStoryblokBridge();
 };
 
+const CustomLink = Mark.create({
+  name: 'link',
+  renderHTML({ HTMLAttributes }: { HTMLAttributes: Record<string, string> }) {
+    return ['button', { href: HTMLAttributes.href, target: HTMLAttributes.target }, 0];
+  },
+});
+
 window.renderRichText = () => {
   const options: StoryblokRichTextOptions = {
-    resolvers: {
-      [MarkTypes.LINK]: (node: StoryblokRichTextNode<string>) => {
-        return `<button href="${node.attrs?.href}" target="${node.attrs?.target}">${node.attrs?.href}</button>`;
-      },
+    tiptapExtensions: {
+      link: CustomLink,
     },
   };
   const html = renderRichText(richTextFixture as any, options);

packages/js/src/fixtures/richTextObject.json

@@ -26,13 +26,13 @@
       "type": "paragraph",
       "content": [
         {
-          "text": "hola@alvarosaburido.dev",
+          "text": "jane@example.com",
           "type": "text",
           "marks": [
             {
               "type": "link",
               "attrs": {
-                "href": "hola@alvarosaburido.dev",
+                "href": "jane@example.com",
                 "uuid": null,
                 "anchor": null,
                 "target": null,

packages/js/src/index.test.ts

@@ -9,14 +9,14 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { loadBridge } from './bridge';
 
-const renderMock = vi.fn(() => '<p>Rendered HTML</p>');
-vi.mock('@storyblok/richtext', () => {
-  return {
-    richTextResolver: vi.fn(() => ({
-      render: renderMock,
-    })),
-  };
+const { renderMock, richTextResolverMock } = vi.hoisted(() => {
+  const renderMock = vi.fn(() => '<p>Rendered HTML</p>');
+  const richTextResolverMock = vi.fn(() => ({ render: renderMock }));
+  return { renderMock, richTextResolverMock };
 });
+vi.mock('@storyblok/richtext', () => ({
+  richTextResolver: richTextResolverMock,
+}));
 describe('@storyblok/js', () => {
   afterEach(() => {
     vi.restoreAllMocks();
@@ -299,29 +299,24 @@ describe('@storyblok/js', () => {
       vi.clearAllMocks();
     });
 
-    it('should call richTextResolver with correct options', () => {
+    it('should call render with the provided data', () => {
       const data = { type: 'doc', content: [] } as StoryblokRichTextNode<string>;
-      const options = {
-        resolvers: {
-          paragraph: () => '<p>test</p>',
-        },
-      };
 
-      renderRichText(data, options);
+      renderRichText(data);
 
+      expect(richTextResolverMock).toHaveBeenCalledWith(undefined);
       expect(renderMock).toHaveBeenCalledWith(data);
     });
 
-    it('calls render with the provided data', () => {
+    it('should forward tiptapExtensions to richTextResolver', () => {
       const data = { type: 'doc', content: [] } as StoryblokRichTextNode<string>;
       const options = {
-        resolvers: {
-          paragraph: () => '<p>test</p>',
-        },
+        tiptapExtensions: { link: { name: 'link' } },
       };
 
-      renderRichText(data, options);
+      renderRichText(data, options as any);
 
+      expect(richTextResolverMock).toHaveBeenCalledWith(options);
       expect(renderMock).toHaveBeenCalledWith(data);
     });
   });

packages/js/src/index.ts

@@ -123,16 +123,17 @@ export * from './types';
 
 // New Richtext Resolver
 export {
+  asTag,
   BlockTypes,
+  ComponentBlok,
+  LinkTypes,
   MarkTypes,
   richTextResolver,
   type StoryblokRichTextDocumentNode,
   type StoryblokRichTextImageOptimizationOptions,
   type StoryblokRichTextNode,
-  type StoryblokRichTextNodeResolver,
   type StoryblokRichTextNodeTypes,
   type StoryblokRichTextOptions,
-  type StoryblokRichTextResolvers,
   TextTypes,
 } from '@storyblok/richtext';
 

packages/nuxt/playground/app/pages/richtext.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { NuxtLink } from '#components';
-import { MarkTypes, type StoryblokRichTextNode } from '@storyblok/vue';
+import { Mark } from '@tiptap/core';
 
 const { story } = await useAsyncStoryblok('vue/test-richtext', {
   api: {
@@ -9,33 +9,25 @@ const { story } = await useAsyncStoryblok('vue/test-richtext', {
   bridge: {},
 });
 
-const resolvers = {
-  [MarkTypes.LINK]: (node: StoryblokRichTextNode<VNode>) => {
-    return node.attrs?.linktype === 'STORY'
-      ? h(
-          NuxtLink,
-          {
-            to: node.attrs?.href,
-            target: node.attrs?.target,
-          },
-          node.text,
-        )
-      : h(
-          'a',
-          {
-            href: node.attrs?.href,
-            target: node.attrs?.target,
-          },
-          node.text,
-        );
+const CustomLink = Mark.create({
+  name: 'link',
+  renderHTML({ HTMLAttributes }: { HTMLAttributes: Record<string, string> }) {
+    if (HTMLAttributes.linktype === 'story') {
+      return [asTag(NuxtLink), { to: HTMLAttributes.href }, 0];
+    }
+    return ['a', { href: HTMLAttributes.href, target: HTMLAttributes.target }, 0];
   },
+});
+
+const tiptapExtensions = {
+  link: CustomLink,
 };
 </script>
 
 <template>
   <StoryblokRichText
     v-if="story?.content.richText"
     :doc="story.content.richText"
-    :resolvers="resolvers"
+    :tiptap-extensions="tiptapExtensions"
   />
 </template>

packages/nuxt/playground/app/storyblok/EmojiRandomizer.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import type { SbBlokData } from '@storyblok/vue';
+
+interface EmojiRandomizerBlok extends SbBlokData {
+  label?: string;
+}
+
+interface Props {
+  blok: EmojiRandomizerBlok;
+}
+
+defineProps<Props>();
+
+// List of fun emojis to randomly choose from
+const emojis = ['😊', '🎉', '🚀', '✨', '🌈', '🎨', '🎸', '🎮', '🍕', '🌺'];
+
+// Reactive state to track current emoji
+const currentEmoji = ref<string>(
+  emojis[Math.floor(Math.random() * emojis.length)],
+);
+
+/**
+ * Generates a new random emoji different from the current one
+ */
+const randomizeEmoji = (): void => {
+  let newEmoji: string;
+  do {
+    newEmoji = emojis[Math.floor(Math.random() * emojis.length)];
+  } while (newEmoji === currentEmoji.value);
+
+  currentEmoji.value = newEmoji;
+};
+</script>
+
+<template>
+  <div
+    v-editable="blok"
+    class="flex flex-col items-center gap-6 p-4 bg-gray-100 dark:bg-gray-900 rounded-lg"
+    data-test="emoji-randomizer"
+  >
+    <!-- Large emoji display -->
+    <div class="text-6xl">
+      {{ currentEmoji }}
+    </div>
+
+    <!-- Randomize button -->
+    <button
+      class="px-6 py-3 rounded-lg bg-blue-500 hover:bg-blue-600 active:bg-blue-700 text-white font-small transition-colors duration-200 dark:bg-blue-600 dark:hover:bg-blue-700 dark:active:bg-blue-800"
+      @click="randomizeEmoji"
+    >
+      {{ blok.label || 'Randomize Emoji' }}
+    </button>
+  </div>
+</template>

packages/nuxt/src/module.ts

@@ -80,12 +80,12 @@ export default defineNuxtModule<AllModuleOptions>({
       'MarkTypes',
       'BlockTypes',
       'LinkTypes',
-      'AssetTypes',
-      'StoryblokRichTextResolvers',
+      'TextTypes',
+      'ComponentBlok',
+      'asTag',
       'StoryblokRichTextDocumentNode',
       'StoryblokRichTextImageOptimizationOptions',
       'StoryblokRichTextNode',
-      'StoryblokRichTextNodeResolver',
       'StoryblokRichTextNodeTypes',
       'StoryblokRichTextOptions',
     ];