@aiaiai-pt/design-system 0.24.0 → 0.26.0

package/components/ActionFormRenderer.svelte

@@ -85,6 +85,22 @@
     /** Inline error rendered by the geo MapPicker(s) (e.g. the consumer's
      *  out-of-bounds copy) — forwarded as MapPicker's `error`. */
     geoError?: string;
+    /** Service-flow wizard (#105 P6): render ONLY the section whose
+     *  name (its label, falling back to its key) matches — one screen per
+     *  step. The value bag still spans ALL parameters (so answers persist
+     *  across steps and the final payload is complete); only the DISPLAY is
+     *  scoped. Null (default) renders every section, byte-identical to today. */
+    activeSectionKey?: string | null;
+    /** Service-flow wizard (#105 P6): suppress the renderer's own submit
+     *  button / captcha / error — the wizard shell owns the nav and posts the
+     *  payload once at the end. Default false (the standalone form keeps its
+     *  button). */
+    hideSubmit?: boolean;
+    /** Service-flow wizard (#105 P6): fires with the freshly built payload
+     *  whenever a value or attachment changes, so the wizard always holds the
+     *  complete payload (incl. attachment_keys) to review and submit. Read-only
+     *  consumers omit it. */
+    onchange?: (payload: Record<string, unknown>) => void;
   }
 
   let {
@@ -102,6 +118,9 @@
     layers = [],
     onoutofbounds = undefined,
     geoError = undefined,
+    activeSectionKey = null,
+    hideSubmit = false,
+    onchange = undefined,
   }: Props = $props();
 
   let values = $state<Record<string, unknown>>({});
@@ -125,7 +144,9 @@
   // 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);
+  // The wizard (#105 P6) suppresses the internal button via hideSubmit — it
+  // owns the nav and posts once at the end.
+  const showSubmit = $derived(isSubmitMode && onApply !== undefined && !hideSubmit);
 
   const renderedAction = $derived((schema?.action as Entity | null | undefined) ?? action);
   const renderedPlacement = $derived((schema?.placement as Entity | null | undefined) ?? placement);
@@ -146,9 +167,23 @@
   );
   const schemaSections = $derived(schemaSectionsFromContract());
   const sections = $derived(schemaSections ?? groupIntoSections(visibleParameters));
+  // Wizard pagination (#105 P6): when a section is active, render only it. The
+  // value bag is unaffected — every parameter is still seeded and submitted.
+  const displaySections = $derived(
+    activeSectionKey == null
+      ? sections
+      : sections.filter((section) => section.name === activeSectionKey),
+  );
   const payload = $derived(buildPayload());
   const payloadJson = $derived(JSON.stringify(payload, null, 2));
 
+  // Wizard (#105 P6): surface the live payload so the shell can review + submit
+  // it. Reading `payload` registers the dependency; the effect re-runs whenever
+  // a value or attachment changes.
+  $effect(() => {
+    onchange?.(payload);
+  });
+
   // 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`.
@@ -520,21 +555,26 @@
 {/snippet}
 
 <div class="renderer" data-testid={`action-form-renderer-${mode}`} data-layout={resolvedLayout.key}>
-  <div class="renderer-header">
-    <div>
-      <!-- The placement-preview eyebrow + surface badge are operator chrome —
-           hidden in public-submit so a citizen sees a clean form title. -->
+  <!-- Wizard pagination (#105 P6): the ServiceFlow shell owns the step
+       heading, so the renderer's own action-title header is suppressed when a
+       section is active to avoid a duplicate heading per step. -->
+  {#if activeSectionKey == null}
+    <div class="renderer-header">
+      <div>
+        <!-- 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>
       {#if mode !== "public-submit"}
-        <p class="eyebrow">Placement preview</p>
+        <Badge variant={renderedPlacement ? "info" : "neutral"}>
+          {String(renderedPlacement?.surface ?? "No placement")}
+        </Badge>
       {/if}
-      <h3>{String(renderedAction?.label ?? renderedAction?.key ?? "Select an action")}</h3>
     </div>
-    {#if mode !== "public-submit"}
-      <Badge variant={renderedPlacement ? "info" : "neutral"}>
-        {String(renderedPlacement?.surface ?? "No placement")}
-      </Badge>
-    {/if}
-  </div>
+  {/if}
 
   {#if !renderedAction}
     <p class="muted">Select an action to preview its placement-aware form contract.</p>
@@ -550,7 +590,7 @@
         renderedAction?.label ?? renderedAction?.key ?? "Form",
       )}
     >
-      <Layout {sections} field={fieldRow} />
+      <Layout sections={displaySections} field={fieldRow} />
     </form>
   {/if}
 

package/components/ActionFormRenderer.svelte.d.ts

@@ -70,6 +70,22 @@ interface Props {
     /** Inline error rendered by the geo MapPicker(s) (e.g. the consumer's
      *  out-of-bounds copy) — forwarded as MapPicker's `error`. */
     geoError?: string;
+    /** Service-flow wizard (#105 P6): render ONLY the section whose
+     *  name (its label, falling back to its key) matches — one screen per
+     *  step. The value bag still spans ALL parameters (so answers persist
+     *  across steps and the final payload is complete); only the DISPLAY is
+     *  scoped. Null (default) renders every section, byte-identical to today. */
+    activeSectionKey?: string | null;
+    /** Service-flow wizard (#105 P6): suppress the renderer's own submit
+     *  button / captcha / error — the wizard shell owns the nav and posts the
+     *  payload once at the end. Default false (the standalone form keeps its
+     *  button). */
+    hideSubmit?: boolean;
+    /** Service-flow wizard (#105 P6): fires with the freshly built payload
+     *  whenever a value or attachment changes, so the wizard always holds the
+     *  complete payload (incl. attachment_keys) to review and submit. Read-only
+     *  consumers omit it. */
+    onchange?: (payload: Record<string, unknown>) => void;
 }
 declare const ActionFormRenderer: import("svelte").Component<Props, {}, "">;
 type ActionFormRenderer = ReturnType<typeof ActionFormRenderer>;

package/components/CallToAction.svelte

@@ -0,0 +1,180 @@
+<!--
+  @component CallToAction
+
+  A conversion band: a heading, optional body, and one or two action buttons.
+  The reusable "ready to act?" strip at the foot of landing / campaign / content
+  pages. Presentational — heading, body and buttons (label + href) are DATA, so
+  it drops into any vertical.
+
+  `variant="accent"` fills the band with the brand accent (text flips to
+  `--color-text-on-accent`); `"surface"` (default) is a quiet bordered band.
+
+  @example
+  <CallToAction
+    heading="Tem uma ideia para o seu município?"
+    body="Submeta a sua proposta ao Orçamento Participativo."
+    primary={{ label: "Submeter proposta", href: "/propor" }}
+    secondary={{ label: "Ver propostas", href: "/mapa" }}
+    variant="accent"
+  />
+-->
+<script>
+  import Button from "./Button.svelte";
+
+  let {
+    /** @type {string} */
+    heading = "",
+    /** @type {string} */
+    body = "",
+    /** @type {2 | 3} Heading level for `heading`. */
+    headingLevel = 2,
+    /** @type {{ label?: string, href?: string } | undefined} Primary CTA. */
+    primary = undefined,
+    /** @type {{ label?: string, href?: string } | undefined} Secondary CTA. */
+    secondary = undefined,
+    /** @type {'surface' | 'accent'} Band fill. */
+    variant = "surface",
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+</script>
+
+<section class="cta cta-{variant} {className}" {...rest}>
+  <div class="cta-inner">
+    {#if heading}
+      <svelte:element this={`h${headingLevel}`} class="cta-heading"
+        >{heading}</svelte:element
+      >
+    {/if}
+    {#if body}<p class="cta-body">{body}</p>{/if}
+    {#if (primary && primary.label) || (secondary && secondary.label)}
+      <div class="cta-actions">
+        {#if variant === "accent"}
+          <!-- On an accent (brand-coloured) fill the DS button variants don't
+               guarantee contrast (the theme's `secondary`/`ghost` text/bg sit
+               too close to the accent). Render explicit INVERTED controls whose
+               colours are the on-accent/accent token pair — the same contrast
+               ratio as a primary button, just flipped. -->
+          {#if primary && primary.label}
+            <a class="cta-btn-inverted" href={primary.href || undefined}
+              >{primary.label}</a
+            >
+          {/if}
+          {#if secondary && secondary.label}
+            <a class="cta-link-on-accent" href={secondary.href || undefined}
+              >{secondary.label}</a
+            >
+          {/if}
+        {:else}
+          {#if primary && primary.label}
+            <Button href={primary.href || undefined} variant="primary"
+              >{primary.label}</Button
+            >
+          {/if}
+          {#if secondary && secondary.label}
+            <Button href={secondary.href || undefined} variant="ghost"
+              >{secondary.label}</Button
+            >
+          {/if}
+        {/if}
+      </div>
+    {/if}
+  </div>
+</section>
+
+<style>
+  .cta {
+    border-radius: var(--card-radius);
+    overflow-wrap: break-word;
+  }
+
+  .cta-surface {
+    background: var(--color-surface-secondary);
+    border: 1px solid var(--color-border);
+  }
+
+  .cta-accent {
+    background: var(--color-accent);
+    color: var(--color-text-on-accent);
+  }
+
+  .cta-inner {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+    align-items: flex-start;
+    max-width: var(--content-width-wide);
+    margin-inline: auto;
+    padding: var(--space-2xl) var(--content-padding-x);
+  }
+
+  .cta-heading {
+    margin: 0;
+    font-family: var(--type-heading-font);
+    font-size: var(--type-heading-size);
+    line-height: var(--type-heading-leading);
+    color: inherit;
+  }
+
+  .cta-surface .cta-heading {
+    color: var(--color-text);
+  }
+
+  .cta-body {
+    margin: 0;
+    max-width: var(--content-width-narrow);
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    line-height: var(--type-body-leading);
+    color: inherit;
+  }
+
+  .cta-surface .cta-body {
+    color: var(--color-text-secondary);
+  }
+
+  .cta-actions {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--space-md);
+    margin-top: var(--space-xs);
+  }
+
+  /* Inverted solid button for the accent band: the on-accent surface as the
+     fill, the accent as the text — the primary-button token pair, flipped, so
+     it carries the same contrast guarantee against the coloured band. */
+  .cta-btn-inverted {
+    display: inline-flex;
+    align-items: center;
+    height: var(--button-md-height);
+    padding-inline: var(--button-md-padding-x);
+    border-radius: var(--button-radius);
+    background: var(--color-text-on-accent);
+    color: var(--color-accent);
+    font-family: var(--button-font);
+    font-size: var(--button-md-font-size);
+    letter-spacing: var(--button-tracking);
+    text-decoration: none;
+    white-space: nowrap;
+  }
+
+  .cta-btn-inverted:focus-visible {
+    outline: var(--focus-ring-width) solid var(--color-text-on-accent);
+    outline-offset: var(--focus-ring-offset);
+  }
+
+  .cta-link-on-accent {
+    color: var(--color-text-on-accent);
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    text-decoration: underline;
+    text-underline-offset: 0.2em;
+  }
+
+  .cta-link-on-accent:focus-visible {
+    outline: var(--focus-ring-width) solid var(--color-text-on-accent);
+    outline-offset: var(--focus-ring-offset);
+  }
+</style>

package/components/CallToAction.svelte.d.ts

@@ -0,0 +1,43 @@
+export default CallToAction;
+type CallToAction = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * CallToAction
+ *
+ * A conversion band: a heading, optional body, and one or two action buttons.
+ * The reusable "ready to act?" strip at the foot of landing / campaign / content
+ * pages. Presentational — heading, body and buttons (label + href) are DATA, so
+ * it drops into any vertical.
+ *
+ * `variant="accent"` fills the band with the brand accent (text flips to
+ * `--color-text-on-accent`); `"surface"` (default) is a quiet bordered band.
+ *
+ * @example
+ * <CallToAction
+ *   heading="Tem uma ideia para o seu município?"
+ *   body="Submeta a sua proposta ao Orçamento Participativo."
+ *   primary={{ label: "Submeter proposta", href: "/propor" }}
+ *   secondary={{ label: "Ver propostas", href: "/mapa" }}
+ *   variant="accent"
+ * />
+ */
+declare const CallToAction: import("svelte").Component<{
+    heading?: string;
+    body?: string;
+    headingLevel?: number;
+    primary?: any;
+    secondary?: any;
+    variant?: string;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    heading?: string;
+    body?: string;
+    headingLevel?: number;
+    primary?: any;
+    secondary?: any;
+    variant?: string;
+    class?: string;
+} & Record<string, any>;

package/components/CheckAnswers.svelte

@@ -0,0 +1,197 @@
+<!--
+  @component CheckAnswers
+
+  The "review your answers before submitting" summary — a grouped description
+  list of every answer the citizen gave, each with a "Change" link back to the
+  step that captured it. Vertical-agnostic: it renders whatever label/value
+  pairs the consumer collected (from the action's parameter labels), grouped by
+  the flow's sections. Pure presentation — no state, no network.
+
+  Accessibility (WCAG 3.3.4, Error Prevention): every answer is reviewable and
+  editable before the irreversible submit. Each "Change" control carries an
+  accessible name that includes WHAT it changes (the visible "Change" plus a
+  visually-hidden field label), so a screen-reader user never meets a row of
+  identical "Change" links. Answers are a `<dl>` (the semantic structure for
+  term/description pairs); section headings are `<h3>` under the widget's `h2`.
+
+  @example
+  <CheckAnswers
+    label="Check your answers"
+    groups={[
+      { label: "About you", items: [
+        { key: "name", label: "Full name", value: "Ana Silva", onChange: () => goTo(0) },
+      ]},
+      { label: "Your idea", items: [
+        { key: "title", label: "Title", value: "Bike lanes", onChange: () => goTo(1) },
+      ]},
+    ]}
+  />
+-->
+<script module>
+  /**
+   * @typedef {{ key: string, label: string, value: string, onChange?: () => void }} AnswerItem
+   * @typedef {{ label?: string, items: AnswerItem[] }} AnswerGroup
+   */
+</script>
+
+<script>
+  let {
+    /** @type {AnswerGroup[]} The collected answers, grouped by section. */
+    groups = [],
+    /** @type {string} Accessible name for the review region (localize it). */
+    label = "Check your answers",
+    /** @type {string} Visible text on each change control (localize it). */
+    changeLabel = "Change",
+    /** @type {string} Shown when there are no answers yet (localize it). */
+    emptyText = "There are no answers to review yet.",
+    /** @type {string} Placeholder for an answer the citizen left blank (localize it). */
+    blankText = "Not provided",
+
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+
+  const hasAnswers = $derived(groups.some((g) => g.items.length > 0));
+</script>
+
+<section class="check-answers {className}" aria-label={label} {...rest}>
+  {#if hasAnswers}
+    {#each groups as group (group.label ?? group.items[0]?.key)}
+      {#if group.items.length > 0}
+        <div class="check-answers-group">
+          {#if group.label}
+            <h3 class="check-answers-group-heading">{group.label}</h3>
+          {/if}
+          <dl class="check-answers-list">
+            {#each group.items as item (item.key)}
+              <div class="check-answers-row">
+                <dt class="check-answers-term">{item.label}</dt>
+                <dd class="check-answers-value">
+                  {item.value || blankText}
+                </dd>
+                <dd class="check-answers-action">
+                  {#if item.onChange}
+                    <button
+                      type="button"
+                      class="check-answers-change"
+                      onclick={() => item.onChange?.()}
+                    >
+                      {changeLabel}<span class="check-answers-sr"
+                        >&nbsp;{item.label}</span
+                      >
+                    </button>
+                  {/if}
+                </dd>
+              </div>
+            {/each}
+          </dl>
+        </div>
+      {/if}
+    {/each}
+  {:else}
+    <p class="check-answers-empty">{emptyText}</p>
+  {/if}
+</section>
+
+<style>
+  .check-answers {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+  }
+
+  .check-answers-group {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+  }
+
+  .check-answers-group-heading {
+    font-family: var(--type-heading-sm-font);
+    font-size: var(--type-heading-sm-size);
+    color: var(--color-text);
+    margin: 0;
+  }
+
+  .check-answers-list {
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .check-answers-row {
+    display: grid;
+    grid-template-columns: minmax(8rem, 1fr) 2fr auto;
+    gap: var(--space-sm);
+    align-items: start;
+    padding: var(--space-sm) 0;
+    border-bottom: 1px solid var(--color-border);
+  }
+
+  .check-answers-term {
+    font-family: var(--type-body-sm-font);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-muted);
+    margin: 0;
+  }
+
+  .check-answers-value {
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text);
+    margin: 0;
+    overflow-wrap: anywhere;
+  }
+
+  .check-answers-action {
+    margin: 0;
+    justify-self: end;
+  }
+
+  .check-answers-change {
+    appearance: none;
+    background: none;
+    border: none;
+    padding: 0;
+    cursor: pointer;
+    font-family: var(--type-body-sm-font);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-accent);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+
+  .check-answers-change:hover {
+    color: var(--color-accent-hover);
+  }
+
+  .check-answers-empty {
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text-muted);
+    margin: 0;
+  }
+
+  /* Visually-hidden text that screen readers still announce (WCAG 3.3.4). */
+  .check-answers-sr {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  @media (max-width: 30rem) {
+    .check-answers-row {
+      grid-template-columns: 1fr auto;
+    }
+    .check-answers-term {
+      grid-column: 1 / -1;
+    }
+  }
+</style>

package/components/CheckAnswers.svelte.d.ts

@@ -0,0 +1,60 @@
+export default CheckAnswers;
+export type AnswerItem = {
+    key: string;
+    label: string;
+    value: string;
+    onChange?: () => void;
+};
+export type AnswerGroup = {
+    label?: string;
+    items: AnswerItem[];
+};
+type CheckAnswers = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * CheckAnswers
+ *
+ * The "review your answers before submitting" summary — a grouped description
+ * list of every answer the citizen gave, each with a "Change" link back to the
+ * step that captured it. Vertical-agnostic: it renders whatever label/value
+ * pairs the consumer collected (from the action's parameter labels), grouped by
+ * the flow's sections. Pure presentation — no state, no network.
+ *
+ * Accessibility (WCAG 3.3.4, Error Prevention): every answer is reviewable and
+ * editable before the irreversible submit. Each "Change" control carries an
+ * accessible name that includes WHAT it changes (the visible "Change" plus a
+ * visually-hidden field label), so a screen-reader user never meets a row of
+ * identical "Change" links. Answers are a `<dl>` (the semantic structure for
+ * term/description pairs); section headings are `<h3>` under the widget's `h2`.
+ *
+ * @example
+ * <CheckAnswers
+ *   label="Check your answers"
+ *   groups={[
+ *     { label: "About you", items: [
+ *       { key: "name", label: "Full name", value: "Ana Silva", onChange: () => goTo(0) },
+ *     ]},
+ *     { label: "Your idea", items: [
+ *       { key: "title", label: "Title", value: "Bike lanes", onChange: () => goTo(1) },
+ *     ]},
+ *   ]}
+ * />
+ */
+declare const CheckAnswers: import("svelte").Component<{
+    groups?: any[];
+    label?: string;
+    changeLabel?: string;
+    emptyText?: string;
+    blankText?: string;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    groups?: any[];
+    label?: string;
+    changeLabel?: string;
+    emptyText?: string;
+    blankText?: string;
+    class?: string;
+} & Record<string, any>;