@storyblok/astro 9.0.0 → 9.0.1

package/dist/lib/client.d.ts

@@ -1 +1,2 @@
+export { richTextToHTML } from './richTextToHTML';
 export { storyblokApiInstance as storyblokApi } from 'virtual:storyblok-init';

package/dist/lib/client.ts

@@ -1 +1,4 @@
+import '../public.d.ts';
+
+export { richTextToHTML } from './richTextToHTML';
 export { storyblokApiInstance as storyblokApi } from 'virtual:storyblok-init';

package/dist/lib/richTextToHTML.ts

@@ -0,0 +1,94 @@
+import {
+  ComponentBlok,
+  richTextResolver,
+  type StoryblokRichTextNode,
+  type StoryblokRichTextOptions,
+} from '@storyblok/js';
+import { experimental_AstroContainer } from 'astro/container';
+import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro';
+
+// Lazily initialized Astro container (for rendering blok components)
+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
+ * [experimental_AstroContainer](https://docs.astro.build/en/reference/container-reference/) feature.
+ *
+ * @async
+ * @param {StoryblokRichTextNode} richTextField - The root RichText node to convert.
+ * @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.
+ *
+ * @example
+ * ```astro
+ * ---
+ * import { richTextToHTML } from '@storyblok/astro/client';
+ * const { blok } = Astro.props;
+ * const renderedRichText = await richTextToHTML(blok.text);
+ * ---
+ *
+ * <div set:html={renderedRichText} />
+ * ```
+ */
+export const richTextToHTML = async (
+  richTextField: StoryblokRichTextNode,
+  tiptapExtensions?: StoryblokRichTextOptions['tiptapExtensions'],
+): Promise<string> => {
+  // Create Astro container only once
+  if (!container) {
+    container = await experimental_AstroContainer.create();
+  }
+
+  // Collect async render results keyed by placeholder ID
+  const asyncReplacements: Promise<{ id: string; result: string }>[] = [];
+
+  const resolver = richTextResolver<string>({
+    tiptapExtensions: {
+      blok: ComponentBlok.configure({
+        renderComponent: (blok: Record<string, unknown>, _id?: string) => {
+          if (!blok || typeof blok !== 'object' || !container) {
+            return '';
+          }
+
+          // Generate unique placeholder ID
+          const id = crypto.randomUUID();
+          const placeholder = `<!--ASYNC-${id}-->`;
+
+          // Queue async render
+          const promise = container
+            .renderToString(StoryblokComponent, {
+              props: { blok },
+            })
+            .then(result => ({ id, result }))
+            .catch((err) => {
+              console.error('Component rendering failed:', err);
+              return { id, result: '<!-- Component render error -->' };
+            });
+
+          asyncReplacements.push(promise);
+          return placeholder;
+        },
+      }),
+      ...tiptapExtensions,
+    },
+  });
+
+  let html = resolver.render(richTextField);
+  // Wait for all async renders
+  const results = await Promise.all(asyncReplacements);
+  const replacements = new Map(
+    results.map(({ id, result }) => [id, result ?? '']),
+  );
+
+  // Single-pass replacement using regex
+  html = html.replace(/<!--ASYNC-([\w-]+)-->/g, (_, id: string) => {
+    return replacements.get(id) ?? '';
+  });
+
+  return html;
+};

package/dist/public.d.ts

@@ -3,6 +3,12 @@
  * Provides IntelliSense, JSDoc, and type safety for SDK consumers.
  */
 
+declare module 'virtual:storyblok-init' {
+  import type { StoryblokClient } from '@storyblok/astro';
+
+  export const storyblokApiInstance: StoryblokClient;
+}
+
 declare module '@storyblok/astro/StoryblokComponent.astro' {
   import type { SbBlokData } from '@storyblok/astro';
 
@@ -28,7 +34,7 @@ declare module '@storyblok/astro/client' {
   import type {
     StoryblokClient,
     StoryblokRichTextNode,
-    StoryblokRichTextResolvers,
+    StoryblokRichTextOptions,
   } from '@storyblok/astro';
   /**
    * @experimental Converts a Storyblok RichText field into an HTML string.
@@ -39,7 +45,7 @@ declare module '@storyblok/astro/client' {
    *
    * @async
    * @param {StoryblokRichTextNode} richTextField - The root RichText node to convert.
-   * @param {StoryblokRichTextResolvers} [customResolvers] - Optional custom resolvers
+   * @param {StoryblokRichTextOptions['tiptapExtensions']} [tiptapExtensions] - Optional custom resolvers
    *   for customizing how specific nodes or marks are transformed into HTML.
    * @returns {Promise<string>} A promise that resolves to the HTML string representation
    *   of the provided RichText content.
@@ -57,7 +63,7 @@ declare module '@storyblok/astro/client' {
    */
   export function richTextToHTML(
     richTextField: StoryblokRichTextNode,
-    customResolvers?: StoryblokRichTextResolvers
+    tiptapExtensions?: StoryblokRichTextOptions['tiptapExtensions'],
   ): Promise<string>;
 
   /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/astro",
   "type": "module",
-  "version": "9.0.0",
+  "version": "9.0.1",
   "private": false,
   "description": "Official Astro integration for the Storyblok Headless CMS",
   "author": "Storyblok",