@aiaiai-pt/design-system 0.17.0 → 0.17.1

package/components/ActionFormRenderer.svelte

@@ -73,6 +73,18 @@
      *  in submit modes. */
     captcha?: Snippet;
     submitLabel?: string;
+    /** Forwarded VERBATIM to every `geo` parameter's MapPicker (the renderer
+     *  stays generic — boundary/overlay semantics live in the consumer):
+     *  `boundary` draws the dashed tenant-boundary overlay and arms the
+     *  out-of-bounds check; `layers` are ordered GeoJSON overlays (unbounded);
+     *  `onoutofbounds(outside, coords)` fires on every point placement when a
+     *  boundary is set — NON-blocking, the consumer owns surfacing/gating. */
+    boundary?: unknown;
+    layers?: unknown[];
+    onoutofbounds?: (outside: boolean, coords: [number, number]) => void;
+    /** Inline error rendered by the geo MapPicker(s) (e.g. the consumer's
+     *  out-of-bounds copy) — forwarded as MapPicker's `error`. */
+    geoError?: string;
   }
 
   let {
@@ -86,6 +98,10 @@
     uploadFile = undefined,
     captcha = undefined,
     submitLabel = "Submit",
+    boundary = undefined,
+    layers = [],
+    onoutofbounds = undefined,
+    geoError = undefined,
   }: Props = $props();
 
   let values = $state<Record<string, unknown>>({});
@@ -451,6 +467,10 @@
     <MapPicker
       mode="point"
       height="20rem"
+      {boundary}
+      {layers}
+      {onoutofbounds}
+      error={geoError}
       label={String(parameter.label ?? key)}
       center={Array.isArray(parameter.default_value)
         ? (parameter.default_value as [number, number])

package/components/ActionFormRenderer.svelte.d.ts

@@ -58,6 +58,18 @@ interface Props {
      *  in submit modes. */
     captcha?: Snippet;
     submitLabel?: string;
+    /** Forwarded VERBATIM to every `geo` parameter's MapPicker (the renderer
+     *  stays generic — boundary/overlay semantics live in the consumer):
+     *  `boundary` draws the dashed tenant-boundary overlay and arms the
+     *  out-of-bounds check; `layers` are ordered GeoJSON overlays (unbounded);
+     *  `onoutofbounds(outside, coords)` fires on every point placement when a
+     *  boundary is set — NON-blocking, the consumer owns surfacing/gating. */
+    boundary?: unknown;
+    layers?: unknown[];
+    onoutofbounds?: (outside: boolean, coords: [number, number]) => void;
+    /** Inline error rendered by the geo MapPicker(s) (e.g. the consumer's
+     *  out-of-bounds copy) — forwarded as MapPicker's `error`. */
+    geoError?: string;
 }
 declare const ActionFormRenderer: import("svelte").Component<Props, {}, "">;
 type ActionFormRenderer = ReturnType<typeof ActionFormRenderer>;

package/components/MapCluster.svelte

@@ -15,7 +15,7 @@
 <script>
   import { fromLonLat } from 'ol/proj.js';
   import { boundingExtent } from 'ol/extent.js';
-  import { createTileLayer, createMapStyles, watchTheme, renderMapError } from './map-utils.js';
+  import { createTileLayer, createMapStyles, createOverlayLayers, watchTheme, renderMapError } from './map-utils.js';
 
   let {
     /** @type {{ id: string, lon: number, lat: number, label?: string, [key: string]: any }[]} */
@@ -31,6 +31,12 @@
     distance = 40,
     /** @type {import('./map-utils.js').TileSourceConfig} */
     tileSource = { type: 'osm' },
+    /** @type {import('./map-utils.js').OverlayLayerDef[]} — ordered GeoJSON
+     *  overlays rendered between the tiles and the cluster layer. Each
+     *  entry: inline `data` or a `url` (e.g. the platform's
+     *  `/{app}/public/layers/{id}/features`), optional flat or GeoStyler
+     *  `style`. Unbounded — render as many as the consumer configures. */
+    layers = [],
     /** @type {((marker: { id: string, lon: number, lat: number, label?: string }) => void) | undefined} */
     onclick = undefined,
     /** @type {string} */
@@ -50,11 +56,40 @@
   let _vectorSource = $state();
   /** @type {any} — Cluster source */
   let _clusterSource = $state();
+  /** @type {any} — shared style factory (set at mount, consumed by the
+   *  overlay owner effect) */
+  let _styles = $state();
   /** @type {any} — Feature constructor */
   let _Feature;
   /** @type {any} — Point constructor */
   let _Point;
 
+  // The `layers` overlays have ONE owner: this effect (same contract as
+  // MapPicker's boundary). Consumers typically RESOLVE overlay defs
+  // asynchronously (layer codes → url defs, after a fetch), so a
+  // mount-time-only build silently drops them — the overlays must track
+  // `layers` for as long as the map lives. The sequence counter drops
+  // stale async builds when the defs change mid-flight.
+  /** @type {any[]} */
+  let _overlayLayers = [];
+  let _overlaySeq = 0;
+  $effect(() => {
+    const defs = layers;
+    const map = _map;
+    const styles = _styles;
+    if (!map || !styles) return;
+    const seq = ++_overlaySeq;
+    void (async () => {
+      const built = defs?.length ? await createOverlayLayers(defs, styles) : [];
+      if (seq !== _overlaySeq || _map !== map) return;
+      for (const l of _overlayLayers) map.removeLayer(l);
+      _overlayLayers = built;
+      // Between the tiles (index 0) and the cluster layer — overlays never
+      // cover the markers.
+      built.forEach((l, i) => map.getLayers().insertAt(1 + i, l));
+    })();
+  });
+
   // Reactive: animate when the CALLER's center/zoom props change. Guarded
   // against the mount-time run — with no explicit `center` the view was
   // initialised to the markers' extent/mean, and animating to the prop
@@ -135,6 +170,7 @@
       // Store refs for reactive effects
       _vectorSource = vectorSource;
       _clusterSource = clusterSource;
+      _styles = styles;
       _Feature = Feature;
       _Point = Point;
 
@@ -186,6 +222,8 @@
 
       map = new OlMap({
         target: container,
+        // The `layers` overlays are NOT built here — the reactive owner
+        // effect above inserts them between the tiles and the cluster layer.
         layers: [tileLayer, clusterLayer],
         overlays: [tooltipOverlay],
         view: new View({

package/components/MapCluster.svelte.d.ts

@@ -23,6 +23,7 @@ declare const MapCluster: import("svelte").Component<{
     zoom?: number;
     distance?: number;
     tileSource?: Record<string, any>;
+    layers?: any[];
     onclick?: any;
     height?: string;
     class?: string;
@@ -33,6 +34,7 @@ type $$ComponentProps = {
     zoom?: number;
     distance?: number;
     tileSource?: Record<string, any>;
+    layers?: any[];
     onclick?: any;
     height?: string;
     class?: string;

package/components/MapDisplay.svelte

@@ -41,6 +41,38 @@
   /** @type {HTMLElement | undefined} */
   let container = $state();
 
+  // Hoisted references for the overlay owner effect
+  /** @type {import('ol/Map.js').default | undefined} */
+  let _map = $state();
+  /** @type {any} — shared style factory (set at mount) */
+  let _styles = $state();
+
+  // The `layers` overlays have ONE owner: this effect (same contract as
+  // MapPicker's boundary). Consumers typically RESOLVE overlay defs
+  // asynchronously (layer codes → url defs, after a fetch), so a
+  // mount-time-only build silently drops them — the overlays must track
+  // `layers` for as long as the map lives. The sequence counter drops
+  // stale async builds when the defs change mid-flight.
+  /** @type {any[]} */
+  let _overlayLayers = [];
+  let _overlaySeq = 0;
+  $effect(() => {
+    const defs = layers;
+    const map = _map;
+    const styles = _styles;
+    if (!map || !styles) return;
+    const seq = ++_overlaySeq;
+    void (async () => {
+      const built = defs?.length ? await createOverlayLayers(defs, styles) : [];
+      if (seq !== _overlaySeq || _map !== map) return;
+      for (const l of _overlayLayers) map.removeLayer(l);
+      _overlayLayers = built;
+      // Between the tiles (index 0) and the marker/polygon vector layer —
+      // overlays never cover the marker.
+      built.forEach((l, i) => map.getLayers().insertAt(1 + i, l));
+    })();
+  });
+
   $effect(() => {
     if (!container) return;
 
@@ -77,8 +109,7 @@
       ]);
       if (disposed) return;
 
-      const overlayLayers = await createOverlayLayers(layers, styles);
-      if (disposed) return;
+      _styles = styles;
 
       /** @type {Feature[]} */
       const features = [];
@@ -103,20 +134,23 @@
 
       map = new OlMap({
         target: container,
-        layers: [tileLayer, ...overlayLayers, vectorLayer],
+        // The `layers` overlays are NOT built here — the reactive owner
+        // effect above inserts them between the tiles and the vector layer.
+        layers: [tileLayer, vectorLayer],
         view: new View({
           center: fromLonLat(center),
           zoom,
         }),
         controls: [],
       });
+      _map = map;
 
       disposeTheme = watchTheme(() => {
         styles.refresh();
         vectorLayer.getSource()?.changed();
         // Token-styled overlays (no custom style) re-read via the shared
         // styles object; poke their sources so OL repaints.
-        for (const l of overlayLayers) l.getSource()?.changed();
+        for (const l of _overlayLayers) l.getSource()?.changed();
       });
     } catch (err) { renderMapError(container, 'MapDisplay', /** @type {Error} */ (err)); } })();
 

package/components/MapHeatmap.svelte

@@ -21,7 +21,7 @@
 -->
 <script>
   import { fromLonLat } from 'ol/proj.js';
-  import { createTileLayer, getHeatmapGradient, watchTheme, renderMapError } from './map-utils.js';
+  import { createTileLayer, createMapStyles, createOverlayLayers, getHeatmapGradient, watchTheme, renderMapError } from './map-utils.js';
 
   let {
     /** @type {{ lon: number, lat: number, weight?: number }[]} */
@@ -38,6 +38,12 @@
     gradient = undefined,
     /** @type {import('./map-utils.js').TileSourceConfig} */
     tileSource = { type: 'osm' },
+    /** @type {import('./map-utils.js').OverlayLayerDef[]} — ordered GeoJSON
+     *  overlays rendered between the tiles and the heatmap layer. Each
+     *  entry: inline `data` or a `url` (e.g. the platform's
+     *  `/{app}/public/layers/{id}/features`), optional flat or GeoStyler
+     *  `style`. Unbounded — render as many as the consumer configures. */
+    layers = [],
     /** @type {number} — max zoom when auto-fitting to points extent */
     maxZoom = 17,
     /** @type {string} */
@@ -50,6 +56,38 @@
   /** @type {HTMLElement | undefined} */
   let container = $state();
 
+  // Hoisted references for the overlay owner effect
+  /** @type {import('ol/Map.js').default | undefined} */
+  let _map = $state();
+  /** @type {any} — shared style factory (set at mount) */
+  let _styles = $state();
+
+  // The `layers` overlays have ONE owner: this effect (same contract as
+  // MapPicker's boundary). Consumers typically RESOLVE overlay defs
+  // asynchronously (layer codes → url defs, after a fetch), so a
+  // mount-time-only build silently drops them — the overlays must track
+  // `layers` for as long as the map lives. The sequence counter drops
+  // stale async builds when the defs change mid-flight.
+  /** @type {any[]} */
+  let _overlayLayers = [];
+  let _overlaySeq = 0;
+  $effect(() => {
+    const defs = layers;
+    const map = _map;
+    const styles = _styles;
+    if (!map || !styles) return;
+    const seq = ++_overlaySeq;
+    void (async () => {
+      const built = defs?.length ? await createOverlayLayers(defs, styles) : [];
+      if (seq !== _overlaySeq || _map !== map) return;
+      for (const l of _overlayLayers) map.removeLayer(l);
+      _overlayLayers = built;
+      // Between the tiles (index 0) and the heatmap layer — overlays never
+      // cover the heat surface.
+      built.forEach((l, i) => map.getLayers().insertAt(1 + i, l));
+    })();
+  });
+
   $effect(() => {
     if (!container) return;
 
@@ -81,6 +119,12 @@
       const tileLayer = await createTileLayer(tileSource);
       if (disposed) return;
 
+      // Style factory only feeds overlay fallback styles here — the heatmap
+      // layer itself styles via gradient tokens.
+      const styles = await createMapStyles(container);
+      if (disposed) return;
+      _styles = styles;
+
       // Non-linear weight normalization: sqrt lifts low values so they're
       // visible while preserving relative ordering. OL expects 0-1.
       const maxWeight = Math.max(...points.map(p => p.weight ?? 1), 1);
@@ -106,12 +150,15 @@
 
       map = new OlMap({
         target: container,
+        // The `layers` overlays are NOT built here — the reactive owner
+        // effect above inserts them between the tiles and the heatmap layer.
         layers: [tileLayer, heatmapLayer],
         view: new View({
           center: fromLonLat(center),
           zoom,
         }),
       });
+      _map = map;
 
       // Auto-fit view to points extent
       if (points.length > 0) {

package/components/MapHeatmap.svelte.d.ts

@@ -32,6 +32,7 @@ declare const MapHeatmap: import("svelte").Component<{
     blur?: number;
     gradient?: any;
     tileSource?: Record<string, any>;
+    layers?: any[];
     maxZoom?: number;
     height?: string;
     class?: string;
@@ -44,6 +45,7 @@ type $$ComponentProps = {
     blur?: number;
     gradient?: any;
     tileSource?: Record<string, any>;
+    layers?: any[];
     maxZoom?: number;
     height?: string;
     class?: string;

package/components/MapPicker.svelte

@@ -95,6 +95,9 @@
   let container = $state();
   /** @type {import('ol/Map.js').default | undefined} */
   let _map = $state();
+  /** @type {any} — shared style factory (set at mount, consumed by the
+   *  overlay owner effect) */
+  let _styles = $state();
   /** @type {any} — VectorSource for placing markers via search */
   let _vectorSource;
   /** @type {any} */
@@ -142,6 +145,56 @@
     onoutofbounds(!pointInRings(coords, boundaryRings), coords);
   }
 
+  // The dashed boundary overlay has ONE owner: this effect. Consumers
+  // typically FETCH the boundary (it arrives after map init), so a
+  // mount-time-only build silently drops it — the overlay must track
+  // `boundaryRings` for as long as the map lives. The sequence counter
+  // drops stale async builds when the rings change mid-flight.
+  /** @type {any} */
+  let _boundaryLayer = null;
+  let _boundarySeq = 0;
+  $effect(() => {
+    const rings = boundaryRings;
+    const map = _map;
+    if (!map || !container) return;
+    const seq = ++_boundarySeq;
+    void (async () => {
+      const layer = rings.length ? await createBoundaryLayer(rings, container) : null;
+      if (seq !== _boundarySeq || _map !== map) return;
+      if (_boundaryLayer) map.removeLayer(_boundaryLayer);
+      _boundaryLayer = layer;
+      if (layer) {
+        // Just below the pin/draw vector layer — boundary never covers the pin.
+        const coll = map.getLayers();
+        coll.insertAt(coll.getLength() - 1, layer);
+      }
+    })();
+  });
+
+  // The `layers` overlays get the same single-owner treatment as the
+  // boundary above: consumers typically RESOLVE overlay defs asynchronously
+  // (layer codes → url defs, after a fetch), so a mount-time-only build
+  // silently drops them.
+  /** @type {any[]} */
+  let _overlayLayers = [];
+  let _overlaySeq = 0;
+  $effect(() => {
+    const defs = layers;
+    const map = _map;
+    const styles = _styles;
+    if (!map || !styles) return;
+    const seq = ++_overlaySeq;
+    void (async () => {
+      const built = defs?.length ? await createOverlayLayers(defs, styles) : [];
+      if (seq !== _overlaySeq || _map !== map) return;
+      for (const l of _overlayLayers) map.removeLayer(l);
+      _overlayLayers = built;
+      // Between the tiles (index 0) and the boundary/pin layers — overlays
+      // never cover the pin.
+      built.forEach((l, i) => map.getLayers().insertAt(1 + i, l));
+    })();
+  });
+
   $effect(() => {
     if (!container || disabled) return;
 
@@ -178,11 +231,10 @@
       ]);
       if (disposed) return;
 
-      const [overlayLayers, boundaryLayer] = await Promise.all([
-        createOverlayLayers(layers, styles),
-        createBoundaryLayer(boundaryRings, container),
-      ]);
-      if (disposed) return;
+      // Neither the boundary overlay NOR the `layers` overlays are built
+      // here — the reactive owner effects above track their late-arriving
+      // props for as long as the map lives.
+      _styles = styles;
 
       const vectorSource = new VectorSource();
       _vectorSource = vectorSource;
@@ -240,12 +292,7 @@
 
       map = new OlMap({
         target: container,
-        layers: [
-          tileLayer,
-          ...overlayLayers,
-          ...(boundaryLayer ? [boundaryLayer] : []),
-          vectorLayer,
-        ],
+        layers: [tileLayer, vectorLayer],
         view: new View({
           center: initialCenter,
           zoom,
@@ -258,7 +305,7 @@
       disposeTheme = watchTheme(() => {
         styles.refresh();
         vectorSource.changed();
-        for (const l of overlayLayers) l.getSource()?.changed();
+        for (const l of _overlayLayers) l.getSource()?.changed();
       });
     } catch (err) { renderMapError(container, 'MapPicker', /** @type {Error} */ (err)); } })();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",