@bettercms-ai/richtext 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.6.0",
+  "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";
@@ -332,7 +340,7 @@ const buildComponents = (
      * renders the LABEL rather than deleting it — a blocked link must not lose the words.
      */
     [PT_TYPES.link]: ({ value, children }) => {
-      const v = (value ?? {}) as { href?: unknown; target?: unknown; rel?: unknown };
+      const v = (value ?? {}) as { href?: unknown; target?: unknown; rel?: unknown; className?: unknown };
       const href = typeof v.href === "string" ? safeHref(v.href) : null;
       if (!href) return children;
       // `rel` is author data too (the importer keeps `prev`/`next` on pagination links), so only
@@ -346,7 +354,9 @@ const buildComponents = (
         rel.add("noreferrer");
       }
       const relAttr = rel.size ? ` rel="${esc([...rel].join(" "))}"` : "";
-      return `<a${cls(classes, "a")} href="${esc(href)}"${target}${relAttr}>${children}</a>`;
+      // The link's own class (kept on ingest) wins over the caller's default: it IS the site.
+      const own = typeof v.className === "string" && v.className ? ` class="${esc(v.className)}"` : "";
+      return `<a${own || cls(classes, "a")} href="${esc(href)}"${target}${relAttr}>${children}</a>`;
     },
     /**
      * The site's own inline markup, written back out as itself.
@@ -390,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/ingest.ts

@@ -9,7 +9,7 @@ import {
 } from "./types";
 import { randomKey, isValidKey, type KeyGenerator } from "./key";
 import { safeHref } from "./href";
-import { isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
+import { BARE_IS_DESIGN, isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
 import type { PtSchema } from "./schema";
 
 /**
@@ -197,11 +197,12 @@ function tableRule(key: KeyGenerator, ingestCell: (html: string) => PortableText
  * for exactly that reason.
  *
  * A `<span>` with nothing on it is NOT annotated: it carries no design, so recording it would
- * mint a markDef per stray wrapper and bloat every value for nothing. The other tags are
- * annotated bare, because there the TAG is the design (`<small>`, `<sup>`, `<kbd>`).
+ * mint a markDef per stray wrapper and bloat every value for nothing. `<small>`, `<sup>`,
+ * `<kbd>` … are annotated bare, because there the TAG is the design.
  *
- * Decorator tags (`b/strong`, `i/em`, `u`, `s`, `mark`, `code`) are deliberately absent: they
- * have real decorators and the standard rules run right after this one.
+ * Decorator tags (`b/strong`, `i/em`, `u`, `s`, `mark`, `code`, …) take this rule ONLY when
+ * they carry a class or an admitted attribute — the one thing their decorator cannot hold.
+ * Bare, they fall through to the standard rules and become the decorator as before.
  *
  * `__annotation` is the deserialiser's own internal placeholder — the same one its built-in
  * link rule returns — so nesting composes for free: `<strong><span class>` comes back as one
@@ -215,7 +216,7 @@ function styledRule(key: KeyGenerator): DeserializerRule {
       if (!isStyledTag(tag)) return undefined;
       const className = el.getAttribute("class")?.trim() || undefined;
       const attrs = styledAttrsOf(el);
-      if (tag === "span" && !className && !attrs) return undefined;
+      if (!className && !attrs && !BARE_IS_DESIGN.has(tag)) return undefined;
       const markDef: StyledMarkDef = {
         _type: PT_TYPES.styled,
         _key: key(),
@@ -228,6 +229,38 @@ function styledRule(key: KeyGenerator): DeserializerRule {
   };
 }
 
+/**
+ * `<a class>` → a `link` annotation that keeps the site's class as `className`.
+ *
+ * The built-in link rule records `href` and nothing else, so a styled link (`<a class="underline
+ * text-brand">`) came back bare and the design died on ingest. Only a link WITH a class takes
+ * this rule; a plain link still goes to the built-in one. `href` is checked by `normalise`.
+ */
+function classedLinkRule(key: KeyGenerator): DeserializerRule {
+  return {
+    deserialize(el: Node, next) {
+      if (!isElement(el) || el.nodeName.toLowerCase() !== "a") return undefined;
+      const className = el.getAttribute("class")?.trim();
+      const href = el.getAttribute("href")?.trim();
+      if (!className || !href) return undefined;
+      const rel = el.getAttribute("rel")?.trim();
+      const markDef = {
+        _type: PT_TYPES.link,
+        _key: key(),
+        href,
+        className,
+        ...(el.getAttribute("target") === "_blank" ? { target: "_blank" } : {}),
+        ...(rel ? { rel } : {}),
+      };
+      return { _type: "__annotation", markDef, children: next(el.childNodes) } as never;
+    },
+  };
+}
+
+/** Does this field's schema carry the link annotation? */
+const allowsLinks = (schema: PtSchema | undefined): boolean =>
+  !schema || schema.annotations.some((a) => a.name === PT_TYPES.link);
+
 /**
  * ── MEDIA, WHICH USED TO PRODUCE NO NODE AT ALL ──────────────────────────────────────────
  *
@@ -383,6 +416,7 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
       ...(allowsTables(opts.schema) ? [tableRule(key, (cell) => htmlToPortableText(cell, opts))] : []),
       mediaRule(key, opts.schema),
       ...(allowsStyled(opts.schema) ? [styledRule(key)] : []),
+      ...(allowsLinks(opts.schema) ? [classedLinkRule(key)] : []),
     ],
     keyGenerator: key,
   });

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/schema.ts

@@ -111,6 +111,8 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
       fields: [
         { name: "href", type: "string" },
         { name: "target", type: "string" },
+        // The site's own class on the `<a>`, kept so a styled link round-trips.
+        { name: "className", type: "string" },
       ],
     });
   }

package/src/styled.ts

@@ -22,8 +22,22 @@
  * NOT passed through — its value is a language of its own, bounded by `safeStyle` below.
  */
 
-/** Inline tags a `styled` annotation may wear. Nothing outside this list is ever rendered. */
-export const STYLED_TAGS = ["span", "small", "sup", "sub", "kbd", "abbr", "time"] as const;
+/**
+ * Inline tags a `styled` annotation may wear. Nothing outside this list is ever rendered.
+ *
+ * The decorator tags (`strong` … `code`) are here for the one case their decorator cannot
+ * hold: the site put a CLASS on them (`<strong class="text-yellow-500">`). A decorator is a
+ * bit with nowhere to keep a class, so without this the design died on ingest — which is what
+ * made agents rewrite a site's markup to dodge the loss. A bare `<strong>` still becomes the
+ * decorator (see `BARE_IS_DESIGN`).
+ */
+export const STYLED_TAGS = [
+  "span", "small", "sup", "sub", "kbd", "abbr", "time",
+  "strong", "b", "em", "i", "u", "s", "mark", "code", "q", "cite", "dfn", "var", "samp", "ins", "del",
+] as const;
+
+/** Tags whose bare form IS the design, so they are annotated even with no class. */
+export const BARE_IS_DESIGN: ReadonlySet<string> = new Set(["small", "sup", "sub", "kbd", "abbr", "time"]);
 
 export type StyledTag = (typeof STYLED_TAGS)[number];
 

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.
  *