@aiaiai-pt/design-system 0.24.0 → 0.26.0

package/components/ServiceFlow.svelte

@@ -0,0 +1,264 @@
+<!--
+  @component ServiceFlow
+
+  The chrome for a multi-step submit journey (a "service flow"): a step
+  indicator, a progress bar, an error-summary region, the active step's body,
+  and the prev / next / submit navigation. Vertical-agnostic — it renders
+  whatever the consumer puts in the `children` snippet for the active step and
+  never knows what an "eligibility check" or "proposal" is. The consumer owns
+  the wizard STATE (which step, the collected answers) and the network; this
+  shell owns the layout, the accessible step semantics, and focus management.
+
+  Controlled: pass `current` (0-based active step) and the `steps` labels;
+  drive it with `onPrev` / `onNext` (advance) and `onSubmit` (the final step's
+  primary action). `canProceed=false` disables the primary button (e.g. an
+  eligibility gate failed or the step is invalid); `busy=true` shows it loading
+  and locks the nav (a dry-run or the submit is in flight).
+
+  Accessibility (WCAG): a `<section>` region named by `label`; a polite live
+  region announces "Step X of Y"; on every step change focus moves to the step
+  body (or, if the consumer surfaces `errors`, to the error summary — an
+  `role="alert"` list the citizen lands on so the reason is read first). The
+  error summary, the step nav buttons, and the progress bar all ride semantic
+  tokens, so dark / high-contrast schemes (#244) work unchanged.
+
+  @example
+  <ServiceFlow
+    label="Submit a proposal"
+    steps={[{ label: "Eligibility" }, { label: "Your idea" }, { label: "Review" }]}
+    current={step}
+    canProceed={eligible}
+    busy={checking}
+    errors={violations}
+    onPrev={() => step--}
+    onNext={() => step++}
+    onSubmit={() => submit()}
+  >
+    {@render activeStepBody()}
+  </ServiceFlow>
+-->
+<script module>
+  /**
+   * @typedef {{ label: string }} FlowStep
+   */
+</script>
+
+<script>
+  import Stepper from "./Stepper.svelte";
+  import Progress from "./Progress.svelte";
+  import Button from "./Button.svelte";
+
+  let {
+    /** @type {FlowStep[]} Ordered step labels for the indicator. */
+    steps = [],
+    /** @type {number} The active step, 0-based. */
+    current = 0,
+    /** @type {string} Accessible name for the flow region (localize it). */
+    label = "Step-by-step form",
+    /** @type {boolean} Whether the primary (next/submit) button is enabled. */
+    canProceed = true,
+    /** @type {boolean} A step action is in flight — locks nav, loads the button. */
+    busy = false,
+    /** @type {string[]} Blocking messages for the error summary (localize them). */
+    errors = [],
+
+    /** @type {string} Label for the error-summary heading (localize it). */
+    errorSummaryLabel = "There is a problem",
+    /** @type {string} Back-button label (localize it). */
+    prevLabel = "Back",
+    /** @type {string} Advance-button label (localize it). */
+    nextLabel = "Continue",
+    /** @type {string} Final-step primary label (localize it). */
+    submitLabel = "Submit",
+    /**
+     * @type {(stepNumber: number, total: number) => string}
+     * Builds the "Step X of Y" announcement (localize it).
+     */
+    progressLabel = (n, total) => `Step ${n} of ${total}`,
+
+    /** @type {(() => void) | undefined} Go to the previous step. */
+    onPrev = undefined,
+    /** @type {(() => void) | undefined} Advance to the next step. */
+    onNext = undefined,
+    /** @type {(() => void) | undefined} Run the final step's primary action. */
+    onSubmit = undefined,
+
+    /** @type {import('svelte').Snippet | undefined} The active step's body. */
+    children = undefined,
+
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+
+  const total = $derived(steps.length || 1);
+  const isFirst = $derived(current <= 0);
+  const isLast = $derived(current >= total - 1);
+  const hasErrors = $derived(errors.length > 0);
+
+  /** Map the flat step labels to the Stepper's status model. */
+  const indicatorSteps = $derived(
+    steps.map((s, i) => ({
+      label: s.label,
+      status:
+        i < current ? "complete" : i === current ? "active" : "upcoming",
+    })),
+  );
+
+  /** @type {HTMLElement | undefined} */
+  let bodyRef = $state(undefined);
+  /** @type {HTMLElement | undefined} */
+  let errorRef = $state(undefined);
+
+  // Focus management: after the first render, every step change (or a newly
+  // surfaced error) moves focus so a keyboard / screen-reader user is taken to
+  // the right place — the error summary when blocked, otherwise the step body.
+  // The initial mount is skipped so the page doesn't steal focus on load.
+  let mounted = false;
+  $effect(() => {
+    // Re-run when the step or the error state changes.
+    void current;
+    void hasErrors;
+    if (!mounted) {
+      mounted = true;
+      return;
+    }
+    const target = hasErrors ? errorRef : bodyRef;
+    target?.focus();
+  });
+</script>
+
+<section class="service-flow {className}" aria-label={label} {...rest}>
+  {#if steps.length > 1}
+    <Stepper steps={indicatorSteps} class="service-flow-stepper" />
+  {/if}
+
+  <Progress
+    value={current + 1}
+    max={total}
+    class="service-flow-progress"
+    aria-label={progressLabel(current + 1, total)}
+  />
+  <p class="service-flow-progress-text" aria-live="polite">
+    {progressLabel(current + 1, total)}
+  </p>
+
+  {#if hasErrors}
+    <div
+      class="service-flow-errors"
+      role="alert"
+      tabindex="-1"
+      bind:this={errorRef}
+    >
+      <h2 class="service-flow-errors-heading">{errorSummaryLabel}</h2>
+      <ul class="service-flow-errors-list">
+        {#each errors as message}
+          <li>{message}</li>
+        {/each}
+      </ul>
+    </div>
+  {/if}
+
+  <div class="service-flow-body" tabindex="-1" bind:this={bodyRef}>
+    {@render children?.()}
+  </div>
+
+  <div class="service-flow-nav">
+    {#if !isFirst}
+      <Button variant="ghost" disabled={busy} onclick={() => onPrev?.()}>
+        {prevLabel}
+      </Button>
+    {/if}
+    {#if isLast}
+      <Button
+        variant="primary"
+        loading={busy}
+        disabled={!canProceed || busy}
+        onclick={() => onSubmit?.()}
+      >
+        {submitLabel}
+      </Button>
+    {:else}
+      <Button
+        variant="primary"
+        loading={busy}
+        disabled={!canProceed || busy}
+        onclick={() => onNext?.()}
+      >
+        {nextLabel}
+      </Button>
+    {/if}
+  </div>
+</section>
+
+<style>
+  .service-flow {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+  }
+
+  .service-flow-progress-text {
+    font-family: var(--type-body-sm-font);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-muted);
+    margin: calc(-1 * var(--space-sm)) 0 0;
+  }
+
+  .service-flow-errors {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+    padding: var(--space-md);
+    border: 1px solid var(--color-destructive);
+    border-radius: var(--radius-md);
+    background: var(--color-destructive-subtle);
+  }
+
+  /* The alert region is programmatically focusable but shows no focus ring. */
+  .service-flow-errors:focus {
+    outline: none;
+  }
+
+  .service-flow-errors-heading {
+    font-family: var(--type-heading-sm-font);
+    font-size: var(--type-heading-sm-size);
+    color: var(--color-text);
+    margin: 0;
+  }
+
+  .service-flow-errors-list {
+    margin: 0;
+    padding-left: var(--space-lg);
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2xs);
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text);
+  }
+
+  .service-flow-body {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .service-flow-body:focus {
+    outline: none;
+  }
+
+  .service-flow-nav {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    gap: var(--space-sm);
+    padding-top: var(--space-md);
+    border-top: 1px solid var(--color-border);
+  }
+
+  /* When only the primary button shows (first step), keep it right-aligned. */
+  .service-flow-nav:has(> :only-child) {
+    justify-content: flex-end;
+  }
+</style>

package/components/ServiceFlow.svelte.d.ts

@@ -0,0 +1,83 @@
+export default ServiceFlow;
+export type FlowStep = {
+    label: string;
+};
+type ServiceFlow = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * ServiceFlow
+ *
+ * The chrome for a multi-step submit journey (a "service flow"): a step
+ * indicator, a progress bar, an error-summary region, the active step's body,
+ * and the prev / next / submit navigation. Vertical-agnostic — it renders
+ * whatever the consumer puts in the `children` snippet for the active step and
+ * never knows what an "eligibility check" or "proposal" is. The consumer owns
+ * the wizard STATE (which step, the collected answers) and the network; this
+ * shell owns the layout, the accessible step semantics, and focus management.
+ *
+ * Controlled: pass `current` (0-based active step) and the `steps` labels;
+ * drive it with `onPrev` / `onNext` (advance) and `onSubmit` (the final step's
+ * primary action). `canProceed=false` disables the primary button (e.g. an
+ * eligibility gate failed or the step is invalid); `busy=true` shows it loading
+ * and locks the nav (a dry-run or the submit is in flight).
+ *
+ * Accessibility (WCAG): a `<section>` region named by `label`; a polite live
+ * region announces "Step X of Y"; on every step change focus moves to the step
+ * body (or, if the consumer surfaces `errors`, to the error summary — an
+ * `role="alert"` list the citizen lands on so the reason is read first). The
+ * error summary, the step nav buttons, and the progress bar all ride semantic
+ * tokens, so dark / high-contrast schemes (#244) work unchanged.
+ *
+ * @example
+ * <ServiceFlow
+ *   label="Submit a proposal"
+ *   steps={[{ label: "Eligibility" }, { label: "Your idea" }, { label: "Review" }]}
+ *   current={step}
+ *   canProceed={eligible}
+ *   busy={checking}
+ *   errors={violations}
+ *   onPrev={() => step--}
+ *   onNext={() => step++}
+ *   onSubmit={() => submit()}
+ * >
+ *   {@render activeStepBody()}
+ * </ServiceFlow>
+ */
+declare const ServiceFlow: import("svelte").Component<{
+    steps?: any[];
+    current?: number;
+    label?: string;
+    canProceed?: boolean;
+    busy?: boolean;
+    errors?: any[];
+    errorSummaryLabel?: string;
+    prevLabel?: string;
+    nextLabel?: string;
+    submitLabel?: string;
+    progressLabel?: Function;
+    onPrev?: any;
+    onNext?: any;
+    onSubmit?: any;
+    children?: any;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    steps?: any[];
+    current?: number;
+    label?: string;
+    canProceed?: boolean;
+    busy?: boolean;
+    errors?: any[];
+    errorSummaryLabel?: string;
+    prevLabel?: string;
+    nextLabel?: string;
+    submitLabel?: string;
+    progressLabel?: Function;
+    onPrev?: any;
+    onNext?: any;
+    onSubmit?: any;
+    children?: any;
+    class?: string;
+} & Record<string, any>;

package/components/Steps.svelte

@@ -0,0 +1,137 @@
+<!--
+  @component Steps
+
+  A numbered "how it works" explainer — an ordered list of steps, each a number
+  badge, a heading and a short description. Distinct from `ServiceFlow`/`Stepper`
+  (which drive a live multi-step form): this is presentational marketing content
+  that explains a process. The numbers come from the list order (decorative
+  badges, `aria-hidden`) so screen readers get the native `<ol>` sequence.
+
+  @example
+  <Steps
+    heading="Como funciona"
+    steps={[
+      { title: "Proponha", text: "Submeta a sua ideia até 31 de março." },
+      { title: "Análise", text: "A comissão verifica a elegibilidade." },
+      { title: "Votação", text: "Os cidadãos votam nas finalistas." },
+      { title: "Execução", text: "As propostas vencedoras são executadas." },
+    ]}
+  />
+-->
+<script>
+  let {
+    /** @type {string} Optional band heading. */
+    heading = "",
+    /** @type {2 | 3} Heading level for `heading`. */
+    headingLevel = 2,
+    /**
+     * @type {Array<{ title?: string, text?: string }>} The ordered steps.
+     */
+    steps = [],
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+</script>
+
+<section class="steps {className}" {...rest}>
+  {#if heading}
+    <svelte:element this={`h${headingLevel}`} class="steps-heading"
+      >{heading}</svelte:element
+    >
+  {/if}
+  <ol class="steps-list">
+    {#each steps as step, i (step.title)}
+      <li class="steps-item">
+        <span class="steps-number" aria-hidden="true">{i + 1}</span>
+        <div class="steps-body">
+          {#if step.title}
+            <svelte:element
+              this={`h${Math.min(headingLevel + 1, 4)}`}
+              class="steps-title">{step.title}</svelte:element
+            >
+          {/if}
+          {#if step.text}<p class="steps-text">{step.text}</p>{/if}
+        </div>
+      </li>
+    {/each}
+  </ol>
+</section>
+
+<style>
+  .steps {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xl);
+    overflow-wrap: break-word;
+  }
+
+  .steps-heading {
+    margin: 0;
+    font-family: var(--type-heading-font);
+    font-size: var(--type-heading-size);
+    line-height: var(--type-heading-leading);
+    color: var(--color-text);
+  }
+
+  .steps-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: var(--space-lg);
+    counter-reset: step;
+  }
+
+  @media (min-width: 768px) {
+    .steps-list {
+      grid-template-columns: repeat(2, 1fr);
+    }
+  }
+
+  .steps-item {
+    display: flex;
+    gap: var(--space-md);
+    align-items: flex-start;
+  }
+
+  .steps-number {
+    flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.25rem;
+    height: 2.25rem;
+    border-radius: 50%;
+    background: var(--color-accent);
+    color: var(--color-text-on-accent);
+    font-family: var(--type-data-font);
+    font-size: var(--type-data-size);
+    font-weight: 600;
+  }
+
+  .steps-body {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2xs);
+    /* Shrink past the number badge so the text can wrap a long token. */
+    min-width: 0;
+  }
+
+  .steps-title {
+    margin: 0;
+    font-family: var(--type-heading-sm-font);
+    font-size: var(--type-heading-sm-size);
+    line-height: var(--type-heading-sm-leading);
+    color: var(--color-text);
+  }
+
+  .steps-text {
+    margin: 0;
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    line-height: var(--type-body-leading);
+    color: var(--color-text-secondary);
+  }
+</style>

package/components/Steps.svelte.d.ts

@@ -0,0 +1,37 @@
+export default Steps;
+type Steps = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * Steps
+ *
+ * A numbered "how it works" explainer — an ordered list of steps, each a number
+ * badge, a heading and a short description. Distinct from `ServiceFlow`/`Stepper`
+ * (which drive a live multi-step form): this is presentational marketing content
+ * that explains a process. The numbers come from the list order (decorative
+ * badges, `aria-hidden`) so screen readers get the native `<ol>` sequence.
+ *
+ * @example
+ * <Steps
+ *   heading="Como funciona"
+ *   steps={[
+ *     { title: "Proponha", text: "Submeta a sua ideia até 31 de março." },
+ *     { title: "Análise", text: "A comissão verifica a elegibilidade." },
+ *     { title: "Votação", text: "Os cidadãos votam nas finalistas." },
+ *     { title: "Execução", text: "As propostas vencedoras são executadas." },
+ *   ]}
+ * />
+ */
+declare const Steps: import("svelte").Component<{
+    heading?: string;
+    headingLevel?: number;
+    steps?: any[];
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    heading?: string;
+    headingLevel?: number;
+    steps?: any[];
+    class?: string;
+} & Record<string, any>;

package/components/Testimonial.svelte

@@ -0,0 +1,161 @@
+<!--
+  @component Testimonial
+
+  A quote / testimonial band — one prominent pull-quote, or a small grid of
+  them. Semantic `<figure>` + `<blockquote>` + `<figcaption>` so the attribution
+  is correctly associated with the quote. Presentational: the quotes (text +
+  author + role + optional avatar) are DATA.
+
+  @example Single quote
+  <Testimonial quote="Finalmente a minha rua tem iluminação nova." author="Maria S." role="Junta de Freguesia" />
+
+  @example A grid of quotes
+  <Testimonial
+    heading="O que dizem os cidadãos"
+    items={[
+      { quote: "Simples e rápido.", author: "João P." },
+      { quote: "A minha proposta foi executada!", author: "Ana R.", role: "Valongo" },
+    ]}
+  />
+-->
+<script>
+  let {
+    /** @type {string} Optional band heading (for the grid form). */
+    heading = "",
+    /** @type {2 | 3} Heading level for `heading`. */
+    headingLevel = 2,
+    /** @type {string} Single-quote text (when `items` is empty). */
+    quote = "",
+    /** @type {string} */
+    author = "",
+    /** @type {string} */
+    role = "",
+    /** @type {string | undefined} Avatar image URL. */
+    avatar = undefined,
+    /**
+     * @type {Array<{ quote?: string, author?: string, role?: string, avatar?: string }>}
+     * Multiple testimonials (renders a grid). Overrides the single-quote props.
+     */
+    items = [],
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+
+  const list = $derived(
+    items.length > 0
+      ? items
+      : quote
+        ? [{ quote, author, role, avatar }]
+        : [],
+  );
+</script>
+
+<section class="testimonial {className}" {...rest}>
+  {#if heading}
+    <svelte:element this={`h${headingLevel}`} class="testimonial-heading"
+      >{heading}</svelte:element
+    >
+  {/if}
+  <div class="testimonial-grid" class:testimonial-grid-multi={list.length > 1}>
+    {#each list as item (item.quote)}
+      <figure class="testimonial-item">
+        <blockquote class="testimonial-quote">{item.quote}</blockquote>
+        {#if item.author || item.role}
+          <figcaption class="testimonial-cite">
+            {#if item.avatar}
+              <img class="testimonial-avatar" src={item.avatar} alt="" loading="lazy" />
+            {/if}
+            <span class="testimonial-attrib">
+              {#if item.author}<span class="testimonial-author">{item.author}</span>{/if}
+              {#if item.role}<span class="testimonial-role">{item.role}</span>{/if}
+            </span>
+          </figcaption>
+        {/if}
+      </figure>
+    {/each}
+  </div>
+</section>
+
+<style>
+  .testimonial {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xl);
+    overflow-wrap: break-word;
+  }
+
+  .testimonial-heading {
+    margin: 0;
+    font-family: var(--type-heading-font);
+    font-size: var(--type-heading-size);
+    line-height: var(--type-heading-leading);
+    color: var(--color-text);
+  }
+
+  .testimonial-grid {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: var(--space-lg);
+  }
+
+  @media (min-width: 768px) {
+    .testimonial-grid-multi {
+      grid-template-columns: repeat(2, 1fr);
+    }
+  }
+
+  .testimonial-item {
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+    padding: var(--space-xl);
+    background: var(--color-surface-secondary);
+    border-left: 3px solid var(--color-accent);
+    border-radius: var(--card-radius);
+    /* Grid child: shrink so a long quote/name wraps instead of overflowing. */
+    min-width: 0;
+  }
+
+  .testimonial-quote {
+    margin: 0;
+    font-family: var(--type-heading-sm-font);
+    font-size: var(--type-heading-sm-size);
+    line-height: var(--type-heading-sm-leading);
+    color: var(--color-text);
+  }
+
+  .testimonial-cite {
+    display: flex;
+    align-items: center;
+    gap: var(--space-sm);
+    font-style: normal;
+  }
+
+  .testimonial-avatar {
+    width: 2.5rem;
+    height: 2.5rem;
+    border-radius: 50%;
+    object-fit: cover;
+  }
+
+  .testimonial-attrib {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+  }
+
+  .testimonial-author {
+    font-family: var(--type-label-font);
+    font-size: var(--type-body-sm-size);
+    font-weight: 600;
+    color: var(--color-text);
+  }
+
+  .testimonial-role {
+    font-family: var(--type-caption-font);
+    font-size: var(--type-caption-size);
+    color: var(--color-text-muted);
+  }
+</style>