=== HKC Blocks ===
Contributors: hkabla
Plugin URI: https://plugins.hervekabla.com/
Tags: blocks, search, fuzzy, related posts, index
Requires at least: 6.1
Tested up to: 6.6
Requires PHP: 7.2
Stable tag: 1.16.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Collection de blocs maison : recherche floue, articles similaires, index alphabétique.

== Description ==

**Bloc « Recherche floue »**

Un champ de recherche qui pardonne les fautes de frappe. Le visiteur valide, et arrive sur
la page de résultats habituelle du thème — dont le classement a été remplacé :

1. **les correspondances exactes d'abord**, du plus grand nombre d'occurrences au plus
   petit, puis de la plus récente à la plus ancienne ;
2. **les correspondances approchées ensuite**, de la plus proche à la plus lointaine.

La proximité est mesurée par la distance de Damerau-Levenshtein, qui compte l'inversion de
deux lettres voisines comme une seule faute : pour la saisie « kabal », « kabla » (une
inversion, même longueur) passe devant « kabbal » (une insertion, une lettre de plus).

La recherche porte sur le titre, l'extrait et le contenu complet des articles et des pages.

Réglages du bloc, dans la colonne de droite de l'éditeur :

* le texte indicatif du champ et le libellé du bouton ;
* la **tolérance aux fautes** : stricte, normale ou large.

Aucun JavaScript côté visiteur : le formulaire est un simple formulaire GET et tout le
classement est calculé en PHP. Le bloc est écrit sans étape de compilation.

**Bloc « Articles similaires »**

À poser sous un billet : il affiche les billets les plus proches, mesurés sur le contenu
lui-même — sans dépendre des catégories ni des mots-clés, souvent inégalement tenus sur un
blog ancien.

Le principe : les mots caractéristiques du billet courant sont extraits (les plus fréquents,
mots vides écartés), les billets qui les contiennent sont notés, et les mieux notés sortent.
Un mot du titre pèse quatre fois un mot du corps, un billet fleuve est amorti pour ne pas
gagner par sa seule longueur, et deux mots partagés valent mieux qu'un seul répété.

Réglages : titre de la rubrique, nombre de billets, vignette, date, extrait.

**Bloc « Index des termes »**

Les termes les plus employés du blog — 500 par défaut, réglable — paginés par lettre. Chaque terme
mène aux billets qui en parlent, et porte trois chiffres : le nombre d'occurrences, le
nombre d'articles où il apparaît, et la part des articles du blog que cela représente
(« 43 articles » sur 500 publiés donne 8,6 %).

Trois filtres successifs écartent ce qui n'a rien à faire dans un index :

* les mots vides (« le », « du », « dans »…) et les mots trop courts ;
* les formes verbales françaises, reconnues par une liste des verbes les plus employés et
  quelques terminaisons sans ambiguïté ;
* les variantes d'un même terme sont rassemblées, et c'est la forme de base qui s'affiche :
  singulier plutôt que pluriel (« réseau » et non « réseaux »), masculin plutôt que féminin,
  nom plutôt qu'adjectif dérivé (« président » pour « présidentiel », « Paris » pour
  « parisienne », « nombreux » pour « nombreuses ») ;
* les noms propres gardent leur majuscule (« Macron »), tandis qu'un mot ordinaire commençant
  une phrase retrouve sa minuscule ;
* les expressions sont indexées : binômes (« Emmanuel Macron », « réseau social ») et
  groupes de trois mots reliés par un mot outil (« agence de communication », « empire du
  milieu »). Elles remplacent les mots qui ne s'emploient presque jamais seuls — « Emmanuel »
  s'efface, « Macron » reste ;
* les locutions élidées sont jugées entières : « d'abord » et « aujourd'hui » sont écartés,
  tandis que « l'entreprise » est bien compris comme le terme « entreprise » ;
* les locutions dont toutes les parties sont des mots outils : « est-ce », « peut-être »,
  « au-delà » — tandis que « porte-parole », « sous-traitance » ou « Jean-Luc » sont conservés ;
* les mots amputés par un défaut d'encodage dans d'anciens articles — « succ », « iphon » —
  sont rattachés à leur forme complète, qui reste celle affichée ;
* les termes présents dans une trop grande part des billets — c'est ainsi que disparaissent
  les mentions recopiées d'un billet à l'autre : signature, appel à l'abonnement, intitulés
  de rubriques. Le seuil est réglable (40 % par défaut).

Les menus, la colonne latérale et les gabarits du thème ne sont jamais lus : seul le contenu
des billets est parcouru.

Le calcul est fait une fois, rangé en base et rafraîchi chaque nuit. Réglages › HKC Blocks ›
Index des termes indique le nombre de termes retenus, le nombre d'articles parcourus, la date
et la durée du dernier calcul ; on y règle le nombre de termes — une seule valeur, qui vaut
pour le calcul comme pour l'affichage —, la longueur minimale d'un terme, le seuil de présence
et la liste des termes exclus. Modifier l'un de ces réglages relance le calcul.

**Historique des recherches**

Chaque recherche lancée depuis un bloc « Recherche floue » est consignée dans une table
dédiée : date, terme cherché, nombre de résultats, tolérance et adresse IP. L'onglet
« Historique des recherches » les affiche, avec le classement des termes les plus demandés —
et surtout ceux qui ne donnent aucun résultat, les plus instructifs.

Une adresse IP complète étant une donnée personnelle, une case permet de les anonymiser, la
durée de conservation est réglable (90 jours par défaut) et les entrées plus anciennes sont
supprimées chaque nuit.

**Insertion automatique (thèmes classiques)**

Les thèmes sans éditeur de modèles — Blocksy, GeneratePress, Astra, la plupart des thèmes
classiques — ne permettent pas de poser les blocs dans le modèle d'article. Réglages ›
HKC Blocks propose alors deux insertions automatiques, sans rien modifier dans le thème :

* **la barre de recherche floue**, avec trois positions — au-dessus du titre, sous le titre,
  sous le texte — et le choix des contextes : articles, pages, et tête de liste (accueil,
  résultats de recherche, archives). « Au-dessus du titre » est la seule position qui vaut
  aussi pour les listes ;
* **les articles similaires**, à la fin de chaque article, avec le titre de la rubrique, le
  nombre de billets et les éléments affichés.

Avec un thème à blocs, préférer le placement du bloc dans le modèle « Article unique » :
la position reste sous votre contrôle.

**Performances**

Les calculs des deux blocs sont mis en cache douze heures, et le cache est vidé dès qu'un
contenu est publié, modifié ou supprimé.

== Installation ==

1. Téléverser `hkc-blocks.zip` depuis Extensions › Ajouter › Téléverser une extension.
2. Activer l'extension.
3. Dans l'éditeur, ajouter le bloc « Recherche floue » (catégorie Widgets).

== Frequently Asked Questions ==

= Quels types de contenu sont explorés ? =

Les articles et les pages. Le filtre `hkc_fuzzy_search_post_types` permet d'en changer :

`add_filter( 'hkc_fuzzy_search_post_types', function ( $types ) {
	return array( 'post', 'page', 'livre' );
} );`

= La recherche du site est-elle modifiée partout ? =

Non. Le classement flou ne s'applique qu'aux recherches lancées depuis le bloc, reconnues à
un paramètre d'URL. Le formulaire de recherche du thème continue de fonctionner comme avant.

= Les articles similaires portent-ils sur d'autres types de contenu ? =

Par défaut sur les articles. Le filtre `hkc_related_posts_post_types` permet d'en changer.

= Comment ajuster la liste des mots vides ? =

Via le filtre `hkc_blocks_stopwords`, qui reçoit la liste par défaut (français et anglais).

= Comment ajouter un autre bloc à cette extension ? =

Créer un dossier `blocks/mon-bloc/` contenant `block.json`, `index.js` et `render.php` :
il est repéré et enregistré automatiquement, sans modifier le code de l'extension.

== Changelog ==

= 1.16.2 =
* Les mises à jour apparaissent dans l'heure qui suit leur mise en ligne, au lieu d'attendre jusqu'à une demi-journée : le manifeste du site éditeur n'est plus gardé que soixante minutes, la cadence à laquelle WordPress redemande de lui-même.

= 1.16.1 =
* Consultation sur téléphone : le tableau de l'historique des recherches défile horizontalement en gardant ses en-têtes.

= 1.16.0 =
* Mises à jour automatiques depuis plugins.hervekabla.com : les nouvelles versions apparaissent dans l'écran des extensions.

= 1.15.0 =
* Historique des recherches, dans une table dédiée : date, terme, résultats, tolérance et adresse IP, avec anonymisation possible et purge automatique.
* Désinstallation propre : table et options supprimées.

= 1.14.0 =
* Les réglages indiquent la répartition des termes (mots simples, binômes, expressions de trois mots) et le poids de l'index en base.
* Les expressions de trois mots exigent cinq occurrences, contre trois pour un binôme : elles sont bien plus nombreuses et la plupart ne sont que des rencontres de hasard.
* Nettoyage renforcé en mémoire au-delà de 200 000 expressions suivies.

= 1.13.0 =
* Les expressions de trois mots reliées par un mot outil sont indexées : « agence de communication », « empire du milieu ».
* Les locutions élidées sont reconnues entières : « d'abord » n'entre plus dans l'index sous la forme « abord ».
* Verbes complétés : laisser, garder, tenter, augmenter, participer et quelques autres.

= 1.12.1 =
* Index : les chiffres d'un terme tiennent sur la même ligne que lui, en gris — « abord, 579 occurrences, 377 articles, 6 % ».
* Index : l'en-tête indique la part de la lettre — « 54 termes en A sur 750 au total, soit 7,2 % ».

= 1.12.0 =
* Le singulier et la forme de base sont désormais préférés à l'affichage : « réseau », « président », « Paris ».
* Dérivations rassemblées : présidentiel/président, parisienne/Paris, nombreuses/nombreux.
* Les entités HTML sont décodées avant analyse : « nbsp » n'entre plus dans l'index.
* Mots outils écartés : jusqu'à, voici, voilà, tant, nombreux, grand, petit.
* Les chiffres d'un terme sont légèrement décalés, pour que le terme ressorte.

= 1.11.0 =
* Le nombre de termes devient un réglage unique, commun au calcul et à l'affichage : l'administration et le site ne peuvent plus se contredire.
* La durée du dernier calcul est indiquée dans les réglages.
* Modifier un réglage de l'index relance le calcul en tâche de fond.

= 1.10.0 =
* La forme retenue d'un groupe de variantes est désormais la plus employée, et non la plus courte : « iPhone » ne s'affiche plus « iPhon », ni « succès » « succ ».
* Les mots tronqués par un défaut d'encodage sont rattachés à leur forme complète.
* Les locutions faites de mots outils (« est-ce », « au-delà », « peut-être ») sont écartées, sans toucher aux mots composés porteurs de sens.
* Les séquences invalides des anciens articles sont nettoyées avant analyse.

= 1.9.1 =
* Index : le pourcentage indique la part des articles du blog où le terme apparaît, plus lisible que la part du vocabulaire.

= 1.9.0 =
* Index : chaque terme indique ses occurrences et le nombre d'articles où il apparaît.

= 1.8.1 =
* Correction d'une erreur fatale sur toutes les pages du site : une méthode de chargement des styles avait disparu lors de la réorganisation en onglets, alors que son branchement subsistait.
* L'index des termes n'est plus calculé pendant l'affichage d'une page : le calcul part en tâche de fond, et la page reste affichable pendant ce temps.
* Repli automatique si le plafond de présence écarte tous les termes.

= 1.8.0 =
* Page de réglages réorganisée en onglets, un par bloc. Chaque onglet possède son propre groupe de réglages : enregistrer l'un ne touche plus aux autres.

= 1.7.0 =
* Index : fusion du singulier et du pluriel, du masculin et du féminin.
* Index : majuscules des noms propres conservées, binômes indexés et remplacement des termes qui ne s'emploient pas seuls.
* Recherche : une correspondance exacte ne peut plus être évincée par la limite de candidats.
* Recherche : option pour remplacer le formulaire du thème par la version floue, notamment sur la page « aucun résultat ».

= 1.6.1 =
* Correction : la recherche restait exacte. WordPress retirait le paramètre de tolérance de l'URL lors de sa redirection canonique ; il est désormais déclaré et préservé.

= 1.6.0 =
* Le bloc « Index alphabétique » devient « Index des termes » : il liste les termes les plus employés du blog au lieu des titres de billets.
* Écarte les mots vides, les formes verbales françaises et les termes présents dans trop de billets.
* Pagination par lettre, liens vers les billets, réglages et reconstruction dans Réglages › HKC Blocks.

= 1.5.2 =
* Sur un article, la barre insérée au-dessus du titre s'aligne sur le conteneur du thème au lieu d'occuper toute la page (le thème y démarre la boucle avant son conteneur).

= 1.5.1 =
* Correction d'un affichage écrasé (champ et bouton empilés) introduit par la 1.5.0 : la marge intérieure reprenait une variable du thème qui désigne en réalité une largeur.

= 1.5.0 =
* Largeur ajustable à la main si besoin : `--hkc-auto-insert-width`.

= 1.4.2 =
* La barre insérée au-dessus du titre reste dans la colonne de contenu et ne déborde plus sur la barre latérale.

= 1.4.1 =
* Reprise des réglages enregistrés par la 1.3.0, et repli sur la position par défaut si la position enregistrée est inconnue.

= 1.4.0 =
* La barre de recherche peut se placer au-dessus du titre, et en tête des listes (accueil, résultats, archives).
* Choix des contextes d'affichage : articles, pages, listes.

= 1.3.0 =
* Insertion automatique de la barre de recherche floue sur chaque article, au-dessus ou sous le contenu.

= 1.2.0 =
* Insertion automatique des articles similaires sous chaque article, réglable dans Réglages › HKC Blocks, pour les thèmes sans éditeur de modèles.

= 1.1.0 =
* Bloc « Articles similaires » : proximité mesurée sur le contenu, sans catégories ni mots-clés.
* Bloc « Index alphabétique » : A-Z des billets, tri insensible aux accents et à l'article initial.
* Socle commun extrait (outils de texte, cache) et partagé par les trois blocs.

= 1.0.0 =
* Bloc « Recherche floue » et son moteur de classement.
* Registre de blocs : tout dossier de `blocks/` est enregistré automatiquement.
