@beyondwork/docx-react-component 1.0.2 → 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,9 +1,8 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
-  "packageManager": "pnpm@10.30.3",
   "type": "module",
   "files": [
     "README.md",
@@ -30,26 +29,10 @@
     "./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",
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "pnpm exec tsx --test $(find test -type f \\( -name '*.test.ts' -o -name '*.test.tsx' \\) | sort)",
-    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
-    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
-    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
-    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
-    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
-    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
-    "wave:launch:managed": "bash scripts/wave-launch.sh",
-    "wave:status": "bash scripts/wave-status.sh",
-    "wave:watch": "bash scripts/wave-watch.sh --follow",
-    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
-    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
-    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
-  },
   "keywords": [
     "docx",
     "word",
@@ -71,6 +54,7 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "fflate": "^0.8.2",
     "lucide-react": "^1.7.0"
   },
   "peerDependencies": {
@@ -82,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",
@@ -101,14 +86,21 @@
     "tsup": "^8.3.0",
     "tsx": "^4.21.0"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "sharp"
-    ],
-    "overrides": {
-      "react": "19.2.4",
-      "react-dom": "19.2.4"
-    }
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "pnpm exec tsx --test $(find test -type f \\( -name '*.test.ts' -o -name '*.test.tsx' \\) | sort)",
+    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
+    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
+    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
+    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
+    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
+    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
+    "wave:launch:managed": "bash scripts/wave-launch.sh",
+    "wave:status": "bash scripts/wave-status.sh",
+    "wave:watch": "bash scripts/wave-watch.sh --follow",
+    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
+    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
+    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
   }
 }

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}"`);