Los componentes

Tres de los elementos estándar tratan de una observación: la escena en que se reproduce, el reproductor que la muestra y el editor que la describe. El editor de casos y el editor de entrevistas tienen sus secciones en las páginas que hablan de ellos.

Web Components estándar

Son cinco Web Components — el estándar del propio navegador para un elemento personalizado, no un componente del framework de nadie. Lo que de ello se deriva merece explicarse, porque es lo que permite ponerte la herramienta en las manos:

  • Funcionan en cualquier página. Un sitio estático, WordPress, una aplicación React o Vue, una wiki, un archivo HTML escrito a mano. Son elementos: una página que puede contener un <video> puede contener estos.
  • Nada que compilar. Ni bundler, ni paso de compilación, ni configuración en tu proyecto. El módulo registra su elemento al importarlo y el navegador hace el resto.
  • Nada que mantener al día. No hay versión de framework con la que coincidir, así que la nueva versión mayor de otro no puede dejarlos obsoletos.
  • Su interior es suyo. Cada uno lleva su marcado y sus estilos en un shadow root, así que el CSS de tu página no puede romperlos y ellos no pueden romper tu página.

Se componen en una línea: tanto <rr0-sighting> como <rr0-sighting-editor> contienen un <rr0-scene>, y la escena contiene la capa de reproducción — la línea de tiempo, los controles, el lienzo del puntero. Así que todo aquello a lo que responde la escena está disponible en los tres — mediante .scene y .scene.ufoElement desde el más externo, ya que la composición vive en un shadow root.

Para qué sirve cada uno#

  • <rr0-scene> — el fenómeno en el mundo que lo rodea. La forma que dibujó un testigo, su color, su halo y su movimiento, situada en el cielo, el horizonte, el tiempo y el suelo reales de una fecha, una hora y un lugar declarados — oculta por lo que había delante. Útil también por sí solo, para un cielo en el que no hay nada.
  • <rr0-sighting> — el relato, para verlo. Una escena más quién testifica, los metadatos de la observación, sus créditos y las líneas que permiten a un lector llevarlo a otra parte. Así es como se ve un avistamiento publicado.
  • <rr0-sighting-editor> — el relato, para reconstruirlo. Todo lo anterior más la barra de herramientas de edición: describir una observación, o corregir una.
  • <rr0-case-editor> — un caso, para armar. Contiene un <rr0-sighting-editor> y le presenta una grabación de un case.json cada vez: los relatos de los testigos y las lecturas que se hacen de ellos. Los añade, los selecciona y los elimina, y exporta el caso.
  • <rr0-date-input> — una fecha, con su precisión. Un selector para un instante completo, un texto para menos (EDTF), y el grado de certeza. Los editores lo usan para el inicio y el fin de una observación y para la fecha de un caso; dice lo que contiene con un evento datechange.

Cómo encajan entre sí#

Nunca escribes el anidamiento. Cada elemento construye el de debajo dentro de su propio shadow root, así que lo que contiene tu página es una sola etiqueta:

<rr0-sighting>           quién testifica, el panel de metadatos, las líneas de inserción
└─ <rr0-scene>           el cielo, el horizonte, el tiempo y el decorado reales, el fenómeno, la reproducción

<rr0-sighting-editor>    los ocho paneles de edición
└─ <rr0-scene>           una escena, no un avistamiento: un editor tiene su propia barra de herramientas

Por eso una sola etiqueta de script trae consigo los de debajo:

Cargar estoregistra
/lib/rr0-scene.mjs<rr0-scene>
/lib/rr0-sighting.mjs<rr0-sighting>, <rr0-scene>
/lib/rr0-sighting-editor.mjs<rr0-sighting-editor>, <rr0-scene>

Así, una página que muestra un avistamiento y, más abajo, un cielo propio sin nada necesita un solo script y dos etiquetas — el segundo elemento ya está registrado.

Se puede entrar en una composición, una propiedad cada vez:

const sighting = document.querySelector("rr0-sighting")
sighting.scene                    // el <rr0-scene> que compone
sighting.scene.ufoElement         // y la capa de reproducción debajo
sighting.scene.ufoElement.play()  // así que la reproducción está a dos propiedades

<rr0-sighting-editor> se guarda su composición para sí: lo que ofrece a una página es el registro — sightingData — y el evento que avisa de que ha cambiado.

Cuál necesitas#

No son variantes de un mismo bundle: cada uno es autónomo, así que carga solo el que necesites. Los tres incluyen Three.js y un catálogo de estrellas, que es lo que cuesta un cielo real.

Lo que estás haciendoComponenteMódulogzip
Mostrar un avistamiento ovni — un expediente, un artículo, un informe<rr0-sighting>/lib/rr0-sighting.mjs249 KB
Dejar que alguien describa o corrija uno<rr0-sighting-editor>/lib/rr0-sighting-editor.mjs293 KB
Mostrar un cielo sin nada — cómo se veían esa noche un halo, un cometa o el paso de un satélite<rr0-scene>/lib/rr0-scene.mjs238 KB
Mostrar un avistamiento dentro de una escena propia, sin barra de herramientas encima<rr0-scene>/lib/rr0-scene.mjs238 KB
No estás seguro<rr0-sighting>/lib/rr0-sighting.mjs249 KB

Ponerlo en una página son dos líneas.

Integrarlo en tu aplicación#

Tras 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>

O copia el contenido de los directorios dist-embed* del paquete en tu propio servidor y apunta allí el <script src>. Cada módulo referencia sus propios recursos — el catálogo de estrellas, el audio meteorológico — de forma relativa a sí mismo, así que sigue funcionando desde cualquier ruta; basta con mantener juntos los archivos de cada bundle. Nada depende entonces de este sitio.

Idioma#

Cada etiqueta se traduce por detección, sin selector: primero el idioma declarado por la propia página — el atributo lang más cercano, así que <html lang="fr"> obtiene etiquetas en francés —, luego las preferencias del navegador y, por último, el inglés. Una página que no declara ningún idioma sigue, por tanto, las preferencias del navegador.

<rr0-sighting>#

La vista estándar de un avistamiento

La opción por defecto para un avistamiento real, con uno o varios testigos. Compone un <rr0-scene> y añade la barra de herramientas: quién da su relato, y el panel i con los metadatos propios de la observación y sus créditos, y un botón de compartir: el enlace que la reproduce, y sus líneas de inserción.

<rr0-sighting src="sighting.json"></rr0-sighting>
<rr0-sighting src="case.json"></rr0-sighting>  <!-- un caso, y todos sus testigos -->
MiembroTipoQué hace
srcatributoUna sola grabación, o un caso cuyos eventos sighting enumeran varias (el elemento distingue uno de otro por su estructura). Un simple array de grabaciones se rechaza: enuméralas como los eventos sighting de un caso
observerUrlspropiedadLas grabaciones que mostrar, como simple array de URL, en lugar de src. Volver a asignarla mantiene el testigo mostrado si la nueva lista aún lo contiene
sightingDatapropiedadUna grabación, asignada directamente — para una página que la tiene en memoria en lugar de en una URL
scenepropiedad (lectura)El <rr0-scene> compuesto, y a través de scene.ufoElement los miembros de reproducción
loadFromSrc(url)método (async)Lo que el atributo desencadena
show-labelsatributoLa franja de chips que enuncian la grabación bajo la imagen, agrupados (resumen, observación, posición, momento, tiempo, sonido, testigo): la fecha dicha con palabras y su día de la semana, y un chip Descripción que muestra las primeras palabras del relato y abre el texto entero, con desplazamiento pasada una altura máxima, en lugar de los chips. Desactivada por defecto en el elemento — la página del reproductor la activa — y un lector puede abrirla o cerrarla desde el panel i
show-observer-map / hide-milestonesatributoSe transmiten a través del <rr0-scene> compuesto hasta el reproductor que los posee
start-timeatributoDónde se abre la grabación, como una duración desde su inicio: segundos (125), 1:30, 1m30s o una duración ISO 8601 (PT1M30S). Se aplica una vez, a la grabación que el elemento carga a continuación; un valor más allá del final abre al final
start-clockatributoDónde se abre la grabación, como una hora dicha durante la observación, en su hora local: 02:33:15, o con el día 2026-08-11T02:33:15. El inicio de la grabación la sitúa; prevalece sobre start-time cuando puede, y se ignora en una grabación que no dice su hora
compare-accountatributoEmpieza con el relato del testigo mostrado junto a la lectura elegida, y medido contra ella

Una grabación que no nombra a ningún testigo no muestra ninguna línea “relato de”, que es lo exacto que cabe decir de un cielo preparado para mostrar un halo.

La grabación de cada testigo se carga en cuanto se conoce la lista, así que elegir otra es inmediato. La lista nombra a cada uno por su title, si no por sus nombres y apellido, si no por su id; uno que no nombra a nadie se numera según su lugar en la lista.

El panel i se abre como un popover, que Escape o un clic fuera cierran (solo un clic fuera, en un navegador sin popover). Indica el caso, la fecha, el lugar, el relato y las etiquetas; fecha, lugar y etiquetas desaparecen de él mientras la franja show-labels ya los indica. La fecha está en la hora del propio testigo (utcOffsetHours, o una aproximada a partir de la longitud), no en la del lector. La versión al pie abre esta observación en el editor. La descripción también lo deja mientras los chips se muestran: está en su caja Resumen, que se abre con un clic.

El botón Compartir, entre los del reproductor, abre una sola ventana que da el enlace o el código para insertar (el código en un editor que ajusta las líneas y se puede modificar), para el reproductor o para el editor, con las opciones de la página de compartir, cada una ofrecida tal como está el reproductor. El código carga el elemento desde dondequiera que esta copia se cargó a su vez, así que un fragmento copiado desde una copia local o de pruebas apunta de vuelta a esa copia.

Lo que emite

EventoCuándoDónde escucharlo
observerchangeCuando cambia la grabación mostrada: cargada, asignada mediante sightingData, u otro testigo elegido en la lista. detail.src es su dirección, vacía para una grabación asignada por scriptEn este elemento. No hace bubbling: escucha en el propio <rr0-sighting> y luego vuelve a leer su sightingData (su descripción, su id)
recordingissuesUna vez que una grabación cargada se ha comprobado contra el formato: detail.issues enumera lo que no se reprodujo tal como estaba escrito (una clave que nada lee, un valor de tipo erróneo o fuera de su lista, un valor inventado porque el archivo lo omitía), cada uno con su kind y su path. Vacía cuando no hay nada que decir. La misma lista se muestra sobre la imagen tras un ⚠, y se escribe en la consolaEn cualquier parte por encima del elemento: se propaga fuera de todas las raíces shadow

Ponerlo en tu página

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

sighting.json es un archivo de avistamiento. O bien, tras npm install @rr0/ufoathome: import "@rr0/ufoathome/sighting". El bundle pesa 249 KB comprimido con gzip y registra la etiqueta por sí mismo — no hay nada más que llamar. La presentación de arriba explica qué más supone, y compartir una observación tiene el ejemplo completo, para probarlo y copiarlo.

<rr0-scene>#

El fenómeno, el cielo y el suelo

La forma que dibujó un testigo, situada en el cielo, el horizonte, el tiempo meteorológico y el suelo reales de la fecha, la hora y el lugar de la grabación, y oculta por lo que hubiera delante — con los controles de reproducción debajo. Es el elemento sobre el que se construyen los otros dos.

<rr0-scene src="sighting.json"></rr0-scene>
MiembroTipoQué hace
srcatributoURL de una grabación, cargada al conectarse y cada vez que cambia
sightingDatapropiedadLa grabación como objeto simple (véase el formato) — para leerla de nuevo tras editarla, o para asignarla en lugar de usar src
loadFromSrc(url)método (async)Lo que el atributo desencadena internamente. Espéralo cuando necesites que la grabación esté YA cargada antes de hacer cualquier otra cosa
ufoElementpropiedad (lectura)La capa de reproducción que compone — la línea de tiempo, los controles, el lienzo sobre el que actúa el puntero — y, a través de ella, todos los miembros de reproducción de más abajo
sceneRendererpropiedad (lectura)El motor de renderizado 3D, para lo que nada más expone
show-compassatributoLas etiquetas N/NE/E/… alrededor del horizonte. Desactivado por defecto: útil al fijar un rumbo, ruido al mirar
star-catalog-src / deep-star-catalog-srcatributoDe dónde cargar el catálogo de estrellas, cuando alojas tu propia copia en lugar de la que acompaña al bundle: el nivel básico (hasta la magnitud 7,5, cargado por toda escena) y el nivel profundo (de 7,5 a 9, cargado solo por una grabación cuyo instrumento llega más allá de 7,5)
max-pixel-ratioatributoEl máximo de píxeles de la pantalla por píxel CSS con que la escena puede dibujar; el de la propia pantalla, hasta 2, si falta. La escena lo reduce por sí misma mientras las imágenes llegan tarde
show-observer-map / hide-milestonesatributoSe transmiten tal cual a la capa de reproducción de debajo — escríbelos en la etiqueta que tu página contenga realmente

Al pasar el puntero por encima, nombra lo que hay debajo — una estrella con su magnitud y su altura, un planeta, un cometa, un edificio, otro testigo — y no dice nada donde el suelo oculta lo que señalas.

El botón © de su esquina enumera los créditos de lo que muestra — las imágenes del suelo y del mapa, los modelos, las fotos del lugar, los sonidos. Dentro de <rr0-sighting> el botón está oculto: están en su panel i.

La reproducción, en ufoElement

Todo lo relativo a reproducir la grabación vive una propiedad más abajo, en la capa de reproducción — scene.ufoElement.play() —, la misma capa a la que los otros dos componentes llegan a través de su propia scene.

MiembroTipoQué hace
srcatributoURL de una grabación, cargada al conectarse y cada vez que cambia
sightingDatapropiedadLa grabación como objeto simple (véase el formato) — para leerla de nuevo tras editarla, o para asignarla en lugar de usar src
sightingpropiedad (lectura)El modelo vivo: la hora y el lugar reales más la línea de tiempo de la grabación
loadFromSrc(url)método (async)Lo que el atributo desencadena internamente. Espéralo cuando necesites que la grabación esté YA cargada antes de hacer cualquier otra cosa — reproducir antes de que se resuelva encuentra una línea de tiempo de longitud cero
play() / pause()métodoDicen qué estado se quiere, en lugar de invertir el actual
togglePlayPause()métodoLo que hacen el botón, el clic y la barra espaciadora
playbackStatepropiedad (lectura)"stopped", "playing" o "paused"
currentTimepropiedadEl cabezal de reproducción, en las unidades propias de la línea de tiempo — no en milisegundos reales, véase positionLabel
seekableDurationpropiedad (lectura)El intervalo que puede tomar currentTime
autoReplayEnabledpropiedadLa repetición en bucle, desactivada por defecto: una reproducción se ejecuta una vez y luego emite ended. Actívala para un bucle
positionLabel / durationLabelpropiedad (lectura)La posición y la duración ya formateadas por el elemento: la hora del reloj cuando la observación indica una fecha y se conoce su duración, el tiempo transcurrido en otro caso. Un clic en cualquiera de los dos contadores bajo la barra (o Intro sobre él) cambia de uno a otro, y emite timedisplaychange
refresh()métodoVuelve a leer la duración y repinta — llámalo tras modificar sighting.timeline desde fuera
canvasElement / rendererpropiedad (lectura)El <canvas>, y el renderizador que pinta en él
enableClickToPlaypropiedadSi un clic alterna la reproducción y un doble clic alterna la pantalla completa (ambas cosas, o ninguna). El doble clic también devuelve la reproducción al estado en que estaba antes de su primer clic. Ponlo a false donde el lienzo te sirva para otra cosa
fullscreenTargetpropiedadQué elemento amplía el botón de pantalla completa. <rr0-scene> lo fija en su propio escenario, para que sea el cielo lo que pase a pantalla completa y no solo la capa superpuesta. Donde el navegador no ofrece pantalla completa (un iPhone, un iframe sin allow="fullscreen"), el elemento llena la ventana en su lugar, y Escape sale de ella igualmente
show-observer-mapatributoSi el mapa de dónde se encontraba el testigo empieza abierto: presente, lo abre; "false" lo mantiene cerrado. Ausente, decide la grabación: su propio observerMap si lo indica, y si no abierto cuando el testigo se desplazó (un paseo por un campo, un trayecto en coche, un vuelo), cerrado cuando se quedó donde estaba. Decide el estado inicial del mapa, no si existe: el botón está ahí para toda grabación que indique un lugar
toggleObserverMap()métodoLo que hace ese botón. En el propio mapa, la rueda amplía alrededor del puntero, un arrastre desplaza el terreno, y sus propios botones amplían y vuelven al trayecto completo. Ampliado, se recentra en el testigo cada vez que este llega a su borde, para que nunca salga de él
observerPlacingpropiedadSi un clic en el suelo despejado del mapa emite observerplace con { lat, lng } — desactivado por defecto, ya que decir dónde se encontraba el testigo corresponde a la grabación. El editor lo activa y escribe la posición en el cabezal de reproducción
hide-milestonesatributoQuita los momentos con nombre del relato — las marcas a lo largo de la barra, el rótulo que nombra el que se está reproduciendo y los puntos con letra del mapa. Aparecen allí donde una grabación nombra alguno, así que esta es la única manera de indicar lo contrario
toggleMilestones()métodoLo que hace ese botón

Los momentos con nombre y el mapa son las dos únicas cosas que este elemento muestra u oculta por defecto (los momentos visibles, el mapa oculto), y la diferencia es deliberada. Los momentos con nombre de una grabación son sus propias palabras sobre sí misma, así que se muestran allí donde existen; el mapa cuesta peticiones de teselas a un tercero la primera vez que se abre, y no le corresponde a una página gastarlas en nombre de un lector sin decirlo. En ambos casos el lector conserva los dos botones, junto al de pantalla completa — que una página fije un valor por defecto no significa que prohíba lo contrario.

La barra de herramientas y los botones de la esquina solo se muestran mientras el puntero está sobre la imagen, en reproducción o en pausa, o cuando el teclado lleva el foco hasta ellos. Una pantalla táctil, que no tiene puntero con el que pasar por encima, los mantiene visibles.

Con la barra de tiempo enfocada, las teclas funcionan como en un sitio de vídeos: ← retrocede 5 s, → avanza 5 s y Espacio reproduce o pausa. Reproducir o pausar, con una tecla, con el botón o con un clic en la imagen, muestra su símbolo un instante en el centro de la imagen.

Lo que emite

EventoCuándoDónde escucharlo
endedUna vez, cuando la reproducción llega al final sin repetirse en bucle. No al pausar, ni al arrastrar hasta el finalEn cualquier parte: es bubbling y composed, así que sale de <rr0-scene> y de <rr0-sighting> y llega al elemento que pusiste en la página. Así se reproducen varias grabaciones una tras otra
timedisplaychangeCuando los contadores cambian entre la hora del reloj y el tiempo transcurridoEn cualquier parte, igual que arriba
timeupdateEn cada paso de la reproducción y en cada salto, con detail.timeSolo en este elemento. No es bubbling ni composed, así que una página que contiene un <rr0-scene> tiene que llegar a su ufoElement — está pensado para los elementos que lo contienen

Ponerlo en tu página

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

sighting.json es un archivo de avistamiento. O bien, tras npm install @rr0/ufoathome: import "@rr0/ufoathome/scene". El bundle pesa 238 KB comprimido con gzip y registra la etiqueta por sí mismo — no hay nada más que llamar. La presentación de arriba explica qué más supone, y compartir una observación tiene el ejemplo completo, para probarlo y copiarlo.

<rr0-sighting-editor>#

El editor

Una escena (<rr0-scene>) más la barra de herramientas de edición. Ponlo en una página donde la gente deba poder describir o corregir una observación por sí misma.

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

Su lienzo es una superficie de edición, así que enableClickToPlay está desactivado ahí: un clic selecciona y arrastra una forma en lugar de alternar la reproducción. Lo que hacen los ocho grupos de su barra de herramientas está en la página del propio editor.

MiembroTipoQué hace
ufoElementpropiedad (lectura)Da acceso al lienzo, a la línea de tiempo y al trabajo de apariencia
appearancepropiedadCómo será la próxima forma dibujada: { presetId, color, transparency, haloScale, blur, brightness }, siendo presetId "oval" o "polygon" y los demás los campos de forma del mismo nombre. Asignarla solo toma los campos que le des
sightingchangeeventoSe emite tras cada edición — la única señal de que la grabación ha cambiado

Lo que emite

EventoCuándoDónde escucharlo
sightingchangeTras una edición: un campo escrito, un instrumento elegido, una zona horaria deducida, una forma desplazada a lo largo de la línea de tiempoEn este elemento. No hace bubbling, así que escucha en el propio <rr0-sighting-editor> — y luego vuelve a leer su sightingData

Ponerlo en tu página

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

O bien, tras npm install @rr0/ufoathome: import "@rr0/ufoathome/editor". El bundle pesa 293 KB comprimido con gzip y registra la etiqueta por sí mismo — no hay nada más que llamar. La presentación de arriba explica qué más supone, y compartir una observación tiene el ejemplo completo, para probarlo y copiarlo.