@bettercms-ai/richtext 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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

@@ -230,6 +230,9 @@ export interface RenderOptions {
    * Wrapping at the top level rather than inside the block components is deliberate: a block
    * component only ever sees TEXT blocks, so a divider or an embedded image would get no
    * address — and those are exactly the nodes an editor most wants to click.
+   *
+   * List items are the one exception: a run of them renders as ONE `<ul>`/`<ol>` and the address
+   * sits on each `<li>`, because a wrapper per item would split the list into one-item lists.
    */
   bindingBase?: string;
 }
@@ -253,10 +256,27 @@ const tagOverrides = <T extends string>(
   return out;
 };
 
-const buildComponents = (classes: HtmlClasses = {}): Partial<PortableTextHtmlComponents> => ({
+/** The per-node address `portableTextToHtml({ bindingBase })` stamps. "" for a node with no key. */
+const bindingAttrs = (base: string, key: unknown): string =>
+  typeof key === "string" && key
+    ? ` data-bcms-field="${esc(base)}#${esc(key)}" data-bcms-kind="richtext"`
+    : "";
+
+/**
+ * `keys` is the set of `_key`s the value actually carries: to-html invents one (`li-0-1`) for an
+ * item that has none, and an invented key is an address that resolves to nothing.
+ */
+const buildComponents = (
+  classes: HtmlClasses = {},
+  binding?: { base: string; keys: ReadonlySet<unknown> },
+): Partial<PortableTextHtmlComponents> => ({
   block: tagOverrides(classes, STYLE_TAGS),
   list: tagOverrides(classes, { bullet: "ul", number: "ol", check: "ul" }),
-  listItem: tagOverrides(classes, { bullet: "li", number: "li", check: "li" }),
+  // With a base, every item carries its own address ON the `<li>` — see `bindingBase`.
+  listItem: binding
+    ? ({ value, children }: { value: { _key?: unknown }; children?: string }) =>
+        `<li${cls(classes, "li")}${binding.keys.has(value._key) ? bindingAttrs(binding.base, value._key) : ""}>${children ?? ""}</li>`
+    : tagOverrides(classes, { bullet: "li", number: "li", check: "li" }),
   types: {
     [PT_TYPES.divider]: () => "<hr>",
     [PT_TYPES.table]: ({ value }) => tableHtml(value as PortableTextTable),
@@ -312,7 +332,7 @@ const buildComponents = (classes: HtmlClasses = {}): Partial<PortableTextHtmlCom
      * 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
@@ -326,7 +346,9 @@ const buildComponents = (classes: HtmlClasses = {}): Partial<PortableTextHtmlCom
         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.
@@ -362,6 +384,9 @@ const buildComponents = (classes: HtmlClasses = {}): Partial<PortableTextHtmlCom
 /** The undressed components, built once: the overwhelming majority of calls pass no classes. */
 const defaultComponents = buildComponents();
 
+const isListItem = (node: unknown): boolean =>
+  isRecord(node) && node._type === "block" && typeof node.listItem === "string" && !!node.listItem;
+
 export function portableTextToHtml(
   value: PortableText | null | undefined,
   opts: RenderOptions = {},
@@ -370,16 +395,28 @@ export function portableTextToHtml(
   const components = opts.classes ? buildComponents(opts.classes) : defaultComponents;
 
   if (opts.bindingBase) {
-    const base = esc(opts.bindingBase);
-    return value
-      .map((node) => {
-        const inner = toHTML([node] as never, { components });
-        // A node with no key cannot be addressed. Render it rather than dropping it — an
-        // unaddressable paragraph is a small loss, a missing one is content disappearing.
-        if (!node._key) return inner;
-        return `<div data-bcms-field="${base}#${esc(node._key)}" data-bcms-kind="richtext">${inner}</div>`;
-      })
-      .join("");
+    const base = opts.bindingBase;
+    const bound = buildComponents(opts.classes, { base, keys: new Set(value.map((n) => n._key)) });
+    const out: string[] = [];
+    for (let i = 0; i < value.length; ) {
+      const node = value[i];
+      // A RUN of list items renders as ONE list, each `<li>` carrying its own address. Wrapping
+      // items one by one gave every item its own `<ol>`, so numbering restarted at 1 on every line
+      // and bullets sat a list-margin apart — the canvas no longer looked like the site.
+      if (isListItem(node)) {
+        let end = i + 1;
+        while (end < value.length && isListItem(value[end])) end++;
+        out.push(toHTML(value.slice(i, end) as never, { components: bound }));
+        i = end;
+        continue;
+      }
+      const inner = toHTML([node] as never, { components });
+      // A node with no key cannot be addressed. Render it rather than dropping it — an
+      // unaddressable paragraph is a small loss, a missing one is content disappearing.
+      out.push(node._key ? `<div${bindingAttrs(base, node._key)}>${inner}</div>` : inner);
+      i++;
+    }
+    return out.join("");
   }
 
   const html = toHTML(value as never, { components });

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/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];