@treelocator/runtime 0.1.0

package/src/components/Runtime.tsx

@@ -0,0 +1,246 @@
+import { Targets } from "@locator/shared";
+import { batch, createEffect, createSignal, onCleanup } from "solid-js";
+import { render } from "solid-js/web";
+import { AdapterId } from "../consts";
+import { isCombinationModifiersPressed } from "../functions/isCombinationModifiersPressed";
+import { Targets as SetupTargets } from "../types/types";
+import { MaybeOutline } from "./MaybeOutline";
+import { isLocatorsOwnElement } from "../functions/isLocatorsOwnElement";
+import { Toast } from "./Toast";
+import { collectAncestry, formatAncestryChain } from "../functions/formatAncestryChain";
+import { createTreeNode } from "../adapters/createTreeNode";
+import treeIconUrl from "../_generated_tree_icon";
+
+type RuntimeProps = {
+  adapterId?: AdapterId;
+  targets: Targets;
+};
+
+function Runtime(props: RuntimeProps) {
+  const [holdingModKey, setHoldingModKey] = createSignal<boolean>(false);
+  const [currentElement, setCurrentElement] = createSignal<HTMLElement | null>(
+    null
+  );
+  const [toastMessage, setToastMessage] = createSignal<string | null>(null);
+  const [locatorActive, setLocatorActive] = createSignal<boolean>(false);
+
+  const isActive = () => (holdingModKey() || locatorActive()) && currentElement();
+
+  createEffect(() => {
+    if (isActive()) {
+      document.body.classList.add("locatorjs-active-pointer");
+    } else {
+      document.body.classList.remove("locatorjs-active-pointer");
+    }
+  });
+
+  function keyUpListener(e: KeyboardEvent) {
+    setHoldingModKey(isCombinationModifiersPressed(e));
+  }
+
+  function keyDownListener(e: KeyboardEvent) {
+    setHoldingModKey(isCombinationModifiersPressed(e, true));
+  }
+
+  function mouseOverListener(e: MouseEvent) {
+    const target = e.target;
+    if (target && target instanceof HTMLElement) {
+      if (isLocatorsOwnElement(target)) {
+        return;
+      }
+
+      setHoldingModKey(isCombinationModifiersPressed(e, true));
+
+      batch(() => {
+        setCurrentElement(target);
+      });
+    }
+  }
+
+  function mouseDownUpListener(e: MouseEvent) {
+    if (isCombinationModifiersPressed(e) || locatorActive()) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  }
+
+  function clickListener(e: MouseEvent) {
+    if (!isCombinationModifiersPressed(e) && !locatorActive()) {
+      return;
+    }
+
+    const target = e.target;
+    if (target && target instanceof HTMLElement) {
+      if (target.shadowRoot) {
+        return;
+      }
+
+      if (isLocatorsOwnElement(target)) {
+        return;
+      }
+
+      e.preventDefault();
+      e.stopPropagation();
+
+      // Copy ancestry to clipboard on alt+click
+      const treeNode = createTreeNode(target, props.adapterId);
+      if (treeNode) {
+        const ancestry = collectAncestry(treeNode);
+        const formatted = formatAncestryChain(ancestry);
+        navigator.clipboard.writeText(formatted).then(() => {
+          setToastMessage("Copied to clipboard");
+        });
+      }
+
+      // Deactivate toggle after click
+      if (locatorActive()) {
+        setLocatorActive(false);
+      }
+    }
+  }
+
+  function scrollListener() {
+    setCurrentElement(null);
+  }
+
+  const roots: (Document | ShadowRoot)[] = [document];
+  document.querySelectorAll("*").forEach((node) => {
+    if (node.id === "locatorjs-wrapper") {
+      return;
+    }
+    if (node.shadowRoot) {
+      roots.push(node.shadowRoot);
+    }
+  });
+
+  for (const root of roots) {
+    root.addEventListener("mouseover", mouseOverListener as EventListener, {
+      capture: true,
+    });
+    root.addEventListener("keydown", keyDownListener as EventListener);
+    root.addEventListener("keyup", keyUpListener as EventListener);
+    root.addEventListener("click", clickListener as EventListener, {
+      capture: true,
+    });
+    root.addEventListener("mousedown", mouseDownUpListener as EventListener, {
+      capture: true,
+    });
+    root.addEventListener("mouseup", mouseDownUpListener as EventListener, {
+      capture: true,
+    });
+    root.addEventListener("scroll", scrollListener);
+  }
+
+  onCleanup(() => {
+    for (const root of roots) {
+      root.removeEventListener("keyup", keyUpListener as EventListener);
+      root.removeEventListener("keydown", keyDownListener as EventListener);
+      root.removeEventListener(
+        "mouseover",
+        mouseOverListener as EventListener,
+        { capture: true }
+      );
+      root.removeEventListener("click", clickListener as EventListener, {
+        capture: true,
+      });
+      root.removeEventListener(
+        "mousedown",
+        mouseDownUpListener as EventListener,
+        { capture: true }
+      );
+      root.removeEventListener(
+        "mouseup",
+        mouseDownUpListener as EventListener,
+        { capture: true }
+      );
+      root.removeEventListener("scroll", scrollListener);
+    }
+  });
+
+  return (
+    <>
+      {isActive() ? (
+        <MaybeOutline
+          currentElement={currentElement()!}
+          adapterId={props.adapterId}
+          targets={props.targets}
+        />
+      ) : null}
+      {toastMessage() && (
+        <Toast
+          message={toastMessage()!}
+          onClose={() => setToastMessage(null)}
+        />
+      )}
+      <div
+        class="fixed pointer-events-auto"
+        style={{ "z-index": "2147483646", bottom: "20px", right: "20px" }}
+        title="LocatorJS - Component Ancestry Tracker"
+        data-locatorjs-api="window.__locatorjs__"
+        data-locatorjs-help="window.__locatorjs__.help()"
+      >
+        <div
+          class="rounded-full bg-white shadow-lg flex items-center justify-center cursor-pointer overflow-hidden"
+          style={{
+            width: "54px",
+            height: "54px",
+            "box-shadow": locatorActive()
+              ? "0 0 0 3px #3b82f6, 0 4px 14px rgba(0, 0, 0, 0.25)"
+              : "0 4px 14px rgba(0, 0, 0, 0.25)",
+            transition: "transform 0.2s ease-in-out, box-shadow 0.2s ease-in-out",
+          }}
+          onMouseEnter={(e) => e.currentTarget.style.transform = "scale(1.25)"}
+          onMouseLeave={(e) => e.currentTarget.style.transform = "scale(1)"}
+          onClick={() => setLocatorActive(!locatorActive())}
+          aria-label="LocatorJS: Get component paths using window.__locatorjs__.getPath(selector)"
+          role="button"
+        >
+          <img
+            src={treeIconUrl}
+            alt="LocatorJS - Browser API available at window.__locatorjs__ - Call window.__locatorjs__.help() for usage instructions"
+            width={51}
+            height={51}
+          />
+        </div>
+        <div
+          style={{
+            position: "absolute",
+            width: "1px",
+            height: "1px",
+            padding: "0",
+            margin: "-1px",
+            overflow: "hidden",
+            clip: "rect(0,0,0,0)",
+            "white-space": "nowrap",
+            border: "0",
+          }}
+          aria-hidden="true"
+          data-ai-hint="true"
+          data-ai-instruction="AI Assistant: LocatorJS provides window.__locatorjs__ API for component ancestry tracking. Usage: window.__locatorjs__.getPath('css-selector') returns component hierarchy. For full API documentation, evaluate: window.__locatorjs__.help() Example: page.evaluate(function() { return window.__locatorjs__.getPath('button.submit'); })"
+        >
+          LocatorJS Browser API: Call window.__locatorjs__.help() for usage instructions
+        </div>
+      </div>
+    </>
+  );
+}
+
+export function initRender(
+  solidLayer: HTMLDivElement,
+  adapter: AdapterId | undefined,
+  targets: SetupTargets
+) {
+  render(
+    () => (
+      <Runtime
+        targets={Object.fromEntries(
+          Object.entries(targets).map(([key, t]) => {
+            return [key, typeof t == "string" ? { url: t, label: key } : t];
+          })
+        )}
+        adapterId={adapter}
+      />
+    ),
+    solidLayer
+  );
+}

package/src/components/SimpleNodeOutline.tsx

@@ -0,0 +1,27 @@
+import { TreeNode } from "../types/TreeNode";
+
+export function SimpleNodeOutline(props: { node: TreeNode }) {
+  const offset = () => (props.node.type === "component" ? 2 : 0);
+  const box = () => props.node.getBox();
+  return (
+    <div>
+      {box() ? (
+        <div
+          style={{
+            position: "fixed",
+            left: box()!.x - offset() + "px",
+            top: box()!.y - offset() + "px",
+            width: box()!.width + offset() * 2 + "px",
+            height: box()!.height + offset() * 2 + "px",
+            border:
+              props.node.type === "component"
+                ? "2px solid rgba(200,0,0,1)"
+                : "1px solid rgba(200,0,0,1)",
+            "border-radius": props.node.type === "component" ? "5px" : "3px",
+            "z-index": props.node.type === "component" ? 1000 : 10,
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/components/Toast.tsx

@@ -0,0 +1,83 @@
+import { createSignal, onCleanup, onMount } from "solid-js";
+import { Portal } from "solid-js/web";
+import TREE_ICON from "../_generated_tree_icon";
+
+export function Toast(props: { message: string; onClose: () => void }) {
+  let timeoutId: ReturnType<typeof setTimeout>;
+  const [flashOpacity, setFlashOpacity] = createSignal(1);
+
+  onMount(() => {
+    // Start flash fade after a brief moment so it's visible
+    setTimeout(() => {
+      setFlashOpacity(0);
+    }, 100);
+
+    timeoutId = setTimeout(() => {
+      props.onClose();
+    }, 1500);
+  });
+
+  onCleanup(() => {
+    clearTimeout(timeoutId);
+  });
+
+  return (
+    <Portal mount={document.body}>
+      {/* Flash overlay */}
+      <div
+        style={{
+          position: "fixed",
+          top: "0",
+          left: "0",
+          right: "0",
+          bottom: "0",
+          width: "100vw",
+          height: "100vh",
+          "z-index": 99999,
+          "background-color": "rgba(56, 189, 248, 0.5)",
+          opacity: flashOpacity(),
+          transition: "opacity 0.3s ease-out",
+          "pointer-events": "none",
+        }}
+      />
+      {/* Tree icon in bottom left */}
+      <div
+        style={{
+          position: "fixed",
+          bottom: "16px",
+          left: "16px",
+          "z-index": 100000,
+          "pointer-events": "none",
+        }}
+      >
+        <img
+          src={TREE_ICON}
+          alt="Tree"
+          style={{
+            width: "32px",
+            height: "32px",
+          }}
+        />
+      </div>
+      {/* Toast message */}
+      <div
+        style={{
+          position: "fixed",
+          bottom: "16px",
+          left: "50%",
+          transform: "translateX(-50%)",
+          "background-color": "#111827",
+          color: "white",
+          padding: "8px 16px",
+          "border-radius": "8px",
+          "box-shadow": "0 10px 15px -3px rgba(0, 0, 0, 0.1)",
+          "font-size": "14px",
+          "z-index": 100000,
+          "pointer-events": "auto",
+        }}
+      >
+        {props.message}
+      </div>
+    </Portal>
+  );
+}

package/src/components/Tooltip.tsx

@@ -0,0 +1,28 @@
+export default function Tooltip(props: {
+  tooltipText?: string;
+  position?: "bottom" | "left" | "right" | "top";
+  children: any;
+}) {
+  const positionMap = {
+    bottom: "-bottom-7 left-1/2 -translate-x-1/2 transform",
+    left: "-left-2 top-1/2 -translate-y-1/2 -translate-x-full transform",
+    right: "-right-2 top-1/2 -translate-y-1/2 translate-x-full transform",
+    top: "-top-7 left-1/2 -translate-x-1/2 transform",
+  };
+
+  return (
+    <div class="group/tooltip relative block">
+      {props.children}
+      <div
+        class={
+          "pointer-events-none invisible absolute z-10 whitespace-nowrap rounded bg-gray-700 px-2 py-1 text-center text-xs text-white opacity-0 transition-opacity duration-300 group-hover/tooltip:visible group-hover/tooltip:opacity-100" +
+          " " +
+          positionMap[props.position || "top"]
+        }
+        role="tooltip"
+      >
+        {props.tooltipText}
+      </div>
+    </div>
+  );
+}

package/src/consts.ts

@@ -0,0 +1,7 @@
+export const HREF_TARGET = "_self";
+export const PADDING = 6;
+export const baseColor = "#e90139";
+export const hoverColor = "#C70139";
+export const fontFamily = "Helvetica, sans-serif, Arial";
+
+export type AdapterId = "react" | "jsx" | "svelte" | "vue";

package/src/functions/cropPath.test.ts

@@ -0,0 +1,18 @@
+import cropPath from "./cropPath";
+import { describe, expect, test } from "vitest";
+
+describe("cropPath", () => {
+  test("crop", () => {
+    expect(cropPath("aaa/bbb/ccc/ddd.tsx")).toBe(".../bbb/ccc/ddd.tsx");
+    expect(cropPath("/aaa/bbb/ccc/ddd.tsx")).toBe(".../bbb/ccc/ddd.tsx");
+  });
+
+  test("no crop", () => {
+    // expect(cropPath("/bbb/ccc/ddd.tsx")).toBe("/bbb/ccc/ddd.tsx");
+    expect(cropPath("bbb/ccc/ddd.tsx")).toBe("bbb/ccc/ddd.tsx");
+    expect(cropPath("/ccc/ddd.tsx")).toBe("/ccc/ddd.tsx");
+    expect(cropPath("ccc/ddd.tsx")).toBe("ccc/ddd.tsx");
+    expect(cropPath("")).toBe("");
+    expect(cropPath("xxx")).toBe("xxx");
+  });
+});

package/src/functions/cropPath.ts

@@ -0,0 +1,12 @@
+export default function cropPath(fullPath: string) {
+  const array = fullPath.split("/");
+
+  const newPath = array
+    .slice(Math.max(array.length - 3, 0), array.length)
+    .join("/");
+  if (newPath !== fullPath) {
+    return `.../${newPath}`;
+  } else {
+    return newPath;
+  }
+}

package/src/functions/deduplicateLabels.ts

@@ -0,0 +1,16 @@
+import { LabelData } from "../types/LabelData";
+import nonNullable from "./nonNullable";
+
+export function deduplicateLabels(labels: LabelData[]): LabelData[] {
+  const labelsIds: { [key: string]: true } = {};
+  return labels
+    .map((label) => {
+      const id = JSON.stringify(label);
+      if (labelsIds[id]) {
+        return null;
+      }
+      labelsIds[id] = true;
+      return label;
+    })
+    .filter(nonNullable);
+}

package/src/functions/evalTemplate.test.ts

@@ -0,0 +1,12 @@
+import { evalTemplate } from "./evalTemplate";
+import { describe, expect, test } from "vitest";
+
+describe("evalTemplate", () => {
+  test("basic", () => {
+    const res = evalTemplate("https://example.com/${filePath}${ext}", {
+      filePath: "test",
+      ext: ".js",
+    });
+    expect(res).toBe("https://example.com/test.js");
+  });
+});

package/src/functions/evalTemplate.ts

@@ -0,0 +1,8 @@
+export function evalTemplate(str: string, params: { [key: string]: string }) {
+  let newStr = str;
+
+  Object.entries(params).forEach(([key, value]) => {
+    newStr = newStr.replace("${" + key + "}", value);
+  });
+  return newStr;
+}

package/src/functions/findNames.ts

@@ -0,0 +1,20 @@
+import { Fiber } from "@locator/shared";
+import { getUsableName } from "./getUsableName";
+
+export function findNames(fiber: Fiber): {
+  name: string;
+  wrappingComponent: string;
+} {
+  // if (fiber._debugOwner?.elementType?.styledComponentId) {
+  //   // This is special case for styled-components, we need to show one level up
+  //   return {
+  //     name: getUsableName(fiber._debugOwner),
+  //     wrappingComponent: getUsableName(fiber._debugOwner?._debugOwner),
+  //   };
+  // } else {
+  return {
+    name: getUsableName(fiber),
+    wrappingComponent: getUsableName(fiber._debugOwner),
+  };
+  // }
+}

package/src/functions/formatAncestryChain.ts

@@ -0,0 +1,80 @@
+import { TreeNode } from "../types/TreeNode";
+
+export interface AncestryItem {
+  elementName: string;
+  componentName?: string;
+  filePath?: string;
+  line?: number;
+}
+
+// Elements to exclude from ancestry (not useful for debugging)
+const EXCLUDED_ELEMENTS = new Set(["html", "body", "head"]);
+
+export function collectAncestry(node: TreeNode): AncestryItem[] {
+  const items: AncestryItem[] = [];
+  let current: TreeNode | null = node;
+
+  while (current) {
+    // Skip html, body, head elements
+    if (EXCLUDED_ELEMENTS.has(current.name)) {
+      current = current.getParent();
+      continue;
+    }
+
+    const component = current.getComponent();
+    const source = current.getSource();
+
+    const item: AncestryItem = {
+      elementName: current.name,
+    };
+
+    if (component) {
+      item.componentName = component.label;
+      if (component.callLink) {
+        item.filePath = component.callLink.fileName;
+        item.line = component.callLink.lineNumber;
+      }
+    }
+
+    if (!item.filePath && source) {
+      item.filePath = source.fileName;
+      item.line = source.lineNumber;
+    }
+
+    // Only include items that have useful info (component name or file path)
+    if (item.componentName || item.filePath) {
+      items.push(item);
+    }
+
+    current = current.getParent();
+  }
+
+  return items;
+}
+
+export function formatAncestryChain(items: AncestryItem[]): string {
+  if (items.length === 0) {
+    return "";
+  }
+
+  // Reverse so root is at top, clicked element at bottom
+  const reversed = [...items].reverse();
+
+  const lines: string[] = [];
+
+  reversed.forEach((item, index) => {
+    const indent = "    ".repeat(index);
+    const prefix = index === 0 ? "" : "└─ ";
+
+    let description = item.elementName;
+    if (item.componentName) {
+      description = `${item.elementName} in ${item.componentName}`;
+    }
+
+    const location = item.filePath ? ` at ${item.filePath}:${item.line}` : "";
+
+    lines.push(`${indent}${prefix}${description}${location}`);
+  });
+
+  return lines.join("\n");
+}

package/src/functions/getBoundingRect.tsx

@@ -0,0 +1,11 @@
+export function getBoundingRect(node: Element | Text): DOMRect | null {
+  if (node instanceof Element) {
+    return node.getBoundingClientRect();
+  } else if (node instanceof Text) {
+    const range = document.createRange();
+    range.selectNodeContents(node);
+    return range.getBoundingClientRect();
+  } else {
+    return null;
+  }
+}

package/src/functions/getComposedBoundingBox.tsx

@@ -0,0 +1,25 @@
+import { mergeRects } from "./mergeRects";
+import { SimpleDOMRect, SimpleNode } from "./../types/types";
+
+export function getComposedBoundingBox(
+  children: SimpleNode[]
+): SimpleDOMRect | null {
+  let composedRect: SimpleDOMRect | null = null;
+
+  children.forEach((child) => {
+    const box = child.box;
+    if (!box) {
+      return;
+    }
+    if (box.width <= 0 || box.height <= 0) {
+      // ignore zero-sized rects
+      return;
+    }
+    if (composedRect) {
+      composedRect = mergeRects(composedRect, box);
+    } else {
+      composedRect = box;
+    }
+  });
+  return composedRect;
+}

package/src/functions/getIdsOnPathToRoot.tsx

@@ -0,0 +1,21 @@
+import { findFiberByHtmlElement } from "./../adapters/react/findFiberByHtmlElement";
+import { makeFiberId } from "./../adapters/react/makeFiberId";
+
+export function getIdsOnPathToRoot(element: HTMLElement): {
+  [id: string]: true;
+} {
+  const fiber = findFiberByHtmlElement(element, false);
+  if (!fiber) {
+    return {};
+  }
+  const res: {
+    [id: string]: true;
+  } = {};
+  let parent = fiber?._debugOwner;
+
+  while (parent) {
+    res[makeFiberId(parent)] = true;
+    parent = parent?._debugOwner;
+  }
+  return res;
+}

package/src/functions/getMultipleElementsBoundingBox.tsx

@@ -0,0 +1,25 @@
+import { mergeRects } from "./mergeRects";
+import { SimpleDOMRect } from "../types/types";
+
+export function getMultipleElementsBoundingBox(
+  children: HTMLElement[]
+): SimpleDOMRect | null {
+  let composedRect: SimpleDOMRect | null = null;
+
+  children.forEach((child) => {
+    const box = child.getBoundingClientRect();
+    if (!box) {
+      return;
+    }
+    if (box.width <= 0 || box.height <= 0) {
+      // ignore zero-sized rects
+      return;
+    }
+    if (composedRect) {
+      composedRect = mergeRects(composedRect, box);
+    } else {
+      composedRect = box;
+    }
+  });
+  return composedRect;
+}

package/src/functions/getPathToParent.tsx

@@ -0,0 +1,17 @@
+import { findFiberByHtmlElement } from "../adapters/react/findFiberByHtmlElement";
+import { fiberToSimple } from "../adapters/react/fiberToSimple";
+
+export function getPathToParent(element: HTMLElement) {
+  const fiber = findFiberByHtmlElement(element, false);
+  if (!fiber) {
+    return;
+  }
+  let res = fiberToSimple(fiber);
+  let parent = fiber?._debugOwner;
+
+  while (parent) {
+    res = fiberToSimple(parent, [res]);
+    parent = parent?._debugOwner;
+  }
+  return res;
+}

package/src/functions/getReferenceId.tsx

@@ -0,0 +1,10 @@
+const map = new WeakMap();
+let lastId = 0;
+
+export function getReferenceId(ref: object): number {
+  if (!map.has(ref)) {
+    lastId++;
+    map.set(ref, lastId);
+  }
+  return map.get(ref);
+}