feat!: update tree view APIs

Author: kermanx

demo/src/treeView.ts

@@ -1,31 +1,40 @@
-import { createSingletonComposable, useTreeView } from 'reactive-vscode'
+import type { TreeViewNode } from 'reactive-vscode'
+import { computed, createSingletonComposable, useTreeView } from 'reactive-vscode'
 import { TreeItemCollapsibleState } from 'vscode'
+import { calledTimes } from './states'
 
 export const useDemoTreeView = createSingletonComposable(() => {
-  return useTreeView(
-    'reactive-tree-view',
-    [
-      {
-        data: 1,
-        children: [
-          { data: 2 },
-          { data: 3 },
-        ],
-      },
-      {
-        data: 4,
+  function getRootNode(index: number) {
+    return {
+      children: [
+        getChildNode(index * 10 + 1),
+        getChildNode(index * 10 + 2),
+      ],
+      treeItem: {
+        label: `Root ${index}`,
+        collapsibleState: TreeItemCollapsibleState.Expanded,
       },
-      {
-        data: 5,
-      },
-    ],
-    {
-      getTreeItem(node) {
-        return {
-          label: `Item ${node.data}`,
-          collapsibleState: node.children?.length ? TreeItemCollapsibleState.Expanded : TreeItemCollapsibleState.None,
-        }
+    }
+  }
+
+  function getChildNode(index: number) {
+    return {
+      treeItem: {
+        label: `Child ${index}`,
+        collapsibleState: TreeItemCollapsibleState.None,
       },
-    },
+    }
+  }
+
+  const treeData = computed(() => {
+    const roots: TreeViewNode[] = []
+    for (let i = 0; i < calledTimes.value; i++)
+      roots.push(getRootNode(i))
+    return roots
+  })
+
+  return useTreeView(
+    'reactive-tree-view',
+    treeData,
   )
 })

docs/guide/view.md

@@ -42,7 +42,7 @@ As described in the [official documentation](https://code.visualstudio.com/api/r
 
 Here is an example of a tree view:
 
-<<< @/snippets/treeView.ts
+<<< @/snippets/treeView.ts {35-41}
 
 Then you can call the `useDemoTreeView` function every where to register the tree view and get the returned value:
 
@@ -56,7 +56,9 @@ export = defineExtension(() => {
 })
 ```
 
-The `children` property in nodes is used to define the children of the node. Other properties are user-defined and can be used in the `getTreeItem` function. The `getTreeItem` function returns a `vscode::TreeItem` object from a node.
+The `children` property in nodes is used to define the children of the node. The `treeItem` propert is required and is used to define the tree item of the node. It should be a `vscode::TreeItem` object, or a promise that resolves to a `vscode::TreeItem` object.
+
+If you want to trigger an update based on some reactive values that aren't tracked in `treeData`, you can pass them to the `watchSource` option.
 
 ::: details About `reactive::createSingletonComposable`
 `reactive::createSingletonComposable` is a helper function to create a singleton composable. It will only create the composable once and return the same instance every time it is called.

docs/snippets/treeView.ts

@@ -1,23 +1,45 @@
+import type { TreeViewNode } from 'reactive-vscode'
 import { computed, createSingletonComposable, useTreeView } from 'reactive-vscode'
 import { TreeItemCollapsibleState } from 'vscode'
 
 export const useDemoTreeView = createSingletonComposable(() => {
-  const rootNodes = computed(() => [
-    { data: 1, children: [{ data: 2 }] },
-    { data: 3 },
-  ])
-  // return anything you want to expose
-  return useTreeView(
+  function getRootNode(index: number) {
+    return {
+      children: [
+        getChildNode(index * 10 + 1),
+        getChildNode(index * 10 + 2),
+      ],
+      treeItem: {
+        label: `Root ${index}`,
+        collapsibleState: TreeItemCollapsibleState.Expanded,
+      },
+    }
+  }
+
+  function getChildNode(index: number) {
+    return {
+      treeItem: {
+        label: `Child ${index}`,
+        collapsibleState: TreeItemCollapsibleState.None,
+      },
+    }
+  }
+
+  const treeData = computed(() => {
+    const roots: TreeViewNode[] = []
+    for (let i = 1; i < 5; i++)
+      roots.push(getRootNode(i))
+    return roots
+  })
+
+  const view = useTreeView(
     'reactive-tree-view',
-    rootNodes,
+    treeData,
     {
-      title: () => `Tree with ${rootNodes.value.length} roots`,
-      getTreeItem(node) {
-        return {
-          label: `Item ${node.data}`,
-          collapsibleState: node.children?.length ? TreeItemCollapsibleState.Expanded : TreeItemCollapsibleState.None,
-        }
-      },
+      title: () => `Tree with ${treeData.value.length} roots`,
     },
   )
+
+  // return anything you want to expose
+  return view
 })

packages/core/src/composables/useTreeView.ts

@@ -1,26 +1,29 @@
-import type { MaybeRefOrGetter } from '@reactive-vscode/reactivity'
+import type { MaybeRefOrGetter, WatchSource } from '@reactive-vscode/reactivity'
 import { toValue, watch } from '@reactive-vscode/reactivity'
-import type { TreeDataProvider, TreeView, TreeViewOptions, ViewBadge } from 'vscode'
-import { EventEmitter, window } from 'vscode'
+import type { TreeDataProvider, TreeItem, TreeView, TreeViewOptions, ViewBadge } from 'vscode'
+import { window } from 'vscode'
 import { createKeyedComposable } from '../utils'
 import { useDisposable } from './useDisposable'
+import { useEventEmitter } from './useEventEmitter'
 import { useViewBadge } from './useViewBadge'
 import { useViewTitle } from './useViewTitle'
 
 export interface TreeViewNode {
   readonly children?: this[]
+  readonly treeItem: TreeItem | Thenable<TreeItem>
 }
 
 export type UseTreeViewOptions<T> =
-  | (
-    & Omit<TreeViewOptions<T>, 'treeDataProvider'>
-    & Pick<TreeDataProvider<T>, 'getTreeItem' | 'resolveTreeItem'>
-    & {
-      title?: MaybeRefOrGetter<string | undefined>
-      badge?: MaybeRefOrGetter<ViewBadge | undefined>
-    }
-  )
-  | TreeDataProvider<T>['getTreeItem']
+  & Omit<TreeViewOptions<T>, 'treeDataProvider'>
+  & Pick<TreeDataProvider<T>, 'resolveTreeItem'>
+  & {
+    title?: MaybeRefOrGetter<string | undefined>
+    badge?: MaybeRefOrGetter<ViewBadge | undefined>
+    /**
+     * Additional watch source to trigger a change event. Useful when `treeItem` is a promise.
+     */
+    watchSource?: WatchSource<any>
+  }
 
 /**
  * Register a tree view. See `vscode::window.createTreeView`.
@@ -31,22 +34,24 @@ export const useTreeView = createKeyedComposable(
   <T extends TreeViewNode>(
     viewId: string,
     treeData: MaybeRefOrGetter<T[]>,
-    options: UseTreeViewOptions<T>,
+    options?: UseTreeViewOptions<T>,
   ): TreeView<T> => {
-    const normalizedOptions = typeof options === 'function' ? { getTreeItem: options } : options
-    const changeEventEmitter = new EventEmitter<void>()
+    const changeEventEmitter = useEventEmitter<void>()
 
     watch(treeData, () => changeEventEmitter.fire())
 
+    if (options?.watchSource)
+      watch(options.watchSource, () => changeEventEmitter.fire())
+
     const childrenToParentMap = new WeakMap<T, T>()
 
     const view = useDisposable(window.createTreeView(viewId, {
-      ...normalizedOptions,
+      ...options,
       treeDataProvider: {
-        ...normalizedOptions,
+        ...options,
         onDidChangeTreeData: changeEventEmitter.event,
         getTreeItem(node: T) {
-          return normalizedOptions.getTreeItem(node)
+          return node.treeItem
         },
         getChildren(node?: T) {
           if (node) {
@@ -61,11 +66,11 @@ export const useTreeView = createKeyedComposable(
       },
     }))
 
-    if (normalizedOptions?.title)
-      useViewTitle(view, normalizedOptions.title)
+    if (options?.title)
+      useViewTitle(view, options.title)
 
-    if (normalizedOptions?.badge)
-      useViewBadge(view, normalizedOptions.badge)
+    if (options?.badge)
+      useViewBadge(view, options.badge)
 
     return view
   },