vcom/docs/project-description.md

vcom: описание проекта и реализованного функционала

vcom — терминальный файловый менеджер в стиле Midnight Commander, написанный на Go на базе Bubble Tea.

1. Основная концепция

Приложение работает в двухпанельном режиме:

• левая файловая панель,
• правая файловая панель.

Активная панель управляется с клавиатуры и мыши, неактивная сохраняет своё состояние (путь, позицию курсора).

2. Реализованные режимы интерфейса

• Двухпанельный браузер директорий.
• Режим Info/Preview (i): неактивная панель временно заменяется превью выбранного элемента из активной панели.
• Режим выделения текста в превью (Ctrl+t) для текстовых файлов.
• Модальные окна (подтверждения, прогресс операций, help, уведомления).

3. Навигация и просмотр

• Перемещение по списку: j/k, Up/Down, PgUp/PgDn.
• Переключение активной панели: Tab, h, l.
• Вход в директорию: Enter / Right.
• Переход в родительскую директорию: Backspace / Left.
• Обновление панелей: r.
• Внешний просмотр файла: F3 ($PAGER при наличии).
• Внешнее редактирование файла: F4 ($VISUAL/$EDITOR или fallback-редакторы).

4. Операции с файлами и директориями

• F5 — копирование.
• F6 — перемещение.
• F7 — создание директории.
• F8 — удаление.

Операции copy/move реализованы с:

• предварительным диалогом подтверждения,
• подсчётом объёма и количества файлов,
• прогрессом по байтам и по количеству файлов,
• возможностью отправить операцию в фон (b),
• уведомлением о завершении фоновой операции.

Подтверждение overwrite учитывается для существующих целей.

5. Мультивыделение

Реализовано выделение элементов с клавиатуры:

• Shift+Up/Shift+Down (а также Shift+K/Shift+J) добавляют/снимают выделение на текущем проходе.
• Повторный проход по уже выделенному элементу снимает его выделение (toggle).
• Esc очищает выделение активной панели.

Если есть выделенные элементы, F5/F6/F8 применяются ко всему выделенному набору. Если выделения нет — операция применяется к текущему элементу под курсором.

6. Работа мыши

• ЛКМ: выбор элемента и активация панели.
• Двойной ЛКМ: открытие элемента.
• ПКМ: переключение режима Info/Preview для выбранного элемента.
• Колесо мыши: прокрутка списка; в preview-области — прокрутка содержимого превью.

7. Help-окно

F1 или ? открывает справку по управлению.

Особенности help:

• логические блоки (Navigation, View and Panels, Dialogs and Transfers, Mouse),
• цветовое оформление заголовков и элементов на основе активной темы,
• закрытие по F1, ?, Esc, Enter, q.

8. Модальные окна и закрытие

Во всех модальных окнах поддержано закрытие по q.

Поведение в прогрессе copy/move:

• q не прерывает операцию,
• окно закрывается,
• операция продолжается в фоне.

9. Визуальные доработки

• Убрана верхняя title-строка приложения.
• Убраны текстовые лейблы LEFT/RIGHT в заголовках панелей.
• Убрана строка CONTENT в preview-панели.
• Путь активной панели сделан жирным и в цвете TextFile текущей темы.
• Подсветка курсора отображается только в активной панели.
• Выделенные (marked) элементы подсвечиваются цветом Danger темы по всей строке.

10. Конфигурация

Поддерживается TOML-конфиг (vcom.toml), включая:

• стартовые директории,
• визуальные параметры UI,
• набор и видимость колонок,
• сортировку,
• поведение превью,
• поведение подтверждений и операций.

11. Технологический стек

• Go
• Bubble Tea (github.com/charmbracelet/bubbletea)
• Bubbles
• Lip Gloss
• TOML (pelletier/go-toml/v2)

12. Сборка и запуск

Локально:

go run ./cmd/vcom

Сборка бинаря:

go build -o vcom ./cmd/vcom

Nix:

nix run .

Для запуска тегов из GitHub-репозитория рекомендуется использовать версии с v0.1.1 и выше.