| 1 | # Avalonia + Dock UI — operational playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | Операционный контракт для агента и разработчика: от **дизайн-задачи** до **проверенной** правки в Avalonia/Dock (как в CascadeIDE). Фундаментальные понятия — `kb-avalonia-ui-dock-fundamentals-v1.md`. Версии и статус домена — `status-avalonia-cascade-ide-ui-v1.md`. |
| 6 | |
| 7 | ## Scope |
| 8 | |
| 9 | - AXAML, стили, ресурсы, биндинги (compiled) |
| 10 | - Dock.Model + Dock.Avalonia (`DockControl`, фабрика, документы) |
| 11 | - Локальная компоновка (`Grid`, `DockPanel`, `Flyout`, scroll) |
| 12 | - Смежные пакеты: AvaloniaEdit, Markdown.Avalonia (smoke-уровень) |
| 13 | - Согласование с HCI: `../hci-ux-dx/playbook-hci-core-v1`, `../hci-ux-dx/ui-ux-playbook` |
| 14 | |
| 15 | ## Retrieval order (обязательный) |
| 16 | |
| 17 | 1. `status-avalonia-cascade-ide-ui-v1.md` — актуальные версии и guardrails. |
| 18 | 2. Этот playbook — шаги и чек-листы. |
| 19 | 3. `kb-avalonia-ui-dock-fundamentals-v1.md` — углубление по спорному месту. |
| 20 | 4. При «застрял на API» — `playbook-learn-basics-when-stuck-v1` + официальная дока / Context7, затем фиксация вывода в KB при повторяемости. |
| 21 | |
| 22 | ## Evidence-based working format |
| 23 | |
| 24 | - **Fact:** что видит пользователь / что в логе / точный текст ошибки XAML или биндинга. |
| 25 | - **Hypothesis:** минимальное объяснение (layout, DataContext, ресурс, модель Dock). |
| 26 | - **Check:** smallest change + `dotnet build` + ручная проверка сценария. |
| 27 | - **Decision criterion:** зелёная сборка + отсутствие ошибок биндинга в типичном потоке. |
| 28 | - **Confidence mark:** отдельно уверенность в API версии (сверка с csproj). |
| 29 | |
| 30 | ## Contract A — новый UI-блок по макету |
| 31 | |
| 32 | 1. **Зафиксировать режим:** какой `DataContext` / под-VM; видимость (`IsVisible`, режимы приложения). |
| 33 | 2. **Иерархия по HCI:** один главный фокус; вторичное — progressive disclosure (flyout, сворачивание). |
| 34 | 3. **Выбрать контейнер:** `Grid` vs `StackPanel` vs `UniformGrid`; где нужен `ScrollViewer` и `MaxHeight`. |
| 35 | 4. **Ресурсы:** новые цвета → ключ темы (`DynamicResource`); не хардкодить без причины. |
| 36 | 5. **Стили:** один «блок-секция» классом; избегать конфликтующих `Classes`. |
| 37 | 6. **Сборка + прогон сценария** (открыть экран, сменить тему если релевантно). |
| 38 | |
| 39 | ## Contract B — правка Dock (документы / панели) |
| 40 | |
| 41 | 1. Найти: `DockControl`, `IFactory`, `IDock` / `IDockable`, где собирается `RootDock` и список документов. |
| 42 | 2. Проверить: обновляется ли коллекция `VisibleDockables` / активный документ при смене состояния VM. |
| 43 | 3. Не путать с локальным `DockPanel` внутри чата/панели — это не модель Dock. |
| 44 | 4. После изменений: открытие/закрытие документа, переключение вкладки, нет ли «пустого» layout. |
| 45 | |
| 46 | ## Contract C — биндинги и compiled bindings |
| 47 | |
| 48 | 1. Убедиться в `x:DataType` на корне шаблона / контрола где требуется. |
| 49 | 2. Ошибка «cannot find property» → несовпадение типа `DataContext` или опечатка в пути. |
| 50 | 3. Для вложенных контекстов: явный `DataContext=` на границе; не полагаться на неявное наследование через шаблоны без проверки. |
| 51 | |
| 52 | ## Contract D — темы и Power/режимы |
| 53 | |
| 54 | 1. Режимы UI (Focus/Balanced/Power и т.д.) — свойства VM; XAML только отражает. |
| 55 | 2. Специальные палитры (например power-theme) — не дублировать логику в двух JSON без необходимости; документировать ключи в репо (`docs/ux` при наличии). |
| 56 | |
| 57 | ## Contract E — обновление зависимостей |
| 58 | |
| 59 | 1. Сверить версии: Avalonia, Dock.*, AvaloniaEdit — матрица совместимости в release notes. |
| 60 | 2. Smoke: старт приложения, док, редактор, чат-панель, смена темы. |
| 61 | 3. Обновить `status-avalonia-cascade-ide-ui-v1.md` и при необходимости секцию версий в fundamentals. |
| 62 | |
| 63 | ## Contract F — TextMate / подсветка / новый язык в редакторе |
| 64 | |
| 65 | 1. Найти в коде точку **регистрации TextMate** и список путей к **grammar bundle** (не гадать пути из KB). |
| 66 | 2. Проверить **наличие файлов** bundle после сборки (выходной каталог / ресурсы) и соответствие **расширения файла** ожидаемым правилам. |
| 67 | 3. При сбое после обновления пакетов — сначала **совместимость AvaloniaEdit + AvaloniaEdit.TextMate**, затем правки `.tmLanguage` / scope. |
| 68 | 4. Зафиксировать smoke: открытие эталонного файла языка + переключение темы приложения + отсутствие повторяющихся ошибок в логе редактора. |
| 69 | 5. Повторяемый инцидент — карточка по `templates/template-knowledge-card-v1.md` с путём к коду инициализации и именем grammar. |
| 70 | |
| 71 | ## Integration with other playbooks |
| 72 | |
| 73 | - **C# диагностика / рефакторинг:** `../software-dotnet-tooling-roslyn/troubleshooting/playbook-dotnet-roslyn-troubleshooting-v1.md` |
| 74 | - **Сборка/тест/отладка:** `../../hci-ux-dx/troubleshooting/playbook-tooling-debug-troubleshooting-v1.md` |
| 75 | - **Симптомы UI Avalonia:** `troubleshooting/playbook-avalonia-ui-troubleshooting-v1.md` |
| 76 | - **DX-поток и среда (не только UI):** `../hci-ux-dx/de-dx-playbook.md` |
| 77 | - **Общий .NET frontend:** `frontend-dotnet-playbook.md` |
| 78 | - **HCI / продуктовый UX:** `../hci-ux-dx/playbook-hci-core-v1.md`, `../hci-ux-dx/ui-ux-playbook.md`, `../hci-ux-dx/kb-hci-usability-and-dialog-rules-v1.md` |
| 79 | |
| 80 | ## Metrics |
| 81 | |
| 82 | - Время от постановки UI-задачи до зелёной сборки. |
| 83 | - Число итераций «угадывания» XAML до первого успешного build. |
| 84 | - Повторяемость регрессий на одном и том же экране. |
| 85 | |
| 86 | ## Revisit triggers |
| 87 | |
| 88 | - Повторяющиеся ошибки одного класса (flyout, dock active document, theme key missing). |
| 89 | - Крупный редизайн главного окна или замена dock-пакета. |
| 90 | |
| 91 | Версия: v1. 2026-03-20. |
| 92 | |