@zevra/support-widget 0.2.0

package/src/zone.ts

@@ -0,0 +1,284 @@
+// ============================================================================
+// Le choix d'une zone à capturer.
+// ============================================================================
+//
+// Capturer la page entière répond à « voilà mon écran » ; choisir une zone
+// répond à « voilà LE bouton qui ne réagit pas ». La seconde question est
+// celle qu'on pose quand on signale, et c'est aussi celle qui produit une
+// image qu'on peut lire dans un ticket sans zoomer.
+//
+// Ce module fait deux choses, séparées exprès :
+//
+//   • la GÉOMÉTRIE (`rectangleEntre`, `zoneDansImage`) est pure et testée ;
+//     c'est là que vivent les bugs de recadrage, pas dans le voile ;
+//   • le VOILE (`choisirZone`) touche au document, ne calcule rien, et rend
+//     toujours la main — y compris quand la personne renonce.
+//
+// ⚠️ LES COORDONNÉES SONT CELLES DE LA FENÊTRE, en pixels CSS, comme
+// `getBoundingClientRect`. Elles ne sont PAS celles de l'image capturée : une
+// page défilée, un écran à forte densité et un élément qui déborde donnent
+// trois facteurs d'écart différents. La conversion se fait en un seul endroit,
+// `zoneDansImage`, et jamais à la main dans un composant.
+
+export interface Point {
+  x: number
+  y: number
+}
+
+export interface Rectangle {
+  x: number
+  y: number
+  largeur: number
+  hauteur: number
+}
+
+/**
+ * En deçà, c'est un clic, pas un tracé.
+ *
+ * ⚠️ Sans ce seuil, un simple clic sur le voile rendrait un rectangle de zéro
+ * pixel : la capture partirait, vide, et personne ne comprendrait pourquoi la
+ * pièce jointe est une image blanche de 1 pixel.
+ */
+export const COTE_MINIMAL = 8
+
+/** Le rectangle entre deux points, quel que soit le sens du tracé. PUR. */
+export function rectangleEntre(depart: Point, arrivee: Point): Rectangle {
+  const x = Math.min(depart.x, arrivee.x)
+  const y = Math.min(depart.y, arrivee.y)
+  return {
+    x,
+    y,
+    largeur: Math.abs(arrivee.x - depart.x),
+    hauteur: Math.abs(arrivee.y - depart.y),
+  }
+}
+
+/** Assez grand pour valoir une capture ? PUR. */
+export function zoneExploitable(zone: Rectangle): boolean {
+  return zone.largeur >= COTE_MINIMAL && zone.hauteur >= COTE_MINIMAL
+}
+
+export interface EntreeZoneDansImage {
+  /** Le tracé, en coordonnées de FENÊTRE. */
+  zone: Rectangle
+  /** `getBoundingClientRect()` de l'élément capturé — donc fenêtre aussi. */
+  cadre: Point
+  /** Les dimensions réelles de l'image rendue par la capture. */
+  imageLargeur: number
+  imageHauteur: number
+  /** Les dimensions en pixels CSS de l'élément capturé. */
+  elementLargeur: number
+  elementHauteur: number
+}
+
+/**
+ * Traduit un tracé de fenêtre en rectangle de l'image capturée. PUR.
+ *
+ * Trois écarts à absorber, et c'est pour ça que cette fonction existe :
+ *
+ *   1. l'élément capturé n'est pas à l'origine de la fenêtre — il est défilé,
+ *      ou décalé. `cadre` porte ce décalage, négatif quand on a défilé ;
+ *   2. l'image n'a pas la taille de l'élément — la bibliothèque de capture
+ *      applique son propre facteur ;
+ *   3. le tracé peut déborder de l'élément, quand on glisse jusqu'au bord.
+ *
+ * ⚠️ RENDRE `null` PLUTÔT QU'UN RECTANGLE VIDE. Un tracé entièrement hors de
+ * l'élément (on a visé une barre fixe qui n'est pas dans la capture) donnerait
+ * après bornage une largeur de zéro, et un canevas de zéro pixel jette dans
+ * certains navigateurs et rend une image noire dans d'autres. Le `null` est
+ * rattrapé plus haut par un message, pas par une image fausse.
+ */
+export function zoneDansImage(entree: EntreeZoneDansImage): Rectangle | null {
+  const { zone, cadre, imageLargeur, imageHauteur, elementLargeur, elementHauteur } = entree
+  if (!(imageLargeur > 0) || !(imageHauteur > 0)) return null
+  if (!(elementLargeur > 0) || !(elementHauteur > 0)) return null
+
+  const facteurX = imageLargeur / elementLargeur
+  const facteurY = imageHauteur / elementHauteur
+
+  // Bornage sur les DEUX bords, et dans cet ordre : on calcule les extrémités
+  // avant de les ramener dans l'image, sinon une largeur bornée à partir d'une
+  // origine déjà bornée déborde encore.
+  const gauche = (zone.x - cadre.x) * facteurX
+  const haut = (zone.y - cadre.y) * facteurY
+  const droite = gauche + zone.largeur * facteurX
+  const bas = haut + zone.hauteur * facteurY
+
+  const x = Math.max(0, Math.min(gauche, imageLargeur))
+  const y = Math.max(0, Math.min(haut, imageHauteur))
+  const x2 = Math.max(0, Math.min(droite, imageLargeur))
+  const y2 = Math.max(0, Math.min(bas, imageHauteur))
+
+  const largeur = Math.round(x2 - x)
+  const hauteur = Math.round(y2 - y)
+  if (largeur < 1 || hauteur < 1) return null
+
+  return { x: Math.round(x), y: Math.round(y), largeur, hauteur }
+}
+
+// ----------------------------------------------------------------------------
+// Le voile de sélection — IMPUR
+// ----------------------------------------------------------------------------
+
+/**
+ * Ce que le widget montre pendant qu'on trace.
+ *
+ * ⚠️ Écrit en DOM natif et non en React, volontairement. Ce voile doit
+ * recouvrir la page de l'hôte pendant que le tiroir est caché : le faire
+ * rendre par React obligerait à remonter l'état jusqu'au composant racine, à
+ * le redescendre dans l'onglet, et à garder les deux synchronisés pour une
+ * surface qui n'existe que le temps d'un glissement. Ici, tout ce qui est créé
+ * est détruit par `nettoyer`, dans le même fichier, à la ligne près.
+ */
+/**
+ * Les classes du voile, nommées ici et nulle part ailleurs.
+ *
+ * ⚠️ ELLES NE DOIVENT RIEN PARTAGER AVEC LES CHAMPS DU FORMULAIRE. La première
+ * version employait `zvs-zone`, qui désigne depuis toujours la zone de texte
+ * du signalement : la règle du voile, posée plus bas dans la même feuille, a
+ * rendu le champ `position: fixed; inset: 0` — un écran blanc au premier clic,
+ * sans aucune erreur en console. C'est `tests/styles.test.ts` qui tient
+ * désormais la règle.
+ */
+export const CLASSES_SELECTION = [
+  'zvs-selection',
+  'zvs-selection__voile',
+  'zvs-selection__consigne',
+  'zvs-selection__trace',
+] as const
+
+interface Attelage {
+  voile: HTMLElement
+  trace: HTMLElement
+  nettoyer: () => void
+}
+
+/**
+ * Cache le widget pendant le tracé, et rend de quoi le rétablir.
+ *
+ * ⚠️ `visibility` et non `display` : `display: none` démonte la mise en page
+ * du tiroir, et React, en le remontant, repart d'un formulaire vide. On perdrait
+ * la saisie en cours au moment précis où on va la compléter d'une image.
+ */
+function masquerLeWidget(doc: Document): () => void {
+  const masques = [...doc.querySelectorAll<HTMLElement>('.zvs-racine')]
+  const avant = masques.map((noeud) => noeud.style.visibility)
+  for (const noeud of masques) noeud.style.visibility = 'hidden'
+  return () => {
+    masques.forEach((noeud, index) => {
+      noeud.style.visibility = avant[index] ?? ''
+    })
+  }
+}
+
+function poserLAttelage(doc: Document, surEchap: () => void): Attelage {
+  const voile = doc.createElement('div')
+  voile.className = CLASSES_SELECTION[0]
+  voile.setAttribute('role', 'presentation')
+
+  const voileSombre = doc.createElement('div')
+  voileSombre.className = CLASSES_SELECTION[1]
+
+  const consigne = doc.createElement('p')
+  consigne.className = CLASSES_SELECTION[2]
+  consigne.textContent = 'Tracez la zone à capturer — Échap pour annuler'
+
+  const trace = doc.createElement('div')
+  trace.className = CLASSES_SELECTION[3]
+  trace.hidden = true
+
+  voile.append(voileSombre, consigne, trace)
+  doc.body.appendChild(voile)
+
+  const auClavier = (evenement: KeyboardEvent) => {
+    if (evenement.key === 'Escape') {
+      evenement.preventDefault()
+      surEchap()
+    }
+  }
+  doc.addEventListener('keydown', auClavier, true)
+
+  return {
+    voile,
+    trace,
+    nettoyer: () => {
+      doc.removeEventListener('keydown', auClavier, true)
+      voile.remove()
+    },
+  }
+}
+
+function dessiner(trace: HTMLElement, zone: Rectangle): void {
+  trace.hidden = false
+  trace.style.left = `${zone.x}px`
+  trace.style.top = `${zone.y}px`
+  trace.style.width = `${zone.largeur}px`
+  trace.style.height = `${zone.hauteur}px`
+}
+
+/**
+ * Laisse tracer une zone. Rend `null` si on renonce.
+ *
+ * NE JETTE JAMAIS, et rend toujours la main : le voile est retiré et le widget
+ * rétabli dans tous les chemins de sortie — tracé validé, Échap, tracé trop
+ * petit, pointeur annulé par le système. Un voile qui survivrait à une
+ * exception laisserait l'app hôte inutilisable, avec une surface invisible
+ * par-dessus tout, et rien à cliquer pour s'en sortir.
+ */
+export function choisirZone(doc?: Document | null): Promise<Rectangle | null> {
+  const document_ = doc ?? (typeof document === 'undefined' ? null : document)
+  if (!document_ || !document_.body) return Promise.resolve(null)
+
+  return new Promise<Rectangle | null>((resoudre) => {
+    const retablir = masquerLeWidget(document_)
+    let depart: Point | null = null
+    let zone: Rectangle | null = null
+    let fini = false
+
+    const finir = (resultat: Rectangle | null) => {
+      if (fini) return
+      fini = true
+      attelage.nettoyer()
+      document_.removeEventListener('pointermove', auMouvement, true)
+      document_.removeEventListener('pointerup', auRelachement, true)
+      document_.removeEventListener('pointercancel', auRenoncement, true)
+      retablir()
+      resoudre(resultat)
+    }
+
+    const auMouvement = (evenement: PointerEvent) => {
+      if (depart === null) return
+      zone = rectangleEntre(depart, { x: evenement.clientX, y: evenement.clientY })
+      dessiner(attelage.trace, zone)
+    }
+
+    const auRelachement = () => {
+      // Un tracé minuscule est un clic qui a ripé : on renonce plutôt que de
+      // joindre une image de huit pixels.
+      finir(zone !== null && zoneExploitable(zone) ? zone : null)
+    }
+
+    const auRenoncement = () => finir(null)
+
+    const attelage = poserLAttelage(document_, () => finir(null))
+
+    attelage.voile.addEventListener('pointerdown', (evenement: PointerEvent) => {
+      // Le bouton secondaire ouvre le menu du navigateur : le laisser
+      // commencer un tracé donnerait un rectangle qu'aucun relâchement ne
+      // vient fermer.
+      if (evenement.button !== 0) return
+      evenement.preventDefault()
+      depart = { x: evenement.clientX, y: evenement.clientY }
+      zone = null
+      attelage.trace.hidden = true
+    })
+
+    // Sur le DOCUMENT et en capture : le pointeur sort régulièrement du voile
+    // (une barre fixe de l'hôte par-dessus, le bord de la fenêtre), et des
+    // écouteurs posés sur le seul voile perdraient alors le relâchement — le
+    // tracé resterait collé au pointeur jusqu'à la fin des temps.
+    document_.addEventListener('pointermove', auMouvement, true)
+    document_.addEventListener('pointerup', auRelachement, true)
+    document_.addEventListener('pointercancel', auRenoncement, true)
+  })
+}