@bettercms-ai/richtext 0.12.0 → 0.14.0

package/src/schema.ts

@@ -102,7 +102,7 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
       ],
     },
   ];
-  if (has("link") || has("internalLink")) {
+  if (has("link") || has("internalLink") || has("button")) {
     annotations.push({
       name: PT_TYPES.link,
       title: "Link",
@@ -113,6 +113,9 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
         { name: "target", 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
+        // text in the flow. Only a field with the button feature has the field to set.
+        ...(has("button") ? [{ name: "button", type: "boolean" as const }] : []),
       ],
     });
   }
@@ -222,6 +225,40 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
    * hold and move it; it does not validate the payload, so a deeper declaration would buy
    * nothing and drift from the types that do.
    */
+  // RT3: the third-party embed; its provider and frame are derived from `url` (embed.ts).
+  if (has("providerEmbed")) {
+    blockObjects.push({
+      name: PT_TYPES.embed,
+      title: "Embed",
+      fields: [
+        { name: "url", type: "string" },
+        { name: "title", type: "string" },
+        { name: "aspect", type: "string" },
+      ],
+    });
+  }
+  // RT4: the gallery; each image is the rich-text image's `{ src, alt }` (gallery.ts).
+  if (has("gallery")) {
+    blockObjects.push({
+      name: PT_TYPES.gallery,
+      title: "Gallery",
+      fields: [
+        { name: "layout", type: "string" },
+        { name: "images", type: "object" },
+      ],
+    });
+  }
+  // RT5: the table of contents; its outline is derived from the headings (toc.ts).
+  if (has("tableOfContents")) {
+    blockObjects.push({
+      name: PT_TYPES.tableOfContents,
+      title: "Table of contents",
+      fields: [
+        { name: "title", type: "string" },
+        { name: "depth", type: "string" },
+      ],
+    });
+  }
   if (has("table")) {
     blockObjects.push({
       name: PT_TYPES.table,

package/src/toc.ts

@@ -0,0 +1,129 @@
+import { slugify } from "@bettercms-ai/types";
+import { PT_TYPES } from "./types";
+import { isPortableTextTable } from "./table";
+
+/**
+ * RT5: the table of contents (`PortableTextTableOfContents`, types.ts): the one `slugify`, the
+ * outline a value's headings make, the write check, and the tree both renderers draw.
+ *
+ * Stored is what the author sets, `{ title?, depth }`; the outline is derived from the value's
+ * headings on every render and never stored (R8 refuses `outline`). Every top-level h2 and h3 is
+ * given its outline id on every render, with or without a table of contents, so a link to a
+ * heading keeps working when one is added or removed.
+ */
+export const PT_TOC_LIMITS = { titleChars: 40 } as const;
+export const TOC_DEPTHS = ["2", "3"] as const;
+export type TocDepth = (typeof TOC_DEPTHS)[number];
+
+/** The id a heading's words make: V2's `slugify`, whose one spelling lives in @bettercms-ai/types. */
+export { slugify };
+
+export interface OutlineItem {
+  id: string;
+  text: string;
+  depth: 2 | 3;
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+const headingText = (node: Record<string, unknown>): string =>
+  (Array.isArray(node.children) ? node.children : [])
+    .map((c) => (isRecord(c) && typeof c.text === "string" ? c.text : ""))
+    .join("")
+    .replace(/​/g, "")
+    .trim();
+
+/**
+ * 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.
+ */
+export function outlineOf(value: unknown): { items: OutlineItem[]; nodes: WeakMap<object, string> } {
+  const items: OutlineItem[] = [];
+  const nodes = new WeakMap<object, string>();
+  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);
+    nodes.set(node, id);
+    items.push({ id, text, depth: node.style === "h2" ? 2 : 3 });
+  }
+  return { items, nodes };
+}
+
+export type TocEntry = OutlineItem & { children: OutlineItem[] };
+
+/**
+ * The list a table of contents draws (V2 `renderArticle("toc")`): only h2 at depth "2"; an h3
+ * nests under the entry before it, and opens the list only when nothing comes before it.
+ */
+export function tocTree(items: readonly OutlineItem[], depth: TocDepth): TocEntry[] {
+  const out: TocEntry[] = [];
+  for (const it of items) {
+    if (it.depth === 3 && depth === "2") continue;
+    const last = out[out.length - 1];
+    if (it.depth === 3 && last) last.children.push(it);
+    else out.push({ ...it, children: [] });
+  }
+  return out;
+}
+
+/** What a reader sees of the block itself: its title (trimmed), the label its nav carries, and its depth. */
+export function tocView(value: unknown): { title: string; label: string; depth: TocDepth } {
+  const v = isRecord(value) ? value : {};
+  const title = typeof v.title === "string" ? v.title.trim() : "";
+  return { title, label: title || "Table of contents", depth: v.depth === "2" ? "2" : "3" };
+}
+
+/** One reason a stored table of contents is refused, at its own path inside the block. */
+export type PortableTextTocProblem = { path: Array<string | number>; code: string; message: string };
+
+const KEYS = new Set(["_type", "_key", "title", "depth"]);
+
+/**
+ * Every reason `node` cannot be stored: `toc_invalid` (a shape problem) or `toc_limit_exceeded`
+ * (V2's 40-character title). A derived `outline` is refused by the R8 check, by name.
+ */
+export function tableOfContentsProblems(node: unknown): PortableTextTocProblem[] {
+  const out: PortableTextTocProblem[] = [];
+  if (!isRecord(node) || node._type !== PT_TYPES.tableOfContents) return out;
+  const bad = (path: Array<string | number>, message: string, code = "toc_invalid") =>
+    out.push({ path, code, message: `${code}: ${message}` });
+  for (const k of Object.keys(node)) if (!KEYS.has(k) && k !== "outline") bad([k], `unknown key "${k}" (title, depth)`);
+  if (!(TOC_DEPTHS as readonly unknown[]).includes(node.depth)) bad(["depth"], 'depth must be "2" or "3"');
+  if (node.title !== undefined) {
+    if (typeof node.title !== "string") bad(["title"], "title must be a string");
+    else if (node.title.length > PT_TOC_LIMITS.titleChars) {
+      bad(["title"], `title is ${node.title.length} characters; at most ${PT_TOC_LIMITS.titleChars}`, "toc_limit_exceeded");
+    }
+  }
+  return out;
+}
+
+/** `tableOfContentsProblems` for every table of contents in a value (top level, and in table cells), with its block key. */
+export function portableTextTableOfContentsProblems(value: unknown): Array<PortableTextTocProblem & { block: string }> {
+  const out: Array<PortableTextTocProblem & { block: string }> = [];
+  const walk = (blocks: unknown) => {
+    if (!Array.isArray(blocks)) return;
+    for (const node of blocks) {
+      if (isPortableTextTable(node)) {
+        for (const row of node.rows as unknown[]) {
+          if (!isRecord(row) || !Array.isArray(row.cells)) continue;
+          for (const cell of row.cells) if (isRecord(cell)) walk(cell.content);
+        }
+        continue;
+      }
+      if (!isRecord(node) || node._type !== PT_TYPES.tableOfContents) continue;
+      const block = typeof node._key === "string" ? node._key : "";
+      for (const p of tableOfContentsProblems(node)) out.push({ ...p, block });
+    }
+  };
+  walk(value);
+  return out;
+}

package/src/types.ts

@@ -338,6 +338,39 @@ export interface PortableTextKeyTakeaways extends PortableTextObject {
   points: string[];
 }
 
+/**
+ * RT3: an embed, as V2's EmbedModel. Only what the author sets is stored: the link, the
+ * screen-reader title (≤ EMBED_TITLE_MAX) and the shape. The provider, its kind and the frame src
+ * are derived from `url` at render (`resolveEmbed`), never stored.
+ */
+export interface PortableTextEmbed extends PortableTextObject {
+  _type: "embed";
+  url: string;
+  title: string;
+  aspect: "16:9" | "4:3" | "1:1" | "9:16";
+}
+
+/**
+ * RT4: a gallery, as V2's GalleryModel. Each image is the rich-text image's own `{ src, alt }`
+ * (+ an optional media id), so media rewrites, alt audits and CDN transforms read it the same way.
+ * Limits and the write check: gallery.ts.
+ */
+export interface PortableTextGallery extends PortableTextObject {
+  _type: "gallery";
+  layout: "grid" | "carousel";
+  images: { _key: string; image: { src: string; alt: string; mediaId?: string } | null; caption?: string }[];
+}
+
+/**
+ * RT5: a table of contents, as V2's TocModel: a title (≤ 40) and which headings it lists. The
+ * outline is derived from the value's headings at render (toc.ts) and never stored.
+ */
+export interface PortableTextTableOfContents extends PortableTextObject {
+  _type: "tableOfContents";
+  title?: string;
+  depth: "2" | "3";
+}
+
 export const isPortableTextBlock = (n: unknown): n is PortableTextBlock =>
   !!n && typeof n === "object" && (n as PortableTextNode)._type === "block";
 
@@ -359,6 +392,8 @@ export interface RichTextEnvelope {
   format: typeof PORTABLE_TEXT_FORMAT;
   value: PortableText;
   html: string;
+  /** RT3: what its embeds need beside `html` (the X cards), written at html-cache build. */
+  embeds?: import("@bettercms-ai/types").RichTextEmbeds;
 }
 
 /**
@@ -389,6 +424,16 @@ export const PT_TYPES = {
   pullQuote: "pullQuote",
   /** Key takeaways — see `PortableTextKeyTakeaways`. The V2 kit's `<aside data-rt="takeaways">`. */
   keyTakeaways: "keyTakeaways",
+  /**
+   * A third-party embed (X, CodePen, Figma, Maps, Spotify, Podcasts, audio, a link card) — see
+   * `PortableTextEmbed` and `embed.ts`. The V2 kit's `<figure data-rt="embed">`. Gated by the
+   * `embed` feature; YouTube and Vimeo links still resolve here too, through the video resolver.
+   */
+  embed: "embed",
+  /** A gallery of images, a grid or a carousel — see `PortableTextGallery`. The V2 kit's `<figure data-rt="gallery">`. */
+  gallery: "gallery",
+  /** A table of contents built from the headings — see `PortableTextTableOfContents`. The V2 kit's `<nav data-rt="toc">`. */
+  tableOfContents: "tableOfContents",
   /**
    * 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
@@ -446,6 +491,9 @@ export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
   PT_TYPES.file,
   PT_TYPES.pullQuote,
   PT_TYPES.keyTakeaways,
+  PT_TYPES.embed,
+  PT_TYPES.gallery,
+  PT_TYPES.tableOfContents,
 ]);
 
 /**
@@ -465,6 +513,13 @@ export const BUILTIN_EMBED_KEY = "builtin:video" as const;
 /** A callout (`{ tone: info|tip|warning, title, message }`) and a toggle (`{ title, body }`): plain text, read straight. */
 export const BUILTIN_CALLOUT_KEY = "builtin:callout" as const;
 export const BUILTIN_TOGGLE_KEY = "builtin:toggle" as const;
+/**
+ * A part of a body the SITE's own code renders: an MDX component (`<Figure>…</Figure>`, a chart, a
+ * tabs widget) or an `{expression}`. Not content an author edits here: the page shows what the
+ * build drew, publish never writes over it, and the editor shows it as a locked card. `fields.source`
+ * keeps what the repo wrote, for the card; the delivered html carries only the empty marker.
+ */
+export const BUILTIN_SITE_KEY = "builtin:site" as const;
 
 /**
  * The `schemaKey` of a component embedded in rich text. A wire value shared with the dashboard
@@ -493,7 +548,7 @@ export function foreignBlocks(value: unknown): { _type: string; _key: string }[]
     if (!node || typeof node !== "object" || Array.isArray(node)) continue;
     const type = (node as PortableTextNode)._type;
     if (typeof type !== "string") continue;
-    // A table, a pull quote and key takeaways are admitted by SHAPE, never by `_type` alone —
+    // A table, a pull quote, key takeaways, a gallery and a table of contents are admitted by SHAPE, never by `_type` alone —
     // see `isStorableTable`.
     const storable = type === PT_TYPES.table
       ? isStorableTable(node)
@@ -501,7 +556,11 @@ export function foreignBlocks(value: unknown): { _type: string; _key: string }[]
         ? isStorablePullQuote(node)
         : type === PT_TYPES.keyTakeaways
           ? isStorableKeyTakeaways(node)
-          : STORABLE_BLOCK_TYPES.has(type);
+          : type === PT_TYPES.gallery
+            ? isStorableGallery(node)
+            : type === PT_TYPES.tableOfContents
+              ? isStorableTableOfContents(node)
+              : STORABLE_BLOCK_TYPES.has(type);
     if (storable) continue;
     const key = (node as PortableTextNode)._key;
     out.push({ _type: type, _key: typeof key === "string" ? key : "" });
@@ -575,6 +634,30 @@ export function isStorableKeyTakeaways(node: unknown): boolean {
   return Array.isArray((node as { points?: unknown }).points);
 }
 
+/** An embed holds a link, a title of at most 120 characters, and one of V2's four shapes. */
+export function isStorableEmbed(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  const n = node as { url?: unknown; title?: unknown; aspect?: unknown };
+  return typeof n.url === "string" && typeof n.title === "string" && n.title.length <= 120
+    && (n.aspect === "16:9" || n.aspect === "4:3" || n.aspect === "1:1" || n.aspect === "9:16");
+}
+
+/**
+ * Is this `_type:"gallery"` one we can render? An `images` array; what is in it and the limits
+ * are judged by `galleryProblems` (gallery.ts), which names each problem with a code.
+ */
+export function isStorableGallery(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  return Array.isArray((node as { images?: unknown }).images);
+}
+
+/** 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;
+  const depth = (node as { depth?: unknown }).depth;
+  return depth === "2" || depth === "3";
+}
+
 /**
  * @deprecated The marker a table-accepting field used to carry INSTEAD of a table.
  *

package/src/write-refusals.ts

@@ -0,0 +1,106 @@
+/**
+ * What a rich-text WRITE may not hold, refused by name and never removed (RT0, properties R4, R8).
+ *
+ * Both read the value and answer a list. Neither changes it, so a caller that writes after an
+ * empty answer writes exactly what it was given: there is no strip step for content to vanish in.
+ * Callers that judge a stored value should judge only what the write introduces, as the field-key
+ * rules do: values written before a rule existed must keep saving.
+ */
+import { richTextRefusal, type UiRefusal } from "@bettercms-ai/types";
+import { acceptFor } from "./accept";
+import { ptSchemaFor } from "./schema";
+import { isPortableTextBlock, type PortableText, type PortableTextNode } from "./types";
+
+/**
+ * R4: every node, style, list, mark or annotation a field's features do not accept, judged against
+ * `ptSchemaFor(acceptFor(features))`, the same schema the editor offers. One refusal per name:
+ * `richtext.block_not_accepted:<name>`, where name is a block object's or inline object's `_type`,
+ * a style (`h2`), a list (`check`), a decorator (`strong`) or an annotation's `_type` (`link`).
+ */
+export function notAcceptedProblems(value: PortableText, features: readonly string[]): UiRefusal[] {
+  const accepted = acceptFor(features);
+  const schema = ptSchemaFor(accepted);
+  // One `link` annotation carries both: a plain link needs a link element, a button the button one.
+  const linkOk = accepted.includes("link") || accepted.includes("internalLink");
+  const buttonOk = accepted.includes("button");
+  const names = (list: { name: string }[]) => new Set(list.map((x) => x.name));
+  const styles = names(schema.styles);
+  const lists = names(schema.lists);
+  const decorators = names(schema.decorators);
+  const annotations = names(schema.annotations);
+  const blockObjects = names(schema.blockObjects);
+  const inlineObjects = names(schema.inlineObjects);
+
+  const out: UiRefusal[] = [];
+  const refused = new Set<string>();
+  const refuse = (name: string) => {
+    if (refused.has(name)) return;
+    refused.add(name);
+    out.push(richTextRefusal("block_not_accepted", name));
+  };
+
+  for (const node of value) {
+    if (!isPortableTextBlock(node)) {
+      if (!blockObjects.has(node._type)) refuse(node._type);
+      continue;
+    }
+    if (!styles.has(node.style ?? "normal")) refuse(node.style);
+    if (node.listItem !== undefined && !lists.has(node.listItem)) refuse(node.listItem);
+    const defs = new Set<string>();
+    for (const def of node.markDefs ?? []) {
+      defs.add(def._key);
+      if (def._type === "link") {
+        if (def.button === true ? !buttonOk : !linkOk) refuse(def.button === true ? "button" : "link");
+      } else if (!annotations.has(def._type)) refuse(def._type);
+    }
+    for (const child of node.children ?? []) {
+      if (child._type !== "span") {
+        if (!inlineObjects.has(child._type)) refuse(child._type);
+        continue;
+      }
+      // 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);
+    }
+  }
+  return out;
+}
+
+/**
+ * What each V2 block computes at render time and never stores (kit-richtext-blocks-gap.md, the
+ * "Derived" line of each block). `posts[].title` means that key on every entry of `posts`. Each RT
+ * step confirms its row when it builds the type; a key outside its row is not judged here.
+ */
+export const DERIVED_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  footnote: ["number"],
+  embed: ["provider", "shape", "src"],
+  columns: ["cols"],
+  tableOfContents: ["outline"],
+  authorBio: ["name", "avatar", "bio"],
+  relatedPosts: ["posts[].title", "posts[].slug", "posts[].url", "posts[].cover", "posts[].category"],
+};
+
+/** Whether a node holds a derived path: `key`, or `list[].key` on any entry of the list. */
+const holds = (node: Record<string, unknown>, path: string): boolean => {
+  const [list, key] = path.split("[].");
+  if (key === undefined) return Object.hasOwn(node, path);
+  const items = node[list];
+  return Array.isArray(items) && items.some((item) => item !== null && typeof item === "object" && Object.hasOwn(item, key));
+};
+
+/**
+ * R8: every derived key a write carries, top-level nodes and inline children alike, refused as
+ * `richtext.derived_field:<_type>.<path>` (`embed.provider`, `relatedPosts.posts[].title`).
+ */
+export function derivedFieldProblems(value: PortableText): UiRefusal[] {
+  const out: UiRefusal[] = [];
+  const judge = (node: PortableTextNode) => {
+    for (const path of DERIVED_FIELDS[node._type] ?? []) {
+      if (holds(node as unknown as Record<string, unknown>, path)) out.push(richTextRefusal("derived_field", `${node._type}.${path}`));
+    }
+  };
+  for (const node of value) {
+    judge(node);
+    if (isPortableTextBlock(node)) for (const child of node.children ?? []) judge(child);
+  }
+  return out;
+}