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

@@ -52,6 +52,10 @@
     tileSource = { type: 'osm' },
     /** @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} */
@@ -234,6 +238,7 @@
       providerUrl={searchProviderUrl}
       viewbox={searchViewbox}
       onlocation={handleGeoLocation}
+      onresolved={onaddress}
       bind:coords={searchCoords}
       size="sm"
     />

package/components/MapPicker.svelte.d.ts

@@ -35,6 +35,7 @@ declare const MapPicker: import("svelte").Component<{
     searchViewbox?: any;
     tileSource?: Record<string, any>;
     onchange?: any;
+    onaddress?: any;
     height?: string;
     id?: any;
     class?: string;
@@ -53,6 +54,7 @@ type $$ComponentProps = {
     searchViewbox?: any;
     tileSource?: Record<string, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.15.0",
+  "version": "0.16.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);

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 {