@aiaiai-pt/design-system 0.24.0 → 0.26.0

package/components/Confirmation.svelte

@@ -0,0 +1,172 @@
+<!--
+  @component Confirmation
+
+  The receipt panel shown after a successful submission: a success banner with
+  the citizen's reference number front-and-centre, a "what happens next" body,
+  and an optional link to track the submission. Vertical-agnostic — it knows
+  nothing about proposals or occurrences, only "here is your reference and what
+  to expect". Pure presentation; the consumer fetched the reference.
+
+  Accessibility: a `<section>` region named by `label`; the success heading is
+  an `<h2>` (the page `<h1>` is the consumer's, same split as the other account
+  widgets) carrying a decorative check. The reference is emphasised text inside
+  a labelled block, not colour alone. Semantic tokens throughout, so the
+  success styling survives dark / high-contrast schemes (#244).
+
+  @example
+  <Confirmation
+    label="Submission received"
+    title="Your proposal has been submitted"
+    reference="PRP-2026-0042"
+    referenceLabel="Your reference number"
+    body="We've sent a confirmation. The committee will review your proposal."
+    trackHref="/participacao/acompanhar/PRP-2026-0042"
+    trackLabel="Track this proposal"
+  />
+-->
+<script>
+  import Button from "./Button.svelte";
+
+  let {
+    /** @type {string} Accessible name for the confirmation region (localize it). */
+    label = "Confirmation",
+    /** @type {string} The success headline (localize it). */
+    title = "Submission received",
+    /** @type {string} The reference / tracking number to surface. */
+    reference = "",
+    /** @type {string} Label above the reference number (localize it). */
+    referenceLabel = "Your reference number",
+    /** @type {string} The "what happens next" copy (localize it). */
+    body = "",
+    /** @type {string | undefined} Link to track the submission. */
+    trackHref = undefined,
+    /** @type {string} Label for the track link (localize it). */
+    trackLabel = "Track your submission",
+
+    /** @type {import('svelte').Snippet | undefined} Extra content (e.g. a next-steps list). */
+    children = undefined,
+
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+</script>
+
+<section class="confirmation {className}" aria-label={label} {...rest}>
+  <div class="confirmation-banner">
+    <span class="confirmation-icon" aria-hidden="true">
+      <svg viewBox="0 0 24 24" fill="none">
+        <path
+          d="M5 12.5l4.5 4.5L19 7.5"
+          stroke="currentColor"
+          stroke-width="2.5"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    </span>
+    <h2 class="confirmation-title">{title}</h2>
+  </div>
+
+  {#if reference}
+    <div class="confirmation-reference">
+      <span class="confirmation-reference-label">{referenceLabel}</span>
+      <strong class="confirmation-reference-value">{reference}</strong>
+    </div>
+  {/if}
+
+  {#if body}
+    <p class="confirmation-body">{body}</p>
+  {/if}
+
+  {#if children}
+    <div class="confirmation-extra">{@render children()}</div>
+  {/if}
+
+  {#if trackHref}
+    <div class="confirmation-actions">
+      <Button variant="secondary" href={trackHref}>{trackLabel}</Button>
+    </div>
+  {/if}
+</section>
+
+<style>
+  .confirmation {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+    padding: var(--space-xl);
+    border: 1px solid var(--color-success);
+    border-radius: var(--radius-lg);
+    background: var(--color-success-subtle);
+  }
+
+  .confirmation-banner {
+    display: flex;
+    align-items: center;
+    gap: var(--space-md);
+  }
+
+  .confirmation-icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    width: 2.5rem;
+    height: 2.5rem;
+    border-radius: var(--radius-circle);
+    background: var(--color-success);
+    color: var(--color-surface);
+  }
+
+  .confirmation-icon svg {
+    width: 1.5rem;
+    height: 1.5rem;
+  }
+
+  .confirmation-title {
+    font-family: var(--type-heading-font);
+    font-size: var(--type-heading-size);
+    color: var(--color-text);
+    margin: 0;
+  }
+
+  .confirmation-reference {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2xs);
+  }
+
+  .confirmation-reference-label {
+    font-family: var(--type-body-sm-font);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-muted);
+  }
+
+  .confirmation-reference-value {
+    font-family: var(--type-data-font);
+    font-size: var(--type-heading-sm-size);
+    letter-spacing: var(--type-data-tracking);
+    color: var(--color-text);
+  }
+
+  .confirmation-body {
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    line-height: var(--type-body-leading);
+    color: var(--color-text);
+    margin: 0;
+  }
+
+  .confirmation-extra {
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text);
+  }
+
+  .confirmation-actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-sm);
+  }
+</style>

package/components/Confirmation.svelte.d.ts

@@ -0,0 +1,53 @@
+export default Confirmation;
+type Confirmation = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * Confirmation
+ *
+ * The receipt panel shown after a successful submission: a success banner with
+ * the citizen's reference number front-and-centre, a "what happens next" body,
+ * and an optional link to track the submission. Vertical-agnostic — it knows
+ * nothing about proposals or occurrences, only "here is your reference and what
+ * to expect". Pure presentation; the consumer fetched the reference.
+ *
+ * Accessibility: a `<section>` region named by `label`; the success heading is
+ * an `<h2>` (the page `<h1>` is the consumer's, same split as the other account
+ * widgets) carrying a decorative check. The reference is emphasised text inside
+ * a labelled block, not colour alone. Semantic tokens throughout, so the
+ * success styling survives dark / high-contrast schemes (#244).
+ *
+ * @example
+ * <Confirmation
+ *   label="Submission received"
+ *   title="Your proposal has been submitted"
+ *   reference="PRP-2026-0042"
+ *   referenceLabel="Your reference number"
+ *   body="We've sent a confirmation. The committee will review your proposal."
+ *   trackHref="/participacao/acompanhar/PRP-2026-0042"
+ *   trackLabel="Track this proposal"
+ * />
+ */
+declare const Confirmation: import("svelte").Component<{
+    label?: string;
+    title?: string;
+    reference?: string;
+    referenceLabel?: string;
+    body?: string;
+    trackHref?: any;
+    trackLabel?: string;
+    children?: any;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    label?: string;
+    title?: string;
+    reference?: string;
+    referenceLabel?: string;
+    body?: string;
+    trackHref?: any;
+    trackLabel?: string;
+    children?: any;
+    class?: string;
+} & Record<string, any>;

package/components/FaqList.svelte

@@ -0,0 +1,159 @@
+<!--
+  @component FaqList
+
+  A frequently-asked-questions accordion. Built on native `<details>`/`<summary>`
+  so it expand/collapses with zero JS and is keyboard + screen-reader accessible
+  out of the box. Distinct from `CollapsibleSection` (filter-group chrome, label
+  styling): this renders question-weight summaries for content/help pages.
+  Presentational — the Q/A pairs are DATA. Answers accept pre-sanitised HTML
+  (the consumer owns the XSS boundary) or plain text.
+
+  @example
+  <FaqList
+    heading="Perguntas frequentes"
+    items={[
+      { q: "Quem pode participar?", a: "Qualquer cidadão recenseado no município." },
+      { q: "Como submeto?", aHtml: "<p>Use o <a href='/propor'>formulário</a>.</p>" },
+    ]}
+  />
+-->
+<script>
+  let {
+    /** @type {string} Optional heading above the list. */
+    heading = "",
+    /** @type {2 | 3} Heading level for `heading`. */
+    headingLevel = 2,
+    /**
+     * @type {Array<{ q?: string, a?: string, aHtml?: string }>} The questions.
+     * `aHtml` (pre-sanitised) takes precedence over the plain `a` text.
+     */
+    items = [],
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+</script>
+
+<section class="faq {className}" {...rest}>
+  {#if heading}
+    <svelte:element this={`h${headingLevel}`} class="faq-heading"
+      >{heading}</svelte:element
+    >
+  {/if}
+  <div class="faq-list">
+    {#each items as item (item.q)}
+      <details class="faq-item">
+        <summary class="faq-question">
+          <span class="faq-question-text">{item.q}</span>
+          <svg
+            class="faq-caret"
+            width="14"
+            height="14"
+            viewBox="0 0 14 14"
+            fill="none"
+            aria-hidden="true"
+          >
+            <path
+              d="M3 5L7 10L11 5"
+              stroke="currentColor"
+              stroke-width="1.5"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            />
+          </svg>
+        </summary>
+        <div class="faq-answer">
+          {#if item.aHtml !== undefined}
+            <!-- eslint-disable-next-line svelte/no-at-html-tags — caller-sanitised -->
+            {@html item.aHtml}
+          {:else if item.a}
+            <p>{item.a}</p>
+          {/if}
+        </div>
+      </details>
+    {/each}
+  </div>
+</section>
+
+<style>
+  .faq {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+    overflow-wrap: break-word;
+  }
+
+  .faq-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);
+  }
+
+  .faq-item {
+    border-bottom: 1px solid var(--color-border);
+  }
+
+  .faq-question {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-md);
+    cursor: pointer;
+    padding: var(--space-md) 0;
+    list-style: none;
+    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);
+  }
+
+  .faq-question::-webkit-details-marker {
+    display: none;
+  }
+  .faq-question::marker {
+    content: "";
+  }
+
+  .faq-question:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+
+  /* Flex item: shrink past the caret so a long question wraps/breaks. */
+  .faq-question-text {
+    min-width: 0;
+  }
+
+  .faq-caret {
+    flex-shrink: 0;
+    color: var(--color-text-secondary);
+    transition: transform var(--duration-fast) var(--easing-default);
+  }
+
+  .faq-item[open] .faq-caret {
+    transform: rotate(180deg);
+  }
+
+  .faq-answer {
+    padding: 0 0 var(--space-md);
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    line-height: var(--type-body-leading);
+    color: var(--color-text-secondary);
+  }
+
+  .faq-answer :global(p) {
+    margin: 0 0 var(--space-sm);
+  }
+  .faq-answer :global(p:last-child) {
+    margin-bottom: 0;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .faq-caret {
+      transition: none;
+    }
+  }
+</style>

package/components/FaqList.svelte.d.ts

@@ -0,0 +1,36 @@
+export default FaqList;
+type FaqList = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * FaqList
+ *
+ * A frequently-asked-questions accordion. Built on native `<details>`/`<summary>`
+ * so it expand/collapses with zero JS and is keyboard + screen-reader accessible
+ * out of the box. Distinct from `CollapsibleSection` (filter-group chrome, label
+ * styling): this renders question-weight summaries for content/help pages.
+ * Presentational — the Q/A pairs are DATA. Answers accept pre-sanitised HTML
+ * (the consumer owns the XSS boundary) or plain text.
+ *
+ * @example
+ * <FaqList
+ *   heading="Perguntas frequentes"
+ *   items={[
+ *     { q: "Quem pode participar?", a: "Qualquer cidadão recenseado no município." },
+ *     { q: "Como submeto?", aHtml: "<p>Use o <a href='/propor'>formulário</a>.</p>" },
+ *   ]}
+ * />
+ */
+declare const FaqList: import("svelte").Component<{
+    heading?: string;
+    headingLevel?: number;
+    items?: any[];
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    heading?: string;
+    headingLevel?: number;
+    items?: any[];
+    class?: string;
+} & Record<string, any>;

package/components/FeatureGrid.svelte

@@ -0,0 +1,139 @@
+<!--
+  @component FeatureGrid
+
+  A responsive grid of feature cards — each an optional icon, a heading, and a
+  short description (optionally a link). The landing/marketing "what you can do"
+  / highlights band. Purely presentational: the items are DATA (page props), so
+  it drops into any vertical with different copy. Built on CardGrid + Card.
+
+  Headings render at `headingLevel` (default h3 — the band sits under a section
+  heading the consumer owns). Icons are DECORATIVE: the DS stays icon-set
+  agnostic, so the consumer supplies an `icon` snippet that renders an icon for
+  each item (e.g. mapping `item.icon` to its own icon library). No snippet → no
+  icons, cards still render.
+
+  @example
+  <FeatureGrid
+    heading="Como participar"
+    items={[
+      { icon: "lightbulb", title: "Proponha", text: "Submeta a sua ideia." },
+      { icon: "check-circle", title: "Vote", text: "Escolha as vencedoras.", href: "/propor" },
+    ]}
+  >
+    {#snippet icon(item)}<MyIcon name={item.icon} />{/snippet}
+  </FeatureGrid>
+-->
+<script>
+  import CardGrid from "./CardGrid.svelte";
+  import Card from "./Card.svelte";
+
+  let {
+    /** @type {string} Optional band heading (rendered above the grid). */
+    heading = "",
+    /** @type {string} Optional supporting text under the heading. */
+    intro = "",
+    /** @type {2 | 3 | 4} Heading level for `heading`. */
+    headingLevel = 2,
+    /** @type {'2' | '3' | '4'} Grid columns at desktop. */
+    columns = "3",
+    /**
+     * @type {Array<{ icon?: string, title?: string, text?: string, href?: string }>}
+     * Feature items. `icon` is an opaque name passed to the `icon` snippet;
+     * `href` makes the whole card a link.
+     */
+    items = [],
+    /**
+     * @type {import('svelte').Snippet<[{ icon?: string }]> | undefined}
+     * Decorative per-item icon. Receives the item; the consumer maps `item.icon`
+     * to its own icon component (the DS doesn't bundle an icon set).
+     */
+    icon = undefined,
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+</script>
+
+<div class="feature-grid {className}" {...rest}>
+  {#if heading}
+    <div class="feature-grid-head">
+      <svelte:element this={`h${headingLevel}`} class="feature-grid-heading"
+        >{heading}</svelte:element
+      >
+      {#if intro}<p class="feature-grid-intro">{intro}</p>{/if}
+    </div>
+  {/if}
+
+  <CardGrid {columns}>
+    {#each items as item (item.title)}
+      <Card href={item.href || undefined} interactive={!!item.href}>
+        {#if icon && item.icon}
+          <span class="feature-icon" aria-hidden="true">{@render icon(item)}</span>
+        {/if}
+        {#if item.title}
+          <svelte:element
+            this={`h${Math.min(headingLevel + 1, 4)}`}
+            class="feature-title">{item.title}</svelte:element
+          >
+        {/if}
+        {#if item.text}<p class="feature-text">{item.text}</p>{/if}
+      </Card>
+    {/each}
+  </CardGrid>
+</div>
+
+<style>
+  .feature-grid {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xl);
+    /* Break a pathological unbreakable token instead of blowing out a card
+       (CardGrid already sets min-width:0 on its children). Inherited. */
+    overflow-wrap: break-word;
+  }
+
+  .feature-grid-head {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+  }
+
+  .feature-grid-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);
+  }
+
+  .feature-grid-intro {
+    margin: 0;
+    max-width: var(--content-width-narrow);
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text-secondary);
+  }
+
+  .feature-icon {
+    display: inline-flex;
+    color: var(--color-accent);
+    margin-bottom: var(--space-sm);
+    line-height: 0;
+  }
+
+  .feature-title {
+    margin: 0 0 var(--space-xs);
+    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);
+  }
+
+  .feature-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/FeatureGrid.svelte.d.ts

@@ -0,0 +1,48 @@
+export default FeatureGrid;
+type FeatureGrid = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * FeatureGrid
+ *
+ * A responsive grid of feature cards — each an optional icon, a heading, and a
+ * short description (optionally a link). The landing/marketing "what you can do"
+ * / highlights band. Purely presentational: the items are DATA (page props), so
+ * it drops into any vertical with different copy. Built on CardGrid + Card.
+ *
+ * Headings render at `headingLevel` (default h3 — the band sits under a section
+ * heading the consumer owns). Icons are DECORATIVE: the DS stays icon-set
+ * agnostic, so the consumer supplies an `icon` snippet that renders an icon for
+ * each item (e.g. mapping `item.icon` to its own icon library). No snippet → no
+ * icons, cards still render.
+ *
+ * @example
+ * <FeatureGrid
+ *   heading="Como participar"
+ *   items={[
+ *     { icon: "lightbulb", title: "Proponha", text: "Submeta a sua ideia." },
+ *     { icon: "check-circle", title: "Vote", text: "Escolha as vencedoras.", href: "/propor" },
+ *   ]}
+ * >
+ *   {#snippet icon(item)}<MyIcon name={item.icon} />{/snippet}
+ * </FeatureGrid>
+ */
+declare const FeatureGrid: import("svelte").Component<{
+    heading?: string;
+    intro?: string;
+    headingLevel?: number;
+    columns?: string;
+    items?: any[];
+    icon?: any;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    heading?: string;
+    intro?: string;
+    headingLevel?: number;
+    columns?: string;
+    items?: any[];
+    icon?: any;
+    class?: string;
+} & Record<string, any>;

package/components/Hero.svelte

@@ -16,6 +16,11 @@
 
   @example Background image (a theme-tinted scrim keeps text contrast)
   <Hero title="Report a problem" image="/images/city.jpg" />
+
+  @example Centered marketing hero with a call-to-action
+  <Hero title="Participe" subtitle="As suas ideias." align="center" image="/op.jpg">
+    {#snippet actions()}<Button href="/propor">Submeter</Button>{/snippet}
+  </Hero>
 -->
 <script>
   let {
@@ -28,6 +33,10 @@
     /** @type {string | undefined} Background image URL — rendered cover/center
      *  under a `--hero-scrim` overlay so the text tokens keep contrast. */
     image = undefined,
+    /** @type {'start' | 'center'} Content alignment — `center` is the marketing
+     *  variant (centered title/subtitle/actions); `start` (default) is the
+     *  left-aligned process hero. */
+    align = "start",
     /** @type {string} */
     class: className = "",
     /** @type {import('svelte').Snippet | undefined} Title override (rich content). */
@@ -46,7 +55,7 @@
 </script>
 
 <section
-  class="hero {className}"
+  class="hero hero-align-{align} {className}"
   class:hero-has-image={!!image}
   style={bgStyle}
   {...rest}
@@ -69,6 +78,9 @@
 <style>
   .hero {
     background: var(--color-surface);
+    /* Break a pathological unbreakable token (long URL/word) instead of
+       overflowing the band. overflow-wrap is inherited → covers all text. */
+    overflow-wrap: break-word;
   }
 
   .hero-has-image {
@@ -120,4 +132,14 @@
     gap: var(--space-sm);
     margin-top: var(--space-sm);
   }
+
+  /* Centered marketing variant — title/subtitle/actions all centre-aligned. */
+  .hero-align-center .hero-inner {
+    align-items: center;
+    text-align: center;
+  }
+
+  .hero-align-center .hero-subtitle {
+    margin-inline: auto;
+  }
 </style>

package/components/Hero.svelte.d.ts

@@ -21,12 +21,18 @@ type Hero = {
  *
  * @example Background image (a theme-tinted scrim keeps text contrast)
  * <Hero title="Report a problem" image="/images/city.jpg" />
+ *
+ * @example Centered marketing hero with a call-to-action
+ * <Hero title="Participe" subtitle="As suas ideias." align="center" image="/op.jpg">
+ *   {#snippet actions()}<Button href="/propor">Submeter</Button>{/snippet}
+ * </Hero>
  */
 declare const Hero: import("svelte").Component<{
     title?: string;
     subtitle?: string;
     headingLevel?: number;
     image?: any;
+    align?: string;
     class?: string;
     children?: any;
     actions?: any;
@@ -36,6 +42,7 @@ type $$ComponentProps = {
     subtitle?: string;
     headingLevel?: number;
     image?: any;
+    align?: string;
     class?: string;
     children?: any;
     actions?: any;