ixmaps-gl 0.2.0 → 0.2.3

package/README.md

@@ -72,7 +72,7 @@ circle/square/diamond/triangle. See the top-of-file comment in
 A page's `.require(url)` scripts (page code, e.g. a user chart function) load in order before the
 layers are built. `ixmaps.map()` is the map handle as in flat — its calls wait until the map is ready —
 with `add(theme, flags)` / `replace` / `replaceTheme` / `remove`, `changeThemeStyle` for any style key,
-`getZoom()` (flat's zoom), `resize()` and `setBasemapOpacity`; the page's `htmlgui_onNewTheme(id)` and
+`getZoom()` (flat's zoom), `resize()`, `setBasemapOpacity` and `setMapType(id)` (also `setMapTypeId`, `mapType`: a basemap name reading dark/black/night/matter loads CARTO Dark Matter, any other name CARTO Positron, a color a plain background — the same rule the `mapType` option follows at start); the page's `htmlgui_onNewTheme(id)` and
 `htmlgui_onZoomAndPan()` (also once on load) are called (as in flat, a theme swapped in with `replace` comes last
 in the legend, while FEATURE and CHOROPLETH shapes always draw under the charts), and `map`, `getZoom` and flat's
 `formatValue` exist as globals. `.data({name})` without a URL waits for data of that name: from
@@ -155,8 +155,9 @@ ones, `replace` swaps themes by `style.name`/`meta.name`, `themeonly`/`maponly`/
 work as in flat. Themes in flat's older shape (data source in `style.dbtable*`, value field at
 the top level) are translated first. It resolves to `{ themes, skipped, notes }`: a theme
 that can't load is skipped with a warning, the rest still load. **Code a project names is not
-run by default** — `required` scripts, `ext` data scripts and a project's `process` functions are
-reported, not executed (only a page's own `.data({process})` runs) — and the basemap isn't switched.
+run by default** — `required` scripts, `ext` data scripts and a project's `process` and `query`
+functions and function-string `colorscheme`s are reported, not executed (only a page's own
+`.data({process, query})` and colorscheme functions run) — and the basemap isn't switched.
 
 A page can opt in to a project's **scripts** (`data.ext`) for script URLs under prefixes it lists —
 no built-in prefixes, and a project file's own `options.trustedscripts` is ignored. Both of flat's
@@ -181,7 +182,9 @@ script. For brokers that query by view, like flat's bbox data providers, ixmaps-
 `ixmaps.getBoundingBox()`, `ixmaps.refreshTheme(id)` (loads the theme's data again, in place),
 `ixmaps.setTitle(html)`/`setTitleBox(text, color)`, `ixmaps.getThemeObj(id).fVisible` (false for a
 FEATURE theme out of scale) and calls a page's `ixmaps.htmlgui_onZoomAndPan(zoom)` after each zoom
-or pan. Scripts that reach further into flat's internals (`ixmaps.parentApi`, other `htmlgui_*`
+or pan — and also during a zoom, at the pace of the layer refresh (about every 150 ms, zoom changes only),
+so zoom-dependent page state (e.g. a basemap opacity ramp) changes in step with the scale gates
+(`featurelower`, `chartupper`, …) instead of after the gesture has ended. Scripts that reach further into flat's internals (`ixmaps.parentApi`, other `htmlgui_*`
 hooks) aren't supported. `test/project-report.mjs` shows which themes
 of your own project files gl can render.
 
@@ -190,7 +193,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.0/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.3/ixmaps-gl.js"></script>
 ```
 
 or from unpkg, the npm package [`ixmaps-gl`](https://www.npmjs.com/package/ixmaps-gl)
@@ -198,13 +201,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.0/ixmaps-gl.js"></script>
+<script src="https://unpkg.com/ixmaps-gl@0.2.3/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.0/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.3/ixmaps-gl.js"></script>
 <div id="map_div" style="position:absolute;inset:0;"></div>
 
 <script>

package/ixmaps-gl.js

@@ -80,7 +80,7 @@
   // ---------------------------------------------------------------
   // this engine's release (= package.json "version", checked by
   // test/unit/version.test.mjs); ixmaps.glVersion, and logged once at start
-  const IXMAPS_GL_VERSION = '0.2.0';
+  const IXMAPS_GL_VERSION = '0.2.3';
 
   const LIB_URLS = {
     // Bumped 3.6.2 -> 5.x (2026-09-21, globe-projection compat fix): native
@@ -1720,7 +1720,7 @@
   // htmlgui_flat.js). Its methods act on the last built map; called while
   // the map is still building, they run once it is ready.
   const MAP_HANDLE_METHODS = ['replace', 'add', 'remove', 'removeTheme', 'replaceTheme', 'changeThemeStyle', 'setThemeStyle',
-    'refreshTheme', 'setBasemapOpacity', 'resize', 'view', 'options', 'layer', 'loadProject', 'require', 'setThemeVisible'];
+    'refreshTheme', 'setBasemapOpacity', 'setMapType', 'setMapTypeId', 'mapType', 'resize', 'view', 'options', 'layer', 'loadProject', 'require', 'setThemeVisible'];
   const _mapHandle = {};
   for (const m of MAP_HANDLE_METHODS) {
     _mapHandle[m] = (...args) => {
@@ -2148,6 +2148,36 @@
     dbtable: 'name', dbtableUrl: 'url', dbtableType: 'type', dbtableExt: 'ext',
     dbtableProcess: 'process', dbtableQuery: 'query', dbtableObj: 'obj', datacache: 'cache',
   };
+  // Every project key the engine would turn into code (new Function)
+  // is kept out, never run — a page's own .data({process, query}) and
+  // .style({colorscheme: fn.toString()}) still run. Project keys of
+  // that kind: the data processing function (data.process /
+  // style.dbtableProcess), the broker query (data.query /
+  // style.dbtableQuery — without it a data.name still reaches a
+  // provider the PAGE defined as ixmaps[name]) and a colorscheme given
+  // as a string, which resolveColorScheme evaluates as a function
+  // (an array colorscheme is data and stays).
+  const PROJECT_CODE_KEYS = [
+    ['data', 'process', 'data.process function'],
+    ['style', 'dbtableProcess', 'data.process function'],
+    ['data', 'query', 'data.query function'],
+    ['style', 'dbtableQuery', 'data.query function'],
+    ['style', 'colorscheme', 'colorscheme function', v => typeof v === 'string'],
+  ];
+  function withoutProjectCode(t, report) {
+    const found = PROJECT_CODE_KEYS.filter(([part, key, , isCode]) =>
+      t[part] && t[part][key] != null && (!isCode || isCode(t[part][key])));
+    if (!found.length) return t;
+    const copy = Object.assign({}, t);
+    found.forEach(([part, key]) => {
+      if (copy[part] === t[part]) copy[part] = Object.assign({}, t[part]);
+      delete copy[part][key];
+    });
+    const what = [...new Set(found.map(f => f[2]))].join(', ');
+    report.notes.push(`theme "${t.layer}": the project's ${what} is never run by ixmaps-gl`);
+    return copy;
+  }
+
   function projectThemeToDefinition(theme) {
     const t = theme || {};
     const style = Object.assign({}, t.style);
@@ -2418,6 +2448,19 @@
     const named = NAMED_MAPTYPE_COLORS[t.toLowerCase()];
     return named || null;
   }
+  // A basemap NAME (flat's mapType: "VT_TONER_LITE", "VT_DATAVIZ_DARK",
+  // "CartoDB - Dark matter", ...) picks one of two keyless CARTO vector
+  // styles: dark for a name reading dark/black/night/matter, otherwise
+  // light (Positron, gl's default). A color mapType (resolveMapTypeColor)
+  // is a plain background instead and wins, so "dark" alone stays the
+  // #1a1a1a background it always was.
+  const BASEMAP_STYLE_URLS = {
+    light: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
+    dark: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
+  };
+  function resolveBasemapStyleUrl(mapType) {
+    return typeof mapType === 'string' && /dark|black|night|matter/i.test(mapType) ? BASEMAP_STYLE_URLS.dark : BASEMAP_STYLE_URLS.light;
+  }
   // Real ixmaps-flat's legend look (tools/legend.js 3773-3845, via
   // tools/background_theme.js): DARK when the basemap is more than half
   // opaque and the map background reads as dark — a map type naming
@@ -2688,7 +2731,7 @@
       const map = new maplibregl.Map({
         container: this.containerId,
         style: mapTypeColor ? buildBlankBackgroundStyle(mapTypeColor)
-                             : 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
+                             : resolveBasemapStyleUrl(this.mapOptions.mapType),
         center: [lon, lat],
         zoom: this._viewZoom != null && this._viewZoom !== '' ? flatToMapLibreZoom(Number(this._viewZoom)) : 8,
         // .attribution(a) (MapBuilder, above) was stored but never read —
@@ -2728,6 +2771,16 @@
       // broker re-queries its data from it. Read at call time: pages wrap
       // it after loading. flat passes its SVG zoom scale; this passes the
       // flat zoom level, the one value gl has.
+      //
+      // gl also calls it DURING a zoom (notifyZoomAndPanMidGesture, wired
+      // into the throttled refresh below), zoom changes only: the scale
+      // gates (featurelower/chartupper ...) switch on the live zoom while
+      // the gesture runs, so a page that ties something zoom-dependent to
+      // this hook (e.g. a basemap opacity ramp) must be told in the same
+      // tick — from 'moveend' alone it arrived after the gate had already
+      // flipped (FEATURE gone, basemap still at the old, faint opacity: a
+      // blank background until the zoom ended).
+      let notifyZoomAndPanMidGesture = () => {};
       {
         let last = null;
         map.on('moveend', () => {
@@ -2739,6 +2792,14 @@
           if (z === prev.z && Math.abs(p.x - q.x) <= 10 && Math.abs(p.y - q.y) <= 10) return;
           try { hook.call(global.ixmaps, mapLibreToFlatZoom(z)); } catch (e) { console.error('[ixmaps-gl] htmlgui_onZoomAndPan:', e); }
         });
+        notifyZoomAndPanMidGesture = () => {
+          const hook = pageIxmaps() && pageIxmaps().htmlgui_onZoomAndPan;
+          if (typeof hook !== 'function' || !last) return;
+          const z = map.getZoom();
+          if (z === last.z) return; // a pan alone waits for 'moveend' (and its 10 px rule)
+          last = { z, c: map.getCenter() };
+          try { hook.call(global.ixmaps, mapLibreToFlatZoom(z)); } catch (e) { console.error('[ixmaps-gl] htmlgui_onZoomAndPan:', e); }
+        };
         // flat calls it on the first draw too (its old zoom is unset then)
         map.once('load', () => {
           last = { z: map.getZoom(), c: map.getCenter() };
@@ -3122,6 +3183,31 @@
         },
         replaceTheme: (id, layerBuilder, flag) => engineApi.replace(id, layerBuilder, flag),
         remove: (id) => { removeThemeById(id); return engineApi; },
+        // flat's map.setMapType(id) / setMapTypeId / mapType (htmlgui_flat.js
+        // mapApi): swap the basemap at runtime. MapLibre's setStyle replaces
+        // the whole style; deck.gl's interleaved overlay re-adds its own
+        // layers on 'styledata' by itself. What the new style resets is put
+        // back once it has loaded: the projection (globe), the basemap
+        // opacity (it is written into the style's paint properties).
+        setMapType: (id) => {
+          const color = resolveMapTypeColor(id);
+          const style = color ? buildBlankBackgroundStyle(color) : resolveBasemapStyleUrl(id);
+          const current = color ? null : resolveBasemapStyleUrl(builder.mapOptions.mapType);
+          const wasColor = !!resolveMapTypeColor(builder.mapOptions.mapType);
+          builder.mapOptions.mapType = id;
+          if (!color && !wasColor && style === current) return engineApi; // same style: nothing to reload
+          const projection = typeof map.getProjection === 'function' ? map.getProjection() : null;
+          map.once('style.load', () => {
+            if (projection && projection.type && typeof map.setProjection === 'function') {
+              try { map.setProjection({ type: projection.type }); } catch (e) { /* projection unsupported by this build */ }
+            }
+            applyBasemapOpacity();
+          });
+          map.setStyle(style);
+          return engineApi;
+        },
+        setMapTypeId: (id) => engineApi.setMapType(id),
+        mapType: (id) => engineApi.setMapType(id),
         setBasemapOpacity: (delta, mode) => {
           _basemapOpacity = mode === 'relative'
             ? Math.max(0, Math.min(1, _basemapOpacity + (parseFloat(delta) || 0)))
@@ -3593,19 +3679,6 @@
         return report;
       }
 
-      // a project file's data processing function is code the project
-      // names — kept out, never run (a page's own .data({process}) runs)
-      function withoutProjectCode(t, report) {
-        const hasData = t.data && t.data.process != null;
-        const hasStyle = t.style && t.style.dbtableProcess != null;
-        if (!hasData && !hasStyle) return t;
-        report.notes.push(`theme "${t.layer}": the project's data.process function is never run by ixmaps-gl`);
-        const copy = Object.assign({}, t);
-        if (hasData) { copy.data = Object.assign({}, t.data); delete copy.data.process; }
-        if (hasStyle) { copy.style = Object.assign({}, t.style); delete copy.style.dbtableProcess; }
-        return copy;
-      }
-
       function applyProjectMap(m, f, report) {
         const svg = String(m.map || '');
         if (svg && !/generic\/(mercator|orthographic)\.svg$/i.test(svg)) report.notes.push(`flat SVG map "${svg.split('/').pop()}" is not available in ixmaps-gl — mercator used`);
@@ -3878,10 +3951,11 @@
         const elapsed = now - lastRefreshAt;
         if (elapsed >= REFRESH_INTERVAL_MS) {
           lastRefreshAt = now;
+          notifyZoomAndPanMidGesture();
           refreshLayers();
         } else {
           clearTimeout(refreshTimer);
-          refreshTimer = setTimeout(() => { lastRefreshAt = Date.now(); refreshLayers(); }, REFRESH_INTERVAL_MS - elapsed);
+          refreshTimer = setTimeout(() => { lastRefreshAt = Date.now(); notifyZoomAndPanMidGesture(); refreshLayers(); }, REFRESH_INTERVAL_MS - elapsed);
         }
         scheduleNotifyRedraw();
       }
@@ -5247,6 +5321,16 @@
     return text;
   }
 
+  // Records behind one drawn chart item: a group's per-category record
+  // counts summed, else a Supercluster cluster's point_count, else 1.
+  // recordCounts only exists on RELOCATE groups (groupCoLocated); a plain
+  // grid group (no RELOCATE) carries counts only — read unguarded, BOX|TITLE
+  // without RELOCATE threw on the first cluster and the theme stopped drawing.
+  function groupRecordCount(props) {
+    const perCat = props.recordCounts || props.counts;
+    return perCat ? perCat.reduce((x, c) => x + c, 0) : (props.point_count || 1);
+  }
+
   function valuesFontSizePx(radiusPx, text, valueScale) {
     return Math.min(radiusPx * 0.8, radiusPx * (3.3 / Math.max(1, text.length))) * (valueScale || 1);
   }
@@ -9345,7 +9429,7 @@
         let title = null;
         if (titleShown) {
           const raw = d.properties.raw;
-          const n = d.properties.counts ? d.properties.recordCounts.reduce((x, c) => x + c, 0) : (d.properties.point_count || 1);
+          const n = groupRecordCount(d.properties);
           const text = n > 3 ? '(' + n + ')' : (raw && raw[this.binding.title] != null ? String(raw[this.binding.title]) : '');
           if (text) {
             const f = titleFontPx;
@@ -9968,7 +10052,7 @@
   // engine runs in a Node vm there); deliberately NOT on the ixmaps object
   global.__ixmapsGlInternals = {
     IXMAPS_GL_VERSION,
-    normalizeTheme, projectThemeToDefinition, LayerBuilder, LayerRuntime, typeStyleNumbers, styleNum,
+    normalizeTheme, projectThemeToDefinition, withoutProjectCode, groupRecordCount, resolveBasemapStyleUrl, resolveMapTypeColor, LayerBuilder, LayerRuntime, typeStyleNumbers, styleNum,
     resolveScriptUrl, isTrustedScriptUrl, loadProcessingScript, loadBrokerData, applyBrokerThemePatch, makeBrokerTheme,
     equalIntervalBreaks, quantileBreaks, naturalBreaks, evenStrideSample, jenksBreakValues, partsFromBreakValues, resolvePartsClass,
     computeAlphaStats, computeMultiFieldClasses, computeDominantStats, resolveDominantClass, computeComposeColorStats,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ixmaps-gl",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "MapLibre GL + deck.gl reimplementation of the ixmaps-flat declarative mapping engine",
   "main": "ixmaps-gl.js",
   "browser": "ixmaps-gl.js",