@aiaiai-pt/design-system 0.10.1 → 0.14.0

package/components/ActionFormRenderer.svelte

@@ -2,10 +2,14 @@
   // DS-internal sibling imports (this component lives in the DS now, #73 73f —
   // converged so admin preview AND portal runtime mount the SAME renderer).
   import Badge from "./Badge.svelte";
+  import Button from "./Button.svelte";
+  import Alert from "./Alert.svelte";
   import CodeBlock from "./CodeBlock.svelte";
   import Input from "./Input.svelte";
+  import MapPicker from "./MapPicker.svelte";
   import Select from "./Select.svelte";
   import Tag from "./Tag.svelte";
+  import type { Snippet } from "svelte";
   import {
     buildActionPayload,
     placementConsequenceRows as buildPlacementConsequenceRows,
@@ -39,6 +43,15 @@
     criteria?: Entity[];
   };
 
+  /**
+   * The `apply` seam (see dev_docs/adl/action-form-apply-seam.md). The renderer
+   * owns the form + validation + submit button + state; the CONSUMER injects how
+   * to actually send it. Foundry's `applyAction` model: every consumer converges
+   * on the one action engine; only transport/auth/captcha differ. Receives the
+   * normalized ActionPayload; resolves `{ ok }` (and may navigate on success).
+   */
+  type ApplyResult = { ok: boolean; status?: number; error?: string };
+
   interface Props {
     action: Entity | null;
     placement?: Entity | null;
@@ -46,6 +59,13 @@
     criteria?: Entity[];
     mode?: RendererMode;
     schema?: ActionSchema | null;
+    /** 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>;
+    /** Environment-specific captcha (e.g. Turnstile), rendered above the button
+     *  in submit modes. */
+    captcha?: Snippet;
+    submitLabel?: string;
   }
 
   let {
@@ -55,10 +75,24 @@
     criteria = [],
     mode = "admin-preview",
     schema = null,
+    onApply = undefined,
+    captcha = undefined,
+    submitLabel = "Submit",
   }: Props = $props();
 
   let values = $state<Record<string, unknown>>({});
 
+  // Submit state (apply seam). Only meaningful in submit modes with an onApply.
+  let submitting = $state(false);
+  let submitError = $state<string | null>(null);
+  let submitted = $state(false);
+
+  // A form is a SUBMIT form (button shown) only in the submit modes AND when the
+  // consumer wired an apply. Preview modes (admin-preview/adapter-preview) and a
+  // missing onApply stay read-only — the button never renders.
+  const isSubmitMode = $derived(mode === "public-submit" || mode === "admin-execute");
+  const showSubmit = $derived(isSubmitMode && onApply !== undefined);
+
   const renderedAction = $derived((schema?.action as Entity | null | undefined) ?? action);
   const renderedPlacement = $derived((schema?.placement as Entity | null | undefined) ?? placement);
   const renderedParameters = $derived((schema?.parameters as Entity[] | undefined) ?? parameters);
@@ -80,6 +114,36 @@
   const sections = $derived(schemaSections ?? groupIntoSections(visibleParameters));
   const payload = $derived(buildPayload());
   const payloadJson = $derived(JSON.stringify(payload, null, 2));
+
+  // Client-side submit gate (layer 1 — see the ADL): every required, visible
+  // parameter must have a non-empty value. Server-side submission criteria are
+  // enforced by the BFF on submit and surfaced via `submitError`.
+  function isEmpty(value: unknown): boolean {
+    return value === undefined || value === null || value === "";
+  }
+  const canSubmit = $derived(
+    visibleParameters
+      .filter((parameter) => parameter.required)
+      .every((parameter) => !isEmpty(values[parameterKey(parameter)])),
+  );
+
+  async function handleSubmit(): Promise<void> {
+    if (!onApply || submitting || !canSubmit) return;
+    submitError = null;
+    submitting = true;
+    try {
+      const result = await onApply(buildPayload());
+      if (result.ok) {
+        submitted = true; // a consumer that navigates (portal → tracker) supersedes this
+      } else {
+        submitError = result.error ?? "We couldn't submit your form. Please try again.";
+      }
+    } catch {
+      submitError = "Something went wrong. Please try again.";
+    } finally {
+      submitting = false;
+    }
+  }
   const criteriaSummary = $derived(
     renderedCriteria
       .filter((criterion) => criterion.is_active !== false)
@@ -286,6 +350,23 @@
       ]}
       onchange={(value: string) => setValue(key, value === "true")}
     />
+  {: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. -->
+    <MapPicker
+      mode="point"
+      height="20rem"
+      label={String(parameter.label ?? key)}
+      center={Array.isArray(parameter.default_value)
+        ? (parameter.default_value as [number, number])
+        : undefined}
+      value={Array.isArray(values[key])
+        ? (values[key] as [number, number])
+        : undefined}
+      onchange={(coords: [number, number]) => setValue(key, coords)}
+    />
   {:else}
     <Input
       label={String(parameter.label ?? key)}
@@ -332,6 +413,31 @@
     </form>
   {/if}
 
+  <!-- Submit (apply seam) — only in submit modes with an injected onApply, so
+       preview modes never render a button. Captcha snippet sits above it. -->
+  {#if showSubmit && renderedAction && orderedParameters.length > 0}
+    <div class="submit-area">
+      {#if submitted}
+        <Alert variant="success">Your submission was received.</Alert>
+      {:else}
+        {#if submitError}
+          <Alert variant="error">{submitError}</Alert>
+        {/if}
+        {#if captcha}
+          <div class="submit-captcha">{@render captcha()}</div>
+        {/if}
+        <Button
+          variant="primary"
+          loading={submitting}
+          disabled={submitting || !canSubmit}
+          onclick={handleSubmit}
+        >
+          {submitLabel}
+        </Button>
+      {/if}
+    </div>
+  {/if}
+
   {#if mode === "admin-preview"}
     <div class="admin-preview">
       <section class="preview-block">
@@ -420,12 +526,22 @@
 
   .rendered-form,
   .admin-preview,
-  .preview-block {
+  .preview-block,
+  .submit-area {
     display: flex;
     flex-direction: column;
     gap: var(--space-md);
   }
 
+  .submit-area {
+    align-items: flex-start;
+    gap: var(--space-lg);
+  }
+
+  .submit-captcha {
+    min-height: var(--space-4xl);
+  }
+
   .preview-block h4 {
     margin: 0;
     font-size: var(--type-body-size);

package/components/ActionFormRenderer.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { Snippet } from "svelte";
 import { type RendererMode } from "./action-form-renderer-payload";
 /**
  * The renderer treats every parameter/action/placement as a loose record
@@ -22,6 +23,18 @@ type ActionSchema = {
     parameters?: Entity[];
     criteria?: Entity[];
 };
+/**
+ * The `apply` seam (see dev_docs/adl/action-form-apply-seam.md). The renderer
+ * owns the form + validation + submit button + state; the CONSUMER injects how
+ * to actually send it. Foundry's `applyAction` model: every consumer converges
+ * on the one action engine; only transport/auth/captcha differ. Receives the
+ * normalized ActionPayload; resolves `{ ok }` (and may navigate on success).
+ */
+type ApplyResult = {
+    ok: boolean;
+    status?: number;
+    error?: string;
+};
 interface Props {
     action: Entity | null;
     placement?: Entity | null;
@@ -29,6 +42,13 @@ interface Props {
     criteria?: Entity[];
     mode?: RendererMode;
     schema?: ActionSchema | null;
+    /** 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>;
+    /** Environment-specific captcha (e.g. Turnstile), rendered above the button
+     *  in submit modes. */
+    captcha?: Snippet;
+    submitLabel?: string;
 }
 declare const ActionFormRenderer: import("svelte").Component<Props, {}, "">;
 type ActionFormRenderer = ReturnType<typeof ActionFormRenderer>;

package/components/Breadcrumb.svelte.d.ts

@@ -1,7 +1,7 @@
 export default Breadcrumb;
 type Breadcrumb = {
-  $on?(type: string, callback: (e: any) => void): () => void;
-  $set?(props: Partial<$$ComponentProps>): void;
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
 };
 /**
  * Breadcrumb
@@ -22,17 +22,13 @@ type Breadcrumb = {
  *   max_items={4}
  * />
  */
-declare const Breadcrumb: import("svelte").Component<
-  {
+declare const Breadcrumb: import("svelte").Component<{
     items?: any[];
     max_items?: any;
     class?: string;
-  } & Record<string, any>,
-  {},
-  ""
->;
+} & Record<string, any>, {}, "">;
 type $$ComponentProps = {
-  items?: any[];
-  max_items?: any;
-  class?: string;
+    items?: any[];
+    max_items?: any;
+    class?: string;
 } & Record<string, any>;

package/components/Button.svelte.d.ts

@@ -1,7 +1,7 @@
 export default Button;
 type Button = {
-  $on?(type: string, callback: (e: any) => void): () => void;
-  $set?(props: Partial<$$ComponentProps>): void;
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
 };
 /**
  * Button
@@ -32,8 +32,7 @@ type Button = {
  *   {#snippet icon()}<PhGear size={16} />{/snippet}
  * </Button>
  */
-declare const Button: import("svelte").Component<
-  {
+declare const Button: import("svelte").Component<{
     variant?: string;
     size?: string;
     loading?: boolean;
@@ -41,24 +40,21 @@ declare const Button: import("svelte").Component<
     iconOnly?: boolean;
     type?: string;
     href?: any;
-    ref?: HTMLElement | undefined;
+    ref?: any;
     class?: string;
     icon?: any;
     children?: any;
-  } & Record<string, any>,
-  {},
-  "ref"
->;
+} & Record<string, any>, {}, "ref">;
 type $$ComponentProps = {
-  variant?: string;
-  size?: string;
-  loading?: boolean;
-  disabled?: boolean;
-  iconOnly?: boolean;
-  type?: string;
-  href?: any;
-  ref?: HTMLElement | undefined;
-  class?: string;
-  icon?: any;
-  children?: any;
+    variant?: string;
+    size?: string;
+    loading?: boolean;
+    disabled?: boolean;
+    iconOnly?: boolean;
+    type?: string;
+    href?: any;
+    ref?: any;
+    class?: string;
+    icon?: any;
+    children?: any;
 } & Record<string, any>;

package/components/Card.svelte

@@ -14,6 +14,11 @@
   <Card interactive selected={isSelected} onclick={() => select(id)}>
     Clickable card
   </Card>
+
+  @example Link card (navigation — renders an <a>, like Button's href)
+  <Card href="/submit/potholes">
+    Report a pothole
+  </Card>
 -->
 <script>
   /**
@@ -27,17 +32,26 @@
     interactive = false,
     /** @type {boolean} */
     selected = false,
+    /** @type {string | undefined} — renders an <a> when set (navigation card) */
+    href = undefined,
     /** @type {string} */
     class: className = '',
     /** @type {import('svelte').Snippet | undefined} */
     children = undefined,
     ...rest
   } = $props();
-
-  // tag variable unused — rendering uses {#if interactive} branching
 </script>
 
-{#if interactive}
+{#if href}
+  <a
+    {href}
+    class="card card-{variant} card-interactive card-link {className}"
+    class:card-selected={selected}
+    {...rest}
+  >
+    {#if children}{@render children()}{/if}
+  </a>
+{:else if interactive}
   <button
     class="card card-{variant} card-interactive {className}"
     class:card-selected={selected}
@@ -102,6 +116,12 @@
     outline-offset: var(--focus-ring-offset);
   }
 
+  /* Anchor reset — a link card reads as a card, not as link text. */
+  .card-link {
+    text-decoration: none;
+    color: inherit;
+  }
+
   .card-selected {
     border-color: var(--card-selected-border-color);
   }

package/components/Card.svelte.d.ts

@@ -19,11 +19,17 @@ type Card = {
  * <Card interactive selected={isSelected} onclick={() => select(id)}>
  *   Clickable card
  * </Card>
+ *
+ * @example Link card (navigation — renders an <a>, like Button's href)
+ * <Card href="/submit/potholes">
+ *   Report a pothole
+ * </Card>
  */
 declare const Card: import("svelte").Component<{
     variant?: string;
     interactive?: boolean;
     selected?: boolean;
+    href?: any;
     class?: string;
     children?: any;
 } & Record<string, any>, {}, "">;
@@ -31,6 +37,7 @@ type $$ComponentProps = {
     variant?: string;
     interactive?: boolean;
     selected?: boolean;
+    href?: any;
     class?: string;
     children?: any;
 } & Record<string, any>;

package/components/Combobox.svelte.d.ts

@@ -1,13 +1,13 @@
 export default Combobox;
 export type ComboboxItem = {
-  value: string;
-  label: string;
-  group?: string;
-  description?: string;
+    value: string;
+    label: string;
+    group?: string;
+    description?: string;
 };
 type Combobox = {
-  $on?(type: string, callback: (e: any) => void): () => void;
-  $set?(props: Partial<$$ComponentProps>): void;
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
 };
 /**
  * Combobox
@@ -34,8 +34,7 @@ type Combobox = {
  *   bind:value={selected}
  * />
  */
-declare const Combobox: import("svelte").Component<
-  {
+declare const Combobox: import("svelte").Component<{
     items?: any[];
     value?: string;
     label?: any;
@@ -45,26 +44,21 @@ declare const Combobox: import("svelte").Component<
     help?: any;
     size?: string;
     onchange?: any;
-    /** Async search callback; when set, disables internal filtering. Parent must update `items` with results. */
-    onsearch?: (query: string) => void;
-    /** Show "Searching…" in dropdown while loading async results */
+    onsearch?: any;
     loading?: boolean;
     class?: string;
-  } & Record<string, any>,
-  {},
-  "value"
->;
+} & Record<string, any>, {}, "value">;
 type $$ComponentProps = {
-  items?: any[];
-  value?: string;
-  label?: any;
-  placeholder?: string;
-  disabled?: boolean;
-  error?: any;
-  help?: any;
-  size?: string;
-  onchange?: any;
-  onsearch?: (query: string) => void;
-  loading?: boolean;
-  class?: string;
+    items?: any[];
+    value?: string;
+    label?: any;
+    placeholder?: string;
+    disabled?: boolean;
+    error?: any;
+    help?: any;
+    size?: string;
+    onchange?: any;
+    onsearch?: any;
+    loading?: boolean;
+    class?: string;
 } & Record<string, any>;

package/components/DataTable.svelte.d.ts

@@ -1,7 +1,14 @@
 export default DataTable;
+export type ColumnDef = {
+    key: string;
+    label: string;
+    width?: string;
+    sortable?: boolean;
+    render?: (value: unknown, row: Record<string, unknown>) => string;
+};
 type DataTable = {
-  $on?(type: string, callback: (e: any) => void): () => void;
-  $set?(props: Partial<$$ComponentProps>): void;
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
 };
 /**
  * DataTable
@@ -32,9 +39,30 @@ type DataTable = {
  *
  * @example Loading
  * <DataTable {columns} rows={[]} loading />
+ *
+ * @example Responsive (default)
+ * Tables card-stack below `card_breakpoint` (default 768px) so columns
+ * don't scroll off-screen on phones/tablets. The first column becomes the
+ * card title; the rest render as label:value rows. Opt out with
+ * `responsive={false}`, or raise the breakpoint for wide tables.
+ * <DataTable {columns} {rows} card_breakpoint={1024} />
+ *
+ * @example Custom cell rendering (badges, chips, components)
+ * Pass a `cell` snippet to override the default per-cell text rendering.
+ * The default behavior (using `column.render` to produce a string) is
+ * preserved when no `cell` snippet is provided.
+ *
+ * <DataTable {columns} {rows}>
+ *   {#snippet cell({ row, column, value })}
+ *     {#if column.key === 'status'}
+ *       <Badge variant={statusVariant(value)}>{value}</Badge>
+ *     {:else}
+ *       {value ?? '-'}
+ *     {/if}
+ *   {/snippet}
+ * </DataTable>
  */
-declare const DataTable: import("svelte").Component<
-  {
+declare const DataTable: import("svelte").Component<{
     columns?: any[];
     rows?: any[];
     loading?: boolean;
@@ -42,7 +70,7 @@ declare const DataTable: import("svelte").Component<
     sort_key?: any;
     sort_direction?: string;
     selectable?: boolean;
-    selected_rows?: Set<string>;
+    selected_rows?: any;
     row_key?: string;
     responsive?: boolean;
     card_breakpoint?: number;
@@ -51,27 +79,28 @@ declare const DataTable: import("svelte").Component<
     on_sort?: any;
     on_select?: any;
     on_row_click?: any;
+    cell?: any;
     children?: any;
     class?: string;
-  } & Record<string, any>,
-  {},
-  "selected_rows"
->;
+} & Record<string, any>, {}, "selected_rows">;
 type $$ComponentProps = {
-  columns?: any[];
-  rows?: any[];
-  loading?: boolean;
-  sortable?: boolean;
-  sort_key?: any;
-  sort_direction?: string;
-  selectable?: boolean;
-  selected_rows?: Set<string>;
-  row_key?: string;
-  empty_heading?: string;
-  empty_body?: string;
-  on_sort?: any;
-  on_select?: any;
-  on_row_click?: any;
-  children?: any;
-  class?: string;
+    columns?: any[];
+    rows?: any[];
+    loading?: boolean;
+    sortable?: boolean;
+    sort_key?: any;
+    sort_direction?: string;
+    selectable?: boolean;
+    selected_rows?: any;
+    row_key?: string;
+    responsive?: boolean;
+    card_breakpoint?: number;
+    empty_heading?: string;
+    empty_body?: string;
+    on_sort?: any;
+    on_select?: any;
+    on_row_click?: any;
+    cell?: any;
+    children?: any;
+    class?: string;
 } & Record<string, any>;

package/components/DateRangePicker.svelte.d.ts

@@ -6,9 +6,10 @@ type DateRangePicker = {
 /**
  * DateRangePicker
  *
- * Start/end date pair for filters and ranges. Two coordinated DatePickers
- * where start constrains end and vice versa.
- * Consumes --datepicker-* and --input-* tokens from components.css.
+ * Integrated calendar for selecting a date range. Single calendar with
+ * two-phase selection: click start → hover preview → click end.
+ * Range highlighted between start and end dates.
+ * Consumes --datepicker-* tokens from components.css.
  *
  * @example Basic
  * <DateRangePicker label="PERIOD" bind:start bind:end />
@@ -32,8 +33,9 @@ declare const DateRangePicker: import("svelte").Component<{
     displayFormat?: string;
     locale?: typeof enUS;
     onchange?: any;
+    id?: any;
     class?: string;
-} & Record<string, any>, {}, "start" | "end">;
+} & Record<string, any>, {}, "end" | "start">;
 type $$ComponentProps = {
     start?: any;
     end?: any;
@@ -50,6 +52,7 @@ type $$ComponentProps = {
     displayFormat?: string;
     locale?: typeof enUS;
     onchange?: any;
+    id?: any;
     class?: string;
 } & Record<string, any>;
 import { enUS } from 'date-fns/locale';

package/components/DateTimePicker.svelte.d.ts

@@ -6,7 +6,7 @@ type DateTimePicker = {
 /**
  * DateTimePicker
  *
- * Date + time selection. Composes DatePicker with a time input.
+ * Date + time selection. Composes DatePicker with styled hour/minute selects.
  * Values displayed in Berkeley Mono (data font).
  * Consumes --datepicker-* and --input-* tokens from components.css.
  *

package/components/FilterPanel.svelte.d.ts

@@ -1,23 +1,20 @@
 export default FilterPanel;
 export type FilterOption = {
-  value: string;
-  label: string;
+    value: string;
+    label: string;
 };
 export type FilterFieldDef = {
-  key: string;
-  label: string;
-  type: "select" | "boolean" | "search";
-  options?: FilterOption[];
-  /** Async search callback for 'search' type filters (FK relationships) */
-  onsearch?: (query: string) => void;
-  /** Items for 'search' type, managed by parent */
-  searchItems?: FilterOption[];
-  /** Loading state for 'search' type */
-  searchLoading?: boolean;
+    key: string;
+    label: string;
+    type: "select" | "boolean" | "search";
+    options?: FilterOption[];
+    onsearch?: (query: string) => void;
+    searchItems?: FilterOption[];
+    searchLoading?: boolean;
 };
 type FilterPanel = {
-  $on?(type: string, callback: (e: any) => void): () => void;
-  $set?(props: Partial<$$ComponentProps>): void;
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
 };
 /**
  * FilterPanel
@@ -26,6 +23,8 @@ type FilterPanel = {
  * Each filter renders as the appropriate widget based on its type:
  * select → Select dropdown, boolean → Toggle pair, search → Combobox.
  *
+ * Consumes --filter-chip-*, --filter-bar-clear-*, and --input-* tokens from components.css.
+ *
  * @example
  * <FilterPanel
  *   filters={[
@@ -39,21 +38,17 @@ type FilterPanel = {
  *   onchange={handleFilterChange}
  * />
  */
-declare const FilterPanel: import("svelte").Component<
-  {
-    filters?: FilterFieldDef[];
+declare const FilterPanel: import("svelte").Component<{
+    filters?: any[];
     value?: Record<string, any>;
-    onchange?: (value: Record<string, any>) => void;
-    onclear?: () => void;
+    onchange?: any;
+    onclear?: any;
     class?: string;
-  } & Record<string, any>,
-  {},
-  "value"
->;
+} & Record<string, any>, {}, "value">;
 type $$ComponentProps = {
-  filters?: FilterFieldDef[];
-  value?: Record<string, any>;
-  onchange?: (value: Record<string, any>) => void;
-  onclear?: () => void;
-  class?: string;
+    filters?: any[];
+    value?: Record<string, any>;
+    onchange?: any;
+    onclear?: any;
+    class?: string;
 } & Record<string, any>;

package/components/GeoSearch.svelte.d.ts

@@ -6,25 +6,23 @@ type GeoSearch = {
 /**
  * GeoSearch
  *
- * Geocoding search input powered by Nominatim (OpenStreetMap).
- * Wraps Combobox with built-in address/place search and debounced API calls.
- * Emits lon/lat coordinates when a result is selected.
+ * Bidirectional geocoding input powered by Nominatim (OpenStreetMap).
+ * Forward: type address → get coordinates.
+ * Reverse: set `coords` prop → shows resolved address.
  * Consumes --combobox-* tokens from components.css.
  *
- * @example Basic
+ * @example Forward geocoding
  * <GeoSearch onlocation={(lon, lat) => console.log(lon, lat)} />
  *
- * @example With label and bounding box bias
+ * @example Bidirectional (MapPicker sets coords on click → address shows)
  * <GeoSearch
- *   label="Search location"
- *   placeholder="City, address, or place..."
- *   viewbox={[-9.5, 38.5, -8.8, 39.0]}
- *   onlocation={(lon, lat) => { mapCenter = [lon, lat]; mapZoom = 15; }}
+ *   bind:coords={pickedCoords}
+ *   onlocation={(lon, lat) => { mapCenter = [lon, lat]; }}
  * />
  *
- * @example Custom provider URL
+ * @example With viewbox bias
  * <GeoSearch
- *   providerUrl="https://my-nominatim.example.com/search"
+ *   viewbox={[-9.5, 38.5, -8.8, 39.0]}
  *   onlocation={(lon, lat) => console.log(lon, lat)}
  * />
  */
@@ -38,8 +36,9 @@ declare const GeoSearch: import("svelte").Component<{
     providerUrl?: string;
     viewbox?: any;
     onlocation?: any;
+    coords?: any;
     class?: string;
-} & Record<string, any>, {}, "">;
+} & Record<string, any>, {}, "coords">;
 type $$ComponentProps = {
     label?: any;
     placeholder?: string;
@@ -50,5 +49,6 @@ type $$ComponentProps = {
     providerUrl?: string;
     viewbox?: any;
     onlocation?: any;
+    coords?: any;
     class?: string;
 } & Record<string, any>;

package/components/Hero.svelte

@@ -13,6 +13,9 @@
 
   @example Custom heading level (when the hero is not the page's H1)
   <Hero title="Latest consultations" headingLevel={2} />
+
+  @example Background image (a theme-tinted scrim keeps text contrast)
+  <Hero title="Report a problem" image="/images/city.jpg" />
 -->
 <script>
   let {
@@ -22,6 +25,9 @@
     subtitle = "",
     /** @type {1 | 2 | 3} Heading level for `title` — keep one h1 per page. */
     headingLevel = 1,
+    /** @type {string | undefined} Background image URL — rendered cover/center
+     *  under a `--hero-scrim` overlay so the text tokens keep contrast. */
+    image = undefined,
     /** @type {string} */
     class: className = "",
     /** @type {import('svelte').Snippet | undefined} Title override (rich content). */
@@ -30,9 +36,21 @@
     actions = undefined,
     ...rest
   } = $props();
+
+  // CSS-string escape for the url() value — the image URL is operator data.
+  const bgStyle = $derived(
+    image
+      ? `background-image: url('${image.replace(/\\/g, "%5C").replace(/'/g, "%27")}')`
+      : undefined,
+  );
 </script>
 
-<section class="hero {className}" {...rest}>
+<section
+  class="hero {className}"
+  class:hero-has-image={!!image}
+  style={bgStyle}
+  {...rest}
+>
   <div class="hero-inner">
     {#if children}
       {@render children()}
@@ -53,6 +71,24 @@
     background: var(--color-surface);
   }
 
+  .hero-has-image {
+    position: relative;
+    background-size: cover;
+    background-position: center;
+  }
+
+  /* Theme-tinted scrim between the image and the text (contrast guard). */
+  .hero-has-image::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    background: var(--hero-scrim);
+  }
+
+  .hero-has-image .hero-inner {
+    position: relative;
+  }
+
   .hero-inner {
     width: 100%;
     max-width: var(--content-width-wide);

package/components/Hero.svelte.d.ts

@@ -18,11 +18,15 @@ type Hero = {
  *
  * @example Custom heading level (when the hero is not the page's H1)
  * <Hero title="Latest consultations" headingLevel={2} />
+ *
+ * @example Background image (a theme-tinted scrim keeps text contrast)
+ * <Hero title="Report a problem" image="/images/city.jpg" />
  */
 declare const Hero: import("svelte").Component<{
     title?: string;
     subtitle?: string;
     headingLevel?: number;
+    image?: any;
     class?: string;
     children?: any;
     actions?: any;
@@ -31,6 +35,7 @@ type $$ComponentProps = {
     title?: string;
     subtitle?: string;
     headingLevel?: number;
+    image?: any;
     class?: string;
     children?: any;
     actions?: any;

package/components/MapPicker.svelte.d.ts

@@ -9,11 +9,15 @@ type MapPicker = {
  * Interactive map for selecting a point or drawing a polygon.
  * OpenLayers with configurable tiles and Draw interaction.
  * Draw sketch styled with DS tokens (not OL blue default).
+ * Built-in GeoSearch (Nominatim) for address lookup + pan.
  * Consumes --map-* tokens from components.css.
  *
- * @example Point selection
+ * @example Point selection with search
  * <MapPicker mode="point" onchange={(coords) => console.log(coords)} />
  *
+ * @example Without search
+ * <MapPicker mode="point" search={false} onchange={(coords) => console.log(coords)} />
+ *
  * @example Polygon drawing
  * <MapPicker mode="polygon" onchange={(coords) => console.log(coords)} />
  */
@@ -26,6 +30,9 @@ declare const MapPicker: import("svelte").Component<{
     help?: any;
     error?: any;
     disabled?: boolean;
+    search?: boolean;
+    searchProviderUrl?: any;
+    searchViewbox?: any;
     tileSource?: Record<string, any>;
     onchange?: any;
     height?: string;
@@ -41,6 +48,9 @@ type $$ComponentProps = {
     help?: any;
     error?: any;
     disabled?: boolean;
+    search?: boolean;
+    searchProviderUrl?: any;
+    searchViewbox?: any;
     tileSource?: Record<string, any>;
     onchange?: any;
     height?: string;

package/components/Pagination.svelte.d.ts

@@ -1,13 +1,14 @@
 export default Pagination;
 type Pagination = {
-  $on?(type: string, callback: (e: any) => void): () => void;
-  $set?(props: Partial<$$ComponentProps>): void;
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
 };
 /**
  * Pagination
  *
  * Cursor-based and offset-based pagination with page size selector.
- * Consumes --pagination-* tokens (falls back to semantic tokens).
+ * Self-contained nav controls with correct icon placement (chevron
+ * leading for PREV, trailing for NEXT).
  *
  * @example Cursor mode (default)
  * <Pagination
@@ -30,8 +31,7 @@ type Pagination = {
  *   on_page_size_change={(s) => setSize(s)}
  * />
  */
-declare const Pagination: import("svelte").Component<
-  {
+declare const Pagination: import("svelte").Component<{
     mode?: string;
     has_next?: boolean;
     has_prev?: boolean;
@@ -42,25 +42,22 @@ declare const Pagination: import("svelte").Component<
     total_items?: any;
     on_page_change?: any;
     page_size?: number;
-    page_sizes?: number[];
+    page_sizes?: any;
     on_page_size_change?: any;
     class?: string;
-  } & Record<string, any>,
-  {},
-  ""
->;
+} & Record<string, any>, {}, "">;
 type $$ComponentProps = {
-  mode?: string;
-  has_next?: boolean;
-  has_prev?: boolean;
-  on_next?: any;
-  on_prev?: any;
-  current_page?: number;
-  total_pages?: any;
-  total_items?: any;
-  on_page_change?: any;
-  page_size?: number;
-  page_sizes?: number[];
-  on_page_size_change?: any;
-  class?: string;
+    mode?: string;
+    has_next?: boolean;
+    has_prev?: boolean;
+    on_next?: any;
+    on_prev?: any;
+    current_page?: number;
+    total_pages?: any;
+    total_items?: any;
+    on_page_change?: any;
+    page_size?: number;
+    page_sizes?: any;
+    on_page_size_change?: any;
+    class?: string;
 } & Record<string, any>;

package/components/SiteHeader.svelte.d.ts

@@ -16,7 +16,7 @@ type SiteHeader = {
  * @example
  * <SiteHeader>
  *   {#snippet brand()}<a href="/"><Logo /> Valongo</a>{/snippet}
- *   {#snippet nav()}<a href="/report">Report</a><a href="/info/privacy">Privacy</a>{/snippet}
+ *   {#snippet nav()}<ServiceNavigation items={navItems} />{/snippet}
  *   {#snippet actions()}<LocaleSwitch /> <Button>Sign in</Button>{/snippet}
  * </SiteHeader>
  */

package/components/ValueSourcePicker.svelte.d.ts

@@ -82,6 +82,7 @@ declare const ValueSourcePicker: import("svelte").Component<{
     value?: any;
     onchange?: any;
     allowed?: any[];
+    defaultMode?: any;
     context?: Record<string, any>;
     expectedType?: any;
     label?: any;
@@ -95,6 +96,7 @@ type $$ComponentProps = {
     value?: any;
     onchange?: any;
     allowed?: any[];
+    defaultMode?: any;
     context?: Record<string, any>;
     expectedType?: any;
     label?: any;

package/components/index.d.ts

@@ -17,6 +17,17 @@ export { default as Progress } from "./Progress.svelte";
 export { default as List } from "./List.svelte";
 export { default as ListItem } from "./ListItem.svelte";
 export { default as PageContainer } from "./PageContainer.svelte";
+export { default as AppFrame } from "./AppFrame.svelte";
+export { default as SiteHeader } from "./SiteHeader.svelte";
+export { default as SiteFooter } from "./SiteFooter.svelte";
+export { default as SkipLink } from "./SkipLink.svelte";
+export { default as ServiceNavigation } from "./ServiceNavigation.svelte";
+export { default as Link } from "./Link.svelte";
+export { default as Hero } from "./Hero.svelte";
+export { default as ContentBlock } from "./ContentBlock.svelte";
+export { default as StatusTimeline } from "./StatusTimeline.svelte";
+export { default as WidgetGrid } from "./WidgetGrid.svelte";
+export { default as VotingWidget } from "./VotingWidget.svelte";
 export { default as Card } from "./Card.svelte";
 export { default as Panel } from "./Panel.svelte";
 export { default as Modal } from "./Modal.svelte";
@@ -25,8 +36,12 @@ export { default as Menu } from "./Menu.svelte";
 export { default as MenuItem } from "./MenuItem.svelte";
 export { default as MenuSeparator } from "./MenuSeparator.svelte";
 export { default as Combobox } from "./Combobox.svelte";
+export { default as DatePicker } from "./DatePicker.svelte";
+export { default as DateTimePicker } from "./DateTimePicker.svelte";
+export { default as DateRangePicker } from "./DateRangePicker.svelte";
 export { default as SearchInput } from "./SearchInput.svelte";
 export { default as FilterBar } from "./FilterBar.svelte";
+export { default as FilterPanel } from "./FilterPanel.svelte";
 export { default as CommandPalette } from "./CommandPalette.svelte";
 export { default as Tabs } from "./Tabs.svelte";
 export { default as TabList } from "./TabList.svelte";
@@ -34,26 +49,27 @@ export { default as Tab } from "./Tab.svelte";
 export { default as TabPanel } from "./TabPanel.svelte";
 export { default as Alert } from "./Alert.svelte";
 export { default as Toast } from "./Toast.svelte";
+export { default as ToastManager } from "./ToastManager.svelte";
 export { default as EmptyState } from "./EmptyState.svelte";
+export { default as NotificationBell } from "./NotificationBell.svelte";
 export { default as Sidebar } from "./Sidebar.svelte";
 export { default as SidebarItem } from "./SidebarItem.svelte";
 export { default as SidebarSection } from "./SidebarSection.svelte";
 export { default as BottomNav } from "./BottomNav.svelte";
 export { default as BottomNavItem } from "./BottomNavItem.svelte";
 export { default as Stepper } from "./Stepper.svelte";
+export { default as ValueSourcePicker } from "./ValueSourcePicker.svelte";
 export { default as CodeBlock } from "./CodeBlock.svelte";
 export { default as CodeEditor } from "./CodeEditor.svelte";
 export { default as CollapsibleSection } from "./CollapsibleSection.svelte";
 export { default as OptionGrid } from "./OptionGrid.svelte";
 export { default as ConditionTable } from "./ConditionTable.svelte";
 export { default as LogViewer } from "./LogViewer.svelte";
+export { default as Tree } from "./Tree.svelte";
+export { default as TreeNode } from "./TreeNode.svelte";
 export { default as DataTable } from "./DataTable.svelte";
 export { default as Pagination } from "./Pagination.svelte";
 export { default as Breadcrumb } from "./Breadcrumb.svelte";
-export { default as DatePicker } from "./DatePicker.svelte";
-export { default as DateTimePicker } from "./DateTimePicker.svelte";
-export { default as DateRangePicker } from "./DateRangePicker.svelte";
-export { default as FilterPanel } from "./FilterPanel.svelte";
 export { default as StatCard } from "./StatCard.svelte";
 export { default as StatGrid } from "./StatGrid.svelte";
 export { default as MapDisplay } from "./MapDisplay.svelte";
@@ -61,4 +77,7 @@ export { default as MapPicker } from "./MapPicker.svelte";
 export { default as MapCluster } from "./MapCluster.svelte";
 export { default as MapHeatmap } from "./MapHeatmap.svelte";
 export { default as MapPopup } from "./MapPopup.svelte";
+export { default as GeoSearch } from "./GeoSearch.svelte";
 export { default as Calendar } from "./Calendar.svelte";
+export { default as ActionFormRenderer } from "./ActionFormRenderer.svelte";
+export { serializeValueSource, parseValueSource } from "./ValueSourcePicker.helpers.js";

package/package.json

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

package/tokens/components.css

@@ -111,6 +111,15 @@
   --checkbox-bg-checked: var(--color-accent);
   --checkbox-check-color: var(--color-text-on-accent);
 
+  /* ═══════════════════════════════════════════════
+     HERO
+     ═══════════════════════════════════════════════ */
+
+  /* Scrim laid over a hero background image so the text tokens keep their
+     contrast on any photo. Surface-tinted (not black/white) so it follows
+     the theme — raise the mix % for busier imagery. */
+  --hero-scrim: color-mix(in srgb, var(--color-surface) 78%, transparent);
+
   /* ═══════════════════════════════════════════════
      CARD
      ═══════════════════════════════════════════════ */