@beyondwork/docx-react-component 1.0.0

package/src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts

@@ -0,0 +1,327 @@
+import { Fragment, type Node as PMNode } from "prosemirror-model";
+import { EditorState, type Plugin, TextSelection } from "prosemirror-state";
+
+import type {
+  EditorSurfaceSnapshot,
+  SelectionSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+  SurfaceTableRowSnapshot,
+  SurfaceTableCellSnapshot,
+} from "../../api/public-types";
+import { editorSchema } from "./pm-schema";
+import { buildPositionMap, type PositionMap } from "./pm-position-map";
+
+export interface PMStateResult {
+  state: EditorState;
+  positionMap: PositionMap;
+}
+
+/**
+ * Create a ProseMirror EditorState from a runtime surface snapshot.
+ *
+ * The PM document mirrors the snapshot for rendering and input.
+ * It is NOT the canonical source — the runtime owns that.
+ */
+export function createPMStateFromSnapshot(
+  surface: EditorSurfaceSnapshot,
+  selection: SelectionSnapshot,
+  plugins: Plugin[],
+): PMStateResult {
+  const doc = buildPMDoc(surface);
+  const positionMap = buildPositionMap(surface);
+
+  // Convert runtime selection to PM selection
+  const pmAnchor = clamp(
+    positionMap.runtimeToPm(selection.anchor),
+    1,
+    positionMap.pmDocSize - 1,
+  );
+  const pmHead = clamp(
+    positionMap.runtimeToPm(selection.head),
+    1,
+    positionMap.pmDocSize - 1,
+  );
+
+  let pmSelection: TextSelection;
+  try {
+    pmSelection = TextSelection.create(doc, pmAnchor, pmHead);
+  } catch {
+    // If the position is invalid (e.g., inside an atom), fall back to start
+    pmSelection = TextSelection.create(doc, 1);
+  }
+
+  const state = EditorState.create({
+    doc,
+    selection: pmSelection,
+    plugins,
+  });
+
+  return { state, positionMap };
+}
+
+function buildPMDoc(surface: EditorSurfaceSnapshot): PMNode {
+  const blocks: PMNode[] = [];
+
+  for (const block of surface.blocks) {
+    if (block.kind === "paragraph") {
+      blocks.push(buildParagraph(block));
+    } else if (block.kind === "table") {
+      blocks.push(buildTable(block));
+    } else if (block.kind === "sdt_block") {
+      blocks.push(buildSdtBlock(block));
+    } else {
+      blocks.push(buildOpaqueBlock(block));
+    }
+  }
+
+  // Ensure at least one block (PM requires non-empty doc)
+  if (blocks.length === 0) {
+    blocks.push(editorSchema.nodes.paragraph.create());
+  }
+
+  return editorSchema.nodes.doc.create(null, Fragment.from(blocks));
+}
+
+function buildParagraph(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): PMNode {
+  const content: PMNode[] = [];
+
+  for (const segment of block.segments) {
+    const nodes = buildInlineContent(segment);
+    content.push(...nodes);
+  }
+
+  return editorSchema.nodes.paragraph.create(
+    {
+      styleId: block.styleId ?? null,
+      numberingInstanceId: block.numbering?.numberingInstanceId ?? null,
+      numberingLevel: block.numbering?.level ?? null,
+    },
+    content.length > 0 ? Fragment.from(content) : undefined,
+  );
+}
+
+function buildInlineContent(segment: SurfaceInlineSegment): PMNode[] {
+  switch (segment.kind) {
+    case "text": {
+      if (!segment.text) return [];
+
+      // Build PM marks from segment marks
+      let marks = editorSchema.marks.bold.isInSet([])
+        ? [] // shouldn't happen, just type safety
+        : [];
+
+      const pmMarks = [];
+      if (segment.marks) {
+        for (const mark of segment.marks) {
+          const pmMark = editorSchema.marks[mark];
+          if (pmMark) {
+            pmMarks.push(pmMark.create());
+          }
+        }
+      }
+      if (segment.hyperlinkHref) {
+        pmMarks.push(editorSchema.marks.link.create({ href: segment.hyperlinkHref }));
+      }
+
+      return [editorSchema.text(segment.text, pmMarks.length > 0 ? pmMarks : undefined)];
+    }
+
+    case "hard_break":
+      return [editorSchema.nodes.hard_break.create()];
+
+    case "tab":
+      return [editorSchema.nodes.tab_char.create()];
+
+    case "image":
+      return [
+        editorSchema.nodes.image_atom.create({
+          mediaId: segment.mediaId,
+          altText: segment.altText ?? null,
+          state: segment.state,
+          display: segment.display ?? "inline",
+          detail: segment.detail ?? null,
+        }),
+      ];
+
+    case "opaque_inline":
+      return [buildOpaqueInlineOrComplexAtom(segment)];
+
+    default:
+      return [];
+  }
+}
+
+function buildTable(
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
+): PMNode {
+  const rows: PMNode[] = [];
+  for (const row of block.rows) {
+    const cells: PMNode[] = [];
+    for (const cell of row.cells) {
+      const cellContent: PMNode[] = [];
+      for (const child of cell.content) {
+        if (child.kind === "paragraph") {
+          cellContent.push(buildParagraph(child as Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>));
+        } else if (child.kind === "table") {
+          cellContent.push(buildNestedTablePlaceholder(child as Extract<SurfaceBlockSnapshot, { kind: "table" }>));
+        } else if (child.kind === "sdt_block") {
+          cellContent.push(buildOpaqueBlock({
+            blockId: child.blockId,
+            kind: "opaque_block",
+            from: child.from,
+            to: child.to,
+            fragmentId: child.blockId,
+            warningId: child.blockId,
+            label: child.alias ?? child.tag ?? "Content control",
+            detail: "Structured content control remains read-only inside table cells.",
+            state: "locked-preserve-only",
+          }));
+        } else if (child.kind === "opaque_block") {
+          cellContent.push(buildOpaqueBlock(child as Extract<SurfaceBlockSnapshot, { kind: "opaque_block" }>));
+        }
+      }
+      // Ensure at least one paragraph in cell (PM requires non-empty)
+      if (cellContent.length === 0) {
+        cellContent.push(editorSchema.nodes.paragraph.create());
+      }
+      cells.push(
+        editorSchema.nodes.table_cell.create(
+          {
+            colspan: cell.colspan,
+            rowspan: cell.rowspan,
+            gridSpan: cell.gridSpan,
+            verticalMerge: cell.verticalMerge,
+          },
+          Fragment.from(cellContent),
+        ),
+      );
+    }
+    rows.push(editorSchema.nodes.table_row.create(null, Fragment.from(cells)));
+  }
+  return editorSchema.nodes.table.create(
+    {
+      styleId: block.styleId ?? null,
+      gridColumns: block.gridColumns,
+    },
+    Fragment.from(rows),
+  );
+}
+
+function buildNestedTablePlaceholder(
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
+): PMNode {
+  return buildOpaqueBlock({
+    blockId: block.blockId,
+    kind: "opaque_block",
+    from: block.from,
+    to: block.to,
+    fragmentId: block.blockId,
+    warningId: block.blockId,
+    label: "Nested table",
+    detail: "Nested table remains read-only in the live ProseMirror cell surface.",
+    state: "locked-preserve-only",
+  });
+}
+
+function buildSdtBlock(
+  block: Extract<SurfaceBlockSnapshot, { kind: "sdt_block" }>,
+): PMNode {
+  const children = block.children.map((child) => {
+    if (child.kind === "paragraph") {
+      return buildParagraph(child);
+    }
+    if (child.kind === "table") {
+      return buildTable(child);
+    }
+    if (child.kind === "sdt_block") {
+      return buildSdtBlock(child);
+    }
+    return buildOpaqueBlock(child);
+  });
+
+  if (children.length === 0) {
+    children.push(editorSchema.nodes.paragraph.create());
+  }
+
+  return editorSchema.nodes.sdt_block.create(
+    {
+      sdtType: block.sdtType ?? null,
+      alias: block.alias ?? null,
+      tag: block.tag ?? null,
+      lock: block.lock ?? null,
+    },
+    Fragment.from(children),
+  );
+}
+
+/**
+ * Map an opaque_inline surface segment to a dedicated complex-rendering PM atom
+ * node when the label identifies a known complex content type, or fall back to
+ * the generic opaque_inline node.
+ */
+function buildOpaqueInlineOrComplexAtom(
+  segment: Extract<import("../../api/public-types").SurfaceInlineSegment, { kind: "opaque_inline" }>,
+): PMNode {
+  const label = segment.label;
+  const detail = segment.detail;
+
+  if (label === "Chart") {
+    return editorSchema.nodes.chart_atom.create({ detail });
+  }
+  if (label === "SmartArt") {
+    return editorSchema.nodes.smartart_atom.create({ detail });
+  }
+  if (label === "Shape") {
+    // Extract text hint from detail if present
+    const textMatch = /Text: "([^"]+)"/.exec(detail);
+    const geometryMatch = /Geometry: ([^.]+)\./.exec(detail);
+    return editorSchema.nodes.shape_atom.create({
+      text: textMatch ? textMatch[1] : null,
+      geometry: geometryMatch ? geometryMatch[1] : null,
+      detail,
+    });
+  }
+  if (label === "WordArt") {
+    const textMatch = /Text: "([^"]+)"/.exec(detail);
+    const effectMatch = /Effect: ([^.]+)\./.exec(detail);
+    return editorSchema.nodes.wordart_atom.create({
+      text: textMatch ? textMatch[1] : "",
+      geometry: effectMatch ? effectMatch[1] : null,
+      detail,
+    });
+  }
+  if (label === "VML shape") {
+    const textMatch = /Text: "([^"]+)"/.exec(detail);
+    const typeMatch = /Type: ([^.]+)\./.exec(detail);
+    return editorSchema.nodes.vml_atom.create({
+      text: textMatch ? textMatch[1] : null,
+      shapeType: typeMatch ? typeMatch[1] : null,
+      detail,
+    });
+  }
+
+  return editorSchema.nodes.opaque_inline.create({
+    fragmentId: segment.fragmentId,
+    warningId: segment.warningId,
+    label,
+    detail,
+  });
+}
+
+function buildOpaqueBlock(
+  block: Extract<SurfaceBlockSnapshot, { kind: "opaque_block" }>,
+): PMNode {
+  return editorSchema.nodes.opaque_block.create({
+    fragmentId: block.fragmentId,
+    warningId: block.warningId,
+    label: block.label,
+    detail: block.detail,
+  });
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}

package/src/ui-tailwind/editor-surface/search-plugin.ts

@@ -0,0 +1,157 @@
+/**
+ * ProseMirror search/highlight plugin for the editor surface.
+ *
+ * Provides in-document search with optional case sensitivity and regex support.
+ * Matched ranges are shown as inline decorations with a configurable highlight color.
+ *
+ * Usage:
+ *   1. Include createSearchPlugin() in the editor plugin list.
+ *   2. Call performSearch(state, query, options) to compute matches.
+ *   3. Dispatch the results into the plugin state via searchPluginKey meta.
+ *   4. Call clearSearch(state, dispatch) to remove all highlights.
+ */
+
+import { Plugin, PluginKey } from "prosemirror-state";
+import type { EditorState, Transaction } from "prosemirror-state";
+import { Decoration, DecorationSet } from "prosemirror-view";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface SearchResult {
+  from: number;
+  to: number;
+  text: string;
+  index: number;
+}
+
+export interface SearchOptions {
+  caseSensitive?: boolean;
+  regex?: boolean;
+  highlightColor?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin state
+// ---------------------------------------------------------------------------
+
+interface SearchPluginState {
+  results: SearchResult[];
+  highlightColor: string | null;
+}
+
+export const searchPluginKey = new PluginKey<SearchPluginState>("search");
+
+// ---------------------------------------------------------------------------
+// Plugin factory
+// ---------------------------------------------------------------------------
+
+export function createSearchPlugin(): Plugin<SearchPluginState> {
+  return new Plugin<SearchPluginState>({
+    key: searchPluginKey,
+
+    state: {
+      init(): SearchPluginState {
+        return { results: [], highlightColor: null };
+      },
+
+      apply(tr: Transaction, pluginState: SearchPluginState): SearchPluginState {
+        const meta = tr.getMeta(searchPluginKey) as SearchPluginState | undefined;
+        if (meta) return meta;
+        return pluginState;
+      },
+    },
+
+    props: {
+      decorations(state: EditorState): DecorationSet {
+        const pluginState = searchPluginKey.getState(state);
+        if (
+          !pluginState ||
+          pluginState.results.length === 0 ||
+          !pluginState.highlightColor
+        ) {
+          return DecorationSet.empty;
+        }
+
+        const decos = pluginState.results.map((r) =>
+          Decoration.inline(r.from, r.to, {
+            style: `background-color: ${pluginState.highlightColor}; border-radius: 2px;`,
+            class: "search-highlight",
+          }),
+        );
+
+        return DecorationSet.create(state.doc, decos);
+      },
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Search computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan all text nodes in the document for matches of `query`.
+ * Returns an array of match ranges; does not dispatch anything.
+ * To apply highlights, set the results on the plugin via:
+ *   view.dispatch(view.state.tr.setMeta(searchPluginKey, { results, highlightColor }))
+ */
+export function performSearch(
+  state: EditorState,
+  query: string,
+  options: SearchOptions = {},
+): SearchResult[] {
+  if (!query) return [];
+
+  const { caseSensitive = false, regex = false } = options;
+
+  let pattern: RegExp;
+  try {
+    if (regex) {
+      pattern = new RegExp(query, caseSensitive ? "g" : "gi");
+    } else {
+      const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      pattern = new RegExp(escaped, caseSensitive ? "g" : "gi");
+    }
+  } catch {
+    return [];
+  }
+
+  const results: SearchResult[] = [];
+
+  state.doc.descendants((node, pos) => {
+    if (!node.isText || !node.text) return;
+
+    let match: RegExpExecArray | null;
+    pattern.lastIndex = 0;
+    while ((match = pattern.exec(node.text)) !== null) {
+      results.push({
+        from: pos + match.index,
+        to: pos + match.index + match[0].length,
+        text: match[0],
+        index: results.length,
+      });
+    }
+  });
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Clear helper (ProseMirror Command signature)
+// ---------------------------------------------------------------------------
+
+/**
+ * ProseMirror command that clears all search highlights from the plugin state.
+ */
+export function clearSearch(
+  state: EditorState,
+  dispatch?: (tr: Transaction) => void,
+): boolean {
+  if (!dispatch) return true;
+  dispatch(
+    state.tr.setMeta(searchPluginKey, { results: [], highlightColor: null }),
+  );
+  return true;
+}

package/src/ui-tailwind/editor-surface/tw-caret.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+
+import type { SelectionSnapshot } from "../../api/public-types";
+
+export function renderTwCaret(selection: SelectionSnapshot, position: number) {
+  return selection.isCollapsed && selection.anchor === position ? (
+    <span
+      aria-hidden="true"
+      className="inline-block w-0.5 h-[1.2em] bg-accent rounded-full align-middle animate-wre-blink"
+    />
+  ) : null;
+}

package/src/ui-tailwind/editor-surface/tw-editor-surface.tsx

@@ -0,0 +1,150 @@
+import React, { type FocusEventHandler, useMemo } from "react";
+
+import type {
+  EditorUser,
+  RuntimeRenderSnapshot,
+  SelectionSnapshot,
+} from "../../api/public-types";
+import {
+  createCommentDecorationModel,
+  type MarkupDisplay,
+} from "../../ui/headless/comment-decoration-model";
+import { createRevisionDecorationModel } from "../../ui/headless/revision-decoration-model";
+import { createEditorKeyboardHandler } from "../../ui/headless/use-editor-keyboard";
+import { TwOpaqueBlock } from "./tw-opaque-block";
+import { TwParagraphBlock } from "./tw-paragraph-block";
+
+export interface TwEditorSurfaceProps {
+  currentUser: EditorUser;
+  snapshot: RuntimeRenderSnapshot;
+  reviewMode: "editing" | "review";
+  markupDisplay: MarkupDisplay;
+  activeRevisionId?: string;
+  /** When false, revision decorations are suppressed in the document surface. */
+  showTrackedChanges?: boolean;
+  onFocus: FocusEventHandler<HTMLDivElement>;
+  onBlur: FocusEventHandler<HTMLDivElement>;
+  onSelectionChange?: (selection: SelectionSnapshot) => void;
+  onInsertText?: (text: string) => void;
+  onDeleteBackward?: () => void;
+  onDeleteForward?: () => void;
+  onInsertTab?: () => void;
+  onInsertHardBreak?: () => void;
+  onSplitParagraph?: () => void;
+  onCommentActivated?: (commentId: string) => void;
+  onRevisionActivated?: (revisionId: string) => void;
+}
+
+export function TwEditorSurface(props: TwEditorSurfaceProps) {
+  const { currentUser, markupDisplay, onBlur, onFocus, snapshot } = props;
+  const surface = snapshot.surface;
+
+  const canEdit = Boolean(
+    surface && snapshot.isReady && !snapshot.readOnly && !snapshot.fatalError,
+  );
+
+  const commentDecorations = useMemo(
+    () => createCommentDecorationModel(snapshot.comments),
+    [snapshot.comments],
+  );
+
+  const showTrackedChanges = props.showTrackedChanges !== false;
+  const revisionDecorations = useMemo(
+    () => showTrackedChanges
+      ? createRevisionDecorationModel(snapshot.trackedChanges, props.activeRevisionId)
+      : undefined,
+    [snapshot.trackedChanges, props.activeRevisionId, showTrackedChanges],
+  );
+
+  const handleKeyDown = useMemo(() => {
+    if (!surface) return undefined;
+    return createEditorKeyboardHandler(
+      {
+        selection: snapshot.selection,
+        storySize: surface.storySize,
+        canEdit,
+      },
+      {
+        onSelectionChange: props.onSelectionChange,
+        onInsertText: props.onInsertText,
+        onDeleteBackward: props.onDeleteBackward,
+        onDeleteForward: props.onDeleteForward,
+        onInsertTab: props.onInsertTab,
+        onInsertHardBreak: props.onInsertHardBreak,
+        onSplitParagraph: props.onSplitParagraph,
+      },
+    );
+  }, [surface, snapshot.selection, canEdit, props]);
+
+  const fontClass = markupDisplay === "clean"
+    ? "font-[family-name:var(--font-legal-sans)]"
+    : "font-[family-name:var(--font-legal-serif)]";
+
+  return (
+    <section aria-label="Document canvas" className="min-w-0">
+      <div
+        aria-label="Document surface"
+        aria-multiline="true"
+        role="textbox"
+        tabIndex={0}
+        onFocus={onFocus}
+        onBlur={onBlur}
+        onKeyDown={handleKeyDown}
+        className={`bg-transparent border-none px-12 py-10 outline-offset-1 ${fontClass}`}
+      >
+        {/* Document header */}
+        <div className="flex justify-between gap-4 items-start mb-5">
+          <div>
+            <h1 className="font-[family-name:var(--font-legal-serif)] text-2xl leading-tight text-primary">
+              {snapshot.sourceLabel ?? "Document draft"}
+            </h1>
+            <p className="text-xs text-secondary mt-2">
+              {snapshot.sessionId} · {snapshot.documentStats.storyLength} chars
+            </p>
+          </div>
+          <span className="text-xs text-secondary whitespace-nowrap">
+            Reviewer {currentUser.displayName}
+          </span>
+        </div>
+
+        {/* Document blocks */}
+        <div className="space-y-4 pl-10 relative">
+          {surface ? (
+            surface.blocks.map((block) =>
+              block.kind === "paragraph" ? (
+                <TwParagraphBlock
+                  key={block.blockId}
+                  block={block}
+                  selection={snapshot.selection}
+                  markupDisplay={markupDisplay}
+                  commentDecorations={commentDecorations}
+                  revisionDecorations={revisionDecorations}
+                  onSelectionChange={props.onSelectionChange}
+                  onCommentActivated={props.onCommentActivated}
+                  onRevisionActivated={props.onRevisionActivated}
+                />
+              ) : (
+                <TwOpaqueBlock
+                  key={block.blockId}
+                  block={block}
+                  selection={snapshot.selection}
+                  onSelectionChange={props.onSelectionChange}
+                />
+              ),
+            )
+          ) : (
+            <p className="text-sm text-secondary leading-relaxed">
+              Loading the review surface. Compatibility cues and edit actions appear here once
+              the runtime snapshot is ready.
+            </p>
+          )}
+          {snapshot.fatalError ? (
+            <p className="text-sm text-danger">
+              Fatal runtime error: {snapshot.fatalError.message}
+            </p>
+          ) : null}
+        </div>
+      </div>
+    </section>
+  );
+}