Integración
La versión recomendada es 2.1.3. Corrige la navegación de los accesos cuando el navegador usa el panel sin Popover. Las versiones publicadas 2.1.0, 2.1.1 y 2.1.2 se conservan inmutables.
La biblioteca canónica es C:\Users\ASUS\Documents\ZafiroxShared. Sus paquetes @zafirox/shared-core, @zafirox/shared-angular y @zafirox/shared-browser contienen contratos, el componente original y su cargador. sdkSite distribuye los artefactos generados de la versión CDN 2.1.3.
import { mountZafiroxTopbar } from '@zafirox/shared-browser';
const topbar = await mountZafiroxTopbar(document.querySelector('#navigation'), {
brand: false,
mainOrigin: 'https://joyeriazafirox.com',
slots: {
left: { route: '/', label: 'Volver a ZAFIROX', icon: 'arrow_back', policy: 'public-home' },
search: { kind: 'public-catalog' },
},
});
// Al desmontar la vista:
// topbar.destroy();El mismo export se distribuye mediante la ruta versionada /cdn/2.1.3/zafirox-topbar.js. brand: false omite la marca cuando la tarjeta ya muestra el logo. setInputs actualiza items, menuOpen, contextLabel, accessState y slots. El contrato expone eventos de apertura, cierre, activación, reintento, navegación y tema. La búsqueda conserva sugerencias, imagen, categoría, estados y reintento; carga el índice al recibir foco y busca localmente. Los resultados completos enlazan a /search?q=....
Una implementación y adaptadores de entorno
El módulo zafirox.desktop-topbar monta la misma clase DesktopTopbarComponent, plantilla y CSS del paquete Angular neutral. provideZafiroxModules() registra el adaptador nativo de Angular, que reutiliza el inyector, router y políticas reales del consumidor. Ese adaptador tiene prioridad sobre el montaje genérico. Los puertos de aplicación conservan la autoridad de identidad y permisos.
El SDK consulta el registro de capacidades Symbol.for('zafirox.modules.adapters.v1'). Otros frameworks pueden registrar un adaptador tipado con prioridad; sin adaptador, el cargador utiliza el bundle AOT del mismo componente. Un documento Angular sin provider recibe una indicación para instalarlo. Se identifica el entorno del navegador; el lenguaje del servidor que entregó el HTML no determina el montaje.
components-provenance.json registra las fuentes y la entrada compilada que comparten ambos montajes. Su SHA-256 verificado es 7c6a68c543132ebec27844f91ed7897ea40580238c568c03ff9ea768c97248cc. La herramienta tools/verify-angular-consumer.mjs --consumer-root <rutaAngular> comprueba la identidad del paquete instalado, el tarball, la entrada genérica y las dependencias.
Preferencia visual
El contrato zafirox.presentation.theme.v1 conserva versión 1, preferencia light, dark, system o classic y fecha savedAt. Gana el registro válido más reciente; la sincronización conserva su fecha. La cookie segura comparte únicamente esta preferencia entre los dominios autorizados. Los servicios y tokens oficiales gobiernan el componente y el host; el evento zafirox:themechange permite sincronizar la tarjeta y sus variantes de marca.
Distribución y estilos
tools/build-distribution.mjs en ZafiroxShared genera los paquetes propios, el CDN compatible y la copia de bienvenida. CSS y tokens globales se sirven desde /assets/zafirox-topbar-2.1.3.css. La fuente original y su licencia están en los paquetes y en el CDN versionado; bienvenida las carga localmente. stylesUrl: false permite que el consumidor incluya esos estilos previamente. El consumidor configura los orígenes de scripts, estilos y fuentes admitidos. La distribución mantiene los canales y versiones ya publicados.
Atlas público en un host del mismo origen
El montaje genérico admite catalogAtlasUrl: '/api/catalog/atlas/' cuando el consumidor sirve un transporte público del atlas desde su propio origen. Se exige HTTPS, mismo origen y ausencia de credenciales, query y fragmento; HTTP sólo se admite en localhost/127.0.0.1/[::1] para desarrollo. Esta opción sólo cambia la descarga del atlas. Productos, imágenes y resultados de búsqueda conservan sus URLs oficiales de tienda. Angular nativo configura el mismo puerto tipado PUBLIC_STORE_CONFIG mediante su propio inyector.
Bienvenida ofrece un endpoint PHP fijo que consulta exclusivamente el atlas público de tienda sin reenviar cookies, autorización u Origin. No es un proxy de URL arbitraria. El buscador compartido conserva el contrato v1, validación, single-flight, sugerencias y reintento originales. El adaptador cambia sólo el transporte: la clase, plantilla y CSS del componente AOT son los mismos.
Sin una preferencia explícita válida, el tema inicial es claro incluso si el dispositivo usa oscuro. Las elecciones dark, system y classic conservan su comportamiento y la fecha guardada. La entrada AOT compartida del componente conserva SHA-256 7c6a68c543132ebec27844f91ed7897ea40580238c568c03ff9ea768c97248cc.
La ruta versionada es /cdn/2.1.3/zafirox-topbar.js; los canales v1, v2 y latest conservan sus versiones previas. La versión explícita identifica los artefactos de esta integración sin promover otros canales.
Bienvenida consume su grafo ESM desde un directorio identificado por versión y hash del runtime, por ejemplo shared/zafirox-topbar-2.1.3-<hash>/. El HTML revalida el documento y cambia el identificador del entry al actualizar; no se requiere borrar el caché del navegador para recibir una release nueva.