@lvl99dotcom/paintcanvas 0.7.0 → 0.8.0

package/dist/lib/settings/index.js

@@ -1,14 +1,10 @@
-import { formatErrors } from "../presets/index.js";
-import { validateSettings, validateSettingsFile } from "../validation/validators.generated.js";
-import { MAX_SAVED_SHORTCUTS, MAX_SETTINGS_FILE_FORMAT_LENGTH, SETTINGS_FILE_FORMAT, SETTINGS_FILE_FORMATS, SETTINGS_FILE_VERSION, keyComboSchema, settingsFileSchema, settingsSchema } from "./schema.js";
+import { formatErrors, isValidBrushPreset } from "../presets/index.js";
+import { validateAppSettings, validateSettings } from "../validation/validators.generated.js";
+import { AssetFileError } from "../assets/index.js";
+import { compareVersions, majorVersion, parseSchemaUrl } from "../schemas/index.js";
+import { sanitisePalette } from "../classes/Palette/index.js";
+import { APP_SETTINGS_SCHEMA_VERSION, APP_SETTINGS_TYPE, MAX_SAVED_SHORTCUTS, appSettingsSchema, keyComboSchema, settingsSchema } from "./schema.js";
 // src/lib/settings/index.ts
-/** Messages shown when importing settings fails */
-var SETTINGS_FILE_ERRORS = {
-	incompatible: "Settings JSON file not compatible",
-	read: "Failed to read settings JSON file"
-};
-/** Importing settings failed, with a message for the user */
-var SettingsFileError = class extends Error {};
 /**
 * Check app settings (e.g. kept in the browser) against `settingsSchema`.
 *
@@ -23,37 +19,62 @@ var isValidSettings = (input) => validateSettings(input) ? {
 	errors: formatErrors(validateSettings.errors)
 };
 /**
-* The app settings of a canvas: its input settings, keyboard shortcuts, colour palette, colours, profile graphs, theme
-* and language.
+* The app settings of a canvas: its input settings, keyboard shortcuts, colours, the user's colour palettes, profile
+* graphs and brush presets, theme and language, and settings wrapper apps added (see `SettingsExtension`).
 *
 * @example
-* collectSettings(canvas).palette; // ["#2c6bff", ...]
+* collectSettings(canvas).palettes; // the user's own palettes
+* collectSettings(canvas, { without: ["profiles"] }).profiles; // undefined
 */
-var collectSettings = (app) => ({
+var collectSettings = (app, { without = [] } = {}) => ({
 	input: structuredClone(app.input.data),
 	shortcuts: structuredClone(app.shortcuts.bindings),
-	palette: [...app.palette.colours],
+	...without.includes("palettes") ? {} : { palettes: structuredClone([...app.palettes.items]) },
 	colours: { ...app.colours },
-	profiles: structuredClone([...app.profiles.graphs]),
-	ui: { ...app.ui.data }
+	...without.includes("profiles") ? {} : { profiles: structuredClone([...app.profiles.graphs]) },
+	...without.includes("brushes") ? {} : { brushes: structuredClone(app.customPresets.presets) },
+	ui: { ...app.ui.data },
+	...structuredClone(app.settingsExtensions.collect())
 });
+/** Name of the palette that colours saved in PaintCanvas's palette by older versions are moved to */
+var OLDER_PALETTE_NAME = "My colours";
+/**
+* Keep colours that older versions saved in PaintCanvas's palette (which can no longer be changed) in a palette of the
+* user's own, named `OLDER_PALETTE_NAME`: unless they're PaintCanvas's colours, or one of the user's palettes already has
+* them.
+*
+* @example
+* keepOlderPalette(canvas, ["#123456"]); // the user now has a "My colours" palette with #123456
+*/
+var keepOlderPalette = (app, colours) => {
+	const valid = sanitisePalette(colours) ?? [];
+	const same = (other) => other.length === valid.length && other.every((colour, i) => colour === valid[i]);
+	if (valid.length === 0 || same(app.palette.colours) || app.palettes.items.some((palette) => same(palette.colours))) return;
+	app.palettes.create(OLDER_PALETTE_NAME, valid, app.author);
+};
 /**
 * Use app settings on a canvas, e.g. ones kept in the browser or imported. Parts left out stay as they are; invalid
-* values within a part are left out (see each part's sanitising).
+* values within a part are left out (see each part's sanitising). Colour palettes, profile graphs and brush presets are
+* added to the user's own, replacing those with the same IDs. Colours older versions saved in PaintCanvas's palette are
+* moved to one of the user's own (see `keepOlderPalette`). Other parts go to the settings extensions (see
+* `SettingsExtensions.apply`).
 *
 * @example
-* applySettings(canvas, { colours: { foreground: "#ff0000", background: "#ffffff" } });
+* await applySettings(canvas, { colours: { foreground: "#ff0000", background: "#ffffff" } });
 */
-var applySettings = (app, settings) => {
+var applySettings = async (app, settings) => {
 	if (settings.input) app.input.update(settings.input);
 	if (settings.shortcuts) app.shortcuts.load(settings.shortcuts);
-	if (settings.palette) app.palette.set(settings.palette);
+	if (settings.palette) keepOlderPalette(app, settings.palette);
+	if (settings.palettes) app.palettes.merge(settings.palettes);
 	if (settings.colours) {
 		app.setColour(settings.colours.foreground, "foreground");
 		app.setColour(settings.colours.background, "background");
 	}
-	if (settings.profiles) app.profiles.set(settings.profiles);
+	if (settings.profiles) app.profiles.merge(settings.profiles);
 	if (settings.ui) app.ui.update(settings.ui);
+	app.settingsExtensions.apply(settings);
+	if (Array.isArray(settings.brushes)) await app.customPresets.save(...settings.brushes.filter((preset) => isValidBrushPreset(preset).valid));
 };
 /**
 * The file name settings are exported to on a day, starting with a prefix (see `PaintCanvasNames.filePrefix`).
@@ -66,31 +87,51 @@ var settingsFileName = (date = /* @__PURE__ */ new Date(), prefix = "paintcanvas
 	return `${prefix}-settings-${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}.json`;
 };
 /**
-* Write app settings to a settings file (JSON) of a format (see `PaintCanvasNames.settingsFileFormat`).
+* Write app settings to an app settings file (JSON). Colours older versions saved in PaintCanvas's palette are left out.
 *
 * @example
-* exportSettingsFile(collectSettings(canvas)); // '{ "format": "paintcanvas-settings", "version": 1, "settings": {...} }'
+* exportSettingsFile(collectSettings(canvas)); // '{ "$schema": ".../app-settings-1.0.0.json", "@type": "PaintCanvas/AppSettings", ... }'
 */
-var exportSettingsFile = (settings, format = SETTINGS_FILE_FORMAT) => JSON.stringify({
-	format,
-	version: 1,
-	settings
-}, null, 2);
+var exportSettingsFile = (settings) => {
+	const parts = { ...settings };
+	delete parts.palette;
+	const file = {
+		$schema: appSettingsSchema.$id,
+		"@type": APP_SETTINGS_TYPE,
+		...parts
+	};
+	return JSON.stringify(file, null, 2);
+};
+/** Whether a value is a plain object */
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
-* Read the app settings in a settings file of one of the given formats (PaintCanvas's by default). Throws a
-* `SettingsFileError` if it isn't valid JSON or a compatible file.
+* Read the app settings in an app settings file. Settings files from before versioned schemas (`format`, `version: 1`
+* and `settings`, of any format name) are read too. Throws an `AssetFileError`: `read` if it isn't JSON, `invalid` if it
+* isn't a settings file or doesn't match its schema, `unsupported` if it's a version the app can't read.
 *
 * @example
-* applySettings(canvas, parseSettingsFile(text));
+* await applySettings(canvas, parseSettingsFile(text));
 */
-var parseSettingsFile = (text, formats = SETTINGS_FILE_FORMATS) => {
+var parseSettingsFile = (text) => {
 	let data;
 	try {
 		data = JSON.parse(text);
 	} catch {
-		throw new SettingsFileError(SETTINGS_FILE_ERRORS.incompatible);
+		throw new AssetFileError("read");
+	}
+	if (!isRecord(data)) throw new AssetFileError("invalid");
+	if (typeof data.format === "string" && data.version === 1) {
+		const result = isValidSettings(data.settings);
+		if (!result.valid) throw new AssetFileError("invalid");
+		return result.value;
 	}
-	if (!validateSettingsFile(data) || !formats.includes(data.format)) throw new SettingsFileError(SETTINGS_FILE_ERRORS.incompatible);
-	return data.settings;
+	const named = parseSchemaUrl(data.$schema);
+	if (named?.name !== "app-settings") throw new AssetFileError("invalid");
+	if (majorVersion(named.version) !== majorVersion("1.0.0") || compareVersions(named.version, "1.0.0") > 0) throw new AssetFileError("unsupported");
+	if (!validateAppSettings(data)) throw new AssetFileError("invalid");
+	const settings = { ...data };
+	delete settings.$schema;
+	delete settings["@type"];
+	return settings;
 };
-export { MAX_SAVED_SHORTCUTS, MAX_SETTINGS_FILE_FORMAT_LENGTH, SETTINGS_FILE_ERRORS, SETTINGS_FILE_FORMAT, SETTINGS_FILE_FORMATS, SETTINGS_FILE_VERSION, SettingsFileError, applySettings, collectSettings, exportSettingsFile, isValidSettings, keyComboSchema, parseSettingsFile, settingsFileName, settingsFileSchema, settingsSchema };
+export { APP_SETTINGS_SCHEMA_VERSION, APP_SETTINGS_TYPE, MAX_SAVED_SHORTCUTS, OLDER_PALETTE_NAME, appSettingsSchema, applySettings, collectSettings, exportSettingsFile, isValidSettings, keepOlderPalette, keyComboSchema, parseSettingsFile, settingsFileName, settingsSchema };

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

@@ -1,25 +1,31 @@
 import type { InputSettingsData } from "../classes/InputSettings";
 import { type UiSettingsData } from "../classes/UiSettings/index.ts";
 import type { KeyCombo } from "../utils/shortcuts";
+import { type ColourPalette } from "../palette/schema.ts";
 import type { ProfileGraph } from "../profiles/index.ts";
-/** The `format` of a settings file, unless the implementer names their own (see `PaintCanvasNames`) */
-export declare const SETTINGS_FILE_FORMAT = "paintcanvas-settings";
-/** Formats of settings files that are imported by default */
-export declare const SETTINGS_FILE_FORMATS: readonly string[];
-/** The version of the settings file format */
-export declare const SETTINGS_FILE_VERSION = 1;
-/** Longest settings file format name (characters) */
-export declare const MAX_SETTINGS_FILE_FORMAT_LENGTH = 100;
+import type { BrushConfig } from "../brushes/types/index.ts";
+/** Version of the app settings schema */
+export declare const APP_SETTINGS_SCHEMA_VERSION = "1.0.0";
+/** `@type` of an app settings file */
+export declare const APP_SETTINGS_TYPE = "PaintCanvas/AppSettings";
 /** Most keyboard shortcuts in saved settings */
 export declare const MAX_SAVED_SHORTCUTS = 200;
-/** The user's app settings. Each part is optional, so a file can hold only some of them. */
+/**
+ * The user's app settings. Each part is optional, so a file can hold only some of them. Wrapper apps add their own
+ * parts under keys of their own (see `SettingsExtension`).
+ */
 export interface AppSettings {
     /** How input devices control the canvas */
     input?: Partial<InputSettingsData>;
     /** Each configurable keyboard shortcut action's key combination, by ID (null when it has none) */
     shortcuts?: Record<string, KeyCombo | null>;
-    /** The colour palette's colours, as `#rrggbb` */
+    /**
+     * Colours saved in PaintCanvas's palette by older versions, as `#rrggbb` (no longer saved: applying them moves them
+     * to one of the user's palettes, see `keepOlderPalette`)
+     */
     palette?: string[];
+    /** The user's own colour palettes */
+    palettes?: ColourPalette[];
     /** The foreground and background colours, as `#rrggbb` */
     colours?: {
         foreground: string;
@@ -27,19 +33,21 @@ export interface AppSettings {
     };
     /** The user's own profile graphs */
     profiles?: ProfileGraph[];
+    /** The user's own and imported brush presets */
+    brushes?: BrushConfig[];
     /** The theme, language and where canvases draw */
     ui?: Partial<UiSettingsData>;
+    /** Parts added by wrapper apps, by their keys */
+    [extension: string]: unknown;
 }
-/** A settings file: what users export and import */
-export interface SettingsFile {
-    /** Names the app or kind of file, e.g. `SETTINGS_FILE_FORMAT` */
-    format: string;
-    version: typeof SETTINGS_FILE_VERSION;
-    settings: AppSettings;
-}
+/** An app settings file: what users export and import */
+export type AppSettingsFile = Omit<AppSettings, "palette"> & {
+    /** URL of the schema, which names its version */
+    $schema: string;
+    "@type": typeof APP_SETTINGS_TYPE;
+};
 /** Schema of a key combination */
 export declare const keyComboSchema: {
-    readonly $id: "paintcanvas/key-combo";
     readonly type: "object";
     readonly additionalProperties: false;
     readonly required: readonly ["key"];
@@ -63,12 +71,22 @@ export declare const keyComboSchema: {
         };
     };
 };
-/** Schema of the user's app settings */
+/**
+ * Schema of the user's app settings as kept in the browser: parts PaintCanvas doesn't know are left for wrapper apps
+ * to check (see `SettingsExtension`), and colours older versions saved in PaintCanvas's palette (`palette`) are allowed.
+ */
 export declare const settingsSchema: {
     readonly $id: "paintcanvas/settings";
     readonly type: "object";
-    readonly additionalProperties: false;
     readonly properties: {
+        readonly palette: {
+            readonly type: "array";
+            readonly maxItems: 1000;
+            readonly items: {
+                readonly type: "string";
+                readonly pattern: "^#[0-9a-fA-F]{6}$";
+            };
+        };
         readonly input: {
             readonly type: "object";
             readonly additionalProperties: false;
@@ -105,16 +123,36 @@ export declare const settingsSchema: {
                 readonly anyOf: readonly [{
                     readonly type: "null";
                 }, {
-                    readonly $ref: "key-combo";
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["key"];
+                    readonly properties: {
+                        readonly key: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 32;
+                        };
+                        readonly cmd: {
+                            readonly type: "boolean";
+                        };
+                        readonly ctrl: {
+                            readonly type: "boolean";
+                        };
+                        readonly shift: {
+                            readonly type: "boolean";
+                        };
+                        readonly alt: {
+                            readonly type: "boolean";
+                        };
+                    };
                 }];
             };
         };
-        readonly palette: {
+        readonly palettes: {
             readonly type: "array";
-            readonly maxItems: 1000;
+            readonly maxItems: 100;
             readonly items: {
-                readonly type: "string";
-                readonly pattern: "^#[0-9a-fA-F]{6}$";
+                readonly $ref: string;
             };
         };
         readonly colours: {
@@ -136,48 +174,144 @@ export declare const settingsSchema: {
             readonly type: "array";
             readonly maxItems: 100;
             readonly items: {
-                readonly type: "object";
-                readonly additionalProperties: false;
-                readonly required: readonly ["id", "name", "points"];
-                readonly properties: {
-                    readonly id: {
-                        readonly type: "string";
-                        readonly minLength: 1;
-                        readonly maxLength: 100;
-                    };
-                    readonly name: {
+                readonly $ref: string;
+            };
+        };
+        readonly brushes: {
+            readonly type: "array";
+            readonly maxItems: 1000;
+            readonly items: {
+                readonly $ref: string;
+            };
+        };
+        readonly ui: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly theme: {
+                    readonly enum: readonly ["light", "dark", "system"];
+                };
+                readonly locale: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 35;
+                    readonly pattern: "^[A-Za-z0-9-]+$";
+                };
+                readonly rendering: {
+                    readonly enum: readonly ["cpu", "gpu"];
+                };
+            };
+        };
+    };
+};
+/**
+ * Schema of an app settings file. Parts it doesn't name are added by wrapper apps, which check them (see
+ * `SettingsExtension`), and can publish schemas of their own that extend this one.
+ */
+export declare const appSettingsSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: string;
+    readonly "@type": "PaintCanvas/AppSettings";
+    readonly type: "object";
+    readonly required: readonly ["$schema", "@type"];
+    readonly properties: {
+        readonly input: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly scrollPan: {
+                    readonly type: "boolean";
+                };
+                readonly pinchZoom: {
+                    readonly type: "boolean";
+                };
+                readonly modifierScrollZoom: {
+                    readonly type: "boolean";
+                };
+                readonly focusPen: {
+                    readonly type: "boolean";
+                };
+                readonly gestures: {
+                    readonly type: "object";
+                    readonly maxProperties: 20;
+                    readonly additionalProperties: {
                         readonly type: "string";
-                        readonly minLength: 1;
-                        readonly maxLength: 100;
+                        readonly maxLength: 50;
                     };
-                    readonly points: {
-                        readonly type: "array";
-                        readonly minItems: 2;
-                        readonly maxItems: 32;
-                        readonly items: {
-                            readonly type: "object";
-                            readonly additionalProperties: false;
-                            readonly required: readonly ["x", "y", "i"];
-                            readonly properties: {
-                                readonly x: {
-                                    readonly type: "number";
-                                    readonly minimum: 0;
-                                    readonly maximum: 10;
-                                };
-                                readonly y: {
-                                    readonly type: "number";
-                                    readonly minimum: number;
-                                    readonly maximum: 0;
-                                };
-                                readonly i: {
-                                    readonly enum: ("linear" | "bezier-cubic")[];
-                                };
-                            };
+                };
+            };
+        };
+        readonly shortcuts: {
+            readonly type: "object";
+            readonly maxProperties: 200;
+            readonly propertyNames: {
+                readonly maxLength: 64;
+            };
+            readonly additionalProperties: {
+                readonly anyOf: readonly [{
+                    readonly type: "null";
+                }, {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["key"];
+                    readonly properties: {
+                        readonly key: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 32;
+                        };
+                        readonly cmd: {
+                            readonly type: "boolean";
+                        };
+                        readonly ctrl: {
+                            readonly type: "boolean";
+                        };
+                        readonly shift: {
+                            readonly type: "boolean";
+                        };
+                        readonly alt: {
+                            readonly type: "boolean";
                         };
                     };
+                }];
+            };
+        };
+        readonly palettes: {
+            readonly type: "array";
+            readonly maxItems: 100;
+            readonly items: {
+                readonly $ref: string;
+            };
+        };
+        readonly colours: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["foreground", "background"];
+            readonly properties: {
+                readonly foreground: {
+                    readonly type: "string";
+                    readonly pattern: "^#[0-9a-fA-F]{6}$";
+                };
+                readonly background: {
+                    readonly type: "string";
+                    readonly pattern: "^#[0-9a-fA-F]{6}$";
                 };
             };
         };
+        readonly profiles: {
+            readonly type: "array";
+            readonly maxItems: 100;
+            readonly items: {
+                readonly $ref: string;
+            };
+        };
+        readonly brushes: {
+            readonly type: "array";
+            readonly maxItems: 1000;
+            readonly items: {
+                readonly $ref: string;
+            };
+        };
         readonly ui: {
             readonly type: "object";
             readonly additionalProperties: false;
@@ -196,25 +330,13 @@ export declare const settingsSchema: {
                 };
             };
         };
-    };
-};
-/** Schema of a settings file */
-export declare const settingsFileSchema: {
-    readonly $id: "paintcanvas/settings-file";
-    readonly type: "object";
-    readonly additionalProperties: false;
-    readonly required: readonly ["format", "version", "settings"];
-    readonly properties: {
-        readonly format: {
+        readonly $schema: {
             readonly type: "string";
             readonly minLength: 1;
-            readonly maxLength: 100;
-        };
-        readonly version: {
-            readonly const: 1;
+            readonly maxLength: 2048;
         };
-        readonly settings: {
-            readonly $ref: "settings";
+        readonly "@type": {
+            readonly const: "PaintCanvas/AppSettings";
         };
     };
 };