@treelocator/runtime 0.1.7 → 0.2.0

package/src/adapters/jsx/getExpressionData.ts

@@ -2,12 +2,16 @@ import type { ExpressionInfo, FileStorage } from "@locator/shared";
 import { parseDataId, parseDataPath } from "../../functions/parseDataId";
 
 export function getExpressionData(
-  target: HTMLElement,
+  target: Element,
   fileData: FileStorage | null
 ): ExpressionInfo | null {
+  // Use getAttribute instead of dataset to support both HTML and SVG elements
+  const dataLocatorjs = target.getAttribute("data-locatorjs");
+  const dataLocatorjsId = target.getAttribute("data-locatorjs-id");
+
   // First check for data-locatorjs (path-based, for server components)
-  if (target.dataset.locatorjs) {
-    const parsed = parseDataPath(target.dataset.locatorjs);
+  if (dataLocatorjs) {
+    const parsed = parseDataPath(dataLocatorjs);
     if (parsed) {
       const [, line, column] = parsed;
 
@@ -35,8 +39,8 @@ export function getExpressionData(
   }
 
   // Fall back to data-locatorjs-id (ID-based, traditional approach)
-  if (target.dataset.locatorjsId && fileData) {
-    const [, id] = parseDataId(target.dataset.locatorjsId);
+  if (dataLocatorjsId && fileData) {
+    const [, id] = parseDataId(dataLocatorjsId);
     const expData = fileData.expressions[Number(id)];
     if (expData) {
       return expData;

package/src/adapters/jsx/getJSXComponentBoundingBox.ts

@@ -5,32 +5,37 @@ import type { SimpleDOMRect } from "../../types/types";
 import { getExpressionData } from "./getExpressionData";
 
 export function getJSXComponentBoundingBox(
-  found: HTMLElement,
+  found: Element,
   locatorData: { [filename: string]: FileStorage },
   componentFolder: string,
   componentId: number
 ): SimpleDOMRect {
   let composedBox: SimpleDOMRect = found.getBoundingClientRect();
   // Currently it works well only for components with one root element, but for components with multiple root elements we would need to track instance ids.
-  function goParent(current: HTMLElement) {
+  function goParent(current: Element) {
     const parent = current.parentNode;
     if (!parent) {
       return;
     }
-    if (parent instanceof HTMLElement) {
+    // Support both HTMLElement and SVGElement
+    if (parent instanceof HTMLElement || parent instanceof SVGElement) {
+      // Use getAttribute instead of dataset to support both HTML and SVG elements
+      const dataLocatorjs = parent.getAttribute("data-locatorjs");
+      const dataLocatorjsId = parent.getAttribute("data-locatorjs-id");
+
       // Check for either data-locatorjs (path-based) or data-locatorjs-id (ID-based)
-      if (parent.dataset.locatorjs || parent.dataset.locatorjsId) {
+      if (dataLocatorjs || dataLocatorjsId) {
         let fileFullPath: string;
 
-        if (parent.dataset.locatorjs) {
-          const parsed = parseDataPath(parent.dataset.locatorjs);
+        if (dataLocatorjs) {
+          const parsed = parseDataPath(dataLocatorjs);
           if (!parsed) {
             goParent(parent);
             return;
           }
           [fileFullPath] = parsed;
-        } else if (parent.dataset.locatorjsId) {
-          [fileFullPath] = parseDataId(parent.dataset.locatorjsId);
+        } else if (dataLocatorjsId) {
+          [fileFullPath] = parseDataId(dataLocatorjsId);
         } else {
           goParent(parent);
           return;

package/src/adapters/jsx/jsxAdapter.ts

@@ -20,17 +20,17 @@ import { getJSXComponentBoundingBox } from "./getJSXComponentBoundingBox";
 export function getElementInfo(target: HTMLElement): FullElementInfo | null {
   const found = target.closest("[data-locatorjs-id], [data-locatorjs]");
 
+  // Support both HTMLElement and SVGElement
+  // SVG elements don't have dataset, so use getAttribute instead
+  const dataId = found?.getAttribute("data-locatorjs-id");
+  const dataPath = found?.getAttribute("data-locatorjs");
+  const styledDataId = found?.getAttribute("data-locatorjs-styled");
+
   if (
     found &&
-    found instanceof HTMLElement &&
-    found.dataset &&
-    (found.dataset.locatorjsId ||
-      found.dataset.locatorjs ||
-      found.dataset.locatorjsStyled)
+    (found instanceof HTMLElement || found instanceof SVGElement) &&
+    (dataId || dataPath || styledDataId)
   ) {
-    const dataId = found.dataset.locatorjsId;
-    const dataPath = found.dataset.locatorjs;
-    const styledDataId = found.dataset.locatorjsStyled;
 
     if (!dataId && !dataPath) {
       return null;
@@ -135,8 +135,9 @@ export function getElementInfo(target: HTMLElement): FullElementInfo | null {
 
 export class JSXTreeNodeElement extends HtmlElementTreeNode {
   getSource(): Source | null {
-    const dataId = this.element.dataset.locatorjsId;
-    const dataPath = this.element.dataset.locatorjs;
+    // Use getAttribute instead of dataset to support both HTML and SVG elements
+    const dataId = this.element.getAttribute("data-locatorjs-id");
+    const dataPath = this.element.getAttribute("data-locatorjs");
 
     if (!dataId && !dataPath) {
       return null;
@@ -184,8 +185,9 @@ export class JSXTreeNodeElement extends HtmlElementTreeNode {
     return null;
   }
   getComponent(): TreeNodeComponent | null {
-    const dataId = this.element.dataset.locatorjsId;
-    const dataPath = this.element.dataset.locatorjs;
+    // Use getAttribute instead of dataset to support both HTML and SVG elements
+    const dataId = this.element.getAttribute("data-locatorjs-id");
+    const dataPath = this.element.getAttribute("data-locatorjs");
 
     if (!dataId && !dataPath) {
       return null;

package/src/adapters/nextjs/parseNextjsDataAttributes.ts

@@ -0,0 +1,112 @@
+import { ServerComponentInfo } from "../../types/ServerComponentInfo";
+import { normalizeFilePath } from "../../functions/normalizeFilePath";
+
+/**
+ * Parse Next.js server component data from data-locatorjs attribute.
+ *
+ * Format: data-locatorjs="/path/to/app/layout.tsx:27:4"
+ *
+ * The @treelocator/webpack-loader adds these attributes to elements
+ * rendered by Next.js Server Components.
+ */
+
+/**
+ * Extract component name from file path.
+ * Examples:
+ *   - "/apps/next-16/app/layout.tsx:27:4" → "RootLayout"
+ *   - "/apps/next-16/app/page.tsx:5:4" → "Home"
+ *   - "/apps/next-16/app/components/Header.tsx:10:2" → "Header"
+ */
+function extractComponentName(filePath: string): string {
+  // Remove line:column suffix
+  const pathOnly = filePath.split(":")[0] || filePath;
+
+  // Get filename without extension
+  const fileName = pathOnly.split("/").pop()?.replace(/\.(tsx?|jsx?)$/, "") || "Unknown";
+
+  // Common Next.js conventions:
+  // - "layout" → "RootLayout" or "Layout"
+  // - "page" → Component name (we don't know it, so use "Page")
+  // - Others → Use as-is
+  if (fileName === "layout") {
+    return "RootLayout";
+  } else if (fileName === "page") {
+    return "Page";
+  }
+
+  return fileName;
+}
+
+/**
+ * Parse a data-locatorjs attribute value.
+ * Format: "/path/to/file.tsx:line:column"
+ * Returns ServerComponentInfo or null if parsing fails.
+ */
+function parseDataLocatorjsValue(value: string): ServerComponentInfo | null {
+  if (!value) return null;
+
+  // Split by ":" to get [filePath, line, column]
+  const parts = value.split(":");
+  if (parts.length < 2) return null;
+
+  // Last two parts are column and line (in reverse order)
+  const column = parts.pop();
+  const line = parts.pop();
+
+  // Everything else is the file path (which may contain colons on Windows)
+  const filePath = parts.join(":");
+
+  if (!filePath || !line) return null;
+
+  const componentName = extractComponentName(filePath);
+  const normalizedPath = normalizeFilePath(filePath);
+
+  return {
+    name: componentName,
+    filePath: normalizedPath,
+    line: parseInt(line, 10),
+    type: "component",
+  };
+}
+
+/**
+ * Get the data-locatorjs attribute from the current element only.
+ * Returns array with single component info, or empty array if not found.
+ *
+ * We only look at the current element because the tree structure already
+ * shows the hierarchy - each parent element will have its own server component.
+ *
+ * Example DOM:
+ * ```html
+ * <html data-locatorjs="/app/layout.tsx:27:4">        <!-- RootLayout -->
+ *   <body data-locatorjs="/app/layout.tsx:28:6">      <!-- RootLayout -->
+ *     <div data-locatorjs="/app/page.tsx:5:4">        <!-- Page -->
+ *       <button>Click</button>
+ *     </div>
+ *   </body>
+ * </html>
+ * ```
+ *
+ * For the div, returns: [{ name: "Page", filePath: "/app/page.tsx", line: 5 }]
+ * The tree structure will show: html (RootLayout) > body (RootLayout) > div (Page)
+ */
+export function collectNextjsServerComponents(element: Element): ServerComponentInfo[] {
+  const value = element.getAttribute("data-locatorjs");
+  if (!value) return [];
+
+  const info = parseDataLocatorjsValue(value);
+  return info ? [info] : [];
+}
+
+/**
+ * Main entry point: extract Next.js server component info from element.
+ * Returns null if no data-locatorjs attribute found.
+ *
+ * This function is called during ancestry collection to enrich each AncestryItem
+ * with server-side Next.js component information.
+ */
+export function parseNextjsServerComponents(element: Element): ServerComponentInfo[] | null {
+  const components = collectNextjsServerComponents(element);
+  if (components.length === 0) return null;
+  return components;
+}

package/src/adapters/phoenix/__tests__/parsePhoenixComments.test.ts

@@ -0,0 +1,264 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  findPrecedingPhoenixComments,
+  phoenixMatchesToServerComponents,
+  parsePhoenixServerComponents,
+} from "../parsePhoenixComments";
+
+describe("parsePhoenixComments", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+  });
+
+  describe("findPrecedingPhoenixComments", () => {
+    it("parses @caller comment", () => {
+      container.innerHTML = `
+        <!-- @caller lib/app_web/home_live.ex:20 -->
+        <header>Content</header>
+      `;
+
+      const header = container.querySelector("header")!;
+      const matches = findPrecedingPhoenixComments(header);
+
+      expect(matches).toHaveLength(1);
+      expect(matches[0]).toMatchObject({
+        name: "@caller",
+        filePath: "lib/app_web/home_live.ex",
+        line: 20,
+        type: "caller",
+      });
+    });
+
+    it("parses component comment", () => {
+      container.innerHTML = `
+        <!-- <AppWeb.CoreComponents.header> lib/app_web/core_components.ex:123 -->
+        <header>Content</header>
+      `;
+
+      const header = container.querySelector("header")!;
+      const matches = findPrecedingPhoenixComments(header);
+
+      expect(matches).toHaveLength(1);
+      expect(matches[0]).toMatchObject({
+        name: "AppWeb.CoreComponents.header",
+        filePath: "lib/app_web/core_components.ex",
+        line: 123,
+        type: "component",
+      });
+    });
+
+    it("ignores closing tag comments", () => {
+      container.innerHTML = `
+        <!-- </AppWeb.CoreComponents.header> -->
+        <header>Content</header>
+      `;
+
+      const header = container.querySelector("header")!;
+      const matches = findPrecedingPhoenixComments(header);
+
+      expect(matches).toHaveLength(0);
+    });
+
+    it("finds multiple preceding comments in correct order", () => {
+      container.innerHTML = `
+        <!-- @caller lib/app_web/home_live.ex:20 -->
+        <!-- <AppWeb.CoreComponents.header> lib/app_web/core_components.ex:123 -->
+        <header>Content</header>
+      `;
+
+      const header = container.querySelector("header")!;
+      const matches = findPrecedingPhoenixComments(header);
+
+      expect(matches).toHaveLength(2);
+      // Should be ordered from outermost to innermost
+      expect(matches[0]!.name).toBe("@caller");
+      expect(matches[0]!.line).toBe(20);
+      expect(matches[1]!.name).toBe("AppWeb.CoreComponents.header");
+      expect(matches[1]!.line).toBe(123);
+    });
+
+    it("stops at non-comment element node", () => {
+      container.innerHTML = `
+        <div>Other element</div>
+        <!-- <AppWeb.CoreComponents.header> lib/app_web/core_components.ex:123 -->
+        <header>Content</header>
+      `;
+
+      const header = container.querySelector("header")!;
+      const matches = findPrecedingPhoenixComments(header);
+
+      // Should only find the comment between the div and header
+      expect(matches).toHaveLength(1);
+      expect(matches[0]!.name).toBe("AppWeb.CoreComponents.header");
+    });
+
+    it("skips whitespace text nodes", () => {
+      container.innerHTML = `
+        <!-- @caller lib/app_web/home_live.ex:20 -->
+
+        <header>Content</header>
+      `;
+
+      const header = container.querySelector("header")!;
+      const matches = findPrecedingPhoenixComments(header);
+
+      // Should find the comment despite whitespace text node
+      expect(matches).toHaveLength(1);
+      expect(matches[0]!.name).toBe("@caller");
+    });
+
+    it("stops at non-whitespace text node", () => {
+      container.innerHTML = `
+        <!-- @caller lib/app_web/home_live.ex:20 -->
+        Some text
+        <header>Content</header>
+      `;
+
+      const header = container.querySelector("header")!;
+      const matches = findPrecedingPhoenixComments(header);
+
+      // Should stop at the text node, not finding the comment
+      expect(matches).toHaveLength(0);
+    });
+
+    it("returns empty array if no preceding comments", () => {
+      container.innerHTML = `<header>Content</header>`;
+
+      const header = container.querySelector("header")!;
+      const matches = findPrecedingPhoenixComments(header);
+
+      expect(matches).toHaveLength(0);
+    });
+
+    it("ignores non-Phoenix comments", () => {
+      container.innerHTML = `
+        <!-- Regular HTML comment -->
+        <header>Content</header>
+      `;
+
+      const header = container.querySelector("header")!;
+      const matches = findPrecedingPhoenixComments(header);
+
+      expect(matches).toHaveLength(0);
+    });
+
+    it("finds Phoenix comments and ignores non-Phoenix comments", () => {
+      container.innerHTML = `
+        <!-- Regular comment -->
+        <!-- @caller lib/app_web/home_live.ex:20 -->
+        <!-- Another regular comment -->
+        <!-- <AppWeb.CoreComponents.header> lib/app_web/core_components.ex:123 -->
+        <header>Content</header>
+      `;
+
+      const header = container.querySelector("header")!;
+      const matches = findPrecedingPhoenixComments(header);
+
+      // Should only find the 2 Phoenix comments
+      expect(matches).toHaveLength(2);
+      expect(matches[0]!.name).toBe("@caller");
+      expect(matches[1]!.name).toBe("AppWeb.CoreComponents.header");
+    });
+  });
+
+  describe("phoenixMatchesToServerComponents", () => {
+    it("converts matches to ServerComponentInfo format", () => {
+      container.innerHTML = `
+        <!-- @caller lib/app_web/home_live.ex:20 -->
+        <!-- <AppWeb.CoreComponents.button> lib/app_web/core_components.ex:456 -->
+        <button>Click</button>
+      `;
+
+      const button = container.querySelector("button")!;
+      const matches = findPrecedingPhoenixComments(button);
+      const serverComponents = phoenixMatchesToServerComponents(matches);
+
+      expect(serverComponents).toHaveLength(2);
+      expect(serverComponents[0]).toEqual({
+        name: "@caller",
+        filePath: "lib/app_web/home_live.ex",
+        line: 20,
+        type: "caller",
+      });
+      expect(serverComponents[1]).toEqual({
+        name: "AppWeb.CoreComponents.button",
+        filePath: "lib/app_web/core_components.ex",
+        line: 456,
+        type: "component",
+      });
+    });
+  });
+
+  describe("parsePhoenixServerComponents", () => {
+    it("returns ServerComponentInfo array when comments found", () => {
+      container.innerHTML = `
+        <!-- @caller lib/app_web/home_live.ex:48 -->
+        <!-- <AppWeb.CoreComponents.button> lib/app_web/core_components.ex:456 -->
+        <button data-phx-loc="458">Click Me</button>
+      `;
+
+      const button = container.querySelector("button")!;
+      const result = parsePhoenixServerComponents(button);
+
+      expect(result).not.toBeNull();
+      expect(result!).toHaveLength(2);
+      expect(result![0]).toEqual({
+        name: "@caller",
+        filePath: "lib/app_web/home_live.ex",
+        line: 48,
+        type: "caller",
+      });
+      expect(result![1]).toEqual({
+        name: "AppWeb.CoreComponents.button",
+        filePath: "lib/app_web/core_components.ex",
+        line: 456,
+        type: "component",
+      });
+    });
+
+    it("returns null when no comments found", () => {
+      container.innerHTML = `<button>Click Me</button>`;
+
+      const button = container.querySelector("button")!;
+      const result = parsePhoenixServerComponents(button);
+
+      expect(result).toBeNull();
+    });
+
+    it("handles nested structure with multiple components", () => {
+      container.innerHTML = `
+        <!-- @caller lib/app_web/home_live.ex:20 -->
+        <!-- <AppWeb.CoreComponents.header> lib/app_web/core_components.ex:123 -->
+        <header data-phx-loc="125" class="p-5">
+          <!-- @caller lib/app_web/home_live.ex:48 -->
+          <!-- <AppWeb.CoreComponents.button> lib/app_web/core_components.ex:456 -->
+          <button data-phx-loc="458" class="px-2">Click</button>
+        </header>
+      `;
+
+      const header = container.querySelector("header")!;
+      const headerResult = parsePhoenixServerComponents(header);
+
+      expect(headerResult).not.toBeNull();
+      expect(headerResult!).toHaveLength(2);
+      expect(headerResult![0]!.name).toBe("@caller");
+      expect(headerResult![0]!.line).toBe(20);
+      expect(headerResult![1]!.name).toBe("AppWeb.CoreComponents.header");
+
+      const button = container.querySelector("button")!;
+      const buttonResult = parsePhoenixServerComponents(button);
+
+      expect(buttonResult).not.toBeNull();
+      expect(buttonResult!).toHaveLength(2);
+      expect(buttonResult![0]!.name).toBe("@caller");
+      expect(buttonResult![0]!.line).toBe(48);
+      expect(buttonResult![1]!.name).toBe("AppWeb.CoreComponents.button");
+    });
+  });
+});

package/src/adapters/phoenix/detectPhoenix.ts

@@ -0,0 +1,44 @@
+/**
+ * Detect if Phoenix LiveView is present on the page.
+ *
+ * Checks for multiple signals:
+ * 1. window.liveSocket - Phoenix LiveView JS client
+ * 2. data-phx-* attributes in the DOM
+ * 3. Phoenix debug comment patterns
+ *
+ * Returns true if any signal indicates Phoenix LiveView is running.
+ */
+export function detectPhoenix(): boolean {
+  // Check 1: Look for LiveView socket (most reliable)
+  if (typeof window !== "undefined" && (window as any).liveSocket) {
+    return true;
+  }
+
+  // Check 2: Look for Phoenix data attributes in the DOM
+  if (typeof document !== "undefined") {
+    // Phoenix LiveView adds data-phx-main or data-phx-session to the main LiveView container
+    if (document.querySelector("[data-phx-main], [data-phx-session]")) {
+      return true;
+    }
+
+    // Check 3: Quick scan for Phoenix debug comments (first 50 comments)
+    // This is useful when debug_heex_annotations is enabled
+    const walker = document.createTreeWalker(
+      document.body,
+      NodeFilter.SHOW_COMMENT,
+      null
+    );
+
+    let count = 0;
+    while (walker.nextNode() && count < 50) {
+      const text = walker.currentNode.textContent;
+      // Look for Phoenix-specific comment patterns
+      if (text?.includes("@caller") || text?.includes("<App")) {
+        return true;
+      }
+      count++;
+    }
+  }
+
+  return false;
+}

package/src/adapters/phoenix/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Phoenix LiveView adapter for TreeLocatorJS.
+ *
+ * Parses server-side component information from Phoenix LiveView debug annotations.
+ * Requires Phoenix LiveView v1.1+ with debug_heex_annotations: true in config.
+ */
+
+export { parsePhoenixServerComponents, findPrecedingPhoenixComments } from "./parsePhoenixComments";
+export { detectPhoenix } from "./detectPhoenix";
+export type { ServerComponentInfo } from "../../types/ServerComponentInfo";
+export type { PhoenixCommentMatch } from "./types";