@lvl99dotcom/paintcanvas 0.3.1 → 0.5.0

package/dist/lib/utils/shortcuts/index.d.ts

@@ -1,16 +1,24 @@
-import { Tool } from "../../classes/PaintCanvas";
+import { Tool } from "../../classes/PaintCanvas/tool";
 /** Actions that keyboard shortcuts trigger */
 export type ShortcutAction = {
     type: "tool";
     tool: Tool;
+} | {
+    type: "pan";
 } | {
     type: "brush-smaller";
 } | {
     type: "brush-bigger";
+} | {
+    type: "brush-less-opaque";
+} | {
+    type: "brush-more-opaque";
 } | {
     type: "toggle-interface";
 } | {
     type: "select-all";
+} | {
+    type: "invert-selection";
 } | {
     type: "deselect";
 } | {
@@ -31,21 +39,124 @@ export type ShortcutAction = {
     type: "cancel";
 } | {
     type: "commit";
+} | {
+    type: "fill-foreground";
+} | {
+    type: "fill-background";
+} | {
+    type: "swap-colours";
+} | {
+    type: "zoom-in";
+} | {
+    type: "zoom-out";
+} | {
+    type: "reset-zoom";
+} | {
+    type: "layer-opacity";
+    opacity: number;
 };
-/** A key combination. `cmd` matches the Command key on macOS and Ctrl on Windows/Linux. */
+/**
+ * A key combination. `cmd` is the Command key on Apple devices and Ctrl elsewhere; `ctrl` is the Control key on Apple
+ * devices only (elsewhere Ctrl is `cmd`).
+ */
 export interface KeyCombo {
-    /** Lowercase `KeyboardEvent.key` value */
+    /** Lowercase `KeyboardEvent.key` value, e.g. `a`, `[`, `backspace` or ` ` (Space) */
     key: string;
     cmd?: boolean;
+    ctrl?: boolean;
     shift?: boolean;
     alt?: boolean;
 }
+/** A key combination and the action it runs */
 export interface Shortcut extends KeyCombo {
     action: ShortcutAction;
 }
-/** All keyboard shortcuts */
+/** Groups shortcuts are listed in, e.g. in the keyboard shortcuts settings */
+export type ShortcutGroup = "tools" | "brushes" | "masking" | "fills" | "viewport" | "layers" | "clipboard" | "history" | "general";
+/** A keyboard shortcut action and its default key combinations */
+export interface ShortcutDefinition {
+    /** Names the action, e.g. to save its key combination and to translate its name (`paintCanvas.shortcuts.<id>`) */
+    id: string;
+    group: ShortcutGroup;
+    action: ShortcutAction;
+    /** Default key combinations (a configurable action has one) */
+    combos: readonly KeyCombo[];
+    /** Whether users can change or remove its key combination */
+    configurable: boolean;
+}
+/** ID of the action run while its key is held: pan, returning to the last tool when released */
+export declare const HOLD_TO_PAN = "pan";
+/** Every keyboard shortcut action, in the order they are listed */
+export declare const SHORTCUT_DEFINITIONS: readonly ShortcutDefinition[];
+/** The actions users can change the key combinations of */
+export declare const CONFIGURABLE_SHORTCUTS: readonly ShortcutDefinition[];
+/** The actions whose key combinations can't be changed */
+export declare const FIXED_SHORTCUTS: readonly ShortcutDefinition[];
+/** The key combination of each configurable action, by ID (null when it has none) */
+export type ShortcutBindings = Record<string, KeyCombo | null>;
+/**
+ * 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 }
+ */
+export declare const normaliseCombo: ({ key, cmd, ctrl, shift, alt, }: KeyCombo) => KeyCombo;
+/**
+ * Whether two key combinations are the same.
+ *
+ * @example
+ * sameCombo({ key: "s", cmd: true }, { key: "s", cmd: true, shift: false }); // true
+ */
+export declare const sameCombo: (a: KeyCombo, b: KeyCombo) => boolean;
+/**
+ * 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
+ */
+export declare const sanitiseCombo: (input: unknown) => KeyCombo | undefined;
+/**
+ * The default key combination of each configurable action.
+ *
+ * @example
+ * defaultShortcutBindings()["tool-brush"]; // { key: "b" }
+ */
+export declare const defaultShortcutBindings: () => ShortcutBindings;
+/**
+ * The fixed action that uses a key combination, if any.
+ *
+ * @example
+ * fixedShortcutFor({ key: "z", cmd: true })?.id; // "undo"
+ */
+export declare const fixedShortcutFor: (combo: KeyCombo) => ShortcutDefinition | undefined;
+/**
+ * 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());
+ */
+export declare const sanitiseShortcutBindings: (input: unknown, defaults: ShortcutBindings) => ShortcutBindings;
+/**
+ * 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 }
+ */
+export declare const shortcutsFor: (bindings: ShortcutBindings) => Shortcut[];
+/** All keyboard shortcuts with their default key combinations */
 export declare const SHORTCUTS: readonly Shortcut[];
-/** Key held to pan temporarily (handled separately because it acts while held, not on press) */
+/**
+ * Whether a platform (`navigator.platform` by default) is an Apple device, where "cmd" is the Command key.
+ *
+ * @example
+ * isApplePlatform("MacIntel"); // true
+ * isApplePlatform("Win32"); // false
+ */
+export declare const isApplePlatform: (platform?: string) => boolean;
 /**
  * The symbol for the "cmd" key in shortcut labels: ⌘ on Apple devices, ^ (Control) elsewhere.
  *
@@ -54,17 +165,69 @@ export declare const SHORTCUTS: readonly Shortcut[];
  * cmdSymbol("Win32"); // "^"
  */
 export declare const cmdSymbol: (platform?: string) => string;
-export declare const HOLD_TO_PAN_KEY = " ";
-/** The parts of a keyboard event used to match shortcuts */
-export type KeyEventLike = Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "shiftKey" | "altKey">;
 /**
- * Find the action for a key press. Modifier keys must match exactly.
+ * 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"); // "⌥⌫"
+ */
+export declare const shortcutLabel: (combo: KeyCombo, platform?: string) => string;
+/**
+ * A key combination as an `aria-keyshortcuts` value, so screen readers can announce it.
  *
  * @example
- * matchShortcut({ key: "Z", metaKey: true, ctrlKey: false, shiftKey: true, altKey: false });
+ * ariaKeyShortcut({ key: "s", cmd: true }, "MacIntel"); // "Meta+S"
+ * ariaKeyShortcut({ key: "backspace", alt: true }, "Win32"); // "Alt+Backspace"
+ */
+export declare const ariaKeyShortcut: (combo: KeyCombo, platform?: string) => string;
+/** The parts of a keyboard event used to read key combinations */
+export type KeyEventLike = Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "shiftKey" | "altKey"> & Partial<Pick<KeyboardEvent, "code" | "isComposing" | "getModifierState">>;
+/**
+ * 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 }
+ */
+export declare const comboFromEvent: (event: KeyEventLike, platform?: string) => KeyCombo | undefined;
+/**
+ * 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" }
  */
-export declare const matchShortcut: (event: KeyEventLike, shortcuts?: readonly Shortcut[]) => ShortcutAction | undefined;
+export declare const matchShortcut: (event: KeyEventLike, shortcuts?: readonly Shortcut[], platform?: string) => ShortcutAction | undefined;
+/**
+ * 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 }
+ */
+export declare const heldModifiers: (event: KeyEventLike, platform?: string) => KeyCombo;
+/**
+ * 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)
+ */
+export declare const comboText: (combo: KeyCombo, platform?: string) => string;
 /**
  * Check if a key press happened while typing in a text field, where shortcuts must not apply.
  *