@library/dom 0.0.6

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@library/dom",
+  "version": "0.0.6",
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "types": "./dist/cjs/index.d.cts",
+  "module": "./dist/esm/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    }
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "rimraf dist && tsup --tsconfig tsconfig.build.json",
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "e1d0caf47e9ca8305ad84b2e2284c30fbe6b754d"
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { uniqueSelectorOf } from "./uniqueSelectorOf";

package/src/uniqueSelectorOf.spec.ts

@@ -0,0 +1,242 @@
+import { uniqueSelectorOf } from "./uniqueSelectorOf";
+
+describe("uniqueSelectorOf", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("should return ID selector when element has an ID", () => {
+    document.body.innerHTML = '<div id="myId"></div>';
+    const el = document.getElementById("myId")!;
+
+    expect(uniqueSelectorOf(el)).toBe("#myId");
+  });
+
+  it("should return unique class selector", () => {
+    document.body.innerHTML = '<div class="unique-class"></div>';
+    const el = document.querySelector(".unique-class") as HTMLElement;
+
+    expect(uniqueSelectorOf(el)).toBe(".unique-class");
+  });
+
+  it("should return combined class selector when single classes are not unique", () => {
+    document.body.innerHTML = `
+            <div class="common another"></div>
+            <div class="common unique"></div>
+        `;
+    const el = document.querySelector(".unique") as HTMLElement;
+
+    // .unique is actually unique in this case, so it should return .unique
+    expect(uniqueSelectorOf(el)).toBe(".unique");
+  });
+
+  it("should prefer single class over combined classes when unique", () => {
+    document.body.innerHTML = '<div class="first second"></div>';
+    const el = document.querySelector(".first") as HTMLElement;
+
+    const result = uniqueSelectorOf(el);
+    expect(result === ".first" || result === ".second").toBe(true);
+  });
+
+  it("should return path with nth-of-type when classes are not unique", () => {
+    document.body.innerHTML = `
+            <div>
+                <p>First</p>
+                <p>Second</p>
+                <p>Third</p>
+            </div>
+        `;
+    const el = document.querySelectorAll("p")[1] as HTMLElement;
+
+    // Returns shortest unique path - p:nth-of-type(2) is already unique
+    expect(uniqueSelectorOf(el)).toBe("p:nth-of-type(2)");
+  });
+
+  it("should return shortest unique path", () => {
+    document.body.innerHTML = `
+            <div>
+                <section>
+                    <p>First</p>
+                </section>
+            </div>
+        `;
+    const el = document.querySelector("p") as HTMLElement;
+
+    // Should return shortest unique path
+    expect(uniqueSelectorOf(el)).toBe("p");
+  });
+
+  it("should handle nested elements with same tag", () => {
+    document.body.innerHTML = `
+            <div>
+                <span>1</span>
+                <span>2</span>
+            </div>
+            <div>
+                <span>3</span>
+                <span>4</span>
+            </div>
+        `;
+    const el = document.querySelectorAll("span")[2] as HTMLElement;
+
+    expect(uniqueSelectorOf(el)).toBe(
+      "div:nth-of-type(2) > span:nth-of-type(1)",
+    );
+  });
+
+  it("should stop at parent with ID when needed", () => {
+    document.body.innerHTML = `
+            <div id="parent">
+                <p>Content</p>
+            </div>
+            <div>
+                <p>Another p</p>
+            </div>
+        `;
+    const el = document.querySelector("#parent p") as HTMLElement;
+
+    // Should use parent ID to make it unique
+    expect(uniqueSelectorOf(el)).toBe("#parent > p");
+  });
+
+  it("should return unique selector for deeply nested elements", () => {
+    document.body.innerHTML = `
+            <div>
+                <div>
+                    <div>
+                        <span>Target</span>
+                    </div>
+                </div>
+            </div>
+        `;
+    const el = document.querySelector("span") as HTMLElement;
+
+    const selector = uniqueSelectorOf(el)!;
+    expect(document.querySelectorAll(selector).length).toBe(1);
+    expect(document.querySelector(selector)).toBe(el);
+  });
+
+  it("should handle elements with multiple non-unique classes", () => {
+    document.body.innerHTML = `
+            <div class="common shared">1</div>
+            <div class="common shared">2</div>
+            <div class="common shared">3</div>
+        `;
+    const el = document.querySelectorAll("div")[1] as HTMLElement;
+
+    const selector = uniqueSelectorOf(el)!;
+    expect(document.querySelectorAll(selector).length).toBe(1);
+    expect(document.querySelector(selector)).toBe(el);
+  });
+
+  it("should handle body element", () => {
+    const selector = uniqueSelectorOf(document.body)!;
+
+    expect(selector).toBe("body");
+    expect(document.querySelector(selector)).toBe(document.body);
+  });
+
+  it("should return unique selector even for complex DOM", () => {
+    document.body.innerHTML = `
+            <div>
+                <div>
+                    <span class="common">1</span>
+                    <span class="common">2</span>
+                </div>
+                <div>
+                    <span class="common">3</span>
+                    <span class="common">4</span>
+                </div>
+            </div>
+        `;
+    const el = document.querySelectorAll(".common")[2] as HTMLElement;
+
+    const selector = uniqueSelectorOf(el)!;
+    expect(document.querySelectorAll(selector).length).toBe(1);
+    expect(document.querySelector(selector)).toBe(el);
+  });
+
+  it("should handle elements with empty class attribute", () => {
+    document.body.innerHTML = `
+            <div class="">
+                <p></p>
+            </div>
+        `;
+    const el = document.querySelector("p") as HTMLElement;
+
+    expect(uniqueSelectorOf(el)).toBe("p");
+  });
+
+  it("should verify returned selector actually queries the correct element", () => {
+    document.body.innerHTML = `
+            <div id="container">
+                <div class="row">
+                    <span>A</span>
+                    <span>B</span>
+                </div>
+                <div class="row">
+                    <span>C</span>
+                    <span>D</span>
+                </div>
+            </div>
+        `;
+
+    const allSpans = document.querySelectorAll("span");
+
+    allSpans.forEach((span) => {
+      const selector = uniqueSelectorOf(span as HTMLElement)!;
+      const queried = document.querySelector(selector);
+
+      expect(queried).toBe(span);
+      expect(document.querySelectorAll(selector).length).toBe(1);
+    });
+  });
+
+  it("should return combined class selector when unique", () => {
+    document.body.innerHTML = `
+            <div class="foo">1</div>
+            <div class="bar">2</div>
+            <div class="foo bar">3</div>
+        `;
+    const el = document.querySelector(".foo.bar") as HTMLElement;
+
+    expect(uniqueSelectorOf(el)).toBe(".foo.bar");
+  });
+
+  it("should handle elements without parent", () => {
+    const html = document.documentElement;
+
+    const selector = uniqueSelectorOf(html);
+    expect(selector).toBe("html");
+  });
+
+  it("should handle case where path never becomes unique until root", () => {
+    // Create a scenario where we traverse all the way to root
+    // This tests the final return path.join(' > ') at line 79
+    document.body.innerHTML = `
+            <div>
+                <div>
+                    <div>
+                        <div>
+                            <span></span>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        `;
+
+    const span = document.querySelector("span") as HTMLElement;
+    const selector = uniqueSelectorOf(span)!;
+
+    // Should return the full path and be unique
+    expect(document.querySelectorAll(selector).length).toBe(1);
+    expect(document.querySelector(selector)).toBe(span);
+  });
+
+  it("should return null when unable to generate unique selector", () => {
+    // Create a detached element that's not in the document
+    const detachedElement = document.createElement("div");
+
+    expect(uniqueSelectorOf(detachedElement)).toBeNull();
+  });
+});

package/src/uniqueSelectorOf.ts

@@ -0,0 +1,79 @@
+/**
+ * Generate the shortest unique querySelector string that identifies the given element.
+ * Priority: id > unique class > path with nth-of-type
+ * @param {HTMLElement} element - The HTML element to generate a query selector for.
+ * @returns {string | null} - A unique query selector string that can be used with document.querySelector.
+ * @example
+ * ```
+ * import { queryKeyOf } from "@library/dom";
+ *
+ * const el = document.getElementById('myId');
+ * queryKeyOf(el); // "#myId"
+ *
+ * const el2 = document.querySelector('.unique-class');
+ * queryKeyOf(el2); // ".unique-class"
+ * ```
+ */
+export function uniqueSelectorOf(element: HTMLElement): string | null {
+  // 1. ID is the shortest and always unique
+  if (element.id) {
+    return `#${element.id}`;
+  }
+
+  // 2. Check for unique class combinations
+  if (element.className) {
+    const classes = element.className.trim().split(/\s+/).filter(Boolean);
+
+    // Try single classes first
+    for (const cls of classes) {
+      const selector = `.${cls}`;
+      if (document.querySelectorAll(selector).length === 1) {
+        return selector;
+      }
+    }
+
+    // Try class combinations
+    if (classes.length > 1) {
+      const selector = classes.map((c) => `.${c}`).join("");
+      if (document.querySelectorAll(selector).length === 1) {
+        return selector;
+      }
+    }
+  }
+
+  // 3. Build path from root until unique
+  const path: string[] = [];
+  let current: HTMLElement | null = element;
+
+  while (current && current.nodeType === Node.ELEMENT_NODE) {
+    let selector = current.tagName.toLowerCase();
+
+    // If parent exists, add nth-of-type
+    if (current.parentElement) {
+      const siblings = Array.from(current.parentElement.children).filter(
+        (el) => el.tagName === current!.tagName,
+      );
+
+      if (siblings.length > 1) {
+        const index = siblings.indexOf(current) + 1;
+        selector += `:nth-of-type(${index})`;
+      }
+    }
+
+    path.unshift(selector);
+
+    // Check if current path is unique
+    const currentPath = path.join(" > ");
+    if (document.querySelectorAll(currentPath).length === 1) {
+      return currentPath;
+    }
+
+    // Move to parent, but stop at elements with ID
+    current = current.parentElement;
+    if (current?.id) {
+      path.unshift(`#${current.id}`);
+      return path.join(" > ");
+    }
+  }
+  return null;
+}

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["**/*.spec.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from "tsup";
+
+const common = {
+  dts: true,
+  clean: true,
+  sourcemap: false,
+  skipNodeModulesBundle: true,
+  minify: true,
+} as const;
+
+export default defineConfig([
+  {
+    ...common,
+    format: ["cjs"],
+    target: ["es2016"],
+    outDir: "dist/cjs",
+    entry: ["src/index.ts"],
+  },
+  {
+    ...common,
+    format: ["esm"],
+    target: ["esnext"],
+    outDir: "dist/esm",
+    entry: ["src/**/*.ts", "!src/**/*.spec.ts"],
+  },
+]);

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+import { baseConfig } from "../../vitest.config.base";
+
+export default defineConfig({
+  test: {
+    ...baseConfig,
+    environment: "jsdom",
+  },
+});