@aiaiai-pt/design-system 0.16.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

@@ -12,7 +12,7 @@
 -->
 <script>
   import { fromLonLat } from 'ol/proj.js';
-  import { createTileLayer, createMapStyles, watchTheme, renderMapError } from './map-utils.js';
+  import { createTileLayer, createMapStyles, createOverlayLayers, watchTheme, renderMapError } from './map-utils.js';
 
   let {
     /** @type {[number, number]} — [longitude, latitude] WGS84 */
@@ -25,6 +25,12 @@
     polygon = 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 marker/polygon layer.
+     *  Each entry: inline `data` or a `url` (e.g. the platform's
+     *  `/{app}/public/layers/{id}/features`), optional flat or GeoStyler
+     *  `style`. See map-utils OverlayLayerDef. */
+    layers = [],
     /** @type {string} */
     height = '100%',
     /** @type {string} */
@@ -35,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;
 
@@ -71,6 +109,8 @@
       ]);
       if (disposed) return;
 
+      _styles = styles;
+
       /** @type {Feature[]} */
       const features = [];
 
@@ -94,6 +134,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 vector layer.
         layers: [tileLayer, vectorLayer],
         view: new View({
           center: fromLonLat(center),
@@ -101,10 +143,14 @@
         }),
         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();
       });
     } catch (err) { renderMapError(container, 'MapDisplay', /** @type {Error} */ (err)); } })();
 

package/components/MapDisplay.svelte.d.ts

@@ -21,6 +21,7 @@ declare const MapDisplay: import("svelte").Component<{
     marker?: any;
     polygon?: any;
     tileSource?: Record<string, any>;
+    layers?: any[];
     height?: string;
     class?: string;
 } & Record<string, any>, {}, "">;
@@ -30,6 +31,7 @@ type $$ComponentProps = {
     marker?: any;
     polygon?: any;
     tileSource?: Record<string, any>;
+    layers?: any[];
     height?: string;
     class?: string;
 } & Record<string, any>;

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

@@ -22,7 +22,16 @@
 
 <script>
   import { fromLonLat, toLonLat } from 'ol/proj.js';
-  import { createTileLayer, createMapStyles, watchTheme, renderMapError } from './map-utils.js';
+  import {
+    createTileLayer,
+    createMapStyles,
+    createOverlayLayers,
+    createBoundaryLayer,
+    boundaryToRings,
+    pointInRings,
+    watchTheme,
+    renderMapError,
+  } from './map-utils.js';
   import GeoSearch from './GeoSearch.svelte';
 
   let {
@@ -50,6 +59,18 @@
     searchViewbox = undefined,
     /** @type {import('./map-utils.js').TileSourceConfig} */
     tileSource = { type: 'osm' },
+    /** @type {import('./map-utils.js').OverlayLayerDef[]} — ordered GeoJSON
+     *  overlays between the tiles and the draw layer (see MapDisplay). */
+    layers = [],
+    /** @type {any} — tenant boundary: GeoJSON Polygon/MultiPolygon/Feature/
+     *  FeatureCollection or a raw ring [[lon,lat],...]. Rendered as a dashed
+     *  --map-boundary-* overlay; point placements are tested against it. */
+    boundary = undefined,
+    /** @type {((outside: boolean, coords: [number, number]) => void) | undefined}
+     *  Fired on every point placement (map click or search pick) when a
+     *  `boundary` is set. The pin still lands — surfacing/blocking is the
+     *  consumer's call (the intake hard-gate is server-side regardless). */
+    onoutofbounds = undefined,
     /** @type {((coords: [number, number] | number[][]) => void) | undefined} */
     onchange = undefined,
     /** @type {((displayName: string) => void) | undefined} — the resolved
@@ -74,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} */
@@ -103,6 +127,7 @@
       _vectorSource.clear();
       _vectorSource.addFeature(new _Feature({ geometry: new _Point(fromLonLat([lon, lat])) }));
       value = [lon, lat];
+      checkBoundary([lon, lat]);
       onchange?.([lon, lat]);
     }
   }
@@ -112,6 +137,64 @@
     searchCoords = [lon, lat];
   }
 
+  const boundaryRings = $derived(boundaryToRings(boundary));
+
+  /** @param {[number, number]} coords */
+  function checkBoundary(coords) {
+    if (!boundaryRings.length || !onoutofbounds) return;
+    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;
 
@@ -148,6 +231,11 @@
       ]);
       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;
       _Feature = Feature;
@@ -191,6 +279,7 @@
           const wgs84 = /** @type {[number, number]} */ (toLonLat(coords));
           value = wgs84;
           handleMapPointPlaced(wgs84[0], wgs84[1]);
+          checkBoundary(wgs84);
           onchange?.(wgs84);
         } else {
           const coords = /** @type {import('ol/geom/Polygon.js').default} */ (geom).getCoordinates()[0];
@@ -216,6 +305,7 @@
       disposeTheme = watchTheme(() => {
         styles.refresh();
         vectorSource.changed();
+        for (const l of _overlayLayers) l.getSource()?.changed();
       });
     } catch (err) { renderMapError(container, 'MapPicker', /** @type {Error} */ (err)); } })();
 

package/components/MapPicker.svelte.d.ts

@@ -34,6 +34,9 @@ declare const MapPicker: import("svelte").Component<{
     searchProviderUrl?: any;
     searchViewbox?: any;
     tileSource?: Record<string, any>;
+    layers?: any[];
+    boundary?: any;
+    onoutofbounds?: any;
     onchange?: any;
     onaddress?: any;
     height?: string;
@@ -53,6 +56,9 @@ type $$ComponentProps = {
     searchProviderUrl?: any;
     searchViewbox?: any;
     tileSource?: Record<string, any>;
+    layers?: any[];
+    boundary?: any;
+    onoutofbounds?: any;
     onchange?: any;
     onaddress?: any;
     height?: string;

package/components/map-utils.js

@@ -336,3 +336,264 @@ export function getHeatmapGradient(el) {
 
   return ["rgba(251, 227, 142, 0)", "#fbe38e", "#fb923c", "#e85a28", "#ae2a1e"];
 }
+
+// ─── Overlay Layers (#187 D-c) ───────────────────────────────────
+
+/**
+ * @typedef {object} OverlayLayerStyle
+ * Flat style subset applied to a whole overlay layer. Colors are CSS color
+ * strings (they come from layer DATA — geolayers GeoStyler styles — not
+ * from design tokens; absent values fall back to the DS-tokened defaults).
+ * @property {string} [pointColor]
+ * @property {number} [pointRadius]
+ * @property {string} [strokeColor]
+ * @property {number} [strokeWidth]
+ * @property {string} [fillColor]
+ *
+ * @typedef {object} OverlayLayerDef
+ * One ordered overlay rendered between the tile layer and the component's
+ * own interactive vector layer. v1 is GeoJSON-only — the platform's citizen
+ * data plane serves GeoJSON (`/{app}/public/layers/{id}/features`); WMS/tile
+ * overlays arrive with the per-tenant raster principal (spec open question).
+ * @property {string} [id]
+ * @property {'geojson'} [type]
+ * @property {object} [data] — inline GeoJSON (Feature/FeatureCollection)
+ * @property {string} [url] — fetched when `data` is absent
+ * @property {OverlayLayerStyle | object} [style] — flat style or GeoStyler
+ *   JSON (best-effort subset via `geoStylerToFlat`)
+ * @property {boolean} [visible]
+ */
+
+/**
+ * Best-effort GeoStyler → flat style. Reads the first symbolizer of the
+ * first rule — enough for the platform's single-rule layer styles. Unknown
+ * shapes return {} so the DS-tokened defaults apply.
+ *
+ * @param {any} style
+ * @returns {OverlayLayerStyle}
+ */
+export function geoStylerToFlat(style) {
+  if (!style || typeof style !== "object") return {};
+  if (!Array.isArray(style.rules)) return /** @type {OverlayLayerStyle} */ (style);
+  const sym = style.rules?.[0]?.symbolizers?.[0];
+  if (!sym || typeof sym !== "object") return {};
+  /** @type {OverlayLayerStyle} */
+  const flat = {};
+  if (sym.kind === "Mark" || sym.kind === "Icon") {
+    if (typeof sym.color === "string") flat.pointColor = sym.color;
+    if (typeof sym.radius === "number") flat.pointRadius = sym.radius;
+    if (typeof sym.strokeColor === "string") flat.strokeColor = sym.strokeColor;
+    if (typeof sym.strokeWidth === "number") flat.strokeWidth = sym.strokeWidth;
+  } else if (sym.kind === "Line") {
+    if (typeof sym.color === "string") flat.strokeColor = sym.color;
+    if (typeof sym.width === "number") flat.strokeWidth = sym.width;
+  } else if (sym.kind === "Fill") {
+    if (typeof sym.color === "string") flat.fillColor = sym.color;
+    if (typeof sym.outlineColor === "string") flat.strokeColor = sym.outlineColor;
+    if (typeof sym.outlineWidth === "number") flat.strokeWidth = sym.outlineWidth;
+  }
+  return flat;
+}
+
+/**
+ * Builds OL vector layers for `layers` overlay defs, ordered as given.
+ * URL-sourced layers load asynchronously into their source; a fetch failure
+ * leaves that overlay empty and logs a warning (the map still renders).
+ *
+ * @param {OverlayLayerDef[]} defs
+ * @param {import('./map-utils.js').MapStyles} styles — DS default styles
+ * @returns {Promise<import('ol/layer/Vector.js').default[]>}
+ */
+export async function createOverlayLayers(defs, styles) {
+  if (!Array.isArray(defs) || defs.length === 0) return [];
+
+  const [
+    { default: VectorLayer },
+    { default: VectorSource },
+    { default: GeoJSON },
+    { default: Style },
+    { default: CircleStyle },
+    { default: Fill },
+    { default: Stroke },
+  ] = await Promise.all([
+    import("ol/layer/Vector.js"),
+    import("ol/source/Vector.js"),
+    import("ol/format/GeoJSON.js"),
+    import("ol/style/Style.js"),
+    import("ol/style/Circle.js"),
+    import("ol/style/Fill.js"),
+    import("ol/style/Stroke.js"),
+  ]);
+
+  const format = new GeoJSON({ featureProjection: "EPSG:3857" });
+
+  /** @param {OverlayLayerDef} def */
+  function buildStyleFn(def) {
+    const flat = geoStylerToFlat(def.style);
+    const hasCustom = Object.keys(flat).length > 0;
+    if (!hasCustom) {
+      return (/** @type {any} */ feature) => {
+        const type = feature.getGeometry()?.getType();
+        return type === "Point" || type === "MultiPoint"
+          ? styles.marker
+          : styles.polygon;
+      };
+    }
+    const stroke = new Stroke({
+      color: flat.strokeColor ?? flat.pointColor ?? "#3366cc",
+      width: flat.strokeWidth ?? 2,
+    });
+    const fill = new Fill({
+      color: flat.fillColor ?? "rgba(51,102,204,0.15)",
+    });
+    const point = new Style({
+      image: new CircleStyle({
+        radius: flat.pointRadius ?? 6,
+        fill: new Fill({ color: flat.pointColor ?? flat.strokeColor ?? "#3366cc" }),
+        stroke,
+      }),
+    });
+    const shape = new Style({ fill, stroke });
+    return (/** @type {any} */ feature) => {
+      const type = feature.getGeometry()?.getType();
+      return type === "Point" || type === "MultiPoint" ? point : shape;
+    };
+  }
+
+  return defs
+    .filter((def) => def && def.visible !== false)
+    .map((def) => {
+      const source = new VectorSource();
+      if (def.data) {
+        source.addFeatures(format.readFeatures(def.data));
+      } else if (def.url) {
+        fetch(def.url)
+          .then((r) => {
+            if (!r.ok) throw new Error(`HTTP ${r.status}`);
+            return r.json();
+          })
+          .then((geojson) => source.addFeatures(format.readFeatures(geojson)))
+          .catch((err) =>
+            console.warn(
+              `[map] overlay layer ${def.id ?? def.url} failed to load:`,
+              err,
+            ),
+          );
+      }
+      return new VectorLayer({ source, style: buildStyleFn(def) });
+    });
+}
+
+// ─── Boundary (#187 D-e prep) ────────────────────────────────────
+
+/**
+ * Normalises a boundary prop into polygon rings (lon/lat WGS84).
+ * Accepts: raw ring `number[][]`, GeoJSON Polygon / MultiPolygon,
+ * Feature, or FeatureCollection (first polygonal feature per entry).
+ *
+ * @param {any} boundary
+ * @returns {number[][][]} — array of outer rings (one per polygon)
+ */
+export function boundaryToRings(boundary) {
+  if (!boundary) return [];
+  if (Array.isArray(boundary)) {
+    // Raw ring: [[lon,lat], ...]
+    return boundary.length >= 3 ? [boundary] : [];
+  }
+  if (boundary.type === "FeatureCollection") {
+    return (boundary.features ?? []).flatMap((/** @type {any} */ f) =>
+      boundaryToRings(f),
+    );
+  }
+  if (boundary.type === "Feature") return boundaryToRings(boundary.geometry);
+  if (boundary.type === "Polygon") {
+    const ring = boundary.coordinates?.[0];
+    return ring && ring.length >= 3 ? [ring] : [];
+  }
+  if (boundary.type === "MultiPolygon") {
+    return (boundary.coordinates ?? [])
+      .map((/** @type {any} */ poly) => poly?.[0])
+      .filter((/** @type {any} */ r) => r && r.length >= 3);
+  }
+  return [];
+}
+
+/**
+ * Ray-casting point-in-polygon over WGS84 rings (outer rings only — holes
+ * are out of scope for the boundary gate; the BFF hard-gate is authoritative).
+ *
+ * @param {[number, number]} lonLat
+ * @param {number[][][]} rings — from `boundaryToRings`
+ * @returns {boolean} true when the point is inside ANY ring
+ */
+export function pointInRings(lonLat, rings) {
+  const [x, y] = lonLat;
+  for (const ring of rings) {
+    let inside = false;
+    for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+      const [xi, yi] = ring[i];
+      const [xj, yj] = ring[j];
+      const intersects =
+        yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi;
+      if (intersects) inside = !inside;
+    }
+    if (inside) return true;
+  }
+  return false;
+}
+
+/**
+ * Builds the boundary overlay layer (dashed outline, faint fill — distinct
+ * from the selection polygon so "the edge of the allowed area" reads as
+ * context, not content). Token-driven: --map-boundary-*.
+ *
+ * @param {number[][][]} rings
+ * @param {Element} el — token read context
+ * @returns {Promise<import('ol/layer/Vector.js').default | null>}
+ */
+export async function createBoundaryLayer(rings, el) {
+  if (!rings.length) return null;
+  const [
+    { default: VectorLayer },
+    { default: VectorSource },
+    { default: Feature },
+    { default: Polygon },
+    { default: Style },
+    { default: Fill },
+    { default: Stroke },
+    { fromLonLat },
+  ] = await Promise.all([
+    import("ol/layer/Vector.js"),
+    import("ol/source/Vector.js"),
+    import("ol/Feature.js"),
+    import("ol/geom/Polygon.js"),
+    import("ol/style/Style.js"),
+    import("ol/style/Fill.js"),
+    import("ol/style/Stroke.js"),
+    import("ol/proj.js"),
+  ]);
+
+  const dash = cssPx(el, "--map-boundary-dash", 8);
+  const style = new Style({
+    fill: new Fill({
+      color: cssVar(el, "--map-boundary-fill", "rgba(255,107,53,0.06)"),
+    }),
+    stroke: new Stroke({
+      color: cssVar(el, "--map-boundary-stroke", "#ff6b35"),
+      width: cssPx(el, "--map-boundary-stroke-width", 2),
+      lineDash: [dash, dash * 0.75],
+    }),
+  });
+
+  const features = rings.map(
+    (ring) =>
+      new Feature({
+        geometry: new Polygon([ring.map((c) => fromLonLat(c))]),
+      }),
+  );
+
+  return new VectorLayer({
+    source: new VectorSource({ features }),
+    style,
+  });
+}

package/package.json

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

package/tokens/components.css

@@ -797,6 +797,12 @@
   --map-polygon-stroke: var(--color-accent);
   --map-polygon-stroke-width: var(--border-width-thick);
 
+  /* Boundary overlay (#187 — tenant geofence context, not content) */
+  --map-boundary-fill: color-mix(in srgb, var(--color-accent) 8%, transparent);
+  --map-boundary-stroke: var(--map-polygon-stroke);
+  --map-boundary-stroke-width: var(--map-polygon-stroke-width);
+  --map-boundary-dash: var(--space-sm);
+
   /* Heatmap (accent-derived sequential ramp — follows theme) */
   --map-heatmap-stop-1: var(--color-accent-subtle);
   --map-heatmap-stop-2: color-mix(