feat: Tables a11y (BLO-1230) (BLO-1231)

packages/core/src/api/exporters/html/util/serializeBlocksExternalHTML.ts

@@ -1,5 +1,7 @@
+import { UniqueID } from "../../../../extensions/tiptap-extensions/UniqueID/UniqueID.js";
 import { DOMSerializer, Fragment, Node } from "prosemirror-model";
 
+import { createTableSerializer } from "../../../../blocks/Table/TableAccessibility/createTableSerializer.js";
 import { PartialBlock } from "../../../../blocks/defaultBlocks.js";
 import type { BlockNoteEditor } from "../../../../editor/BlockNoteEditor.js";
 import {
@@ -57,7 +59,7 @@ export function serializeInlineContentExternalHTML<
   editor: BlockNoteEditor<any, I, S>,
   blockContent: PartialBlock<BSchema, I, S>["content"],
   serializer: DOMSerializer,
-  options?: { document?: Document; blockType?: string },
+  options?: { document?: Document; blockType?: string; blockId?: string },
 ) {
   let nodes: Node[];
 
@@ -78,6 +80,12 @@ export function serializeInlineContentExternalHTML<
     );
   } else if (blockContent.type === "tableContent") {
     nodes = tableContentToNodes(blockContent, editor.pmSchema);
+    serializer = createTableSerializer(
+      serializer,
+      editor.pmSchema.nodes.table.create(null, nodes),
+      options?.blockId ?? UniqueID.options.generateID(),
+      options?.document ?? document,
+    );
   } else {
     throw new UnreachableCaseError(blockContent.type);
   }
@@ -351,7 +359,11 @@ function serializeBlock<
         editor,
         block.content as any, // TODO
         serializer,
-        { ...options, blockType: block.type },
+        {
+          ...options,
+          blockType: block.type,
+          blockId: block.id,
+        },
       );
 
       ret.contentDOM.appendChild(ic);

packages/core/src/api/exporters/html/util/serializeBlocksInternalHTML.ts

@@ -1,5 +1,7 @@
+import { UniqueID } from "../../../../extensions/tiptap-extensions/UniqueID/UniqueID.js";
 import { DOMSerializer, Fragment, Node } from "prosemirror-model";
 
+import { createTableSerializer } from "../../../../blocks/Table/TableAccessibility/createTableSerializer.js";
 import { PartialBlock } from "../../../../blocks/defaultBlocks.js";
 import type { BlockNoteEditor } from "../../../../editor/BlockNoteEditor.js";
 import {
@@ -29,7 +31,7 @@ export function serializeInlineContentInternalHTML<
   blockContent: PartialBlock<BSchema, I, S>["content"],
   serializer: DOMSerializer,
   blockType?: string,
-  options?: { document?: Document },
+  options?: { document?: Document; blockId?: string },
 ) {
   let nodes: Node[];
 
@@ -42,6 +44,12 @@ export function serializeInlineContentInternalHTML<
     nodes = inlineContentToNodes(blockContent, editor.pmSchema, blockType);
   } else if (blockContent.type === "tableContent") {
     nodes = tableContentToNodes(blockContent, editor.pmSchema);
+    serializer = createTableSerializer(
+      serializer,
+      editor.pmSchema.nodes.table.create(null, nodes),
+      options?.blockId ?? UniqueID.options.generateID(),
+      options?.document ?? document,
+    );
   } else {
     throw new UnreachableCaseError(blockContent.type);
   }
@@ -196,7 +204,10 @@ function serializeBlock<
       block.content as any, // TODO
       serializer,
       block.type,
-      options,
+      {
+        ...options,
+        blockId: block.id,
+      },
     );
     ret.contentDOM.appendChild(ic);
   }

packages/core/src/api/nodeConversions/blockToNode.ts

@@ -217,7 +217,6 @@ export function tableContentToNodes<
     const isHeaderRow = headerRows[rowIndex];
     for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex++) {
       const cell = row.cells[cellIndex];
-      const isHeaderCol = headerCols[cellIndex];
       /**
        * The attributes of the cell to apply to the node
        */
@@ -236,6 +235,8 @@ export function tableContentToNodes<
         { type: "table", content: tableContent } as any,
       );
 
+      const isHeaderCol = headerCols[absoluteCellIndex.col];
+
       // Assume the column width is the width of the cell at the absolute cell index
       let colwidth: (number | undefined)[] | null = columnWidths[
         absoluteCellIndex.col

packages/core/src/api/nodeConversions/nodeToBlock.ts

@@ -1,3 +1,4 @@
+import { TableMap } from "prosemirror-tables";
 import { Mark, Node, Slice } from "@tiptap/pm/model";
 import type { Block } from "../../blocks/defaultBlocks.js";
 import { isLayoutNode } from "../../schema/blocks/children.js";
@@ -72,11 +73,16 @@
     rows: [],
   };
 
-  /**
-   * A matrix of boolean values indicating whether a cell is a header.
-   * The first index is the row index, the second index is the cell index.
-   */
-  const headerMatrix: boolean[][] = [];
+  // Include slots covered by row/column spans when identifying header bands.
+  const map = TableMap.get(contentNode);
+  const headerMatrix = Array.from({ length: map.height }, (_, row) =>
+    Array.from(
+      { length: map.width },
+      (_, col) =>
+        contentNode.nodeAt(map.map[row * map.width + col])?.type.spec
+          .tableRole === "header_cell",
+    ),
+  );
 
   contentNode.content.forEach((rowNode, _offset, rowIndex) => {
     const row: TableContent<I, S>["rows"][0] = {
@@ -93,12 +99,7 @@
       });
     }
 
-    row.cells = rowNode.content.content.map((cellNode, cellIndex) => {
-      if (!headerMatrix[rowIndex]) {
-        headerMatrix[rowIndex] = [];
-      }
-      // Mark the cell as a header if it is a tableHeader node.
-      headerMatrix[rowIndex][cellIndex] = cellNode.type.name === "tableHeader";
+    row.cells = rowNode.content.content.map((cellNode) => {
       // Convert cell content to inline content and merge adjacent styled text nodes
       const content = cellNode.content.content
         .map((child) =>

packages/core/src/blocks/Table/TableAccessibility/TableAccessibilityPlugin.ts

@@ -0,0 +1,57 @@
+import { Node as PMNode } from "prosemirror-model";
+import { Plugin, PluginKey } from "prosemirror-state";
+import { Decoration, DecorationSet } from "prosemirror-view";
+import {
+  applyCellHeaders,
+  applyHeaderId,
+  applyHeaderScope,
+} from "./cellAttributes.js";
+
+export function TableAccessibilityPlugin() {
+  const accessibilityKey = new PluginKey<DecorationSet>("tableAccessibility");
+
+  function createAccessibilityDecorations(doc: PMNode) {
+    const decorations: Decoration[] = [];
+    doc.descendants((table, tablePosition, parent) => {
+      if (table.type.spec.tableRole !== "table") {
+        return;
+      }
+      const tableId = parent!.attrs.id;
+      table.forEach((row, rowOffset) => {
+        row.forEach((cell, cellOffset) => {
+          // TableMap positions start at table content; decorations use
+          // absolute document positions, including the table's opening token.
+          const position = rowOffset + cellOffset + 1;
+          const attributes: Record<string, string> = {};
+          if (cell.type.spec.tableRole === "header_cell") {
+            applyHeaderScope(attributes, table, position);
+            applyHeaderId(attributes, table, tableId, position);
+          } else {
+            applyCellHeaders(attributes, table, tableId, position);
+          }
+          const from = tablePosition + 1 + position;
+          decorations.push(
+            Decoration.node(from, from + cell.nodeSize, attributes),
+          );
+        });
+      });
+      return false;
+    });
+    return DecorationSet.create(doc, decorations);
+  }
+
+  return new Plugin<DecorationSet>({
+    key: accessibilityKey,
+    state: {
+      init: (_, state) => createAccessibilityDecorations(state.doc),
+      // Recompute relationships after edits; selection changes reuse them.
+      apply: (transaction, decorations) =>
+        transaction.docChanged
+          ? createAccessibilityDecorations(transaction.doc)
+          : decorations,
+    },
+    props: {
+      decorations: (state) => accessibilityKey.getState(state),
+    },
+  });
+}

packages/core/src/blocks/Table/TableAccessibility/cellAttributes.ts

@@ -0,0 +1,99 @@
+import { TableMap } from "prosemirror-tables";
+import { Node } from "prosemirror-model";
+
+function getHeaderScope(table: Node, position: number) {
+  const map = TableMap.get(table);
+  const { top, left } = map.findCell(position);
+  const isHeader = (position: number) =>
+    table.nodeAt(position)?.type.spec.tableRole === "header_cell";
+
+  // A full header row identifies column headers, including intersections with
+  // header columns. TableMap includes slots covered by merged cells.
+  if (map.map.slice(top * map.width, (top + 1) * map.width).every(isHeader)) {
+    return "col";
+  }
+  for (let row = 0; row < map.height; row++) {
+    if (!isHeader(map.map[row * map.width + left])) {
+      return undefined;
+    }
+  }
+  return "row";
+}
+
+function getHeaderId(
+  tableId: string,
+  scope: "row" | "col",
+  row: number,
+  col: number,
+) {
+  // Both coordinates distinguish headers in multiple header rows or columns.
+  return `bn-table-${tableId}-${scope}-header-${row}-${col}`;
+}
+
+export function applyCellHeaders(
+  attributes: Record<string, string>,
+  table: Node,
+  tableId: string,
+  cellPosition: number,
+) {
+  const ids = new Set<string>();
+  const map = TableMap.get(table);
+  const rect = map.findCell(cellPosition);
+
+  function addHeader(position: number, scope: "row" | "col") {
+    if (
+      table.nodeAt(position)?.type.spec.tableRole !== "header_cell" ||
+      getHeaderScope(table, position) !== scope
+    ) {
+      return;
+    }
+    const { top, left } = map.findCell(position);
+    ids.add(getHeaderId(tableId, scope, top, left));
+  }
+
+  // Search every header row/column along the cell's covered grid indices.
+  // A merged header may occupy several slots; the Set keeps one reference.
+  for (let row = 0; row < map.height; row++) {
+    for (let col = rect.left; col < rect.right; col++) {
+      addHeader(map.map[row * map.width + col], "col");
+    }
+  }
+  for (let row = rect.top; row < rect.bottom; row++) {
+    for (let col = 0; col < map.width; col++) {
+      addHeader(map.map[row * map.width + col], "row");
+    }
+  }
+  if (ids.size) {
+    attributes.headers = [...ids].join(" ");
+  } else {
+    delete attributes.headers;
+  }
+}
+
+export function applyHeaderScope(
+  attributes: Record<string, string>,
+  table: Node,
+  position: number,
+) {
+  const scope = getHeaderScope(table, position);
+  if (scope) {
+    attributes.scope = scope;
+  } else {
+    delete attributes.scope;
+  }
+}
+
+export function applyHeaderId(
+  attributes: Record<string, string>,
+  table: Node,
+  tableId: string,
+  position: number,
+) {
+  const scope = getHeaderScope(table, position);
+  if (scope) {
+    const { top, left } = TableMap.get(table).findCell(position);
+    attributes.id = getHeaderId(tableId, scope, top, left);
+  } else {
+    delete attributes.id;
+  }
+}

packages/core/src/blocks/Table/TableAccessibility/createTableSerializer.ts

@@ -0,0 +1,54 @@
+import { DOMSerializer, Node } from "prosemirror-model";
+import {
+  applyCellHeaders,
+  applyHeaderId,
+  applyHeaderScope,
+} from "./cellAttributes.js";
+
+/** Give cell serializers the table position that ProseMirror's toDOM omits. */
+export function createTableSerializer(
+  serializer: DOMSerializer,
+  table: Node,
+  tableId: string,
+  document: Document,
+) {
+  const positions = new Map<Node, number>();
+  table.forEach((row, rowOffset) => {
+    row.forEach((cell, cellOffset) => {
+      positions.set(cell, rowOffset + cellOffset + 1);
+    });
+  });
+
+  function renderCell(cell: Node) {
+    const position = positions.get(cell);
+    if (position === undefined) {
+      throw new Error("Cannot serialize a cell outside its table");
+    }
+    const attributes: Record<string, string> = {};
+    if (cell.type.spec.tableRole === "header_cell") {
+      applyHeaderScope(attributes, table, position);
+      applyHeaderId(attributes, table, tableId, position);
+    } else {
+      applyCellHeaders(attributes, table, tableId, position);
+    }
+
+    // Preserve the existing renderer's spans, styles, and content hole. The
+    // serializer will fill that hole with the cell's content after this returns.
+    const output = DOMSerializer.renderSpec(
+      document,
+      serializer.nodes[cell.type.name](cell),
+    );
+    if (!(output.dom instanceof HTMLElement)) {
+      throw new Error("Table cells must render an HTML element");
+    }
+    for (const [name, value] of Object.entries(attributes)) {
+      output.dom.setAttribute(name, value);
+    }
+    return output;
+  }
+
+  return new DOMSerializer(
+    { ...serializer.nodes, tableHeader: renderCell, tableCell: renderCell },
+    serializer.marks,
+  );
+}

packages/core/src/blocks/Table/TableExtension.ts

@@ -10,15 +10,18 @@ import {
   tableEditing,
 } from "prosemirror-tables";
 
+import { TableAccessibilityPlugin } from "./TableAccessibility/TableAccessibilityPlugin.js";
+
 export const RESIZE_MIN_WIDTH = 35;
 export const EMPTY_CELL_WIDTH = 120;
 export const EMPTY_CELL_HEIGHT = 31;
 
 export const TableExtension = Extension.create({
   name: "BlockNoteTableExtension",
 
-  addProseMirrorPlugins: () => {
+  addProseMirrorPlugins() {
     return [
+      TableAccessibilityPlugin(),
       columnResizing({
         cellMinWidth: RESIZE_MIN_WIDTH,
         defaultCellMinWidth: EMPTY_CELL_WIDTH,