Possibilité d'avoir plusieurs ressources pour chaque {{ref}}

[YannisDelmas]

Hypothèse 1: Une liste déroulante à côté de la case de recherche, avec les différentes possibilités, mais ça fait du boulot pour référencer même les principales constructions. Hypothèse 2: Le survol du ⓘ occasionne un "pop-hover" un peu à la façon de VS code, ce qui permet de mettre une ou plusieurs ressources pour chaque construction, mais ne permet pas de gérer le niveau…

[enguerranws]

Reprise de la question en #8 :

Je peux proposer quelque chose pour cette fonctionnalité, mais ça implique de revoir la structure des données passées à cssSelectorExplain() :

cssSelectorExplain({
    ...
    references: { 
        id: { // un objet pour structurer les 
                    "Références" : [ // les clés utilisées sont les titres des sections, utilisées dans la vue
                       // Liste de liens sous forme de tableau
                        "https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity",
                        "https://www.w3.org/TR/CSS1/#cascading-order"
                    ],
                    "Problèmes connus": [
                        "https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity",
                    ]
                },
    },
});

Ça met en avant plusieurs questions :

• la clé de l'objet, si utilisée comme titre de section dans la vue, implique que cette donnée est déjà définie comme étant en français. Ça ne me semble pas déconnant : les explications elles-mêmes sont en français aussi. Si on veut rendre ces données prêtes à être exploitées quelque soit la langue, il faut passer par un système intermédiaire qui va mapper les propriétés de cet objet, vers un label défini dans un fichier de traductions.
• en l'état, on ne pourrait afficher qu'une liste de liens. Si on prend exemple sur CanIUse, les liens sont accompagnés d'un titre. Il pourrait être bon alors de modifier la liste de liens afin de passer sur une liste d'objets :

{
    url: "https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity",
    titre: "Doc MDN concernant la spécificité en CSS",
}

L'avantage de cette solution serait aussi de pouvoir, à l'avenir, rajouter des champs sans modifier le type de donnée.

Tu en penses quoi @YannisDelmas ?

[YannisDelmas]

Ça me va bien, sur le principe. Pour éviter la confusion avec la structure arborescente des références, j'éviterais peut-être d'ajouter un niveau d'objet. On pourrait utiliser un simple tableau. Ça donnerait ce qui suit. C'est moins structuré, mais pas bien compliqué à traiter. Pour les titres, on pourrait simplement remplacer l'URL par un tableau ou un objet, comme @enguerranws propose.

cssSelectorExplain({
    ...
    references: [
        // un tableau, pour éviter la confusion avec l'arborescence
        "Références", // les non-liens de simples textes (et font office de titres de section)
        "https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity", // simple lien
        ["Recommandation CSS1", "https://www.w3.org/TR/CSS1/#cascading-order"], // avec titre
        "Problèmes connus",
        "https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity",
        ],
    …
});

La principale question que je me pose est celle du rendu pour l'utilisateur. @enguerranws proposait d'utiliser Popper, qu'on pourrait compléter avec Tippy. C'est très souple. Ça m'irait bien.

[enguerranws]

La principale question que je me pose est celle du rendu pour l'utilisateur. @enguerranws proposait d'utiliser Popper, qu'on pourrait compléter avec Tippy. C'est très souple. Ça m'irait bien.

Oui, en partant là dessus, je pourrais te proposer quelque chose niveau interface : une base de travail qu'on pourra faire évoluer sur une branche dédiée.

C'est moins structuré, mais pas bien compliqué à traiter.

Personnellement, si c'est moins structuré, je ne vois pas trop le gain. Ça rajoute effectivement de la profondeur, mais la donnée est qualifiée, ce qui sera toujours utile. J'ai peur que passer de la donnée structurée dans un tableau (éventuellement à plusieurs dimensions) va poser plusieurs soucis à l'avenir (notamment si on veut plus tard filtrer cette donnée par section - pour récupérer tous les liens de toutes les références par exemple : c'est faisable, mais ça va pas être très élégant).

[YannisDelmas]

Je corrige ma proposition, j'avais oublié une partie de la structure. On ne toucherait pas à la superstructure:

cssSelectorExplain({
    module: 'css-selector',
    lang: 'fr',
    explanations: { … },
    references: {…},
    specificity: {…}
});

On garderait aussi la structure générale de l'arborescence references (par type, sous-type, etc.):

references: {
    ':type': 'type',
    selectors_group: …,
    descendant: …,
    pseudo_class: {
        ':type': 'name',
        ':default': …,
        link: …,
        visited: …,
    …},
…},

On ne modifierait que ce qui concerne le niveau d'explication d'une structure d'expression. Je propose qu'on reste quand même avec une structure de liste, pour éviter le problème de confusion entre un niveau dans l'aborescence (il n'y a pas de limite) et un niveau au sein des explications. Comme on n'a pas de typage pour ces objets, il faut être précautionneux pour les distinguer (on pourrait tester l'existence de la propriété :type, au besoin). Si on combine le fait d'avoir une liste et ton idée de structurer les références, on pourrait avoir ce qui suit (j'ai remis en anglais la structure de données, comme le reste). Tous les éléments: titre, références, sections etc. seraient facultatifs.

…   target: 'https://www.w3.org/TR/selectors-3/#target-pseudo', // cas simple : une réf.
    checked: [
        "titre éventuel",
        "https://www.w3.org/TR/selectors-3/#checked", // une réf seule
        {url: "https://developer.mozilla.or…", title: "MDN"}, // une réf. avec intitulé
        …suite de références sans section…
        [ // section n°1
        "titre de section", …suite de références comme ci-dessus…
    ], [    …section n°2…
    ]…suite des sections…
]

[enguerranws]

Ok, je crois que je vois le problème : la structure en objet peut interférer avec l'interprètation des options de conf de cssSelectorExplain()?

Dans ce cas, une nouvelle proposition, repartant de ton exemple :

checked: [ // on reste sur une liste (à une seule dimension), et on enlève les titres de section
                  // on normalise ces références en objets avec (pour le moment du moins) 3 propriétés (nommage à revoir probablement)
        {
                  titre: "", // optionnel, le titre de la référence
                  uri: "https://www.w3.org/TR/selectors-3/#checked", // le lien de la référence
                  section: "references", // la section concernée, via un système de clés connues
                },
                {
                  titre: "", // optionnel, le titre de la référence
                  uri: "https://www.w3.org/TR/selectors-3/#section", // le lien de la référence
                  section: "known-issues", // la section concernée, via un système de clés connues
                },
    ]

Il faudrait déclarer, ailleurs dans le projet, des sections pour les références, par exemple, pour la version FR :

const sectionRéférencesFR = [
  {
     "label": "Références", // la libellé, ici en FR
     "identifiant": "references" // le nom normalisé 
  },
  {
    "label": "Problèmes connus", // la libellé, ici en FR
    "identifiant": "known-issues" // le nom normalisé 
  }
];

Au final, ces blocs de références seraient créé en bouclant sur ces listes de section de références, et en récupérant, si elles existent les références correspondantes. Si une section ne trouve pas de références correspondantes, on ne rend pas la section de références.

Ça permettrait de garder une donnée structurée, "normalisée" et sans, je pense, risquer des problèmes liés à une structure de référence en objet, comme je l'ai proposé précédemment.

Ça implique un chouilla plus de boulot, mais qui sera toujours utile dans le cadre d'une version multilingue.

[YannisDelmas]

Ça me convient bien, comme proposition. Validons ce que tu proposes pour le cssSelectorExplain().

Pour le tableau 'sectionRéférencesFR', je propose quelque-chose d'un peu plus léger, qu'on mettrait simplement dans le fichier de traduction global de l'application, en PHP, donc:

$interface = Array(
    'title' => 'Explique un sélecteur CSS',
    …
    'additional-info' => Array(
        'references' => Array('label'=> 'Références'),
        'known-issues' => Array('label'=> 'Problèmes connus'),
    ),
…);

L'intérêt qu'il y a à mettre ça dans le fichier PHP c'est qu'on peut faire exister ces sections (onglets de l'issue #8 ?) dès que la page est chargée, s'il y a un contenu. On peut imaginer, pour cela, ajouter un texte permanent en plus du label.

[enguerranws]

Si tu veux, mais je vois un souci quand même à le faire en PHP : on ne pourra pas faire le lien entre les données des références en JS (comme présentées plus haut) et leur section (puisque les données des sections seraient en PHP).

 {
     titre: "",
     uri: "https://www.w3.org/TR/selectors-3/#section", 
     section: "known-issues", // là, ça aurait moins d'intérêt
},

[enguerranws]

Je peux te proposer quelque chose sur une branche ? Ce sera plus simple de discuter avec une base de travail.

Le mar. 14 avr. 2020 à 16:50, Yannis Delmas notifications@github.com a écrit :

Ça me convient bien, comme proposition. Validons ce que tu proposes pour le cssSelectorExplain().

Pour le tableau 'sectionRéférencesFR', je propose quelque-chose d'un peu plus léger, qu'on mettrait simplement dans le fichier de traduction global de l'application, en PHP, donc:

$interface = Array( 'title' => 'Explique un sélecteur CSS', … 'additional-info' => Array( 'references' => Array('label'=> 'Références'), 'known-issues' => Array('label'=> 'Problèmes connus'), ), …);

L'intérêt qu'il y a à mettre ça dans le fichier PHP c'est qu'on peut faire exister ces sections (onglets de l'issue #8 https://github.com/YannisDelmas/explain-expression/issues/8 ?) dès que la page est chargée, s'il y a un contenu. On peut imaginer, pour cela, ajouter un texte permanent en plus du label.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/YannisDelmas/explain-expression/issues/7#issuecomment-613488698, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAQWWKKBV236IKMSNUPTQVTRMRZ5DANCNFSM4MDX7NNQ .

[YannisDelmas]

Oui, ça oblige à une transmission du PHP vers le Javascript. C'est ce que j'ai fait de manière pas super-élégante dans index.php:

var JSlang = <?= json_encode($interface['JSlang']) ?>;

On pourrait peut-être en profiter pour rationaliser ce passage…

[YannisDelmas]

OK pour la proposition sur une branche. Il n'y a plus grand-chose à trancher, de toute façon. Et sur ces histoire de PHP ou JS, on pourra évoluer en fonction de l'issue #8 et de ses évolutions, si besoin.

[enguerranws]

C'est en cours sur la branche feature/tooltips-references

[YannisDelmas]

Je suis allé voir. Je trouve ça bien. Tu me diras quand on pourra faire un premier merge dans devel.

[enguerranws]

Il me reste un petit peu de boulot, je te tiens au courant. Si tu as des remarques sur le code, je suis preneur (n'hésite pas à intervenir directement sur la branche si tu veux). Il y aurait probablement des choses plus élégantes à faire par moment.

[YannisDelmas]

OK, je vais faire quelques petites modifs. J'ai repéré ce qui me semble être un petit bug: prepareReference() est appelée au moment de la création du texte, donc quand il y a plusieurs tippys, le 2e écrase le contenu du 1er. Je suis en train de faire un correctif.

[enguerranws]

Effectivement, je n'ai testé qu'avec un seul élément rattaché à Tippy pour l'instant... Le truc à corriger surtout, c'est que le contenu HTML d'un tippy est donné via un élément HTML. Je pense que ça va être plus contraignant qu'autre chose au final.

[YannisDelmas]

Tu verras, j'ai déplacé le contenu dans data-tippy-content, justement, pour ne pas être embêtés. Ça m'a obligé à compléter un peu le dispositif d'échappement, mais ça a l'air de bien fonctionner. Il faudra juste que je vérifie ce que deviennent les éléments textarea créés, pour éviter un memory leak. Edit: Apparemment, les éléments détachés sont supprimés dès lors qu'il n'y a plus de référence vers eux, donc tout va bien.

[enguerranws]

Oui, ça marche bien, et c'est la solution la plus adaptée je trouve. Je suis repassé sur les références et j'ai ajouté un mini dictionnaire de sections de références, pour pouvoir avoir des libellés sur les sections, plutôt que des identifiants. Et puis, un petit coup de CSS pour harmoniser tous les .ref. Ça prend forme !

[YannisDelmas]

OK, super. Je suis en train de déplacer le dictionnaire dans le fichier de langue, histoire d'être cohérent avec le reste.

[YannisDelmas]

Je vois qu'on a introduit un bug dans les templates pour les pseudo-classes. Je vais essayer de voir d'où ça vient...

[YannisDelmas]

Trouvé: il manquait des parenthèses à !(template instanceof Array) dans trouveModele()

[enguerranws]

Je reviens aux nouvelles sur ce ticket : que reste-t-il à faire pour proposer une PR ?

[YannisDelmas]

De fait, la première release est faite ☺, avec mon erreur de merge.

Pour une seconde, on pourrait ajouter des onglets en bas de page, mais ça n'est ni urgent ni, peut-être, nécessaire. Avais-tu d'autres idées en tête?