@aiaiai-pt/design-system 0.8.4 → 0.10.0

package/components/ContentBlock.svelte

@@ -0,0 +1,100 @@
+<!--
+  @component ContentBlock
+
+  Prose container for documentation / legal / content pages (privacy, terms,
+  accessibility, regulamento — the `content` page template). Applies readable
+  measure + typographic rhythm to long-form content, with an optional title
+  and a version/date badge slot.
+
+  SECURITY: ContentBlock only STYLES its children — it does not parse or
+  sanitise. A consumer rendering operator-authored markdown/HTML MUST sanitise
+  before injecting it (XSS); pass the sanitised result as `children`.
+
+  @example
+  <ContentBlock title="Privacy Policy">
+    {#snippet badge()}<Badge>v3 · updated 2026-05-01</Badge>{/snippet}
+    {@html sanitizedHtml}
+  </ContentBlock>
+-->
+<script>
+  let {
+    /** @type {string} Page title (rendered as h1 — keep one per page). */
+    title = "",
+    /** @type {1 | 2} Heading level for `title`. */
+    headingLevel = 1,
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Version / date badge. */
+    badge = undefined,
+    /** @type {import('svelte').Snippet | undefined} The (pre-sanitised) prose. */
+    children = undefined,
+    ...rest
+  } = $props();
+</script>
+
+<article class="content-block {className}" {...rest}>
+  {#if title}
+    <header class="content-block-head">
+      <svelte:element this={`h${headingLevel}`} class="content-block-title">{title}</svelte:element>
+      {#if badge}<div class="content-block-badge">{@render badge()}</div>{/if}
+    </header>
+  {/if}
+  <div class="content-block-prose">
+    {#if children}{@render children()}{/if}
+  </div>
+</article>
+
+<style>
+  .content-block {
+    width: 100%;
+    max-width: var(--content-width-narrow);
+    margin-inline: auto;
+    padding: var(--space-2xl) var(--content-padding-x);
+  }
+
+  .content-block-head {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    gap: var(--space-sm);
+    margin-bottom: var(--space-lg);
+  }
+
+  .content-block-title {
+    margin: 0;
+    font-family: var(--type-heading-lg-font);
+    font-size: var(--type-heading-lg-size);
+    color: var(--color-text);
+  }
+
+  /* Long-form rhythm. Scoped to descendants since prose is consumer-injected
+     (:global needed — these elements aren't in this component's own markup). */
+  .content-block-prose {
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text);
+    line-height: 1.6;
+  }
+
+  .content-block-prose :global(h2) {
+    font-family: var(--type-heading-font);
+    font-size: var(--type-heading-size);
+    margin: var(--space-xl) 0 var(--space-sm);
+  }
+
+  .content-block-prose :global(h3) {
+    font-family: var(--type-heading-sm-font);
+    font-size: var(--type-heading-sm-size);
+    margin: var(--space-lg) 0 var(--space-xs);
+  }
+
+  .content-block-prose :global(p),
+  .content-block-prose :global(ul),
+  .content-block-prose :global(ol) {
+    margin: 0 0 var(--space-md);
+  }
+
+  .content-block-prose :global(a) {
+    color: var(--color-accent);
+  }
+</style>

package/components/ContentBlock.svelte.d.ts

@@ -0,0 +1,37 @@
+export default ContentBlock;
+type ContentBlock = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * ContentBlock
+ *
+ * Prose container for documentation / legal / content pages (privacy, terms,
+ * accessibility, regulamento — the `content` page template). Applies readable
+ * measure + typographic rhythm to long-form content, with an optional title
+ * and a version/date badge slot.
+ *
+ * SECURITY: ContentBlock only STYLES its children — it does not parse or
+ * sanitise. A consumer rendering operator-authored markdown/HTML MUST sanitise
+ * before injecting it (XSS); pass the sanitised result as `children`.
+ *
+ * @example
+ * <ContentBlock title="Privacy Policy">
+ *   {#snippet badge()}<Badge>v3 · updated 2026-05-01</Badge>{/snippet}
+ *   {@html sanitizedHtml}
+ * </ContentBlock>
+ */
+declare const ContentBlock: import("svelte").Component<{
+    title?: string;
+    headingLevel?: number;
+    class?: string;
+    badge?: any;
+    children?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    title?: string;
+    headingLevel?: number;
+    class?: string;
+    badge?: any;
+    children?: any;
+} & Record<string, any>;

package/components/Hero.svelte

@@ -0,0 +1,87 @@
+<!--
+  @component Hero
+
+  Landing / page hero. Renders the page's primary heading (an `<h1>` by
+  default — keep exactly one per page for the single-H1 a11y contract), an
+  optional subtitle, and an actions slot. Use at the top of `landing` and
+  `service-flow` page templates.
+
+  @example
+  <Hero title="Report a problem in Valongo" subtitle="Potholes, lighting, waste — in two minutes.">
+    {#snippet actions()}<Button href="/report">Start a report</Button>{/snippet}
+  </Hero>
+
+  @example Custom heading level (when the hero is not the page's H1)
+  <Hero title="Latest consultations" headingLevel={2} />
+-->
+<script>
+  let {
+    /** @type {string} */
+    title = "",
+    /** @type {string} */
+    subtitle = "",
+    /** @type {1 | 2 | 3} Heading level for `title` — keep one h1 per page. */
+    headingLevel = 1,
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Title override (rich content). */
+    children = undefined,
+    /** @type {import('svelte').Snippet | undefined} Call-to-action buttons. */
+    actions = undefined,
+    ...rest
+  } = $props();
+</script>
+
+<section class="hero {className}" {...rest}>
+  <div class="hero-inner">
+    {#if children}
+      {@render children()}
+    {:else if title}
+      <svelte:element this={`h${headingLevel}`} class="hero-title">{title}</svelte:element>
+    {/if}
+    {#if subtitle}
+      <p class="hero-subtitle">{subtitle}</p>
+    {/if}
+    {#if actions}
+      <div class="hero-actions">{@render actions()}</div>
+    {/if}
+  </div>
+</section>
+
+<style>
+  .hero {
+    background: var(--color-surface);
+  }
+
+  .hero-inner {
+    width: 100%;
+    max-width: var(--content-width-wide);
+    margin-inline: auto;
+    padding: var(--space-3xl) var(--content-padding-x);
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .hero-title {
+    margin: 0;
+    font-family: var(--type-display-font);
+    font-size: var(--type-display-size);
+    color: var(--color-text);
+  }
+
+  .hero-subtitle {
+    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);
+  }
+
+  .hero-actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-sm);
+    margin-top: var(--space-sm);
+  }
+</style>

package/components/Hero.svelte.d.ts

@@ -0,0 +1,37 @@
+export default Hero;
+type Hero = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * Hero
+ *
+ * Landing / page hero. Renders the page's primary heading (an `<h1>` by
+ * default — keep exactly one per page for the single-H1 a11y contract), an
+ * optional subtitle, and an actions slot. Use at the top of `landing` and
+ * `service-flow` page templates.
+ *
+ * @example
+ * <Hero title="Report a problem in Valongo" subtitle="Potholes, lighting, waste — in two minutes.">
+ *   {#snippet actions()}<Button href="/report">Start a report</Button>{/snippet}
+ * </Hero>
+ *
+ * @example Custom heading level (when the hero is not the page's H1)
+ * <Hero title="Latest consultations" headingLevel={2} />
+ */
+declare const Hero: import("svelte").Component<{
+    title?: string;
+    subtitle?: string;
+    headingLevel?: number;
+    class?: string;
+    children?: any;
+    actions?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    title?: string;
+    subtitle?: string;
+    headingLevel?: number;
+    class?: string;
+    children?: any;
+    actions?: any;
+} & Record<string, any>;

package/components/LayoutCompactMobile.svelte

@@ -0,0 +1,72 @@
+<script lang="ts">
+  /**
+   * Compact-mobile layout (#27 / S7).
+   *
+   * Sections collapse into a single tight column with reduced padding
+   * and smaller meta. Used by `public_submit` placements that target
+   * narrow viewports (citizen mobile portal). Structurally a single
+   * column like stacked-default, but distinguishable by reduced gap +
+   * absent section card chrome — section labels become inline headings
+   * so the form reads denser on mobile.
+   */
+  import type { LayoutSection } from "./action-form-renderer-layouts";
+  import type { Snippet } from "svelte";
+
+  let {
+    sections,
+    field,
+  }: {
+    sections: LayoutSection[];
+    field: Snippet<[Record<string, unknown>]>;
+  } = $props();
+</script>
+
+<div class="layout-compact" data-layout-shape="compact">
+  {#each sections as section (section.name)}
+    <section class="compact-section" aria-label={section.name}>
+      <h5>{section.name}</h5>
+      {#each section.items as parameter}
+        <div class="field-row">
+          {@render field(parameter)}
+        </div>
+      {/each}
+    </section>
+  {/each}
+</div>
+
+<style>
+  /* Single tight column — distinguishable from stacked-default by:
+     1. No Card chrome around sections (HTML <section>, not DS Card),
+     2. Compact gap and padding,
+     3. <h5> heading not <h4>. */
+  .layout-compact {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+  }
+
+  .compact-section {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+    padding: var(--space-xs) 0;
+    border-bottom: var(--elevation-border);
+  }
+
+  .compact-section:last-child {
+    border-bottom: 0;
+  }
+
+  .compact-section h5 {
+    margin: 0;
+    font-size: var(--type-caption-size);
+    /* #63 typography — uppercase reserved for code tokens. */
+    color: var(--color-text-muted);
+  }
+
+  .field-row {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+  }
+</style>

package/components/LayoutCompactMobile.svelte.d.ts

@@ -0,0 +1,19 @@
+/**
+   * Compact-mobile layout (#27 / S7).
+   *
+   * Sections collapse into a single tight column with reduced padding
+   * and smaller meta. Used by `public_submit` placements that target
+   * narrow viewports (citizen mobile portal). Structurally a single
+   * column like stacked-default, but distinguishable by reduced gap +
+   * absent section card chrome — section labels become inline headings
+   * so the form reads denser on mobile.
+   */
+import type { LayoutSection } from "./action-form-renderer-layouts";
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    sections: LayoutSection[];
+    field: Snippet<[Record<string, unknown>]>;
+};
+declare const LayoutCompactMobile: import("svelte").Component<$$ComponentProps, {}, "">;
+type LayoutCompactMobile = ReturnType<typeof LayoutCompactMobile>;
+export default LayoutCompactMobile;

package/components/LayoutInlineRow.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+  /**
+   * Inline-row layout (#27 / S7).
+   *
+   * Parameters in each section are arranged in a single horizontal row
+   * using auto-fit grid, suitable for compact admin runtime forms
+   * (one-line filters, narrow inline panels). This is structurally
+   * distinct from stacked-default — same parameter set produces a grid
+   * with multiple columns instead of a vertical column. The S7
+   * acceptance asserts the structural difference.
+   */
+  import Card from "./Card.svelte";
+  import type { LayoutSection } from "./action-form-renderer-layouts";
+  import type { Snippet } from "svelte";
+
+  let {
+    sections,
+    field,
+  }: {
+    sections: LayoutSection[];
+    field: Snippet<[Record<string, unknown>]>;
+  } = $props();
+</script>
+
+<div class="layout-inline" data-layout-shape="inline">
+  {#each sections as section (section.name)}
+    <Card variant="flat" class="section" role="group" aria-label={section.name}>
+      <h4>{section.name}</h4>
+      <div class="row">
+        {#each section.items as parameter}
+          <div class="field-cell">
+            {@render field(parameter)}
+          </div>
+        {/each}
+      </div>
+    </Card>
+  {/each}
+</div>
+
+<style>
+  .layout-inline {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .layout-inline :global(.section) {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+  }
+
+  /* The defining shape — auto-fit columns, NOT a vertical stack. The
+     same parameter set renders as a multi-column grid here vs. one
+     column in stacked-default. */
+  .row {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
+    gap: var(--space-md);
+    align-items: end;
+  }
+
+  .field-cell {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+    min-width: 0;
+  }
+
+  h4 {
+    margin: 0;
+    font-size: var(--type-body-size);
+  }
+</style>

package/components/LayoutInlineRow.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { LayoutSection } from "./action-form-renderer-layouts";
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    sections: LayoutSection[];
+    field: Snippet<[Record<string, unknown>]>;
+};
+declare const LayoutInlineRow: import("svelte").Component<$$ComponentProps, {}, "">;
+type LayoutInlineRow = ReturnType<typeof LayoutInlineRow>;
+export default LayoutInlineRow;

package/components/LayoutStackedDefault.svelte

@@ -0,0 +1,66 @@
+<script lang="ts">
+  /**
+   * Default vertical-stack layout for the action renderer (#27 / S7).
+   *
+   * Each section is a labelled <fieldset>, parameters laid out as a
+   * single-column flex column. This is the safe fallback for unknown
+   * layout keys — see `resolve.ts`.
+   */
+  import Card from "./Card.svelte";
+  import type { LayoutSection } from "./action-form-renderer-layouts";
+  import type { Snippet } from "svelte";
+
+  let {
+    sections,
+    field,
+  }: {
+    sections: LayoutSection[];
+    field: Snippet<[Record<string, unknown>]>;
+  } = $props();
+</script>
+
+<div class="layout-stacked" data-layout-shape="stacked">
+  {#each sections as section (section.name)}
+    <Card variant="flat" class="section" role="group" aria-label={section.name}>
+      <h4>{section.name}</h4>
+      <div class="rows">
+        {#each section.items as parameter}
+          <div class="field-row">
+            {@render field(parameter)}
+          </div>
+        {/each}
+      </div>
+    </Card>
+  {/each}
+</div>
+
+<style>
+  .layout-stacked {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .layout-stacked :global(.section) {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+  }
+
+  .rows {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .field-row {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+  }
+
+  h4 {
+    margin: 0;
+    font-size: var(--type-body-size);
+  }
+</style>

package/components/LayoutStackedDefault.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { LayoutSection } from "./action-form-renderer-layouts";
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    sections: LayoutSection[];
+    field: Snippet<[Record<string, unknown>]>;
+};
+declare const LayoutStackedDefault: import("svelte").Component<$$ComponentProps, {}, "">;
+type LayoutStackedDefault = ReturnType<typeof LayoutStackedDefault>;
+export default LayoutStackedDefault;

package/components/Link.svelte

@@ -0,0 +1,100 @@
+<!--
+  @component Link
+
+  A text hyperlink. Two variants, following the Carbon convention:
+   - `inline` (default): used inside sentences/prose — always underlined so it's
+     distinguishable from surrounding text.
+   - `standalone`: used on its own after content (lists, CTAs, footers) —
+     underlined only on hover/focus.
+
+  Accessibility:
+   - A link with no (or empty) `href` is NOT a link — it renders a
+     non-interactive `<span aria-current="page">` (the canonical "you are here"
+     treatment) instead of a keyboard-trap `<a>` with no destination.
+   - `external` adds `target="_blank"` + `rel="noopener noreferrer"`.
+   - Visible focus ring on `:focus-visible`.
+
+  @example Inline (prose)
+  Read our <Link href="/info/privacy">privacy policy</Link>.
+
+  @example Standalone CTA
+  <Link href="/report" variant="standalone">Report a problem</Link>
+
+  @example Current page (no href → rendered as non-interactive)
+  <Link current>Home</Link>
+-->
+<script>
+  let {
+    /** @type {string | undefined} Destination. Falsy → rendered as a non-interactive span. */
+    href = undefined,
+    /** @type {'inline' | 'standalone'} */
+    variant = "inline",
+    /** @type {boolean} Marks the current page (`aria-current="page"`). */
+    current = false,
+    /** @type {boolean} Open in a new tab with safe rel. */
+    external = false,
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} */
+    children = undefined,
+    ...rest
+  } = $props();
+
+  const isLink = $derived(typeof href === "string" && href.length > 0);
+  const externalAttrs = $derived(
+    external ? { target: "_blank", rel: "noopener noreferrer" } : {},
+  );
+</script>
+
+{#if isLink}
+  <a
+    {href}
+    class="link link-{variant} {className}"
+    aria-current={current ? "page" : undefined}
+    {...externalAttrs}
+    {...rest}
+  >
+    {#if children}{@render children()}{/if}
+  </a>
+{:else}
+  <!-- No destination → not a link. Non-interactive, still announces "current". -->
+  <span class="link link-{variant} link-static {className}" aria-current={current ? "page" : undefined} {...rest}>
+    {#if children}{@render children()}{/if}
+  </span>
+{/if}
+
+<style>
+  .link {
+    color: var(--color-accent);
+    border-radius: var(--radius-sm);
+  }
+
+  .link-inline {
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+  }
+
+  .link-standalone {
+    text-decoration: none;
+  }
+  .link-standalone:hover {
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+  }
+
+  a.link:hover {
+    color: var(--color-accent-hover);
+  }
+
+  a.link:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+
+  /* Non-interactive (current/no-href): inherit text colour, no affordance. */
+  .link-static {
+    color: var(--color-text);
+    text-decoration: none;
+    cursor: default;
+  }
+</style>

package/components/Link.svelte.d.ts

@@ -0,0 +1,46 @@
+export default Link;
+type Link = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * Link
+ *
+ * A text hyperlink. Two variants, following the Carbon convention:
+ *  - `inline` (default): used inside sentences/prose — always underlined so it's
+ *    distinguishable from surrounding text.
+ *  - `standalone`: used on its own after content (lists, CTAs, footers) —
+ *    underlined only on hover/focus.
+ *
+ * Accessibility:
+ *  - A link with no (or empty) `href` is NOT a link — it renders a
+ *    non-interactive `<span aria-current="page">` (the canonical "you are here"
+ *    treatment) instead of a keyboard-trap `<a>` with no destination.
+ *  - `external` adds `target="_blank"` + `rel="noopener noreferrer"`.
+ *  - Visible focus ring on `:focus-visible`.
+ *
+ * @example Inline (prose)
+ * Read our <Link href="/info/privacy">privacy policy</Link>.
+ *
+ * @example Standalone CTA
+ * <Link href="/report" variant="standalone">Report a problem</Link>
+ *
+ * @example Current page (no href → rendered as non-interactive)
+ * <Link current>Home</Link>
+ */
+declare const Link: import("svelte").Component<{
+    href?: any;
+    variant?: string;
+    current?: boolean;
+    external?: boolean;
+    class?: string;
+    children?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    href?: any;
+    variant?: string;
+    current?: boolean;
+    external?: boolean;
+    class?: string;
+    children?: any;
+} & Record<string, any>;