@aiaiai-pt/design-system 0.10.0 → 0.12.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)}
@@ -294,20 +375,31 @@
       oninput={(event: Event) => setValue(key, (event.target as HTMLInputElement).value)}
     />
   {/if}
-  <p class="field-meta">
-    {String(parameter.required ? "Required" : "Optional")} / {type}
-  </p>
+  {#if mode === "public-submit"}
+    <!-- Citizen-facing: just a quiet required hint, no operator type debug. -->
+    {#if parameter.required}<p class="field-meta">Required</p>{/if}
+  {:else}
+    <p class="field-meta">
+      {String(parameter.required ? "Required" : "Optional")} / {type}
+    </p>
+  {/if}
 {/snippet}
 
 <div class="renderer" data-testid={`action-form-renderer-${mode}`} data-layout={resolvedLayout.key}>
   <div class="renderer-header">
     <div>
-      <p class="eyebrow">{mode === "public-submit" ? "Public portal" : "Placement preview"}</p>
+      <!-- The placement-preview eyebrow + surface badge are operator chrome —
+           hidden in public-submit so a citizen sees a clean form title. -->
+      {#if mode !== "public-submit"}
+        <p class="eyebrow">Placement preview</p>
+      {/if}
       <h3>{String(renderedAction?.label ?? renderedAction?.key ?? "Select an action")}</h3>
     </div>
-    <Badge variant={renderedPlacement ? "info" : "neutral"}>
-      {String(renderedPlacement?.surface ?? "No placement")}
-    </Badge>
+    {#if mode !== "public-submit"}
+      <Badge variant={renderedPlacement ? "info" : "neutral"}>
+        {String(renderedPlacement?.surface ?? "No placement")}
+      </Badge>
+    {/if}
   </div>
 
   {#if !renderedAction}
@@ -321,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">
@@ -409,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/package.json

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