@bettercms-ai/richtext 0.8.3 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.8.3",
+  "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.",
@@ -9,6 +9,7 @@
   "files": [
     "src",
     "!src/__tests__",
+    "!src/__fixtures__",
     "package.json",
     "README.md"
   ],

package/src/component-copy.ts

@@ -0,0 +1,138 @@
+import { EMBEDDED_COMPONENT_KEY } from "./types";
+
+/**
+ * A component embedded in rich text, kept as a SEPARATE COPY (V2 "Keep as a separate copy" /
+ * "Make a separate copy", bettercms-v2-demo features/blocks/instances.ts `instanceOps.detach`).
+ *
+ * Linked (every value stored before this existed):
+ *   { _type: "bcmsBlock", schemaKey: "component", fields: { componentId, overrides?, variant? } }
+ *   → renders the shared component with this place's overrides; edits to the component reach it.
+ *
+ * Detached:
+ *   { _type: "bcmsBlock", schemaKey: "component", fields: {
+ *       componentId,        the component it was copied from (kept for "Use shared version again")
+ *       detached: true,
+ *       props,              the values readers saw when it was copied (the component's ⊕ this place's)
+ *       blocks,             the block tree readers see, resolved and frozen: no `component` block inside
+ *       sourcePublishedAt,  the source's `lastPublishedAt` when it was copied (0454; older copies hold its first `publishedAt`): the version it was taken from
+ *       variant?
+ *   } }
+ *   → renders `blocks` and never looks the component up again.
+ *
+ * V2 keeps only `props` because its renderer draws a catalog type from props. Here a component's
+ * markup is its own block tree, so a copy that kept only props would still follow the shared
+ * component's structure; `blocks` is what makes the copy separate.
+ */
+export interface DetachedComponentCopy {
+  /** The node's `_key`. */
+  id: string;
+  componentId: string;
+  props: Record<string, unknown>;
+  blocks: unknown[];
+  sourcePublishedAt?: string;
+  variant?: string;
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+
+const fieldsOf = (value: unknown): Record<string, unknown> | null =>
+  isRecord(value) && value.schemaKey === EMBEDDED_COMPONENT_KEY && isRecord(value.fields) ? value.fields : null;
+
+/** True when the node is an embedded component stored as a separate copy (whatever else it holds). */
+export function isDetachedComponent(value: unknown): boolean {
+  return fieldsOf(value)?.detached === true;
+}
+
+/** The separate copy a node stands for, or null (a linked embed, any other node, a malformed copy). */
+export function detachedComponentCopy(value: unknown): DetachedComponentCopy | null {
+  const f = fieldsOf(value);
+  if (!f || f.detached !== true || !Array.isArray(f.blocks)) return null;
+  return {
+    id: isRecord(value) && typeof value._key === "string" ? value._key : "",
+    componentId: typeof f.componentId === "string" ? f.componentId : "",
+    props: isRecord(f.props) ? f.props : {},
+    blocks: f.blocks,
+    ...(typeof f.sourcePublishedAt === "string" ? { sourcePublishedAt: f.sourcePublishedAt } : {}),
+    ...(typeof f.variant === "string" ? { variant: f.variant } : {}),
+  };
+}
+
+/** One reason a stored copy is refused, at its path inside the node's `fields`. */
+export type ComponentCopyProblem = { path: Array<string | number>; code: string; message: string };
+
+/**
+ * Every reason a separate copy cannot be stored, named `component_copy_invalid` (the shape) or
+ * `component_copy_not_frozen` (its blocks still reference a component, so it would keep
+ * following one).
+ *
+ * 🔴 ONLY A NODE THAT CARRIES `detached` IS JUDGED. A linked embed answers `[]`, so every value
+ * stored before copies existed saves exactly as it did.
+ */
+export function componentCopyProblems(node: unknown): ComponentCopyProblem[] {
+  const f = fieldsOf(node);
+  if (!f || f.detached === undefined) return [];
+  const out: ComponentCopyProblem[] = [];
+  const bad = (path: Array<string | number>, message: string, code = "component_copy_invalid") =>
+    out.push({ path, code, message: `${code}: ${message}` });
+  if (f.detached !== true) bad(["detached"], "detached must be true (leave it out for a linked component)");
+  if (typeof f.componentId !== "string" || !f.componentId) bad(["componentId"], "needs the componentId it was copied from");
+  if (!isRecord(f.props)) bad(["props"], "props must be an object of the values readers see");
+  if (!Array.isArray(f.blocks)) {
+    bad(["blocks"], "needs blocks, the copy readers see; get_component { detachedCopy } returns them");
+  } else {
+    const live = componentRefs(f.blocks);
+    if (live.length) {
+      bad(["blocks"], `still holds ${live.length} component block(s) (${live.slice(0, 3).join(", ")}), so it would keep following the shared one`, "component_copy_not_frozen");
+    }
+  }
+  if (f.sourcePublishedAt !== undefined && (typeof f.sourcePublishedAt !== "string" || Number.isNaN(Date.parse(f.sourcePublishedAt)))) {
+    bad(["sourcePublishedAt"], "sourcePublishedAt must be an ISO date");
+  }
+  if (isRecord(f.overrides) && Object.keys(f.overrides).length) {
+    bad(["overrides"], "a separate copy keeps its values in props; overrides belong to a linked component");
+  }
+  return out;
+}
+
+/** `componentCopyProblems` for every embedded component at the top of a rich-text value, with its `_key`. */
+export function portableTextComponentCopyProblems(value: unknown): Array<ComponentCopyProblem & { block: string }> {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((node) => {
+    const block = isRecord(node) && typeof node._key === "string" ? node._key : "";
+    return componentCopyProblems(node).map((p) => ({ ...p, block }));
+  });
+}
+
+/** The component ids a block tree still references, at any depth. */
+function componentRefs(blocks: unknown, out: string[] = [], depth = 0): string[] {
+  if (depth > 32) return out;
+  if (Array.isArray(blocks)) {
+    for (const b of blocks) componentRefs(b, out, depth + 1);
+    return out;
+  }
+  if (!isRecord(blocks)) return out;
+  if (blocks.type === "component") {
+    const p = isRecord(blocks.props) ? blocks.props : {};
+    out.push(typeof p.componentId === "string" && p.componentId ? p.componentId : "(no id)");
+  }
+  for (const v of Object.values(blocks)) if (v && typeof v === "object") componentRefs(v, out, depth + 1);
+  return out;
+}
+
+/**
+ * What a separate copy says, one line per value, for search and plain text: its own copy is
+ * content this page owns, unlike a linked embed, whose words live in the component.
+ * Strings (markup stripped), numbers, and a link's or button's label; nothing else.
+ */
+export function componentCopyLines(copy: Pick<DetachedComponentCopy, "props">): string[] {
+  const line = (v: unknown): string | null => {
+    if (typeof v === "number" && Number.isFinite(v)) return String(v);
+    if (typeof v === "string") {
+      const t = v.replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+      return t || null;
+    }
+    if (isRecord(v)) return line(v.label ?? v.text ?? v.title);
+    return null;
+  };
+  return Object.values(copy.props).map(line).filter((s): s is string => !!s);
+}

package/src/html.ts

@@ -3,14 +3,17 @@ import {
   BUILTIN_EMBED_KEY,
   BUILTIN_IMAGE_KEY,
   PT_TYPES,
+  pullQuoteHref,
   type PortableText,
   type PortableTextTable,
 } from "./types";
 import { resolveVideoSource } from "./video";
-import { builtInTableToTable } 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";
+import { keyTakeawaysView } from "./key-takeaways";
 
 /**
  * Portable Text → HTML.
@@ -62,34 +65,116 @@ 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"' : "";
-  return `<table${cls}>${head.length ? `<thead>${head.map(rowHtml).join("")}</thead>` : ""}${
-    body.length ? `<tbody>${body.map(rowHtml).join("")}</tbody>` : ""
-  }</table>`;
+  const notes = typeof table.notes === "string" ? table.notes.trim() : "";
+  const notesId = notes && 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).
+  // "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>`))
+        .join("")}</tr>`
+    : "";
+  const thead = groupRow || head.length ? `<thead>${groupRow}${head.map(rowHtml).join("")}</thead>` : "";
+
+  // Row groups: each run of body rows sharing a group is its own `<tbody>`, under a
+  // `scope="rowgroup"` label row. With no grouped row, ONE `<tbody>`, exactly as before.
+  const tbody = layout.rows.length
+    ? layout.rows
+        .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 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.
+  // "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>`;
 }
 
 /**
@@ -215,6 +300,49 @@ function fileHtml(value: unknown, classes: HtmlClasses): string {
   return `<a${cls(classes, "a")} href="${esc(src)}" download>${esc(name)}</a>`;
 }
 
+/**
+ * A pull quote, as the V2 kit renders it (`renderArticle("pullquote")`, article.ts): the same
+ * markup when no classes are passed, with one byte-level difference — a `"` in text comes out
+ * as `&quot;` here (as everywhere in this serialiser, and as React writes it) where the kit
+ * leaves it bare. Both parse to the same DOM, and the kit reads the markup through the DOM, so
+ * only a raw string comparison could tell them apart. The `data-rt`, `data-name` and
+ * `data-role` hooks are the contract, not decoration.
+ *
+ * The name links to `link` (and the blockquote cites it) only through `safeHref`; a refused
+ * link keeps the name, unlinked.
+ */
+function pullQuoteHtml(value: unknown, classes: HtmlClasses): string {
+  const v = isRecord(value) ? value : {};
+  const quote = typeof v.quote === "string" ? v.quote : "";
+  const name = str(v.name);
+  const role = str(v.role);
+  const href = safeHref(pullQuoteHref(v.link));
+  const nameHtml = name
+    ? href
+      ? `<a href="${esc(href)}" data-name>${esc(name)}</a>`
+      : `<span data-name>${esc(name)}</span>`
+    : "";
+  const roleHtml = role ? `<span data-role>${esc(role)}</span>` : "";
+  const caption = nameHtml || roleHtml
+    ? `<figcaption>${nameHtml}${nameHtml && roleHtml ? ", " : ""}${roleHtml}</figcaption>`
+    : "";
+  const cite = href ? ` cite="${esc(href)}"` : "";
+  return `<figure${cls(classes, "figure")} data-rt="pullquote"><blockquote${cls(classes, "blockquote")}${cite}><p>${esc(quote)}</p></blockquote>${caption}</figure>`;
+}
+
+/**
+ * Key takeaways, as the V2 kit renders them (`renderArticle("takeaways")`, article.ts):
+ * `<aside data-rt="takeaways"><p data-title>…</p><ul><li>…</li></ul></aside>`, the title only
+ * when there is one, each point trimmed and the empty ones left out. The same bytes when no
+ * classes are passed, save the pull quote's one difference: a `"` in text is `&quot;` here.
+ * A site's own list classes dress the `<ul>` and `<li>`, as they dress its other lists.
+ */
+function keyTakeawaysHtml(value: unknown, classes: HtmlClasses): string {
+  const { title, points } = keyTakeawaysView(value);
+  const items = points.map((p) => `<li${cls(classes, "li")}>${esc(p)}</li>`).join("");
+  return `<aside data-rt="takeaways">${title ? `<p data-title>${esc(title)}</p>` : ""}<ul${cls(classes, "ul")}>${items}</ul></aside>`;
+}
+
 export interface RenderOptions {
   /**
    * Render a single value with no wrapping `<p>`, for a field whose consumer supplies its own
@@ -303,6 +431,8 @@ const buildComponents = (
     },
     [PT_TYPES.video]: ({ value }) => videoHtml(value, classes),
     [PT_TYPES.file]: ({ value }) => fileHtml(value, classes),
+    [PT_TYPES.pullQuote]: ({ value }) => pullQuoteHtml(value, classes),
+    [PT_TYPES.keyTakeaways]: ({ value }) => keyTakeawaysHtml(value, classes),
     /**
      * A generic embedded block. A block whose payload this serialiser can READ renders as
      * content; one carrying a reference it would have to resolve against a project renders as a

package/src/index.ts

@@ -5,8 +5,10 @@ export * from "./key";
 export * from "./from-lexical";
 export * from "./plain";
 export * from "./table";
+export * from "./key-takeaways";
 export * from "./styled";
 export * from "./read";
+export * from "./component-copy";
 export * from "./accept";
 export * from "./features";
 export * from "./video";