<kaleidr-map>, el elemento

<kaleidr-map> es la forma declarativa de montar un producto Kaleidr. Escribes el elemento con atributos y se monta automáticamente al entrar en el documento y se destruye al salir. Lo define kaleidr.js, por lo que la página debe cargar ese script.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

El elemento es un envoltorio ligero: convierte los atributos en opciones y llama a Kaleidr.mount sobre sí mismo. Todo lo que hace el elemento puede hacerse mediante Kaleidr.mount, pero no al revés: el elemento no acepta un objeto de mapa activo ni devuelve el controlador.

Usa el elemento cuando	Usa Kaleidr.mount cuando
La incrustación es HTML estático.	Necesitas el controlador para setCamera, setStyle, setTheme o destroy.
Un CMS o plantilla genera el HTML.	Conectas Chat a tu propio mapa y necesitas la opción map.
Quieres que se limpie automáticamente al eliminarlo del documento.	Un framework controla cuándo montar y desmontar los componentes.

Atributos

Los nombres de atributos usan kebab-case. Las opciones de montaje equivalentes usan camelCase.

Atributo	Opción de montaje	Productos	Obligatorio	Predeterminado	Observado después del montaje	Descripción
product	product	todos	sí	ninguno	no	chat, viewer, editor o tile.
publishable-key	publishableKey	chat, editor, tile	sí, excepto Chat en mapa publicado	ninguno	no	Tu clave kld_pk_…. Viewer no la utiliza.
share-id	shareId	viewer, chat	Viewer: sí	ninguno	no	Viewer: ID del mapa publicado. Chat sin clave: el mapa publicado que proporciona Chat.
map-id	mapId	viewer	no	ninguno	no	Alias de share-id.
style-id	styleId	tile, editor	recomendado en Tile	mapa base predeterminado de la organización; en Editor, después kaleidr-morning	no	ID de estilo o URL de estilo.
map-target	mapTarget	chat	no	ninguno	no	Selector CSS para un elemento Viewer o Tile <kaleidr-map> que controlará el asistente.
contained	contained	chat	no	desactivado	no	Ancla el panel dentro de este elemento, que debe tener posición y dimensiones.
lang	lang	chat	no	valor de <html lang> si es una etiqueta válida; de lo contrario, inglés	no	Idioma de respuesta del panel, como etiqueta BCP 47 (en, ko, pt-BR). Consulta Idioma de Chat.
chat-title	title	chat	no	título propio del panel	no	Título de la cabecera. El atributo es chat-title, no title: el title de HTML muestra información al pasar el ratón.
placeholder	placeholder	chat	no	marcador de posición propio del panel	no	Texto orientativo del campo de entrada.
layout	layout	viewer	no	map	no	bar monta la barra de chat, que también lee chat-title, placeholder, theme y lang, con sus propios valores predeterminados: consulta las opciones del viewer. locator y listings muestran el mapa junto a una lista de una colección de la Biblioteca de lugares: consulta Diseños de lugares. guide abre el chat junto a un mapa de establecimientos: consulta Diseño de guía. live muestra los vehículos y las paradas de hoy: consulta Diseño en vivo.
collection	collection	localizador, anuncios, guía y en vivo de viewer	no	la primera colección del tipo del diseño que dibuja el mapa	no	El identificador de la colección que se lista; en live, el de la colección de Vehículos.
stops	stops	viewer en vivo	no	la primera colección de Paradas que dibuja el mapa	no	El identificador de la colección de Paradas.
filters	filters	localizador y anuncios de viewer	no	todos los filtros de la colección	no	Los filtros para visitantes que se muestran, separados por |: search, category, price, beds, baths, open_now.
card	card	viewer	no	auto	no	Las fichas de lugar compact muestran solo el título, el subtítulo y las acciones.
prompt	prompt	viewer	no	ninguno	no	Pregunta que se plantea a la Kaleidr AI del mapa al abrirse; en una barra de chat, el texto precargado del campo.
prompt-param	promptParam	viewer	no	ninguno	no	Lee prompt de ese parámetro de consulta de la URL de la página, cuando el visitante llegó desde una página del mismo origen.
prompts	prompts	barra de chat de viewer	no	ninguno	no	Preguntas de ejemplo, separadas por |.
accent	accent	barra de chat de viewer	no	#2da84a	no	Un color CSS.
results-url	resultsUrl	barra de chat de viewer	no	ninguno	no	Envía a los visitantes a esa página con ?q=<question>.
center	center	viewer, tile, editor	no	predeterminado del producto	sí	"longitude,latitude", por ejemplo "-0.1276,51.5072".
zoom	zoom	viewer, tile, editor	no	predeterminado del producto	sí	Número. Al montar Viewer y Tile solo se aplica junto con center.
pitch	pitch	viewer, tile, editor	no	predeterminado del producto	sí	Inclinación en grados.
bearing	bearing	viewer, tile, editor	no	predeterminado del producto	sí	Rotación en grados.
theme	theme	chat, editor	no	ninguno	sí (solo afecta a Chat)	Cadena JSON. Chat: propiedades CSS personalizadas. Editor: 17 claves de tema.
flag	enabled	todos	no	ninguno	no	Control del elemento de la puerta de activación.
base	base	todos	no	https://cdn.kaleidr.com	no	Origen de los paquetes. Solo se acepta la CDN de Kaleidr (https://cdn.kaleidr.com), el origen del que se cargó kaleidr.js o el de la página; otros se ignoran con una advertencia. Consulta Sustitución de base.
viewer-base	viewerBase	viewer, tile	no	https://map-embed.kaleidr.com	no	Origen del iframe.
api-base	apiBase	chat, editor, tile	no	https://api.kaleidr.com/inference-api	no	Destino del intercambio de sesión y solicitudes. Debe incluir /inference-api.
tile-base	tileBase	editor	no	https://tile.kaleidr.com	no	Host donde se resuelven los IDs de estilo.

api-key es un alias obsoleto de publishable-key. Los cuatro atributos …-base se usan para probar otros despliegues y no son necesarios en producción.

Atributos booleanos

flag y contained se interpretan como booleanos:

Escrito como	Interpretado como
contained (sin valor), contained=""	verdadero
"true", "1", "yes", "on"	verdadero
"false", "0", "no", "off"	falso
atributo ausente	sin establecer
cualquier otro valor	ignorado, con advertencia en consola

Las palabras no distinguen mayúsculas y minúsculas ni espacios exteriores, por lo que flag="False" también desactiva el elemento. Como un atributo sin valor equivale a verdadero, una plantilla que produzca flag="" lo activa. Escribe false explícitamente.

Atributos numéricos y de cámara

zoom, pitch y bearing se convierten a números. center son dos números separados por coma, primero la longitud. Un valor que no puede convertirse se ignora sin mensaje y se usa el predeterminado del producto.

Atributos después del montaje

El elemento lee sus atributos una vez, al entrar en el documento. Después solo observa cinco:

Atributo modificado	viewer	tile	editor	chat
center, zoom, pitch, bearing	La cámara salta a la nueva vista.	La cámara salta a la nueva vista.	La cámara salta a la nueva vista.	Advertencia en consola; sin efecto.
theme	Advertencia.	Advertencia.	Advertencia. Editor solo lee el tema al montar.	El panel cambia de estilo.
Cualquier otro atributo	Sin efecto.	Sin efecto.	Sin efecto.	Sin efecto.

Un cambio de cámara mediante atributos nunca se anima. Para animar el movimiento, monta mediante Kaleidr.mount y llama a handle.setCamera({ …, duration: 800 }).

Al cambiar un atributo de cámara, el elemento envía todos los atributos de cámara que tiene en ese momento. Si cambias únicamente zoom en un elemento con center, se vuelve a aplicar ese centro.

Para modificar share-id, style-id, publishable-key, product, flag, contained, lang, chat-title o placeholder, sustituye el elemento: elimínalo e inserta otro con los nuevos atributos. En Tile, handle.setStyle permite cambiar el estilo sin volver a montar, pero solo si se montó con Kaleidr.mount.

// Show a different published map in the same place.
const old = document.querySelector('kaleidr-map');
const next = old.cloneNode(false);
next.setAttribute('share-id', 'ANOTHER_MAP_ID');
old.replaceWith(next);

Ciclo de vida

Evento	Acción del elemento
Entra en el documento	Lee atributos y se monta. En Chat, Editor y Tile comienza el intercambio de sesión.
Ya está en el documento antes de cargar kaleidr.js	No hace nada hasta que se carga el script; entonces se monta.
Sale del documento	Destruye el montaje, elimina lo añadido y detiene las renovaciones de sesión.
Vuelve a entrar	Lee otra vez sus atributos y se monta de nuevo, con otro intercambio de sesión.
Se mueve a otro elemento padre	Sale y entra: se destruye y se monta de nuevo.
Falta product o no es uno de los cuatro	Registra [kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile" y no se monta. Establecer después product no hace nada.

Consecuencias:

• Configura los atributos antes de insertar el elemento. Si lo creas con JavaScript, define todas las propiedades y después añádelo. Si lo añades primero, se monta con los valores disponibles entonces.

  const el = document.createElement('kaleidr-map');
  el.setAttribute('product', 'tile');
  el.setAttribute('publishable-key', 'kld_pk_live_…');
  el.setAttribute('style-id', 'kaleidr-night');
  el.style.cssText = 'display:block; height:480px';
  document.getElementById('slot').appendChild(el); // mounts here

• Volver a montar tiene un coste. Un elemento Tile que se monta otra vez consume otra carga de mapa. Editor pierde sus ediciones, y Chat inicia otra conversación. Código que recrea o reordena nodos DOM, como los cambios de una lista en un framework, puede provocarlo inadvertidamente. Consulta Integración con frameworks.

• Un elemento oculto se monta igualmente. display:none no retrasa el montaje: Tile en una pestaña cerrada inicia una sesión.

• El elemento muestra a sus hijos hasta que un mapa los reemplaza. El contenido interior se ve normalmente. Viewer y Tile sustituyen ese contenido por el iframe cuando cargan, así que puede servir como marcador de carga y permanece como alternativa si falla el montaje o está retenido por la puerta de activación. Chat y Editor nunca eliminan los hijos. Déjalo vacío salvo que quieras ese comportamiento.

Dimensiones

<kaleidr-map> usa display:block por defecto, por lo que se le puede dar height:

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="height:480px"></kaleidr-map>

Tres detalles sobre este valor predeterminado:

• Tu propiedad display siempre prevalece. Un estilo en línea, una regla CSS o el atributo hidden la reemplazan. Si pones display:inline, height deja de funcionar.
• No requiere ninguna excepción en tu Política de Seguridad de Contenido. No se define mediante etiqueta <style> ni atributo style, así que funciona aunque se prohíba 'unsafe-inline'.
• Safari anterior a 16.4 no admite ese valor predeterminado. El elemento permanece en línea e ignora width y height. Por eso los ejemplos incluyen display:block en el atributo style: no perjudica en otros navegadores y permite dar dimensiones en los antiguos.

Por eso esta documentación usa:

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

o bien, una vez para todo el sitio:

kaleidr-map { display: block; height: 480px; }

Producto	Comportamiento de dimensiones
viewer, tile	El iframe ocupa el 100 % del ancho. Su altura es el 100 % del elemento si este tiene altura al montar; en caso contrario son 500 píxeles fijos. Se establecen position:relative (si no existe posición en línea) y overflow:hidden en el elemento.
editor	Ocupa el 100 % del ancho y la altura del elemento. Sin altura, no se ve nada.
chat	Sin contained, es una ventana fija arriba a la izquierda de la pantalla, sin importar las dimensiones del elemento. Con contained, queda dentro del elemento, que necesita position:relative (u otro posicionamiento) y dimensiones.

El valor alternativo de 500 píxeles se decide una sola vez, al montar. Si el elemento carecía de altura entonces, el iframe seguirá teniendo 500 píxeles aunque le asignes otra altura más tarde.

Si tu Política de Seguridad de Contenido prohíbe atributos style en línea, dimensiona el elemento mediante una hoja de estilos. La configuración de bloque predeterminada no se ve afectada por esa política.

Matriz del controlador

El elemento no expone ningún controlador. Para llamar a estos métodos, monta mediante Kaleidr.mount, que devuelve uno.

Método	chat	viewer	editor	tile
destroy()	sí	sí	sí	sí
setCamera(camera)	no admitido	sí	sí	sí
setTheme(theme)	sí	no admitido	no admitido	no admitido
setStyle(style)	no admitido	no admitido	no admitido	sí
send(text)	no admitido	sí	no admitido	no admitido
setFilters(filters)	no admitido	sí	no admitido	no admitido
showVehiclesLayer(layer)	no admitido	sí	no admitido	no admitido
clearVehiclesLayer()	no admitido	sí	no admitido	no admitido

Todos los controladores tienen todos estos métodos. Uno marcado como «no admitido» no hace nada al llamarlo y emite una advertencia de consola, sin lanzar excepción. Este comportamiento forma parte del contrato /embed/v1.

Por producto:

• chat: setTheme cambia el estilo del panel. setCamera no se admite porque Chat no posee un mapa: el asistente mueve el mapa al que se conecta cuando responde; tu código puede moverlo mediante la API de la biblioteca de mapas.
• viewer: setCamera mueve el mapa publicado. setFilters establece los filtros para visitantes de un diseño de lugares. showVehiclesLayer dibuja tus propios vehículos en el mapa y clearVehiclesLayer los quita: consulta la capa de vehículos.
• editor: setCamera mueve el mapa del editor. El tema y el mapa base quedan fijados al montar.
• tile: setCamera mueve el mapa y setStyle cambia el mapa base sin remontar.

setCamera acepta { center, zoom, pitch, bearing, duration }. Todos los campos son opcionales, center es [longitude, latitude] y duration se expresa en milisegundos. Los detalles están en kaleidr.js.

Chat y map-target

Chat puede controlar dos tipos de mapa:

• Tu propio mapa (Mapbox GL JS, MapLibre GL JS, Google Maps o Leaflet). No puedes expresar el objeto de mapa como atributo: usa Kaleidr.mount con la opción map. Consulta la referencia de Chat.

• Un elemento Viewer o Tile de Kaleidr en la misma página. Apunta map-target a él usando un selector CSS:

  <div style="position:relative">
    <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
                 style-id="kaleidr-morning"
                 style="display:block; height:480px"></kaleidr-map>
  
    <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
                 map-target="#basemap"
                 style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
  </div>

  No importa el orden de los dos elementos. Chat busca su destino cuando lo necesita.

Sin map ni map-target, Chat es un panel sin mapa.

El contenedor y el estilo del elemento de Chat colocan el panel sobre el mapa. Cada declaración se explica en Temas y disposición. Chat en un mapa publicado se explica en Chat en un mapa publicado.

Mensajes de consola

Mensaje	Significado
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	Falta product o está mal escrito; el elemento no se monta.
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. Use <attribute>="true" / "false" (or omit it).	flag o contained tiene un valor no admitido. La advertencia identifica el atributo: flag="…" o contained="…".
[kaleidr] base "<value>" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.	El atributo base señala un origen prohibido. El producto se carga desde la CDN predeterminada.
[kaleidr] embed is disabled — this mount passed `enabled: false` (or `flag="false"`). …	La configuración flag retiene el montaje. Sustituye el elemento sin ese valor para montarlo.
[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. …	Se cambió un atributo de cámara en Chat.
[kaleidr] setTheme() is not supported on product "<product>" — the call is a no-op. …	Se cambió theme en Viewer, Tile o Editor.

Los fallos al montar se registran como [kaleidr:<product>] …. Están enumerados en kaleidr.js.

No disponible

• Eventos. El elemento no emite eventos DOM.
• Propiedades o métodos. El elemento no tiene setCamera, propiedad handle ni promesa ready.
• Nueva lectura de atributos. Excepto los cinco observados, los cambios posteriores al montaje se ignoran.

Relacionado

• El cargador kaleidr.js
• Integración con frameworks
• Viewer, Tile, Editor y Chat