@treelocator/runtime 0.5.2 → 0.6.0

package/dist/functions/getUsableName.test.js

@@ -0,0 +1,219 @@
+import { describe, expect, test } from "vitest";
+import { getUsableName } from "./getUsableName";
+describe("getUsableName", () => {
+  test("returns 'Not found' when fiber is null", () => {
+    expect(getUsableName(null)).toBe("Not found");
+  });
+  test("returns 'Not found' when fiber is undefined", () => {
+    expect(getUsableName(undefined)).toBe("Not found");
+  });
+  test("returns string elementType directly", () => {
+    const fiber = {
+      elementType: "div"
+    };
+    expect(getUsableName(fiber)).toBe("div");
+  });
+  test("returns 'Anonymous' when elementType is null", () => {
+    const fiber = {
+      elementType: null
+    };
+    expect(getUsableName(fiber)).toBe("Anonymous");
+  });
+  test("returns elementType.name when available", () => {
+    const fiber = {
+      elementType: {
+        name: "MyComponent"
+      }
+    };
+    expect(getUsableName(fiber)).toBe("MyComponent");
+  });
+  test("returns elementType.displayName when name unavailable", () => {
+    const fiber = {
+      elementType: {
+        displayName: "MyComponent"
+      }
+    };
+    expect(getUsableName(fiber)).toBe("MyComponent");
+  });
+  test("prefers name over displayName", () => {
+    const fiber = {
+      elementType: {
+        name: "FromName",
+        displayName: "FromDisplayName"
+      }
+    };
+    expect(getUsableName(fiber)).toBe("FromName");
+  });
+  test("handles React.memo with type.name", () => {
+    const fiber = {
+      elementType: {
+        type: {
+          name: "MemoizedComponent"
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("MemoizedComponent");
+  });
+  test("handles React.memo with type.displayName", () => {
+    const fiber = {
+      elementType: {
+        type: {
+          displayName: "MemoizedComponent"
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("MemoizedComponent");
+  });
+  test("prefers type.name over type.displayName", () => {
+    const fiber = {
+      elementType: {
+        type: {
+          name: "FromName",
+          displayName: "FromDisplayName"
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("FromName");
+  });
+  test("handles React.forwardRef with render.name", () => {
+    const fiber = {
+      elementType: {
+        render: {
+          name: "ForwardRefComponent"
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("ForwardRefComponent");
+  });
+  test("handles React.forwardRef with render.displayName", () => {
+    const fiber = {
+      elementType: {
+        render: {
+          displayName: "ForwardRefComponent"
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("ForwardRefComponent");
+  });
+  test("prefers render.name over render.displayName", () => {
+    const fiber = {
+      elementType: {
+        render: {
+          name: "FromName",
+          displayName: "FromDisplayName"
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("FromName");
+  });
+  test("handles React.lazy with _payload._result.name", () => {
+    const fiber = {
+      elementType: {
+        _payload: {
+          _result: {
+            name: "LazyComponent"
+          }
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("LazyComponent");
+  });
+  test("handles React.lazy with _payload._result.displayName", () => {
+    const fiber = {
+      elementType: {
+        _payload: {
+          _result: {
+            displayName: "LazyComponent"
+          }
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("LazyComponent");
+  });
+  test("prefers _payload._result.name over displayName", () => {
+    const fiber = {
+      elementType: {
+        _payload: {
+          _result: {
+            name: "FromName",
+            displayName: "FromDisplayName"
+          }
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("FromName");
+  });
+  test("falls back to fiber.type.name when elementType doesn't have name", () => {
+    const fiber = {
+      elementType: {},
+      type: {
+        name: "TypeComponent"
+      }
+    };
+    expect(getUsableName(fiber)).toBe("TypeComponent");
+  });
+  test("ignores fiber.type when it equals elementType", () => {
+    const elementType = {
+      name: "Component"
+    };
+    const fiber = {
+      elementType,
+      type: elementType
+    };
+    expect(getUsableName(fiber)).toBe("Component");
+  });
+  test("ignores fiber.type when it is a string", () => {
+    const fiber = {
+      elementType: {},
+      type: "div"
+    };
+    expect(getUsableName(fiber)).toBe("Anonymous");
+  });
+  test("returns 'Anonymous' when all fallbacks fail", () => {
+    const fiber = {
+      elementType: {},
+      type: {}
+    };
+    expect(getUsableName(fiber)).toBe("Anonymous");
+  });
+  test("follows priority order correctly", () => {
+    // elementType.name should be used before type.name
+    const fiber = {
+      elementType: {
+        name: "ElementTypeComponent"
+      },
+      type: {
+        name: "TypeComponent"
+      }
+    };
+    expect(getUsableName(fiber)).toBe("ElementTypeComponent");
+  });
+  test("handles deeply nested fiber with multiple name sources", () => {
+    const fiber = {
+      elementType: {
+        render: {
+          name: "VeryNested"
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("VeryNested");
+  });
+  test("handles missing _payload gracefully", () => {
+    const fiber = {
+      elementType: {
+        _payload: null
+      }
+    };
+    expect(getUsableName(fiber)).toBe("Anonymous");
+  });
+  test("handles missing _result in _payload gracefully", () => {
+    const fiber = {
+      elementType: {
+        _payload: {
+          _result: null
+        }
+      }
+    };
+    expect(getUsableName(fiber)).toBe("Anonymous");
+  });
+});

package/dist/functions/isCombinationModifiersPressed.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/functions/isCombinationModifiersPressed.test.js

@@ -0,0 +1,192 @@
+import { describe, expect, test, beforeEach, afterEach } from "vitest";
+import { isCombinationModifiersPressed, getMouseModifiers } from "./isCombinationModifiersPressed";
+describe("getMouseModifiers", () => {
+  afterEach(() => {
+    delete document.documentElement.dataset.locatorMouseModifiers;
+  });
+  test("returns default alt modifier when not set", () => {
+    const modifiers = getMouseModifiers();
+    expect(modifiers).toEqual({
+      alt: true
+    });
+  });
+  test("parses single modifier from dataset", () => {
+    document.documentElement.dataset.locatorMouseModifiers = "ctrl";
+    const modifiers = getMouseModifiers();
+    expect(modifiers).toEqual({
+      ctrl: true
+    });
+  });
+  test("parses multiple modifiers separated by +", () => {
+    document.documentElement.dataset.locatorMouseModifiers = "ctrl+shift";
+    const modifiers = getMouseModifiers();
+    expect(modifiers).toEqual({
+      ctrl: true,
+      shift: true
+    });
+  });
+  test("parses three modifiers", () => {
+    document.documentElement.dataset.locatorMouseModifiers = "ctrl+alt+shift";
+    const modifiers = getMouseModifiers();
+    expect(modifiers).toEqual({
+      ctrl: true,
+      alt: true,
+      shift: true
+    });
+  });
+  test("parses meta modifier", () => {
+    document.documentElement.dataset.locatorMouseModifiers = "meta";
+    const modifiers = getMouseModifiers();
+    expect(modifiers).toEqual({
+      meta: true
+    });
+  });
+});
+describe("isCombinationModifiersPressed", () => {
+  afterEach(() => {
+    delete document.documentElement.dataset.locatorMouseModifiers;
+  });
+  describe("default alt modifier", () => {
+    test("returns true when altKey is true", () => {
+      const event = new KeyboardEvent("keydown", {
+        altKey: true
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(true);
+    });
+    test("returns false when altKey is false", () => {
+      const event = new KeyboardEvent("keydown", {
+        altKey: false
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(false);
+    });
+    test("returns false when ctrlKey is true", () => {
+      const event = new KeyboardEvent("keydown", {
+        altKey: true,
+        ctrlKey: true
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(false);
+    });
+    test("returns false when ctrlKey is true but altKey is false", () => {
+      const event = new KeyboardEvent("keydown", {
+        altKey: false,
+        ctrlKey: true
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(false);
+    });
+    test("returns false when metaKey is true but altKey is false", () => {
+      const event = new KeyboardEvent("keydown", {
+        altKey: false,
+        metaKey: true
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(false);
+    });
+  });
+  describe("custom ctrl+alt modifier", () => {
+    beforeEach(() => {
+      document.documentElement.dataset.locatorMouseModifiers = "ctrl+alt";
+    });
+    test("returns true when both ctrl and alt are true", () => {
+      const event = new KeyboardEvent("keydown", {
+        ctrlKey: true,
+        altKey: true
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(true);
+    });
+    test("returns false when only ctrl is true", () => {
+      const event = new KeyboardEvent("keydown", {
+        ctrlKey: true,
+        altKey: false
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(false);
+    });
+    test("returns false when only alt is true", () => {
+      const event = new KeyboardEvent("keydown", {
+        ctrlKey: false,
+        altKey: true
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(false);
+    });
+    test("returns false when neither ctrl nor alt are true", () => {
+      const event = new KeyboardEvent("keydown", {
+        ctrlKey: false,
+        altKey: false
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(false);
+    });
+  });
+  describe("shift modifier handling", () => {
+    test("shift not configured allows shift to be pressed without affecting result", () => {
+      document.documentElement.dataset.locatorMouseModifiers = "alt";
+      const event = new KeyboardEvent("keydown", {
+        altKey: true,
+        shiftKey: true
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(true);
+    });
+    test("shift configured requires shift to be pressed", () => {
+      document.documentElement.dataset.locatorMouseModifiers = "alt+shift";
+      const event = new KeyboardEvent("keydown", {
+        altKey: true,
+        shiftKey: false
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(false);
+    });
+    test("shift configured returns true when shift is pressed", () => {
+      document.documentElement.dataset.locatorMouseModifiers = "alt+shift";
+      const event = new KeyboardEvent("keydown", {
+        altKey: true,
+        shiftKey: true
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(true);
+    });
+  });
+  describe("rightClick parameter", () => {
+    beforeEach(() => {
+      document.documentElement.dataset.locatorMouseModifiers = "alt";
+    });
+    test("rightClick=true ignores ctrlKey requirement", () => {
+      const event = new KeyboardEvent("keydown", {
+        altKey: true,
+        ctrlKey: false
+      });
+      expect(isCombinationModifiersPressed(event, true)).toBe(true);
+    });
+    test("rightClick=true still requires alt", () => {
+      const event = new KeyboardEvent("keydown", {
+        altKey: false,
+        metaKey: false
+      });
+      expect(isCombinationModifiersPressed(event, true)).toBe(false);
+    });
+    test("rightClick=true checks metaKey", () => {
+      const event = new KeyboardEvent("keydown", {
+        altKey: true,
+        metaKey: true
+      });
+      expect(isCombinationModifiersPressed(event, true)).toBe(false);
+    });
+    test("rightClick=true with meta modifier configured", () => {
+      document.documentElement.dataset.locatorMouseModifiers = "meta";
+      const event = new KeyboardEvent("keydown", {
+        altKey: false,
+        metaKey: true
+      });
+      expect(isCombinationModifiersPressed(event, true)).toBe(true);
+    });
+  });
+  describe("MouseEvent support", () => {
+    test("works with MouseEvent", () => {
+      const event = new MouseEvent("click", {
+        altKey: true
+      });
+      expect(isCombinationModifiersPressed(event)).toBe(true);
+    });
+    test("rightClick parameter works with MouseEvent", () => {
+      document.documentElement.dataset.locatorMouseModifiers = "alt";
+      const event = new MouseEvent("click", {
+        altKey: true
+      });
+      expect(isCombinationModifiersPressed(event, true)).toBe(true);
+    });
+  });
+});

package/dist/functions/mergeRects.test.js

@@ -1,7 +1,7 @@
 import { mergeRects } from "./mergeRects";
 import { describe, expect, test } from "vitest";
 describe("mergeRects", () => {
-  test("basic", () => {
+  test("basic overlapping rects", () => {
     const a = {
       x: 0,
       y: 0,
@@ -20,4 +20,213 @@ describe("mergeRects", () => {
     expect(res.width).toEqual(15);
     expect(res.height).toEqual(15);
   });
+  test("non-overlapping rects side by side", () => {
+    const a = {
+      x: 0,
+      y: 0,
+      width: 10,
+      height: 10
+    };
+    const b = {
+      x: 10,
+      y: 0,
+      width: 10,
+      height: 10
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(0);
+    expect(res.y).toEqual(0);
+    expect(res.width).toEqual(20);
+    expect(res.height).toEqual(10);
+  });
+  test("non-overlapping rects vertically separated", () => {
+    const a = {
+      x: 0,
+      y: 0,
+      width: 10,
+      height: 10
+    };
+    const b = {
+      x: 0,
+      y: 10,
+      width: 10,
+      height: 10
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(0);
+    expect(res.y).toEqual(0);
+    expect(res.width).toEqual(10);
+    expect(res.height).toEqual(20);
+  });
+  test("identical rects", () => {
+    const a = {
+      x: 5,
+      y: 5,
+      width: 10,
+      height: 10
+    };
+    const b = {
+      x: 5,
+      y: 5,
+      width: 10,
+      height: 10
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(5);
+    expect(res.y).toEqual(5);
+    expect(res.width).toEqual(10);
+    expect(res.height).toEqual(10);
+  });
+  test("one rect fully contains another", () => {
+    const a = {
+      x: 0,
+      y: 0,
+      width: 20,
+      height: 20
+    };
+    const b = {
+      x: 5,
+      y: 5,
+      width: 10,
+      height: 10
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(0);
+    expect(res.y).toEqual(0);
+    expect(res.width).toEqual(20);
+    expect(res.height).toEqual(20);
+  });
+  test("small rect contains large rect", () => {
+    const a = {
+      x: 5,
+      y: 5,
+      width: 10,
+      height: 10
+    };
+    const b = {
+      x: 0,
+      y: 0,
+      width: 20,
+      height: 20
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(0);
+    expect(res.y).toEqual(0);
+    expect(res.width).toEqual(20);
+    expect(res.height).toEqual(20);
+  });
+  test("zero-area rect (point)", () => {
+    const a = {
+      x: 5,
+      y: 5,
+      width: 0,
+      height: 0
+    };
+    const b = {
+      x: 10,
+      y: 10,
+      width: 10,
+      height: 10
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(5);
+    expect(res.y).toEqual(5);
+    expect(res.width).toEqual(15);
+    expect(res.height).toEqual(15);
+  });
+  test("both rects have zero area", () => {
+    const a = {
+      x: 5,
+      y: 5,
+      width: 0,
+      height: 0
+    };
+    const b = {
+      x: 10,
+      y: 10,
+      width: 0,
+      height: 0
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(5);
+    expect(res.y).toEqual(5);
+    expect(res.width).toEqual(5);
+    expect(res.height).toEqual(5);
+  });
+  test("negative coordinates", () => {
+    const a = {
+      x: -10,
+      y: -10,
+      width: 20,
+      height: 20
+    };
+    const b = {
+      x: 5,
+      y: 5,
+      width: 10,
+      height: 10
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(-10);
+    expect(res.y).toEqual(-10);
+    expect(res.width).toEqual(25);
+    expect(res.height).toEqual(25);
+  });
+  test("both rects with negative coordinates", () => {
+    const a = {
+      x: -20,
+      y: -20,
+      width: 10,
+      height: 10
+    };
+    const b = {
+      x: -15,
+      y: -15,
+      width: 10,
+      height: 10
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(-20);
+    expect(res.y).toEqual(-20);
+    expect(res.width).toEqual(15);
+    expect(res.height).toEqual(15);
+  });
+  test("rects with large coordinates", () => {
+    const a = {
+      x: 1000,
+      y: 1000,
+      width: 100,
+      height: 100
+    };
+    const b = {
+      x: 1050,
+      y: 1050,
+      width: 100,
+      height: 100
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(1000);
+    expect(res.y).toEqual(1000);
+    expect(res.width).toEqual(150);
+    expect(res.height).toEqual(150);
+  });
+  test("rects with fractional coordinates and dimensions", () => {
+    const a = {
+      x: 1.5,
+      y: 2.5,
+      width: 3.5,
+      height: 4.5
+    };
+    const b = {
+      x: 4,
+      y: 5,
+      width: 2,
+      height: 2
+    };
+    const res = mergeRects(a, b);
+    expect(res.x).toEqual(1.5);
+    expect(res.y).toEqual(2.5);
+    expect(res.width).toEqual(4.5);
+    expect(res.height).toEqual(4.5);
+  });
 });

package/dist/functions/namedSnapshots.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Named element snapshots persisted in localStorage.
+ *
+ * Workflow: takeSnapshot(selector, id) → change code → getSnapshotDiff(id).
+ * Stored snapshots are immutable — getSnapshotDiff never overwrites the
+ * baseline, so iterating on a fix always diffs against the original state.
+ */
+import { StyleSnapshot } from "./extractComputedStyles";
+export interface StoredSnapshot {
+    snapshotId: string;
+    selector: string;
+    index: number;
+    label?: string;
+    takenAt: string;
+    snapshot: StyleSnapshot;
+}
+export interface TakeSnapshotResult {
+    snapshotId: string;
+    selector: string;
+    index: number;
+    takenAt: string;
+    propertyCount: number;
+    boundingRect: StyleSnapshot["boundingRect"];
+}
+export interface SnapshotDiffResult {
+    snapshotId: string;
+    selector: string;
+    index: number;
+    takenAt: string;
+    formatted: string;
+    changes: Array<{
+        type: "added" | "removed" | "changed";
+        property: string;
+        before?: string;
+        after?: string;
+    }>;
+    boundingRectChanges: Array<{
+        key: "x" | "y" | "width" | "height";
+        before: number;
+        after: number;
+    }>;
+}
+export declare class NamedSnapshotError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function takeNamedSnapshot(selector: string, snapshotId: string, options?: {
+    index?: number;
+    label?: string;
+}): TakeSnapshotResult;
+export declare function getNamedSnapshotDiff(snapshotId: string): SnapshotDiffResult;
+export declare function clearNamedSnapshot(snapshotId: string): void;