ixmaps-gl 0.2.1 → 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
@@ -192,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.1/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)
@@ -200,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.1/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.1/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.1';
+  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 —
@@ -3140,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)))
@@ -3611,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`);
@@ -5266,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);
   }
@@ -9364,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;
@@ -9987,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.1",
+  "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",