@beyondwork/docx-react-component 1.0.29 → 1.0.30

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

@@ -0,0 +1,373 @@
+import {
+  cloneParagraphProperties,
+  cloneStoryUnit,
+  parseTextStory,
+  serializeTextStory,
+  type TextStory,
+} from "../schema/text-schema.ts";
+import { createSelectionSnapshot, type CanonicalDocumentEnvelope, type SelectionSnapshot } from "../state/editor-state.ts";
+import { TextTransactionError } from "../state/text-transaction.ts";
+import type { TransactionMapping } from "../selection/mapping.ts";
+import type { MediaItem, ParagraphNode } from "../../model/canonical-document.ts";
+import {
+  replaceParagraphScope,
+  resolveParagraphScope,
+} from "./structural-helpers.ts";
+
+export interface ImageCommandContext {
+  timestamp: string;
+  altText?: string;
+  display?: "inline" | "floating";
+}
+
+export interface InsertImageResult {
+  document: CanonicalDocumentEnvelope;
+  selection: SelectionSnapshot;
+  mapping: TransactionMapping;
+  mediaId: string;
+}
+
+/**
+ * Insert an image into the document at the current selection.
+ *
+ * Registers a MediaItem in the catalog with the supplied mimeType and
+ * optional dimensions, then inserts an image unit into the text story.
+ * Binary data is NOT stored in the canonical document — callers are
+ * responsible for persisting it to an external media store.
+ */
+export function insertImage(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  _data: Uint8Array | string,
+  mimeType: string,
+  _width?: number,
+  _height?: number,
+  context: ImageCommandContext = { timestamp: new Date().toISOString() },
+): InsertImageResult {
+  const scope = resolveParagraphScope(document, selection);
+  if (!scope) {
+    throw new TextTransactionError(
+      "unsupported_content",
+      "Image insertion is only supported when the selection stays within one paragraph-backed scope.",
+    );
+  }
+
+  const localDocument: CanonicalDocumentEnvelope = {
+    ...document,
+    content: {
+      type: "doc",
+      children: [scope.paragraph],
+    },
+  };
+  const localSelection = createSelectionSnapshot(
+    selection.anchor - scope.paragraphStart,
+    selection.head - scope.paragraphStart,
+  );
+  const localResult = insertImageIntoParagraph(
+    localDocument,
+    localSelection,
+    _data,
+    mimeType,
+    _width,
+    _height,
+    context,
+  );
+  const nextDocument = replaceParagraphScope(
+    {
+      ...document,
+      media: localResult.document.media,
+    },
+    scope,
+    [
+      {
+        ...scope.paragraph,
+        children:
+          localResult.document.content.type === "doc"
+            ? (localResult.document.content.children.find(
+                (block): block is ParagraphNode => block.type === "paragraph",
+              )?.children ?? scope.paragraph.children)
+            : scope.paragraph.children,
+      },
+    ],
+  );
+
+  return {
+    ...localResult,
+    document: {
+      ...nextDocument,
+      updatedAt: context.timestamp,
+      media: localResult.document.media,
+    },
+    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,
+      })),
+    },
+  };
+}
+
+function insertImageIntoParagraph(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  _data: Uint8Array | string,
+  mimeType: string,
+  width?: number,
+  height?: number,
+  context: ImageCommandContext = { timestamp: new Date().toISOString() },
+): InsertImageResult {
+  const story = parseTextStory(document.content);
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+
+  if (from > story.size || to > story.size) {
+    throw new TextTransactionError(
+      "invalid_selection",
+      `Selection ${from}-${to} exceeds story size ${story.size}.`,
+    );
+  }
+
+  // Reject insertions whose replacement range crosses protected content.
+  const rangeUnits = story.units.slice(from, to);
+  const protectedUnit = rangeUnits.find(
+    (unit) =>
+      unit.kind === "opaque_inline" ||
+      unit.kind === "opaque_block" ||
+      unit.kind === "image",
+  );
+  if (protectedUnit) {
+    throw new TextTransactionError(
+      "unsupported_content",
+      `Image insertion range crosses protected ${protectedUnit.kind} content.`,
+    );
+  }
+
+  const ext = mimeTypeToExtension(mimeType);
+  const timestamp = context.timestamp.replace(/[^0-9]/g, "").slice(0, 14);
+  const mediaId = `media:img-${timestamp}`;
+  const packagePartName = `/word/media/${mediaId.replace("media:", "")}.${ext}`;
+
+  const mediaItem: MediaItem = {
+    mediaId,
+    contentType: mimeType,
+    filename: `${mediaId.replace("media:", "")}.${ext}`,
+    packagePartName,
+    ...(context.altText ? { altText: context.altText } : {}),
+    ...(context.display ? { display: context.display } : {}),
+  };
+
+  const existingItems =
+    document.media && "items" in document.media
+      ? (document.media as { items: Record<string, MediaItem> }).items
+      : {};
+
+  const updatedMedia = {
+    items: {
+      ...existingItems,
+      [mediaId]: mediaItem,
+    },
+  };
+
+  const nextUnits = [
+    ...story.units.slice(0, from).map(cloneStoryUnit),
+    {
+      kind: "image" as const,
+      mediaId,
+      ...(context.altText ? { altText: context.altText } : {}),
+    },
+    ...story.units.slice(to).map(cloneStoryUnit),
+  ];
+
+  const nextStory: TextStory = {
+    firstParagraph: cloneParagraphProperties(story.firstParagraph),
+    units: nextUnits,
+    size: nextUnits.length,
+  };
+
+  const caret = from + 1;
+
+  return {
+    document: {
+      ...document,
+      updatedAt: context.timestamp,
+      media: updatedMedia,
+      content: serializeTextStory(nextStory),
+    },
+    selection: createSelectionSnapshot(caret, caret),
+    mapping: {
+      steps: [{ from, to, insertSize: 1 }],
+    },
+    mediaId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 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":
+      return "png";
+    case "image/jpeg":
+    case "image/jpg":
+      return "jpg";
+    case "image/gif":
+      return "gif";
+    case "image/webp":
+      return "webp";
+    case "image/svg+xml":
+      return "svg";
+    case "image/bmp":
+      return "bmp";
+    default:
+      return "bin";
+  }
+}