fabricjs-document-engine 1.0.2 → 1.1.0

package/dist/commands/clipboard.d.cts

@@ -0,0 +1,47 @@
+import { SerializedFabricObject } from "../document/document-format.cjs";
+import { ContentLimits } from "../security/content-limits.cjs";
+import { DocumentEngine } from "../engine/create-document-engine.cjs";
+import { FabricObject } from "fabric";
+//#region src/commands/clipboard.d.ts
+export declare const CLIPBOARD_FORMAT = "fabricjs-document-engine/objects";
+/** What the clipboard holds. Plain JSON, so an app can put it on the system clipboard. */
+export interface ClipboardContent {
+  format: typeof CLIPBOARD_FORMAT;
+  version: 1;
+  objects: SerializedFabricObject[];
+}
+export interface ClipboardOptions {
+  /** How far each paste moves from the last one, in canvas units. Default 10. */
+  offset?: number;
+  /** Limits for content passed to `write`, as for loading documents. */
+  limits?: ContentLimits;
+}
+export interface PasteOptions {
+  /** The engine to paste into. Defaults to the engine the clipboard was made for. */
+  target?: DocumentEngine;
+  /** Overrides the offset for this paste. */
+  offset?: number;
+  /** Selects the pasted objects on an interactive canvas. Default true. */
+  select?: boolean;
+}
+export interface Clipboard {
+  /** Copies objects, or the current selection. Returns how many objects were copied. */
+  copy(objects?: readonly FabricObject[]): number;
+  /** Copies and then removes objects, as one undo step. Returns how many objects were cut. */
+  cut(objects?: readonly FabricObject[]): number;
+  /** Adds a copy of the clipboard with fresh ids, as one undo step. Returns the new objects. */
+  paste(options?: PasteOptions): Promise<FabricObject[]>;
+  hasContent(): boolean;
+  /** The copied objects as JSON, or `undefined` when the clipboard is empty. */
+  read(): ClipboardContent | undefined;
+  /** Replaces the clipboard with content from `read`, for example from another tab. */
+  write(content: unknown): void;
+  clear(): void;
+}
+/**
+ * A clipboard for one engine. Copies keep custom properties and the exact
+ * position of objects in groups and selections; pastes get fresh ids for
+ * every object and child and count as one undo step.
+ */
+export declare function createClipboard(engine: DocumentEngine, options?: ClipboardOptions): Clipboard;
+//#endregion

package/dist/commands/clipboard.d.ts

@@ -0,0 +1,47 @@
+import { SerializedFabricObject } from "../document/document-format.js";
+import { ContentLimits } from "../security/content-limits.js";
+import { DocumentEngine } from "../engine/create-document-engine.js";
+import { FabricObject } from "fabric";
+//#region src/commands/clipboard.d.ts
+export declare const CLIPBOARD_FORMAT = "fabricjs-document-engine/objects";
+/** What the clipboard holds. Plain JSON, so an app can put it on the system clipboard. */
+export interface ClipboardContent {
+  format: typeof CLIPBOARD_FORMAT;
+  version: 1;
+  objects: SerializedFabricObject[];
+}
+export interface ClipboardOptions {
+  /** How far each paste moves from the last one, in canvas units. Default 10. */
+  offset?: number;
+  /** Limits for content passed to `write`, as for loading documents. */
+  limits?: ContentLimits;
+}
+export interface PasteOptions {
+  /** The engine to paste into. Defaults to the engine the clipboard was made for. */
+  target?: DocumentEngine;
+  /** Overrides the offset for this paste. */
+  offset?: number;
+  /** Selects the pasted objects on an interactive canvas. Default true. */
+  select?: boolean;
+}
+export interface Clipboard {
+  /** Copies objects, or the current selection. Returns how many objects were copied. */
+  copy(objects?: readonly FabricObject[]): number;
+  /** Copies and then removes objects, as one undo step. Returns how many objects were cut. */
+  cut(objects?: readonly FabricObject[]): number;
+  /** Adds a copy of the clipboard with fresh ids, as one undo step. Returns the new objects. */
+  paste(options?: PasteOptions): Promise<FabricObject[]>;
+  hasContent(): boolean;
+  /** The copied objects as JSON, or `undefined` when the clipboard is empty. */
+  read(): ClipboardContent | undefined;
+  /** Replaces the clipboard with content from `read`, for example from another tab. */
+  write(content: unknown): void;
+  clear(): void;
+}
+/**
+ * A clipboard for one engine. Copies keep custom properties and the exact
+ * position of objects in groups and selections; pastes get fresh ids for
+ * every object and child and count as one undo step.
+ */
+export declare function createClipboard(engine: DocumentEngine, options?: ClipboardOptions): Clipboard;
+//#endregion

package/dist/commands/clipboard.js

@@ -0,0 +1,135 @@
+import { DocumentEngineError } from "../engine/errors.js";
+import { refuseUnsafeImageUrls, secureDocument } from "../security/content-limits.js";
+import { readObjectId } from "../fabric/object-ids.js";
+import { collectSerializedTypes } from "../fabric/walk-objects.js";
+import { createObjects } from "../fabric/fabric-adapter.js";
+import { ActiveSelection, classRegistry } from "fabric";
+//#region src/commands/clipboard.ts
+const CLIPBOARD_FORMAT = "fabricjs-document-engine/objects";
+function clone(value) {
+	return JSON.parse(JSON.stringify(value));
+}
+/** Removes every id, so the engine gives each pasted object, child and clip path a new one. */
+function withoutIds(object) {
+	const copy = { ...object };
+	delete copy.id;
+	if (Array.isArray(copy.objects)) copy.objects = copy.objects.map(withoutIds);
+	if (copy.clipPath && typeof copy.clipPath === "object") copy.clipPath = withoutIds(copy.clipPath);
+	return copy;
+}
+function moved(object, distance) {
+	const left = typeof object.left === "number" ? object.left : 0;
+	const top = typeof object.top === "number" ? object.top : 0;
+	return {
+		...object,
+		left: left + distance,
+		top: top + distance
+	};
+}
+function refuseInvalidContent(message) {
+	throw new DocumentEngineError("INVALID_DOCUMENT", `The clipboard content is not valid: ${message}`);
+}
+function checkContent(content, limits) {
+	if (typeof content !== "object" || content === null) refuseInvalidContent("it is not an object");
+	const candidate = content;
+	if (candidate.format !== "fabricjs-document-engine/objects") refuseInvalidContent(`its format is not "${CLIPBOARD_FORMAT}"`);
+	if (candidate.version !== 1) refuseInvalidContent("its version is not 1");
+	if (!Array.isArray(candidate.objects)) refuseInvalidContent("it has no objects list");
+	const secured = secureDocument({ objects: candidate.objects }, limits);
+	const objects = secured.objects.filter((object) => typeof object === "object" && object !== null && typeof object.type === "string");
+	if (objects.length !== secured.objects.length) refuseInvalidContent("every object needs a type");
+	refuseUnsafeImageUrls(objects, limits?.isAllowedUrl);
+	return {
+		format: CLIPBOARD_FORMAT,
+		version: 1,
+		objects
+	};
+}
+function topLevelInOrder(engine, objects) {
+	const stack = engine.canvas.getObjects();
+	const wanted = new Set(objects);
+	return stack.filter((object) => wanted.has(object));
+}
+function selectionOf(engine) {
+	return engine.canvas.getActiveObjects?.() ?? [];
+}
+function refuseUnknownTypes(objects) {
+	const unknownTypes = [...collectSerializedTypes(objects)].filter((type) => !classRegistry.has(type));
+	if (unknownTypes.length === 0) return;
+	throw new DocumentEngineError("UNKNOWN_OBJECT_TYPE", `The clipboard holds object types that are not registered: ${unknownTypes.join(", ")}`, { unknownTypes });
+}
+function select(engine, objects) {
+	const canvas = engine.canvas;
+	if (typeof canvas.setActiveObject !== "function" || objects.length === 0) return;
+	canvas.discardActiveObject?.();
+	canvas.setActiveObject(objects.length === 1 ? objects[0] : new ActiveSelection(objects, { canvas: engine.canvas }));
+}
+/**
+* A clipboard for one engine. Copies keep custom properties and the exact
+* position of objects in groups and selections; pastes get fresh ids for
+* every object and child and count as one undo step.
+*/
+function createClipboard(engine, options = {}) {
+	const defaultOffset = options.offset ?? 10;
+	let content;
+	let pastes = 0;
+	function copyObjects(objects) {
+		const chosen = topLevelInOrder(engine, objects);
+		if (chosen.length === 0) return 0;
+		const document = engine.toDocument();
+		const serialized = chosen.map((object) => readObjectId(object)).map((id) => document.objects.find((object) => object.id === id)).filter((object) => object !== void 0);
+		content = {
+			format: CLIPBOARD_FORMAT,
+			version: 1,
+			objects: clone(serialized)
+		};
+		return serialized.length;
+	}
+	return {
+		copy(objects) {
+			const count = copyObjects(objects ?? selectionOf(engine));
+			if (count > 0) pastes = 0;
+			return count;
+		},
+		cut(objects) {
+			const chosen = topLevelInOrder(engine, objects ?? selectionOf(engine));
+			const count = copyObjects(chosen);
+			if (count === 0) return 0;
+			pastes = -1;
+			engine.transaction(count === 1 ? "Cut" : `Cut ${count} objects`, () => {
+				engine.canvas.discardActiveObject?.();
+				engine.canvas.remove(...chosen);
+			});
+			engine.canvas.requestRenderAll();
+			return count;
+		},
+		async paste(pasteOptions = {}) {
+			if (!content) return [];
+			const target = pasteOptions.target ?? engine;
+			const offset = pasteOptions.offset ?? defaultOffset;
+			pastes += 1;
+			const distance = offset * pastes;
+			const serialized = content.objects.map((object) => moved(withoutIds(object), distance));
+			refuseUnknownTypes(serialized);
+			const created = await createObjects(clone(serialized));
+			target.transaction(created.length === 1 ? "Paste" : `Paste ${created.length} objects`, () => {
+				target.canvas.add(...created);
+			});
+			if (pasteOptions.select ?? true) select(target, created);
+			target.canvas.requestRenderAll();
+			return created;
+		},
+		hasContent: () => content !== void 0,
+		read: () => content ? clone(content) : void 0,
+		write(next) {
+			content = checkContent(next, options.limits);
+			pastes = 0;
+		},
+		clear() {
+			content = void 0;
+			pastes = 0;
+		}
+	};
+}
+//#endregion
+export { CLIPBOARD_FORMAT, createClipboard };

package/dist/commands/layers.cjs

@@ -0,0 +1,97 @@
+const require_object_ids = require("../fabric/object-ids.cjs");
+//#region src/commands/layers.ts
+function chosenObjects(engine, objects) {
+	const list = objects ?? engine.canvas.getActiveObjects?.() ?? [];
+	const stack = new Set(engine.canvas.getObjects());
+	return new Set(list.filter((object) => stack.has(object)));
+}
+/**
+* Works out the new order on the objects that may move, then puts every
+* pinned object back at the index it had.
+*/
+function reorder(engine, label, objects, options, arrange) {
+	const stack = engine.canvas.getObjects();
+	const isPinned = options.pinned ?? (() => false);
+	const chosen = chosenObjects(engine, objects);
+	for (const object of chosen) if (isPinned(object)) chosen.delete(object);
+	if (chosen.size === 0) return false;
+	const pinnedAt = /* @__PURE__ */ new Map();
+	const free = [];
+	stack.forEach((object, index) => {
+		if (isPinned(object)) pinnedAt.set(index, object);
+		else free.push(object);
+	});
+	const arranged = arrange(free, chosen);
+	const next = [];
+	let freeIndex = 0;
+	for (let index = 0; index < stack.length; index += 1) next.push(pinnedAt.get(index) ?? arranged[freeIndex++]);
+	if (next.every((object, index) => object === stack[index])) return false;
+	engine.transaction(chosen.size === 1 ? label : `${label} (${chosen.size} objects)`, () => {
+		next.forEach((object, index) => {
+			if (engine.canvas.getObjects()[index] !== object) engine.canvas.moveObjectTo(object, index);
+		});
+	});
+	engine.canvas.requestRenderAll();
+	return true;
+}
+/** Moves objects, or the selection, to the top of the stack. Returns false when nothing moved. */
+function bringToFront(engine, objects, options = {}) {
+	return reorder(engine, "Bring to front", objects, options, (free, chosen) => [...free.filter((object) => !chosen.has(object)), ...free.filter((object) => chosen.has(object))]);
+}
+/** Moves objects, or the selection, to the bottom of the stack. Returns false when nothing moved. */
+function sendToBack(engine, objects, options = {}) {
+	return reorder(engine, "Send to back", objects, options, (free, chosen) => [...free.filter((object) => chosen.has(object)), ...free.filter((object) => !chosen.has(object))]);
+}
+/** Moves objects, or the selection, one step up. Selected objects next to each other move as a block. */
+function bringForward(engine, objects, options = {}) {
+	return reorder(engine, "Bring forward", objects, options, (free, chosen) => {
+		const next = [...free];
+		for (let index = next.length - 2; index >= 0; index -= 1) if (chosen.has(next[index]) && !chosen.has(next[index + 1])) [next[index], next[index + 1]] = [next[index + 1], next[index]];
+		return next;
+	});
+}
+/** Moves objects, or the selection, one step down. Selected objects next to each other move as a block. */
+function sendBackward(engine, objects, options = {}) {
+	return reorder(engine, "Send backward", objects, options, (free, chosen) => {
+		const next = [...free];
+		for (let index = 1; index < next.length; index += 1) if (chosen.has(next[index]) && !chosen.has(next[index - 1])) [next[index], next[index - 1]] = [next[index - 1], next[index]];
+		return next;
+	});
+}
+/**
+* Moves objects to `index`, counted from the bottom among objects that are not
+* pinned. Several objects keep their order and land as a block.
+*/
+function moveToIndex(engine, objects, index, options = {}) {
+	return reorder(engine, "Move layer", objects, options, (free, chosen) => {
+		const rest = free.filter((object) => !chosen.has(object));
+		const block = free.filter((object) => chosen.has(object));
+		const at = Math.max(0, Math.min(Math.floor(index), rest.length));
+		return [
+			...rest.slice(0, at),
+			...block,
+			...rest.slice(at)
+		];
+	});
+}
+/** The top-level objects from top to bottom, for a layers panel. */
+function getLayers(engine) {
+	return engine.canvas.getObjects().map((object, index) => {
+		const name = object.name;
+		return {
+			id: require_object_ids.readObjectId(object),
+			type: object.type,
+			name: typeof name === "string" ? name : void 0,
+			index,
+			visible: object.visible !== false,
+			locked: object.selectable === false
+		};
+	}).reverse();
+}
+//#endregion
+exports.bringForward = bringForward;
+exports.bringToFront = bringToFront;
+exports.getLayers = getLayers;
+exports.moveToIndex = moveToIndex;
+exports.sendBackward = sendBackward;
+exports.sendToBack = sendToBack;

package/dist/commands/layers.d.cts

@@ -0,0 +1,39 @@
+import { DocumentEngine } from "../engine/create-document-engine.cjs";
+import { FabricObject } from "fabric";
+//#region src/commands/layers.d.ts
+/**
+ * Keeps an object where it is in the stack. Use it for a background that must
+ * stay at the bottom or a frame that must stay on top.
+ */
+export type LayerPin = (object: FabricObject) => boolean;
+export interface LayerOptions {
+  /** Objects this returns true for never move, and keep their place in the stack. */
+  pinned?: LayerPin;
+}
+export interface LayerInfo {
+  id: string | undefined;
+  type: string;
+  /** The object's `name` property, when it has one. */
+  name: string | undefined;
+  /** Position from the bottom of the stack, as Fabric counts it. */
+  index: number;
+  visible: boolean;
+  /** True when the object cannot be selected. */
+  locked: boolean;
+}
+/** Moves objects, or the selection, to the top of the stack. Returns false when nothing moved. */
+export declare function bringToFront(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): boolean;
+/** Moves objects, or the selection, to the bottom of the stack. Returns false when nothing moved. */
+export declare function sendToBack(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): boolean;
+/** Moves objects, or the selection, one step up. Selected objects next to each other move as a block. */
+export declare function bringForward(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): boolean;
+/** Moves objects, or the selection, one step down. Selected objects next to each other move as a block. */
+export declare function sendBackward(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): boolean;
+/**
+ * Moves objects to `index`, counted from the bottom among objects that are not
+ * pinned. Several objects keep their order and land as a block.
+ */
+export declare function moveToIndex(engine: DocumentEngine, objects: readonly FabricObject[], index: number, options?: LayerOptions): boolean;
+/** The top-level objects from top to bottom, for a layers panel. */
+export declare function getLayers(engine: DocumentEngine): LayerInfo[];
+//#endregion

package/dist/commands/layers.d.ts

@@ -0,0 +1,39 @@
+import { DocumentEngine } from "../engine/create-document-engine.js";
+import { FabricObject } from "fabric";
+//#region src/commands/layers.d.ts
+/**
+ * Keeps an object where it is in the stack. Use it for a background that must
+ * stay at the bottom or a frame that must stay on top.
+ */
+export type LayerPin = (object: FabricObject) => boolean;
+export interface LayerOptions {
+  /** Objects this returns true for never move, and keep their place in the stack. */
+  pinned?: LayerPin;
+}
+export interface LayerInfo {
+  id: string | undefined;
+  type: string;
+  /** The object's `name` property, when it has one. */
+  name: string | undefined;
+  /** Position from the bottom of the stack, as Fabric counts it. */
+  index: number;
+  visible: boolean;
+  /** True when the object cannot be selected. */
+  locked: boolean;
+}
+/** Moves objects, or the selection, to the top of the stack. Returns false when nothing moved. */
+export declare function bringToFront(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): boolean;
+/** Moves objects, or the selection, to the bottom of the stack. Returns false when nothing moved. */
+export declare function sendToBack(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): boolean;
+/** Moves objects, or the selection, one step up. Selected objects next to each other move as a block. */
+export declare function bringForward(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): boolean;
+/** Moves objects, or the selection, one step down. Selected objects next to each other move as a block. */
+export declare function sendBackward(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): boolean;
+/**
+ * Moves objects to `index`, counted from the bottom among objects that are not
+ * pinned. Several objects keep their order and land as a block.
+ */
+export declare function moveToIndex(engine: DocumentEngine, objects: readonly FabricObject[], index: number, options?: LayerOptions): boolean;
+/** The top-level objects from top to bottom, for a layers panel. */
+export declare function getLayers(engine: DocumentEngine): LayerInfo[];
+//#endregion

package/dist/commands/layers.js

@@ -0,0 +1,92 @@
+import { readObjectId } from "../fabric/object-ids.js";
+//#region src/commands/layers.ts
+function chosenObjects(engine, objects) {
+	const list = objects ?? engine.canvas.getActiveObjects?.() ?? [];
+	const stack = new Set(engine.canvas.getObjects());
+	return new Set(list.filter((object) => stack.has(object)));
+}
+/**
+* Works out the new order on the objects that may move, then puts every
+* pinned object back at the index it had.
+*/
+function reorder(engine, label, objects, options, arrange) {
+	const stack = engine.canvas.getObjects();
+	const isPinned = options.pinned ?? (() => false);
+	const chosen = chosenObjects(engine, objects);
+	for (const object of chosen) if (isPinned(object)) chosen.delete(object);
+	if (chosen.size === 0) return false;
+	const pinnedAt = /* @__PURE__ */ new Map();
+	const free = [];
+	stack.forEach((object, index) => {
+		if (isPinned(object)) pinnedAt.set(index, object);
+		else free.push(object);
+	});
+	const arranged = arrange(free, chosen);
+	const next = [];
+	let freeIndex = 0;
+	for (let index = 0; index < stack.length; index += 1) next.push(pinnedAt.get(index) ?? arranged[freeIndex++]);
+	if (next.every((object, index) => object === stack[index])) return false;
+	engine.transaction(chosen.size === 1 ? label : `${label} (${chosen.size} objects)`, () => {
+		next.forEach((object, index) => {
+			if (engine.canvas.getObjects()[index] !== object) engine.canvas.moveObjectTo(object, index);
+		});
+	});
+	engine.canvas.requestRenderAll();
+	return true;
+}
+/** Moves objects, or the selection, to the top of the stack. Returns false when nothing moved. */
+function bringToFront(engine, objects, options = {}) {
+	return reorder(engine, "Bring to front", objects, options, (free, chosen) => [...free.filter((object) => !chosen.has(object)), ...free.filter((object) => chosen.has(object))]);
+}
+/** Moves objects, or the selection, to the bottom of the stack. Returns false when nothing moved. */
+function sendToBack(engine, objects, options = {}) {
+	return reorder(engine, "Send to back", objects, options, (free, chosen) => [...free.filter((object) => chosen.has(object)), ...free.filter((object) => !chosen.has(object))]);
+}
+/** Moves objects, or the selection, one step up. Selected objects next to each other move as a block. */
+function bringForward(engine, objects, options = {}) {
+	return reorder(engine, "Bring forward", objects, options, (free, chosen) => {
+		const next = [...free];
+		for (let index = next.length - 2; index >= 0; index -= 1) if (chosen.has(next[index]) && !chosen.has(next[index + 1])) [next[index], next[index + 1]] = [next[index + 1], next[index]];
+		return next;
+	});
+}
+/** Moves objects, or the selection, one step down. Selected objects next to each other move as a block. */
+function sendBackward(engine, objects, options = {}) {
+	return reorder(engine, "Send backward", objects, options, (free, chosen) => {
+		const next = [...free];
+		for (let index = 1; index < next.length; index += 1) if (chosen.has(next[index]) && !chosen.has(next[index - 1])) [next[index], next[index - 1]] = [next[index - 1], next[index]];
+		return next;
+	});
+}
+/**
+* Moves objects to `index`, counted from the bottom among objects that are not
+* pinned. Several objects keep their order and land as a block.
+*/
+function moveToIndex(engine, objects, index, options = {}) {
+	return reorder(engine, "Move layer", objects, options, (free, chosen) => {
+		const rest = free.filter((object) => !chosen.has(object));
+		const block = free.filter((object) => chosen.has(object));
+		const at = Math.max(0, Math.min(Math.floor(index), rest.length));
+		return [
+			...rest.slice(0, at),
+			...block,
+			...rest.slice(at)
+		];
+	});
+}
+/** The top-level objects from top to bottom, for a layers panel. */
+function getLayers(engine) {
+	return engine.canvas.getObjects().map((object, index) => {
+		const name = object.name;
+		return {
+			id: readObjectId(object),
+			type: object.type,
+			name: typeof name === "string" ? name : void 0,
+			index,
+			visible: object.visible !== false,
+			locked: object.selectable === false
+		};
+	}).reverse();
+}
+//#endregion
+export { bringForward, bringToFront, getLayers, moveToIndex, sendBackward, sendToBack };