@aiaiai-pt/design-system 0.41.0 → 0.43.0

package/components/MegaMenu.svelte

@@ -0,0 +1,247 @@
+<!--
+  @component MegaMenu
+
+  Category mega-menu for many-section portals (#507): a single "Services ▾"
+  disclosure in the primary band that opens a full-width panel of category
+  columns, so ~20 verticals collapse into one trigger instead of overflowing
+  the bar. Modelled on the GOV.UK "Menu" / Designers Italia mega-nav pattern.
+
+  Semantics: a disclosure (`button[aria-expanded][aria-controls]` + panel),
+  NOT a `menu` role — the panel holds plain links in labelled groups, which
+  screen readers navigate as ordinary lists. Escape closes and restores focus
+  to the trigger; clicking outside or navigating closes. The trigger reads as
+  current (underline bar) when any contained link is current.
+
+  Desktop-only affordance: below `--breakpoint` it renders nothing — small
+  screens keep their native menu (SiteHeader's unified disclosure), which the
+  consumer feeds the same category groups.
+
+  Layout note: the panel is absolutely positioned against the NEAREST
+  POSITIONED ANCESTOR — inside `SiteHeader` (position: sticky) it spans the
+  full header band, which is the intended composition:
+
+  @example
+  <SiteHeader>
+    {#snippet nav()}
+      <ServiceNavigation label="Primary" items={primary} />
+      <MegaMenu label="Serviços" categories={buckets} />
+    {/snippet}
+  </SiteHeader>
+-->
+<script>
+  let {
+    /** @type {string} Visible trigger label (localize it). */
+    label = "Services",
+    /** @type {Array<{ label: string, items: Array<{ href: string, label: string, current?: boolean }> }>} */
+    categories = [],
+    /** @type {string} id linking the trigger to the panel (unique per page). */
+    menuId = "mega-menu",
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Trigger icon (chevron). */
+    icon = undefined,
+    ...rest
+  } = $props();
+
+  let open = $state(false);
+  /** @type {HTMLElement | undefined} */
+  let root = $state(undefined);
+  /** @type {HTMLButtonElement | undefined} */
+  let trigger = $state(undefined);
+
+  const hasCurrent = $derived(
+    categories.some((c) => (c.items ?? []).some((i) => i.current)),
+  );
+
+  function onDocumentClick(event) {
+    if (open && root && !root.contains(event.target)) open = false;
+  }
+  function onDocumentKeydown(event) {
+    if (event.key === "Escape" && open) {
+      open = false;
+      trigger?.focus();
+    }
+  }
+</script>
+
+{#if categories.length > 0}
+  <div class="mega-menu {className}" bind:this={root} {...rest}>
+    <button
+      type="button"
+      class="mega-menu-trigger"
+      class:current={hasCurrent}
+      aria-expanded={open}
+      aria-controls={menuId}
+      bind:this={trigger}
+      onclick={() => (open = !open)}
+    >
+      {label}
+      {#if icon}{@render icon()}{:else}
+        <svg
+          class="mega-menu-chevron"
+          class:open
+          viewBox="0 0 16 16"
+          aria-hidden="true"
+        >
+          <path
+            d="M4 6l4 4 4-4"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="1.5"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          />
+        </svg>
+      {/if}
+    </button>
+
+    {#if open}
+      <div id={menuId} class="mega-menu-panel">
+        {#each categories as category (category.label)}
+          <section class="mega-menu-category" aria-label={category.label}>
+            <h3 class="mega-menu-heading">{category.label}</h3>
+            <ul class="mega-menu-list">
+              {#each category.items ?? [] as item (item.href)}
+                <li class="mega-menu-item">
+                  <a
+                    href={item.href}
+                    class="mega-menu-link"
+                    aria-current={item.current ? "page" : undefined}
+                    onclick={() => (open = false)}
+                  >
+                    {item.label}
+                  </a>
+                </li>
+              {/each}
+            </ul>
+          </section>
+        {/each}
+      </div>
+    {/if}
+  </div>
+{/if}
+
+<svelte:document onclick={onDocumentClick} onkeydown={onDocumentKeydown} />
+
+<style>
+  .mega-menu {
+    display: flex;
+    align-items: stretch;
+  }
+
+  /* The trigger reads as a peer of ServiceNavigation's links: same type ramp,
+     full band height, and the same accent underline bar when a contained link
+     is the current page. */
+  .mega-menu-trigger {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-2xs);
+    height: 100%;
+    padding-inline: var(--space-md);
+    border: none;
+    background: none;
+    color: var(--color-text-secondary);
+    font-family: var(--type-label-font);
+    font-size: var(--nav-service-link-size);
+    font-weight: var(--raw-font-weight-medium);
+    cursor: pointer;
+    transition: color var(--duration-fast) var(--easing-default);
+  }
+  .mega-menu-trigger:hover,
+  .mega-menu-trigger[aria-expanded="true"] {
+    color: var(--color-text);
+  }
+  .mega-menu-trigger:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+  .mega-menu-trigger.current {
+    color: var(--color-text);
+    font-weight: var(--raw-font-weight-semibold);
+    box-shadow: inset 0 calc(-1 * var(--nav-service-underline)) 0 0
+      var(--color-accent);
+  }
+  .mega-menu-chevron {
+    width: var(--icon-size-sm);
+    height: var(--icon-size-sm);
+    transition: transform var(--duration-fast) var(--easing-default);
+  }
+  .mega-menu-chevron.open {
+    transform: rotate(180deg);
+  }
+
+  /* Full-width panel anchored under the band (the nearest positioned ancestor
+     — SiteHeader's sticky banner). Category columns auto-flow; the panel
+     scrolls internally rather than covering the page (#507 overflow fix). */
+  .mega-menu-panel {
+    position: absolute;
+    top: 100%;
+    inset-inline: 0;
+    z-index: 50;
+    display: grid;
+    grid-template-columns: repeat(
+      auto-fill,
+      minmax(var(--nav-mega-column-min-width), 1fr)
+    );
+    gap: var(--space-lg);
+    padding: var(--space-lg) var(--content-padding-x);
+    max-height: var(--nav-mega-panel-max-height);
+    overflow-y: auto;
+    background: var(--color-surface-raised);
+    border-top: var(--border-width) solid var(--color-border);
+    border-bottom: var(--border-width) solid var(--color-border);
+    box-shadow: var(--shadow-md);
+  }
+
+  .mega-menu-heading {
+    margin: 0 0 var(--space-2xs);
+    font-family: var(--type-label-font);
+    font-size: var(--type-body-sm-size);
+    font-weight: var(--raw-font-weight-semibold);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--color-text-secondary);
+  }
+  .mega-menu-list {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .mega-menu-item {
+    display: flex;
+  }
+  .mega-menu-link {
+    flex: 1;
+    padding: var(--space-2xs) var(--space-2xs);
+    border-radius: var(--radius-md);
+    color: var(--color-text);
+    text-decoration: none;
+    font-family: var(--type-label-font);
+    font-size: var(--type-body-sm-size);
+  }
+  .mega-menu-link:hover {
+    background: var(--color-surface-tertiary);
+  }
+  .mega-menu-link:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+  .mega-menu-link[aria-current="page"] {
+    background: var(--color-surface-tertiary);
+    font-weight: var(--raw-font-weight-semibold);
+  }
+
+  /* Desktop-only: small screens use the consumer's native menu (SiteHeader's
+     unified disclosure), grouped by the same categories. */
+  @media (max-width: 47.99rem) {
+    .mega-menu {
+      display: none;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .mega-menu-chevron {
+      transition: none;
+    }
+  }
+</style>

package/components/MegaMenu.svelte.d.ts

@@ -0,0 +1,49 @@
+export default MegaMenu;
+type MegaMenu = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * MegaMenu
+ *
+ * Category mega-menu for many-section portals (#507): a single "Services ▾"
+ * disclosure in the primary band that opens a full-width panel of category
+ * columns, so ~20 verticals collapse into one trigger instead of overflowing
+ * the bar. Modelled on the GOV.UK "Menu" / Designers Italia mega-nav pattern.
+ *
+ * Semantics: a disclosure (`button[aria-expanded][aria-controls]` + panel),
+ * NOT a `menu` role — the panel holds plain links in labelled groups, which
+ * screen readers navigate as ordinary lists. Escape closes and restores focus
+ * to the trigger; clicking outside or navigating closes. The trigger reads as
+ * current (underline bar) when any contained link is current.
+ *
+ * Desktop-only affordance: below `--breakpoint` it renders nothing — small
+ * screens keep their native menu (SiteHeader's unified disclosure), which the
+ * consumer feeds the same category groups.
+ *
+ * Layout note: the panel is absolutely positioned against the NEAREST
+ * POSITIONED ANCESTOR — inside `SiteHeader` (position: sticky) it spans the
+ * full header band, which is the intended composition:
+ *
+ * @example
+ * <SiteHeader>
+ *   {#snippet nav()}
+ *     <ServiceNavigation label="Primary" items={primary} />
+ *     <MegaMenu label="Serviços" categories={buckets} />
+ *   {/snippet}
+ * </SiteHeader>
+ */
+declare const MegaMenu: import("svelte").Component<{
+    label?: string;
+    categories?: any[];
+    menuId?: string;
+    class?: string;
+    icon?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    label?: string;
+    categories?: any[];
+    menuId?: string;
+    class?: string;
+    icon?: any;
+} & Record<string, any>;

package/components/ServiceNavigation.svelte

@@ -161,6 +161,11 @@
       flex-direction: column;
       align-items: stretch;
       min-width: var(--nav-service-dropdown-min-width);
+      /* #507 overflow fix: many sections used to grow the dropdown past the
+         viewport and cover the page — cap it and scroll internally instead. */
+      max-width: calc(100vw - 2 * var(--content-padding-x));
+      max-height: min(70vh, 28rem);
+      overflow-y: auto;
       padding: var(--space-2xs);
       background: var(--color-surface);
       border: var(--border-width) solid var(--color-border);

package/components/index.d.ts

@@ -19,6 +19,7 @@ export { default as ListItem } from "./ListItem.svelte";
 export { default as PageContainer } from "./PageContainer.svelte";
 export { default as AppFrame } from "./AppFrame.svelte";
 export { default as SiteHeader } from "./SiteHeader.svelte";
+export { default as MegaMenu } from "./MegaMenu.svelte";
 export { default as SiteFooter } from "./SiteFooter.svelte";
 export { default as SkipLink } from "./SkipLink.svelte";
 export { default as TextSizeAdjuster } from "./TextSizeAdjuster.svelte";

package/components/index.js

@@ -36,6 +36,7 @@ export { default as PageContainer } from "./PageContainer.svelte";
 // Public site shell (locked a11y chrome — citizen portal, #7/#71)
 export { default as AppFrame } from "./AppFrame.svelte";
 export { default as SiteHeader } from "./SiteHeader.svelte";
+export { default as MegaMenu } from "./MegaMenu.svelte";
 export { default as SiteFooter } from "./SiteFooter.svelte";
 export { default as SkipLink } from "./SkipLink.svelte";
 export { default as TextSizeAdjuster } from "./TextSizeAdjuster.svelte";

package/components/renderer/MetabaseEmbedWidget.svelte

@@ -0,0 +1,76 @@
+<script lang="ts">
+  import type { WidgetProps } from "./types";
+
+  // `embed` widget (#517, atelier) — a Metabase analytics embed on the unified
+  // dashboard/portal `Block[]` grid. PRESENTATION-ONLY: the DS never mints or
+  // holds a Metabase URL; the HOST resolves the signed/proxy URL and passes it
+  // as `props.src` (an `/internal/metabase-embed/…` route or a signed URL), and
+  // this widget renders an `<iframe>`. Presentational kind → `resolveData`
+  // short-circuits it (no DS fetch); the widget owns its props.
+  //
+  //   props.src         — the iframe URL (host-resolved). Absent ⇒ placeholder.
+  //   props.title       — accessible iframe title / caption.
+  //   props.height      — CSS height (e.g. "400px"); defaults to 400px.
+  //   props.width       — "full" | "half" (grid-agnostic max-width hint).
+  //   props.embed_type  — "dashboard" | "question" (informational; caption).
+  let { props }: WidgetProps = $props();
+
+  const src = $derived(typeof props.src === "string" ? props.src : "");
+  const title = $derived(typeof props.title === "string" && props.title ? props.title : "Metabase embed");
+  const height = $derived(typeof props.height === "string" && props.height ? props.height : "400px");
+  const half = $derived(props.width === "half");
+</script>
+
+<figure class="mb-embed" class:half data-widget="metabase-embed">
+  {#if src}
+    <iframe {src} {title} style:height loading="lazy" referrerpolicy="strict-origin-when-cross-origin"
+    ></iframe>
+    {#if props.title}<figcaption>{props.title}</figcaption>{/if}
+  {:else}
+    <div class="mb-embed-empty" style:height>
+      <p>Metabase embed not configured — set the dashboard/question id.</p>
+    </div>
+  {/if}
+</figure>
+
+<style>
+  .mb-embed {
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+    inline-size: 100%;
+  }
+
+  .mb-embed.half {
+    max-inline-size: 50%;
+  }
+
+  .mb-embed iframe {
+    inline-size: 100%;
+    border: var(--elevation-border);
+    border-radius: var(--radius-md);
+    background: var(--color-surface);
+  }
+
+  .mb-embed figcaption {
+    font-size: var(--type-caption-size);
+    color: var(--color-text-muted);
+  }
+
+  .mb-embed-empty {
+    display: grid;
+    place-items: center;
+    inline-size: 100%;
+    border: var(--border-width) dashed var(--color-border);
+    border-radius: var(--radius-md);
+    background: var(--color-surface-secondary);
+  }
+
+  .mb-embed-empty p {
+    margin: 0;
+    padding: var(--space-md);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-muted);
+  }
+</style>

package/components/renderer/MetabaseEmbedWidget.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { WidgetProps } from "./types";
+declare const MetabaseEmbedWidget: import("svelte").Component<WidgetProps, {}, "">;
+type MetabaseEmbedWidget = ReturnType<typeof MetabaseEmbedWidget>;
+export default MetabaseEmbedWidget;

package/components/renderer/StatGridWidget.svelte

@@ -14,6 +14,11 @@
     label?: string;
     value?: string;
     variant?: string;
+    /** #517 — optional Phosphor icon NAME (kebab-case, e.g. "chart-bar"),
+     * rendered via the Phosphor web font. Lets a dashboard KPI block carry its
+     * per-card icon through the DS widget, so KPI renders via `resolveWidget`
+     * like every other block (no host-side StatCard special-case). */
+    icon?: string;
   }
 
   const view = $derived((data ?? {}) as Record<string, unknown>);
@@ -24,10 +29,21 @@
         ? props.stats
         : []) as Stat[],
   );
+
+  // Phosphor web-font class names are kebab-case (`ph ph-chart-bar`); keep only
+  // the safe charset so a bad name can't leak into `class` (defensive — attribute
+  // values are escaped, but this keeps the class well-formed).
+  const iconClass = (name: string): string => `ph ph-${name.replace(/[^a-z0-9-]/gi, "")}`;
 </script>
 
 <StatGrid>
   {#each stats as stat (stat.label)}
-    <StatCard label={stat.label} value={stat.value} variant={stat.variant} />
+    {#snippet cardIcon()}<i class={iconClass(stat.icon ?? "")} aria-hidden="true"></i>{/snippet}
+    <StatCard
+      label={stat.label}
+      value={stat.value}
+      variant={stat.variant}
+      icon={stat.icon ? cardIcon : undefined}
+    />
   {/each}
 </StatGrid>

package/components/renderer/registry.ts

@@ -23,6 +23,7 @@ import {
 import type { Block, OntologySchema, WidgetKind, WidgetProps } from "./types";
 
 import EChartWidget from "./EChartWidget.svelte";
+import MetabaseEmbedWidget from "./MetabaseEmbedWidget.svelte";
 import ResultsChartWidget from "./ResultsChartWidget.svelte";
 import StatGridWidget from "./StatGridWidget.svelte";
 
@@ -75,6 +76,9 @@ const _entries: RegistryEntry<WidgetComponent>[] = [
   // the kind-specific registry keys + wrapper components are retired.
   // `results-chart` stays as the SSR / no-JS a11y fallback key.
   byTypeOnKind("chart", "aggregate", EChartWidget),
+  // #517 (atelier) — Metabase embed on the unified Block[] grid. Presentation-
+  // only (renders `props.src`); one kind-generic entry, no `type` ranking.
+  byKind("metabase-embed", "embed", MetabaseEmbedWidget),
 ];
 
 /**

package/components/renderer/resolve-data.ts

@@ -35,6 +35,9 @@ export const PRESENTATIONAL_KINDS: ReadonlySet<WidgetKind> =
   new Set<WidgetKind>([
     "hero",
     "lookup",
+    // #517 — the Metabase embed renders from a host-resolved `props.src`; it has
+    // no DS-fetched data path, so short-circuit it like the other content kinds.
+    "embed",
     "feature-grid",
     "cta",
     "media-text",

package/components/renderer/types.d.ts

@@ -13,7 +13,7 @@
  * here the descriptors are SEEDED (same staged pattern #70/#72 used).
  */
 /** The bounded, governed widget kinds (spec §5 catalog). */
-export type WidgetKind = "list" | "detail" | "form" | "map" | "calendar" | "kpi" | "content" | "vote" | "status" | "forms" | "hero" | "lookup" | "feed" | "filters" | "actions" | "aggregate" | "subscriptions" | "consent" | "deliveries" | "owned-list" | "feature-grid" | "cta" | "media-text" | "steps" | "testimonial" | "faq" | "logo-strip" | "media-gallery";
+export type WidgetKind = "list" | "detail" | "form" | "map" | "calendar" | "kpi" | "content" | "embed" | "vote" | "status" | "forms" | "hero" | "lookup" | "feed" | "filters" | "actions" | "aggregate" | "subscriptions" | "consent" | "deliveries" | "owned-list" | "feature-grid" | "cta" | "media-text" | "steps" | "testimonial" | "faq" | "logo-strip" | "media-gallery";
 /** The feed sub-views a `feed`/`filters` binding may toggle/scope (#308). */
 export type FeedView = "list" | "map";
 /** Declarative pointer — "I render <kind> of <entity|action>, scoped by filter". */

package/components/renderer/types.ts

@@ -22,6 +22,12 @@ export type WidgetKind =
   | "calendar"
   | "kpi"
   | "content"
+  // #517 (atelier) — a Metabase analytics embed. Presentational: the DS
+  // `MetabaseEmbedWidget` renders an `<iframe>` from a HOST-resolved `props.src`
+  // (the signed/proxy URL), so the DS stays presentation-only and carries no
+  // metabase auth. Lets a dashboard/portal `Block[]` hold embeds uniformly
+  // (resolved via `resolveWidget`, not a host special-case).
+  | "embed"
   | "vote"
   | "status"
   | "forms"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",

package/tokens/components.css

@@ -229,6 +229,11 @@
      rendered standalone, without SiteHeader's unified menu). */
   --nav-service-dropdown-min-width: 12rem;
 
+  /* MegaMenu (#507) — category column sizing + the panel's internal-scroll cap
+     so an 8-category panel scrolls inside itself instead of covering the page. */
+  --nav-mega-column-min-width: 13rem;
+  --nav-mega-panel-max-height: min(70vh, 32rem);
+
   /* ═══════════════════════════════════════════════
      DATA DISPLAY
      ═══════════════════════════════════════════════ */