@lvl99dotcom/paintcanvas 0.3.1 → 0.5.0

package/dist/lib/settings/schema.js

@@ -0,0 +1,116 @@
+import { LOCALE_PATTERN, THEMES } from "../classes/UiSettings/index.js";
+import { HEX_COLOUR_PATTERN, MAX_PALETTE_COLOURS, paletteFileSchema } from "../palette/schema.js";
+// src/lib/settings/schema.ts
+/** The `format` of a settings file, unless the implementer names their own (see `PaintCanvasNames`) */
+var SETTINGS_FILE_FORMAT = "paintcanvas-settings";
+/** Formats of settings files that are imported by default */
+var SETTINGS_FILE_FORMATS = [SETTINGS_FILE_FORMAT];
+/** The version of the settings file format */
+var SETTINGS_FILE_VERSION = 1;
+/** Longest settings file format name (characters) */
+var MAX_SETTINGS_FILE_FORMAT_LENGTH = 100;
+/** Most keyboard shortcuts in saved settings */
+var MAX_SAVED_SHORTCUTS = 200;
+/** A `#rrggbb` colour */
+var hexColour = {
+	type: "string",
+	pattern: HEX_COLOUR_PATTERN
+};
+/** Schema of a key combination */
+var keyComboSchema = {
+	$id: "paintcanvas/key-combo",
+	type: "object",
+	additionalProperties: false,
+	required: ["key"],
+	properties: {
+		key: {
+			type: "string",
+			minLength: 1,
+			maxLength: 32
+		},
+		cmd: { type: "boolean" },
+		ctrl: { type: "boolean" },
+		shift: { type: "boolean" },
+		alt: { type: "boolean" }
+	}
+};
+/** Schema of the user's app settings */
+var settingsSchema = {
+	$id: "paintcanvas/settings",
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		input: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				scrollPan: { type: "boolean" },
+				pinchZoom: { type: "boolean" },
+				modifierScrollZoom: { type: "boolean" },
+				focusPen: { type: "boolean" },
+				gestures: {
+					type: "object",
+					maxProperties: 20,
+					additionalProperties: {
+						type: "string",
+						maxLength: 50
+					}
+				}
+			}
+		},
+		shortcuts: {
+			type: "object",
+			maxProperties: 200,
+			propertyNames: { maxLength: 64 },
+			additionalProperties: { anyOf: [{ type: "null" }, { $ref: "key-combo" }] }
+		},
+		palette: {
+			type: "array",
+			maxItems: MAX_PALETTE_COLOURS,
+			items: paletteFileSchema.properties.colours.items
+		},
+		colours: {
+			type: "object",
+			additionalProperties: false,
+			required: ["foreground", "background"],
+			properties: {
+				foreground: hexColour,
+				background: hexColour
+			}
+		},
+		ui: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				theme: { enum: THEMES },
+				locale: {
+					type: "string",
+					minLength: 1,
+					maxLength: 35,
+					pattern: LOCALE_PATTERN
+				}
+			}
+		}
+	}
+};
+/** Schema of a settings file */
+var settingsFileSchema = {
+	$id: "paintcanvas/settings-file",
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"format",
+		"version",
+		"settings"
+	],
+	properties: {
+		format: {
+			type: "string",
+			minLength: 1,
+			maxLength: 100
+		},
+		version: { const: 1 },
+		settings: { $ref: "settings" }
+	}
+};
+export { MAX_SAVED_SHORTCUTS, MAX_SETTINGS_FILE_FORMAT_LENGTH, SETTINGS_FILE_FORMAT, SETTINGS_FILE_FORMATS, SETTINGS_FILE_VERSION, keyComboSchema, settingsFileSchema, settingsSchema };

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

@@ -1,8 +1,11 @@
 import type { LayerConfig } from "../classes/Layer";
+import type { AppSettings } from "../settings/schema";
 /** Version of a saved drawing's shape, so drawings saved by other versions can be recognised */
 export declare const SAVED_DRAWING_VERSION = 1;
-/** Name of the IndexedDB database `IndexedDbLayerStore` keeps drawings in */
+/** Name of the IndexedDB database `IndexedDbLayerStore` keeps drawings in, and `IndexedDbSettingsStore` settings */
 export declare const DATABASE_NAME = "paintcanvas";
+/** Version of the database's object stores (2 added settings) */
+export declare const DATABASE_VERSION = 2;
 /** A saved layer's settings (its pixels are kept separately, as a PNG) */
 export type SavedLayer = Required<LayerConfig>;
 /** A saved drawing: its size, its layers (top first) without their pixels, and the selected layer */
@@ -43,8 +46,7 @@ export interface LayerStoreLike {
  */
 export default class IndexedDbLayerStore implements LayerStoreLike {
     readonly name: string;
-    private readonly factory;
-    private database?;
+    private readonly connection;
     /**
      * @param name - the drawing's name
      * @param factory - the IndexedDB to use (the browser's by default)
@@ -54,10 +56,39 @@ export default class IndexedDbLayerStore implements LayerStoreLike {
     save(drawing: SavedDrawing, images: ReadonlyMap<string, Blob>): Promise<void>;
     clear(): Promise<void>;
     /**
-     * Open the database (once), creating its object stores the first time. If it can't be opened, the next call tries
-     * again.
+     * Open the database (once). If it can't be opened, the next call tries again.
      */
     private open;
     /** The keys of this drawing's layer images: `[name, layerId]` (arrays sort after strings) */
     private imageKeys;
 }
+/** Where the user's app settings are kept (see `IndexedDbSettingsStore`) */
+export interface SettingsStoreLike {
+    /** The settings' name, e.g. to keep settings for different apps apart */
+    readonly name: string;
+    /** The saved settings (untrusted: check them before using them), or undefined if none were saved */
+    load(): Promise<unknown>;
+    /** Save the settings */
+    save(settings: AppSettings): Promise<void>;
+}
+/** Name the app settings are kept under when none is given */
+export declare const DEFAULT_SETTINGS_NAME = "default";
+/**
+ * Keeps the user's app settings (see `AppSettings`) in the browser's IndexedDB database (`DATABASE_NAME`), under a
+ * name.
+ *
+ * @example
+ * const store = new IndexedDbSettingsStore();
+ * await store.save(collectSettings(canvas));
+ */
+export declare class IndexedDbSettingsStore implements SettingsStoreLike {
+    readonly name: string;
+    private readonly connection;
+    /**
+     * @param name - the settings' name (`DEFAULT_SETTINGS_NAME` by default)
+     * @param factory - the IndexedDB to use (the browser's by default)
+     */
+    constructor(name?: string, factory?: IDBFactory);
+    load(): Promise<unknown>;
+    save(settings: AppSettings): Promise<void>;
+}

package/dist/lib/storage/index.js

@@ -1,14 +1,22 @@
 // src/lib/storage/index.ts
 /** Version of a saved drawing's shape, so drawings saved by other versions can be recognised */
 var SAVED_DRAWING_VERSION = 1;
-/** Name of the IndexedDB database `IndexedDbLayerStore` keeps drawings in */
+/** Name of the IndexedDB database `IndexedDbLayerStore` keeps drawings in, and `IndexedDbSettingsStore` settings */
 var DATABASE_NAME = "paintcanvas";
-/** Version of the database's object stores */
-var DATABASE_VERSION = 1;
+/** Version of the database's object stores (2 added settings) */
+var DATABASE_VERSION = 2;
 /** Object store of saved drawings, by name */
 var DRAWINGS = "drawings";
 /** Object store of layer images (PNG blobs), by drawing name and layer ID */
 var IMAGES = "images";
+/** Object store of app settings, by name */
+var SETTINGS = "settings";
+/** Every object store, created when the database is first opened or upgraded */
+var OBJECT_STORES = [
+	DRAWINGS,
+	IMAGES,
+	SETTINGS
+];
 /**
 * Wait for an IndexedDB request's result.
 */
@@ -24,6 +32,46 @@ var completed = (transaction) => new Promise((resolve, reject) => {
 	transaction.onabort = () => reject(transaction.error ?? /* @__PURE__ */ new Error("Transaction aborted"));
 });
 /**
+* Open PaintCanvas's database, creating the object stores it doesn't have yet. When another window upgrades the
+* database, this connection closes and `onClose` is called, so the next use opens it again.
+*/
+var openDatabase = (factory, onClose) => new Promise((resolve, reject) => {
+	const request = factory.open(DATABASE_NAME, 2);
+	request.onupgradeneeded = () => {
+		const database = request.result;
+		for (const store of OBJECT_STORES) if (!database.objectStoreNames.contains(store)) database.createObjectStore(store);
+	};
+	request.onsuccess = () => {
+		const database = request.result;
+		database.onversionchange = () => {
+			database.close();
+			onClose();
+		};
+		resolve(database);
+	};
+	request.onerror = () => reject(request.error);
+});
+/**
+* Opens PaintCanvas's database once and keeps the connection, opening it again if it closes or fails to open.
+*/
+var DatabaseConnection = class {
+	factory;
+	database;
+	constructor(factory) {
+		this.factory = factory;
+	}
+	/** The open database */
+	open() {
+		this.database ??= openDatabase(this.factory, () => {
+			this.database = void 0;
+		}).catch((error) => {
+			this.database = void 0;
+			throw error;
+		});
+		return this.database;
+	}
+};
+/**
 * The layer ID in a layer image's key (`[name, layerId]`).
 */
 var layerIdOf = (key) => key[1];
@@ -36,15 +84,14 @@ var layerIdOf = (key) => key[1];
 */
 var IndexedDbLayerStore = class {
 	name;
-	factory;
-	database;
+	connection;
 	/**
 	* @param name - the drawing's name
 	* @param factory - the IndexedDB to use (the browser's by default)
 	*/
 	constructor(name, factory = indexedDB) {
 		this.name = name;
-		this.factory = factory;
+		this.connection = new DatabaseConnection(factory);
 	}
 	async load() {
 		const transaction = (await this.open()).transaction([DRAWINGS, IMAGES], "readonly");
@@ -81,34 +128,45 @@ var IndexedDbLayerStore = class {
 		await done;
 	}
 	/**
-	* Open the database (once), creating its object stores the first time. If it can't be opened, the next call tries
-	* again.
+	* Open the database (once). If it can't be opened, the next call tries again.
 	*/
 	open() {
-		this.database ??= new Promise((resolve, reject) => {
-			const request = this.factory.open(DATABASE_NAME, DATABASE_VERSION);
-			request.onupgradeneeded = () => {
-				request.result.createObjectStore(DRAWINGS);
-				request.result.createObjectStore(IMAGES);
-			};
-			request.onsuccess = () => {
-				const database = request.result;
-				database.onversionchange = () => {
-					database.close();
-					this.database = void 0;
-				};
-				resolve(database);
-			};
-			request.onerror = () => {
-				this.database = void 0;
-				reject(request.error);
-			};
-		});
-		return this.database;
+		return this.connection.open();
 	}
 	/** The keys of this drawing's layer images: `[name, layerId]` (arrays sort after strings) */
 	imageKeys() {
 		return IDBKeyRange.bound([this.name], [this.name, []]);
 	}
 };
-export { DATABASE_NAME, SAVED_DRAWING_VERSION, IndexedDbLayerStore as default };
+/** Name the app settings are kept under when none is given */
+var DEFAULT_SETTINGS_NAME = "default";
+/**
+* Keeps the user's app settings (see `AppSettings`) in the browser's IndexedDB database (`DATABASE_NAME`), under a
+* name.
+*
+* @example
+* const store = new IndexedDbSettingsStore();
+* await store.save(collectSettings(canvas));
+*/
+var IndexedDbSettingsStore = class {
+	name;
+	connection;
+	/**
+	* @param name - the settings' name (`DEFAULT_SETTINGS_NAME` by default)
+	* @param factory - the IndexedDB to use (the browser's by default)
+	*/
+	constructor(name = DEFAULT_SETTINGS_NAME, factory = indexedDB) {
+		this.name = name;
+		this.connection = new DatabaseConnection(factory);
+	}
+	async load() {
+		return result((await this.connection.open()).transaction(SETTINGS, "readonly").objectStore(SETTINGS).get(this.name));
+	}
+	async save(settings) {
+		const transaction = (await this.connection.open()).transaction(SETTINGS, "readwrite");
+		const done = completed(transaction);
+		transaction.objectStore(SETTINGS).put(settings, this.name);
+		await done;
+	}
+};
+export { DATABASE_NAME, DATABASE_VERSION, DEFAULT_SETTINGS_NAME, IndexedDbSettingsStore, SAVED_DRAWING_VERSION, IndexedDbLayerStore as default };

package/dist/lib/utils/colour/index.d.ts

@@ -0,0 +1,72 @@
+/** A colour's red, green and blue channels, each from 0 to 255 */
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/** A colour's hue (0–360 degrees), saturation (0–100%) and lightness (0–100%) */
+export interface Hsl {
+    h: number;
+    s: number;
+    l: number;
+}
+/**
+ * Check that a value is a 6-digit hex colour, e.g. `#ff0000`.
+ *
+ * @example
+ * isHexColour("#FF00aa"); // true
+ * isHexColour("red"); // false
+ */
+export declare const isHexColour: (value: unknown) => value is string;
+/**
+ * Turn a hex colour as typed (3 or 6 digits, with or without `#`, any case) into `#rrggbb`. Undefined if it isn't one.
+ *
+ * @example
+ * normaliseHex("F0a"); // "#ff00aa"
+ * normaliseHex(" #123456 "); // "#123456"
+ * normaliseHex("#12345"); // undefined
+ */
+export declare const normaliseHex: (input: string) => string | undefined;
+/**
+ * The red, green and blue channels of a `#rrggbb` colour.
+ *
+ * @example
+ * hexToRgb("#ff8000"); // { r: 255, g: 128, b: 0 }
+ */
+export declare const hexToRgb: (hex: string) => Rgb;
+/**
+ * Format red, green and blue channels as `#rrggbb`, rounding and keeping each from 0 to 255.
+ *
+ * @example
+ * rgbToHex({ r: 255, g: 127.6, b: -3 }); // "#ff8000"
+ */
+export declare const rgbToHex: ({ r, g, b }: Rgb) => string;
+/**
+ * Convert red, green and blue channels to hue, saturation and lightness, rounded to whole numbers. Greys have hue 0.
+ *
+ * @example
+ * rgbToHsl({ r: 255, g: 0, b: 0 }); // { h: 0, s: 100, l: 50 }
+ */
+export declare const rgbToHsl: ({ r, g, b }: Rgb) => Hsl;
+/**
+ * Convert hue (degrees, wrapped to 0–360), saturation and lightness (percentages, kept from 0 to 100) to red, green and
+ * blue channels, rounded to whole numbers.
+ *
+ * @example
+ * hslToRgb({ h: 120, s: 100, l: 25 }); // { r: 0, g: 128, b: 0 }
+ */
+export declare const hslToRgb: ({ h, s, l }: Hsl) => Rgb;
+/**
+ * Convert a `#rrggbb` colour to hue, saturation and lightness.
+ *
+ * @example
+ * hexToHsl("#ff0000"); // { h: 0, s: 100, l: 50 }
+ */
+export declare const hexToHsl: (hex: string) => Hsl;
+/**
+ * Convert hue, saturation and lightness to a `#rrggbb` colour.
+ *
+ * @example
+ * hslToHex({ h: 240, s: 100, l: 50 }); // "#0000ff"
+ */
+export declare const hslToHex: (hsl: Hsl) => string;

package/dist/lib/utils/colour/index.js

@@ -0,0 +1,154 @@
+// src/lib/utils/colour/index.ts
+/** Pattern for `#rrggbb` colours */
+var HEX_PATTERN = /^#[0-9a-f]{6}$/i;
+/** Pattern for hex colours as people type them: 3 or 6 digits, with or without `#` */
+var HEX_INPUT_PATTERN = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;
+/**
+* Keep a number within a range.
+*
+* @example
+* clamp(300, 0, 255); // 255
+*/
+var clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/**
+* Check that a value is a 6-digit hex colour, e.g. `#ff0000`.
+*
+* @example
+* isHexColour("#FF00aa"); // true
+* isHexColour("red"); // false
+*/
+var isHexColour = (value) => typeof value === "string" && HEX_PATTERN.test(value);
+/**
+* Turn a hex colour as typed (3 or 6 digits, with or without `#`, any case) into `#rrggbb`. Undefined if it isn't one.
+*
+* @example
+* normaliseHex("F0a"); // "#ff00aa"
+* normaliseHex(" #123456 "); // "#123456"
+* normaliseHex("#12345"); // undefined
+*/
+var normaliseHex = (input) => {
+	const digits = HEX_INPUT_PATTERN.exec(input.trim())?.[1];
+	if (!digits) return void 0;
+	return `#${(digits.length === 3 ? [...digits].map((digit) => digit + digit).join("") : digits).toLowerCase()}`;
+};
+/**
+* The red, green and blue channels of a `#rrggbb` colour.
+*
+* @example
+* hexToRgb("#ff8000"); // { r: 255, g: 128, b: 0 }
+*/
+var hexToRgb = (hex) => {
+	const value = Number.parseInt(hex.slice(1), 16);
+	return {
+		r: value >> 16 & 255,
+		g: value >> 8 & 255,
+		b: value & 255
+	};
+};
+/**
+* Format red, green and blue channels as `#rrggbb`, rounding and keeping each from 0 to 255.
+*
+* @example
+* rgbToHex({ r: 255, g: 127.6, b: -3 }); // "#ff8000"
+*/
+var rgbToHex = ({ r, g, b }) => `#${[
+	r,
+	g,
+	b
+].map((channel) => Math.round(clamp(channel, 0, 255)).toString(16).padStart(2, "0")).join("")}`;
+/**
+* Convert red, green and blue channels to hue, saturation and lightness, rounded to whole numbers. Greys have hue 0.
+*
+* @example
+* rgbToHsl({ r: 255, g: 0, b: 0 }); // { h: 0, s: 100, l: 50 }
+*/
+var rgbToHsl = ({ r, g, b }) => {
+	const [red, green, blue] = [
+		r,
+		g,
+		b
+	].map((channel) => channel / 255);
+	const max = Math.max(red, green, blue);
+	const min = Math.min(red, green, blue);
+	const lightness = (max + min) / 2;
+	const range = max - min;
+	if (range === 0) return {
+		h: 0,
+		s: 0,
+		l: Math.round(lightness * 100)
+	};
+	const saturation = range / (1 - Math.abs(2 * lightness - 1));
+	const hue = max === red ? ((green - blue) / range + 6) % 6 : max === green ? (blue - red) / range + 2 : (red - green) / range + 4;
+	return {
+		h: Math.round(hue * 60) % 360,
+		s: Math.round(saturation * 100),
+		l: Math.round(lightness * 100)
+	};
+};
+/**
+* Convert hue (degrees, wrapped to 0–360), saturation and lightness (percentages, kept from 0 to 100) to red, green and
+* blue channels, rounded to whole numbers.
+*
+* @example
+* hslToRgb({ h: 120, s: 100, l: 25 }); // { r: 0, g: 128, b: 0 }
+*/
+var hslToRgb = ({ h, s, l }) => {
+	const hue = (h % 360 + 360) % 360 / 60;
+	const saturation = clamp(s, 0, 100) / 100;
+	const lightness = clamp(l, 0, 100) / 100;
+	const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
+	const second = chroma * (1 - Math.abs(hue % 2 - 1));
+	const [red, green, blue] = [
+		[
+			chroma,
+			second,
+			0
+		],
+		[
+			second,
+			chroma,
+			0
+		],
+		[
+			0,
+			chroma,
+			second
+		],
+		[
+			0,
+			second,
+			chroma
+		],
+		[
+			second,
+			0,
+			chroma
+		],
+		[
+			chroma,
+			0,
+			second
+		]
+	][Math.floor(hue)];
+	const match = lightness - chroma / 2;
+	return {
+		r: Math.round((red + match) * 255),
+		g: Math.round((green + match) * 255),
+		b: Math.round((blue + match) * 255)
+	};
+};
+/**
+* Convert a `#rrggbb` colour to hue, saturation and lightness.
+*
+* @example
+* hexToHsl("#ff0000"); // { h: 0, s: 100, l: 50 }
+*/
+var hexToHsl = (hex) => rgbToHsl(hexToRgb(hex));
+/**
+* Convert hue, saturation and lightness to a `#rrggbb` colour.
+*
+* @example
+* hslToHex({ h: 240, s: 100, l: 50 }); // "#0000ff"
+*/
+var hslToHex = (hsl) => rgbToHex(hslToRgb(hsl));
+export { hexToHsl, hexToRgb, hslToHex, hslToRgb, isHexColour, normaliseHex, rgbToHex, rgbToHsl };