# Plan d'amélioration – Shaarli Professional Theme (`shaarli-pro`)

> Objectif : transformer le thème actuel, riche en fonctionnalités mais encore très artisanal, en une solution **professionnelle**, **sécurisée**, **maintenable**, **performante** et **accessible**.

Ce plan repose sur une analyse statique complète du code (README, rapport d'analyse existant, templates, CSS, JS, comparaison avec le thème `default` officiel de Shaarli).

---

## 1. Synthèse de l'état actuel

### 1.1 Métriques

| Fichier / catégorie | Taille | Remarque |
|---|---|---|
| `js/script.js` | ~3 620 lignes | Thème, navigation, recherche, lecteur, multi-sélection, etc. |
| `js/custom_views.js` | ~6 160 lignes | Notes, todos, archive, color picker, background studio |
| `js/shaarit-rules.js` | 377 lignes | Règles métier ShaarIt (tags, détection, URLs) |
| `css/style.css` | ~4 700 lignes | Design system principal |
| `css/custom_views.css` | ~1 780 lignes | Styles des vues notes/todos |
| `css/themes.css` | ~1 680 lignes | 16 palettes de couleurs |
| Templates HTML | ~40 fichiers | Dont plusieurs non documentés |
| Tests / CI / lint | 0 | Aucun outil d'assurance qualité |

### 1.2 Forces à préserver

- UI moderne, cohérente, avec sidebar + header.
- Mode clair/sombre et système de thèmes multiples.
- Fonctionnalités avancées : notes, todos, archive, lecteur média, multi-sélection, recherche Spotlight.
- Variables CSS et design system en place.
- Utilisation de `localStorage` pour la persistance locale.

### 1.3 Appréciation globale

Le thème vaut **~6,5 / 10** en termes de professionnalisation. Il est fonctionnellement abouti, mais accumule de la dette technique : failles XSS potentielles, code monolithique, duplication, dépendances externes non maîtrisées, absence de tests et documentation obsolète.

---

## 2. Problèmes critiques – à traiter en priorité (Phase 1)

Ces points bloquent une mise en production professionnelle.

### 2.1 Sécurité

| Problème | Fichier(s) | Risque | Action |
|---|---|---|---|
| **XSS via `innerHTML`** sur descriptions, previews, lecteur popup, tags | `js/script.js` (l. 1547, 1603, 2151…), `js/custom_views.js` (passim) | Exécution de code si un bookmark contient du HTML/JS malveillant | Tout contenu dynamique doit passer par `textContent` ou être échappé avec `escapeHtml`. Remplacer `innerHTML` par `innerText` / création DOM sécurisée. |
| **Génération de code JavaScript en chaîne** pour la popup lecteur | `js/script.js` `buildPlayerHTML()` (l. 2523–3053) | Injection possible si titre/URL contiennent des quotes ou du code | Supprimer `buildPlayerHTML()` ; utiliser le template `player.html` existant ou un composant DOM réel. |
| **Persistance de la configuration via un bookmark privé** (`shaarit_config`) | `js/script.js` `ShaaritThemeConfig` (l. 7–154) | Fuite de config, pollution de la base, risque si un attaquant crée un bookmark avec ce tag | Remplacer par `localStorage` uniquement, ou par un vrai plugin backend dédié. |
| **URLs internes fixes vers `shaarit.app`** | `js/shaarit-rules.js` (l. 142–148), `js/script.js`, `migrate-todos.php` | Dépendance externe, fuite de données, rupture si le domaine change | Rendre les schémas d'URLs internes configurables (`note://`, `todo://`, ou URLs relatives). |
| **Script PHP de migration dans le thème** | `migrate-todos.php` | Modification directe de la base, pas de contrôle d'accès, exécutable via web | Supprimer du thème ; en faire un plugin admin ou un script CLI documenté hors `tpl/`. |
| **`descEl.innerHTML` utilisé comme source de Markdown** | `js/custom_views.js` (l. 2422, 2492, 4239) | Récupère le HTML rendu par Shaarli, potentiellement exécutable | Utiliser `textContent` comme source unique. |

### 2.2 Bugs et instabilités

| Problème | Fichier(s) | Action |
|---|---|---|
| **`player.html` n'est jamais utilisé** mais dupliqué en JS | `player.html`, `js/script.js` | Supprimer `player.html` si inutile, ou l'utiliser comme cible de la popup. |
| **Template officiel `pluginscontent.html` absent** | `tpl/default/pluginscontent.html` | Ajouter `pluginscontent.html` pour ne pas casser les plugins qui utilisent `plugin_content`. |
| **Gestion d'erreurs `fetch` insuffisante** | `js/script.js`, `js/custom_views.js` | Ajouter des `try/catch`, vérifier `response.ok`, informer l'utilisateur en cas d'échec. |
| **Écouteurs d'événements ajoutés mais jamais supprimés** | `js/script.js` (102 `addEventListener`), `js/custom_views.js` (104) | Nettoyer les listeners dans les modales, popups, sidebars mobile. |
| **`tools_plugin` inclus deux fois** | `tools.html` (l. 217 et 283) | Ne garder qu'une seule zone. |
| **Hidden tags stockés uniquement dans `localStorage`** | `hidden-tags.html`, `tools.html` | Per-browser, non synchronisés. Persister côté serveur (plugin) ou au minimum documenter la limitation. |
| **Sélecteurs DOM très longs et fragiles** | `css/style.css`, JS | Raccourcir et utiliser des classes sémantiques (BEM ou équivalent). |

### 2.3 Compatibilité avec Shaarli officiel

- Le thème `default` utilise `{$version_hash}` pour le cache-busting ; `shaarli-pro` utilise des versions codées en dur (`v=1.0.5`, etc.) qui ne correspondent pas à `theme_info.php` (`1.0.0`).
- OpenGraph et `apple-touch-icon` sont absents du `includes.html` alors que le thème officiel les fournit.
- Les templates officiels utilisent systématiquement `{'key'|t}` pour l'internationalisation ; `shaarli-pro` mélange français, anglais et textes en dur.

---

## 3. Points non finis / fonctionnalités à finaliser

### 3.1 Vue Archive

- `initArchiveView()` existe (`js/custom_views.js`) mais l'expérience semble moins aboutie que Notes/Todos (moins de styles dédiés, pas de création d'archive explicite).
- **Action** : finaliser l'UI archive ou fusionner avec une fonction "archiver" depuis la vue Notes.

### 3.2 Gestion des tags cachés

- Double implémentation : `hidden-tags.html` et le panneau dans `tools.html`.
- La logique est dupliquée entre `js/script.js` (chargement) et le script inline de `hidden-tags.html`.
- **Action** : centraliser la liste des tags système, définir une source unique (idéalement côté serveur via un plugin).

### 3.3 Lecteur média

- Le lecteur inline et la popup partagent un état via `localStorage` et `BroadcastChannel`, ce qui est complexe.
- `player.html` n'est pas utilisé.
- **Action** : choisir une architecture unique (inline OU popup via un vrai template) et la stabiliser.

### 3.4 Panneau des thèmes

- `themes.css` charge 16 palettes (37 Ko) même si l'utilisateur n'en utilise qu'une.
- **Action** : charger dynamiquement le CSS du thème actif, ou au minimum splitter `themes.css` par thème.

### 3.5 README et documentation

- Le README annonce une "Structure du Projet" incomplète : il omet `custom_views.js/css`, `themes.css`, `player.html`, `hidden-tags.html`, `install.html`, `migrate-todos.php`, `shaarit-rules.js`, `backgrounds-manifest.json`, les fonds d'écran `note-bg-*`.
- **Action** : réécrire le README, ajouter un CHANGELOG et un guide de contribution.

---

## 4. Axes d'amélioration structurants

### 4.1 Qualité et maintenabilité du code

1. **Modulariser le JavaScript**
   - Découper `script.js` en modules thématiques : `theme.js`, `search.js`, `media-player.js`, `bulk-actions.js`, `editor.js`, `mobile-nav.js`.
   - Découper `custom_views.js` en : `notes.js`, `todos.js`, `archive.js`, `palette.js`, `background-studio.js`.
2. **Supprimer les `console.log` de debug** (calendar, pin, theme sync, etc.).
3. **Uniformiser la gestion des erreurs** : toutes les fonctions `async` doivent avoir un `try/catch` et un retour utilisateur.
4. **Réduire la spécificité CSS** : éviter les sélecteurs de plus de 3 niveaux, nettoyer les `!important` (26 dans `custom_views.css`).
5. **Dédupliquer la navigation** sidebar / header, soit via un template partagé, soit via génération JS à partir d'un tableau de liens.

### 4.2 Performance

1. **Mettre en place un build frontend** (Vite, Webpack ou Rollup) pour :
   - minifier JS/CSS,
   - splitter les thèmes,
   - ajouter des hashes de cache-busting,
   - héberger localement les polices et les icônes si possible.
2. **Charger `custom_views.js` uniquement sur les pages concernées** (actuellement chargé partout via `includes.html`).
3. **Remplacer l'`@import` Google Fonts** par un `<link rel="preload" as="style">` ou des polices locales.
4. **Optimiser les images** de fond (`note-bg-*`) : WebP/AVIF, redimensionnement, lazy-loading.
5. **Supprimer le CSS mort** avec un outil comme PurgeCSS ou un audit manuel des classes.

### 4.3 Accessibilité (a11y)

1. **Rendre les modales focus-trap** (recherche, filtres, QR code, notes, todos).
2. **Utiliser `aria-selected`** sur les boutons de mode de recherche et les onglets.
3. **Ajouter `prefers-reduced-motion`** pour désactiver les animations.
4. **Vérifier tous les contrastes** (notamment `--tag-green-text` signalé comme limite).
5. **Ajouter des skip-links** et s'assurer que tous les boutons icônes ont un `aria-label` explicite.
6. **Remplacer les emojis utilisés comme indicateurs** (📌 dans `linklist.html`) par des icônes sémantiques.

### 4.4 Internationalisation (i18n)

1. **Extraire toutes les chaînes** des templates vers le format Shaarli : `{'Ma clé'|t}`.
2. Faire de même pour les textes générés en JS (labels de boutons, messages d'erreur, placeholders).
3. Documenter les nouvelles clés de traduction ajoutées.

### 4.5 Architecture des fonctionnalités ShaarIt

1. **Rendre les règles ShaarIt configurables** : le serveur Shaarli, pas `shaarit.app`, doit être la source de vérité pour les URLs internes.
2. **Ne plus utiliser des tags comme base de données** pour stocker la config thème ; utiliser `localStorage` ou un plugin backend.
3. **Réfléchir à un backend dédié** pour notes/todos (plugin PHP) afin d'éviter les contournements par bookmarks et `fetch` sur les formulaires d'édition.

---

## 5. Nouvelles idées à intégrer (par ordre de valeur)

| Idée | Intérêt | Complexité |
|---|---|---|
| **Service Worker / PWA** (offline, manifest, icônes) | Professionnalisation forte, usage mobile | Moyenne |
| **Tests E2E avec Playwright** (recherche, thème, multi-sélection, lecteur) | Garantie de non-régression | Moyenne |
| **CI/CD GitHub Actions** (lint, build, tests, release) | Qualité continue | Faible |
| **ESLint + Stylelint + Prettier** | Maintenabilité, style cohérent | Faible |
| **Mode haut contraste** (`prefers-contrast`) | Accessibilité | Faible |
| **Amélioration du lecteur** : playlist, historique, gestion des erreurs | UX | Moyenne |
| **Recherche serveur** pour les grosses collections (au lieu de parser le DOM) | Performance | Moyenne/forte |
| **API côté serveur** pour notes/todos/tags cachés | Sécurité, fiabilité | Forte |
| **Dashboard de statistiques** plus riche dans Tools | UX | Moyenne |
| **Documentation technique auto-générée** (JSDoc, Storybook-like) | Maintenabilité | Moyenne |

---

## 6. Roadmap recommandée

### Phase 1 – Sécurité et stabilité (2 à 3 semaines)

- [ ] Audit XSS : remplacer tous les `innerHTML` à risque par du DOM sécurisé.
- [ ] Supprimer ou sécuriser `buildPlayerHTML()` ; utiliser `player.html` ou un composant DOM.
- [ ] Retirer `migrate-todos.php` du thème (plugin/CLI séparé).
- [ ] Remplacer la persistance "bookmark config" par `localStorage` pur ou un plugin backend.
- [ ] Ajouter le template `pluginscontent.html` manquant.
- [ ] Nettoyer les `console.log` de debug.
- [ ] Gestion d'erreurs robuste sur tous les `fetch`.
- [ ] Tests manuels complets sur une instance Shaarli propre.

### Phase 2 – Qualité et maintenabilité (2 à 3 semaines)

- [ ] Découper `script.js` et `custom_views.js` en modules thématiques.
- [ ] Refactoriser la navigation sidebar/header pour supprimer la duplication.
- [ ] Unifier le CSS variables et supprimer les variables mortes.
- [ ] Extraire les textes en dur vers `{'key'|t}`.
- [ ] Mettre en place ESLint + Stylelint + Prettier.
- [ ] Réécrire le README et ajouter un CHANGELOG.

### Phase 3 – Performance et accessibilité (1 à 2 semaines)

- [ ] Mettre en place un build (minification, hash, split des thèmes).
- [ ] Charger `custom_views.js` à la demande.
- [ ] Optimiser les polices et icônes (local/swap).
- [ ] Audit a11y complet (modales, contrastes, reduced-motion).
- [ ] Optimiser les images de fond.

### Phase 4 – Évolutions (selon les priorités utilisateur)

- [ ] PWA / Service Worker.
- [ ] Tests E2E Playwright.
- [ ] CI/CD GitHub Actions.
- [ ] Backend plugin pour notes/todos/config.
- [ ] Améliorations du lecteur (playlist, historique).

---

## 7. Critères de validation

Pour considérer le thème comme professionnel, les critères suivants doivent être atteints :

1. **Sécurité** : aucune alerte critique (XSS, injection, `eval`, `document.write`) ; contenu utilisateur toujours échappé.
2. **Stabilité** : aucune erreur JS en console sur les parcours principaux (login, liste, ajout, édition, recherche, notes, todos, tools).
3. **Compatibilité** : tous les templates officiels sont présents ou justifiés ; les plugins standard fonctionnent.
4. **Performance** : score Lighthouse > 90 sur Performance et Accessibilité (sur une instance de référence).
5. **Maintenabilité** : code modularisé, linté, documenté.
6. **Internationalisation** : toutes les chaînes utilisateur passent par le système de traduction Shaarli.
7. **Tests** : tests E2E critiques passants (recherche, multi-sélection, changement de thème, lecteur).

---

## 8. Premières actions immédiates (si vous voulez démarrer demain)

1. Corriger les failles XSS dans `js/script.js::renderResults`, `js/custom_views.js` et la popup lecteur.
2. Supprimer `migrate-todos.php` du dossier thème.
3. Décider de l'avenir de la persistance thème : `localStorage` uniquement ou plugin backend ?
4. Créer `pluginscontent.html`.
5. Nettoyer les `console.log` restants.
6. Mettre à jour le README avec la structure réelle.

---

*Plan rédigé le 8 août 2026. Il doit être affiné avec les retours utilisateurs et les contraintes réelles de déploiement (version de Shaarli, hébergement, usage du mobile).*