telegram-tui/README.md

# tele-tui

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org/)

Консольный Telegram клиент с Vim-style навигацией.

![tele-tui screenshot](docs/screenshot.png)

## Возможности

- **Полная интеграция с Telegram**: отправка/получение сообщений, редактирование, удаление, пересылка
- **Vim-style навигация**: hjkl + поддержка русской раскладки (ролд)
- **Markdown форматирование**: жирный, курсив, подчёркивание, зачёркивание, код, спойлеры, ссылки
- **Реакции на сообщения**: emoji picker с навигацией стрелками
- **Папки Telegram**: переключение между папками (1-9)
- **Поиск**: по чатам (Ctrl+S) и внутри чата (Ctrl+F)
- **Черновики**: автосохранение набранного текста при переключении чатов
- **Typing indicator**: показывает когда собеседник печатает
- **Закреплённые сообщения**: отображение и переход к закреплённому сообщению
- **Копирование в буфер**: copy сообщений в системный буфер обмена
- **Профиль**: просмотр информации о пользователе/чате
- **Конфигурация**: настройка цветов и часового пояса через TOML
- **Оптимизация**: 60 FPS, умное кеширование, graceful shutdown

## Установка

### Требования

- Rust 1.70+
- TDLib (скачивается автоматически через tdlib-rs)

### Сборка

```bash
git clone https://github.com/your-username/tele-tui.git
cd tele-tui
cargo build --release
```

### API Credentials

Получите API credentials на https://my.telegram.org/apps

Создайте файл `~/.config/tele-tui/credentials`:
```
API_ID=your_api_id
API_HASH=your_api_hash
```

Или используйте `.env` файл в директории проекта:
```
API_ID=your_api_id
API_HASH=your_api_hash
```

## Использование

```bash
cargo run --release
```

При первом запуске нужно пройти авторизацию (телефон + код + опционально 2FA пароль).

## Конфигурация

Конфигурационный файл создаётся автоматически в `~/.config/tele-tui/config.toml`:

```toml
[general]
# Часовой пояс в формате "+03:00" или "-05:00"
timezone = "+03:00"

[colors]
# Поддерживаемые цвета: black, red, green, yellow, blue, magenta, cyan, gray, white,
# darkgray, lightred, lightgreen, lightyellow, lightblue, lightmagenta, lightcyan
incoming_message = "white"
outgoing_message = "green"
selected_message = "yellow"
reaction_chosen = "yellow"
reaction_other = "gray"
```

## Горячие клавиши

### Навигация
- `↑/↓` или `k/j` (р/о) — навигация по списку чатов
- `Enter` — открыть чат / отправить сообщение
- `Esc` — закрыть чат / отменить действие
- `1-9` — переключение между папками
- `Ctrl+S` — поиск по чатам
- `Ctrl+R` — обновить список чатов
- `Ctrl+C` — выход

### В открытом чате
- `↑/↓` — скролл сообщений
- `Ctrl+F` — поиск в чате
- `n/N` — следующий/предыдущий результат поиска
- `i` — информация о чате/пользователе

### Работа с сообщениями
- `↑` при пустом инпуте — выбор сообщения
- `Enter` в режиме выбора — редактировать
- `r` / `к` — ответить (reply)
- `f` / `а` — переслать (forward)
- `d` / `в` / `Delete` — удалить
- `y` / `н` — скопировать в буфер
- `e` / `у` — добавить реакцию

### Emoji Picker (реакции)
- `←/→/↑/↓` — навигация по сетке
- `Enter` — добавить/удалить реакцию
- `Esc` — закрыть picker

### Редактирование текста
- `←/→` — перемещение курсора
- `Home` — в начало строки
- `End` — в конец строки
- `Backspace` — удалить символ слева
- `Delete` — удалить символ справа

## Структура проекта

```
src/
├── main.rs           # Точка входа, event loop
├── config.rs         # Конфигурация (TOML), credentials
├── app/              # Состояние приложения
├── ui/               # Отрисовка интерфейса
├── input/            # Обработка ввода
├── utils.rs          # Утилиты (форматирование времени, логи)
└── tdlib/            # TDLib интеграция
```

## Зависимости

- `ratatui` 0.29 — TUI framework
- `crossterm` 0.28 — terminal handling
- `tdlib-rs` 1.1 — Telegram API
- `tokio` 1.x — async runtime
- `serde` + `serde_json` — serialization
- `toml` 0.8 — config parsing
- `dirs` 5.0 — XDG directories
- `clipboard` 0.5 — clipboard access
- `chrono` 0.4 — date/time formatting

## Тестирование

tele-tui использует **snapshot тестирование** для UI и интеграционные тесты для логики.

### Запуск всех тестов

```bash
cargo test
```

### Snapshot тесты

Snapshot тесты проверяют отображение UI компонентов через виртуальный терминал:

```bash
# Прогнать snapshot тесты
cargo test --test chat_list
cargo test --test messages

# Посмотреть изменения в snapshots
cargo insta review

# Принять все новые snapshots
cargo insta accept

# Отклонить все изменения
cargo insta reject
```

### Установка cargo-insta

Для работы со snapshot тестами нужен `cargo-insta`:

```bash
cargo install cargo-insta
```

### Структура тестов

```
tests/
├── helpers/              # Тестовые утилиты
│   ├── app_builder.rs    # TestAppBuilder для создания тестовых App
│   ├── test_data.rs      # Builders для чатов и сообщений
│   ├── snapshot_utils.rs # Утилиты для snapshot тестов
│   └── fake_tdclient.rs  # Mock TDLib клиент (для будущих integration тестов)
├── chat_list.rs          # Snapshot тесты для списка чатов (9 тестов)
├── messages.rs           # Snapshot тесты для сообщений (18 тестов)
├── modals.rs             # Snapshot тесты для модалок (8 тестов)
└── input_field.rs        # Snapshot тесты для поля ввода (7 тестов)
```

### Создание snapshot теста

```rust
use helpers::test_data::TestChatBuilder;
use helpers::app_builder::TestAppBuilder;
use helpers::snapshot_utils::{render_to_buffer, buffer_to_string};
use insta::assert_snapshot;

#[test]
fn snapshot_my_feature() {
    let chat = TestChatBuilder::new("Test Chat", 123)
        .unread_count(5)
        .build();

    let mut app = TestAppBuilder::new()
        .with_chat(chat)
        .selected_chat(123)
        .build();

    let buffer = render_to_buffer(80, 24, |f| {
        tele_tui::ui::chat_list::render(f, f.area(), &mut app);
    });

    let output = buffer_to_string(&buffer);
    assert_snapshot!("my_feature", output);
}
```

### Покрытие тестами

**Текущий прогресс**: 81/151 тестов (54%)

- ✅ Фаза 0: Инфраструктура (100%)
- ✅ Фаза 1: UI Snapshot Tests (100%)
  - Chat List, Messages, Modals, Input Field, Footer, Screens  
- 🔄 Фаза 2: Integration Tests (35%)
  - ✅ Send Message Flow (6 тестов)
  - ✅ Edit Message Flow (6 тестов)
  - ✅ Delete Message Flow (6 тестов)
  - ✅ Reply & Forward Flow (8 тестов)
  - 📋 Reactions, Search, Drafts, Navigation, Profile, Network (0/48)

Подробный план: [TESTING_ROADMAP.md](TESTING_ROADMAP.md)

## Документация

- [INSTALL.md](INSTALL.md) — подробная инструкция по установке
- [HOTKEYS.md](HOTKEYS.md) — все горячие клавиши
- [FAQ.md](FAQ.md) — часто задаваемые вопросы
- [CONTRIBUTING.md](CONTRIBUTING.md) — как внести вклад
- [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) — структура проекта
- [SECURITY.md](SECURITY.md) — политика безопасности
- [CHANGELOG.md](CHANGELOG.md) — история изменений
- [REQUIREMENTS.md](REQUIREMENTS.md) — функциональные требования
- [DEVELOPMENT.md](DEVELOPMENT.md) — правила разработки
- [ROADMAP.md](ROADMAP.md) — план развития проекта
- [REFACTORING_ROADMAP.md](REFACTORING_ROADMAP.md) — план рефакторинга кода
- [TESTING_ROADMAP.md](TESTING_ROADMAP.md) — план покрытия тестами
- [TESTING_PROGRESS.md](TESTING_PROGRESS.md) — прогресс тестирования
- [CONTEXT.md](CONTEXT.md) — текущий статус разработки

## Лицензия

MIT