@treelocator/runtime 0.1.0

package/src/browserApi.ts

@@ -0,0 +1,288 @@
+import { AdapterId } from "./consts";
+import { createTreeNode } from "./adapters/createTreeNode";
+import {
+  collectAncestry,
+  formatAncestryChain,
+  AncestryItem,
+} from "./functions/formatAncestryChain";
+
+export interface LocatorJSAPI {
+  /**
+   * Get formatted ancestry path for an element.
+   * Returns a human-readable string showing the component hierarchy from root to target element.
+   *
+   * @param elementOrSelector - HTMLElement or CSS selector string (e.g., 'button.submit', '#login-form')
+   * @returns Formatted ancestry chain as string, or null if element not found/unsupported
+   *
+   * @example
+   * // Basic usage with CSS selector
+   * window.__locatorjs__.getPath('button.submit');
+   * // Returns:
+   * // "div in App at src/App.tsx:15
+   * //  └─ button in SubmitButton at src/components/SubmitButton.tsx:12"
+   *
+   * @example
+   * // Usage with HTMLElement
+   * const button = document.querySelector('button.submit');
+   * window.__locatorjs__.getPath(button);
+   *
+   * @example
+   * // In Playwright
+   * const path = await page.evaluate(() => {
+   *   return window.__locatorjs__.getPath('button.submit');
+   * });
+   * console.log(path);
+   */
+  getPath(elementOrSelector: HTMLElement | string): string | null;
+
+  /**
+   * Get raw ancestry data for an element.
+   * Returns an array of objects containing component names, file paths, and line numbers.
+   *
+   * @param elementOrSelector - HTMLElement or CSS selector string
+   * @returns Array of ancestry items with structure:
+   *   - elementName: HTML element tag (e.g., 'div', 'button')
+   *   - componentName: Component name (e.g., 'LoginButton')
+   *   - filePath: Source file path (e.g., 'src/components/LoginButton.tsx')
+   *   - line: Line number in source file
+   *
+   * @example
+   * // Get structured ancestry data
+   * const ancestry = window.__locatorjs__.getAncestry('button.submit');
+   * // Returns: [
+   * //   { elementName: 'div', componentName: 'App', filePath: 'src/App.tsx', line: 15 },
+   * //   { elementName: 'button', componentName: 'SubmitButton', filePath: 'src/components/SubmitButton.tsx', line: 12 }
+   * // ]
+   *
+   * @example
+   * // In Playwright - extract just component names
+   * const components = await page.evaluate(() => {
+   *   const ancestry = window.__locatorjs__.getAncestry('.my-element');
+   *   return ancestry?.map(item => item.componentName).filter(Boolean);
+   * });
+   */
+  getAncestry(elementOrSelector: HTMLElement | string): AncestryItem[] | null;
+
+  /**
+   * Get both formatted path and raw ancestry data in a single call.
+   * Convenience method that combines getPath() and getAncestry().
+   *
+   * @param elementOrSelector - HTMLElement or CSS selector string
+   * @returns Object with { path: string, ancestry: AncestryItem[] }, or null
+   *
+   * @example
+   * // Get both formats at once
+   * const data = window.__locatorjs__.getPathData('button.submit');
+   * console.log(data.path);      // Human-readable string
+   * console.log(data.ancestry);  // Structured array
+   *
+   * @example
+   * // In Playwright - useful for comprehensive debugging
+   * const data = await page.evaluate(() => {
+   *   return window.__locatorjs__.getPathData('.error-message');
+   * });
+   * if (data) {
+   *   console.log('Component tree:', data.path);
+   *   console.log('Source files:', data.ancestry.map(a => a.filePath));
+   * }
+   */
+  getPathData(
+    elementOrSelector: HTMLElement | string
+  ): { path: string; ancestry: AncestryItem[] } | null;
+
+  /**
+   * Display help information about the LocatorJS API.
+   * Shows usage examples and method descriptions for browser automation tools.
+   *
+   * @returns Help text as a string
+   *
+   * @example
+   * // View help in browser console
+   * console.log(window.__locatorjs__.help());
+   *
+   * @example
+   * // In Playwright - view help
+   * const help = await page.evaluate(() => window.__locatorjs__.help());
+   * console.log(help);
+   */
+  help(): string;
+}
+
+let adapterId: AdapterId | undefined;
+
+function resolveElement(
+  elementOrSelector: HTMLElement | string
+): HTMLElement | null {
+  if (typeof elementOrSelector === "string") {
+    const element = document.querySelector(elementOrSelector);
+    return element instanceof HTMLElement ? element : null;
+  }
+  return elementOrSelector;
+}
+
+function getAncestryForElement(element: HTMLElement): AncestryItem[] | null {
+  const treeNode = createTreeNode(element, adapterId);
+  if (!treeNode) {
+    return null;
+  }
+  return collectAncestry(treeNode);
+}
+
+const HELP_TEXT = `
+╔═══════════════════════════════════════════════════════════════════════════╗
+║                          LocatorJS Browser API                            ║
+║                  Programmatic Component Ancestry Access                   ║
+╚═══════════════════════════════════════════════════════════════════════════╝
+
+METHODS:
+--------
+
+1. getPath(elementOrSelector)
+   Returns a formatted string showing the component hierarchy.
+
+   Usage:
+     window.__locatorjs__.getPath('button.submit')
+     window.__locatorjs__.getPath(document.querySelector('.my-button'))
+
+   Returns:
+     "div in App at src/App.tsx:15
+      └─ button in SubmitButton at src/components/SubmitButton.tsx:12"
+
+2. getAncestry(elementOrSelector)
+   Returns raw ancestry data as an array of objects.
+
+   Usage:
+     window.__locatorjs__.getAncestry('button.submit')
+
+   Returns:
+     [
+       { elementName: 'div', componentName: 'App',
+         filePath: 'src/App.tsx', line: 15 },
+       { elementName: 'button', componentName: 'SubmitButton',
+         filePath: 'src/components/SubmitButton.tsx', line: 12 }
+     ]
+
+3. getPathData(elementOrSelector)
+   Returns both formatted path and raw ancestry in one call.
+
+   Usage:
+     const data = window.__locatorjs__.getPathData('button.submit')
+     console.log(data.path)      // formatted string
+     console.log(data.ancestry)  // structured array
+
+4. help()
+   Displays this help message.
+
+PLAYWRIGHT EXAMPLES:
+-------------------
+
+// Get component path for debugging
+const path = await page.evaluate(() => {
+  return window.__locatorjs__.getPath('button.submit');
+});
+console.log(path);
+
+// Extract component names
+const components = await page.evaluate(() => {
+  const ancestry = window.__locatorjs__.getAncestry('.error-message');
+  return ancestry?.map(item => item.componentName).filter(Boolean);
+});
+
+// Create a test helper
+async function getComponentPath(page, selector) {
+  return await page.evaluate((sel) => {
+    return window.__locatorjs__.getPath(sel);
+  }, selector);
+}
+
+PUPPETEER EXAMPLES:
+------------------
+
+const path = await page.evaluate(() => {
+  return window.__locatorjs__.getPath('.my-button');
+});
+
+SELENIUM EXAMPLES:
+-----------------
+
+const path = await driver.executeScript(() => {
+  return window.__locatorjs__.getPath('button.submit');
+});
+
+CYPRESS EXAMPLES:
+----------------
+
+cy.window().then((win) => {
+  const path = win.__locatorjs__.getPath('button.submit');
+  cy.log(path);
+});
+
+NOTES:
+------
+• Accepts CSS selectors or HTMLElement objects
+• Returns null if element not found or framework not supported
+• Works with React, Vue, Svelte, Preact, and any JSX framework
+• Automatically installed when LocatorJS runtime initializes
+
+Documentation: https://github.com/infi-pc/locatorjs
+`;
+
+export function createBrowserAPI(
+  adapterIdParam?: AdapterId
+): LocatorJSAPI {
+  adapterId = adapterIdParam;
+
+  return {
+    getPath(elementOrSelector: HTMLElement | string): string | null {
+      const element = resolveElement(elementOrSelector);
+      if (!element) {
+        return null;
+      }
+
+      const ancestry = getAncestryForElement(element);
+      if (!ancestry) {
+        return null;
+      }
+
+      return formatAncestryChain(ancestry);
+    },
+
+    getAncestry(elementOrSelector: HTMLElement | string): AncestryItem[] | null {
+      const element = resolveElement(elementOrSelector);
+      if (!element) {
+        return null;
+      }
+
+      return getAncestryForElement(element);
+    },
+
+    getPathData(
+      elementOrSelector: HTMLElement | string
+    ): { path: string; ancestry: AncestryItem[] } | null {
+      const element = resolveElement(elementOrSelector);
+      if (!element) {
+        return null;
+      }
+
+      const ancestry = getAncestryForElement(element);
+      if (!ancestry) {
+        return null;
+      }
+
+      return {
+        path: formatAncestryChain(ancestry),
+        ancestry,
+      };
+    },
+
+    help(): string {
+      return HELP_TEXT;
+    },
+  };
+}
+
+export function installBrowserAPI(adapterIdParam?: AdapterId): void {
+  if (typeof window !== "undefined") {
+    (window as any).__locatorjs__ = createBrowserAPI(adapterIdParam);
+  }
+}

package/src/components/Button.tsx

@@ -0,0 +1,14 @@
+export function Button(props: { onClick: () => void; children: any }) {
+  return (
+    <button
+      class="py-1 px-1 hover:bg-white/30 pointer hover:text-gray-100 rounded"
+      onClick={(e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        props.onClick();
+      }}
+    >
+      {props.children}
+    </button>
+  );
+}

package/src/components/ComponentOutline.tsx

@@ -0,0 +1,98 @@
+import { For } from "solid-js";
+import { PADDING } from "../consts";
+import { LabelData } from "../types/LabelData";
+import { SimpleDOMRect } from "../types/types";
+
+export function ComponentOutline(props: {
+  bbox: SimpleDOMRect;
+  labels: LabelData[];
+  element: HTMLElement;
+}) {
+  const isInside = () => props.bbox.height >= window.innerHeight - 40;
+  const isBelow = () => props.bbox.y < 30 && !isInside();
+
+  const left = () => Math.max(props.bbox.x - PADDING, 0);
+  const top = () => Math.max(props.bbox.y - PADDING, 0);
+
+  const cutFromTop = () => (props.bbox.y < 0 ? -(props.bbox.y - PADDING) : 0);
+  const cutFromLeft = () => (props.bbox.x < 0 ? -(props.bbox.x - PADDING) : 0);
+
+  const width = () =>
+    Math.min(props.bbox.width - cutFromLeft() + PADDING * 2, window.innerWidth);
+  const height = () =>
+    Math.min(
+      props.bbox.height - cutFromTop() + PADDING * 2,
+      window.innerHeight
+    );
+
+  return (
+    <div
+      class="border border-purple-500"
+      style={{
+        "z-index": 1,
+        position: "fixed",
+        left: left() + "px",
+        top: top() + "px",
+        width: width() + "px",
+        height: height() + "px",
+        "border-top-left-radius": left() === 0 || top() === 0 ? "0" : "8px",
+        "border-top-right-radius":
+          left() + width() === window.innerWidth || top() === 0 ? "0" : "8px",
+        "border-bottom-left-radius":
+          left() === 0 || top() + height() === window.innerHeight ? "0" : "8px",
+        "border-bottom-right-radius":
+          left() + width() === window.innerWidth ||
+          top() + height() === window.innerHeight
+            ? "0"
+            : "8px",
+      }}
+    >
+      <div
+        id="locatorjs-labels-section"
+        style={{
+          position: "absolute",
+          display: "flex",
+          "justify-content": "center",
+          bottom: isBelow() ? (isInside() ? "2px" : "-28px") : undefined,
+          top: isBelow() ? undefined : isInside() ? "2px" : "-28px",
+          left: "0px",
+          width: "100%",
+          "pointer-events": "auto",
+          cursor: "pointer",
+          ...(isBelow()
+            ? {
+                "border-bottom-left-radius": "100%",
+                "border-bottom-right-radius": "100%",
+              }
+            : {
+                "border-top-left-radius": "100%",
+                "border-top-right-radius": "100%",
+              }),
+        }}
+      >
+        <div
+          id="locatorjs-labels-wrapper"
+          style={{
+            padding: isBelow() ? "10px 10px 2px 10px" : "2px 10px 10px 10px",
+          }}
+        >
+          <For each={props.labels}>
+            {(label) => {
+              const labelClass =
+                "bg-purple-500 block text-white text-xs font-bold text-center px-1 py-0.5 rounded whitespace-nowrap pointer-events-auto";
+              const labelStyles = {
+                "line-height": "18px",
+              };
+
+              return (
+                <div class={labelClass} style={labelStyles}>
+                  {label.label}
+                </div>
+              );
+            }}
+          </For>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/MaybeOutline.tsx

@@ -0,0 +1,49 @@
+import { Targets } from "@locator/shared";
+import { createMemo } from "solid-js";
+import { AdapterId } from "../consts";
+import { getElementInfo } from "../adapters/getElementInfo";
+import { Outline } from "./Outline";
+
+export function MaybeOutline(props: {
+  currentElement: HTMLElement;
+  adapterId?: AdapterId;
+  targets: Targets;
+}) {
+  const elInfo = createMemo(() =>
+    getElementInfo(props.currentElement, props.adapterId)
+  );
+  const box = () => props.currentElement.getBoundingClientRect();
+  return (
+    <>
+      {elInfo() ? (
+        <Outline
+          element={elInfo()!}
+          targets={props.targets}
+        />
+      ) : (
+        <div class="fixed top-0 left-0 w-screen h-screen flex items-center justify-center">
+          <div
+            class="flex items-center justify-center"
+            style={{
+              position: "absolute",
+              left: box().x + "px",
+              top: box().y + "px",
+              width: box().width + "px",
+              height: box().height + "px",
+              "background-color": "rgba(222, 0, 0, 0.3)",
+              border: "1px solid rgba(222, 0, 0, 0.5)",
+              "border-radius": "2px",
+              "font-size": "12px",
+              "font-weight": "bold",
+              "text-shadow":
+                "-1px 1px 0 #fff, 1px 1px 0 #fff, 1px -1px 0 #fff, -1px -1px 0 #fff",
+              "text-overflow": "ellipsis",
+            }}
+          >
+            No source found
+          </div>
+        </div>
+      )}
+    </>
+  );
+}

package/src/components/Outline.tsx

@@ -0,0 +1,153 @@
+import type { Targets } from "@locator/shared";
+import type { FullElementInfo } from "../adapters/adapterApi";
+import { RenderBoxes } from "./RenderBoxes";
+
+type Box = {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+  label: string;
+};
+type IndividualBoxes = {
+  top: Box;
+  left: Box;
+  right: Box;
+  bottom: Box;
+};
+
+export type AllBoxes = {
+  margin: IndividualBoxes;
+  padding: IndividualBoxes;
+  innerBox: Box;
+};
+
+export function Outline(props: {
+  element: FullElementInfo;
+  targets: Targets;
+}) {
+  const box = () => props.element.thisElement.box;
+
+  const domElementInfo = () => {
+    const htmlElement = props.element.htmlElement;
+    const box = props.element.thisElement.box;
+    if (htmlElement && box) {
+      const style = window.getComputedStyle(htmlElement);
+
+      const margin = {
+        top: parseFloat(style.marginTop),
+        left: parseFloat(style.marginLeft),
+        right: parseFloat(style.marginRight),
+        bottom: parseFloat(style.marginBottom),
+      };
+      const padding = {
+        top: parseFloat(style.paddingTop),
+        left: parseFloat(style.paddingLeft),
+        right: parseFloat(style.paddingRight),
+        bottom: parseFloat(style.paddingBottom),
+      };
+      const individualMarginBoxes: IndividualBoxes = {
+        top: {
+          top: box.y - margin.top,
+          left: box.x,
+          width: box.width,
+          height: margin.top,
+          label: label(margin.top),
+        },
+        left: {
+          top: box.y - margin.top,
+          left: box.x - margin.left,
+          width: margin.left,
+          height: box.height + margin.top + margin.bottom,
+          label: label(margin.left),
+        },
+        right: {
+          top: box.y - margin.top,
+          left: box.x + box.width,
+          width: margin.right,
+          height: box.height + margin.top + margin.bottom,
+          label: label(margin.right),
+        },
+        bottom: {
+          top: box.y + box.height,
+          left: box.x,
+          width: box.width,
+          height: margin.bottom,
+          label: label(margin.bottom),
+        },
+      };
+
+      const individualPaddingBoxes: IndividualBoxes = {
+        top: {
+          top: box.y,
+          left: box.x,
+          width: box.width,
+          height: padding.top,
+          label: label(padding.top),
+        },
+        left: {
+          top: box.y + padding.top,
+          left: box.x,
+          width: padding.left,
+          height: box.height - padding.top - padding.bottom,
+          label: label(padding.left),
+        },
+        right: {
+          top: box.y + padding.top,
+          left: box.x + box.width - padding.right,
+          width: padding.right,
+          height: box.height - padding.top - padding.bottom,
+          label: label(padding.right),
+        },
+        bottom: {
+          top: box.y + box.height - padding.bottom,
+          left: box.x,
+          width: box.width,
+          height: padding.bottom,
+          label: label(padding.bottom),
+        },
+      };
+
+      return {
+        margin: individualMarginBoxes,
+        padding: individualPaddingBoxes,
+        innerBox: {
+          top: box.y + padding.top,
+          left: box.x + padding.left,
+          width: box.width - padding.left - padding.right,
+          height: box.height - padding.top - padding.bottom,
+          label: "",
+        },
+      };
+    }
+
+    return null;
+  };
+
+  return (
+    <>
+      <div>
+        {domElementInfo() && <RenderBoxes allBoxes={domElementInfo()!} />}
+        <div
+          class="fixed flex text-xs font-bold items-center justify-center text-sky-500 rounded border border-solid border-sky-500"
+          style={{
+            "z-index": 2,
+            left: box().x + "px",
+            top: box().y + "px",
+            width: box().width + "px",
+            height: box().height + "px",
+            "text-shadow":
+              "-1px 1px 0 #fff, 1px 1px 0 #fff, 1px -1px 0 #fff, -1px -1px 0 #fff",
+            "text-overflow": "ellipsis",
+          }}
+        >
+          {props.element.thisElement.label}
+        </div>
+      </div>
+    </>
+  );
+}
+
+function label(value: number) {
+  return value ? `${value}px` : "";
+}

package/src/components/RenderBoxes.tsx

@@ -0,0 +1,57 @@
+import { AllBoxes } from "./Outline";
+
+export function RenderBoxes(props: { allBoxes: AllBoxes }) {
+  return (
+    <>
+      {Object.entries(props.allBoxes.margin).map(([, box]) => {
+        return (
+          <div
+            class="fixed flex text-xs font-bold items-center justify-center text-orange-500 bg-orange-500/30"
+            style={{
+              left: box.left + "px",
+              top: box.top + "px",
+              width: box.width + "px",
+              height: box.height + "px",
+              "text-shadow":
+                "-1px 1px 0 #fff, 1px 1px 0 #fff, 1px -1px 0 #fff, -1px -1px 0 #fff",
+            }}
+          >
+            {/* {box.label} */}
+          </div>
+        );
+      })}
+      {Object.entries(props.allBoxes.padding).map(([, box]) => {
+        return (
+          <div
+            class="fixed flex text-xs font-bold items-center justify-center text-green-500 bg-green-500/30"
+            style={{
+              left: box.left + "px",
+              top: box.top + "px",
+              width: box.width + "px",
+              height: box.height + "px",
+              "text-shadow":
+                "-1px 1px 0 #fff, 1px 1px 0 #fff, 1px -1px 0 #fff, -1px -1px 0 #fff",
+            }}
+          >
+            {/* {box.label} */}
+          </div>
+        );
+      })}
+
+      <div
+        class="fixed flex text-xs font-bold items-center justify-center text-blue-500 bg-blue-500/30"
+        style={{
+          left: props.allBoxes.innerBox.left + "px",
+          top: props.allBoxes.innerBox.top + "px",
+          width: props.allBoxes.innerBox.width + "px",
+          height: props.allBoxes.innerBox.height + "px",
+
+          "text-shadow":
+            "-1px 1px 0 #fff, 1px 1px 0 #fff, 1px -1px 0 #fff, -1px -1px 0 #fff",
+        }}
+      >
+        {props.allBoxes.innerBox.label}
+      </div>
+    </>
+  );
+}