ixmaps-gl 0.2.30 → 0.2.33

package/README.md

@@ -114,10 +114,10 @@ page. It currently implements:
   `window.__setFacetFilter`) for building filterable sidebars
 - Globe (orthographic) projection alongside flat Mercator
 
-Not yet implemented: plain (non-AGGREGATE) `CATEGORICAL` choropleths, and the `QUAD`/
-`WAFFLE` base types, and SYMBOL shape variants beyond
-circle/square/diamond/triangle. See the top-of-file comment in
-[`ixmaps-gl.js`](./ixmaps-gl.js) for the exact, currently-accurate scope note.
+Not yet implemented: the `QUAD`/`WAFFLE` base types. Custom SYMBOL shapes are supported
+as image-URL symbols (`symbols: [...]`), not as built-in shape variants.
+The top-of-file comment in [`ixmaps-gl.js`](./ixmaps-gl.js) is the single source of truth
+for scope; this list only summarises it.
 
 ### Page scripts, named data and the runtime API
 
@@ -230,6 +230,38 @@ space beside it. `.options({themecopies: true})` (also at runtime) repeats the t
 copy. `.options({worldcopies: false})` draws the world once for the map itself, but MapLibre then
 also stops the zoom-out where the world gets narrower than the window.
 
+### Map events, bounds and the MapLibre map
+
+`map.on("zoomend moveend", fn)` (flat's `mapApi.on`; on the builder chain, the callback object or
+`ixmaps.map()`) fires:
+
+| event | when | handler receives |
+|---|---|---|
+| `ready` | the map has loaded (called at once if it already has) | `{type, szMap}` |
+| `viewchange` (`zoompan`) | after every pan or zoom | `{type, szMap, nZoom, zoomChanged, panChanged}` |
+| `zoomend` / `moveend` | the zoom changed / the centre moved without a zoom change | as `viewchange` |
+| `click` (`itemclick`) | an item was clicked — every item, also of a theme bound by geometry only | `{type, szMap, szId, id, theme, record, lngLat, point}` |
+| `mapclick` | any click on the map, background included (gl addition) | `{type, szMap, lngLat: {lng, lat}, point: {x, y}}` |
+| `layerdraw` (`drawtheme`) | after every redraw, once per theme | `{type, szMap, szId, id}` |
+
+`szId` is `theme::key` and `id` the key: the theme's selection field value (the `id`, position or lookup
+field), else the feature's `id`, else its position `"lng,lat"`; `record` is the item's data record (gl
+addition). `szMap` is the map's `name` option, or `null`. flat's `frozenDynamic` is not provided.
+`map.off("click", fn)` removes a handler, as in flat; several event names may be given, separated by
+spaces, and the names in brackets are flat's aliases.
+
+Differences from flat: `layerdraw` fires for every theme on every redraw, panning included (flat: once per
+theme as it is drawn); `ready` means the MapLibre map has loaded, themes may still be loading; view events
+fire when a movement ends, not during it. The other flat event names (`mouseover`/`itemover`,
+`mouseout`/`itemout`, `resize`, `layeradd`/`newtheme`, `layerremove`/`removetheme`) are accepted but never
+fire; the console says so once. `ixmaps.onItemAction(null, null, {lngLat, point})` gets the click position on
+a background click as a third argument; it is still called for items only when the theme has a selection
+field.
+
+`ixmaps.map().getBounds()` returns flat's `[swLat, swLng, neLat, neLng]` (`ixmaps.getBoundingBox()`
+the same box as `[{lat, lng} SW, {lat, lng} NE]`); `ixmaps.map().getMapLibre()` returns the MapLibre
+map itself, or `undefined` until it is built.
+
 ### Click to action
 
 flat's click-to-action (`ui/js/tools/tooltip_to_action.js`, e.g. a click on a country filters every
@@ -302,7 +334,7 @@ of your own project files gl can render.
 Load the engine from jsDelivr, pinned to a release tag (or `@main` for the latest commit):
 
 ```html
-<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.30/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.33/ixmaps-gl.js"></script>
 ```
 
 or from unpkg, the npm package [`ixmaps-gl`](https://www.npmjs.com/package/ixmaps-gl)
@@ -310,13 +342,13 @@ or from unpkg, the npm package [`ixmaps-gl`](https://www.npmjs.com/package/ixmap
 browser script, which defines the global `ixmaps`):
 
 ```html
-<script src="https://unpkg.com/ixmaps-gl@0.2.30/ixmaps-gl.js"></script>
+<script src="https://unpkg.com/ixmaps-gl@0.2.33/ixmaps-gl.js"></script>
 ```
 
 or use a local copy (`<script src="ixmaps-gl.js"></script>`). A minimal page:
 
 ```html
-<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.30/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.33/ixmaps-gl.js"></script>
 <div id="map_div" style="position:absolute;inset:0;"></div>
 
 <script>