@cerca.red/mapa 0.2.0

package/README.md

@@ -0,0 +1,133 @@
+# @cerca.red/mapa
+
+El SDK del mapa de Cerca: modelo, cámara, capas y eventos sobre MapLibre GL JS.
+
+El paquete guarda su propio estado y trata el mapa como una proyección de él.
+Eso es lo que hace que cambiar de tema no pierda los negocios pintados, y lo
+que permite probar casi todo sin GPU.
+
+## Los tres puntos de entrada
+
+| Import                      | Qué trae                                         | Dónde corre                |
+| --------------------------- | ------------------------------------------------ | -------------------------- |
+| `@cerca.red/mapa`           | el modelo, el encuadre, el manifiesto, los tipos | navegador, workerd y Node  |
+| `@cerca.red/mapa/navegador` | `crearMapa` y el adaptador de MapLibre           | solo el navegador (WebGL2) |
+| `@cerca.red/mapa/doble`     | un motor falso con la geometría de verdad        | donde sea, sin canvas      |
+
+El punto de entrada por defecto **no alcanza `maplibre-gl`**, ni directamente
+ni cinco archivos más adentro. Se puede importar desde un Server Component
+sobre Cloudflare Workers sin que el build reviente. El mapa de verdad entra por
+la subruta `./navegador`, que es explícita a propósito: importarla se ve en el
+diff. Dos pruebas lo comprueban, una dentro de workerd y otra leyendo el grafo
+de imports.
+
+## Resultados y clusterización híbrida
+
+El backend consumidor decide qué devolver para la caja y el zoom actuales. La
+actualización es una sola orden y los dos modos son mutuamente excluyentes:
+
+```ts
+mapa.ponerResultados({
+  modo: "grupos",
+  grupos: [
+    {
+      id: "z12:1234:2187",
+      cantidad: 384,
+      ubicacion: { lon: -75.696, lat: 4.813 },
+      caja: [-75.71, 4.8, -75.68, 4.83],
+    },
+  ],
+});
+
+mapa.ponerResultados({ modo: "negocios", negocios });
+```
+
+Los grupos del servidor tienen fuente y capas propias y no vuelven a
+clusterizarse. Los negocios individuales conservan la agrupación visual local
+de MapLibre. `ponerNegocios(negocios)` sigue siendo compatible y equivale al
+segundo ejemplo.
+
+`grupo:clic` discrimina `origen: "servidor" | "local"`. Un grupo del servidor
+incluye su `caja` y el SDK la encuadra; uno local conserva el acercamiento
+incremental existente.
+
+## Next.js y los bundlers que pierden `import.meta.url`
+
+MapLibre 6 reparte el motor en dos archivos. `maplibre-gl.mjs` corre en el hilo
+principal; `maplibre-gl-worker.mjs` corre en un Web Worker y hace el trabajo
+pesado. El segundo no se importa: el primero deduce su URL a partir de su
+propio `import.meta.url` y llama a `new Worker(...)`.
+
+Un bundler que reescriba `import.meta.url` rompe esa deducción. Medido en
+`cerca-pwa` con Next.js 16 sobre OpenNext: con Turbopack y con `--webpack`, el
+motor recibe la URL de la propia página y pide un archivo que no está ahí. Con
+Vite no pasa, y por eso el mismo paquete pinta el mapa en `laboratorio/` y no
+lo pinta bajo Next.
+
+La salida es decirle la URL:
+
+```ts
+import { crearMapa } from "@cerca.red/mapa/navegador";
+
+const mapa = crearMapa({
+  contenedor,
+  estilo,
+  urlDeTeselas,
+  urlDelWorker: "/maplibre/maplibre-gl-worker.mjs",
+});
+```
+
+Con `<Mapa>` de `@cerca.red/mapa-react` es la prop `urlDelWorker`. Y quien
+prefiera fijarla una sola vez al arrancar tiene `fijarUrlDelWorker(url)` en la
+misma subruta. En los tres casos hay que hacerlo **antes del primer mapa**: el
+pool de workers de MapLibre es único para toda la página, se crea dentro del
+constructor de `Map` y no vuelve a leer la URL mientras quede un mapa vivo.
+Fijarla después no da error ni aviso, y tampoco hace nada.
+
+Sin la opción no se toca la configuración de MapLibre, que es lo correcto bajo
+Vite.
+
+### Qué archivo hay que servir
+
+El `maplibre-gl-worker.mjs` de la **misma versión** de `maplibre-gl` que
+resuelve el proyecto. El protocolo entre el hilo principal y el worker es
+interno de MapLibre y no está versionado: un worker de otra versión no da un
+error que lo diga, da un mapa que no pinta teselas.
+
+Para copiarlo en la compilación y para comprobarlo, el punto de entrada por
+defecto exporta dos cadenas —no importan `maplibre-gl`, así que se pueden leer
+desde un guion de Node:
+
+```ts
+import {
+  RUTA_DEL_WORKER_DE_MAPLIBRE, // "maplibre-gl/dist/maplibre-gl-worker.mjs"
+  VERSION_DE_MAPLIBRE, // la versión contra la que se compiló este paquete
+} from "@cerca.red/mapa";
+```
+
+El guion que lo copia resuelve el especificador en vez de unir cadenas, para
+que salga el archivo del `maplibre-gl` que ese proyecto resolvió:
+
+```ts
+import { copyFileSync, mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { RUTA_DEL_WORKER_DE_MAPLIBRE } from "@cerca.red/mapa";
+
+const origen = createRequire(import.meta.url).resolve(
+  RUTA_DEL_WORKER_DE_MAPLIBRE,
+);
+mkdirSync("public/maplibre", { recursive: true });
+copyFileSync(origen, "public/maplibre/maplibre-gl-worker.mjs");
+```
+
+Y la prueba que impide la pareja desigual compara la versión que resuelve la
+superficie con `VERSION_DE_MAPLIBRE`. Dentro de este repositorio esa
+comparación la hace `src/worker-de-maplibre.test.ts`.
+
+## Cómo se prueba
+
+`@cerca.red/mapa/doble` da un motor falso con la geometría de verdad, para
+comprobar sin levantar un contexto WebGL que al tocar un resultado de la lista
+el mapa recibió la orden de seleccionarlo. Lo que sí necesita un navegador —un
+objetivo táctil sobre el canvas, un radio de toque— se comprueba tocando, con
+`map.project` para calcular el punto; nunca comparando píxeles.

package/dist/capas.d.ts

@@ -0,0 +1,29 @@
+import type { CapaDelEstilo } from "./estilo.ts";
+import { type Anclas } from "./identificadores.ts";
+import type { PaletaDelMapa } from "./paleta.ts";
+/**
+ * Las capas de Cerca, como datos.
+ *
+ * Cada función devuelve una lista de capas y **el ancla donde van**. El SDK
+ * las inserta en ese orden; no hay ninguna que dependa de dónde quedó otra.
+ *
+ * Se rehacen enteras cada vez que cambia el tema, porque cambiar de tema en
+ * MapLibre es reemplazar el estilo completo y el estilo nuevo llega sin nada
+ * de esto. Que sean funciones puras de la paleta es lo que hace que esa
+ * reconstrucción no pueda quedar a medias.
+ */
+/** Una capa con el ancla debajo de la cual se inserta. */
+export interface CapaConAncla {
+    readonly capa: CapaDelEstilo;
+    readonly antesDe: string;
+}
+/** Las áreas: isócronas, zonas de cobertura y halos de imprecisión. */
+export declare function capasDeAreas(paleta: PaletaDelMapa, anclas: Anclas): readonly CapaConAncla[];
+/** Las líneas: rutas, con su contorno y sus alternativas. */
+export declare function capasDeLineas(paleta: PaletaDelMapa, anclas: Anclas): readonly CapaConAncla[];
+/** Los puntos: grupos, negocios, sedes, vehículos y la ubicación del usuario. */
+export declare function capasDePuntos(paleta: PaletaDelMapa, anclas: Anclas): readonly CapaConAncla[];
+/** La selección: encima de todo, con anillo además de color. */
+export declare function capasDeSeleccion(paleta: PaletaDelMapa): readonly CapaConAncla[];
+/** Todas las capas de Cerca, en el orden en que se insertan. */
+export declare function todasLasCapas(paleta: PaletaDelMapa, anclas: Anclas): readonly CapaConAncla[];

package/dist/capas.js

@@ -0,0 +1,489 @@
+import { CAPAS, FUENTES, RADIO_TACTIL_MINIMO_EN_PX, } from "./identificadores.js";
+/** Radio del punto de un negocio, por énfasis. El tamaño distingue tanto como el color. */
+const RADIO_POR_ENFASIS = {
+    atenuado: 4,
+    normal: 6,
+    destacado: 9,
+};
+/**
+ * La expresión que elige radio según el énfasis y el zoom.
+ *
+ * Interpola con el zoom porque un punto de radio fijo se ve enorme al alejarse
+ * —cuando hay cien en pantalla— y minúsculo al acercarse. Los valores están
+ * atados a los tres énfasis para que la diferencia entre destacado y atenuado
+ * siga siendo visible a cualquier zoom.
+ */
+function radioDeNegocio(multiplicador) {
+    return [
+        "interpolate",
+        ["linear"],
+        ["zoom"],
+        10,
+        [
+            "*",
+            multiplicador * 0.7,
+            [
+                "match",
+                ["get", "enfasis"],
+                "destacado",
+                RADIO_POR_ENFASIS.destacado,
+                "atenuado",
+                RADIO_POR_ENFASIS.atenuado,
+                RADIO_POR_ENFASIS.normal,
+            ],
+        ],
+        16,
+        [
+            "*",
+            multiplicador,
+            [
+                "match",
+                ["get", "enfasis"],
+                "destacado",
+                RADIO_POR_ENFASIS.destacado,
+                "atenuado",
+                RADIO_POR_ENFASIS.atenuado,
+                RADIO_POR_ENFASIS.normal,
+            ],
+        ],
+    ];
+}
+/**
+ * Las capas invisibles que reciben los toques.
+ *
+ * Radio 22 px, o sea un objetivo de 44 (CLAUDE.md §1). No se comprueba
+ * leyendo este número: se comprueba tocando, calculando el punto con la
+ * proyección del mapa y tocando dentro y fuera del radio. Un radio que nadie
+ * tocó no está comprobado.
+ */
+function capaDeToque(id, fuente, filter) {
+    return {
+        id,
+        type: "circle",
+        source: fuente,
+        ...(filter === undefined ? {} : { filter }),
+        paint: {
+            "circle-radius": RADIO_TACTIL_MINIMO_EN_PX,
+            // Cero, no `visibility: none`. La consulta de entidades dibujadas
+            // devuelve capas transparentes y no devuelve capas apagadas: si esto
+            // fuera `none`, los alfileres dejarían de ser tocables sin que nada
+            // cambiara de aspecto.
+            "circle-opacity": 0,
+        },
+    };
+}
+/** Las áreas: isócronas, zonas de cobertura y halos de imprecisión. */
+export function capasDeAreas(paleta, anclas) {
+    const antesDe = anclas.lineas;
+    return [
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.isocronas,
+                type: "fill",
+                source: FUENTES.isocronas,
+                paint: {
+                    "fill-color": paleta.isocrona,
+                    // Las bandas se superponen: la de 15 minutos contiene a la de 5.
+                    // Con opacidad baja, la acumulación es justo lo que hace legible
+                    // que el centro se alcanza antes.
+                    "fill-opacity": [
+                        "interpolate",
+                        ["linear"],
+                        ["get", "minutos"],
+                        5,
+                        0.28,
+                        30,
+                        0.1,
+                    ],
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.isocronasBorde,
+                type: "line",
+                source: FUENTES.isocronas,
+                paint: {
+                    "line-color": paleta.isocrona,
+                    "line-width": 1,
+                    "line-opacity": 0.6,
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.zonas,
+                type: "fill",
+                source: FUENTES.zonas,
+                paint: {
+                    "fill-color": paleta.zona,
+                    "fill-opacity": [
+                        "match",
+                        ["get", "enfasis"],
+                        "destacado",
+                        0.28,
+                        "atenuado",
+                        0.08,
+                        0.16,
+                    ],
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.zonasBorde,
+                type: "line",
+                source: FUENTES.zonas,
+                paint: { "line-color": paleta.bordeDeZona, "line-width": 1.5 },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.imprecision,
+                type: "fill",
+                source: FUENTES.imprecision,
+                paint: { "fill-color": paleta.imprecision, "fill-opacity": 0.18 },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.imprecisionBorde,
+                type: "line",
+                source: FUENTES.imprecision,
+                paint: {
+                    "line-color": paleta.bordeDeImprecision,
+                    "line-width": 1.5,
+                    // Discontinuo a propósito: es la forma, no el color, la que dice
+                    // «esto es una estimación». Quien no distinga los dos morados sigue
+                    // viendo que este borde no es como los demás.
+                    "line-dasharray": [2, 2],
+                },
+            },
+        },
+    ];
+}
+/** Las líneas: rutas, con su contorno y sus alternativas. */
+export function capasDeLineas(paleta, anclas) {
+    const antesDe = anclas.puntos;
+    return [
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.rutasAlternativas,
+                type: "line",
+                source: FUENTES.rutas,
+                filter: ["!", ["get", "principal"]],
+                layout: { "line-cap": "round", "line-join": "round" },
+                paint: {
+                    "line-color": paleta.rutaAlternativa,
+                    "line-width": 4,
+                    "line-dasharray": [2, 1.5],
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.rutaPrincipalContorno,
+                type: "line",
+                source: FUENTES.rutas,
+                filter: ["get", "principal"],
+                layout: { "line-cap": "round", "line-join": "round" },
+                // El contorno claro por debajo es lo que hace que la ruta se lea
+                // sobre una avenida del mismo grosor y color parecido. Sin él, la
+                // línea desaparece justo donde va por la vía que sigue.
+                paint: { "line-color": paleta.contornoDeRuta, "line-width": 9 },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.rutaPrincipal,
+                type: "line",
+                source: FUENTES.rutas,
+                filter: ["get", "principal"],
+                layout: { "line-cap": "round", "line-join": "round" },
+                paint: { "line-color": paleta.ruta, "line-width": 5 },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.rutasToque,
+                type: "line",
+                source: FUENTES.rutas,
+                paint: {
+                    "line-width": RADIO_TACTIL_MINIMO_EN_PX * 2,
+                    "line-opacity": 0,
+                },
+            },
+        },
+    ];
+}
+/** Los puntos: grupos, negocios, sedes, vehículos y la ubicación del usuario. */
+export function capasDePuntos(paleta, anclas) {
+    const antesDe = anclas.seleccion;
+    return [
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.ubicacionHalo,
+                type: "fill",
+                source: FUENTES.ubicacion,
+                // El halo es un **polígono**, no un círculo de MapLibre, y el filtro
+                // lo separa del punto que va en la misma fuente. La razón está en
+                // `circuloComoPoligono`: el radio de un círculo de MapLibre va en
+                // píxeles, así que un halo de «30 metros de incertidumbre» dibujado
+                // así mediría kilómetros al alejarse. Un polígono está en el mundo y
+                // se queda donde está.
+                filter: ["==", ["geometry-type"], "Polygon"],
+                paint: {
+                    "fill-color": paleta.haloDeUbicacion,
+                    "fill-opacity": 0.15,
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.ubicacionPunto,
+                type: "circle",
+                source: FUENTES.ubicacion,
+                filter: ["==", ["geometry-type"], "Point"],
+                paint: {
+                    "circle-radius": 6,
+                    "circle-color": paleta.ubicacion,
+                    "circle-stroke-width": 2,
+                    "circle-stroke-color": paleta.contornoDePunto,
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.gruposServidorCirculo,
+                type: "circle",
+                source: FUENTES.grupos,
+                paint: {
+                    "circle-color": paleta.grupo,
+                    "circle-radius": ["step", ["get", "cantidad"], 16, 10, 20, 50, 26],
+                    "circle-stroke-width": 2,
+                    "circle-stroke-color": paleta.contornoDePunto,
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.gruposServidorCantidad,
+                type: "symbol",
+                source: FUENTES.grupos,
+                layout: {
+                    "text-field": [
+                        "coalesce",
+                        ["get", "rotulo"],
+                        ["to-string", ["get", "cantidad"]],
+                    ],
+                    "text-size": 12,
+                    "text-allow-overlap": true,
+                },
+                paint: { "text-color": paleta.textoDeGrupo },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.gruposCirculo,
+                type: "circle",
+                source: FUENTES.negocios,
+                filter: ["has", "point_count"],
+                paint: {
+                    "circle-color": paleta.grupo,
+                    // El círculo crece con lo que contiene, en escalones. Un grupo de
+                    // 200 y uno de 3 tienen que verse distintos antes de leer el número.
+                    "circle-radius": ["step", ["get", "point_count"], 16, 10, 20, 50, 26],
+                    "circle-stroke-width": 2,
+                    "circle-stroke-color": paleta.contornoDePunto,
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.gruposCantidad,
+                type: "symbol",
+                source: FUENTES.negocios,
+                filter: ["has", "point_count"],
+                layout: {
+                    "text-field": ["get", "point_count_abbreviated"],
+                    "text-size": 12,
+                    "text-allow-overlap": true,
+                },
+                paint: { "text-color": paleta.textoDeGrupo },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.sedesPunto,
+                type: "circle",
+                source: FUENTES.sedes,
+                paint: {
+                    "circle-radius": 4,
+                    "circle-color": paleta.negocioAtenuado,
+                    "circle-stroke-width": 1.5,
+                    "circle-stroke-color": paleta.contornoDePunto,
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.negociosPunto,
+                type: "circle",
+                source: FUENTES.negocios,
+                filter: ["!", ["has", "point_count"]],
+                paint: {
+                    "circle-radius": radioDeNegocio(1),
+                    "circle-color": [
+                        "match",
+                        ["get", "enfasis"],
+                        "destacado",
+                        paleta.negocioDestacado,
+                        "atenuado",
+                        paleta.negocioAtenuado,
+                        paleta.negocio,
+                    ],
+                    "circle-stroke-width": [
+                        "case",
+                        ["boolean", ["feature-state", "encima"], false],
+                        3,
+                        2,
+                    ],
+                    "circle-stroke-color": paleta.contornoDePunto,
+                    "circle-opacity": ["match", ["get", "enfasis"], "atenuado", 0.65, 1],
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.negociosSimbolo,
+                type: "symbol",
+                source: FUENTES.negocios,
+                filter: ["all", ["!", ["has", "point_count"]], ["has", "simbolo"]],
+                layout: {
+                    "icon-image": ["get", "simbolo"],
+                    "icon-size": 0.8,
+                    "icon-allow-overlap": true,
+                    "text-field": ["coalesce", ["get", "rotulo"], ""],
+                    "text-size": 11,
+                    "text-offset": [0, 1.3],
+                    "text-anchor": "top",
+                    "text-optional": true,
+                },
+                paint: {
+                    "icon-color": paleta.contornoDePunto,
+                    "text-color": paleta.rotulo,
+                    "text-halo-color": paleta.haloDeRotulo,
+                    "text-halo-width": 1.2,
+                },
+            },
+        },
+        {
+            antesDe,
+            capa: {
+                id: CAPAS.vehiculos,
+                type: "symbol",
+                source: FUENTES.vehiculos,
+                layout: {
+                    "icon-image": ["coalesce", ["get", "simbolo"], "cerca-vehiculo"],
+                    "icon-size": 0.9,
+                    "icon-allow-overlap": true,
+                    "icon-rotate": ["coalesce", ["get", "rumbo"], 0],
+                    "icon-rotation-alignment": "map",
+                },
+                paint: { "icon-color": paleta.vehiculo },
+            },
+        },
+        {
+            antesDe,
+            capa: capaDeToque(CAPAS.gruposServidorToque, FUENTES.grupos),
+        },
+        {
+            antesDe,
+            capa: capaDeToque(CAPAS.gruposToque, FUENTES.negocios, [
+                "has",
+                "point_count",
+            ]),
+        },
+        { antesDe, capa: capaDeToque(CAPAS.sedesToque, FUENTES.sedes) },
+        {
+            antesDe,
+            capa: capaDeToque(CAPAS.negociosToque, FUENTES.negocios, [
+                "!",
+                ["has", "point_count"],
+            ]),
+        },
+        { antesDe, capa: capaDeToque(CAPAS.vehiculosToque, FUENTES.vehiculos) },
+    ];
+}
+/** La selección: encima de todo, con anillo además de color. */
+export function capasDeSeleccion(paleta) {
+    return [
+        {
+            // Sin ancla: la selección es lo último y va arriba del todo. Es la
+            // única familia de capas que no recibe `anclas`, y por eso su firma es
+            // distinta — fingir que la recibe para igualar las firmas dejaría un
+            // parámetro que nadie lee y que el siguiente lector creería que hace
+            // algo.
+            antesDe: "",
+            capa: {
+                id: CAPAS.seleccionArea,
+                type: "fill",
+                source: FUENTES.seleccion,
+                // Un negocio seleccionado con ubicación aproximada llega aquí como
+                // polígono, no como punto: ver `coleccionDeSeleccion`.
+                filter: ["==", ["geometry-type"], "Polygon"],
+                paint: {
+                    "fill-color": paleta.seleccion,
+                    "fill-opacity": 0.25,
+                    "fill-outline-color": paleta.seleccion,
+                },
+            },
+        },
+        {
+            antesDe: "",
+            capa: {
+                id: CAPAS.seleccion,
+                type: "circle",
+                source: FUENTES.seleccion,
+                filter: ["==", ["geometry-type"], "Point"],
+                paint: {
+                    "circle-radius": radioDeNegocio(1.35),
+                    "circle-color": paleta.seleccion,
+                    // El anillo grueso es la señal que no depende del color: quien no
+                    // distinga el naranja del azul sigue viendo cuál está elegido.
+                    "circle-stroke-width": 4,
+                    "circle-stroke-color": paleta.contornoDePunto,
+                },
+            },
+        },
+    ];
+}
+/** Todas las capas de Cerca, en el orden en que se insertan. */
+export function todasLasCapas(paleta, anclas) {
+    return [
+        ...capasDeAreas(paleta, anclas),
+        ...capasDeLineas(paleta, anclas),
+        ...capasDePuntos(paleta, anclas),
+        ...capasDeSeleccion(paleta),
+    ];
+}
+//# sourceMappingURL=capas.js.map