Les composants

Trois des éléments standards concernent une observation : la scène où elle est rejouée, le lecteur qui la montre, et l'éditeur qui la décrit. L'éditeur de dossier et l'éditeur d'interview sont décrits sur les pages consacrées aux dossiers et aux interviews.

Des composants web standards

Ce sont cinq composants web : le standard du navigateur pour créer un élément personnalisé, et non un composant propre à un framework. Ce qui en découle mérite d'être détaillé, car c'est ce qui permet de vous confier l'outil :

  • 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 à mettre à jour. Il n'y a pas de version de framework à respecter : aucune nouvelle version majeure d'un outil tiers ne peut les rendre obsolètes.
  • Leur contenu est isolé. 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.

Leur imbrication tient en une phrase : <rr0-sighting> comme <rr0-sighting-editor> contiennent un <rr0-scene>, et la scène contient la couche de lecture (la chronologie, les commandes, le canevas du pointeur). Tout ce à quoi la scène répond est donc accessible dans les trois : depuis l'élément le plus extérieur, on y accède par .scene et .scene.ufoElement, car l'imbrication est enfermée dans un shadow root.

À quoi sert chacun#

  • <rr0-scene> — le phénomène dans le monde autour. La forme dessinée par un témoin, sa couleur, son halo, son mouvement, placée dans le ciel, l'horizon, la météo et le sol réels de la date, de l'heure et du lieu déclarés, et masquée par ce qui se trouvait devant elle. Utile seul aussi, pour un ciel où il n'y a rien du tout.
  • <rr0-sighting> — le compte rendu, à regarder. Une scène, plus le choix du témoin, les métadonnées de l'observation, ses crédits, et le code qui permet de l'intégrer dans une autre page. C'est à cela que ressemble une observation publiée.
  • <rr0-sighting-editor> — le compte rendu, à reconstruire. Tout ce qui précède, plus la barre d'outils de saisie : décrire une observation, ou en corriger une.
  • <rr0-case-editor> — un dossier, à assembler. Contient un <rr0-sighting-editor> et lui confie, un par un, les enregistrements d'un case.json : les comptes rendus des témoins et les lectures qu'on en fait. Il les ajoute, les sélectionne et les supprime, et exporte le dossier.
  • <rr0-date-input> — une date, avec sa précision. Un sélecteur pour un instant complet, un champ texte pour une date moins précise (EDTF), et le degré de certitude. Les éditeurs s'en servent pour le début et la fin d'une observation et pour la date d'un dossier ; il dit ce qu'il contient par un événement datechange.

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, le phénomène, 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

C'est pourquoi la balise de script d'un composant enregistre aussi ceux qu'il contient :

Charger cecienregistre
/lib/rr0-scene.mjs<rr0-scene>
/lib/rr0-sighting.mjs<rr0-sighting>, <rr0-scene>
/lib/rr0-sighting-editor.mjs<rr0-sighting-editor>, <rr0-scene>

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 atteint les éléments imbriqués de propriété en propriété :

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

<rr0-sighting-editor> garde ses éléments imbriqués 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. Tous trois embarquent Three.js et un catalogue d'étoiles : c'est le poids d'un vrai ciel.

Ce que vous faitesComposantModulegzip
Montrer une observation d'ovni — un dossier, un article, un rapport<rr0-sighting>/lib/rr0-sighting.mjs249 Ko
Laisser quelqu'un en décrire ou en corriger une<rr0-sighting-editor>/lib/rr0-sighting-editor.mjs293 Ko
Montrer un ciel sans rien dedans — ce qu'un halo, une comète ou un passage satellite donnaient cette nuit-là<rr0-scene>/lib/rr0-scene.mjs238 Ko
Montrer une observation dans une scène à vous, sans barre d'outils par-dessus<rr0-scene>/lib/rr0-scene.mjs238 Ko
Vous ne savez pas<rr0-sighting>/lib/rr0-sighting.mjs249 Ko

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

Intégrer dans votre application#

Après npm install @rr0/ufoathome :

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 aucune langue suit donc les préférences du navigateur.

<rr0-sighting>#

La vue standard d'une observation

Le composant à utiliser pour une observation réelle, qu'il y ait un témoin ou plusieurs. Il contient un <rr0-scene> et y ajoute une barre d'outils : le choix du témoin, le panneau i (métadonnées de l'observation et crédits) et un bouton de partage (le lien qui rejoue l'observation et le code pour l'intégrer).

<rr0-sighting src="sighting.json"></rr0-sighting>
<rr0-sighting src="case.json"></rr0-sighting>  <!-- un dossier, et tous ses témoins -->
MembreNatureRôle
srcattributUn enregistrement, ou un dossier dont les événements sighting en listent plusieurs (l'élément distingue l'un de l'autre à leur structure). Un simple tableau d'enregistrements est refusé : listez-les comme événements sighting d'un dossier
observerUrlspropriétéLes enregistrements à montrer, comme simple tableau d'URLs, au lieu de src. Lui donner une nouvelle liste garde le témoin affiché si elle le contient encore
sightingDatapropriétéUn enregistrement posé directement — pour une page qui en tient un en mémoire plutôt qu'à une URL
scenepropriété (lecture)Le <rr0-scene> qu'il contient, et par scene.ufoElement les membres de lecture
loadFromSrc(url)méthode (async)Ce que déclenche l'attribut
show-labelsattributSous l'image, un bandeau de pastilles qui résument l'enregistrement, rangées par groupe (résumé, observation, position, moment, météo, son, témoin). La date y est écrite en toutes lettres avec son jour de la semaine ; une pastille Description montre les premiers mots du récit et, d'un clic, affiche le texte entier à la place des pastilles (avec défilement au-delà d'une hauteur maximale). Désactivé par défaut sur l'élément (la page du lecteur l'active) ; le visiteur peut l'ouvrir ou le fermer depuis le panneau i
show-observer-map / hide-milestonesattributTransmis à travers le <rr0-scene> qu'il contient jusqu'à la couche de lecture qui les gère
start-timeattributOù l'enregistrement s'ouvre, comme une durée depuis son début : des secondes (125), 1:30, 1m30s ou une durée ISO 8601 (PT1M30S). Appliqué une fois, à l'enregistrement que l'élément charge ensuite ; une valeur au-delà de la fin ouvre à la fin
start-clockattributOù l'enregistrement s'ouvre, comme une heure dite pendant l'observation, à son heure locale : 02:33:15, ou avec le jour 2026-08-11T02:33:15. Elle est située par rapport au début déclaré de l'enregistrement ; elle l'emporte sur start-time quand elle le peut, et est ignorée pour un enregistrement qui n'indique pas l'heure de la journée
compare-accountattributAffiche dès le départ le récit du témoin à côté de la lecture choisie, et le compare à elle

Un enregistrement qui ne nomme aucun témoin n'affiche aucune ligne « compte rendu de » : c'est ce qu'il faut pour un ciel préparé seulement pour montrer un halo.

L'enregistrement de chaque témoin est chargé dès que la liste est connue : en choisir un autre est immédiat. La liste nomme chacun par son title, sinon ses prénoms et son nom, sinon son id ; un enregistrement qui ne nomme personne est numéroté selon sa place dans la liste.

Le panneau i s'ouvre en popover, que ferment Échap ou un clic à l'extérieur (seulement un clic à l'extérieur, sur un navigateur sans popover). Il indique le dossier, la date, le lieu, le compte rendu et les tags ; date, lieu et tags n'y figurent pas quand le bandeau show-labels les affiche déjà. La date est donnée à l'heure locale du témoin (utcOffsetHours, ou un décalage estimé d'après la longitude), pas à celle du visiteur. Le numéro de version, en bas du panneau, ouvre cette observation dans l'éditeur. La description n'y figure pas non plus quand les pastilles sont affichées : elle est alors dans leur groupe Résumé, qu'un clic ouvre.

Le bouton Partager, parmi ceux du lecteur, ouvre une seule fenêtre qui donne le lien ou le code d'intégration (le code dans un éditeur qui passe à la ligne et qu'on peut modifier), pour le lecteur ou pour l'éditeur, avec les options décrites sur la page de partage, chacune réglée d'emblée sur l'état actuel du lecteur. Le code d'intégration charge l'élément depuis l'endroit d'où cet exemplaire du lecteur a lui-même été chargé : un extrait copié depuis une installation locale ou de recette pointe donc vers elle.

Ce qu'il émet

ÉvénementQuandOù l'écouter
observerchangeQuand l'enregistrement affiché change : chargé, posé par sightingData, ou un autre témoin choisi dans la liste. detail.src est son adresse, vide pour un enregistrement posé par scriptSur cet élément. Il n'est pas bubbling : écoutez sur le <rr0-sighting> lui-même, puis relisez son sightingData (sa description, son identifiant)
recordingissuesUne fois qu'un enregistrement chargé a été vérifié par rapport au format : detail.issues liste ce qui n'a pas été joué comme écrit (une clé que rien ne lit, une valeur du mauvais type ou hors de sa liste, une valeur inventée parce que le fichier l'omettait), chacun avec son kind et son path. Vide quand il n'y a rien à dire. La même liste s'affiche sur l'image derrière un ⚠, et en consoleN'importe où au-dessus de l'élément : il sort de tous les shadow roots

L'intégrer

<script type="module" src="https://ufoathome.org/lib/rr0-sighting.mjs"></script>
<rr0-sighting src="sighting.json"></rr0-sighting>

sighting.json est un fichier d'observation. Ou, après npm install @rr0/ufoathome : import "@rr0/ufoathome/sighting". Le bundle pèse 249 Ko compressé et enregistre le tag lui-même — rien d'autre à appeler. La présentation plus haut dit ce que cela suppose par ailleurs, et partager une observation a l'exemple complet, à essayer et à copier.

<rr0-scene>#

Le phénomène, le ciel et le sol

La forme dessinée par un témoin, placée dans le ciel, l'horizon, la météo et le sol réels de la date, de l'heure et du lieu de l'enregistrement, et masquée par ce qui se trouvait devant elle, avec les commandes de lecture en dessous. C'est l'élément sur lequel les deux autres se construisent.

<rr0-scene src="sighting.json"></rr0-scene>
MembreNatureRôle
srcattributURL d'un enregistrement, chargée à la connexion et à chaque changement
sightingDatapropriétéL'enregistrement comme objet simple (voir le format) — à relire après modification, ou à poser au lieu d'utiliser src
loadFromSrc(url)méthode (async)Ce que déclenche l'attribut. À attendre quand l'enregistrement doit être arrivé avant toute autre chose
ufoElementpropriété (lecture)La couche de lecture qu'il contient (la chronologie, les commandes, le canevas du pointeur) et, par elle, tous les membres de lecture décrits plus bas
sceneRendererpropriété (lecture)Le moteur de rendu 3D, pour ce que rien d'autre n'expose
show-compassattributLes repères N/NE/E/… sur l'horizon. Désactivé par défaut : utile pour régler une direction pendant la saisie, gênant pour qui regarde
star-catalog-src / deep-star-catalog-srcattributD'où charger le catalogue d'étoiles, quand vous en hébergez votre propre copie plutôt que celle posée à côté du bundle : le niveau de base (jusqu'à la magnitude 7,5, chargé par toute scène) et le niveau profond (de 7,5 à 9, chargé seulement par un enregistrement dont l'instrument va au-delà de 7,5)
max-pixel-ratioattributLe nombre maximal de pixels de l'écran par pixel CSS auquel la scène peut dessiner ; celui de l'écran, jusqu'à 2, s'il est absent. La scène le baisse d'elle-même tant que ses images sont en retard
show-observer-map / hide-milestonesattributTransmis tels quels à la couche de lecture ci-dessous — à écrire sur la balise que votre page contient réellement

Le survol nomme ce qui est sous le curseur — une étoile avec sa magnitude et sa hauteur, une planète, une comète, un bâtiment, un autre témoin — et ne dit rien là où le sol cache ce que vous pointez.

Le bouton © dans son coin liste les crédits de ce qu'il montre — l'imagerie du sol et de la carte, les modèles, les photos du lieu, les sons. Dans <rr0-sighting>, ce bouton est masqué : les crédits figurent alors dans son panneau i.

La lecture, sur ufoElement

Tout ce qui sert à rejouer l'enregistrement se trouve un niveau plus bas, sur la couche de lecture (scene.ufoElement.play()) : la même couche que les deux autres composants atteignent par leur propre propriété scene.

MembreNatureRôle
srcattributURL d'un enregistrement, chargée à la connexion et à chaque changement
sightingDatapropriétéL'enregistrement comme objet simple (voir le format) — à relire après modification, ou à poser au lieu d'utiliser src
sightingpropriété (lecture)Le modèle vivant : date et lieu réels, plus la chronologie de l'enregistrement
loadFromSrc(url)méthode (async)Ce que déclenche l'attribut. À attendre quand l'enregistrement doit être arrivé avant toute autre chose : lancer la lecture avant que la promesse soit résolue tombe sur une chronologie vide
play() / pause()méthodeDire quel état on veut, plutôt que basculer l'état courant
togglePlayPause()méthodeCe que font le bouton et le clic
playbackStatepropriété (lecture)"stopped", "playing" ou "paused"
currentTimepropriétéLa tête de lecture, dans les unités de la chronologie — pas des millisecondes réelles, voir positionLabel
seekableDurationpropriété (lecture)L'étendue que currentTime peut prendre
autoReplayEnabledpropriétéLa lecture en boucle, désactivée par défaut : une lecture se joue une fois puis émet ended. À mettre à true pour boucler
positionLabel / durationLabelpropriété (lecture)Position et durée déjà mises en forme : l'heure quand l'observation énonce une date et que sa durée est connue, le temps écoulé sinon. Un clic sur l'un des compteurs sous la barre (ou Entrée) bascule de l'un à l'autre, et émet timedisplaychange
refresh()méthodeRelit la durée et repeint — à appeler après avoir modifié sighting.timeline de l'extérieur
canvasElement / rendererpropriété (lecture)Le <canvas>, et ce qui peint dessus
enableClickToPlaypropriétéSi un clic bascule la lecture et un double-clic le plein écran (les deux, ou aucun). Le double-clic remet aussi la lecture dans l'état où elle était avant son premier clic. À mettre à false là où le canevas vous sert à autre chose
fullscreenTargetpropriétéQuel élément le bouton plein écran agrandit. <rr0-scene> y met sa propre scène, pour que ce soit le ciel qui s'agrandisse et non la seule surcouche. Là où le navigateur n'offre pas de plein écran (un iPhone, une iframe sans allow="fullscreen"), l'élément remplit la fenêtre à la place, et Échap en sort de même
show-observer-mapattributSi la carte de l'endroit où se tenait le témoin est ouverte au départ : présent, l'attribut l'ouvre, "false" la garde fermée. Absent, l'enregistrement décide : son propre observerMap s'il en énonce un, sinon ouverte quand le témoin s'est déplacé (une marche à travers champ, un trajet en voiture, un vol), fermée quand il est resté sur place. Il décide de l'état de départ de la carte, pas de son existence : le bouton est là pour tout enregistrement qui énonce un lieu
toggleObserverMap()méthodeCe que fait ce bouton. Sur la carte elle-même, la molette zoome autour du pointeur, un glisser déplace le terrain, et ses propres boutons zooment et reviennent au trajet entier. Zoomée, elle se recentre sur le témoin dès qu'il en atteint le bord, pour qu'il n'en sorte jamais
observerPlacingpropriétéSi un clic sur le sol de la carte émet observerplace avec { lat, lng } — désactivé par défaut, car où se tenait le témoin, c'est à l'enregistrement de le dire. L'éditeur l'active et écrit la position à la tête de lecture
hide-milestonesattributRetirer les moments nommés du récit — les repères sur la barre, la légende qui nomme celui qu'on joue, et les points lettrés sur la carte. Ils sont là partout où un enregistrement en nomme, donc c'est la seule façon de dire le contraire
toggleMilestones()méthodeCe que fait ce bouton

Les moments nommés et la carte sont les deux seules choses que cet élément affiche ou masque par défaut (les moments affichés, la carte masquée), et cette différence est voulue. Les moments nommés d'un enregistrement sont ses propres mots sur lui-même : ils s'affichent partout où ils existent. La carte, elle, demande ses tuiles à un service tiers dès sa première ouverture, et ce n'est pas à une page d'engager ces requêtes au nom d'un visiteur sans le lui dire. Dans les deux cas le visiteur garde les deux boutons, à côté de celui du plein écran : qu'une page choisisse l'état de départ ne l'empêche pas de passer à l'autre.

La barre d'outils et les boutons du coin n'apparaissent que tant que le pointeur survole l'image, en lecture comme en pause, ou quand le clavier y amène le focus. Un écran tactile, qui n'a pas de pointeur pour survoler, les garde affichés.

Quand la barre de temps a le focus, les touches font comme sur un site de vidéos : ← recule de 5 s, → avance de 5 s, et Espace lance ou met en pause. Chaque lancement ou mise en pause, au clavier, au bouton ou d'un clic sur l'image, affiche brièvement son symbole au centre de l'image.

Ce qu'il émet

ÉvénementQuandOù l'écouter
endedUne fois, quand la lecture atteint la fin sans boucler. Ni à la pause, ni à un déplacement manuel jusqu'à la finN'importe où : il est bubbling et composed, donc il sort de <rr0-scene> et de <rr0-sighting> et atteint l'élément que vous avez posé sur la page. C'est ainsi qu'on enchaîne plusieurs enregistrements
timedisplaychangeQuand les compteurs basculent entre heure et temps écouléN'importe où, comme ci-dessus
timeupdateÀ chaque image de lecture et à chaque déplacement, avec detail.timeSur cet élément seulement. Il n'est ni bubbling ni composed : une page qui tient un <rr0-scene> doit passer par son ufoElement — il est destiné aux éléments qui contiennent celui-ci

L'intégrer

<script type="module" src="https://ufoathome.org/lib/rr0-scene.mjs"></script>
<rr0-scene src="sighting.json"></rr0-scene>

sighting.json est un fichier d'observation. Ou, après npm install @rr0/ufoathome : import "@rr0/ufoathome/scene". Le bundle pèse 238 Ko compressé et enregistre le tag lui-même — rien d'autre à appeler. La présentation plus haut dit ce que cela suppose par ailleurs, et partager une observation a l'exemple complet, à essayer et à copier.

<rr0-sighting-editor>#

L'éditeur

Une scène (<rr0-scene>), plus la barre d'outils de saisie. À poser sur une page où l'on doit pouvoir décrire ou corriger une observation soi-même.

<rr0-sighting-editor></rr0-sighting-editor>
<rr0-sighting-editor src="sighting.json"></rr0-sighting-editor>

Son canevas est une surface d'édition : enableClickToPlay y est désactivé, un clic sélectionne et déplace une forme au lieu de basculer la lecture. Ce que font les huit groupes de sa barre d'outils est sur la page de l'éditeur.

MembreNatureRôle
ufoElementpropriété (lecture)Donne accès au canevas, à la chronologie et aux réglages d'apparence
appearancepropriétéL'allure de la prochaine forme dessinée : { presetId, color, transparency, haloScale, blur, brightness }, presetId valant "oval" ou "polygon" et les autres étant les champs de forme de même nom. Lui affecter un objet ne modifie que les champs fournis
sightingchangeévénementÉmis après chaque modification — le signal unique que l'enregistrement a changé

Ce qu'il émet

ÉvénementQuandOù l'écouter
sightingchangeAprès une modification : un champ écrit, un instrument choisi, un fuseau dérivé, une forme déplacée sur la chronologieSur cet élément. Il n'est pas bubbling : écoutez sur le <rr0-sighting-editor> lui-même, puis relisez son sightingData

L'intégrer

<script type="module" src="https://ufoathome.org/lib/rr0-sighting-editor.mjs"></script>
<rr0-sighting-editor></rr0-sighting-editor>

Ou, après npm install @rr0/ufoathome : import "@rr0/ufoathome/editor". Le bundle pèse 293 Ko compressé et enregistre le tag lui-même — rien d'autre à appeler. La présentation plus haut dit ce que cela suppose par ailleurs, et partager une observation a l'exemple complet, à essayer et à copier.