I componenti

Tre degli elementi standard riguardano un'osservazione: la scena in cui viene riprodotta, il lettore che la mostra e l'editor che la descrive. L'editor di casi e l'editor di interviste hanno le loro sezioni, nelle pagine che ne parlano.

Web Component standard

Sono cinque Web Component — lo standard del browser stesso per un elemento personalizzato, non un componente del framework di qualcuno. Ciò che ne consegue merita di essere detto, perché è ciò che permette di metterti in mano lo strumento:

  • Funzionano in qualsiasi pagina. Un sito statico, WordPress, un'applicazione React o Vue, un wiki, un file HTML scritto a mano. Sono elementi: una pagina che può contenere un <video> può contenere anche questi.
  • Niente da compilare. Nessun bundler, nessuna fase di compilazione, nessuna configurazione nel tuo progetto. Il modulo registra il suo elemento all'importazione e il browser fa il resto.
  • Niente da inseguire. Non c'è una versione di framework a cui adeguarsi, quindi la nuova major release di qualcun altro non può renderli obsoleti.
  • Il loro interno è affar loro. Ognuno porta il proprio markup e i propri stili in uno shadow root, quindi il CSS della tua pagina non può romperli e loro non possono rompere la tua pagina.

Si compongono in una riga: sia <rr0-sighting> sia <rr0-sighting-editor> contengono un <rr0-scene>, e la scena contiene lo strato di riproduzione — la linea temporale, i controlli, il canvas del puntatore. Quindi tutto ciò a cui risponde la scena è disponibile in tutti e tre — tramite .scene e .scene.ufoElement dal più esterno, poiché la composizione vive in uno shadow root.

A cosa serve ciascuno#

  • <rr0-scene> — il fenomeno nel mondo che lo circonda. La forma disegnata da un testimone, il suo colore, il suo alone e il suo movimento, collocata nel cielo, nell'orizzonte, nel meteo e nel suolo reali di una data, un'ora e un luogo dichiarati — nascosta da ciò che stava davanti. Utile anche da sola, per un cielo in cui non c'è niente.
  • <rr0-sighting> — il resoconto, da guardare. Una scena più chi testimonia, i metadati dell'osservazione, i suoi crediti e le righe che permettono a un lettore di portarlo altrove. È così che appare un avvistamento pubblicato.
  • <rr0-sighting-editor> — il resoconto, da ricostruire. Tutto quanto sopra più la barra degli strumenti di redazione: descrivere un'osservazione, o correggerne una.
  • <rr0-case-editor> — un caso, da assemblare. Contiene un <rr0-sighting-editor> e gli presenta una registrazione di un case.json alla volta: i resoconti dei testimoni e le letture che se ne fanno. Li aggiunge, li seleziona e li elimina, ed esporta il caso.
  • <rr0-date-input> — una data, con la sua precisione. Un selettore per un istante completo, un testo per meno (EDTF), e il grado di certezza. Gli editor lo usano per l'inizio e la fine di un'osservazione e per la data di un caso; dice ciò che contiene con un evento datechange.

Come si incastrano#

Non scrivi mai l'annidamento. Ogni elemento costruisce quello sottostante dentro il proprio shadow root, quindi ciò che la tua pagina contiene è un solo tag:

<rr0-sighting>           chi testimonia, il pannello dei metadati, le righe di incorporamento
└─ <rr0-scene>           il cielo, l'orizzonte, il meteo e lo scenario reali, il fenomeno, la riproduzione

<rr0-sighting-editor>    gli otto pannelli di redazione
└─ <rr0-scene>           una scena, non un avvistamento: un editor ha la propria barra degli strumenti

Ecco perché un solo tag script si porta dietro quelli sottostanti:

Caricando questosi registra
/lib/rr0-scene.mjs<rr0-scene>
/lib/rr0-sighting.mjs<rr0-sighting>, <rr0-scene>
/lib/rr0-sighting-editor.mjs<rr0-sighting-editor>, <rr0-scene>

Così una pagina che mostra un avvistamento e, più in basso, un cielo tutto suo ha bisogno di un solo script e di due tag — il secondo elemento è già registrato.

Si può entrare in una composizione, una proprietà alla volta:

const sighting = document.querySelector("rr0-sighting")
sighting.scene                    // il <rr0-scene> che compone
sighting.scene.ufoElement         // e lo strato di riproduzione sotto di esso
sighting.scene.ufoElement.play()  // quindi la riproduzione è a due proprietà di distanza

<rr0-sighting-editor> tiene per sé la propria composizione: ciò che offre a una pagina è la registrazione — sightingData — e l'evento che segnala che è cambiata.

Quale ti serve#

Non sono varianti di un unico bundle: ognuno è autonomo, quindi carica solo quello che ti serve. Tutti e tre includono Three.js e un catalogo stellare, che è il prezzo di un cielo reale.

Cosa stai facendoComponenteModulogzip
Mostrare un avvistamento UFO — un fascicolo, un articolo, un rapporto<rr0-sighting>/lib/rr0-sighting.mjs249 KB
Permettere a qualcuno di descriverne o correggerne uno<rr0-sighting-editor>/lib/rr0-sighting-editor.mjs293 KB
Mostrare un cielo senza niente — che aspetto avevano quella notte un alone, una cometa o il passaggio di un satellite<rr0-scene>/lib/rr0-scene.mjs238 KB
Mostrare un avvistamento dentro una scena tua, senza barra degli strumenti sopra<rr0-scene>/lib/rr0-scene.mjs238 KB
Non sei sicuro<rr0-sighting>/lib/rr0-sighting.mjs249 KB

Metterne uno in una pagina richiede due righe.

Integrarlo nella tua applicazione#

Dopo npm install @rr0/ufoathome:

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

Oppure copia il contenuto delle cartelle dist-embed* del pacchetto sul tuo server e punta lì il <script src>. Ogni modulo fa riferimento alle proprie risorse — il catalogo stellare, l'audio meteorologico — in modo relativo a se stesso, quindi continua a funzionare da qualsiasi percorso; basta tenere insieme i file di ogni bundle. A quel punto nulla dipende più da questo sito.

Lingua#

Ogni etichetta è tradotta per rilevamento, senza selettore: prima la lingua dichiarata dalla pagina stessa — l'attributo lang più vicino, quindi <html lang="fr"> ottiene etichette in francese — poi le preferenze del browser, poi l'inglese. Una pagina che non dichiara alcuna lingua segue quindi le preferenze del browser.

<rr0-sighting>#

La vista standard di un avvistamento

La scelta predefinita per un avvistamento reale, con uno o più testimoni. Compone un <rr0-scene> e aggiunge la barra degli strumenti: chi rende il resoconto, e il pannello i con i metadati propri dell'osservazione e i suoi crediti, e un pulsante di condivisione: il link che la riproduce, e le sue righe di incorporamento.

<rr0-sighting src="sighting.json"></rr0-sighting>
<rr0-sighting src="case.json"></rr0-sighting>  <!-- un caso, e tutti i suoi testimoni -->
MembroTipoCosa fa
srcattributoUna sola registrazione, o un caso i cui eventi sighting ne elencano diverse (l'elemento distingue l'uno dall'altro dalla loro struttura). Un semplice array di registrazioni viene rifiutato: elencale come eventi sighting di un caso
observerUrlsproprietàLe registrazioni da mostrare, come semplice array di URL, invece di src. Reimpostarla mantiene il testimone mostrato se la nuova lista lo contiene ancora
sightingDataproprietàUna registrazione, impostata direttamente — per una pagina che ne tiene una in memoria invece che a un URL
sceneproprietà (lettura)Il <rr0-scene> composto, e attraverso scene.ufoElement i membri di riproduzione
loadFromSrc(url)metodo (async)Ciò che l'attributo innesca
show-labelsattributoLa striscia di chip che enunciano la registrazione sotto l'immagine, raggruppati (riepilogo, osservazione, posizione, momento, meteo, suono, testimone): la data detta a parole con il suo giorno della settimana, e un chip Descrizione che mostra le prime parole del resoconto e apre il testo intero, con scorrimento oltre un'altezza massima, al posto dei chip. Disattivata per impostazione predefinita sull'elemento — la pagina del lettore la attiva — e un lettore può aprirla o chiuderla dal pannello i
show-observer-map / hide-milestonesattributoPassati attraverso il <rr0-scene> composto fino al lettore che li possiede
start-timeattributoDove si apre la registrazione, come una durata dall'inizio: secondi (125), 1:30, 1m30s o una durata ISO 8601 (PT1M30S). Applicato una volta, alla registrazione che l'elemento carica dopo; un valore oltre la fine apre alla fine
start-clockattributoDove si apre la registrazione, come un'ora detta durante l'osservazione, nella sua ora locale: 02:33:15, o con il giorno 2026-08-11T02:33:15. L'inizio della registrazione la colloca; prevale su start-time quando può, ed è ignorata per una registrazione che non dice la sua ora
compare-accountattributoParte con il resoconto del testimone mostrato accanto alla lettura scelta, e misurato rispetto ad essa

Una registrazione che non nomina alcun testimone non ha nessuna riga “resoconto di”, ed è la cosa esatta da dire di un cielo preparato per mostrare un alone.

La registrazione di ogni testimone viene caricata non appena la lista è nota, quindi sceglierne un'altra è immediato. La lista nomina ciascuno con il suo title, altrimenti con nomi e cognome, altrimenti con il suo id; uno che non nomina nessuno è numerato secondo il suo posto nella lista.

Il pannello i si apre come popover, che Esc o un clic all'esterno chiudono (solo un clic all'esterno, su un browser senza popover). Indica il caso, la data, il luogo, il resoconto e i tag; data, luogo e tag ne escono finché la striscia show-labels li indica già. La data è all'ora del testimone stesso (utcOffsetHours, o un'ora approssimata dalla longitudine), non a quella del lettore. La versione in fondo apre questa osservazione nell'editor. Anche la descrizione lo lascia finché i chip sono mostrati: è nella loro scatola Riepilogo, che si apre con un clic.

Il pulsante Condividi, tra quelli del lettore, apre un'unica finestra che dà il link o il codice da incorporare (il codice in un editor che va a capo e si può modificare), per il lettore o per l'editor, con le opzioni della pagina di condivisione, ciascuna offerta com'è il lettore. Il codice carica l'elemento da dovunque questa copia sia stata a sua volta caricata, così che uno snippet copiato da una copia locale o di staging rimandi a quella copia.

Cosa emette

EventoQuandoDove ascoltarlo
observerchangeQuando cambia la registrazione mostrata: caricata, impostata tramite sightingData, o un altro testimone scelto dalla lista. detail.src è il suo indirizzo, vuoto per una registrazione impostata da scriptSu questo elemento. Non fa bubbling: ascolta sul <rr0-sighting> stesso, poi rileggi il suo sightingData (la sua descrizione, il suo id)
recordingissuesUna volta che una registrazione caricata è stata verificata rispetto al formato: detail.issues elenca ciò che non è stato riprodotto come scritto (una chiave che nulla legge, un valore del tipo sbagliato o fuori dalla sua lista, un valore inventato perché il file lo ometteva), ciascuno con il suo kind e il suo path. Vuota quando non c'è nulla da dire. La stessa lista è mostrata sull'immagine dietro un ⚠, e scritta nella consoleOvunque sopra l'elemento: si propaga fuori da tutte le shadow root

Inserirlo nella tua pagina

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

sighting.json è un file di avvistamento. Oppure, dopo npm install @rr0/ufoathome: import "@rr0/ufoathome/sighting". Il bundle pesa 249 KB compresso con gzip e registra il tag da sé — nient'altro da chiamare. La presentazione sopra dice cos'altro comporta, e condividere un'osservazione ha l'esempio completo, da provare e da copiare.

<rr0-scene>#

Il fenomeno, il cielo e il suolo

La forma disegnata da un testimone, collocata nel cielo, nell'orizzonte, nel meteo e nel suolo reali della data, dell'ora e del luogo della registrazione, e nascosta da ciò che le stava davanti — con i comandi di riproduzione sotto. È l'elemento su cui si costruiscono gli altri due.

<rr0-scene src="sighting.json"></rr0-scene>
MembroTipoCosa fa
srcattributoURL di una registrazione, caricata alla connessione e a ogni cambiamento
sightingDataproprietàLa registrazione come oggetto semplice (vedere il formato) — da rileggere dopo la modifica, o da impostare invece di usare src
loadFromSrc(url)metodo (async)Ciò che l'attributo innesca internamente. Attendilo quando la registrazione deve essere GIÀ caricata prima di fare qualsiasi altra cosa
ufoElementproprietà (lettura)Il livello di riproduzione che compone — la cronologia, i comandi, il canvas su cui agisce il puntatore — e, attraverso di esso, tutti i membri di riproduzione qui sotto
sceneRendererproprietà (lettura)Il motore di rendering 3D, per ciò che nient'altro espone
show-compassattributoLe etichette N/NE/E/… lungo l'orizzonte. Disattivato per impostazione predefinita: utile quando si imposta una direzione, rumore quando si guarda
star-catalog-src / deep-star-catalog-srcattributoDa dove caricare il catalogo stellare, quando ne ospiti una tua copia invece di quella accanto al bundle: il livello base (fino alla magnitudine 7,5, caricato da ogni scena) e il livello profondo (da 7,5 a 9, caricato solo da una registrazione il cui strumento va oltre 7,5)
max-pixel-ratioattributoIl massimo di pixel del dispositivo per pixel CSS con cui la scena può disegnare; quello dello schermo stesso, fino a 2, se assente. La scena lo abbassa da sé finché i fotogrammi sono in ritardo
show-observer-map / hide-milestonesattributoPassati tali e quali al livello di riproduzione sottostante — scrivili sul tag che la tua pagina contiene davvero

Al passaggio del puntatore nomina ciò che c'è sotto — una stella con la sua magnitudine e la sua altezza, un pianeta, una cometa, un edificio, un altro testimone — e non dice nulla dove il suolo nasconde ciò che stai indicando.

Il pulsante © nel suo angolo elenca i crediti di ciò che mostra — le immagini del suolo e della mappa, i modelli, le foto del luogo, i suoni. Dentro <rr0-sighting> il pulsante è nascosto: sono nel suo pannello i.

La riproduzione, su ufoElement

Tutto ciò che riguarda la riproduzione della registrazione sta una proprietà più in basso, nel livello di riproduzione — scene.ufoElement.play() — lo stesso livello che gli altri due componenti raggiungono attraverso la propria scene.

MembroTipoCosa fa
srcattributoURL di una registrazione, caricata alla connessione e a ogni cambiamento
sightingDataproprietàLa registrazione come oggetto semplice (vedere il formato) — da rileggere dopo la modifica, o da impostare invece di usare src
sightingproprietà (lettura)Il modello vivo: ora e luogo reali più la cronologia della registrazione
loadFromSrc(url)metodo (async)Ciò che l'attributo innesca internamente. Attendilo quando la registrazione deve essere GIÀ caricata prima di fare qualsiasi altra cosa — riprodurre prima che si risolva trova una cronologia di durata zero
play() / pause()metodoDicono quale stato si vuole, invece di invertire quello attuale
togglePlayPause()metodoCiò che fanno il pulsante, il clic e la barra spaziatrice
playbackStateproprietà (lettura)"stopped", "playing" o "paused"
currentTimeproprietàLa testina di riproduzione, nelle unità proprie della cronologia — non in millisecondi reali, vedere positionLabel
seekableDurationproprietà (lettura)L'intervallo che currentTime può assumere
autoReplayEnabledproprietàLa ripetizione in loop, disattivata per impostazione predefinita: una riproduzione va una volta, poi emette ended. Attivala per un loop
positionLabel / durationLabelproprietà (lettura)La posizione e la durata già formattate dall'elemento: l'ora dell'orologio quando l'osservazione indica una data e la sua durata è nota, il tempo trascorso altrimenti. Un clic su uno dei due contatori sotto la barra (o Invio su di esso) passa dall'uno all'altro, ed emette timedisplaychange
refresh()metodoRilegge la durata e ridisegna — chiamalo dopo aver modificato sighting.timeline dall'esterno
canvasElement / rendererproprietà (lettura)Il <canvas>, e il renderer che ci dipinge sopra
enableClickToPlayproprietàSe un clic avvia o ferma la riproduzione e un doppio clic attiva o disattiva lo schermo intero (entrambe le cose, o nessuna). Il doppio clic riporta anche la riproduzione allo stato in cui era prima del suo primo clic. Impostala a false dove il canvas ti serve per altro
fullscreenTargetproprietàQuale elemento viene ingrandito dal pulsante schermo intero. <rr0-scene> la imposta sul proprio palco, così che sia il cielo ad andare a schermo intero e non solo il livello sovrapposto. Dove il browser non offre lo schermo intero (un iPhone, un iframe senza allow="fullscreen"), l'elemento riempie invece la finestra, ed Esc ne esce allo stesso modo
show-observer-mapattributoSe la mappa del punto in cui si trovava il testimone parte aperta: presente la apre, "false" la tiene chiusa. Assente, decide la registrazione: il suo observerMap se lo indica, altrimenti aperta quando il testimone si è spostato (una camminata in un campo, un tragitto in auto, un volo), chiusa quando è rimasto dov'era. Decide lo stato iniziale della mappa, non se esista: il pulsante c'è per ogni registrazione che indica un luogo
toggleObserverMap()metodoCiò che fa quel pulsante. Sulla mappa stessa la rotella ingrandisce attorno al puntatore, un trascinamento sposta il terreno, e i suoi pulsanti ingrandiscono e tornano al percorso intero. Ingrandita, si ricentra sul testimone ogni volta che questi ne raggiunge il bordo, perché non ne esca mai
observerPlacingproprietàSe un clic sul suolo libero della mappa emette observerplace con { lat, lng } — disattivata per impostazione predefinita, perché dire dove si trovava il testimone spetta alla registrazione. L'editor la attiva e scrive la posizione alla testina di riproduzione
hide-milestonesattributoToglie i momenti nominati del resoconto — le tacche lungo la barra, la didascalia che nomina quello in riproduzione e i punti con lettera sulla mappa. Compaiono ovunque una registrazione ne nomini qualcuno, quindi questo è l'unico modo di dire il contrario
toggleMilestones()metodoCiò che fa quel pulsante

I momenti nominati e la mappa sono le sole due cose che questo elemento mostra o nasconde per impostazione predefinita (i momenti visibili, la mappa nascosta), e la differenza è voluta. I momenti nominati di una registrazione sono le sue stesse parole su di sé, quindi si mostrano ovunque esistano; la mappa costa richieste di tile a una terza parte la prima volta che si apre, e non spetta a una pagina spenderle per conto di un lettore senza dirlo. In entrambi i casi il lettore conserva i due pulsanti, accanto a quello dello schermo intero — una pagina che imposta un valore predefinito non è una pagina che vieta il contrario.

La barra degli strumenti e i pulsanti dell'angolo compaiono solo mentre il puntatore è sopra l'immagine, in riproduzione o in pausa, o quando la tastiera vi porta il focus. Uno schermo tattile, che non ha un puntatore con cui passarci sopra, li tiene visibili.

Con la barra del tempo attiva, i tasti funzionano come su un sito di video: ← torna indietro di 5 s, → va avanti di 5 s e Spazio avvia o mette in pausa. Avviare o mettere in pausa, con un tasto, con il pulsante o con un clic sull'immagine, ne mostra il simbolo per un istante al centro dell'immagine.

Cosa emette

EventoQuandoDove ascoltarlo
endedUna volta, quando la riproduzione arriva alla fine senza ripartire in loop. Non a una pausa, né trascinando fino alla fineOvunque: è bubbling e composed, quindi esce da <rr0-scene> e da <rr0-sighting> e raggiunge l'elemento che hai messo nella pagina. È così che si riproducono più registrazioni una dopo l'altra
timedisplaychangeQuando i contatori passano dall'ora dell'orologio al tempo trascorso, o viceversaOvunque, come sopra
timeupdateA ogni passo della riproduzione e a ogni salto, con detail.timeSolo su questo elemento. Non è né bubbling né composed, quindi una pagina che contiene un <rr0-scene> deve passare dal suo ufoElement — è pensato per gli elementi che lo contengono

Inserirlo nella tua pagina

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

sighting.json è un file di avvistamento. Oppure, dopo npm install @rr0/ufoathome: import "@rr0/ufoathome/scene". Il bundle pesa 238 KB compresso con gzip e registra il tag da sé — nient'altro da chiamare. La presentazione sopra dice cos'altro comporta, e condividere un'osservazione ha l'esempio completo, da provare e da copiare.

<rr0-sighting-editor>#

L'editor

Una scena (<rr0-scene>) più la barra degli strumenti di creazione. Mettilo in una pagina dove le persone devono poter descrivere o correggere un'osservazione da sé.

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

Il suo canvas è una superficie di modifica, quindi enableClickToPlay lì è disattivato: un clic seleziona e trascina una forma invece di avviare o fermare la riproduzione. Cosa fanno gli otto gruppi della sua barra degli strumenti è spiegato nella pagina dell'editor.

MembroTipoCosa fa
ufoElementproprietà (lettura)Dà accesso al canvas, alla cronologia e al lavoro sull'aspetto
appearanceproprietàL'aspetto che avrà la prossima forma disegnata: { presetId, color, transparency, haloScale, blur, brightness }, dove presetId vale "oval" o "polygon" e gli altri sono i campi di forma con lo stesso nome. Impostarla prende solo i campi che fornisci
sightingchangeeventoEmesso dopo ogni modifica — l'unico segnale che la registrazione è cambiata

Cosa emette

EventoQuandoDove ascoltarlo
sightingchangeDopo una modifica: un campo scritto, uno strumento scelto, un fuso orario dedotto, una forma spostata lungo la cronologiaSu questo elemento. Non fa bubbling, quindi ascolta sul <rr0-sighting-editor> stesso — poi rileggi il suo sightingData

Inserirlo nella tua pagina

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

Oppure, dopo npm install @rr0/ufoathome: import "@rr0/ufoathome/editor". Il bundle pesa 293 KB compresso con gzip e registra il tag da sé — nient'altro da chiamare. La presentazione sopra dice cos'altro comporta, e condividere un'osservazione ha l'esempio completo, da provare e da copiare.