@pooder/kit 6.2.2 → 6.3.1

package/src/extensions/image/ImageTool.ts

@@ -39,6 +39,12 @@ import {
 } from "../../shared/constants/layers";
 import { createImageCommands } from "./commands";
 import { createImageConfigurations } from "./config";
+import {
+  computeImageOperationUpdates,
+  resolveImageOperationArea,
+  type ImageOperation,
+} from "./imageOperations";
+import { validateImagePlacement } from "./imagePlacement";
 import { buildImageSessionOverlaySpecs } from "./sessionOverlay";
 
 export interface ImageItem {
@@ -53,6 +59,37 @@ export interface ImageItem {
   committedUrl?: string;
 }
 
+export interface ImageTransformUpdates {
+  scale?: number;
+  angle?: number;
+  left?: number;
+  top?: number;
+  opacity?: number;
+}
+
+export interface ImageViewState {
+  items: ImageItem[];
+  hasAnyImage: boolean;
+  focusedId: string | null;
+  focusedItem: ImageItem | null;
+  isToolActive: boolean;
+  isImageSelectionActive: boolean;
+  hasWorkingChanges: boolean;
+  source: "working" | "committed";
+  placementPolicy: ImageSessionPlacementPolicy;
+  sessionNotice: ImageSessionNotice | null;
+}
+
+export type ImageSessionPlacementPolicy = "free" | "warn" | "strict";
+
+export interface ImageSessionNotice {
+  code: "image-outside-frame";
+  level: "warning" | "error";
+  message: string;
+  imageIds: string[];
+  policy: ImageSessionPlacementPolicy;
+}
+
 interface RenderImageState {
   src: string;
   left: number;
@@ -92,14 +129,7 @@ interface UpsertImageOptions {
   id?: string;
   mode?: "replace" | "add";
   addOptions?: Partial<ImageItem>;
-  fitOnAdd?: boolean;
-}
-
-interface DielineFitArea {
-  width: number;
-  height: number;
-  left: number;
-  top: number;
+  operation?: ImageOperation;
 }
 
 interface UpdateImageOptions {
@@ -221,6 +251,7 @@ export class ImageTool implements Extension {
   private activeSnapX: SnapMatch | null = null;
   private activeSnapY: SnapMatch | null = null;
   private movingImageId: string | null = null;
+  private sessionNotice: ImageSessionNotice | null = null;
   private hasRenderedSnapGuides = false;
   private canvasObjectMovingHandler?: (e: any) => void;
   private canvasMouseUpHandler?: (e: any) => void;
@@ -332,8 +363,12 @@ export class ImageTool implements Extension {
           if (
             e.key.startsWith("size.") ||
             e.key.startsWith("image.frame.") ||
+            e.key.startsWith("image.session.") ||
             e.key.startsWith("image.control.")
           ) {
+            if (e.key === "image.session.placementPolicy") {
+              this.clearSessionNotice();
+            }
             if (e.key.startsWith("image.control.")) {
               this.imageControlsByCapabilityKey.clear();
             }
@@ -370,6 +405,7 @@ export class ImageTool implements Extension {
     this.clearRenderedImages();
     this.renderProducerDisposable?.dispose();
     this.renderProducerDisposable = undefined;
+    this.emitImageStateChange();
     if (this.canvasService) {
       void this.canvasService.flushRenderFromProducers();
       this.canvasService = undefined;
@@ -932,9 +968,10 @@ export class ImageTool implements Extension {
           name: "Image",
           interaction: "session",
           commands: {
-            begin: "resetWorkingImages",
+            begin: "imageSessionReset",
+            validate: "validateImageSession",
             commit: "completeImages",
-            rollback: "resetWorkingImages",
+            rollback: "imageSessionReset",
           },
           session: {
             autoBegin: true,
@@ -979,6 +1016,77 @@ export class ImageTool implements Extension {
     return this.normalizeItems((items || []).map((i) => ({ ...i })));
   }
 
+  private getViewItems(): ImageItem[] {
+    return this.isToolActive ? this.workingItems : this.items;
+  }
+
+  private getPlacementPolicy(): ImageSessionPlacementPolicy {
+    const policy = this.getConfig<ImageSessionPlacementPolicy>(
+      "image.session.placementPolicy",
+      "free",
+    );
+    return policy === "warn" || policy === "strict" ? policy : "free";
+  }
+
+  private areSessionNoticesEqual(
+    a: ImageSessionNotice | null,
+    b: ImageSessionNotice | null,
+  ): boolean {
+    if (!a && !b) return true;
+    if (!a || !b) return false;
+    return (
+      a.code === b.code &&
+      a.level === b.level &&
+      a.message === b.message &&
+      a.policy === b.policy &&
+      JSON.stringify(a.imageIds) === JSON.stringify(b.imageIds)
+    );
+  }
+
+  private setSessionNotice(
+    notice: ImageSessionNotice | null,
+    options: { emit?: boolean } = {},
+  ) {
+    if (this.areSessionNoticesEqual(this.sessionNotice, notice)) {
+      return;
+    }
+    this.sessionNotice = notice;
+    if (options.emit !== false) {
+      this.context?.eventBus.emit("image:session:notice", this.sessionNotice);
+      this.emitImageStateChange();
+    }
+  }
+
+  private clearSessionNotice(options: { emit?: boolean } = {}) {
+    this.setSessionNotice(null, options);
+  }
+
+  private getImageViewState(): ImageViewState {
+    this.syncToolActiveFromWorkbench();
+    const items = this.cloneItems(this.getViewItems());
+    const focusedItem =
+      this.focusedImageId == null
+        ? null
+        : items.find((item) => item.id === this.focusedImageId) || null;
+
+    return {
+      items,
+      hasAnyImage: items.length > 0,
+      focusedId: this.focusedImageId,
+      focusedItem,
+      isToolActive: this.isToolActive,
+      isImageSelectionActive: this.isImageSelectionActive,
+      hasWorkingChanges: this.hasWorkingChanges,
+      source: this.isToolActive ? "working" : "committed",
+      placementPolicy: this.getPlacementPolicy(),
+      sessionNotice: this.sessionNotice,
+    };
+  }
+
+  private emitImageStateChange() {
+    this.context?.eventBus.emit("image:state:change", this.getImageViewState());
+  }
+
   private emitWorkingChange(changedId: string | null = null) {
     this.context?.eventBus.emit("image:working:change", {
       changedId,
@@ -1026,6 +1134,8 @@ export class ImageTool implements Extension {
 
     if (!options.skipRender) {
       this.updateImages();
+    } else {
+      this.emitImageStateChange();
     }
 
     return { ok: true, id };
@@ -1034,8 +1144,10 @@ export class ImageTool implements Extension {
   private async addImageEntry(
     url: string,
     options?: Partial<ImageItem>,
-    fitOnAdd = true,
+    operation?: ImageOperation,
   ): Promise<string> {
+    this.syncToolActiveFromWorkbench();
+    this.clearSessionNotice({ emit: false });
     const id = this.generateId();
     const newItem = this.normalizeItem({
       id,
@@ -1044,13 +1156,20 @@ export class ImageTool implements Extension {
       ...options,
     } as ImageItem);
 
-    const sessionDirtyBeforeAdd = this.isToolActive && this.hasWorkingChanges;
     const waitLoaded = this.waitImageLoaded(id, true);
-    this.updateConfig([...this.items, newItem]);
-    this.addItemToWorkingSessionIfNeeded(newItem, sessionDirtyBeforeAdd);
+    if (this.isToolActive) {
+      this.workingItems = this.cloneItems([...this.workingItems, newItem]);
+      this.hasWorkingChanges = true;
+      this.updateImages();
+      this.emitWorkingChange(id);
+    } else {
+      this.updateConfig([...this.items, newItem]);
+    }
     const loaded = await waitLoaded;
-    if (loaded && fitOnAdd) {
-      await this.fitImageToDefaultArea(id);
+    if (loaded && operation) {
+      await this.applyImageOperation(id, operation, {
+        target: this.isToolActive ? "working" : "config",
+      });
     }
     if (loaded) {
       this.setImageFocus(id);
@@ -1062,8 +1181,8 @@ export class ImageTool implements Extension {
     url: string,
     options: UpsertImageOptions = {},
   ): Promise<{ id: string; mode: "replace" | "add" }> {
+    this.syncToolActiveFromWorkbench();
     const mode = options.mode || (options.id ? "replace" : "add");
-    const fitOnAdd = options.fitOnAdd !== false;
     if (mode === "replace") {
       if (!options.id) {
         throw new Error("replace-target-id-required");
@@ -1072,25 +1191,39 @@ export class ImageTool implements Extension {
       if (!this.hasImageItem(targetId)) {
         throw new Error("replace-target-not-found");
       }
-      await this.updateImageInConfig(targetId, { url });
+      if (this.isToolActive) {
+        const current =
+          this.workingItems.find((item) => item.id === targetId) ||
+          this.items.find((item) => item.id === targetId);
+        this.purgeSourceSizeCacheForItem(current);
+        this.updateImageInWorking(targetId, {
+          url,
+          sourceUrl: url,
+          committedUrl: undefined,
+        });
+      } else {
+        await this.updateImageInConfig(targetId, { url });
+      }
+      const loaded = await this.waitImageLoaded(targetId, true);
+      if (loaded && options.operation) {
+        await this.applyImageOperation(targetId, options.operation, {
+          target: this.isToolActive ? "working" : "config",
+        });
+      }
+      if (loaded) {
+        this.setImageFocus(targetId);
+      }
       return { id: targetId, mode: "replace" };
     }
 
-    const id = await this.addImageEntry(url, options.addOptions, fitOnAdd);
+    const id = await this.addImageEntry(
+      url,
+      options.addOptions,
+      options.operation,
+    );
     return { id, mode: "add" };
   }
 
-  private addItemToWorkingSessionIfNeeded(
-    item: ImageItem,
-    sessionDirtyBeforeAdd: boolean,
-  ) {
-    if (!sessionDirtyBeforeAdd || !this.isToolActive) return;
-    if (this.workingItems.some((existing) => existing.id === item.id)) return;
-    this.workingItems = this.cloneItems([...this.workingItems, item]);
-    this.updateImages();
-    this.emitWorkingChange(item.id);
-  }
-
   private async updateImage(
     id: string,
     updates: Partial<ImageItem>,
@@ -1134,6 +1267,7 @@ export class ImageTool implements Extension {
 
   private updateConfig(newItems: ImageItem[], skipCanvasUpdate = false) {
     if (!this.context) return;
+    this.clearSessionNotice({ emit: false });
     this.applyCommittedItems(newItems);
     runDeferredConfigUpdate(
       this,
@@ -1165,38 +1299,6 @@ export class ImageTool implements Extension {
     return this.canvasService.toScreenRect(frame || this.getFrameRect());
   }
 
-  private async resolveDefaultFitArea(): Promise<DielineFitArea | null> {
-    if (!this.canvasService) return null;
-    const frame = this.getFrameRect();
-    if (frame.width <= 0 || frame.height <= 0) return null;
-    return {
-      width: Math.max(1, frame.width),
-      height: Math.max(1, frame.height),
-      left: frame.left + frame.width / 2,
-      top: frame.top + frame.height / 2,
-    };
-  }
-
-  private async fitImageToDefaultArea(id: string) {
-    if (!this.canvasService) return;
-    const area = await this.resolveDefaultFitArea();
-
-    if (area) {
-      await this.fitImageToArea(id, area);
-      return;
-    }
-
-    const viewport = this.canvasService.getSceneViewportRect();
-    const canvasW = Math.max(1, viewport.width || 0);
-    const canvasH = Math.max(1, viewport.height || 0);
-    await this.fitImageToArea(id, {
-      width: canvasW,
-      height: canvasH,
-      left: viewport.left + canvasW / 2,
-      top: viewport.top + canvasH / 2,
-    });
-  }
-
   private getImageObjects(): any[] {
     if (!this.canvasService) return [];
     return this.canvasService.canvas.getObjects().filter((obj: any) => {
@@ -1279,6 +1381,82 @@ export class ImageTool implements Extension {
     return getCoverScaleFromRect(frame, size);
   }
 
+  private resolvePlacementState(item: ImageItem) {
+    return {
+      left: Number.isFinite(item.left as any) ? (item.left as number) : 0.5,
+      top: Number.isFinite(item.top as any) ? (item.top as number) : 0.5,
+      scale: Math.max(0.05, item.scale ?? 1),
+      angle: Number.isFinite(item.angle as any) ? (item.angle as number) : 0,
+    };
+  }
+
+  private async validatePlacementForItem(item: ImageItem): Promise<boolean> {
+    const frame = this.getFrameRect();
+    if (!frame.width || !frame.height) {
+      return true;
+    }
+
+    const src = item.sourceUrl || item.url;
+    if (!src) {
+      return true;
+    }
+
+    const source = await this.resolveImageSourceSize(item.id, src);
+    if (!source) {
+      return true;
+    }
+
+    return validateImagePlacement({
+      frame,
+      source,
+      placement: this.resolvePlacementState(item),
+    }).ok;
+  }
+
+  private async validateImageSession() {
+    const policy = this.getPlacementPolicy();
+    if (policy === "free") {
+      this.clearSessionNotice();
+      return { ok: true, policy };
+    }
+
+    const invalidImageIds: string[] = [];
+    for (const item of this.workingItems) {
+      const valid = await this.validatePlacementForItem(item);
+      if (!valid) {
+        invalidImageIds.push(item.id);
+      }
+    }
+
+    if (!invalidImageIds.length) {
+      this.clearSessionNotice();
+      return { ok: true, policy };
+    }
+
+    const notice: ImageSessionNotice = {
+      code: "image-outside-frame",
+      level: policy === "strict" ? "error" : "warning",
+      message:
+        policy === "strict"
+          ? "图片位置不能超出 frame，请调整后再提交。"
+          : "图片位置已超出 frame，建议调整后再提交。",
+      imageIds: invalidImageIds,
+      policy,
+    };
+    this.setSessionNotice(notice);
+    this.setImageFocus(invalidImageIds[0], {
+      syncCanvasSelection: true,
+      skipRender: true,
+    });
+    return {
+      ok: policy !== "strict",
+      reason: notice.code,
+      message: notice.message,
+      imageIds: notice.imageIds,
+      policy: notice.policy,
+    };
+  }
+
   private getFrameVisualConfig(): FrameVisualConfig {
     const strokeStyleRaw = (this.getConfig<string>(
       "image.frame.strokeStyle",
@@ -1587,6 +1765,7 @@ export class ImageTool implements Extension {
       isImageSelectionActive: this.isImageSelectionActive,
       focusedImageId: this.focusedImageId,
     });
+    this.emitImageStateChange();
     this.canvasService.requestRenderAll();
   }
 
@@ -1594,6 +1773,41 @@ export class ImageTool implements Extension {
     return Math.max(-1, Math.min(2, value));
   }
 
+  private async setImageTransform(
+    id: string,
+    updates: ImageTransformUpdates,
+    options: UpdateImageOptions = {},
+  ) {
+    const next: Partial<ImageItem> = {};
+
+    if (Number.isFinite(updates.scale as number)) {
+      next.scale = Math.max(0.05, Number(updates.scale));
+    }
+    if (Number.isFinite(updates.angle as number)) {
+      next.angle = Number(updates.angle);
+    }
+    if (Number.isFinite(updates.left as number)) {
+      next.left = this.clampNormalized(Number(updates.left));
+    }
+    if (Number.isFinite(updates.top as number)) {
+      next.top = this.clampNormalized(Number(updates.top));
+    }
+    if (Number.isFinite(updates.opacity as number)) {
+      next.opacity = Math.max(0, Math.min(1, Number(updates.opacity)));
+    }
+
+    if (!Object.keys(next).length) return;
+    await this.updateImage(id, next, options);
+  }
+
+  private resetImageSession() {
+    this.clearSessionNotice({ emit: false });
+    this.workingItems = this.cloneItems(this.items);
+    this.hasWorkingChanges = false;
+    this.updateImages();
+    this.emitWorkingChange();
+  }
+
   private onObjectModified = (e: any) => {
     if (!this.isToolActive) return;
     const target = e?.target;
@@ -1637,6 +1851,7 @@ export class ImageTool implements Extension {
     const index = this.workingItems.findIndex((item) => item.id === id);
     if (index < 0) return;
 
+    this.clearSessionNotice({ emit: false });
     const next = [...this.workingItems];
     next[index] = this.normalizeItem({ ...next[index], ...updates });
     this.workingItems = next;
@@ -1655,6 +1870,7 @@ export class ImageTool implements Extension {
     const index = this.items.findIndex((item) => item.id === id);
     if (index < 0) return;
 
+    this.clearSessionNotice({ emit: false });
     const replacingSource =
       typeof updates.url === "string" && updates.url.length > 0;
     const next = [...this.items];
@@ -1669,10 +1885,6 @@ export class ImageTool implements Extension {
             url: replacingUrl,
             sourceUrl: replacingUrl,
             committedUrl: undefined,
-            scale: updates.scale ?? 1,
-            angle: updates.angle ?? 0,
-            left: updates.left ?? 0.5,
-            top: updates.top ?? 0.5,
           }
         : {}),
     });
@@ -1680,14 +1892,7 @@ export class ImageTool implements Extension {
     this.updateConfig(next);
 
     if (replacingSource) {
-      this.debug("replace:image:begin", { id, replacingUrl });
       this.purgeSourceSizeCacheForItem(base);
-      const loaded = await this.waitImageLoaded(id, true);
-      this.debug("replace:image:loaded", { id, loaded });
-      if (loaded) {
-        await this.refitImageToFrame(id);
-        this.setImageFocus(id);
-      }
     }
   }
 
@@ -1709,93 +1914,62 @@ export class ImageTool implements Extension {
     });
   }
 
-  private async refitImageToFrame(id: string) {
+  private async resolveImageSourceSize(
+    id: string,
+    src: string,
+  ): Promise<SourceSize | null> {
     const obj = this.getImageObject(id);
-    if (!obj || !this.canvasService) return;
-    const current = this.items.find((item) => item.id === id);
-    if (!current) return;
-    const render = this.resolveRenderImageState(current);
-
-    this.rememberSourceSize(render.src, obj);
-    const source = this.getSourceSize(render.src, obj);
-    const frame = this.getFrameRect();
-    const coverScale = this.getCoverScale(frame, source);
-
-    const currentScale = this.toSceneObjectScale(obj.scaleX || 1);
-    const zoom = Math.max(0.05, currentScale / coverScale);
-
-    const updated: Partial<ImageItem> = {
-      scale: Number.isFinite(zoom) ? zoom : 1,
-      angle: 0,
-      left: 0.5,
-      top: 0.5,
-    };
-
-    const index = this.items.findIndex((item) => item.id === id);
-    if (index < 0) return;
+    if (obj) {
+      this.rememberSourceSize(src, obj);
+    }
+    const ensured = await this.ensureSourceSize(src);
+    if (ensured) return ensured;
+    if (!obj) return null;
 
-    const next = [...this.items];
-    next[index] = this.normalizeItem({ ...next[index], ...updated });
-    this.updateConfig(next);
-    this.workingItems = this.cloneItems(next);
-    this.hasWorkingChanges = false;
-    this.updateImages();
-    this.emitWorkingChange(id);
+    const width = Number(obj?.width || 0);
+    const height = Number(obj?.height || 0);
+    if (width <= 0 || height <= 0) return null;
+    return { width, height };
   }
 
-  private async fitImageToArea(
+  private async applyImageOperation(
     id: string,
-    area: { width: number; height: number; left?: number; top?: number },
+    operation: ImageOperation,
+    options: UpdateImageOptions = {},
   ) {
     if (!this.canvasService) return;
 
-    const loaded = await this.waitImageLoaded(id, false);
-    if (!loaded) return;
-
-    const obj = this.getImageObject(id);
-    if (!obj) return;
-    const renderItems = this.isToolActive ? this.workingItems : this.items;
+    this.syncToolActiveFromWorkbench();
+    const target = options.target || "auto";
+    const renderItems =
+      target === "working" || (target === "auto" && this.isToolActive)
+        ? this.workingItems
+        : this.items;
     const current = renderItems.find((item) => item.id === id);
     if (!current) return;
+
     const render = this.resolveRenderImageState(current);
+    const source = await this.resolveImageSourceSize(id, render.src);
+    if (!source) return;
 
-    this.rememberSourceSize(render.src, obj);
-    const source = this.getSourceSize(render.src, obj);
     const frame = this.getFrameRect();
-    const baseCover = this.getCoverScale(frame, source);
-
-    const desiredScale = Math.max(
-      Math.max(1, area.width) / Math.max(1, source.width),
-      Math.max(1, area.height) / Math.max(1, source.height),
-    );
-
     const viewport = this.canvasService.getSceneViewportRect();
-    const canvasW = viewport.width || 1;
-    const canvasH = viewport.height || 1;
-
-    const areaLeftInput = area.left ?? 0.5;
-    const areaTopInput = area.top ?? 0.5;
-
-    const areaLeftPx =
-      areaLeftInput <= 1.5
-        ? viewport.left + areaLeftInput * canvasW
-        : areaLeftInput;
-    const areaTopPx =
-      areaTopInput <= 1.5
-        ? viewport.top + areaTopInput * canvasH
-        : areaTopInput;
-
-    const updates: Partial<ImageItem> = {
-      scale: Math.max(0.05, desiredScale / baseCover),
-      left: this.clampNormalized(
-        (areaLeftPx - frame.left) / Math.max(1, frame.width),
-      ),
-      top: this.clampNormalized(
-        (areaTopPx - frame.top) / Math.max(1, frame.height),
-      ),
-    };
+    const area =
+      operation.type === "resetTransform"
+        ? resolveImageOperationArea({ frame, viewport })
+        : resolveImageOperationArea({
+            frame,
+            viewport,
+            area: operation.area,
+          });
+    const updates = computeImageOperationUpdates({
+      frame,
+      source,
+      operation,
+      area,
+    });
 
-    if (this.isToolActive) {
+    if (target === "working" || (target === "auto" && this.isToolActive)) {
       this.updateImageInWorking(id, updates);
       return;
     }
@@ -1841,12 +2015,44 @@ export class ImageTool implements Extension {
     }
 
     this.hasWorkingChanges = false;
+    this.clearSessionNotice({ emit: false });
     this.workingItems = this.cloneItems(next);
     this.updateConfig(next);
     this.emitWorkingChange(this.focusedImageId);
     return { ok: true };
   }
 
+  private async completeImageSession() {
+    const sessionState =
+      this.context?.services.get<ToolSessionService>("ToolSessionService");
+    const workbench = this.context?.services.get<any>("WorkbenchService");
+    console.info("[ImageTool] completeImageSession:start", {
+      activeToolId: workbench?.activeToolId ?? null,
+      isToolActive: this.isToolActive,
+      dirtyBeforeComplete: this.hasWorkingChanges,
+      workingCount: this.workingItems.length,
+      committedCount: this.items.length,
+      sessionDirty: sessionState?.isDirty(this.id),
+    });
+    const validation = await this.validateImageSession();
+    if (!validation.ok) {
+      console.warn("[ImageTool] completeImageSession:validation-failed", {
+        validation,
+        dirtyAfterValidation: this.hasWorkingChanges,
+      });
+      return validation;
+    }
+    const result = await this.commitWorkingImagesAsCropped();
+    console.info("[ImageTool] completeImageSession:done", {
+      result,
+      dirtyAfterComplete: this.hasWorkingChanges,
+      workingCount: this.workingItems.length,
+      committedCount: this.items.length,
+      sessionDirty: sessionState?.isDirty(this.id),
+    });
+    return result;
+  }
+
   private async exportCroppedImageByIds(
     imageIds: string[],
     options: ExportCroppedImageOptions,