ixmaps-gl 0.2.1 → 0.2.4

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.4/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.4/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.4/ixmaps-gl.js"></script>
 <div id="map_div" style="position:absolute;inset:0;"></div>
 
 <script>
@@ -272,7 +273,7 @@ For checking page files before they run, use the static checker in ixmaps-gramma
 | [`mappa_stranieri_30.html`](./stage/mappa_stranieri_30.html) | Symbol shapes, city picker, runtime `changeThemeStyle` filtering, light legend theme |
 | [`roma_incidenti_pericolosita_sidebar_gl.html`](./stage/roma_incidenti_pericolosita_sidebar_gl.html) | AGGREGATE on a gridwidth grid, facets sidebar |
 | [`roma_incidenti_pericolosita_sidebar.html`](./stage/roma_incidenti_pericolosita_sidebar.html) | The same page on the **real** ixmaps-flat engine, kept for side-by-side reference |
-| [`uk_collisions_2023.html`](./stage/uk_collisions_2023.html), [`ixmaps-loader_70.html`](./stage/ixmaps-loader_70.html) | Additional real-page compatibility tests |
+| [`uk_collisions_2023.html`](./stage/uk_collisions_2023.html), [`app/ixmaps-loader_70.html`](./app/ixmaps-loader_70.html) | Additional real-page compatibility tests |
 | [`examples/`](./examples) | Smaller feature-by-feature test pages (choropleth classing modes, bubble ranges, etc.) |
 
 Serve any of these with a static file server (they fetch remote data over HTTPS, so

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.4';
 
   const LIB_URLS = {
     // Bumped 3.6.2 -> 5.x (2026-09-21, globe-projection compat fix): native
@@ -306,7 +306,7 @@
   // crafted link must not be able to load arbitrary code into the page.
   // ---------------------------------------------------------------
   // v0.1.6: knows this engine's aliases, lookupfield rule, meta↔style, builder methods, project loading
-  const VALIDATOR_URL_DEFAULT = 'https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-grammar@v0.1.20/dist/validate.mjs';
+  const VALIDATOR_URL_DEFAULT = 'https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-grammar@v0.1.21/dist/validate.mjs';
   // a page may set ixmaps.validate BEFORE loading this script — the
   // `global.ixmaps = {...}` export below would otherwise overwrite it
   const _preloadValidate = global.ixmaps && global.ixmaps.validate;
@@ -587,6 +587,78 @@
     }
     return null;
   }
+  // ---------------------------------------------------------------
+  // flat's data cache (maptheme.js 2457-2500, themeDataCacheA): data once
+  // loaded from a source is reused by every later theme of the map with the
+  // same source — data.cache (also style.datacache, see the dbtable* table)
+  // defaults to true (fDataCache, maptheme.js 7736); cache: false reloads.
+  // The key is the fetch identity PLUS the shape the binding asks for:
+  // rowsResult() turns the same CSV rows into a Table (lookup only) or a
+  // FeatureCollection (position), so two themes reading one URL differently
+  // must not share one result.
+  // ---------------------------------------------------------------
+  // the data source itself (no shape) — also rt._dataSourceKey, which tells the
+  // facet filters which themes share one dataset (setFacetFilter)
+  function dataSourceKey(data) {
+    const d = data || {};
+    return JSON.stringify({ url: d.url, urls: d.urls, type: d.type, query: d.query,
+      process: d.process && String(d.process), ext: d.ext, name: d.ext ? d.name : undefined });
+  }
+  function dataCacheKey(data, binding) {
+    const b = binding || {};
+    return dataSourceKey(data) + '|' + (b.lookup && !b.position ? 'table' : 'pos:' + (b.position || ''));
+  }
+  function dataCacheDisabled(dataConfig) {
+    const c = dataConfig && dataConfig.cache;
+    return c === false || (typeof c === 'string' && c.trim().toLowerCase() === 'false');
+  }
+  // cache: Map key → Promise; a failed load is not kept (the next theme tries again)
+  function cachedLayerData(cache, data, binding, engineOptions, { reload = false } = {}) {
+    const key = dataCacheKey(data, binding);
+    if (reload || dataCacheDisabled(data) || !cache.has(key)) {
+      const p = fetchLayerData(data, binding, engineOptions);
+      cache.set(key, p);
+      p.catch(() => { if (cache.get(key) === p) cache.delete(key); });
+    }
+    return { key, sourceKey: dataSourceKey(data), promise: cache.get(key) };
+  }
+
+  // ---------------------------------------------------------------
+  // SHOW / ZOOMTO (flat maptheme.js 8714-8740, MapTheme.zoomTo 15664): once
+  // a theme is drawn, the map zooms to the extent of its items, then the
+  // flag is dropped — once per theme definition, not on every redraw.
+  // featuresBounds: [[west, south], [east, north]] of every coordinate, or
+  // null when there is none.
+  // ---------------------------------------------------------------
+  function featuresBounds(features) {
+    let w = Infinity, s = Infinity, e = -Infinity, n = -Infinity;
+    const visit = c => {
+      if (!Array.isArray(c)) return;
+      if (typeof c[0] === 'number' && typeof c[1] === 'number') {
+        if (!isFinite(c[0]) || !isFinite(c[1]) || Math.abs(c[1]) > 90) return;
+        if (c[0] < w) w = c[0]; if (c[0] > e) e = c[0];
+        if (c[1] < s) s = c[1]; if (c[1] > n) n = c[1];
+        return;
+      }
+      for (const x of c) visit(x);
+    };
+    const geom = g => {
+      if (!g) return;
+      if (g.type === 'GeometryCollection') (g.geometries || []).forEach(geom);
+      else visit(g.coordinates);
+    };
+    for (const f of features || []) geom(f && f.geometry);
+    return w === Infinity ? null : [[w, s], [e, n]];
+  }
+  // the `legend` map option as flat reads it (htmlgui_flat.js 748-794): on whenever given
+  // and not false/"false"/0
+  function legendIsOn(opt) {
+    return opt !== undefined && opt !== null && opt !== false && opt !== 'false' && opt !== 0 && opt !== '0';
+  }
+  function wantsZoomToExtent(flags) {
+    return !!flags && (flags.has('SHOW') || flags.has('ZOOMTO'));
+  }
+
   function rowsResult(rows, binding) {
     if (binding && binding.lookup && !binding.position) return { type: 'Table', rows };
     const position = (binding && binding.position) || geometryField(rows);
@@ -1720,7 +1792,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) => {
@@ -1994,7 +2066,7 @@
   // edit it by hand; `npm run unit` fails when it drifts.
   // ---------------------------------------------------------------
   // <grammar:binding-aliases>
-  // generated from ixmaps-grammar 0.1.20 (ixmaps-flat 1.0.41, eaaf2b7 2026-09-20) — 52 aliases
+  // generated from ixmaps-grammar 0.1.21 (ixmaps-flat 1.0.41, eaaf2b7 2026-09-20) — 52 aliases
   const FLAT_BINDING_ALIASES = {
     "aggregation": "style.aggregationfield",
     "aggregationfield": "style.aggregationfield",
@@ -2056,7 +2128,7 @@
   // both — so .style({tooltip}) is a tooltip and .meta({fillopacity}) a style
   // property. GENERATED by test/sync-grammar.mjs — do not edit.
   // <grammar:meta-keys>
-  // generated from ixmaps-grammar 0.1.20 — 5 meta keys
+  // generated from ixmaps-grammar 0.1.21 — 5 meta keys
   const FLAT_META_KEYS = ["description","name","snippet","title","tooltip"];
   // </grammar:meta-keys>
 
@@ -2148,6 +2220,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 +2520,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
@@ -2610,7 +2725,9 @@
       // ones. Confirmed live as a real, not just theoretical, problem:
       // without this, a 3-layer page sharing one >1.2M-row multi-file CSV
       // source fetched all 5 files 3 SEPARATE times.
-      const dataCache = new Map();
+      // one data cache for the map's whole lifetime (flat's themeDataCacheA):
+      // build() and every later defineLayer()/refreshTheme() share it
+      const dataCache = this._dataCache = this._dataCache || new Map();
       const runtimes = [];
       // themes whose data comes by name (see namedDataTheme) start empty and
       // load on their own once the map is built, as in flat, where every
@@ -2650,9 +2767,9 @@
           raw = await fetchLayerData(spec.data, spec.binding, this._engineOptions);
           cacheKey = 'obj:' + spec.name;
         } else {
-          cacheKey = JSON.stringify({ url: spec.data && spec.data.url, urls: spec.data && spec.data.urls, type: spec.data && spec.data.type, query: spec.data && spec.data.query, process: spec.data && spec.data.process && String(spec.data.process), ext: spec.data && spec.data.ext, name: spec.data && spec.data.ext ? spec.data.name : undefined });
-          if (!dataCache.has(cacheKey)) dataCache.set(cacheKey, fetchLayerData(spec.data, spec.binding, this._engineOptions));
-          raw = await dataCache.get(cacheKey);
+          const cached = cachedLayerData(dataCache, spec.data, spec.binding, this._engineOptions);
+          cacheKey = cached.sourceKey;
+          raw = await cached.promise;
         }
         const filtered = applyWhereFilter(raw, spec.filter);
         const fc = filtered.type === 'Table' ? joinTableFeatures(spec, filtered, runtimes) : filtered;
@@ -2666,6 +2783,7 @@
         rt._definition = def; // for refreshTheme
         rt._deferredLoad = deferred;
         rt._named = named;
+        rt._zoomToPending = wantsZoomToExtent(spec.flags);
         runtimes.push(rt);
         notifyNewTheme(rt);
         _globalThemeRegistry.set(rt.name, rt);
@@ -2688,7 +2806,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 —
@@ -2722,6 +2840,10 @@
         const b = map.getBounds();
         return [{ lat: b.getSouth(), lng: b.getWest() }, { lat: b.getNorth(), lng: b.getEast() }];
       };
+      // set once by the 'load' event — NOT map.loaded(), which MapLibre turns false again
+      // whenever tiles are loading (after every pan/zoom), so a theme defined then would
+      // wait for a 'load' that never fires again (SHOW / ZOOMTO, see maybeZoomToTheme)
+      let mapHasLoaded = false;
 
       // flat's page hook ixmaps.htmlgui_onZoomAndPan(nZoom), called after
       // a zoom or a pan of more than 10 px (mapscript2.js 6445-6454) — a
@@ -3104,6 +3226,7 @@
         else map.once('idle', () => map.fire('move'));
       };
       let addLegendPanel = () => {}; // set up with the legend, below
+      let setLegendOption = () => {}; // map.setLegend(value) — set up with the legend, below
       let updateSubTheme = () => {};
       let layoutLegends = () => {}; // set up with the legend, below
       let setDataLoading = () => {}; // set up with the loads, below
@@ -3140,6 +3263,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)))
@@ -3290,10 +3438,14 @@
         options: (o) => {
           if (o && typeof o === 'object') {
             Object.assign(builder._engineOptions, o);
+            // read only when the MapLibre map is created — switched here at runtime
+            if ('worldcopies' in o) map.setRenderWorldCopies(o.worldcopies !== false && o.worldcopies !== 'false');
             refresh();
           }
           return engineApi;
         },
+        // the `legend` map option at runtime (see setLegendOption)
+        setLegend: (opt) => { setLegendOption(opt); return engineApi; },
         layer: (nameOrBuilder) => {
           if (typeof nameOrBuilder !== 'string') {
             const lb = nameOrBuilder;
@@ -3345,9 +3497,14 @@
           for (const rt of targets) {
             if (rt._named) { await loadNamedTheme(rt, true); continue; }
             const spec = normalizeTheme(rt._definition);
-            const raw = await fetchLayerData(spec.data, rt._specBinding, builder._engineOptions);
+            // flat's refresh reloads, cache or not (maptheme.js 2366: datacache = false);
+            // the fresh result also replaces the cached one for later themes
+            const raw = spec.data && spec.data.obj
+              ? await fetchLayerData(spec.data, rt._specBinding, builder._engineOptions)
+              : await cachedLayerData(builder._dataCache, spec.data, rt._specBinding, builder._engineOptions, { reload: true }).promise;
             const filtered = applyWhereFilter(raw, spec.filter);
             rt.replaceFeatures(filtered.type === 'Table' ? joinTableFeatures(spec, filtered, runtimes) : filtered);
+            maybeZoomToTheme(rt); // a scale-deferred theme gets its first data here
           }
           if (targets.length) { refresh(); notifyRedraw(); }
         }
@@ -3438,6 +3595,19 @@
           loadingEl.style.display = 'none';
         }
       };
+      // SHOW / ZOOMTO: zoom to the theme's extent the first time it has
+      // features on a loaded map (see featuresBounds), then never again for
+      // this definition — as flat drops the flag after its zoomTo()
+      function maybeZoomToTheme(rt) {
+        if (!rt || !rt._zoomToPending || !mapHasLoaded || !runtimes.includes(rt)) return;
+        const bounds = featuresBounds(rt.features);
+        if (!bounds) return; // no data yet (named / deferred): wait for it
+        rt._zoomToPending = false;
+        const [[w, s], [e, n]] = bounds;
+        if (w === e && s === n) map.jumpTo({ center: [w, s], zoom: Math.max(map.getZoom(), 12) });
+        else map.fitBounds(bounds, { padding: 30, animate: false, maxZoom: 16 });
+      }
+
       async function loadNamedTheme(rt, force) {
         const spec = normalizeTheme(rt._definition);
         const name = String(spec.data.name);
@@ -3455,7 +3625,7 @@
             table = await w.promise;
           }
           await built;
-          if (runtimes.includes(rt)) fillNamedTheme(rt, spec, table, patch);
+          if (runtimes.includes(rt)) { fillNamedTheme(rt, spec, table, patch); maybeZoomToTheme(rt); }
         } catch (err) {
           // a broker that hands nothing over yet is normal in flat (it may
           // wait for other data); the theme stays empty until a refresh
@@ -3536,10 +3706,16 @@
         let raw;
         const deferred = deferredFeatureLoad(spec, map.getZoom());
         const named = namedDataTheme(spec);
+        let sourceKey = null;
         if (deferred || named) {
           raw = { type: 'FeatureCollection', features: [] };
-        } else {
+        } else if (spec.data && spec.data.obj) {
+          // in memory already — nothing to cache (see build())
           raw = await fetchLayerData(spec.data, spec.binding, builder._engineOptions);
+        } else {
+          const cached = cachedLayerData(builder._dataCache, spec.data, spec.binding, builder._engineOptions);
+          sourceKey = cached.sourceKey;
+          raw = await cached.promise;
         }
         const filtered = applyWhereFilter(raw, spec.filter);
         const fc = filtered.type === 'Table' ? joinTableFeatures(spec, filtered, runtimes) : filtered;
@@ -3547,8 +3723,9 @@
         rt._definition = pdef; // for refreshTheme
         rt._deferredLoad = deferred;
         rt._named = named;
+        rt._zoomToPending = wantsZoomToExtent(spec.flags);
         rt._dataSourceKey = named ? 'name:' + spec.data.name
-          : JSON.stringify({ url: spec.data && spec.data.url, urls: spec.data && spec.data.urls, type: spec.data && spec.data.type, query: spec.data && spec.data.query, obj: !!(spec.data && spec.data.obj) });
+          : sourceKey || JSON.stringify({ url: spec.data && spec.data.url, urls: spec.data && spec.data.urls, type: spec.data && spec.data.type, query: spec.data && spec.data.query, obj: !!(spec.data && spec.data.obj) });
         runtimes.push(rt);
         _globalThemeRegistry.set(rt.name, rt);
         if (rt.meta && rt.meta.name && rt.meta.name !== rt.name) _globalThemeRegistry.set(rt.meta.name, rt);
@@ -3556,6 +3733,7 @@
         notifyNewTheme(rt);
         refresh();
         notifyRedraw();
+        maybeZoomToTheme(rt); // before the map's 'load': its handler zooms pending themes
         if (named) { listenNamedData(rt); if (!deferred) loadNamedTheme(rt, false); }
         return rt.name;
       }
@@ -3611,19 +3789,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`);
@@ -3875,8 +4040,10 @@
       map.on('moveend', loadDeferredThemes);
 
       map.on('load', () => {
+        mapHasLoaded = true;
         loadDeferredThemes();
         refresh();
+        runtimes.forEach(maybeZoomToTheme);
         hideSplash(splash);
         const initialOpacity = parseFloat(this._engineOptions.basemapopacity);
         if (!isNaN(initialOpacity)) { _basemapOpacity = Math.max(0, Math.min(1, initialOpacity)); applyBasemapOpacity(); }
@@ -3986,8 +4153,9 @@
       // isn't false/"false" ("true", "open", "", 1, …), folded for
       // "closed", off when not given at all.
       const legendOpt = this.mapOptions.legend;
-      const legendOn = legendOpt !== undefined && legendOpt !== null && legendOpt !== false && legendOpt !== 'false' && legendOpt !== 0 && legendOpt !== '0';
-      const legendFolded = legendOpt === 'closed';
+      // let, not const: map.setLegend(value) switches them at runtime (see setLegendOption)
+      let legendOn = legendIsOn(legendOpt);
+      let legendFolded = legendOpt === 'closed';
       {
         // Map-level `align` option positions the legend panel — a map-
         // wide placement choice, not per-theme (unlike legendtheme/
@@ -4104,6 +4272,23 @@
           el.parentElement.appendChild(legendStack);
           return legendStack;
         };
+        // map.setLegend(value): the `legend` map option at runtime, same values as
+        // ixmaps.Map(id, {legend}) — on ("true", "open", …), folded ("closed"), off
+        // (false/"false"/0/undefined). Panels are made for themes that lack one,
+        // removed when off, folded/unfolded otherwise.
+        setLegendOption = (opt) => {
+          builder.mapOptions.legend = opt;
+          legendFolded = opt === 'closed';
+          legendOn = legendIsOn(opt);
+          runtimes.forEach(rt => {
+            if (!legendOn) {
+              if (rt._legendPanel && rt._legendPanel.parentNode) rt._legendPanel.parentNode.removeChild(rt._legendPanel);
+              rt._legendPanel = null;
+            } else if (!rt._legendPanel) addLegendPanel(rt);
+            else if (rt._setLegendCollapsed) rt._setLegendCollapsed(legendFolded);
+          });
+          layoutLegends();
+        };
         layoutLegends = () => {
           if (!legendStack) return;
           const z = map.getZoom();
@@ -4498,6 +4683,7 @@
             }
             collapseBtn.addEventListener('click', () => { collapsed = !collapsed; applyCollapsed(); });
             applyCollapsed();
+            rt._setLegendCollapsed = c => { collapsed = !!c; applyCollapsed(); }; // setLegendOption
 
             // Selection/filter by field — opt-in via .style({legendfilter:
             // "<field>"}), e.g. "country_long" on the power-plants sample.
@@ -5266,6 +5452,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 +9560,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 +10183,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,
@@ -9997,6 +10193,7 @@
     fetchLayerData, parseCsvText, dataTableRows, geometryRowsToFeatureCollection, filterFlatValues, applyField100, field100Binding, rangeClassLegendTotals, resolveAggregateValue, classValueSeparate, cellAggregatedValues, oneHot, groupCoLocated, aggregateOnGrid, GridAggregateIndex, flatRangeParts, aggregateField100, formatBubbleValue, valueRadius, itemPlotGeometry, itemAnchor, objectZoomFactor, resolveZoomReference, defaultNormalSizeValue,
     applyWhereFilter, joinChartPositions, flatLookupKey, flatShapeCenter, chartHiddenByScale, featuresHiddenByScale, boxHiddenByScale, flatShadowOn, snapToAggregationGrid,
     flatFormatValue,
+    dataCacheKey, dataCacheDisabled, cachedLayerData, featuresBounds, wantsZoomToExtent, legendIsOn,
   };
   global.__setFilter = __setFilter;
   global.__removeFacets = __removeFacets;

package/package.json

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