ADR 0167: Solution Explorer UX — Go to File, компактное дерево и единый индекс путей

Статус: Proposed
Дата: 2026-06-28

Резюме

Обозреватель решения (SolutionExplorerView) остаётся вторичным каналом навигации (0039), но его текущая реализация создаёт высокий когнитивный налог: все узлы раскрыты, нет быстрого поиска файлов, неудобные отступы и плотность в Power mode.

Принято направление:

1. Visual Studio — UX baseline для механики Solution Explorer (поиск в панели, collapse, sync с документом, плотность, жесты) — см. §2.0.
2. Go to File (глобально, Ctrl+P) — быстрый вход по имени/пути; единый WorkspaceFileIndex для палитры, slash и фильтра дерева.
3. Дерево + иконки — свёрнуто по умолчанию, компактные отступы, читаемый набор иконок (не текущий «vivid» mix на 16–20 px).
4. Не дублировать три независимых fuzzy-поиска: обобщить WorkspaceFileSlashCompletionProvider → WorkspaceFileIndex.

Целевой релизный срез — MLP (Minimum Lovable Product): не «минимум работает», а «приятно пользоваться каждый день» — см. §3.

Semantic Map и «вокруг текущего файла» (0039) дополняют дерево; этот ADR не отменяет их.

Связанные ADR

Снимок реализации (на момент ADR)

1. Контекст

1.1 Симптомы (operator feedback)

• Глубокое дерево на крупном .sln — длинный скролл без быстрого фильтра.
• Отступы Avalonia TreeView + Power styles (MinHeight 32, padding) — мало файлов на экран.
• Все папки раскрыты при открытии solution — шум вместо обзора.
• Нет Ctrl+P / Go to File в глобальной палитре; поиск файлов доступен только через slash в чате (0125).
• Иконки — визуально слабые: смешение vivid SVG на 16–20 px, нет согласованности с Power/Standard темой; solution/project/folder плохо отличимы от «ещё одной картинки» (operator feedback).

1.2 Visual Studio как эталон механики

Visual Studio Solution Explorer — признанный хороший UX для взаимодействия с деревом (не для единственной навигации по всему IDE). CIDE копирует механику VS, а не изобретает альтернативное дерево:

Не копируем в MLP: Solution Folders editor, References UI, Show All Files, drag-drop между проектами — отдельные ADR/фазы.

1.3 Согласование с 0039

0039 уже фиксирует: классическое дерево полезно, но не должно быть единственным способом навигации. Этот ADR доводит SE до VS-grade mechanics и добавляет Go to File; Semantic Map остаётся слоем C.

1.4 Существующий актив

Логика сбора и ранжирования путей для slash уже реализована (WorkspaceFileSlashCompletionProvider, McpSolutionTree.CollectFileEntries). Дублировать её в Go to File и фильтре дерева — технический долг; ADR вводит единый WorkspaceFileIndex.

2. Решение

2.0 Visual Studio baseline (нормативно)

Правило: при споре о поведении SE по умолчанию сравнивать с Visual Studio 2022 Solution Explorer (механика, не весь shell). «Lovable» = оператор не ощущает регрессию относительно VS при ежедневном открытии файлов из дерева.

2.1 Три слоя навигации (нормативно)

Слои A и VS-grade B (включая иконки) — обязательная часть MLP; слой C без изменений.

2.2 WorkspaceFileIndex (единый индекс)

Контракт (предложение):

// Features/Workspace/Application/WorkspaceFileIndex.cs
public sealed class WorkspaceFileIndex
{
    void Invalidate(ObservableCollection<SolutionItem> roots, string? solutionPath, string workspaceRoot);
    IReadOnlyList<WorkspaceFileMatch> Search(string query, int limit);
}

• Источник: обход SolutionItem / McpSolutionTree.CollectFileEntries (как в 0125).
• Потребители: WorkspaceFileSlashCompletionProvider (тонкая обёртка), Go to File palette, in-panel filter дерева (фаза 2).
• Ранжирование: сохранить существующую эвристику Rank из slash provider; при необходимости добавить fuzzy (subsequence / prefix segments) в одном месте.

Инвалидация при LoadSolution / смене SolutionRoots.

2.3 Go to File

Не заменяет полную command palette (0013) — только файлы solution/workspace.

Паритет MCP: опционально ide_execute_command с тем же command_id (фаза 1 или 2).

2.4 Дерево: раскрытие и синхронизация

Убрать глобальный стиль IsExpanded = True на всех TreeViewItem.

По умолчанию после load solution:

• Раскрыты: корень solution, узлы проектов (.csproj).
• Свёрнуты: папки и файлы внутри проектов.

Track Active Item (как в VS, toggle в overflow / контекстном меню панели):

• On: при смене активного документа — раскрыть путь и выделить узел (SyncSelectedSolutionItemToCurrentFile).
• Off: дерево не прыгает при переключении табов (поведение VS по умолчанию можно сделать On).

Сохранение состояния (фаза 2): per-workspace в %LocalAppData%\CascadeIDE\ или workspace.toml — не блокер MLP.

2.5 Компактность и отступы

Ввести стиль solutionExplorerTreeCompact (Standard и Power):

Переключатель «Компактное дерево» в overflow заголовка панели; default on для Power, on для Standard после фазы 1.

2.6 In-panel filter (Search Solution Explorer)

Под заголовком «Решение · дерево проекта» — поле поиска (паритет VS Search Solution Explorer):

• Жест: Ctrl+; когда фокус в панели SE (или глобально с routing в SE — как в VS);
• substring / fuzzy по Title и относительному пути через WorkspaceFileIndex;
• при непустом фильтре: prune tree (показать match + предков);
• очистка фильтра — Esc.

2.7 Поведение мыши и контекстное меню (фаза 2)

2.8 Lazy children (фаза 3, опционально)

При очень глубоких ProjectFileTreeBuilder — placeholder-папки до первого expand. Не блокер MLP; метрика: время построения дерева на CascadeIDE.sln < 500 ms UI freeze.

2.9 Размещение PFD vs MFD

Без смены 0021:

• PFD (IsDockedPfdSolutionExplorerTree): компактное дерево или Semantic Map (переключение пресетом).
• MFD (SolutionExplorerMfdPageView): тот же контрол SE + предпочтительный дом для Semantic Map на 2 мониторах — см. 0168.

Два монитора (P+F)(M): по 0168 PFD скрыт по умолчанию — не map, не SE; дерево и карта на MFD, файлы — Ctrl+P.

Не поддерживать два разных дерева с расходящейся логикой — один SolutionExplorerView + bindable options (ShowFilter, CompactMode, TrackActiveItem).

2.10 Иконки дерева (MLP — обязательно)

Проблема: текущий набор file-icon-vectors (vivid) на 16–20 px в SolutionExplorerView воспринимается как визуальный шум: разный стиль glyph, плохая читаемость в Power theme, слабое различие solution / project / folder, .csproj часто уходит в generic xml.svg.

Цель (VS-grade readability): за один взгляд отличать тип узла и основные расширения; иконки не «ломают» lovable-ощущение панели.

Решение:

MLP checklist (иконки):

• Solution / project / folder узнаются без чтения текста
• .cs, .axaml, .json, .md различимы на 16 px
• Power mode: контраст ≥ WCAG для фона PowerSolutionTreePanelBackground
• Нет fallback на file.svg для типичных расширений cascade-ide solution

Не в MLP: git status overlays (modified/added), nested project badges, custom per-solution icons — фаза 3+.

3. MLP (Minimum Lovable Product)

MLP — один релизный срез, после которого SE не стыдно использовать ежедневно (паритет механики VS + приятные иконки). Не «минимум фич», а минимум качества.

4. Не цели

• Весь Visual Studio Solution Explorer (Solution Folders editor, References UI, nested project drag-drop, Show All Files) — механика VS в MLP, не полный feature parity.
• Замена Semantic Map или HCI navigation graph.
• Fuzzy по всему диску workspace без привязки к solution tree.
• Три разных алгоритма file search.
• 1170 иконок file-icon-vectors в репо — только курируемый MLP-набор + fallback.

5. Последствия

Положительные

• Оператор и агент (через workspace.go_to_file / MCP) открывают файлы быстрее, чем через скролл дерева.
• Меньше визуального шума при открытии solution.
• SE визуально не хуже VS на первом впечатлении (иконки + плотность).

Отрицательные / риски

• Рефактор slash provider — регрессия autocomplete в чате; обязательны тесты на WorkspaceFileSlashCompletionProvider.
• Avalonia TreeView indent — может потребовать custom item template; риск платформенных багов.
• Ctrl+P конфликтует с браузерными привычками в WebView host — разрешение через hotkeys.toml overlay.

Тесты

6. Отклонённые альтернативы

История