Shaarli_bm_theme/README.md

Shaarli Professional Theme

Thème moderne et professionnel pour 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.

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 :

cd shaarli-pro
npm run test:e2e:install   # installer les navigateurs Playwright (une fois)

# Linux / macOS
SHAARLI_URL=http://localhost:8080 npm run test:e2e

# Windows (PowerShell)
$env: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

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

2. Supprimer le thème en place

# 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/ :

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

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

4. Permissions

# 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 :

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

Ou via Docker :

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/ :

  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 :

/* 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 ! 🔖