select

docs/window.md

@@ -1,6 +1,7 @@
 # Окно и ввод — `api.window`
 
-Группа `api.window` управляет окном приложения и плавающим полем ввода.
+Группа `api.window` управляет окном приложения, плавающим полем ввода и
+списком выбора.
 
 ## Окно
 
@@ -39,3 +40,47 @@ api.window:open_input({
   end,
 })
 ```
+
+## Плавающий список выбора
+
+`api.window:open_select(options)` открывает список выбора чуть выше центра
+окна. Параметры передаются таблицей:
+
+| Поле | Описание |
+| --- | --- |
+| `items` | Непустой массив пунктов (см. ниже) |
+| `selected` | id пункта, выделенного при открытии; если не задан или не найден — первый пункт |
+| `title` | Текст над списком; отделяется горизонтальной чертой, без заголовка черты нет |
+| `callback` | `function(id)` — вызывается после Enter, когда окно уже закрыто; получает id выбранного пункта |
+
+Каждый пункт — таблица с полями:
+
+| Поле | Описание |
+| --- | --- |
+| `label` | Отображаемое значение (обязательно) |
+| `id` | Строка, которая вернётся в `callback` (обязательно) |
+| `icon` | Имя иконки Lucide, например `"file"`; пустое или неизвестное имя — пункт без иконки |
+| `description` | Серое описание справа от названия; обрезается троеточием, название имеет приоритет |
+
+Каждый пункт занимает одну строку. Если иконка есть хотя бы у одного
+пункта, у остальных остаётся пустое место такой же ширины, чтобы названия
+начинались на одном уровне.
+
+Пока список открыт, сочетания клавиш приложения не работают: стрелки меняют
+выделение, `Home`/`End` прыгают к краям, `Enter` подтверждает выбор и вызывает
+`callback` с id пункта, клик по пункту выбирает и подтверждает его, а `Esc` и
+клик вне окна закрывают список без колбэка.
+
+```lua
+api.window:open_select({
+  title = "Режим",
+  selected = "release",
+  items = {
+    { id = "debug", label = "Debug", icon = "file", description = "с отладкой" },
+    { id = "release", label = "Release", icon = "folder" },
+  },
+  callback = function(id)
+    api.editor:set_active_text(id)
+  end,
+})
+```