@treelocator/runtime 0.1.0

package/dist/adapters/react/reactAdapter.js

@@ -0,0 +1,114 @@
+import { findDebugSource } from "./findDebugSource";
+import { findFiberByHtmlElement } from "./findFiberByHtmlElement";
+import { getFiberLabel } from "./getFiberLabel";
+import { getAllWrappingParents } from "./getAllWrappingParents";
+import { deduplicateLabels } from "../../functions/deduplicateLabels";
+import { getFiberOwnBoundingBox } from "./getFiberOwnBoundingBox";
+import { getAllParentsElementsAndRootComponent } from "./getAllParentsElementsAndRootComponent";
+import { isStyledElement } from "./isStyled";
+import { goUpByTheTree } from "../goUpByTheTree";
+import { HtmlElementTreeNode } from "../HtmlElementTreeNode";
+export function getElementInfo(found) {
+  // Instead of labels, return this element, parent elements leading to closest component, its component labels, all wrapping components labels.
+  const labels = [];
+  const fiber = findFiberByHtmlElement(found, false);
+  if (fiber) {
+    const {
+      component,
+      componentBox,
+      parentElements
+    } = getAllParentsElementsAndRootComponent(fiber);
+    const allPotentialComponentFibers = getAllWrappingParents(component);
+
+    // This handles a common case when the component root is basically the comopnent itself, so I want to go to usage of the component
+    // TODO: whaat? why? currently I see that it adds the original styled components which is not necessary.
+
+    // if (fiber.return && fiber.return === fiber._debugOwner) {
+    //   allPotentialComponentFibers.unshift(fiber.return);
+    // }
+
+    allPotentialComponentFibers.forEach(fiber => {
+      const fiberWithSource = findDebugSource(fiber);
+      if (fiberWithSource) {
+        const label = getFiberLabel(fiberWithSource.fiber, fiberWithSource.source);
+        labels.push(label);
+      }
+    });
+    const thisLabel = getFiberLabel(fiber, findDebugSource(fiber)?.source);
+    if (isStyledElement(fiber)) {
+      thisLabel.label = `${thisLabel.label} (styled)`;
+    }
+    return {
+      thisElement: {
+        box: getFiberOwnBoundingBox(fiber) || found.getBoundingClientRect(),
+        ...thisLabel
+      },
+      htmlElement: found,
+      parentElements: parentElements,
+      componentBox,
+      componentsLabels: deduplicateLabels(labels)
+    };
+  }
+  return null;
+}
+export class ReactTreeNodeElement extends HtmlElementTreeNode {
+  getSource() {
+    const fiber = findFiberByHtmlElement(this.element, false);
+    if (fiber && fiber._debugSource) {
+      return {
+        fileName: fiber._debugSource.fileName,
+        lineNumber: fiber._debugSource.lineNumber,
+        columnNumber: fiber._debugSource.columnNumber
+      };
+    }
+    return null;
+  }
+  getComponent() {
+    const fiber = findFiberByHtmlElement(this.element, false);
+    const componentFiber = fiber?._debugOwner;
+    if (componentFiber) {
+      const fiberLabel = getFiberLabel(componentFiber, findDebugSource(componentFiber)?.source);
+      return {
+        label: fiberLabel.label,
+        callLink: fiberLabel.link && {
+          fileName: fiberLabel.link.filePath,
+          lineNumber: fiberLabel.link.line,
+          columnNumber: fiberLabel.link.column,
+          projectPath: fiberLabel.link.projectPath
+        } || undefined
+      };
+    }
+    return null;
+  }
+}
+function getTree(element) {
+  const originalRoot = new ReactTreeNodeElement(element);
+  return goUpByTheTree(originalRoot);
+}
+function fiberToPathItem(fiber) {
+  const label = getFiberLabel(fiber, findDebugSource(fiber)?.source);
+  return {
+    title: label.label,
+    link: label.link
+  };
+}
+function getParentsPaths(element) {
+  const fiber = findFiberByHtmlElement(element, false);
+  if (fiber) {
+    const pathItems = [];
+    let currentFiber = fiber;
+    pathItems.push(fiberToPathItem(currentFiber));
+    while (currentFiber._debugOwner) {
+      currentFiber = currentFiber._debugOwner;
+      pathItems.push(fiberToPathItem(currentFiber));
+    }
+    return pathItems;
+  }
+  return [];
+}
+const reactAdapter = {
+  getElementInfo,
+  getTree,
+  getParentsPaths
+};
+export default reactAdapter;

package/dist/adapters/react/searchDevtoolsRenderersForClosestTarget.d.ts

@@ -0,0 +1 @@
+export declare function searchDevtoolsRenderersForClosestTarget(target: HTMLElement): HTMLElement | null;

package/dist/adapters/react/searchDevtoolsRenderersForClosestTarget.js

@@ -0,0 +1,11 @@
+import { findFiberByHtmlElement } from "./findFiberByHtmlElement";
+export function searchDevtoolsRenderersForClosestTarget(target) {
+  let closest = target;
+  while (closest) {
+    if (findFiberByHtmlElement(closest, false)) {
+      return closest;
+    }
+    closest = closest.parentElement;
+  }
+  return null;
+}

package/dist/adapters/svelte/svelteAdapter.d.ts

@@ -0,0 +1,22 @@
+import { Source } from "@locator/shared";
+import { TreeNodeComponent } from "../../types/TreeNode";
+import { AdapterObject, FullElementInfo } from "../adapterApi";
+import { HtmlElementTreeNode } from "../HtmlElementTreeNode";
+type SvelteLoc = {
+    char: number;
+    column: number;
+    file: string;
+    line: number;
+};
+type SvelteElement = HTMLElement & {
+    __svelte_meta?: {
+        loc: SvelteLoc;
+    };
+};
+export declare function getElementInfo(found: SvelteElement): FullElementInfo | null;
+export declare class SvelteTreeNodeElement extends HtmlElementTreeNode {
+    getSource(): Source | null;
+    getComponent(): TreeNodeComponent | null;
+}
+declare const svelteAdapter: AdapterObject;
+export default svelteAdapter;

package/dist/adapters/svelte/svelteAdapter.js

@@ -0,0 +1,88 @@
+import { goUpByTheTree } from "../goUpByTheTree";
+import { HtmlElementTreeNode } from "../HtmlElementTreeNode";
+export function getElementInfo(found) {
+  if (found.__svelte_meta) {
+    const {
+      loc
+    } = found.__svelte_meta;
+    return {
+      thisElement: {
+        box: found.getBoundingClientRect(),
+        label: found.nodeName.toLowerCase(),
+        link: {
+          column: loc.column + 1,
+          line: loc.line + 1,
+          filePath: loc.file,
+          projectPath: ""
+        }
+      },
+      htmlElement: found,
+      parentElements: [],
+      componentBox: found.getBoundingClientRect(),
+      componentsLabels: []
+    };
+  }
+  return null;
+}
+export class SvelteTreeNodeElement extends HtmlElementTreeNode {
+  getSource() {
+    const element = this.element;
+    if (element.__svelte_meta) {
+      const {
+        loc
+      } = element.__svelte_meta;
+      return {
+        fileName: loc.file,
+        lineNumber: loc.line + 1,
+        columnNumber: loc.column + 1
+      };
+    }
+    return null;
+  }
+  getComponent() {
+    return null;
+  }
+}
+function getTree(element) {
+  const originalRoot = new SvelteTreeNodeElement(element);
+  return goUpByTheTree(originalRoot);
+}
+function getParentsPaths(element) {
+  const path = [];
+  let currentElement = element;
+  let maxDepth = 10000; // just in case, it should not be needed
+
+  do {
+    if (currentElement?.__svelte_meta) {
+      const {
+        loc
+      } = currentElement.__svelte_meta;
+
+      // we assume that there is one component per file
+      const isSameFileAsTheLastOne = loc.file === path[path.length - 1]?.link?.filePath;
+      if (!isSameFileAsTheLastOne) {
+        path.push({
+          title: currentElement.nodeName.toLowerCase(),
+          link: {
+            column: loc.column + 1,
+            line: loc.line + 1,
+            filePath: loc.file,
+            projectPath: ""
+          }
+        });
+      }
+    }
+    currentElement = currentElement.parentElement;
+    maxDepth--;
+    if (maxDepth < 0) {
+      break;
+    }
+  } while (currentElement);
+  return path;
+}
+const svelteAdapter = {
+  getElementInfo,
+  getTree,
+  getParentsPaths
+};
+export default svelteAdapter;

package/dist/adapters/vue/getVNodeBoundingBox.d.ts

@@ -0,0 +1,4 @@
+import { SimpleDOMRect } from "../../types/types";
+import type { ComponentInternalInstance, VNode } from "vue";
+export declare function getVueComponentBoundingBox(vcomponent: ComponentInternalInstance): null;
+export declare function getVNodeBoundingBox(vnode: VNode): SimpleDOMRect | null;

package/dist/adapters/vue/getVNodeBoundingBox.js

@@ -0,0 +1,31 @@
+import { mergeRects } from "../../functions/mergeRects";
+export function getVueComponentBoundingBox(vcomponent) {
+  let composedRect = null;
+  if (vcomponent?.subTree?.children && vcomponent?.subTree?.children instanceof Array) {
+    vcomponent?.subTree?.children.forEach(child => {
+      const box = getVNodeBoundingBox(child);
+      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;
+}
+export function getVNodeBoundingBox(vnode) {
+  if (vnode.el instanceof HTMLElement) {
+    return vnode.el.getBoundingClientRect();
+  }
+  if (vnode.component) {
+    return getVueComponentBoundingBox(vnode.component);
+  }
+  return null;
+}

package/dist/adapters/vue/vueAdapter.d.ts

@@ -0,0 +1,15 @@
+import { Source } from "@locator/shared";
+import type { ComponentInternalInstance } from "vue";
+import { TreeNodeComponent } from "../../types/TreeNode";
+import { AdapterObject, FullElementInfo } from "../adapterApi";
+import { HtmlElementTreeNode } from "../HtmlElementTreeNode";
+type VueElement = HTMLElement & {
+    __vueParentComponent?: ComponentInternalInstance;
+};
+export declare function getElementInfo(found: VueElement): FullElementInfo | null;
+export declare class VueTreeNodeElement extends HtmlElementTreeNode {
+    getSource(): Source | null;
+    getComponent(): TreeNodeComponent | null;
+}
+declare const vueAdapter: AdapterObject;
+export default vueAdapter;

package/dist/adapters/vue/vueAdapter.js

@@ -0,0 +1,113 @@
+import { goUpByTheTree } from "../goUpByTheTree";
+import { HtmlElementTreeNode } from "../HtmlElementTreeNode";
+import { getVueComponentBoundingBox } from "./getVNodeBoundingBox";
+export function getElementInfo(found) {
+  const parentComponent = found.__vueParentComponent;
+  if (parentComponent) {
+    if (!parentComponent.type) {
+      return null;
+    }
+    const componentBBox = getVueComponentBoundingBox(parentComponent);
+    const {
+      __file,
+      __name
+    } = parentComponent.type;
+    if (__file && __name) {
+      return {
+        thisElement: {
+          box: found.getBoundingClientRect(),
+          label: found.nodeName.toLowerCase(),
+          link: {
+            column: 1,
+            line: 1,
+            filePath: __file,
+            projectPath: ""
+          }
+        },
+        htmlElement: found,
+        parentElements: [],
+        componentBox: componentBBox || found.getBoundingClientRect(),
+        componentsLabels: [{
+          label: __name,
+          link: {
+            column: 1,
+            line: 1,
+            filePath: __file,
+            projectPath: ""
+          }
+        }]
+      };
+    }
+  }
+  return null;
+}
+export class VueTreeNodeElement extends HtmlElementTreeNode {
+  getSource() {
+    const element = this.element;
+    const parentComponent = element.__vueParentComponent;
+    if (parentComponent && parentComponent.type) {
+      const {
+        __file
+      } = parentComponent.type;
+      if (__file) {
+        return {
+          fileName: __file,
+          lineNumber: 1,
+          columnNumber: 1
+        };
+      }
+    }
+    return null;
+  }
+  getComponent() {
+    return null;
+  }
+  // getComponent(): TreeNodeComponent | null {
+  //   const element = this.element as VueElement;
+  //   const parentComponent = element.__vueParentComponent;
+  //   if (parentComponent && parentComponent.type) {
+  //     const { __name } = parentComponent.type;
+  //     if (__name) {
+  //       return {
+  //         label: __name,
+  //         definitionLink: this.getSource() || undefined,
+  //       };
+  //     }
+  //   }
+  //   return null;
+  // }
+}
+function getTree(element) {
+  const originalRoot = new VueTreeNodeElement(element);
+  return goUpByTheTree(originalRoot);
+}
+function getParentsPaths(element) {
+  const path = [];
+  let currentElement = element;
+  let previousComponentKey = null;
+  do {
+    if (currentElement) {
+      const info = getElementInfo(currentElement);
+      const currentComponentKey = JSON.stringify(info?.componentsLabels);
+      if (info && currentComponentKey !== previousComponentKey) {
+        previousComponentKey = currentComponentKey;
+        const link = info.thisElement.link;
+        const label = info.thisElement.label;
+        if (link) {
+          path.push({
+            title: label,
+            link: link
+          });
+        }
+      }
+    }
+    currentElement = currentElement.parentElement;
+  } while (currentElement);
+  return path;
+}
+const vueAdapter = {
+  getElementInfo,
+  getTree,
+  getParentsPaths
+};
+export default vueAdapter;

package/dist/browserApi.d.ts

@@ -0,0 +1,103 @@
+import { AdapterId } from "./consts";
+import { 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;
+}
+export declare function createBrowserAPI(adapterIdParam?: AdapterId): LocatorJSAPI;
+export declare function installBrowserAPI(adapterIdParam?: AdapterId): void;

package/dist/browserApi.js

@@ -0,0 +1,160 @@
+import { createTreeNode } from "./adapters/createTreeNode";
+import { collectAncestry, formatAncestryChain } from "./functions/formatAncestryChain";
+let adapterId;
+function resolveElement(elementOrSelector) {
+  if (typeof elementOrSelector === "string") {
+    const element = document.querySelector(elementOrSelector);
+    return element instanceof HTMLElement ? element : null;
+  }
+  return elementOrSelector;
+}
+function getAncestryForElement(element) {
+  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 = adapterIdParam;
+  return {
+    getPath(elementOrSelector) {
+      const element = resolveElement(elementOrSelector);
+      if (!element) {
+        return null;
+      }
+      const ancestry = getAncestryForElement(element);
+      if (!ancestry) {
+        return null;
+      }
+      return formatAncestryChain(ancestry);
+    },
+    getAncestry(elementOrSelector) {
+      const element = resolveElement(elementOrSelector);
+      if (!element) {
+        return null;
+      }
+      return getAncestryForElement(element);
+    },
+    getPathData(elementOrSelector) {
+      const element = resolveElement(elementOrSelector);
+      if (!element) {
+        return null;
+      }
+      const ancestry = getAncestryForElement(element);
+      if (!ancestry) {
+        return null;
+      }
+      return {
+        path: formatAncestryChain(ancestry),
+        ancestry
+      };
+    },
+    help() {
+      return HELP_TEXT;
+    }
+  };
+}
+export function installBrowserAPI(adapterIdParam) {
+  if (typeof window !== "undefined") {
+    window.__locatorjs__ = createBrowserAPI(adapterIdParam);
+  }
+}

package/dist/components/Button.d.ts

@@ -0,0 +1,4 @@
+export declare function Button(props: {
+    onClick: () => void;
+    children: any;
+}): import("solid-js").JSX.Element;

package/dist/components/Button.js

@@ -0,0 +1,17 @@
+import { template as _$template } from "solid-js/web";
+import { delegateEvents as _$delegateEvents } from "solid-js/web";
+import { insert as _$insert } from "solid-js/web";
+var _tmpl$ = /*#__PURE__*/_$template(`<button class="py-1 px-1 hover:bg-white/30 pointer hover:text-gray-100 rounded">`);
+export function Button(props) {
+  return (() => {
+    var _el$ = _tmpl$();
+    _el$.$$click = e => {
+      e.preventDefault();
+      e.stopPropagation();
+      props.onClick();
+    };
+    _$insert(_el$, () => props.children);
+    return _el$;
+  })();
+}
+_$delegateEvents(["click"]);