refactor: Restructure GUI components into separate modules for improved maintainability

1 files changed, 235 insertions, 0 deletions

diff --git a/docs/gui_refactoring.md b/docs/gui_refactoring.md
new file mode 100644
index 0000000..76fac79
--- /dev/null
+++ b/docs/gui_refactoring.md
@@ -0,0 +1,235 @@
+# Architecture GUI Refactorée
+
+## Vue d'ensemble
+
+Le fichier `gui.py` a été refactorisé pour améliorer la maintenabilité en divisant la classe `MainWindow` monolithique (1837 lignes) en plusieurs modules organisés dans le dossier `gui/`.
+
+## Structure des fichiers
+
+```
+tidal_dl_ng/
+├── gui/
+│   ├── __init__.py              # Point d'entrée du module GUI
+│   ├── activate.py              # Fonction d'activation de l'application GUI
+│   ├── main_window.py           # Classe MainWindow principale
+│   ├── initialization.py        # Mixin: Initialisation des composants UI
+│   ├── tidal_session.py         # Mixin: Gestion de la session Tidal
+│   ├── signals.py               # Mixin: Gestion des signaux Qt
+│   ├── progress.py              # Mixin: Barres de progression
+│   ├── ui_helpers.py            # Mixin: Helpers UI (spinners, logs, statusbar)
+│   ├── track_extras.py          # Mixin: Cache et gestion des extras de tracks
+│   ├── updates.py               # Mixin: Vérification des mises à jour
+│   ├── downloads.py             # Mixin: Gestion des téléchargements
+│   ├── trees_results.py         # Mixin: Gestion des arbres et résultats
+│   ├── context_menus.py         # Mixin: Menus contextuels et actions
+│   ├── history.py               # Mixin: Historique et prévention des doublons
+│   ├── covers.py                # Manager de couvertures
+│   ├── playlist.py              # Manager de playlists
+│   ├── queue.py                 # Manager de queue
+│   └── search.py                # Manager de recherche
+├── gui.py                       # Point de compatibilité (redirige vers gui/)
+```
+
+## Mixins et Responsabilités
+
+### 1. InitializationMixin (`initialization.py`)
+
+Responsable de l'initialisation de tous les composants de l'interface utilisateur.
+
+**Méthodes:**
+
+- `_init_gui()` - Configuration de la fenêtre principale
+- `_init_threads()` - Initialisation du pool de threads
+- `_init_dl()` - Configuration de l'objet Download
+- `_init_progressbar()` - Initialisation des barres de progression
+- `_init_info()` - Configuration de l'image de couverture par défaut
+- `_init_tree_results()` - Configuration de l'arbre des résultats
+- `_init_tree_results_model()` - Configuration du modèle de l'arbre
+- `_init_tree_queue()` - Configuration de la queue de téléchargement
+- `_init_tree_lists()` - Configuration de l'arbre des listes utilisateur
+- `_init_menu_actions()` - Ajout d'actions de menu personnalisées
+- `_populate_quality()` - Remplissage des options de qualité
+- `_populate_search_types()` - Remplissage des types de recherche
+
+### 2. TidalSessionMixin (`tidal_session.py`)
+
+Gère l'authentification et la session Tidal.
+
+**Méthodes:**
+
+- `init_tidal()` - Initialisation de la session Tidal avec gestion du login
+- `on_logout()` - Déconnexion de Tidal
+
+### 3. SignalsMixin (`signals.py`)
+
+Configure toutes les connexions de signaux Qt.
+
+**Méthodes:**
+
+- `_init_signals()` - Connexion de tous les signaux aux slots
+- `on_result_item_clicked()` - Gestion du clic sur un élément de résultat
+- `on_quality_set_audio()` - Configuration de la qualité audio
+- `on_quality_set_video()` - Configuration de la qualité vidéo
+
+### 4. ProgressMixin (`progress.py`)
+
+Gère les barres de progression.
+
+**Méthodes:**
+
+- `on_progress_reset()` - Réinitialisation des barres de progression
+- `on_progress_list()` - Mise à jour de la barre de progression de liste
+- `on_progress_item()` - Mise à jour de la barre de progression d'élément
+- `on_progress_item_name()` - Définition du nom d'élément
+- `on_progress_list_name()` - Définition du nom de liste
+
+### 5. UIHelpersMixin (`ui_helpers.py`)
+
+Fournit des fonctions utilitaires pour l'interface utilisateur.
+
+**Méthodes:**
+
+- `on_spinner_start()` - Démarrage d'un spinner de chargement
+- `on_spinner_stop()` - Arrêt de tous les spinners
+- `on_statusbar_message()` - Affichage d'un message dans la barre d'état
+- `_log_output()` - Redirection des logs vers l'interface
+- `button_reload_status()` - Mise à jour du statut du bouton de rechargement
+
+### 6. TrackExtrasMixin (`track_extras.py`)
+
+Gère le cache et la récupération des informations supplémentaires des tracks.
+
+**Méthodes:**
+
+- `get_track_extras()` - Récupération des extras (avec cache)
+- `_on_invoke_callback()` - Invocation du callback dans le thread principal
+- `_decorate_extras()` - Ajout de champs formatés aux extras
+- `preload_covers_for_playlist()` - Préchargement des couvertures
+
+### 7. UpdatesMixin (`updates.py`)
+
+Gère la vérification des mises à jour de l'application.
+
+**Méthodes:**
+
+- `on_update_check()` - Vérification des mises à jour disponibles
+- `on_version()` - Affichage du dialogue de version
+
+### 8. DownloadsMixin (`downloads.py`)
+
+Gère la queue de téléchargement et les opérations de téléchargement.
+
+**Méthodes:**
+
+- `on_download_results()` - Téléchargement des résultats sélectionnés
+- `queue_download_media()` - Ajout d'un élément à la queue
+- `watcher_queue_download()` - Surveillance de la queue
+- `on_queue_download()` - Exécution d'un téléchargement
+- `download()` - Téléchargement d'un élément média
+- Méthodes de gestion de statut: `on_queue_download_item_downloading()`, etc.
+
+### 9. TreesResultsMixin (`trees_results.py`)
+
+Gère les arbres de vue et l'affichage des résultats.
+
+**Méthodes:**
+
+- `handle_filter_activated()` - Gestion des filtres d'en-tête
+- `populate_tree_results()` - Remplissage de l'arbre des résultats
+- `populate_tree_result_child()` - Création d'un élément enfant
+- `on_tr_results_expanded()` - Gestion de l'expansion des résultats
+- `tr_results_expanded()` - Chargement des enfants d'un élément
+- `list_items_show_result()` - Affichage des éléments d'une liste
+- `tidal_user_lists()` - Récupération des listes utilisateur
+- `on_populate_tree_lists()` - Remplissage de l'arbre des listes
+- `on_track_hover_confirmed()` - Gestion du survol d'un track
+- `on_track_hover_left()` - Gestion de la sortie du survol
+
+### 10. ContextMenusMixin (`context_menus.py`)
+
+Gère les menus contextuels et leurs actions.
+
+**Méthodes:**
+
+- `menu_context_tree_results()` - Menu contextuel pour les résultats
+- `menu_context_queue_download()` - Menu contextuel pour la queue
+- `on_copy_url_share()` - Copie de l'URL de partage
+- `on_download_album_from_track()` - Téléchargement de l'album d'un track
+- `on_download_all_albums_from_playlist()` - Téléchargement de tous les albums
+- `_extract_album_ids_from_tracks()` - Extraction des IDs d'albums
+- `_load_albums_with_rate_limiting()` - Chargement avec limitation de débit
+- `on_search_in_app()` - Recherche dans l'application
+- `on_search_in_browser()` - Ouverture de recherche dans le navigateur
+
+### 11. HistoryMixin (`history.py`)
+
+Gère l'historique des téléchargements et la prévention des doublons.
+
+**Méthodes:**
+
+- `on_view_history()` - Affichage du dialogue d'historique
+- `on_toggle_duplicate_prevention()` - Activation/désactivation de la prévention
+- `on_mark_track_as_downloaded()` - Marquer un track comme téléchargé
+- `on_mark_track_as_not_downloaded()` - Retirer le marquage
+- `_update_downloaded_column()` - Mise à jour de la colonne UI
+- `on_preferences()` - Ouverture du dialogue de préférences
+- `on_settings_save()` - Sauvegarde des paramètres
+
+## Classe MainWindow
+
+La classe `MainWindow` hérite de tous les mixins et de `QtWidgets.QMainWindow` + `Ui_MainWindow`:
+
+```python
+class MainWindow(
+    QtWidgets.QMainWindow,
+    Ui_MainWindow,
+    InitializationMixin,
+    TidalSessionMixin,
+    SignalsMixin,
+    ProgressMixin,
+    UIHelpersMixin,
+    TrackExtrasMixin,
+    UpdatesMixin,
+    DownloadsMixin,
+    TreesResultsMixin,
+    ContextMenusMixin,
+    HistoryMixin,
+):
+    ...
+```
+
+## Compatibilité
+
+Le fichier `gui.py` original est maintenu comme point de compatibilité :
+
+- Redirige les imports vers `tidal_dl_ng.gui`
+- Conserve les directives de compilation nuitka
+- Permet une migration progressive
+
+## Avantages de cette architecture
+
+1. **Maintenabilité** : Chaque mixin a une responsabilité claire et limitée
+2. **Lisibilité** : Fichiers plus petits et focalisés (100-300 lignes vs 1837)
+3. **Testabilité** : Les mixins peuvent être testés individuellement
+4. **Extensibilité** : Facile d'ajouter de nouvelles fonctionnalités
+5. **Réutilisabilité** : Les mixins peuvent être réutilisés si nécessaire
+6. **Organisation** : Structure logique par fonctionnalité
+
+## Migration
+
+Pour utiliser la nouvelle structure :
+
+```python
+# Ancienne méthode (toujours supportée)
+from tidal_dl_ng.gui import gui_activate
+
+# Nouvelle méthode recommandée
+from tidal_dl_ng.gui import MainWindow
+from tidal_dl_ng.gui.activate import gui_activate
+```
+
+## Notes
+
+- Les avertissements IDE sur les "unresolved attributes" dans les mixins sont normaux
+- Les mixins accèdent à `self` qui sera fourni par `MainWindow` via l'héritage multiple
+- L'ordre des mixins dans l'héritage est important pour la résolution de méthode (MRO)