@lvl99dotcom/paintcanvas 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,194 @@
+// src/lib/classes/Viewport/index.ts
+/** Zoom steps used by the zoom tool, from 1/16 to 32× */
+var ZOOM_LEVELS = [
+	.0625,
+	.125,
+	.25,
+	1 / 3,
+	.5,
+	2 / 3,
+	1,
+	1.5,
+	2,
+	3,
+	4,
+	6,
+	8,
+	12,
+	16,
+	24,
+	32
+];
+/** Smallest zoom */
+var MIN_ZOOM = ZOOM_LEVELS[0];
+/** Largest zoom */
+var MAX_ZOOM = ZOOM_LEVELS[ZOOM_LEVELS.length - 1];
+/** Screen space (CSS pixels) of canvas that must stay visible so it can't be panned out of reach */
+var MIN_VISIBLE = 64;
+/** Space left around the canvas when fitting it to the screen, in CSS pixels */
+var FIT_PADDING = 24;
+var NO_INSETS = {
+	top: 0,
+	right: 0,
+	bottom: 0,
+	left: 0
+};
+/**
+* Clamp a value between min and max.
+*/
+var clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+/**
+* The user's view of the canvas: zoom level and position. Converts between screen and canvas coordinates.
+*
+* The canvas pixel at `(0, 0)` is drawn at screen position `(offsetX, offsetY)`, and one canvas pixel is `zoom` CSS pixels wide.
+*
+* Dispatches a `change` event whenever the view moves or zooms.
+*
+* @example
+* const view = new Viewport(2000, 2000);
+* view.resize(1280, 800);
+* view.fit();
+* view.zoomAt({ x: 640, y: 400 }, 2);
+* view.screenToCanvas({ x: 640, y: 400 }); // canvas point under the screen centre
+*/
+var Viewport = class extends EventTarget {
+	/** Canvas width in pixels */
+	canvasWidth;
+	/** Canvas height in pixels */
+	canvasHeight;
+	/** Screen width in CSS pixels */
+	width = 0;
+	/** Screen height in CSS pixels */
+	height = 0;
+	/** CSS pixels per canvas pixel */
+	zoom = 1;
+	/** Screen X of the canvas's left edge */
+	offsetX = 0;
+	/** Screen Y of the canvas's top edge */
+	offsetY = 0;
+	constructor(canvasWidth, canvasHeight) {
+		super();
+		this.canvasWidth = canvasWidth;
+		this.canvasHeight = canvasHeight;
+	}
+	/**
+	* Convert a screen point to canvas pixels.
+	*/
+	screenToCanvas({ x, y }) {
+		return {
+			x: (x - this.offsetX) / this.zoom,
+			y: (y - this.offsetY) / this.zoom
+		};
+	}
+	/**
+	* Convert a canvas point to screen (CSS) pixels.
+	*/
+	canvasToScreen({ x, y }) {
+		return {
+			x: x * this.zoom + this.offsetX,
+			y: y * this.zoom + this.offsetY
+		};
+	}
+	/**
+	* The part of the canvas currently visible on screen, clipped to the canvas.
+	*/
+	visibleRect() {
+		const topLeft = this.screenToCanvas({
+			x: 0,
+			y: 0
+		});
+		const bottomRight = this.screenToCanvas({
+			x: this.width,
+			y: this.height
+		});
+		const x = clamp(topLeft.x, 0, this.canvasWidth);
+		const y = clamp(topLeft.y, 0, this.canvasHeight);
+		return {
+			x,
+			y,
+			width: clamp(bottomRight.x, 0, this.canvasWidth) - x,
+			height: clamp(bottomRight.y, 0, this.canvasHeight) - y
+		};
+	}
+	/**
+	* Set the screen size (e.g. when the window resizes). Keeps the view in reach.
+	*/
+	resize(width, height) {
+		this.width = width;
+		this.height = height;
+		this.constrain();
+		this.notify();
+	}
+	/**
+	* Zoom and centre so the whole canvas fits in the space not covered by the interface (never zooming in past 100%).
+	*/
+	fit(insets = NO_INSETS) {
+		const availableWidth = Math.max(1, this.width - insets.left - insets.right - 48);
+		const availableHeight = Math.max(1, this.height - insets.top - insets.bottom - 48);
+		this.zoom = clamp(Math.min(availableWidth / this.canvasWidth, availableHeight / this.canvasHeight, 1), MIN_ZOOM, MAX_ZOOM);
+		this.offsetX = insets.left + (this.width - insets.left - insets.right - this.canvasWidth * this.zoom) / 2;
+		this.offsetY = insets.top + (this.height - insets.top - insets.bottom - this.canvasHeight * this.zoom) / 2;
+		this.notify();
+	}
+	/**
+	* Move the view so a canvas point is in the middle of the space not covered by the interface (e.g. clicking the canvas map).
+	*/
+	centreOn({ x, y }, insets = NO_INSETS) {
+		const centreX = insets.left + (this.width - insets.left - insets.right) / 2;
+		const centreY = insets.top + (this.height - insets.top - insets.bottom) / 2;
+		this.offsetX = centreX - x * this.zoom;
+		this.offsetY = centreY - y * this.zoom;
+		this.constrain();
+		this.notify();
+	}
+	/**
+	* Move the view by a distance in screen pixels (e.g. while dragging with the pan tool).
+	*/
+	panBy(dx, dy) {
+		this.offsetX += dx;
+		this.offsetY += dy;
+		this.constrain();
+		this.notify();
+	}
+	/**
+	* Zoom to a level, keeping the canvas point under `anchor` (a screen point) in place.
+	*/
+	zoomAt(anchor, zoom) {
+		const canvasPoint = this.screenToCanvas(anchor);
+		this.zoom = clamp(zoom, MIN_ZOOM, MAX_ZOOM);
+		this.offsetX = anchor.x - canvasPoint.x * this.zoom;
+		this.offsetY = anchor.y - canvasPoint.y * this.zoom;
+		this.constrain();
+		this.notify();
+	}
+	/**
+	* Zoom in one step around a screen point (zoom tool click).
+	*/
+	zoomIn(anchor) {
+		this.zoomAt(anchor, ZOOM_LEVELS.find((level) => level > this.zoom + 1e-9) ?? MAX_ZOOM);
+	}
+	/**
+	* Zoom out one step around a screen point (zoom tool Alt+click).
+	*/
+	zoomOut(anchor) {
+		this.zoomAt(anchor, [...ZOOM_LEVELS].reverse().find((level) => level < this.zoom - 1e-9) ?? MIN_ZOOM);
+	}
+	/**
+	* Keep at least `MIN_VISIBLE` pixels of the canvas on screen in each direction.
+	*/
+	constrain() {
+		const canvasScreenWidth = this.canvasWidth * this.zoom;
+		const canvasScreenHeight = this.canvasHeight * this.zoom;
+		const keepX = Math.min(64, canvasScreenWidth);
+		const keepY = Math.min(64, canvasScreenHeight);
+		this.offsetX = clamp(this.offsetX, keepX - canvasScreenWidth, this.width - keepX);
+		this.offsetY = clamp(this.offsetY, keepY - canvasScreenHeight, this.height - keepY);
+	}
+	/**
+	* Dispatch a `change` event.
+	*/
+	notify() {
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { FIT_PADDING, MAX_ZOOM, MIN_VISIBLE, MIN_ZOOM, ZOOM_LEVELS, Viewport as default };

package/dist/lib/document/index.d.ts

@@ -0,0 +1,17 @@
+import type { PaintCanvasDocument } from "./schema";
+export * from "./schema";
+/** Result of checking a document */
+export type DocumentValidationResult = {
+    valid: true;
+    value: PaintCanvasDocument;
+} | {
+    valid: false;
+    errors: string[];
+};
+/**
+ * Check a document (e.g. read from a file) against `documentSchema`, and that its selected layer exists.
+ *
+ * @example
+ * isValidDocument(JSON.parse(text)).valid; // true
+ */
+export declare const isValidDocument: (input: unknown) => DocumentValidationResult;

package/dist/lib/document/index.js

@@ -0,0 +1,25 @@
+import { formatErrors } from "../presets/index.js";
+import { validateDocument } from "../validation/validators.generated.js";
+import { DOCUMENT_BLEND_MODES, DOCUMENT_FORMAT, DOCUMENT_VERSION, MAX_DOCUMENT_IMAGE_LENGTH, MAX_DOCUMENT_LAYERS, MAX_DOCUMENT_SHEETS, MAX_DOCUMENT_SIZE, documentSchema } from "./schema.js";
+// src/lib/document/index.ts
+/**
+* Check a document (e.g. read from a file) against `documentSchema`, and that its selected layer exists.
+*
+* @example
+* isValidDocument(JSON.parse(text)).valid; // true
+*/
+var isValidDocument = (input) => {
+	if (!validateDocument(input)) return {
+		valid: false,
+		errors: formatErrors(validateDocument.errors)
+	};
+	if (input.activeLayer >= input.layers.length) return {
+		valid: false,
+		errors: ["/activeLayer must be one of the layers"]
+	};
+	return {
+		valid: true,
+		value: input
+	};
+};
+export { DOCUMENT_BLEND_MODES, DOCUMENT_FORMAT, DOCUMENT_VERSION, MAX_DOCUMENT_IMAGE_LENGTH, MAX_DOCUMENT_LAYERS, MAX_DOCUMENT_SHEETS, MAX_DOCUMENT_SIZE, documentSchema, isValidDocument };

package/dist/lib/document/schema.d.ts

@@ -0,0 +1,132 @@
+/** The `format` of a PaintCanvas document */
+export declare const DOCUMENT_FORMAT = "paintcanvas-document";
+/** Version of the document format */
+export declare const DOCUMENT_VERSION = 1;
+/** Largest canvas width or height a document may have */
+export declare const MAX_DOCUMENT_SIZE = 10000;
+/** Most layers in a document (a canvas may allow fewer, see `maxLayers`) */
+export declare const MAX_DOCUMENT_LAYERS = 100;
+/** Most drawings from elsewhere in a document */
+export declare const MAX_DOCUMENT_SHEETS = 100;
+/** Longest image in a document (characters): a PNG data URL of up to 100 MB */
+export declare const MAX_DOCUMENT_IMAGE_LENGTH: number;
+/** Blend modes a layer may have (see `BlendMode`) */
+export declare const DOCUMENT_BLEND_MODES: readonly ["source-over", "screen", "lighten", "multiply", "darken", "overlay"];
+/** A layer in a document */
+export interface DocumentLayer {
+    name: string;
+    visible: boolean;
+    opacity: number;
+    blendMode: (typeof DOCUMENT_BLEND_MODES)[number];
+    alphaLock: boolean;
+    /** The layer's pixels as a PNG data URL, the size of the canvas */
+    image: string;
+}
+/** A drawing from elsewhere in a document (see `ExternalSheets`) */
+export interface DocumentSheet {
+    /** Where it came from */
+    source: string;
+    /** Its pixels as a PNG data URL, the size of the canvas */
+    image: string;
+}
+/** A saved drawing */
+export interface PaintCanvasDocument {
+    format: typeof DOCUMENT_FORMAT;
+    version: typeof DOCUMENT_VERSION;
+    width: number;
+    height: number;
+    /** The user's layers, top first */
+    layers: DocumentLayer[];
+    /** Index of the selected layer in `layers` */
+    activeLayer: number;
+    /** Drawings from elsewhere, top first */
+    external: DocumentSheet[];
+}
+/** JSON schema for a document */
+export declare const documentSchema: {
+    readonly $id: "paintcanvas/document";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["format", "version", "width", "height", "layers", "activeLayer", "external"];
+    readonly properties: {
+        readonly format: {
+            readonly const: "paintcanvas-document";
+        };
+        readonly version: {
+            readonly const: 1;
+        };
+        readonly width: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 10000;
+        };
+        readonly height: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 10000;
+        };
+        readonly layers: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly maxItems: 100;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["name", "visible", "opacity", "blendMode", "alphaLock", "image"];
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 64;
+                        readonly pattern: "\\S";
+                    };
+                    readonly visible: {
+                        readonly type: "boolean";
+                    };
+                    readonly opacity: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                        readonly maximum: 1;
+                    };
+                    readonly blendMode: {
+                        readonly enum: readonly ["source-over", "screen", "lighten", "multiply", "darken", "overlay"];
+                    };
+                    readonly alphaLock: {
+                        readonly type: "boolean";
+                    };
+                    readonly image: {
+                        readonly type: "string";
+                        readonly pattern: "^data:image/png;base64,[A-Za-z0-9+/]*={0,2}$";
+                        readonly maxLength: number;
+                    };
+                };
+            };
+        };
+        readonly activeLayer: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly maximum: number;
+        };
+        readonly external: {
+            readonly type: "array";
+            readonly maxItems: 100;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["source", "image"];
+                readonly properties: {
+                    readonly source: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 2048;
+                    };
+                    readonly image: {
+                        readonly type: "string";
+                        readonly pattern: "^data:image/png;base64,[A-Za-z0-9+/]*={0,2}$";
+                        readonly maxLength: number;
+                    };
+                };
+            };
+        };
+    };
+};

package/dist/lib/document/schema.js

@@ -0,0 +1,110 @@
+// src/lib/document/schema.ts
+/** The `format` of a PaintCanvas document */
+var DOCUMENT_FORMAT = "paintcanvas-document";
+/** Version of the document format */
+var DOCUMENT_VERSION = 1;
+/** Largest canvas width or height a document may have */
+var MAX_DOCUMENT_SIZE = 1e4;
+/** Most layers in a document (a canvas may allow fewer, see `maxLayers`) */
+var MAX_DOCUMENT_LAYERS = 100;
+/** Most drawings from elsewhere in a document */
+var MAX_DOCUMENT_SHEETS = 100;
+/** Longest image in a document (characters): a PNG data URL of up to 100 MB */
+var MAX_DOCUMENT_IMAGE_LENGTH = Math.ceil(104857600 / 3) * 4 + 22;
+/** Blend modes a layer may have (see `BlendMode`) */
+var DOCUMENT_BLEND_MODES = [
+	"source-over",
+	"screen",
+	"lighten",
+	"multiply",
+	"darken",
+	"overlay"
+];
+var image = {
+	type: "string",
+	pattern: "^data:image/png;base64,[A-Za-z0-9+/]*={0,2}$",
+	maxLength: MAX_DOCUMENT_IMAGE_LENGTH
+};
+var size = {
+	type: "integer",
+	minimum: 1,
+	maximum: MAX_DOCUMENT_SIZE
+};
+/** JSON schema for a document */
+var documentSchema = {
+	$id: "paintcanvas/document",
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"format",
+		"version",
+		"width",
+		"height",
+		"layers",
+		"activeLayer",
+		"external"
+	],
+	properties: {
+		format: { const: DOCUMENT_FORMAT },
+		version: { const: 1 },
+		width: size,
+		height: size,
+		layers: {
+			type: "array",
+			minItems: 1,
+			maxItems: 100,
+			items: {
+				type: "object",
+				additionalProperties: false,
+				required: [
+					"name",
+					"visible",
+					"opacity",
+					"blendMode",
+					"alphaLock",
+					"image"
+				],
+				properties: {
+					name: {
+						type: "string",
+						minLength: 1,
+						maxLength: 64,
+						pattern: "\\S"
+					},
+					visible: { type: "boolean" },
+					opacity: {
+						type: "number",
+						minimum: 0,
+						maximum: 1
+					},
+					blendMode: { enum: DOCUMENT_BLEND_MODES },
+					alphaLock: { type: "boolean" },
+					image
+				}
+			}
+		},
+		activeLayer: {
+			type: "integer",
+			minimum: 0,
+			maximum: 99
+		},
+		external: {
+			type: "array",
+			maxItems: 100,
+			items: {
+				type: "object",
+				additionalProperties: false,
+				required: ["source", "image"],
+				properties: {
+					source: {
+						type: "string",
+						minLength: 1,
+						maxLength: 2048
+					},
+					image
+				}
+			}
+		}
+	}
+};
+export { DOCUMENT_BLEND_MODES, DOCUMENT_FORMAT, DOCUMENT_VERSION, MAX_DOCUMENT_IMAGE_LENGTH, MAX_DOCUMENT_LAYERS, MAX_DOCUMENT_SHEETS, MAX_DOCUMENT_SIZE, documentSchema };

package/dist/lib/i18n/index.d.ts

@@ -0,0 +1,131 @@
+/** Translated text, by key */
+export type Strings = Record<string, string>;
+/** Loads a locale's strings (e.g. a dynamic `import()` of its JSON file, so it's only downloaded when used) */
+export type LocaleLoader = () => Promise<Strings | {
+    default: Strings;
+}>;
+/** The locale used when no other matches, and whose strings fill in any missing from other locales */
+export declare const FALLBACK_LOCALE = "en-US";
+/** Locales whose files come with PaintCanvas (in `locales/`, named by their IETF BCP 47 tag) */
+export declare const BUILT_IN_LOCALES: Record<string, LocaleLoader>;
+/**
+ * The best available locale for the requested ones (e.g. the device's `navigator.languages`, most preferred first):
+ * the same tag, then the same language and script (`zh-TW` → `zh-Hant`), then the same language (British regions
+ * prefer `en-GB`, other English `en-US`), otherwise `fallback`.
+ *
+ * @example
+ * matchLocale(["zh-TW", "en"], ["en-US", "zh-Hans", "zh-Hant"]); // "zh-Hant"
+ * matchLocale(["en-AU"], ["en-US", "en-GB"]); // "en-GB"
+ * matchLocale(["fr-FR"], ["en-US", "ja"]); // "en-US"
+ */
+export declare const matchLocale: (requested: readonly string[], available: readonly string[], fallback?: string) => string;
+/**
+ * Put values into a string's `{name}` placeholders. Placeholders without a value are left as they are.
+ *
+ * @example
+ * interpolate("Delete \"{name}\"?", { name: "Sketch" }); // 'Delete "Sketch"?'
+ */
+export declare const interpolate: (text: string, values?: Record<string, string | number>) => string;
+/**
+ * A locale's language name, written in that language (so people can find their own), with its first letter in
+ * capitals. Gives the tag itself if the browser can't name it.
+ *
+ * @example
+ * languageName("ja"); // "日本語"
+ * languageName("fr"); // "Français"
+ * languageName("en-GB"); // "English (United Kingdom)"
+ */
+export declare const languageName: (locale: string) => string;
+/** Options for translations */
+export interface TranslationsOptions {
+    /** Locales that can be used, and how to load each (default: all the locales that come with PaintCanvas) */
+    locales?: Record<string, LocaleLoader>;
+    /** Locale used when no other matches (default `FALLBACK_LOCALE`) */
+    fallback?: string;
+    /** The fallback locale's strings, available straight away (default: PaintCanvas's US English) */
+    fallbackStrings?: Strings;
+}
+/**
+ * The text the UI shows, in the chosen language. Starts in the fallback locale; `useDeviceLocale` switches to the best
+ * match for the device, and `setLocale` to any available locale. Locale files load when first used, without reloading
+ * the page. Strings missing from a locale come from the fallback locale, then the key itself.
+ *
+ * Other projects can add their own strings and locales with `addLocales` and `addStrings`. A locale's strings from
+ * every set load together and are merged in the order the sets were added (PaintCanvas's first), so a key in a later
+ * set replaces the same key in an earlier one. Keys are prefixed by project by convention: `paintCanvas.` for
+ * PaintCanvas's, and e.g. `liveCanvas.` for an app's.
+ *
+ * Dispatches a `change` event when the locale or its strings change, so the UI can show the new text.
+ *
+ * @example
+ * const translations = new Translations({ locales: { "en-US": ..., ja: () => import("./ja.json") } });
+ * await translations.useDeviceLocale();
+ * translations.t("paintCanvas.layers.delete", { name: "Sketch" });
+ */
+export default class Translations extends EventTarget {
+    private readonly fallback;
+    /** Sets of strings, in the order they were added */
+    private readonly sources;
+    /** Each locale's strings from every set loaded so far, merged in order */
+    private readonly merged;
+    private current;
+    /** The locale most recently asked for, so a slow load can't override a later choice */
+    private requested?;
+    constructor(options?: TranslationsOptions);
+    /** The locale in use (an IETF BCP 47 tag, e.g. `ja`) */
+    get locale(): string;
+    /** Locales that can be used: the fallback, and every locale a set of strings can load */
+    get locales(): string[];
+    /**
+     * Switch to the best available locale for the device's languages (`navigator.languages`).
+     */
+    useDeviceLocale(languages?: readonly string[]): Promise<void>;
+    /**
+     * Switch to a locale (the best available match for the tag), loading its strings from every set if needed.
+     * Dispatches `change` once they're ready. If loading fails, the current locale stays and this rejects.
+     *
+     * @example
+     * await translations.setLocale("zh-TW"); // uses zh-Hant
+     */
+    setLocale(tag: string): Promise<void>;
+    /**
+     * Add a set of strings for some locales, loaded when first used, after the sets already added (so its keys replace
+     * theirs). Its locales become available. The locale in use and the fallback load straight away, then `change` is
+     * dispatched if the set has strings for either.
+     *
+     * @example
+     * await translations.addLocales({
+     *   "en-US": () => import("./locales/en-US.json"),
+     *   fr: () => import("./locales/fr.json"),
+     * });
+     * translations.t("liveCanvas.share");
+     */
+    addLocales(loaders: Record<string, LocaleLoader>): Promise<void>;
+    /**
+     * Add or replace strings for a locale (e.g. the implementer's own wording or extra keys), after the sets already
+     * added. Dispatches `change` if it's the locale in use or the fallback.
+     *
+     * @example
+     * translations.addStrings("en-US", { "paintCanvas.tool.brush": "Paintbrush" });
+     */
+    addStrings(locale: string, strings: Strings): void;
+    /**
+     * Load a locale's strings from every set, including sets added while loading, then merge them.
+     */
+    private load;
+    /**
+     * Merge a locale's strings loaded so far from every set, in the order the sets were added.
+     */
+    private merge;
+    /**
+     * Translate a key, putting values into its `{name}` placeholders. With a numeric `count`, the key's plural form for
+     * the locale is used when there is one (e.g. `paintCanvas.presets.imported.one` and
+     * `paintCanvas.presets.imported.other`). Falls back to the fallback locale, then the key.
+     *
+     * @example
+     * translations.t("paintCanvas.presets.imported", { count: 3 }); // "Imported 3 brush presets"
+     */
+    t(key: string, values?: Record<string, string | number>): string;
+}
+/** The translations PaintCanvas's UI uses, unless an element is given others */
+export declare const translations: Translations;