@treelocator/runtime 0.1.0

package/src/functions/getUsableFileName.test.tsx

@@ -0,0 +1,24 @@
+import getUsableFileName from "./getUsableFileName"; // assuming the function is in filenameUtils.ts
+import { describe, expect, it } from "vitest";
+
+describe("getUsableFileName", () => {
+  it("should return filename if it is not index.<extension>", () => {
+    expect(getUsableFileName("myProject/utils/getSomething.js")).toBe(
+      "getSomething.js"
+    );
+  });
+
+  it("should return parent folder and filename if the filename is index.<extension>", () => {
+    expect(getUsableFileName("myProject/Button/index.tsx")).toBe(
+      "Button/index.tsx"
+    );
+  });
+
+  it("should handle paths with only one segment", () => {
+    expect(getUsableFileName("file.ts")).toBe("file.ts");
+  });
+
+  it("should handle paths with index.<extension> without parent folder", () => {
+    expect(getUsableFileName("index.ts")).toBe("index.ts");
+  });
+});

package/src/functions/getUsableFileName.tsx

@@ -0,0 +1,19 @@
+export default function getUsableFileName(path: string): string {
+  const pathSegments = path.split("/");
+
+  // If the path has only one segment, return it directly.
+  if (pathSegments.length === 1) {
+    return pathSegments[0] || "unnamed";
+  }
+
+  const fileName = pathSegments[pathSegments.length - 1] || "unnamed";
+
+  if (fileName.startsWith("index.")) {
+    // If the file name is index.<extension>, return the parent folder's name
+    // along with the filename.
+    return `${pathSegments[pathSegments.length - 2]}/${fileName}`;
+  } else {
+    // Otherwise, just return the filename.
+    return fileName;
+  }
+}

package/src/functions/getUsableName.ts

@@ -0,0 +1,52 @@
+import { Fiber } from "@locator/shared";
+
+// function printDebugOwnerTree(fiber: Fiber): string | null {
+//   let current: Fiber | null = fiber || null;
+//   let results = [];
+//   while (current) {
+//     results.push(getUsableName(current));
+//     current = current._debugOwner || null;
+//   }
+//   console.log('DEBUG OWNER: ', results);
+//   return null;
+// }
+// function printReturnTree(fiber: Fiber): string | null {
+//   let current: Fiber | null = fiber || null;
+//   let results = [];
+//   while (current) {
+//     results.push(getUsableName(current));
+//     current = current.return || null;
+//   }
+//   console.log('RETURN: ', results);
+//   return null;
+// }
+
+export function getUsableName(fiber: Fiber | null | undefined): string {
+  if (!fiber) {
+    return "Not found";
+  }
+
+  if (typeof fiber.elementType === "string") {
+    return fiber.elementType;
+  }
+  if (!fiber.elementType) {
+    return "Anonymous";
+  }
+
+  if (fiber.elementType.name) {
+    return fiber.elementType.name;
+  }
+  // Not sure about this
+  if (fiber.elementType.displayName) {
+    return fiber.elementType.displayName;
+  }
+  // Used in rect.memo
+  if (fiber.elementType.type?.name) {
+    return fiber.elementType.type.name;
+  }
+  if (fiber.elementType._payload?._result?.name) {
+    return fiber.elementType._payload._result.name;
+  }
+
+  return "Anonymous";
+}

package/src/functions/isCombinationModifiersPressed.ts

@@ -0,0 +1,32 @@
+export function getMouseModifiers() {
+  const mouseModifiers =
+    document.documentElement.dataset.locatorMouseModifiers || "alt";
+  const mouseModifiersArray = mouseModifiers.split("+");
+  const modifiers: { [key: string]: true } = {};
+  mouseModifiersArray.forEach((modifier) => {
+    modifiers[modifier] = true;
+  }, {});
+
+  return modifiers;
+}
+
+export function isCombinationModifiersPressed(
+  e: MouseEvent | KeyboardEvent,
+  rightClick = false
+) {
+  const modifiers = getMouseModifiers();
+
+  if (rightClick) {
+    return (
+      e.altKey == !!modifiers.alt &&
+      e.metaKey == !!modifiers.meta &&
+      e.shiftKey == !!modifiers.shift
+    );
+  }
+  return (
+    e.altKey == !!modifiers.alt &&
+    e.ctrlKey == !!modifiers.ctrl &&
+    e.metaKey == !!modifiers.meta &&
+    e.shiftKey == !!modifiers.shift
+  );
+}

package/src/functions/isLocatorsOwnElement.tsx

@@ -0,0 +1,9 @@
+export function isLocatorsOwnElement(element: HTMLElement) {
+  return (
+    element.className == "locatorjs-label" ||
+    element.id == "locatorjs-labels-section" ||
+    element.id == "locatorjs-layer" ||
+    element.id == "locatorjs-wrapper" ||
+    element.matches("#locatorjs-wrapper *")
+  );
+}

package/src/functions/mergeRects.test.ts

@@ -0,0 +1,15 @@
+import { mergeRects } from "./mergeRects";
+import { SimpleDOMRect } from "../types/types";
+import { describe, expect, test } from "vitest";
+
+describe("mergeRects", () => {
+  test("basic", () => {
+    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);
+    expect(res.x).toEqual(0);
+    expect(res.y).toEqual(0);
+    expect(res.width).toEqual(15);
+    expect(res.height).toEqual(15);
+  });
+});

package/src/functions/mergeRects.tsx

@@ -0,0 +1,12 @@
+import { SimpleDOMRect } from "../types/types";
+
+export function mergeRects(a: SimpleDOMRect, b: SimpleDOMRect): SimpleDOMRect {
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  return {
+    x,
+    y,
+    width: Math.max(a.x + a.width, b.x + b.width) - x,
+    height: Math.max(a.y + a.height, b.y + b.height) - y,
+  };
+}

package/src/functions/nonNullable.ts

@@ -0,0 +1,3 @@
+export default function nonNullable<T>(value: T): value is NonNullable<T> {
+  return value !== null && value !== undefined;
+}

package/src/functions/parseDataId.ts

@@ -0,0 +1,62 @@
+export function parseDataId(
+  dataId: string
+): [fileFullPath: string, id: string] {
+  const [fileFullPath, id] = dataId.split("::");
+  if (!fileFullPath || !id) {
+    throw new Error("locatorjsId is malformed");
+  }
+  return [fileFullPath, id];
+}
+
+export function parseDataPath(
+  dataPath: string
+): [fileFullPath: string, line: number, column: number] | null {
+  // Format: /path/to/file.tsx:line:column
+  // Need to handle Windows paths like C:\path\to\file.tsx:line:column
+
+  // Find the last two colons (for line and column)
+  const lastColonIndex = dataPath.lastIndexOf(":");
+  if (lastColonIndex === -1) return null;
+
+  const secondLastColonIndex = dataPath.lastIndexOf(":", lastColonIndex - 1);
+  if (secondLastColonIndex === -1) return null;
+
+  const fileFullPath = dataPath.substring(0, secondLastColonIndex);
+  const lineStr = dataPath.substring(secondLastColonIndex + 1, lastColonIndex);
+  const columnStr = dataPath.substring(lastColonIndex + 1);
+
+  const line = parseInt(lineStr, 10);
+  const column = parseInt(columnStr, 10);
+
+  if (Number.isNaN(line) || Number.isNaN(column)) {
+    return null;
+  }
+
+  return [fileFullPath, line, column];
+}
+
+export function splitFullPath(
+  fullPath: string
+): [projectPath: string, filePath: string] {
+  // Try to find a common project root indicator
+  const indicators = ["/src/", "/app/", "/pages/", "/components/"];
+
+  for (const indicator of indicators) {
+    const index = fullPath.indexOf(indicator);
+    if (index !== -1) {
+      return [fullPath.substring(0, index), fullPath.substring(index)];
+    }
+  }
+
+  // Fallback: treat the whole path as project path with empty file path
+  // or try to split at the last reasonable directory
+  const lastSlash = fullPath.lastIndexOf("/");
+  if (lastSlash !== -1) {
+    return [
+      fullPath.substring(0, lastSlash + 1),
+      fullPath.substring(lastSlash + 1),
+    ];
+  }
+
+  return [fullPath, ""];
+}

package/src/functions/transformPath.test.ts

@@ -0,0 +1,28 @@
+import { transformPath } from "./transformPath";
+import { describe, expect, test } from "vitest";
+
+describe("transformPath", () => {
+  test("replacing internal url to external", () => {
+    expect(transformPath("/app/src/myFile.js", "/app/", "C://myPath/")).toBe(
+      "C://myPath/src/myFile.js"
+    );
+  });
+
+  test("unifying absolute and relative paths", () => {
+    const from = "^/src/";
+    const to = "/myPath/src/";
+
+    expect(transformPath("/src/myFile.js", from, to)).toBe(
+      "/myPath/src/myFile.js"
+    );
+    expect(transformPath("/myPath/src/myFile.js", from, to)).toBe(
+      "/myPath/src/myFile.js"
+    );
+  });
+
+  test("invalid regex should keep original", () => {
+    expect(transformPath("/app/src/myFile.js", "[", "C://myPath/")).toBe(
+      "/app/src/myFile.js"
+    );
+  });
+});

package/src/functions/transformPath.ts

@@ -0,0 +1,7 @@
+export function transformPath(path: string, from: string, to: string) {
+  try {
+    return path.replace(new RegExp(`${from}`), to);
+  } catch (e) {
+    return path;
+  }
+}

package/src/global.d.ts

@@ -0,0 +1,31 @@
+import { ReactDevtoolsHook } from "@locator/shared";
+import { FileStorage } from "./types/types";
+import { LocatorJSAPI } from "./browserApi";
+
+declare global {
+  interface Window {
+    __REACT_DEVTOOLS_GLOBAL_HOOK__: ReactDevtoolsHook;
+    __LOCATOR_DATA__: { [filename: string]: FileStorage };
+    /**
+     * LocatorJS Browser API
+     *
+     * Provides programmatic access to component ancestry information.
+     * Works with browser automation tools like Playwright, Puppeteer, Selenium, etc.
+     *
+     * @example
+     * // In Playwright
+     * const path = await page.evaluate(() => {
+     *   return window.__locatorjs__.getPath('button.submit');
+     * });
+     * console.log(path);
+     *
+     * @example
+     * // Get raw ancestry data
+     * const ancestry = await page.evaluate(() => {
+     *   const element = document.querySelector('button.submit');
+     *   return window.__locatorjs__.getAncestry(element);
+     * });
+     */
+    __locatorjs__: LocatorJSAPI;
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+import { Target } from "@locator/shared";
+import { AdapterId } from "./consts";
+import { initRuntime } from "./initRuntime";
+export * from "./adapters/jsx/runtimeStore";
+
+export const MAX_ZINDEX = 2147483647;
+
+export function setup({
+  adapter,
+  targets,
+}: {
+  adapter?: AdapterId;
+  targets?: { [k: string]: Target | string };
+} = {}) {
+  setTimeout(() => initRuntime({ adapter, targets }), 0);
+}
+
+export default setup;

package/src/initRuntime.ts

@@ -0,0 +1,83 @@
+import { allTargets, Target } from "@locator/shared";
+import { AdapterId, fontFamily } from "./consts";
+import generatedStyles from "./_generated_styles";
+import { MAX_ZINDEX } from "./index";
+import { installBrowserAPI } from "./browserApi";
+
+export function initRuntime({
+  adapter,
+  targets,
+}: {
+  adapter?: AdapterId;
+  targets?: { [k: string]: Target | string };
+} = {}) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return;
+  }
+  if (document.getElementById("locatorjs-wrapper")) {
+    // already initialized
+    return;
+  }
+
+  // Install browser API on window.__locatorjs__
+  installBrowserAPI(adapter);
+
+  // add style tag to head
+  const style = document.createElement("style");
+  style.id = "locatorjs-style";
+  style.innerHTML = `
+      #locatorjs-layer {
+        all: initial;
+        pointer-events: none;
+        font-family: ${fontFamily};
+      }
+      #locatorjs-layer * {
+        box-sizing: border-box;
+      }
+      #locatorjs-labels-wrapper {
+        display: flex;
+        gap: 8px;
+      }
+      ${generatedStyles}
+    `;
+
+  const globalStyle = document.createElement("style");
+  globalStyle.id = "locatorjs-global-style";
+  globalStyle.innerHTML = `
+      #locatorjs-wrapper {
+        z-index: ${MAX_ZINDEX};
+        pointer-events: none;
+        position: fixed;
+      }
+      .locatorjs-active-pointer * {
+        cursor: pointer !important;
+      }
+    `;
+
+  const wrapper = document.createElement("div");
+  wrapper.setAttribute("id", "locatorjs-wrapper");
+
+  const shadow = wrapper.attachShadow({ mode: "open" });
+  const layer = document.createElement("div");
+  layer.setAttribute("id", "locatorjs-layer");
+
+  shadow.appendChild(style);
+  shadow.appendChild(layer);
+
+  document.body.appendChild(wrapper);
+  document.head.appendChild(globalStyle);
+
+  // This weird import is needed because:
+  // SSR React (Next.js) breaks when importing any SolidJS compiled file, so the import has to be conditional
+  // Browser Extension breaks when importing with "import()"
+  // Vite breaks when importing with "require()"
+  if (typeof require !== "undefined") {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { initRender } = require("./components/Runtime");
+    initRender(layer, adapter, targets || allTargets);
+  } else {
+    import("./components/Runtime").then(({ initRender }) => {
+      initRender(layer, adapter, targets || allTargets);
+    });
+  }
+}

package/src/main.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

package/src/types/LabelData.ts

@@ -0,0 +1,6 @@
+import { LinkProps } from "./types";
+
+export type LabelData = {
+  link: LinkProps | null;
+  label: string;
+};

package/src/types/TreeNode.ts

@@ -0,0 +1,22 @@
+import { SimpleDOMRect, Source } from "./types";
+
+export interface TreeNode {
+  type: "component" | "element";
+  name: string;
+  uniqueId: string;
+  getBox(): SimpleDOMRect | null;
+  getParent(): TreeNode | null;
+  getChildren(): TreeNode[];
+  getSource(): Source | null;
+  getComponent(): TreeNodeComponent | null;
+}
+
+export type TreeNodeComponent = {
+  label: string;
+  callLink?: Source;
+  definitionLink?: Source;
+};
+
+export interface TreeNodeElement extends TreeNode {
+  getElement(): Element | Text;
+}

package/src/types/types.ts

@@ -0,0 +1,55 @@
+import { Fiber, Target } from "@locator/shared";
+
+export type Source = {
+  fileName: string;
+  lineNumber: number;
+  columnNumber?: number;
+  projectPath?: string;
+};
+
+type SimpleElement = {
+  type: "element";
+  name: string;
+  uniqueId: string;
+  fiber: Fiber;
+  box: SimpleDOMRect | null;
+  element: Element | Text;
+  children: (SimpleElement | SimpleComponent)[];
+  source: Source | null;
+};
+
+type SimpleComponent = {
+  type: "component";
+  uniqueId: string;
+  name: string;
+  fiber: Fiber;
+  box: SimpleDOMRect | null;
+  children: (SimpleElement | SimpleComponent)[];
+  source: Source | null;
+  definitionSourceFile: string | null;
+};
+
+export type SimpleNode = SimpleElement | SimpleComponent;
+
+export type HighlightedNode = {
+  getNode: () => SimpleNode | null;
+  setNode: (node: SimpleNode | null) => void;
+};
+
+export type SimpleDOMRect = {
+  height: number;
+  width: number;
+  x: number;
+  y: number;
+};
+
+export type Targets = { [k: string]: Target | string };
+
+export type LinkProps = {
+  filePath: string;
+  projectPath: string;
+  line: number;
+  column: number;
+};
+
+export type ContextMenuState = { target: HTMLElement; x: number; y: number };

package/tailwind.config.js

@@ -0,0 +1,9 @@
+/* eslint-disable no-undef */
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ["./src/**/*.{tsx,ts}"],
+  theme: {
+    extend: {},
+  },
+  plugins: [require("@tailwindcss/forms")],
+};

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "include": ["src"],
+  "exclude": ["dist", "build", "node_modules"],
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es6",
+    "noEmit": true,
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "lib": ["ESNext", "dom", "DOM.Iterable"],
+    "moduleResolution": "node",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "strictNullChecks": true,
+    "noImplicitAny": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}