@bettercms-ai/richtext 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.16.0",
+  "version": "0.17.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/href.ts

@@ -25,3 +25,42 @@ export function safeHref(raw: string): string | null {
     return null;
   }
 }
+
+/**
+ * A MEDIA url: `safeHref`, plus a plain relative path.
+ *
+ * An imported page is full of `images/hero.png` and `../media/clip.mp4`, and `safeHref` refuses
+ * a path with no leading slash — so every one of those images would render as nothing. Widened
+ * only for `<img>`, `<video>` and a poster: they load a picture, while an `<iframe>` frames a
+ * whole page and keeps the strict check. A colon or whitespace is refused, so no scheme
+ * (`javascript:`) can ride this path, and a PROTOCOL-RELATIVE `//host/clip.mp4` is refused with
+ * it — it is off-origin, not relative, and `safeHref` rejects the same shape for the same reason.
+ */
+export const safeMediaSrc = (raw: string): string | null =>
+  safeHref(raw) ?? (raw !== "" && !raw.startsWith("//") && !/[:\s]/.test(raw) ? raw : null);
+
+/** What a new tab always carries on render, so it is never the author's own `rel`. */
+const NEW_TAB_REL = ["noopener", "noreferrer"];
+
+/**
+ * A link's `rel` is author data (V2's link form writes `nofollow`, `sponsored`, `ugc`; the
+ * importer keeps `prev`/`next`): plain link-type tokens only, lowercased, once each. V2's
+ * `follow` is its "no rel" and is no token.
+ */
+const relTokens = (raw: unknown): string[] =>
+  typeof raw === "string"
+    ? [...new Set(raw.toLowerCase().split(/\s+/).filter((t) => /^[a-z][a-z-]*$/.test(t) && t !== "follow"))]
+    : [];
+
+/** The `rel` to store from a link's markup: a new tab's noopener/noreferrer are the renderer's, not kept. */
+export function readLinkRel(raw: unknown, blank: boolean): string | undefined {
+  const tokens = relTokens(raw).filter((t) => !blank || !NEW_TAB_REL.includes(t));
+  return tokens.length ? tokens.join(" ") : undefined;
+}
+
+/** The `rel` both renderers write: the stored tokens, and a new tab always adds noopener + noreferrer. */
+export function writeLinkRel(raw: unknown, blank: boolean): string | undefined {
+  const tokens = new Set(relTokens(raw));
+  if (blank) for (const t of NEW_TAB_REL) tokens.add(t);
+  return tokens.size ? [...tokens].join(" ") : undefined;
+}

package/src/html.ts

@@ -3,6 +3,7 @@ import {
   BUILTIN_CALLOUT_KEY,
   BUILTIN_EMBED_KEY,
   BUILTIN_IMAGE_KEY,
+  BUILTIN_TABLE_KEY,
   BUILTIN_TOGGLE_KEY,
   PT_TYPES,
   pullQuoteHref,
@@ -12,7 +13,7 @@ import {
 import { resolveVideoSource } from "./video";
 import { builtInTableToTable, designOf, footnoteNumbers, footnotesOf, highlightedColumns, isTypedTable, jsonLdOf, sortableColumns, tableColumns, tableGroupLayout, tableSections, typedCellView } from "./table";
 import { portableTextToPlainText } from "./plain";
-import { safeHref } from "./href";
+import { safeHref, safeMediaSrc, writeLinkRel } from "./href";
 import { isStyledTag, styledAttrEntries } from "./styled";
 import { richTextImageFrame, richTextImageLayout } from "./image-layout";
 import { keyTakeawaysView } from "./key-takeaways";
@@ -253,19 +254,8 @@ const STYLE_TAGS: Record<string, ClassTag> = {
 
 const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
 
-/**
- * A MEDIA url: `safeHref`, plus a plain relative path.
- *
- * An imported page is full of `images/hero.png` and `../media/clip.mp4`, and `safeHref` refuses
- * a path with no leading slash — so every one of those images would render as nothing, which is
- * the loss this whole pass exists to stop. Widened only for `<img>`, `<video>` and a poster:
- * they load a picture, while an `<iframe>` frames a whole page and keeps the strict check.
- * A colon or whitespace is refused, so no scheme (`javascript:`) can ride this path, and a
- * PROTOCOL-RELATIVE `//host/clip.mp4` is refused with it — it is off-origin, not relative, and
- * `safeHref` rejects the same shape for the same reason (href.ts:20).
- */
-const mediaSrc = (raw: string): string | null =>
-  safeHref(raw) ?? (raw !== "" && !raw.startsWith("//") && !/[:\s]/.test(raw) ? raw : null);
+/** A media url (`<img>`, `<video>`, a poster): href.ts `safeMediaSrc`, shared with ui's renderer. */
+const mediaSrc = safeMediaSrc;
 
 const fieldsOf = (value: unknown): Record<string, unknown> => {
   const f = isRecord(value) ? value.fields : undefined;
@@ -664,6 +654,35 @@ const checkItemHtml = (classes: HtmlClasses, value: { checked?: unknown }, child
   return `<li${cls(classes, "li")}${address} data-checked="${checked}"><input disabled type="checkbox"${checked ? " checked" : ""}>${children ?? ""}</li>`;
 };
 
+/**
+ * The built-in blocks drawn from their OWN fields, by `schemaKey`: null falls through to the
+ * caller's `renderBlock`, then the marker. A map, so ui's twin can be checked key for key
+ * (portable-text-coverage.test.tsx): a built-in drawn here and not there is content one site loses.
+ *
+ * 🔴 AN IMAGE AND AN EMBED ARE READABLE, and rendering them as markers was silent loss: an
+ * imported article's illustrations and its YouTube embed disappeared from every delivered
+ * rendition while the stored value still held them. Their payload is a URL — there is nothing to
+ * resolve. A legacy columns block reads as columns only in the shape it was written in.
+ *
+ * A pre-P1c TABLE resolves against nothing either: its rows are text, held right here, so a marker
+ * would DELETE visible content. Migrating it rather than rendering the matrix directly is what
+ * keeps ONE table renderer: a value that came through the reader and one that did not produce the
+ * same page, which is the property four surfaces used to get wrong independently.
+ */
+const SELF_RENDERED_BUILTINS = {
+  [BUILTIN_IMAGE_KEY]: (value: unknown, classes: HtmlClasses) => imageHtml(value, classes),
+  [BUILTIN_EMBED_KEY]: (value: unknown, classes: HtmlClasses) => embedHtml(value, classes),
+  [BUILTIN_CALLOUT_KEY]: (value: unknown) => calloutHtml(value),
+  [BUILTIN_TOGGLE_KEY]: (value: unknown) => toggleHtml(value),
+  [BUILTIN_COLUMNS_KEY]: (value: unknown, _classes: HtmlClasses, components: Parameters<typeof columnsHtml>[1]) =>
+    columnsView(value) ? columnsHtml(value, components) : null,
+  [BUILTIN_TABLE_KEY]: (value: unknown) => {
+    const legacy = builtInTableToTable(value);
+    return legacy ? tableHtml(legacy) : null;
+  },
+} satisfies Record<string, (value: unknown, classes: HtmlClasses, components: Parameters<typeof columnsHtml>[1]) => string | null>;
+type SelfRenderedBuiltin = keyof typeof SELF_RENDERED_BUILTINS;
+
 /**
  * `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.
@@ -725,24 +744,10 @@ const buildComponents = (
      */
     [PT_TYPES.block]: ({ value }) => {
       const v = value as { schemaKey?: unknown };
-      if (v.schemaKey === BUILTIN_IMAGE_KEY) return imageHtml(value, classes);
-      if (v.schemaKey === BUILTIN_EMBED_KEY) return embedHtml(value, classes);
-      if (v.schemaKey === BUILTIN_CALLOUT_KEY) return calloutHtml(value);
-      if (v.schemaKey === BUILTIN_TOGGLE_KEY) return toggleHtml(value);
-      // A legacy columns block in the shape it was written in reads as columns; any other stays a marker.
-      if (v.schemaKey === BUILTIN_COLUMNS_KEY && columnsView(value)) return columnsHtml(value, () => buildComponents(classes, undefined, renderBlock, embeds, resolved));
-      /**
-       * A pre-P1c TABLE is the exception to the marker, and it has to be: it resolves against
-       * nothing. Its rows are text, held right here, so a marker would DELETE visible content.
-       * Every other built-in block (an image, a video, a component) carries a reference this
-       * serialiser cannot resolve, so those stay markers.
-       *
-       * Migrating it here rather than rendering the matrix directly is what keeps ONE table
-       * renderer: a value that came through the reader and one that did not produce the same
-       * page, which is the property four surfaces used to get wrong independently.
-       */
-      const legacy = builtInTableToTable(value);
-      if (legacy) return tableHtml(legacy);
+      const own = typeof v.schemaKey === "string" && Object.hasOwn(SELF_RENDERED_BUILTINS, v.schemaKey)
+        ? SELF_RENDERED_BUILTINS[v.schemaKey as SelfRenderedBuiltin](value, classes, () => buildComponents(classes, undefined, renderBlock, embeds, resolved))
+        : null;
+      if (own !== null) return own;
       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:/, ""))
@@ -768,17 +773,10 @@ const buildComponents = (
       if (!href) return children;
       // RT2: a button is a link the author marked as one; V2's `data-button` is the site's style hook.
       const button = v.button === true ? ' data-button="true"' : "";
-      // `rel` is author data too (the importer keeps `prev`/`next` on pagination links), so only
-      // plain link-type tokens pass; a new tab always adds noopener + noreferrer.
-      const rel = new Set(
-        typeof v.rel === "string" ? v.rel.toLowerCase().split(/\s+/).filter((t) => /^[a-z][a-z-]*$/.test(t)) : [],
-      );
+      // `rel` is author data too: only plain link-type tokens pass; a new tab always adds noopener + noreferrer.
       const target = v.target === "_blank" ? ' target="_blank"' : "";
-      if (target) {
-        rel.add("noopener");
-        rel.add("noreferrer");
-      }
-      const relAttr = rel.size ? ` rel="${esc([...rel].join(" "))}"` : "";
+      const rel = writeLinkRel(v.rel, !!target);
+      const relAttr = rel ? ` rel="${esc(rel)}"` : "";
       // 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")}${button} href="${esc(href)}"${target}${relAttr}>${children}</a>`;
@@ -817,6 +815,16 @@ const buildComponents = (
 /** The undressed components, built once: the overwhelming majority of calls pass no classes. */
 const defaultComponents = buildComponents();
 
+/**
+ * What this serialiser draws: its node types, its marks, and the built-in blocks it draws from
+ * their own fields. ui's React renderer must draw every one of them (portable-text-coverage.test.tsx).
+ */
+export const HTML_RENDERS = {
+  types: Object.keys(defaultComponents.types ?? {}),
+  marks: Object.keys(defaultComponents.marks ?? {}),
+  builtins: Object.keys(SELF_RENDERED_BUILTINS),
+} as const;
+
 const isListItem = (node: unknown): boolean =>
   isRecord(node) && node._type === "block" && typeof node.listItem === "string" && !!node.listItem;
 

package/src/ingest.ts

@@ -14,7 +14,7 @@ import {
   type PortableTextTableRow,
 } from "./types";
 import { randomKey, isValidKey, type KeyGenerator } from "./key";
-import { safeHref } from "./href";
+import { readLinkRel, safeHref } from "./href";
 import { BARE_IS_DESIGN, isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
 import { EMBED_TITLE_MAX, isEmbedAspect, nearestEmbedAspect, resolveEmbed } from "./embed";
 import { cellTypeOf, columnOf, designOf, isColumnType, isValueType, jsonLdOf, PT_TABLE_LIMITS, typedCellText } from "./table";
@@ -755,45 +755,39 @@ function buttonLinkRule(key: KeyGenerator, schema: PtSchema | undefined): Deseri
       const flag = el.getAttribute("data-button");
       const href = el.getAttribute("href")?.trim();
       if (flag === null || flag === "false" || !href) return undefined;
-      const className = el.getAttribute("class")?.trim();
-      const rel = el.getAttribute("rel")?.trim();
-      const markDef = {
-        _type: PT_TYPES.link,
-        _key: key(),
-        href,
-        button: true,
-        ...(className ? { className } : {}),
-        ...(el.getAttribute("target") === "_blank" ? { target: "_blank" } : {}),
-        ...(rel ? { rel } : {}),
-      };
+      const markDef = { _type: PT_TYPES.link, _key: key(), href, button: true, ...linkExtras(el) };
       return { _type: "__annotation", markDef, children: next(el.childNodes) } as never;
     },
   };
 }
 
 /**
- * `<a class>` → a `link` annotation that keeps the site's class as `className`.
+ * What an `<a>` stores beyond its href: the site's class, a new tab (only `_blank`) and its
+ * `rel` (author tokens; the noopener/noreferrer a new tab adds on render are not kept).
+ */
+function linkExtras(el: Element): { className?: string; target?: "_blank"; rel?: string } {
+  const className = el.getAttribute("class")?.trim();
+  const blank = el.getAttribute("target")?.trim().toLowerCase() === "_blank";
+  const rel = readLinkRel(el.getAttribute("rel"), blank);
+  return { ...(className ? { className } : {}), ...(blank ? { target: "_blank" } : {}), ...(rel ? { rel } : {}) };
+}
+
+/**
+ * `<a class>`, `<a target="_blank">`, `<a rel>` → a `link` annotation that keeps them.
  *
  * 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`.
+ * text-brand">`) came back bare and the design died on ingest, and a link's new tab and its
+ * `nofollow` (V2's link form writes both) were lost the same way. Only a link carrying one of
+ * them takes this rule; a bare link still goes to the built-in one. `href` is checked by `normalise`.
  */
-function classedLinkRule(key: KeyGenerator): DeserializerRule {
+function linkRule(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 } : {}),
-      };
+      const extras = linkExtras(el);
+      if (!href || !Object.keys(extras).length) return undefined;
+      const markDef = { _type: PT_TYPES.link, _key: key(), href, ...extras };
       return { _type: "__annotation", markDef, children: next(el.childNodes) } as never;
     },
   };
@@ -1253,7 +1247,7 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
       ownDecoratorRule(opts.schema),
       ...(allowsStyled(opts.schema) ? [styledRule(key)] : []),
       buttonLinkRule(key, opts.schema),
-      ...(allowsLinks(opts.schema) ? [classedLinkRule(key)] : []),
+      ...(allowsLinks(opts.schema) ? [linkRule(key)] : []),
     ],
     keyGenerator: key,
   });

package/src/read.ts

@@ -4,6 +4,7 @@ import { migrateTable } from "./table";
 import { detachedComponentCopy, type DetachedComponentCopy } from "./component-copy";
 import { randomKey, type KeyGenerator } from "./key";
 import type { EmbedCard, ResolvedAuthor, ResolvedPost, RichTextEmbeds, RichTextResolved } from "@bettercms-ai/types";
+import type { ClassTag, HtmlClasses } from "./html";
 
 /**
  * THE reader. One function, every stored shape, and it never throws.
@@ -335,3 +336,23 @@ export function readStructuredResolved(props: unknown): RichTextResolved | undef
   }
   return { posts, authors, related };
 }
+
+/** Every tag a caller may class (html.ts `ClassTag`); a Record so a tag added there must be added here. */
+const CLASS_TAGS = Object.keys({
+  p: 1, h1: 1, h2: 1, h3: 1, h4: 1, h5: 1, h6: 1, ul: 1, ol: 1, li: 1, a: 1, img: 1, figure: 1, blockquote: 1,
+} satisfies Record<ClassTag, 1>) as ClassTag[];
+
+/**
+ * The site's own class per tag for a DELIVERED value (`value.classes`, the field's
+ * `config.htmlClasses`, which the delivery puts beside the value); undefined when there are none.
+ * Checked, not trusted: only the tags a renderer dresses, with non-empty string classes.
+ */
+export function readStructuredClasses(props: unknown): HtmlClasses | undefined {
+  if (!isRecord(props)) return undefined;
+  const candidate = props.content ?? props.value;
+  const raw = isRecord(candidate) ? candidate.classes : undefined;
+  if (!isRecord(raw)) return undefined;
+  const out: HtmlClasses = {};
+  for (const tag of CLASS_TAGS) if (typeof raw[tag] === "string" && raw[tag]) out[tag] = raw[tag] as string;
+  return Object.keys(out).length ? out : undefined;
+}

package/src/schema.ts

@@ -111,6 +111,9 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
       fields: [
         { name: "href", type: "string" },
         { name: "target", type: "string" },
+        // The author's link-type tokens (V2's link form: nofollow, sponsored, ugc); a new tab's
+        // noopener/noreferrer are the renderer's and are not stored (href.ts `readLinkRel`).
+        { name: "rel", type: "string" },
         // The site's own class on the `<a>`, kept so a styled link round-trips.
         { name: "className", type: "string" },
         // RT2: V2's button is a link the author marked as one (`<a data-button="true">`), edited as