@bettercms-ai/richtext 0.14.0 → 0.17.0

package/src/toc.ts

@@ -27,6 +27,13 @@ export interface OutlineItem {
 const isRecord = (v: unknown): v is Record<string, unknown> =>
   !!v && typeof v === "object" && !Array.isArray(v);
 
+/** A heading id kept from an imported page: a plain HTML id a link can name (`#…`) without escaping. */
+export const isHeadingAnchor = (v: unknown): v is string => typeof v === "string" && /^[A-Za-z0-9][A-Za-z0-9_:.-]{0,127}$/.test(v);
+
+/** Does this value hold a heading anchor? A comparison reads the page with anchors only when it does (ingest `headingAnchors`). */
+export const hasHeadingAnchors = (value: unknown): boolean =>
+  Array.isArray(value) && value.some((n) => isRecord(n) && n._type === "block" && isHeadingAnchor(n.anchor));
+
 const headingText = (node: Record<string, unknown>): string =>
   (Array.isArray(node.children) ? node.children : [])
     .map((c) => (isRecord(c) && typeof c.text === "string" ? c.text : ""))
@@ -36,21 +43,31 @@ const headingText = (node: Record<string, unknown>): string =>
 
 /**
  * The value's top-level h2 and h3, in order, each with a de-duplicated id (V2 `outlineOf`): a
- * heading with no words is left out. `nodes` maps each heading node to its id, which is how a
- * renderer finds the id of the heading it is drawing.
+ * heading with no words is left out. A heading's own `anchor` (an imported page's id, RT9) is its
+ * id, the first time it appears; every other heading's slug steps around the anchors. `nodes` maps
+ * each heading node to its id, which is how a renderer finds the id of the heading it is drawing.
  */
 export function outlineOf(value: unknown): { items: OutlineItem[]; nodes: WeakMap<object, string> } {
-  const items: OutlineItem[] = [];
-  const nodes = new WeakMap<object, string>();
+  const heads: { node: Record<string, unknown>; text: string; anchor: string | null }[] = [];
   const used = new Set<string>();
   for (const node of Array.isArray(value) ? value : []) {
     if (!isRecord(node) || node._type !== "block" || node.listItem || (node.style !== "h2" && node.style !== "h3")) continue;
     const text = headingText(node);
     if (!text) continue;
-    const base = slugify(text);
-    let id = base;
-    for (let n = 2; used.has(id); n++) id = `${base}-${n}`;
-    used.add(id);
+    const anchor = isHeadingAnchor(node.anchor) && !used.has(node.anchor) ? node.anchor : null;
+    if (anchor) used.add(anchor);
+    heads.push({ node, text, anchor });
+  }
+  const items: OutlineItem[] = [];
+  const nodes = new WeakMap<object, string>();
+  for (const { node, text, anchor } of heads) {
+    let id = anchor;
+    if (!id) {
+      const base = slugify(text);
+      id = base;
+      for (let n = 2; used.has(id); n++) id = `${base}-${n}`;
+      used.add(id);
+    }
     nodes.set(node, id);
     items.push({ id, text, depth: node.style === "h2" ? 2 : 3 });
   }

package/src/types.ts

@@ -57,6 +57,11 @@ export interface PortableTextBlock extends PortableTextNode {
   level?: number;
   /** Only meaningful when `listItem` is "check". A checklist item's state is content, not style. */
   checked?: boolean;
+  /**
+   * RT9: a top-level h2/h3's own id from the page it was imported from, kept so the site's links
+   * to it keep working. Only when it differs from the id its words would make (toc.ts `outlineOf`).
+   */
+  anchor?: string;
 }
 
 /** Anything that is not text — an image, an embed, a table, a placed component. */
@@ -358,7 +363,12 @@ export interface PortableTextEmbed extends PortableTextObject {
 export interface PortableTextGallery extends PortableTextObject {
   _type: "gallery";
   layout: "grid" | "carousel";
-  images: { _key: string; image: { src: string; alt: string; mediaId?: string } | null; caption?: string }[];
+  images: {
+    _key: string;
+    /** The rich-text image's own shape, its RT9 framing (`crop`, `focal`; @bettercms-ai/image-url) included. */
+    image: { src: string; alt: string; mediaId?: string; crop?: { top: number; right: number; bottom: number; left: number }; focal?: { x: number; y: number } } | null;
+    caption?: string;
+  }[];
 }
 
 /**
@@ -371,6 +381,45 @@ export interface PortableTextTableOfContents extends PortableTextObject {
   depth: "2" | "3";
 }
 
+/**
+ * RT6: a footnote, an inline object in body text (V2's `<sup data-rt="fn" data-note>`). Only the
+ * note is stored; its number, ids, the end list and the back links are derived (footnote.ts).
+ */
+export interface PortableTextFootnote {
+  _type: "footnote";
+  _key: string;
+  note: string;
+}
+
+/**
+ * RT7: columns, as V2's ColumnsModel: a gap and 2 to 4 columns, each a run of text blocks of its
+ * own (depth 1). The column count is derived. Limits and the write check: columns.ts.
+ */
+export interface PortableTextColumns extends PortableTextObject {
+  _type: "columns";
+  gap: "s" | "m" | "l";
+  columns: { _key: string; content: PortableTextBlock[] }[];
+}
+
+/** RT8: an author bio, a reference to the author's entry; name, avatar and bio are resolved at render (references.ts). */
+export interface PortableTextAuthorBio extends PortableTextObject {
+  _type: "authorBio";
+  author?: { _ref: string };
+}
+
+/**
+ * RT8: related posts: a title, how they are chosen (`topic`: shared topics; `newest`: the
+ * collection's newest; `manual`: the hand-picked `posts`), and how many. Each post is resolved at render.
+ */
+export interface PortableTextRelatedPosts extends PortableTextObject {
+  _type: "relatedPosts";
+  title?: string;
+  mode: "topic" | "newest" | "manual";
+  count: number;
+  /** The hand-picked posts. Absent is none, which is what an automatic (topic, newest) block holds. */
+  posts?: { _key: string; _ref: string }[];
+}
+
 export const isPortableTextBlock = (n: unknown): n is PortableTextBlock =>
   !!n && typeof n === "object" && (n as PortableTextNode)._type === "block";
 
@@ -434,6 +483,14 @@ export const PT_TYPES = {
   gallery: "gallery",
   /** A table of contents built from the headings — see `PortableTextTableOfContents`. The V2 kit's `<nav data-rt="toc">`. */
   tableOfContents: "tableOfContents",
+  /** A footnote, an INLINE object in body text — see `PortableTextFootnote`. The V2 kit's `<sup data-rt="fn">`. */
+  footnote: "footnote",
+  /** Columns of text — see `PortableTextColumns`. The V2 kit's `<div data-rt="columns">`; the legacy `builtin:columns` reads the same way. */
+  columns: "columns",
+  /** An author bio — see `PortableTextAuthorBio`. The V2 kit's `<aside data-rt="author">`. */
+  authorBio: "authorBio",
+  /** Related posts — see `PortableTextRelatedPosts`. The V2 kit's `<aside data-rt="related">`. */
+  relatedPosts: "relatedPosts",
   /**
    * A table. Spelled `table`, unprefixed, because that is what every other Portable Text
    * producer calls one — the Sanity-shaped `{_type:"table", rows}` this platform used to refuse
@@ -494,6 +551,9 @@ export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
   PT_TYPES.embed,
   PT_TYPES.gallery,
   PT_TYPES.tableOfContents,
+  PT_TYPES.columns,
+  PT_TYPES.authorBio,
+  PT_TYPES.relatedPosts,
 ]);
 
 /**
@@ -560,7 +620,12 @@ export function foreignBlocks(value: unknown): { _type: string; _key: string }[]
             ? isStorableGallery(node)
             : type === PT_TYPES.tableOfContents
               ? isStorableTableOfContents(node)
-              : STORABLE_BLOCK_TYPES.has(type);
+              : type === PT_TYPES.columns
+                ? isStorableColumns(node)
+                : type === PT_TYPES.relatedPosts
+                  ? // No `posts` is no picks: an automatic block (topic, newest) needs none.
+                    (node as { posts?: unknown }).posts === undefined || Array.isArray((node as { posts?: unknown }).posts)
+                  : STORABLE_BLOCK_TYPES.has(type);
     if (storable) continue;
     const key = (node as PortableTextNode)._key;
     out.push({ _type: type, _key: typeof key === "string" ? key : "" });
@@ -651,6 +716,13 @@ export function isStorableGallery(node: unknown): boolean {
   return Array.isArray((node as { images?: unknown }).images);
 }
 
+/** Is this `_type:"columns"` one we can render? A `columns` array whose entries hold a `content` array; the rest is `columnsProblems`'. */
+export function isStorableColumns(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  const columns = (node as { columns?: unknown }).columns;
+  return Array.isArray(columns) && columns.every((c) => !!c && typeof c === "object" && Array.isArray((c as { content?: unknown }).content));
+}
+
 /** Is this `_type:"tableOfContents"` one we can render? One of V2's two depths; the title is judged by `tableOfContentsProblems`. */
 export function isStorableTableOfContents(node: unknown): boolean {
   if (!node || typeof node !== "object" || Array.isArray(node)) return false;

package/src/write-refusals.ts

@@ -9,7 +9,7 @@
 import { richTextRefusal, type UiRefusal } from "@bettercms-ai/types";
 import { acceptFor } from "./accept";
 import { ptSchemaFor } from "./schema";
-import { isPortableTextBlock, type PortableText, type PortableTextNode } from "./types";
+import { PT_TYPES, isPortableTextBlock, type PortableText, type PortableTextNode } from "./types";
 
 /**
  * R4: every node, style, list, mark or annotation a field's features do not accept, judged against
@@ -39,10 +39,16 @@ export function notAcceptedProblems(value: PortableText, features: readonly stri
     out.push(richTextRefusal("block_not_accepted", name));
   };
 
-  for (const node of value) {
+  const judge = (node: PortableText[number]) => {
     if (!isPortableTextBlock(node)) {
       if (!blockObjects.has(node._type)) refuse(node._type);
-      continue;
+      // RT7: a column's text is the field's text too, judged by the same features.
+      if (node._type === PT_TYPES.columns && Array.isArray((node as { columns?: unknown }).columns)) {
+        for (const col of (node as unknown as { columns: { content?: unknown }[] }).columns) {
+          if (Array.isArray(col?.content)) for (const b of col.content as PortableText) judge(b);
+        }
+      }
+      return;
     }
     if (!styles.has(node.style ?? "normal")) refuse(node.style);
     if (node.listItem !== undefined && !lists.has(node.listItem)) refuse(node.listItem);
@@ -61,7 +67,8 @@ export function notAcceptedProblems(value: PortableText, features: readonly stri
       // A mark is a markDef key (its annotation was judged above) or a decorator name.
       for (const mark of (child as { marks?: string[] }).marks ?? []) if (!defs.has(mark) && !decorators.has(mark)) refuse(mark);
     }
-  }
+  };
+  for (const node of value) judge(node);
   return out;
 }
 
@@ -75,8 +82,9 @@ export const DERIVED_FIELDS: Readonly<Record<string, readonly string[]>> = {
   embed: ["provider", "shape", "src"],
   columns: ["cols"],
   tableOfContents: ["outline"],
-  authorBio: ["name", "avatar", "bio"],
-  relatedPosts: ["posts[].title", "posts[].slug", "posts[].url", "posts[].cover", "posts[].category"],
+  // RT8 (G-RT8): what a reference resolves to is never stored, on the block or as a `resolved` map.
+  authorBio: ["name", "avatar", "bio", "resolved"],
+  relatedPosts: ["posts[].title", "posts[].slug", "posts[].url", "posts[].cover", "posts[].category", "resolved"],
 };
 
 /** Whether a node holds a derived path: `key`, or `list[].key` on any entry of the list. */