@aiaiai-pt/design-system 0.25.0 → 0.26.0

package/components/LogoStrip.svelte

@@ -0,0 +1,116 @@
+<!--
+  @component LogoStrip
+
+  A row of partner / sponsor logos. Presentational — the logos (image URL + alt
+  text + optional link) are DATA. The strip wraps on narrow viewports. When a
+  logo has an `href` it renders a link; otherwise a plain image. Each logo MUST
+  carry meaningful `alt` (the partner's name) or be explicitly decorative.
+
+  @example
+  <LogoStrip
+    label="Parceiros"
+    logos={[
+      { src: "/logos/cm-valongo.svg", alt: "Câmara Municipal de Valongo", href: "https://cm-valongo.pt" },
+      { src: "/logos/ue.svg", alt: "União Europeia" },
+    ]}
+  />
+-->
+<script>
+  let {
+    /** @type {string} Accessible label for the logo group (localize it). */
+    label = "Partners",
+    /** @type {string} Optional visible heading (renders above the strip). */
+    heading = "",
+    /** @type {2 | 3} Heading level for `heading`. */
+    headingLevel = 2,
+    /**
+     * @type {Array<{ src?: string, alt?: string, href?: string }>} The logos.
+     */
+    logos = [],
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+</script>
+
+<section class="logo-strip {className}" aria-label={heading ? undefined : label} {...rest}>
+  {#if heading}
+    <svelte:element this={`h${headingLevel}`} class="logo-strip-heading"
+      >{heading}</svelte:element
+    >
+  {/if}
+  <ul class="logo-strip-list">
+    {#each logos as logo (logo.src)}
+      <li class="logo-strip-item">
+        {#if logo.href}
+          <a class="logo-strip-link" href={logo.href}>
+            <img class="logo-strip-img" src={logo.src} alt={logo.alt ?? ""} loading="lazy" />
+          </a>
+        {:else}
+          <img class="logo-strip-img" src={logo.src} alt={logo.alt ?? ""} loading="lazy" />
+        {/if}
+      </li>
+    {/each}
+  </ul>
+</section>
+
+<style>
+  .logo-strip {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+    align-items: center;
+    overflow-wrap: break-word;
+  }
+
+  .logo-strip-heading {
+    margin: 0;
+    font-family: var(--type-label-font);
+    font-size: var(--type-label-size);
+    font-weight: var(--type-label-weight);
+    letter-spacing: var(--type-label-tracking);
+    text-transform: uppercase;
+    color: var(--color-text-secondary);
+  }
+
+  .logo-strip-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-2xl);
+  }
+
+  .logo-strip-item {
+    display: flex;
+    align-items: center;
+  }
+
+  .logo-strip-link:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+
+  .logo-strip-img {
+    display: block;
+    max-height: 3rem;
+    width: auto;
+    /* Quiet the logos to a single visual weight; full opacity on hover/focus. */
+    opacity: 0.75;
+    transition: opacity var(--duration-fast) var(--easing-default);
+  }
+
+  .logo-strip-link:hover .logo-strip-img,
+  .logo-strip-link:focus-visible .logo-strip-img {
+    opacity: 1;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .logo-strip-img {
+      transition: none;
+    }
+  }
+</style>

package/components/LogoStrip.svelte.d.ts

@@ -0,0 +1,36 @@
+export default LogoStrip;
+type LogoStrip = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * LogoStrip
+ *
+ * A row of partner / sponsor logos. Presentational — the logos (image URL + alt
+ * text + optional link) are DATA. The strip wraps on narrow viewports. When a
+ * logo has an `href` it renders a link; otherwise a plain image. Each logo MUST
+ * carry meaningful `alt` (the partner's name) or be explicitly decorative.
+ *
+ * @example
+ * <LogoStrip
+ *   label="Parceiros"
+ *   logos={[
+ *     { src: "/logos/cm-valongo.svg", alt: "Câmara Municipal de Valongo", href: "https://cm-valongo.pt" },
+ *     { src: "/logos/ue.svg", alt: "União Europeia" },
+ *   ]}
+ * />
+ */
+declare const LogoStrip: import("svelte").Component<{
+    label?: string;
+    heading?: string;
+    headingLevel?: number;
+    logos?: any[];
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    label?: string;
+    heading?: string;
+    headingLevel?: number;
+    logos?: any[];
+    class?: string;
+} & Record<string, any>;

package/components/MediaGallery.svelte

@@ -0,0 +1,175 @@
+<!--
+  @component MediaGallery
+
+  A landing-grade media gallery — a responsive grid (or a horizontal scroll-snap
+  rail) of captioned images. Distinct from the detail-page image strip: this is
+  presentational showcase content for landing / campaign / about pages. No JS
+  carousel/autoplay (an accessibility and reduced-motion liability); on narrow
+  viewports the `rail` layout becomes a swipeable scroll-snap row that is fully
+  keyboard-scrollable. Each image carries operator-authored `alt`; captions are
+  optional `<figcaption>`s.
+
+  @example Grid
+  <MediaGallery
+    heading="Projetos executados"
+    items={[
+      { src: "/g/parque.jpg", alt: "Novo parque urbano", caption: "Parque da Cidade — 2025" },
+      { src: "/g/ciclovia.jpg", alt: "Ciclovia ribeirinha", caption: "Ciclovia — 2024" },
+    ]}
+  />
+
+  @example Horizontal rail
+  <MediaGallery layout="rail" label="Galeria" items={photos} />
+-->
+<script>
+  let {
+    /** @type {string} Optional visible heading. */
+    heading = "",
+    /** @type {2 | 3} Heading level for `heading`. */
+    headingLevel = 2,
+    /** @type {string} Accessible label when there is no visible heading. */
+    label = "Gallery",
+    /** @type {'grid' | 'rail'} Grid (wrap) or horizontal scroll-snap rail. */
+    layout = "grid",
+    /** @type {'2' | '3' | '4'} Grid columns at desktop (grid layout only). */
+    columns = "3",
+    /**
+     * @type {Array<{ src?: string, alt?: string, caption?: string }>} The media.
+     */
+    items = [],
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+</script>
+
+<section
+  class="media-gallery {className}"
+  aria-label={heading ? undefined : label}
+  {...rest}
+>
+  {#if heading}
+    <svelte:element this={`h${headingLevel}`} class="media-gallery-heading"
+      >{heading}</svelte:element
+    >
+  {/if}
+  <!-- A horizontal scroll-snap rail is a scrollable region: give it keyboard
+       access (tabindex=0) and an accessible name so it isn't an axe
+       `scrollable-region-focusable` violation. Keep the native list semantics
+       (no role override) so the <li>s stay valid list items. The grid layout
+       doesn't scroll, so it's a plain list. -->
+  <ul
+    class="media-gallery-list media-gallery-{layout} media-gallery-cols-{columns}"
+    tabindex={layout === "rail" ? 0 : undefined}
+    aria-label={layout === "rail" ? heading || label : undefined}
+  >
+    {#each items as item (item.src)}
+      <li class="media-gallery-item">
+        <figure class="media-gallery-figure">
+          <img class="media-gallery-img" src={item.src} alt={item.alt ?? ""} loading="lazy" />
+          {#if item.caption}
+            <figcaption class="media-gallery-caption">{item.caption}</figcaption>
+          {/if}
+        </figure>
+      </li>
+    {/each}
+  </ul>
+</section>
+
+<style>
+  .media-gallery {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xl);
+    overflow-wrap: break-word;
+  }
+
+  .media-gallery-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);
+  }
+
+  .media-gallery-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  /* ─── Grid layout ─── */
+  .media-gallery-grid {
+    display: grid;
+    gap: var(--grid-gutter);
+    grid-template-columns: 1fr;
+  }
+
+  @media (min-width: 768px) {
+    .media-gallery-grid.media-gallery-cols-2 {
+      grid-template-columns: repeat(2, 1fr);
+    }
+    .media-gallery-grid.media-gallery-cols-3 {
+      grid-template-columns: repeat(2, 1fr);
+    }
+    .media-gallery-grid.media-gallery-cols-4 {
+      grid-template-columns: repeat(2, 1fr);
+    }
+  }
+
+  @media (min-width: 1024px) {
+    .media-gallery-grid.media-gallery-cols-3 {
+      grid-template-columns: repeat(3, 1fr);
+    }
+    .media-gallery-grid.media-gallery-cols-4 {
+      grid-template-columns: repeat(4, 1fr);
+    }
+  }
+
+  /* ─── Horizontal scroll-snap rail ─── */
+  .media-gallery-rail {
+    display: flex;
+    gap: var(--grid-gutter);
+    overflow-x: auto;
+    scroll-snap-type: x mandatory;
+    padding-bottom: var(--space-sm);
+  }
+
+  .media-gallery-rail:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+
+  .media-gallery-rail .media-gallery-item {
+    flex: 0 0 80%;
+    scroll-snap-align: start;
+  }
+
+  @media (min-width: 768px) {
+    .media-gallery-rail .media-gallery-item {
+      flex-basis: 40%;
+    }
+  }
+
+  .media-gallery-figure {
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+  }
+
+  .media-gallery-img {
+    display: block;
+    width: 100%;
+    aspect-ratio: 4 / 3;
+    object-fit: cover;
+    border-radius: var(--card-radius);
+    background: var(--color-surface-secondary);
+  }
+
+  .media-gallery-caption {
+    font-family: var(--type-caption-font);
+    font-size: var(--type-caption-size);
+    color: var(--color-text-muted);
+  }
+</style>

package/components/MediaGallery.svelte.d.ts

@@ -0,0 +1,46 @@
+export default MediaGallery;
+type MediaGallery = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * MediaGallery
+ *
+ * A landing-grade media gallery — a responsive grid (or a horizontal scroll-snap
+ * rail) of captioned images. Distinct from the detail-page image strip: this is
+ * presentational showcase content for landing / campaign / about pages. No JS
+ * carousel/autoplay (an accessibility and reduced-motion liability); on narrow
+ * viewports the `rail` layout becomes a swipeable scroll-snap row that is fully
+ * keyboard-scrollable. Each image carries operator-authored `alt`; captions are
+ * optional `<figcaption>`s.
+ *
+ * @example Grid
+ * <MediaGallery
+ *   heading="Projetos executados"
+ *   items={[
+ *     { src: "/g/parque.jpg", alt: "Novo parque urbano", caption: "Parque da Cidade — 2025" },
+ *     { src: "/g/ciclovia.jpg", alt: "Ciclovia ribeirinha", caption: "Ciclovia — 2024" },
+ *   ]}
+ * />
+ *
+ * @example Horizontal rail
+ * <MediaGallery layout="rail" label="Galeria" items={photos} />
+ */
+declare const MediaGallery: import("svelte").Component<{
+    heading?: string;
+    headingLevel?: number;
+    label?: string;
+    layout?: string;
+    columns?: string;
+    items?: any[];
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    heading?: string;
+    headingLevel?: number;
+    label?: string;
+    layout?: string;
+    columns?: string;
+    items?: any[];
+    class?: string;
+} & Record<string, any>;

package/components/MediaText.svelte

@@ -0,0 +1,143 @@
+<!--
+  @component MediaText
+
+  An image (or video) beside a prose column — the alternating "about / feature"
+  section. Presentational: heading, body, media URL + alt text, and the optional
+  CTA are DATA, so it drops into any vertical. `reverse` flips the media to the
+  other side for the classic zig-zag layout; columns stack on narrow viewports.
+
+  The body slot is the consumer's pre-sanitised rich content (the portal passes
+  sanitised markdown through `bodyHtml`); a plain `body` string is rendered as a
+  paragraph when no HTML is given. The image carries operator-authored `alt`.
+
+  @example
+  <MediaText
+    heading="Orçamento Participativo"
+    body="Os cidadãos decidem como investir parte do orçamento municipal."
+    image="/media/op.jpg"
+    alt="Sessão pública de participação"
+    cta={{ label: "Saber mais", href: "/info/regulamento" }}
+  />
+-->
+<script>
+  import Button from "./Button.svelte";
+
+  let {
+    /** @type {string} */
+    heading = "",
+    /** @type {2 | 3} Heading level for `heading`. */
+    headingLevel = 2,
+    /** @type {string} Plain-text body (used when `bodyHtml`/`children` absent). */
+    body = "",
+    /** @type {string | undefined} Pre-sanitised HTML body (XSS boundary is the consumer). */
+    bodyHtml = undefined,
+    /** @type {string | undefined} Image URL. */
+    image = undefined,
+    /** @type {string} Image alt text (operator data; "" = decorative). */
+    alt = "",
+    /** @type {string | undefined} Video URL (rendered instead of the image). */
+    video = undefined,
+    /** @type {boolean} Place the media on the right (zig-zag). */
+    reverse = false,
+    /** @type {{ label?: string, href?: string } | undefined} */
+    cta = undefined,
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Rich body override. */
+    children = undefined,
+    ...rest
+  } = $props();
+</script>
+
+<section class="media-text {className}" class:media-text-reverse={reverse} {...rest}>
+  <div class="media-text-media">
+    {#if video}
+      <!-- svelte-ignore a11y_media_has_caption -->
+      <video class="media-text-asset" src={video} controls></video>
+    {:else if image}
+      <img class="media-text-asset" src={image} {alt} loading="lazy" />
+    {/if}
+  </div>
+  <div class="media-text-body">
+    {#if heading}
+      <svelte:element this={`h${headingLevel}`} class="media-text-heading"
+        >{heading}</svelte:element
+      >
+    {/if}
+    {#if children}
+      {@render children()}
+    {:else if bodyHtml !== undefined}
+      <!-- eslint-disable-next-line svelte/no-at-html-tags — caller-sanitised -->
+      <div class="media-text-prose">{@html bodyHtml}</div>
+    {:else if body}
+      <p class="media-text-prose">{body}</p>
+    {/if}
+    {#if cta && cta.label}
+      <div class="media-text-cta">
+        <Button href={cta.href || undefined} variant="secondary"
+          >{cta.label}</Button
+        >
+      </div>
+    {/if}
+  </div>
+</section>
+
+<style>
+  .media-text {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: var(--space-xl);
+    align-items: center;
+    overflow-wrap: break-word;
+  }
+
+  @media (min-width: 768px) {
+    .media-text {
+      grid-template-columns: 1fr 1fr;
+      gap: var(--space-3xl);
+    }
+    .media-text-reverse .media-text-media {
+      order: 2;
+    }
+  }
+
+  .media-text-asset {
+    display: block;
+    width: 100%;
+    height: auto;
+    border-radius: var(--card-radius);
+    background: var(--color-surface-secondary);
+  }
+
+  .media-text-body {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+    /* Let the grid column shrink so its prose can wrap a long token. */
+    min-width: 0;
+  }
+
+  .media-text-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);
+  }
+
+  .media-text-prose {
+    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);
+  }
+
+  .media-text-prose :global(p) {
+    margin: 0 0 var(--space-sm);
+  }
+
+  .media-text-cta {
+    margin-top: var(--space-xs);
+  }
+</style>

package/components/MediaText.svelte.d.ts

@@ -0,0 +1,52 @@
+export default MediaText;
+type MediaText = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * MediaText
+ *
+ * An image (or video) beside a prose column — the alternating "about / feature"
+ * section. Presentational: heading, body, media URL + alt text, and the optional
+ * CTA are DATA, so it drops into any vertical. `reverse` flips the media to the
+ * other side for the classic zig-zag layout; columns stack on narrow viewports.
+ *
+ * The body slot is the consumer's pre-sanitised rich content (the portal passes
+ * sanitised markdown through `bodyHtml`); a plain `body` string is rendered as a
+ * paragraph when no HTML is given. The image carries operator-authored `alt`.
+ *
+ * @example
+ * <MediaText
+ *   heading="Orçamento Participativo"
+ *   body="Os cidadãos decidem como investir parte do orçamento municipal."
+ *   image="/media/op.jpg"
+ *   alt="Sessão pública de participação"
+ *   cta={{ label: "Saber mais", href: "/info/regulamento" }}
+ * />
+ */
+declare const MediaText: import("svelte").Component<{
+    heading?: string;
+    headingLevel?: number;
+    body?: string;
+    bodyHtml?: any;
+    image?: any;
+    alt?: string;
+    video?: any;
+    reverse?: boolean;
+    cta?: any;
+    class?: string;
+    children?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    heading?: string;
+    headingLevel?: number;
+    body?: string;
+    bodyHtml?: any;
+    image?: any;
+    alt?: string;
+    video?: any;
+    reverse?: boolean;
+    cta?: any;
+    class?: string;
+    children?: any;
+} & 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>