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'uncase.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énementdatechange.
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 ceci | enregistre |
|---|---|
/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 faites | Composant | Module | gzip |
|---|---|---|---|
| Montrer une observation d'ovni — un dossier, un article, un rapport | <rr0-sighting> | /lib/rr0-sighting.mjs | 249 Ko |
| Laisser quelqu'un en décrire ou en corriger une | <rr0-sighting-editor> | /lib/rr0-sighting-editor.mjs | 293 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.mjs | 238 Ko |
| Montrer une observation dans une scène à vous, sans barre d'outils par-dessus | <rr0-scene> | /lib/rr0-scene.mjs | 238 Ko |
| Vous ne savez pas | <rr0-sighting> | /lib/rr0-sighting.mjs | 249 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 -->
| Membre | Nature | Rôle |
|---|---|---|
src | attribut | Un 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 |
observerUrls | proprié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 |
sightingData | propriété | Un enregistrement posé directement — pour une page qui en tient un en mémoire plutôt qu'à une URL |
scene | proprié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-labels | attribut | Sous 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 Descriptionmontre 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-milestones | attribut | Transmis à travers le <rr0-scene> qu'il contient jusqu'à la couche de lecture qui les gère |
start-time | attribut | Où 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-clock | attribut | Où 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-account | attribut | Affiche 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énement | Quand | Où l'écouter |
|---|---|---|
observerchange | Quand 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 script | Sur cet élément. Il n'est pas bubbling : écoutez sur le <rr0-sighting> lui-même, puis relisez son sightingData (sa description, son identifiant) |
recordingissues | Une 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 console | N'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>
| Membre | Nature | Rôle |
|---|---|---|
src | attribut | URL d'un enregistrement, chargée à la connexion et à chaque changement |
sightingData | proprié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 |
ufoElement | proprié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 |
sceneRenderer | propriété (lecture) | Le moteur de rendu 3D, pour ce que rien d'autre n'expose |
show-compass | attribut | Les 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-src | attribut | D'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-ratio | attribut | Le 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-milestones | attribut | Transmis 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.
| Membre | Nature | Rôle |
|---|---|---|
src | attribut | URL d'un enregistrement, chargée à la connexion et à chaque changement |
sightingData | propriété | L'enregistrement comme objet simple (voir le format) — à relire après modification, ou à poser au lieu d'utiliser src |
sighting | proprié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éthode | Dire quel état on veut, plutôt que basculer l'état courant |
togglePlayPause() | méthode | Ce que font le bouton et le clic |
playbackState | propriété (lecture) | "stopped", "playing" ou "paused" |
currentTime | propriété | La tête de lecture, dans les unités de la chronologie — pas des millisecondes réelles, voir positionLabel |
seekableDuration | propriété (lecture) | L'étendue que currentTime peut prendre |
autoReplayEnabled | proprié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 / durationLabel | proprié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éthode | Relit la durée et repeint — à appeler après avoir modifié sighting.timeline de l'extérieur |
canvasElement / renderer | propriété (lecture) | Le <canvas>, et ce qui peint dessus |
enableClickToPlay | proprié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 |
fullscreenTarget | proprié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-map | attribut | Si 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éthode | Ce 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 |
observerPlacing | proprié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-milestones | attribut | Retirer 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éthode | Ce 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énement | Quand | Où l'écouter |
|---|---|---|
ended | Une fois, quand la lecture atteint la fin sans boucler. Ni à la pause, ni à un déplacement manuel jusqu'à la fin | N'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 |
timedisplaychange | Quand 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.time | Sur 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.
| Membre | Nature | Rôle |
|---|---|---|
ufoElement | propriété (lecture) | Donne accès au canevas, à la chronologie et aux réglages d'apparence |
appearance | proprié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énement | Quand | Où l'écouter |
|---|---|---|
sightingchange | Après une modification : un champ écrit, un instrument choisi, un fuseau dérivé, une forme déplacée sur la chronologie | Sur 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.