@treelocator/runtime 0.4.7 → 0.6.0

package/src/functions/formatAncestryChain.test.ts

@@ -2,7 +2,6 @@ import { describe, it, expect } from "vitest";
 import {
   AncestryItem,
   formatAncestryChain,
-  collectAncestry,
   truncateAtFirstFile,
 } from "./formatAncestryChain";
 
@@ -49,6 +48,29 @@ describe("formatAncestryChain", () => {
     );
   });
 
+  it("includes classes after the id", () => {
+    const items: AncestryItem[] = [
+      {
+        elementName: "button",
+        componentName: "Button",
+        id: "save",
+        classes: ["btn", "btn-primary"],
+      },
+    ];
+
+    const result = formatAncestryChain(items);
+    expect(result).toBe("Button#save.btn.btn-primary");
+  });
+
+  it("includes classes without id", () => {
+    const items: AncestryItem[] = [
+      { elementName: "div", classes: ["card", "card--featured"] },
+    ];
+
+    const result = formatAncestryChain(items);
+    expect(result).toBe("div.card.card--featured");
+  });
+
   it("includes both nth-child and ID at component boundary", () => {
     const items: AncestryItem[] = [
       {

package/src/functions/formatAncestryChain.ts

@@ -16,6 +16,7 @@ export interface AncestryItem {
   filePath?: string;
   line?: number;
   id?: string;
+  classes?: string[];
   nthChild?: number; // 1-indexed, only set when there are ambiguous siblings
   /** All owner components from outermost (Sidebar) to innermost (GlassPanel) */
   ownerComponents?: OwnerComponentInfo[];
@@ -60,6 +61,20 @@ function treeNodeComponentToOwnerInfo(
   };
 }
 
+/**
+ * Build a short label for the innermost (clicked) element in an ancestry array.
+ * Used as the header for computed-style extraction output.
+ *
+ * Example: `"Button at src/components/Button.tsx:23"` or `"div"` as a fallback.
+ */
+export function getElementLabel(ancestry: AncestryItem[]): string {
+  if (ancestry.length === 0) return "";
+  const item = ancestry[0]!;
+  const name = item.componentName || item.elementName;
+  const location = item.filePath ? ` at ${item.filePath}:${item.line}` : "";
+  return `${name}${location}`;
+}
+
 export function collectAncestry(node: TreeNode): AncestryItem[] {
   const items: AncestryItem[] = [];
   let current: TreeNode | null = node;
@@ -84,6 +99,9 @@ export function collectAncestry(node: TreeNode): AncestryItem[] {
         if (element.id) {
           item.id = element.id;
         }
+        if (element.classList.length > 0) {
+          item.classes = Array.from(element.classList);
+        }
         const nthChild = getNthChildIfAmbiguous(element);
         if (nthChild !== undefined) {
           item.nthChild = nthChild;
@@ -254,7 +272,7 @@ export function formatAncestryChain(items: AncestryItem[]): string {
       }
     }
 
-    // Build element selector: displayName:nth-child(n)#id
+    // Build element selector: displayName:nth-child(n)#id.class1.class2
     let selector = displayName;
     if (item.nthChild !== undefined) {
       selector += `:nth-child(${item.nthChild})`;
@@ -262,6 +280,9 @@ export function formatAncestryChain(items: AncestryItem[]): string {
     if (item.id) {
       selector += `#${item.id}`;
     }
+    if (item.classes && item.classes.length > 0) {
+      selector += "." + item.classes.join(".");
+    }
 
     let description = selector;
 

package/src/functions/getUsableName.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, test } from "vitest";
+import { getUsableName } from "./getUsableName";
+import { Fiber } from "@locator/shared";
+
+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",
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("div");
+  });
+
+  test("returns 'Anonymous' when elementType is null", () => {
+    const fiber = {
+      elementType: null,
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("Anonymous");
+  });
+
+  test("returns elementType.name when available", () => {
+    const fiber = {
+      elementType: {
+        name: "MyComponent",
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("MyComponent");
+  });
+
+  test("returns elementType.displayName when name unavailable", () => {
+    const fiber = {
+      elementType: {
+        displayName: "MyComponent",
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("MyComponent");
+  });
+
+  test("prefers name over displayName", () => {
+    const fiber = {
+      elementType: {
+        name: "FromName",
+        displayName: "FromDisplayName",
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("FromName");
+  });
+
+  test("handles React.memo with type.name", () => {
+    const fiber = {
+      elementType: {
+        type: {
+          name: "MemoizedComponent",
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("MemoizedComponent");
+  });
+
+  test("handles React.memo with type.displayName", () => {
+    const fiber = {
+      elementType: {
+        type: {
+          displayName: "MemoizedComponent",
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("MemoizedComponent");
+  });
+
+  test("prefers type.name over type.displayName", () => {
+    const fiber = {
+      elementType: {
+        type: {
+          name: "FromName",
+          displayName: "FromDisplayName",
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("FromName");
+  });
+
+  test("handles React.forwardRef with render.name", () => {
+    const fiber = {
+      elementType: {
+        render: {
+          name: "ForwardRefComponent",
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("ForwardRefComponent");
+  });
+
+  test("handles React.forwardRef with render.displayName", () => {
+    const fiber = {
+      elementType: {
+        render: {
+          displayName: "ForwardRefComponent",
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("ForwardRefComponent");
+  });
+
+  test("prefers render.name over render.displayName", () => {
+    const fiber = {
+      elementType: {
+        render: {
+          name: "FromName",
+          displayName: "FromDisplayName",
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("FromName");
+  });
+
+  test("handles React.lazy with _payload._result.name", () => {
+    const fiber = {
+      elementType: {
+        _payload: {
+          _result: {
+            name: "LazyComponent",
+          },
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("LazyComponent");
+  });
+
+  test("handles React.lazy with _payload._result.displayName", () => {
+    const fiber = {
+      elementType: {
+        _payload: {
+          _result: {
+            displayName: "LazyComponent",
+          },
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("LazyComponent");
+  });
+
+  test("prefers _payload._result.name over displayName", () => {
+    const fiber = {
+      elementType: {
+        _payload: {
+          _result: {
+            name: "FromName",
+            displayName: "FromDisplayName",
+          },
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("FromName");
+  });
+
+  test("falls back to fiber.type.name when elementType doesn't have name", () => {
+    const fiber = {
+      elementType: {},
+      type: {
+        name: "TypeComponent",
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("TypeComponent");
+  });
+
+  test("ignores fiber.type when it equals elementType", () => {
+    const elementType = { name: "Component" };
+    const fiber = {
+      elementType,
+      type: elementType,
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("Component");
+  });
+
+  test("ignores fiber.type when it is a string", () => {
+    const fiber = {
+      elementType: {},
+      type: "div",
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("Anonymous");
+  });
+
+  test("returns 'Anonymous' when all fallbacks fail", () => {
+    const fiber = {
+      elementType: {},
+      type: {},
+    } as any as Fiber;
+    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",
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("ElementTypeComponent");
+  });
+
+  test("handles deeply nested fiber with multiple name sources", () => {
+    const fiber = {
+      elementType: {
+        render: {
+          name: "VeryNested",
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("VeryNested");
+  });
+
+  test("handles missing _payload gracefully", () => {
+    const fiber = {
+      elementType: {
+        _payload: null,
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("Anonymous");
+  });
+
+  test("handles missing _result in _payload gracefully", () => {
+    const fiber = {
+      elementType: {
+        _payload: {
+          _result: null,
+        },
+      },
+    } as any as Fiber;
+    expect(getUsableName(fiber)).toBe("Anonymous");
+  });
+});

package/src/functions/isCombinationModifiersPressed.test.ts

@@ -0,0 +1,156 @@
+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/src/functions/mergeRects.test.ts

@@ -3,7 +3,7 @@ import { SimpleDOMRect } from "../types/types";
 import { describe, expect, test } from "vitest";
 
 describe("mergeRects", () => {
-  test("basic", () => {
+  test("basic overlapping rects", () => {
     const a: SimpleDOMRect = { x: 0, y: 0, width: 10, height: 10 };
     const b: SimpleDOMRect = { x: 5, y: 5, width: 10, height: 10 };
     const res = mergeRects(a, b);
@@ -12,4 +12,114 @@ describe("mergeRects", () => {
     expect(res.width).toEqual(15);
     expect(res.height).toEqual(15);
   });
+
+  test("non-overlapping rects side by side", () => {
+    const a: SimpleDOMRect = { x: 0, y: 0, width: 10, height: 10 };
+    const b: SimpleDOMRect = { 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: SimpleDOMRect = { x: 0, y: 0, width: 10, height: 10 };
+    const b: SimpleDOMRect = { 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: SimpleDOMRect = { x: 5, y: 5, width: 10, height: 10 };
+    const b: SimpleDOMRect = { 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: SimpleDOMRect = { x: 0, y: 0, width: 20, height: 20 };
+    const b: SimpleDOMRect = { 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: SimpleDOMRect = { x: 5, y: 5, width: 10, height: 10 };
+    const b: SimpleDOMRect = { 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: SimpleDOMRect = { x: 5, y: 5, width: 0, height: 0 };
+    const b: SimpleDOMRect = { 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: SimpleDOMRect = { x: 5, y: 5, width: 0, height: 0 };
+    const b: SimpleDOMRect = { 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: SimpleDOMRect = { x: -10, y: -10, width: 20, height: 20 };
+    const b: SimpleDOMRect = { 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: SimpleDOMRect = { x: -20, y: -20, width: 10, height: 10 };
+    const b: SimpleDOMRect = { 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: SimpleDOMRect = { x: 1000, y: 1000, width: 100, height: 100 };
+    const b: SimpleDOMRect = { 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: SimpleDOMRect = { x: 1.5, y: 2.5, width: 3.5, height: 4.5 };
+    const b: SimpleDOMRect = { 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);
+  });
 });