@aiaiai-pt/design-system 0.8.4 → 0.9.0

package/components/ServiceNavigation.svelte.d.ts

@@ -0,0 +1,49 @@
+export default ServiceNavigation;
+type ServiceNavigation = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * ServiceNavigation
+ *
+ * Primary site navigation for the public portal, modelled on the GOV.UK
+ * "Service navigation" and Designers Italia header-nav patterns (the citizen /
+ * PA gold standard). Data-driven: it owns its `<a>` markup (rendered from
+ * `items`), so it styles its own links — no magic descendant styling of
+ * consumer anchors.
+ *
+ * Accessibility:
+ *  - `<nav aria-label>` landmark; the current item carries `aria-current="page"`.
+ *  - Below `--breakpoint` the list collapses behind a toggle button with
+ *    `aria-expanded` + `aria-controls` (WCAG-friendly disclosure).
+ *  - Empty `items` renders NOTHING — never an empty nav landmark.
+ *  - Toggle + links have visible focus rings.
+ *
+ * @example
+ * <ServiceNavigation
+ *   label="Primary"
+ *   items={[
+ *     { href: "/report", label: "Report a problem" },
+ *     { href: "/track", label: "Track a report", current: true },
+ *     { href: "/info/privacy", label: "Privacy" },
+ *   ]}
+ * >
+ *   {#snippet menuIcon()}<MenuIcon />{/snippet}
+ * </ServiceNavigation>
+ */
+declare const ServiceNavigation: import("svelte").Component<{
+    items?: any[];
+    label?: string;
+    menuId?: string;
+    toggleLabel?: string;
+    class?: string;
+    menuIcon?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    items?: any[];
+    label?: string;
+    menuId?: string;
+    toggleLabel?: string;
+    class?: string;
+    menuIcon?: any;
+} & Record<string, any>;

package/components/SiteFooter.svelte

@@ -0,0 +1,83 @@
+<!--
+  @component SiteFooter
+
+  Public site contentinfo landmark (`<footer role="contentinfo">`). Locked
+  accessibility chrome for the citizen portal — holds legal links, tenant
+  attribution, and secondary navigation. Structure fixed; brand varies via
+  `data-theme`.
+
+  @example
+  <SiteFooter>
+    {#snippet links()}
+      <a href="/info/privacy">Privacy</a>
+      <a href="/info/terms">Terms</a>
+      <a href="/info/accessibility">Accessibility</a>
+    {/snippet}
+    {#snippet meta()}© 2026 Município de Valongo{/snippet}
+  </SiteFooter>
+-->
+<script>
+  let {
+    /** @type {string} aria-label for the footer nav (localize it). */
+    navLabel = "Footer",
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Footer navigation links. */
+    links = undefined,
+    /** @type {import('svelte').Snippet | undefined} Attribution / fine print. */
+    meta = undefined,
+    /** @type {import('svelte').Snippet | undefined} Free-form content (overrides links/meta layout). */
+    children = undefined,
+    ...rest
+  } = $props();
+</script>
+
+<footer class="site-footer {className}" {...rest}>
+  <div class="site-footer-inner">
+    {#if children}
+      {@render children()}
+    {:else}
+      {#if links}
+        <nav class="site-footer-nav" aria-label={navLabel}>{@render links()}</nav>
+      {/if}
+      {#if meta}
+        <p class="site-footer-meta">{@render meta()}</p>
+      {/if}
+    {/if}
+  </div>
+</footer>
+
+<style>
+  .site-footer {
+    background: var(--color-surface-secondary);
+    border-top: 1px solid var(--color-border);
+    color: var(--color-text-secondary);
+  }
+
+  .site-footer-inner {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-md);
+    width: 100%;
+    max-width: var(--content-width-wide);
+    margin-inline: auto;
+    padding: var(--space-xl) var(--content-padding-x);
+  }
+
+  /* The links slot hosts `Link` components (self-styled) — no descendant-anchor
+     magic here either. */
+  .site-footer-nav {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-md);
+  }
+
+  .site-footer-meta {
+    margin: 0;
+    font-family: var(--type-caption-font);
+    font-size: var(--type-caption-size);
+    color: var(--color-text-muted);
+  }
+</style>

package/components/SiteFooter.svelte.d.ts

@@ -0,0 +1,37 @@
+export default SiteFooter;
+type SiteFooter = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * SiteFooter
+ *
+ * Public site contentinfo landmark (`<footer role="contentinfo">`). Locked
+ * accessibility chrome for the citizen portal — holds legal links, tenant
+ * attribution, and secondary navigation. Structure fixed; brand varies via
+ * `data-theme`.
+ *
+ * @example
+ * <SiteFooter>
+ *   {#snippet links()}
+ *     <a href="/info/privacy">Privacy</a>
+ *     <a href="/info/terms">Terms</a>
+ *     <a href="/info/accessibility">Accessibility</a>
+ *   {/snippet}
+ *   {#snippet meta()}© 2026 Município de Valongo{/snippet}
+ * </SiteFooter>
+ */
+declare const SiteFooter: import("svelte").Component<{
+    navLabel?: string;
+    class?: string;
+    links?: any;
+    meta?: any;
+    children?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    navLabel?: string;
+    class?: string;
+    links?: any;
+    meta?: any;
+    children?: any;
+} & Record<string, any>;

package/components/SiteHeader.svelte

@@ -0,0 +1,90 @@
+<!--
+  @component SiteHeader
+
+  Public site banner landmark (`<header role="banner">`). Locked accessibility
+  chrome for the citizen portal: a brand area, a primary navigation slot, and
+  an actions slot (locale switch, sign-in). Structure and landmarks are fixed
+  (conformance-checkable); only brand tokens vary per tenant via `data-theme`.
+
+  Icon-agnostic, per DS convention — pass icons/logo as snippets.
+
+  @example
+  <SiteHeader>
+    {#snippet brand()}<a href="/"><Logo /> Valongo</a>{/snippet}
+    {#snippet nav()}<ServiceNavigation items={navItems} />{/snippet}
+    {#snippet actions()}<LocaleSwitch /> <Button>Sign in</Button>{/snippet}
+  </SiteHeader>
+-->
+<script>
+  let {
+    /** @type {string} aria-label for the primary nav (localize it). */
+    navLabel = "Primary",
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Brand / logo area. */
+    brand = undefined,
+    /** @type {import('svelte').Snippet | undefined} Primary navigation links. */
+    nav = undefined,
+    /** @type {import('svelte').Snippet | undefined} Trailing actions (locale, auth). */
+    actions = undefined,
+    ...rest
+  } = $props();
+</script>
+
+<header class="site-header {className}" {...rest}>
+  <div class="site-header-inner">
+    {#if brand}
+      <div class="site-header-brand">{@render brand()}</div>
+    {/if}
+    {#if nav}
+      <nav class="site-header-nav" aria-label={navLabel}>{@render nav()}</nav>
+    {/if}
+    {#if actions}
+      <div class="site-header-actions">{@render actions()}</div>
+    {/if}
+  </div>
+</header>
+
+<style>
+  .site-header {
+    position: sticky;
+    top: 0;
+    z-index: 40;
+    background: var(--color-surface);
+    border-bottom: 1px solid var(--color-border);
+  }
+
+  .site-header-inner {
+    display: flex;
+    align-items: center;
+    gap: var(--space-lg);
+    width: 100%;
+    max-width: var(--content-width-wide);
+    margin-inline: auto;
+    padding: var(--space-sm) var(--content-padding-x);
+  }
+
+  .site-header-brand {
+    display: flex;
+    align-items: center;
+    gap: var(--space-xs);
+    font-family: var(--type-heading-sm-font);
+    font-size: var(--type-heading-sm-size);
+    color: var(--color-text);
+  }
+
+  /* The nav slot hosts a `ServiceNavigation` (data-driven, self-styled).
+     The header doesn't style anchors itself — no descendant-anchor magic. */
+  .site-header-nav {
+    display: flex;
+    align-items: center;
+  }
+
+  /* Push trailing actions to the far end regardless of nav presence. */
+  .site-header-actions {
+    display: flex;
+    align-items: center;
+    gap: var(--space-sm);
+    margin-inline-start: auto;
+  }
+</style>

package/components/SiteHeader.svelte.d.ts

@@ -0,0 +1,36 @@
+export default SiteHeader;
+type SiteHeader = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * SiteHeader
+ *
+ * Public site banner landmark (`<header role="banner">`). Locked accessibility
+ * chrome for the citizen portal: a brand area, a primary navigation slot, and
+ * an actions slot (locale switch, sign-in). Structure and landmarks are fixed
+ * (conformance-checkable); only brand tokens vary per tenant via `data-theme`.
+ *
+ * Icon-agnostic, per DS convention — pass icons/logo as snippets.
+ *
+ * @example
+ * <SiteHeader>
+ *   {#snippet brand()}<a href="/"><Logo /> Valongo</a>{/snippet}
+ *   {#snippet nav()}<a href="/report">Report</a><a href="/info/privacy">Privacy</a>{/snippet}
+ *   {#snippet actions()}<LocaleSwitch /> <Button>Sign in</Button>{/snippet}
+ * </SiteHeader>
+ */
+declare const SiteHeader: import("svelte").Component<{
+    navLabel?: string;
+    class?: string;
+    brand?: any;
+    nav?: any;
+    actions?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    navLabel?: string;
+    class?: string;
+    brand?: any;
+    nav?: any;
+    actions?: any;
+} & Record<string, any>;

package/components/SkipLink.svelte

@@ -0,0 +1,63 @@
+<!--
+  @component SkipLink
+
+  Accessibility skip-to-content link — the first focusable element on a page.
+  Visually hidden until focused, then slides into view. Lets keyboard and
+  screen-reader users bypass repeated header/nav landmarks and jump straight
+  to the main content (WCAG 2.4.1 Bypass Blocks). Part of the locked public
+  site-shell chrome; `AppFrame` renders one automatically.
+
+  The target must be a focusable element (e.g. `<main id="main" tabindex="-1">`,
+  which `AppFrame` provides).
+
+  @example Default (targets #main)
+  <SkipLink />
+
+  @example Custom target + localized label
+  <SkipLink href="#content">{m.skip_to_content()}</SkipLink>
+-->
+<script>
+  let {
+    /** @type {string} Fragment id of the main-content target. */
+    href = "#main",
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Override the default label (for i18n). */
+    children = undefined,
+    ...rest
+  } = $props();
+</script>
+
+<a class="skip-link {className}" {href} {...rest}>
+  {#if children}{@render children()}{:else}Skip to main content{/if}
+</a>
+
+<style>
+  .skip-link {
+    position: absolute;
+    left: var(--space-sm);
+    /* Off-screen until focused — kept in the DOM + tab order, not display:none. */
+    top: calc(-1 * var(--space-4xl) - var(--space-lg));
+    z-index: 100;
+    padding: var(--space-2xs) var(--space-sm);
+    background: var(--color-accent);
+    color: var(--color-text-on-accent);
+    font-family: var(--type-label-font);
+    font-size: var(--type-label-size);
+    text-decoration: none;
+    border-radius: var(--radius-md);
+    transition: top 150ms ease-out;
+  }
+
+  .skip-link:focus-visible {
+    top: var(--space-sm);
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .skip-link {
+      transition: none;
+    }
+  }
+</style>

package/components/SkipLink.svelte.d.ts

@@ -0,0 +1,33 @@
+export default SkipLink;
+type SkipLink = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * SkipLink
+ *
+ * Accessibility skip-to-content link — the first focusable element on a page.
+ * Visually hidden until focused, then slides into view. Lets keyboard and
+ * screen-reader users bypass repeated header/nav landmarks and jump straight
+ * to the main content (WCAG 2.4.1 Bypass Blocks). Part of the locked public
+ * site-shell chrome; `AppFrame` renders one automatically.
+ *
+ * The target must be a focusable element (e.g. `<main id="main" tabindex="-1">`,
+ * which `AppFrame` provides).
+ *
+ * @example Default (targets #main)
+ * <SkipLink />
+ *
+ * @example Custom target + localized label
+ * <SkipLink href="#content">{m.skip_to_content()}</SkipLink>
+ */
+declare const SkipLink: import("svelte").Component<{
+    href?: string;
+    class?: string;
+    children?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    href?: string;
+    class?: string;
+    children?: any;
+} & Record<string, any>;

package/components/StatusTimeline.svelte

@@ -0,0 +1,193 @@
+<!--
+  @component StatusTimeline
+
+  Ordered, accessibility-first progress timeline for the citizen portal — the
+  `tracker` page template's spine (a submission moving submitted → triaged →
+  in-progress → resolved). Renders an `<ol>` so the sequence and position are
+  conveyed structurally, with the active step carrying `aria-current="step"`.
+
+  Each step's state (complete / current / upcoming) is announced to assistive
+  tech via a visually-hidden label — pass `stateLabels` to localise it (the
+  portal feeds Wuchale strings here). Purely structural: no motion, so it is
+  reduced-motion-safe by construction.
+
+  @example
+  <StatusTimeline
+    label="Report progress"
+    steps={[
+      { label: "Submitted", status: "complete", timestamp: "12 May" },
+      { label: "Under review", status: "complete", timestamp: "13 May" },
+      { label: "In progress", status: "current", description: "Crew assigned" },
+      { label: "Resolved", status: "upcoming" },
+    ]}
+  />
+
+  @example Localised state labels (portal i18n)
+  <StatusTimeline steps={steps} stateLabels={{ complete: "Concluído", current: "Atual", upcoming: "Pendente" }} />
+-->
+<script>
+  /**
+   * @typedef {'complete' | 'current' | 'upcoming'} StepStatus
+   * @typedef {{ label: string, status?: StepStatus, description?: string, timestamp?: string }} Step
+   */
+
+  let {
+    /** @type {Step[]} Ordered steps, earliest first. */
+    steps = [],
+    /** @type {string} Accessible name for the timeline list (localize it). */
+    label = "Progress",
+    /**
+     * @type {Record<StepStatus, string>}
+     * Visually-hidden state text announced per step (localize it).
+     */
+    stateLabels = {
+      complete: "Completed",
+      current: "Current step",
+      upcoming: "Upcoming",
+    },
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+
+  /** @param {Step} step @returns {StepStatus} */
+  const statusOf = (step) => step.status ?? "upcoming";
+</script>
+
+{#if steps.length > 0}
+  <ol class="status-timeline {className}" aria-label={label} {...rest}>
+    {#each steps as step, i (i)}
+      {@const status = statusOf(step)}
+      <li
+        class="status-timeline-item status-timeline-item-{status}"
+        aria-current={status === "current" ? "step" : undefined}
+      >
+        <span class="status-timeline-marker" aria-hidden="true">
+          <span class="status-timeline-node"></span>
+        </span>
+        <div class="status-timeline-body">
+          <span class="status-timeline-label">
+            <span class="status-timeline-state">{stateLabels[status]}: </span>
+            {step.label}
+          </span>
+          {#if step.timestamp}
+            <span class="status-timeline-time">{step.timestamp}</span>
+          {/if}
+          {#if step.description}
+            <p class="status-timeline-desc">{step.description}</p>
+          {/if}
+        </div>
+      </li>
+    {/each}
+  </ol>
+{/if}
+
+<style>
+  .status-timeline {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .status-timeline-item {
+    position: relative;
+    display: grid;
+    grid-template-columns: auto 1fr;
+    gap: var(--space-md);
+    padding-bottom: var(--space-lg);
+  }
+  .status-timeline-item:last-child {
+    padding-bottom: 0;
+  }
+
+  /* Connector line down the marker column, drawn behind the nodes. It stops at
+     the last node so the line never dangles past the final step. */
+  .status-timeline-marker {
+    position: relative;
+    display: flex;
+    justify-content: center;
+    width: var(--space-md);
+  }
+  .status-timeline-item:not(:last-child) .status-timeline-marker::before {
+    content: "";
+    position: absolute;
+    top: var(--space-md);
+    bottom: calc(-1 * var(--space-lg));
+    inset-inline-start: 50%;
+    transform: translateX(-50%);
+    width: var(--border-width-thick);
+    background: var(--color-border);
+  }
+  /* A completed step's connector is filled to show progress reaching the next. */
+  .status-timeline-item-complete:not(:last-child) .status-timeline-marker::before {
+    background: var(--color-accent);
+  }
+
+  .status-timeline-node {
+    position: relative;
+    z-index: 1;
+    width: var(--space-md);
+    height: var(--space-md);
+    border-radius: var(--radius-circle);
+    background: var(--color-surface);
+    box-shadow: inset 0 0 0 var(--border-width-thick) var(--color-border);
+  }
+  .status-timeline-item-complete .status-timeline-node {
+    background: var(--color-accent);
+    box-shadow: inset 0 0 0 var(--border-width-thick) var(--color-accent);
+  }
+  .status-timeline-item-current .status-timeline-node {
+    background: var(--color-surface);
+    box-shadow:
+      inset 0 0 0 var(--border-width-thick) var(--color-accent),
+      0 0 0 var(--border-width-thick) var(--color-accent-subtle);
+  }
+
+  .status-timeline-body {
+    padding-top: calc((var(--space-md) - 1em) / 2);
+    min-width: 0;
+  }
+
+  .status-timeline-label {
+    font-family: var(--type-label-font);
+    font-size: var(--type-label-size);
+    color: var(--color-text-secondary);
+  }
+  .status-timeline-item-current .status-timeline-label,
+  .status-timeline-item-complete .status-timeline-label {
+    color: var(--color-text);
+  }
+  .status-timeline-item-current .status-timeline-label {
+    font-weight: var(--raw-font-weight-semibold);
+  }
+
+  /* State text is for assistive tech only — the visual node carries it sighted. */
+  .status-timeline-state {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  .status-timeline-time {
+    display: block;
+    margin-top: var(--space-2xs);
+    font-family: var(--type-caption-font);
+    font-size: var(--type-caption-size);
+    color: var(--color-text-muted);
+  }
+
+  .status-timeline-desc {
+    margin: var(--space-2xs) 0 0;
+    font-family: var(--type-body-sm-font);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-secondary);
+  }
+</style>

package/components/StatusTimeline.svelte.d.ts

@@ -0,0 +1,44 @@
+export default StatusTimeline;
+type StatusTimeline = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * StatusTimeline
+ *
+ * Ordered, accessibility-first progress timeline for the citizen portal — the
+ * `tracker` page template's spine (a submission moving submitted → triaged →
+ * in-progress → resolved). Renders an `<ol>` so the sequence and position are
+ * conveyed structurally, with the active step carrying `aria-current="step"`.
+ *
+ * Each step's state (complete / current / upcoming) is announced to assistive
+ * tech via a visually-hidden label — pass `stateLabels` to localise it (the
+ * portal feeds Wuchale strings here). Purely structural: no motion, so it is
+ * reduced-motion-safe by construction.
+ *
+ * @example
+ * <StatusTimeline
+ *   label="Report progress"
+ *   steps={[
+ *     { label: "Submitted", status: "complete", timestamp: "12 May" },
+ *     { label: "Under review", status: "complete", timestamp: "13 May" },
+ *     { label: "In progress", status: "current", description: "Crew assigned" },
+ *     { label: "Resolved", status: "upcoming" },
+ *   ]}
+ * />
+ *
+ * @example Localised state labels (portal i18n)
+ * <StatusTimeline steps={steps} stateLabels={{ complete: "Concluído", current: "Atual", upcoming: "Pendente" }} />
+ */
+declare const StatusTimeline: import("svelte").Component<{
+    steps?: any[];
+    label?: string;
+    stateLabels?: Record<string, any>;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    steps?: any[];
+    label?: string;
+    stateLabels?: Record<string, any>;
+    class?: string;
+} & Record<string, any>;