Command Palette — UX-концепт (v1)¶

Статус: черновик для ревью (не ADR). Соответствует направлению ADR 0013. Чеклисты discoverability — отдельно ADR 0014.

Хоткей по умолчанию: Ctrl+Q — как Quick Launch в Visual Studio; задаётся в шипнутом Hotkeys/hotkeys.toml (§9), а не строками в C#. Пользовательские правки — в hotkeys.toml в AppData; конфликты с ОС — переопределение там же.

1. Роль в продукте¶

Палитра — одна опорная точка для «сделать действие по имени», без охоты по меню и без раздувания toolbar. Руки остаются на клавиатуре; мышь — опционально. Это стыкуется с PFD/MFD: палитра не показывает состояние (это PFD/телеметрия), а даёт действие без смены зоны внимания на длинный хром. Метафора и антипаттерны (в т.ч. без breadcrumbs в списке по умолчанию) — concept-pfd-mfd-cascade-v1.md §7.

2. Вызов и закрытие¶

Действие	Поведение
Ctrl+Q	Открыть палитру. Если уже открыта — фокус в поле поиска и выделить весь текст (повторное нажатие как «новый поиск»).
Кнопка в toolbar (опционально v1)	То же окно; подпись вроде «Command» или иконка поиска по командам.
Esc	Закрыть без выполнения; возврат фокуса туда, откуда открыли (редактор, список, поле чата — см. §6).
Клик по затемнённому фону	Закрыть как Esc (если используем overlay).

3. Внешний вид (одно главное окно)¶

Overlay поверх клиентской области: лёгкое затемнение (#000 ~35–45 % opacity), клик по фону закрывает.
Панель палитры — компактная карточка по центру по горизонтали, ниже верхнего toolbar (чтобы не перекрывать якорные кнопки и режим), ширина ~480–640 px (ограничить MaxWidth, на узких окнах — почти на всю ширину с отступами).
Поле поиска — первая строка: плейсхолдер «Type a command name…» / «Введите команду…»; слева опционально иконка поиска.
Список результатов — под полем; высота ~6–12 строк видимых, дальше скролл. У каждого пункта:
основной текст — отображаемое имя команды;
вторичная строка или суффикс — категория / группа (например Build · Solution);
справа — назначенный хоткей, если есть (моноширинный бейдж).
Счётчик / подсказка внизу мелким шрифтом: «↑↓ navigate · Enter run · Esc close» (можно сократить в локализованной сборке).
Без лишнего контекста в каждой строке: по умолчанию не дублировать путь к файлу, breadcrumbs и длинный «где я в проекте» — это зона MFD (дерево, редактор), а не палитры команд. Исключение — только если команда семантически про текущий путь/файл и вторичная строка обоснована (см. concept-pfd-mfd-cascade-v1.md §7).

Стиль — Fluent-совместимый с текущей темой Cascade (тот же фон карточек, что у flyout), без отдельного «неонового» модального стиля.

4. Поведение поиска¶

Подстрока + простой fuzzy (например символы по порядку в словах команды) — достаточно для v1; полнотекст по описаниям — позже.
Сортировка: совпадения по началу слова выше; затем по релевантности; опционально недавние и частые вверху при пустом или коротком запросе.
Режимы UI: команда недоступна в текущем режиме — показывать серым с подписью «Not available in Focus» / «Недоступно в режиме …»; Enter не выполняет (или короткий тост «Switch mode» — по решению v1, минимум — не выполнять молча).

5. Клавиатура внутри палитры¶

Клавиша	Действие
↑ / ↓	Выбор в списке; зацикливание опционально.
Enter	Выполнить выделенную команду и закрыть.
Esc	Закрыть без выполнения.
PgUp / PgDn	Прокрутка списка, если список длинный.
Tab	По желанию v1: переход к первому результату или игнор (чтобы не конфликтовать с ожиданиями).

Глобальный Ctrl+Q пока палитра открыта — обновить запрос (фокус + select all) или игнорировать; предпочтительно обновить поле для быстрого второго запроса.

6. Фокус и возврат (критично для редактора)¶

При открытии: фокус в поле поиска палитры; события клавиатуры не уходят в редактор.
При закрытии (Esc / выполнение / клик вне): восстановить фокус на элемент, который был активен до открытия (сохранить ссылку на IInputElement / логический контроль в Avalonia).
Если фокус был в терминале или чате — возврат туда же.

Это закрывает открытый пункт в ADR 0013 § Обсуждение для сценария одного окна. Для нескольких окон — палитра на активном TopLevel; повтор ADR 0017.

7. Объём команд v1¶

Не обязательно весь каталог IDE с первого дня: приоритет — команды, уже имеющие стабильный id в реестре / MCP (ADR 0013), плюс навигация по файлам/решению, если уже есть единый слой.
Расширение списка — итерациями; реестр команд — единый источник правды для палитры, меню и агента.

8. Конфликты хоткеев и платформы¶

Ctrl+Q в веб-браузерах часто «выход» — в desktop IDE на Windows для целевой аудитории VS это приемлемо; при портировании на другие платформы — перепроверить.
Если ОС или драйвер перехватывает сочетание — задать другое в hotkeys.toml (§9); типичный запасной — Ctrl+Shift+P (как в VS Code).

9. Хранение хоткеев: файлы (`Hotkeys/hotkeys.toml` + пользовательский `hotkeys.toml`)¶

Почему не раздел в settings.toml: каталог стандартных сочетаний будет большим и пополняться итерациями; часть хоткеев пока не задана в продукте — в data-файлах появятся по мере готовности команд. Плюс пользователи могут хотеть свою раскладку, несколько пресетов (например «как в VS» / «как в VS Code» / под Dvorak) и делиться только биндингами без AI/MCP и прочего из settings.toml.

Почему не длинная таблица в C#: строки жестов держать в шипнутом TOML рядом с exe (аналогично UiModes/, Themes/), чтобы в коде оставались id команд и обработчики, а не список клавиш, который мешается при ревью и диффах.

Два слоя:

База (шип) — Hotkeys/hotkeys.toml под AppContext.BaseDirectory: полная продуктовая карта дефолтов. Репозиторий хранит тот же файл, что уходит в поставку.
Пользователь — %LocalAppData%\CascadeIDE\hotkeys.toml (рядом с settings.toml): только переопределения поверх базы. Мердж: сначала шип, затем поверх ключи из AppData.

Несколько пресетов (не v1): вариант A — файлы вроде hotkeys.vscode.toml + поле hotkeys_preset в settings.toml; вариант B — подкаталог hotkeys/*.toml. Точное имя поля — на этапе реализации.

На будущее — inherits: в пресете хоткеев можно ввести inherits = "…" по той же логике, что inherits в режимах UI (ADR 0010): сначала разрешить родителя (без циклов), получить полную карту жестов родителя, затем наложить ключи текущего файла. Так пресет «как VS Code» описывается как дельта поверх «базы», без копирования сотен строк. Темы JSON сейчас без наследования; ориентир для поведения — именно UiModes, не файлы Themes/*.json.

Содержимое: таблица или плоский набор пар command_id → строка жеста (например command_palette = "Ctrl+Q"). Ключи в snake_case. Ключ, заданный только в шипе, в AppData не обязателен; ключ только в AppData добавляет или меняет жест. Отсутствие в обоих слоях — команда без жеста (или узкий fallback в коде только для критичных id — по решению реализации).

Сохранение: запись в пользовательский hotkeys.toml при смене биндинга из UI (когда появится редактор хоткеев) или ручное редактирование; шипнутый файл пользователь не перезаписывает. Не смешивать с автосохранением геометрии окна (0010).

10. Не в scope v1 этого концепта¶

Полная Command Palette для MCP-агента как отдельный продукт (палитра — для человека в IDE; агент пользуется тем же реестром через команды).
Ситуационные чеклисты — 0014.
Локализация всех строк команд — по мере готовности строк в реестре.

11. Критерии «готово» для первой поставки¶

Загрузка жестов: шипнутый Hotkeys/hotkeys.toml + переопределения из %LocalAppData%\CascadeIDE\hotkeys.toml (пользовательский файл может отсутствовать).
Ctrl+Q по умолчанию открывает/закрывает палитру, поиск и Enter выполняют команду из реестра.
Esc и фокус-возврат работают для редактора и панелей.
Недоступные в режиме команды визуально отличимы.
Документ для пользователя: где шип и где пользовательский hotkeys.toml, дефолт Ctrl+Q в базе, как переопределить в AppData.

Версия: 2026-04.