fabricjs-document-engine 1.0.2 → 1.2.0

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 };

package/dist/document/document-format.d.cts

@@ -11,7 +11,16 @@ export interface SerializedFabricObject {
 export interface DocumentCanvas {
   width: number;
   height: number;
+  /** A color, gradient or pattern behind everything. */
   background?: unknown;
+  /** A Fabric image drawn behind every object. */
+  backgroundImage?: SerializedFabricObject;
+  /** A color, gradient or pattern drawn over every object. */
+  overlay?: unknown;
+  /** A Fabric image drawn over every object. */
+  overlayImage?: SerializedFabricObject;
+  /** A Fabric object that clips the whole canvas. */
+  clipPath?: SerializedFabricObject;
 }
 export interface FabricDocument {
   schemaVersion: number;
@@ -30,5 +39,11 @@ export interface DocumentInfo {
   createdAt: string;
   updatedAt: string;
   metadata: Record<string, unknown>;
+  /**
+   * Goes up each time the canvas shows a different document: a load, a new
+   * document or a restore. Async work started under one session must not
+   * change the canvas in another. Set by `getDocumentInfo()`.
+   */
+  session?: number;
 }
 //#endregion

package/dist/document/document-format.d.ts

@@ -11,7 +11,16 @@ export interface SerializedFabricObject {
 export interface DocumentCanvas {
   width: number;
   height: number;
+  /** A color, gradient or pattern behind everything. */
   background?: unknown;
+  /** A Fabric image drawn behind every object. */
+  backgroundImage?: SerializedFabricObject;
+  /** A color, gradient or pattern drawn over every object. */
+  overlay?: unknown;
+  /** A Fabric image drawn over every object. */
+  overlayImage?: SerializedFabricObject;
+  /** A Fabric object that clips the whole canvas. */
+  clipPath?: SerializedFabricObject;
 }
 export interface FabricDocument {
   schemaVersion: number;
@@ -30,5 +39,11 @@ export interface DocumentInfo {
   createdAt: string;
   updatedAt: string;
   metadata: Record<string, unknown>;
+  /**
+   * Goes up each time the canvas shows a different document: a load, a new
+   * document or a restore. Async work started under one session must not
+   * change the canvas in another. Set by `getDocumentInfo()`.
+   */
+  session?: number;
 }
 //#endregion

package/dist/document/validate-document.cjs

@@ -67,6 +67,14 @@ function validateDocument(value) {
 	else {
 		if (!isPositiveNumber(value.canvas.width)) issues.push(invalid("canvas.width", "must be a positive number"));
 		if (!isPositiveNumber(value.canvas.height)) issues.push(invalid("canvas.height", "must be a positive number"));
+		for (const field of [
+			"backgroundImage",
+			"overlayImage",
+			"clipPath"
+		]) {
+			const pageObject = value.canvas[field];
+			if (pageObject !== void 0 && pageObject !== null) validateObjectList([pageObject], `canvas.${field}`, issues);
+		}
 	}
 	validateObjectList(value.objects, "objects", issues);
 	return issues;

package/dist/document/validate-document.js

@@ -67,6 +67,14 @@ function validateDocument(value) {
 	else {
 		if (!isPositiveNumber(value.canvas.width)) issues.push(invalid("canvas.width", "must be a positive number"));
 		if (!isPositiveNumber(value.canvas.height)) issues.push(invalid("canvas.height", "must be a positive number"));
+		for (const field of [
+			"backgroundImage",
+			"overlayImage",
+			"clipPath"
+		]) {
+			const pageObject = value.canvas[field];
+			if (pageObject !== void 0 && pageObject !== null) validateObjectList([pageObject], `canvas.${field}`, issues);
+		}
 	}
 	validateObjectList(value.objects, "objects", issues);
 	return issues;