From e45ae315e5a0bd20b1a41da09c02a5690d6d47c3 Mon Sep 17 00:00:00 2001
From: "Baptiste.z" <zellerbaptiste@gmail.com>
Date: Tue, 20 Jun 2023 11:21:13 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20doc(core):=20ajoute=20des=20exem?=
 =?UTF-8?q?ples=20liens=20bruts=20et=20resets=20[DS-2825]=20(#613)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Par défaut, le dsfr stylise les liens natifs, ce qui peut poser problème dans l'utilisation de librairie tierce.
2 classes utilitaires sont mise à disposition pour contrecarrer le style fort du lien :
- `.fr-raw-link` retire toute stylisation sur les liens natifs
- `.fr-reset-link` remet le soulignement natif du navigateur (`text-decoration: underline;`)
Des pages d'exemples en illustrant l'utilisation ont été ajoutées dans les pages d'exemples des fondamentaux.
---
 src/core/.package.yml                      |  8 ++--
 src/core/example/link/index.ejs            |  0
 src/core/example/link/link-raw/index.ejs   | 15 +++++++
 src/core/example/link/link-reset/index.ejs | 15 +++++++
 src/core/example/link/sample/blocks.ejs    | 10 +++++
 src/core/example/link/sample/library.ejs   | 48 ++++++++++++++++++++++
 src/core/example/reset/index.ejs           |  4 --
 src/core/i18n/fr.yml                       |  3 ++
 src/core/style/action/legacy/_link.scss    | 15 ++++---
 src/core/style/action/module/_link.scss    | 19 +++++++--
 src/core/style/action/tool/_link.scss      |  2 +-
 11 files changed, 121 insertions(+), 18 deletions(-)
 create mode 100644 src/core/example/link/index.ejs
 create mode 100644 src/core/example/link/link-raw/index.ejs
 create mode 100644 src/core/example/link/link-reset/index.ejs
 create mode 100644 src/core/example/link/sample/blocks.ejs
 create mode 100644 src/core/example/link/sample/library.ejs

diff --git a/src/core/.package.yml b/src/core/.package.yml
index 4f8666d3f..42e22e862 100644
--- a/src/core/.package.yml
+++ b/src/core/.package.yml
@@ -39,11 +39,13 @@ script:
   - legacy
 example:
   style:
-    - core
+    - accordion
     - button
+    - core
     - table
-    - accordion
+    - toggle
   script:
-    - core
     - accordion
+    - core
     - table
+    - toggle
diff --git a/src/core/example/link/index.ejs b/src/core/example/link/index.ejs
new file mode 100644
index 000000000..e69de29bb
diff --git a/src/core/example/link/link-raw/index.ejs b/src/core/example/link/link-raw/index.ejs
new file mode 100644
index 000000000..b04618cdb
--- /dev/null
+++ b/src/core/example/link/link-raw/index.ejs
@@ -0,0 +1,15 @@
+<% const sample = getSample(include); %>
+<% const rawSubtitle = `Utilisation de la classe <code>${prefix}-raw-link</code> sur les balises de lien pour les afficher de manière brut.` %>
+<% const rawWrapperSubtitle = `Utilisation de la classe <code>${prefix}-raw-link</code> sur un wrapper pour afficher les liens de manière brut.` %>
+
+<div class="<%= prefix %>-container" >
+  <%- section('Liens bruts', null, 0) %>
+  
+  <%- sample({ title: 'Lien brut', subtitle: rawSubtitle }, '../../reset/sample/paragraph', { paragraph: {insert: `<a class="${prefix}-raw-link" title="titre lien" href="../">lien interne</a>`} }, true); %>
+
+  <%- sample({ title: 'Lien externe brut', subtitle: rawSubtitle }, '../../reset/sample/paragraph', { paragraph: {insert: `<a class="${prefix}-raw-link" title="titre lien externe - nouvelle fenêtre" href="https://www.systeme-de-design.gouv.fr/" target="_blank" rel="noopener">lien externe - nouvelle fenêtre</a>`} }, true); %>
+
+  <%- sample( { title: 'Exemple sur plusieurs blocs de texte', subtitle: rawWrapperSubtitle}, '../sample/blocks', { classes: [`${prefix}-raw-link`], paragraphes: [ {insert: `<a title="titre lien" href="../">lien interne</a>`}, {insert: `<a title="titre lien externe - nouvelle fenêtre" href="https://www.systeme-de-design.gouv.fr/" target="_blank" rel="noopener">lien externe - nouvelle fenêtre</a>`}] }, true); %>
+
+  <%- sample({ title: 'Exemple d\'utilisation avec une librairie externe', subtitle: rawWrapperSubtitle }, '../sample/library', { classes: [`${prefix}-raw-link`] }, true); %>
+</div>
diff --git a/src/core/example/link/link-reset/index.ejs b/src/core/example/link/link-reset/index.ejs
new file mode 100644
index 000000000..10cc8613c
--- /dev/null
+++ b/src/core/example/link/link-reset/index.ejs
@@ -0,0 +1,15 @@
+<% const sample = getSample(include); %>
+<% const resetSubtitle = `Utilisation de la classe <code>${prefix}-reset-link</code> sur les balises de lien pour réinitialiser le style des liens.` %>
+<% const resetWrapperSubtitle = `Utilisation de la classe <code>${prefix}-reset-link</code> sur un wrapper pour afficher les liens de manière brut.` %>
+
+<div class="<%= prefix %>-container" >
+  <%- section('Liens réinitialisés', `Utilisation de la classe <code>${prefix}-reset-link</code> pour réinitialiser le style des liens.`, 0) %>
+
+  <%- sample({ title: 'Lien réinitialisé', subtitle: resetSubtitle }, '../../reset/sample/paragraph', { paragraph: {insert: `<a class="${prefix}-reset-link" title="titre lien" href="../">lien interne</a>`} }, true); %>
+
+  <%- sample({ title: 'Lien externe réinitialisé', subtitle: resetSubtitle }, '../../reset/sample/paragraph', { paragraph: {insert: `<a class="${prefix}-reset-link" title="titre lien externe - nouvelle fenêtre" href="https://www.systeme-de-design.gouv.fr/" target="_blank" rel="noopener">lien externe - nouvelle fenêtre</a>`} }, true); %>
+
+  <%- sample( { title: 'Exemple sur plusieurs blocs de texte', subtitle: `Utilisation de la classe <code>${prefix}-reset-link</code> sur un wrapper pour réinitialiser le style des liens.`}, '../sample/blocks', { classes: [`${prefix}-reset-link`], paragraphes: [ {insert: `<a title="titre lien" href="../">lien interne</a>`}, {insert: `<a title="titre lien externe - nouvelle fenêtre" href="https://www.systeme-de-design.gouv.fr/" target="_blank" rel="noopener">lien externe - nouvelle fenêtre</a>`}] }, true); %>
+
+  <%- sample({ title: 'Exemple d\'utilisation avec une librairie externe', subtitle: resetWrapperSubtitle }, '../sample/library', { classes: [`${prefix}-reset-link`] }, true); %>
+</div>
diff --git a/src/core/example/link/sample/blocks.ejs b/src/core/example/link/sample/blocks.ejs
new file mode 100644
index 000000000..8afb969a2
--- /dev/null
+++ b/src/core/example/link/sample/blocks.ejs
@@ -0,0 +1,10 @@
+<%
+ let classes = locals.classes || [];
+ let paragraphes = locals.paragraphes || [];
+ %>
+
+<div <%- includeClasses(classes); %>>
+  <% for (const paragraph of paragraphes) { %>
+    <%- include('../../../template/ejs/typography/paragraph', {paragraph: { ...paragraph, content: lorem(paragraph.insert) }}); %>
+  <% } %>
+</div>
diff --git a/src/core/example/link/sample/library.ejs b/src/core/example/link/sample/library.ejs
new file mode 100644
index 000000000..09f5f58dd
--- /dev/null
+++ b/src/core/example/link/sample/library.ejs
@@ -0,0 +1,48 @@
+<% const sample = getSample(include); %>
+
+<!-- Based on Leaflet Quick Start Guide [https://leafletjs.com/examples/quick-start/]  -->
+<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=" crossorigin=""/>
+<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js" integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin=""></script>
+
+<%
+ let classes = locals.classes || [];
+%>
+
+
+<div <%- includeClasses(classes); %>>
+  <div id="map" class="map"></div>
+
+  <%- include('../../../../component/toggle/template/ejs/toggle.ejs', {toggle: {state: true, checked: true, label: `Interupteur de la classe <code class="${prefix}-px-1w">${classes[0]}</code>sur le wrapper`, id: classes[0]}}); %>
+</div>
+
+<style>
+  .map { height: 400px; }
+</style>
+
+<script>
+  const map = L.map('map', {
+    center: [48.8588897, 2.320041],
+    zoom: 13
+  });
+  const linkClass = '<%- classes[0] %>';
+
+  L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
+    maxZoom: 19,
+    attribution: '&copy; <a href="http://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a>'
+  }).addTo(map);
+
+  L.marker([48.8588897, 2.320041]).addTo(map)
+    .bindPopup('20 avenue de Ségur 75007 Paris')
+    .openPopup();
+
+  const toggle = document.getElementById(linkClass);
+  const wrapper = document.getElementById('map').parentNode;
+
+  toggle.addEventListener('change', function() {
+    if (this.checked) {
+      wrapper.classList.add(linkClass);
+    } else {
+      wrapper.classList.remove(linkClass);
+    }
+  });
+</script>
diff --git a/src/core/example/reset/index.ejs b/src/core/example/reset/index.ejs
index fe3a935a8..9e3b8c24e 100644
--- a/src/core/example/reset/index.ejs
+++ b/src/core/example/reset/index.ejs
@@ -26,10 +26,6 @@ let ol = {
 
 <%- sample('Test de paragraphe et de lien externe :', './sample/paragraph', { paragraph: {insert: '<a title="titre lien externe - nouvelle fenêtre" href="#" target="_blank" rel="noopener">lien externe - nouvelle fenêtre</a>'} }, true); %>
 
-<%- sample('Test de lien externe raw-link :', './sample/paragraph', { paragraph: {insert: `<a class="${prefix}-raw-link" title="titre lien externe - nouvelle fenêtre" href="#" target="_blank" rel="noopener">lien externe - nouvelle fenêtre</a>`} }, true); %>
-
-<%- sample('Test de lien externe reset-link :', './sample/paragraph', { paragraph: {insert: `<a class="${prefix}-reset-link" title="titre lien externe - nouvelle fenêtre" href="#" target="_blank" rel="noopener">lien externe - nouvelle fenêtre</a>`} }, true); %>
-
 <%- sample('Test de liste non-ordonnée:', './sample/ul', {list:ul}, true); %>
 
 <%- sample('Test de liste ordonnée :', './sample/ol', {list:ol}, true); %>
diff --git a/src/core/i18n/fr.yml b/src/core/i18n/fr.yml
index 0dbf408b1..00f8cd907 100644
--- a/src/core/i18n/fr.yml
+++ b/src/core/i18n/fr.yml
@@ -11,3 +11,6 @@ subdir:
   spacing: Espacements
   typography: Typographie
   utility: Utilitaires
+  link: Liens natifs
+  link-raw: Liens bruts
+  link-reset: Liens réinitialisés
diff --git a/src/core/style/action/legacy/_link.scss b/src/core/style/action/legacy/_link.scss
index 71d8a7241..c2ee8af91 100644
--- a/src/core/style/action/legacy/_link.scss
+++ b/src/core/style/action/legacy/_link.scss
@@ -8,15 +8,18 @@
 @include legacy.is(ie11) {
   [href],
   #{ns(reset-link)} {
-    text-decoration: underline;
+    &[href],
+    [href] {
+      text-decoration: underline;
+    }
   }
 
   #{ns(raw-link)} {
-    text-decoration: none;
-  }
-
-  #{ns(reset-link)} {
-    @include after(none);
+    &[href],
+    [href] {
+      text-decoration: none;
+      @include after(none);
+    }
   }
 
   [target="_blank"] {
diff --git a/src/core/style/action/module/_link.scss b/src/core/style/action/module/_link.scss
index 5cd784e83..438142f6b 100644
--- a/src/core/style/action/module/_link.scss
+++ b/src/core/style/action/module/_link.scss
@@ -11,6 +11,7 @@ a {
   @include init-underline;
   @include enable-underline;
   @include enable-external;
+  --text-decoration: none;
 }
 
 // TODO: à checker avec <area href="" >
@@ -33,11 +34,21 @@ form {
 }
 
 #{ns(raw-link)} {
-  @include disable-underline;
+  --text-decoration: none;
+  
+  &[href],
+  [href] {
+    @include disable-underline;
+    @include disable-external;
+  }
 }
 
 #{ns(reset-link)} {
-  @include disable-underline;
-  text-decoration: underline;
-  text-underline-offset: 2px;
+  --text-decoration: underline;
+
+  &[href],
+  [href] {
+    @include disable-underline;
+    text-underline-offset: 2px;
+  }
 }
diff --git a/src/core/style/action/tool/_link.scss b/src/core/style/action/tool/_link.scss
index 7fc39c406..3a47a213a 100644
--- a/src/core/style/action/tool/_link.scss
+++ b/src/core/style/action/tool/_link.scss
@@ -6,7 +6,7 @@
 $underline-thickness: 0.0625em;
 
 @mixin a-reset ($minimal: false) {
-  text-decoration: none;
+  text-decoration: var(--text-decoration);
   @if not $minimal {
     color: inherit;
   }