refactoring

2026-10-31 15:33:00 +03:00
parent e8e2d25600
commit 838627fb33
27 changed files with 2715 additions and 1259 deletions
@@ -0,0 +1,126 @@
+# Привязки клавиш — `api.keymap`
+
+Привязки живут у трёх видов объектов:
+
+- у приложения — `api.keymap` (глобальные привязки);
+- у редактора — `api.editor` (срабатывают, когда фокус в редакторе);
+- у каждого блока панели — `tree` (срабатывают, когда фокус на этом блоке).
+
+Встроенные сочетания можно заменить или удалить: обработчиком принимается
+Lua-функция, имя встроенной команды или `nil`.
+
+```lua
+api.keymap:map_key(modes, keys, handler)          -- глобальные
+api.editor:map_key(modes, keys, handler)          -- только когда фокус в редакторе
+api.keymap:map_completion_key(keys, handler)      -- список автодополнения
+```
+
+Слой автодополнения режимами не управляется: `map_completion_key` принимает
+только клавишу и обработчик.
+
+Порядок обработки всегда такой: сначала глобальные привязки, затем — если
+фокус в редакторе — привязки редактора, а если фокус на блоке панели —
+привязки этого блока. Привязки неактивного объекта не срабатывают.
+
+## Запись клавиши
+
+| Запись | Значение |
+| --- | --- |
+| `"a"` | нажатие A |
+| `"1"` | нажатие 1 |
+| `"!a"` | отпускание A |
+| `"<S-c>"` | C при зажатом Shift |
+| `"<C-z>"` | Z при зажатом Ctrl |
+| `"<A-!r>"` | отпускание R при зажатом Alt |
+| `"<D-s>"` | S при зажатом Cmd на macOS или Super на Linux |
+
+Клавиша сравнивается с именем клавиши от GPUI. Caps Lock не важен. На Linux
+и Windows буквы берутся по аппаратному keycode, поэтому `<C-q>` работает
+и на русской раскладке.
+
+## Режимы
+
+У каждого объекта своя текущая режимная метка: один символ (`n`, `i`, `v`, `r`
+или любой другой) либо `-` — режим по умолчанию. Режимы динамические: заранее
+создавать их не нужно, достаточно переключить метку.
+
+| Значение `modes` | Когда срабатывает |
+| --- | --- |
+| `""` | во всех режимах |
+| `"-"` | только в режиме по умолчанию |
+| `"niv"` | в режимах `n`, `i`, `v` |
+| `"-iv"` | в режиме по умолчанию, а также `i` и `v` |
+
+Текущий режим меняется методами `set_mode(mode)` и читается методом `mode()`.
+Режимы у приложения, редактора и каждого блока независимы.
+
+```lua
+api.keymap:set_mode("n")
+api.editor:set_mode("i")
+
+api.keymap:map_key("n", "<C-n>", "next_tab")       -- только в режиме n
+api.editor:map_key("i", "<C-s>", "save")           -- только в режиме i редактора
+api.editor:map_key("", "<C-space>", function() end) -- в любом режиме
+```
+
+## Встроенные команды
+
+| Имя | Действие |
+| --- | --- |
+| `"save"` | Сохранить активную вкладку |
+| `"next_tab"` | Следующая вкладка |
+| `"previous_tab"` | Предыдущая вкладка |
+| `"open_tab"` | Новая пустая вкладка |
+| `"close_tab"` | Закрыть активную вкладку |
+| `"toggle_left_panel"` | Переключить левую панель |
+| `"toggle_right_panel"` | Переключить правую панель |
+| `"toggle_bottom_panel"` | Переключить нижнюю панель |
+
+Встроенные команды списка автодополнения:
+
+| Имя | Действие |
+| --- | --- |
+| `"completion_trigger"` | Открыть список |
+| `"completion_next"` / `"completion_previous"` | Сдвинуть выделение |
+| `"completion_page_down"` / `"completion_page_up"` | Пролистать список |
+| `"completion_accept"` | Вставить выбранный элемент |
+| `"completion_cancel"` | Закрыть список |
+| `"completion_dismiss"` | Закрыть список и передать клавишу редактору |
+
+При запуске уже назначены:
+
+- `Ctrl/Cmd+S` → `save` во всех режимах;
+- `Ctrl/Cmd+Space` → `completion_trigger`;
+- `Enter`/`Tab`, `Esc`, `↑`/`↓`, `PageUp`/`PageDown`, `←`/`→`, `Home`/`End`
+  → команды слоя автодополнения.
+
+## Примеры
+
+```lua
+-- Переопределить сохранение своей функцией во всех режимах.
+api.keymap:map_key("", "<C-s>", function() api.editor:save() end)
+
+-- Убрать встроенную привязку.
+api.keymap:map_key("", "<C-s>", nil)
+
+-- Назначить встроенную команду на другую клавишу.
+api.keymap:map_key("", "<C-n>", "next_tab")
+api.keymap:map_key("", "<C-b>", "toggle_left_panel")
+
+-- Навигация по списку автодополнения на Ctrl+N / Ctrl+P.
+api.keymap:map_completion_key("<C-n>", "completion_next")
+api.keymap:map_completion_key("<C-p>", "completion_previous")
+
+-- Привязка, которая срабатывает только при фокусе в редакторе.
+api.editor:map_key("", "<A-r>", function()
+  api.editor:set_active_text("editor mode")
+end)
+
+-- Привязка блока дерева: работает, когда фокус на этом дереве.
+tree:map_key("v", "<A-f>", function() print("tree v") end)
+```
+
+Пока список автодополнения открыт, его слой проверяется раньше действий
+редактора. Сочетания с модификаторами и горизонтальные стрелки закрывают
+список, даже если для них нет своей привязки, — так `Shift+↑` продолжает
+выделять текст.