@lvl99dotcom/paintcanvas 0.3.0 → 0.4.0

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

@@ -1,150 +1,224 @@
-import { Tool } from "../../classes/PaintCanvas/index.js";
+import { Tool } from "../../classes/PaintCanvas/tool.js";
 // src/lib/utils/shortcuts/index.ts
-/** All keyboard shortcuts */
-var SHORTCUTS = [
-	{
-		key: "b",
-		action: {
-			type: "tool",
-			tool: Tool.Brush
-		}
-	},
-	{
-		key: "e",
-		action: {
-			type: "tool",
-			tool: Tool.Eraser
-		}
-	},
-	{
-		key: "v",
-		action: {
-			type: "tool",
-			tool: Tool.Move
-		}
-	},
-	{
-		key: "m",
-		action: {
-			type: "tool",
-			tool: Tool.RectangleLasso
-		}
-	},
-	{
+/** ID of the action run while its key is held: pan, returning to the last tool when released */
+var HOLD_TO_PAN = "pan";
+/**
+* Define a shortcut action.
+*/
+var define = (id, group, action, combos, configurable = true) => ({
+	id,
+	group,
+	action,
+	combos,
+	configurable
+});
+/** Define a configurable tool shortcut */
+var tool = (id, toolName, combo) => define(id, "tools", {
+	type: "tool",
+	tool: toolName
+}, [combo]);
+/** Layer opacity shortcuts: 1 for 10% to 9 for 90%, and 0 for 100% */
+var LAYER_OPACITY_SHORTCUTS = Array.from({ length: 10 }, (_, i) => define(`layer-opacity-${(i + 1) * 10}`, "layers", {
+	type: "layer-opacity",
+	opacity: (i + 1) / 10
+}, [{ key: String((i + 1) % 10) }], false));
+/** Every keyboard shortcut action, in the order they are listed */
+var SHORTCUT_DEFINITIONS = [
+	define("pan", "tools", { type: "pan" }, [{ key: " " }]),
+	tool("tool-move", Tool.Move, { key: "v" }),
+	tool("tool-brush", Tool.Brush, { key: "b" }),
+	tool("tool-eraser", Tool.Eraser, { key: "e" }),
+	tool("tool-rectangle-mask", Tool.RectangleLasso, { key: "m" }),
+	tool("tool-circle-mask", Tool.CircleLasso, {
 		key: "m",
-		shift: true,
-		action: {
-			type: "tool",
-			tool: Tool.CircleLasso
-		}
-	},
-	{
-		key: "l",
-		action: {
-			type: "tool",
-			tool: Tool.PolygonLasso
-		}
-	},
-	{
+		shift: true
+	}),
+	tool("tool-polygon-mask", Tool.PolygonLasso, { key: "l" }),
+	tool("tool-freehand-mask", Tool.FreeformLasso, {
 		key: "l",
-		shift: true,
-		action: {
-			type: "tool",
-			tool: Tool.FreeformLasso
-		}
-	},
-	{
-		key: "h",
-		action: {
-			type: "tool",
-			tool: Tool.Pan
-		}
-	},
-	{
-		key: "z",
-		action: {
-			type: "tool",
-			tool: Tool.Zoom
-		}
-	},
-	{
-		key: "i",
-		action: {
-			type: "tool",
-			tool: Tool.ColourSample
-		}
-	},
-	{
-		key: "[",
-		action: { type: "brush-smaller" }
-	},
-	{
-		key: "]",
-		action: { type: "brush-bigger" }
-	},
-	{
-		key: "tab",
-		action: { type: "toggle-interface" }
-	},
-	{
+		shift: true
+	}),
+	tool("tool-colour-sample", Tool.ColourSample, { key: "i" }),
+	tool("tool-zoom", Tool.Zoom, { key: "z" }),
+	define("brush-bigger", "brushes", { type: "brush-bigger" }, [{ key: "]" }]),
+	define("brush-smaller", "brushes", { type: "brush-smaller" }, [{ key: "[" }]),
+	define("brush-more-opaque", "brushes", { type: "brush-more-opaque" }, [{ key: ">" }]),
+	define("brush-less-opaque", "brushes", { type: "brush-less-opaque" }, [{ key: "<" }]),
+	define("select-all", "masking", { type: "select-all" }, [{
 		key: "a",
+		cmd: true
+	}]),
+	define("invert-selection", "masking", { type: "invert-selection" }, [{
+		key: "i",
 		cmd: true,
-		action: { type: "select-all" }
-	},
-	{
+		shift: true
+	}]),
+	define("deselect", "masking", { type: "deselect" }, [{
 		key: "d",
-		cmd: true,
-		action: { type: "deselect" }
-	},
-	{
-		key: "s",
-		cmd: true,
-		action: { type: "save" }
-	},
-	{
-		key: "z",
-		cmd: true,
-		action: { type: "undo" }
-	},
-	{
-		key: "z",
-		cmd: true,
-		shift: true,
-		action: { type: "redo" }
-	},
-	{
-		key: "x",
-		cmd: true,
-		action: { type: "cut" }
-	},
-	{
-		key: "delete",
-		action: { type: "delete" }
-	},
-	{
+		cmd: true
+	}]),
+	define("fill-foreground", "fills", { type: "fill-foreground" }, [{
+		key: "backspace",
+		cmd: true
+	}]),
+	define("fill-background", "fills", { type: "fill-background" }, [{
 		key: "backspace",
-		action: { type: "delete" }
-	},
-	{
+		alt: true
+	}]),
+	define("swap-colours", "fills", { type: "swap-colours" }, [{ key: "x" }]),
+	define("zoom-in", "viewport", { type: "zoom-in" }, [{
+		key: "+",
+		cmd: true
+	}]),
+	define("zoom-out", "viewport", { type: "zoom-out" }, [{
+		key: "-",
+		cmd: true
+	}]),
+	define("reset-zoom", "viewport", { type: "reset-zoom" }, [{
+		key: "0",
+		cmd: true
+	}]),
+	...LAYER_OPACITY_SHORTCUTS,
+	define("cut", "clipboard", { type: "cut" }, [{
+		key: "x",
+		cmd: true
+	}], false),
+	define("copy", "clipboard", { type: "copy" }, [{
 		key: "c",
-		cmd: true,
-		action: { type: "copy" }
-	},
-	{
+		cmd: true
+	}], false),
+	define("paste", "clipboard", { type: "paste" }, [{
 		key: "v",
+		cmd: true
+	}], false),
+	define("undo", "history", { type: "undo" }, [{
+		key: "z",
+		cmd: true
+	}], false),
+	define("redo", "history", { type: "redo" }, [{
+		key: "z",
 		cmd: true,
-		action: { type: "paste" }
-	},
-	{
-		key: "escape",
-		action: { type: "cancel" }
-	},
-	{
-		key: "enter",
-		action: { type: "commit" }
-	}
+		shift: true
+	}], false),
+	define("toggle-interface", "general", { type: "toggle-interface" }, [{ key: "tab" }], false),
+	define("save", "general", { type: "save" }, [{
+		key: "s",
+		cmd: true
+	}], false),
+	define("delete", "general", { type: "delete" }, [{ key: "delete" }, { key: "backspace" }], false),
+	define("cancel", "general", { type: "cancel" }, [{ key: "escape" }], false),
+	define("commit", "general", { type: "commit" }, [{ key: "enter" }], false)
 ];
-/** Key held to pan temporarily (handled separately because it acts while held, not on press) */
+/** The actions users can change the key combinations of */
+var CONFIGURABLE_SHORTCUTS = SHORTCUT_DEFINITIONS.filter((definition) => definition.configurable);
+/** The actions whose key combinations can't be changed */
+var FIXED_SHORTCUTS = SHORTCUT_DEFINITIONS.filter((definition) => !definition.configurable);
+/** Longest key name in a saved key combination (characters) */
+var MAX_KEY_LENGTH = 32;
+/**
+* A key combination with only the modifiers that are on, e.g. to compare or save it.
+*
+* @example
+* normaliseCombo({ key: "s", cmd: true, shift: false }); // { key: "s", cmd: true }
+*/
+var normaliseCombo = ({ key, cmd, ctrl, shift, alt }) => ({
+	key,
+	...cmd && { cmd: true },
+	...ctrl && { ctrl: true },
+	...shift && { shift: true },
+	...alt && { alt: true }
+});
+/**
+* Whether two key combinations are the same.
+*
+* @example
+* sameCombo({ key: "s", cmd: true }, { key: "s", cmd: true, shift: false }); // true
+*/
+var sameCombo = (a, b) => a.key === b.key && Boolean(a.cmd) === Boolean(b.cmd) && Boolean(a.ctrl) === Boolean(b.ctrl) && Boolean(a.shift) === Boolean(b.shift) && Boolean(a.alt) === Boolean(b.alt);
+/**
+* Keep a valid key combination from an untrusted value (e.g. stored or imported). Undefined if it isn't one.
+*
+* @example
+* sanitiseCombo({ key: "s", cmd: true, extra: 1 }); // { key: "s", cmd: true }
+* sanitiseCombo({ key: "" }); // undefined
+*/
+var sanitiseCombo = (input) => {
+	if (typeof input !== "object" || input === null) return void 0;
+	const { key, cmd, ctrl, shift, alt } = input;
+	if (typeof key !== "string" || key.length === 0 || key.length > MAX_KEY_LENGTH || key !== key.toLowerCase() || ![
+		cmd,
+		ctrl,
+		shift,
+		alt
+	].every((flag) => flag === void 0 || typeof flag === "boolean")) return void 0;
+	return normaliseCombo({
+		key,
+		cmd,
+		ctrl,
+		shift,
+		alt
+	});
+};
+/**
+* The default key combination of each configurable action.
+*
+* @example
+* defaultShortcutBindings()["tool-brush"]; // { key: "b" }
+*/
+var defaultShortcutBindings = () => Object.fromEntries(CONFIGURABLE_SHORTCUTS.map(({ id, combos }) => [id, normaliseCombo(combos[0])]));
+/**
+* The fixed action that uses a key combination, if any.
+*
+* @example
+* fixedShortcutFor({ key: "z", cmd: true })?.id; // "undo"
+*/
+var fixedShortcutFor = (combo) => FIXED_SHORTCUTS.find(({ combos }) => combos.some((fixed) => sameCombo(fixed, combo)));
+/**
+* Keep valid key combinations from an untrusted value (e.g. stored or imported), using `defaults` for actions that are
+* missing or invalid. `null` removes an action's key combination. A key combination a fixed action uses, or that an
+* earlier action (in `SHORTCUT_DEFINITIONS` order) already has, is removed. Unknown actions are left out.
+*
+* @example
+* sanitiseShortcutBindings({ "tool-brush": { key: "p" }, cut: null }, defaultShortcutBindings());
+*/
+var sanitiseShortcutBindings = (input, defaults) => {
+	const given = typeof input === "object" && input !== null ? input : {};
+	const used = [];
+	return Object.fromEntries(CONFIGURABLE_SHORTCUTS.map(({ id }) => {
+		const value = given[id];
+		const combo = value === null ? null : sanitiseCombo(value) ?? defaults[id] ?? null;
+		if (!combo || fixedShortcutFor(combo) || used.some((other) => sameCombo(other, combo))) return [id, null];
+		used.push(combo);
+		return [id, combo];
+	}));
+};
+/**
+* The shortcuts to match key presses against: the configurable actions' key combinations (except the hold-to-pan key,
+* which acts while held) and the fixed ones.
+*
+* @example
+* shortcutsFor(defaultShortcutBindings()).find((s) => s.key === "b")?.action; // { type: "tool", tool: Tool.Brush }
+*/
+var shortcutsFor = (bindings) => [...CONFIGURABLE_SHORTCUTS.flatMap(({ id, action }) => {
+	const combo = bindings[id];
+	return combo && id !== "pan" ? [{
+		...combo,
+		action
+	}] : [];
+}), ...FIXED_SHORTCUTS.flatMap(({ action, combos }) => combos.map((combo) => ({
+	...combo,
+	action
+})))];
+/** All keyboard shortcuts with their default key combinations */
+var SHORTCUTS = shortcutsFor(defaultShortcutBindings());
+/**
+* Whether a platform (`navigator.platform` by default) is an Apple device, where "cmd" is the Command key.
+*
+* @example
+* isApplePlatform("MacIntel"); // true
+* isApplePlatform("Win32"); // false
+*/
+var isApplePlatform = (platform = navigator.platform) => /Mac|iPhone|iPad|iPod/.test(platform);
 /**
 * The symbol for the "cmd" key in shortcut labels: ⌘ on Apple devices, ^ (Control) elsewhere.
 *
@@ -152,21 +226,193 @@ var SHORTCUTS = [
 * cmdSymbol("MacIntel"); // "⌘"
 * cmdSymbol("Win32"); // "^"
 */
-var cmdSymbol = (platform = navigator.platform) => /Mac|iPhone|iPad|iPod/.test(platform) ? "⌘" : "^";
-var HOLD_TO_PAN_KEY = " ";
+var cmdSymbol = (platform) => isApplePlatform(platform) ? "⌘" : "^";
+/** Symbols for keys in shortcut labels; other keys are shown in uppercase */
+var KEY_SYMBOLS = {
+	backspace: "⌫",
+	delete: "⌦",
+	tab: "⇥",
+	escape: "⎋",
+	enter: "↵",
+	arrowleft: "←",
+	arrowright: "→",
+	arrowup: "↑",
+	arrowdown: "↓",
+	" ": "Space"
+};
+/** Names of keys for `aria-keyshortcuts`; other keys are named as they are, in uppercase */
+var ARIA_KEY_NAMES = {
+	backspace: "Backspace",
+	delete: "Delete",
+	tab: "Tab",
+	escape: "Escape",
+	enter: "Enter",
+	arrowleft: "ArrowLeft",
+	arrowright: "ArrowRight",
+	arrowup: "ArrowUp",
+	arrowdown: "ArrowDown",
+	" ": "Space"
+};
+/**
+* A short label for a key combination, e.g. for menus: modifier symbols (^ Control, ⌥ Alt, ⇧ Shift, then ⌘ for "cmd" on
+* Apple devices or ^ elsewhere), then the key as a symbol or in uppercase.
+*
+* @example
+* shortcutLabel({ key: "z", cmd: true, shift: true }, "MacIntel"); // "⇧⌘Z"
+* shortcutLabel({ key: "backspace", alt: true }, "Win32"); // "⌥⌫"
+*/
+var shortcutLabel = (combo, platform) => [
+	combo.ctrl && "^",
+	combo.alt && "⌥",
+	combo.shift && "⇧",
+	combo.cmd && cmdSymbol(platform),
+	KEY_SYMBOLS[combo.key] ?? combo.key.toUpperCase()
+].filter(Boolean).join("");
+/**
+* A key combination as an `aria-keyshortcuts` value, so screen readers can announce it.
+*
+* @example
+* ariaKeyShortcut({ key: "s", cmd: true }, "MacIntel"); // "Meta+S"
+* ariaKeyShortcut({ key: "backspace", alt: true }, "Win32"); // "Alt+Backspace"
+*/
+var ariaKeyShortcut = (combo, platform) => [
+	(combo.ctrl || combo.cmd && !isApplePlatform(platform)) && "Control",
+	combo.cmd && isApplePlatform(platform) && "Meta",
+	combo.alt && "Alt",
+	combo.shift && "Shift",
+	ARIA_KEY_NAMES[combo.key] ?? combo.key.toUpperCase()
+].filter(Boolean).join("+");
+/** Keys that are only modifiers, which don't make a key combination on their own (lowercase) */
+var MODIFIER_KEYS = /* @__PURE__ */ new Set([
+	"shift",
+	"control",
+	"alt",
+	"altgraph",
+	"meta",
+	"os",
+	"super",
+	"hyper",
+	"fn",
+	"fnlock",
+	"capslock",
+	"numlock",
+	"scrolllock",
+	"symbol",
+	"symbollock"
+]);
+/** Characters of physical keys (by `KeyboardEvent.code`) other than letters and digits, as on a US keyboard */
+var CODE_CHARACTERS = {
+	Minus: "-",
+	Equal: "=",
+	BracketLeft: "[",
+	BracketRight: "]",
+	Backslash: "\\",
+	Semicolon: ";",
+	Quote: "'",
+	Backquote: "`",
+	Comma: ",",
+	Period: ".",
+	Slash: "/",
+	IntlBackslash: "<"
+};
+/** Keys treated as another key: `=` (typed without Shift on many keyboards) as `+` */
+var KEY_ALIASES = { "=": "+" };
 /**
-* Find the action for a key press. Modifier keys must match exactly.
+* The character of a physical key (by `KeyboardEvent.code`) as on a US keyboard, e.g. `KeyA` → `a`, `Digit5` → `5`.
 *
 * @example
-* matchShortcut({ key: "Z", metaKey: true, ctrlKey: false, shiftKey: true, altKey: false });
+* codeCharacter("KeyG"); // "g"
+* codeCharacter("BracketLeft"); // "["
+*/
+var codeCharacter = (code) => {
+	const character = /^(?:Key([A-Z])|Digit(\d)|Numpad(\d))$/.exec(code ?? "")?.slice(1).find(Boolean);
+	if (character) return character.toLowerCase();
+	return code ? CODE_CHARACTERS[code] : void 0;
+};
+/**
+* Whether a key is one printable basic Latin (ASCII) character.
+*/
+var isBasicCharacter = (key) => key.length === 1 && key >= " " && key <= "~";
+/**
+* The key combination of a key press, matching keyboards with different layouts:
+* - Keys are matched by the character they type, so letters follow the key's label (e.g. `a` on a French keyboard).
+* - Digits and symbols ignore Shift and AltGr/Option, which are often needed to type them (e.g. `<` and `[` on a
+*   German keyboard).
+* - When a key types a character that isn't basic Latin (another alphabet, or Option on macOS), or is a dead key, the
+*   physical key is used instead (e.g. `a` for `ф`, and `alt g` for Option+G typing `©`).
+* - `=` counts as `+`, so `cmd +` works with or without Shift.
+*
+* `cmd` is Command on Apple devices and Ctrl elsewhere; `ctrl` is Control on Apple devices. Undefined while composing
+* text (e.g. with an input method), for modifier keys alone, and for the Windows key elsewhere.
+*
+* @example
+* comboFromEvent({ key: "Z", metaKey: true, ctrlKey: false, shiftKey: true, altKey: false }, "MacIntel");
+* // { key: "z", cmd: true, shift: true }
+*/
+var comboFromEvent = (event, platform) => {
+	const apple = isApplePlatform(platform);
+	const typed = event.key.toLowerCase();
+	if (event.isComposing || typed === "process" || typed === "unidentified" || MODIFIER_KEYS.has(typed) || !apple && event.metaKey) return void 0;
+	const character = [...event.key].length === 1;
+	const physical = character && !isBasicCharacter(typed) || typed === "dead" ? codeCharacter(event.code) : void 0;
+	if (typed === "dead" && !physical) return void 0;
+	const key = KEY_ALIASES[physical ?? typed] ?? physical ?? typed;
+	const altGraph = event.getModifierState?.("AltGraph") ?? false;
+	const typedSymbol = character && !physical && !/^[a-z ]$/.test(key);
+	return normaliseCombo({
+		key,
+		cmd: apple ? event.metaKey : event.ctrlKey && !altGraph,
+		ctrl: apple && event.ctrlKey,
+		shift: event.shiftKey && !typedSymbol,
+		alt: event.altKey && !altGraph && !typedSymbol
+	});
+};
+/**
+* Find the action for a key press (see `comboFromEvent`). Modifier keys must match exactly.
+*
+* @example
+* matchShortcut({ key: "Z", metaKey: true, ctrlKey: false, shiftKey: true, altKey: false }, SHORTCUTS, "MacIntel");
 * // { type: "redo" }
 */
-var matchShortcut = (event, shortcuts = SHORTCUTS) => {
-	const key = event.key.toLowerCase();
-	const cmd = event.metaKey || event.ctrlKey;
-	return shortcuts.find((s) => s.key === key && Boolean(s.cmd) === cmd && Boolean(s.shift) === event.shiftKey && Boolean(s.alt) === event.altKey)?.action;
+var matchShortcut = (event, shortcuts = SHORTCUTS, platform) => {
+	const combo = comboFromEvent(event, platform);
+	return combo && shortcuts.find((shortcut) => sameCombo(shortcut, combo))?.action;
 };
 /**
+* The modifier keys held during a key press, as a key combination without a key (e.g. to show them while recording a
+* key combination). Read like `comboFromEvent`: `cmd` is Command on Apple devices and Ctrl elsewhere.
+*
+* @example
+* heldModifiers({ key: "Shift", metaKey: true, ctrlKey: false, shiftKey: true, altKey: false }, "MacIntel");
+* // { key: "", cmd: true, shift: true }
+*/
+var heldModifiers = (event, platform) => {
+	const apple = isApplePlatform(platform);
+	return normaliseCombo({
+		key: "",
+		cmd: apple ? event.metaKey : event.ctrlKey,
+		ctrl: apple && event.ctrlKey,
+		shift: event.shiftKey,
+		alt: event.altKey
+	});
+};
+/**
+* A key combination as words, e.g. for a text field: modifiers in the order shift, alt, cmd, ctrl, then the key
+* (Space as `space`). "cmd" is written `ctrl` except on Apple devices.
+*
+* @example
+* comboText({ key: "g", shift: true, alt: true, cmd: true, ctrl: true }, "MacIntel"); // "shift alt cmd ctrl g"
+* comboText({ key: "s", cmd: true }, "Win32"); // "ctrl s"
+* comboText({ key: "", shift: true }, "MacIntel"); // "shift" (modifiers only)
+*/
+var comboText = (combo, platform) => [
+	combo.shift && "shift",
+	combo.alt && "alt",
+	combo.cmd && (isApplePlatform(platform) ? "cmd" : "ctrl"),
+	combo.ctrl && "ctrl",
+	combo.key === " " ? "space" : combo.key
+].filter(Boolean).join(" ");
+/**
 * Check if a key press happened while typing in a text field, where shortcuts must not apply.
 *
 * @example
@@ -186,4 +432,4 @@ var isTypingTarget = (target) => {
 	].includes(target.type);
 	return false;
 };
-export { HOLD_TO_PAN_KEY, SHORTCUTS, cmdSymbol, isTypingTarget, matchShortcut };
+export { CONFIGURABLE_SHORTCUTS, FIXED_SHORTCUTS, HOLD_TO_PAN, SHORTCUTS, SHORTCUT_DEFINITIONS, ariaKeyShortcut, cmdSymbol, comboFromEvent, comboText, defaultShortcutBindings, fixedShortcutFor, heldModifiers, isApplePlatform, isTypingTarget, matchShortcut, normaliseCombo, sameCombo, sanitiseCombo, sanitiseShortcutBindings, shortcutLabel, shortcutsFor };

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

@@ -1,6 +1,8 @@
 // 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 {
   HistoryMessage,
   PatchMessage,
@@ -25,3 +27,6 @@ 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 validateSettings: Validator<AppSettings>;
+export declare const validateSettingsFile: Validator<SettingsFile>;