ixmaps-gl 0.2.25 → 0.2.30

package/README.md

@@ -124,7 +124,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()`, `attribution(text)` (the page's attribution, bottom left on the map as in flat, in the style of the basemap credit and on its line — also
+`getZoom()` (flat's zoom), `resize()`, `attribution(text)` (the page's attribution, bottom left on the map as in flat, in the style of the basemap credit and on its line, dark on a dark map like the zoom buttons — also
 `.attribution()` on the builder, the `attribution` map option and `ixmaps.setAttribution(text)`; the basemap's credit stays bottom right), `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
@@ -224,10 +224,23 @@ but unused. It never mutates the page's own objects. Unit tests: `cd test && npm
 
 ### World copies
 
-At an extreme zoom-out MapLibre repeats the world side by side, and the themes are repeated on
-every copy (flat repeats only its basemap tiles). `.options({worldcopies: false})` draws the
-world once, but MapLibre then also stops the zoom-out where the world gets narrower than the
-window.
+At an extreme zoom-out MapLibre repeats the world side by side. The themes are drawn once, as in
+flat (which repeats only its basemap tiles): the map pans freely past the world's edge, with empty
+space beside it. `.options({themecopies: true})` (also at runtime) repeats the themes on every world
+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.
+
+### Click to action
+
+flat's click-to-action (`ui/js/tools/tooltip_to_action.js`, e.g. a click on a country filters every
+theme of the page to it) works as on flat: on a click on an item the engine calls the page's
+`ixmaps.onItemAction(szId, item, themeObj)`, `item.szSelectionId` being the value of the theme's
+selection field, and `ixmaps.onItemAction(null, null)` on a click on the map background. The
+selection field, `getThemeObj(id).szSelectionField`, is the `id` binding, else the position (or
+lookup) field; an aggregated item gives its first record's value. The flat script's own
+`htmlgui_onItemClick`, which reads flat's SVG, is not called — the page only needs
+`.require(".../tooltip_to_action.js")` (or its own `ixmaps.onItemAction`). The click still pins the
+tooltip. See [`ports/index_embed_migration - Zeit online data - 2015-2020 - click2filter.html`](./ports/index_embed_migration%20-%20Zeit%20online%20data%20-%202015-2020%20-%20click2filter.html).
 
 ### Data formats and data.js
 
@@ -289,7 +302,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.25/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.30/ixmaps-gl.js"></script>
 ```
 
 or from unpkg, the npm package [`ixmaps-gl`](https://www.npmjs.com/package/ixmaps-gl)
@@ -297,13 +310,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.25/ixmaps-gl.js"></script>
+<script src="https://unpkg.com/ixmaps-gl@0.2.30/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.25/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.30/ixmaps-gl.js"></script>
 <div id="map_div" style="position:absolute;inset:0;"></div>
 
 <script>

package/ixmaps-gl.js

@@ -100,7 +100,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.25';
+  const IXMAPS_GL_VERSION = '0.2.30';
 
   const LIB_URLS = {
     // Bumped 3.6.2 -> 5.x (2026-09-21, globe-projection compat fix): native
@@ -1201,7 +1201,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     if (!table || !Array.isArray(table.records) || !Array.isArray(table.fields)) {
       return table && typeof table.json === 'function' ? table.json() : [];
     }
-    const names = table.fields.map(f => f.id);
+    // a header cell that spans lines ("Sezione (*)\nSektion", bilingual
+    // exports) reads as one line, as in flat: "Sezione (*) Sektion"
+    const names = table.fields.map(f => String(f.id).replace(/[\r\n]+/g, ' '));
     const rows = new Array(table.records.length);
     for (let i = 0; i < table.records.length; i++) {
       const rec = table.records[i], o = {};
@@ -1210,6 +1212,26 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     }
     return rows;
   }
+  // .data({process}) on topojson/geojson, as flat: its data.js hands the
+  // process function the features' properties as a Table (column(...).map,
+  // addColumn, ...); the result goes back onto the same features, by row
+  function processFeatureCollection(fc, dataConfig) {
+    if (!dataConfig.process || !fc || !Array.isArray(fc.features) || !fc.features.length) return fc;
+    requireDataJs('process');
+    const headers = [];
+    const seen = new Set();
+    for (const f of fc.features) {
+      for (const k of Object.keys(f.properties || {})) if (!seen.has(k)) { seen.add(k); headers.push(k); }
+    }
+    const table = new global.Data.Table().setArray([headers, ...fc.features.map(f => headers.map(h => (f.properties || {})[h]))]);
+    const rows = dataTableRows(runDataProcess(table, dataConfig));
+    if (rows.length !== fc.features.length) {
+      console.warn(`[ixmaps-gl] .data({process}) changed the row count of ${dataConfig.type} features (${fc.features.length} → ${rows.length}); process result ignored`);
+      return fc;
+    }
+    fc.features.forEach((f, i) => { f.properties = rows[i]; });
+    return fc;
+  }
   // parse CSV text with data.js (as flat) → a Table
   function dataJsCsvTable(text) {
     return new Promise((resolve, reject) => {
@@ -1531,8 +1553,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     // genuinely CSV-shaped .obj with a missing binding.position would
     // throw, even though this .obj was never row data in the first place.
     if (dataConfig.obj) {
-      if (dataConfig.type === 'topojson') return topojsonToFeatureCollection(dataConfig.obj, dataConfig.object);
-      if (dataConfig.type === 'geojson') return sanitizeGeoJSON(dataConfig.obj);
+      if (dataConfig.type === 'topojson') return processFeatureCollection(topojsonToFeatureCollection(dataConfig.obj, dataConfig.object), dataConfig);
+      if (dataConfig.type === 'geojson') return processFeatureCollection(sanitizeGeoJSON(dataConfig.obj), dataConfig);
       let obj = dataConfig.obj;
       if (dataConfig.process) {
         requireDataJs('process');
@@ -1624,8 +1646,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // them into a table with a geometry column, and back)
       const resp = await fetch(dataConfig.url);
       if (!resp.ok) throw new Error(`[ixmaps-gl] failed to fetch ${dataConfig.url}: ${resp.status}`);
-      if (dataConfig.type === 'topojson') return topojsonToFeatureCollection(await resp.json(), dataConfig.object);
-      return sanitizeGeoJSON(await resp.json());
+      if (dataConfig.type === 'topojson') return processFeatureCollection(topojsonToFeatureCollection(await resp.json(), dataConfig.object), dataConfig);
+      return processFeatureCollection(sanitizeGeoJSON(await resp.json()), dataConfig);
     }
     // every other format (json, jsonstat, ndjson, rss, kml, gml, geobuf,
     // flatgeobuf, geopackage, parquet, ...) through data.js, as flat
@@ -3100,7 +3122,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     'sizepow', 'rangescale', 'minvalue', 'maxvalue', 'markersize', 'boxopacity', 'outlierscale', 'valuescale',
     'brightness', 'fractionscale', 'dopacityscale', 'dopacitypow', 'gridwidthpx', 'textscale', 'rangecentervalue',
     'shadowblur', 'shadowdx', 'shadowdy', 'maxshadow', 'offsetx', 'offsety', 'gridx', 'boxmargin', 'borderwidth',
-    'borderradius', 'maxcharts', 'archeight'];
+    'borderradius', 'maxcharts', 'archeight', 'alignmargin'];
   function toNumberIfNumeric(v) {
     if (typeof v !== 'string' || !v.trim()) return v;
     const n = Number(v);
@@ -3592,6 +3614,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // The ocean of flat's world / orthographic maps is a {type:"Sphere"} feature: the whole map disc,
   // filled with the layer's color. Here it is the surface of the map (the globe, or the flat
   // map): a background layer under everything, in that color and opacity.
+  // the themes are drawn once, as in flat, even where the map repeats its world (the themecopies map option:
+  // true repeats them on every world copy)
+  function applyThemeCopies(map, value) {
+    if (value !== true && value !== 'true') {
+      if (!map.__ixOrigGetRenderWorldCopies) map.__ixOrigGetRenderWorldCopies = map.getRenderWorldCopies;
+      map.getRenderWorldCopies = () => false;
+    } else if (map.__ixOrigGetRenderWorldCopies) {
+      map.getRenderWorldCopies = map.__ixOrigGetRenderWorldCopies;
+      delete map.__ixOrigGetRenderWorldCopies;
+    }
+  }
   const SPHERE_BACKDROP_LAYER_ID = '__ixmaps_gl_sphere_backdrop';
   function applySphereBackdrop(map, style) {
     const cs = style && style.colorscheme;
@@ -3631,6 +3664,23 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // basemap credit, bottom right — same line, same pill: white, 12px
   // radius, 12px/20px Helvetica Neue, links rgba(0,0,0,0.75)).
   // ---------------------------------------------------------------
+  // On a dark map (the effective darkness, as the legend and the tooltip use it) the MapLibre control buttons
+  // (zoom, compass) and the page's attribution are dark too: the class ixgl-dark on the map element switches them
+  let _controlLookCss = false;
+  function applyControlLook(el, dark) {
+    if (!_controlLookCss && typeof document !== 'undefined') {
+      _controlLookCss = true;
+      const css = document.createElement('style');
+      css.textContent = '.ixgl-dark .maplibregl-ctrl-group{background:#222!important;box-shadow:0 0 0 1px rgba(255,255,255,.15)!important}'
+        + '.ixgl-dark .maplibregl-ctrl-group button+button{border-top:1px solid #444!important}'
+        + '.ixgl-dark .maplibregl-ctrl-group button:not(:disabled):hover{background-color:#3a3a3a!important}'
+        + '.ixgl-dark .maplibregl-ctrl-group .maplibregl-ctrl-icon{filter:invert(1)}'
+        + '.ixgl-dark .ixmaps-gl-attribution{background:#222!important;color:#aaa!important}'
+        + '.ixgl-dark .ixmaps-gl-attribution a{color:#ddd!important}';
+      document.head.appendChild(css);
+    }
+    if (el && el.classList) el.classList.toggle('ixgl-dark', !!dark);
+  }
   let _attributionCss = false;
   function createAttribution(map) {
     if (!_attributionCss && typeof document !== 'undefined') {
@@ -3937,11 +3987,29 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         // pane, the shared look (fonts included) on the container
         return html ? { html: tooltipPaneHtml(html), style: Object.assign({ padding: '0.5em 0.7em', maxWidth: '440px' }, tooltipLook()) } : null;
     }
+    // flat's click-to-action hook (ui/js/tools/tooltip_to_action.js): ixmaps.onItemAction(szId, item, themeObj) on a
+    // click on an item — item.szSelectionId is the value of the theme's selection field — and onItemAction(null, null)
+    // on a click on the map background
+    function callItemAction(rt, object) {
+      const hook = pageIxmaps() && pageIxmaps().onItemAction;
+      if (typeof hook !== 'function') return;
+      try {
+        if (!rt) { hook.call(global.ixmaps, null, null); return; }
+        const field = selectionFieldOf(rt);
+        const props = object.properties || {};
+        // a single record, or an aggregated item's first one
+        const raw = props.raw || props.firstRaw || props.titleRaw || (props.raws && props.raws[0]) || props;
+        const value = field && raw ? raw[field] : null;
+        if (value == null) return;
+        hook.call(global.ixmaps, themeIdOf(rt) + '::' + value, { szSelectionId: String(value) }, getThemeObj(themeIdOf(rt)));
+      } catch (err) { console.error('[ixmaps-gl] onItemAction failed:', err); }
+    }
     function clickFor(picked) {
         const info = picked && Object.assign({}, picked, { object: pickedFeature(picked.object) });
         if (info && info.object && info.layer) {
           const rt = findRuntimeForLayerId(info.layer.id);
           if (rt) {
+            callItemAction(rt, info.object);
             // Only a Point geometry's own coordinates ARE an
             // [lng,lat] pair (every point/bubble/dot/chart-cluster
             // layer) — a CHOROPLETH polygon's geometry.coordinates is
@@ -3972,6 +4040,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           }
         }
         // clicked empty map space (or a non-tooltippable layer) -> unpin
+        callItemAction(null, null);
         pinned = null;
         pinnedTooltipEl.style.display = 'none';
         return false;
@@ -5313,11 +5382,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         // world map can't open fully zoomed out. The deck.gl overlay takes
         // its `repeat` from map.getRenderWorldCopies(), so the themes are
         // drawn on every world copy too (flat draws them once; only its
-        // basemap tiles wrap). .options({worldcopies: false}) draws the
+        // basemap tiles wrap) — unless themecopies is off, which is the default
+        // (see applyThemeCopies). .options({worldcopies: false}) draws the
         // world once, at the cost of that zoom limit.
         renderWorldCopies: this._engineOptions.worldcopies !== false
       });
       engineOptionsByMap.set(map, this._engineOptions);
+      // themecopies (default: off): the map keeps its world copies (free panning past the world's edge, empty
+      // space beside it) but the deck.gl overlay, which asks map.getRenderWorldCopies() for its `repeat`, draws the
+      // themes once, as flat does. .options({themecopies: true}) repeats them. MapLibre's own transform does not
+      // use this method.
+      applyThemeCopies(map, this._engineOptions.themecopies);
       sphereBackdrops.forEach(style => applySphereBackdrop(map, style));
       // the live-SVG pane USER charts render into (see chartHostFor) —
       // registered here, keyed by this map's options object, so every
@@ -5446,6 +5521,16 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // the page's attribution (.attribution(), Map option attribution)
       const attributionBox = createAttribution(map);
       attributionBox.set(this._attributionText != null ? this._attributionText : this.mapOptions.attribution);
+      // dark controls on a dark map; re-read when a style (basemap) loads and when basemapopacity is set
+      const refreshControlLook = () => {
+        const o = parseFloat(this._engineOptions.basemapopacity);
+        const legendBackground = this.mapOptions.legendBackground || this.mapOptions.legendbackground;
+        applyControlLook(el, typeof this.__effectiveDark === 'function'
+          ? this.__effectiveDark(isNaN(o) ? 1 : o, this.mapOptions.mapType, legendBackground) : false);
+      };
+      this._refreshControlLook = refreshControlLook;
+      refreshControlLook();
+      map.on('style.load', refreshControlLook);
       this._setAttribution = text => attributionBox.set(text);
 
       if (this._legendHtml) {
@@ -5586,18 +5671,19 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         add: (layerBuilder, flag) => {
           layerBuilder = unwrapLayer(layerBuilder);
           _chainedLayers = _chainedLayers.then(() => {
+            let slot = null;
             if (/replace/i.test(flag || '')) {
               const def = layerBuilder.definition();
               const id = (def.style && def.style.name) || (def.meta && def.meta.name);
-              if (id) removeThemeById(id);
+              if (id) { slot = captureSlot(id); removeThemeById(id); }
             }
-            return engineApi.defineLayer(layerBuilder);
+            return engineApi.defineLayer(layerBuilder, slot);
           }).catch(err => console.error('[ixmaps-gl] map.add():', err));
           return engineApi;
         },
         replace: (id, layerBuilder, flag) => {
           layerBuilder = unwrapLayer(layerBuilder);
-          _chainedLayers = _chainedLayers.then(() => { removeThemeById(id); return engineApi.defineLayer(layerBuilder); })
+          _chainedLayers = _chainedLayers.then(() => { const slot = captureSlot(id); removeThemeById(id); return engineApi.defineLayer(layerBuilder, slot); })
             .catch(err => console.error('[ixmaps-gl] map.replace():', err));
           return engineApi;
         },
@@ -5612,11 +5698,12 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           layerBuilder = unwrapLayer(layerBuilder);
           const f = String(flag || '');
           _chainedLayers = _chainedLayers.then(() => {
+            let slot = null;
             if (!/force/i.test(f)) {
               if (/replace/i.test(f)) {
                 const def = layerBuilder.definition();
                 const id = (def.style && def.style.name) || (def.meta && def.meta.name);
-                if (id) removeThemeById(id);
+                if (id) { slot = captureSlot(id); removeThemeById(id); }
               } else if (/clearcharts|clear|clearall/i.test(f)) {
                 const charts = /clearcharts/i.test(f);
                 const doomed = runtimes.filter(rt => !flatFlag(rt.flags, 'LOCKED') && (!charts || rt.flags.has('CHART')));
@@ -5625,7 +5712,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
                 byName.forEach((list, name) => removeRuntimes(name, list));
               }
             }
-            return engineApi.defineLayer(layerBuilder);
+            return engineApi.defineLayer(layerBuilder, slot);
           }).catch(err => console.error('[ixmaps-gl] map.newTheme():', err));
           return engineApi;
         },
@@ -5857,7 +5944,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         // exactly how this engine's own facet-filter/style setters below
         // already push responsibility for "what should happen" to the
         // caller rather than guessing.
-        defineLayer: (layerBuilder) => defineFromDefinition(unwrapLayer(layerBuilder).definition()),
+        defineLayer: (layerBuilder, slot) => defineFromDefinition(unwrapLayer(layerBuilder).definition(), slot),
         // GL-PORT COMPAT: real ixmaps-flat's map handle, as a page gets it
         // from `myMap.then(map => map.view(...).options(...).layer(a)
         // .layer(b))` — the common multi-layer idiom — is chainable on the
@@ -5879,6 +5966,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           if (o && typeof o === 'object') {
             Object.assign(builder._engineOptions, o);
             // read only when the MapLibre map is created — switched here at runtime
+            if ('basemapopacity' in o && builder._refreshControlLook) builder._refreshControlLook();
+            if ('themecopies' in o) { applyThemeCopies(map, o.themecopies); map.triggerRepaint(); }
             if ('worldcopies' in o) map.setRenderWorldCopies(o.worldcopies !== false && o.worldcopies !== 'false');
             refresh();
           }
@@ -6017,6 +6106,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         if (removed) { refresh(); notifyRedraw(); }
         return removed;
       }
+      // where the theme(s) removeThemeById(id) would remove stand in the stack: the first remaining
+      // theme after them (null = they were on top). Taken BEFORE the removal, handed to defineLayer.
+      function captureSlot(id) {
+        const named = runtimes.filter(r => (r.style && r.style.name === id) || (r.meta && r.meta.name === id));
+        const doomed = named.length ? named : runtimes.filter(r => r.name === id);
+        if (!doomed.length) return null;
+        const last = Math.max(...doomed.map(r => runtimes.indexOf(r)));
+        const anchor = runtimes.slice(last + 1).find(r => !doomed.includes(r) && !doomed.some(d => d._subTheme === r)) || null;
+        return { anchor };
+      }
+
       // flat addresses a theme by its id — style.name / meta.name (several
       // themes may share one layer), else the layer name
       function removeThemeById(id) {
@@ -6187,11 +6287,16 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // flat itself does ("defining a theme with the same name replaces it
       // in place"; a page's live-refresh loop relies on it, e.g. the NYC
       // status page re-defining its two themes every 10s).
-      async function defineFromDefinition(def) {
+      // `slot` (from captureSlot) is where a replaced theme stood in the stack: the replace paths
+      // remove the old theme first and pass it on, so the new one is not appended on top
+      async function defineFromDefinition(def, slot) {
         if (validation) validation.definition(def);
         const pdef = projectThemeToDefinition(def);
         const replacedId = (pdef.meta && pdef.meta.name) || (pdef.style && pdef.style.name);
-        if (replacedId) removeThemeById(replacedId);
+        if (replacedId) {
+          if (!slot) slot = captureSlot(replacedId);
+          removeThemeById(replacedId);
+        }
         let spec = normalizeTheme(pdef);
         let raw;
         const deferred = deferredFeatureLoad(spec, map.getZoom());
@@ -6218,7 +6323,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         rt._zoomToPending = wantsZoomToExtent(spec.flags);
         rt._dataSourceKey = named ? 'name:' + spec.data.name
           : 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);
+        // a replacement keeps the stacking position (draw order, legend order) of the theme it replaces:
+        // it goes in front of the theme that followed the old one, still on the map after the await above
+        const slotAt = slot && slot.anchor ? runtimes.indexOf(slot.anchor) : -1;
+        if (slotAt >= 0) runtimes.splice(slotAt, 0, rt); else runtimes.push(rt);
         if (fc._sphere) applySphereBackdrop(map, rt.style);
         _globalThemeRegistry.set(rt.name, rt);
         if (rt.meta && rt.meta.name && rt.meta.name !== rt.name) _globalThemeRegistry.set(rt.meta.name, rt);
@@ -6268,10 +6376,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           for (let i = 0; i < themes.length; i++) {
             const t = themes[i] || {};
             const name = (t.style && t.style.name) || (t.meta && t.meta.name);
-            if (/replace/i.test(f) && name) removeThemesNamed(name);
+            let slot = null;
+            if (/replace/i.test(f) && name) { slot = captureSlot(name); removeThemesNamed(name); }
             else if (i === 0 && !/add/i.test(f)) [...new Set(runtimes.map(r => r.name))].forEach(n => engineApi.removeTheme(n));
             try {
-              report.themes.push(await defineFromDefinition(withoutProjectCode(t, report)));
+              report.themes.push(await defineFromDefinition(withoutProjectCode(t, report), slot));
             } catch (e) {
               report.skipped.push({ layer: t.layer, reason: e.message });
             }
@@ -7409,7 +7518,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       : 1;
   }
 
-  function valueRadius(value, zoom, style, mapOptions, flags, maxSizeValue) {
+  function valueRadius(value, zoom, style, mapOptions, flags, maxSizeValue, sizeBound) {
     const zoomFactor = objectZoomFactor(zoom, mapOptions);
     // FIXSIZE (a symbol chart; PLOT / GRIDSIZE size their markers
     // themselves): one radius for every item, whatever its value — the
@@ -7452,7 +7561,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     if (flags && flags.has('SYMBOL') && !flags.has('BUBBLE') && !flags.has('USER')
       && !flags.has('FIXSIZE') && !flags.has('PLOT') && !flags.has('GRIDSIZE')
       && flags.has('CATEGORICAL') && !flags.has('AGGREGATE') && !flatFlag(flags, 'GROUP')
-      && !style.sizefield) {
+      && !style.sizefield && !sizeBound) {
       const fixed = NORMAL_RADIUS_PX * (styleNum(style.scale) || 1);
       return Math.max(VALUE_RADIUS_MIN, Math.min(VALUE_RADIUS_MAX, fixed * zoomFactor));
     }
@@ -7825,6 +7934,13 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     return out;
   }
 
+  // the outline colour of a flat bubble icon: none for NOLINES / linecolor "none", else linecolor, else the
+  // class colour's darker derivate — and none when there is neither (an unfilled "none" class has no colour
+  // to derive from; with a linecolor its outline must still draw)
+  function bubbleStrokeRgb(look, rgb) {
+    return look.noStroke ? null : (look.stroke || (rgb ? flatDerivateRgb(rgb, 0.7) : null));
+  }
+
   // ChartColors.textColor (colorscheme.js 104-116): darker on light colors
   function flatChartTextRgb(rgb) {
     return flatDerivateRgb(rgb, rgb[0] + rgb[1] + rgb[2] > 450 ? 0.6 : 3);
@@ -12103,6 +12219,91 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       return Array.isArray(cs) && cs.length === 1 && String(cs[0]).trim().toLowerCase() === 'none';
     }
 
+    // an external symbol file (.svg/.png/.jpeg) named by `symbols` — flat draws it as an
+    // <image> (maptheme.js 21743, 22168), not as the chart's own shape. null for a shape name
+    _urlSymbolOf(sym) {
+      if (typeof sym !== 'string') return null;
+      const s = sym.trim();
+      // a data: URI is a symbol file too, and the only kind fetch() can read on a file:// page
+      return /\.(svg|png|jpe?g)([?#]|$)/i.test(s) || /^data:image\/(svg\+xml|png|jpe?g)[;,]/i.test(s) ? s : null;
+    }
+
+    // the symbol file as an IconLayer icon descriptor, NOT tinted (flat doesn't recolor an
+    // <image> either); fetched and rasterized once per URL, shared by SEQUENCE and plain symbols
+    _urlSymbolIcon(u) {
+      if (!this._urlIconCache) this._urlIconCache = new Map();
+      if (!this._urlIconCache.has(u)) {
+        // the placeholder is a transparent 1x1 PNG, NOT the raw symbol
+        // URL: deck.gl would immediately try to load that itself, and an
+        // SVG without natural dimensions (a viewBox only, the bus
+        // pictogram of the City-moving page) makes Chrome's
+        // createImageBitmap throw — a console error and a part that
+        // never renders. The real raster replaces it below
+        const entry = { url: TRANSPARENT_1PX_PNG, width: 256, height: 256, anchorX: 128, anchorY: 128, mask: false, id: 'seq-sym-pending:' + u };
+        this._urlIconCache.set(u, entry);
+        // fetch the symbol ONCE and rasterize it into the descriptor's
+        // own 256px cell here: deck then always sees exactly the declared
+        // dimensions, and dimension-less SVGs work like any other. The
+        // redraw lets the next getIcon see the patched descriptor
+        fetch(u).then(r => r.ok ? r.text() : null).then(text => new Promise((resolve, reject) => {
+          if (typeof text !== 'string' || !/<svg[\s>]/i.test(text)) { reject(new Error('not svg')); return; }
+          if (!/\swidth\s*=/i.test(text) || !/\sheight\s*=/i.test(text)) {
+            const vb = text.match(/viewBox\s*=\s*["']([^"']*)["']/i);
+            const p = vb && vb[1].trim().split(/[\s,]+/).map(Number);
+            if (p && p.length === 4 && isFinite(p[2]) && p[2] > 0 && isFinite(p[3]) && p[3] > 0) {
+              text = text.replace(/<svg/i, '<svg width="' + p[2] + '" height="' + p[3] + '"');
+            }
+          }
+          const img = new Image();
+          img.onload = () => resolve(img);
+          img.onerror = () => reject(new Error('svg decode failed'));
+          img.src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(text);
+        })).then(img => {
+          const size = entry.width;
+          const canvas = document.createElement('canvas');
+          canvas.width = size; canvas.height = size;
+          const ctx = canvas.getContext('2d');
+          const s = Math.min(size / (img.naturalWidth || size), size / (img.naturalHeight || size));
+          const dw = (img.naturalWidth || size) * s, dh = (img.naturalHeight || size) * s;
+          ctx.drawImage(img, (size - dw) / 2, (size - dh) / 2, dw, dh);
+          entry.url = canvas.toDataURL('image/png');
+          entry.id = 'seq-sym-raster:' + u;
+          if (this._triggerRedraw) this._triggerRedraw();
+        }).catch(() => {
+          // a symbol FILE of a file:// page can't be fetched (nor loaded by deck): say so once
+          let onDisk = false;
+          try { onDisk = new URL(u, location.href).protocol === 'file:'; } catch (e) { /* not a URL */ }
+          if (onDisk && !this._warnedFileSymbol) {
+            this._warnedFileSymbol = true;
+            console.warn('[ixmaps-gl] symbol file "' + u + '" cannot be loaded from a file:// page — serve the page over http(s) or give the symbol as a data: URI');
+          }
+          // not an SVG (a PNG/JPEG symbol): deck's own URL loading takes
+          // it from here — and a pre-sized SVG that failed to rasterize
+          // gets that same second chance
+          entry.url = u;
+          entry.id = 'seq-sym-natural:' + u;
+          if (this._triggerRedraw) this._triggerRedraw();
+        });
+      }
+      return this._urlIconCache.get(u);
+    }
+
+    // a size field is bound (flat's szSizeField): .binding({size}) or style.sizefield, live —
+    // setSizeField() rebinds at runtime. '$item$' is not a field
+    _sizeBound() { return !!(this.binding.size && this.binding.size !== '$item$'); }
+
+    // the symbol file of a plain (non-SEQUENCE) item, or null: the same class→symbol /
+    // symbolfield mapping as _resolveSymbolShape, before it folds unknown names to 'circle'
+    _resolveSymbolUrl(props) {
+      const s = this.style.symbols;
+      if (!Array.isArray(s)) return null;
+      if (!this.style.symbolfield) {
+        const cat = props && props.cat != null ? props.cat : 0;
+        return this._urlSymbolOf(s[Math.min(cat, s.length - 1)]);
+      }
+      return this._urlSymbolOf(this._resolveSymbolShape(props));
+    }
+
     _buildSingleIcon(colorRgb, opacity, shape, borderColorRgb, borderWidth, borderOpacity = 1) {
       if (!colorRgb) { colorRgb = [128, 128, 128]; opacity = 0; } // no class colour (["none"]): unfilled
       shape = shape || 'circle';
@@ -13681,7 +13882,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         // the item's class (range classes set it for groups too — a negative
         // group total would make dominant() pick the wrong class)
         const cat = d.properties.cat != null ? d.properties.cat : (d.properties.counts ? dominant(d.properties.counts) : 0);
-        const radiusPx = valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue);
+        const radiusPx = valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue, this._sizeBound());
         const size = radiusPx / pxPerUnit;
         const chart = this._userChartSvg(draw, name, theme, flag, d, value, cat, size, sizeValueOf(d));
         if (!chart) continue;
@@ -14321,7 +14522,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // GRIDSIZE: every chart the size of its grid cell, whatever its value
       // (_gridChartRadiusPx); otherwise valueRadius
       const gridR = this._gridChartRadiusPx(zoom, liveZoom);
-      const vRadius = v => (gridR != null ? gridR : valueRadius(v, liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue));
+      const vRadius = v => (gridR != null ? gridR : valueRadius(v, liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue, this._sizeBound()));
       // AGGREGATE sums without a normalsizevalue: flat's default is the
       // largest aggregated value (defaultNormalSizeValue leaves it unset, the
       // sizes depend on the aggregation)
@@ -14641,7 +14842,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         if (!flatLook) return this._buildSingleIcon(rgb, fillOpacity, shapeOf(d.properties), singleBorderColorRgb, singleBorderWidthPx);
         const look = flatLook(d);
         return this._buildSingleIcon(rgb, look.fillOpacity, shapeOf(d.properties),
-          look.noStroke || !rgb ? null : (look.stroke || flatDerivateRgb(rgb, 0.7)), look.width, look.strokeOpacity);
+          bubbleStrokeRgb(look, rgb), look.width, look.strokeOpacity);
       };
       // flat's symbol outline (maptheme.js 21595-21610 and 21950-21997,
       // drawn 21625-21634 / 21995-22035): every SYMBOL shape is stroked,
@@ -14676,7 +14877,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // routing goes by the final id (layerRuntimeById). A symbol's outline
       // is centered on its radius (flat); BUBBLE's border keeps the
       // icon's look, inside the radius
-      if (combined.length && !alignOf.active && combined.every(d => singleSymbol(d) && shapeOf(d.properties) === 'circle')) {
+      if (combined.length && !alignOf.active && combined.every(d => singleSymbol(d) && shapeOf(d.properties) === 'circle' && !this._resolveSymbolUrl(d.properties))) {
         const radiusPx = d => vRadius(sizeValueOf(d));
         // a CATEGORICAL BUBBLE: flat's look (flatBubbleLook) in screen px,
         // its stroke centered on the radius as flat's SVG circle
@@ -14705,6 +14906,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         getPosition: d => d.geometry.coordinates,
         getIcon: d => {
           if (!singleSymbol(d)) return this._buildBubbleIcon(d.properties.counts, this.categoryColorsRgb, this._groupIsolation(d), Array.isArray(this.style.symbols) ? this.style.symbols : null, flatLook && flatLook(d));
+          const symbolUrl = this._resolveSymbolUrl(d.properties);
+          if (symbolUrl) return this._urlSymbolIcon(symbolUrl);
           if (flatLook) return singleIcon(d);
           const shape = shapeOf(d.properties), rgb = outlineRgb(d);
           if (!symbolOutline || !rgb) return this._buildSingleIcon((this.categoryColorsRgb || [])[d.properties.cat], fillOpacity, shape, rgb, rgb ? singleBorderWidthPx : 0);
@@ -14994,60 +15197,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // it itself (its ImageBitmap loader falls back to <img>, which
       // rasterizes SVG) — NOT tinted: these files carry their own colors,
       // and flat doesn't recolor an <image> either
-      const urlSymbolOf = i => {
-        const s = symbols && (symbols[i] || symbols[0]);
-        return typeof s === 'string' && /\.(svg|png|jpe?g)([?#]|$)/i.test(s.trim()) ? s.trim() : null;
-      };
-      if (!this._urlIconCache) this._urlIconCache = new Map();
-      const urlIcon = u => {
-        if (!this._urlIconCache.has(u)) {
-          // the placeholder is a transparent 1x1 PNG, NOT the raw symbol
-          // URL: deck.gl would immediately try to load that itself, and an
-          // SVG without natural dimensions (a viewBox only, the bus
-          // pictogram of the City-moving page) makes Chrome's
-          // createImageBitmap throw — a console error and a part that
-          // never renders. The real raster replaces it below
-          const entry = { url: TRANSPARENT_1PX_PNG, width: 256, height: 256, anchorX: 128, anchorY: 128, mask: false, id: 'seq-sym-pending:' + u };
-          this._urlIconCache.set(u, entry);
-          // fetch the symbol ONCE and rasterize it into the descriptor's
-          // own 256px cell here: deck then always sees exactly the declared
-          // dimensions, and dimension-less SVGs work like any other. The
-          // redraw lets the next getIcon see the patched descriptor
-          fetch(u).then(r => r.ok ? r.text() : null).then(text => new Promise((resolve, reject) => {
-            if (typeof text !== 'string' || !/<svg[\s>]/i.test(text)) { reject(new Error('not svg')); return; }
-            if (!/\swidth\s*=/i.test(text) || !/\sheight\s*=/i.test(text)) {
-              const vb = text.match(/viewBox\s*=\s*["']([^"']*)["']/i);
-              const p = vb && vb[1].trim().split(/[\s,]+/).map(Number);
-              if (p && p.length === 4 && isFinite(p[2]) && p[2] > 0 && isFinite(p[3]) && p[3] > 0) {
-                text = text.replace(/<svg/i, '<svg width="' + p[2] + '" height="' + p[3] + '"');
-              }
-            }
-            const img = new Image();
-            img.onload = () => resolve(img);
-            img.onerror = () => reject(new Error('svg decode failed'));
-            img.src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(text);
-          })).then(img => {
-            const size = entry.width;
-            const canvas = document.createElement('canvas');
-            canvas.width = size; canvas.height = size;
-            const ctx = canvas.getContext('2d');
-            const s = Math.min(size / (img.naturalWidth || size), size / (img.naturalHeight || size));
-            const dw = (img.naturalWidth || size) * s, dh = (img.naturalHeight || size) * s;
-            ctx.drawImage(img, (size - dw) / 2, (size - dh) / 2, dw, dh);
-            entry.url = canvas.toDataURL('image/png');
-            entry.id = 'seq-sym-raster:' + u;
-            if (this._triggerRedraw) this._triggerRedraw();
-          }).catch(() => {
-            // not an SVG (a PNG/JPEG symbol): deck's own URL loading takes
-            // it from here — and a pre-sized SVG that failed to rasterize
-            // gets that same second chance
-            entry.url = u;
-            entry.id = 'seq-sym-natural:' + u;
-            if (this._triggerRedraw) this._triggerRedraw();
-          });
-        }
-        return this._urlIconCache.get(u);
-      };
+      const urlSymbolOf = i => this._urlSymbolOf(symbols && (symbols[i] || symbols[0]));
+      const urlIcon = u => this._urlSymbolIcon(u);
       const shapeOf = i => { const sh = symbols && (symbols[i] || symbols[0]); return normalizeSymbolShape(sh); };
       const colorOf = i => this.classRgb(i);
       const allParts = [], allGlows = [];
@@ -15077,7 +15228,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         const sizeFactor = itemSizeFactor(d);
         const partRadius = multi
           ? v => Math.max(VALUE_RADIUS_MIN, normalR * Math.pow(Math.abs(v) / seqMax, 1 / sizePow) * sizeFactor)
-          : v => valueRadius(v, liveZoom, st, this.mapOptions, this.flags, seqMax);
+          : v => valueRadius(v, liveZoom, st, this.mapOptions, this.flags, seqMax, this._sizeBound());
         let layout = rings ? ringsLayout(counts, partRadius)
           : sequenceLayout(counts, this.flags, partRadius, { maxRadius: normalR, maxValue: seqMax, nParts: nCats, rangeScale: styleNum(st.rangescale) || 0 });
         if (!layout.length) continue;
@@ -16631,7 +16782,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     // flat's chart position for this build (flatChartAlignOffset): a
     // function item → pixel offset, the same for every part of one chart
     // (symbol, glow, shadow, box, title, value text). unit is flat's
-    // normalX(1) on screen, the object zoom × style.scale.
+    // normalX(1) on screen, the object zoom × style.scale. flat keeps a margin of 5 units between the
+    // position and the chart's facing edge for left/right/top/bottom; the gl-only style.alignmargin
+    // changes it (0: the edge touches the position, so a left and a right chart touch each other)
     _chartAlignFn(liveZoom, radiusOf, textOnly = false) {
       const st = this.style;
       const none = () => [0, 0];
@@ -16640,12 +16793,13 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       const unit = objectZoomFactor(liveZoom, this.mapOptions) * (styleNum(st.scale) || 1);
       const symbol = flatChartBranch(this.flags) === 'symbol';
       const normalR = NORMAL_RADIUS_PX * unit; // flat's normalX(chart size / 2)
+      const margin = Number.isFinite(styleNum(st.alignmargin)) ? styleNum(st.alignmargin) : 5;
       const cache = new Map();
       const fn = d => {
         let v = cache.get(d);
         if (v) return v;
         const r = radiusOf(d);
-        v = flatChartAlignOffset(st, { unit, symbolScale: symbol ? r / (2 * normalR) : 1, half: symbol ? normalR : r, orig: r + (textOnly ? 0 : 5 * unit) });
+        v = flatChartAlignOffset(st, { unit, symbolScale: symbol ? r / (2 * normalR) : 1, half: symbol ? normalR : r, orig: r + (textOnly ? 0 : margin * unit) });
         cache.set(d, v);
         return v;
       };
@@ -16824,7 +16978,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       const textOnly = this.flags.has('TEXTONLY');
       const showValues = this.flags.has('VALUES') && !valuesHiddenByScale(this.style, zoom);
       if (textOnly && !showValues) return [];
-      const radiusOf = d => valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue);
+      const radiusOf = d => valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue, this._sizeBound());
       const alignOf = this._chartAlignFn(liveZoom, radiusOf, textOnly);
       const valueScale = styleNum(this.style.valuescale) || 1;
       const textOverride = this.style.valuecolor || this.style.textcolor;
@@ -17385,6 +17539,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // several themes of a page
       szId: themeIdOf(rt),
       szName: rt.name,
+      // flat's szSelectionField: the field a click on an item selects by (the id binding, else the field the
+      // item is positioned by)
+      szSelectionField: selectionFieldOf(rt),
       // the filter in force: a runtime one (changeThemeStyle "filter")
       // replaces the definition's
       szFilter: rt._runtimeFilterExpr || rt._filterExpr || '',
@@ -17421,6 +17578,13 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       get itemA() { return onMap().itemA; }
     };
   }
+  // the field whose value identifies an item on a click (flat's szSelectionField): binding.id, else the position field
+  // (which a join to a geometry layer turns into binding.lookup)
+  function selectionFieldOf(rt) {
+    const b = rt.binding || {};
+    const f = b.id || b.position || b.lookup;
+    return typeof f === 'string' && f && f !== 'geometry' && !/^geometry$/i.test(f) ? f : null;
+  }
   const _warnedOnce = new Set();
   function warnOnce(key, msg) { if (!_warnedOnce.has(key)) { _warnedOnce.add(key); console.info(msg); } }
   // the theme's records as flat's dbFields/dbRecords (cached per data)
@@ -17852,6 +18016,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   function compatRemoveTheme(...a) {
     return _mapHandle.remove(a.length >= 2 ? a[1] : a[0]);
   }
+  // flat's ixmaps.toggleTheme(szMap, szTheme) (htmlgui.js): show / hide a theme by its id, e.g. a page's on / off buttons
+  function compatToggleTheme(...a) {
+    new themeApi(null, a.length >= 2 ? a[1] : a[0]).toggle();
+  }
   function compatSetBasemapOpacity(...a) {
     if (a.length >= 3) {
       const api = (a[0] && _mapApis[a[0]]) || _lastMapApi;
@@ -17887,6 +18055,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     htmlgui_getAttributionString: () => (_lastMapApi && _lastMapApi.getAttribution ? _lastMapApi.getAttribution() : ''),
     changeThemeStyle: compatChangeThemeStyle,
     removeTheme: compatRemoveTheme,
+    toggleTheme: compatToggleTheme,
     // flat's ixmaps.setLocalString(orig, local) (htmlgui.js 3814 →
     // Api.setLocalString → Dictionary.replace): a page-wide translation,
     // e.g. the migration page's ISO code → country name; usable before
@@ -17935,7 +18104,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     flatToMapLibreZoom, mapLibreToFlatZoom, flatViewToMapLibreZoom, mapLibreToFlatViewZoom, flatSvgProjectionOf, flatSvgProjectionByOptions, normalSizeScaleOf, scaleDenominatorAt, resolveZoomReference, resolveAggregationPx, valuesHiddenByScale,
     fetchLayerData, QUERY_HANDOFF, parseCsvText, dataTableRows, geometryRowsToFeatureCollection, filterFlatValues, applyField100, field100Binding, rangeClassLegendTotals, resolveAggregateValue, classValueSeparate, cellAggregatedValues, oneHot, groupCoLocated, aggregateOnGrid, GridAggregateIndex, flatRangeParts, explicitRangeBreaks, explicitRangeParts, resolvePartsClass, isNoneColor, aggregateField100, valueRadius, itemPlotGeometry, itemAnchor, objectZoomFactor, resolveZoomReference, defaultNormalSizeValue,
     applyWhereFilter, joinChartPositions, joinChoroplethFeatures, flatLookupKey, flatShapeCenter, chartHiddenByScale, glowHiddenByScale, isSymbolChart, flatChartAlignOffset, flatChartBranch, flatValueText, categoryValueRecord, flatDerivateRgb, flatBubbleLook, bubbleIconLook, flatChartTextRgb, flatGroupedValue, flatNoBreaks, featuresHiddenByScale, boxHiddenByScale, flatShadowOn, snapToAggregationGrid,
-    drawSymbolPath, normalizeSymbolShape,
+    drawSymbolPath, normalizeSymbolShape, bubbleStrokeRgb,
     flatFormatValue, themeStyleArgs, flatChangedStyleValue, explicitValueDecimals, legendDecimals,
     dataCacheKey, dataCacheDisabled, cachedLayerData, featuresBounds, wantsZoomToExtent, legendIsOn, applySphereBackdrop,
   };

package/package.json

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