@univerjs/sheets-drawing 1.0.0-alpha.8 → 1.0.0-beta.1

package/lib/es/facade.js

@@ -2,7 +2,7 @@ import { ArrangeTypeEnum, CanceledError, DrawingTypeEnum, ICommandService, IUndo
 import { FBase, FEnum, FEventName, FUniver } from "@univerjs/core/facade";
 import { IDrawingManagerService, SetDrawingSelectedOperation, getImageSize, isGroupableDrawingType } from "@univerjs/drawing";
 import { SheetSkeletonService, convertPositionCellToSheetOverGrid, convertPositionSheetOverGridToAbsolute } from "@univerjs/sheets";
-import { DrawingApplyType, ISheetDrawingService, InsertSheetDrawingCommand, RemoveSheetDrawingCommand, SetDrawingApplyMutation, SetDrawingArrangeCommand, SetSheetDrawingCommand, SheetDrawingAnchorType, transformToAxisAlignPosition } from "@univerjs/sheets-drawing";
+import { DrawingApplyType, ISheetDrawingService, InsertSheetDrawingCommand, RemoveSheetDrawingCommand, SetDrawingApplyMutation, SetDrawingArrangeCommand, SetSheetDrawingCommand, SetSheetDrawingPlacementCommand, SheetDrawingAnchorType, applySheetDrawingPlacement, getSheetDrawingPlacement, normalizeSheetDrawingPlacement, transformToAxisAlignPosition } from "@univerjs/sheets-drawing";
 import { getGroupState, transformObjectOutOfGroup } from "@univerjs/engine-render";
 import { FWorksheet } from "@univerjs/sheets/facade";
 
@@ -132,9 +132,10 @@ function convertFOverGridImageToSheetImage(fOverGridImage, sheetSkeletonService)
 	};
 }
 let FOverGridImageBuilder = class FOverGridImageBuilder {
-	constructor(unitId, subUnitId, _injector) {
-		this._injector = _injector;
+	constructor(unitId, subUnitId, _sheetSkeletonService) {
+		this._sheetSkeletonService = _sheetSkeletonService;
 		_defineProperty(this, "_image", void 0);
+		_defineProperty(this, "_placement", void 0);
 		this._image = {
 			drawingId: generateRandomId(6),
 			drawingType: DrawingTypeEnum.DRAWING_IMAGE,
@@ -192,7 +193,7 @@ let FOverGridImageBuilder = class FOverGridImageBuilder {
 	*/
 	setImage(image) {
 		const { unitId, subUnitId } = image;
-		const skeleton = this._injector.get(SheetSkeletonService).getSkeleton(unitId, subUnitId);
+		const skeleton = this._sheetSkeletonService.getSkeleton(unitId, subUnitId);
 		if (!skeleton) throw new Error(`Skeleton for unitId ${unitId} and subUnitId ${subUnitId} not found`);
 		if (image.sheetTransform == null) image.sheetTransform = {
 			from: {
@@ -226,7 +227,7 @@ let FOverGridImageBuilder = class FOverGridImageBuilder {
 		return this;
 	}
 	setSource(source, sourceType) {
-		const sourceTypeVal = sourceType !== null && sourceType !== void 0 ? sourceType : ImageSourceType.URL;
+		const sourceTypeVal = sourceType ?? ImageSourceType.URL;
 		this._image.source = source;
 		this._image.imageSourceType = sourceTypeVal;
 		return this;
@@ -461,6 +462,73 @@ let FOverGridImageBuilder = class FOverGridImageBuilder {
 		return this;
 	}
 	/**
+	* Set an explicit OneCell, TwoCell, or Absolute placement for the image.
+	*
+	* This placement takes precedence over the individual row, column, size,
+	* and anchor type builder fields. Use bounds inference for an existing
+	* transform; use exact markers when a caller explicitly chose cells.
+	* @param {ISheetDrawingPlacementInput} placement Exact placement or bounds with an explicit anchor type.
+	* @returns {FOverGridImageBuilder} This builder.
+	* @example
+	* ```ts
+	* const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+	* const image = await sheet.newOverGridImage()
+	*   .setSource('https://avatars.githubusercontent.com/u/61444807?s=96&v=4')
+	*   .setPlacement({
+	*     kind: univerAPI.Enum.SheetDrawingAnchorType.Position,
+	*     from: { row: 2, column: 2, rowOffset: 8, columnOffset: 8 },
+	*     width: 240,
+	*     height: 120,
+	*   })
+	*   .buildAsync();
+	* sheet.insertImages([image]);
+	* ```
+	* @example Infer Position markers from model-space bounds
+	* ```ts
+	* const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+	* const image = await sheet.newOverGridImage()
+	*   .setSource('https://avatars.githubusercontent.com/u/61444807?s=96&v=4')
+	*   .setPlacement({
+	*     kind: univerAPI.Enum.SheetDrawingAnchorType.Position,
+	*     bounds: { left: 120, top: 80, width: 240, height: 120 },
+	*   })
+	*   .buildAsync();
+	* sheet.insertImages([image]);
+	* ```
+	* @example TwoCell
+	* ```ts
+	* const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+	* const image = await sheet.newOverGridImage()
+	*   .setSource('https://avatars.githubusercontent.com/u/61444807?s=96&v=4')
+	*   .setPlacement({
+	*     kind: univerAPI.Enum.SheetDrawingAnchorType.Both,
+	*     from: { row: 2, column: 2, rowOffset: 8, columnOffset: 8 },
+	*     to: { row: 8, column: 6, rowOffset: 0, columnOffset: 0 },
+	*   })
+	*   .buildAsync();
+	* sheet.insertImages([image]);
+	* ```
+	* @example Absolute
+	* ```ts
+	* const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+	* const image = await sheet.newOverGridImage()
+	*   .setSource('https://avatars.githubusercontent.com/u/61444807?s=96&v=4')
+	*   .setPlacement({
+	*     kind: univerAPI.Enum.SheetDrawingAnchorType.None,
+	*     left: 640,
+	*     top: 96,
+	*     width: 240,
+	*     height: 120,
+	*   })
+	*   .buildAsync();
+	* sheet.insertImages([image]);
+	* ```
+	*/
+	setPlacement(placement) {
+		this._placement = placement;
+		return this;
+	}
+	/**
 	* Set the cropping region of the image by defining the top edges, thereby displaying the specific part of the image you want.
 	* @param {number} top - The number of pixels to crop from the top of the image
 	* @returns {FOverGridImageBuilder} The `FOverGridImageBuilder` for chaining
@@ -601,24 +669,63 @@ let FOverGridImageBuilder = class FOverGridImageBuilder {
 		return this;
 	}
 	async buildAsync() {
-		const sheetSkeletonService = this._injector.get(SheetSkeletonService);
-		if (this._image.width === 0 || this._image.height === 0) {
+		var _this$_placement;
+		const sheetSkeletonService = this._sheetSkeletonService;
+		if (!this._placement && (this._image.width === 0 || this._image.height === 0)) {
 			const size = await getImageSize(this._image.source);
 			const width = size.width;
 			const height = size.height;
 			if (this._image.width === 0) this._image.width = width;
 			if (this._image.height === 0) this._image.height = height;
 		}
-		return convertFOverGridImageToSheetImage(this._image, sheetSkeletonService);
+		if (((_this$_placement = this._placement) === null || _this$_placement === void 0 ? void 0 : _this$_placement.kind) === SheetDrawingAnchorType.None) {
+			const { left, top, width, height } = "bounds" in this._placement ? this._placement.bounds : this._placement;
+			const sheetTransform = {
+				from: {
+					column: 0,
+					columnOffset: left,
+					row: 0,
+					rowOffset: top
+				},
+				to: {
+					column: 0,
+					columnOffset: left + width,
+					row: 0,
+					rowOffset: top + height
+				}
+			};
+			return applySheetDrawingPlacement({
+				...this._image,
+				transform: {
+					left,
+					top,
+					width,
+					height,
+					flipY: this._image.flipY,
+					flipX: this._image.flipX,
+					angle: this._image.angle,
+					skewX: this._image.skewX,
+					skewY: this._image.skewY
+				},
+				sheetTransform,
+				axisAlignSheetTransform: sheetTransform
+			}, this._placement);
+		}
+		const image = convertFOverGridImageToSheetImage(this._image, sheetSkeletonService);
+		if (!this._placement) return image;
+		const skeleton = sheetSkeletonService.ensureSkeleton(image.unitId, image.subUnitId);
+		return applySheetDrawingPlacement(image, this._placement, skeleton);
 	}
 };
-FOverGridImageBuilder = __decorate([__decorateParam(2, Inject(Injector))], FOverGridImageBuilder);
+FOverGridImageBuilder = __decorate([__decorateParam(2, Inject(SheetSkeletonService))], FOverGridImageBuilder);
 let FOverGridImage = class FOverGridImage extends FBase {
-	constructor(_image, _commandService, _injector) {
+	constructor(_image, _commandService, _injector, _sheetDrawingService, _sheetSkeletonService) {
 		super();
 		this._image = _image;
 		this._commandService = _commandService;
 		this._injector = _injector;
+		this._sheetDrawingService = _sheetDrawingService;
+		this._sheetSkeletonService = _sheetSkeletonService;
 	}
 	/**
 	* Get the id of the image
@@ -655,6 +762,78 @@ let FOverGridImage = class FOverGridImage extends FBase {
 		return this._image.drawingType;
 	}
 	/**
+	* Get this image's explicit placement.
+	* @returns {ISheetDrawingPlacement} OneCell, TwoCell, or Absolute placement.
+	* @example
+	* ```ts
+	* const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0];
+	* console.log(image.getPlacement());
+	* ```
+	*/
+	getPlacement() {
+		return getSheetDrawingPlacement(this._sheetDrawingService.getDrawingByParam({
+			unitId: this._image.unitId,
+			subUnitId: this._image.subUnitId,
+			drawingId: this._image.drawingId
+		}) ?? this._image);
+	}
+	/**
+	* Set this image's explicit placement through the drawing command.
+	* `Position`, `Both`, and `None` correspond to OneCell, TwoCell, and
+	* Absolute. Bounds inference is preferable when preserving the current
+	* visual bounds; exact markers are for user-selected cells and offsets.
+	* @param {ISheetDrawingPlacementInput} placement Exact placement or bounds with an explicit anchor type.
+	* @returns {boolean} `true` when the command succeeds.
+	* @example OneCell
+	* ```ts
+	* const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0];
+	* image.setPlacement({
+	*   kind: univerAPI.Enum.SheetDrawingAnchorType.Position,
+	*   from: { row: 4, column: 3, rowOffset: 8, columnOffset: 8 },
+	*   width: 320,
+	*   height: 180,
+	* });
+	* ```
+	* @example Infer TwoCell markers while preserving current model-space bounds
+	* ```ts
+	* const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0];
+	* image.setPlacement({
+	*   kind: univerAPI.Enum.SheetDrawingAnchorType.Both,
+	*   bounds: { left: 120, top: 80, width: 320, height: 160 },
+	* });
+	* ```
+	* @example TwoCell
+	* ```ts
+	* const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0];
+	* image.setPlacement({
+	*   kind: univerAPI.Enum.SheetDrawingAnchorType.Both,
+	*   from: { row: 4, column: 3, rowOffset: 8, columnOffset: 8 },
+	*   to: { row: 10, column: 8, rowOffset: 0, columnOffset: 0 },
+	* });
+	* ```
+	* @example Absolute
+	* ```ts
+	* const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0];
+	* image.setPlacement({
+	*   kind: univerAPI.Enum.SheetDrawingAnchorType.None,
+	*   left: 640,
+	*   top: 96,
+	*   width: 320,
+	*   height: 180,
+	* });
+	* ```
+	*/
+	setPlacement(placement) {
+		return this._commandService.syncExecuteCommand(SetSheetDrawingPlacementCommand.id, {
+			unitId: this._image.unitId,
+			subUnitId: this._image.subUnitId,
+			drawings: [{
+				drawingId: this._image.drawingId,
+				placement
+			}]
+		});
+	}
+	/**
 	* Remove the image from the sheet
 	* @returns {boolean} true if the image is removed successfully, otherwise false
 	* @example
@@ -693,7 +872,7 @@ let FOverGridImage = class FOverGridImage extends FBase {
 		return builder;
 	}
 	setSource(source, sourceType) {
-		const sourceTypeVal = sourceType !== null && sourceType !== void 0 ? sourceType : ImageSourceType.URL;
+		const sourceTypeVal = sourceType ?? ImageSourceType.URL;
 		this._image.source = source;
 		this._image.imageSourceType = sourceTypeVal;
 		return this._commandService.syncExecuteCommand(SetSheetDrawingCommand.id, {
@@ -792,7 +971,7 @@ let FOverGridImage = class FOverGridImage extends FBase {
 		this._image.sheetTransform.angle = angle;
 		this._image.transform && (this._image.transform.angle = angle);
 		if (this._image.transform) {
-			const skeleton = this._injector.get(SheetSkeletonService).getSkeleton(this._image.unitId, this._image.subUnitId);
+			const skeleton = this._sheetSkeletonService.getSkeleton(this._image.unitId, this._image.subUnitId);
 			if (!skeleton) throw new Error(`Skeleton for unitId ${this._image.unitId} and subUnitId ${this._image.subUnitId} not found`);
 			this._image.axisAlignSheetTransform && (this._image.axisAlignSheetTransform = transformToAxisAlignPosition(this._image.transform, skeleton));
 		}
@@ -886,11 +1065,25 @@ let FOverGridImage = class FOverGridImage extends FBase {
 		});
 	}
 };
-FOverGridImage = __decorate([__decorateParam(1, ICommandService), __decorateParam(2, Inject(Injector))], FOverGridImage);
+FOverGridImage = __decorate([
+	__decorateParam(1, ICommandService),
+	__decorateParam(2, Inject(Injector)),
+	__decorateParam(3, ISheetDrawingService),
+	__decorateParam(4, Inject(SheetSkeletonService))
+], FOverGridImage);
 
 //#endregion
 //#region src/facade/f-worksheet.ts
 var FWorksheetDrawingMixin = class extends FWorksheet {
+	get _sheetDrawingService() {
+		return this._injector.get(ISheetDrawingService);
+	}
+	get _sheetSkeletonService() {
+		return this._injector.get(SheetSkeletonService);
+	}
+	get _undoRedoService() {
+		return this._injector.get(IUndoRedoService);
+	}
 	async insertImage(url, column, row, offsetX, offsetY) {
 		const imageBuilder = this.newOverGridImage();
 		if (typeof url === "string") imageBuilder.setSource(url);
@@ -940,7 +1133,7 @@ var FWorksheetDrawingMixin = class extends FWorksheet {
 		return this;
 	}
 	getImages() {
-		const drawingData = this._injector.get(ISheetDrawingService).getDrawingData(this._fWorkbook.getId(), this.getSheetId());
+		const drawingData = this._sheetDrawingService.getDrawingData(this._fWorkbook.getId(), this.getSheetId());
 		const images = [];
 		for (const drawingId in drawingData) {
 			const drawing = drawingData[drawingId];
@@ -950,7 +1143,7 @@ var FWorksheetDrawingMixin = class extends FWorksheet {
 		return images;
 	}
 	getImageById(id) {
-		const drawing = this._injector.get(ISheetDrawingService).getDrawingByParam({
+		const drawing = this._sheetDrawingService.getDrawingByParam({
 			unitId: this._fWorkbook.getId(),
 			subUnitId: this.getSheetId(),
 			drawingId: id
@@ -959,7 +1152,7 @@ var FWorksheetDrawingMixin = class extends FWorksheet {
 		return null;
 	}
 	getActiveImages() {
-		const drawingData = this._injector.get(ISheetDrawingService).getFocusDrawings();
+		const drawingData = this._sheetDrawingService.getFocusDrawings();
 		const images = [];
 		for (const drawingId in drawingData) {
 			const drawing = drawingData[drawingId];
@@ -974,6 +1167,70 @@ var FWorksheetDrawingMixin = class extends FWorksheet {
 		});
 		return this;
 	}
+	getDrawingPlacement(drawingId) {
+		const drawing = this._sheetDrawingService.getDrawingByParam({
+			unitId: this._fWorkbook.getId(),
+			subUnitId: this.getSheetId(),
+			drawingId
+		});
+		return drawing ? getSheetDrawingPlacement(drawing) : null;
+	}
+	setDrawingPlacement(drawingId, placement) {
+		return this._commandService.syncExecuteCommand(SetSheetDrawingPlacementCommand.id, {
+			unitId: this._fWorkbook.getId(),
+			subUnitId: this.getSheetId(),
+			drawings: [{
+				drawingId,
+				placement
+			}]
+		});
+	}
+	resolveDrawingPlacement(placement) {
+		const skeleton = placement.kind === SheetDrawingAnchorType.None ? void 0 : this._sheetSkeletonService.ensureSkeleton(this._fWorkbook.getId(), this.getSheetId());
+		if (placement.kind !== SheetDrawingAnchorType.None && !skeleton) throw new Error("SHEET_DRAWING_PLACEMENT_SKELETON_REQUIRED");
+		return normalizeSheetDrawingPlacement(placement, skeleton);
+	}
+	getDrawingLayout() {
+		const unitId = this._fWorkbook.getId();
+		const subUnitId = this.getSheetId();
+		const skeleton = this._sheetSkeletonService.ensureSkeleton(unitId, subUnitId);
+		if (!skeleton) throw new Error("SHEET_DRAWING_PLACEMENT_SKELETON_REQUIRED");
+		const { startRow, endRow, startColumn, endColumn } = this._worksheet.getDataRealRange();
+		const startCell = skeleton.getCellWithCoordByIndex(startRow, startColumn, false);
+		const endCell = skeleton.getCellWithCoordByIndex(endRow, endColumn, false);
+		const drawingService = this._sheetDrawingService;
+		const drawingData = drawingService.getDrawingData(unitId, subUnitId);
+		const orderedIds = drawingService.getDrawingOrder(unitId, subUnitId);
+		const drawingIds = [...orderedIds, ...Object.keys(drawingData).filter((drawingId) => !orderedIds.includes(drawingId))];
+		const drawings = [];
+		for (const drawingId of drawingIds) {
+			const drawing = drawingData[drawingId];
+			const bounds = drawing && getDrawingBounds(drawing);
+			if (!drawing || !bounds) continue;
+			drawings.push({
+				drawingId,
+				drawingType: drawing.drawingType,
+				bounds,
+				placement: getSheetDrawingPlacement(drawing),
+				groupId: drawing.groupId
+			});
+		}
+		return {
+			gridBounds: {
+				left: 0,
+				top: 0,
+				width: skeleton.columnTotalWidth,
+				height: skeleton.rowTotalHeight
+			},
+			dataBounds: {
+				left: startCell.startX,
+				top: startCell.startY,
+				width: endCell.endX - startCell.startX,
+				height: endCell.endY - startCell.startY
+			},
+			drawings
+		};
+	}
 	newOverGridImage() {
 		const unitId = this._fWorkbook.getId();
 		const subUnitId = this.getSheetId();
@@ -984,7 +1241,7 @@ var FWorksheetDrawingMixin = class extends FWorksheet {
 		if (uniqueDrawingIds.length < 2) return null;
 		const unitId = this._fWorkbook.getId();
 		const subUnitId = this.getSheetId();
-		const sheetDrawingService = this._injector.get(ISheetDrawingService);
+		const sheetDrawingService = this._sheetDrawingService;
 		if (sheetDrawingService.getDrawingByParam({
 			unitId,
 			subUnitId,
@@ -1024,7 +1281,7 @@ var FWorksheetDrawingMixin = class extends FWorksheet {
 	ungroupDrawings(groupIds) {
 		const unitId = this._fWorkbook.getId();
 		const subUnitId = this.getSheetId();
-		const sheetDrawingService = this._injector.get(ISheetDrawingService);
+		const sheetDrawingService = this._sheetDrawingService;
 		const groupParams = [];
 		for (const groupId of groupIds) {
 			const groupDrawing = sheetDrawingService.getDrawingByParam({
@@ -1062,7 +1319,7 @@ var FWorksheetDrawingMixin = class extends FWorksheet {
 	getDrawingGroupChildren(groupId, recursive = false) {
 		const unitId = this._fWorkbook.getId();
 		const subUnitId = this.getSheetId();
-		const sheetDrawingService = this._injector.get(ISheetDrawingService);
+		const sheetDrawingService = this._sheetDrawingService;
 		if (!recursive) return sheetDrawingService.getDrawingsByGroup({
 			unitId,
 			subUnitId,
@@ -1079,7 +1336,7 @@ var FWorksheetDrawingMixin = class extends FWorksheet {
 	getDrawingParentGroup(drawingId) {
 		const unitId = this._fWorkbook.getId();
 		const subUnitId = this.getSheetId();
-		const sheetDrawingService = this._injector.get(ISheetDrawingService);
+		const sheetDrawingService = this._sheetDrawingService;
 		const drawing = sheetDrawingService.getDrawingByParam({
 			unitId,
 			subUnitId,
@@ -1099,9 +1356,9 @@ var FWorksheetDrawingMixin = class extends FWorksheet {
 	}
 	_applyGroupDrawingOperation(groupParams, type) {
 		if (groupParams.length === 0) return false;
-		const sheetDrawingService = this._injector.get(ISheetDrawingService);
+		const sheetDrawingService = this._sheetDrawingService;
 		const commandService = this._commandService;
-		const undoRedoService = this._injector.get(IUndoRedoService);
+		const undoRedoService = this._undoRedoService;
 		const { unitId, subUnitId, undo, redo, objects } = type === DrawingApplyType.GROUP ? sheetDrawingService.getGroupDrawingOp(groupParams) : sheetDrawingService.getUngroupDrawingOp(groupParams);
 		if (commandService.syncExecuteCommand(SetDrawingApplyMutation.id, {
 			op: redo,
@@ -1175,6 +1432,16 @@ var FWorksheetDrawingMixin = class extends FWorksheet {
 		});
 	}
 };
+function getDrawingBounds(drawing) {
+	const { left, top, width, height } = drawing.transform ?? {};
+	if (typeof left !== "number" || typeof top !== "number" || typeof width !== "number" || typeof height !== "number" || !Number.isFinite(left) || !Number.isFinite(top) || !Number.isFinite(width) || !Number.isFinite(height)) return null;
+	return {
+		left,
+		top,
+		width,
+		height
+	};
+}
 FWorksheet.extend(FWorksheetDrawingMixin);
 
 //#endregion