@bettercms-ai/richtext 0.8.3 → 0.10.0

package/src/schema.ts

@@ -124,6 +124,33 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
 
   const blockObjects: PtObject[] = [];
   if (has("p")) blockObjects.push({ name: PT_TYPES.divider, title: "Divider" });
+  // The pull quote rides `p` as the blockquote style does: a quotation is prose, and no stored
+  // field config has to change for an author to get one. `link` is declared as the kit writes
+  // it, a URL string; a link object carrying `href` is read too (`pullQuoteHref`).
+  if (has("p")) {
+    blockObjects.push({
+      name: PT_TYPES.pullQuote,
+      title: "Pull quote",
+      fields: [
+        { name: "quote", type: "string" },
+        { name: "name", type: "string" },
+        { name: "role", type: "string" },
+        { name: "link", type: "string" },
+      ],
+    });
+  }
+  // Key takeaways ride `ul`: they ARE a bulleted list, under a title, so a field that forbids a
+  // list is not handed one in another shape. `points` is an array of strings (types.ts).
+  if (has("ul")) {
+    blockObjects.push({
+      name: PT_TYPES.keyTakeaways,
+      title: "Key takeaways",
+      fields: [
+        { name: "title", type: "string" },
+        { name: "points", type: "object" },
+      ],
+    });
+  }
   if (has("pre")) {
     blockObjects.push({
       name: PT_TYPES.code,
@@ -196,7 +223,18 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
    * nothing and drift from the types that do.
    */
   if (has("table")) {
-    blockObjects.push({ name: PT_TYPES.table, title: "Table", fields: [{ name: "rows", type: "object" }] });
+    blockObjects.push({
+      name: PT_TYPES.table,
+      title: "Table",
+      // `caption`, `notes` and the two group lists are the V2 table's, optional; see `types.ts`.
+      fields: [
+        { name: "rows", type: "object" },
+        { name: "caption", type: "string" },
+        { name: "notes", type: "string" },
+        { name: "rowGroups", type: "object" },
+        { name: "columnGroups", type: "object" },
+      ],
+    });
   }
 
   return {

package/src/table.ts

@@ -4,6 +4,9 @@ import {
   type PortableText,
   type PortableTextTable,
   type PortableTextTableCell,
+  type PortableTextTableGroup,
+  type PortableTextTableDesign,
+  type PortableTextTableJsonLd,
   type PortableTextTableRow,
 } from "./types";
 import { deterministicKeys, isValidKey, randomKey, type KeyGenerator } from "./key";
@@ -143,6 +146,9 @@ function normalizeCell(raw: unknown, at: [number, number], mint: Mint, read: Cel
     ...(raw.header === true ? { header: true } : {}),
     ...(span === undefined ? {} : { span }),
     ...(rowSpan === undefined ? {} : { rowSpan }),
+    ...(typeof raw.group === "string" ? { group: raw.group } : {}),
+    ...(raw.highlight === true ? { highlight: true } : {}),
+    ...(raw.sortable === true ? { sortable: true } : {}),
   };
 }
 
@@ -154,6 +160,10 @@ function normalizeRow(raw: unknown, at: number, mint: Mint, read: CellContentRea
     _key: isRecord(raw) && isValidKey(raw._key) ? raw._key : mint("r", at),
     cells: cells.map((c, col) => normalizeCell(c, [at, col], mint, read)),
     ...(isRecord(raw) && raw.head === true ? { head: true } : {}),
+    ...(isRecord(raw) && typeof raw.group === "string" ? { group: raw.group } : {}),
+    // The V2 table's two row flags ("Totals row", "Highlight this row"); see `PortableTextTableRow`.
+    ...(isRecord(raw) && raw.footer === true ? { footer: true } : {}),
+    ...(isRecord(raw) && raw.highlight === true ? { highlight: true } : {}),
   };
 }
 
@@ -227,5 +237,286 @@ export function migrateTable(
     // Carried through: a migrated table that an author saves back is still the same table, and
     // dropping the flag on that save would change the page the next time it renders.
     ...(node.legacy === true ? { legacy: true } : {}),
+    ...tableExtras(node),
+  };
+}
+
+/**
+ * Caption, notes and the two group lists, carried through the reader. Each is written only when
+ * the stored value has it, so a table without them reads back byte for byte as it did before
+ * they existed. Permissive like the rest of the read: a group entry that is not an object with a
+ * string `_key` is skipped (nothing could name it), and a missing label reads as "". The write
+ * refuses all of it by name — see `tableProblems`.
+ */
+function tableExtras(node: Record<string, unknown>): Partial<PortableTextTable> {
+  const groups = (list: unknown): PortableTextTableGroup[] | undefined =>
+    Array.isArray(list)
+      ? list
+          .filter((g): g is Record<string, unknown> => isRecord(g) && typeof g._key === "string" && g._key !== "")
+          .map((g) => ({ _key: g._key as string, label: typeof g.label === "string" ? g.label : "" }))
+      : undefined;
+  const rowGroups = groups(node.rowGroups);
+  const columnGroups = groups(node.columnGroups);
+  return {
+    ...(typeof node.caption === "string" ? { caption: node.caption } : {}),
+    ...(typeof node.notes === "string" ? { notes: node.notes } : {}),
+    ...(rowGroups ? { rowGroups } : {}),
+    ...(columnGroups ? { columnGroups } : {}),
+    ...(node.filterable === true ? { filterable: true } : {}),
+    ...(jsonLdOf(node.jsonLd) ? { jsonLd: jsonLdOf(node.jsonLd) } : {}),
+    ...(designOf(node.design) ? { design: designOf(node.design) } : {}),
+  };
+}
+
+const DESIGN_KEYS = new Set(["responsive", "sticky"]);
+
+/**
+ * A stored `design` read permissively, as V2's parseTableElement reads the figure: `responsive` only when `stack` or `cards`
+ * (`scroll` is the default and is not kept), `sticky` only when true. Nothing left is nothing.
+ */
+export function designOf(v: unknown): PortableTextTableDesign | undefined {
+  if (!isRecord(v)) return undefined;
+  const d: PortableTextTableDesign = {
+    ...(v.responsive === "stack" || v.responsive === "cards" ? { responsive: v.responsive } : {}),
+    ...(v.sticky === true ? { sticky: true } : {}),
+  };
+  return Object.keys(d).length ? d : undefined;
+}
+
+const JSONLD_TYPES = ["ItemList", "Dataset", "Offers"] as const;
+const JSONLD_KEYS = new Set(["type", "axis", "priceRow"]);
+
+/** A stored `jsonLd` read permissively: a type this table offers, its axis and price row when well formed, else nothing. */
+export function jsonLdOf(v: unknown): PortableTextTableJsonLd | undefined {
+  if (!isRecord(v) || !(JSONLD_TYPES as readonly unknown[]).includes(v.type)) return undefined;
+  return {
+    type: v.type as PortableTextTableJsonLd["type"],
+    ...(v.axis === "rows" || v.axis === "columns" ? { axis: v.axis } : {}),
+    ...(typeof v.priceRow === "string" && v.priceRow ? { priceRow: v.priceRow } : {}),
+  };
+}
+
+/**
+ * The limits a table's caption, notes and group labels are held to — the V2 table's
+ * (`TABLE_LIMITS` in `@bettercms-ai/types` table-value.ts), restated so this package keeps no
+ * dependency on that one.
+ */
+export const PT_TABLE_LIMITS = { captionChars: 300, notesChars: 2000, labelChars: 300, keyChars: 64 } as const;
+
+/** One reason a stored table is refused, at its own path inside the table. The V2 table's shape. */
+export type PortableTextTableProblem = { path: Array<string | number>; code: string; message: string };
+
+const GROUP_KEYS = new Set(["_key", "label"]);
+
+/**
+ * Every reason the caption, notes and groups of `node` cannot be stored, each named with the V2
+ * table's codes (`table_value_invalid`, `table_limit_exceeded`) and its path inside the table.
+ *
+ * 🔴 ONLY THE NEW KEYS ARE JUDGED. A table that carries none of them answers `[]` whatever else it
+ * holds, so every table stored before they existed keeps saving exactly as it did. None of these
+ * checks reads field config, so there is nothing to grandfather.
+ */
+export function tableProblems(node: unknown): PortableTextTableProblem[] {
+  const out: PortableTextTableProblem[] = [];
+  if (!isRecord(node)) return out;
+  const bad = (path: Array<string | number>, message: string, code = "table_value_invalid") =>
+    out.push({ path, code, message: `${code}: ${message}` });
+  const text = (v: unknown, at: Array<string | number>, what: string, max: number, required = false) => {
+    if (v === undefined && !required) return;
+    if (typeof v !== "string") bad(at, `${what} must be a string`);
+    else if (v.length > max) bad(at, `${what} is ${v.length} characters; at most ${max}`, "table_limit_exceeded");
+  };
+  text(node.caption, ["caption"], "caption", PT_TABLE_LIMITS.captionChars);
+  text(node.notes, ["notes"], "notes", PT_TABLE_LIMITS.notesChars);
+  if (node.filterable !== undefined && typeof node.filterable !== "boolean") bad(["filterable"], "filterable must be true or false");
+  if (node.design !== undefined) {
+    const d = node.design;
+    if (!isRecord(d)) bad(["design"], "design must be an object { responsive?, sticky? }");
+    else {
+      for (const k of Object.keys(d)) if (!DESIGN_KEYS.has(k)) bad(["design", k], `unknown key "${k}" (responsive, sticky)`);
+      if (d.responsive !== undefined && !["scroll", "stack", "cards"].includes(d.responsive as string)) bad(["design", "responsive"], 'responsive must be "scroll", "stack" or "cards"');
+      if (d.sticky !== undefined && typeof d.sticky !== "boolean") bad(["design", "sticky"], "sticky must be true or false");
+    }
+  }
+  if (node.jsonLd !== undefined) {
+    const j = node.jsonLd;
+    if (!isRecord(j)) bad(["jsonLd"], "jsonLd must be an object { type, axis?, priceRow? }");
+    else {
+      for (const k of Object.keys(j)) if (!JSONLD_KEYS.has(k)) bad(["jsonLd", k], `unknown key "${k}" (type, axis, priceRow)`);
+      if (!(JSONLD_TYPES as readonly unknown[]).includes(j.type)) bad(["jsonLd", "type"], `type must be one of ${JSONLD_TYPES.join(", ")} (leave jsonLd out for none)`);
+      if (j.axis !== undefined && j.axis !== "rows" && j.axis !== "columns") bad(["jsonLd", "axis"], 'axis must be "rows" or "columns"');
+      if (j.priceRow !== undefined) {
+        const keys = (Array.isArray(node.rows) ? node.rows : []).map((r) => (isRecord(r) ? r._key : undefined));
+        if (typeof j.priceRow !== "string" || !keys.includes(j.priceRow)) bad(["jsonLd", "priceRow"], "priceRow must be the _key of one of the table's rows");
+      }
+    }
+  }
+
+  const keyed = (list: unknown, at: "rowGroups" | "columnGroups"): Set<string> => {
+    const seen = new Set<string>();
+    if (list === undefined) return seen;
+    if (!Array.isArray(list)) {
+      bad([at], `${at} must be an array of { _key, label }`);
+      return seen;
+    }
+    list.forEach((g, i) => {
+      if (!isRecord(g)) return bad([at, i], `${at}[${i}] must be an object { _key, label }`);
+      for (const k of Object.keys(g)) if (!GROUP_KEYS.has(k)) bad([at, i, k], `unknown key "${k}" (_key, label)`);
+      if (typeof g._key !== "string" || g._key === "" || g._key.length > PT_TABLE_LIMITS.keyChars) {
+        bad([at, i, "_key"], `needs a _key string of 1 to ${PT_TABLE_LIMITS.keyChars} characters`);
+      } else if (seen.has(g._key)) bad([at, i, "_key"], `_key "${g._key}" is used twice`);
+      else seen.add(g._key);
+      text(g.label, [at, i, "label"], "label", PT_TABLE_LIMITS.labelChars, true);
+    });
+    return seen;
+  };
+  const rowGroups = keyed(node.rowGroups, "rowGroups");
+  const columnGroups = keyed(node.columnGroups, "columnGroups");
+
+  const rows = Array.isArray(node.rows) ? node.rows : [];
+  rows.forEach((row, r) => {
+    if (!isRecord(row)) return;
+    for (const flag of ["footer", "highlight"] as const) {
+      if (row[flag] !== undefined && typeof row[flag] !== "boolean") bad(["rows", r, flag], `${flag} must be true or false`);
+    }
+    if (row.head === true && row.footer === true) bad(["rows", r, "footer"], "a head row cannot also be a footer (totals) row");
+    if (row.group !== undefined) {
+      if (row.head === true) bad(["rows", r, "group"], "a head row takes no group (row groups hold body rows)");
+      else if (typeof row.group !== "string" || !rowGroups.has(row.group)) {
+        bad(["rows", r, "group"], `group "${String(row.group)}" is not a key of rowGroups`);
+      }
+    }
+    (Array.isArray(row.cells) ? row.cells : []).forEach((cell, c) => {
+      for (const flag of ["highlight", "sortable"] as const) {
+        if (!isRecord(cell) || cell[flag] === undefined) continue;
+        const at = ["rows", r, "cells", c, flag];
+        if (typeof cell[flag] !== "boolean") bad(at, `${flag} must be true or false`);
+        else if (r !== 0 && cell[flag]) bad(at, `a column's ${flag} is named on its cell in the first row only`);
+      }
+      if (!isRecord(cell) || cell.group === undefined) return;
+      const at = ["rows", r, "cells", c, "group"];
+      if (r !== 0) bad(at, "a column's group is named on its cell in the first row only");
+      else if (typeof cell.group !== "string" || !columnGroups.has(cell.group)) {
+        bad(at, `group "${String(cell.group)}" is not a key of columnGroups`);
+      }
+    });
+  });
+  return out;
+}
+
+/**
+ * `tableProblems` for every table in a rich-text value — top level, and inside cells — with the
+ * table's `_key` so a refusal names the table an author has to find.
+ */
+export function portableTextTableProblems(value: unknown): Array<PortableTextTableProblem & { table: string }> {
+  const out: Array<PortableTextTableProblem & { table: string }> = [];
+  const walk = (blocks: unknown) => {
+    if (!Array.isArray(blocks)) return;
+    for (const node of blocks) {
+      if (!isPortableTextTable(node)) continue;
+      const table = typeof node._key === "string" ? node._key : "";
+      for (const p of tableProblems(node)) out.push({ ...p, table });
+      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);
+      }
+    }
+  };
+  walk(value);
+  return out;
+}
+
+/**
+ * A table's rows split into its three sections: the LEADING run of `head` rows (`<thead>`), the
+ * TRAILING run of `footer` rows (`<tfoot>`, the V2 table's "Totals row"), and the body between.
+ *
+ * Runs, not every flagged row, for the reason `<thead>` already is one: a section cannot be
+ * lifted out of document order without moving content the author placed. A `footer` row with a
+ * body row after it stays in the body (permissive read). Shared by every renderer so they agree.
+ */
+export function tableSections(table: PortableTextTable): { head: unknown[]; body: unknown[]; foot: unknown[] } {
+  const rows: unknown[] = Array.isArray(table.rows) ? table.rows : [];
+  const headCount = rows.findIndex((r) => !isRecord(r) || r.head !== true);
+  const head = rows.slice(0, headCount === -1 ? rows.length : headCount);
+  let footFrom = rows.length;
+  while (footFrom > head.length && isRecord(rows[footFrom - 1]) && (rows[footFrom - 1] as Record<string, unknown>).footer === true) footFrom -= 1;
+  return { head, body: rows.slice(head.length, footFrom), foot: rows.slice(footFrom) };
+}
+
+/**
+ * The columns "Highlight this column" marks: the start column of each FIRST-row cell carrying
+ * `highlight` (spans counted). A renderer stamps `data-highlight` on every cell starting there.
+ */
+export function highlightedColumns(table: PortableTextTable): Set<number> {
+  return markedColumns(table, "highlight");
+}
+
+/** The columns "Visitors can sort columns" marks (a FIRST-row cell's `sortable`), as `highlightedColumns`. */
+export function sortableColumns(table: PortableTextTable): Set<number> {
+  return markedColumns(table, "sortable");
+}
+
+function markedColumns(table: PortableTextTable, flag: "highlight" | "sortable"): Set<number> {
+  const out = new Set<number>();
+  const first = Array.isArray(table.rows) ? table.rows[0] : undefined;
+  let at = 0;
+  for (const cell of isRecord(first) && Array.isArray(first.cells) ? first.cells : []) {
+    if (isRecord(cell) && cell[flag] === true) out.add(at);
+    at += isRecord(cell) && typeof cell.span === "number" && Number.isInteger(cell.span) && cell.span > 1 ? cell.span : 1;
+  }
+  return out;
+}
+
+/** A run of columns, or of body rows, that share one group; `label` is absent for an ungrouped run. */
+export type TableColumnRun = { width: number; key?: string; label?: string };
+export type TableRowRun = { rows: unknown[]; key?: string; label?: string };
+
+/**
+ * How a table's groups lay out, or two empty lists when it has none.
+ *
+ * Shared by both renderers (`@bettercms-ai/ui` draws the same runs), so they cannot disagree
+ * about where a group starts. A group key that names no group is ignored here rather than
+ * thrown on: the read is permissive, and the write refuses it by name (`tableProblems`).
+ *
+ * `columns` is empty unless some first-row cell names a known column group; `rows` is empty
+ * unless some body row names a known row group. `width` is the widest row, spans counted.
+ */
+export function tableGroupLayout(table: PortableTextTable): { columns: TableColumnRun[]; rows: TableRowRun[]; width: number } {
+  const rows: unknown[] = Array.isArray(table.rows) ? table.rows : [];
+  const labels = (list: unknown): Map<string, string> =>
+    new Map(
+      (Array.isArray(list) ? list : [])
+        .filter((g): g is Record<string, unknown> => isRecord(g) && typeof g._key === "string")
+        .map((g) => [g._key as string, typeof g.label === "string" ? g.label : ""]),
+    );
+  const cellsOf = (row: unknown): unknown[] => (isRecord(row) && Array.isArray(row.cells) ? row.cells : []);
+  const spanOf = (cell: unknown): number =>
+    isRecord(cell) && typeof cell.span === "number" && Number.isInteger(cell.span) && cell.span > 1 ? cell.span : 1;
+  const width = rows.reduce<number>((max, row) => Math.max(max, cellsOf(row).reduce<number>((n, c) => n + spanOf(c), 0)), 0);
+
+  const colLabels = labels(table.columnGroups);
+  const columns: TableColumnRun[] = [];
+  for (const cell of cellsOf(rows[0])) {
+    const key = isRecord(cell) && typeof cell.group === "string" && colLabels.has(cell.group) ? cell.group : undefined;
+    const last = columns[columns.length - 1];
+    if (last && last.key === key) last.width += spanOf(cell);
+    else columns.push({ width: spanOf(cell), ...(key === undefined ? {} : { key, label: colLabels.get(key) }) });
+  }
+
+  const rowLabels = labels(table.rowGroups);
+  // The body only: a footer (totals) run sits in `<tfoot>`, outside every row group.
+  const { body } = tableSections(table);
+  const runs: TableRowRun[] = [];
+  for (const row of body) {
+    const key = isRecord(row) && typeof row.group === "string" && rowLabels.has(row.group) ? row.group : undefined;
+    const last = runs[runs.length - 1];
+    if (last && last.key === key) last.rows.push(row);
+    else runs.push({ rows: [row], ...(key === undefined ? {} : { key, label: rowLabels.get(key) }) });
+  }
+
+  return {
+    columns: columns.some((r) => r.key !== undefined) ? columns : [],
+    rows: runs.some((r) => r.key !== undefined) ? runs : [],
+    width,
   };
 }

package/src/types.ts

@@ -102,6 +102,24 @@ export interface PortableTextTableCell {
    * would refuse the whole table over an attribute we simply forgot to carry.
    */
   rowSpan?: number;
+  /**
+   * The COLUMN GROUP this cell's column belongs to: a `_key` of the table's `columnGroups`.
+   *
+   * Read from the FIRST row only (the V2 table puts `group` on the column; this grid has no
+   * column object, so the column's first cell carries it). Living on a cell is what keeps it
+   * right when the editor inserts, deletes or moves a column: the cell moves with its column.
+   */
+  group?: string;
+  /**
+   * "Highlight this column" (the V2 table's `TableColumn.highlight`): named, like `group`, on the
+   * column's cell in the FIRST row only. Every cell of that column renders `data-highlight="true"`.
+   */
+  highlight?: boolean;
+  /**
+   * "Visitors can sort columns" (the V2 table's `TableColumn.sortable`): named on the column's FIRST-row cell, like
+   * `highlight`. Renders as the column's `<col data-sortable="true">`, as the V2 table writes it.
+   */
+  sortable?: boolean;
 }
 
 export interface PortableTextTableRow {
@@ -109,6 +127,24 @@ export interface PortableTextTableRow {
   cells: PortableTextTableCell[];
   /** The row sat in `<thead>`. Absent means `<tbody>`, which is what a parser assumes. */
   head?: boolean;
+  /** The ROW GROUP this body row belongs to: a `_key` of the table's `rowGroups`. */
+  group?: string;
+  /**
+   * A totals / summary row: the TRAILING run of these renders as `<tfoot>` (the V2 table's
+   * "Totals row", `TableRow.footer` in `@bettercms-ai/types` table-value.ts).
+   */
+  footer?: boolean;
+  /** "Highlight this row": `<tr data-highlight="true">`, as the V2 table renders it. */
+  highlight?: boolean;
+}
+
+/**
+ * A row or column group, the V2 table's `TableGroup` (`@bettercms-ai/types` table-value.ts), so
+ * both tables speak one language: a stable `_key` and the label a reader sees.
+ */
+export interface PortableTextTableGroup {
+  _key: string;
+  label: string;
 }
 
 /** A table. The ONE table BetterCMS has — see `PT_TYPES.table`. */
@@ -129,6 +165,48 @@ export interface PortableTextTable extends PortableTextObject {
    * authored or pasted since P1c carries neither the flag nor the class.
    */
   legacy?: boolean;
+  /**
+   * The four keys below are the V2 table's (`TableValue`), spelled the same way. All optional,
+   * and a table that has none of them renders byte for byte as it did before they existed.
+   */
+  /** What the table compares, written as `<caption>`. At most 300 characters. */
+  caption?: string;
+  /** A note under the table (`<p data-notes>`), plain text. At most 2,000 characters. */
+  notes?: string;
+  /** Body rows name one with `row.group`; each run of rows is its own `<tbody>` under a label row. */
+  rowGroups?: PortableTextTableGroup[];
+  /** First-row cells name one with `cell.group`; a run of columns gets one `scope="colgroup"` header. */
+  columnGroups?: PortableTextTableGroup[];
+  /**
+   * "Visitors can search rows" (the V2 table's `TableValue.filterable`): the table renders inside
+   * `<figure data-rt="table" data-filter="true">`, as the V2 table writes it.
+   */
+  filterable?: boolean;
+  /**
+   * "Help search engines read this as" (the V2 table's `TableValue.jsonLd`, the field-lane table's `jsonLd`): a
+   * comparison, a data report or a price list. Written on the figure as `data-jsonld="<type>"` (plus
+   * `data-jsonld-axis` / `data-jsonld-price`), as the V2 table writes it. `"none"` is not stored.
+   */
+  jsonLd?: PortableTextTableJsonLd;
+  /**
+   * "On phones" and "Keep column names in view" (the V2 table's `TableValue.design.responsive` / `.sticky`, the field-lane
+   * table's `design`). `responsive` is `stack` or `cards` (`scroll`, the default, is not stored, as V2 reads it); written
+   * on the figure as `data-responsive` / `data-sticky="true"`, as the V2 table writes them.
+   */
+  design?: PortableTextTableDesign;
+}
+
+/** The V2 table's `design` keys the rich-text table offers. */
+export interface PortableTextTableDesign {
+  responsive?: "stack" | "cards";
+  sticky?: boolean;
+}
+
+/** The V2 table's JSON-LD choice: `priceRow` is a row's `_key` (Offers), `axis` what an ItemList lists. */
+export interface PortableTextTableJsonLd {
+  type: "ItemList" | "Dataset" | "Offers";
+  axis?: "rows" | "columns";
+  priceRow?: string;
 }
 
 /**
@@ -157,6 +235,50 @@ export interface PortableTextFile extends PortableTextObject {
   mime?: string;
 }
 
+/**
+ * A pull quote: a quotation lifted out of the body, with who said it.
+ *
+ * 🔴 THE SHAPE IS THE V2 KIT'S, 1:1 — `PullQuoteModel` in the dashboard's
+ * `kit/controls/rich-text/article.ts`, which renders `<figure data-rt="pullquote">`. The kit
+ * writes these four fields and every renderer here draws them, so the names are spelled once.
+ *
+ * `link` is where the NAME links (and the blockquote's `cite`): a URL string, as the kit stores
+ * it, or a link object carrying `href` (the shape a `link` field value takes). Anything
+ * `safeHref` refuses renders the name unlinked rather than dropping it.
+ */
+export interface PortableTextPullQuote extends PortableTextObject {
+  _type: "pullQuote";
+  quote: string;
+  name: string;
+  role?: string;
+  link?: string | { href: string; [k: string]: unknown };
+}
+
+/** The href a pull quote's `link` carries — a string, or a link object's `href`. "" for none. */
+export function pullQuoteHref(link: unknown): string {
+  if (typeof link === "string") return link.trim();
+  if (link && typeof link === "object" && typeof (link as { href?: unknown }).href === "string") {
+    return ((link as { href: string }).href).trim();
+  }
+  return "";
+}
+
+/**
+ * Key takeaways: the story in a few points, set apart near the top of a body.
+ *
+ * 🔴 THE SHAPE IS THE V2 KIT'S, 1:1 — `TakeawaysModel` and `ARTICLE_SCHEMAS.takeaways` (`name:
+ * "keyTakeaways"`, fields `title` and `points`) in the kit's `controls/rich-text/article.ts`,
+ * which renders `<aside data-rt="takeaways">`. `title` is the label over the list ("Key
+ * takeaways" by default), ABSENT rather than empty when an author cleared it. `points` are plain
+ * strings, one per bullet; V2 holds at most 8 and a title of at most 40 characters
+ * (`PT_KEY_TAKEAWAYS_LIMITS`, key-takeaways.ts).
+ */
+export interface PortableTextKeyTakeaways extends PortableTextObject {
+  _type: "keyTakeaways";
+  title?: string;
+  points: string[];
+}
+
 export const isPortableTextBlock = (n: unknown): n is PortableTextBlock =>
   !!n && typeof n === "object" && (n as PortableTextNode)._type === "block";
 
@@ -204,6 +326,10 @@ export const PT_TYPES = {
   video: "video",
   /** A downloadable document — a PDF, a spec sheet. `<a href download>`, nothing more. */
   file: "file",
+  /** A pull quote — see `PortableTextPullQuote`. The V2 kit's `<figure data-rt="pullquote">`. */
+  pullQuote: "pullQuote",
+  /** Key takeaways — see `PortableTextKeyTakeaways`. The V2 kit's `<aside data-rt="takeaways">`. */
+  keyTakeaways: "keyTakeaways",
   /**
    * 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
@@ -259,6 +385,8 @@ export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
   PT_TYPES.mention,
   PT_TYPES.video,
   PT_TYPES.file,
+  PT_TYPES.pullQuote,
+  PT_TYPES.keyTakeaways,
 ]);
 
 /**
@@ -303,8 +431,15 @@ 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 is admitted by SHAPE, never by its `_type` alone — see `isStorableTable`.
-    const storable = type === PT_TYPES.table ? isStorableTable(node) : STORABLE_BLOCK_TYPES.has(type);
+    // A table, a pull quote and key takeaways are admitted by SHAPE, never by `_type` alone —
+    // see `isStorableTable`.
+    const storable = type === PT_TYPES.table
+      ? isStorableTable(node)
+      : type === PT_TYPES.pullQuote
+        ? isStorablePullQuote(node)
+        : type === PT_TYPES.keyTakeaways
+          ? isStorableKeyTakeaways(node)
+          : STORABLE_BLOCK_TYPES.has(type);
     if (storable) continue;
     const key = (node as PortableTextNode)._key;
     out.push({ _type: type, _key: typeof key === "string" ? key : "" });
@@ -347,6 +482,37 @@ export function isStorableTable(node: unknown): boolean {
   });
 }
 
+/**
+ * Is this `_type:"pullQuote"` one we can render?
+ *
+ * Same reason as the table: `pullQuote` is a name other producers use too, and a renderer that
+ * met `{_type:"pullQuote", text}` would draw an empty figure. `quote` and `name` are strings
+ * (either may be empty while an author is still typing); `role`, when present, is a string; and
+ * `link`, when present, is a string or an object carrying a string `href`.
+ */
+export function isStorablePullQuote(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  const v = node as Record<string, unknown>;
+  if (typeof v.quote !== "string" || typeof v.name !== "string") return false;
+  if (v.role !== undefined && typeof v.role !== "string") return false;
+  if (v.link === undefined || typeof v.link === "string") return true;
+  return !!v.link && typeof v.link === "object" && typeof (v.link as { href?: unknown }).href === "string";
+}
+
+/**
+ * Is this `_type:"keyTakeaways"` one we can render?
+ *
+ * Same reason as the table: the name alone is not a contract, and a renderer that met another
+ * producer's `{_type:"keyTakeaways", items}` would draw an empty aside. Ours carries `points`, an
+ * array. What is IN it, the title and the limits are judged by `keyTakeawaysProblems`
+ * (key-takeaways.ts), which names each problem with a code; this only decides whether the node is
+ * ours at all.
+ */
+export function isStorableKeyTakeaways(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  return Array.isArray((node as { points?: unknown }).points);
+}
+
 /**
  * @deprecated The marker a table-accepting field used to carry INSTEAD of a table.
  *