@bettercms-ai/richtext 0.9.0 → 0.10.0

package/package.json

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

@@ -8,7 +8,8 @@ import {
   type PortableTextTable,
 } from "./types";
 import { resolveVideoSource } from "./video";
-import { builtInTableToTable, tableGroupLayout } from "./table";
+import { builtInTableToTable, designOf, highlightedColumns, jsonLdOf, sortableColumns, tableGroupLayout, tableSections } from "./table";
+import { portableTextToPlainText } from "./plain";
 import { safeHref } from "./href";
 import { isStyledTag, styledAttrEntries } from "./styled";
 import { richTextImageLayout } from "./image-layout";
@@ -64,29 +65,65 @@ const isRecord = (v: unknown): v is Record<string, unknown> =>
 const attr = (name: string, value: unknown): string =>
   typeof value === "number" && Number.isInteger(value) && value > 1 ? ` ${name}="${value}"` : "";
 
+/** V2 schema/table.ts withTableRoles, verbatim: a stacked table's explicit ARIA roles. */
+function withTableRoles(html: string): string {
+  return html
+    .replace(/<table(?=[\s>])/, '<table role="table"')
+    .replace(/<(thead|tbody|tfoot)(?=[\s>])/g, '<$1 role="rowgroup"')
+    .replace(/<tr(?=[\s>])/g, '<tr role="row"')
+    .replace(/<th scope="(col|colgroup)"/g, '<th role="columnheader" scope="$1"')
+    .replace(/<th scope="(row|rowgroup)"/g, '<th role="rowheader" scope="$1"')
+    .replace(/<td(?=[\s>])/g, '<td role="cell"');
+}
+
 function tableHtml(table: PortableTextTable): string {
   const rows: unknown[] = Array.isArray(table.rows) ? table.rows : [];
   if (rows.length === 0) return "";
 
-  const cellHtml = (raw: unknown): string => {
+  // "Highlight this column": every cell starting in a marked column (V2 stamps each th/td of it).
+  const marked = highlightedColumns(table);
+  // "On phones" (stack / cards): each body cell names its column (`data-label`, V2 renderTableHtml), from the last head row
+  const design = designOf(table.design);
+  const stacked = design?.responsive === "stack" || design?.responsive === "cards";
+  const labels: string[] = [];
+  if (stacked) {
+    const head = tableSections(table).head;
+    const last = head[head.length - 1];
+    let at = 0;
+    for (const c of isRecord(last) && Array.isArray(last.cells) ? last.cells : []) {
+      const text = isRecord(c) ? portableTextToPlainText(c.content as PortableText).replace(/\s+/g, " ").trim() : "";
+      const w = isRecord(c) && typeof c.span === "number" && Number.isInteger(c.span) && c.span > 1 ? c.span : 1;
+      for (let i = 0; i < w; i += 1) labels[at + i] = text;
+      at += w;
+    }
+  }
+  const cellHtml = (raw: unknown, col: number): string => {
     const cell = isRecord(raw) ? raw : {};
     const tag = cell.header === true ? "th" : "td";
     // `colspan` before `rowspan`, the order every table in the corpus writes them in: the
     // comparison is on serialised markup, and a parser preserves the order it was given.
-    const attrs = `${attr("colspan", cell.span)}${attr("rowspan", cell.rowSpan)}`;
+    const label = stacked && tag === "td" ? ` data-label="${esc(labels[col] || `Column ${col + 1}`)}"` : "";
+    const attrs = `${attr("colspan", cell.span)}${attr("rowspan", cell.rowSpan)}${label}${marked.has(col) ? ' data-highlight="true"' : ""}`;
     return `<${tag}${attrs}>${portableTextToHtml(cell.content as PortableText, { inline: true })}</${tag}>`;
   };
   const rowHtml = (raw: unknown): string => {
     const cells = isRecord(raw) && Array.isArray(raw.cells) ? raw.cells : [];
-    return `<tr>${cells.map(cellHtml).join("")}</tr>`;
+    // "Highlight this row": the V2 table's own attribute (src/schema/table.ts rowHtml).
+    const highlight = isRecord(raw) && raw.highlight === true ? ' data-highlight="true"' : "";
+    let col = 0;
+    const html = cells.map((c) => {
+      const out = cellHtml(c, col);
+      col += isRecord(c) && typeof c.span === "number" && Number.isInteger(c.span) && c.span > 1 ? c.span : 1;
+      return out;
+    });
+    return `<tr${highlight}>${html.join("")}</tr>`;
   };
 
   // The LEADING RUN of head rows, not every row flagged one: `<thead>` is a section, and a
   // header row appearing after body rows cannot be lifted out of document order without moving
   // content the author placed.
-  const headCount = rows.findIndex((r) => !isRecord(r) || r.head !== true);
-  const head = rows.slice(0, headCount === -1 ? rows.length : headCount);
-  const body = rows.slice(head.length);
+  // Likewise the TRAILING run of footer (totals) rows is `<tfoot>`, after every `<tbody>` (V2).
+  const { head, body, foot } = tableSections(table);
   const layout = tableGroupLayout(table);
   // The platform's own class, on migrated values only — see `PortableTextTable["legacy"]`.
   const cls = table.legacy === true ? ' class="bcms-table"' : "";
@@ -96,7 +133,18 @@ function tableHtml(table: PortableTextTable): string {
 
   // Column groups: one `<colgroup>` per run of columns, and a `scope="colgroup"` header over each
   // grouped run, as the first row of `<thead>` (the V2 table's layout).
-  const colgroups = layout.columns.map((run) => `<colgroup${attr("span", run.width)}></colgroup>`).join("");
+  // "Visitors can sort columns": one `<col data-sortable="true">` per sortable column, as the V2 table writes it
+  // (src/schema/table.ts renderTableHtml); with `<col>`s a column group's `<colgroup>` holds them instead of a `span`.
+  const sortable = sortableColumns(table);
+  let colAt = 0;
+  const cols = (width: number): string => {
+    const out = Array.from({ length: width }, (_, i) => (sortable.has(colAt + i) ? '<col data-sortable="true">' : "<col>")).join("");
+    colAt += width;
+    return out;
+  };
+  const colgroups = sortable.size
+    ? (layout.columns.length ? layout.columns.map((run) => run.width) : [layout.width]).map((w) => `<colgroup>${cols(w)}</colgroup>`).join("")
+    : layout.columns.map((run) => `<colgroup${attr("span", run.width)}></colgroup>`).join("");
   const groupRow = layout.columns.length
     ? `<tr>${layout.columns
         .map((run) => (run.label === undefined ? "<td></td>".repeat(run.width) : `<th scope="colgroup"${attr("colspan", run.width)} data-group="${esc(run.key ?? "")}">${esc(run.label)}</th>`))
@@ -111,11 +159,22 @@ function tableHtml(table: PortableTextTable): string {
         .map((run) => `<tbody${run.key === undefined ? "" : ` data-key="${esc(run.key)}"`}>${run.label === undefined ? "" : `<tr><th scope="rowgroup"${attr("colspan", layout.width)}>${esc(run.label)}</th></tr>`}${run.rows.map(rowHtml).join("")}</tbody>`)
         .join("")
     : body.length ? `<tbody>${body.map(rowHtml).join("")}</tbody>` : "";
+  const tfoot = foot.length ? `<tfoot>${foot.map(rowHtml).join("")}</tfoot>` : "";
 
-  const html = `<table${cls}${notesId ? ` aria-describedby="${esc(notesId)}"` : ""}>${caption}${colgroups}${thead}${tbody}</table>`;
+  const plainHtml = `<table${cls}${notesId ? ` aria-describedby="${esc(notesId)}"` : ""}>${caption}${colgroups}${thead}${tbody}${tfoot}</table>`;
   // A note sits UNDER the table, so it needs a container to stay with it: the V2 kit's
   // `<figure data-rt="table">`, which the ingest reads back.
-  return notes ? `<figure data-rt="table">${html}<p data-notes${notesId ? ` id="${esc(notesId)}"` : ""}>${esc(notes)}</p></figure>` : html;
+  // "Visitors can search rows" is the figure's `data-filter="true"` (V2 renderTableHtml), so it takes the figure too.
+  const filter = table.filterable === true ? ' data-filter="true"' : "";
+  // "Help search engines read this as": V2 renderTableHtml's data-jsonld (+ axis, price row) on the figure, after data-filter
+  const j = jsonLdOf(table.jsonLd);
+  const jsonLd = j ? ` data-jsonld="${j.type}"${j.axis ? ` data-jsonld-axis="${j.axis}"` : ""}${j.priceRow ? ` data-jsonld-price="${esc(j.priceRow)}"` : ""}` : "";
+  // "On phones" / "Keep column names in view": V2 renderTableHtml's data-responsive / data-sticky, before data-filter; a
+  // stacked table takes V2's withTableRoles (explicit ARIA roles, since display:block drops the implicit ones)
+  const designAttrs = design ? `${design.responsive ? ` data-responsive="${design.responsive}"` : ""}${design.sticky ? ' data-sticky="true"' : ""}` : "";
+  const html = stacked ? withTableRoles(plainHtml) : plainHtml;
+  if (!notes && !filter && !jsonLd && !designAttrs) return html;
+  return `<figure data-rt="table"${designAttrs}${filter}${jsonLd}>${html}${notes ? `<p data-notes${notesId ? ` id="${esc(notesId)}"` : ""}>${esc(notes)}</p>` : ""}</figure>`;
 }
 
 /**

package/src/ingest.ts

@@ -13,7 +13,7 @@ import {
 import { randomKey, isValidKey, type KeyGenerator } from "./key";
 import { safeHref } from "./href";
 import { BARE_IS_DESIGN, isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
-import { PT_TABLE_LIMITS } from "./table";
+import { designOf, jsonLdOf, PT_TABLE_LIMITS } from "./table";
 import { PT_KEY_TAKEAWAYS_LIMITS } from "./key-takeaways";
 import type { PtSchema } from "./schema";
 
@@ -150,7 +150,7 @@ const cellsOf = (row: Element): Element[] =>
   [...row.querySelectorAll("th,td")].filter((c) => c.closest("tr") === row);
 
 /** A span attribute, recorded and not honoured — see `PortableTextTableCell`. */
-const spanOf = (cell: Element, name: "colspan" | "rowspan"): number | undefined => {
+const spanOf = (cell: Element, name: "colspan" | "rowspan" | "span"): number | undefined => {
   const n = Number(cell.getAttribute(name));
   return Number.isInteger(n) && n > 1 ? n : undefined;
 };
@@ -208,6 +208,18 @@ const groupKey = (value: string | null | undefined, key: KeyGenerator, taken: Se
  */
 function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: string) => PortableText): PortableTextTable | undefined {
   const all = rowsOf(el);
+  // The columns a `<col data-sortable="true">` marks: a `<colgroup>` without `<col>`s spans its `span` columns.
+  const sortableCols = new Set<number>();
+  let colAt = 0;
+  for (const group of [...el.children].filter((c) => isTag(c, "colgroup"))) {
+    const cols = [...group.children].filter((c) => isTag(c, "col"));
+    if (!cols.length) colAt += spanOf(group, "span") ?? 1;
+    for (const col of cols) {
+      const width = spanOf(col, "span") ?? 1;
+      if (col.getAttribute("data-sortable") === "true") for (let i = 0; i < width; i += 1) sortableCols.add(colAt + i);
+      colAt += width;
+    }
+  }
   const groupRow = all.find(isColumnGroupRow);
   const taken = new Set<string>();
 
@@ -261,10 +273,17 @@ function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: str
         ...(spanOf(cell, "colspan") === undefined ? {} : { span: spanOf(cell, "colspan") }),
         ...(spanOf(cell, "rowspan") === undefined ? {} : { rowSpan: spanOf(cell, "rowspan") }),
         ...(group === undefined ? {} : { group }),
+        // "Highlight this column" is named on the column's first-row cell, as `group` is.
+        ...(first && cell.getAttribute("data-highlight") === "true" ? { highlight: true } : {}),
+        // "Visitors can sort columns": the column's `<col data-sortable="true">` (V2 renderTableHtml)
+        ...(first && sortableCols.has(start) ? { sortable: true } : {}),
       };
     });
     if (cells.length === 0) continue;
     const head = isTag(row.parentElement, "thead");
+    // `<tfoot>` is the V2 table's "Totals row", `data-highlight` its "Highlight this row".
+    const footer = !head && isTag(row.parentElement, "tfoot");
+    const highlight = row.getAttribute("data-highlight") === "true";
     rows.push({
       _key: rowKey,
       cells,
@@ -272,7 +291,9 @@ function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: str
       // and never a `<thead>`, so inventing one at render time would make every bare
       // `<tr><th>` table diverge from its own stored markup.
       ...(head ? { head: true } : {}),
-      ...(current && !head ? { group: current.key } : {}),
+      ...(current && !head && !footer ? { group: current.key } : {}),
+      ...(footer ? { footer: true } : {}),
+      ...(highlight ? { highlight: true } : {}),
     });
   }
   if (rows.length === 0) return undefined;
@@ -306,6 +327,13 @@ function tableRule(key: KeyGenerator, ingestCell: (html: string) => PortableText
   };
 }
 
+/** The figure's `data-jsonld` (+ axis, price row) as the table's `jsonLd`, or nothing. */
+function jsonLdIn(el: Element, rowKeys: string[]): { jsonLd?: PortableTextTable["jsonLd"] } {
+  const price = el.getAttribute("data-jsonld-price");
+  const j = jsonLdOf({ type: el.getAttribute("data-jsonld"), axis: el.getAttribute("data-jsonld-axis") ?? undefined, ...(price && rowKeys.includes(price) ? { priceRow: price } : {}) });
+  return j ? { jsonLd: j } : {};
+}
+
 /**
  * `<figure data-rt="table">` → the table, with the note under it: the V2 kit's table island
  * (src/schema/table.ts renderTableHtml) and what `portableTextToHtml` writes for a table with
@@ -326,7 +354,16 @@ function tableFigureRule(key: KeyGenerator, ingestCell: (html: string) => Portab
       // read back as a space and the value would not survive its own round trip.
       const notes = clip([wordsOf(noteEl), ...footnotes].filter(Boolean).join(" "), PT_TABLE_LIMITS.notesChars);
       const own = [el.getAttribute("data-id"), noteEl?.getAttribute("id")?.replace(/-notes$/, "")].find((k) => isValidKey(k));
-      return createBlock({ ...table, ...(own ? { _key: own } : {}), ...(notes ? { notes } : {}) });
+      return createBlock({ ...table, ...(own ? { _key: own } : {}), ...(notes ? { notes } : {}), ...(el.getAttribute("data-filter") === "true" ? { filterable: true } : {}),
+        // "Help search engines read this as" (V2 parseTableElement: dataset.jsonld, jsonldAxis, jsonldPrice). The price row
+        // is kept only when it names a row read here: this renderer writes no row keys, so a round trip falls back to
+        // V2's own default (the first row of prices), never to a key that names nothing.
+        ...jsonLdIn(el, table.rows.map((r) => r._key)),
+        // "On phones" / "Keep column names in view" (V2 parseTableElement: dataset.responsive stack|cards, dataset.sticky)
+        ...(designOf({ responsive: el.getAttribute("data-responsive"), sticky: el.getAttribute("data-sticky") === "true" })
+          ? { design: designOf({ responsive: el.getAttribute("data-responsive"), sticky: el.getAttribute("data-sticky") === "true" }) }
+          : {}),
+      });
     },
   };
 }

package/src/table.ts

@@ -5,6 +5,8 @@ import {
   type PortableTextTable,
   type PortableTextTableCell,
   type PortableTextTableGroup,
+  type PortableTextTableDesign,
+  type PortableTextTableJsonLd,
   type PortableTextTableRow,
 } from "./types";
 import { deterministicKeys, isValidKey, randomKey, type KeyGenerator } from "./key";
@@ -145,6 +147,8 @@ function normalizeCell(raw: unknown, at: [number, number], mint: Mint, read: Cel
     ...(span === undefined ? {} : { span }),
     ...(rowSpan === undefined ? {} : { rowSpan }),
     ...(typeof raw.group === "string" ? { group: raw.group } : {}),
+    ...(raw.highlight === true ? { highlight: true } : {}),
+    ...(raw.sortable === true ? { sortable: true } : {}),
   };
 }
 
@@ -157,6 +161,9 @@ function normalizeRow(raw: unknown, at: number, mint: Mint, read: CellContentRea
     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 } : {}),
   };
 }
 
@@ -255,6 +262,37 @@ function tableExtras(node: Record<string, unknown>): Partial<PortableTextTable>
     ...(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 } : {}),
   };
 }
 
@@ -290,6 +328,29 @@ export function tableProblems(node: unknown): PortableTextTableProblem[] {
   };
   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>();
@@ -315,6 +376,10 @@ export function tableProblems(node: unknown): PortableTextTableProblem[] {
   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)) {
@@ -322,6 +387,12 @@ export function tableProblems(node: unknown): PortableTextTableProblem[] {
       }
     }
     (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");
@@ -355,6 +426,47 @@ export function portableTextTableProblems(value: unknown): Array<PortableTextTab
   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 };
@@ -392,8 +504,8 @@ export function tableGroupLayout(table: PortableTextTable): { columns: TableColu
   }
 
   const rowLabels = labels(table.rowGroups);
-  const headCount = rows.findIndex((r) => !isRecord(r) || r.head !== true);
-  const body = headCount === -1 ? [] : rows.slice(headCount);
+  // 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;

package/src/types.ts

@@ -110,6 +110,16 @@ export interface PortableTextTableCell {
    * 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 {
@@ -119,6 +129,13 @@ export interface PortableTextTableRow {
   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;
 }
 
 /**
@@ -160,6 +177,36 @@ export interface PortableTextTable extends PortableTextObject {
   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;
 }
 
 /**