Skip to content

Commit 8db199a

Browse files
ran-codesran-codes
authored
Merge pull request #32 from ran-codes/set-up-dedicated-view
[Feature] Create custom viewsContainers for Code Organizer #22
2 parents 968d8a3 + 854edae commit 8db199a

6 files changed

Lines changed: 797 additions & 30 deletions

File tree

‎.context/features/issue-22.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# Issue #22: View Location Strategy - Custom Activity Bar Container
2+
3+
## Decision: Custom Activity Bar Tab Only ✅
4+
5+
**Date:** 2025-01-28
6+
**Status:** Implemented
7+
8+
---
9+
10+
## Final Architecture
11+
12+
### What We Have:
13+
1. ✅ **Built-in Outline** (DocumentSymbolProvider) - Legacy integration
14+
2. ✅ **Custom Activity Bar Tab** ("Sections") - Enhanced features
15+
3. ❌ ~~Explorer Section~~ - **REMOVED** (was redundant)
16+
17+
### Visual Result:
18+
```
19+
Activity Bar:
20+
├─ 📁 EXPLORER
21+
├─ 🔍 SEARCH
22+
├─ 🔀 SOURCE CONTROL
23+
├─ 🗂️ CODE ORGANIZER ← Custom tab with "SECTIONS" view
24+
└─ ...
25+
26+
Built-in Outline Panel:
27+
└─ CODE ORGANIZER ← Legacy DocumentSymbolProvider (breadcrumbs, Go to Symbol)
28+
```
29+
30+
---
31+
32+
## Problem Statement
33+
34+
We had **3 views** showing essentially the same data:
35+
36+
1. **Built-in Outline** (DocumentSymbolProvider) - Legacy, limited API
37+
2. **Explorer Section** - New TreeView with highlighting
38+
3. **Custom Activity Bar Tab** - New TreeView with highlighting
39+
40+
This was redundant and confusing. We needed to consolidate to **2 views**: Legacy + ONE enhanced view.
41+
42+
---
43+
44+
## Options Considered
45+
46+
### Option A: Keep Custom Activity Bar Only ✅ **CHOSEN**
47+
- Remove Explorer section
48+
- Keep: Built-in Outline (legacy) + Custom Tab (enhanced)
49+
50+
### Option B: Keep Explorer Section Only
51+
- Remove Custom Activity Bar
52+
- Keep: Built-in Outline (legacy) + Explorer Section (enhanced)
53+
54+
---
55+
56+
## Feature Comparison: Custom Container vs Explorer Section
57+
58+
| Feature | Custom ViewsContainer | Explorer Section | Winner |
59+
|---------|----------------------|------------------|--------|
60+
| **Highlighting/Auto-scroll** | ✅ Full `TreeView` API | ✅ Full `TreeView` API | **TIE** |
61+
| **Multiple views** | ✅ Can add more (Settings, Stats, etc.) | ❌ Only one view | **Container** |
62+
| **Icon customization** | ✅ Custom icon/color | ❌ No custom icon | **Container** |
63+
| **Dedicated space** | ✅ Own tab, no clutter | ❌ Shares with other extensions | **Container** |
64+
| **Discoverability** | ⚠️ Requires icon click | ✅ Always in Explorer | **Explorer** |
65+
| **UI footprint** | ⚠️ Takes activity bar slot | ✅ Minimal | **Explorer** |
66+
| **Future expandability** | ✅ Can add panels, webviews | ⚠️ Limited to tree | **Container** |
67+
| **Professional appearance** | ✅ Like GitLens, Todo Tree | ⚠️ Generic section | **Container** |
68+
69+
---
70+
71+
## Decision Rationale
72+
73+
### Why Custom Activity Bar Container?
74+
75+
**1. Future Expandability**
76+
- Can add multiple views (Settings, Search, Stats)
77+
- Can add webview panels for rich UI
78+
- Explorer section limits you to one tree
79+
80+
**2. Professional Identity**
81+
- Own icon and branding
82+
- Dedicated space (not competing with other extensions)
83+
- Follows pattern of popular extensions (GitLens, Todo Tree)
84+
85+
**3. Prominent & Discoverable**
86+
- Activity bar icon is highly visible
87+
- Users actively looking for Code Organizer click the icon
88+
- Clear single location
89+
90+
**4. No Clutter**
91+
- Explorer sidebar can get crowded with other extensions
92+
- Custom tab keeps Code Organizer separate and focused
93+
94+
**5. Room to Grow**
95+
Planned future features that require custom container:
96+
- Settings panel
97+
- Section search/filter
98+
- Statistics/analytics view
99+
- Quick actions panel
100+
- Export/import views
101+
102+
### Why NOT Explorer Section?
103+
104+
**1. Single View Limitation**
105+
- Explorer sections can only show one tree
106+
- No room for additional panels/views
107+
108+
**2. Competition for Space**
109+
- Stacks with Outline, Timeline, GitLens, Todo Tree, etc.
110+
- Users might collapse it to save space
111+
- Less prominent
112+
113+
**3. Generic Appearance**
114+
- No custom icon
115+
- Just another section in a long list
116+
117+
---
118+
119+
## API Equivalence
120+
121+
For a **single TreeView**, both approaches provide:
122+
- ✅ Full `TreeView` API (`reveal()`, `onDidChangeSelection`, etc.)
123+
- ✅ Same `TreeDataProvider` interface
124+
- ✅ Same customization (icons, commands, tooltips)
125+
- ✅ Same highlighting and auto-scroll capabilities
126+
- ✅ Same performance
127+
128+
**The ONLY differences are:**
129+
- **Location:** Activity bar vs Explorer sidebar
130+
- **Expandability:** Multiple views vs single tree
131+
- **Branding:** Custom icon vs generic section
132+
133+
Since they're API-equivalent for current needs, we chose based on **future potential** and **professional appearance**.
134+
135+
---
136+
137+
## Implementation Changes
138+
139+
### Removed from package.json:
140+
```json
141+
"views": {
142+
"explorer": [
143+
{
144+
"id": "codeOrganizerOutline",
145+
"name": "Code Organizer",
146+
"when": "resourceLangId"
147+
}
148+
]
149+
}
150+
```
151+
152+
### Removed from extension.ts:
153+
```typescript
154+
const treeViewExplorer = vscode.window.createTreeView('codeOrganizerOutline', {
155+
treeDataProvider: treeDataProvider,
156+
showCollapseAll: true
157+
});
158+
159+
// Reveal in explorer view
160+
await treeViewExplorer.reveal(item, {...});
161+
```
162+
163+
### Kept in package.json:
164+
```json
165+
"viewsContainers": {
166+
"activitybar": [
167+
{
168+
"id": "codeOrganizer",
169+
"title": "Code Organizer"
170+
}
171+
]
172+
},
173+
"views": {
174+
"codeOrganizer": [
175+
{
176+
"id": "codeOrganizerOutlineActivity",
177+
"name": "Sections",
178+
"when": "resourceLangId"
179+
}
180+
]
181+
}
182+
```
183+
184+
---
185+
186+
## Benefits Achieved
187+
188+
### For Users:
189+
- ✅ **Clear single location** - One place to find Code Organizer
190+
- ✅ **Prominent icon** - Easy to discover and access
191+
- ✅ **No confusion** - Not duplicated in multiple places
192+
- ✅ **Professional UX** - Matches expectations from other extensions
193+
194+
### For Development:
195+
- ✅ **Maintainability** - One TreeView to manage
196+
- ✅ **Scalability** - Can add more views/panels later
197+
- ✅ **Clean architecture** - Clear separation: Legacy (Outline) + Enhanced (Custom Tab)
198+
- ✅ **Future-proof** - Ready for planned features
199+
200+
---
201+
202+
## Trade-offs Accepted
203+
204+
### What We Gave Up:
205+
- ⚠️ Users must click activity bar icon (not always visible like Explorer)
206+
- ⚠️ Takes up one activity bar slot
207+
- ⚠️ Slightly less discoverable for users who never look at activity bar
208+
209+
### Why These Are Acceptable:
210+
- Users actively using Code Organizer will click the icon
211+
- Activity bar is designed for extension icons (not a scarce resource)
212+
- Icon is more discoverable than scrolling through Explorer sections
213+
- Most popular extensions use custom activity bar tabs (GitLens, Todo Tree, Testing, etc.)
214+
215+
---
216+
217+
## Related Documentation
218+
219+
- [issue-29.md](issue-29.md) - Editor → Outline Synchronization (why we needed TreeView)
220+
- [.context/vs-code-api/tree-view.md](../vs-code-api/tree-view.md) - TreeView API details
221+
- [.context/vs-code-api/README.md](../vs-code-api/README.md) - Overall API architecture
222+
223+
---
224+
225+
## Pattern Validation
226+
227+
### Popular Extensions Using Custom Activity Bar:
228+
- ✅ **GitLens** - Own tab with multiple views
229+
- ✅ **Todo Tree** - Own tab (also has Explorer section for backward compatibility)
230+
- ✅ **Testing** - Built-in VS Code feature, own tab
231+
- ✅ **REST Client** - Own tab for API testing
232+
- ✅ **Docker** - Own tab with multiple views
233+
234+
### Pattern Conclusion:
235+
Extensions that provide **primary workflow tools** (not just supplementary info) use custom activity bar tabs. Code Organizer fits this pattern - it's a core navigation tool, not just informational.
236+
237+
---
238+
239+
## Future Enhancements Enabled
240+
241+
With custom container, we can now add:
242+
243+
1. **Settings Panel** - Configure section patterns, appearance, behavior
244+
2. **Search View** - Find sections across all open files
245+
3. **Statistics View** - Show section counts, nesting depth, etc.
246+
4. **Quick Actions** - Add section, organize, export structure
247+
5. **Webview Panel** - Rich UI for section management
248+
6. **Section History** - Recent sections visited
249+
7. **Bookmarks** - Pin important sections
250+
251+
None of these would be possible with a simple Explorer section.
252+
253+
---
254+
255+
## Conclusion
256+
257+
**Decision:** Use Custom Activity Bar Container exclusively for enhanced Code Organizer features.
258+
259+
**Rationale:** Equal functionality for current needs, superior expandability for future features, professional appearance, and follows industry patterns.
260+
261+
**Result:** Clean architecture with two views serving different purposes:
262+
1. Built-in Outline (legacy integration, breadcrumbs)
263+
2. Custom Activity Bar Tab (enhanced features, future growth)

‎.context/vs-code-api/README.md‎

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,28 +7,9 @@ This directory contains documentation for implementing editor → outline synchr
77
## Documentation Files
88

99
1. **[window-events.md](window-events.md)** - Tracking cursor position and editor changes
10-
- `window.onDidChangeTextEditorSelection` - Detect cursor movements
11-
- `window.onDidChangeActiveTextEditor` - Detect editor switches
12-
- `Selection` and `Position` classes
13-
- Converting between Position and character offsets
14-
1510
2. **[tree-view.md](tree-view.md)** - Custom tree views for outline with highlighting support
16-
- `window.createTreeView()` - Create custom sidebar views
17-
- `TreeView.reveal()` - **Key method for highlighting and scrolling**
18-
- `TreeDataProvider` interface
19-
- Comparison with DocumentSymbolProvider
20-
2111
3. **[document-symbols.md](document-symbols.md)** - Understanding your current implementation
22-
- `DocumentSymbolProvider` interface (what you currently use)
23-
- `DocumentSymbol` class and hierarchy
24-
- Limitations for programmatic highlighting
25-
- Converting between offsets and positions
26-
2712
4. **[editor-decorations.md](editor-decorations.md)** - Highlighting sections in the editor
28-
- `TextEditorDecorationType` - Define visual styles
29-
- `TextEditor.setDecorations()` - Apply highlights to ranges
30-
- `ThemeColor` - Theme-aware colors
31-
- Alternative approach to outline highlighting
3213

3314
## Current Extension Architecture
3415

0 commit comments

Comments
 (0)