@datosgeo-atdt/geo-ui 0.4.8 → 0.6.0

package/README.md

@@ -1,346 +1,352 @@
-# @atdt/geo-ui
-
-Librería de componentes reutilizables en React para aplicaciones geoespaciales. Incluye visualización de mapas con PMTiles, unión con datos tabulares CSV y estilos temáticos (booleano y Jenks).
-
-## Características
-
-- **MapaPMTiles**: Componente para renderizar mapas vectoriales usando MapLibre GL y PMTiles
-- **Join CSV**: Unión automática de datos tabulares con geometrías vectoriales
-- **Estilos temáticos**: Soporte para modo booleano y clasificación Jenks
-- **TypeScript**: Completamente tipado para mejor experiencia de desarrollo
-- **Sin SSR**: Diseñado para aplicaciones client-side (React puro, Vite, CRA)
-
-## Instalación
-
-```bash
-npm install @atdt/geo-ui maplibre-gl pmtiles papaparse @mapbox/vector-tile pbf
-```
-
-**Importante**: Las dependencias `react` y `react-dom` son peer dependencies (versión 18+).
-
-## Uso Básico
-
-### Importar el componente
-
-```tsx
-import { MapaPMTiles } from '@atdt/geo-ui';
-import '@atdt/geo-ui/style.css';
-```
-
-### Ejemplo básico (usando valores por defecto)
-
-La biblioteca incluye **integrada** la URL del PMTiles de entidades de México, por lo que no necesitas especificar `pmtilesUrl`, `sourceLayer` ni `joinGeomKey` si trabajas con entidades:
-
-```tsx
-import React from 'react';
-import { MapaPMTiles } from '@atdt/geo-ui';
-import '@atdt/geo-ui/style.css';
-
-function App() {
-  return (
-    <MapaPMTiles
-      csvUrl="https://example.com/datos.csv"
-      field="valor"
-      mode="boolean"
-      width="100%"
-      height={600}
-    />
-  );
-}
-
-export default App;
-```
-
-### Ejemplo con csvUrl (especificando PMTiles personalizado)
-
-```tsx
-import React from 'react';
-import { MapaPMTiles } from '@atdt/geo-ui';
-import '@atdt/geo-ui/style.css';
-
-function App() {
-  return (
-    <MapaPMTiles
-      pmtilesUrl="https://example.com/custom.pmtiles"
-      sourceLayer="mi-capa"
-      joinGeomKey="ID"
-      csvUrl="https://example.com/datos.csv"
-      field="valor"
-      mode="boolean"
-      width="100%"
-      height={600}
-    />
-  );
-}
-
-export default App;
-```
-
-### Ejemplo con csvFile (archivo local)
-
-```tsx
-import React, { useState } from 'react';
-import { MapaPMTiles } from '@atdt/geo-ui';
-import '@atdt/geo-ui/style.css';
-
-function App() {
-  const [csvFile, setCsvFile] = useState<File | null>(null);
-
-  return (
-    <div>
-      <input
-        type="file"
-        accept=".csv"
-        onChange={(e) => setCsvFile(e.target.files?.[0] || null)}
-      />
-      {csvFile && (
-        <MapaPMTiles
-          csvFile={csvFile}
-          field="poblacion"
-          mode="jenks"
-          jenksK={5}
-        />
-      )}
-    </div>
-  );
-}
-
-export default App;
-```
-
-### Ejemplo con fitToIds (zoom y filtrado por entidades)
-
-Muestra **solo** las entidades seleccionadas y ajusta el mapa automáticamente a su extensión (sin animación):
-
-```tsx
-// Mostrar solo Ciudad de México
-<MapaPMTiles
-  csvUrl="https://example.com/datos.csv"
-  fitToIds="09"
-/>
-
-// Mostrar múltiples entidades (Ciudad de México, Estado de México y Jalisco)
-<MapaPMTiles
-  csvUrl="https://example.com/datos.csv"
-  fitToIds={["09", "15", "14"]}
-/>
-```
-
-**Ventajas de usar `fitToIds`:**
-- ✅ No necesitas configurar `pmtilesUrl` (está integrado)
-- ✅ Filtra automáticamente para mostrar solo las entidades seleccionadas
-- ✅ Calcula y ajusta el bbox combinado sin animación de zoom
-- ✅ Carga directo en la vista correcta
-
-### Ejemplo con municipios
-
-Cuando usas `fitToIds`, puedes habilitar la visualización de municipios con `showMunicipios`:
-
-```tsx
-// Mostrar municipios con datos (aplica el mismo modo que entidades)
-<MapaPMTiles
-  csvUrl="https://example.com/datos-entidades.csv"
-  fitToIds="01"
-  showMunicipios={true}
-  municipiosCsvUrl="https://example.com/datos-municipios.csv"
-  municipiosField="poblacion"
-  mode="jenks"
-/>
-
-// Mostrar solo contornos de municipios (sin datos)
-<MapaPMTiles
-  csvUrl="https://example.com/datos-entidades.csv"
-  fitToIds={["09", "15"]}
-  showMunicipios={true}
-/>
-```
-
-**Características de la capa de municipios:**
-- ✅ URL del PMTiles de municipios integrada
-- ✅ Filtrado automático por CVE_ENT de las entidades seleccionadas
-- ✅ Join con CVEGEO en mayúsculas
-- ✅ Aplica el mismo modo (boolean/jenks) que las entidades si proporcionas CSV
-- ✅ Si no proporcionas CSV, solo muestra contornos (outline)
-- ✅ El contorno de entidades se hace más grueso cuando se muestran municipios
-
-## Props
-
-### Props Obligatorias
-
-| Prop | Tipo | Descripción |
-|------|------|-------------|
-| `csvUrl` o `csvFile` | `string \| File` | URL del CSV remoto o archivo File local. **Al menos uno debe estar presente** |
-
-### Props Opcionales
-
-| Prop | Tipo | Default | Descripción |
-|------|------|---------|-------------|
-| `pmtilesUrl` | `string` | `"https://www.datosgeoespaciales.atdt.gob.mx/datalake/pmtiles/componente/entidad.pmtiles"` | URL del archivo PMTiles remoto. **Por defecto usa el PMTiles de entidades de México** |
-| `sourceLayer` | `string` | `"entidad"` | Nombre de la capa vectorial dentro del PMTiles |
-| `joinGeomKey` | `string` | `"cvegeo"` | Campo de la geometría para hacer el join (también usado como `promoteId`) |
-| `joinCsvKey` | `string` | `joinGeomKey` | Campo del CSV para hacer el join |
-| `field` | `string` | `"valor"` | Campo del CSV con los valores a visualizar |
-| `mode` | `"boolean" \| "jenks"` | `"boolean"` | Modo de estilo: booleano o clasificación Jenks |
-| `width` | `string \| number` | `"100%"` | Ancho del mapa |
-| `height` | `string \| number` | `520` | Alto del mapa (en px si es número) |
-| `initialView` | `object` | `{center: [-102, 23], zoom: 4}` | Vista inicial del mapa (ignorado si se usa `fitToIds`) |
-| `initialView.center` | `[number, number]` | `[-102, 23]` | Centro inicial [lng, lat] |
-| `initialView.zoom` | `number` | `4` | Zoom inicial |
-| `fitToIds` | `string \| string[]` | `undefined` | ID o array de IDs de features para filtrar y hacer zoom automático (sin animación) |
-| `bboxField` | `string` | `"bbox"` | Campo con bbox precalculado en PMTiles |
-| `jenksK` | `number` | `5` | Número de clases para clasificación Jenks |
-| `showMunicipios` | `boolean` | `false` | Habilita la visualización de municipios (requiere `fitToIds`) |
-| `municipiosCsvUrl` | `string` | `undefined` | URL del CSV para unir con municipios (opcional) |
-| `municipiosCsvFile` | `File` | `undefined` | Archivo CSV para unir con municipios (opcional) |
-| `municipiosField` | `string` | `"valor"` | Campo del CSV de municipios con los valores a visualizar |
-
-## Modos de Estilo
-
-### Modo Boolean
-
-Pinta las geometrías en dos colores según el valor:
-
-- `value === 1` → **#66827f** (verde azulado)
-- `value === 0 / null / undefined` → **#f3f3f3** (gris claro)
-
-```tsx
-<MapaPMTiles
-  mode="boolean"
-  {...otherProps}
-/>
-```
-
-### Modo Jenks
-
-Clasifica los valores numéricos usando el algoritmo Jenks Natural Breaks y aplica una rampa de colores:
-
-- De **#f3f3f3** (gris claro) a **#66827f** (verde azulado)
-- Número de clases controlado por `jenksK` (default: 5)
-
-```tsx
-<MapaPMTiles
-  mode="jenks"
-  jenksK={7}
-  {...otherProps}
-/>
-```
-
-## Formato CSV
-
-El archivo CSV debe tener:
-
-- **Header row** con nombres de columnas
-- Una columna con el **join key** que coincida con el campo `joinGeomKey` de las geometrías
-- Una columna con los **valores** especificada en `field`
-
-Ejemplo:
-
-```csv
-CVE_ENT,nombre,valor
-01,Aguascalientes,1
-02,Baja California,0
-09,Ciudad de México,1
-```
-
-## Interactividad del Mapa
-
-El componente tiene **interactividad desactivada** por defecto para mantener un estilo estático:
-
-- `boxZoom`: false
-- `doubleClickZoom`: false
-- `dragRotate`: false
-- `keyboard`: false
-- `scrollZoom`: false
-- `touchPitch`: false
-- `dragPan`: false
-- `touchZoomRotate`: true (permitido)
-
-## Notas CORS
-
-Para consumir PMTiles y CSV de dominios externos, asegúrate de que:
-
-1. El servidor tenga configurado CORS adecuadamente
-2. Para PMTiles, el servidor debe soportar **Range requests** (HTTP 206)
-3. Headers necesarios:
-   ```
-   Access-Control-Allow-Origin: *
-   Access-Control-Allow-Headers: Range
-   Accept-Ranges: bytes
-   ```
-
-## Tecnologías
-
-- **React 18+**
-- **TypeScript**
-- **MapLibre GL JS**: Renderizado de mapas vectoriales
-- **PMTiles**: Formato de tiles vectoriales eficiente
-- **PapaParse**: Parsing de CSV
-- **Vite**: Build tool
-
-## Build y Desarrollo
-
-### Desarrollo local
-
-```bash
-npm install
-npm run dev
-```
-
-### Build de producción
-
-```bash
-npm run build
-```
-
-Esto genera:
-
-- `dist/geo-ui.js` (ES module)
-- `dist/geo-ui.umd.cjs` (UMD)
-- `dist/index.d.ts` (TypeScript definitions)
-- `dist/style.css` (estilos de MapLibre GL)
-
-### Publicar a npm
-
-```bash
-# Asegúrate de estar autenticado en npm
-npm login
-
-# Incrementa versión (patch, minor, major)
-npm version patch
-
-# Publica (ejecutará automáticamente build por prepublishOnly)
-npm publish --access public
-```
-
-**Nota**: Para paquetes con scope `@atdt/`, necesitas usar `--access public` la primera vez.
-
-## Estructura del Proyecto
-
-```
-geo-ui/
-├── src/
-│   ├── components/
-│   │   └── MapaPMTiles.tsx      # Componente principal
-│   ├── utils/
-│   │   ├── csv.ts               # Utilidades para parsear CSV
-│   │   ├── jenks.ts             # Algoritmo Jenks Natural Breaks
-│   │   └── pmtilesFeatureSearch.ts  # Búsqueda de features y bbox
-│   └── index.ts                 # Entry point
-├── dist/                        # Build output (generado)
-├── package.json
-├── tsconfig.json
-├── vite.config.ts
-└── README.md
-```
-
-## Licencia
-
-ISC
-
-## Autor
-
-Dirección de Datos Geográficos - ATDT
-
-## Contribuciones
-
-Issues y pull requests son bienvenidos en [GitLab](https://gitlab.com/atdt-desarrollogeo/componentes).
+# @atdt/geo-ui
+
+Librería de componentes reutilizables en React para aplicaciones geoespaciales. Incluye visualización de mapas con PMTiles, unión con datos tabulares CSV y estilos temáticos (booleano y Jenks).
+
+## Características
+
+- **MapaPMTiles**: Componente para renderizar mapas vectoriales usando MapLibre GL y PMTiles
+- **Join CSV**: Unión automática de datos tabulares con geometrías vectoriales
+- **Estilos temáticos**: Soporte para modo booleano y clasificación Jenks
+- **TypeScript**: Completamente tipado para mejor experiencia de desarrollo
+- **Sin SSR**: Diseñado para aplicaciones client-side (React puro, Vite, CRA)
+
+## Instalación
+
+```bash
+npm install @atdt/geo-ui maplibre-gl pmtiles papaparse @mapbox/vector-tile pbf
+```
+
+**Importante**: Las dependencias `react` y `react-dom` son peer dependencies (versión 18+).
+
+## Uso Básico
+
+### Importar el componente
+
+```tsx
+import { MapaPMTiles } from '@atdt/geo-ui';
+import '@atdt/geo-ui/style.css';
+```
+
+### Ejemplo básico (usando valores por defecto)
+
+La biblioteca incluye **integrada** la URL del PMTiles de entidades de México, por lo que no necesitas especificar `pmtilesUrl`, `sourceLayer` ni `joinGeomKey` si trabajas con entidades:
+
+```tsx
+import React from 'react';
+import { MapaPMTiles } from '@atdt/geo-ui';
+import '@atdt/geo-ui/style.css';
+
+function App() {
+  return (
+    <MapaPMTiles
+      csvUrl="https://example.com/datos.csv"
+      field="valor"
+      mode="boolean"
+      width="100%"
+      height={600}
+    />
+  );
+}
+
+export default App;
+```
+
+### Ejemplo con csvUrl (especificando PMTiles personalizado)
+
+```tsx
+import React from 'react';
+import { MapaPMTiles } from '@atdt/geo-ui';
+import '@atdt/geo-ui/style.css';
+
+function App() {
+  return (
+    <MapaPMTiles
+      pmtilesUrl="https://example.com/custom.pmtiles"
+      sourceLayer="mi-capa"
+      joinGeomKey="ID"
+      csvUrl="https://example.com/datos.csv"
+      field="valor"
+      mode="boolean"
+      width="100%"
+      height={600}
+    />
+  );
+}
+
+export default App;
+```
+
+### Ejemplo con csvFile (archivo local)
+
+```tsx
+import React, { useState } from 'react';
+import { MapaPMTiles } from '@atdt/geo-ui';
+import '@atdt/geo-ui/style.css';
+
+function App() {
+  const [csvFile, setCsvFile] = useState<File | null>(null);
+
+  return (
+    <div>
+      <input
+        type="file"
+        accept=".csv"
+        onChange={(e) => setCsvFile(e.target.files?.[0] || null)}
+      />
+      {csvFile && (
+        <MapaPMTiles
+          csvFile={csvFile}
+          field="poblacion"
+          mode="jenks"
+          jenksK={5}
+        />
+      )}
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Ejemplo con fitToIds (zoom y filtrado por entidades)
+
+Muestra **solo** las entidades seleccionadas y ajusta el mapa automáticamente a su extensión (sin animación):
+
+```tsx
+// Mostrar solo Ciudad de México
+<MapaPMTiles
+  csvUrl="https://example.com/datos.csv"
+  fitToIds="09"
+/>
+
+// Mostrar múltiples entidades (Ciudad de México, Estado de México y Jalisco)
+<MapaPMTiles
+  csvUrl="https://example.com/datos.csv"
+  fitToIds={["09", "15", "14"]}
+/>
+```
+
+**Ventajas de usar `fitToIds`:**
+- No necesitas configurar `pmtilesUrl` (está integrado)
+- Filtra automáticamente para mostrar solo las entidades seleccionadas
+- Calcula y ajusta el bbox combinado sin animación de zoom
+- Carga directo en la vista correcta
+
+### Ejemplo con showMunicipios (visualización municipal)
+
+Cuando activas `showMunicipios={true}`, el componente cambia a **nivel municipal**:
+- La **entidad** se muestra solo como **contorno** (outline grueso)
+- Los **municipios** dentro de esa entidad se muestran con el **relleno temático** (boolean o jenks)
+- Los datos CSV se unen usando el **cvegeo municipal** (5 dígitos)
+
+```tsx
+// Mostrar municipios de Ciudad de México (09)
+// El CSV debe tener cvegeo municipal (ej: "09002", "09010", etc.)
+<MapaPMTiles
+  csvUrl="https://example.com/datos_municipales.csv"
+  fitToIds="09"
+  showMunicipios={true}
+  mode="jenks"
+  jenksK={5}
+/>
+
+// Mostrar municipios de múltiples entidades
+<MapaPMTiles
+  csvUrl="https://example.com/datos_municipales.csv"
+  fitToIds={["09", "15", "14"]}
+  showMunicipios={true}
+/>
+```
+
+**¿Cómo funciona?**
+1. `fitToIds="09"` extrae automáticamente `cve_ent="09"` (primeros 2 dígitos)
+2. Filtra y muestra **todos los municipios** con `cve_ent="09"`
+3. La entidad "09" se dibuja solo como contorno
+4. Los municipios se rellenan según los valores del CSV unidos por `cvegeo` (5 dígitos)
+
+**Formato CSV para municipios:**
+```csv
+cvegeo,nombre,valor
+09002,Azcapotzalco,150
+09003,Coyoacán,200
+09010,Álvaro Obregón,175
+```
+
+## Props
+
+### Props Obligatorias
+
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `csvUrl` o `csvFile` | `string \| File` | URL del CSV remoto o archivo File local. **Al menos uno debe estar presente** |
+
+### Props Opcionales
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `pmtilesUrl` | `string` | `"https://www.datosgeoespaciales.atdt.gob.mx/datalake/pmtiles/componente/entidad.pmtiles"` | URL del archivo PMTiles remoto. **Por defecto usa el PMTiles de entidades de México** |
+| `sourceLayer` | `string` | `"entidad"` | Nombre de la capa vectorial dentro del PMTiles |
+| `joinGeomKey` | `string` | `"cvegeo"` | Campo de la geometría para hacer el join (también usado como `promoteId`) |
+| `joinCsvKey` | `string` | `joinGeomKey` | Campo del CSV para hacer el join |
+| `field` | `string` | `"valor"` | Campo del CSV con los valores a visualizar |
+| `mode` | `"boolean" \| "jenks"` | `"boolean"` | Modo de estilo: booleano o clasificación Jenks |
+| `width` | `string \| number` | `"100%"` | Ancho del mapa |
+| `height` | `string \| number` | `520` | Alto del mapa (en px si es número) |
+| `initialView` | `object` | `{center: [-102, 23], zoom: 4}` | Vista inicial del mapa (ignorado si se usa `fitToIds`) |
+| `initialView.center` | `[number, number]` | `[-102, 23]` | Centro inicial [lng, lat] |
+| `initialView.zoom` | `number` | `4` | Zoom inicial |
+| `fitToIds` | `string \| string[]` | `undefined` | ID o array de IDs de features para filtrar y hacer zoom automático (sin animación) |
+| `bboxField` | `string` | `"bbox"` | Campo con bbox precalculado en PMTiles |
+| `jenksK` | `number` | `5` | Número de clases para clasificación Jenks |
+| `showMunicipios` | `boolean` | `false` | Activa modo municipal: muestra municipios con datos temáticos y entidad como contorno |
+
+## Modos de Estilo
+
+### Modo Boolean
+
+Pinta las geometrías en dos colores según el valor:
+
+- `value === 1` → **#66827f** (verde azulado)
+- `value === 0 / null / undefined` → **#f3f3f3** (gris claro)
+
+```tsx
+<MapaPMTiles
+  mode="boolean"
+  {...otherProps}
+/>
+```
+
+### Modo Jenks
+
+Clasifica los valores numéricos usando el algoritmo Jenks Natural Breaks y aplica una rampa de colores:
+
+- De **#f3f3f3** (gris claro) a **#66827f** (verde azulado)
+- Número de clases controlado por `jenksK` (default: 5)
+
+```tsx
+<MapaPMTiles
+  mode="jenks"
+  jenksK={7}
+  {...otherProps}
+/>
+```
+
+## Formato CSV
+
+El archivo CSV debe tener:
+
+- **Header row** con nombres de columnas
+- Una columna con el **join key** que coincida con el campo `joinGeomKey` de las geometrías
+- Una columna con los **valores** especificada en `field`
+
+Ejemplo:
+
+```csv
+CVE_ENT,nombre,valor
+01,Aguascalientes,1
+02,Baja California,0
+09,Ciudad de México,1
+```
+
+## Interactividad del Mapa
+
+El componente tiene **interactividad desactivada** por defecto para mantener un estilo estático:
+
+- `boxZoom`: false
+- `doubleClickZoom`: false
+- `dragRotate`: false
+- `keyboard`: false
+- `scrollZoom`: false
+- `touchPitch`: false
+- `dragPan`: false
+- `touchZoomRotate`: true (permitido)
+
+## Notas CORS
+
+Para consumir PMTiles y CSV de dominios externos, asegúrate de que:
+
+1. El servidor tenga configurado CORS adecuadamente
+2. Para PMTiles, el servidor debe soportar **Range requests** (HTTP 206)
+3. Headers necesarios:
+   ```
+   Access-Control-Allow-Origin: *
+   Access-Control-Allow-Headers: Range
+   Accept-Ranges: bytes
+   ```
+
+## Tecnologías
+
+- **React 18+**
+- **TypeScript**
+- **MapLibre GL JS**: Renderizado de mapas vectoriales
+- **PMTiles**: Formato de tiles vectoriales eficiente
+- **PapaParse**: Parsing de CSV
+- **Vite**: Build tool
+
+## Build y Desarrollo
+
+### Desarrollo local
+
+```bash
+npm install
+npm run dev
+```
+
+### Build de producción
+
+```bash
+npm run build
+```
+
+Esto genera:
+
+- `dist/geo-ui.js` (ES module)
+- `dist/geo-ui.umd.cjs` (UMD)
+- `dist/index.d.ts` (TypeScript definitions)
+- `dist/style.css` (estilos de MapLibre GL)
+
+### Publicar a npm
+
+```bash
+# Asegúrate de estar autenticado en npm
+npm login
+
+# Incrementa versión (patch, minor, major)
+npm version patch
+
+# Publica (ejecutará automáticamente build por prepublishOnly)
+npm publish --access public
+```
+
+**Nota**: Para paquetes con scope `@atdt/`, necesitas usar `--access public` la primera vez.
+
+## Estructura del Proyecto
+
+```
+geo-ui/
+├── src/
+│   ├── components/
+│   │   └── MapaPMTiles.tsx      # Componente principal
+│   ├── utils/
+│   │   ├── csv.ts               # Utilidades para parsear CSV
+│   │   ├── jenks.ts             # Algoritmo Jenks Natural Breaks
+│   │   └── pmtilesFeatureSearch.ts  # Búsqueda de features y bbox
+│   └── index.ts                 # Entry point
+├── dist/                        # Build output (generado)
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── README.md
+```
+
+## Licencia
+
+ISC
+
+## Autor
+
+Dirección de Datos Geográficos - ATDT
+
+## Contribuciones
+
+Issues y pull requests son bienvenidos en [GitLab](https://gitlab.com/atdt-desarrollogeo/componentes).