@akccakcctw/vue-grab 1.0.0 → 1.4.0

package/README.md

@@ -1,24 +1,27 @@
-# vue-grab
+# @akccakcctw/vue-grab
 
 Developer-only bridge for inspecting Vue/Nuxt component context from the DOM.
 
+[![npm](https://img.shields.io/npm/v/@akccakcctw/vue-grab)](https://www.npmjs.com/package/@akccakcctw/vue-grab)
+NPM package: https://www.npmjs.com/package/@akccakcctw/vue-grab
+
 ## Install
 
 ```bash
-pnpm add -D vue-grab
+pnpm add -D @akccakcctw/vue-grab
 ```
 
 ## Vue Usage
 
 ```ts
 import { createApp } from 'vue'
-import VueGrab from 'vue-grab'
+import { createVueGrabPlugin } from '@akccakcctw/vue-grab'
 
 const app = createApp(App)
 
 // Use import.meta.env.DEV for Vite, or process.env.NODE_ENV === 'development' for Webpack
 if (import.meta.env.DEV) {
-  app.use(VueGrab, {
+  app.use(createVueGrabPlugin({
     overlayStyle: {
       border: '2px dashed #111'
     },
@@ -26,7 +29,7 @@ if (import.meta.env.DEV) {
       console.log('vue-grab payload', payload)
     },
     copyOnClick: true
-  })
+  }))
 }
 
 app.mount('#app')
@@ -36,7 +39,7 @@ app.mount('#app')
 
 ```ts
 export default defineNuxtConfig({
-  modules: ['vue-grab'],
+  modules: ['@akccakcctw/vue-grab'],
   vueGrab: {
     enabled: true,
     overlayStyle: {
@@ -47,6 +50,21 @@ export default defineNuxtConfig({
 })
 ```
 
+## Vite Line/Column Support
+
+Add the Vite plugin to inject `__file`, `__line`, and `__column` metadata into SFCs.
+It also annotates template DOM nodes with their original line/column so element grabs map to the template line numbers.
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { createVueGrabVitePlugin } from '@akccakcctw/vue-grab/vite'
+
+export default defineConfig({
+  plugins: [vue(), createVueGrabVitePlugin()]
+})
+```
+
 ## Browser API
 
 When active, `window.__VUE_GRAB__` exposes:
@@ -68,49 +86,4 @@ const info = window.__VUE_GRAB__.grabFromSelector('.my-button');
 console.log(JSON.stringify(info));
 ```
 
-## Development
-
-For maintainers of this package (local dev + manual testing):
-
-```bash
-pnpm install
-pnpm test
-```
-
-To test in a real app, link this package into a separate Vue/Nuxt project:
-
-```bash
-# In this repo
-pnpm link --global
-
-# In your app repo
-pnpm link --global vue-grab
-```
-
-Note: `pnpm link --global vue-grab` does not update your app's `package.json` by default.
-If you want it recorded in dependencies, use one of the following in your app repo:
-
-```bash
-pnpm add -D link:vue-grab
-# or
-pnpm add -D link:/Users/rex.tsou/vbox/vue-grab
-```
-
-Then run your app and verify `window.__VUE_GRAB__` in the browser console.
-
-Cleanup when finished:
-
-```bash
-# In your app repo
-pnpm unlink --global vue-grab
-```
-
-Manual verification checklist:
-- Hover highlights appear when `activate()` is called.
-- Clicking copies metadata (or triggers `onCopy` if configured).
-- `grabFromSelector` returns component info for a known element.
-
-## Acknowledgment
-
-Special thanks to [react-grab](https://www.react-grab.com/) ([GitHub](https://github.com/aidenybai/react-grab)). This project was inspired by and references the excellent work done by the `react-grab` team. `vue-grab` aims to bring a similar developer experience to the Vue and Nuxt ecosystem.
-
+For the full documentation, see https://github.com/akccakcctw/vue-grab.

package/dist/core/api.d.ts

@@ -0,0 +1,28 @@
+import type { OverlayOptions } from './overlay.js';
+export interface ComponentInfo {
+    name: string;
+    file: string;
+    props: Record<string, any>;
+    data: Record<string, any>;
+    element: HTMLElement;
+    line?: number;
+    column?: number;
+    vnode?: any;
+}
+export type VueGrabOptions = OverlayOptions;
+export interface VueGrabAPI {
+    activate(): void;
+    deactivate(): void;
+    readonly isActive: boolean;
+    grabAt(x: number, y: number): ComponentInfo | null;
+    grabFromSelector(selector: string): ComponentInfo | null;
+    grabFromElement(element: Element): ComponentInfo | null;
+    highlight(selector: string): void;
+    enable(): void;
+    disable(): void;
+    getComponentDetails(selectorOrElement: string | Element): ComponentInfo | null;
+    setOverlayStyle(style: Record<string, string>): void;
+    setDomFileResolver(resolver: VueGrabOptions['domFileResolver']): void;
+}
+export declare function createVueGrabAPI(targetWindow: Window, options?: VueGrabOptions): VueGrabAPI;
+export declare function installVueGrab(targetWindow: Window, options?: VueGrabOptions): VueGrabAPI;

package/dist/core/api.js

@@ -0,0 +1,105 @@
+import { extractMetadata, identifyComponent } from './identifier.js';
+import { createOverlayController } from './overlay.js';
+import { createToggleWidget } from './widget.js';
+function getComponentInfo(el, resolver) {
+    if (!el)
+        return null;
+    const instance = identifyComponent(el);
+    const metadata = extractMetadata(instance, el);
+    if (!metadata)
+        return null;
+    const fallback = !instance && resolver ? resolver(el) : null;
+    if (fallback?.file)
+        metadata.file = fallback.file;
+    if (typeof fallback?.line === 'number')
+        metadata.line = fallback.line;
+    if (typeof fallback?.column === 'number')
+        metadata.column = fallback.column;
+    return {
+        ...metadata,
+        element: el
+    };
+}
+export function createVueGrabAPI(targetWindow, options = {}) {
+    let active = false;
+    let domFileResolver = options.domFileResolver;
+    const overlay = createOverlayController(targetWindow, {
+        ...options,
+        onAfterCopy: () => {
+            api.deactivate();
+        }
+    });
+    const widget = createToggleWidget(targetWindow, {
+        onToggle(nextActive) {
+            if (nextActive) {
+                api.activate();
+            }
+            else {
+                api.deactivate();
+            }
+        }
+    });
+    const api = {
+        activate() {
+            active = true;
+            overlay.start();
+            widget.setActive(true);
+        },
+        deactivate() {
+            active = false;
+            overlay.stop();
+            widget.setActive(false);
+        },
+        get isActive() {
+            return active;
+        },
+        grabAt(x, y) {
+            if (typeof targetWindow.document.elementFromPoint !== 'function')
+                return null;
+            const el = targetWindow.document.elementFromPoint(x, y);
+            return getComponentInfo(el, domFileResolver);
+        },
+        grabFromSelector(selector) {
+            const el = targetWindow.document.querySelector(selector);
+            return getComponentInfo(el, domFileResolver);
+        },
+        grabFromElement(element) {
+            return getComponentInfo(element, domFileResolver);
+        },
+        highlight(selector) {
+            const el = targetWindow.document.querySelector(selector);
+            overlay.highlight(el);
+        },
+        enable() {
+            this.activate();
+        },
+        disable() {
+            this.deactivate();
+        },
+        getComponentDetails(selectorOrElement) {
+            if (typeof selectorOrElement === 'string') {
+                const el = targetWindow.document.querySelector(selectorOrElement);
+                return getComponentInfo(el, domFileResolver);
+            }
+            return getComponentInfo(selectorOrElement, domFileResolver);
+        },
+        setOverlayStyle(style) {
+            overlay.setStyle(style);
+        },
+        setDomFileResolver(resolver) {
+            domFileResolver = resolver;
+            overlay.setDomFileResolver(domFileResolver);
+        }
+    };
+    widget.mount();
+    widget.setActive(active);
+    return api;
+}
+export function installVueGrab(targetWindow, options = {}) {
+    const existing = targetWindow.__VUE_GRAB__;
+    if (existing)
+        return existing;
+    const api = createVueGrabAPI(targetWindow, options);
+    targetWindow.__VUE_GRAB__ = api;
+    return api;
+}

package/dist/core/identifier.d.ts

@@ -0,0 +1,2 @@
+export declare function identifyComponent(el: HTMLElement | null): any;
+export declare function extractMetadata(instance: any, el?: HTMLElement | null): Record<string, any> | null;

package/dist/core/identifier.js

@@ -0,0 +1,101 @@
+export function identifyComponent(el) {
+    let curr = el;
+    while (curr) {
+        // Vue 3 stores the internal component instance on the DOM element
+        // under specific keys depending on the version/environment.
+        const currAny = curr;
+        const instance = currAny.__vueParentComponent ||
+            currAny.__vnode?.component ||
+            currAny.__vnode?.ctx ||
+            currAny.__vue__;
+        if (instance)
+            return instance;
+        curr = curr.parentElement;
+    }
+    return null;
+}
+function getElementLoc(el) {
+    if (!el || typeof el.getAttribute !== 'function')
+        return null;
+    const locAttr = el.getAttribute('data-vue-grab-loc');
+    if (!locAttr)
+        return null;
+    const [lineRaw, columnRaw] = locAttr.split(':');
+    const line = Number(lineRaw);
+    const column = Number(columnRaw);
+    if (!Number.isFinite(line) || !Number.isFinite(column))
+        return null;
+    return { line, column };
+}
+export function extractMetadata(instance, el) {
+    if (!instance && !el)
+        return null;
+    const resolveType = (start) => {
+        let curr = start;
+        while (curr) {
+            const t = curr.type || curr.$options || curr.type?.__vccOpts || {};
+            const file = t.__file || t.__vccOpts?.__file;
+            if (file) {
+                return { type: t, instance: curr };
+            }
+            curr = curr.parent;
+        }
+        return { type: start.type || start.$options || start.type?.__vccOpts || {}, instance: start };
+    };
+    const resolved = instance ? resolveType(instance) : { type: {}, instance: null };
+    const type = resolved.type || {};
+    const props = instance?.props || instance?.$props || {};
+    const data = (instance?.data && Object.keys(instance.data).length > 0
+        ? instance.data
+        : instance?.setupState) ||
+        instance?.$data ||
+        {};
+    const vnode = instance?.vnode || instance?.$vnode;
+    const domLoc = getElementLoc(el);
+    const loc = domLoc ||
+        vnode?.loc?.start ||
+        resolved.instance?.vnode?.loc?.start ||
+        resolved.instance?.parent?.vnode?.loc?.start;
+    const metadata = instance
+        ? {
+            name: type.name || type.__name || type.__vccOpts?.name || 'AnonymousComponent',
+            file: type.__file || type.__vccOpts?.__file || 'unknown',
+            props,
+            data
+        }
+        : {
+            name: el?.tagName ? `<${el.tagName.toLowerCase()}>` : 'unknown',
+            file: 'unknown',
+            props: {},
+            data: {},
+            element: el || null
+        };
+    if (typeof loc?.line === 'number') {
+        metadata.line = loc.line;
+    }
+    else if (typeof type.__line === 'number') {
+        metadata.line = type.__line;
+    }
+    else if (typeof type.line === 'number') {
+        metadata.line = type.line;
+    }
+    else if (typeof type.__vccOpts?.__line === 'number') {
+        metadata.line = type.__vccOpts.__line;
+    }
+    if (typeof loc?.column === 'number') {
+        metadata.column = loc.column;
+    }
+    else if (typeof type.__column === 'number') {
+        metadata.column = type.__column;
+    }
+    else if (typeof type.column === 'number') {
+        metadata.column = type.column;
+    }
+    else if (typeof type.__vccOpts?.__column === 'number') {
+        metadata.column = type.__vccOpts.__column;
+    }
+    if (vnode) {
+        metadata.vnode = vnode;
+    }
+    return metadata;
+}

package/dist/core/overlay.d.ts

@@ -0,0 +1,25 @@
+type OverlayController = {
+    start: () => void;
+    stop: () => void;
+    isActive: () => boolean;
+    highlight: (el: HTMLElement | null) => void;
+    clear: () => void;
+    setStyle: (style: OverlayStyle) => void;
+    setDomFileResolver: (resolver: OverlayOptions['domFileResolver']) => void;
+};
+export type OverlayStyle = Record<string, string>;
+export type OverlayOptions = {
+    overlayStyle?: OverlayStyle;
+    onCopy?: (payload: string) => void;
+    onAfterCopy?: () => void;
+    onAgentTask?: (task: any) => void;
+    copyOnClick?: boolean;
+    rootDir?: string;
+    domFileResolver?: (el: HTMLElement) => {
+        file?: string;
+        line?: number;
+        column?: number;
+    } | null;
+};
+export declare function createOverlayController(targetWindow: Window, options?: OverlayOptions): OverlayController;
+export {};