@bettercms-ai/richtext 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.9.0",
+  "version": "0.11.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, footnoteNumbers, footnotesOf, highlightedColumns, isTypedTable, jsonLdOf, sortableColumns, tableColumns, tableGroupLayout, tableSections, typedCellView } from "./table";
+import { portableTextToPlainText } from "./plain";
 import { safeHref } from "./href";
 import { isStyledTag, styledAttrEntries } from "./styled";
 import { richTextImageLayout } from "./image-layout";
@@ -64,39 +65,118 @@ 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;
+    }
+  }
+  // The V2 table's typed columns (a first-row cell's `column`): a table with one renders V2's typed markup (cellHtml).
+  const columns = tableColumns(table);
+  const typed = isTypedTable(table);
+  const headRows = new Set(tableSections(table).head);
+  const fnNumber = footnoteNumbers(table);
+  const footnotes = footnotesOf(table.footnotes) ?? [];
+  const tableId = typeof table._key === "string" && table._key ? table._key : "tbl";
+  const cellHtml = (raw: unknown, col: number, row: unknown): 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)}`;
-    return `<${tag}${attrs}>${portableTextToHtml(cell.content as PortableText, { inline: true })}</${tag}>`;
+    const label = stacked && tag === "td" ? ` data-label="${esc(labels[col] || `Column ${col + 1}`)}"` : "";
+    // A footnote: V2 renderTableHtml's data-note (after the value, before data-align) and its numbered marker after the
+    // cell's words (V2 cellHtml `inner + sup`)
+    const n = typeof cell.note === "string" ? fnNumber.get(cell.note) : undefined;
+    const sup = n ? `<sup><a href="#${esc(tableId)}-fn-${n}" aria-label="Note ${n}">${n}</a></sup>` : "";
+    const content = portableTextToHtml(cell.content as PortableText, { inline: true });
+    if (!typed) return `<${tag}${attr("colspan", cell.span)}${attr("rowspan", cell.rowSpan)}${label}${marked.has(col) ? ' data-highlight="true"' : ""}${n ? ` data-note="${esc(cell.note as string)}"` : ""}>${content}${sup}</${tag}>`;
+    const view = typedCellView(columns[col], row, cell, headRows.has(row));
+    const tail: [string, string][] = n ? [...view.tail.filter(([k]) => k !== "data-align"), ["data-note", cell.note as string], ...view.tail.filter(([k]) => k === "data-align")] : view.tail;
+    const out = (list: [string, string][]) => list.map(([k, v]) => ` ${k}="${esc(v)}"`).join("");
+    return `<${tag}${attr("colspan", cell.span)}${attr("rowspan", cell.rowSpan)}${out(view.lead)}${label}${marked.has(col) ? ' data-highlight="true"' : ""}${out(tail)}>${view.inner ?? content}${sup}</${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), after the row's type (data-type).
+    const type = isRecord(raw) && typeof raw.type === "string" ? ` data-type="${esc(raw.type)}"` : "";
+    const highlight = isRecord(raw) && raw.highlight === true ? ' data-highlight="true"' : "";
+    let col = 0;
+    const html = cells.map((c) => {
+      const out = cellHtml(c, col, raw);
+      col += isRecord(c) && typeof c.span === "number" && Number.isInteger(c.span) && c.span > 1 ? c.span : 1;
+      return out;
+    });
+    return `<tr${type}${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"' : "";
   const notes = typeof table.notes === "string" ? table.notes.trim() : "";
-  const notesId = notes && typeof table._key === "string" && table._key ? `${table._key}-notes` : "";
+  const notesId = (notes || footnotes.length) && typeof table._key === "string" && table._key ? `${table._key}-notes` : "";
   const caption = typeof table.caption === "string" && table.caption.trim() ? `<caption>${esc(table.caption.trim())}</caption>` : "";
 
   // 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) => `<col${colAttrs(colAt + i)}>`).join("");
+    colAt += width;
+    return out;
+  };
+  // A typed column's `<col>`: V2 renderTableHtml's attributes in its order (schema/table.ts:511-526), data-sortable among them
+  const colAttrs = (i: number): string => {
+    const c = columns[i];
+    const a = c
+      ? [
+          ` data-type="${c.type ?? "text"}"`,
+          c.unit ? ` data-unit="${esc(c.unit)}"` : "",
+          c.currency ? ` data-currency="${esc(c.currency)}"` : "",
+          c.decimals != null ? ` data-decimals="${c.decimals}"` : "",
+          c.align ? ` data-align="${c.align}"` : "",
+        ]
+      : [];
+    a.push(sortable.has(i) ? ' data-sortable="true"' : "");
+    if (c) a.push(c.trueLabel ? ` data-true="${esc(c.trueLabel)}"` : "", c.falseLabel ? ` data-false="${esc(c.falseLabel)}"` : "", c.max != null ? ` data-max="${c.max}"` : "", c.description ? ` data-description="${esc(c.description)}"` : "");
+    return a.join("");
+  };
+  const colgroups = sortable.size || columns.some(Boolean)
+    ? (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 +191,29 @@ 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 && !footnotes.length) return html;
+  // Footnotes: V2 renderTableHtml's notes block, `<div class="bt-notes" id="<key>-notes">` holding the note and the
+  // `<ol data-footnotes>`, each `<li id="<key>-fn-<n>" data-key>`. A note with no footnotes keeps the one `<p>` it had.
+  const under = footnotes.length
+    ? `<div class="bt-notes" id="${esc(tableId)}-notes">${notes ? `<p data-notes>${esc(notes)}</p>` : ""}<ol data-footnotes>${footnotes
+        .map((f, i) => `<li id="${esc(tableId)}-fn-${i + 1}" data-key="${esc(f._key)}">${esc(f.text)}</li>`)
+        .join("")}</ol></div>`
+    : notes ? `<p data-notes${notesId ? ` id="${esc(notesId)}"` : ""}>${esc(notes)}</p>` : "";
+  return `<figure data-rt="table"${designAttrs}${filter}${jsonLd}>${html}${under}</figure>`;
 }
 
 /**

package/src/ingest.ts

@@ -7,13 +7,15 @@ import {
   type PortableText,
   type PortableTextBlock,
   type PortableTextTable,
+  type PortableTextTableColumn,
+  type PortableTextTableColumnType,
   type PortableTextTableGroup,
   type PortableTextTableRow,
 } from "./types";
 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 { cellTypeOf, columnOf, designOf, isColumnType, isValueType, jsonLdOf, PT_TABLE_LIMITS, typedCellText } from "./table";
 import { PT_KEY_TAKEAWAYS_LIMITS } from "./key-takeaways";
 import type { PtSchema } from "./schema";
 
@@ -150,12 +152,13 @@ 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;
 };
 
 /** An element's words, whitespace collapsed. */
+const escText = (s: string): string => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 const wordsOf = (el: Element | null | undefined): string => (el?.textContent ?? "").replace(/\s+/g, " ").trim();
 
 const scopeOf = (cell: Element): string => (cell.getAttribute("scope") ?? "").toLowerCase();
@@ -208,6 +211,24 @@ 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>();
+  // A typed column's `<col data-type …>` (V2 renderTableHtml) → the column, as V2 parseTableElement reads it.
+  const typedCols = new Map<number, PortableTextTableColumn>();
+  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);
+      const d = (name: string) => col.getAttribute(`data-${name}`) ?? undefined;
+      const num = (name: string) => (d(name) === undefined ? undefined : Number(d(name)));
+      const typed = d("type") === undefined ? undefined : columnOf({ type: d("type"), unit: d("unit"), currency: d("currency"), decimals: num("decimals"), align: d("align"), trueLabel: d("true"), falseLabel: d("false"), max: num("max"), description: d("description") });
+      if (typed) for (let i = 0; i < width; i += 1) typedCols.set(colAt + i, typed);
+      colAt += width;
+    }
+  }
   const groupRow = all.find(isColumnGroupRow);
   const taken = new Set<string>();
 
@@ -246,14 +267,35 @@ function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: str
     const first = rows.length === 0;
     // Minted BEFORE the cells, as it always was: a deterministic key sequence is a contract.
     const rowKey = key();
+    // The V2 table's per-row type (`<tr data-type>`)
+    const rowType = isColumnType(row.getAttribute("data-type")) ? (row.getAttribute("data-type") as PortableTextTableColumnType) : undefined;
+    const inHead = isTag(row.parentElement, "thead");
     let at = 0;
     const cells = cellsOf(row).map((cell) => {
       const start = at;
       at += spanOf(cell, "colspan") ?? 1;
       const group = first ? ranges.find((r) => start >= r.from && start < r.to)?.key : undefined;
+      // A footnote marker (V2: `<sup><a href="#<key>-fn-<n>">`) is the cell's note, not its words: taken out, and the note
+      // kept as the cell's `data-note`, else as `#<n>` for the figure to resolve against its footnotes (`resolveNotes`).
+      const own = cell.cloneNode(true) as Element;
+      let mark: string | undefined;
+      for (const sup of [...own.querySelectorAll("sup")]) {
+        const n = /-fn-(\d+)$/.exec(sup.querySelector("a")?.getAttribute("href") ?? "")?.[1];
+        if (!n) continue;
+        mark ??= `#${n}`;
+        sup.remove();
+      }
+      const note = cell.getAttribute("data-note") || mark;
+      // A typed cell (V2 cellHtml): its per-cell type, its value (`data-value`), its words as content; `data-empty` is no words.
+      const column = typedCols.get(start);
+      const ownType = isColumnType(cell.getAttribute("data-type")) ? (cell.getAttribute("data-type") as PortableTextTableColumnType) : undefined;
+      const type = cellTypeOf(column, { type: rowType }, { type: ownType });
+      const raw = cell.getAttribute("data-value");
+      const value = inHead || raw === null || !isValueType(type) ? undefined : type === "boolean" ? raw === "true" : Number.isFinite(Number(raw)) && raw.trim() !== "" ? Number(raw) : undefined;
+      const empty = !inHead && cell.hasAttribute("data-empty");
       return {
         _key: key(),
-        content: ingestCell(cell.innerHTML),
+        content: empty ? [] : value !== undefined ? ingestCell(escText(typedCellText(column, type, value))) : ingestCell(own.innerHTML),
         // A header is what the markup SAYS it is, cell by cell. Deriving it from position
         // would promote the first data row of a headerless table, and would lose the row
         // headers that live in a table's first COLUMN.
@@ -261,10 +303,21 @@ 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 } : {}),
+        ...(first && column ? { column } : {}),
+        ...(ownType && !inHead ? { type: ownType } : {}),
+        ...(value === undefined ? {} : { value }),
+        ...(note ? { note } : {}),
       };
     });
     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 +325,10 @@ 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 } : {}),
+      ...(rowType ? { type: rowType } : {}),
     });
   }
   if (rows.length === 0) return undefined;
@@ -293,6 +349,32 @@ function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: str
   };
 }
 
+/**
+ * A cell's note against the table's footnotes: a `data-note` key kept when it names one, a `#<n>` marker resolved to the
+ * n-th footnote's key, anything else dropped (a note must name a footnote; a bare table has none).
+ */
+function resolveNotes(table: PortableTextTable, footnotes: { _key: string }[]): PortableTextTable {
+  const keys = new Set(footnotes.map((f) => f._key));
+  const resolve = (note: string | undefined): string | undefined => {
+    if (!note) return undefined;
+    const n = /^#(\d+)$/.exec(note)?.[1];
+    const k = n ? footnotes[Number(n) - 1]?._key : note;
+    return k && keys.has(k) ? k : undefined;
+  };
+  return {
+    ...table,
+    rows: table.rows.map((r) => ({
+      ...r,
+      cells: r.cells.map((c) => {
+        if (c.note === undefined) return c;
+        const { note, ...rest } = c;
+        const k = resolve(note);
+        return k ? { ...rest, note: k } : rest;
+      }),
+    })),
+  };
+}
+
 function tableRule(key: KeyGenerator, ingestCell: (html: string) => PortableText): DeserializerRule {
   return {
     deserialize(el: Node, _next, createBlock) {
@@ -301,11 +383,18 @@ function tableRule(key: KeyGenerator, ingestCell: (html: string) => PortableText
       // `createBlock` is what marks this BLOCK-level. Returning the object bare makes the
       // deserialiser treat it as inline and wrap it in a paragraph — the table survives, nested
       // one level down where no renderer looks for it.
-      return table ? createBlock(table) : undefined;
+      return table ? createBlock(resolveNotes(table, [])) : undefined;
     },
   };
 }
 
+/** 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
@@ -321,12 +410,27 @@ function tableFigureRule(key: KeyGenerator, ingestCell: (html: string) => Portab
       const table = inner ? readTableElement(inner, key, ingestCell) : undefined;
       if (!table) return undefined;
       const noteEl = el.querySelector("[data-notes]");
-      const footnotes = [...el.querySelectorAll("[data-footnotes] li")].map((li, i) => `[${i + 1}] ${wordsOf(li)}`);
-      // Joined with a space, not a line break: the note renders as one `<p>`, so a break would
-      // 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 } : {}) });
+      // Footnotes (V2 `<ol data-footnotes>`): kept as footnotes, each with its `data-key` (else a minted one).
+      const taken = new Set<string>();
+      const footnotes = [...el.querySelectorAll("[data-footnotes] li")].map((li) => {
+        const k = li.getAttribute("data-key");
+        const _key = k && k.length <= PT_TABLE_LIMITS.keyChars && !taken.has(k) ? k : key();
+        taken.add(_key);
+        return { _key, text: clip(wordsOf(li), PT_TABLE_LIMITS.notesChars) };
+      });
+      const notes = clip(wordsOf(noteEl), PT_TABLE_LIMITS.notesChars);
+      const notesBox = noteEl?.closest(".bt-notes") ?? el.querySelector(".bt-notes");
+      const own = [el.getAttribute("data-id"), (notesBox?.getAttribute("id") ?? noteEl?.getAttribute("id"))?.replace(/-notes$/, "")].find((k) => isValidKey(k));
+      return createBlock({ ...resolveNotes(table, footnotes), ...(own ? { _key: own } : {}), ...(notes ? { notes } : {}), ...(footnotes.length ? { footnotes } : {}), ...(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/plain.ts

@@ -94,9 +94,12 @@ const tableLines = (table: PortableTextTable): string[] => {
     ...head.map(rowLine),
     ...layout.rows.flatMap((run) => [...(run.label === undefined ? [] : [one(run.label)]), ...(run.rows as typeof rows).map(rowLine)]),
     one(table.notes),
+    // footnotes, numbered as the html numbers them (V2 tableSearchText reads them too)
+    ...(Array.isArray(table.footnotes) ? table.footnotes : []).map((f, i) => one(`[${i + 1}] ${typeof f?.text === "string" ? f.text : ""}`)),
   ];
   // Only the NEW lines are dropped when empty: an empty row has always contributed its "" line.
-  const extras = new Set([0, 1, lines.length - 1]);
+  const fnCount = Array.isArray(table.footnotes) ? table.footnotes.length : 0;
+  const extras = new Set([0, 1, lines.length - 1 - fnCount]);
   return lines.filter((l, i) => l !== "" || !extras.has(i));
 };
 

package/src/table.ts

@@ -1,10 +1,16 @@
 import {
   BUILTIN_TABLE_KEY,
+  PT_TABLE_COLUMN_TYPES,
   PT_TYPES,
   type PortableText,
   type PortableTextTable,
   type PortableTextTableCell,
+  type PortableTextTableColumn,
+  type PortableTextTableColumnType,
   type PortableTextTableGroup,
+  type PortableTextTableDesign,
+  type PortableTextTableFootnote,
+  type PortableTextTableJsonLd,
   type PortableTextTableRow,
 } from "./types";
 import { deterministicKeys, isValidKey, randomKey, type KeyGenerator } from "./key";
@@ -145,6 +151,13 @@ 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 } : {}),
+    // The V2 table's typed cells: the column (first-row cell), the per-cell type, the typed value.
+    ...(columnOf(raw.column) ? { column: columnOf(raw.column) } : {}),
+    ...(isColumnType(raw.type) ? { type: raw.type } : {}),
+    ...(typeof raw.value === "boolean" || (typeof raw.value === "number" && Number.isFinite(raw.value)) ? { value: raw.value } : {}),
+    ...(typeof raw.note === "string" && raw.note ? { note: raw.note } : {}),
   };
 }
 
@@ -157,6 +170,10 @@ 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 } : {}),
+    ...(isRecord(raw) && isColumnType(raw.type) ? { type: raw.type } : {}),
   };
 }
 
@@ -255,6 +272,52 @@ 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) } : {}),
+    ...(footnotesOf(node.footnotes) ? { footnotes: footnotesOf(node.footnotes) } : {}),
+  };
+}
+
+/** Stored footnotes read permissively: entries with a string `_key`, their text ("" when missing); none is nothing. */
+export function footnotesOf(v: unknown): PortableTextTableFootnote[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  const out = v
+    .filter((f): f is Record<string, unknown> => isRecord(f) && typeof f._key === "string" && f._key !== "")
+    .map((f) => ({ _key: f._key as string, text: typeof f.text === "string" ? f.text : "" }));
+  return out.length ? out : undefined;
+}
+
+/** footnote `_key` → its number (1-based, in order), as V2's footnoteIndex. */
+export function footnoteNumbers(table: PortableTextTable): Map<string, number> {
+  return new Map((footnotesOf(table.footnotes) ?? []).map((f, i) => [f._key, i + 1]));
+}
+
+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 +353,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>();
@@ -311,10 +397,32 @@ export function tableProblems(node: unknown): PortableTextTableProblem[] {
   };
   const rowGroups = keyed(node.rowGroups, "rowGroups");
   const columnGroups = keyed(node.columnGroups, "columnGroups");
+  // Footnotes: [{ _key, text }], the field-lane table's (`text` held to the note's limit)
+  const footnoteKeys = new Set<string>();
+  if (node.footnotes !== undefined) {
+    if (!Array.isArray(node.footnotes)) bad(["footnotes"], "footnotes must be an array of { _key, text }");
+    else
+      node.footnotes.forEach((f, i) => {
+        if (!isRecord(f)) return bad(["footnotes", i], `footnotes[${i}] must be an object { _key, text }`);
+        for (const k of Object.keys(f)) if (k !== "_key" && k !== "text") bad(["footnotes", i, k], `unknown key "${k}" (_key, text)`);
+        if (typeof f._key !== "string" || f._key === "" || f._key.length > PT_TABLE_LIMITS.keyChars) bad(["footnotes", i, "_key"], `needs a _key string of 1 to ${PT_TABLE_LIMITS.keyChars} characters`);
+        else if (footnoteKeys.has(f._key)) bad(["footnotes", i, "_key"], `_key "${f._key}" is used twice`);
+        else footnoteKeys.add(f._key);
+        text(f.text, ["footnotes", i, "text"], "text", PT_TABLE_LIMITS.notesChars, true);
+      });
+  }
 
   const rows = Array.isArray(node.rows) ? node.rows : [];
+  // The columns' types, by cell index, as the first row names them (a typed value is judged against its column).
+  const firstCells = isRecord(rows[0]) && Array.isArray(rows[0].cells) ? (rows[0].cells as unknown[]) : [];
+  const columns = firstCells.map((c) => (isRecord(c) ? columnOf(c.column) : undefined));
   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.type !== undefined && !isColumnType(row.type)) bad(["rows", r, "type"], `type must be one of ${PT_TABLE_COLUMN_TYPES.join(", ")}`);
     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 +430,16 @@ export function tableProblems(node: unknown): PortableTextTableProblem[] {
       }
     }
     (Array.isArray(row.cells) ? row.cells : []).forEach((cell, c) => {
+      if (isRecord(cell)) for (const p of typedCellProblems(cell, row, r, c, columns[c])) bad(p.path, p.message);
+      if (isRecord(cell) && cell.note !== undefined && (typeof cell.note !== "string" || !footnoteKeys.has(cell.note))) {
+        bad(["rows", r, "cells", c, "note"], `note "${String(cell.note)}" is not a key of footnotes`);
+      }
+      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 +473,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 +551,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;
@@ -408,3 +567,223 @@ export function tableGroupLayout(table: PortableTextTable): { columns: TableColu
     width,
   };
 }
+
+/* ── Typed cells (the V2 table's column types, src/schema/table.ts) ─────────────────────── */
+
+const COLUMN_KEYS = new Set(["type", "description", "unit", "currency", "decimals", "align", "trueLabel", "falseLabel", "max"]);
+const NUMERIC_TYPES = new Set<string>(["number", "money", "rating"]);
+
+export const isColumnType = (v: unknown): v is PortableTextTableColumnType => (PT_TABLE_COLUMN_TYPES as readonly unknown[]).includes(v);
+
+/** A stored `column` read permissively: each V2 key kept when well formed, a type this table offers; nothing left is nothing. */
+export function columnOf(v: unknown): PortableTextTableColumn | undefined {
+  if (!isRecord(v)) return undefined;
+  const str = (x: unknown) => (typeof x === "string" && x !== "" ? x : undefined);
+  const int = (x: unknown, lo: number, hi: number) => (Number.isInteger(x) && (x as number) >= lo && (x as number) <= hi ? (x as number) : undefined);
+  const c: PortableTextTableColumn = {
+    ...(isColumnType(v.type) ? { type: v.type } : {}),
+    ...(str(v.description) ? { description: str(v.description) } : {}),
+    ...(str(v.unit) ? { unit: str(v.unit) } : {}),
+    ...(typeof v.currency === "string" && /^[A-Z]{3}$/.test(v.currency) ? { currency: v.currency } : {}),
+    ...(int(v.decimals, 0, 10) !== undefined ? { decimals: int(v.decimals, 0, 10) } : {}),
+    ...(v.align === "start" || v.align === "center" || v.align === "end" ? { align: v.align } : {}),
+    ...(str(v.trueLabel) ? { trueLabel: str(v.trueLabel) } : {}),
+    ...(str(v.falseLabel) ? { falseLabel: str(v.falseLabel) } : {}),
+    ...(int(v.max, 1, 10) !== undefined ? { max: int(v.max, 1, 10) } : {}),
+  };
+  return Object.keys(c).length ? c : undefined;
+}
+
+/** Each column's `column`, by column index (spans counted), from the FIRST-row cells. */
+export function tableColumns(table: PortableTextTable): (PortableTextTableColumn | undefined)[] {
+  const out: (PortableTextTableColumn | undefined)[] = [];
+  const first = Array.isArray(table.rows) ? table.rows[0] : undefined;
+  for (const cell of isRecord(first) && Array.isArray(first.cells) ? first.cells : []) {
+    const w = isRecord(cell) && typeof cell.span === "number" && Number.isInteger(cell.span) && cell.span > 1 ? cell.span : 1;
+    const col = isRecord(cell) ? columnOf(cell.column) : undefined;
+    for (let i = 0; i < w; i += 1) out.push(col);
+  }
+  return out;
+}
+
+/**
+ * A table that draws V2's typed markup: its first row names a `column`, or a row or cell carries a type or a value (a "Write
+ * words instead" cell in a link column is typed even when no column is).
+ */
+export function isTypedTable(table: PortableTextTable): boolean {
+  if (tableColumns(table).some(Boolean)) return true;
+  return (Array.isArray(table.rows) ? (table.rows as unknown[]) : []).some(
+    (r) => isRecord(r) && (r.type !== undefined || (Array.isArray(r.cells) && r.cells.some((c: unknown) => isRecord(c) && (c.type !== undefined || c.value !== undefined)))),
+  );
+}
+
+/** V2 `cellType`: the cell's own type, else the row's, else the column's (text when none says). */
+export const cellTypeOf = (col: PortableTextTableColumn | undefined, row: unknown, cell: unknown): PortableTextTableColumnType =>
+  (isRecord(cell) && isColumnType(cell.type) ? cell.type : undefined) ?? (isRecord(row) && isColumnType(row.type) ? row.type : undefined) ?? col?.type ?? "text";
+
+/** V2 `alignOf` (schema/table.ts:365): numbers, money and ratings align end unless the column says otherwise. */
+export const columnAlign = (col: PortableTextTableColumn | undefined, type: PortableTextTableColumnType): "start" | "center" | "end" =>
+  col?.align ?? (NUMERIC_TYPES.has(type) ? "end" : "start");
+
+/** The types whose cell is a value rather than words: V2 renders them from the value (cellHtml). */
+export const isValueType = (t: PortableTextTableColumnType): boolean => t === "boolean" || NUMERIC_TYPES.has(t);
+
+const TRUE_WORDS = new Set(["✓", "✔", "✔️", "☑", "✅", "yes", "y", "true", "included", "available", "supported", "x ✓", "check", "●"]);
+const FALSE_WORDS = new Set(["✗", "✕", "✖", "❌", "×", "x", "no", "n", "false", "not included", "unavailable", "not available", "unsupported", "—", "–", "-", "○"]);
+/** V2 `toBool` (schema/table.ts:315). */
+export function toBool(v: unknown): boolean | null {
+  if (typeof v === "boolean") return v;
+  if (typeof v !== "string") return null;
+  const s = v.trim().toLowerCase();
+  return TRUE_WORDS.has(s) ? true : FALSE_WORDS.has(s) ? false : null;
+}
+/** V2 `toNumber` (schema/table.ts:273). */
+export function toNumber(v: unknown): number | null {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v !== "string") return null;
+  const s = v.replace(/[,\s]/g, "").replace(/[^\d.+-]/g, "");
+  if (!s || !/^[+-]?\d*\.?\d+$/.test(s)) return null;
+  return Number(s);
+}
+/** V2 `formatNumber` (schema/table.ts:262). */
+export const formatNumber = (n: number, decimals?: number): string =>
+  new Intl.NumberFormat("en-US", decimals != null ? { minimumFractionDigits: decimals, maximumFractionDigits: decimals } : { maximumFractionDigits: 6 }).format(n);
+/** V2 `formatMoney` (schema/table.ts:265). */
+export function formatMoney(n: number, currency = "USD", decimals?: number): string {
+  try {
+    const whole = Number.isInteger(n) && decimals == null;
+    return new Intl.NumberFormat("en-US", { style: "currency", currency, minimumFractionDigits: whole ? 0 : decimals ?? 2, maximumFractionDigits: whole ? 0 : decimals ?? 2 }).format(n);
+  } catch {
+    return `${formatNumber(n, decimals)} ${currency}`;
+  }
+}
+/** V2 `boolLabels` (schema/table.ts:252). */
+export const boolLabels = (col: PortableTextTableColumn | undefined) => ({ yes: col?.trueLabel || "Included", no: col?.falseLabel || "Not included" });
+
+/**
+ * V2 `cellText` (schema/table.ts:282) for a value type: the words a Number, Price, Yes / No or Rating cell says, which is what a
+ * typed cell's `content` holds. `v` is the typed value, or the cell's words when it has none.
+ */
+export function typedCellText(col: PortableTextTableColumn | undefined, type: PortableTextTableColumnType, v: unknown): string {
+  if (v == null || v === "") return "";
+  const words = String(v).replace(/\s+/g, " ").trim();
+  switch (type) {
+    case "boolean": {
+      const b = toBool(v);
+      return b == null ? words : b ? boolLabels(col).yes : boolLabels(col).no;
+    }
+    case "number": {
+      const n = toNumber(v);
+      return n == null ? words : `${formatNumber(n, col?.decimals)}${col?.unit ? (/^[%°]/.test(col.unit) ? col.unit : ` ${col.unit}`) : ""}`;
+    }
+    case "money": {
+      const n = toNumber(v);
+      return n == null ? words : formatMoney(n, col?.currency || "USD", col?.decimals);
+    }
+    case "rating": {
+      const n = toNumber(v);
+      return n == null ? words : `${formatNumber(n, 1).replace(/\.0$/, "")} out of ${col?.max ?? 5}`;
+    }
+    default:
+      return words;
+  }
+}
+
+const escHtml = (s: string): string => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+/**
+ * What a cell of a TYPED table (one whose first row names a `column`) draws, shared by both renderers so they cannot disagree:
+ *   a head-row cell  → `lead` data-align (V2: not when start), `tail` the column's description as `title`
+ *                      (V2 renderTableHtml's `<th scope="col" data-align data-highlight title>`, schema/table.ts:564)
+ *   any other cell   → `tail` data-type (its own type), data-value / data-empty, data-align, and `inner`, V2 cellHtml's markup
+ *                      (schema/table.ts:369-437) when the cell is empty or of a value type; text and link cells draw their blocks.
+ * Attribute values are raw (the caller escapes them); `inner` is markup, its text already escaped.
+ */
+export function typedCellView(
+  column: PortableTextTableColumn | undefined,
+  row: unknown,
+  cell: Record<string, unknown>,
+  inHead: boolean,
+): { lead: [string, string][]; tail: [string, string][]; inner?: string } {
+  if (inHead) {
+    const align = columnAlign(column, column?.type ?? "text");
+    return { lead: align !== "start" ? [["data-align", align]] : [], tail: column?.description ? [["title", column.description]] : [] };
+  }
+  const type = cellTypeOf(column, row, cell);
+  const words = portableTextWords(cell.content);
+  const v = typeof cell.value === "number" || typeof cell.value === "boolean" ? cell.value : words;
+  const tail: [string, string][] = isColumnType(cell.type) ? [["data-type", cell.type]] : [];
+  let inner: string | undefined;
+  if (v === "") {
+    inner = cell.header === true ? "" : '<span aria-hidden="true" class="bt-dash">—</span><span class="bt-sr">No value</span>';
+    tail.push(["data-empty", ""]);
+  } else if (type === "boolean") {
+    const b = toBool(v);
+    if (b == null) inner = escHtml(words);
+    else {
+      const { yes, no } = boolLabels(column);
+      inner = `<span aria-hidden="true" class="bt-bool" data-bool="${b}">${b ? "✓" : "–"}</span><span class="bt-sr">${escHtml(b ? yes : no)}</span>`;
+      tail.push(["data-value", String(b)]);
+    }
+  } else if (type === "rating") {
+    const n = toNumber(v);
+    if (n == null) inner = escHtml(words);
+    else {
+      inner = `<span aria-hidden="true" class="bt-star">★</span> ${escHtml(formatNumber(n, 1).replace(/\.0$/, ""))}<span class="bt-dim"> / ${column?.max ?? 5}</span>`;
+      tail.push(["data-value", String(n)]);
+    }
+  } else if (type === "number" || type === "money") {
+    const n = toNumber(v);
+    inner = escHtml(typedCellText(column, type, v));
+    if (n != null) tail.push(["data-value", String(n)]);
+  }
+  const align = columnAlign(column, type);
+  if (align !== "start") tail.push(["data-align", align]);
+  return { lead: [], tail, ...(inner === undefined ? {} : { inner }) };
+}
+
+/** A cell's words: the text of its blocks, whitespace collapsed (as `portableTextToPlainText` reads a paragraph). */
+function portableTextWords(content: unknown): string {
+  return (Array.isArray(content) ? content : [])
+    .map((b) => (isRecord(b) && Array.isArray(b.children) ? b.children.map((c) => (isRecord(c) && typeof c.text === "string" ? c.text : "")).join("") : ""))
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Why a cell's typed keys cannot be stored (`column` only on the first row, a known type, a value its type holds). */
+function typedCellProblems(cell: Record<string, unknown>, row: Record<string, unknown>, r: number, c: number, col: PortableTextTableColumn | undefined): PortableTextTableProblem[] {
+  const out: PortableTextTableProblem[] = [];
+  const bad = (k: string | string[], message: string, code = "table_value_invalid") =>
+    out.push({ path: ["rows", r, "cells", c, ...(Array.isArray(k) ? k : [k])], code, message: `${code}: ${message}` });
+  if (cell.column !== undefined) {
+    const v = cell.column;
+    if (r !== 0) bad("column", "a column's type is named on its cell in the first row only");
+    else if (!isRecord(v)) bad("column", "column must be an object { type, unit?, currency?, decimals?, align?, trueLabel?, falseLabel?, max?, description? }");
+    else {
+      for (const k of Object.keys(v)) if (!COLUMN_KEYS.has(k)) bad(["column", k], `unknown key "${k}" (${[...COLUMN_KEYS].join(", ")})`);
+      if (v.type !== undefined && !isColumnType(v.type)) bad(["column", "type"], `type must be one of ${PT_TABLE_COLUMN_TYPES.join(", ")}`);
+      const text = (k: string, max: number) => {
+        if (v[k] === undefined) return;
+        if (typeof v[k] !== "string") bad(["column", k], `${k} must be a string`);
+        else if ((v[k] as string).length > max) bad(["column", k], `${k} is ${(v[k] as string).length} characters; at most ${max}`, "table_limit_exceeded");
+      };
+      text("description", PT_TABLE_LIMITS.notesChars);
+      text("unit", 16);
+      text("trueLabel", PT_TABLE_LIMITS.labelChars);
+      text("falseLabel", PT_TABLE_LIMITS.labelChars);
+      if (v.currency !== undefined && (typeof v.currency !== "string" || !/^[A-Z]{3}$/.test(v.currency))) bad(["column", "currency"], "currency must be an ISO 4217 code such as USD");
+      if (v.decimals !== undefined && (!Number.isInteger(v.decimals) || (v.decimals as number) < 0 || (v.decimals as number) > 10)) bad(["column", "decimals"], "decimals must be a whole number from 0 to 10");
+      if (v.max !== undefined && (!Number.isInteger(v.max) || (v.max as number) < 1 || (v.max as number) > 10)) bad(["column", "max"], "max must be a whole number from 1 to 10");
+      if (v.align !== undefined && v.align !== "start" && v.align !== "center" && v.align !== "end") bad(["column", "align"], 'align must be "start", "center" or "end"');
+    }
+  }
+  if (cell.type !== undefined && !isColumnType(cell.type)) bad("type", `type must be one of ${PT_TABLE_COLUMN_TYPES.join(", ")}`);
+  if (cell.value !== undefined) {
+    const type = cellTypeOf(col, row, cell);
+    if (type === "boolean" ? typeof cell.value !== "boolean" : NUMERIC_TYPES.has(type) ? typeof cell.value !== "number" || !Number.isFinite(cell.value) : true) {
+      bad("value", `a ${type} cell's value must be ${type === "boolean" ? "true or false" : NUMERIC_TYPES.has(type) ? "a number" : "absent (its words are its content)"}`);
+    }
+  }
+  return out;
+}

package/src/types.ts

@@ -110,6 +110,62 @@ 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;
+  /**
+   * The column's type and its settings (the V2 table's `TableColumn` type, unit, currency, decimals, align, trueLabel,
+   * falseLabel, max, description): named, like `group`, on the column's FIRST-row cell. Nested rather than spread on the
+   * cell because the cell's own `type` is the per-cell type. Renders as the column's `<col data-type …>`, as V2 writes it.
+   */
+  column?: PortableTextTableColumn;
+  /** The per-cell type (the V2 table's `TableCellObject.type`): wins over the row's and the column's. */
+  type?: PortableTextTableColumnType;
+  /**
+   * The typed value of a Number, Price, Yes / No or Rating cell (the V2 table's `TableCellValue`): a number, or true /
+   * false. `content` still holds the words the cell says (V2's `cellText`), so every reader that reads blocks reads it.
+   */
+  value?: number | boolean;
+  /**
+   * A footnote on this cell (the V2 table's `TableCellObject.note`): a `_key` of the table's `footnotes`. The cell renders
+   * `data-note` and the numbered marker V2 writes, `<sup><a href="#<table key>-fn-<n>" aria-label="Note <n>"><n></a></sup>`.
+   */
+  note?: string;
+}
+
+/**
+ * The column types a rich-text table offers: the V2 table's `TableColumnType`s its island offers (table-editor.tsx:80-86
+ * TYPE_UI without the two `dev` ones; V2's rich-text TableBlock passes no `developer`).
+ */
+export const PT_TABLE_COLUMN_TYPES = ["text", "number", "money", "boolean", "rating", "link"] as const;
+export type PortableTextTableColumnType = (typeof PT_TABLE_COLUMN_TYPES)[number];
+
+/** A column's type and settings, the V2 table's `TableColumn` keys (schema/table.ts:44-72), spelled the same way. */
+export interface PortableTextTableColumn {
+  /** Absent reads as `text`. */
+  type?: PortableTextTableColumnType;
+  /** Explains the column: the header's `title`. */
+  description?: string;
+  /** number: written after every value ("kg", "%", "min"). */
+  unit?: string;
+  /** money: ISO 4217 code. Default USD. */
+  currency?: string;
+  /** number / money: fixed decimals. */
+  decimals?: number;
+  /** Default: numbers, money and ratings align end, everything else start. */
+  align?: "start" | "center" | "end";
+  /** boolean: the words. Defaults "Included" / "Not included". */
+  trueLabel?: string;
+  falseLabel?: string;
+  /** rating: the scale. Default 5. */
+  max?: number;
 }
 
 export interface PortableTextTableRow {
@@ -119,6 +175,15 @@ 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;
+  /** The per-row type (the V2 table's `TableRow.type`): a pricing matrix mixes Yes / No rows with limit rows. `<tr data-type>`. */
+  type?: PortableTextTableColumnType;
 }
 
 /**
@@ -160,6 +225,47 @@ 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;
+  /**
+   * Footnotes (the V2 table's `TableValue.footnotes`, the field-lane table's `footnotes`): numbered in order, named by a
+   * cell's `note`, written under the table as V2's `<ol data-footnotes>` inside `<div class="bt-notes">`.
+   */
+  footnotes?: PortableTextTableFootnote[];
+}
+
+/** One table footnote: a stable `_key` (what a cell's `note` names) and its text. */
+export interface PortableTextTableFootnote {
+  _key: string;
+  text: string;
+}
+
+/** 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;
 }
 
 /**