Les composants

Standards, et c'est toute la conception#

Ce sont quatre composants web — le standard du navigateur pour un élément personnalisé, et non le composant du framework de quelqu'un. Ce qui en découle mérite d'être dit, car c'est ce qui permet de vous le remettre :

• Ils fonctionnent dans n'importe quelle page. Un site statique, WordPress, une application React ou Vue, un wiki, un fichier HTML écrit à la main. Ce sont des éléments : une page qui peut contenir une <video> peut les contenir.
• Rien à construire. Ni bundler, ni étape de compilation, ni configuration dans votre projet. Le module enregistre son élément à l'import et le navigateur fait le reste.
• Rien à suivre. Il n'y a pas de version de framework à faire correspondre : la version majeure de quelqu'un d'autre ne peut pas les périmer.
• Leur intérieur est à eux. Chacun porte son balisage et ses styles dans un shadow root : le CSS de votre page ne peut pas les casser, et eux ne peuvent pas casser votre page.

Ils se composent en ligne : <rr0-scene> contient un <rr0-ufo>, et <rr0-sighting> comme <rr0-sighting-editor> contiennent un <rr0-scene>. Tout ce qui figure sous <rr0-ufo> ci-dessous est donc disponible dans les quatre — via .scene.ufoElement depuis le plus extérieur, la composition vivant dans un shadow root.

À quoi sert chacun#

• <rr0-ufo> — le phénomène, et rien d'autre. La forme dessinée par un témoin, sa couleur, son halo, son mouvement, rejoués sur un fond nu. C'est le témoignage sans le monde autour.
• <rr0-scene> — le monde autour. Le ciel, l'horizon, la météo et le sol réels d'une date, d'une heure et d'un lieu énoncés, avec le phénomène composé par-dessus. Utile seul, pour un ciel où il n'y a rien du tout.
• <rr0-sighting> — le témoignage, à regarder. Une scène, plus qui témoigne, les métadonnées de l'observation, ses crédits, et les lignes qui permettent à un lecteur de l'emporter ailleurs. C'est à cela que ressemble une observation publiée.
• <rr0-sighting-editor> — le témoignage, à reconstruire. Tout ce qui précède, plus la barre d'outils de saisie : décrire une observation, ou en corriger une.

Comment ils s'emboîtent#

Vous n'écrivez jamais l'imbrication. Chaque élément construit celui du dessous dans son propre shadow root : ce que votre page contient, c'est une seule balise.

<rr0-sighting>           qui témoigne, le panneau de métadonnées, les lignes d'intégration
└─ <rr0-scene>           le ciel, l'horizon, la météo et le décor réels
   └─ <rr0-ufo>          la zone de dessin, la forme, la lecture

<rr0-sighting-editor>    les huit panneaux de saisie
└─ <rr0-scene>           une scène, pas une observation : un éditeur a sa propre barre d'outils
   └─ <rr0-ufo>

C'est pourquoi une seule balise de script embarque ceux du dessous :

Une page qui montre une observation puis, plus bas, un ciel seul, n'a donc besoin que d'un script et de deux balises : le second élément est déjà enregistré.

On peut entrer dans une composition, une propriété à la fois :

const sighting = document.querySelector("rr0-sighting")
sighting.scene                    // le <rr0-scene> qu'il compose
sighting.scene.ufoElement         // et le <rr0-ufo> en dessous
sighting.scene.ufoElement.play()  // la lecture est donc à deux propriétés

<rr0-sighting-editor> garde sa composition pour lui : ce qu'il offre à une page, c'est l'enregistrement — sightingData — et l'événement qui dit qu'il a changé.

Celui qu'il vous faut#

Ce ne sont pas des variantes d'un même bundle : chacun est autonome, ne chargez donc que celui dont vous avez besoin. Les trois plus lourds embarquent Three.js et un catalogue d'étoiles — c'est ce que coûte un vrai ciel.

En poser un sur une page, c'est deux lignes.

Documentation détaillée#

Ce que chacun prend, ce à quoi il répond, ce qu'il dessine — une page par composant, parce que ce dont vous avez besoin de l'un n'est jamais ce dont vous avez besoin des trois autres au même moment.

Intégrer dans votre application#

Après npm install @rr0/ufoathome :

import "@rr0/ufoathome/ufo"      // enregistre <rr0-ufo>
import "@rr0/ufoathome/scene"    // enregistre <rr0-scene>
import "@rr0/ufoathome/sighting" // enregistre <rr0-sighting>
import "@rr0/ufoathome/editor"   // enregistre <rr0-sighting-editor>

Ou recopiez le contenu des répertoires dist-embed* du paquet sur votre serveur et pointez le <script src> dessus. Chaque module référence ses ressources — catalogue d'étoiles, sons de météo — relativement à lui-même : il fonctionne donc depuis n'importe quel chemin, il suffit de garder ensemble les fichiers d'un même bundle. Plus rien ne dépend alors de ce site.

Langue#

Chaque libellé est traduit par détection, sans sélecteur : la langue déclarée par la page d'abord — l'attribut lang le plus proche, donc <html lang="fr"> donne des libellés français — puis les préférences du navigateur, puis l'anglais. Une page qui ne déclare rien retombe sur le navigateur, exactement comme avant.