@fieldnotes/core 0.32.0 → 0.34.0

package/README.md

@@ -579,6 +579,31 @@ viewport.distributeSelection('horizontal'); // equal horizontal spacing
 
 Grids are ignored by both operations.
 
+## Smart Alignment Guides
+
+Call `viewport.setSmartGuides(true)` to enable drag-time alignment snapping. While dragging a selection, its edges and centers snap to the edges and centers of nearby visible elements (within 6 screen pixels), and guide lines are drawn at each matched alignment. Smart guides replace grid snapping for the duration of the drag; the result is still committed as a single undo step.
+
+```typescript
+viewport.setSmartGuides(true);  // enable
+viewport.setSmartGuides(false); // disable (default)
+```
+
+## Grouping
+
+Group elements so they select, move, delete, z-order, and align as a single unit.
+
+- **`viewport.groupSelection()`** — groups the current selection under a new id.
+- **`viewport.ungroupSelection()`** — dissolves any groups in the current selection.
+
+Each is one undo step. Selecting any member selects its whole group, so to edit a single member individually, ungroup first. Pasting or duplicating a group keeps the copies grouped under a fresh id.
+
+```typescript
+viewport.groupSelection();   // Ctrl/Cmd+G
+viewport.ungroupSelection(); // Ctrl/Cmd+Shift+G
+```
+
+The shortcuts are rebindable as `group` and `ungroup`.
+
 ## Built-in Interactions
 
 | Input                | Action              |

package/dist/index.cjs

@@ -1021,6 +1021,14 @@ var KeyboardActions = class {
     if (this.deps.isToolActive()) return;
     this.deps.fitToContent?.();
   }
+  group() {
+    if (this.deps.isToolActive()) return;
+    this.deps.group?.();
+  }
+  ungroup() {
+    if (this.deps.isToolActive()) return;
+    this.deps.ungroup?.();
+  }
   zOrder(operation) {
     if (this.deps.isToolActive()) return;
     this.flushPendingNudge();
@@ -1054,6 +1062,10 @@ var KeyboardActions = class {
     for (const el of source) {
       idMap.set(el.id, createId(el.type));
     }
+    const groupIdMap = /* @__PURE__ */ new Map();
+    for (const el of source) {
+      if (el.groupId && !groupIdMap.has(el.groupId)) groupIdMap.set(el.groupId, createId("group"));
+    }
     const newIds = [];
     const recorder = this.deps.getHistoryRecorder();
     recorder?.begin();
@@ -1062,6 +1074,7 @@ var KeyboardActions = class {
       const newId = idMap.get(el.id);
       if (!newId) continue;
       clone.id = newId;
+      if (clone.groupId) clone.groupId = groupIdMap.get(clone.groupId) ?? clone.groupId;
       clone.position = { x: clone.position.x + offset.x, y: clone.position.y + offset.y };
       if (clone.type === "arrow") {
         const arrow = clone;
@@ -1115,6 +1128,8 @@ var DEFAULT_BINDINGS = [
   ["zoom-in", ["mod+="]],
   ["zoom-out", ["mod+-"]],
   ["zoom-reset", ["mod+0"]],
+  ["group", ["mod+g"]],
+  ["ungroup", ["mod+shift+g"]],
   ["nudge-left", ["arrowleft"]],
   ["nudge-right", ["arrowright"]],
   ["nudge-up", ["arrowup"]],
@@ -1274,6 +1289,8 @@ var InputHandler = class {
       getHistoryStack: () => this.historyStack,
       isToolActive: () => this.isToolActive,
       fitToContent: options.fitToContent,
+      group: options.group,
+      ungroup: options.ungroup,
       getLastPointerWorld: () => this.lastPointerWorld()
     });
     this.shortcutMap = new ShortcutMap(options.shortcuts?.bindings);
@@ -1513,6 +1530,14 @@ var InputHandler = class {
         e.preventDefault();
         this.actions.zoomToFit();
         return;
+      case "group":
+        e.preventDefault();
+        this.actions.group();
+        return;
+      case "ungroup":
+        e.preventDefault();
+        this.actions.ungroup();
+        return;
       case "zoom-in":
         e.preventDefault();
         this.zoomByFactor(ZOOM_STEP);
@@ -4018,12 +4043,19 @@ var UpdateElementCommand = class {
     this.current = current;
   }
   execute(store) {
-    store.update(this.id, { ...this.current });
+    store.update(this.id, diffPatch(this.previous, this.current));
   }
   undo(store) {
-    store.update(this.id, { ...this.previous });
+    store.update(this.id, diffPatch(this.current, this.previous));
   }
 };
+function diffPatch(from, to) {
+  const patch = { ...to };
+  for (const key of Object.keys(from)) {
+    if (!(key in to)) patch[key] = void 0;
+  }
+  return patch;
+}
 var BatchCommand = class {
   commands;
   constructor(commands) {
@@ -5576,7 +5608,9 @@ var Viewport = class {
       gridSize: this._gridSize,
       activeLayerId: this.layerManager.activeLayerId,
       isLayerVisible: (id) => this.layerManager.isLayerVisible(id),
-      isLayerLocked: (id) => this.layerManager.isLayerLocked(id)
+      isLayerLocked: (id) => this.layerManager.isLayerLocked(id),
+      smartGuides: false,
+      getVisibleRect: () => this.camera.getVisibleRect(this.canvasEl.clientWidth, this.canvasEl.clientHeight)
     };
     this.inputHandler = new InputHandler(this.wrapper, this.camera, {
       toolManager: this.toolManager,
@@ -5584,6 +5618,8 @@ var Viewport = class {
       historyRecorder: this.historyRecorder,
       historyStack: this.history,
       fitToContent: () => this.fitToContent(),
+      group: () => this.groupSelection(),
+      ungroup: () => this.ungroupSelection(),
       shortcuts: options.shortcuts
     });
     this.domNodeManager = new DomNodeManager({
@@ -5680,6 +5716,7 @@ var Viewport = class {
   marginViewport;
   resizeObserver = null;
   _snapToGrid = false;
+  _smartGuides = false;
   _gridSize;
   renderLoop;
   domNodeManager;
@@ -5700,6 +5737,13 @@ var Viewport = class {
     this._snapToGrid = enabled;
     this.toolContext.snapToGrid = enabled;
   }
+  get smartGuides() {
+    return this._smartGuides;
+  }
+  setSmartGuides(enabled) {
+    this._smartGuides = enabled;
+    this.toolContext.smartGuides = enabled;
+  }
   fitToContent(padding = 40) {
     if (this.wrapper.clientWidth === 0 || this.wrapper.clientHeight === 0) return;
     const visibleElements = this.store.getAll().filter((el) => this.layerManager.isLayerVisible(el.layerId));
@@ -5913,6 +5957,26 @@ var Viewport = class {
     }
     this.historyRecorder.commit();
   }
+  groupSelection() {
+    const ids = this.getSelectedIds();
+    if (ids.length < 2) return;
+    const groupId = createId("group");
+    this.historyRecorder.begin();
+    for (const id of ids) {
+      if (this.store.getById(id)) this.store.update(id, { groupId });
+    }
+    this.historyRecorder.commit();
+  }
+  ungroupSelection() {
+    const ids = this.getSelectedIds();
+    if (ids.length === 0) return;
+    this.historyRecorder.begin();
+    for (const id of ids) {
+      const el = this.store.getById(id);
+      if (el && el.groupId !== void 0) this.store.update(id, { groupId: void 0 });
+    }
+    this.historyRecorder.commit();
+  }
   alignSelection(edge) {
     const bounded = this.boundedSelection();
     if (bounded.length < 2) return;
@@ -6622,6 +6686,26 @@ var EraserTool = class {
   }
 };
 
+// src/elements/group.ts
+function expandToGroups(ids, elements) {
+  const byId = new Map(elements.map((e) => [e.id, e]));
+  const groupIds = /* @__PURE__ */ new Set();
+  for (const id of ids) {
+    const g = byId.get(id)?.groupId;
+    if (g) groupIds.add(g);
+  }
+  if (groupIds.size === 0) return ids;
+  const idSet = new Set(ids);
+  const result = [...ids];
+  for (const el of elements) {
+    if (el.groupId && groupIds.has(el.groupId) && !idSet.has(el.id)) {
+      result.push(el.id);
+      idSet.add(el.id);
+    }
+  }
+  return result;
+}
+
 // src/tools/arrow-handles.ts
 var BIND_THRESHOLD = 20;
 var HANDLE_RADIUS = 5;
@@ -6737,8 +6821,47 @@ function renderArrowHandles(canvasCtx, arrow, zoom) {
   }
 }
 
+// src/elements/snap-guides.ts
+function xAnchors(b) {
+  return { lo: b.x, mid: b.x + b.w / 2, hi: b.x + b.w };
+}
+function yAnchors(b) {
+  return { lo: b.y, mid: b.y + b.h / 2, hi: b.y + b.h };
+}
+function bestAxisSnap(moving, targets, anchorsFn, threshold) {
+  let best = null;
+  for (const t of targets) {
+    const ta = anchorsFn(t);
+    const pairs = [
+      // colinear alignment: same-type edges/centers line up
+      [ta.lo - moving.lo, ta.lo],
+      [ta.mid - moving.mid, ta.mid],
+      [ta.hi - moving.hi, ta.hi],
+      // abutment: the moving box sits flush against the target's opposite edge
+      [ta.lo - moving.hi, ta.lo],
+      [ta.hi - moving.lo, ta.hi]
+    ];
+    for (const [delta, position] of pairs) {
+      const abs = Math.abs(delta);
+      if (abs <= threshold && (best === null || abs < Math.abs(best.delta))) {
+        best = { delta, position };
+      }
+    }
+  }
+  return best;
+}
+function computeSnapGuides(moving, targets, threshold) {
+  const xSnap = bestAxisSnap(xAnchors(moving), targets, xAnchors, threshold);
+  const ySnap = bestAxisSnap(yAnchors(moving), targets, yAnchors, threshold);
+  const guides = [];
+  if (xSnap) guides.push({ axis: "x", position: xSnap.position });
+  if (ySnap) guides.push({ axis: "y", position: ySnap.position });
+  return { dx: xSnap?.delta ?? 0, dy: ySnap?.delta ?? 0, guides };
+}
+
 // src/tools/select-tool.ts
 var HANDLE_SIZE = 8;
+var SNAP_PX = 6;
 var HANDLE_HIT_PADDING2 = 4;
 var SELECTION_PAD = 4;
 var MIN_ELEMENT_SIZE = 20;
@@ -6758,6 +6881,9 @@ var SelectTool = class {
   ctx = null;
   pendingSingleSelectId = null;
   hasDragged = false;
+  activeGuides = [];
+  dragSnapTargets = null;
+  dragVisibleRect = null;
   resizeAspectRatio = 0;
   hoveredId = null;
   get selectedIds() {
@@ -6789,6 +6915,9 @@ var SelectTool = class {
     this.setSelectedIds([]);
     this.mode = { type: "idle" };
     this.hoveredId = null;
+    this.activeGuides = [];
+    this.dragSnapTargets = null;
+    this.dragVisibleRect = null;
     ctx.setCursor?.("default");
   }
   snap(point, ctx) {
@@ -6797,6 +6926,8 @@ var SelectTool = class {
   onPointerDown(state, ctx) {
     this.ctx = ctx;
     this.setHovered(null, ctx);
+    this.dragSnapTargets = null;
+    this.dragVisibleRect = null;
     const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
     this.lastWorld = this.snap(world, ctx);
     this.currentWorld = world;
@@ -6840,18 +6971,20 @@ var SelectTool = class {
     this.hasDragged = false;
     const hit = this.hitTest(world, ctx);
     if (hit) {
+      const all = ctx.store.getAll();
       const alreadySelected = this._selectedIds.includes(hit.id);
       if (state.shiftKey) {
         if (alreadySelected) {
-          this.setSelectedIds(this._selectedIds.filter((id) => id !== hit.id));
+          const grp = new Set(expandToGroups([hit.id], all));
+          this.setSelectedIds(this._selectedIds.filter((id) => !grp.has(id)));
           this.mode = { type: "idle" };
         } else {
-          this.setSelectedIds([...this._selectedIds, hit.id]);
+          this.setSelectedIds(expandToGroups([...this._selectedIds, hit.id], all));
           this.mode = hit.locked ? { type: "idle" } : { type: "dragging" };
         }
       } else {
         if (!alreadySelected) {
-          this.setSelectedIds([hit.id]);
+          this.setSelectedIds(expandToGroups([hit.id], all));
         } else if (this._selectedIds.length > 1) {
           this.pendingSingleSelectId = hit.id;
         }
@@ -6897,6 +7030,31 @@ var SelectTool = class {
       const dx = snapped.x - this.lastWorld.x;
       const dy = snapped.y - this.lastWorld.y;
       this.lastWorld = snapped;
+      let adjDx = dx;
+      let adjDy = dy;
+      this.activeGuides = [];
+      if (ctx.smartGuides) {
+        if (this.dragSnapTargets === null) {
+          const selSet = new Set(this._selectedIds);
+          this.dragVisibleRect = ctx.getVisibleRect?.() ?? null;
+          const candidates = (this.dragVisibleRect ? ctx.store.queryRect(this.dragVisibleRect) : ctx.store.getAll()).filter((el) => !selSet.has(el.id) && el.type !== "grid");
+          const targets = [];
+          for (const el of candidates) {
+            const b = getElementBounds(el);
+            if (b) targets.push(b);
+          }
+          this.dragSnapTargets = targets;
+        }
+        const selectedEls = this._selectedIds.map((id) => ctx.store.getById(id)).filter((el) => !!el && !el.locked);
+        const base = getElementsBoundingBox(selectedEls);
+        if (base) {
+          const moving = { x: base.x + dx, y: base.y + dy, w: base.w, h: base.h };
+          const res = computeSnapGuides(moving, this.dragSnapTargets, SNAP_PX / ctx.camera.zoom);
+          adjDx = dx + res.dx;
+          adjDy = dy + res.dy;
+          this.activeGuides = res.guides;
+        }
+      }
       for (const id of this._selectedIds) {
         const el = ctx.store.getById(id);
         if (!el || el.locked) continue;
@@ -6905,13 +7063,13 @@ var SelectTool = class {
             continue;
           }
           ctx.store.update(id, {
-            position: { x: el.position.x + dx, y: el.position.y + dy },
-            from: { x: el.from.x + dx, y: el.from.y + dy },
-            to: { x: el.to.x + dx, y: el.to.y + dy }
+            position: { x: el.position.x + adjDx, y: el.position.y + adjDy },
+            from: { x: el.from.x + adjDx, y: el.from.y + adjDy },
+            to: { x: el.to.x + adjDx, y: el.to.y + adjDy }
           });
-        } else if (ctx.gridType && "size" in el) {
-          const centerX = el.position.x + el.size.w / 2 + dx;
-          const centerY = el.position.y + el.size.h / 2 + dy;
+        } else if (!ctx.smartGuides && ctx.gridType && "size" in el) {
+          const centerX = el.position.x + el.size.w / 2 + adjDx;
+          const centerY = el.position.y + el.size.h / 2 + adjDy;
           const snappedCenter = this.snap({ x: centerX, y: centerY }, ctx);
           ctx.store.update(id, {
             position: {
@@ -6921,7 +7079,7 @@ var SelectTool = class {
           });
         } else {
           ctx.store.update(id, {
-            position: { x: el.position.x + dx, y: el.position.y + dy }
+            position: { x: el.position.x + adjDx, y: el.position.y + adjDy }
           });
         }
       }
@@ -6940,17 +7098,21 @@ var SelectTool = class {
     if (this.mode.type === "marquee") {
       const rect = this.getMarqueeRect();
       if (rect) {
-        this.setSelectedIds(this.findElementsInRect(rect, ctx));
+        this.setSelectedIds(expandToGroups(this.findElementsInRect(rect, ctx), ctx.store.getAll()));
       }
       ctx.requestRender();
     }
     if (!this.hasDragged && this.pendingSingleSelectId !== null) {
-      this.setSelectedIds([this.pendingSingleSelectId]);
+      this.setSelectedIds(expandToGroups([this.pendingSingleSelectId], ctx.store.getAll()));
     }
     this.pendingSingleSelectId = null;
     this.hasDragged = false;
     const resizedNoteId = this.mode.type === "resizing" ? this.mode.elementId : null;
     this.mode = { type: "idle" };
+    this.activeGuides = [];
+    this.dragSnapTargets = null;
+    this.dragVisibleRect = null;
+    ctx.requestRender();
     ctx.setCursor?.("default");
     if (resizedNoteId !== null) {
       const el = ctx.store.getById(resizedNoteId);
@@ -6998,6 +7160,32 @@ var SelectTool = class {
         }
       }
     }
+    this.renderGuideLines(canvasCtx);
+  }
+  renderGuideLines(canvasCtx) {
+    if (this.mode.type !== "dragging" || !this.ctx || this.activeGuides.length === 0) return;
+    const zoom = this.ctx.camera.zoom;
+    const rect = this.dragVisibleRect;
+    canvasCtx.save();
+    canvasCtx.strokeStyle = "#FF4081";
+    canvasCtx.lineWidth = 1 / zoom;
+    canvasCtx.setLineDash([]);
+    for (const g of this.activeGuides) {
+      canvasCtx.beginPath();
+      if (g.axis === "x") {
+        const y0 = rect ? rect.y : this.currentWorld.y - 1e5;
+        const y1 = rect ? rect.y + rect.h : this.currentWorld.y + 1e5;
+        canvasCtx.moveTo(g.position, y0);
+        canvasCtx.lineTo(g.position, y1);
+      } else {
+        const x0 = rect ? rect.x : this.currentWorld.x - 1e5;
+        const x1 = rect ? rect.x + rect.w : this.currentWorld.x + 1e5;
+        canvasCtx.moveTo(x0, g.position);
+        canvasCtx.lineTo(x1, g.position);
+      }
+      canvasCtx.stroke();
+    }
+    canvasCtx.restore();
   }
   updateArrowsBoundTo(ids, ctx) {
     updateArrowsBoundToElements(ids, ctx.store);
@@ -8200,7 +8388,7 @@ var TemplateTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.32.0";
+var VERSION = "0.34.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ArrowTool,