@aiaiai-pt/design-system 0.25.0 → 0.26.0

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/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;