Personalización

<mapvx-website> se renderiza en el DOM normal de tu página, no en un Shadow DOM, e incluye una hoja de estilos global obligatoria, styles.css. Esta página explica qué puedes personalizar (dos colores, la fuente y la cuadrícula de tarjetas) y cómo se afectan entre sí el CSS del componente y el de tu página.

Variables CSS

:root {
  --mapvx-secondary-orange: #b41500; /* valor por defecto #EE5845 */
  --mapvx-secondary-blue: #053a96; /* valor por defecto #2C57A0 */
}

Para cambiar los colores en tiempo de ejecución, define las variables en el elemento raíz. La interfaz se actualiza de inmediato; la línea y el ícono de la ruta toman el nuevo color la próxima vez que se dibuja una ruta.

document.documentElement.style.setProperty('--mapvx-secondary-orange', '#b41500')

Estas dos variables son la única API de temas admitida. Ten en cuenta que:

• Los banners “Deals + Events” del perfil de un lugar usan, para el texto y el borde, el valor de color del primer atributo style de su contenido, o #EE5845 si no lo hay. No siguen a --mapvx-secondary-orange.
• No hay tema oscuro. El componente pinta un fondo blanco y texto oscuro sin importar el esquema de color del visitante.
• styles.css también define más de 100 propiedades personalizadas --definitions-* en :root (colores, valores abreviados de font, una sombra), y la cuadrícula de tarjetas usa --card-width y --card-gap. Son internas: pueden cambiar de nombre o desaparecer en cualquier versión. Para cambiar la cuadrícula, usa en su lugar los atributos card-width y rows-per-page.

Fuentes

El componente no carga fuentes web: styles.css no tiene reglas @font-face ni URLs de fuentes. Su texto usa 'Open Sans', sans-serif, así que se ve en Open Sans solo si tu página carga esa fuente o si el sistema del visitante la tiene; si no, se usa la sans-serif genérica del navegador.

Tienes dos opciones:

• Cargar Open Sans tú mismo. El componente usa los pesos 400, 600 y 700. Por ejemplo, desde Google Fonts (o aloja esos mismos archivos en tu servidor):

  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
  <link
    href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600;700&display=swap"
    rel="stylesheet"
  />

• Usar la fuente de tu página. Con inherit-font-family="true" el componente usa la font-family que hereda de <mapvx-website> y sus ancestros:

  <style>
    mapvx-website {
      display: block;
      width: 100%;
      font-family: 'Inter', system-ui, sans-serif;
    }
  </style>
   
  <mapvx-website
    api-key="YOUR_API_KEY"
    institution-id="YOUR_INSTITUTION_ID"
    inherit-font-family="true"
  ></mapvx-website>

  Solo el texto exacto "true" lo activa; un atributo inherit-font-family sin valor cuenta como falso. Consulta atributos booleanos.

En ambos casos solo cambia la familia tipográfica. Los tamaños y pesos se mantienen como están diseñados y se definen en píxeles, así que el font-size raíz de tu página no cambia el tamaño del texto del componente. Las etiquetas del mapa las dibuja el motor del mapa con sus propios glifos, así que ninguna de las dos opciones las cambia. Los íconos son SVG en línea y no necesitan una fuente de íconos.

El texto dentro de muchos botones del componente, como las tarjetas de lugares, los botones Back y los controles de la ruta, no tiene una familia tipográfica propia. Los navegadores les dan a los botones su propia fuente por defecto (por ejemplo, Arial en Chrome para Windows), así que ese texto no se ve ni en Open Sans ni en la fuente de tu página, con o sin inherit-font-family, a menos que tu CSS ya defina font-family: inherit en los botones, como hacen muchos resets de CSS. Para que siga la fuente del componente, agrega:

mapvx-website button {
  font-family: inherit;
}

Tamaño

mapvx-website {
  display: block;
  width: 100%;
}

• Ancho. El componente ocupa todo el ancho de su contenedor. <mapvx-website> en sí no tiene estilos por defecto, así que es display: inline. Dale display: block y, dentro de una fila flex o de una pista de grid que se ajusta a su contenido, un ancho explícito: el componente mide su propio ancho para su diseño y, sin uno, puede quedar con ancho cero.
• Alto. El alto lo determina el contenido, así que no necesitas definirlo. No le des al elemento un alto fijo como 100vh: el mapa no se estira para llenarlo, y el contenido más alto que ese valor se desborda fuera de la caja del elemento.

Las áreas de mapa tienen estos altos, según el ancho del componente:

La vista de cuadrícula no tiene mapa; su alto depende del número de filas y del tamaño de las tarjetas.

Al abrir el perfil de un lugar, tu página se desplaza con suavidad para que el borde superior de <mapvx-website> quede en el borde superior del viewport. Si tu página tiene un encabezado fijo o sticky, agrega scroll-margin-top para que el encabezado no tape el componente:

mapvx-website {
  display: block;
  width: 100%;
  scroll-margin-top: 80px; /* alto de tu encabezado fijo */
}

Comportamiento responsive

El diseño se adapta al ancho del componente, no al del viewport: usa container queries  sobre su propio contenedor. Una columna de 600px en una pantalla de escritorio recibe el diseño angosto, y un componente a todo el ancho en una tablet grande recibe el diseño ancho.

La cantidad de tarjetas por página se calcula al renderizar la lista. No se recalcula al cambiar el tamaño de la ventana, solo cuando la lista se vuelve a mostrar (por ejemplo, al cambiar entre la vista de cuadrícula y la de mapa, o al volver desde un lugar) o cuando cambian card-width o rows-per-page. Prueba el componente con el ancho que tendrá en tu página.

Opciones de diseño

Dos atributos definen la cuadrícula de tarjetas. Ambos se pueden cambiar en tiempo de ejecución; los detalles de interpretación están en atributos numéricos.

<mapvx-website
  api-key="YOUR_API_KEY"
  institution-id="YOUR_INSTITUTION_ID"
  card-width="280"
  rows-per-page="3"
></mapvx-website>

Las tarjetas por página son floor((ancho de la lista + gap) / (ancho de tarjeta + gap)) × rows-per-page, donde gap es el espacio entre columnas: 13px en la vista de cuadrícula y 8px en la vista de mapa. Por ejemplo, una cuadrícula de 1200px de ancho con card-width="280" tiene 4 columnas de unos 290px cada una, así que rows-per-page="3" muestra 12 tarjetas por página. Con los valores por defecto, la misma cuadrícula muestra 4 columnas y 8 tarjetas por página.

• La misma configuración se aplica a la vista de cuadrícula, a la lista de tarjetas de la vista de mapa y a los resultados de búsqueda.
• En la vista de mapa, con componentes de más de 1024px, la lista ocupa la mitad del ancho, así que en cada fila caben menos tarjetas y hay más páginas.
• card-width reemplaza ambos valores por defecto, incluido el de 170px para anchos angostos, así que un valor grande puede dejar una sola columna en teléfonos.
• Con 640px o menos, la vista de mapa muestra las tarjetas de la página actual en una sola fila con desplazamiento horizontal.

Aislamiento de estilos

El componente no usa Shadow DOM. Su marcado forma parte de tu página, dentro de <mapvx-website>.

• Los estilos del componente se quedan adentro. Se inyectan en tiempo de ejecución como elementos <style> en <head> y se limitan con atributos generados, así que no afectan a tus elementos. Si tu sitio envía una Content Security Policy, estas etiquetas necesitan 'unsafe-inline' o un nonce: consulta Seguridad y privacidad.
• Tus estilos llegan adentro. Las reglas con selectores de elemento o universales (button, input, a, img, de h1 a h3, *) también se aplican a los elementos del componente. Las reglas propias del componente suelen ganar en las propiedades que definen, porque una clase más el atributo de alcance es más específica que un selector de elemento solo. Todas las demás propiedades vienen de tu regla, y las reglas más específicas o con !important se imponen al componente. Las propiedades heredables como color, letter-spacing o text-transform también llegan desde los ancestros donde el componente no las define.

Los orígenes típicos son los resets y frameworks de CSS (*, ::before, ::after con box-sizing) y los estilos globales del sitio para button, input, a o títulos. Limita esas reglas para que excluyan al componente con :not():

/* Antes: también cambia cada botón dentro de <mapvx-website> */
button {
  border-radius: 999px;
  text-transform: uppercase;
}
 
/* Después: excluye todo lo que está dentro de <mapvx-website> */
button:not(mapvx-website *) {
  border-radius: 999px;
  text-transform: uppercase;
}
 
/* Resets universales: :where() mantiene la especificidad en cero, como el * original */
:where(*:not(mapvx-website *)),
:where(*:not(mapvx-website *))::before,
:where(*:not(mapvx-website *))::after {
  box-sizing: border-box;
}

O limita los estilos de tu contenido a un contenedor y coloca el componente fuera de él:

<main class="article">
  <!-- Los estilos de tu contenido apuntan a .article h3, .article a, .article button -->
</main>
 
<section class="directory">
  <mapvx-website api-key="YOUR_API_KEY" institution-id="YOUR_INSTITUTION_ID"></mapvx-website>
</section>

No personalices el interior del componente. Sus nombres de clase, su estructura de DOM y los tokens --definitions-* son internos y pueden cambiar entre versiones; por ejemplo, la clase contenedora de los marcadores del mapa pasó de .lazarillo-marker a .mapvx-marker en la 1.0.0 (consulta migración desde 0.x). La personalización admitida se limita a las dos variables CSS y los atributos, además de la regla de font-family para botones de Fuentes.

Mantén <mapvx-website> en el documento principal y no dentro de un shadow root propio: las reglas de styles.css no llegan al interior de los shadow trees. Si tus estilos siguen apareciendo dentro del componente, consulta Solución de problemas.

Estilos globales

styles.css es obligatorio (consulta contenido del paquete) y se aplica a todo el documento, no solo al componente. Contiene los tokens de diseño en :root, los estilos de MapLibre GL, los del SDK de mapas de MapVX, el CSS base de Font Awesome 7 y las reglas de marcadores y banners. No tiene reglas para html, body ni selectores de elemento solos, así que no cambia tu tipografía. Estas partes pueden afectar al resto de tu página:

/* .store-locator-map es el contenedor de tu propio mapa */
.store-locator-map .maplibregl-control-container {
  display: block;
}

Otras cosas que debes evitar en tu página:

• Los ids map, current-location-marker, route-icon y los que terminan en -marker: el componente crea elementos con esos ids, así que una regla #map en tu CSS también se aplica al mapa del componente.
• Propiedades personalizadas que empiecen con --definitions-.
• Una segunda copia del CSS base de Font Awesome con otra versión. Además de styles.css, el componente inyecta el CSS base de Font Awesome en tiempo de ejecución, en una etiqueta <style id="fa-auto-css"> que inserta antes del primer <style> o <link> de <head>. Si tu página carga otra versión de Font Awesome, las reglas de ambas versiones se aplican a los mismos nombres de clase y, donde difieren, gana la que aparece al final. Consulta Solución de problemas.

Si un mapa MapLibre propio perdió sus controles, consulta también Solución de problemas.