@lvl99dotcom/paintcanvas 0.6.0 → 0.8.0

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

@@ -14,18 +14,24 @@ import Lasso, { type LassoResult } from "../../selection/Lasso";
 import Transformer from "../../transform/Transformer";
 import { type CanvasFactory, type LayerConfig } from "../Layer";
 import LayerAutosave, { type AutosaveOptions } from "../LayerAutosave";
-import type { LayerStoreLike } from "../../storage";
+import type { AssetStores, DocumentStoreLike, LayerStoreLike } from "../../storage";
+import RemoteDocumentAutosave, { type RemoteAutosaveOptions } from "../RemoteDocumentAutosave";
+import type { ProfileGraph } from "../../profiles";
 import type { AssetAuthor, BrushConfig } from "../../brushes/types";
-import CustomPresets, { type PresetStoreLike } from "../CustomPresets";
+import CustomPresets from "../CustomPresets";
+import AssetSync from "../AssetSync";
+import ColourPalettes from "../ColourPalettes";
+import type { ColourPalette } from "../../palette";
 import InputSettings from "../InputSettings";
-import UiSettings from "../UiSettings";
+import UiSettings, { type Rendering } from "../UiSettings";
 import Palette from "../Palette";
 import ProfileGraphs from "../ProfileGraphs";
 import ShortcutSettings from "../ShortcutSettings";
+import SettingsExtensions from "../SettingsExtensions";
 import ExternalSheets from "../ExternalSheets";
 import { type CanvasMessage, type PatchMessage, type StrokeMessage } from "../../messages";
 import { type BoundingBox } from "../../image";
-import { type PaintCanvasDocument } from "../../document";
+import { type DocumentFile, type DocumentInfo, type DrawingDocument } from "../../document";
 export { Tool };
 /** How the colour sample tool samples: the pixel under the pointer, or the average of a dragged rectangle */
 export type SampleMode = "point" | "area";
@@ -54,8 +60,6 @@ export declare const DEFAULT_BACKGROUND_COLOUR = "#ffffff";
  * (painted by the eraser and Delete when the layer's alpha lock is on, and by background fills).
  */
 export type ColourSlot = "foreground" | "background";
-/** Owner of the custom presets when the `ownerId` option isn't given */
-export declare const DEFAULT_OWNER_ID = "local";
 /** Author name of presets made with `newPreset` when the `presetAuthor` option isn't given */
 export declare const DEFAULT_AUTHOR = "Unknown";
 /** Names the implementer can change: what users see and what files are called */
@@ -64,12 +68,6 @@ export interface PaintCanvasNames {
     app: string;
     /** Start of the names of saved files, e.g. screenshots and exported presets */
     filePrefix: string;
-    /** The `format` written in exported brush preset files */
-    presetFileFormat: string;
-    /** The `format` written in exported colour palette files */
-    paletteFileFormat: string;
-    /** The `format` written in exported settings files */
-    settingsFileFormat: string;
     /** Author name of presets made by a user without a handle, e.g. from `presetAuthor` */
     unknownAuthor: string;
 }
@@ -93,6 +91,11 @@ export interface CanvasStats {
     /** Most undo steps kept */
     historyLimit: number;
 }
+/** Options for `PaintCanvas.createDocument` */
+export interface CreateDocumentOptions {
+    /** Whether to include a thumbnail (default true) */
+    thumbnail?: boolean;
+}
 /** Receives the drawing messages PaintCanvas sends; a returned promise that rejects means a patch wasn't delivered */
 export type MessageListener = (message: CanvasMessage) => void | Promise<void>;
 /** Options for sending drawing messages (see `startSending`) */
@@ -116,21 +119,27 @@ export interface PaintCanvasOptions {
     /** Most layers the user can have (default `DEFAULT_MAX_LAYERS`) */
     maxLayers?: number;
     /**
-     * Creates the canvases the engine draws in: layers, stroke buffers, masks and copies. `createMemoryCanvas` by default,
-     * keeping pixels in regular memory so saving and copying don't stall phones; pass `createOffscreenCanvas` to keep them
-     * on the GPU instead (replaceable for tests).
+     * Where the canvases draw (`cpu` by default): `cpu` keeps their pixels in regular memory (`createMemoryCanvas`) so
+     * saving and copying don't stall phones; `gpu` asks the browser to keep them on the GPU (`createOffscreenCanvas`).
+     * Browsers fix this when a canvas is made, so it can't change while the canvas runs: to follow the user's choice
+     * (`ui.data.rendering`), pass the one they made last time (`<paint-canvas>` does this with its `settings-store`).
+     */
+    rendering?: Rendering;
+    /**
+     * Creates the canvases the engine draws in: layers, stroke buffers, masks and copies. Chosen by `rendering` unless
+     * given (replaceable for tests).
      */
     createCanvas?: CanvasFactory;
-    /** Where custom brush presets are kept (defaults to keeping them in memory only) */
-    presetStore?: PresetStoreLike;
-    /** Who the custom presets belong to, passed to the preset store (default `DEFAULT_OWNER_ID`) */
-    ownerId?: string;
+    /** Where the user's assets (brush presets, colour palettes, profile graphs) are kept (see `useAssetStores`) */
+    stores?: AssetStores;
     /** Gives the author of presets made with `newPreset` (asked each time, so it can follow name changes) */
     presetAuthor?: () => AssetAuthor;
     /** Names to use instead of PaintCanvas's own (see `DEFAULT_NAMES`) */
     names?: Partial<PaintCanvasNames>;
     /** Where to keep the user's layers so the drawing survives reloading the page (see `useLayerStore`) */
     layerStore?: LayerStoreLike;
+    /** Where to keep the whole drawing away from the browser, saved less often (see `useRemoteDocumentStore`) */
+    remoteDocumentStore?: DocumentStoreLike;
     /**
      * The system clipboard, which copying and cutting also put a PNG of the copied image data on so other apps (and brush
      * shapes) can use it (the browser's by default; `null` for none)
@@ -172,12 +181,26 @@ export default class PaintCanvas extends EventTarget {
     readonly background: BackgroundWork;
     /** How the user's input devices control the canvas (scrolling, pinching, touch gestures, focus pen mode) */
     readonly input: InputSettings;
-    /** The user's interface choices (theme and language), kept with the other app settings */
+    /** The user's interface choices (theme, language and where canvases draw), kept with the other app settings */
     readonly ui: UiSettings;
     /** The user's saved colours, shown as swatches */
     readonly palette: Palette;
     /** The user's own profile graphs (and the presets), for shaping how brush settings vary */
     readonly profiles: ProfileGraphs;
+    /** The drawing's details (see `documentInfo`) */
+    private info;
+    /** Keeps the drawing in a remote store */
+    private remoteDocumentAutosave?;
+    /** Settings wrapper apps add to the app settings (see `SettingsExtension`) */
+    readonly settingsExtensions: SettingsExtensions;
+    /** The user's own colour palettes (the one PaintCanvas comes with is `palette`) */
+    readonly palettes: ColourPalettes;
+    /** Where the user's assets are kept */
+    private stores;
+    /** Keeps the colour palettes in their store */
+    private palettesAutosave?;
+    /** Keeps the profile graphs in their store */
+    private profilesAutosave?;
     /** The user's keyboard shortcuts: each configurable action's key combination */
     readonly shortcuts: ShortcutSettings;
     /** The user's pointer position over the canvas, in canvas pixels (undefined when off the canvas) */
@@ -233,10 +256,11 @@ export default class PaintCanvas extends EventTarget {
     /** The layer stack whose changes are being sent */
     private sendingLayers?;
     private readonly onLayersChangeToSend;
+    /** Where the canvases draw, chosen when the canvas started (the user's choice for next time is `ui.data.rendering`) */
+    readonly rendering: Rendering;
     /** Creates the canvases the app draws on (fake ones in tests) */
     readonly createCanvas: CanvasFactory;
     /** Who the custom presets belong to (passed to the preset store) */
-    readonly ownerId: string;
     /** The largest canvas width or height allowed */
     readonly maxCanvasSize: number;
     /** Most layers the user can have */
@@ -308,23 +332,60 @@ export default class PaintCanvas extends EventTarget {
      * transport.onMessage((from, message) => canvas.receive(from, message));
      */
     receive(source: string, message: unknown): Promise<boolean>;
+    /** The drawing's details: its ID, name, authors and when it was made and last opened */
+    get documentInfo(): Readonly<DocumentInfo>;
+    /**
+     * Rename the drawing. Returns whether it was renamed (not if the name is empty).
+     *
+     * @example
+     * canvas.renameDocument("Sunset at sea");
+     */
+    renameDocument(name: string): boolean;
+    /**
+     * Use details of a drawing being restored (e.g. kept in the browser), marking it opened now.
+     */
+    restoreDocumentInfo(info: DocumentInfo): void;
+    /**
+     * Start a new drawing: new details (a new ID, the user as its author, made now), and the layers replaced with one
+     * empty layer. Undo history starts again.
+     *
+     * @example
+     * canvas.newDocument("Sketch");
+     */
+    newDocument(name?: string): void;
+    /**
+     * The drawing as a document (see `DrawingDocument`): its details, size, the user's layers and drawings from elsewhere
+     * as PNG blobs, and a thumbnail (at most `THUMBNAIL_SIZE` pixels on its longest side) unless left out. The user is
+     * added to its authors.
+     *
+     * @example
+     * await myStore.save(await canvas.createDocument());
+     */
+    createDocument({ thumbnail, }?: CreateDocumentOptions): Promise<DrawingDocument>;
+    /**
+     * Replace the drawing with a document (e.g. from a store): its details (marked opened now), size, layers and drawings
+     * from elsewhere. Undo history starts again. Returns whether it was opened: not when it has too many layers, is too
+     * big, doesn't have its selected layer, or an image can't be decoded, and then nothing changes.
+     *
+     * @example
+     * await canvas.openDocument(await myStore.load(id));
+     */
+    openDocument(document: DrawingDocument): Promise<boolean>;
     /**
-     * The drawing as a document: its size, the user's layers and drawings from elsewhere, with PNG images (see
-     * `PaintCanvasDocument`). Turn it into JSON to save it as a file.
+     * The drawing as a document file (see `DocumentFile`): turn it into JSON to save it as a file.
      *
      * @example
      * const json = JSON.stringify(await canvas.exportDocument());
      */
-    exportDocument(): Promise<PaintCanvasDocument>;
+    exportDocument(): Promise<DocumentFile>;
     /**
-     * Replace the drawing with a document (e.g. read from a file): its size, layers and drawings from elsewhere. Undo
-     * history starts again. Returns whether it was loaded: not when the document is invalid or an image can't be
-     * decoded, and then nothing changes.
+     * Replace the drawing with a document file (e.g. read from a file, see `documentFromFile`). Returns whether it was
+     * opened: not when it isn't a valid document or can't be opened (see `openDocument`), and then nothing changes.
      *
      * @example
      * await canvas.importDocument(JSON.parse(text));
      */
-    importDocument(document: unknown): Promise<boolean>;
+    importDocument(file: unknown): Promise<boolean>;
     /**
      * Replace the canvas size and the user's layers (top first, each with its image) and select one by ID. Undo history
      * starts again. Throws if the size or number of layers isn't allowed.
@@ -333,6 +394,32 @@ export default class PaintCanvas extends EventTarget {
      * canvas.restoreLayers(800, 600, [{ id: "a", name: "Sketch" }], [sketchImage], "a");
      */
     restoreLayers(width: number, height: number, layers: readonly LayerConfig[], images: readonly CanvasImageSource[], activeLayer: string): void;
+    /** Where the user's assets are kept (see `useAssetStores`) */
+    get assetStores(): Readonly<AssetStores>;
+    /** Keeps the user's profile graphs in their store, while one is used (see `useAssetStores`) */
+    get profileSync(): AssetSync<ProfileGraph> | undefined;
+    /** Keeps the user's colour palettes in their store, while one is used (see `useAssetStores`) */
+    get paletteSync(): AssetSync<ColourPalette> | undefined;
+    /**
+     * Keep the user's assets in stores, by kind: custom brush presets are loaded from theirs (in place of the current
+     * ones) and saved when they change; colour palettes and profile graphs saved there are added and changes saved (see
+     * `AssetSync`). Assets of a kind without a store are kept in memory only.
+     *
+     * @example
+     * canvas.useAssetStores({ brushes: new IndexedDbAssetStore("brushes"), profiles: new IndexedDbAssetStore("profiles") });
+     */
+    useAssetStores(stores: AssetStores): void;
+    /** Keeps the drawing in a remote store, while one is used (see `useRemoteDocumentStore`) */
+    get remoteAutosave(): RemoteDocumentAutosave | undefined;
+    /**
+     * Keep the whole drawing in a remote store (e.g. the user's account online), or stop, without one: changes are saved
+     * every few minutes (see `RemoteDocumentAutosave`), or when asked with `canvas.remoteAutosave.save()`. Returns the
+     * autosave.
+     *
+     * @example
+     * canvas.useRemoteDocumentStore(myAccountStore, { intervalMs: 10 * 60 * 1000 });
+     */
+    useRemoteDocumentStore(store: DocumentStoreLike | undefined, options?: RemoteAutosaveOptions): RemoteDocumentAutosave | undefined;
     /** Keeps the user's layers in a store, while one is used (see `useLayerStore`) */
     get autosave(): LayerAutosave | undefined;
     /**
@@ -553,6 +640,13 @@ export default class PaintCanvas extends EventTarget {
      * own presets are the ones with this handle (see `isOwnAuthor`).
      */
     get authorHandle(): string;
+    /**
+     * The author of assets the user makes, e.g. colour palettes (from the `presetAuthor` option).
+     *
+     * @example
+     * app.palettes.create("Sunset", [], app.author);
+     */
+    get author(): AssetAuthor;
     /**
      * Make a new custom preset from settings: a new ID, the given name, and the author from the `presetAuthor` option.
      *
@@ -652,5 +746,7 @@ export default class PaintCanvas extends EventTarget {
     /**
      * Dispatch a `change` event.
      */
+    /** Use the drawing's details and tell listeners */
+    private setDocumentInfo;
     protected notify(): void;
 }