@kaufmann-lab/ui 0.1.17 → 0.1.19

package/types/kaufmann-lab-ui-map.d.ts

@@ -0,0 +1,631 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Provider } from '@angular/core';
+import { IconName } from '@kaufmann-lab/ui/core';
+
+/**
+ * Motor de mapas configurado a nivel app, no por uso — mismo criterio que
+ * `API_CONFIG` en `packages/api-client` de `route-assistance-monorepo`: el
+ * access token de Mapbox es un dato de despliegue (cada app/entorno tiene
+ * el propio), no algo que cada `<kf-map>` deba repetir.
+ */
+interface MapConfig {
+    /** Access token público de Mapbox (`pk.*`) de la cuenta del proyecto que consume la librería. */
+    accessToken: string;
+    /**
+     * Estilo de Mapbox Studio propio del cliente, si lo tiene. Cuando se
+     * define, gana siempre sobre `theme()` del componente — un estilo de
+     * marca custom no tiene una variante "light"/"dark" que elegir, ya viene
+     * resuelto. Sin esto, `kf-map` usa el estilo `light-v11`/`dark-v11` de
+     * Mapbox según `theme()`.
+     */
+    styleUrl?: string;
+}
+declare const MAP_CONFIG: InjectionToken<MapConfig>;
+/**
+ * `provide*` idiomático (mismo patrón que `provideHttpClient`/`provideRouter`)
+ * para inyectar una sola vez en `app.config.ts` de cada app consumidora:
+ *
+ *   providers: [provideMapConfig({ accessToken: 'pk.xxx' })]
+ */
+declare function provideMapConfig(config: MapConfig): Provider;
+
+/**
+ * Vocabulario de temas de `kf-map`, separado de `MapView.ts` para que
+ * `MapThemePicker` (el panel flotante del control `mapStyle`) pueda
+ * importarlo sin crear un ciclo `MapView → MapControls → MapThemePicker →
+ * MapView`.
+ *
+ * `streets`/`satellite`/`outdoors` se suman a los `light`/`dark`
+ * originales — los 3 IDs de estilo (`streets-v12`, `satellite-streets-v12`,
+ * `outdoors-v12`) están confirmados contra la cuenta/token real del
+ * ecosistema: la API de estilos de Mapbox es por cuenta, no por versión de
+ * `mapbox-gl`, así que cualquier duda se resuelve probando contra el token
+ * real, no leyendo el número de versión instalado.
+ */
+type MapTheme = 'light' | 'dark' | 'streets' | 'satellite' | 'outdoors';
+declare const STYLE_BY_THEME: Record<MapTheme, string>;
+/** Orden fijo en que `MapThemePicker` lista las 5 opciones — predecible
+ * (siempre el mismo orden en toda pantalla que use el picker), no importa
+ * cuál esté activa. */
+declare const THEME_ORDER: MapTheme[];
+/** Nombre en español de cada tema, para el `aria-label`/label del control
+ * `mapStyle` y las opciones del picker — anuncia qué tema rige HOY o qué
+ * tema se está por elegir, no solo "otro tema distinto". */
+declare const THEME_LABEL: Record<MapTheme, string>;
+
+/**
+ * Cada pieza es independiente entre sí — agregar/sacar un `MapControlKind`
+ * de `controls` en `kf-map` no reacomoda ni afecta a los demás. Array vacío
+ * (default de `kf-map`) es "ningún control": opt-in explícito del
+ * consumidor, nunca activado por default (ver JSDoc de `controls` en
+ * `MapView.ts`).
+ *
+ *   zoom       — botones +/- reales (`map.zoomIn()`/`zoomOut()`).
+ *   fullscreen — expandir/contraer el mapa (Fullscreen API nativa).
+ *   mapStyle   — ciclar entre los temas de `MapTheme`.
+ *   recenter   — re-ejecuta el encuadre a markers/route bajo demanda.
+ *   cluster    — togglear agrupamiento nativo de markers cercanos.
+ *   follow     — la cámara sigue al marker `live` mientras se mueve.
+ */
+type MapControlKind = 'zoom' | 'fullscreen' | 'mapStyle' | 'recenter' | 'cluster' | 'follow';
+/**
+ * Barra de controles flotantes de `kf-map` — pieza puramente presentacional,
+ * sin estado propio: todo lo que sabe se lo pasa `MapView` por input, todo
+ * lo que hace lo reporta por output para que `MapView` (única dueña del
+ * `Map` de Mapbox) decida qué hacer. Vive en la misma carpeta que `MapView`
+ * a propósito (mismo criterio que `DropdownItem`/`DropdownPanel` con
+ * `Dropdown`): el acoplamiento es real, no de nombre — no tiene sentido
+ * fuera de un `kf-map` que la controle.
+ *
+ * Un solo stack vertical, siempre en la esquina superior derecha del mapa
+ * (fijado por `MapView.css`, no acá): es donde ya vivía el `NavigationControl`
+ * de Mapbox que este componente reemplaza, y la atribución obligatoria de
+ * Mapbox (`AttributionControl`, nunca oculta) vive abajo-derecha — un solo
+ * stack evita que dos grupos floten en esquinas distintas y compitan por
+ * espacio en un mapa `size="sm"` de 200px de alto.
+ *
+ * El stack no es una lista continua de botones idénticos: cada grupo lógico
+ * es su propia "card" flotante (`kf-radius-md`+`kf-shadow-md`+fondo blanco,
+ * ver `.kf-map-controls__group` en `MapControls.css`), separadas entre sí
+ * por el `gap` del `:host` — mismo lenguaje ya verificado visualmente en
+ * `route-assistance-monorepo/design/mockups/operations-final.html`
+ * (`.map__ctrl-group`). Orden fijo de arriba a abajo, independiente del
+ * orden en el array `controls` del consumidor (para que dos pantallas que
+ * piden los mismos controles en distinto orden se vean IGUAL):
+ *
+ *   1. zoom — magnificación (par +/-, unido por un divisor, sin gap entre sí).
+ *   2. cámara — recenter + follow (posición de la cámara).
+ *   3. datos — cluster (densidad de los markers, eje distinto de cámara).
+ *   4. chrome — mapStyle + fullscreen (nada del mapa en sí).
+ *
+ * Cada grupo usa `@if` sobre AL MENOS UNO de sus controles (ej. el grupo de
+ * cámara aparece con solo `recenter`, solo `follow`, o ambos) — agregar o
+ * sacar un control nunca reacomoda ni depende de los demás grupos.
+ *
+ * Todos los botones siguen siendo `kf-button[variant=surface][shape=circle]`
+ * — sin tocar `Button.ts`: el fondo/sombra propios de `surface` se anulan
+ * SOLO dentro de un `.kf-map-controls__group` vía una custom property CSS
+ * (ver el comentario junto a esa clase en `MapControls.css` sobre por qué
+ * eso sí atraviesa la encapsulación de Angular y un selector normal no).
+ */
+declare class MapControls {
+    readonly controls: _angular_core.InputSignal<MapControlKind[]>;
+    readonly clusterActive: _angular_core.InputSignal<boolean>;
+    readonly followActive: _angular_core.InputSignal<boolean>;
+    /** Sin ningún marker `live`, togglear "seguir" no tendría ningún efecto
+     * visible — se deshabilita en vez de dejar un botón que parece no hacer nada. */
+    readonly canFollow: _angular_core.InputSignal<boolean>;
+    readonly isFullscreen: _angular_core.InputSignal<boolean>;
+    /** Nombre en español del tema actualmente resuelto (ej. "Calles"), para
+     * anunciar en el `aria-label` del botón de estilo qué se está por perder,
+     * no solo que "algo" va a cambiar. */
+    readonly styleLabel: _angular_core.InputSignal<string>;
+    /** Tema resuelto HOY (`light|dark|...`) — a diferencia de `styleLabel`
+     * (ya traducido a texto), esto es lo que `MapThemePicker` necesita para
+     * marcar la opción activa. */
+    readonly activeTheme: _angular_core.InputSignal<MapTheme>;
+    readonly zoomIn: _angular_core.OutputEmitterRef<void>;
+    readonly zoomOut: _angular_core.OutputEmitterRef<void>;
+    readonly recenter: _angular_core.OutputEmitterRef<void>;
+    readonly followToggle: _angular_core.OutputEmitterRef<void>;
+    readonly clusterToggle: _angular_core.OutputEmitterRef<void>;
+    /** Reemplaza al viejo `styleCycle` (ciclado de un click): ahora el botón
+     * `mapStyle` abre `MapThemePicker` y este output reporta la elección real
+     * hecha ahí. */
+    readonly themeSelect: _angular_core.OutputEmitterRef<MapTheme>;
+    readonly fullscreenToggle: _angular_core.OutputEmitterRef<void>;
+    /** Visibilidad del panel de temas — estado puramente de UI (abierto o no),
+     * no de negocio: `MapView` no necesita saberlo, así que vive acá y no
+     * rompe el criterio de "sin estado propio" del resto de la clase (ver
+     * JSDoc). Se cierra solo (click afuera/Escape) vía `kf-dropdown`, y acá
+     * además al elegir un tema. */
+    protected readonly mapStyleOpen: _angular_core.WritableSignal<boolean>;
+    protected onThemeSelect(theme: MapTheme): void;
+    protected readonly hasZoom: _angular_core.Signal<boolean>;
+    protected readonly hasRecenter: _angular_core.Signal<boolean>;
+    protected readonly hasFollow: _angular_core.Signal<boolean>;
+    protected readonly hasCluster: _angular_core.Signal<boolean>;
+    protected readonly hasMapStyle: _angular_core.Signal<boolean>;
+    protected readonly hasFullscreen: _angular_core.Signal<boolean>;
+    /** El grupo "cámara" (card) aparece con solo `recenter`, solo `follow`, o
+     * ambos — ver JSDoc de la clase sobre por qué cada `@if` de grupo cubre
+     * "al menos uno de sus controles" en vez de un control puntual. */
+    protected readonly hasCamera: _angular_core.Signal<boolean>;
+    protected readonly hasChrome: _angular_core.Signal<boolean>;
+    /**
+     * Texto corto que revela cada botón en hover/foco vía `[kfTooltip]` (ver
+     * `MapControls.html` — la librería ya resuelve este patrón con
+     * `TooltipDirective`, no con CSS a mano) — la misma acción que ya describe
+     * `ariaLabel`, condensada para caber en una píldora en vez de leerse como
+     * oración completa. No reemplaza `ariaLabel` (que sigue siendo la fuente
+     * real para lectores de pantalla): esto es SOLO visual, para quien puede
+     * ver el mapa pero no sabe qué hace un ícono suelto.
+     */
+    protected readonly followLabel: _angular_core.Signal<"Dejar de seguir" | "Seguir">;
+    protected readonly clusterLabel: _angular_core.Signal<"Desagrupar" | "Agrupar">;
+    protected readonly mapStyleLabel: _angular_core.Signal<string>;
+    protected readonly fullscreenLabel: _angular_core.Signal<"Salir de pantalla completa" | "Pantalla completa">;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MapControls, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MapControls, "kf-map-controls", never, { "controls": { "alias": "controls"; "required": false; "isSignal": true; }; "clusterActive": { "alias": "clusterActive"; "required": false; "isSignal": true; }; "followActive": { "alias": "followActive"; "required": false; "isSignal": true; }; "canFollow": { "alias": "canFollow"; "required": false; "isSignal": true; }; "isFullscreen": { "alias": "isFullscreen"; "required": false; "isSignal": true; }; "styleLabel": { "alias": "styleLabel"; "required": false; "isSignal": true; }; "activeTheme": { "alias": "activeTheme"; "required": false; "isSignal": true; }; }, { "zoomIn": "zoomIn"; "zoomOut": "zoomOut"; "recenter": "recenter"; "followToggle": "followToggle"; "clusterToggle": "clusterToggle"; "themeSelect": "themeSelect"; "fullscreenToggle": "fullscreenToggle"; }, never, never, true, never>;
+}
+
+type MapSize = 'sm' | 'md' | 'lg' | 'full';
+type MapVariant = 'interactive' | 'preview';
+/** Vocabulario semántico único de tono, compartido con `TextTone`/`StatTileTone`. */
+type MapMarkerTone = 'neutral' | 'ok' | 'warn' | 'error' | 'info';
+interface MapLatLng {
+    lat: number;
+    lng: number;
+}
+/**
+ * Botón de acción real dentro de `MapMarker.popup` — cada click emite
+ * `markerAction` con su `key` (nunca el `label`, ver JSDoc de `popup` más
+ * abajo). `icon` es OPCIONAL a propósito: no romper a los consumidores que
+ * ya usaban `actions` sin él (era el único campo hasta esta ronda).
+ *
+ * La jerarquía visual entre acciones NO es un campo aparte (`variant`) sino
+ * la POSICIÓN en el array: la primera acción se renderiza con estilo
+ * prominente (fill, mismo peso que `kf-button[variant=primary]`, el
+ * default del botón); el resto con estilo discreto (mismo peso que
+ * `kf-button[variant=ghost]` — ver el ejemplo de `Modal` con
+ * `variant="ghost"` para "Cancelar" junto a un primary implícito). Un
+ * consumidor con una sola acción no necesita pensar en esto: esa acción ya
+ * es "la primera".
+ */
+interface MapPopupAction {
+    key: string;
+    label: string;
+    /** Ícono líder del catálogo de `kf-icon` — sin esto, la acción se ve solo
+     * con texto (compatibilidad con `actions` ya declarado sin `icon`). */
+    icon?: IconName;
+}
+interface MapMarker {
+    position: MapLatLng;
+    /** Sin `icon`, cae en `map-pin` — el pin genérico del catálogo. Se
+     * ignora cuando el control `cluster` está activo (ver JSDoc de
+     * `controls` — el clustering nativo resuelve por capas WebGL, no por
+     * DOM, y ahí no hay dónde montar un `kf-icon`). */
+    icon?: IconName;
+    tone?: MapMarkerTone;
+    /** Nombre accesible del marker (`aria-label`/`title`) — no abre un popup. */
+    label?: string;
+    /**
+     * Identificador propio del consumidor (ej. el id del ticket/vehículo que
+     * representa) — sin esto el marker no es clickeable: `kf-map` no tiene
+     * forma de reportar "se hizo click en ESTE marker" sin algo que
+     * identificarlo de vuelta hacia `markerSelect`. Opcional a propósito: un
+     * mapa puramente decorativo (ej. la vista previa de `variant="preview"`)
+     * no necesita que sus markers respondan a nada.
+     */
+    id?: string;
+    /**
+     * Marca este marker como el punto que sigue la cámara cuando el control
+     * `follow` está activo — ej. la posición en tiempo real de un vehículo o
+     * técnico. Genérico a propósito (no `isVehicle` ni ningún nombre atado al
+     * dominio de un portal): `@kaufmann-lab/ui` no sabe qué es un "vehículo",
+     * solo que ALGÚN marker es el que se sigue. Si más de un marker lo marca,
+     * se sigue el primero en `markers()`. Distinto de la geolocalización del
+     * propio dispositivo (`navigator.geolocation`, fuera de alcance): esto
+     * sigue un dato que el consumidor ya tiene, no ubica al usuario.
+     */
+    live?: boolean;
+    /**
+     * Mini-card que aparece al hover/foco de este marker — solo si el marker
+     * tiene `id` (ver JSDoc de arriba): sin `id` el marker no es clickeable ni
+     * enfocable, así que no habría forma de revelarla por teclado.
+     *
+     * `actions` son botones REALES (no el viejo `ctaLabel` de texto plano sin
+     * acción): cada click emite `markerAction` con su `key` — nunca el
+     * `label`, que es solo texto de UI y puede repetirse con significados
+     * distintos entre consumidores — y detiene la propagación del click para
+     * no disparar además `markerSelect` sobre el marker completo (ver
+     * `buildMarkerPopup()`).
+     *
+     * Vocabulario genérico a propósito (`title`/`description`/`details`/
+     * `actions`, no `folio`/`cliente`/`verTicket`): esta librería no sabe qué
+     * es un "ticket" — el caso de uso real (folio+cliente+estado+SLA+acciones)
+     * es responsabilidad de quien arma cada `MapMarker`.
+     */
+    popup?: {
+        title: string;
+        description?: string;
+        /** Pares clave/valor extra (ej. estado + SLA) — se listan debajo de `description`. */
+        details?: {
+            label: string;
+            value: string;
+        }[];
+        /** Botones de acción reales — ver JSDoc de `MapPopupAction`. */
+        actions?: MapPopupAction[];
+    };
+}
+/**
+ * Mapa con motor real de Mapbox GL JS — decisión de producto ya cerrada
+ * (comparación de 6 proveedores). El access token vive a nivel app, no por
+ * uso: ver `provideMapConfig` en `map-config.ts` (mismo criterio que
+ * `API_CONFIG` de `packages/api-client`), inyectado una vez en
+ * `app.config.ts` de cada app consumidora.
+ *
+ * `size` (`sm|md|lg` alturas fijas, `full` llena el contenedor padre) NO
+ * hace step-down por viewport como `kf-page-header`: ese mecanismo existe
+ * ahí porque un tamaño de FUENTE fijo se corta en pantallas chicas; una
+ * caja de mapa no tiene ese problema — el canvas de Mapbox ya es
+ * responsive dentro de cualquier tamaño de contenedor. Lo que sí hace
+ * falta (y que el header no necesita) es un `ResizeObserver` real: Mapbox
+ * no se entera solo de que su contenedor cambió de tamaño (un layout que
+ * colapsa un sidebar, un cambio de orientación) — hay que llamar
+ * `map.resize()` a mano cuando el contenedor cambia (mismo motivo por el
+ * que `fullscreenchange` también llama `resize()`, ver `onFullscreenChange`).
+ *
+ * `variant` es un eje ortogonal a `size` (mismo criterio que `variant` +
+ * `tone` en `kf-badge`): `interactive` trae la posibilidad de controles
+ * flotantes reales (ver `controls`); `preview` (`interactive: false` de
+ * Mapbox GL) es para una card de lista, sin chrome y sin foco por teclado —
+ * no hace nada al recibir foco, así que no debe formar parte del tab order,
+ * y por eso NUNCA renderiza `controls` aunque el consumidor los pida:
+ * togglear "seguir" o abrir pantalla completa no tiene sentido en un mapa
+ * que no acepta interacción. Ninguna de las dos variantes oculta la
+ * atribución: es requisito de licencia de Mapbox, no cosmético.
+ *
+ * `theme` (`light|dark|streets|satellite|outdoors`) resuelve el estilo real
+ * de Mapbox — eje totalmente distinto del `[data-theme]` de
+ * `tokens/themes/*` (paleta de marca de la librería): ninguno de los 5
+ * temas de `tokens/` es oscuro todavía, así que no hay ninguna señal real
+ * de la que derivar un default "según el tema de marca activo" — construir
+ * esa detección ahora sería simular una señal que no existe.
+ *
+ * `controls` (`MapControlKind[]`, default `[]`) es siempre opt-in: un mapa
+ * sin `controls` no dibuja ningún botón flotante, ni siquiera en
+ * `interactive` (antes de esta versión, `interactive` agregaba el
+ * `NavigationControl` default de Mapbox gratis — se sacó a propósito: era
+ * el look genérico de Mapbox, no el de esta librería, exactamente la queja
+ * que motivó este rediseño. Un consumidor que quería esos botones de zoom
+ * ahora los pide con `[controls]="['zoom']"`). Cada kind es una pieza
+ * independiente entre sí (ver `MapControls.ts` para el detalle de cada
+ * una) — agregar una no reacomoda ni depende de las demás.
+ *
+ *   <kf-map label="Ubicación del vehículo y del destino" [markers]="markers()" />
+ *   <kf-map size="sm" variant="preview" label="Vista previa de la ruta" [route]="route()" />
+ *   <kf-map label="Flota completa" [markers]="fleet()" [controls]="['zoom', 'recenter', 'cluster', 'follow']" />
+ */
+declare class MapView {
+    readonly size: _angular_core.InputSignal<MapSize>;
+    readonly variant: _angular_core.InputSignal<MapVariant>;
+    readonly markers: _angular_core.InputSignal<MapMarker[]>;
+    readonly route: _angular_core.InputSignal<MapLatLng[] | undefined>;
+    readonly fitToMarkers: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly center: _angular_core.InputSignal<MapLatLng | undefined>;
+    readonly zoom: _angular_core.InputSignal<number | undefined>;
+    /**
+     * Default `'streets'`, no `'light'` ni `'dark'`. `'dark'` se probó
+     * primero por coherencia con la paleta navy de marca, pero una
+     * verificación visual real sobre una ubicación de servicio típica (una
+     * faena/zona rural, no un centro urbano denso) mostró el problema real:
+     * `dark-v11` casi no tiene datos que pintar fuera de ciudades grandes —
+     * el mapa se ve prácticamente todo negro, ilegible, exactamente donde
+     * más importa que se lea bien (ubicaciones de terreno, no de oficina).
+     * `'streets'` SIEMPRE tiene cartografía base visible (calles, nombres,
+     * uso de suelo) sin importar la densidad del lugar — es el único de los
+     * 5 estilos sin ese riesgo. Sigue siendo overrideable por el consumidor. */
+    readonly theme: _angular_core.InputSignal<MapTheme>;
+    /** Controles flotantes a mostrar — ver JSDoc de la clase y `MapControls.ts`. */
+    readonly controls: _angular_core.InputSignal<MapControlKind[]>;
+    /**
+     * Descripción accesible real del mapa — el `<div>` donde Mapbox renderiza
+     * su canvas queda vacío de semántica para un lector de pantalla. Requerido
+     * a propósito: un default genérico ("Mapa") no dice qué está mostrando
+     * ESTE mapa; cada consumidor conoce su propio caso real (ej. "Ubicación
+     * del vehículo y del destino").
+     */
+    readonly label: _angular_core.InputSignal<string>;
+    /** Se emite al hacer click sobre un marker que declaró `id` (ver JSDoc de
+     * `MapMarker.id`) — un marker SIN `id` no es clickeable, no emite nada.
+     * No dispara en modo `cluster` (los markers pasan a ser capas WebGL sin
+     * DOM propio donde colgar un listener) ni en `variant="preview"` (el
+     * mapa entero no es interactivo ahí). */
+    readonly markerSelect: _angular_core.OutputEmitterRef<string>;
+    /** Se emite al clickear un botón de `MapMarker.popup.actions` — ver el
+     * JSDoc de `popup` para por qué reporta `actionKey` (nunca el `label`) y
+     * por qué el click no dispara además `markerSelect`. */
+    readonly markerAction: _angular_core.OutputEmitterRef<{
+        markerId: string;
+        actionKey: string;
+    }>;
+    private readonly mapConfig;
+    private readonly environmentInjector;
+    private readonly document;
+    private readonly destroyRef;
+    private readonly hostElementRef;
+    private readonly containerRef;
+    /** `preview` no es foco-navegable ni se anuncia como región interactiva. */
+    protected readonly isPreview: _angular_core.Signal<boolean>;
+    protected readonly containerRole: _angular_core.Signal<"img" | "region">;
+    /** Ver estado de carga/error real, más abajo (`status`). */
+    protected readonly status: _angular_core.WritableSignal<"error" | "loading" | "ready">;
+    /** Elección manual del consumidor final vía el control `mapStyle` — pisa
+     * `theme()` de forma sostenida (no vuelve a `theme()` sola) hasta que se
+     * destruya este `kf-map`; ver `resolvedTheme()`. */
+    private readonly userTheme;
+    protected readonly styleLabel: _angular_core.Signal<string>;
+    /** Igual que `resolvedTheme()` pero público para el template — lo necesita
+     * `MapThemePicker` (vía `MapControls`) para marcar la opción activa. */
+    protected readonly activeTheme: _angular_core.Signal<MapTheme>;
+    protected readonly clusterActive: _angular_core.WritableSignal<boolean>;
+    protected readonly followActive: _angular_core.WritableSignal<boolean>;
+    protected readonly hasLiveMarker: _angular_core.Signal<boolean>;
+    protected readonly isFullscreen: _angular_core.WritableSignal<boolean>;
+    /** Sin estilo de marca propio (Mapbox Studio) no hay nada que ciclar con
+     * `mapStyle` — se filtra en vez de dejar un botón que no cambiaría nada. */
+    protected readonly effectiveControls: _angular_core.Signal<MapControlKind[]>;
+    protected readonly showControls: _angular_core.Signal<boolean>;
+    private map;
+    /** `extraIconRefs`: íconos de las acciones del popup (ver `buildMarkerPopup()`)
+     * — se crean con `createComponent()` igual que `iconRef` (el pin), así que
+     * necesitan el mismo `.destroy()` en `clearMarkers()`. */
+    private markerHandles;
+    /** Markers DOM reales sobre cada cluster real (punto 1, a11y) — separados
+     * de `markerHandles` porque se reconstruyen en su propio ciclo (ver
+     * `syncClusterMarkers()`) y no tienen `iconRef` propio (sin `kf-icon`
+     * adentro, ver JSDoc de `addClusterMarkerToMap()`). */
+    private clusterMarkerHandles;
+    private resizeObserver;
+    private currentStyle;
+    private mapReady;
+    /** Popup resumen de un cluster real (ver `renderClusterPopup()`) — a
+     * diferencia del popup de marker individual (siempre en el DOM, mostrado
+     * por CSS `:hover`/`:focus-within`), este se crea/destruye a demanda: no
+     * cuelga de ningún elemento con estado hover propio, lo abre un click
+     * sobre una capa WebGL sin DOM. */
+    private clusterPopupElement;
+    private clusterPopupIconRefs;
+    /** Coordenadas del cluster abierto — necesarias para volver a proyectar
+     * contra pantalla en cada `'move'` (ver `repositionClusterPopup()`); el
+     * cluster en sí no se mueve, pero su posición EN PANTALLA sí cuando se
+     * hace pan. */
+    private clusterPopupCoordinates;
+    private readonly onFullscreenChange;
+    constructor();
+    private initializeMap;
+    private resolvedTheme;
+    private resolvedStyle;
+    private toLngLat;
+    /**
+     * `matchMedia` (no una media query CSS): esta preferencia decide la
+     * `duration` que se le pasa a la API de cámara de Mapbox, que corre en
+     * JS/WebGL — CSS no tiene nada que animar acá. `document.defaultView` (no
+     * el `window` global) para que quede mockeable en test igual que el resto
+     * de la clase usa `DOCUMENT` inyectado.
+     */
+    private prefersReducedMotion;
+    /** Colapsa cualquier duración a 0 (instantáneo, sin animar) si el usuario
+     * pidió `prefers-reduced-motion: reduce` — un único punto de verdad para
+     * que ningún movimiento de cámara se salga de esa preferencia. */
+    private cameraDuration;
+    private syncCamera;
+    /**
+     * Encuadra `bounds` con `fitBounds()`, salvo que sea una caja degenerada
+     * (ver `DEGENERATE_BOUNDS_THRESHOLD_DEG`) — un solo punto total (un único
+     * marker sin ruta, o vehículo+destino prácticamente en el mismo sitio) le
+     * da a `fitBounds()` un ancho y alto ~cero, que Mapbox resuelve con un
+     * `padding`/zoom que en la práctica deja el mapa mayormente en blanco
+     * ("se ve todo blanco", el bug real que esto corrige). Un `easeTo` con
+     * zoom fijo sensato muestra contexto real de calle en ese caso, animado
+     * igual que el resto (antes era un `jumpTo` seco).
+     */
+    private frameBounds;
+    private isDegenerateBounds;
+    /**
+     * Extiende sobre markers Y route: el nombre del input sigue el caso de
+     * uso principal (encuadrar los markers), pero un mapa con solo `route` y
+     * sin `markers` tampoco debería quedar en el encuadre default inútil.
+     */
+    private computeBounds;
+    private syncMarkers;
+    /**
+     * Crea el marker de Mapbox (DOM + `kf-icon` + wiring de click/teclado/
+     * popup) para UN `MapMarker` y lo agrega a `markerHandles` — compartido
+     * entre el modo normal (`syncMarkers()`, todos los markers) y el modo
+     * cluster (`syncClusterMarkers()`, solo los que quedan sueltos): un punto
+     * suelto en modo cluster tiene que verse y comportarse EXACTAMENTE igual
+     * que en modo normal, así que no puede haber dos implementaciones.
+     */
+    private addMarkerToMap;
+    /**
+     * Mini-card hija del `<div>` del marker — mismo patrón que
+     * `.kf-map-controls__label` (ver `MapControls.css`): un elemento SIEMPRE
+     * presente en el DOM, oculto por defecto vía `opacity`/`pointer-events` en
+     * `MapView.css` y revelado por CSS puro en `:hover`/`:focus-within` del
+     * marker padre — sin JS de show/hide, y sin `mapboxgl.Popup` (evita una
+     * segunda gestión de overlay/posicionamiento cuando el CSS ya alcanza acá,
+     * igual que ya decidió `.kf-map-controls__label`).
+     *
+     * Todo el subárbol (título, descripción, `details`, `actions`) se arma con
+     * `document.createElement` puro, nunca `kf-text`/`kf-button`: este marker
+     * entero vive fuera del template de Angular (ver el comentario grande de
+     * `ViewEncapsulation.None` más arriba) — meter un componente real acá
+     * significaría un `createComponent()` propio por cada línea de texto, el
+     * mismo costo que ya paga `kf-icon` en `syncMarkers()` pero sin ninguna
+     * necesidad real (no hay nada dinámico que un componente resuelva mejor
+     * que texto plano estilado por clase). Es la MISMA decisión que ya regía
+     * para `title`/`description` antes de esta ronda — se extiende acá para no
+     * mezclar dos convenciones distintas dentro del mismo fragmento de DOM.
+     *
+     * `actions` sí necesita wiring propio (a diferencia del resto de la card,
+     * que burbujea su click al listener ya cableado sobre `element` en
+     * `syncMarkers()`): cada botón corta esa burbuja con `stopPropagation()`
+     * para reportar `markerAction` en vez de (además) `markerSelect`.
+     *
+     * Jerarquía visual de `actions` (ver JSDoc de `MapPopupAction`): la
+     * PRIMERA acción del array es la principal (`--primary`, fill); el resto
+     * es secundaria (`--ghost`, transparente) — mismo peso que ya usan
+     * `kf-button[variant=primary]`/`[variant=ghost]` en el resto de la
+     * librería, sin inventar un esquema de color nuevo acá.
+     *
+     * El punto de color junto al título (`kf-map__marker-popup-tone`) reusa
+     * el `tone` del propio marker — no el de cada `details` (que son pares
+     * label/value genéricos, sin un campo "cuál de estos es el estado"): es
+     * la misma señal que YA pinta el círculo del marker en el mapa, mostrada
+     * de nuevo acá para que el popup se lea sin tener que mirar el marker.
+     */
+    private buildMarkerPopup;
+    private clearMarkers;
+    /**
+     * Recorte de borde para el popup de marker individual (punto 2) —
+     * `getBoundingClientRect()` del marker y del propio contenedor del mapa,
+     * recalculado en el evento que dispara la apertura (`mouseenter`/
+     * `focusin`, ver `addMarkerToMap()`). El mecanismo de mostrar/ocultar
+     * sigue siendo 100% CSS; esto solo decide 3 clases modificadoras que
+     * `MapView.css` traduce en alineación horizontal/vertical:
+     *
+     *   `--align-start` — el popup se desborda por la izquierda del
+     *   contenedor si se centra sobre el marker: se alinea su borde
+     *   izquierdo con el del marker en vez de centrarlo.
+     *   `--align-end` — mismo caso, contra el borde derecho.
+     *   `--below` — no entra arriba del marker (cerca del borde superior del
+     *   contenedor): se muestra debajo en vez de arriba.
+     *
+     * El popup YA está en el DOM en este punto (oculto por `opacity`, no por
+     * `display:none` — ver `MapView.css`), así que `getBoundingClientRect()`
+     * devuelve su tamaño real aunque todavía no sea visible.
+     */
+    private positionMarkerPopup;
+    /**
+     * Clustering nativo de Mapbox (`cluster: true` en la fuente GeoJSON, no un
+     * algoritmo armado a mano) — 2 capas, solo para clusters REALES (2+
+     * puntos agrupados, `has: point_count`): círculo agregado y su label de
+     * cantidad. Un punto que Mapbox deja suelto (sin `point_count`) YA NO
+     * tiene capa WebGL propia — ver `syncClusterMarkers()`, que lo renderiza
+     * como el mismo marker DOM de siempre (con ícono/tono/popup reales, cosa
+     * que una capa `circle` no puede mostrar).
+     */
+    private syncClusterSource;
+    /**
+     * Contraparte en DOM de la capa WebGL: mientras esa capa solo dibuja
+     * clusters reales, ESTE método decide qué puntos quedan sueltos al zoom
+     * ACTUAL (`querySourceFeatures` con el mismo filtro `!has(point_count)`
+     * que ya usa Mapbox para separar cluster de leaf) y les arma el mismo
+     * marker DOM que tendrían sin clustering — vía `addMarkerToMap()`, la
+     * MISMA función que usa el modo normal, no una copia.
+     *
+     * `querySourceFeatures` puede devolver una feature repetida si cae cerca
+     * de un borde interno de tile — de ahí el `Set` sobre `index` (la
+     * property que identifica al `MapMarker` de origen, ver
+     * `markersToFeatureCollection()`), no una lista con posibles duplicados.
+     * Mismo motivo (y mismo `Set`, esta vez sobre `cluster_id`) para los
+     * clusters reales que se resuelven acá abajo.
+     *
+     * Se llama solo cuando `clusterActive()` — ver los listeners `'data'`/
+     * `'moveend'` en `initializeMap()` sobre CUÁNDO se llama esto.
+     */
+    private syncClusterMarkers;
+    /**
+     * Marker DOM real sobre un cluster (punto 1, a11y) — MISMO patrón de
+     * wiring que `addMarkerToMap()` (`role="button"`, `tabindex="0"`,
+     * `click`+`keydown` de Enter/Space), aplicado acá porque el círculo que
+     * pinta `CLUSTER_CIRCLE_LAYER_ID` es una capa WebGL sin nodo DOM propio
+     * —inalcanzable por teclado (WCAG SC 2.1.1 Keyboard). `mapboxgl.Marker`
+     * posiciona y reproyecta este `<div>` solo en cada pan/zoom, igual que ya
+     * hace con cualquier marker individual — no hace falta reposicionarlo a
+     * mano como sí necesita el popup resumen (ver `repositionClusterPopup()`).
+     *
+     * Sin `kf-icon`/texto propio adentro a propósito: el círculo+conteo que ya
+     * pinta la capa WebGL sigue siendo la representación visual (mismo
+     * `'circle-radius'`, ver `clusterMarkerRadiusPx()`); este `<div>` es
+     * transparente y se superpone exacto encima, aportando SOLO la
+     * interactividad real que la capa WebGL no puede tener.
+     */
+    private addClusterMarkerToMap;
+    private clearClusterMarkers;
+    /**
+     * Activación de un cluster real (click O Enter/Space sobre su marker DOM,
+     * ver `addClusterMarkerToMap()`): ANTES hacía zoom directo
+     * (`getClusterExpansionZoom()` + `easeTo`) — ahora abre el popup resumen
+     * (`renderClusterPopup()`) con la lista de tickets agrupados, y ESE zoom
+     * pasa a ser la acción explícita "Acercar para separar" dentro del popup
+     * (ver `expandCluster()`).
+     */
+    private activateCluster;
+    /** Dispara el zoom que antes hacía el click directo sobre el círculo —
+     * ahora vive detrás del botón "Acercar para separar" del popup resumen. */
+    private expandCluster;
+    /**
+     * `index` identifica de vuelta al `MapMarker` de origen (ver
+     * `syncClusterMarkers()`); `title`/`description`/`markerId` son las
+     * mismas properties que ya arma `buildMarkerPopup()` (folio/cliente/id
+     * del caso real) — se serializan acá TAMBIÉN para que
+     * `getClusterLeaves()` pueda listarlas en el popup resumen sin tener que
+     * ir a buscar cada `MapMarker` original por separado. Los campos son
+     * `string` (no `undefined`): las properties de una `Feature` de GeoJSON
+     * no viajan bien como `undefined` — `''` significa "sin dato" en los 3.
+     */
+    private markersToFeatureCollection;
+    private clearClusterLayers;
+    /**
+     * Popup resumen de un cluster real (punto 4) — a diferencia del popup de
+     * marker individual (siempre en el DOM, `:hover`/`:focus-within` puro),
+     * este no cuelga de ningún elemento con estado hover propio: lo abre un
+     * click sobre una capa WebGL sin DOM, así que se crea/destruye a demanda
+     * y su visibilidad la maneja JS, no CSS. Se agrega como hijo del HOST
+     * (`kf-map`, no `.kf-map__container`): ambos comparten exactamente la
+     * misma caja (`.kf-map__container` es `width/height:100%` sin padding/
+     * borde dentro de un host `position:relative`), así que las coordenadas
+     * de `map.project()` (relativas al contenedor) valen también acá — mismo
+     * ancestro posicionado que ya usa `.kf-map__overlay`.
+     *
+     * `title`/`description` de cada leaf son `popup.title`/`popup.description`
+     * del `MapMarker` original (folio/cliente en el caso real) — ver
+     * `markersToFeatureCollection()`. El punto de color reusa `tone`, MISMO
+     * criterio que el punto de color del popup individual (ver JSDoc de
+     * `buildMarkerPopup()`): no se inventa un texto de "estado" que la
+     * librería no tiene, se reusa la señal de color que sí existe.
+     */
+    private renderClusterPopup;
+    /** Reproyecta el popup de cluster contra pantalla — se llama en cada
+     * `'move'` (ver `initializeMap()`): el punto geográfico no se mueve, pero
+     * su posición EN PANTALLA sí cuando se hace pan. Mismo criterio de
+     * recorte de borde que `positionMarkerPopup()` (punto 2), pero en
+     * píxeles calculados a mano en vez de clases CSS: este popup no cuelga
+     * de un ancestro posicionado por CSS relativo al marker, su posición
+     * ENTERA viene de `map.project()`. */
+    private repositionClusterPopup;
+    private closeClusterPopup;
+    private syncRoute;
+    private resolveColorToken;
+    protected handleZoomIn(): void;
+    protected handleZoomOut(): void;
+    /** Reencuadra a demanda, ignorando `fitToMarkers()` (tiene sentido pedirlo
+     * justo cuando `fitToMarkers` está en `false`) y sin apagar `follow`: si
+     * está activo, la próxima posición nueva vuelve a pegar la cámara al
+     * marker `live` — este reencuadre es una corrección puntual, no un modo. */
+    protected handleRecenter(): void;
+    protected handleFollowToggle(): void;
+    protected handleClusterToggle(): void;
+    /** Reemplaza al viejo ciclado de un click (`handleStyleCycle`): la
+     * elección real llega desde `MapThemePicker`, vía `MapControls`. */
+    protected handleThemeSelect(theme: MapTheme): void;
+    protected handleFullscreenToggle(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MapView, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MapView, "kf-map", never, { "size": { "alias": "size"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "markers": { "alias": "markers"; "required": false; "isSignal": true; }; "route": { "alias": "route"; "required": false; "isSignal": true; }; "fitToMarkers": { "alias": "fitToMarkers"; "required": false; "isSignal": true; }; "center": { "alias": "center"; "required": false; "isSignal": true; }; "zoom": { "alias": "zoom"; "required": false; "isSignal": true; }; "theme": { "alias": "theme"; "required": false; "isSignal": true; }; "controls": { "alias": "controls"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": true; "isSignal": true; }; }, { "markerSelect": "markerSelect"; "markerAction": "markerAction"; }, never, never, true, never>;
+}
+
+export { MAP_CONFIG, MapControls, MapView, STYLE_BY_THEME, THEME_LABEL, THEME_ORDER, provideMapConfig };
+export type { MapConfig, MapControlKind, MapLatLng, MapMarker, MapMarkerTone, MapPopupAction, MapSize, MapTheme, MapVariant };