feat: add utilities API

docs/plugin/api-reference.md

@@ -471,6 +471,31 @@ api.on.inspectTimelineEvent(payload => {
 
 ## Utilities
 
+### getComponentInstances
+
+Component instances on the Vue app.
+- `app`: the target Vue app instance
+
+Example:
+
+```js
+let componentInstances = []
+
+api.on.getInspectorTree(async (payload) => {
+  if (payload.inspectorId === 'test-inspector') { // e.g. custom inspector
+    componentInstances = await api.getComponentInstances(app)
+      for (const instance of instances) {
+      payload.rootNodes.push({
+        id: instance.uid.toString(),
+        label: `Component ${instance.uid}`
+      })
+    }
+
+    // something todo ...
+  }
+})
+```
+
 ### getComponentBounds
 
 Computes the component bounds on the page.
@@ -513,3 +538,51 @@ api.on.inspectComponent(async payload => {
   }
 })
 ```
+
+### highlightElement
+
+Highlight the element of the component.
+- `instance`: the target component instance
+
+Example:
+
+```js
+let componentInstances = [] // keeped component instance of the Vue app (e.g. `getComponentInstances`)
+
+api.on.getInspectorState(payload => {
+  if (payload.inspectorId === 'test-inspector') { // e.g. custom inspector
+    // find component instance from custom inspector node
+    const instance = componentInstances.find(instance => instance.uid.toString() === payload.nodeId)
+
+    if (instance) {
+      api.highlightElement(instance)
+    }
+
+    // something todo ...
+  }
+})
+```
+
+### unhighlightElement
+
+Unhighlight the element.
+- `instance`: the target component instance
+
+Example:
+
+```js
+let componentInstances = [] // keeped component instance of the Vue app (e.g. `getComponentInstances`)
+
+api.on.getInspectorState(payload => {
+  if (payload.inspectorId === 'test-inspector') { // e.g. custom inspector
+    // find component instance from custom inspector node
+    const instance = componentInstances.find(instance => instance.uid.toString() === payload.nodeId)
+
+    if (instance) {
+      api.unhighlightElement(instance)
+    }
+
+    // something todo ...
+  }
+})
+```

packages/api/src/api/api.ts

@@ -1,6 +1,7 @@
 import { ComponentBounds, Hookable } from './hooks'
 import { Context } from './context'
 import { ComponentInstance, ComponentState, StateBase } from './component'
+import { App } from './app'
 import { ID } from './util'
 
 export interface DevtoolsPluginApi {
@@ -13,6 +14,9 @@ export interface DevtoolsPluginApi {
   sendInspectorState (inspectorId: string)
   getComponentBounds (instance: ComponentInstance): Promise<ComponentBounds>
   getComponentName (instance: ComponentInstance): Promise<string>
+  getComponentInstances (app: App): Promise<ComponentInstance[]>
+  highlightElement (instance: ComponentInstance)
+  unhighlightElement ()
 }
 
 export interface AppRecord {

packages/api/src/api/hooks.ts

@@ -13,6 +13,7 @@ export const enum Hooks {
   INSPECT_COMPONENT = 'inspectComponent',
   GET_COMPONENT_BOUNDS = 'getComponentBounds',
   GET_COMPONENT_NAME = 'getComponentName',
+  GET_COMPONENT_INSTANCES = 'getComponentInstances',
   GET_ELEMENT_COMPONENT = 'getElementComponent',
   GET_COMPONENT_ROOT_ELEMENTS = 'getComponentRootElements',
   EDIT_COMPONENT_STATE = 'editComponentState',
@@ -73,6 +74,10 @@ export type HookPayloads = {
     componentInstance: ComponentInstance
     name: string
   }
+  [Hooks.GET_COMPONENT_INSTANCES]: {
+    app: App
+    componentInstances: ComponentInstance[]
+  }
   [Hooks.GET_ELEMENT_COMPONENT]: {
     element: HTMLElement | any
     componentInstance: ComponentInstance
@@ -138,6 +143,7 @@ export interface Hookable<TContext> {
   inspectComponent (handler: HookHandler<HookPayloads[Hooks.INSPECT_COMPONENT], TContext>)
   getComponentBounds (handler: HookHandler<HookPayloads[Hooks.GET_COMPONENT_BOUNDS], TContext>)
   getComponentName (handler: HookHandler<HookPayloads[Hooks.GET_COMPONENT_NAME], TContext>)
+  getComponentInstances (handler: HookHandler<HookPayloads[Hooks.GET_COMPONENT_INSTANCES], TContext>)
   getElementComponent (handler: HookHandler<HookPayloads[Hooks.GET_ELEMENT_COMPONENT], TContext>)
   getComponentRootElements (handler: HookHandler<HookPayloads[Hooks.GET_COMPONENT_ROOT_ELEMENTS], TContext>)
   editComponentState (handler: HookHandler<HookPayloads[Hooks.EDIT_COMPONENT_STATE], TContext>)

packages/app-backend-api/src/api.ts

@@ -126,6 +126,14 @@ export class DevtoolsApi {
     return payload.name
   }
 
+  async getComponentInstances (app: App) {
+    const payload = await this.callHook(Hooks.GET_COMPONENT_INSTANCES, {
+      app,
+      componentInstances: []
+    })
+    return payload.componentInstances
+  }
+
   async getElementComponent (element: HTMLElement | any) {
     const payload = await this.callHook(Hooks.GET_ELEMENT_COMPONENT, {
       element,
@@ -259,4 +267,16 @@ export class DevtoolsPluginApiInstance implements DevtoolsPluginApi {
   getComponentName (instance: ComponentInstance) {
     return this.ctx.api.getComponentName(instance)
   }
+
+  getComponentInstances (app: App) {
+    return this.ctx.api.getComponentInstances(app)
+  }
+
+  highlightElement (instance: ComponentInstance) {
+    this.ctx.hook.emit(HookEvents.COMPONENT_HIGHLIGHT, instance.__VUE_DEVTOOLS_UID__, this.plugin)
+  }
+
+  unhighlightElement () {
+    this.ctx.hook.emit(HookEvents.COMPONENT_UNHIGHLIGHT, this.plugin)
+  }
 }

packages/app-backend-api/src/hooks.ts

@@ -81,6 +81,10 @@ export class DevtoolsHookable implements Hookable<BackendContext> {
     this.hook(Hooks.GET_COMPONENT_NAME, handler)
   }
 
+  getComponentInstances (handler: Handler<HookPayloads[Hooks.GET_COMPONENT_INSTANCES]>) {
+    this.hook(Hooks.GET_COMPONENT_INSTANCES, handler)
+  }
+
   getElementComponent (handler: Handler<HookPayloads[Hooks.GET_ELEMENT_COMPONENT]>) {
     this.hook(Hooks.GET_ELEMENT_COMPONENT, handler)
   }

packages/app-backend-core/src/index.ts

@@ -200,6 +200,14 @@ async function connect () {
     unHighlight()
   })
 
+  hook.on(HookEvents.COMPONENT_HIGHLIGHT, instanceId => {
+    highlight(ctx.currentAppRecord.instanceMap.get(instanceId), ctx)
+  })
+
+  hook.on(HookEvents.COMPONENT_UNHIGHLIGHT, () => {
+    unHighlight()
+  })
+
   // Component picker
 
   const componentPicker = new ComponentPicker(ctx)

packages/app-backend-vue3/src/components/util.ts

@@ -1,5 +1,6 @@
 import { classify } from '@vue-devtools/shared-utils'
 import { basename } from '../util'
+import { ComponentInstance, App } from '@vue/devtools-api'
 import { BackendContext } from '@vue-devtools/app-backend-api'
 
 export function isBeingDestroyed (instance) {
@@ -66,3 +67,11 @@ export function getRenderKey (value): string {
     return 'Object'
   }
 }
+
+export function getComponentInstances (app: App): ComponentInstance[] {
+  const appRecord = app.__VUE_DEVTOOLS_APP_RECORD__
+  const appId = appRecord.id.toString()
+  return [...appRecord.instanceMap]
+    .filter(([key]) => key.split(':')[0] === appId)
+    .map(([,instance]) => instance) // eslint-disable-line comma-spacing
+}

packages/app-backend-vue3/src/index.ts

@@ -1,7 +1,7 @@
 import { DevtoolsBackend, BuiltinBackendFeature } from '@vue-devtools/app-backend-api'
 import { ComponentWalker } from './components/tree'
 import { editState, getInstanceDetails } from './components/data'
-import { getInstanceName } from './components/util'
+import { getInstanceName, getComponentInstances } from './components/util'
 import { getComponentInstanceFromElement, getInstanceOrVnodeRect, getRootElementsFromComponentInstance } from './components/el'
 import { HookEvents } from '@vue-devtools/shared-utils'
 
@@ -51,6 +51,10 @@ export const backend: DevtoolsBackend = {
       payload.componentInstance = getComponentInstanceFromElement(payload.element)
     })
 
+    api.on.getComponentInstances(payload => {
+      payload.componentInstances = getComponentInstances(payload.app)
+    })
+
     api.on.getComponentRootElements(payload => {
       payload.rootElements = getRootElementsFromComponentInstance(payload.componentInstance)
     })

packages/shared-utils/src/consts.ts

@@ -88,6 +88,8 @@ export enum HookEvents {
   COMPONENT_ADDED = 'component:added',
   COMPONENT_REMOVED = 'component:removed',
   COMPONENT_EMIT = 'component:emit',
+  COMPONENT_HIGHLIGHT = 'component:highlight',
+  COMPONENT_UNHIGHLIGHT = 'component:unhighlight',
   SETUP_DEVTOOLS_PLUGIN = 'devtools-plugin:setup',
   TIMELINE_LAYER_ADDED = 'timeline:layer-added',
   TIMELINE_EVENT_ADDED = 'timeline:event-added',

packages/shell-dev-vue3/src/devtools-plugin/index.js

@@ -129,6 +129,8 @@ export default {
         label: 'Test inspector 2'
       })
 
+      let componentInstances = []
+
       api.on.getInspectorTree(payload => {
         if (payload.app === app && payload.inspectorId === 'test-inspector') {
           payload.rootNodes = [
@@ -155,6 +157,16 @@ export default {
               ]
             }
           ]
+        } else if (payload.app === app && payload.inspectorId === 'test-inspector2') {
+          api.getComponentInstances(app).then((instances) => {
+            componentInstances = instances
+            for (const instance of instances) {
+              payload.rootNodes.push({
+                id: instance.uid.toString(),
+                label: `Component ${instance.uid}`
+              })
+            }
+          })
         }
       })
 
@@ -194,6 +206,12 @@ export default {
               ]
             }
           }
+        } else if (payload.app === app && payload.inspectorId === 'test-inspector2') {
+          const instance = componentInstances.find(instance => instance.uid.toString() === payload.nodeId)
+          if (instance) {
+            api.unhighlightElement()
+            api.highlightElement(instance)
+          }
         }
       })