@beyondwork/docx-react-component 1.0.1 → 1.0.2

package/src/runtime/surface-projection.ts

@@ -0,0 +1,570 @@
+import type {
+  EditorSurfaceSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+  SurfaceTableCellSnapshot,
+  SurfaceTableRowSnapshot,
+} from "../api/public-types";
+import type {
+  CanonicalDocumentEnvelope,
+  SelectionSnapshot,
+} from "../core/state/editor-state.ts";
+import type {
+  BlockNode,
+  ChartPreviewNode,
+  DocumentRootNode,
+  InlineNode,
+  ParagraphNode,
+  SdtNode,
+  ShapeNode,
+  SmartArtPreviewNode,
+  TableNode,
+  TextMark,
+  VmlShapeNode,
+  WordArtNode,
+} from "../model/canonical-document.ts";
+import {
+  describeOpaqueFragment,
+  getOpaqueFragment,
+} from "../preservation/store.ts";
+
+interface ParagraphAccumulator {
+  blockId: string;
+  kind: "paragraph";
+  from: number;
+  to: number;
+  styleId?: string;
+  numbering?: ParagraphNode["numbering"];
+  segments: SurfaceInlineSegment[];
+}
+
+export function createEditorSurfaceSnapshot(
+  document: CanonicalDocumentEnvelope,
+  _selection: SelectionSnapshot,
+): EditorSurfaceSnapshot {
+  const root = normalizeDocumentRoot(document.content);
+  const blocks: SurfaceBlockSnapshot[] = [];
+  const lockedFragmentIds: string[] = [];
+  let cursor = 0;
+  const counters = {
+    paragraph: 0,
+    table: 0,
+    opaque: 0,
+    sdt: 0,
+    customXml: 0,
+    altChunk: 0,
+  };
+
+  for (let index = 0; index < root.children.length; index += 1) {
+    const surfaceBlock = createSurfaceBlock(root.children[index], document, cursor, counters);
+    blocks.push(surfaceBlock.block);
+    lockedFragmentIds.push(...surfaceBlock.lockedFragmentIds);
+    cursor = surfaceBlock.nextCursor;
+    if (index < root.children.length - 1 && root.children[index + 1]?.type === "paragraph") {
+      cursor += 1;
+    }
+  }
+
+  return {
+    storySize: cursor,
+    plainText: createPlainText(blocks),
+    blocks,
+    lockedFragmentIds,
+  };
+}
+
+function createSurfaceBlock(
+  block: BlockNode,
+  document: CanonicalDocumentEnvelope,
+  cursor: number,
+  counters: {
+    paragraph: number;
+    table: number;
+    opaque: number;
+    sdt: number;
+    customXml: number;
+    altChunk: number;
+  },
+): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
+  if (block.type === "opaque_block") {
+    const fragment = getOpaqueFragment(document.preservation as never, block.fragmentId);
+    const descriptor = fragment ? describeOpaqueFragment(fragment) : null;
+    const blockId = `opaque-${counters.opaque}`;
+    counters.opaque += 1;
+    return {
+      block: {
+        blockId,
+        kind: "opaque_block",
+        from: cursor,
+        to: cursor + 1,
+        fragmentId: block.fragmentId,
+        warningId: block.warningId,
+        label: descriptor?.label ?? "Unsupported OOXML fragment",
+        detail:
+          descriptor?.detail ??
+          "Locked whole-unit to keep unsupported OOXML intact through export.",
+        state: "locked-preserve-only",
+      },
+      lockedFragmentIds: [block.fragmentId],
+      nextCursor: cursor + 1,
+    };
+  }
+
+  if (block.type === "table") {
+    const tableIndex = counters.table;
+    counters.table += 1;
+    return createTableBlock(tableIndex, block, document, cursor, counters);
+  }
+
+  if (block.type === "sdt") {
+    const sdtIndex = counters.sdt;
+    counters.sdt += 1;
+    return createSdtBlock(sdtIndex, block, document, cursor, counters);
+  }
+
+  if (block.type === "custom_xml") {
+    const blockId = `custom-xml-${counters.customXml}`;
+    counters.customXml += 1;
+    return {
+      block: {
+        blockId,
+        kind: "opaque_block",
+        from: cursor,
+        to: cursor + 1,
+        fragmentId: blockId,
+        warningId: blockId,
+        label: "Custom XML block",
+        detail:
+          block.uri || block.element
+            ? `Custom XML wrapper ${[block.element, block.uri].filter(Boolean).join(" ")} preserved as a read-only block.`
+            : "Custom XML wrapper preserved as a read-only block.",
+        state: "locked-preserve-only",
+      },
+      lockedFragmentIds: [],
+      nextCursor: cursor + 1,
+    };
+  }
+
+  if (block.type === "alt_chunk") {
+    const blockId = `alt-chunk-${counters.altChunk}`;
+    counters.altChunk += 1;
+    return {
+      block: {
+        blockId,
+        kind: "opaque_block",
+        from: cursor,
+        to: cursor + 1,
+        fragmentId: blockId,
+        warningId: blockId,
+        label: "AltChunk import",
+        detail: `Alternate content import remains read-only through relationship ${block.relationshipId}.`,
+        state: "locked-preserve-only",
+      },
+      lockedFragmentIds: [],
+      nextCursor: cursor + 1,
+    };
+  }
+
+  const paragraphIndex = counters.paragraph;
+  counters.paragraph += 1;
+  return createParagraphBlock(paragraphIndex, block, document, cursor);
+}
+
+function createTableBlock(
+  tableIndex: number,
+  table: TableNode,
+  document: CanonicalDocumentEnvelope,
+  cursor: number,
+  counters: {
+    paragraph: number;
+    table: number;
+    opaque: number;
+    sdt: number;
+    customXml: number;
+    altChunk: number;
+  },
+): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
+  const lockedFragmentIds: string[] = [];
+  let innerCursor = cursor;
+  const rows: SurfaceTableRowSnapshot[] = [];
+
+  for (const row of table.rows) {
+    const cells: SurfaceTableCellSnapshot[] = [];
+    for (const cell of row.cells) {
+      const cellContent: SurfaceBlockSnapshot[] = [];
+      for (const child of cell.children) {
+        const result = createSurfaceBlock(child, document, innerCursor, counters);
+        cellContent.push(result.block);
+        lockedFragmentIds.push(...result.lockedFragmentIds);
+        innerCursor = result.nextCursor;
+      }
+      cells.push({
+        gridSpan: cell.gridSpan ?? 1,
+        verticalMerge: cell.verticalMerge ?? null,
+        colspan: cell.gridSpan ?? 1,
+        rowspan: cell.verticalMerge === "restart" ? 1 : 1,
+        content: cellContent,
+      });
+    }
+    rows.push({ cells });
+  }
+
+  return {
+    block: {
+      blockId: `table-${tableIndex}`,
+      kind: "table",
+      from: cursor,
+      to: innerCursor,
+      styleId: table.styleId,
+      gridColumns: table.gridColumns,
+      rows,
+    },
+    lockedFragmentIds,
+    nextCursor: innerCursor,
+  };
+}
+
+function createSdtBlock(
+  sdtIndex: number,
+  block: SdtNode,
+  document: CanonicalDocumentEnvelope,
+  cursor: number,
+  counters: {
+    paragraph: number;
+    table: number;
+    opaque: number;
+    sdt: number;
+    customXml: number;
+    altChunk: number;
+  },
+): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
+  const children: SurfaceBlockSnapshot[] = [];
+  const lockedFragmentIds: string[] = [];
+  let innerCursor = cursor;
+
+  for (const child of block.children) {
+    const result = createSurfaceBlock(child, document, innerCursor, counters);
+    children.push(result.block);
+    lockedFragmentIds.push(...result.lockedFragmentIds);
+    innerCursor = result.nextCursor;
+  }
+
+  return {
+    block: {
+      blockId: `sdt-${sdtIndex}`,
+      kind: "sdt_block",
+      from: cursor,
+      to: innerCursor,
+      ...(block.properties.sdtType ? { sdtType: block.properties.sdtType } : {}),
+      ...(block.properties.alias ? { alias: block.properties.alias } : {}),
+      ...(block.properties.tag ? { tag: block.properties.tag } : {}),
+      ...(block.properties.lock ? { lock: block.properties.lock } : {}),
+      children,
+    },
+    lockedFragmentIds,
+    nextCursor: innerCursor,
+  };
+}
+
+function createParagraphBlock(
+  paragraphIndex: number,
+  paragraph: ParagraphNode,
+  document: CanonicalDocumentEnvelope,
+  start: number,
+): {
+  block: SurfaceBlockSnapshot;
+  nextCursor: number;
+  lockedFragmentIds: string[];
+} {
+  const accumulator: ParagraphAccumulator = {
+    blockId: `paragraph-${paragraphIndex}`,
+    kind: "paragraph",
+    from: start,
+    to: start,
+    ...(paragraph.styleId ? { styleId: paragraph.styleId } : {}),
+    ...(paragraph.numbering ? { numbering: paragraph.numbering } : {}),
+    segments: [],
+  };
+  const lockedFragmentIds: string[] = [];
+  let cursor = start;
+  const children = Array.isArray(paragraph.children) ? paragraph.children : [];
+
+  for (const child of children) {
+    const result = appendInlineSegments(accumulator, child, document, cursor);
+    cursor = result.nextCursor;
+    lockedFragmentIds.push(...result.lockedFragmentIds);
+  }
+
+  accumulator.to = cursor;
+  return {
+    block: accumulator,
+    nextCursor: cursor,
+    lockedFragmentIds,
+  };
+}
+
+function appendInlineSegments(
+  paragraph: ParagraphAccumulator,
+  node: InlineNode,
+  document: CanonicalDocumentEnvelope,
+  start: number,
+  hyperlinkHref?: string,
+): { nextCursor: number; lockedFragmentIds: string[] } {
+  switch (node.type) {
+    case "text":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "text",
+        from: start,
+        to: start + Array.from(node.text).length,
+        text: node.text,
+        ...(node.marks ? { marks: cloneMarks(node.marks) } : {}),
+        ...(hyperlinkHref ? { hyperlinkHref } : {}),
+      });
+      return { nextCursor: start + Array.from(node.text).length, lockedFragmentIds: [] };
+    case "tab":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "tab",
+        from: start,
+        to: start + 1,
+        ...(hyperlinkHref ? { hyperlinkHref } : {}),
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+    case "hard_break":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "hard_break",
+        from: start,
+        to: start + 1,
+        ...(hyperlinkHref ? { hyperlinkHref } : {}),
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+    case "hyperlink": {
+      let cursor = start;
+      for (const child of node.children) {
+        const result = appendInlineSegments(paragraph, child, document, cursor, node.href);
+        cursor = result.nextCursor;
+      }
+      return { nextCursor: cursor, lockedFragmentIds: [] };
+    }
+    case "image":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "image",
+        from: start,
+        to: start + 1,
+        mediaId: node.mediaId,
+        altText: node.altText,
+        state: hasMediaItem(document.media, node.mediaId) ? "editable" : "missing",
+        ...(node.display ? { display: node.display } : {}),
+        detail:
+          node.display === "floating"
+            ? createFloatingImageDetail(node.altText, node.floating)
+            : node.altText
+              ? `Alt text ${node.altText}.`
+              : "Inline image remains a whole-unit render surface.",
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+    case "opaque_inline": {
+      const fragment = getOpaqueFragment(document.preservation as never, node.fragmentId);
+      const descriptor = fragment ? describeOpaqueFragment(fragment) : null;
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "opaque_inline",
+        from: start,
+        to: start + 1,
+        fragmentId: node.fragmentId,
+        warningId: node.warningId,
+        label: descriptor?.label ?? "Unsupported inline OOXML",
+        detail:
+          descriptor?.detail ??
+          "Locked whole-unit to keep unsupported inline OOXML intact through export.",
+        state: "locked-preserve-only",
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [node.fragmentId] };
+    }
+    case "chart_preview":
+      return appendComplexPreviewSegment(paragraph, node, start, "Chart", createChartDetail(node));
+    case "smartart_preview":
+      return appendComplexPreviewSegment(paragraph, node, start, "SmartArt", createSmartArtDetail(node));
+    case "shape":
+      return appendComplexPreviewSegment(paragraph, node, start, "Shape", createShapeDetail(node));
+    case "wordart":
+      return appendComplexPreviewSegment(paragraph, node, start, "WordArt", createWordArtDetail(node));
+    case "vml_shape":
+      return appendComplexPreviewSegment(paragraph, node, start, "VML shape", createVmlDetail(node));
+  }
+}
+
+function appendComplexPreviewSegment(
+  paragraph: ParagraphAccumulator,
+  node: { rawXml: string },
+  start: number,
+  label: string,
+  detail: string,
+): { nextCursor: number; lockedFragmentIds: string[] } {
+  paragraph.segments.push({
+    segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+    kind: "opaque_inline",
+    from: start,
+    to: start + 1,
+    fragmentId: `complex:${label.replace(/\s/g, "-").toLowerCase()}:${start}`,
+    warningId: `warning:complex-preview:${start}`,
+    label,
+    detail,
+    state: "locked-preserve-only",
+  });
+  return { nextCursor: start + 1, lockedFragmentIds: [] };
+}
+
+function createChartDetail(node: ChartPreviewNode): string {
+  return node.previewMediaId
+    ? `Chart read-only preview. Fallback image ${node.previewMediaId}. Original XML preserved for export.`
+    : "Chart read-only preview. Original XML preserved for export.";
+}
+
+function createSmartArtDetail(node: SmartArtPreviewNode): string {
+  return node.previewMediaId
+    ? `SmartArt diagram read-only preview. Fallback image ${node.previewMediaId}. Original XML preserved for export.`
+    : "SmartArt diagram read-only preview. Original XML preserved for export.";
+}
+
+function createShapeDetail(node: ShapeNode): string {
+  const parts = ["Shape read-only preview."];
+  if (node.geometry) parts.push(`Geometry: ${node.geometry}.`);
+  if (node.text) parts.push(`Text: "${node.text}".`);
+  parts.push("Original XML preserved for export.");
+  return parts.join(" ");
+}
+
+function createWordArtDetail(node: WordArtNode): string {
+  const parts = ["WordArt read-only preview."];
+  if (node.text) parts.push(`Text: "${node.text}".`);
+  if (node.geometry) parts.push(`Effect: ${node.geometry}.`);
+  parts.push("Original XML preserved for export.");
+  return parts.join(" ");
+}
+
+function createVmlDetail(node: VmlShapeNode): string {
+  const parts = ["VML shape read-only preview."];
+  if (node.shapeType) parts.push(`Type: ${node.shapeType}.`);
+  if (node.text) parts.push(`Text: "${node.text}".`);
+  parts.push("Legacy VML; original XML preserved for export.");
+  return parts.join(" ");
+}
+
+function createPlainText(
+  blocks: SurfaceBlockSnapshot[],
+): string {
+  const text: string[] = [];
+  for (const block of blocks) {
+    if (block.kind === "opaque_block") {
+      text.push("\uFFFA");
+      continue;
+    }
+
+    if (block.kind === "table") {
+      text.push("\uFFFA"); // placeholder for table in plain text
+      continue;
+    }
+
+    if (block.kind === "sdt_block") {
+      text.push(createPlainText(block.children));
+      continue;
+    }
+
+    for (const segment of block.segments) {
+      switch (segment.kind) {
+        case "text":
+          text.push(segment.text);
+          break;
+        case "tab":
+          text.push("\t");
+          break;
+        case "hard_break":
+          text.push("\n");
+          break;
+        case "image":
+          text.push("\uFFFC");
+          break;
+        case "opaque_inline":
+          text.push("\uFFF9");
+          break;
+      }
+    }
+  }
+
+  return text.join("");
+}
+
+function cloneMarks(marks: TextMark[]): Array<"bold" | "italic" | "underline" | "strikethrough"> {
+  return marks.map((mark) => mark.type);
+}
+
+function normalizeDocumentRoot(content: unknown): DocumentRootNode {
+  if (content && typeof content === "object" &&
+    ((content as { type?: string }).type === "doc" || (content as { type?: string }).type === "document_root")) {
+    return content as DocumentRootNode;
+  }
+
+  if (Array.isArray(content)) {
+    return {
+      type: "doc",
+      children: content.filter(
+        (value): value is DocumentRootNode["children"][number] =>
+          Boolean(value) &&
+          typeof value === "object" &&
+          ((value as { type?: string }).type === "paragraph" ||
+            (value as { type?: string }).type === "table" ||
+            (value as { type?: string }).type === "sdt" ||
+            (value as { type?: string }).type === "custom_xml" ||
+            (value as { type?: string }).type === "alt_chunk" ||
+            (value as { type?: string }).type === "opaque_block"),
+      ),
+    };
+  }
+
+  return {
+    type: "doc",
+    children: [{ type: "paragraph", children: [] }],
+  };
+}
+
+function createFloatingImageDetail(
+  altText: string | undefined,
+  floating: {
+    horizontalPosition?: { relativeFrom?: string; align?: string; offset?: number };
+    verticalPosition?: { relativeFrom?: string; align?: string; offset?: number };
+    wrap?: string;
+  } | undefined,
+): string {
+  const parts = [altText ? `Alt text ${altText}.` : "Floating image rendered inline in the editor."];
+  if (floating?.wrap) {
+    parts.push(`Wrap ${floating.wrap}.`);
+  }
+  if (floating?.horizontalPosition?.align || floating?.horizontalPosition?.offset !== undefined) {
+    parts.push(
+      `Horizontal ${floating.horizontalPosition.align ?? floating.horizontalPosition.offset}.`,
+    );
+  }
+  if (floating?.verticalPosition?.align || floating?.verticalPosition?.offset !== undefined) {
+    parts.push(
+      `Vertical ${floating.verticalPosition.align ?? floating.verticalPosition.offset}.`,
+    );
+  }
+  return parts.join(" ");
+}
+
+function hasMediaItem(media: Record<string, unknown>, mediaId: string): boolean {
+  if (mediaId in media) {
+    return true;
+  }
+
+  const items = media.items;
+  if (!items || typeof items !== "object" || Array.isArray(items)) {
+    return false;
+  }
+
+  return mediaId in items;
+}

package/src/runtime/table-commands.ts

@@ -0,0 +1,87 @@
+/**
+ * ProseMirror table editing commands backed by prosemirror-tables.
+ *
+ * Each command follows the standard ProseMirror command signature:
+ *   (state, dispatch?) => boolean
+ *
+ * The prosemirror-tables commands replace the previous hand-rolled
+ * implementations and support merged cells, colspan/rowspan, and
+ * the full prosemirror-tables table model including table_header nodes.
+ */
+
+import type { Command as PMCommand, EditorState } from "prosemirror-state";
+import {
+  addColumnAfter as pmAddColumnAfter,
+  addColumnBefore as pmAddColumnBefore,
+  addRowAfter as pmAddRowAfter,
+  addRowBefore as pmAddRowBefore,
+  deleteColumn as pmDeleteColumn,
+  deleteRow as pmDeleteRow,
+  deleteTable,
+  goToNextCell,
+  mergeCells,
+  splitCell,
+  toggleHeaderCell,
+  toggleHeaderColumn,
+  toggleHeaderRow,
+} from "prosemirror-tables";
+
+// prosemirror-tables does not export goToPreviousCell; replicate via direction -1.
+const goToPreviousCell: PMCommand = (state, dispatch, view) =>
+  goToNextCell(-1)(state, dispatch, view);
+
+export type { Command as TableCommand } from "prosemirror-state";
+
+function tableAtSelection(state: EditorState) {
+  const { $head } = state.selection;
+  for (let depth = $head.depth; depth > 0; depth -= 1) {
+    const node = $head.node(depth);
+    if (node.type.spec.tableRole === "table") {
+      return node;
+    }
+  }
+  return null;
+}
+
+function withTableGuard(
+  canRun: (state: EditorState) => boolean,
+  command: PMCommand,
+): PMCommand {
+  return (state, dispatch, view) => {
+    if (!canRun(state)) return false;
+    return command(state, dispatch, view);
+  };
+}
+
+export const addRowBefore: PMCommand = (state, dispatch, view) =>
+  pmAddRowBefore(state, dispatch, view);
+
+export const addRowAfter: PMCommand = (state, dispatch, view) =>
+  pmAddRowAfter(state, dispatch, view);
+
+export const deleteRow: PMCommand = withTableGuard((state) => {
+  const table = tableAtSelection(state);
+  return table !== null && table.childCount > 1;
+}, pmDeleteRow);
+
+export const addColumnBefore: PMCommand = (state, dispatch, view) =>
+  pmAddColumnBefore(state, dispatch, view);
+
+export const addColumnAfter: PMCommand = (state, dispatch, view) =>
+  pmAddColumnAfter(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;
+}, pmDeleteColumn);
+
+export {
+  deleteTable,
+  mergeCells,
+  splitCell,
+  toggleHeaderRow,
+  toggleHeaderColumn,
+  toggleHeaderCell,
+  goToNextCell,
+  goToPreviousCell,
+};