@aiaiai-pt/design-system 0.15.0 → 0.17.0

package/components/ActionFormRenderer.svelte

@@ -7,6 +7,8 @@
   import CodeBlock from "./CodeBlock.svelte";
   import Input from "./Input.svelte";
   import MapPicker from "./MapPicker.svelte";
+  import FileUpload from "./FileUpload.svelte";
+  import FileUploadItem from "./FileUploadItem.svelte";
   import Select from "./Select.svelte";
   import Tag from "./Tag.svelte";
   import type { Snippet } from "svelte";
@@ -62,6 +64,11 @@
     /** Injected apply. Required for a working submit button; absent → no button
      *  (so admin-preview / adapter-preview stay read-only). */
     onApply?: (payload: Record<string, unknown>) => Promise<ApplyResult>;
+    /** Transport for `file`-typed parameters (#75 M5 slice 4b): receives one
+     *  validated File, returns its storage key. The renderer owns the UI +
+     *  the attachment_keys payload contract; the CONSUMER owns transport/auth
+     *  (FileUpload philosophy). Omitted → file params render disabled. */
+    uploadFile?: (file: File) => Promise<{ key: string } | { error: string }>;
     /** Environment-specific captcha (e.g. Turnstile), rendered above the button
      *  in submit modes. */
     captcha?: Snippet;
@@ -76,11 +83,22 @@
     mode = "admin-preview",
     schema = null,
     onApply = undefined,
+    uploadFile = undefined,
     captcha = undefined,
     submitLabel = "Submit",
   }: Props = $props();
 
   let values = $state<Record<string, unknown>>({});
+  // `file` params live OUTSIDE values — their keys ride the payload's
+  // top-level attachment_keys, never raw_values (the form schema doesn't
+  // know them; validation would reject strays).
+  let fileUploads = $state<Record<string, Array<{ key: string; name: string }>>>({});
+  let fileBusy = $state<Record<string, boolean>>({});
+  let fileError = $state<Record<string, string>>({});
+  // Platform caps mirror the public upload surface (3 × 5MB, web image types).
+  const FILE_MAX_COUNT = 3;
+  const FILE_MAX_BYTES = 5 * 1024 * 1024;
+  const FILE_ACCEPT = "image/jpeg,image/png,image/webp";
 
   // Submit state (apply seam). Only meaningful in submit modes with an onApply.
   let submitting = $state(false);
@@ -124,7 +142,11 @@
   const canSubmit = $derived(
     visibleParameters
       .filter((parameter) => parameter.required)
-      .every((parameter) => !isEmpty(values[parameterKey(parameter)])),
+      .every((parameter) =>
+        String(parameter.type ?? "") === "file"
+          ? (fileUploads[parameterKey(parameter)] ?? []).length > 0
+          : !isEmpty(values[parameterKey(parameter)]),
+      ),
   );
 
   async function handleSubmit(): Promise<void> {
@@ -287,6 +309,45 @@
       : {};
   }
 
+  async function handleFiles(key: string, files: File[]) {
+    if (!uploadFile) return;
+    fileError = { ...fileError, [key]: "" };
+    const existing = fileUploads[key] ?? [];
+    const room = FILE_MAX_COUNT - existing.length;
+    const batch = files.slice(0, room);
+    if (files.length > room) {
+      fileError = { ...fileError, [key]: `Up to ${FILE_MAX_COUNT} files` };
+    }
+    if (batch.length === 0) return;
+    fileBusy = { ...fileBusy, [key]: true };
+    try {
+      for (const file of batch) {
+        const result = await uploadFile(file);
+        if ("key" in result) {
+          fileUploads = {
+            ...fileUploads,
+            [key]: [...(fileUploads[key] ?? []), { key: result.key, name: file.name }],
+          };
+        } else {
+          fileError = { ...fileError, [key]: result.error };
+        }
+      }
+    } finally {
+      fileBusy = { ...fileBusy, [key]: false };
+    }
+  }
+
+  function removeFile(key: string, storageKey: string) {
+    fileUploads = {
+      ...fileUploads,
+      [key]: (fileUploads[key] ?? []).filter((f) => f.key !== storageKey),
+    };
+  }
+
+  function allAttachmentKeys(): string[] {
+    return Object.values(fileUploads).flatMap((list) => list.map((f) => f.key));
+  }
+
   function buildPayload(): Record<string, unknown> {
     return buildActionPayload({
       action: renderedAction ?? null,
@@ -294,6 +355,7 @@
       targetConfig: targetConfig(),
       sourceSchema: sourceSchema(),
       rawValues: visibleValueBag(),
+      attachmentKeys: allAttachmentKeys(),
       schemaVersion: schema?.schema_version ?? null,
       mode,
     }) as unknown as Record<string, unknown>;
@@ -350,11 +412,42 @@
       ]}
       onchange={(value: string) => setValue(key, value === "true")}
     />
+  {:else if type === "file"}
+    <!-- `file` parameter (#75 M5 slice 4b): upload-as-you-attach. The keys
+         ride payload.attachment_keys; raw_values never sees this param. -->
+    <div class="afr-file-param">
+      <span class="afr-file-label">{String(parameter.label ?? key)}</span>
+      {#each fileUploads[key] ?? [] as f (f.key)}
+        <FileUploadItem
+          name={f.name}
+          onremove={() => removeFile(key, f.key)}
+        />
+      {/each}
+      {#if (fileUploads[key] ?? []).length < FILE_MAX_COUNT}
+        <FileUpload
+          accept={FILE_ACCEPT}
+          maxSize={FILE_MAX_BYTES}
+          multiple
+          disabled={!uploadFile || fileBusy[key]}
+          onfiles={(files: File[]) => handleFiles(key, files)}
+          onreject={() => {
+            fileError = { ...fileError, [key]: "JPEG, PNG or WebP up to 5MB" };
+          }}
+        />
+      {/if}
+      {#if fileError[key]}
+        <p class="afr-file-error" role="alert">{fileError[key]}</p>
+      {/if}
+    </div>
   {:else if type === "geo"}
     <!-- A `geo` parameter renders the DS map-picker; its value is the
          [lon, lat] the BFF's GEO_PARSE binding transform turns into a Point.
          The renderer stays generic — geo is just another param type, the
-         occurrence/location coupling lives entirely in the ontology binding. -->
+         occurrence/location coupling lives entirely in the ontology binding.
+         SIBLING-ADDRESS CONVENTION: when the form also declares a parameter
+         keyed `address`, the picker's resolved address (search pick or
+         reverse geocode) auto-fills it — tracking the pin; the citizen can
+         still edit the field afterwards (a later pin overwrites). -->
     <MapPicker
       mode="point"
       height="20rem"
@@ -366,6 +459,11 @@
         ? (values[key] as [number, number])
         : undefined}
       onchange={(coords: [number, number]) => setValue(key, coords)}
+      onaddress={(displayName: string) => {
+        if (renderedParameters.some((p) => parameterKey(p) === "address")) {
+          setValue("address", displayName);
+        }
+      }}
     />
   {:else}
     <Input
@@ -538,6 +636,23 @@
     gap: var(--space-lg);
   }
 
+  .afr-file-param {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+  }
+
+  .afr-file-label {
+    font-size: var(--input-label-size, var(--type-body-sm-size));
+    color: var(--color-text-secondary);
+  }
+
+  .afr-file-error {
+    margin: 0;
+    font-size: var(--type-body-sm-size);
+    color: var(--input-error-text);
+  }
+
   .submit-captcha {
     min-height: var(--space-4xl);
   }

package/components/ActionFormRenderer.svelte.d.ts

@@ -45,6 +45,15 @@ interface Props {
     /** Injected apply. Required for a working submit button; absent → no button
      *  (so admin-preview / adapter-preview stay read-only). */
     onApply?: (payload: Record<string, unknown>) => Promise<ApplyResult>;
+    /** Transport for `file`-typed parameters (#75 M5 slice 4b): receives one
+     *  validated File, returns its storage key. The renderer owns the UI +
+     *  the attachment_keys payload contract; the CONSUMER owns transport/auth
+     *  (FileUpload philosophy). Omitted → file params render disabled. */
+    uploadFile?: (file: File) => Promise<{
+        key: string;
+    } | {
+        error: string;
+    }>;
     /** Environment-specific captcha (e.g. Turnstile), rendered above the button
      *  in submit modes. */
     captcha?: Snippet;

package/components/GeoSearch.svelte

@@ -43,6 +43,10 @@
     viewbox = undefined,
     /** @type {((lon: number, lat: number, item: { label: string, value: string }) => void) | undefined} */
     onlocation = undefined,
+    /** @type {((displayName: string) => void) | undefined} — fires with the
+     *  resolved address label on BOTH paths: reverse geocode (map click /
+     *  coords set) and forward selection. Consumers feed address fields. */
+    onresolved = undefined,
     /** @type {[number, number] | undefined} — set externally to reverse-geocode and show address */
     coords = $bindable(undefined),
     /** @type {string} */
@@ -78,6 +82,7 @@
       if (result.display_name) {
         value = `${lon},${lat}`;
         items = [{ value: `${lon},${lat}`, label: result.display_name, description: result.type?.replace(/_/g, ' ') ?? '' }];
+        onresolved?.(result.display_name);
       }
     } catch {
       // Reverse geocoding failed — leave search bar as-is
@@ -135,9 +140,10 @@
     const [lonStr, latStr] = val.split(',');
     const lon = parseFloat(lonStr);
     const lat = parseFloat(latStr);
-    if (!Number.isNaN(lon) && !Number.isNaN(lat) && onlocation) {
+    if (!Number.isNaN(lon) && !Number.isNaN(lat)) {
       const selectedItem = items.find((i) => i.value === val);
-      onlocation(lon, lat, selectedItem ?? { label: '', value: val });
+      if (selectedItem?.label) onresolved?.(selectedItem.label);
+      onlocation?.(lon, lat, selectedItem ?? { label: '', value: val });
     }
   }
 </script>

package/components/GeoSearch.svelte.d.ts

@@ -36,6 +36,7 @@ declare const GeoSearch: import("svelte").Component<{
     providerUrl?: string;
     viewbox?: any;
     onlocation?: any;
+    onresolved?: any;
     coords?: any;
     class?: string;
 } & Record<string, any>, {}, "coords">;
@@ -49,6 +50,7 @@ type $$ComponentProps = {
     providerUrl?: string;
     viewbox?: any;
     onlocation?: any;
+    onresolved?: any;
     coords?: any;
     class?: string;
 } & Record<string, any>;

package/components/MapCluster.svelte

@@ -14,13 +14,17 @@
 -->
 <script>
   import { fromLonLat } from 'ol/proj.js';
+  import { boundingExtent } from 'ol/extent.js';
   import { createTileLayer, createMapStyles, watchTheme, renderMapError } from './map-utils.js';
 
   let {
     /** @type {{ id: string, lon: number, lat: number, label?: string, [key: string]: any }[]} */
     markers = [],
-    /** @type {[number, number]} — initial center [lon, lat] */
-    center = [0, 0],
+    /** @type {[number, number] | undefined} — initial center [lon, lat].
+     *  Omit to auto-FIT the markers' extent (the right default for "show
+     *  my data" maps; explicit center wins for dashboards pinned to a
+     *  region). */
+    center = undefined,
     /** @type {number} */
     zoom = 6,
     /** @type {number} — cluster distance in pixels */
@@ -51,13 +55,21 @@
   /** @type {any} — Point constructor */
   let _Point;
 
-  // Reactive: animate to new center/zoom when props change
+  // 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
+  // default ([0,0], null island) shoved every marker off-screen.
+  let _lastCenterKey = $state("");
   $effect(() => {
-    if (!_map) return;
+    const key = center ? `${center[0]},${center[1]},${zoom}` : "";
+    if (!_map || !center) return;
+    if (key === _lastCenterKey) return;
+    const first = _lastCenterKey === "";
+    _lastCenterKey = key;
+    if (first) return; // initial view already honours the props
     const view = _map.getView();
     if (!view) return;
-    const targetCenter = fromLonLat(center);
-    view.animate({ center: targetCenter, zoom, duration: 300 });
+    view.animate({ center: fromLonLat(center), zoom, duration: 300 });
   });
 
   // Reactive: update markers when props change
@@ -155,14 +167,22 @@
         element: tooltipEl,
         positioning: 'bottom-center',
         offset: [0, -12],
+        // The hover tooltip anchors AT the feature — OL's default
+        // stopEvent:true puts it in the event-stopping overlay pane, so the
+        // very click the tooltip invites lands on the overlay container and
+        // dies (the element's own pointer-events:none can't help; the
+        // CONTAINER captures). Informational overlay → never stop events.
+        stopEvent: false,
       });
 
-      const viewCenter = markers.length > 0
-        ? fromLonLat([
-            markers.reduce((s, m) => s + m.lon, 0) / markers.length,
-            markers.reduce((s, m) => s + m.lat, 0) / markers.length,
-          ])
-        : fromLonLat(center);
+      const viewCenter = center
+        ? fromLonLat(center)
+        : markers.length > 0
+          ? fromLonLat([
+              markers.reduce((s, m) => s + m.lon, 0) / markers.length,
+              markers.reduce((s, m) => s + m.lat, 0) / markers.length,
+            ])
+          : fromLonLat([0, 0]);
 
       map = new OlMap({
         target: container,
@@ -174,6 +194,14 @@
         }),
       });
       _map = map;
+      // No explicit center → fit the markers' extent so every cluster is on
+      // screen regardless of how the data spreads (mean-centre alone leaves
+      // distant clouds outside the default zoom).
+      if (!center && markers.length > 1) {
+        const coords = markers.map((m) => fromLonLat([m.lon, m.lat]));
+        const ext = boundingExtent(coords);
+        map.getView().fit(ext, { padding: [48, 48, 48, 48], maxZoom: 15 });
+      }
 
       // Hover: show tooltip
       map.on('pointermove', (evt) => {
@@ -212,6 +240,18 @@
             const data = clustered[0].get('markerData');
             if (data) onclick(data);
           } else if (clustered?.length > 1) {
+            // A cluster of (near-)IDENTICAL coordinates can never split by
+            // zooming (stacked reports at one point are common in civic
+            // data) — open the first item instead of zoom-looping forever.
+            const coords = clustered.map((f) => f.getGeometry()?.getCoordinates()).filter(Boolean);
+            const lons = coords.map((c) => c[0]);
+            const lats = coords.map((c) => c[1]);
+            const spread = Math.max(...lons) - Math.min(...lons) + (Math.max(...lats) - Math.min(...lats));
+            if (spread < 1) { // metres in web-mercator units — a stacked pile
+              const data = clustered[0].get('markerData');
+              if (data) onclick(data);
+              return;
+            }
             const view = map?.getView();
             const currentZoom = view?.getZoom() ?? zoom;
             view?.animate({

package/components/MapCluster.svelte.d.ts

@@ -19,7 +19,7 @@ type MapCluster = {
  */
 declare const MapCluster: import("svelte").Component<{
     markers?: any[];
-    center?: any[];
+    center?: any;
     zoom?: number;
     distance?: number;
     tileSource?: Record<string, any>;
@@ -29,7 +29,7 @@ declare const MapCluster: import("svelte").Component<{
 } & Record<string, any>, {}, "">;
 type $$ComponentProps = {
     markers?: any[];
-    center?: any[];
+    center?: any;
     zoom?: number;
     distance?: number;
     tileSource?: Record<string, any>;

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} */
@@ -71,6 +77,9 @@
       ]);
       if (disposed) return;
 
+      const overlayLayers = await createOverlayLayers(layers, styles);
+      if (disposed) return;
+
       /** @type {Feature[]} */
       const features = [];
 
@@ -94,7 +103,7 @@
 
       map = new OlMap({
         target: container,
-        layers: [tileLayer, vectorLayer],
+        layers: [tileLayer, ...overlayLayers, vectorLayer],
         view: new View({
           center: fromLonLat(center),
           zoom,
@@ -105,6 +114,9 @@
       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/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,8 +59,24 @@
     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
+     *  address whenever the pin settles (search pick or reverse geocode of a
+     *  map click). Feed it to an address field; coords stay `onchange`. */
+    onaddress = undefined,
     /** @type {string} */
     height = '100%',
     /** @type {string | undefined} */
@@ -99,6 +124,7 @@
       _vectorSource.clear();
       _vectorSource.addFeature(new _Feature({ geometry: new _Point(fromLonLat([lon, lat])) }));
       value = [lon, lat];
+      checkBoundary([lon, lat]);
       onchange?.([lon, lat]);
     }
   }
@@ -108,6 +134,14 @@
     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);
+  }
+
   $effect(() => {
     if (!container || disabled) return;
 
@@ -144,6 +178,12 @@
       ]);
       if (disposed) return;
 
+      const [overlayLayers, boundaryLayer] = await Promise.all([
+        createOverlayLayers(layers, styles),
+        createBoundaryLayer(boundaryRings, container),
+      ]);
+      if (disposed) return;
+
       const vectorSource = new VectorSource();
       _vectorSource = vectorSource;
       _Feature = Feature;
@@ -187,6 +227,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];
@@ -199,7 +240,12 @@
 
       map = new OlMap({
         target: container,
-        layers: [tileLayer, vectorLayer],
+        layers: [
+          tileLayer,
+          ...overlayLayers,
+          ...(boundaryLayer ? [boundaryLayer] : []),
+          vectorLayer,
+        ],
         view: new View({
           center: initialCenter,
           zoom,
@@ -212,6 +258,7 @@
       disposeTheme = watchTheme(() => {
         styles.refresh();
         vectorSource.changed();
+        for (const l of overlayLayers) l.getSource()?.changed();
       });
     } catch (err) { renderMapError(container, 'MapPicker', /** @type {Error} */ (err)); } })();
 
@@ -234,6 +281,7 @@
       providerUrl={searchProviderUrl}
       viewbox={searchViewbox}
       onlocation={handleGeoLocation}
+      onresolved={onaddress}
       bind:coords={searchCoords}
       size="sm"
     />

package/components/MapPicker.svelte.d.ts

@@ -34,7 +34,11 @@ 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;
     id?: any;
     class?: string;
@@ -52,7 +56,11 @@ type $$ComponentProps = {
     searchProviderUrl?: any;
     searchViewbox?: any;
     tileSource?: Record<string, any>;
+    layers?: any[];
+    boundary?: any;
+    onoutofbounds?: any;
     onchange?: any;
+    onaddress?: any;
     height?: string;
     id?: any;
     class?: string;

package/components/action-form-renderer-payload.d.ts

@@ -39,10 +39,16 @@ export interface BuildArgs {
     sourceSchema: Record<string, unknown>;
     /** Submitted values keyed by parameter source_field_path or key. */
     rawValues: Record<string, unknown>;
+    /** Uploaded file storage keys (`file`-typed parameters) — the platform
+     *  attachment contract: a TOP-LEVEL `attachment_keys` sibling, never part
+     *  of raw_values (the form schema doesn't validate file params). */
+    attachmentKeys?: string[];
     schemaVersion: string | null;
     mode: RendererMode;
 }
 export interface ActionPayload {
+    /** Uploaded file storage keys (file-typed params) — absent when none. */
+    attachment_keys?: string[];
     source: string;
     action: {
         id: string | null;

package/components/action-form-renderer-payload.ts

@@ -42,11 +42,17 @@ export interface BuildArgs {
   sourceSchema: Record<string, unknown>;
   /** Submitted values keyed by parameter source_field_path or key. */
   rawValues: Record<string, unknown>;
+  /** Uploaded file storage keys (`file`-typed parameters) — the platform
+   *  attachment contract: a TOP-LEVEL `attachment_keys` sibling, never part
+   *  of raw_values (the form schema doesn't validate file params). */
+  attachmentKeys?: string[];
   schemaVersion: string | null;
   mode: RendererMode;
 }
 
 export interface ActionPayload {
+  /** Uploaded file storage keys (file-typed params) — absent when none. */
+  attachment_keys?: string[];
   source: string;
   action: {
     id: string | null;
@@ -102,7 +108,7 @@ function pickScope(targetConfig: Record<string, unknown>): Record<string, unknow
 }
 
 export function buildActionPayload(args: BuildArgs): ActionPayload {
-  const { action, placement, targetConfig, sourceSchema, rawValues, schemaVersion, mode } = args;
+  const { action, placement, targetConfig, sourceSchema, rawValues, schemaVersion, mode, attachmentKeys } = args;
 
   const sourceFromSchema = nullableString(sourceSchema.source);
   const targetModel =
@@ -143,6 +149,9 @@ export function buildActionPayload(args: BuildArgs): ActionPayload {
       target_model: targetModel,
       form_definition_id: nullableString(targetConfig.form_definition_id),
     },
+    ...(attachmentKeys && attachmentKeys.length > 0
+      ? { attachment_keys: attachmentKeys }
+      : {}),
   };
 }
 

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.15.0",
+  "version": "0.17.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",

package/tokens/components.css

@@ -514,7 +514,7 @@
      POPOVER
      ═══════════════════════════════════════════════ */
 
-  --popover-bg: var(--raw-color-white);
+  --popover-bg: var(--color-surface-raised);
   --popover-border: var(--elevation-border-strong);
   --popover-shadow: var(--elevation-overlay);
   --popover-radius: var(--radius-md);
@@ -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(

package/tokens/semantic.css

@@ -18,6 +18,9 @@
   --color-surface: var(--raw-color-neutral-50);
   --color-surface-secondary: var(--raw-color-neutral-100);
   --color-surface-tertiary: var(--raw-color-neutral-200);
+  /* Raised surface — popovers/menus that float ABOVE the page surface
+     (lighter than the page in light scheme, lighter-than-base in dark). */
+  --color-surface-raised: var(--raw-color-white);
   --color-overlay: rgba(44, 40, 37, 0.5);
 
   /* Borders */
@@ -216,6 +219,71 @@
   --content-padding-y: var(--space-lg);
 }
 
+/* ═══════════════════════════════════════════════
+   DARK SCHEME — `<html data-scheme="dark">`
+   ═══════════════════════════════════════════════
+
+   One generic layer over the NEUTRAL-derived roles (surfaces, borders,
+   text, overlay). Brand hues survive untouched — the accent stays the
+   theme's accent — while every `-subtle` wash is re-derived from its
+   live hue via color-mix, so a tenant theme's accent gets a correct
+   dark wash for free. Per-theme bespoke dark = a `[data-theme="x"]`
+   block in the theme file, not here.
+
+   Selector is `:root[data-scheme="dark"]` (0,1,1): it TIES tenant theme
+   blocks (`:root[data-theme="x"]`, runtime-injected in <head>) and wins
+   on order — DS styles load after the injected theme block. Consumers
+   resolving an "auto" preference must set the RESOLVED value on <html>
+   (a pre-paint `prefers-color-scheme` read), never "auto" itself. */
+
+:root[data-scheme="dark"] {
+  color-scheme: dark;
+
+  /* Surfaces — darkest at the base, lighter as elevation rises */
+  --color-surface: var(--raw-color-neutral-950);
+  --color-surface-secondary: var(--raw-color-neutral-900);
+  --color-surface-tertiary: var(--raw-color-neutral-800);
+  --color-surface-raised: var(--raw-color-neutral-900);
+  --color-overlay: rgba(0, 0, 0, 0.65);
+
+  /* Borders */
+  --color-border: var(--raw-color-neutral-800);
+  --color-border-strong: var(--raw-color-neutral-700);
+
+  /* Text — warm off-whites off the same neutral ramp */
+  --color-text: var(--raw-color-neutral-100);
+  --color-text-secondary: var(--raw-color-neutral-400);
+  --color-text-muted: var(--raw-color-neutral-500);
+
+  /* Subtle washes — derived from the LIVE hue (theme-set or default),
+     mixed into the dark surface instead of the light-only raw tints. */
+  --color-accent-subtle: color-mix(
+    in srgb,
+    var(--color-accent) 16%,
+    var(--raw-color-neutral-950)
+  );
+  --color-destructive-subtle: color-mix(
+    in srgb,
+    var(--color-destructive) 14%,
+    var(--raw-color-neutral-950)
+  );
+  --color-success-subtle: color-mix(
+    in srgb,
+    var(--color-success) 14%,
+    var(--raw-color-neutral-950)
+  );
+  --color-warning-subtle: color-mix(
+    in srgb,
+    var(--color-warning) 14%,
+    var(--raw-color-neutral-950)
+  );
+  --color-info-subtle: color-mix(
+    in srgb,
+    var(--color-info) 14%,
+    var(--raw-color-neutral-950)
+  );
+}
+
 /* ─── Tablet (768px+) ─── */
 @media (min-width: 768px) {
   :root {