@bettercms-ai/richtext 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "sideEffects": false,
   "description": "The one Portable Text contract for BetterCMS: schema, converters, and rendering. Shared by the backend, the dashboard and every delivery SDK.",

package/src/html.ts

@@ -235,6 +235,11 @@ export interface RenderOptions {
    * sits on each `<li>`, because a wrapper per item would split the list into one-item lists.
    */
   bindingBase?: string;
+  /**
+   * Renders an embedded block this serialiser cannot resolve itself (a component, say). A
+   * string replaces the marker; `undefined` keeps it.
+   */
+  renderBlock?: (value: Record<string, unknown>) => string | undefined;
 }
 
 /**
@@ -269,6 +274,7 @@ const bindingAttrs = (base: string, key: unknown): string =>
 const buildComponents = (
   classes: HtmlClasses = {},
   binding?: { base: string; keys: ReadonlySet<unknown> },
+  renderBlock?: RenderOptions["renderBlock"],
 ): Partial<PortableTextHtmlComponents> => ({
   block: tagOverrides(classes, STYLE_TAGS),
   list: tagOverrides(classes, { bullet: "ul", number: "ol", check: "ul" }),
@@ -315,6 +321,8 @@ const buildComponents = (
        */
       const legacy = builtInTableToTable(value);
       if (legacy) return tableHtml(legacy);
+      const rendered = renderBlock?.(value as Record<string, unknown>);
+      if (rendered !== undefined) return rendered;
       const key = typeof v.schemaKey === "string" && TOKEN.test(v.schemaKey.replace(/^builtin:/, ""))
         ? v.schemaKey
         : "block";
@@ -392,11 +400,12 @@ export function portableTextToHtml(
   opts: RenderOptions = {},
 ): string {
   if (!Array.isArray(value) || value.length === 0) return "";
-  const components = opts.classes ? buildComponents(opts.classes) : defaultComponents;
+  const components =
+    opts.classes || opts.renderBlock ? buildComponents(opts.classes, undefined, opts.renderBlock) : defaultComponents;
 
   if (opts.bindingBase) {
     const base = opts.bindingBase;
-    const bound = buildComponents(opts.classes, { base, keys: new Set(value.map((n) => n._key)) });
+    const bound = buildComponents(opts.classes, { base, keys: new Set(value.map((n) => n._key)) }, opts.renderBlock);
     const out: string[] = [];
     for (let i = 0; i < value.length; ) {
       const node = value[i];

package/src/read.ts

@@ -1,4 +1,4 @@
-import { PORTABLE_TEXT_FORMAT, PT_TYPES, type PortableText } from "./types";
+import { EMBEDDED_COMPONENT_KEY, PORTABLE_TEXT_FORMAT, PT_TYPES, type PortableText } from "./types";
 import { lexicalToPortableText } from "./from-lexical";
 import { migrateTable } from "./table";
 import { randomKey, type KeyGenerator } from "./key";
@@ -231,3 +231,26 @@ export function readStructuredContent(props: unknown): PortableText | null {
       : null;
   return arr && arr.length > 0 ? (arr as PortableText) : null;
 }
+
+/** The `component` block an embed in rich text stands for. */
+export interface EmbeddedComponentBlock {
+  type: "component";
+  /** The node's `_key` — unique within its rich-text field only. */
+  id: string;
+  props: { componentId: string; overrides: Record<string, unknown> };
+}
+
+/**
+ * A component embedded in rich text, as the ordinary `component` block every renderer already
+ * draws — so an embed gets the same resolver, cycle guard and identity attributes as a placed
+ * instance. Null for any other node.
+ */
+export function embeddedComponentBlock(value: unknown): EmbeddedComponentBlock | null {
+  if (!isRecord(value) || value.schemaKey !== EMBEDDED_COMPONENT_KEY || !isRecord(value.fields)) return null;
+  const { componentId, overrides } = value.fields;
+  return {
+    type: "component",
+    id: typeof value._key === "string" ? value._key : "",
+    props: { componentId: String(componentId ?? ""), overrides: isRecord(overrides) ? overrides : {} },
+  };
+}

package/src/types.ts

@@ -276,6 +276,12 @@ export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
 export const BUILTIN_IMAGE_KEY = "builtin:image" as const;
 export const BUILTIN_EMBED_KEY = "builtin:video" as const;
 
+/**
+ * The `schemaKey` of a component embedded in rich text. A wire value shared with the dashboard
+ * (`COMPONENT_SCHEMA_KEY`) and the backend (`RICHTEXT_COMPONENT_KEY`).
+ */
+export const EMBEDDED_COMPONENT_KEY = "component" as const;
+
 /**
  * Top-level nodes whose `_type` this platform cannot store or render, in document order.
  *