fabricjs-document-engine 1.1.0 → 1.3.0

package/dist/commands/text-edit.cjs

@@ -0,0 +1,223 @@
+//#region src/commands/text-edit.ts
+function sameStyle(a, b) {
+	if (a === b) return true;
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return false;
+	return keys.every((key) => a[key] === b[key]);
+}
+function hasStyle(style) {
+	return style !== void 0 && style !== null && Object.keys(style).length > 0;
+}
+function readStyleRuns(graphemes, styles) {
+	const runs = [];
+	let line = 0;
+	let char = 0;
+	for (let index = 0; index < graphemes.length; index += 1) {
+		if (graphemes[index] === "\n") {
+			line += 1;
+			char = 0;
+			continue;
+		}
+		const style = styles?.[line]?.[char];
+		char += 1;
+		if (!hasStyle(style)) continue;
+		const last = runs[runs.length - 1];
+		if (last && last.end === index && sameStyle(last.style, style)) last.end = index + 1;
+		else runs.push({
+			start: index,
+			end: index + 1,
+			style
+		});
+	}
+	return runs;
+}
+function writeStyleRuns(graphemes, runs) {
+	const styles = {};
+	let line = 0;
+	let char = 0;
+	let next = 0;
+	for (let index = 0; index < graphemes.length; index += 1) {
+		var _line;
+		if (graphemes[index] === "\n") {
+			line += 1;
+			char = 0;
+			continue;
+		}
+		while (next < runs.length && runs[next].end <= index) next += 1;
+		const run = runs[next];
+		if (run && run.start <= index) (styles[_line = line] ?? (styles[_line] = {}))[char] = { ...run.style };
+		char += 1;
+	}
+	return styles;
+}
+function shiftStyleRuns(runs, start, end, insertedLength, style) {
+	const delta = insertedLength - (end - start);
+	const shifted = [];
+	let inherited;
+	for (const run of runs) if (run.end <= start) {
+		const copy = { ...run };
+		if (copy.end === start) inherited = copy;
+		shifted.push(copy);
+	} else if (run.start >= end) shifted.push({
+		start: run.start + delta,
+		end: run.end + delta,
+		style: run.style
+	});
+	else {
+		if (run.start < start) {
+			inherited = {
+				start: run.start,
+				end: start,
+				style: run.style
+			};
+			shifted.push(inherited);
+		}
+		if (run.end > end) shifted.push({
+			start: end + delta,
+			end: run.end + delta,
+			style: run.style
+		});
+	}
+	if (insertedLength === 0) return shifted;
+	if (style === void 0) {
+		if (inherited) inherited.end += insertedLength;
+		return shifted;
+	}
+	if (!hasStyle(style)) return shifted;
+	const inserted = {
+		start,
+		end: start + insertedLength,
+		style
+	};
+	const at = shifted.findIndex((run) => run.start >= start);
+	if (at === -1) shifted.push(inserted);
+	else shifted.splice(at, 0, inserted);
+	return shifted;
+}
+function clamp(value, low, high) {
+	return Math.min(Math.max(value, low), high);
+}
+function moveIndex(index, start, end, insertedLength) {
+	if (index <= start) return index;
+	if (index >= end) return index + insertedLength - (end - start);
+	return start + insertedLength;
+}
+function replaceTextRange(target, start, end, insert, style) {
+	const text = target;
+	const graphemes = text._text ?? text.graphemeSplit(text.text);
+	const from = clamp(Math.floor(start), 0, graphemes.length);
+	const to = clamp(Math.floor(end), from, graphemes.length);
+	const inserted = insert ? text.graphemeSplit(insert) : [];
+	const runs = shiftStyleRuns(readStyleRuns(graphemes, text.styles), from, to, inserted.length, style);
+	const next = [
+		...graphemes.slice(0, from),
+		...inserted,
+		...graphemes.slice(to)
+	];
+	const selectionStart = moveIndex(text.selectionStart ?? 0, from, to, inserted.length);
+	const selectionEnd = moveIndex(text.selectionEnd ?? 0, from, to, inserted.length);
+	applyTextAndStyles(text, next, runs);
+	text.selectionStart = selectionStart;
+	text.selectionEnd = Math.max(selectionStart, selectionEnd);
+	announceTextChange(text);
+}
+function setTextRangeStyle(target, start, end, style) {
+	const text = target;
+	const graphemes = text._text ?? text.graphemeSplit(text.text);
+	const from = clamp(Math.floor(start), 0, graphemes.length);
+	const to = clamp(Math.floor(end), from, graphemes.length);
+	if (from === to) return;
+	const runs = readStyleRuns(graphemes, text.styles);
+	const result = [];
+	let cursor = from;
+	for (const run of runs) {
+		if (run.end <= from || run.start >= to) {
+			if (run.start >= to && cursor < to) {
+				result.push({
+					start: cursor,
+					end: to,
+					style: { ...style }
+				});
+				cursor = to;
+			}
+			result.push(run);
+			continue;
+		}
+		if (run.start < from) result.push({
+			start: run.start,
+			end: from,
+			style: run.style
+		});
+		const overlapStart = Math.max(run.start, from);
+		if (cursor < overlapStart) result.push({
+			start: cursor,
+			end: overlapStart,
+			style: { ...style }
+		});
+		const overlapEnd = Math.min(run.end, to);
+		result.push({
+			start: overlapStart,
+			end: overlapEnd,
+			style: {
+				...run.style,
+				...style
+			}
+		});
+		cursor = overlapEnd;
+		if (run.end > to) result.push({
+			start: to,
+			end: run.end,
+			style: run.style
+		});
+	}
+	if (cursor < to) result.push({
+		start: cursor,
+		end: to,
+		style: { ...style }
+	});
+	applyTextAndStyles(text, graphemes, result);
+	announceTextChange(text);
+}
+function applyTextAndStyles(text, graphemes, runs) {
+	const value = graphemes.join("");
+	text.styles = writeStyleRuns(graphemes, runs);
+	if (text.text !== value) text.set("text", value);
+	else text.initDimensions();
+	text.set("dirty", true);
+	text.setCoords();
+}
+function announceTextChange(text) {
+	if (text.isEditing && text.hiddenTextarea && !text.inCompositionMode) {
+		text.hiddenTextarea.value = text.text;
+		text._updateTextarea?.();
+	}
+	text.fire("changed");
+	text.canvas?.fire("text:changed", { target: text });
+	text.canvas?.requestRenderAll();
+}
+function createTextCommands(engine) {
+	return {
+		insertText(target, index, text, style) {
+			if (!text) return;
+			engine.transaction("Insert text", () => replaceTextRange(target, index, index, text, style));
+		},
+		deleteText(target, start, end) {
+			if (end <= start) return;
+			engine.transaction("Delete text", () => replaceTextRange(target, start, end, ""));
+		},
+		replaceText(target, start, end, text, style) {
+			engine.transaction("Replace text", () => replaceTextRange(target, start, end, text, style));
+		},
+		setTextStyle(target, start, end, style) {
+			if (end <= start) return;
+			engine.transaction("Style text", () => setTextRangeStyle(target, start, end, style));
+		}
+	};
+}
+//#endregion
+exports.createTextCommands = createTextCommands;
+exports.readStyleRuns = readStyleRuns;
+exports.replaceTextRange = replaceTextRange;
+exports.setTextRangeStyle = setTextRangeStyle;
+exports.shiftStyleRuns = shiftStyleRuns;
+exports.writeStyleRuns = writeStyleRuns;

package/dist/commands/text-edit.d.cts

@@ -0,0 +1,23 @@
+import { DocumentEngine } from "../engine/create-document-engine.cjs";
+import { IText, TextStyleDeclaration, Textbox } from "fabric";
+//#region src/commands/text-edit.d.ts
+export type EditableTextObject = IText | Textbox;
+export interface StyleRun {
+  start: number;
+  end: number;
+  style: TextStyleDeclaration;
+}
+export type InsertedStyle = TextStyleDeclaration | null | undefined;
+export declare function readStyleRuns(graphemes: readonly string[], styles: IText["styles"]): StyleRun[];
+export declare function writeStyleRuns(graphemes: readonly string[], runs: readonly StyleRun[]): IText["styles"];
+export declare function shiftStyleRuns(runs: readonly StyleRun[], start: number, end: number, insertedLength: number, style?: InsertedStyle): StyleRun[];
+export declare function replaceTextRange(target: EditableTextObject, start: number, end: number, insert: string, style?: InsertedStyle): void;
+export declare function setTextRangeStyle(target: EditableTextObject, start: number, end: number, style: TextStyleDeclaration): void;
+export interface TextCommands {
+  insertText(target: EditableTextObject, index: number, text: string, style?: InsertedStyle): void;
+  deleteText(target: EditableTextObject, start: number, end: number): void;
+  replaceText(target: EditableTextObject, start: number, end: number, text: string, style?: InsertedStyle): void;
+  setTextStyle(target: EditableTextObject, start: number, end: number, style: TextStyleDeclaration): void;
+}
+export declare function createTextCommands(engine: DocumentEngine): TextCommands;
+//#endregion

package/dist/commands/text-edit.d.ts

@@ -0,0 +1,23 @@
+import { DocumentEngine } from "../engine/create-document-engine.js";
+import { IText, TextStyleDeclaration, Textbox } from "fabric";
+//#region src/commands/text-edit.d.ts
+export type EditableTextObject = IText | Textbox;
+export interface StyleRun {
+  start: number;
+  end: number;
+  style: TextStyleDeclaration;
+}
+export type InsertedStyle = TextStyleDeclaration | null | undefined;
+export declare function readStyleRuns(graphemes: readonly string[], styles: IText["styles"]): StyleRun[];
+export declare function writeStyleRuns(graphemes: readonly string[], runs: readonly StyleRun[]): IText["styles"];
+export declare function shiftStyleRuns(runs: readonly StyleRun[], start: number, end: number, insertedLength: number, style?: InsertedStyle): StyleRun[];
+export declare function replaceTextRange(target: EditableTextObject, start: number, end: number, insert: string, style?: InsertedStyle): void;
+export declare function setTextRangeStyle(target: EditableTextObject, start: number, end: number, style: TextStyleDeclaration): void;
+export interface TextCommands {
+  insertText(target: EditableTextObject, index: number, text: string, style?: InsertedStyle): void;
+  deleteText(target: EditableTextObject, start: number, end: number): void;
+  replaceText(target: EditableTextObject, start: number, end: number, text: string, style?: InsertedStyle): void;
+  setTextStyle(target: EditableTextObject, start: number, end: number, style: TextStyleDeclaration): void;
+}
+export declare function createTextCommands(engine: DocumentEngine): TextCommands;
+//#endregion

package/dist/commands/text-edit.js

@@ -0,0 +1,218 @@
+//#region src/commands/text-edit.ts
+function sameStyle(a, b) {
+	if (a === b) return true;
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return false;
+	return keys.every((key) => a[key] === b[key]);
+}
+function hasStyle(style) {
+	return style !== void 0 && style !== null && Object.keys(style).length > 0;
+}
+function readStyleRuns(graphemes, styles) {
+	const runs = [];
+	let line = 0;
+	let char = 0;
+	for (let index = 0; index < graphemes.length; index += 1) {
+		if (graphemes[index] === "\n") {
+			line += 1;
+			char = 0;
+			continue;
+		}
+		const style = styles?.[line]?.[char];
+		char += 1;
+		if (!hasStyle(style)) continue;
+		const last = runs[runs.length - 1];
+		if (last && last.end === index && sameStyle(last.style, style)) last.end = index + 1;
+		else runs.push({
+			start: index,
+			end: index + 1,
+			style
+		});
+	}
+	return runs;
+}
+function writeStyleRuns(graphemes, runs) {
+	const styles = {};
+	let line = 0;
+	let char = 0;
+	let next = 0;
+	for (let index = 0; index < graphemes.length; index += 1) {
+		var _line;
+		if (graphemes[index] === "\n") {
+			line += 1;
+			char = 0;
+			continue;
+		}
+		while (next < runs.length && runs[next].end <= index) next += 1;
+		const run = runs[next];
+		if (run && run.start <= index) (styles[_line = line] ?? (styles[_line] = {}))[char] = { ...run.style };
+		char += 1;
+	}
+	return styles;
+}
+function shiftStyleRuns(runs, start, end, insertedLength, style) {
+	const delta = insertedLength - (end - start);
+	const shifted = [];
+	let inherited;
+	for (const run of runs) if (run.end <= start) {
+		const copy = { ...run };
+		if (copy.end === start) inherited = copy;
+		shifted.push(copy);
+	} else if (run.start >= end) shifted.push({
+		start: run.start + delta,
+		end: run.end + delta,
+		style: run.style
+	});
+	else {
+		if (run.start < start) {
+			inherited = {
+				start: run.start,
+				end: start,
+				style: run.style
+			};
+			shifted.push(inherited);
+		}
+		if (run.end > end) shifted.push({
+			start: end + delta,
+			end: run.end + delta,
+			style: run.style
+		});
+	}
+	if (insertedLength === 0) return shifted;
+	if (style === void 0) {
+		if (inherited) inherited.end += insertedLength;
+		return shifted;
+	}
+	if (!hasStyle(style)) return shifted;
+	const inserted = {
+		start,
+		end: start + insertedLength,
+		style
+	};
+	const at = shifted.findIndex((run) => run.start >= start);
+	if (at === -1) shifted.push(inserted);
+	else shifted.splice(at, 0, inserted);
+	return shifted;
+}
+function clamp(value, low, high) {
+	return Math.min(Math.max(value, low), high);
+}
+function moveIndex(index, start, end, insertedLength) {
+	if (index <= start) return index;
+	if (index >= end) return index + insertedLength - (end - start);
+	return start + insertedLength;
+}
+function replaceTextRange(target, start, end, insert, style) {
+	const text = target;
+	const graphemes = text._text ?? text.graphemeSplit(text.text);
+	const from = clamp(Math.floor(start), 0, graphemes.length);
+	const to = clamp(Math.floor(end), from, graphemes.length);
+	const inserted = insert ? text.graphemeSplit(insert) : [];
+	const runs = shiftStyleRuns(readStyleRuns(graphemes, text.styles), from, to, inserted.length, style);
+	const next = [
+		...graphemes.slice(0, from),
+		...inserted,
+		...graphemes.slice(to)
+	];
+	const selectionStart = moveIndex(text.selectionStart ?? 0, from, to, inserted.length);
+	const selectionEnd = moveIndex(text.selectionEnd ?? 0, from, to, inserted.length);
+	applyTextAndStyles(text, next, runs);
+	text.selectionStart = selectionStart;
+	text.selectionEnd = Math.max(selectionStart, selectionEnd);
+	announceTextChange(text);
+}
+function setTextRangeStyle(target, start, end, style) {
+	const text = target;
+	const graphemes = text._text ?? text.graphemeSplit(text.text);
+	const from = clamp(Math.floor(start), 0, graphemes.length);
+	const to = clamp(Math.floor(end), from, graphemes.length);
+	if (from === to) return;
+	const runs = readStyleRuns(graphemes, text.styles);
+	const result = [];
+	let cursor = from;
+	for (const run of runs) {
+		if (run.end <= from || run.start >= to) {
+			if (run.start >= to && cursor < to) {
+				result.push({
+					start: cursor,
+					end: to,
+					style: { ...style }
+				});
+				cursor = to;
+			}
+			result.push(run);
+			continue;
+		}
+		if (run.start < from) result.push({
+			start: run.start,
+			end: from,
+			style: run.style
+		});
+		const overlapStart = Math.max(run.start, from);
+		if (cursor < overlapStart) result.push({
+			start: cursor,
+			end: overlapStart,
+			style: { ...style }
+		});
+		const overlapEnd = Math.min(run.end, to);
+		result.push({
+			start: overlapStart,
+			end: overlapEnd,
+			style: {
+				...run.style,
+				...style
+			}
+		});
+		cursor = overlapEnd;
+		if (run.end > to) result.push({
+			start: to,
+			end: run.end,
+			style: run.style
+		});
+	}
+	if (cursor < to) result.push({
+		start: cursor,
+		end: to,
+		style: { ...style }
+	});
+	applyTextAndStyles(text, graphemes, result);
+	announceTextChange(text);
+}
+function applyTextAndStyles(text, graphemes, runs) {
+	const value = graphemes.join("");
+	text.styles = writeStyleRuns(graphemes, runs);
+	if (text.text !== value) text.set("text", value);
+	else text.initDimensions();
+	text.set("dirty", true);
+	text.setCoords();
+}
+function announceTextChange(text) {
+	if (text.isEditing && text.hiddenTextarea && !text.inCompositionMode) {
+		text.hiddenTextarea.value = text.text;
+		text._updateTextarea?.();
+	}
+	text.fire("changed");
+	text.canvas?.fire("text:changed", { target: text });
+	text.canvas?.requestRenderAll();
+}
+function createTextCommands(engine) {
+	return {
+		insertText(target, index, text, style) {
+			if (!text) return;
+			engine.transaction("Insert text", () => replaceTextRange(target, index, index, text, style));
+		},
+		deleteText(target, start, end) {
+			if (end <= start) return;
+			engine.transaction("Delete text", () => replaceTextRange(target, start, end, ""));
+		},
+		replaceText(target, start, end, text, style) {
+			engine.transaction("Replace text", () => replaceTextRange(target, start, end, text, style));
+		},
+		setTextStyle(target, start, end, style) {
+			if (end <= start) return;
+			engine.transaction("Style text", () => setTextRangeStyle(target, start, end, style));
+		}
+	};
+}
+//#endregion
+export { createTextCommands, readStyleRuns, replaceTextRange, setTextRangeStyle, shiftStyleRuns, writeStyleRuns };

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;