@heyramzi/ui 1.54.1 → 2.0.0

package/src/canvas/editor/keymap.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it } from "vite-plus/test";
+import {
+  resolveEditorKeyAction,
+  resolveNudge,
+  isEditingTarget,
+  isPanActivationKey,
+} from "./keymap.js";
+
+function press(
+  key: string,
+  opts: { meta?: boolean; shift?: boolean; editing?: boolean } = {},
+): KeyboardEvent {
+  const target = opts.editing ? { tagName: "INPUT" } : { tagName: "DIV" };
+  return {
+    key,
+    metaKey: opts.meta ?? false,
+    ctrlKey: false,
+    shiftKey: opts.shift ?? false,
+    target,
+  } as unknown as KeyboardEvent;
+}
+
+describe("resolveEditorKeyAction", () => {
+  it("maps the undo and redo chords", () => {
+    expect(resolveEditorKeyAction(press("z", { meta: true }), false)).toBe("undo");
+    expect(resolveEditorKeyAction(press("z", { meta: true, shift: true }), false)).toBe("redo");
+    expect(resolveEditorKeyAction(press("y", { meta: true }), false)).toBe("redo");
+  });
+
+  it("maps the clipboard chords, and leaves them to a field being typed in", () => {
+    expect(resolveEditorKeyAction(press("c", { meta: true }), false)).toBe("copy");
+    expect(resolveEditorKeyAction(press("v", { meta: true }), false)).toBe("paste");
+    expect(resolveEditorKeyAction(press("a", { meta: true }), false)).toBe("select-all");
+    expect(resolveEditorKeyAction(press("c", { meta: true, editing: true }), false)).toBeNull();
+    expect(resolveEditorKeyAction(press("a", { meta: true, editing: true }), false)).toBeNull();
+  });
+
+  it("saves whatever has focus", () => {
+    expect(resolveEditorKeyAction(press("s", { meta: true }), false)).toBe("save");
+    expect(resolveEditorKeyAction(press("s", { meta: true, editing: true }), false)).toBe("save");
+  });
+
+  it("deletes only with a selection, and never while typing", () => {
+    expect(resolveEditorKeyAction(press("Delete"), true)).toBe("delete");
+    expect(resolveEditorKeyAction(press("Backspace"), true)).toBe("delete");
+    expect(resolveEditorKeyAction(press("Delete"), false)).toBeNull();
+    expect(resolveEditorKeyAction(press("Backspace", { editing: true }), true)).toBeNull();
+  });
+
+  it("claims nothing else", () => {
+    expect(resolveEditorKeyAction(press("Tab"), true)).toBeNull();
+    expect(resolveEditorKeyAction(press("k"), true)).toBeNull();
+    expect(resolveEditorKeyAction(press("b", { meta: true }), true)).toBeNull();
+  });
+});
+
+describe("isEditingTarget", () => {
+  it("names the elements that own their own keys", () => {
+    expect(isEditingTarget({ tagName: "INPUT" } as unknown as EventTarget)).toBe(true);
+    expect(isEditingTarget({ tagName: "TEXTAREA" } as unknown as EventTarget)).toBe(true);
+    expect(
+      isEditingTarget({ tagName: "DIV", isContentEditable: true } as unknown as EventTarget),
+    ).toBe(true);
+    expect(isEditingTarget({ tagName: "DIV" } as unknown as EventTarget)).toBe(false);
+    expect(isEditingTarget(null)).toBe(false);
+  });
+});
+
+describe("isPanActivationKey", () => {
+  function space(
+    target: Record<string, unknown> = { tagName: "DIV" },
+    mods: { meta?: boolean; ctrl?: boolean; alt?: boolean } = {},
+  ): KeyboardEvent {
+    return {
+      code: "Space",
+      key: " ",
+      metaKey: mods.meta ?? false,
+      ctrlKey: mods.ctrl ?? false,
+      altKey: mods.alt ?? false,
+      target: { getAttribute: () => null, ...target },
+    } as unknown as KeyboardEvent;
+  }
+
+  it("is the hand tool over the canvas", () => {
+    expect(isPanActivationKey(space())).toBe(true);
+  });
+
+  it("leaves space to a field being typed in", () => {
+    expect(isPanActivationKey(space({ tagName: "TEXTAREA" }))).toBe(false);
+    expect(isPanActivationKey(space({ tagName: "DIV", isContentEditable: true }))).toBe(false);
+  });
+
+  it("leaves space to a control that activates on it", () => {
+    expect(isPanActivationKey(space({ tagName: "BUTTON" }))).toBe(false);
+    expect(isPanActivationKey(space({ tagName: "DIV", getAttribute: () => "button" }))).toBe(false);
+  });
+
+  it("claims no other key, and no chord", () => {
+    expect(isPanActivationKey({ code: "KeyS", key: "s" } as KeyboardEvent)).toBe(false);
+    expect(isPanActivationKey(space({ tagName: "DIV" }, { meta: true }))).toBe(false);
+  });
+});
+
+describe("the editor chords and zoom keys", () => {
+  const code = (key: string, codeName: string, shift = false) =>
+    ({
+      key,
+      code: codeName,
+      metaKey: false,
+      ctrlKey: false,
+      altKey: false,
+      shiftKey: shift,
+      target: { tagName: "DIV" },
+    }) as unknown as KeyboardEvent;
+
+  it("maps duplicate, group and ungroup", () => {
+    expect(resolveEditorKeyAction(press("d", { meta: true }), false)).toBe("duplicate");
+    expect(resolveEditorKeyAction(press("g", { meta: true }), false)).toBe("group");
+    expect(resolveEditorKeyAction(press("g", { meta: true, shift: true }), false)).toBe("ungroup");
+    expect(resolveEditorKeyAction(press("d", { meta: true, editing: true }), false)).toBeNull();
+  });
+
+  it("maps chord and plain zoom", () => {
+    expect(resolveEditorKeyAction(press("=", { meta: true }), false)).toBe("zoom-in");
+    expect(resolveEditorKeyAction(press("-", { meta: true }), false)).toBe("zoom-out");
+    expect(resolveEditorKeyAction(code("+", "Equal", true), false)).toBe("zoom-in");
+    expect(resolveEditorKeyAction(code("-", "Minus"), false)).toBe("zoom-out");
+  });
+
+  it("maps Shift with 0, 1 and 2 by key code", () => {
+    expect(resolveEditorKeyAction(code(")", "Digit0", true), false)).toBe("zoom-100");
+    expect(resolveEditorKeyAction(code("!", "Digit1", true), false)).toBe("zoom-fit");
+    expect(resolveEditorKeyAction(code("@", "Digit2", true), false)).toBe("zoom-selection");
+  });
+
+  it("stays out of a field being typed in", () => {
+    expect(resolveEditorKeyAction(press("-", { editing: true }), false)).toBeNull();
+  });
+});
+
+describe("resolveNudge", () => {
+  const arrow = (key: string, shift = false, editing = false) =>
+    ({
+      key,
+      metaKey: false,
+      ctrlKey: false,
+      altKey: false,
+      shiftKey: shift,
+      target: { tagName: editing ? "TEXTAREA" : "DIV" },
+    }) as unknown as KeyboardEvent;
+
+  it("moves 1px, or 10px with Shift", () => {
+    expect(resolveNudge(arrow("ArrowLeft"))).toEqual({ dx: -1, dy: 0 });
+    expect(resolveNudge(arrow("ArrowDown", true))).toEqual({ dx: 0, dy: 10 });
+  });
+
+  it("ignores other keys and fields", () => {
+    expect(resolveNudge(arrow("a"))).toBeNull();
+    expect(resolveNudge(arrow("ArrowUp", false, true))).toBeNull();
+  });
+});

package/src/canvas/editor/keymap.ts

@@ -0,0 +1,151 @@
+// The canvas keyboard map, as a resolver rather than a switch in the editor.
+// Mirrors resolveMindmapKeyAction in mindmap-keyboard.ts, which the mode
+// controllers already read.
+
+export type EditorKeyAction =
+  | "undo"
+  | "redo"
+  | "copy"
+  | "paste"
+  | "select-all"
+  | "save"
+  | "delete"
+  | "duplicate"
+  | "group"
+  | "ungroup"
+  | "zoom-in"
+  | "zoom-out"
+  | "zoom-100"
+  | "zoom-fit"
+  | "zoom-selection"
+  | "bring-forward"
+  | "send-backward"
+  | "bring-to-front"
+  | "send-to-back"
+  | "lock"
+  | "copy-as-png"
+  | "present";
+
+/** True while the event's target owns its own text editing. */
+export function isEditingTarget(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null;
+  const tag = el?.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || el?.isContentEditable === true;
+}
+
+/** The action a key means on the canvas, or null when the canvas does not own it. */
+export function resolveEditorKeyAction(
+  event: KeyboardEvent,
+  hasSelection: boolean,
+): EditorKeyAction | null {
+  const key = event.key.toLowerCase();
+  const mod = event.metaKey || event.ctrlKey;
+  const editing = isEditingTarget(event.target);
+  if (mod) return modAction(key, event.shiftKey, editing);
+  if (event.key === "Delete" || event.key === "Backspace") {
+    return hasSelection && !editing ? "delete" : null;
+  }
+  return editing || event.altKey ? null : plainAction(event);
+}
+
+/** Shift with a digit zooms. Read by code, so a layout that moves the digits still works. */
+const SHIFT_ZOOM = new Map<string, EditorKeyAction>([
+  ["Digit0", "zoom-100"],
+  ["Digit1", "zoom-fit"],
+  ["Digit2", "zoom-selection"],
+]);
+
+const PLAIN_KEYS = new Map<string, EditorKeyAction>([
+  ["]", "bring-forward"],
+  ["[", "send-backward"],
+  ["+", "zoom-in"],
+  ["=", "zoom-in"],
+  ["-", "zoom-out"],
+  ["_", "zoom-out"],
+]);
+
+/** Zoom keys with no chord: + and -, and Shift with 0, 1 or 2. */
+function plainAction(event: KeyboardEvent): EditorKeyAction | null {
+  const zoom = event.shiftKey ? SHIFT_ZOOM.get(event.code) : undefined;
+  return zoom ?? PLAIN_KEYS.get(event.key) ?? null;
+}
+
+/** The move an arrow key asks for: 1px, or 10px with Shift. Null for anything else, or while a field owns the keys. */
+export function resolveNudge(event: KeyboardEvent): { dx: number; dy: number } | null {
+  if (event.metaKey || event.ctrlKey || event.altKey || isEditingTarget(event.target)) return null;
+  const step = event.shiftKey ? 10 : 1;
+  switch (event.key) {
+    case "ArrowLeft":
+      return { dx: -step, dy: 0 };
+    case "ArrowRight":
+      return { dx: step, dy: 0 };
+    case "ArrowUp":
+      return { dx: 0, dy: -step };
+    case "ArrowDown":
+      return { dx: 0, dy: step };
+    default:
+      return null;
+  }
+}
+
+/** What a chord means without Shift, then with it. Null where that variant is not ours. */
+type Chord = readonly [plain: EditorKeyAction | null, shifted: EditorKeyAction | null];
+
+const both = (action: EditorKeyAction): Chord => [action, action];
+
+const CHORDS = new Map<string, Chord>([
+  ["c", ["copy", "copy-as-png"]],
+  ["v", both("paste")],
+  ["a", both("select-all")],
+  ["d", ["duplicate", null]],
+  ["g", ["group", "ungroup"]],
+  ["l", [null, "lock"]],
+  ["]", both("bring-to-front")],
+  ["[", both("send-to-back")],
+  ["enter", both("present")],
+  ["=", both("zoom-in")],
+  ["+", both("zoom-in")],
+  ["-", both("zoom-out")],
+  ["_", both("zoom-out")],
+]);
+
+/** The chord half of the map. `editing` is true while a field owns the keys. */
+function modAction(key: string, shift: boolean, editing: boolean): EditorKeyAction | null {
+  if (key === "z") return shift ? "redo" : "undo";
+  if (key === "y") return "redo";
+  // Save works whatever has focus, and whatever the autosave preference is.
+  if (key === "s" && !shift) return "save";
+  // Cut, copy, paste and select-all belong to the focused field while one is
+  // being typed in; the canvas only claims them otherwise.
+  if (editing) return null;
+  return CHORDS.get(key)?.[shift ? 1 : 0] ?? null;
+}
+
+/** Tags and roles that activate on Space themselves, so the canvas must not steal it. */
+const SPACE_OWNING_TAGS = new Set(["BUTTON", "A", "SUMMARY", "SELECT", "OPTION"]);
+const SPACE_OWNING_ROLES = new Set([
+  "button",
+  "checkbox",
+  "switch",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "radio",
+  "tab",
+]);
+
+/** Space means hand tool over the canvas, never in a field or on a Space-activating control. Reads code, so remapped layouts still pan. */
+export function isPanActivationKey(event: KeyboardEvent): boolean {
+  if (event.code !== "Space" && event.key !== " ") return false;
+  if (event.metaKey || event.ctrlKey || event.altKey) return false;
+  if (isEditingTarget(event.target)) return false;
+  return !ownsSpace(event.target as HTMLElement | null);
+}
+
+/** A control that already does something on Space: a button, a checkbox, a tab. */
+function ownsSpace(el: HTMLElement | null): boolean {
+  if (el?.tagName && SPACE_OWNING_TAGS.has(el.tagName)) return true;
+  const role = el?.getAttribute?.("role");
+  return Boolean(role && SPACE_OWNING_ROLES.has(role));
+}

package/src/canvas/editor/layout-actions.test.ts

@@ -0,0 +1,156 @@
+import { expectDefined } from "../test-utils.js";
+import { describe, it, expect } from "vite-plus/test";
+import { alignNodes, groupSelectionOps, tidyGroup } from "./layout-actions.js";
+
+function pos(id: string, x: number, y: number) {
+  return { id, position: { x, y } };
+}
+
+describe("alignNodes", () => {
+  it("returns empty map for fewer than 2 nodes", () => {
+    const result = alignNodes([pos("a", 10, 20)], "left");
+    expect(result.size).toBe(0);
+  });
+
+  it("aligns left to minimum x", () => {
+    const result = alignNodes([pos("a", 100, 0), pos("b", 200, 0), pos("c", 50, 0)], "left");
+    expect(expectDefined(result.get("a"), "entry a").x).toBe(50);
+    expect(expectDefined(result.get("b"), "entry b").x).toBe(50);
+    expect(expectDefined(result.get("c"), "entry c").x).toBe(50);
+  });
+
+  it("aligns right to maximum x", () => {
+    const result = alignNodes([pos("a", 100, 0), pos("b", 200, 0)], "right");
+    expect(expectDefined(result.get("a"), "entry a").x).toBe(200);
+    expect(expectDefined(result.get("b"), "entry b").x).toBe(200);
+  });
+
+  it("aligns top to minimum y", () => {
+    const result = alignNodes([pos("a", 0, 100), pos("b", 0, 50)], "top");
+    expect(expectDefined(result.get("a"), "entry a").y).toBe(50);
+    expect(expectDefined(result.get("b"), "entry b").y).toBe(50);
+  });
+
+  it("aligns bottom to maximum y", () => {
+    const result = alignNodes([pos("a", 0, 100), pos("b", 0, 200)], "bottom");
+    expect(expectDefined(result.get("a"), "entry a").y).toBe(200);
+    expect(expectDefined(result.get("b"), "entry b").y).toBe(200);
+  });
+
+  it("center-h aligns to minimum x (vertical center)", () => {
+    const result = alignNodes([pos("a", 100, 0), pos("b", 200, 0)], "center-h");
+    // alignNodesVertically sets all to min x
+    expect(expectDefined(result.get("a"), "entry a").x).toBe(100);
+    expect(expectDefined(result.get("b"), "entry b").x).toBe(100);
+  });
+
+  it("center-v aligns to average y", () => {
+    const result = alignNodes([pos("a", 0, 100), pos("b", 0, 200), pos("c", 0, 300)], "center-v");
+    expect(expectDefined(result.get("a"), "entry a").y).toBe(200);
+    expect(expectDefined(result.get("b"), "entry b").y).toBe(200);
+    expect(expectDefined(result.get("c"), "entry c").y).toBe(200);
+  });
+
+  it("does not mutate input positions", () => {
+    const nodes = [pos("a", 100, 0), pos("b", 200, 0)];
+    alignNodes(nodes, "left");
+    expect(nodes[0].position.x).toBe(100);
+    expect(nodes[1].position.x).toBe(200);
+  });
+});
+
+describe("groupSelectionOps", () => {
+  const box = (id: string, x: number, y: number, parentId?: string) => ({
+    id,
+    position: { x, y },
+    measured: { width: 100, height: 50 },
+    ...(parentId ? { parentId } : {}),
+  });
+
+  it("refuses to group fewer than two nodes", () => {
+    expect(groupSelectionOps([box("a", 0, 0)], "Group")).toEqual([]);
+  });
+
+  it("draws the box around the selection and re-parents every member", () => {
+    const ops = groupSelectionOps([box("a", 100, 100), box("b", 300, 200)], "Group");
+    const [add, ...rest] = ops;
+
+    expect(add).toMatchObject({
+      kind: "addNode",
+      node: {
+        type: "group",
+        // 32 of padding on every side, plus 36 of title row above.
+        position: { x: 68, y: 32 },
+        width: 364,
+        height: 250,
+      },
+    });
+
+    const groupId = (add as { node: { id: string } }).node.id;
+    expect(rest).toEqual([
+      { kind: "setParent", nodeId: "a", parentId: groupId, extent: "parent" },
+      { kind: "moveNode", nodeId: "a", position: { x: 32, y: 68 } },
+      { kind: "setParent", nodeId: "b", parentId: groupId, extent: "parent" },
+      { kind: "moveNode", nodeId: "b", position: { x: 232, y: 168 } },
+    ]);
+  });
+
+  it("takes only the members sharing the first one's parent, and joins it", () => {
+    const ops = groupSelectionOps(
+      [box("a", 0, 0, "p1"), box("b", 100, 0, "p1"), box("loose", 900, 900)],
+      "Group",
+    );
+    expect(ops).toHaveLength(5);
+    expect(ops[0]).toMatchObject({ kind: "addNode", node: { parentId: "p1" } });
+    expect(ops.some((op) => "nodeId" in op && op.nodeId === "loose")).toBe(false);
+  });
+});
+
+describe("tidyGroup", () => {
+  const box = (id: string, x: number, y: number, width: number, height: number) => ({
+    id,
+    position: { x, y },
+    measured: { width, height },
+  });
+
+  it("has nothing to tidy in an empty group", () => {
+    expect(tidyGroup([])).toBeNull();
+  });
+
+  it("keeps side-by-side cards in one row, stacks the rest, and fits the box", () => {
+    const result = expectDefined(
+      tidyGroup([
+        box("card2", 800, 110, 640, 220),
+        box("title", 0, 10, 200, 30),
+        box("card1", 5, 120, 750, 500),
+        box("subtitle", 5, 70, 600, 20),
+      ]),
+      "tidy result",
+    );
+
+    // 32 of padding, 36 of title row, 24 between rows and between cards.
+    expect(Object.fromEntries(result.positions)).toEqual({
+      title: { x: 32, y: 68 },
+      subtitle: { x: 32, y: 122 },
+      card1: { x: 32, y: 166 },
+      card2: { x: 806, y: 166 },
+    });
+    expect(result.size).toEqual({ width: 1478, height: 698 });
+  });
+
+  it("pulls overlapping nodes apart along their row", () => {
+    const result = expectDefined(
+      tidyGroup([box("b", 10, 5, 100, 50), box("a", 0, 0, 100, 50)]),
+      "tidy result",
+    );
+    expect(result.positions.get("a")).toEqual({ x: 32, y: 68 });
+    expect(result.positions.get("b")).toEqual({ x: 156, y: 68 });
+  });
+
+  it("never shrinks the box below the container minimum", () => {
+    expect(expectDefined(tidyGroup([box("a", 400, 400, 10, 10)]), "tidy result").size).toEqual({
+      width: 250,
+      height: 150,
+    });
+  });
+});

package/src/canvas/editor/layout-actions.ts

@@ -0,0 +1,219 @@
+import type { CanvasOp } from "../ops/ops.js";
+import type { CanvasNode } from "../types.js";
+import { alignNodesHorizontally, alignNodesVertically } from "../headless/alignment.js";
+
+/** The smallest a group frame gets. An app passes its own to `tidyGroup`. */
+const DEFAULT_GROUP_MIN = { width: 250, height: 150 } as const;
+
+type AlignDirection = "left" | "right" | "top" | "bottom" | "center-h" | "center-v";
+
+type Positioned = { id: string; position: { x: number; y: number } };
+
+function setX(nodes: Positioned[], x: number): void {
+  for (const n of nodes) n.position.x = x;
+}
+
+function setY(nodes: Positioned[], y: number): void {
+  for (const n of nodes) n.position.y = y;
+}
+
+const ALIGNERS: Record<AlignDirection, (nodes: Positioned[]) => void> = {
+  left: (nodes) => setX(nodes, Math.min(...nodes.map((n) => n.position.x))),
+  right: (nodes) => setX(nodes, Math.max(...nodes.map((n) => n.position.x))),
+  top: (nodes) => alignNodesHorizontally(nodes as CanvasNode[]),
+  bottom: (nodes) => setY(nodes, Math.max(...nodes.map((n) => n.position.y))),
+  "center-h": (nodes) => alignNodesVertically(nodes as CanvasNode[]),
+  "center-v": (nodes) =>
+    setY(nodes, nodes.reduce((sum, n) => sum + n.position.y, 0) / nodes.length),
+};
+
+/**
+ * Compute new positions for the given nodes based on alignment direction.
+ * Returns a Map of nodeId to new position.
+ */
+export function alignNodes(
+  selected: Positioned[],
+  direction: AlignDirection,
+): Map<string, { x: number; y: number }> {
+  if (selected.length < 2) return new Map();
+
+  const mutableNodes = selected.map((n) => ({
+    id: n.id,
+    position: { ...n.position },
+  }));
+  ALIGNERS[direction](mutableNodes);
+
+  return new Map(mutableNodes.map((n) => [n.id, n.position]));
+}
+
+const TIDY_GAP = 40;
+
+/**
+ * Distribute selected nodes evenly along their dominant axis.
+ * Detects whether nodes are mostly horizontal or vertical and
+ * equalizes gaps while preserving the cross-axis positions.
+ */
+export function tidySelectedNodes(
+  selected: Array<{
+    id: string;
+    position: { x: number; y: number };
+    measured?: { width?: number; height?: number };
+    width?: number;
+    height?: number;
+  }>,
+): Map<string, { x: number; y: number }> {
+  if (selected.length < 2) return new Map();
+
+  const xs = selected.map((n) => n.position.x);
+  const ys = selected.map((n) => n.position.y);
+  const xSpread = Math.max(...xs) - Math.min(...xs);
+  const ySpread = Math.max(...ys) - Math.min(...ys);
+
+  const horizontal = xSpread >= ySpread;
+
+  const sorted = [...selected].sort((a, b) =>
+    horizontal ? a.position.x - b.position.x : a.position.y - b.position.y,
+  );
+
+  return horizontal ? stackAlongX(sorted) : stackAlongY(sorted);
+}
+
+type Tidyable = Parameters<typeof tidySelectedNodes>[0][number];
+
+function stackAlongX(sorted: Tidyable[]): Map<string, { x: number; y: number }> {
+  const result = new Map<string, { x: number; y: number }>();
+  let cursorX = sorted[0].position.x;
+  for (const node of sorted) {
+    result.set(node.id, { x: cursorX, y: node.position.y });
+    cursorX += (node.measured?.width ?? node.width ?? 200) + TIDY_GAP;
+  }
+  return result;
+}
+
+function stackAlongY(sorted: Tidyable[]): Map<string, { x: number; y: number }> {
+  const result = new Map<string, { x: number; y: number }>();
+  let cursorY = sorted[0].position.y;
+  for (const node of sorted) {
+    result.set(node.id, { x: node.position.x, y: cursorY });
+    cursorY += (node.measured?.height ?? node.height ?? 100) + TIDY_GAP;
+  }
+  return result;
+}
+
+// A group box drawn around a selection: the padding on every side, plus the
+// room the container's own title row takes at the top.
+const GROUP_PADDING = 32;
+const GROUP_HEADER = 36;
+
+type Measurable = {
+  id: string;
+  position: { x: number; y: number };
+  measured?: { width?: number; height?: number };
+  width?: number;
+  height?: number;
+  parentId?: string;
+};
+
+const GROUP_GAP = 24;
+const ROW_TOLERANCE = 8;
+
+/**
+ * Tidy a group's direct children: rows by reading order, even gaps, then the
+ * box fitted around them. Null when the group is empty.
+ */
+export function tidyGroup(
+  children: Measurable[],
+  min: { width: number; height: number } = DEFAULT_GROUP_MIN,
+): {
+  positions: Map<string, { x: number; y: number }>;
+  size: { width: number; height: number };
+} | null {
+  if (children.length === 0) return null;
+  const width = (n: Measurable) => n.measured?.width ?? n.width ?? 200;
+  const height = (n: Measurable) => n.measured?.height ?? n.height ?? 100;
+
+  // A node joins the current row when it overlaps it vertically by more than a hair.
+  const rows: { bottom: number; items: Measurable[] }[] = [];
+  for (const n of [...children].sort((a, b) => a.position.y - b.position.y)) {
+    const row = rows.at(-1);
+    if (row && n.position.y < row.bottom - ROW_TOLERANCE) {
+      row.items.push(n);
+      row.bottom = Math.max(row.bottom, n.position.y + height(n));
+    } else {
+      rows.push({ bottom: n.position.y + height(n), items: [n] });
+    }
+  }
+
+  const positions = new Map<string, { x: number; y: number }>();
+  let y = GROUP_PADDING + GROUP_HEADER;
+  let right = 0;
+  for (const row of rows) {
+    let x = GROUP_PADDING;
+    for (const n of row.items.sort((a, b) => a.position.x - b.position.x)) {
+      positions.set(n.id, { x, y });
+      x += width(n) + GROUP_GAP;
+    }
+    right = Math.max(right, x - GROUP_GAP);
+    y += Math.max(...row.items.map(height)) + GROUP_GAP;
+  }
+
+  return {
+    positions,
+    size: {
+      width: Math.max(min.width, right + GROUP_PADDING),
+      height: Math.max(min.height, y - GROUP_GAP + GROUP_PADDING),
+    },
+  };
+}
+
+export type GroupOptions = {
+  /** The node type of the frame. Defaults to "group". */
+  type?: string;
+  /** Extra `data` on the frame beside its label. */
+  data?: Record<string, unknown>;
+};
+
+/** Wrap a selection in a frame node, or [] when there is nothing to group. */
+export function groupSelectionOps(
+  selected: Measurable[],
+  groupLabel: string,
+  { type = "group", data = {} }: GroupOptions = {},
+): CanvasOp[] {
+  if (selected.length < 2) return [];
+  const parentId = selected[0].parentId;
+  const members = selected.filter((n) => n.parentId === parentId);
+  if (members.length < 2) return [];
+
+  const width = (n: Measurable) => n.measured?.width ?? n.width ?? 200;
+  const height = (n: Measurable) => n.measured?.height ?? n.height ?? 100;
+  const minX = Math.min(...members.map((n) => n.position.x));
+  const minY = Math.min(...members.map((n) => n.position.y));
+  const maxX = Math.max(...members.map((n) => n.position.x + width(n)));
+  const maxY = Math.max(...members.map((n) => n.position.y + height(n)));
+
+  const origin = { x: minX - GROUP_PADDING, y: minY - GROUP_PADDING - GROUP_HEADER };
+  const groupId = crypto.randomUUID();
+
+  return [
+    {
+      kind: "addNode",
+      node: {
+        id: groupId,
+        type,
+        position: origin,
+        data: { ...data, label: groupLabel },
+        width: maxX - minX + GROUP_PADDING * 2,
+        height: maxY - minY + GROUP_PADDING * 2 + GROUP_HEADER,
+        ...(parentId ? { parentId } : {}),
+      },
+    },
+    ...members.flatMap((n): CanvasOp[] => [
+      { kind: "setParent", nodeId: n.id, parentId: groupId, extent: "parent" },
+      {
+        kind: "moveNode",
+        nodeId: n.id,
+        position: { x: n.position.x - origin.x, y: n.position.y - origin.y },
+      },
+    ]),
+  ];
+}