Copilot instructions

1---
2description: Use when asked to consume workbench tree widgets in VS Code.
3---
4 
5# Workbench Tree Widgets Overview
6 
7**Location**: `src/vs/platform/list/browser/listService.ts`
8**Type**: Platform Services
9**Layer**: Platform
10 
11## Purpose
12 
13The Workbench Tree Widgets provide high-level, workbench-integrated tree components that extend the base tree implementations with VS Code-specific functionality like context menus, keyboard navigation, theming, accessibility, and dependency injection integration. These widgets serve as the primary tree components used throughout the VS Code workbench for file explorers, debug views, search results, and other hierarchical data presentations.
14 
15## Scope
16 
17### Included Functionality
18- **Context Integration**: Automatic context key management, focus handling, and VS Code theme integration
19- **Resource Navigation**: Built-in support for opening files and resources with proper editor integration
20- **Accessibility**: Complete accessibility provider integration with screen reader support
21- **Keyboard Navigation**: Smart keyboard navigation with search-as-you-type functionality
22- **Multi-selection**: Configurable multi-selection behavior with platform-appropriate modifier keys
23- **Dependency Injection**: Full integration with VS Code's service container for automatic service injection
24- **Configuration**: Automatic integration with user settings for tree behavior customization
25 
26### Integration Points
27- **IInstantiationService**: For service injection and component creation
28- **IContextKeyService**: For managing focus, selection, and tree state context keys
29- **IListService**: For registering trees and managing workbench list lifecycle
30- **IConfigurationService**: For reading tree configuration settings
31- **Resource Navigators**: For handling file/resource opening with proper editor integration
32 
33### Out of Scope
34- Low-level tree rendering and virtualization (handled by base tree classes)
35- Data management and async loading logic (provided by data sources)
36- Custom styling beyond workbench theming integration
37 
38## Architecture
39 
40### Key Classes & Interfaces
41 
42- **WorkbenchTreeInternals**: Encapsulates common workbench functionality across all tree types
43- **ResourceNavigator**: Handles file/resource opening with proper editor integration
44- **IOpenEvent**: Event interface for resource opening with editor options
45- **IWorkbench*TreeOptions**: Configuration interfaces extending base options with workbench features
46- **IResourceNavigatorOptions**: Configuration for resource opening behavior
47 
48### Key Files
49 
50- **`src/vs/platform/list/browser/listService.ts`**: Contains all workbench tree widget implementations, shared workbench functionality (`WorkbenchTreeInternals`), and configuration utilities
51	- `src/vs/platform/list/browser/test/listService.test.ts`: Unit tests for workbench trees
52- **`src/vs/base/browser/ui/tree/objectTree.ts`**: Base implementation for static trees and compressible trees
53	- `src/vs/base/test/browser/ui/tree/objectTree.test.ts`: Base tree tests
54- **`src/vs/base/browser/ui/tree/asyncDataTree.ts`**: Base implementation for async trees with lazy loading support
55	- `src/vs/base/test/browser/ui/tree/asyncDataTree.test.ts`: Async tree tests
56- **`src/vs/base/browser/ui/tree/dataTree.ts`**: Base implementation for data-driven trees with explicit data sources
57	- `src/vs/base/test/browser/ui/tree/dataTree.test.ts`: Data tree tests
58- **`src/vs/base/browser/ui/tree/abstractTree.ts`**: Base tree foundation
59- **`src/vs/base/browser/ui/tree/tree.ts`**: Core interfaces and types
60 
61## Development Guidelines
62 
63### Choosing the Right Tree Widget
64 
651. **WorkbenchObjectTree**: Use for simple, static hierarchical data that doesn't change frequently
66```typescript
67   // Example: Timeline items, loaded scripts
68   const tree = instantiationService.createInstance(
69     WorkbenchObjectTree<TimelineItem, FuzzyScore>,
70     'TimelineView', container, delegate, renderers, options
71   );
72```
73 
742. **WorkbenchAsyncDataTree**: Use for dynamic data that loads asynchronously
75```typescript
76   // Example: Debug variables, file contents
77   const tree = instantiationService.createInstance(
78     WorkbenchAsyncDataTree<IStackFrame, IExpression, FuzzyScore>,
79     'VariablesView', container, delegate, renderers, dataSource, options
80   );
81```
82 
833. **WorkbenchCompressible*Tree**: Use when you need path compression for deep hierarchies
84```typescript
85   // Example: File explorer, call stack
86   const tree = instantiationService.createInstance(
87     WorkbenchCompressibleAsyncDataTree<ExplorerItem[], ExplorerItem, FuzzyScore>,
88     'FileExplorer', container, delegate, compressionDelegate, renderers, dataSource, options
89   );
90```
91 
92### Construction Pattern
93 
94**Always use IInstantiationService.createInstance()** to ensure proper dependency injection:
95 
96```typescript
97constructor(
98  @IInstantiationService private instantiationService: IInstantiationService
99) {
100  this.tree = this.instantiationService.createInstance(
101    WorkbenchAsyncDataTree<TInput, T, TFilterData>,
102    'UniqueTreeId',           // Used for settings and context keys
103    container,                // DOM container element
104    delegate,                 // IListVirtualDelegate for item height/template
105    renderers,                // Array of tree renderers
106    dataSource,              // Data source (async trees only)
107    options                  // Tree configuration options
108  );
109}
110```
111 
112### Required Options
113 
114All workbench trees require an **accessibilityProvider**:
115```typescript
116const options: IWorkbenchAsyncDataTreeOptions<T, TFilterData> = {
117  accessibilityProvider: {
118    getAriaLabel: (element: T) => element.name,
119    getRole: () => 'treeitem'
120  }
121  // ... other options
122};
123```
124 
125### Common Configuration Patterns
126 
127```typescript
128// Standard tree setup with search, identity, and navigation
129const options = {
130  accessibilityProvider: new MyAccessibilityProvider(),
131  identityProvider: { getId: (element) => element.id },
132  keyboardNavigationLabelProvider: {
133    getKeyboardNavigationLabel: (element) => element.name
134  },
135  multipleSelectionController: {
136    isSelectionSingleChangeEvent: (e) => e.ctrlKey || e.metaKey,
137    isSelectionRangeChangeEvent: (e) => e.shiftKey
138  },
139  overrideStyles: this.getLocationBasedColors().listOverrideStyles
140};
141```
142 
143### Lifecycle Management
144 
145- **Always register trees as disposables** in the containing component
146- **Use the tree's `setInput()` method** to provide initial data
147- **Always call `layout()` when the container initializes and when its size changes**
148- **Handle selection and open events** through the tree's event system
149 
150### Performance Considerations
151 
152- Use **compression** for deep hierarchies to reduce DOM nodes
153- Implement **efficient data sources** that avoid unnecessary data fetching
154- Consider **virtualization settings** for large datasets
155- Use **identity providers** for efficient updates and state preservation
156 
157---
158