@lvl99dotcom/paintcanvas 0.0.0-stage → 0.2.0

package/dist/ui/ChangeController/index.js

@@ -0,0 +1,62 @@
+// src/ui/ChangeController/index.ts
+/**
+* Re-renders a Lit component whenever any of the given state objects dispatch a `change` event, first telling
+* `onChange` (if given) which one changed.
+*
+* The targets are re-read before every update, so replaced state objects (e.g. new layers after a canvas resize) are picked up.
+*
+* @example
+* class MyElement extends LitElement {
+*   private changes = new ChangeController(this, () => [this.app, this.app?.layers]);
+* }
+*/
+var ChangeController = class {
+	host;
+	getTargets;
+	subscribed = [];
+	notify;
+	onChange = (event) => {
+		this.notify?.(event.currentTarget);
+		this.host.requestUpdate();
+	};
+	constructor(host, getTargets, onChange) {
+		this.host = host;
+		this.getTargets = getTargets;
+		this.notify = onChange;
+		host.addController(this);
+	}
+	/**
+	* Subscribe to the current targets, replacing any previous subscriptions.
+	*/
+	refresh() {
+		this.unsubscribe();
+		this.subscribed = this.getTargets().filter((t) => t !== void 0);
+		for (const target of this.subscribed) target.addEventListener("change", this.onChange);
+	}
+	/**
+	* Subscribe when the component connects.
+	*/
+	hostConnected() {
+		this.refresh();
+	}
+	/**
+	* Re-subscribe before each update in case targets were replaced.
+	*/
+	hostUpdate() {
+		this.refresh();
+	}
+	/**
+	* Unsubscribe when the component disconnects.
+	*/
+	hostDisconnected() {
+		this.unsubscribe();
+	}
+	/**
+	* Remove all subscriptions.
+	*/
+	unsubscribe() {
+		for (const target of this.subscribed) target.removeEventListener("change", this.onChange);
+		this.subscribed = [];
+	}
+};
+export { ChangeController as default };

package/dist/ui/base/index.d.ts

@@ -0,0 +1,69 @@
+import { LitElement, type CSSResultGroup } from "lit";
+import { type IconRegistry } from "../icons";
+import Translations from "../../lib/i18n";
+/**
+ * Register a custom element unless the name is already registered (e.g. by another copy of PaintCanvas, or after hot
+ * module reload).
+ *
+ * @example
+ * defineElement("pc-button", PcButton);
+ */
+export declare const defineElement: (name: string, constructor: CustomElementConstructor) => void;
+/**
+ * Dispatch a custom event that crosses shadow DOM boundaries, so the implementer can listen anywhere above.
+ *
+ * @example
+ * emit(this, "pc-select", { value: "duplicate" });
+ */
+export declare const emit: <T>(target: EventTarget, type: string, detail?: T) => boolean;
+/**
+ * The base of PaintCanvas's elements: the design tokens, the translations and icons they use (shared ones unless
+ * given others), and re-rendering when either changes.
+ *
+ * @example
+ * class PcThing extends PcElement {
+ *   override render() {
+ *     return html`<button>${this.t("common.close")}</button>`;
+ *   }
+ * }
+ */
+export declare class PcElement extends LitElement {
+    static styles: CSSResultGroup;
+    static properties: {
+        translations: {
+            attribute: boolean;
+        };
+        icons: {
+            attribute: boolean;
+        };
+        theme: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+    };
+    /** The text the element shows, in the chosen language */
+    translations: Translations;
+    /** The icons the element shows */
+    icons: IconRegistry;
+    /** "light" (default), "dark", or "auto" to follow the device (see the design tokens) */
+    theme?: "light" | "dark" | "auto";
+    /** The translations and icons being listened to */
+    private watched;
+    private readonly onSourceChange;
+    constructor();
+    /**
+     * An icon's URL from the element's icons, or "" if there's none by that name.
+     */
+    protected iconUrl(name: string): string;
+    /**
+     * Translate a key with the element's translations.
+     */
+    protected t(key: string, values?: Record<string, string | number>): string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: Map<PropertyKey, unknown>): void;
+    /** Listen to the current translations and icons */
+    private watch;
+    /** Stop listening */
+    private unwatch;
+}

package/dist/ui/base/index.js

@@ -0,0 +1,94 @@
+import { installTokens, tokens } from "../tokens/index.js";
+import { icons } from "../icons/index.js";
+import { translations } from "../../lib/i18n/index.js";
+import { LitElement } from "lit";
+// src/ui/base/index.ts
+/**
+* Register a custom element unless the name is already registered (e.g. by another copy of PaintCanvas, or after hot
+* module reload).
+*
+* @example
+* defineElement("pc-button", PcButton);
+*/
+var defineElement = (name, constructor) => {
+	if (!customElements.get(name)) customElements.define(name, constructor);
+};
+/**
+* Dispatch a custom event that crosses shadow DOM boundaries, so the implementer can listen anywhere above.
+*
+* @example
+* emit(this, "pc-select", { value: "duplicate" });
+*/
+var emit = (target, type, detail) => target.dispatchEvent(new CustomEvent(type, {
+	detail,
+	bubbles: true,
+	composed: true,
+	cancelable: true
+}));
+/**
+* The base of PaintCanvas's elements: the design tokens, the translations and icons they use (shared ones unless
+* given others), and re-rendering when either changes.
+*
+* @example
+* class PcThing extends PcElement {
+*   override render() {
+*     return html`<button>${this.t("common.close")}</button>`;
+*   }
+* }
+*/
+var PcElement = class extends LitElement {
+	static styles = [tokens];
+	static properties = {
+		translations: { attribute: false },
+		icons: { attribute: false },
+		theme: {
+			type: String,
+			reflect: true
+		}
+	};
+	/** The translations and icons being listened to */
+	watched = [];
+	onSourceChange = () => this.requestUpdate();
+	constructor() {
+		super();
+		this.translations = translations;
+		this.icons = icons;
+	}
+	/**
+	* An icon's URL from the element's icons, or "" if there's none by that name.
+	*/
+	iconUrl(name) {
+		return this.icons.get(name) ?? "";
+	}
+	/**
+	* Translate a key with the element's translations.
+	*/
+	t(key, values) {
+		return this.translations.t(key, values);
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		installTokens(this.ownerDocument);
+		this.watch();
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		this.unwatch();
+	}
+	willUpdate(changed) {
+		super.willUpdate(changed);
+		if (this.isConnected && (changed.has("translations") || changed.has("icons"))) this.watch();
+	}
+	/** Listen to the current translations and icons */
+	watch() {
+		this.unwatch();
+		this.watched = [this.translations, this.icons];
+		for (const source of this.watched) source.addEventListener("change", this.onSourceChange);
+	}
+	/** Stop listening */
+	unwatch() {
+		for (const source of this.watched) source.removeEventListener("change", this.onSourceChange);
+		this.watched = [];
+	}
+};
+export { PcElement, defineElement, emit };

package/dist/ui/elements/PaintCanvas/index.d.ts

@@ -0,0 +1,249 @@
+import { PcElement } from "../../base";
+import PaintCanvas from "../../../lib/classes/PaintCanvas";
+import type { BrushConfig } from "../../../lib/brushes/types";
+import { type SaveMethod } from "../../../lib/rendering/screenshot";
+import { type InputKind, type LayoutState } from "../../layout";
+import type { PcPanel } from "../PcPanel";
+import "../PcPanel";
+import "../PcToolbar";
+import "../PcToolSettings";
+import "../PcCanvas";
+import "../PcCanvasMap";
+import "../PcBrushMenu";
+import "../PcLayersMenu";
+import "../PcBrushConfig";
+import "../PcStats";
+import "../PcDialog";
+/** A side of the layout */
+type Side = "left" | "right";
+/**
+ * A ready-made painting app: the drawing elements arranged around the canvas, sized to its container (not the
+ * window), with slots to add or replace content:
+ *
+ * - `header`: across the top (empty by default)
+ * - `left`: `<pc-toolbar>` by default
+ * - `top`: `<pc-tool-settings>` (for tools that have settings) by default
+ * - `right`: empty by default (e.g. a `<pc-panel>` with a layers menu or chat)
+ * - `center`: `<pc-canvas>` by default
+ * - `overlay`: drawn over the canvas; `<pc-canvas-map>` by default
+ * - `bottom`: under the canvas (empty by default)
+ * - `footer`: across the bottom; `<pc-stats>` by default
+ * - `menu`: the app menu the toolbar's menu button opens (the button shows only with a menu)
+ *
+ * Content given for a slot replaces its default; an empty element clears it. Empty slots take no space. Hiding the
+ * interface (Tab key) leaves only the canvas and overlay. A `<pc-layers-menu>` given in a side (e.g. in a `<pc-panel>`)
+ * replaces the toolbar's layers menu button.
+ *
+ * Each side has a mode, chosen by the layout's width from `left-modes` and `right-modes` (default `"docked,
+ * rail@600"`): `docked` beside the canvas; `rail`, a column of buttons (one per `<pc-panel>`) that open each panel over
+ * the canvas; or `floating`, the side over the canvas as a palette that collapses to a button.
+ *
+ * Reports its state for styling as attributes (`narrow`, `input="pen|touch|mouse"`, `ui-hidden`, `left-mode`,
+ * `right-mode`) and as `pc-state-change` events (see `LayoutState`). Creates its own canvas unless given one, and
+ * handles keyboard shortcuts unless `shortcuts` is false.
+ *
+ * With a `store` name, the user's layers are kept in the browser (IndexedDB) under that name, so the drawing survives
+ * reloading the page (see `LayerAutosave`). While another window is drawing on it, the layout is blocked by a message
+ * that offers to draw here instead. Fires `pc-toast` when the drawing can't be loaded or saved.
+ *
+ * @example
+ * html`<paint-canvas style="height: 600px"></paint-canvas>`
+ * html`<paint-canvas .app=${canvas} right-modes="docked, rail@800">
+ *   <pc-panel slot="right" icon="layers" label="Layers"><pc-layers-menu .app=${canvas}></pc-layers-menu></pc-panel>
+ * </paint-canvas>`
+ */
+export declare class PaintCanvasElement extends PcElement {
+    static properties: {
+        app: {
+            attribute: boolean;
+        };
+        leftModes: {
+            type: StringConstructor;
+            attribute: string;
+        };
+        rightModes: {
+            type: StringConstructor;
+            attribute: string;
+        };
+        narrowWidth: {
+            type: NumberConstructor;
+            attribute: string;
+        };
+        menuText: {
+            type: StringConstructor;
+            attribute: string;
+        };
+        menuLabel: {
+            type: StringConstructor;
+            attribute: string;
+        };
+        shortcuts: {
+            type: BooleanConstructor;
+        };
+        store: {
+            type: StringConstructor;
+        };
+        width: {
+            state: boolean;
+        };
+        input: {
+            state: boolean;
+        };
+        configuring: {
+            state: boolean;
+        };
+        collapsed: {
+            state: boolean;
+        };
+        openPanel: {
+            state: boolean;
+        };
+        translations: {
+            attribute: boolean;
+        };
+        icons: {
+            attribute: boolean;
+        };
+        theme: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+    };
+    static styles: import("lit").CSSResultGroup[];
+    /** The canvas (one is created if none is given) */
+    app?: PaintCanvas;
+    /** The left side's modes (see `parseSideModes`) */
+    leftModes: string;
+    /** The right side's modes (see `parseSideModes`) */
+    rightModes: string;
+    /** Width (CSS pixels) below which the layout is narrow */
+    narrowWidth: number;
+    /** What the toolbar's menu button shows */
+    menuText: string;
+    /** The toolbar's menu button's name for screen readers */
+    menuLabel?: string;
+    /** Whether the layout handles keyboard shortcuts (default true) */
+    shortcuts: boolean;
+    /** Name to keep the user's layers under in the browser, so the drawing survives reloading the page (none by default) */
+    store?: string;
+    /** The layout's width in CSS pixels */
+    width: number;
+    /** The input being used now */
+    input: InputKind;
+    /** The brush or eraser configuration window, while open */
+    configuring?: {
+        kind: "brush" | "eraser";
+        config: BrushConfig;
+        editingId?: string;
+    };
+    /** Which floating sides are collapsed to a button */
+    collapsed: Record<Side, boolean>;
+    /** The panel open from a rail, if any */
+    openPanel?: PcPanel;
+    /** Saves files (replaceable for tests) */
+    saveFile: (blob: Blob, name: string) => Promise<SaveMethod | undefined>;
+    private changes;
+    /** The autosave the layout started for `store`, if any */
+    private ownAutosave?;
+    /** The autosave whose errors are shown */
+    private watchedAutosave?;
+    /** Whether drawing was blocked when shortcuts were last watched */
+    private blockedShortcuts;
+    /** The panels in each side's slot */
+    private panels;
+    /** Whether each side's slot has a layers menu (the toolbar's isn't needed then) */
+    private sideLayers;
+    /** Whether the implementer gave a menu */
+    private hasMenu;
+    /** Slots the implementer gave content for (their defaults aren't created) */
+    private filled;
+    /** Keyboard shortcuts, while handled */
+    private keys?;
+    /** The state last reported, to report only changes */
+    private reported?;
+    /** Space the floating sides cover over the canvas */
+    private floatingInsets;
+    /** The rail button that opened the open panel, to return focus to */
+    private opener?;
+    private readonly resizeObserver?;
+    private readonly panelObserver;
+    private readonly onPointerDown;
+    private readonly onAutosaveError;
+    private readonly onShortcut;
+    private readonly onDocumentPointerDown;
+    private readonly onKeyDown;
+    constructor();
+    /** Whether another window is drawing on the stored drawing, so this one is blocked */
+    get blocked(): boolean;
+    /** The layout's state now (see `LayoutState`) */
+    get state(): LayoutState;
+    /** A side's mode for the layout's width */
+    private modeOf;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: Map<PropertyKey, unknown>): void;
+    protected updated(): void;
+    /** Keep the canvas clear of floating sides when fitting it */
+    private measureFloatingSides;
+    /**
+     * Keep the canvas's layers under the `store` name, replacing an autosave the layout started earlier (also on the
+     * previous canvas). An autosave the implementer started is left alone when there's no name.
+     */
+    private useStore;
+    /** Show errors from the canvas's current autosave */
+    private watchAutosaveErrors;
+    /** Handle keyboard shortcuts for the current canvas, if asked to (not while blocked) */
+    private watchShortcuts;
+    /** Stop handling keyboard shortcuts */
+    private unwatchShortcuts;
+    /**
+     * Save the whole canvas as a PNG on white, at full size, including a stroke or transform in progress. Returns how it
+     * was saved, or undefined if cancelled.
+     */
+    saveScreenshot(): Promise<SaveMethod | undefined>;
+    /** The brush or eraser settings */
+    private toolSettings;
+    /**
+     * Open the configuration window for the current brush or eraser settings. When the selected preset is one of the
+     * user's own, the window can delete it.
+     */
+    configure(kind: "brush" | "eraser"): void;
+    /**
+     * Open the configuration window to make a new preset, starting from the current brush or eraser settings.
+     */
+    newPreset(kind: "brush" | "eraser"): void;
+    /** Which side a panel is in */
+    private sideOf;
+    /**
+     * Open a panel from its rail button (closing any other), or close it if it's open. Focus moves into the panel.
+     */
+    togglePanel(panel: PcPanel, opener?: HTMLElement): void;
+    /**
+     * Close the panel open from a rail, moving focus back to its rail button if asked.
+     */
+    closePanel(returnFocus: boolean): void;
+    /** Follow which slots have content given (their defaults aren't needed) */
+    private onSlotChange;
+    /** A slot, with its default content unless content was given for it */
+    private slotWithDefault;
+    /** Follow the panels given for a side, and whether it has a layers menu */
+    private onSideSlotChange;
+    /** Follow whether a menu was given */
+    private onMenuSlotChange;
+    /** Whether a side has a layers menu, replacing the toolbar's */
+    private get layersInSide();
+    /** The toolbar shown on the left unless the implementer gives other content */
+    private renderToolbar;
+    /** A side's rail buttons, one per panel */
+    private renderRail;
+    /** A side, in its mode */
+    private renderSide;
+    /** The menus the toolbar opens, floating over the canvas beside it */
+    private renderPanels;
+    /** The brush configuration window, while open */
+    private renderConfig;
+    /** The message blocking the layout while another window is drawing on the stored drawing */
+    private renderBlocked;
+    render(): import("lit").TemplateResult<1>;
+}
+export {};