@lvl99dotcom/paintcanvas 0.3.1 → 0.5.0

package/dist/lib/classes/BrushSettings/index.js

@@ -5,6 +5,10 @@ var MIN_BRUSH_SIZE = 1;
 var MAX_BRUSH_SIZE = 256;
 /** Fraction of the current size added or removed by `grow` and `shrink` ("]" and "[" keys) */
 var BRUSH_SIZE_STEP = .1;
+/** Opacity step for the opacity keyboard shortcuts, in percent */
+var BRUSH_OPACITY_STEP = 10;
+/** Lowest opacity the opacity keyboard shortcuts go to, in percent */
+var MIN_BRUSH_OPACITY = 1;
 /**
 * Clamp a value between min and max.
 *
@@ -13,6 +17,35 @@ var BRUSH_SIZE_STEP = .1;
 */
 var clamp = (value, min, max) => Math.max(min, Math.min(max, value));
 /**
+* The next opacity step up or down, in percent: to the next multiple of `BRUSH_OPACITY_STEP`, from
+* `MIN_BRUSH_OPACITY` to 100.
+*
+* @example
+* stepOpacity(45, 1); // 50
+* stepOpacity(10, -1); // 1
+* stepOpacity(1, 1); // 10
+*/
+var stepOpacity = (percent, direction) => {
+	const steps = percent / 10;
+	return clamp((direction > 0 ? Math.floor(steps + 1e-9) + 1 : Math.ceil(steps - 1e-9) - 1) * 10, 1, 100);
+};
+/**
+* A brush size with the given width and proportions (width ÷ height), in whole pixels. The width is kept within the
+* range where the smaller side is at least `MIN_BRUSH_SIZE` and the larger side at most `MAX_BRUSH_SIZE`, so the
+* proportions are kept at either end.
+*
+* @example
+* proportionalSize(0, 3); // { width: 3, height: 1 }
+* proportionalSize(1000, 0.5); // { width: 128, height: 256 }
+*/
+var proportionalSize = (width, aspect) => {
+	const fitted = Math.round(clamp(width, Math.max(1, 1 * aspect), Math.min(256, 256 * aspect)));
+	return {
+		width: fitted,
+		height: Math.round(clamp(fitted / aspect, 1, 256))
+	};
+};
+/**
 * The settings of a brush or eraser: the selected preset, an editable copy of its settings (changed from the tool
 * settings bar or the configuration window, without changing the preset) and the size. The brush and eraser each have
 * their own instance.
@@ -35,6 +68,11 @@ var BrushSettings = class extends EventTarget {
 	presetId;
 	/** The current settings: a copy of the selected preset, with any changes */
 	current;
+	/**
+	* The brush's proportions (width ÷ height), kept apart from the rounded size so resizing to either end and back
+	* doesn't change them. Set by the preset and by setting the size while proportions aren't constrained.
+	*/
+	aspect = 1;
 	constructor(presets) {
 		super();
 		const first = Object.values(presets)[0];
@@ -101,39 +139,64 @@ var BrushSettings = class extends EventTarget {
 	* Set the height, clamped to 1–256 pixels. If the settings constrain proportions, width follows height.
 	*/
 	setHeight(height) {
-		if (!this.current.constrainProportions) {
-			this.setSize(this.width, height);
-			return;
-		}
-		const ratio = this.width / this.height;
-		this.setSize(clamp(height, 1, 256) * ratio);
+		if (this.current.constrainProportions) this.setProportionalSize(height * this.aspect);
+		else this.setSize(this.width, height);
 	}
 	/**
-	* Set the size, clamped to 1–256 pixels. If the settings constrain proportions, height follows width.
+	* Set the size, clamped to 1–256 pixels. If the settings constrain proportions, height follows width, and the width
+	* stops where either side would leave that range.
 	*/
 	setSize(width, height = width) {
-		const ratio = this.height / this.width;
+		if (this.current.constrainProportions) {
+			this.setProportionalSize(width);
+			return;
+		}
 		this.width = Math.round(clamp(width, 1, 256));
-		this.height = Math.round(clamp(this.preset.constrainProportions ? this.width * ratio : height, 1, 256));
+		this.height = Math.round(clamp(height, 1, 256));
+		this.aspect = this.width / this.height;
 		this.notify();
 	}
 	/**
-	* Change the size by a number of pixels (positive = bigger). Used when dragging up/right (bigger) or down/left (smaller).
+	* Change the size by a number of pixels (positive = bigger), keeping the proportions: the larger side changes by
+	* `delta`. Stops when the smaller side reaches 1 pixel or the larger 256. Used when dragging up/right (bigger) or
+	* down/left (smaller).
 	*/
 	resize(delta) {
-		this.setSize(this.width + delta, this.height + delta);
+		const larger = Math.max(this.width, this.height) + delta;
+		this.setProportionalSize(this.aspect >= 1 ? larger : larger * this.aspect);
+	}
+	/** The larger side (what `resize` changes), which `grow` and `shrink` step from */
+	get largerSide() {
+		return Math.max(this.width, this.height);
 	}
 	/**
 	* Increase the size by one step (at least 1 pixel).
 	*/
 	grow() {
-		this.resize(Math.max(1, Math.round(this.width * BRUSH_SIZE_STEP)));
+		this.resize(Math.max(1, Math.round(this.largerSide * BRUSH_SIZE_STEP)));
 	}
 	/**
 	* Decrease the size by one step (at least 1 pixel).
 	*/
 	shrink() {
-		this.resize(-Math.max(1, Math.round(this.width * BRUSH_SIZE_STEP)));
+		this.resize(-Math.max(1, Math.round(this.largerSide * BRUSH_SIZE_STEP)));
+	}
+	/**
+	* Increase the opacity by one step (see `stepOpacity`).
+	*/
+	moreOpaque() {
+		this.stepOpacity(1);
+	}
+	/**
+	* Decrease the opacity by one step (see `stepOpacity`).
+	*/
+	lessOpaque() {
+		this.stepOpacity(-1);
+	}
+	/** Change the opacity by one step up or down */
+	stepOpacity(direction) {
+		const percent = Math.round((this.current.alpha ?? 1) * 100);
+		this.update({ alpha: stepOpacity(percent, direction) / 100 });
 	}
 	/**
 	* Use a preset's (or configuration's) default size.
@@ -141,6 +204,14 @@ var BrushSettings = class extends EventTarget {
 	applyPresetSize(preset) {
 		this.width = preset.width ?? 1;
 		this.height = preset.height ?? this.width;
+		this.aspect = this.width / this.height;
+	}
+	/**
+	* Set the width, with the height following the stored proportions (see `proportionalSize`).
+	*/
+	setProportionalSize(width) {
+		Object.assign(this, proportionalSize(width, this.aspect));
+		this.notify();
 	}
 	/**
 	* Dispatch a `change` event.
@@ -149,4 +220,4 @@ var BrushSettings = class extends EventTarget {
 		this.dispatchEvent(new Event("change"));
 	}
 };
-export { BRUSH_SIZE_STEP, MAX_BRUSH_SIZE, MIN_BRUSH_SIZE, clamp, BrushSettings as default };
+export { BRUSH_OPACITY_STEP, BRUSH_SIZE_STEP, MAX_BRUSH_SIZE, MIN_BRUSH_OPACITY, MIN_BRUSH_SIZE, clamp, BrushSettings as default, proportionalSize, stepOpacity };

package/dist/lib/classes/KeyboardShortcuts/index.d.ts

@@ -1,14 +1,32 @@
 import { type default as PaintCanvas } from "../PaintCanvas";
 import { type ShortcutAction } from "../../utils/shortcuts";
+/**
+ * How long (milliseconds) the paste shortcut waits for the browser's `paste` event (which carries other apps' images)
+ * before pasting the image data copied here
+ */
+export declare const PASTE_EVENT_WAIT_MS = 50;
+/**
+ * The first image in a paste's clipboard data (e.g. copied in another app), if any.
+ *
+ * @example
+ * pastedImage(event.clipboardData); // File of type "image/png", or undefined
+ */
+export declare const pastedImage: (data: DataTransfer | null) => File | undefined;
 /** Event dispatched on the window for shortcut actions handled elsewhere (e.g. saving) */
 export declare const SHORTCUT_EVENT = "pc-shortcut";
 /**
- * Listens for key presses and runs the matching shortcut on the app. Shortcuts are ignored while typing in text fields.
+ * Listens for key presses and runs the matching shortcut on the app, using the user's key combinations
+ * (`app.shortcuts`). Shortcuts are ignored while typing in text fields and inside open `<dialog>` elements. Key presses are matched on keyboards with
+ * different layouts (see `comboFromEvent`).
  *
- * Tool selection, brush/eraser size, interface visibility, select all/deselect, undo/redo, cut/copy/paste, deleting the
- * masked image data (Delete or Backspace) and finishing or cancelling a
- * lasso shape are handled here; other actions (and Escape/Enter for later features) dispatch an `pc-shortcut` event with the action as `detail`.
- * Holding Space pans temporarily; releasing it returns to the selected tool.
+ * Tool selection, brush/eraser size and opacity, interface visibility, select all/invert/deselect, undo/redo,
+ * cut/copy/paste, deleting the masked image data (Delete or Backspace), fills, swapping colours, zooming, layer opacity
+ * and finishing or cancelling a lasso shape are handled here. Pasting (the shortcut, or the browser's own paste, e.g. from
+ * its Edit menu) pastes the image data copied here, unless the window has lost focus since it was copied and the
+ * clipboard has an image (e.g. copied in another app): that image is pasted instead (see `PaintCanvas.pasteImage`).
+ * Other actions other actions (and Escape/Enter for later features)
+ * dispatch an `pc-shortcut` event with the action as `detail`. Holding the hold-to-pan key (Space by default) pans
+ * temporarily; releasing it returns to the selected tool.
  *
  * @example
  * const shortcuts = new KeyboardShortcuts(app);
@@ -17,10 +35,19 @@ export declare const SHORTCUT_EVENT = "pc-shortcut";
 export default class KeyboardShortcuts {
     private readonly app;
     private target;
+    /** The hold-to-pan key while it is held */
+    private heldKey?;
     private readonly onKeyDown;
     private readonly onKeyUp;
+    /** Turns pasted image files into images (replaceable for tests) */
+    private readonly decodeImage;
+    /** `app.copyCount` when the window last lost focus: copies since then were made here */
+    private copiesBeforeBlur;
+    /** Pastes the image data copied here if the browser doesn't fire `paste` soon after the shortcut */
+    private pasteTimer?;
     private readonly onBlur;
-    constructor(app: PaintCanvas);
+    private readonly onPaste;
+    constructor(app: PaintCanvas, decodeImage?: (blob: Blob) => Promise<ImageBitmap>);
     /**
      * Start listening for key presses on a target (usually `window`).
      */
@@ -34,13 +61,26 @@ export default class KeyboardShortcuts {
      */
     handle(event: KeyboardEvent): ShortcutAction | undefined;
     /**
-     * Return to the selected tool when the hold-to-pan key is released.
+     * Paste from the browser's `paste` event: the image data copied here if it was copied since the window last lost
+     * focus (or the clipboard has no image), otherwise the clipboard's image. Ignored in text fields and open dialogs.
+     */
+    handlePaste(event: ClipboardEvent): Promise<void>;
+    /** Stop waiting for the browser's `paste` event */
+    private cancelPasteTimer;
+    /**
+     * Return to the selected tool when the hold-to-pan key is released (whatever modifiers are held by then).
      */
     handleKeyUp(event: KeyboardEvent): void;
+    /** Stop holding the hold-to-pan key */
+    private release;
     /**
      * Run a shortcut action.
      */
     run(action: ShortcutAction): void;
+    /** The brush or eraser settings while that tool is selected */
+    private brushSettings;
+    /** The middle of the viewport, which zoom shortcuts zoom around */
+    private viewportCentre;
     /**
      * Dispatch an action as an `pc-shortcut` event for features handled elsewhere.
      */

package/dist/lib/classes/KeyboardShortcuts/index.js

@@ -1,15 +1,39 @@
-import { Tool } from "../PaintCanvas/index.js";
-import { isTypingTarget, matchShortcut } from "../../utils/shortcuts/index.js";
+import { Tool } from "../PaintCanvas/tool.js";
+import "../PaintCanvas/index.js";
+import { comboFromEvent, isTypingTarget, sameCombo } from "../../utils/shortcuts/index.js";
 // src/lib/classes/KeyboardShortcuts/index.ts
+/**
+* Whether a key press happened inside an open `<dialog>` (e.g. a settings window), where shortcuts must not apply and
+* Escape is left to close it.
+*/
+var inOpenDialog = (path) => path.some((target) => target instanceof HTMLDialogElement && target.open);
+/**
+* How long (milliseconds) the paste shortcut waits for the browser's `paste` event (which carries other apps' images)
+* before pasting the image data copied here
+*/
+var PASTE_EVENT_WAIT_MS = 50;
+/**
+* The first image in a paste's clipboard data (e.g. copied in another app), if any.
+*
+* @example
+* pastedImage(event.clipboardData); // File of type "image/png", or undefined
+*/
+var pastedImage = (data) => [...data?.files ?? []].find((file) => file.type.startsWith("image/"));
 /** Event dispatched on the window for shortcut actions handled elsewhere (e.g. saving) */
 var SHORTCUT_EVENT = "pc-shortcut";
 /**
-* Listens for key presses and runs the matching shortcut on the app. Shortcuts are ignored while typing in text fields.
+* Listens for key presses and runs the matching shortcut on the app, using the user's key combinations
+* (`app.shortcuts`). Shortcuts are ignored while typing in text fields and inside open `<dialog>` elements. Key presses are matched on keyboards with
+* different layouts (see `comboFromEvent`).
 *
-* Tool selection, brush/eraser size, interface visibility, select all/deselect, undo/redo, cut/copy/paste, deleting the
-* masked image data (Delete or Backspace) and finishing or cancelling a
-* lasso shape are handled here; other actions (and Escape/Enter for later features) dispatch an `pc-shortcut` event with the action as `detail`.
-* Holding Space pans temporarily; releasing it returns to the selected tool.
+* Tool selection, brush/eraser size and opacity, interface visibility, select all/invert/deselect, undo/redo,
+* cut/copy/paste, deleting the masked image data (Delete or Backspace), fills, swapping colours, zooming, layer opacity
+* and finishing or cancelling a lasso shape are handled here. Pasting (the shortcut, or the browser's own paste, e.g. from
+* its Edit menu) pastes the image data copied here, unless the window has lost focus since it was copied and the
+* clipboard has an image (e.g. copied in another app): that image is pasted instead (see `PaintCanvas.pasteImage`).
+* Other actions other actions (and Escape/Enter for later features)
+* dispatch an `pc-shortcut` event with the action as `detail`. Holding the hold-to-pan key (Space by default) pans
+* temporarily; releasing it returns to the selected tool.
 *
 * @example
 * const shortcuts = new KeyboardShortcuts(app);
@@ -18,11 +42,24 @@ var SHORTCUT_EVENT = "pc-shortcut";
 var KeyboardShortcuts = class {
 	app;
 	target = null;
+	/** The hold-to-pan key while it is held */
+	heldKey;
 	onKeyDown = (event) => this.handle(event);
 	onKeyUp = (event) => this.handleKeyUp(event);
-	onBlur = () => this.app.releaseHeldTool();
-	constructor(app) {
+	/** Turns pasted image files into images (replaceable for tests) */
+	decodeImage;
+	/** `app.copyCount` when the window last lost focus: copies since then were made here */
+	copiesBeforeBlur = 0;
+	/** Pastes the image data copied here if the browser doesn't fire `paste` soon after the shortcut */
+	pasteTimer;
+	onBlur = () => {
+		this.release();
+		this.copiesBeforeBlur = this.app.copyCount;
+	};
+	onPaste = (event) => void this.handlePaste(event);
+	constructor(app, decodeImage = (blob) => createImageBitmap(blob)) {
 		this.app = app;
+		this.decodeImage = decodeImage;
 	}
 	/**
 	* Start listening for key presses on a target (usually `window`).
@@ -33,6 +70,7 @@ var KeyboardShortcuts = class {
 		target.addEventListener("keydown", this.onKeyDown);
 		target.addEventListener("keyup", this.onKeyUp);
 		target.addEventListener("blur", this.onBlur);
+		target.addEventListener("paste", this.onPaste);
 	}
 	/**
 	* Stop listening for key presses.
@@ -41,29 +79,74 @@ var KeyboardShortcuts = class {
 		this.target?.removeEventListener("keydown", this.onKeyDown);
 		this.target?.removeEventListener("keyup", this.onKeyUp);
 		this.target?.removeEventListener("blur", this.onBlur);
+		this.target?.removeEventListener("paste", this.onPaste);
 		this.target = null;
+		this.cancelPasteTimer();
 	}
 	/**
 	* Run the shortcut for a key press, if any. Returns the action run.
 	*/
 	handle(event) {
-		if (isTypingTarget(event.composedPath()[0] ?? event.target)) return void 0;
-		if (event.key === " " && !event.metaKey && !event.ctrlKey && !event.altKey) {
+		const path = event.composedPath();
+		if (isTypingTarget(path[0] ?? event.target) || inOpenDialog(path)) return void 0;
+		const combo = comboFromEvent(event);
+		if (!combo) return void 0;
+		const { holdToPan, shortcuts } = this.app.shortcuts;
+		if (holdToPan && sameCombo(combo, holdToPan)) {
 			event.preventDefault();
+			this.heldKey = combo.key;
 			this.app.holdTool(Tool.Pan);
 			return;
 		}
-		const action = matchShortcut(event);
+		const action = shortcuts.find((shortcut) => sameCombo(shortcut, combo))?.action;
 		if (!action) return void 0;
+		if (action.type === "paste") {
+			this.cancelPasteTimer();
+			this.pasteTimer = setTimeout(() => {
+				this.pasteTimer = void 0;
+				this.app.paste();
+			}, 50);
+			return action;
+		}
 		event.preventDefault();
 		this.run(action);
 		return action;
 	}
 	/**
-	* Return to the selected tool when the hold-to-pan key is released.
+	* Paste from the browser's `paste` event: the image data copied here if it was copied since the window last lost
+	* focus (or the clipboard has no image), otherwise the clipboard's image. Ignored in text fields and open dialogs.
+	*/
+	async handlePaste(event) {
+		const path = event.composedPath();
+		if (isTypingTarget(path[0] ?? event.target) || inOpenDialog(path)) return;
+		this.cancelPasteTimer();
+		event.preventDefault();
+		const app = this.app;
+		const image = pastedImage(event.clipboardData);
+		const copiedHere = app.copyCount > this.copiesBeforeBlur;
+		if (!image || copiedHere && app.hasClipboard) {
+			app.paste();
+			return;
+		}
+		try {
+			app.pasteImage(await this.decodeImage(image));
+		} catch {}
+	}
+	/** Stop waiting for the browser's `paste` event */
+	cancelPasteTimer() {
+		clearTimeout(this.pasteTimer);
+		this.pasteTimer = void 0;
+	}
+	/**
+	* Return to the selected tool when the hold-to-pan key is released (whatever modifiers are held by then).
 	*/
 	handleKeyUp(event) {
-		if (event.key === " ") this.app.releaseHeldTool();
+		if (this.heldKey !== void 0 && comboFromEvent(event)?.key === this.heldKey) this.release();
+	}
+	/** Stop holding the hold-to-pan key */
+	release() {
+		this.heldKey = void 0;
+		this.app.releaseHeldTool();
 	}
 	/**
 	* Run a shortcut action.
@@ -75,21 +158,41 @@ var KeyboardShortcuts = class {
 				app.selectTool(action.tool);
 				break;
 			case "brush-smaller":
-			case "brush-bigger": {
-				const settings = app.tool === Tool.Eraser ? app.eraser : app.tool === Tool.Brush ? app.brush : void 0;
-				if (action.type === "brush-bigger") settings?.grow();
-				else settings?.shrink();
+				this.brushSettings()?.shrink();
+				break;
+			case "brush-bigger":
+				this.brushSettings()?.grow();
+				break;
+			case "brush-less-opaque":
+				this.brushSettings()?.lessOpaque();
+				break;
+			case "brush-more-opaque":
+				this.brushSettings()?.moreOpaque();
 				break;
-			}
 			case "toggle-interface":
 				app.toggleInterface();
 				break;
 			case "select-all":
 				app.selection.selectAll();
 				break;
+			case "invert-selection":
+				app.selection.invert();
+				break;
 			case "deselect":
 				app.selection.clear();
 				break;
+			case "zoom-in":
+				app.viewport.zoomIn(this.viewportCentre());
+				break;
+			case "zoom-out":
+				app.viewport.zoomOut(this.viewportCentre());
+				break;
+			case "reset-zoom":
+				app.viewport.zoomAt(this.viewportCentre(), 1);
+				break;
+			case "layer-opacity":
+				app.layers.update(app.layers.active.id, { opacity: action.opacity });
+				break;
 			case "undo":
 				app.undo();
 				break;
@@ -102,6 +205,15 @@ var KeyboardShortcuts = class {
 			case "delete":
 				app.deleteMasked();
 				break;
+			case "fill-foreground":
+				app.fill("foreground");
+				break;
+			case "fill-background":
+				app.fill("background");
+				break;
+			case "swap-colours":
+				app.swapColours();
+				break;
 			case "copy":
 				app.copy();
 				break;
@@ -127,6 +239,19 @@ var KeyboardShortcuts = class {
 			default: this.dispatch(action);
 		}
 	}
+	/** The brush or eraser settings while that tool is selected */
+	brushSettings() {
+		const { app } = this;
+		return app.tool === Tool.Eraser ? app.eraser : app.tool === Tool.Brush ? app.brush : void 0;
+	}
+	/** The middle of the viewport, which zoom shortcuts zoom around */
+	viewportCentre() {
+		const { width, height } = this.app.viewport;
+		return {
+			x: width / 2,
+			y: height / 2
+		};
+	}
 	/**
 	* Dispatch an action as an `pc-shortcut` event for features handled elsewhere.
 	*/
@@ -134,4 +259,4 @@ var KeyboardShortcuts = class {
 		(this.target ?? this.app).dispatchEvent(new CustomEvent(SHORTCUT_EVENT, { detail: action }));
 	}
 };
-export { SHORTCUT_EVENT, KeyboardShortcuts as default };
+export { PASTE_EVENT_WAIT_MS, SHORTCUT_EVENT, KeyboardShortcuts as default, pastedImage };