@lvl99dotcom/paintcanvas 0.6.0 → 0.8.0

package/dist/lib/settings/schema.js

@@ -1,15 +1,14 @@
-import { LOCALE_PATTERN, THEMES } from "../classes/UiSettings/index.js";
-import { HEX_COLOUR_PATTERN, MAX_PALETTE_COLOURS, paletteFileSchema } from "../palette/schema.js";
+import { LOCALE_PATTERN, RENDERINGS, THEMES } from "../classes/UiSettings/index.js";
+import { HEX_COLOUR_PATTERN, colourPaletteSchema, paletteColoursSchema } from "../palette/schema.js";
 import { profileGraphSchema } from "../profiles/schema.js";
+import { MAX_PRESETS_PER_FILE, brushPresetSchema } from "../presets/schema.js";
+import { fileSchemaUrlSchema } from "../assets/schema.js";
+import { SCHEMA_DIALECT, schemaUrl } from "../schemas/index.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;
+/** Version of the app settings schema */
+var APP_SETTINGS_SCHEMA_VERSION = "1.0.0";
+/** `@type` of an app settings file */
+var APP_SETTINGS_TYPE = "PaintCanvas/AppSettings";
 /** Most keyboard shortcuts in saved settings */
 var MAX_SAVED_SHORTCUTS = 200;
 /** A `#rrggbb` colour */
@@ -19,7 +18,6 @@ var hexColour = {
 };
 /** Schema of a key combination */
 var keyComboSchema = {
-	$id: "paintcanvas/key-combo",
 	type: "object",
 	additionalProperties: false,
 	required: ["key"],
@@ -35,88 +33,97 @@ var keyComboSchema = {
 		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
-			}
-		},
-		profiles: {
-			type: "array",
-			maxItems: 100,
-			items: profileGraphSchema
-		},
-		ui: {
-			type: "object",
-			additionalProperties: false,
-			properties: {
-				theme: { enum: THEMES },
-				locale: {
+/** Schemas of each part of the app settings PaintCanvas has */
+var settingsProperties = {
+	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",
-					minLength: 1,
-					maxLength: 35,
-					pattern: LOCALE_PATTERN
+					maxLength: 50
 				}
 			}
 		}
+	},
+	shortcuts: {
+		type: "object",
+		maxProperties: 200,
+		propertyNames: { maxLength: 64 },
+		additionalProperties: { anyOf: [{ type: "null" }, keyComboSchema] }
+	},
+	palettes: {
+		type: "array",
+		maxItems: 100,
+		items: { $ref: colourPaletteSchema.$id }
+	},
+	colours: {
+		type: "object",
+		additionalProperties: false,
+		required: ["foreground", "background"],
+		properties: {
+			foreground: hexColour,
+			background: hexColour
+		}
+	},
+	profiles: {
+		type: "array",
+		maxItems: 100,
+		items: { $ref: profileGraphSchema.$id }
+	},
+	brushes: {
+		type: "array",
+		maxItems: MAX_PRESETS_PER_FILE,
+		items: { $ref: brushPresetSchema.$id }
+	},
+	ui: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			theme: { enum: THEMES },
+			locale: {
+				type: "string",
+				minLength: 1,
+				maxLength: 35,
+				pattern: LOCALE_PATTERN
+			},
+			rendering: { enum: RENDERINGS }
+		}
 	}
 };
-/** Schema of a settings file */
-var settingsFileSchema = {
-	$id: "paintcanvas/settings-file",
+/**
+* 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.
+*/
+var settingsSchema = {
+	$id: "paintcanvas/settings",
 	type: "object",
-	additionalProperties: false,
-	required: [
-		"format",
-		"version",
-		"settings"
-	],
 	properties: {
-		format: {
-			type: "string",
-			minLength: 1,
-			maxLength: 100
-		},
-		version: { const: 1 },
-		settings: { $ref: "settings" }
+		...settingsProperties,
+		palette: paletteColoursSchema
+	}
+};
+/**
+* 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.
+*/
+var appSettingsSchema = {
+	$schema: SCHEMA_DIALECT,
+	$id: schemaUrl("app-settings", APP_SETTINGS_SCHEMA_VERSION),
+	"@type": APP_SETTINGS_TYPE,
+	type: "object",
+	required: ["$schema", "@type"],
+	properties: {
+		$schema: fileSchemaUrlSchema,
+		"@type": { const: APP_SETTINGS_TYPE },
+		...settingsProperties
 	}
 };
-export { MAX_SAVED_SHORTCUTS, MAX_SETTINGS_FILE_FORMAT_LENGTH, SETTINGS_FILE_FORMAT, SETTINGS_FILE_FORMATS, SETTINGS_FILE_VERSION, keyComboSchema, settingsFileSchema, settingsSchema };
+export { APP_SETTINGS_SCHEMA_VERSION, APP_SETTINGS_TYPE, MAX_SAVED_SHORTCUTS, appSettingsSchema, keyComboSchema, settingsSchema };

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

@@ -1,17 +1,28 @@
 import type { LayerConfig } from "../classes/Layer";
 import type { AppSettings } from "../settings/schema";
+import type { BrushConfig } from "../brushes/types";
+import type { ColourPalette } from "../palette/schema";
+import type { ProfileGraph } from "../profiles";
+import type { DocumentInfo, DrawingDocument } from "../document/schema";
+import { type Rendering } from "../classes/UiSettings";
 /** 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, 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;
+/** Version of the database's object stores (2 added settings; 3 added brushes, palettes and profiles) */
+export declare const DATABASE_VERSION = 3;
+/** Kinds of asset kept in the database, each in its own object store, by settings name and asset ID */
+export declare const ASSET_KINDS: readonly ["brushes", "palettes", "profiles"];
+/** A kind of asset kept in the database */
+export type AssetKind = (typeof ASSET_KINDS)[number];
 /** 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 */
+/** A saved drawing: its details, size, its layers (top first) without their pixels, and the selected layer */
 export interface SavedDrawing {
     /** The shape's version (see `SAVED_DRAWING_VERSION`) */
     version: number;
+    /** The drawing's details (drawings saved by older versions have none) */
+    document?: DocumentInfo;
     width: number;
     height: number;
     layers: SavedLayer[];
@@ -92,3 +103,97 @@ export declare class IndexedDbSettingsStore implements SettingsStoreLike {
     load(): Promise<unknown>;
     save(settings: AppSettings): Promise<void>;
 }
+/** An asset: anything with an ID */
+export interface Asset {
+    id: string;
+}
+/** Where assets of one kind (e.g. brush presets) are kept (see `IndexedDbAssetStore`) */
+export interface AssetStoreLike<T extends Asset> {
+    /** The saved assets (untrusted: check them before using them), in the order they were first saved */
+    list(): Promise<unknown[]>;
+    /** Save an asset, replacing one with the same ID */
+    put(asset: T): Promise<void>;
+    /** Delete an asset */
+    remove(id: string): Promise<void>;
+}
+/**
+ * Keeps assets of one kind (e.g. brush presets) in the browser's IndexedDB database (`DATABASE_NAME`), under a name
+ * (like `IndexedDbSettingsStore`'s), each in its own record so saving one doesn't rewrite the others.
+ *
+ * @example
+ * const store = new IndexedDbAssetStore<BrushConfig>("brushes");
+ * await store.put(myPreset);
+ */
+export declare class IndexedDbAssetStore<T extends Asset> implements AssetStoreLike<T> {
+    readonly kind: AssetKind;
+    readonly name: string;
+    private readonly connection;
+    /**
+     * @param kind - the kind of asset
+     * @param name - the settings' name the assets belong to (`DEFAULT_SETTINGS_NAME` by default)
+     * @param factory - the IndexedDB to use (the browser's by default)
+     */
+    constructor(kind: AssetKind, name?: string, factory?: IDBFactory);
+    list(): Promise<unknown[]>;
+    put(asset: T): Promise<void>;
+    remove(id: string): Promise<void>;
+    /** The keys of this name's assets: `[name, id]` (arrays sort after strings) */
+    private keys;
+}
+/**
+ * Where whole documents are kept away from the browser, e.g. a user's account online (see `RemoteDocumentAutosave`).
+ * Saving can be slow, so it's done less often than keeping the drawing in the browser.
+ */
+export interface DocumentStoreLike {
+    /** Names the store for the user, e.g. "Bluesky" (shown while saving) */
+    readonly label?: string;
+    /**
+     * Save a document, replacing the one with the same ID. Call `onProgress` with how much is done (0 to 1), if known.
+     */
+    save(document: DrawingDocument, onProgress?: (done: number) => void): Promise<void>;
+    /** A saved document by ID, or undefined if there's none */
+    load(id: string): Promise<DrawingDocument | undefined>;
+}
+/** Where the user's assets are kept, by kind. Assets of a kind without a store are kept in memory only. */
+export interface AssetStores {
+    brushes?: AssetStoreLike<BrushConfig>;
+    palettes?: AssetStoreLike<ColourPalette>;
+    profiles?: AssetStoreLike<ProfileGraph>;
+}
+/** Where the user's settings and assets are kept */
+export interface PaintCanvasStores extends AssetStores {
+    settings?: SettingsStoreLike;
+}
+/**
+ * Stores keeping the user's settings and assets in the browser's IndexedDB database, under a name.
+ *
+ * @example
+ * const { settings, ...assets } = indexedDbStores("my-app");
+ * canvas.useAssetStores(assets);
+ */
+export declare const indexedDbStores: (name?: string, factory?: IDBFactory) => Required<PaintCanvasStores>;
+/**
+ * The browser storage key that keeps the rendering chosen with the app settings of a name (see
+ * `loadRenderingChoice`).
+ *
+ * @example
+ * renderingChoiceKey("demo"); // "paintcanvas-rendering:demo"
+ */
+export declare const renderingChoiceKey: (name: string) => string;
+/**
+ * The rendering (`cpu` or `gpu`) last chosen with the app settings of a name, kept in `localStorage` so it can be read
+ * before the canvas is made (the app settings themselves load later, from IndexedDB). Undefined when none was kept, it
+ * isn't valid, or the storage can't be read (e.g. blocked by the browser).
+ *
+ * @example
+ * new PaintCanvas({ rendering: loadRenderingChoice("demo") });
+ */
+export declare const loadRenderingChoice: (name?: string, storage?: Pick<Storage, "getItem"> | undefined) => Rendering | undefined;
+/**
+ * Keep the rendering chosen with the app settings of a name, to be read with `loadRenderingChoice` when the canvas is
+ * next made. Does nothing if the storage can't be written.
+ *
+ * @example
+ * canvas.ui.addEventListener("change", () => saveRenderingChoice("demo", canvas.ui.data.rendering));
+ */
+export declare const saveRenderingChoice: (name: string, rendering: Rendering, storage?: Pick<Storage, "setItem"> | undefined) => void;

package/dist/lib/storage/index.js

@@ -1,21 +1,29 @@
+import { isRendering } from "../classes/UiSettings/index.js";
 // 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, and `IndexedDbSettingsStore` settings */
 var DATABASE_NAME = "paintcanvas";
-/** Version of the database's object stores (2 added settings) */
-var DATABASE_VERSION = 2;
+/** Version of the database's object stores (2 added settings; 3 added brushes, palettes and profiles) */
+var DATABASE_VERSION = 3;
 /** 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";
+/** Kinds of asset kept in the database, each in its own object store, by settings name and asset ID */
+var ASSET_KINDS = [
+	"brushes",
+	"palettes",
+	"profiles"
+];
 /** Every object store, created when the database is first opened or upgraded */
 var OBJECT_STORES = [
 	DRAWINGS,
 	IMAGES,
-	SETTINGS
+	SETTINGS,
+	...ASSET_KINDS
 ];
 /**
 * Wait for an IndexedDB request's result.
@@ -36,7 +44,7 @@ var completed = (transaction) => new Promise((resolve, reject) => {
 * 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);
+	const request = factory.open(DATABASE_NAME, 3);
 	request.onupgradeneeded = () => {
 		const database = request.result;
 		for (const store of OBJECT_STORES) if (!database.objectStoreNames.contains(store)) database.createObjectStore(store);
@@ -169,4 +177,110 @@ var IndexedDbSettingsStore = class {
 		await done;
 	}
 };
-export { DATABASE_NAME, DATABASE_VERSION, DEFAULT_SETTINGS_NAME, IndexedDbSettingsStore, SAVED_DRAWING_VERSION, IndexedDbLayerStore as default };
+/** The order of the asset last saved for the first time */
+var lastOrder = 0;
+/**
+* The order of an asset saved for the first time: when it was saved, and always after the one before.
+*/
+var nextOrder = () => lastOrder = Math.max(Date.now(), lastOrder + 1);
+/**
+* Keeps assets of one kind (e.g. brush presets) in the browser's IndexedDB database (`DATABASE_NAME`), under a name
+* (like `IndexedDbSettingsStore`'s), each in its own record so saving one doesn't rewrite the others.
+*
+* @example
+* const store = new IndexedDbAssetStore<BrushConfig>("brushes");
+* await store.put(myPreset);
+*/
+var IndexedDbAssetStore = class {
+	kind;
+	name;
+	connection;
+	/**
+	* @param kind - the kind of asset
+	* @param name - the settings' name the assets belong to (`DEFAULT_SETTINGS_NAME` by default)
+	* @param factory - the IndexedDB to use (the browser's by default)
+	*/
+	constructor(kind, name = DEFAULT_SETTINGS_NAME, factory = indexedDB) {
+		this.kind = kind;
+		this.name = name;
+		this.connection = new DatabaseConnection(factory);
+	}
+	async list() {
+		return (await result((await this.connection.open()).transaction(this.kind, "readonly").objectStore(this.kind).getAll(this.keys()))).sort((a, b) => a.order - b.order).map((record) => record.asset);
+	}
+	async put(asset) {
+		const transaction = (await this.connection.open()).transaction(this.kind, "readwrite");
+		const done = completed(transaction);
+		const store = transaction.objectStore(this.kind);
+		const key = [this.name, asset.id];
+		const existing = store.get(key);
+		existing.onsuccess = () => {
+			const order = existing.result?.order ?? nextOrder();
+			store.put({
+				asset,
+				order
+			}, key);
+		};
+		await done;
+	}
+	async remove(id) {
+		const transaction = (await this.connection.open()).transaction(this.kind, "readwrite");
+		const done = completed(transaction);
+		transaction.objectStore(this.kind).delete([this.name, id]);
+		await done;
+	}
+	/** The keys of this name's assets: `[name, id]` (arrays sort after strings) */
+	keys() {
+		return IDBKeyRange.bound([this.name], [this.name, []]);
+	}
+};
+/**
+* Stores keeping the user's settings and assets in the browser's IndexedDB database, under a name.
+*
+* @example
+* const { settings, ...assets } = indexedDbStores("my-app");
+* canvas.useAssetStores(assets);
+*/
+var indexedDbStores = (name = DEFAULT_SETTINGS_NAME, factory = indexedDB) => ({
+	settings: new IndexedDbSettingsStore(name, factory),
+	brushes: new IndexedDbAssetStore("brushes", name, factory),
+	palettes: new IndexedDbAssetStore("palettes", name, factory),
+	profiles: new IndexedDbAssetStore("profiles", name, factory)
+});
+/**
+* The browser storage key that keeps the rendering chosen with the app settings of a name (see
+* `loadRenderingChoice`).
+*
+* @example
+* renderingChoiceKey("demo"); // "paintcanvas-rendering:demo"
+*/
+var renderingChoiceKey = (name) => `${DATABASE_NAME}-rendering:${name}`;
+/**
+* The rendering (`cpu` or `gpu`) last chosen with the app settings of a name, kept in `localStorage` so it can be read
+* before the canvas is made (the app settings themselves load later, from IndexedDB). Undefined when none was kept, it
+* isn't valid, or the storage can't be read (e.g. blocked by the browser).
+*
+* @example
+* new PaintCanvas({ rendering: loadRenderingChoice("demo") });
+*/
+var loadRenderingChoice = (name = DEFAULT_SETTINGS_NAME, storage = globalThis.localStorage) => {
+	try {
+		const value = storage?.getItem(renderingChoiceKey(name));
+		return isRendering(value) ? value : void 0;
+	} catch {
+		return;
+	}
+};
+/**
+* Keep the rendering chosen with the app settings of a name, to be read with `loadRenderingChoice` when the canvas is
+* next made. Does nothing if the storage can't be written.
+*
+* @example
+* canvas.ui.addEventListener("change", () => saveRenderingChoice("demo", canvas.ui.data.rendering));
+*/
+var saveRenderingChoice = (name, rendering, storage = globalThis.localStorage) => {
+	try {
+		storage?.setItem(renderingChoiceKey(name), rendering);
+	} catch {}
+};
+export { ASSET_KINDS, DATABASE_NAME, DATABASE_VERSION, DEFAULT_SETTINGS_NAME, IndexedDbAssetStore, IndexedDbSettingsStore, SAVED_DRAWING_VERSION, IndexedDbLayerStore as default, indexedDbStores, loadRenderingChoice, renderingChoiceKey, saveRenderingChoice };

package/dist/lib/validation/validators.generated.d.ts

@@ -1,8 +1,10 @@
 // Types for the generated validators (see validators.generated.js).
-import type { BrushPresetFile } from "../presets/schema";
-import type { PaintCanvasDocument } from "../document/schema";
-import type { PaletteFile } from "../palette/schema";
-import type { AppSettings, SettingsFile } from "../settings/schema";
+import type { AssetCollectionFile } from "../assets/schema";
+import type { BrushConfig } from "../brushes/types";
+import type { ProfileGraph } from "../profiles";
+import type { DocumentFile } from "../document/schema";
+import type { ColourPalette } from "../palette/schema";
+import type { AppSettings, AppSettingsFile } from "../settings/schema";
 import type {
   HistoryMessage,
   PatchMessage,
@@ -22,11 +24,20 @@ export interface Validator<T> {
 }
 
 export declare const validateBrushPreset: Validator<Record<string, unknown>>;
-export declare const validateBrushPresetFile: Validator<BrushPresetFile>;
+export declare const validateBrushPresetCollection: Validator<
+  AssetCollectionFile<BrushConfig>
+>;
+export declare const validateColourPalette: Validator<ColourPalette>;
+export declare const validateColourPaletteCollection: Validator<
+  AssetCollectionFile<ColourPalette>
+>;
+export declare const validateProfileGraph: Validator<ProfileGraph>;
+export declare const validateProfileGraphCollection: Validator<
+  AssetCollectionFile<ProfileGraph>
+>;
 export declare const validatePatchMessage: Validator<PatchMessage>;
 export declare const validateStrokeMessage: Validator<StrokeMessage>;
 export declare const validateHistoryMessage: Validator<HistoryMessage>;
-export declare const validateDocument: Validator<PaintCanvasDocument>;
-export declare const validatePaletteFile: Validator<PaletteFile>;
+export declare const validateDocument: Validator<DocumentFile>;
 export declare const validateSettings: Validator<AppSettings>;
-export declare const validateSettingsFile: Validator<SettingsFile>;
+export declare const validateAppSettings: Validator<AppSettingsFile>;