@beyondwork/docx-react-component 1.0.3 → 1.0.4

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml)
 
-`docx-react-component` is now configured as an npm-ready package for the shipped product in this repository: `WordReviewEditor`, a fidelity-first React editor for legal-review-safe `docx` workflows.
+`@beyondwork/docx-react-component` is now configured as an npm-ready package for the shipped product in this repository: `WordReviewEditor`, a fidelity-first React editor for legal-review-safe `docx` workflows.
 
 The broader repository is still evolving toward a layered `react-ooxml-office` platform, but the source reality is unchanged:
 
@@ -13,7 +13,7 @@ The broader repository is still evolving toward a layered `react-ooxml-office` p
 ## Install
 
 ```bash
-pnpm add docx-react-component react react-dom \
+pnpm add @beyondwork/docx-react-component react react-dom tailwindcss \
   prosemirror-commands prosemirror-keymap prosemirror-model \
   prosemirror-state prosemirror-tables prosemirror-transform prosemirror-view
 ```
@@ -23,6 +23,7 @@ Current packaging truth:
 - the package is ESM-only
 - exports point at shipped TypeScript source entry points
 - consumers need a bundler or runtime that can resolve `.ts` and `.tsx` ESM imports
+- consumers should import `@beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css` once and provide a Tailwind v4 CSS pipeline for it
 - package and source identifiers remain docx-first until a deliberate rename lands
 
 ## Shipped Product
@@ -30,7 +31,7 @@ Current packaging truth:
 The primary shipped surface is:
 
 ```tsx
-import { WordReviewEditor } from "docx-react-component";
+import { WordReviewEditor } from "@beyondwork/docx-react-component";
 
 <WordReviewEditor />
 ```
@@ -43,9 +44,10 @@ import { WordReviewEditor } from "docx-react-component";
 
 The current public ESM exports are:
 
-- `docx-react-component` -> `WordReviewEditor`
-- `docx-react-component/public-types` -> public TypeScript contracts
-- `docx-react-component/ui-tailwind` -> current Tailwind UI primitives
+- `@beyondwork/docx-react-component` -> `WordReviewEditor`
+- `@beyondwork/docx-react-component/public-types` -> public TypeScript contracts
+- `@beyondwork/docx-react-component/ui-tailwind` -> current Tailwind UI primitives
+- `@beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css` -> shipped theme variables and Tailwind theme import
 
 ## Product Contract
 
@@ -84,6 +86,7 @@ Start here:
 Current shipped docx contracts:
 
 - `docs/reference/public-api.md`
+  This doc separates the shipped Wave 21 surface from the future Waves 25 through 27 ref expansion.
 - `docs/reference/ooxml-compliance.md`
 - `docs/reference/word-review-editor-frontend-architecture.md`
 - `docs/reference/word-review-editor-ux-guide.md`
@@ -99,9 +102,10 @@ Shared platform and planned xlsx docs:
 
 ## Packaging And Release
 
-- `.github/workflows/publish.yml` publishes on `v*` tags
+- `.github/workflows/publish.yml` publishes on `v*` tags after verifying the tag matches `package.json`
 - `pnpm pack --dry-run` is the baseline package proof for this wave
 - npm provenance is enabled in `publishConfig`
+- the published package currently ships source ESM entry points plus TypeScript source-backed `types` exports
 - the Microsoft Open XML SDK remains CI/internal-service only, never part of the shipped browser runtime
 
 ## Contribution Rules

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "files": [
@@ -29,6 +29,7 @@
     "./io/docx-session": "./src/io/docx-session.ts",
     "./runtime/document-runtime": "./src/runtime/document-runtime.ts",
     "./api/public-types": "./src/api/public-types.ts",
+    "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css",
     "./package.json": "./package.json"
   },
   "types": "./src/index.ts",
@@ -65,7 +66,8 @@
     "prosemirror-transform": "^1.11.0",
     "prosemirror-view": "^1.41.7",
     "react": "^19.2.0",
-    "react-dom": "^19.2.0"
+    "react-dom": "^19.2.0",
+    "tailwindcss": "^4.2.2"
   },
   "devDependencies": {
     "@chllming/wave-orchestration": "^0.9.8",

package/src/compare/export-redlines.ts

@@ -1,5 +1,3 @@
-import { TextEncoder } from "node:util";
-
 import type { OpcRelationship } from "../io/ooxml/part-manifest.ts";
 import { serializeMainDocument } from "../io/export/serialize-main-document.ts";
 import {

package/src/core/commands/index.ts

@@ -9,8 +9,13 @@ import {
 } from "../state/editor-state.ts";
 import {
   areAnchorsEqual,
+  createDetachedAnchor,
   createEmptyMapping,
+  createNodeAnchor,
+  createRangeAnchor,
+  DEFAULT_BOUNDARY_ASSOC,
   mapAnchor,
+  type BoundaryAssoc,
   type EditorAnchorProjection,
   type MappingStep,
   type TransactionMapping,
@@ -655,20 +660,123 @@ function createTransaction(
 }
 
 function normalizeSelection(selection: SelectionSnapshot): SelectionSnapshot {
-  if (selection.activeRange.kind === "range") {
+  const activeRange = normalizeSelectionAnchor(
+    selection.activeRange,
+    selection.anchor,
+    selection.head,
+  );
+
+  if (activeRange.kind === "range") {
     return {
-      ...selection,
-      anchor: selection.activeRange.range.from,
-      head: selection.activeRange.range.to,
-      isCollapsed: selection.activeRange.range.from === selection.activeRange.range.to,
+      anchor: activeRange.range.from,
+      head: activeRange.range.to,
+      isCollapsed: activeRange.range.from === activeRange.range.to,
+      activeRange,
     };
   }
 
-  if (selection.activeRange.kind === "node") {
-    return createSelectionSnapshot(selection.activeRange.at, selection.activeRange.at);
+  if (activeRange.kind === "node") {
+    return createSelectionSnapshot(activeRange.at, activeRange.at);
+  }
+
+  return {
+    anchor: activeRange.lastKnownRange.from,
+    head: activeRange.lastKnownRange.to,
+    isCollapsed: activeRange.lastKnownRange.from === activeRange.lastKnownRange.to,
+    activeRange,
+  };
+}
+
+function normalizeSelectionAnchor(
+  value: SelectionSnapshot["activeRange"],
+  anchor: number,
+  head: number,
+): EditorAnchorProjection {
+  if (!value || typeof value !== "object") {
+    return createRangeAnchor(anchor, head, DEFAULT_BOUNDARY_ASSOC);
+  }
+
+  const record = value as unknown as Record<string, unknown>;
+  switch (record.kind) {
+    case "range": {
+      const assoc = normalizeBoundaryAssoc(record.assoc);
+      const internalRange = record.range;
+      if (
+        internalRange &&
+        typeof internalRange === "object" &&
+        typeof (internalRange as { from?: unknown }).from === "number" &&
+        typeof (internalRange as { to?: unknown }).to === "number"
+      ) {
+        return createRangeAnchor(
+          (internalRange as { from: number }).from,
+          (internalRange as { to: number }).to,
+          assoc,
+        );
+      }
+
+      if (typeof record.from === "number" && typeof record.to === "number") {
+        return createRangeAnchor(record.from, record.to, assoc);
+      }
+
+      return createRangeAnchor(anchor, head, assoc);
+    }
+    case "node":
+      return createNodeAnchor(
+        typeof record.at === "number" ? record.at : anchor,
+        normalizeAssoc(record.assoc),
+      );
+    case "detached": {
+      const lastKnownRange = record.lastKnownRange;
+      if (
+        lastKnownRange &&
+        typeof lastKnownRange === "object" &&
+        typeof (lastKnownRange as { from?: unknown }).from === "number" &&
+        typeof (lastKnownRange as { to?: unknown }).to === "number"
+      ) {
+        return createDetachedAnchor(
+          {
+            from: (lastKnownRange as { from: number }).from,
+            to: (lastKnownRange as { to: number }).to,
+          },
+          normalizeDetachedReason(record.reason),
+        );
+      }
+
+      return createDetachedAnchor({ from: anchor, to: head }, normalizeDetachedReason(record.reason));
+    }
+    default:
+      return createRangeAnchor(anchor, head, DEFAULT_BOUNDARY_ASSOC);
+  }
+}
+
+function normalizeBoundaryAssoc(value: unknown): BoundaryAssoc {
+  if (value && typeof value === "object") {
+    const record = value as unknown as Record<string, unknown>;
+    return {
+      start: normalizeAssoc(record.start),
+      end: normalizeAssoc(record.end),
+    };
+  }
+
+  return DEFAULT_BOUNDARY_ASSOC;
+}
+
+function normalizeAssoc(value: unknown): -1 | 1 {
+  return value === -1 ? -1 : 1;
+}
+
+function normalizeDetachedReason(
+  value: unknown,
+): "deleted" | "invalidatedByStructureChange" | "importAmbiguity" {
+  if (
+    value === "deleted" ||
+    value === "invalidatedByStructureChange" ||
+    value === "importAmbiguity"
+  ) {
+    return value;
   }
 
-  return selection;
+  return "importAmbiguity";
 }
 
 function applyTextCommand(

package/src/core/state/text-transaction.ts

@@ -10,6 +10,8 @@ import {
   type StoryUnit,
   type TextStory,
 } from "../schema/text-schema.ts";
+import { createEditorSurfaceSnapshot } from "../../runtime/surface-projection.ts";
+import type { DocumentRootNode, ParagraphNode, TableNode } from "../../model/canonical-document.ts";
 
 export type TextInsertion =
   | {
@@ -69,6 +71,27 @@ export function applyTextTransaction(
   options: {
     timestamp: string;
   },
+): TextTransactionResult {
+  const tableScopedResult = tryApplyTableParagraphTransaction(
+    document,
+    selection,
+    intent,
+    options,
+  );
+  if (tableScopedResult) {
+    return tableScopedResult;
+  }
+
+  return applyLinearTextTransaction(document, selection, intent, options);
+}
+
+function applyLinearTextTransaction(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  intent: TextTransactionIntent,
+  options: {
+    timestamp: string;
+  },
 ): TextTransactionResult {
   const story = parseTextStory(document.content);
   const normalizedRange = resolveRange(selection, story.size, intent);
@@ -118,6 +141,209 @@ export function applyTextTransaction(
   };
 }
 
+function tryApplyTableParagraphTransaction(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  intent: TextTransactionIntent,
+  options: {
+    timestamp: string;
+  },
+): TextTransactionResult | null {
+  const scope = resolveTableParagraphScope(document, selection);
+  if (!scope) {
+    return null;
+  }
+  if (scope === "unsupported") {
+    throw new TextTransactionError(
+      "unsupported_content",
+      "Text transactions inside table structures are only supported when the selection stays within one paragraph-backed table cell.",
+    );
+  }
+
+  const localDocument: CanonicalDocumentEnvelope = {
+    ...document,
+    content: {
+      type: "doc",
+      children: [scope.paragraph],
+    },
+  };
+  const localSelection = createSelectionSnapshot(
+    selection.anchor - scope.paragraphStart,
+    selection.head - scope.paragraphStart,
+  );
+  const localResult = applyLinearTextTransaction(localDocument, localSelection, intent, options);
+  const nextParagraphBlocks = (localResult.document.content as DocumentRootNode).children;
+  const nextRoot: DocumentRootNode = {
+    ...scope.root,
+    children: scope.root.children.map((child, blockIndex) => {
+      if (blockIndex !== scope.tableBlockIndex) {
+        return child;
+      }
+
+      const table = child as TableNode;
+      return {
+        ...table,
+        rows: table.rows.map((row, rowIndex) => {
+          if (rowIndex !== scope.rowIndex) {
+            return row;
+          }
+
+          return {
+            ...row,
+            cells: row.cells.map((cell, cellIndex) => {
+              if (cellIndex !== scope.cellIndex) {
+                return cell;
+              }
+
+              return {
+                ...cell,
+                children: [
+                  ...cell.children.slice(0, scope.childIndex),
+                  ...nextParagraphBlocks,
+                  ...cell.children.slice(scope.childIndex + 1),
+                ],
+              };
+            }),
+          };
+        }),
+      };
+    }),
+  };
+
+  return {
+    document: {
+      ...document,
+      updatedAt: options.timestamp,
+      content: nextRoot,
+    },
+    selection: createSelectionSnapshot(
+      localResult.selection.anchor + scope.paragraphStart,
+      localResult.selection.head + scope.paragraphStart,
+    ),
+    mapping: {
+      ...localResult.mapping,
+      steps: localResult.mapping.steps.map((step) => ({
+        ...step,
+        from: step.from + scope.paragraphStart,
+        to: step.to + scope.paragraphStart,
+      })),
+    },
+    storyText: localResult.storyText,
+  };
+}
+
+function resolveTableParagraphScope(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+):
+  | {
+      root: DocumentRootNode;
+      tableBlockIndex: number;
+      rowIndex: number;
+      cellIndex: number;
+      childIndex: number;
+      paragraph: ParagraphNode;
+      paragraphStart: number;
+    }
+  | "unsupported"
+  | null {
+  const root = document.content as DocumentRootNode;
+  if (!root || root.type !== "doc" || !Array.isArray(root.children)) {
+    return null;
+  }
+
+  const surface = createEditorSurfaceSnapshot(document, selection);
+  const selectionFrom = Math.min(selection.anchor, selection.head);
+  const selectionTo = Math.max(selection.anchor, selection.head);
+
+  for (let blockIndex = 0; blockIndex < root.children.length; blockIndex += 1) {
+    const block = root.children[blockIndex];
+    const surfaceBlock = surface.blocks[blockIndex];
+    if (block?.type !== "table" || surfaceBlock?.kind !== "table") {
+      continue;
+    }
+
+    const insideTable = selectionFallsWithinSurfaceRange(
+      selectionFrom,
+      selectionTo,
+      surfaceBlock.from,
+      surfaceBlock.to,
+    );
+    if (!insideTable) {
+      continue;
+    }
+
+    for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex += 1) {
+      const row = block.rows[rowIndex];
+      const surfaceRow = surfaceBlock.rows[rowIndex];
+      if (!row || !surfaceRow) {
+        continue;
+      }
+
+      for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+        const cell = row.cells[cellIndex];
+        const surfaceCell = surfaceRow.cells[cellIndex];
+        if (!cell || !surfaceCell) {
+          continue;
+        }
+
+        for (
+          let childIndex = 0;
+          childIndex < Math.min(cell.children.length, surfaceCell.content.length);
+          childIndex += 1
+        ) {
+          const child = cell.children[childIndex];
+          const surfaceChild = surfaceCell.content[childIndex];
+          if (child?.type !== "paragraph" || surfaceChild?.kind !== "paragraph") {
+            continue;
+          }
+
+          const insideParagraph = selectionFallsWithinSurfaceRange(
+            selectionFrom,
+            selectionTo,
+            surfaceChild.from,
+            surfaceChild.to,
+          );
+          if (!insideParagraph) {
+            continue;
+          }
+
+          return {
+            root,
+            tableBlockIndex: blockIndex,
+            rowIndex,
+            cellIndex,
+            childIndex,
+            paragraph: child,
+            paragraphStart: surfaceChild.from,
+          };
+        }
+      }
+    }
+
+    return "unsupported";
+  }
+
+  return null;
+}
+
+function selectionFallsWithinSurfaceRange(
+  selectionFrom: number,
+  selectionTo: number,
+  rangeFrom: number,
+  rangeTo: number,
+): boolean {
+  if (rangeFrom === rangeTo) {
+    return selectionFrom === rangeFrom && selectionTo === rangeTo;
+  }
+
+  return (
+    selectionFrom >= rangeFrom &&
+    selectionTo <= rangeTo &&
+    selectionFrom < rangeTo
+  );
+}
+
 function resolveRange(
   selection: SelectionSnapshot,
   storySize: number,

package/src/formats/xlsx/io/xlsx-session.ts

@@ -302,5 +302,5 @@ function convertCachedFormulaValue(
 // ---------------------------------------------------------------------------
 
 function decodePartBytes(bytes: Uint8Array): string {
-  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("utf8");
+  return new TextDecoder("utf-8").decode(bytes);
 }

package/src/io/docx-session.ts

@@ -1733,7 +1733,7 @@ function decodeUtf8(bytes: Uint8Array | undefined): string {
     return "";
   }
 
-  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("utf8");
+  return new TextDecoder("utf-8").decode(bytes);
 }
 
 function toUint8Array(bytes: Uint8Array | ArrayBuffer): Uint8Array {

package/src/io/export/serialize-tables.ts

@@ -6,6 +6,7 @@ import type {
   ParsedTableBorders,
   ParsedTableCell,
   ParsedTableCellBorders,
+  ParsedTableLook,
   ParsedTableRow,
   ParsedTableWidth,
 } from "../ooxml/parse-tables.ts";
@@ -36,6 +37,9 @@ function serializeCell(cell: ParsedTableCell): string {
 
 function buildTablePropertiesXml(table: ParsedTable): string {
   const children: string[] = [];
+  if (table.styleId) {
+    children.push(`<w:tblStyle w:val="${table.styleId}"/>`);
+  }
   if (table.width) {
     children.push(serializeWidth("tblW", table.width));
   }
@@ -50,6 +54,10 @@ function buildTablePropertiesXml(table: ParsedTable): string {
     const marginsXml = serializeTableCellMargins(table.cellMargins);
     if (marginsXml) children.push(`<w:tblCellMar>${marginsXml}</w:tblCellMar>`);
   }
+  if (table.tblLook) {
+    const tblLookXml = serializeTableLook(table.tblLook);
+    if (tblLookXml) children.push(tblLookXml);
+  }
   return children.length > 0 ? `<w:tblPr>${children.join("")}</w:tblPr>` : "";
 }
 
@@ -128,6 +136,25 @@ function serializeCellBorders(borders: ParsedTableCellBorders): string {
     .join("");
 }
 
+function serializeTableLook(tblLook: ParsedTableLook): string {
+  const attrs: string[] = [];
+  if (tblLook.val) attrs.push(`w:val="${tblLook.val}"`);
+  for (const [key, attr] of [
+    ["firstRow", "w:firstRow"],
+    ["lastRow", "w:lastRow"],
+    ["firstColumn", "w:firstColumn"],
+    ["lastColumn", "w:lastColumn"],
+    ["noHBand", "w:noHBand"],
+    ["noVBand", "w:noVBand"],
+  ] as const) {
+    const value = tblLook[key];
+    if (value !== undefined) {
+      attrs.push(`${attr}="${value ? "1" : "0"}"`);
+    }
+  }
+  return attrs.length > 0 ? `<w:tblLook ${attrs.join(" ")}/>` : "";
+}
+
 function serializeCellShading(shading: ParsedCellShading): string {
   const attrs: string[] = [];
   if (shading.val) attrs.push(`w:val="${shading.val}"`);

package/src/io/ooxml/parse-tables.ts

@@ -59,12 +59,23 @@ export interface ParsedCellMargins {
   right?: number;
 }
 
+export interface ParsedTableLook {
+  val?: string;
+  firstRow?: boolean;
+  lastRow?: boolean;
+  firstColumn?: boolean;
+  lastColumn?: boolean;
+  noHBand?: boolean;
+  noVBand?: boolean;
+}
+
 export interface ParsedTableDocument {
   tables: ParsedTable[];
 }
 
 export interface ParsedTable {
   type: "table";
+  styleId?: string;
   propertiesXml?: string;
   gridColumns: number[];
   rows: ParsedTableRow[];
@@ -73,6 +84,7 @@ export interface ParsedTable {
   alignment?: "left" | "center" | "right";
   borders?: ParsedTableBorders;
   cellMargins?: ParsedCellMargins;
+  tblLook?: ParsedTableLook;
 }
 
 export interface ParsedTableRow {
@@ -115,13 +127,16 @@ function parseTable(node: XmlElementNode, sourceXml: string): ParsedTable {
     .filter((child): child is XmlElementNode => child.type === "element" && localName(child.name) === "tr")
     .map((rowNode) => parseRow(rowNode, sourceXml));
 
+  const styleId = propertiesNode ? readTableStyleId(propertiesNode) : undefined;
   const width = propertiesNode ? readTableWidth(propertiesNode) : undefined;
   const alignment = propertiesNode ? readTableAlignment(propertiesNode) : undefined;
   const borders = propertiesNode ? readTableBorders(propertiesNode) : undefined;
   const cellMargins = propertiesNode ? readTableCellMargins(propertiesNode) : undefined;
+  const tblLook = propertiesNode ? readTableLook(propertiesNode) : undefined;
 
   return {
     type: "table",
+    ...(styleId ? { styleId } : {}),
     ...(propertiesNode ? { propertiesXml: sourceXml.slice(propertiesNode.start, propertiesNode.end) } : {}),
     gridColumns: gridNode ? readGridColumns(gridNode) : [],
     rows,
@@ -130,6 +145,7 @@ function parseTable(node: XmlElementNode, sourceXml: string): ParsedTable {
     ...(alignment ? { alignment } : {}),
     ...(borders ? { borders } : {}),
     ...(cellMargins ? { cellMargins } : {}),
+    ...(tblLook ? { tblLook } : {}),
   };
 }
 
@@ -493,6 +509,40 @@ function readTableAlignment(propertiesNode: XmlElementNode): "left" | "center" |
   return undefined;
 }
 
+function readTableStyleId(propertiesNode: XmlElementNode): string | undefined {
+  const styleNode = findFirstChild(propertiesNode, "tblStyle");
+  if (!styleNode) return undefined;
+  return styleNode.attributes["w:val"] ?? styleNode.attributes.val;
+}
+
+function readTableLook(propertiesNode: XmlElementNode): ParsedTableLook | undefined {
+  const tblLookNode = findFirstChild(propertiesNode, "tblLook");
+  if (!tblLookNode) return undefined;
+
+  const tableLook: ParsedTableLook = {};
+  const val = tblLookNode.attributes["w:val"] ?? tblLookNode.attributes.val;
+  if (val) {
+    tableLook.val = val;
+  }
+
+  for (const [attribute, key] of [
+    ["w:firstRow", "firstRow"],
+    ["w:lastRow", "lastRow"],
+    ["w:firstColumn", "firstColumn"],
+    ["w:lastColumn", "lastColumn"],
+    ["w:noHBand", "noHBand"],
+    ["w:noVBand", "noVBand"],
+  ] as const) {
+    const fallback = attribute.replace("w:", "");
+    const raw = tblLookNode.attributes[attribute] ?? tblLookNode.attributes[fallback];
+    if (raw !== undefined) {
+      tableLook[key] = raw !== "0" && raw !== "false" && raw !== "off";
+    }
+  }
+
+  return Object.keys(tableLook).length > 0 ? tableLook : undefined;
+}
+
 function readTableBorders(propertiesNode: XmlElementNode): ParsedTableBorders | undefined {
   const bordersNode = findFirstChild(propertiesNode, "tblBorders");
   if (!bordersNode) return undefined;

package/src/io/opc/package-reader.ts

@@ -1,4 +1,4 @@
-import { inflateRawSync } from "fflate";
+import { inflateSync } from "fflate";
 
 import {
   CONTENT_TYPES_PATH,
@@ -184,7 +184,7 @@ function readZipEntry(archive: Uint8Array, entry: ZipCentralDirectoryEntry): Uin
     case "store":
       return new Uint8Array(compressed);
     case "deflate":
-      return inflateRawSync(compressed);
+      return inflateSync(compressed);
     default:
       throw new Error(`Unsupported ZIP compression for ${entry.path}.`);
   }

package/src/runtime/table-commands.ts

@@ -11,6 +11,7 @@
 
 import type { Command as PMCommand, EditorState } from "prosemirror-state";
 import {
+  TableMap,
   addColumnAfter as pmAddColumnAfter,
   addColumnBefore as pmAddColumnBefore,
   addRowAfter as pmAddRowAfter,
@@ -48,8 +49,14 @@ function withTableGuard(
   command: PMCommand,
 ): PMCommand {
   return (state, dispatch, view) => {
-    if (!canRun(state)) return false;
-    return command(state, dispatch, view);
+    try {
+      if (!canRun(state)) {
+        return false;
+      }
+      return command(state, dispatch, view);
+    } catch {
+      return false;
+    }
   };
 }
 
@@ -72,7 +79,7 @@ export const addColumnAfter: PMCommand = (state, dispatch, view) =>
 
 export const deleteColumn: PMCommand = withTableGuard((state) => {
   const table = tableAtSelection(state);
-  return table !== null && table.childCount > 0 && table.firstChild !== null && table.firstChild.childCount > 1;
+  return table !== null && TableMap.get(table).width > 1;
 }, pmDeleteColumn);
 
 export {

package/src/runtime/table-schema.ts

@@ -11,6 +11,14 @@
 
 import type { NodeSpec } from "prosemirror-model";
 
+type TableCellAttrs = {
+  colspan?: number | null;
+  rowspan?: number | null;
+  colwidth?: number[] | null;
+  gridSpan?: number | null;
+  verticalMerge?: "restart" | "continue" | null;
+};
+
 function resolveRenderedColspan(attrs: {
   colspan?: number | null;
   gridSpan?: number | null;
@@ -24,6 +32,93 @@ function resolveRenderedColspan(attrs: {
   return 1;
 }
 
+function resolveRenderedRowspan(attrs: { rowspan?: number | null }): number {
+  return typeof attrs.rowspan === "number" && attrs.rowspan > 1 ? attrs.rowspan : 1;
+}
+
+function parseColwidthAttr(dom: HTMLElement, colspan: number): number[] | null {
+  const widthAttr = dom.getAttribute("data-colwidth");
+  if (!widthAttr || !/^\d+(,\d+)*$/.test(widthAttr)) {
+    return null;
+  }
+
+  const widths = widthAttr.split(",").map((value) => Number.parseInt(value, 10));
+  return widths.length === colspan ? widths : null;
+}
+
+function getCellAttrs(dom: HTMLElement): TableCellAttrs {
+  const colspan = Number(dom.getAttribute("colspan") || 1);
+  const rowspan = Number(dom.getAttribute("rowspan") || 1);
+  const gridSpanAttr = dom.getAttribute("data-grid-span");
+  const verticalMergeAttr = dom.getAttribute("data-vertical-merge");
+  const gridSpan = gridSpanAttr ? Number.parseInt(gridSpanAttr, 10) : colspan;
+
+  return {
+    colspan,
+    rowspan,
+    colwidth: parseColwidthAttr(dom, colspan),
+    gridSpan: Number.isFinite(gridSpan) && gridSpan > 0 ? gridSpan : colspan,
+    verticalMerge:
+      verticalMergeAttr === "restart" || verticalMergeAttr === "continue"
+        ? verticalMergeAttr
+        : null,
+  };
+}
+
+function setCellDomAttrs(nodeAttrs: TableCellAttrs, className: string): Record<string, string> {
+  const attrs: Record<string, string> = { class: className };
+  const colspan = resolveRenderedColspan(nodeAttrs);
+  const rowspan = resolveRenderedRowspan(nodeAttrs);
+
+  if (colspan > 1) {
+    attrs.colspan = String(colspan);
+  }
+  if (rowspan > 1) {
+    attrs.rowspan = String(rowspan);
+  }
+  if (nodeAttrs.colwidth && nodeAttrs.colwidth.length > 0) {
+    attrs["data-colwidth"] = nodeAttrs.colwidth.join(",");
+  }
+  if (typeof nodeAttrs.gridSpan === "number" && nodeAttrs.gridSpan > 1) {
+    attrs["data-grid-span"] = String(nodeAttrs.gridSpan);
+  }
+  if (nodeAttrs.verticalMerge) {
+    attrs["data-vertical-merge"] = nodeAttrs.verticalMerge;
+  }
+
+  return attrs;
+}
+
+function validateColwidth(value: unknown): void {
+  if (value === null) {
+    return;
+  }
+  if (!Array.isArray(value)) {
+    throw new TypeError("colwidth must be null or an array");
+  }
+  for (const item of value) {
+    if (typeof item !== "number") {
+      throw new TypeError("colwidth must be null or an array of numbers");
+    }
+  }
+}
+
+function validateVerticalMerge(value: unknown): void {
+  if (value === null || value === "restart" || value === "continue") {
+    return;
+  }
+  throw new TypeError("verticalMerge must be null, 'restart', or 'continue'");
+}
+
+const tableCellSpecAttrs = {
+  propertiesXml: { default: null },
+  gridSpan: { default: 1, validate: "number" },
+  verticalMerge: { default: null, validate: validateVerticalMerge },
+  colspan: { default: 1, validate: "number" },
+  rowspan: { default: 1, validate: "number" },
+  colwidth: { default: null, validate: validateColwidth },
+} as const;
+
 export const tableNodeSpec: NodeSpec = {
   content: "table_row+",
   tableRole: "table",
@@ -56,35 +151,24 @@ export const tableCellNodeSpec: NodeSpec = {
   content: "paragraph+",
   tableRole: "cell",
   isolating: true,
-  attrs: {
-    propertiesXml: { default: null },
-    gridSpan: { default: 1 },
-    verticalMerge: { default: null },
-    colspan: { default: 1 },
-    rowspan: { default: 1 },
-    colwidth: { default: null },
-  },
+  attrs: tableCellSpecAttrs,
   parseDOM: [
     {
       tag: "td",
-      getAttrs(dom: HTMLElement) {
-        const colspan = dom.getAttribute("colspan");
-        const rowspan = dom.getAttribute("rowspan");
-        return {
-          colspan: colspan ? Number.parseInt(colspan, 10) : 1,
-          rowspan: rowspan ? Number.parseInt(rowspan, 10) : 1,
-        };
+      getAttrs(dom) {
+        if (!(dom instanceof HTMLElement)) {
+          return false;
+        }
+        return getCellAttrs(dom);
       },
     },
   ],
   toDOM(node) {
-    const attrs: Record<string, string> = {
-      class: "border border-primary/20 p-2 align-top",
-    };
-    const colspan = resolveRenderedColspan(node.attrs as { colspan?: number; gridSpan?: number });
-    if (colspan > 1) attrs.colspan = String(colspan);
-    if (node.attrs.rowspan > 1) attrs.rowspan = String(node.attrs.rowspan);
-    return ["td", attrs, 0];
+    return [
+      "td",
+      setCellDomAttrs(node.attrs as TableCellAttrs, "border border-primary/20 p-2 align-top"),
+      0,
+    ];
   },
 };
 
@@ -92,35 +176,27 @@ export const tableHeaderCellNodeSpec: NodeSpec = {
   content: "paragraph+",
   tableRole: "header_cell",
   isolating: true,
-  attrs: {
-    propertiesXml: { default: null },
-    gridSpan: { default: 1 },
-    verticalMerge: { default: null },
-    colspan: { default: 1 },
-    rowspan: { default: 1 },
-    colwidth: { default: null },
-  },
+  attrs: tableCellSpecAttrs,
   parseDOM: [
     {
       tag: "th",
-      getAttrs(dom: HTMLElement) {
-        const colspan = dom.getAttribute("colspan");
-        const rowspan = dom.getAttribute("rowspan");
-        return {
-          colspan: colspan ? Number.parseInt(colspan, 10) : 1,
-          rowspan: rowspan ? Number.parseInt(rowspan, 10) : 1,
-        };
+      getAttrs(dom) {
+        if (!(dom instanceof HTMLElement)) {
+          return false;
+        }
+        return getCellAttrs(dom);
       },
     },
   ],
   toDOM(node) {
-    const attrs: Record<string, string> = {
-      class: "border border-primary/20 p-2 align-top font-semibold bg-surface-raised",
-    };
-    const colspan = resolveRenderedColspan(node.attrs as { colspan?: number; gridSpan?: number });
-    if (colspan > 1) attrs.colspan = String(colspan);
-    if (node.attrs.rowspan > 1) attrs.rowspan = String(node.attrs.rowspan);
-    return ["th", attrs, 0];
+    return [
+      "th",
+      setCellDomAttrs(
+        node.attrs as TableCellAttrs,
+        "border border-primary/20 p-2 align-top font-semibold bg-surface-raised",
+      ),
+      0,
+    ];
   },
 };
 

package/src/ui-tailwind/editor-surface/tw-table-node-view.tsx

@@ -2,17 +2,36 @@
  * ProseMirror NodeView implementations for table nodes.
  *
  * These NodeViews render table structure as proper HTML tables with
- * colspan/rowspan support for merged cells (from gridSpan/verticalMerge attrs).
- *
- * Usage with EditorView:
- *   new EditorView(mount, {
- *     nodeViews: tableNodeViews,
- *     ...
- *   })
+ * colspan/rowspan support for merged cells. Horizontal merges come
+ * directly from `colspan`/`gridSpan`. Vertical merges can be rendered
+ * from either explicit `rowspan` attrs or OOXML `verticalMerge`
+ * chains when upstream projection has not yet materialized row spans.
  */
 
 import type { Node as PMNode } from "prosemirror-model";
 
+const TABLE_LAYOUT_SYNC_EVENT = "pm-table-layout-sync";
+
+interface TableCellLayout {
+  cellIndex: number;
+  colSpan: number;
+  hidden: boolean;
+  rowSpan: number;
+}
+
+interface OpenVerticalMerge {
+  col: number;
+  colSpan: number;
+  continuedThisRow: boolean;
+  layout: TableCellLayout;
+}
+
+interface OpenExplicitRowSpan {
+  col: number;
+  colSpan: number;
+  remainingRows: number;
+}
+
 function resolveRenderedColspan(node: PMNode): number {
   const colspan = node.attrs.colspan as number | undefined;
   if (typeof colspan === "number" && colspan > 1) {
@@ -27,6 +46,166 @@ function resolveRenderedColspan(node: PMNode): number {
   return 1;
 }
 
+function resolveRenderedRowspan(node: PMNode): number {
+  const rowspan = node.attrs.rowspan as number | undefined;
+  return typeof rowspan === "number" && rowspan > 1 ? rowspan : 1;
+}
+
+function readVerticalMerge(node: PMNode): "restart" | "continue" | null {
+  const value = node.attrs.verticalMerge;
+  return value === "restart" || value === "continue" ? value : null;
+}
+
+function isColumnCoveredBySpan(spans: readonly OpenExplicitRowSpan[], column: number): boolean {
+  return spans.some(
+    (span) => column >= span.col && column < span.col + span.colSpan,
+  );
+}
+
+function findVerticalMergeOwner(
+  openVerticalMerges: readonly OpenVerticalMerge[],
+  column: number,
+  colSpan: number,
+): OpenVerticalMerge | null {
+  const matchingByWidth = openVerticalMerges.find(
+    (merge) => merge.col >= column && merge.colSpan === colSpan,
+  );
+  if (matchingByWidth) {
+    return matchingByWidth;
+  }
+
+  return openVerticalMerges.find((merge) => merge.col >= column) ?? null;
+}
+
+function computeTableLayout(tableNode: PMNode): TableCellLayout[][] {
+  const rowLayouts: TableCellLayout[][] = [];
+  const openVerticalMerges: OpenVerticalMerge[] = [];
+  const openExplicitRowSpans: OpenExplicitRowSpan[] = [];
+
+  for (let rowIndex = 0; rowIndex < tableNode.childCount; rowIndex += 1) {
+    for (const merge of openVerticalMerges) {
+      merge.continuedThisRow = false;
+    }
+
+    const rowNode = tableNode.child(rowIndex);
+    const layoutRow: TableCellLayout[] = [];
+    let column = 0;
+
+    for (let cellIndex = 0; cellIndex < rowNode.childCount; cellIndex += 1) {
+      const cellNode = rowNode.child(cellIndex);
+      const colSpan = resolveRenderedColspan(cellNode);
+      const explicitRowSpan = resolveRenderedRowspan(cellNode);
+      const verticalMerge = readVerticalMerge(cellNode);
+
+      if (verticalMerge === "continue") {
+        const owner = findVerticalMergeOwner(openVerticalMerges, column, colSpan);
+        if (owner) {
+          owner.layout.rowSpan += 1;
+          owner.continuedThisRow = true;
+          layoutRow.push({
+            cellIndex,
+            colSpan,
+            hidden: true,
+            rowSpan: 1,
+          });
+          column = owner.col + owner.colSpan;
+          continue;
+        }
+      }
+
+      while (isColumnCoveredBySpan(openExplicitRowSpans, column)) {
+        column += 1;
+      }
+
+      const layout: TableCellLayout = {
+        cellIndex,
+        colSpan,
+        hidden: false,
+        rowSpan: explicitRowSpan,
+      };
+      layoutRow.push(layout);
+
+      if (verticalMerge === "restart") {
+        openVerticalMerges.push({
+          col: column,
+          colSpan,
+          continuedThisRow: true,
+          layout,
+        });
+      }
+
+      if (explicitRowSpan > 1) {
+        openExplicitRowSpans.push({
+          col: column,
+          colSpan,
+          remainingRows: explicitRowSpan - 1,
+        });
+      }
+
+      column += colSpan;
+    }
+
+    for (let index = openVerticalMerges.length - 1; index >= 0; index -= 1) {
+      if (!openVerticalMerges[index]?.continuedThisRow) {
+        openVerticalMerges.splice(index, 1);
+      }
+    }
+
+    for (let index = openExplicitRowSpans.length - 1; index >= 0; index -= 1) {
+      const span = openExplicitRowSpans[index];
+      if (!span) {
+        continue;
+      }
+      span.remainingRows -= 1;
+      if (span.remainingRows <= 0) {
+        openExplicitRowSpans.splice(index, 1);
+      }
+    }
+
+    rowLayouts.push(layoutRow);
+  }
+
+  return rowLayouts;
+}
+
+function syncRenderedTableLayout(tableBody: HTMLTableSectionElement, tableNode: PMNode): void {
+  const rowLayouts = computeTableLayout(tableNode);
+  const rowElements = Array.from(tableBody.rows);
+
+  for (let rowIndex = 0; rowIndex < rowLayouts.length; rowIndex += 1) {
+    const rowLayout = rowLayouts[rowIndex];
+    const rowElement = rowElements[rowIndex];
+    if (!rowLayout || !rowElement) {
+      continue;
+    }
+
+    const cellElements = Array.from(rowElement.cells);
+    for (const cellLayout of rowLayout) {
+      const element = cellElements[cellLayout.cellIndex];
+      if (!element) {
+        continue;
+      }
+
+      element.colSpan = cellLayout.colSpan > 1 ? cellLayout.colSpan : 1;
+      element.rowSpan = cellLayout.hidden ? 1 : cellLayout.rowSpan > 1 ? cellLayout.rowSpan : 1;
+      element.style.display = cellLayout.hidden ? "none" : "";
+
+      if (cellLayout.hidden) {
+        element.setAttribute("aria-hidden", "true");
+        element.setAttribute("data-vertical-merge-hidden", "true");
+      } else {
+        element.removeAttribute("aria-hidden");
+        element.removeAttribute("data-vertical-merge-hidden");
+      }
+    }
+  }
+}
+
+function requestTableLayoutSync(start: HTMLElement): void {
+  const table = start.closest("[data-pm-table-root='true']");
+  table?.dispatchEvent(new Event(TABLE_LAYOUT_SYNC_EVENT));
+}
+
 /**
  * NodeView for the table node.
  * Renders as <table><tbody>...</tbody></table>.
@@ -34,17 +213,57 @@ function resolveRenderedColspan(node: PMNode): number {
  */
 export class TableNodeView {
   dom: HTMLElement;
-  contentDOM: HTMLElement;
+  contentDOM: HTMLTableSectionElement;
+  private node: PMNode;
+  private syncQueued = false;
+  private readonly onSyncRequest: EventListener;
+
+  constructor(node: PMNode) {
+    this.node = node;
 
-  constructor(_node: PMNode) {
     const table = document.createElement("table");
     table.className = "border-collapse w-full my-2 text-sm";
+    table.setAttribute("data-pm-table-root", "true");
 
     const tbody = document.createElement("tbody");
     table.appendChild(tbody);
 
     this.dom = table;
     this.contentDOM = tbody;
+    this.onSyncRequest = () => {
+      this.scheduleLayoutSync();
+    };
+    this.dom.addEventListener(TABLE_LAYOUT_SYNC_EVENT, this.onSyncRequest);
+    this.scheduleLayoutSync();
+  }
+
+  update(node: PMNode): boolean {
+    if (node.type !== this.node.type) {
+      return false;
+    }
+
+    this.node = node;
+    this.scheduleLayoutSync();
+    return true;
+  }
+
+  destroy(): void {
+    this.dom.removeEventListener(TABLE_LAYOUT_SYNC_EVENT, this.onSyncRequest);
+  }
+
+  ignoreMutation(record: MutationRecord): boolean {
+    return record.type === "attributes" && record.target === this.dom;
+  }
+
+  private scheduleLayoutSync(): void {
+    if (this.syncQueued) {
+      return;
+    }
+    this.syncQueued = true;
+    queueMicrotask(() => {
+      this.syncQueued = false;
+      syncRenderedTableLayout(this.contentDOM, this.node);
+    });
   }
 }
 
@@ -66,8 +285,8 @@ export class TableRowNodeView {
 /**
  * NodeView for table_cell and table_header_cell nodes.
  *
- * Applies colspan/rowspan from node attrs (mapped from gridSpan/verticalMerge
- * in the OOXML model). Distinguishes header cells by tableRole spec attribute.
+ * Applies colspan immediately and defers final rowspan/vertical-merge
+ * layout to the owning table node view.
  */
 export class TableCellNodeView {
   dom: HTMLElement;
@@ -82,9 +301,13 @@ export class TableCellNodeView {
       : "border border-primary/20 p-2 align-top";
 
     const colspan = resolveRenderedColspan(node);
-    const rowspan = node.attrs.rowspan as number;
-    if (colspan > 1) (cell as HTMLTableCellElement).colSpan = colspan;
-    if (rowspan > 1) (cell as HTMLTableCellElement).rowSpan = rowspan;
+    const rowspan = resolveRenderedRowspan(node);
+    if (colspan > 1) {
+      (cell as HTMLTableCellElement).colSpan = colspan;
+    }
+    if (rowspan > 1) {
+      (cell as HTMLTableCellElement).rowSpan = rowspan;
+    }
 
     this.dom = cell;
     this.contentDOM = cell;
@@ -97,15 +320,25 @@ export class TableCellNodeView {
   update(node: PMNode): boolean {
     const isHeader = (node.type.spec as { tableRole?: string }).tableRole === "header_cell";
     const expectedTag = isHeader ? "TH" : "TD";
-    if (this.dom.tagName !== expectedTag) return false;
+    if (this.dom.tagName !== expectedTag) {
+      return false;
+    }
 
     const colspan = resolveRenderedColspan(node);
-    const rowspan = node.attrs.rowspan as number;
+    const rowspan = resolveRenderedRowspan(node);
     const cell = this.dom as HTMLTableCellElement;
     cell.colSpan = colspan > 1 ? colspan : 1;
     cell.rowSpan = rowspan > 1 ? rowspan : 1;
+    cell.style.display = "";
+    cell.removeAttribute("aria-hidden");
+    cell.removeAttribute("data-vertical-merge-hidden");
+    requestTableLayoutSync(this.dom);
     return true;
   }
+
+  ignoreMutation(record: MutationRecord): boolean {
+    return record.type === "attributes" && record.target === this.dom;
+  }
 }
 
 /**

package/src/ui-tailwind/theme/editor-theme.css

@@ -6,7 +6,7 @@
  * individual variables in your own stylesheet for custom themes.
  *
  * Usage:
- *   @import "@docx-react-component/ui-tailwind/theme/editor-theme.css";
+ *   @import "@beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css";
  *
  * Custom theme:
  *   .my-brand { --color-accent: #8b5cf6; }