@beyondwork/docx-react-component 1.0.18 → 1.0.20

package/src/api/session-state.ts

@@ -0,0 +1,60 @@
+import type {
+  EditorSessionState,
+  PersistedEditorSnapshot,
+} from "./public-types.ts";
+
+export const EDITOR_SESSION_STATE_VERSION = "editor-session-state/1" as const;
+
+function cloneStructuredValue<T>(value: T): T {
+  return structuredClone(value);
+}
+
+export function createEditorSessionState(
+  input: Omit<EditorSessionState, "sessionVersion">,
+): EditorSessionState {
+  return cloneStructuredValue({
+    sessionVersion: EDITOR_SESSION_STATE_VERSION,
+    ...input,
+  });
+}
+
+export function editorSessionStateFromPersistedSnapshot(
+  snapshot: PersistedEditorSnapshot,
+): EditorSessionState {
+  return createEditorSessionState({
+    schemaVersion: snapshot.schemaVersion,
+    documentId: snapshot.documentId,
+    docId: snapshot.docId,
+    createdAt: snapshot.createdAt,
+    updatedAt: snapshot.updatedAt,
+    editorBuild: snapshot.editorBuild,
+    canonicalDocument: snapshot.canonicalDocument,
+    compatibility: snapshot.compatibility,
+    warningLog: snapshot.warningLog,
+    protectionSnapshot: snapshot.protectionSnapshot,
+    sourcePackage: snapshot.sourcePackage,
+  });
+}
+
+export function persistedSnapshotFromEditorSessionState(
+  sessionState: EditorSessionState,
+  options: {
+    savedAt: string;
+  },
+): PersistedEditorSnapshot {
+  return cloneStructuredValue({
+    snapshotVersion: "persisted-editor-snapshot/2",
+    schemaVersion: sessionState.schemaVersion,
+    documentId: sessionState.documentId,
+    docId: sessionState.docId,
+    createdAt: sessionState.createdAt,
+    updatedAt: sessionState.updatedAt,
+    savedAt: options.savedAt,
+    editorBuild: sessionState.editorBuild,
+    canonicalDocument: sessionState.canonicalDocument,
+    compatibility: sessionState.compatibility,
+    warningLog: sessionState.warningLog,
+    protectionSnapshot: sessionState.protectionSnapshot,
+    sourcePackage: sessionState.sourcePackage,
+  });
+}

package/src/core/commands/formatting-commands.ts

@@ -271,6 +271,7 @@ export function getFormattingStateFromRenderSnapshot(
     alignment: getConsistentValue(paragraphs, (paragraph) =>
       toPublicAlignment(paragraph.alignment),
     ),
+    paragraphStyleId: getConsistentValue(paragraphs, (paragraph) => paragraph.styleId),
     breadcrumb: getSelectionBreadcrumb(surface.blocks, snapshot.selection),
   };
 }
@@ -972,7 +973,7 @@ function setMarkValue(
 ): TextMark[] | undefined {
   const nextMarks = cloneMarks(marks).filter((candidate) => {
     if (markType === "backgroundColor") {
-      return candidate.type !== "backgroundColor";
+      return candidate.type !== "backgroundColor" && candidate.type !== "highlight";
     }
     return candidate.type !== markType;
   });

package/src/core/commands/image-commands.ts

@@ -17,6 +17,7 @@ import {
 export interface ImageCommandContext {
   timestamp: string;
   altText?: string;
+  display?: "inline" | "floating";
 }
 
 export interface InsertImageResult {
@@ -158,6 +159,7 @@ function insertImageIntoParagraph(
     filename: `${mediaId.replace("media:", "")}.${ext}`,
     packagePartName,
     ...(context.altText ? { altText: context.altText } : {}),
+    ...(context.display ? { display: context.display } : {}),
   };
 
   const existingItems =
@@ -205,6 +207,151 @@ function insertImageIntoParagraph(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Bounded geometry commands — export-safe, command-backed
+// ---------------------------------------------------------------------------
+
+/** EMU-based image dimensions. 1 inch = 914400 EMU. */
+export interface ImageDimensions {
+  widthEmu: number;
+  heightEmu: number;
+}
+
+/** Bounded resize constraints. */
+const MIN_DIMENSION_EMU = 91440; // ~0.1 inch
+const MAX_DIMENSION_EMU = 27432000; // ~30 inches — Word practical max
+
+function clampDimension(value: number): number {
+  return Math.max(MIN_DIMENSION_EMU, Math.min(MAX_DIMENSION_EMU, Math.round(value)));
+}
+
+export interface ResizeImageResult {
+  document: CanonicalDocumentEnvelope;
+  dimensions: ImageDimensions;
+}
+
+/**
+ * Resize an image in the media catalog by media ID.
+ *
+ * Bounded: dimensions are clamped to [0.1in, 30in] and stored on the
+ * MediaItem so they survive export round-trip. The ImageNode in the story
+ * is not mutated — placement geometry lives on the media item and the
+ * preserved `placementXml` is updated if present.
+ */
+export function resizeImage(
+  document: CanonicalDocumentEnvelope,
+  mediaId: string,
+  dimensions: ImageDimensions,
+  timestamp: string = new Date().toISOString(),
+): ResizeImageResult {
+  const media = document.media as { items: Record<string, MediaItem> } | undefined;
+  if (!media?.items[mediaId]) {
+    throw new TextTransactionError(
+      "invalid_selection",
+      `Media item ${mediaId} does not exist in the catalog.`,
+    );
+  }
+
+  const clamped: ImageDimensions = {
+    widthEmu: clampDimension(dimensions.widthEmu),
+    heightEmu: clampDimension(dimensions.heightEmu),
+  };
+
+  const updatedItem: MediaItem = {
+    ...media.items[mediaId],
+    widthEmu: clamped.widthEmu,
+    heightEmu: clamped.heightEmu,
+  };
+
+  return {
+    document: {
+      ...document,
+      updatedAt: timestamp,
+      media: {
+        items: {
+          ...media.items,
+          [mediaId]: updatedItem,
+        },
+      },
+    },
+    dimensions: clamped,
+  };
+}
+
+export interface RepositionImageResult {
+  document: CanonicalDocumentEnvelope;
+}
+
+/**
+ * Reposition a floating image by updating its floating axis offsets.
+ *
+ * Only applies to images with `display: "floating"`. The offset values are
+ * EMU-based and stored on the canonical ImageNode's `floating` property so
+ * they survive export. Inline images cannot be repositioned — callers must
+ * first change the display mode through a separate command.
+ */
+export function repositionFloatingImage(
+  document: CanonicalDocumentEnvelope,
+  mediaId: string,
+  offsets: { horizontalOffsetEmu?: number; verticalOffsetEmu?: number },
+  timestamp: string = new Date().toISOString(),
+): RepositionImageResult {
+  const blocks = document.content.children;
+  let found = false;
+  const nextBlocks = blocks.map((block) => {
+    if (block.type !== "paragraph") return block;
+    const nextChildren = block.children.map((child) => {
+      if (child.type !== "image" || child.mediaId !== mediaId) return child;
+      if (child.display !== "floating") {
+        throw new TextTransactionError(
+          "unsupported_content",
+          `Image ${mediaId} is not floating — reposition requires display: "floating".`,
+        );
+      }
+      found = true;
+      const prevFloating = child.floating ?? {};
+      return {
+        ...child,
+        floating: {
+          ...prevFloating,
+          ...(offsets.horizontalOffsetEmu !== undefined
+            ? {
+                horizontalPosition: {
+                  ...prevFloating.horizontalPosition,
+                  offset: offsets.horizontalOffsetEmu,
+                },
+              }
+            : {}),
+          ...(offsets.verticalOffsetEmu !== undefined
+            ? {
+                verticalPosition: {
+                  ...prevFloating.verticalPosition,
+                  offset: offsets.verticalOffsetEmu,
+                },
+              }
+            : {}),
+        },
+      };
+    });
+    return { ...block, children: nextChildren };
+  });
+
+  if (!found) {
+    throw new TextTransactionError(
+      "invalid_selection",
+      `No floating image with mediaId ${mediaId} found in document content.`,
+    );
+  }
+
+  return {
+    document: {
+      ...document,
+      updatedAt: timestamp,
+      content: { ...document.content, children: nextBlocks },
+    },
+  };
+}
+
 function mimeTypeToExtension(mimeType: string): string {
   switch (mimeType.toLowerCase()) {
     case "image/png":

package/src/core/commands/index.ts

@@ -60,6 +60,7 @@ export type EditorCommand =
       document: CanonicalDocumentEnvelope;
       mapping?: TransactionMapping;
       selection?: SelectionSnapshot;
+      protectionSelection?: SelectionSnapshot;
       origin?: CommandOrigin;
     }
   | {
@@ -110,6 +111,7 @@ export type EditorCommand =
   | {
       type: "comment.add";
       comment: CommentThreadRecord;
+      selection?: SelectionSnapshot;
       origin?: CommandOrigin;
     }
   | {
@@ -541,7 +543,11 @@ export function executeEditorCommand(
       }
       const editedEntries = [...threadToEdit.entries];
       editedEntries[0] = { ...editedEntries[0], body: command.body };
-      const editedThread = { ...threadToEdit, entries: editedEntries };
+      const editedThread = {
+        ...threadToEdit,
+        body: command.body,
+        entries: editedEntries,
+      };
       const editedComments = {
         ...state.document.review.comments,
         [command.commentId]: editedThread,
@@ -611,7 +617,12 @@ export function remapSelection(
   }
 
   if (activeRange.kind === "node") {
-    return createSelectionSnapshot(activeRange.at, activeRange.at);
+    return {
+      anchor: activeRange.at,
+      head: activeRange.at,
+      isCollapsed: true,
+      activeRange,
+    };
   }
 
   return {
@@ -676,7 +687,12 @@ function normalizeSelection(selection: SelectionSnapshot): SelectionSnapshot {
   }
 
   if (activeRange.kind === "node") {
-    return createSelectionSnapshot(activeRange.at, activeRange.at);
+    return {
+      anchor: activeRange.at,
+      head: activeRange.at,
+      isCollapsed: true,
+      activeRange,
+    };
   }
 
   return {

package/src/core/commands/list-commands.ts

@@ -1,5 +1,6 @@
 import type {
   AbstractNumberingDefinition,
+  BlockNode,
   CanonicalDocument as CanonicalDocumentEnvelope,
   NumberingCatalog,
   NumberingInstance,
@@ -16,9 +17,6 @@ export interface ListCommandResult {
   createdNumberingInstanceId?: string;
 }
 
-type OpaqueBlockLike = { type: "opaque_block"; [key: string]: unknown };
-type BlockLike = ParagraphNode | OpaqueBlockLike;
-
 export function toggleNumberedList(
   document: CanonicalDocumentEnvelope,
   paragraphIndexes: readonly number[],
@@ -51,6 +49,98 @@ export function outdentListItems(
   return adjustListLevels(document, paragraphIndexes, -1, context);
 }
 
+/**
+ * Word-like Enter behavior on a list paragraph:
+ * - If the paragraph has content, split normally (caller handles the split).
+ *   Returns `action: "split"` so the caller can proceed with a standard paragraph split.
+ * - If the paragraph is empty AND at level > 0, outdent one level → `action: "outdented"`.
+ * - If the paragraph is empty AND at level 0, remove numbering → `action: "removed"`.
+ */
+export function splitListParagraph(
+  document: CanonicalDocumentEnvelope,
+  paragraphIndex: number,
+  paragraphIsEmpty: boolean,
+  context: ListCommandContext,
+): ListCommandResult & { action: "split" | "outdented" | "removed" } {
+  if (!paragraphIsEmpty) {
+    return {
+      document,
+      affectedParagraphIndexes: [],
+      action: "split",
+    };
+  }
+
+  const working = cloneEnvelope(document, context.timestamp);
+  const paragraphs = captureEditableParagraphs(working);
+  const target = paragraphs[paragraphIndex];
+
+  if (!target?.numbering) {
+    return {
+      document: working,
+      affectedParagraphIndexes: [],
+      action: "split",
+    };
+  }
+
+  if (target.numbering.level > 0) {
+    target.numbering = {
+      numberingInstanceId: target.numbering.numberingInstanceId,
+      level: clampLevel(target.numbering.level - 1),
+    };
+    return {
+      document: working,
+      affectedParagraphIndexes: [paragraphIndex],
+      action: "outdented",
+    };
+  }
+
+  delete target.numbering;
+  return {
+    document: working,
+    affectedParagraphIndexes: [paragraphIndex],
+    action: "removed",
+  };
+}
+
+/**
+ * Word-like Backspace at the start of a list paragraph:
+ * - If at level > 0, outdent one level.
+ * - If at level 0, remove numbering entirely.
+ * Returns the modified document and whether numbering was changed.
+ */
+export function backspaceAtListStart(
+  document: CanonicalDocumentEnvelope,
+  paragraphIndex: number,
+  context: ListCommandContext,
+): ListCommandResult & { handled: boolean } {
+  const working = cloneEnvelope(document, context.timestamp);
+  const paragraphs = captureEditableParagraphs(working);
+  const target = paragraphs[paragraphIndex];
+
+  if (!target?.numbering) {
+    return {
+      document: working,
+      affectedParagraphIndexes: [],
+      handled: false,
+    };
+  }
+
+  if (target.numbering.level > 0) {
+    target.numbering = {
+      numberingInstanceId: target.numbering.numberingInstanceId,
+      level: clampLevel(target.numbering.level - 1),
+    };
+  } else {
+    delete target.numbering;
+  }
+
+  return {
+    document: working,
+    affectedParagraphIndexes: [paragraphIndex],
+    handled: true,
+  };
+}
+
 export function restartNumbering(
   document: CanonicalDocumentEnvelope,
   paragraphIndex: number,
@@ -58,10 +148,10 @@ export function restartNumbering(
   startAt = 1,
 ): ListCommandResult {
   const working = cloneEnvelope(document, context.timestamp);
-  const blocks = captureBlocks(working);
-  const target = blocks[paragraphIndex];
+  const paragraphs = captureEditableParagraphs(working);
+  const target = paragraphs[paragraphIndex];
 
-  if (!isParagraphNode(target) || !target.numbering) {
+  if (!target?.numbering) {
     return {
       document: working,
       affectedParagraphIndexes: [],
@@ -88,18 +178,18 @@ export function restartNumbering(
   };
 
   const affectedParagraphIndexes: number[] = [];
-  for (let index = paragraphIndex; index < blocks.length; index += 1) {
-    const block = blocks[index];
-    if (!isParagraphNode(block)) {
+  for (let index = paragraphIndex; index < paragraphs.length; index += 1) {
+    const paragraph = paragraphs[index];
+    if (!paragraph?.numbering) {
       break;
     }
-    if (block.numbering?.numberingInstanceId !== existingInstance.numberingInstanceId) {
+    if (paragraph.numbering.numberingInstanceId !== existingInstance.numberingInstanceId) {
       break;
     }
 
-    block.numbering = {
+    paragraph.numbering = {
       numberingInstanceId,
-      level: block.numbering.level,
+      level: paragraph.numbering.level,
     };
     affectedParagraphIndexes.push(index);
   }
@@ -113,6 +203,70 @@ export function restartNumbering(
   };
 }
 
+export function continueNumbering(
+  document: CanonicalDocumentEnvelope,
+  paragraphIndex: number,
+  context: ListCommandContext,
+): ListCommandResult {
+  const working = cloneEnvelope(document, context.timestamp);
+  const paragraphs = captureEditableParagraphs(working);
+  const target = paragraphs[paragraphIndex];
+
+  if (!target?.numbering) {
+    return {
+      document: working,
+      affectedParagraphIndexes: [],
+    };
+  }
+
+  const catalog = ensureNumberingCatalog(working.numbering);
+  const currentInstanceId = target.numbering.numberingInstanceId;
+  const currentKind = getListKind(catalog, currentInstanceId);
+  if (!currentKind) {
+    return {
+      document: working,
+      affectedParagraphIndexes: [],
+    };
+  }
+
+  const compatibleInstanceId = findPreviousCompatibleInstance(
+    paragraphs,
+    catalog,
+    paragraphIndex,
+    currentKind,
+  );
+  if (!compatibleInstanceId || compatibleInstanceId === currentInstanceId) {
+    return {
+      document: working,
+      affectedParagraphIndexes: [],
+    };
+  }
+
+  const affectedParagraphIndexes: number[] = [];
+  for (let index = paragraphIndex; index < paragraphs.length; index += 1) {
+    const paragraph = paragraphs[index];
+    if (!paragraph?.numbering) {
+      break;
+    }
+    if (paragraph.numbering.numberingInstanceId !== currentInstanceId) {
+      break;
+    }
+    paragraph.numbering = {
+      numberingInstanceId: compatibleInstanceId,
+      level: paragraph.numbering.level,
+    };
+    affectedParagraphIndexes.push(index);
+  }
+
+  working.numbering = catalog;
+
+  return {
+    document: working,
+    affectedParagraphIndexes,
+    createdNumberingInstanceId: compatibleInstanceId,
+  };
+}
+
 function toggleListKind(
   document: CanonicalDocumentEnvelope,
   paragraphIndexes: readonly number[],
@@ -120,8 +274,8 @@ function toggleListKind(
   context: ListCommandContext,
 ): ListCommandResult {
   const working = cloneEnvelope(document, context.timestamp);
-  const blocks = captureBlocks(working);
-  const normalizedIndexes = normalizeParagraphIndexes(blocks, paragraphIndexes);
+  const paragraphs = captureEditableParagraphs(working);
+  const normalizedIndexes = normalizeParagraphIndexes(paragraphs, paragraphIndexes);
 
   if (normalizedIndexes.length === 0) {
     return {
@@ -132,7 +286,7 @@ function toggleListKind(
 
   const catalog = ensureNumberingCatalog(working.numbering);
   const allAlreadyKind = normalizedIndexes.every((index) => {
-    const paragraph = blocks[index] as ParagraphNode;
+    const paragraph = paragraphs[index] as ParagraphNode;
     return paragraph.numbering
       ? getListKind(catalog, paragraph.numbering.numberingInstanceId) === kind
       : false;
@@ -140,7 +294,7 @@ function toggleListKind(
 
   if (allAlreadyKind) {
     for (const index of normalizedIndexes) {
-      delete (blocks[index] as ParagraphNode).numbering;
+      delete (paragraphs[index] as ParagraphNode).numbering;
     }
     working.numbering = catalog;
     return {
@@ -150,11 +304,11 @@ function toggleListKind(
   }
 
   const numberingInstanceId =
-    findAdjacentCompatibleInstance(blocks, catalog, normalizedIndexes[0]!, kind) ??
+    findAdjacentCompatibleInstance(paragraphs, catalog, normalizedIndexes[0]!, kind) ??
     ensureDefaultInstance(catalog, kind);
 
   for (const index of normalizedIndexes) {
-    const paragraph = blocks[index] as ParagraphNode;
+    const paragraph = paragraphs[index] as ParagraphNode;
     paragraph.numbering = {
       numberingInstanceId,
       level: clampLevel(paragraph.numbering?.level ?? 0),
@@ -177,13 +331,13 @@ function adjustListLevels(
   context: ListCommandContext,
 ): ListCommandResult {
   const working = cloneEnvelope(document, context.timestamp);
-  const blocks = captureBlocks(working);
-  const affectedParagraphIndexes = normalizeParagraphIndexes(blocks, paragraphIndexes).filter(
-    (index) => isParagraphNode(blocks[index]) && Boolean((blocks[index] as ParagraphNode).numbering),
+  const paragraphs = captureEditableParagraphs(working);
+  const affectedParagraphIndexes = normalizeParagraphIndexes(paragraphs, paragraphIndexes).filter(
+    (index) => Boolean(paragraphs[index]?.numbering),
   );
 
   for (const index of affectedParagraphIndexes) {
-    const paragraph = blocks[index] as ParagraphNode;
+    const paragraph = paragraphs[index] as ParagraphNode;
     if (!paragraph.numbering) {
       continue;
     }
@@ -226,13 +380,13 @@ function ensureDefaultInstance(
 }
 
 function findAdjacentCompatibleInstance(
-  blocks: BlockLike[],
+  paragraphs: readonly ParagraphNode[],
   catalog: NumberingCatalog,
   fromIndex: number,
   kind: "numbered" | "bulleted",
 ): string | undefined {
-  const previous = blocks[fromIndex - 1];
-  if (isParagraphNode(previous) && previous.numbering) {
+  const previous = paragraphs[fromIndex - 1];
+  if (previous?.numbering) {
     const previousKind = getListKind(catalog, previous.numbering.numberingInstanceId);
     if (previousKind === kind) {
       return previous.numbering.numberingInstanceId;
@@ -242,6 +396,24 @@ function findAdjacentCompatibleInstance(
   return undefined;
 }
 
+function findPreviousCompatibleInstance(
+  paragraphs: readonly ParagraphNode[],
+  catalog: NumberingCatalog,
+  fromIndex: number,
+  kind: "numbered" | "bulleted",
+): string | undefined {
+  for (let index = fromIndex - 1; index >= 0; index -= 1) {
+    const paragraph = paragraphs[index];
+    if (!paragraph?.numbering) {
+      continue;
+    }
+    if (getListKind(catalog, paragraph.numbering.numberingInstanceId) === kind) {
+      return paragraph.numbering.numberingInstanceId;
+    }
+  }
+  return undefined;
+}
+
 function getListKind(
   catalog: NumberingCatalog,
   numberingInstanceId: string,
@@ -333,9 +505,11 @@ function cloneEnvelope(
   };
 }
 
-function captureBlocks(document: CanonicalDocumentEnvelope): BlockLike[] {
+function captureEditableParagraphs(document: CanonicalDocumentEnvelope): ParagraphNode[] {
   if (isDocumentRoot(document.content)) {
-    return document.content.children as BlockLike[];
+    const paragraphs: ParagraphNode[] = [];
+    collectEditableParagraphs(document.content.children as BlockNode[], paragraphs);
+    return paragraphs;
   }
 
   const fallback = {
@@ -343,16 +517,42 @@ function captureBlocks(document: CanonicalDocumentEnvelope): BlockLike[] {
     children: [{ type: "paragraph" as const, children: [] }],
   };
   document.content = fallback;
-  return fallback.children as BlockLike[];
+  return fallback.children as ParagraphNode[];
+}
+
+function collectEditableParagraphs(
+  blocks: readonly BlockNode[],
+  output: ParagraphNode[],
+): void {
+  for (const block of blocks) {
+    switch (block.type) {
+      case "paragraph":
+        output.push(block);
+        break;
+      case "table":
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            collectEditableParagraphs(cell.children, output);
+          }
+        }
+        break;
+      case "sdt":
+        collectEditableParagraphs(block.children, output);
+        break;
+      case "custom_xml":
+        break;
+      default:
+        break;
+    }
+  }
 }
 
 function normalizeParagraphIndexes(
-  blocks: BlockLike[],
+  paragraphs: readonly ParagraphNode[],
   paragraphIndexes: readonly number[],
 ): number[] {
   return [...new Set(paragraphIndexes)]
-    .filter((index) => Number.isInteger(index) && index >= 0 && index < blocks.length)
-    .filter((index) => isParagraphNode(blocks[index]))
+    .filter((index) => Number.isInteger(index) && index >= 0 && index < paragraphs.length)
     .sort((left, right) => left - right);
 }
 
@@ -363,8 +563,3 @@ function clampLevel(level: number): number {
 function isDocumentRoot(value: unknown): value is { type: "doc"; children: unknown[] } {
   return Boolean(value) && typeof value === "object" && (value as { type?: string }).type === "doc";
 }
-
-function isParagraphNode(value: unknown): value is ParagraphNode {
-  return Boolean(value) && typeof value === "object" && (value as { type?: string }).type === "paragraph";
-}
-