@fieldnotes/core 0.18.0 → 0.19.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Irakli Iremashvili
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Irakli Iremashvili
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -269,6 +269,35 @@ viewport.toolManager.onChange((toolName) => {
 });
 ```
 
+## Keyboard shortcuts
+
+Defaults (remappable): `Delete`/`Backspace` delete · `Escape` deselect · `mod+Z` undo ·
+`mod+Y`/`mod+Shift+Z` redo · `mod+A` select all · `mod+C/V/D` copy/paste/duplicate ·
+`[`/`]` z-order (with `mod` = to back/front) · `Shift+1` zoom-to-fit · arrows nudge
+(`Shift` = one grid cell) · tool keys `V` select, `H` hand, `P` pencil, `E` eraser,
+`A` arrow, `N` note, `T` text, `S` shape, `M` measure, `G` template.
+
+`mod` = Ctrl or Cmd. Shortcuts fire only while the canvas has focus (click it once);
+pass `shortcuts: { scope: 'window' }` for page-wide handling.
+
+```ts
+const viewport = new Viewport(el, {
+  shortcuts: {
+    bindings: {
+      duplicate: 'mod+shift+d', // remap
+      'tool:pencil': ['p', 'b'], // multiple bindings
+      copy: null, // disable
+      'tool:my-custom-tool': 'f', // any registered tool works
+    },
+  },
+});
+
+viewport.shortcuts.rebind('undo', 'mod+u');
+viewport.shortcuts.disable('select-all');
+viewport.shortcuts.reset(); // back to defaults
+viewport.shortcuts.getBindings(); // current table — render a settings UI
+```
+
 ## Changing Tool Options at Runtime
 
 All drawing tools support `setOptions()` for changing color, width, and other settings without re-creating the tool:
@@ -435,7 +464,8 @@ Works in all modern browsers supporting Pointer Events API and HTML5 Canvas.
 
 `@fieldnotes/core` and `@fieldnotes/react` are versioned independently. The react
 package's `peerDependencies` declare the compatible core range. Pre-1.0, minor
-versions may contain breaking changes.
+versions may contain breaking changes. The core peer range is bounded at the next major rather than per-minor; if a core minor
+ever breaks the wrapper, a coordinated react release raises the lower bound.
 
 ## License
 

package/dist/index.cjs

@@ -1150,14 +1150,158 @@ var KeyboardActions = class {
   }
 };
 
+// src/canvas/shortcut-map.ts
+var DEFAULT_BINDINGS = [
+  ["delete", ["delete", "backspace"]],
+  ["deselect", ["escape"]],
+  ["undo", ["mod+z"]],
+  ["redo", ["mod+y", "mod+shift+z"]],
+  ["select-all", ["mod+a"]],
+  ["copy", ["mod+c"]],
+  ["paste", ["mod+v"]],
+  ["duplicate", ["mod+d"]],
+  ["z-forward", ["]"]],
+  ["z-backward", ["["]],
+  ["z-front", ["mod+]"]],
+  ["z-back", ["mod+["]],
+  ["zoom-fit", ["shift+1"]],
+  ["nudge-left", ["arrowleft"]],
+  ["nudge-right", ["arrowright"]],
+  ["nudge-up", ["arrowup"]],
+  ["nudge-down", ["arrowdown"]],
+  ["tool:select", ["v"]],
+  ["tool:hand", ["h"]],
+  ["tool:pencil", ["p"]],
+  ["tool:eraser", ["e"]],
+  ["tool:arrow", ["a"]],
+  ["tool:note", ["n"]],
+  ["tool:text", ["t"]],
+  ["tool:shape", ["s"]],
+  ["tool:measure", ["m"]],
+  ["tool:template", ["g"]]
+];
+var ALLOW_SHIFT = /* @__PURE__ */ new Set(["nudge-left", "nudge-right", "nudge-up", "nudge-down"]);
+var MODIFIERS = /* @__PURE__ */ new Set(["mod", "ctrl", "meta", "shift", "alt"]);
+function parseBinding(binding) {
+  const parts = binding.toLowerCase().split("+");
+  const key = parts.pop();
+  if (key === void 0 || key.length === 0 || MODIFIERS.has(key)) {
+    throw new Error(`Invalid shortcut binding "${binding}": missing key`);
+  }
+  const normalizedKey = key === "space" ? " " : key;
+  const parsed = {
+    mod: false,
+    ctrl: false,
+    meta: false,
+    shift: false,
+    alt: false,
+    key: normalizedKey,
+    digit: /^[0-9]$/.test(normalizedKey)
+  };
+  for (const part of parts) {
+    switch (part) {
+      case "mod":
+        parsed.mod = true;
+        break;
+      case "ctrl":
+        parsed.ctrl = true;
+        break;
+      case "meta":
+        parsed.meta = true;
+        break;
+      case "shift":
+        parsed.shift = true;
+        break;
+      case "alt":
+        parsed.alt = true;
+        break;
+      default:
+        throw new Error(`Invalid shortcut binding "${binding}": unknown modifier "${part}"`);
+    }
+  }
+  return parsed;
+}
+function bindingMatches(p, e, allowShift) {
+  if (p.mod) {
+    if (!e.ctrlKey && !e.metaKey) return false;
+  } else if (e.ctrlKey !== p.ctrl || e.metaKey !== p.meta) {
+    return false;
+  }
+  if (!allowShift && e.shiftKey !== p.shift) return false;
+  if (e.altKey !== p.alt) return false;
+  return p.digit ? e.code === `Digit${p.key}` : e.key.toLowerCase() === p.key;
+}
+function toArray(bindings) {
+  if (bindings === null) return [];
+  return Array.isArray(bindings) ? [...bindings] : [bindings];
+}
+var ShortcutMap = class {
+  raw = /* @__PURE__ */ new Map();
+  parsed = /* @__PURE__ */ new Map();
+  constructor(overrides) {
+    this.applyDefaults();
+    if (overrides) {
+      for (const [action, bindings] of Object.entries(overrides)) {
+        this.rebind(action, bindings);
+      }
+    }
+  }
+  /** First matching action in registration order wins when bindings conflict. */
+  match(e) {
+    for (const [action, parsedList] of this.parsed) {
+      const allowShift = ALLOW_SHIFT.has(action);
+      for (const p of parsedList) {
+        if (bindingMatches(p, e, allowShift)) return action;
+      }
+    }
+    return null;
+  }
+  rebind(action, bindings) {
+    const list = toArray(bindings);
+    const parsedList = list.map(parseBinding);
+    this.raw.set(action, list);
+    this.parsed.set(action, parsedList);
+  }
+  disable(action) {
+    this.rebind(action, null);
+  }
+  reset(action) {
+    if (action === void 0) {
+      this.raw.clear();
+      this.parsed.clear();
+      this.applyDefaults();
+      return;
+    }
+    const def = DEFAULT_BINDINGS.find(([name]) => name === action);
+    if (def) {
+      this.rebind(action, [...def[1]]);
+    } else if (this.raw.has(action)) {
+      this.raw.delete(action);
+      this.parsed.delete(action);
+    }
+  }
+  getBindings() {
+    const out = {};
+    for (const [action, list] of this.raw) {
+      out[action] = [...list];
+    }
+    return out;
+  }
+  applyDefaults() {
+    for (const [action, bindings] of DEFAULT_BINDINGS) {
+      this.rebind(action, [...bindings]);
+    }
+  }
+};
+
 // src/canvas/input-handler.ts
 var ZOOM_SENSITIVITY = 1e-3;
 var MIDDLE_BUTTON = 1;
-var NUDGE_KEYS = {
-  ArrowLeft: [-1, 0],
-  ArrowRight: [1, 0],
-  ArrowUp: [0, -1],
-  ArrowDown: [0, 1]
+var NUDGE_DELTAS = {
+  "nudge-left": [-1, 0],
+  "nudge-right": [1, 0],
+  "nudge-up": [0, -1],
+  "nudge-down": [0, 1]
 };
 var InputHandler = class {
   constructor(element, camera, options = {}) {
@@ -1175,7 +1319,13 @@ var InputHandler = class {
       isToolActive: () => this.isToolActive,
       fitToContent: options.fitToContent
     });
+    this.shortcutMap = new ShortcutMap(options.shortcuts?.bindings);
+    this.scope = options.shortcuts?.scope ?? "focus";
     this.element.style.touchAction = "none";
+    if (this.scope === "focus") {
+      this.element.tabIndex = 0;
+      this.element.style.outline = "none";
+    }
     this.bind();
   }
   isPanning = false;
@@ -1194,6 +1344,8 @@ var InputHandler = class {
   deferredDown = null;
   abortController = new AbortController();
   actions;
+  shortcutMap;
+  scope;
   setToolManager(toolManager, toolContext) {
     this.toolManager = toolManager;
     this.toolContext = toolContext;
@@ -1201,6 +1353,9 @@ var InputHandler = class {
   flushPendingHistory() {
     this.actions.flushPendingNudge();
   }
+  get shortcuts() {
+    return this.shortcutMap;
+  }
   destroy() {
     this.actions.dispose();
     this.abortController.abort();
@@ -1230,6 +1385,7 @@ var InputHandler = class {
     });
   };
   onPointerDown = (e) => {
+    this.focusSelf();
     this.activePointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
     this.element.setPointerCapture?.(e.pointerId);
     if (this.activePointers.size === 2) {
@@ -1312,57 +1468,13 @@ var InputHandler = class {
     if (target?.isContentEditable) return;
     const tag = target?.tagName;
     if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return;
+    if (!this.isInScope()) return;
     if (e.key === " ") {
       this.spaceHeld = true;
     }
-    if (e.key === "Delete" || e.key === "Backspace") {
-      this.actions.deleteSelected();
-    }
-    if (e.key === "Escape") {
-      this.actions.deselect();
-    }
-    if ((e.ctrlKey || e.metaKey) && e.key === "z" && !e.shiftKey) {
-      e.preventDefault();
-      this.actions.undo();
-    }
-    if ((e.ctrlKey || e.metaKey) && (e.key === "y" || e.key === "z" && e.shiftKey)) {
-      e.preventDefault();
-      this.actions.redo();
-    }
-    if ((e.ctrlKey || e.metaKey) && e.key === "a") {
-      e.preventDefault();
-      this.actions.selectAll();
-    }
-    if ((e.ctrlKey || e.metaKey) && e.key === "c") {
-      e.preventDefault();
-      this.actions.copy();
-    }
-    if ((e.ctrlKey || e.metaKey) && e.key === "v") {
-      e.preventDefault();
-      this.actions.paste();
-    }
-    if ((e.ctrlKey || e.metaKey) && e.key === "d") {
-      e.preventDefault();
-      this.actions.duplicate();
-    }
-    if (e.key === "]") {
-      e.preventDefault();
-      this.actions.zOrder(e.ctrlKey || e.metaKey ? "front" : "forward");
-    }
-    if (e.key === "[") {
-      e.preventDefault();
-      this.actions.zOrder(e.ctrlKey || e.metaKey ? "back" : "backward");
-    }
-    if (e.shiftKey && e.code === "Digit1" && !e.ctrlKey && !e.metaKey && !e.altKey) {
-      e.preventDefault();
-      this.actions.zoomToFit();
-    }
-    const nudgeDelta = NUDGE_KEYS[e.key];
-    if (nudgeDelta) {
-      const [dx, dy] = nudgeDelta;
-      if (this.actions.nudge(dx, dy, e.shiftKey)) {
-        e.preventDefault();
-      }
+    const action = this.shortcutMap.match(e);
+    if (action !== null) {
+      this.runAction(action, e);
     }
   };
   onKeyUp = (e) => {
@@ -1377,6 +1489,79 @@ var InputHandler = class {
       }
     }
   };
+  runAction(action, e) {
+    switch (action) {
+      case "delete":
+        e.preventDefault();
+        this.actions.deleteSelected();
+        return;
+      case "deselect":
+        this.actions.deselect();
+        return;
+      case "undo":
+        e.preventDefault();
+        this.actions.undo();
+        return;
+      case "redo":
+        e.preventDefault();
+        this.actions.redo();
+        return;
+      case "select-all":
+        e.preventDefault();
+        this.actions.selectAll();
+        return;
+      case "copy":
+        e.preventDefault();
+        this.actions.copy();
+        return;
+      case "paste":
+        e.preventDefault();
+        this.actions.paste();
+        return;
+      case "duplicate":
+        e.preventDefault();
+        this.actions.duplicate();
+        return;
+      case "z-forward":
+        e.preventDefault();
+        this.actions.zOrder("forward");
+        return;
+      case "z-backward":
+        e.preventDefault();
+        this.actions.zOrder("backward");
+        return;
+      case "z-front":
+        e.preventDefault();
+        this.actions.zOrder("front");
+        return;
+      case "z-back":
+        e.preventDefault();
+        this.actions.zOrder("back");
+        return;
+      case "zoom-fit":
+        e.preventDefault();
+        this.actions.zoomToFit();
+        return;
+      case "nudge-left":
+      case "nudge-right":
+      case "nudge-up":
+      case "nudge-down": {
+        const delta = NUDGE_DELTAS[action];
+        if (delta && this.actions.nudge(delta[0], delta[1], e.shiftKey)) {
+          e.preventDefault();
+        }
+        return;
+      }
+      default:
+        if (action.startsWith("tool:")) {
+          if (this.isToolActive) return;
+          e.preventDefault();
+          this.toolContext?.switchTool?.(action.slice("tool:".length));
+          return;
+        }
+        console.warn(`[fieldnotes] unknown shortcut action "${action}"`);
+    }
+  }
   startPinch() {
     this.inputFilter.reset();
     this.deferredDown = null;
@@ -1447,6 +1632,15 @@ var InputHandler = class {
     this.toolManager.handlePointerUp(this.toPointerState(e), this.toolContext);
     this.historyRecorder?.commit();
   }
+  isInScope() {
+    if (this.scope === "window") return true;
+    const active = document.activeElement;
+    return active === this.element || this.element.contains(active);
+  }
+  focusSelf() {
+    if (this.scope !== "focus" || this.isInScope()) return;
+    this.element.focus({ preventScroll: true });
+  }
   cancelToolIfActive(e) {
     if (this.isToolActive) {
       this.dispatchToolUp(e);
@@ -4841,7 +5035,8 @@ var Viewport = class {
       toolContext: this.toolContext,
       historyRecorder: this.historyRecorder,
       historyStack: this.history,
-      fitToContent: () => this.fitToContent()
+      fitToContent: () => this.fitToContent(),
+      shortcuts: options.shortcuts
     });
     this.domNodeManager = new DomNodeManager({
       domLayer: this.domLayer,
@@ -5015,6 +5210,9 @@ var Viewport = class {
   setTool(name) {
     this.toolManager.setTool(name, this.toolContext);
   }
+  get shortcuts() {
+    return this.inputHandler.shortcuts;
+  }
   undo() {
     this.inputHandler.flushPendingHistory();
     this.historyRecorder.pause();
@@ -7053,7 +7251,7 @@ var TemplateTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.18.0";
+var VERSION = "0.19.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AddElementCommand,