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 uncase.jsoncada 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 eventodatechange.
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 esto | 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> |
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 haciendo | Componente | Módulo | gzip |
|---|---|---|---|
| Mostrar un avistamiento ovni — un expediente, un artículo, un informe | <rr0-sighting> | /lib/rr0-sighting.mjs | 249 KB |
| Dejar que alguien describa o corrija uno | <rr0-sighting-editor> | /lib/rr0-sighting-editor.mjs | 293 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.mjs | 238 KB |
| Mostrar un avistamiento dentro de una escena propia, sin barra de herramientas encima | <rr0-scene> | /lib/rr0-scene.mjs | 238 KB |
| No estás seguro | <rr0-sighting> | /lib/rr0-sighting.mjs | 249 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 -->
| Miembro | Tipo | Qué hace |
|---|---|---|
src | atributo | Una 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 |
observerUrls | propiedad | Las 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 |
sightingData | propiedad | Una grabación, asignada directamente — para una página que la tiene en memoria en lugar de en una URL |
scene | propiedad (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-labels | atributo | La 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ónque 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-milestones | atributo | Se transmiten a través del <rr0-scene> compuesto hasta el reproductor que los posee |
start-time | atributo | Dó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-clock | atributo | Dó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-account | atributo | Empieza 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
| Evento | Cuándo | Dónde escucharlo |
|---|---|---|
observerchange | Cuando 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 script | En este elemento. No hace bubbling: escucha en el propio <rr0-sighting> y luego vuelve a leer su sightingData (su descripción, su id) |
recordingissues | Una 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 consola | En 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>
| Miembro | Tipo | Qué hace |
|---|---|---|
src | atributo | URL de una grabación, cargada al conectarse y cada vez que cambia |
sightingData | propiedad | La 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 |
ufoElement | propiedad (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 |
sceneRenderer | propiedad (lectura) | El motor de renderizado 3D, para lo que nada más expone |
show-compass | atributo | Las etiquetas N/NE/E/… alrededor del horizonte. Desactivado por defecto: útil al fijar un rumbo, ruido al mirar |
star-catalog-src / deep-star-catalog-src | atributo | De 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-ratio | atributo | El 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-milestones | atributo | Se 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.
| Miembro | Tipo | Qué hace |
|---|---|---|
src | atributo | URL de una grabación, cargada al conectarse y cada vez que cambia |
sightingData | propiedad | La grabación como objeto simple (véase el formato) — para leerla de nuevo tras editarla, o para asignarla en lugar de usar src |
sighting | propiedad (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étodo | Dicen qué estado se quiere, en lugar de invertir el actual |
togglePlayPause() | método | Lo que hacen el botón, el clic y la barra espaciadora |
playbackState | propiedad (lectura) | "stopped", "playing" o "paused" |
currentTime | propiedad | El cabezal de reproducción, en las unidades propias de la línea de tiempo — no en milisegundos reales, véase positionLabel |
seekableDuration | propiedad (lectura) | El intervalo que puede tomar currentTime |
autoReplayEnabled | propiedad | La repetición en bucle, desactivada por defecto: una reproducción se ejecuta una vez y luego emite ended. Actívala para un bucle |
positionLabel / durationLabel | propiedad (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étodo | Vuelve a leer la duración y repinta — llámalo tras modificar sighting.timeline desde fuera |
canvasElement / renderer | propiedad (lectura) | El <canvas>, y el renderizador que pinta en él |
enableClickToPlay | propiedad | Si 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 |
fullscreenTarget | propiedad | Qué 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-map | atributo | Si 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étodo | Lo 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 |
observerPlacing | propiedad | Si 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-milestones | atributo | Quita 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étodo | Lo 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
| Evento | Cuándo | Dónde escucharlo |
|---|---|---|
ended | Una vez, cuando la reproducción llega al final sin repetirse en bucle. No al pausar, ni al arrastrar hasta el final | En 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 |
timedisplaychange | Cuando los contadores cambian entre la hora del reloj y el tiempo transcurrido | En cualquier parte, igual que arriba |
timeupdate | En cada paso de la reproducción y en cada salto, con detail.time | Solo 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.
| Miembro | Tipo | Qué hace |
|---|---|---|
ufoElement | propiedad (lectura) | Da acceso al lienzo, a la línea de tiempo y al trabajo de apariencia |
appearance | propiedad | Có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 |
sightingchange | evento | Se emite tras cada edición — la única señal de que la grabación ha cambiado |
Lo que emite
| Evento | Cuándo | Dónde escucharlo |
|---|---|---|
sightingchange | Tras una edición: un campo escrito, un instrumento elegido, una zona horaria deducida, una forma desplazada a lo largo de la línea de tiempo | En 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.