ADR 0045 – Aperçu d’un nœud au survol des liens

Statut : Accepté (2026-10-16, mode autonome)

Item 15 du jalon 3 (vague 2 du document d’idées) : survoler un lien wiki, ou une ligne du panneau de contexte, affiche le début du nœud et ses propriétés sans quitter la fiche, à la manière d’IntelliJ.

Contexte

Pour savoir ce qu’il y a derrière un [[lien]] ou une ligne « Rétroliens », il faut aujourd’hui ouvrir le nœud, puis revenir. Les liens apparaissent dans trois endroits :

• l’aperçu Markdown : <a href="/nodes/<id>" data-wiki-link="resolved"> ;
• l’éditeur Tiptap : un span[data-wiki-node] décoré, ouvert par Ctrl+clic ;
• le panneau de contexte : des routerLink vers /nodes/<id> (rétroliens, liens, sous-nœuds, vues contextuelles).

Le panneau de contexte fait partie de la coquille : tout ce qu’il importe pèse sur le bundle initial.

Décision

• Aucun nouvel endpoint : l’aperçu lit GET /api/nodes/{id}, déjà testé. Le résultat est gardé 30 secondes par nœud.

• Zones déclarées : une directive appNodePreviewZone sur le corps de la fiche (éditeur et aperçu) et sur le panneau de contexte. Elle écoute par délégation mouseover, mouseout, focusin et focusout, car les liens apparaissent après coup (rendu Markdown, décorations de l’éditeur). Un élément est une cible :

  • s’il porte data-preview-node="<id>" ;
  • ou si c’est un lien interne dont le chemin est exactement /nodes/<uuid>.

  Création, liens externes et autres pages n’ouvrent rien. L’arbre et les onglets ne sont pas des zones : on les parcourt trop vite.

• Éditeur : la décoration d’un lien résolu porte data-preview-node, et perd son infobulle native « Ctrl+clic pour ouvrir ». La carte reprend cette indication.

• Contenu de la carte, tiré des définitions et sans rien du domaine :

  • pastille, titre et libellé du type ;
  • propriétés : jusqu’à 6, prises dans les champs ui.listColumns de chaque aspect porté (sinon ui.order, sinon le schéma), dates en relatif, références par leur titre ;
  • les 280 premiers caractères du corps en texte brut ;
  • les tags.

• Comportement (WCAG 1.4.13) : un seul aperçu à la fois.

  • Il s’ouvre après 450 ms de survol, et tout de suite au focus clavier : le focus est intentionnel, et la description doit exister quand le lecteur d’écran annonce le lien.
  • Il reste ouvert tant que le pointeur est sur le lien ou sur la carte, ou que le focus est sur le lien. Il se ferme 200 ms après que ces trois conditions sont tombées.
  • Échap, un clic, une navigation ou la disparition du lien (liste re-rendue, bascule de l’éditeur, surveillée par un MutationObserver) le ferment tout de suite. Échap annule aussi une ouverture en attente.
  • Il n’y a pas d’aperçu au toucher.
  • La carte a role="tooltip". Le lien pointe vers elle par aria-describedby tant qu’elle est ouverte, en plus d’une description existante, rétablie à la fermeture.

• Placement : sous le lien dans la zone centrale. À sa gauche dans la moitié droite de l’écran, pour ne pas cacher les lignes voisines du panneau de contexte.

• Chargement : la carte et son modèle sont importés à la première ouverture. La coquille ne gagne que la directive et le service.

Alternatives écartées

• Endpoint d’aperçu dédié (titre, propriétés, extrait calculés côté serveur) : plus léger à transférer, mais il faudrait un contrat de plus, alors que la fiche complète est petite et souvent déjà demandée.
• Rendre l’extrait en Markdown : il faudrait marked dans la coquille ou un second chargement. Un texte brut de quelques lignes suffit pour reconnaître le nœud.
• Aperçu partout (arbre, onglets, tables) : trop de cartes en parcourant une liste. On pourra étendre les zones plus tard en posant la directive.

Conséquences

• Une modification faite ailleurs apparaît dans l’aperçu au plus 30 secondes plus tard. Les entrées expirées du cache sont purgées à chaque lecture.
• Au toucher, un lien wiki résolu de l’éditeur n’a plus d’infobulle « Ctrl+clic pour ouvrir » (ni d’aperçu) : l’indication passe dans la carte, avec ⌘ sur macOS.
• Toute nouvelle liste de liens vers des nœuds obtient l’aperçu en posant appNodePreviewZone sur son conteneur.