@bettercms-ai/richtext 0.14.0 → 0.17.0

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,12 +13,16 @@ 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 { richTextImageLayout } from "./image-layout";
+import { richTextImageFrame, richTextImageLayout } from "./image-layout";
 import { keyTakeawaysView } from "./key-takeaways";
 import { GALLERY_STYLES, galleryView } from "./gallery";
 import { outlineOf, tocTree, tocView, type OutlineItem } from "./toc";
+import { footnoteOrder } from "./footnote";
+import { BUILTIN_COLUMNS_KEY, COLUMNS_STYLES, columnsView } from "./columns";
+import { authorBioView, relatedPostsView } from "./references";
+import type { RichTextResolved } from "@bettercms-ai/types";
 import { isEmbedAspect, resolveEmbed, type EmbedCard, type EmbedRender } from "./embed";
 
 /**
@@ -249,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;
@@ -282,9 +276,13 @@ function imageHtml(value: unknown, classes: HtmlClasses): string {
   if (!src) return "";
   const caption = str(f.caption);
   const layout = richTextImageLayout(f);
+  // RT9: the crop rides the url, the focal point is object-position; what is stored rides data-*.
+  const frame = richTextImageFrame(src, f.crop, f.focal);
   // A placed image fills its figure; the figure carries the width and position (image-layout.ts).
-  const imgStyle = layout ? ' style="display:block;width:100%;height:auto"' : "";
-  const img = `<img${cls(classes, "img")} src="${esc(src)}" alt="${esc(str(f.alt))}"${imgStyle}>`;
+  const styles = [layout ? "display:block;width:100%;height:auto" : "", frame.position ? `object-position:${frame.position}` : ""].filter(Boolean);
+  const imgStyle = styles.length ? ` style="${styles.join(";")}"` : "";
+  const data = frame.data.map(([k, v]) => ` ${k}="${esc(v)}"`).join("");
+  const img = `<img${cls(classes, "img")} src="${esc(frame.src)}" alt="${esc(str(f.alt))}"${imgStyle}${data}>`;
   const figureClass = [classes.figure, layout?.className].filter(Boolean).join(" ");
   const figureAttrs = `${figureClass ? ` class="${esc(figureClass)}"` : ""}${
     layout ? ` style="${esc(layout.figureStyle)}"` : ""
@@ -434,7 +432,9 @@ function galleryHtml(value: unknown): string {
   const { layout, images } = galleryView(value);
   const s = GALLERY_STYLES[layout];
   const items = images
-    .map((x) => `<li style="${s.li}"><figure style="${s.figure}"><img alt="${esc(x.alt)}" style="${s.img}" loading="lazy" src="${esc(x.src)}">${
+    .map((x) => `<li style="${s.li}"><figure style="${s.figure}"><img alt="${esc(x.alt)}" style="${s.img}${x.position ? `;object-position:${x.position}` : ""}" loading="lazy"${x.data
+      .map(([k, v]) => ` ${k}="${esc(v)}"`)
+      .join("")} src="${esc(x.src)}">${
       x.caption ? `<figcaption>${esc(x.caption)}</figcaption>` : ""
     }</figure></li>`)
     .join("");
@@ -448,6 +448,75 @@ function galleryHtml(value: unknown): string {
  * one); an inline render (a cell, a heading field) keeps the value's outline it sits in.
  */
 let outline: { items: OutlineItem[]; nodes: WeakMap<object, string> } = { items: [], nodes: new WeakMap() };
+/** RT6: the footnotes of the value being rendered, numbered in text order; set and restored with `outline`. */
+let footnotes: { notes: string[]; nodes: WeakMap<object, number> } = { notes: [], nodes: new WeakMap() };
+
+/**
+ * RT6: a footnote's marker, V2's `<sup data-rt="fn" id="fnref-N" data-note><a href="#fn-N">N</a></sup>`.
+ * `data-note` carries the stored note, so the ingest reads it back; the number is its place in the
+ * value. A marker outside the value's body text (a table cell, which the write refuses) has none.
+ */
+function footnoteMarkHtml(value: object): string {
+  const note = esc(typeof (value as { note?: unknown }).note === "string" ? (value as { note: string }).note : "");
+  const n = footnotes.nodes.get(value);
+  return n
+    ? `<sup data-rt="fn" id="fnref-${n}" data-note="${note}"><a href="#fn-${n}" aria-label="Footnote ${n}">${n}</a></sup>`
+    : `<sup data-rt="fn" data-note="${note}"></sup>`;
+}
+
+/**
+ * RT7: columns, V2's `<div data-rt="columns" data-gap data-cols><div data-col="true">…</div></div>`,
+ * each column's text rendered by the same components as the body. The flex row is inline (no
+ * stylesheet on a hosted page): side by side, wrapping one under another on a narrow screen. A
+ * legacy `builtin:columns` renders the same way.
+ */
+function columnsHtml(value: unknown, components: () => Partial<PortableTextHtmlComponents>): string {
+  const view = columnsView(value);
+  if (!view) return "";
+  const s = COLUMNS_STYLES[view.gap];
+  const cols = view.columns
+    .map((c) => `<div data-col="true" style="${s.col}">${c.content.length ? toHTML(c.content as never, { components: components() }) : ""}</div>`)
+    .join("");
+  return `<div data-rt="columns" data-gap="${view.gap}" data-cols="${view.columns.length}" style="${s.row}">${cols}</div>`;
+}
+
+/**
+ * RT8: related posts, V2's `<aside data-rt="related" data-mode data-count data-posts><p data-title>…</p>
+ * <ul><li><a href>…</a></li></ul></aside>`, listing what the server resolved (relatedPostsView).
+ */
+function relatedPostsHtml(value: unknown, resolved: RichTextResolved | undefined): string {
+  const { key, title, mode, count, picked, items } = relatedPostsView(value, resolved);
+  if (!resolved) {
+    return `<aside data-rt="related" data-key="${esc(key)}" data-mode="${mode}" data-count="${count}" data-posts="${esc(picked.join(","))}"${
+      title ? ` data-title="${esc(title)}"` : ""
+    }></aside>`;
+  }
+  if (!items.length) return "";
+  const list = items.map((p) => `<li><a href="${esc(p.url)}">${esc(p.title)}</a></li>`).join("");
+  return `<aside data-rt="related" data-mode="${mode}" data-count="${count}" data-posts="${esc(picked.join(","))}">${
+    title ? `<p data-title>${esc(title)}</p>` : ""
+  }${list ? `<ul>${list}</ul>` : ""}</aside>`;
+}
+
+/**
+ * RT8: an author bio, V2's `<aside data-rt="author" data-author><img><p data-name>…</p><p data-bio>…</p></aside>`.
+ * The `<img>` writes `src` last, as React does, so both renderers give the same bytes (R6).
+ */
+function authorBioHtml(value: unknown, resolved: RichTextResolved | undefined): string {
+  const { key, id, author } = authorBioView(value, resolved);
+  if (!resolved) return `<aside data-rt="author" data-key="${esc(key)}" data-author="${esc(id)}"></aside>`;
+  if (!author) return "";
+  return `<aside data-rt="author" data-author="${esc(id)}">${author?.avatar ? `<img alt="" src="${esc(author.avatar)}">` : ""}${
+    author ? `<p data-name>${esc(author.name)}</p>` : ""
+  }${author?.bio ? `<p data-bio>${esc(author.bio)}</p>` : ""}</aside>`;
+}
+
+/** RT6: the end list, V2 `renderFootnotes` byte for byte: each note, then a link back to its marker. */
+function footnoteListHtml(notes: readonly string[]): string {
+  if (!notes.length) return "";
+  const items = notes.map((n, i) => `<li id="fn-${i + 1}">${esc(n)} <a href="#fnref-${i + 1}" aria-label="Back to reference ${i + 1}">↩</a></li>`).join("");
+  return `<ol class="cs-footnotes" data-rt="footnotes" aria-label="Footnotes">${items}</ol>`;
+}
 
 /** An h2 or h3 with its outline id, so a table of contents (or any link) can point at it. */
 const headingWithId = (tag: "h2" | "h3", classes: HtmlClasses) =>
@@ -511,9 +580,15 @@ export interface RenderOptions {
   inline?: boolean;
   /**
    * RT3: what an embed needs that the value does not hold: the X cards the server fetched for this
-   * render (by url), and the site's opt-in to X's script. Absent: every X post is a link card.
+   * render (by canonical url). Absent: every X post is a link card.
    */
   embeds?: EmbedRender;
+  /**
+   * RT8: the entries this value's author bios and related posts point at, resolved by the caller
+   * whenever a page is produced; never stored. Absent: each block is a placeholder aside carrying
+   * only what is stored (the stored html cache). Present: a block with nothing to show draws nothing.
+   */
+  resolved?: RichTextResolved;
   /**
    * The site's own class per tag, for a value derived FROM that site.
    *
@@ -579,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.
@@ -588,6 +692,7 @@ const buildComponents = (
   binding?: { base: string; keys: ReadonlySet<unknown> },
   renderBlock?: RenderOptions["renderBlock"],
   embeds: EmbedRender = {},
+  resolved?: RichTextResolved,
 ): Partial<PortableTextHtmlComponents> => ({
   block: { ...tagOverrides(classes, STYLE_TAGS), h2: headingWithId("h2", classes), h3: headingWithId("h3", classes) },
   list: {
@@ -624,6 +729,9 @@ const buildComponents = (
     [PT_TYPES.embed]: ({ value }) => embedFigureHtml(value, embeds),
     [PT_TYPES.gallery]: ({ value }) => galleryHtml(value),
     [PT_TYPES.tableOfContents]: ({ value }) => tocHtml(value),
+    [PT_TYPES.relatedPosts]: ({ value }) => relatedPostsHtml(value, resolved),
+    [PT_TYPES.authorBio]: ({ value }) => authorBioHtml(value, resolved),
+    [PT_TYPES.columns]: ({ value }) => columnsHtml(value, () => buildComponents(classes, undefined, renderBlock, embeds, resolved)),
     /**
      * A generic embedded block. A block whose payload this serialiser can READ renders as
      * content; one carrying a reference it would have to resolve against a project renders as a
@@ -636,22 +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 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:/, ""))
@@ -659,6 +755,7 @@ const buildComponents = (
         : "block";
       return `<div class="bcms-block" data-bcms-schema-key="${esc(key)}"></div>`;
     },
+    [PT_TYPES.footnote]: ({ value }) => footnoteMarkHtml(value),
     [PT_TYPES.mention]: ({ value }) => {
       const v = value as { label?: unknown };
       return `<span class="bcms-mention">${esc(typeof v.label === "string" ? v.label : "")}</span>`;
@@ -676,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>`;
@@ -725,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;
 
@@ -734,24 +834,25 @@ export function portableTextToHtml(
 ): string {
   if (!Array.isArray(value) || value.length === 0) return "";
   if (opts.inline) return render(value, opts);
-  const outer = outline;
+  const outer = { outline, footnotes };
   outline = outlineOf(value);
+  footnotes = footnoteOrder(value);
   try {
-    return render(value, opts);
+    return render(value, opts) + footnoteListHtml(footnotes.notes);
   } finally {
-    outline = outer;
+    ({ outline, footnotes } = outer);
   }
 }
 
 function render(value: PortableText, opts: RenderOptions): string {
   const components =
-    opts.classes || opts.renderBlock || opts.embeds
-      ? buildComponents(opts.classes, undefined, opts.renderBlock, opts.embeds)
+    opts.classes || opts.renderBlock || opts.embeds || opts.resolved
+      ? buildComponents(opts.classes, undefined, opts.renderBlock, opts.embeds, opts.resolved)
       : defaultComponents;
 
   if (opts.bindingBase) {
     const base = opts.bindingBase;
-    const bound = buildComponents(opts.classes, { base, keys: new Set(value.map((n) => n._key)) }, opts.renderBlock, opts.embeds);
+    const bound = buildComponents(opts.classes, { base, keys: new Set(value.map((n) => n._key)) }, opts.renderBlock, opts.embeds, opts.resolved);
     const out: string[] = [];
     for (let i = 0; i < value.length; ) {
       const node = value[i];

package/src/image-layout.ts

@@ -1,3 +1,14 @@
+import {
+  focalInCrop,
+  formatImageRect,
+  imageValueUrl,
+  normalizeImageCrop,
+  normalizeImageFocal,
+  objectPosition,
+  parseImageRect,
+  type ImageCrop,
+  type ImageFocal,
+} from "@bettercms-ai/image-url";
 /**
  * Where a rich-text image sits and how wide it is — `align` and `size` on a `builtin:image`
  * block's fields.
@@ -67,3 +78,46 @@ export function richTextImageLayout(fields: Record<string, unknown>): RichTextIm
     figureStyle: `max-width:${maxWidth};margin-left:${ml};margin-right:${mr}`,
   };
 }
+
+/**
+ * RT9: a rich-text image's framing, the platform's own image vocabulary (`@bettercms-ai/image-url`):
+ * `crop`, how much to cut from each edge as 0–1 fractions of the source, and `focal`, a 0–1 point
+ * of the source. Both optional on a `builtin:image`'s fields and on a gallery image.
+ *
+ * The crop is applied the way every lane applies it, through `imageValueUrl` (`?rect=` on a
+ * BetterCMS media url; any other url is drawn uncropped); the focal point is `object-position`
+ * inside that crop. What is stored rides the `<img>` as `data-src` / `data-crop` / `data-focal`
+ * whenever there is a frame, so the ingest reads back exactly what was stored.
+ */
+export interface RichTextImageFrame {
+  /** The url to draw: the stored one, with the crop applied when it can be. */
+  src: string;
+  crop: ImageCrop | null;
+  focal: ImageFocal | null;
+  /** `object-position` for the focal point, or null when there is none. */
+  position: string | null;
+  /** The `data-*` attributes carrying what is stored, in render order; empty when there is no frame. */
+  data: [string, string][];
+}
+
+export function richTextImageFrame(src: string, crop: unknown, focal: unknown): RichTextImageFrame {
+  const c = normalizeImageCrop(crop);
+  const f = normalizeImageFocal(focal);
+  if (!c && !f) return { src, crop: null, focal: null, position: null, data: [] };
+  const drawn = imageValueUrl({ url: src, crop: c, focal: f }) ?? src;
+  const data: [string, string][] = [];
+  if (drawn !== src) data.push(["data-src", src]);
+  if (c) data.push(["data-crop", formatImageRect(c)]);
+  if (f) data.push(["data-focal", `${f.x},${f.y}`]);
+  return { src: drawn, crop: c, focal: f, position: f ? objectPosition(focalInCrop(f, c)) : null, data };
+}
+
+/** The stored framing an `<img>` carries back (`richTextImageFrame`'s `data`), for the ingest. */
+export function readImageFrame(img: { getAttribute(name: string): string | null }): { src: string | null; crop: ImageCrop | null; focal: ImageFocal | null } {
+  const xy = (img.getAttribute("data-focal") ?? "").split(",").map(Number);
+  return {
+    src: img.getAttribute("data-src"),
+    crop: parseImageRect(img.getAttribute("data-crop")),
+    focal: xy.length === 2 ? normalizeImageFocal({ x: xy[0], y: xy[1] }) : null,
+  };
+}

package/src/index.ts

@@ -8,6 +8,9 @@ export * from "./table";
 export * from "./key-takeaways";
 export * from "./gallery";
 export * from "./toc";
+export * from "./footnote";
+export * from "./columns";
+export * from "./references";
 export * from "./styled";
 export * from "./read";
 export * from "./component-copy";