Shaarli_bm_theme/README.md

# Shaarli Professional Theme

> Thème moderne et professionnel pour [Shaarli](https://github.com/shaarli/Shaarli), pensé pour une expérience utilisateur premium, responsive et performante.

## Présentation

| | |
|---|---|
| **Nom interne** | Professional (`shaarli-pro`) |
| **Version** | 1.1.0 |
| **Compatibilité** | Shaarli ≥ 0.9, PHP ≥ 7.4 |
| **Licence** | MIT |
| **Dossier** | `tpl/shaarli-pro` |
| **Build** | Node.js ≥ 18, `npm run build` |

Le thème offre un layout de type application avec barre latérale fixe, navigation fluide, mode clair/sombre natif, et une couche JavaScript riche dédiée à l'interactivité.

---

## Fonctionnalités

### 🎨 Design & Interface

- **Mode clair / sombre** avec bascule instantanée, mémorisation dans `localStorage`, et support de `prefers-color-scheme` du système.
- **Anti-FOUC** : un script inline dans `<head>` applique le thème *avant* le chargement du CSS pour éviter le flash de contenu non stylé.
- **Variables CSS centralisées** (`--primary`, `--bg-body`, `--text-main`, etc.) pour une personnalisation aisée de la palette, des ombres et de la typographie.
- **Police Inter** (Google Fonts) pour une typographie moderne et lisible.
- **Icônes Material Design Icons** (MDI Webfont v7.2) pour une iconographie cohérente et riche.
- **Animations fluides** : transitions sur les cartes, menus, modales, filtres, et effets de hover.

### 📐 Layout Sidebar + Header

- **Sidebar fixe** sur desktop (230px) avec :
  - Logo et titre de l'instance
  - Navigation : Bookmarks, Tag Cloud, Picture Wall, Daily
  - Section Admin (si connecté) : Tools, Settings
  - Bouton « New Bookmark » (si connecté)
  - Toggle clair/sombre intégré
- **Header sticky** avec :
  - Navigation principale (HOME, TAG CLOUD, PICTURE WALL, DAILY, SEARCH)
  - Actions rapides : filtres, multi-sélection, RSS, outils, login/logout
  - Support des boutons de plugins (`plugins_header.buttons_toolbar`)
- **Responsive** : la sidebar se transforme en menu escamotable (hamburger) sous 1024px.

### 🔍 Recherche « Spotlight »

- Modale de recherche en surimpression inspirée de macOS Spotlight.
- **Raccourci clavier** : touche `S` pour ouvrir, `ESC` pour fermer.
- **Deux modes** : recherche par texte libre ou filtrage par tags.
- **Résultats en temps réel** avec défilement au clavier (↑ / ↓) et sélection via `Enter`.
- **Surlignage** (highlight) des termes correspondants dans les résultats.
- **Debounce** (150ms) pour optimiser les performances lors de la saisie.

### 🎛️ Filtres Rapides

- **Panneau de filtres** en dropdown depuis le header :
  - Nombre de liens par page (20, 50, 100, ou valeur personnalisée)
  - Filtrage par visibilité : liens privés, publics, ou tous (si connecté)
  - Filtrage par tags : liens non tagués uniquement
- **Bannière d'information** dynamique indiquant les filtres actifs avec compteur de résultats.
- **Indicateur visuel** (badge pulsant) sur le bouton filtre lorsque des filtres sont actifs.
- **Bouton "Clear"** pour réinitialiser tous les filtres en un clic.

### 📄 Trois Vues de Liens

| Vue | Description |
|-----|-------------|
| **Grille** | Cartes avec miniatures, description tronquée (3 lignes), tags et actions. Idéal pour le parcours visuel. |
| **Liste** | Disposition horizontale avec miniature latérale en fondu, description (2 lignes), footer avec tags et actions. |
| **Compact** | Mode dense style tableau : titre + URL sur une ligne, tags et actions alignés à droite. Parfait pour les grandes collections. |

- Le choix de vue est persisté dans `localStorage`.
- Chaque vue a son propre positionnement pour : badges de visibilité, cases de sélection, boutons d'action.

### ✅ Multi-Sélection & Actions Groupées

- **Mode sélection** activable via le bouton dans le header.
- Cases à cocher sur chaque bookmark (apparaissent au survol ou en mode sélection).
- **Barre d'actions groupées** fixe en bas avec :
  - Compteur de sélection
  - « Select all » pour sélectionner tous les liens visibles
  - Actions : DELETE, SET PUBLIC, SET PRIVATE
  - Bouton CANCEL pour quitter le mode

### 🖼️ Picture Wall (Mur d'Images)

- **Grille responsive** avec taille d'image configurable via un slider (120px–400px).
- **Boutons +/−** pour ajuster rapidement la taille.
- **Persistance** de la taille choisie dans `localStorage`.
- **Overlay au survol** avec titre et URL du bookmark.
- **Animations** : zoom léger de l'image au survol, apparition de l'overlay en slide.
- **Indicateur de lien externe** (icône en haut à droite au survol).

### 📅 Page Daily

- Navigation jour / semaine / mois avec boutons de sélection.
- Affichage chronologique des bookmarks avec :
  - Titre cliquable vers l'URL originale
  - Miniature (si disponible)
  - Description formatée
  - Horodatage et tags
- Navigation précédent / suivant entre les périodes.
- Support des zones de plugins.

### 🎵 Lecteur Multimédia Persistant

- **Détection automatique** des URLs audio/streaming dans les bookmarks.
- Bouton ▶ injecté dans la barre d'actions des bookmarks contenant des médias.
- **Barre de lecture fixe** en bas de page avec :
  - Lecture / Pause
  - Barre de progression interactive
  - Affichage du temps (ou « LIVE » pour les flux en continu)
  - Contrôle de volume avec bouton mute
  - Bouton de fermeture
- **Persistance entre pages** : le lecteur reprend la lecture au même point lors de la navigation.
- Formats supportés : MP3, OGG, FLAC, WAV, AAC, M4A, OPUS, WMA, WEBM, M3U8, M3U, PLS.

### 🔌 Intégration des Plugins

- **QR Code** : remplacement de l'image inline par une icône MDI + modale élégante avec animation.
- **ReadItLater** : 
  - Icônes MDI (œil ouvert/fermé) au lieu du texte brut
  - Badge « To Read » positionné sur les bookmarks non lus
  - Bordure rouge sur les bookmarks à lire
  - Masquage du bouton « Mark as Read » dans la zone de pagination
- **Zones de plugins** : toutes les zones Shaarli standard sont supportées (`plugin_start_zone`, `plugin_end_zone`, `link_plugin`, `edit_link_plugin`, `buttons_toolbar`, etc.).

### 📄 Pages d'Administration

- **Outils** : liste moderne avec icônes, labels, sous-labels et chevrons de navigation.
- **Configuration** : formulaires stylés avec le design system du thème.
- **Gestion des tags** : renommage et suppression avec interface claire.
- **Import / Export** : pages de gestion des bookmarks Netscape.
- **Plugins Admin** : configuration et activation/désactivation des plugins.
- **Statistiques** : affichage du nombre total de liens et liens privés.
- **Bookmarklets** : boutons « Shaare link » et « Add Note » prêts à glisser.
- **Apps tierces** : liens rapides vers les extensions Firefox, Chrome, et apps Android/iOS.

### ♿ Accessibilité & Performance

- `:focus-visible` pour les éléments interactifs (clavier uniquement).
- `content-visibility: auto` sur les cartes de bookmarks pour un rendu optimisé.
- `loading="lazy"` sur les images et miniatures.
- Support `@media print` : masquage automatique de la sidebar, header et actions.
- Markup sémantique HTML5.
- Attributs `title` sur tous les boutons et liens d'action.

### 📱 Responsive Design

| Breakpoint | Adaptations |
|------------|-------------|
| `> 1024px` | Layout complet sidebar + contenu |
| `≤ 1024px` | Sidebar escamotable, menu mobile, textes de nav masqués |
| `≤ 768px` | Grille en colonne unique, toolbar empilé, header nav masqué |
| `≤ 480px` | Paddings réduits, vue liste en colonne, miniatures pleine largeur |

---

## Build & Développement

Le thème inclut un pipeline de build frontend pour minifier les assets et ajouter du cache-busting.

```bash
cd shaarli-pro
npm install       # installer les dépendances
npm run build     # minifier CSS/JS et générer dist/
npm run build:css # CSS uniquement
npm run build:js  # JS uniquement
npm run clean     # supprimer dist/
```

Les templates chargent les fichiers minifiés depuis `dist/` avec le hash de version Shaarli (`{$version_hash}`).
Les sources (`css/`, `js/`) restent les fichiers de référence : **ne modifiez jamais `dist/` à la main**.

Après chaque build, pensez à committer `dist/` pour que le thème reste utilisable sans Node.js côté production.

## Tests

### Tests E2E (Playwright)

Un socle de tests E2E est fourni pour valider les parcours critiques :

```bash
cd shaarli-pro
npm run test:e2e:install   # installer les navigateurs Playwright (une fois)
SHAARLI_URL=http://localhost:8080 npm run test:e2e
```

Les tests couvrent actuellement :

- chargement de la page d'accueil,
- ouverture de la recherche au clavier (`S`),
- bascule clair/sombre,
- présence du skip-link,
- présence du bouton de multi-sélection.

Un workflow GitHub Actions dédié (`.github/workflows/e2e.yml`) permet de les exécuter manuellement ou via cron une fois configuré avec `SHAARLI_URL`.

## PWA (Progressive Web App)

Le thème fournit un manifeste et un service worker de base :

- `manifest.json` : icônes, theme-color, mode standalone.
- `service-worker.js` : cache les assets statiques du thème (CSS/JS/icônes) pour un fonctionnement dégradé offline.

Le service worker intercepte uniquement les requêtes situées dans son scope (le dossier du thème). Les pages Shaarli dynamiques continuent d'être servies par le réseau.

## Installation

### 1. Téléchargement

```bash
git clone https://git.dracodev.net/Projets/Shaarli_bm_theme.git
```

### 2. Supprimer le thème en place

```bash
# Via Docker
docker exec -it shaarli_bookmarks rm -rf /var/www/shaarli/tpl/shaarli-pro

# Ou manuellement
rm -rf /path/to/shaarli/tpl/shaarli-pro
```

### 3. Copie dans Shaarli

Le dossier `dist/` contient les assets CSS/JS déjà minifiés et est versionné. Vous n'avez **pas besoin de lancer `npm install`** si vous utilisez le thème tel quel.

Copier le dossier `shaarli-pro/` dans le répertoire `tpl/` de votre instance Shaarli, à côté du dossier `default/` :

```bash
# Via Docker
docker cp "./shaarli-pro" shaarli_bookmarks:/var/www/shaarli/tpl/

# Ou manuellement
cp -r shaarli-pro/ /path/to/shaarli/tpl/
```

### 4. Permissions

```bash
# Docker
docker exec -it shaarli_bookmarks chown -R nginx:nginx /var/www/shaarli/tpl/shaarli-pro

# Manuel
chown -R www-data:www-data /path/to/shaarli/tpl/shaarli-pro/
```

---

## Activation

### Via l'interface (recommandé)

1. Connectez-vous à Shaarli en tant qu'administrateur.
2. Ouvrez **Tools > Configure your Shaarli**.
3. Choisissez **Professional (shaarli-pro)** dans la liste des thèmes.
4. Sauvegardez, puis rafraîchissez la page d'accueil.

### Activation manuelle (Shaarli < 0.9)

Modifiez `data/config.json.php` :

```json
{
  "resource": {
    "theme": "shaarli-pro"
  }
}
```

Ou via Docker :

```bash
docker exec -it myshaarli sed -i 's/"theme": "default"/"theme": "shaarli-pro"/' /var/www/shaarli/data/config.json.php
```

Redémarrez PHP si nécessaire et videz le cache navigateur.

### Notes importantes

- Le dossier `dist/` (assets minifiés) est versionné. Si vous clonez/pull le dépôt tel quel, le thème fonctionne immédiatement sans Node.js.
- Si vous modifiez `css/` ou `js/`, vous devez relancer le build et committer le nouveau `dist/` :

  ```bash
  cd shaarli-pro
  npm install
  npm run build
  git add dist/
  git commit -m "rebuild assets"
  ```

---

## Configuration & Personnalisation

### Palette et Typographies

Modifiez les variables CSS dans `shaarli-pro/css/style.css` section `:root` et `[data-theme="dark"]`, ou surchargez-les proprement via `data/user.css` :

```css
/* data/user.css */
:root {
    --primary: #8b5cf6;        /* Violet au lieu de bleu */
    --primary-hover: #7c3aed;
    --bg-body: #fafaf9;
}
```

### Comportements JavaScript

Adaptez `shaarli-pro/js/script.js` pour personnaliser :
- Le mode de recherche par défaut (tags vs texte)
- Les extensions audio reconnues par le lecteur
- Le comportement des filtres

### Templates additionnels

Créez un fichier `tpl/shaarli-pro/extra.html` pour injecter du CSS/JS supplémentaire — il sera automatiquement inclus s'il existe.

---

## Structure du Projet

```
shaarli-pro/
├── css/
│   ├── style.css          # Styles principaux + variables CSS (light/dark)
│   ├── themes.css         # 16 palettes de couleurs
│   ├── custom_views.css   # Styles des vues Notes / Todos / Archive
│   └── awesomplete.css    # Autocomplete des tags
├── js/
│   ├── script.js          # Thème, recherche, filtres, multi-sélection, lecteur média
│   ├── custom_views.js    # Vues Notes, Todos, Archive, Background Studio, Color Picker
│   ├── i18n.js            # Système d'internationalisation côté client
│   ├── shaarit-rules.js   # Détection notes/todos/pins et règles métier ShaarIt
│   ├── modules/           # Modules JS thématiques (theme, search, navigation, bulk-actions, a11y)
│   ├── awesomplete.min.js # Autocomplete des tags
│   ├── metadata.min.js    # Récupération asynchrone des métadonnées de lien
│   ├── backgrounds-manifest.js   # Manifest des fonds d'écran notes
│   └── backgrounds-manifest.json # Données des fonds d'écran
├── dist/                  # Assets minifiés générés par le build (CSS + JS)
├── img/
│   ├── favicon.png
│   ├── note-bg-light/     # Fonds d'écran clairs pour les notes
│   └── note-bg-dark/      # Fonds d'écran sombres pour les notes
├── theme_info.php         # Métadonnées du thème
├── manifest.json          # Manifest PWA
├── service-worker.js      # Service Worker pour le cache offline
├── package.json           # Dépendances et scripts de build
├── build.js               # Pipeline de minification CSS/JS
├── includes.html          # Head commun (meta, CSS, JS, config Shaarli)
├── page.header.html       # Sidebar + Header + Search overlay + Filtres
├── page.footer.html       # Footer + Bulk actions bar + Media player
├── linklist.html          # Page principale des bookmarks
├── linklist.paging.html   # Composant de pagination
├── daily.html             # Vue quotidienne / hebdomadaire / mensuelle
├── dailyrss.html          # Template RSS quotidien
├── editlink.html          # Formulaire d'ajout/édition de bookmark
├── editlink.batch.html    # Édition par lot
├── picwall.html           # Mur d'images avec contrôle de taille
├── tag.cloud.html         # Nuage de tags avec filtre alphabétique
├── tag.list.html          # Liste de tags avec recherche dynamique
├── tag.sort.html          # Navigation entre vues tag
├── tools.html             # Page d'administration + gestion des thèmes et tags cachés
├── hidden-tags.html       # Gestion des tags système cachés
├── player.html            # Lecteur média popup (template autonome)
├── pluginscontent.html    # Zone de contenu injectée par les plugins
├── install.html           # Page d'installation Shaarli
├── loginform.html         # Formulaire de connexion
├── configure.html         # Page de configuration
├── changepassword.html    # Changement de mot de passe
├── changetag.html         # Gestion des tags
├── pluginsadmin.html      # Administration des plugins
├── server.html            # Informations serveur
├── server.requirements.html # Prérequis serveur
├── import.html            # Import de bookmarks
├── export.html            # Export de bookmarks
├── export.bookmarks.html  # Template d'export Netscape
├── addlink.html           # Ajout rapide de lien
├── thumbnails.html        # Synchronisation des miniatures
├── opensearch.html        # Descripteur OpenSearch
├── feed.rss.html          # Template de flux RSS
├── feed.atom.html         # Template de flux Atom
├── 404.html               # Page d'erreur 404
├── error.html             # Page d'erreur générique
└── page.html              # Page wrapper
```

---

## Raccourcis Clavier

| Touche | Action |
|--------|--------|
| `S` | Ouvrir la recherche Spotlight |
| `ESC` | Fermer la recherche / les filtres / les modales |
| `↑` / `↓` | Naviguer dans les résultats de recherche |
| `Enter` | Sélectionner le résultat courant |

---

## Mise à Jour

1. Sauvegardez vos personnalisations (`data/user.css`, `extra.html`).
2. Remplacez le dossier `tpl/shaarli-pro/` par la nouvelle version.
3. Purgez les caches navigateur et OPcache.
4. Vérifiez le bon fonctionnement de vos plugins.

---

## Support

- Ouvrez une issue en joignant captures d'écran et logs.
- Indiquez vos versions : Shaarli, PHP, thème et plugins activés.

---

Bon partage de liens ! 🔖